@openvtc/trust-tasks 0.18.3 → 0.18.5

package/src/rooms/epoch/prune/0.1/payload.ts

@@ -0,0 +1,289 @@
+/**
+ * Generated by scripts/build-ts-bindings.mjs — DO NOT EDIT BY HAND.
+ * Source: specs/rooms/epoch/prune/0.1/payload.schema.json
+ */
+
+import type { AuthorityPresentation, Ext } from "../../../../_shared/components.js";
+
+
+/**
+ * TODO: what the request payload of rooms/epoch/prune carries. The outer document members (id, type, issuer, recipient, issuedAt, expiresAt, proof) are owned by the framework — SPEC §6.3.
+ */
+export interface RoomsEpochPrunePayload {
+  /**
+   * The room to prune.
+   */
+  roomId: string;
+  /**
+   * Drop every rung *below* this epoch, so the chain walks back no further than it.
+   *
+   * `minimum: 2` because pruning below epoch 1 would drop nothing and asking to is a caller that has misunderstood the direction — the chain walks backwards, and epoch 1 is where it ends.
+   */
+  beforeEpoch: number;
+  /**
+   * Must confer `admin` at this room's scope. Not `curate`, and not `write`: pruning is not a statement about any record, and every member who can write can curate. It ends the room's ability to open a span of its own history, for everyone, which is the same class of act as advancing the epoch.
+   */
+  presentation: AuthorityPresentation;
+  /**
+   * Why, for the room's audit trail. A prune is irreversible and unattributable after the fact — the rungs are simply gone — so the only record of intent is the one made at the time.
+   */
+  reason?: string;
+  /**
+   * Ecosystem-defined extension members per SPEC.md §4.5.1.
+   */
+  ext?: Ext;
+}
+/**
+ * Success response to rooms/epoch/prune. Type https://trusttasks.org/spec/rooms/epoch/prune/0.1#response.
+ */
+export interface RoomsEpochPruneResponsePayload {
+  roomId: string;
+  /**
+   * How many rungs were dropped. `0` is a success: the chain already went back no further, and a caller that read it as a failure would retry an operation that has nothing left to do.
+   */
+  pruned: number;
+  /**
+   * The lowest epoch the chain still reaches, after pruning. **Not a restatement of `beforeEpoch`**: a chain with a gap in it already stopped somewhere, and a prune below that gap changes nothing about how far back a member can actually walk. Reporting the request back would tell an operator they had achieved something they had not.
+   */
+  earliestRung: number;
+  ext?: Ext;
+}
+
+/** Shared definitions this specification references, re-exported under the names it used to declare them with. */
+export type { AuthorityPresentation, Ext };
+
+/** Trust Task type URI. */
+export const TYPE_URI = "https://trusttasks.org/spec/rooms/epoch/prune/0.1" as const;
+
+/** Stable alias for this specification's request payload shape. */
+export type Payload = RoomsEpochPrunePayload;
+
+/** Trust Task response type URI (request type URI + "#response"). */
+export const RESPONSE_TYPE_URI = "https://trusttasks.org/spec/rooms/epoch/prune/0.1#response" as const;
+
+/** Stable alias for this specification's success-response payload shape. */
+export type Response = RoomsEpochPruneResponsePayload;
+
+/**
+ * This specification's payload schema, as a value.
+ *
+ * SPEC.md §7.2 item 2 is performed against this. It is shipped as data
+ * rather than only as a `.json` file because TypeScript types are erased
+ * at runtime: without a schema a consumer has nothing to validate, and
+ * every REQUIRED payload member is optional in practice. Cross-file
+ * `$ref`s are already inlined, so it needs no resolver.
+ */
+export const PAYLOAD_SCHEMA = {
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://trusttasks.org/spec/rooms/epoch/prune/0.1",
+  "title": "Rooms Epoch Prune — payload",
+  "description": "TODO: what the request payload of rooms/epoch/prune carries. The outer document members (id, type, issuer, recipient, issuedAt, expiresAt, proof) are owned by the framework — SPEC §6.3.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "roomId",
+    "beforeEpoch",
+    "presentation"
+  ],
+  "properties": {
+    "roomId": {
+      "type": "string",
+      "description": "The room to prune."
+    },
+    "beforeEpoch": {
+      "type": "integer",
+      "minimum": 2,
+      "description": "Drop every rung *below* this epoch, so the chain walks back no further than it.\n\n`minimum: 2` because pruning below epoch 1 would drop nothing and asking to is a caller that has misunderstood the direction — the chain walks backwards, and epoch 1 is where it ends."
+    },
+    "presentation": {
+      "$ref": "#/$defs/AuthorityPresentation",
+      "description": "Must confer `admin` at this room's scope. Not `curate`, and not `write`: pruning is not a statement about any record, and every member who can write can curate. It ends the room's ability to open a span of its own history, for everyone, which is the same class of act as advancing the epoch."
+    },
+    "reason": {
+      "type": "string",
+      "maxLength": 512,
+      "description": "Why, for the room's audit trail. A prune is irreversible and unattributable after the fact — the rungs are simply gone — so the only record of intent is the one made at the time."
+    },
+    "ext": {
+      "$ref": "#/$defs/Ext",
+      "description": "Ecosystem-defined extension members per SPEC.md §4.5.1."
+    }
+  },
+  "$defs": {
+    "Response": {
+      "$anchor": "response",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "roomId",
+        "pruned",
+        "earliestRung"
+      ],
+      "description": "Success response to rooms/epoch/prune. Type https://trusttasks.org/spec/rooms/epoch/prune/0.1#response.",
+      "properties": {
+        "roomId": {
+          "type": "string"
+        },
+        "pruned": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "How many rungs were dropped. `0` is a success: the chain already went back no further, and a caller that read it as a failure would retry an operation that has nothing left to do."
+        },
+        "earliestRung": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "The lowest epoch the chain still reaches, after pruning. **Not a restatement of `beforeEpoch`**: a chain with a gap in it already stopped somewhere, and a prune below that gap changes nothing about how far back a member can actually walk. Reporting the request back would tell an operator they had achieved something they had not."
+        },
+        "ext": {
+          "$ref": "#/$defs/Ext"
+        }
+      },
+      "title": "Rooms Epoch Prune — response payload"
+    },
+    "Ext": {
+      "title": "Ext",
+      "description": "Vendor-namespaced extension object per SPEC.md §4.5.1. Each immediate key MUST be a reverse-DNS namespace; structure under each namespace is opaque to the framework.",
+      "type": "object",
+      "minProperties": 1,
+      "additionalProperties": true,
+      "propertyNames": {
+        "pattern": "^[a-z][a-z0-9-]*(\\.[a-z0-9-]+)+$"
+      }
+    },
+    "AuthorityPresentation": {
+      "title": "AuthorityPresentation",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "membership",
+        "authority"
+      ],
+      "description": "What a party presents to act on a room. Carries the whole authority chain: a host MUST NOT dereference an authority credential's `parent` to fetch a link it was not given. Resolving over the network would make verification depend on availability, turn every identifier into a request the host can be induced to make against an address the holder chooses, and signal credential use to whoever hosts the identifier. A host MUST bind the presenter to the chain's leaf. A chain that verifies is evidence that authority was conferred on somebody; it is not evidence that the party presenting it is that somebody. The leaf's subject MUST equal the party the host authenticated for this request — an identity the transport established or a document `proof` proved, never one named in a payload. A host that omits this check authorizes every captured presentation, and the omission is silent, because the chain still verifies.",
+      "properties": {
+        "membership": {
+          "type": "string",
+          "description": "The presenter's membership credential for this room, or — on a `private` room — a zero-knowledge presentation of it. Serialized per the governing profile."
+        },
+        "authority": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 8,
+          "items": {
+            "type": "string"
+          },
+          "description": "The authority chain, LEAF FIRST: the first element is the credential being relied on and the last MUST be one issued by the room itself. Every link the presenter relies on is present, because the host will not fetch one. Capped at 8: verification is linear in chain length and runs on every operation, so an unbounded chain is a denial-of-service surface against the host. The known uses need 2 to 3 — a person attenuating to an agent, and that agent to a sub-agent."
+        },
+        "subjectBinding": {
+          "type": "string",
+          "description": "REQUIRED on a `private` room, where the subject identifier is withheld: a proof that the membership credential and the authority chain's leaf describe the SAME subject. Without it two parties pool credentials — one contributes membership, the other authority — and the combination verifies as a single party holding both. A host MUST refuse a private-room presentation that omits this."
+        }
+      }
+    }
+  }
+} as const;
+
+/** As {@link PAYLOAD_SCHEMA}, for the success-response variant. */
+export const RESPONSE_PAYLOAD_SCHEMA = {
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$ref": "#/$defs/Response",
+  "$defs": {
+    "Response": {
+      "$anchor": "response",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "roomId",
+        "pruned",
+        "earliestRung"
+      ],
+      "description": "Success response to rooms/epoch/prune. Type https://trusttasks.org/spec/rooms/epoch/prune/0.1#response.",
+      "properties": {
+        "roomId": {
+          "type": "string"
+        },
+        "pruned": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "How many rungs were dropped. `0` is a success: the chain already went back no further, and a caller that read it as a failure would retry an operation that has nothing left to do."
+        },
+        "earliestRung": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "The lowest epoch the chain still reaches, after pruning. **Not a restatement of `beforeEpoch`**: a chain with a gap in it already stopped somewhere, and a prune below that gap changes nothing about how far back a member can actually walk. Reporting the request back would tell an operator they had achieved something they had not."
+        },
+        "ext": {
+          "$ref": "#/$defs/Ext"
+        }
+      },
+      "title": "Rooms Epoch Prune — response payload"
+    },
+    "Ext": {
+      "title": "Ext",
+      "description": "Vendor-namespaced extension object per SPEC.md §4.5.1. Each immediate key MUST be a reverse-DNS namespace; structure under each namespace is opaque to the framework.",
+      "type": "object",
+      "minProperties": 1,
+      "additionalProperties": true,
+      "propertyNames": {
+        "pattern": "^[a-z][a-z0-9-]*(\\.[a-z0-9-]+)+$"
+      }
+    },
+    "AuthorityPresentation": {
+      "title": "AuthorityPresentation",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "membership",
+        "authority"
+      ],
+      "description": "What a party presents to act on a room. Carries the whole authority chain: a host MUST NOT dereference an authority credential's `parent` to fetch a link it was not given. Resolving over the network would make verification depend on availability, turn every identifier into a request the host can be induced to make against an address the holder chooses, and signal credential use to whoever hosts the identifier. A host MUST bind the presenter to the chain's leaf. A chain that verifies is evidence that authority was conferred on somebody; it is not evidence that the party presenting it is that somebody. The leaf's subject MUST equal the party the host authenticated for this request — an identity the transport established or a document `proof` proved, never one named in a payload. A host that omits this check authorizes every captured presentation, and the omission is silent, because the chain still verifies.",
+      "properties": {
+        "membership": {
+          "type": "string",
+          "description": "The presenter's membership credential for this room, or — on a `private` room — a zero-knowledge presentation of it. Serialized per the governing profile."
+        },
+        "authority": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 8,
+          "items": {
+            "type": "string"
+          },
+          "description": "The authority chain, LEAF FIRST: the first element is the credential being relied on and the last MUST be one issued by the room itself. Every link the presenter relies on is present, because the host will not fetch one. Capped at 8: verification is linear in chain length and runs on every operation, so an unbounded chain is a denial-of-service surface against the host. The known uses need 2 to 3 — a person attenuating to an agent, and that agent to a sub-agent."
+        },
+        "subjectBinding": {
+          "type": "string",
+          "description": "REQUIRED on a `private` room, where the subject identifier is withheld: a proof that the membership credential and the authority chain's leaf describe the SAME subject. Without it two parties pool credentials — one contributes membership, the other authority — and the combination verifies as a single party holding both. A host MUST refuse a private-room presentation that omits this."
+        }
+      }
+    }
+  }
+} as const;
+
+/**
+ * SPEC.md §7.2 policy for the request variant, from this specification's
+ * front matter. Pass to `consumeInbound` — items 5b, 7 and 8 are
+ * per-specification and cannot be derived from the document alone, and
+ * item 2 needs the schema this carries.
+ */
+export const SPEC = {
+  typeUri: TYPE_URI,
+  isBearer: false,
+  isProofRequired: true,
+  isRecipientRequired: true,
+  isIssuedAtRequired: true,
+  payloadSchema: PAYLOAD_SCHEMA,
+} as const;
+
+/**
+ * SPEC.md §7.2 policy for the success-response variant. `isRecipientRequired`
+ * tracks the *issuer* party's requirement because a response swaps the
+ * parties (§7.3 item 5).
+ */
+export const RESPONSE_SPEC = {
+  typeUri: RESPONSE_TYPE_URI,
+  isBearer: false,
+  isProofRequired: true,
+  isRecipientRequired: true,
+  isIssuedAtRequired: true,
+  payloadSchema: RESPONSE_PAYLOAD_SCHEMA,
+} as const;

package/src/rooms/keys/browse/0.1/payload.ts

@@ -194,6 +194,18 @@ export const PAYLOAD_SCHEMA = {
           ],
           "description": "Whether this root matches what the agent has seen from this host for this room **at this `headVersion`**.\n\nThis is the comparison a member cannot make for themselves. A tab does not outlive itself and a CLI holds nothing; the agent is the only party on the member's side of the boundary that saw both reads.\n\n  - `agree` — seen at this head before, same root.\n  - `conflict` — seen at this head before, **different root**. A host caught: there is no write to attribute the difference to, because a write would have moved the head.\n  - `noneHeld` — first read at this head. Not evidence of anything; a memory of one is not a comparison.\n  - `notChecked` — this agent keeps no root history. An honest answer for an agent that cannot make the comparison, and **not** a synonym for `noneHeld`: one says nothing was found, the other says nothing was looked for.\n\nREQUIRED, so that an agent which does not check has to say so rather than omit the question."
         },
+        "anchor": {
+          "type": "string",
+          "enum": [
+            "agrees",
+            "ahead",
+            "behind",
+            "conflict",
+            "none",
+            "notChecked"
+          ],
+          "description": "How what the host served compares with the room's own **witnessed anchor** (`EpochAnchor`).\n\nThis is the comparison that needs neither a gossip channel rooms deliberately lack nor durable state in an agent: every member resolves the same room DID and reads the same entry, co-signed by witnesses. It is the only one of the three a first-time reader can make.\n\n  - `agrees` — the host served the anchored state, and its root matches.\n  - `ahead` — the room has moved past the anchor. The ordinary case; an anchor describes a moment, not the present, and says nothing about records written since.\n  - `behind` — **the host is serving a state older than the room's own witnessed statement.** A rollback, and a detection nothing else in this family can make: a member with no history, no peer and no prior read still catches it.\n  - `conflict` — same `headVersion` as the anchor, different root. The host has contradicted a value its own room published and witnesses co-signed.\n  - `none` — the room has published no anchor. Not a fault; anchoring costs a witnessed update and a key rotation, and a room may reasonably decline.\n  - `notChecked` — the consumer did not resolve the room. An honest answer, and **not** a synonym for `none`: one says the room published nothing, the other says nobody looked."
+        },
         "count": {
           "type": "string",
           "enum": [
@@ -389,6 +401,18 @@ export const RESPONSE_PAYLOAD_SCHEMA = {
           ],
           "description": "Whether this root matches what the agent has seen from this host for this room **at this `headVersion`**.\n\nThis is the comparison a member cannot make for themselves. A tab does not outlive itself and a CLI holds nothing; the agent is the only party on the member's side of the boundary that saw both reads.\n\n  - `agree` — seen at this head before, same root.\n  - `conflict` — seen at this head before, **different root**. A host caught: there is no write to attribute the difference to, because a write would have moved the head.\n  - `noneHeld` — first read at this head. Not evidence of anything; a memory of one is not a comparison.\n  - `notChecked` — this agent keeps no root history. An honest answer for an agent that cannot make the comparison, and **not** a synonym for `noneHeld`: one says nothing was found, the other says nothing was looked for.\n\nREQUIRED, so that an agent which does not check has to say so rather than omit the question."
         },
+        "anchor": {
+          "type": "string",
+          "enum": [
+            "agrees",
+            "ahead",
+            "behind",
+            "conflict",
+            "none",
+            "notChecked"
+          ],
+          "description": "How what the host served compares with the room's own **witnessed anchor** (`EpochAnchor`).\n\nThis is the comparison that needs neither a gossip channel rooms deliberately lack nor durable state in an agent: every member resolves the same room DID and reads the same entry, co-signed by witnesses. It is the only one of the three a first-time reader can make.\n\n  - `agrees` — the host served the anchored state, and its root matches.\n  - `ahead` — the room has moved past the anchor. The ordinary case; an anchor describes a moment, not the present, and says nothing about records written since.\n  - `behind` — **the host is serving a state older than the room's own witnessed statement.** A rollback, and a detection nothing else in this family can make: a member with no history, no peer and no prior read still catches it.\n  - `conflict` — same `headVersion` as the anchor, different root. The host has contradicted a value its own room published and witnesses co-signed.\n  - `none` — the room has published no anchor. Not a fault; anchoring costs a witnessed update and a key rotation, and a room may reasonably decline.\n  - `notChecked` — the consumer did not resolve the room. An honest answer, and **not** a synonym for `none`: one says the room published nothing, the other says nobody looked."
+        },
         "count": {
           "type": "string",
           "enum": [

package/src/rooms/keys/read/0.1/payload.ts

@@ -216,6 +216,18 @@ export const PAYLOAD_SCHEMA = {
           ],
           "description": "Whether this root matches what the agent has seen from this host for this room **at this `headVersion`**.\n\nThis is the comparison a member cannot make for themselves. A tab does not outlive itself and a CLI holds nothing; the agent is the only party on the member's side of the boundary that saw both reads.\n\n  - `agree` — seen at this head before, same root.\n  - `conflict` — seen at this head before, **different root**. A host caught: there is no write to attribute the difference to, because a write would have moved the head.\n  - `noneHeld` — first read at this head. Not evidence of anything; a memory of one is not a comparison.\n  - `notChecked` — this agent keeps no root history. An honest answer for an agent that cannot make the comparison, and **not** a synonym for `noneHeld`: one says nothing was found, the other says nothing was looked for.\n\nREQUIRED, so that an agent which does not check has to say so rather than omit the question."
         },
+        "anchor": {
+          "type": "string",
+          "enum": [
+            "agrees",
+            "ahead",
+            "behind",
+            "conflict",
+            "none",
+            "notChecked"
+          ],
+          "description": "How what the host served compares with the room's own **witnessed anchor** (`EpochAnchor`).\n\nThis is the comparison that needs neither a gossip channel rooms deliberately lack nor durable state in an agent: every member resolves the same room DID and reads the same entry, co-signed by witnesses. It is the only one of the three a first-time reader can make.\n\n  - `agrees` — the host served the anchored state, and its root matches.\n  - `ahead` — the room has moved past the anchor. The ordinary case; an anchor describes a moment, not the present, and says nothing about records written since.\n  - `behind` — **the host is serving a state older than the room's own witnessed statement.** A rollback, and a detection nothing else in this family can make: a member with no history, no peer and no prior read still catches it.\n  - `conflict` — same `headVersion` as the anchor, different root. The host has contradicted a value its own room published and witnesses co-signed.\n  - `none` — the room has published no anchor. Not a fault; anchoring costs a witnessed update and a key rotation, and a room may reasonably decline.\n  - `notChecked` — the consumer did not resolve the room. An honest answer, and **not** a synonym for `none`: one says the room published nothing, the other says nobody looked."
+        },
         "count": {
           "type": "string",
           "enum": [
@@ -381,6 +393,18 @@ export const RESPONSE_PAYLOAD_SCHEMA = {
           ],
           "description": "Whether this root matches what the agent has seen from this host for this room **at this `headVersion`**.\n\nThis is the comparison a member cannot make for themselves. A tab does not outlive itself and a CLI holds nothing; the agent is the only party on the member's side of the boundary that saw both reads.\n\n  - `agree` — seen at this head before, same root.\n  - `conflict` — seen at this head before, **different root**. A host caught: there is no write to attribute the difference to, because a write would have moved the head.\n  - `noneHeld` — first read at this head. Not evidence of anything; a memory of one is not a comparison.\n  - `notChecked` — this agent keeps no root history. An honest answer for an agent that cannot make the comparison, and **not** a synonym for `noneHeld`: one says nothing was found, the other says nothing was looked for.\n\nREQUIRED, so that an agent which does not check has to say so rather than omit the question."
         },
+        "anchor": {
+          "type": "string",
+          "enum": [
+            "agrees",
+            "ahead",
+            "behind",
+            "conflict",
+            "none",
+            "notChecked"
+          ],
+          "description": "How what the host served compares with the room's own **witnessed anchor** (`EpochAnchor`).\n\nThis is the comparison that needs neither a gossip channel rooms deliberately lack nor durable state in an agent: every member resolves the same room DID and reads the same entry, co-signed by witnesses. It is the only one of the three a first-time reader can make.\n\n  - `agrees` — the host served the anchored state, and its root matches.\n  - `ahead` — the room has moved past the anchor. The ordinary case; an anchor describes a moment, not the present, and says nothing about records written since.\n  - `behind` — **the host is serving a state older than the room's own witnessed statement.** A rollback, and a detection nothing else in this family can make: a member with no history, no peer and no prior read still catches it.\n  - `conflict` — same `headVersion` as the anchor, different root. The host has contradicted a value its own room published and witnesses co-signed.\n  - `none` — the room has published no anchor. Not a fault; anchoring costs a witnessed update and a key rotation, and a room may reasonably decline.\n  - `notChecked` — the consumer did not resolve the room. An honest answer, and **not** a synonym for `none`: one says the room published nothing, the other says nobody looked."
+        },
         "count": {
           "type": "string",
           "enum": [