pet.trezy.repairRecords Documentation (EN)

main procedure

Report, clean up, or repair the caller's own game records. Acts only on the authenticated caller's repo; it never accepts a DID.

Input

Encodingapplication/json

action string Required

status reports and mutates nothing; cleanup deletes the caller's rogue records from their repo; repair rebuilds the wallet from the server-side high-water mark and re-signs it; restore writes back pet records the server-side ledger has and the caller's repo does not.

Output

Encodingapplication/json

action string Optional

The action that was performed, echoed back.

Known values: status, cleanup, repair, restore

collected integer Optional

The high-water total this instance has issued the caller, absent when they have never collected.

deletedCount integer Optional

Records removed from the caller's repo by this call. Zero for status and repair, and zero is a success rather than an error.

error string Optional

Present INSTEAD OF the whole report when the call was refused for an expected reason. A stable machine code the client branches on — add codes, never rename them. Its presence is why nothing below is `required`: a refusal carries none of those fields, and requiring even one would fail response validation and turn an expected refusal back into a 500.

Known values: unknown-action

lastUpdated stringdatetime Optional

THE ACCRUAL ANCHOR, NOT A WRITE TIME. Income is measured FROM this moment, so it is where the next payout starts rather than when this record was last saved. The two usually coincide, because a settle banks everything and moves the anchor to now — but a PARTIAL collect advances it only as far as the coins actually taken, leaving it EARLIER than the write that produced it. Reading it as "when the wallet was last written" has already cost this project one wrong diagnosis. It is deliberately NOT renamed: it sits inside the signed payload, so changing it would invalidate every wallet attestation ever issued and require rewriting records in players' repos.

message string Optional

A sentence to show the player, accompanying `error`. Free to reword; do not branch on it.

missingPets integer Optional

Pets the server's ledger holds for the caller with no record in the index — deleted from the repo, or lost when an index was rebuilt. The pets themselves are unaffected; only the copy in the repo is gone, and restore puts it back. This is NOT a rogue-record count and must never be worded as one: nothing was forged and the player is not accused of anything. Counts what a restore would act on rather than every hole, exactly as rogueCount counts deletable rejections rather than all of them: a row the server cannot rebuild is logged for an operator, not offered to the player as a button that would answer zero. RETIRED PETS ARE EXCLUDED, from this count and from restore: retiring is the player saying they are done with a pet, so a missing record for one is not a hole they want filled, and counting it would leave them a prompt no un-retire could ever resolve. Counted after the action, so a restore reports what is left. Optional rather than required, deliberately: an instance running a repairRecords older than this lexicon does not emit it, and a client must read its absence as 'unknown' rather than 'none'.

needsRepair boolean Optional

True when running repair would actually change something for this player.

reasons array Optional

The rejection reasons present for this caller and how many of each, so the prompt can be worded per reason.

rejectedCount integer Optional

Every record of the caller's the ingest guards refused, whatever the reason.

repaired boolean Optional

Whether this call rewrote the wallet. False when there was no high-water row to rebuild from, which is a success.

restoreAttempted integer Optional

Pet records this call TRIED to write back, before any of them succeeded or failed. Zero for every action but restore. Exists because restoredCount alone cannot tell 'there was no hole to fill' from 'every write failed' — the two need opposite words in front of a player, and conflating them once told somebody nothing was wrong while their pet stayed invisible. restoreAttempted > restoredCount means the reasons are in the instance log, one line per record.

restoredCount integer Optional

Pet records written back into the caller's repo by this call. Zero for every action but restore. Zero is NOT necessarily a success: compare it with restoreAttempted, because a restore that tried and failed also reports zero.

rogueCount integer Optional

The subset whose remedy is deletion: records that did not come from the game. Never includes a stale wallet.

rogueWallet boolean Optional

The wallet in the caller's repo is among the records cleanup would delete. Deleting it drops the good index row with it, so the balance falls back to the high-water mark; the prompt must not promise the cleanup leaves progress untouched. Never true for a stale wallet, which cleanup passes over. Optional rather than required, deliberately: an instance running a repairRecords older than this lexicon does not emit it, and that is exactly the case the client's third state exists to word — declaring it required would let response validation reject the payload before the client ever saw it.

staleWallet boolean Optional

The wallet in the caller's repo was refused as out of date. Its remedy is repair, never deletion.

walletState string Optional

How the caller's indexed wallet stands: ok, absent, carrying no attestation, signed with a key this instance has rotated away from, failing verification, or unjudgeable because the instance has no signer.

Known values: ok, missing, unsigned, stale-key, invalid, unverifiable

Try It

Requests are sent directly from your browser. Some servers may block requests due to CORS.

Service Endpoint Base URL for XRPC calls (e.g., https://bsky.social)

Request Body (JSON) Enter valid JSON for the request body

View raw schema

{
  "type": "procedure",
  "input": {
    "schema": {
      "type": "object",
      "required": [
        "action"
      ],
      "properties": {
        "action": {
          "type": "string",
          "description": "status reports and mutates nothing; cleanup deletes the caller's rogue records from their repo; repair rebuilds the wallet from the server-side high-water mark and re-signs it; restore writes back pet records the server-side ledger has and the caller's repo does not.",
          "knownValues": [
            "status",
            "cleanup",
            "repair",
            "restore"
          ]
        }
      }
    },
    "encoding": "application/json"
  },
  "output": {
    "schema": {
      "type": "object",
      "required": [],
      "properties": {
        "error": {
          "type": "string",
          "description": "Present INSTEAD OF the whole report when the call was refused for an expected reason. A stable machine code the client branches on — add codes, never rename them. Its presence is why nothing below is `required`: a refusal carries none of those fields, and requiring even one would fail response validation and turn an expected refusal back into a 500.",
          "knownValues": [
            "unknown-action"
          ]
        },
        "action": {
          "type": "string",
          "description": "The action that was performed, echoed back.",
          "knownValues": [
            "status",
            "cleanup",
            "repair",
            "restore"
          ]
        },
        "message": {
          "type": "string",
          "description": "A sentence to show the player, accompanying `error`. Free to reword; do not branch on it."
        },
        "reasons": {
          "type": "array",
          "items": {
            "ref": "#reasonCount",
            "type": "ref"
          },
          "description": "The rejection reasons present for this caller and how many of each, so the prompt can be worded per reason."
        },
        "repaired": {
          "type": "boolean",
          "description": "Whether this call rewrote the wallet. False when there was no high-water row to rebuild from, which is a success."
        },
        "collected": {
          "type": "integer",
          "description": "The high-water total this instance has issued the caller, absent when they have never collected."
        },
        "rogueCount": {
          "type": "integer",
          "description": "The subset whose remedy is deletion: records that did not come from the game. Never includes a stale wallet."
        },
        "lastUpdated": {
          "type": "string",
          "format": "datetime",
          "description": "THE ACCRUAL ANCHOR, NOT A WRITE TIME. Income is measured FROM this moment, so it is where the next payout starts rather than when this record was last saved. The two usually coincide, because a settle banks everything and moves the anchor to now — but a PARTIAL collect advances it only as far as the coins actually taken, leaving it EARLIER than the write that produced it. Reading it as \"when the wallet was last written\" has already cost this project one wrong diagnosis. It is deliberately NOT renamed: it sits inside the signed payload, so changing it would invalidate every wallet attestation ever issued and require rewriting records in players' repos."
        },
        "missingPets": {
          "type": "integer",
          "description": "Pets the server's ledger holds for the caller with no record in the index — deleted from the repo, or lost when an index was rebuilt. The pets themselves are unaffected; only the copy in the repo is gone, and restore puts it back. This is NOT a rogue-record count and must never be worded as one: nothing was forged and the player is not accused of anything. Counts what a restore would act on rather than every hole, exactly as rogueCount counts deletable rejections rather than all of them: a row the server cannot rebuild is logged for an operator, not offered to the player as a button that would answer zero. RETIRED PETS ARE EXCLUDED, from this count and from restore: retiring is the player saying they are done with a pet, so a missing record for one is not a hole they want filled, and counting it would leave them a prompt no un-retire could ever resolve. Counted after the action, so a restore reports what is left. Optional rather than required, deliberately: an instance running a repairRecords older than this lexicon does not emit it, and a client must read its absence as 'unknown' rather than 'none'."
        },
        "needsRepair": {
          "type": "boolean",
          "description": "True when running repair would actually change something for this player."
        },
        "rogueWallet": {
          "type": "boolean",
          "description": "The wallet in the caller's repo is among the records cleanup would delete. Deleting it drops the good index row with it, so the balance falls back to the high-water mark; the prompt must not promise the cleanup leaves progress untouched. Never true for a stale wallet, which cleanup passes over. Optional rather than required, deliberately: an instance running a repairRecords older than this lexicon does not emit it, and that is exactly the case the client's third state exists to word — declaring it required would let response validation reject the payload before the client ever saw it."
        },
        "staleWallet": {
          "type": "boolean",
          "description": "The wallet in the caller's repo was refused as out of date. Its remedy is repair, never deletion."
        },
        "walletState": {
          "type": "string",
          "description": "How the caller's indexed wallet stands: ok, absent, carrying no attestation, signed with a key this instance has rotated away from, failing verification, or unjudgeable because the instance has no signer.",
          "knownValues": [
            "ok",
            "missing",
            "unsigned",
            "stale-key",
            "invalid",
            "unverifiable"
          ]
        },
        "deletedCount": {
          "type": "integer",
          "description": "Records removed from the caller's repo by this call. Zero for status and repair, and zero is a success rather than an error."
        },
        "rejectedCount": {
          "type": "integer",
          "description": "Every record of the caller's the ingest guards refused, whatever the reason."
        },
        "restoredCount": {
          "type": "integer",
          "description": "Pet records written back into the caller's repo by this call. Zero for every action but restore. Zero is NOT necessarily a success: compare it with restoreAttempted, because a restore that tried and failed also reports zero."
        },
        "restoreAttempted": {
          "type": "integer",
          "description": "Pet records this call TRIED to write back, before any of them succeeded or failed. Zero for every action but restore. Exists because restoredCount alone cannot tell 'there was no hole to fill' from 'every write failed' — the two need opposite words in front of a player, and conflating them once told somebody nothing was wrong while their pet stayed invisible. restoreAttempted > restoredCount means the reasons are in the instance log, one line per record."
        }
      }
    },
    "encoding": "application/json"
  },
  "description": "Report, clean up, or repair the caller's own game records. Acts only on the authenticated caller's repo; it never accepts a DID."
}

reasonCount object

No description available.

Properties

count integer Required

No description available.

reason string Required

A reason code emitted by the ingest guards. Treat as open: the guards may add codes.`unchecked` is NOT an accusation and must never be worded as one: it means the instance could not check the signature at all — a decode that failed, a field that was missing, a key that would not load — and says nothing about the record or the player. It is deliberately distinct from `invalid-signature`, which means the signature was read and did not match, and from the `unverifiable` walletState, which means there is no signer configured to judge with.

Known values: missing-signature, invalid-signature, unchecked, malformed, duplicate, replay, duplicate-check-unavailable, procedure-only

View raw schema

{
  "type": "object",
  "required": [
    "reason",
    "count"
  ],
  "properties": {
    "count": {
      "type": "integer"
    },
    "reason": {
      "type": "string",
      "description": "A reason code emitted by the ingest guards. Treat as open: the guards may add codes.`unchecked` is NOT an accusation and must never be worded as one: it means the instance could not check the signature at all — a decode that failed, a field that was missing, a key that would not load — and says nothing about the record or the player. It is deliberately distinct from `invalid-signature`, which means the signature was read and did not match, and from the `unverifiable` walletState, which means there is no signer configured to judge with.",
      "knownValues": [
        "missing-signature",
        "invalid-signature",
        "unchecked",
        "malformed",
        "duplicate",
        "replay",
        "duplicate-check-unavailable",
        "procedure-only"
      ]
    }
  }
}