@openvtc/trust-tasks 0.27.3 → 0.27.5

package/src/vta/_shared/0.1/app-state-record.ts

@@ -20,4 +20,4 @@ export interface AppStateRecordSharedDefinitionForTheVtaAppStateSpecFamily {
  * The definitions this shared schema publishes, hoisted to one declaration each.
  * See "../../../_shared/components.js".
  */
-export type { AppStateRecord, ExpectedVersion_VtaV0_1 as ExpectedVersion, Key_VtaV0_1 as Key, Namespace, Version_VtaV0_1 as Version, WriteResult } from "../../../_shared/components.js";
+export type { AppStateRecord, ExpectedVersion_VtaV0_1 as ExpectedVersion, Key_VtaV0_1 as Key, Namespace, Version_VtaV0_1 as Version, WriteResult_VtaV0_1 as WriteResult } from "../../../_shared/components.js";

package/src/vta/_shared/0.1/service.ts

@@ -14,4 +14,4 @@ export interface ServiceDefinitionsSharedAcrossTheVtaServicesSpecFamily {
  * The definitions this shared schema publishes, hoisted to one declaration each.
  * See "../../../_shared/components.js".
  */
-export type { DrainEntry, RollbackResult, ServiceKind, ServiceMutationResult, ServiceState } from "../../../_shared/components.js";
+export type { DrainEntry_VtaV0_1 as DrainEntry, RollbackResult_VtaV0_1 as RollbackResult, ServiceKind, ServiceMutationResult_VtaV0_1 as ServiceMutationResult, ServiceState_VtaV0_1 as ServiceState } from "../../../_shared/components.js";

package/src/vta/_shared/0.1/webvh-records.ts

@@ -14,4 +14,4 @@ export interface WebVHRecordsSharedDefinitionsForTheVtaWebvhSpecFamily {
  * The definitions this shared schema publishes, hoisted to one declaration each.
  * See "../../../_shared/components.js".
  */
-export type { AgentNameEntry, WebvhDidRecord, WebvhServerRecord } from "../../../_shared/components.js";
+export type { AgentNameEntry_VtaV0_1 as AgentNameEntry, WebvhDidRecord, WebvhServerRecord } from "../../../_shared/components.js";

package/src/vta/_shared/0.7/app-state-record.ts

@@ -0,0 +1,23 @@
+/**
+ * Generated by scripts/build-ts-bindings.mjs — DO NOT EDIT BY HAND.
+ * Source: specs/vta/_shared/0.7/app-state-record.schema.json
+ */
+
+/**
+ * Application state is versioned, namespaced JSON that an application owns and the VTA stores without interpreting. A record is addressed by the triple `(contextId, namespace, key)`; `AppStateRecord` is the shape every task in the family hands back, defined once here because `get`, `list`, `get-many` and the conflict details of `put` and `put-many` all return the same record and an inline copy per task would fork the moment one of them gained a member.
+ *
+ * The store is deliberately schema-agnostic: `value` is any JSON, and the maintainer never validates, migrates, or interprets it. It is also deliberately NOT a secret store — the vault (`vault/*`) is where secret material belongs, and a maintainer SHOULD surface application state in operator tooling on that understanding.
+ *
+ * The version counter is the family's load-bearing invariant and is described once, here. `version` is a monotonically increasing integer maintained per `(contextId, namespace)` pair, NOT per record: every write in a namespace takes the next value of that namespace's counter, and a record's `version` is the counter value its most recent write took. One number therefore serves two purposes that would otherwise need two — it is the optimistic-concurrency token `expectedVersion` is compared against, and it is the watermark `sinceVersion` is compared against. A per-record counter could do the first but not the second, because two records' counters are not comparable to each other and so no single number can mean "everything changed after this point". Consumers MUST treat version numbers as opaque and monotonic: a record's version can jump by any amount between two writes, because writes to its neighbours consumed the intervening values.
+ *
+ * Timestamp invariants (SHOULD-level, prose — not expressible in JSON Schema): when `createdAt` is present, `updatedAt >= createdAt`; when `deletedAt` is present, `deleted` is true and `deletedAt >= createdAt`. Consumers SHOULD reject documents that violate either.
+ */
+export interface AppStateRecordSharedDefinitionForTheVtaAppStateSpecFamily {
+  [k: string]: unknown | undefined;
+}
+
+/**
+ * The definitions this shared schema publishes, hoisted to one declaration each.
+ * See "../../../_shared/components.js".
+ */
+export type { ExpectedVersion_VtaV0_1 as ExpectedVersion, Key_VtaV0_1 as Key, Namespace, Version_VtaV0_1 as Version, WriteResult_VtaV0_7 as WriteResult } from "../../../_shared/components.js";

package/src/vta/_shared/0.7/did-template.ts

@@ -0,0 +1,17 @@
+/**
+ * Generated by scripts/build-ts-bindings.mjs — DO NOT EDIT BY HAND.
+ * Source: specs/vta/_shared/0.7/did-template.schema.json
+ */
+
+/**
+ * A *DID template* is the JSON shape of a DID document with `{TOKEN}` placeholders plus the variable contract the VTA's renderer enforces; the VTA fills the placeholders with keys it mints and caller-supplied variables when provisioning an integration. `DidTemplate` is the authored shape a caller uploads; `DidTemplateRecord` is the persisted shape the VTA returns (the DidTemplate fields flattened at the top level alongside the resolved `Scope` and provenance metadata). Shared by every task in the vta/did-templates/* family so the record is defined once rather than duplicated per task.
+ */
+export interface DidTemplateDidTemplateRecordSharedDefinitionsForTheVtaDidTemplatesSpecFamily {
+  [k: string]: unknown | undefined;
+}
+
+/**
+ * The definitions this shared schema publishes, hoisted to one declaration each.
+ * See "../../../_shared/components.js".
+ */
+export type { DidTemplate_VtaV0_2 as DidTemplate, DidTemplateRecord_VtaV0_7 as DidTemplateRecord, Scope_VtaV0_1 as Scope } from "../../../_shared/components.js";

package/src/vta/_shared/0.7/webvh-records.ts

@@ -0,0 +1,17 @@
+/**
+ * Generated by scripts/build-ts-bindings.mjs — DO NOT EDIT BY HAND.
+ * Source: specs/vta/_shared/0.7/webvh-records.schema.json
+ */
+
+/**
+ * A `did:webvh` DID is published as an append-only log served at a URL. The VTA holds the keys and the authority to append; a *hosting server* serves the log. These definitions describe what the VTA holds about each: the DID record, the server registration, and an agent name bound to a DID. Shared because the DID record is returned by create, get and list, and the server record by list and register.
+ */
+export interface WebVHRecordsSharedDefinitionsForTheVtaWebvhSpecFamily {
+  [k: string]: unknown | undefined;
+}
+
+/**
+ * The definitions this shared schema publishes, hoisted to one declaration each.
+ * See "../../../_shared/components.js".
+ */
+export type { AgentNameEntry_VtaV0_7 as AgentNameEntry } from "../../../_shared/components.js";

package/src/vta/_shared/0.8/service.ts

@@ -0,0 +1,17 @@
+/**
+ * Generated by scripts/build-ts-bindings.mjs — DO NOT EDIT BY HAND.
+ * Source: specs/vta/_shared/0.8/service.schema.json
+ */
+
+/**
+ * A *service* is a transport the agent advertises in its own DID document: DIDComm mediation, a REST endpoint, TSP mediation, or a WebAuthn origin. Enabling or disabling one edits `service` in the agent's did:webvh document and republishes the signed log, so every mutation in this family produces a new log entry rather than flipping a runtime flag — which is why they all return `ServiceMutationResult`. These shapes are defined once because `enable`, `disable`, `update` and `rollback` return the same result, and `list` and `get` return the same state; an inline copy per task would fork the moment one of them gained a member.
+ */
+export interface ServiceDefinitionsSharedAcrossTheVtaServicesSpecFamily {
+  [k: string]: unknown | undefined;
+}
+
+/**
+ * The definitions this shared schema publishes, hoisted to one declaration each.
+ * See "../../../_shared/components.js".
+ */
+export type { DrainEntry_VtaV0_8 as DrainEntry, RollbackResult_VtaV0_8 as RollbackResult, ServiceKind, ServiceMutationResult_VtaV0_8 as ServiceMutationResult, ServiceState_VtaV0_8 as ServiceState } from "../../../_shared/components.js";

package/src/vta/app-state/list/1.1/payload.ts

@@ -0,0 +1,444 @@
+/**
+ * Generated by scripts/build-ts-bindings.mjs — DO NOT EDIT BY HAND.
+ * Source: specs/vta/app-state/list/1.1/payload.schema.json
+ */
+
+import type { AppStateRecord, Ext, Key_VtaV0_1 as Key, Namespace, Version_VtaV0_1 as Version } from "../../../../_shared/components.js";
+
+
+/**
+ * Enumerate application-state records in a context. Two modes, distinguished by whether `sinceVersion` is supplied. Without it this is a SNAPSHOT of live records, optionally narrowed by `prefix`. With it this is a CHANGE FEED: every record in the namespace whose version exceeds the watermark, tombstones included, which is what lets an incremental consumer converge. Pagination is opaque-cursor based.
+ */
+export interface VTAApplicationStateListPayload {
+  /**
+   * The VTA context to enumerate; the isolation boundary.
+   */
+  contextId: string;
+  /**
+   * Restrict to one namespace. Optional in snapshot mode, where omitting it enumerates every namespace the caller can read in the context. REQUIRED in change-feed mode, because the version counter `sinceVersion` is compared against is maintained per (contextId, namespace) and a watermark spanning namespaces would name no single point in time.
+   */
+  namespace?: Namespace;
+  /**
+   * Restrict to records whose `key` begins with this byte prefix, compared over the UTF-8 encoding. Lets a consumer read one record family — `community/`, `contact/` — without dragging every record in the namespace through the response.
+   */
+  prefix?: string;
+  /**
+   * Watermark. Selects change-feed mode: only records whose `version` is strictly greater are returned, tombstones included. Supply the `highWatermark` from the previous sync, or 0 for a first full pull in change-feed form. Requires `namespace`.
+   */
+  sinceVersion?: number;
+  /**
+   * When true, each returned record carries its `value`. Defaults to false, which returns the metadata view — address, version, timestamps, `valueBytes` — so a prefix scan is cheap. Setting it makes a scan one round trip rather than a scan plus N gets, at the cost of the response carrying every value.
+   */
+  includeValues?: boolean;
+  /**
+   * Snapshot mode only: when true, tombstones still inside the retention window are returned alongside live records. Defaults to false. In change-feed mode tombstones are always returned and this member MUST NOT be set to false — a change feed that omits deletions cannot converge, so asking for one is a contradiction rather than a preference.
+   */
+  includeDeleted?: boolean;
+  /**
+   * An opaque continuation token from a previous response's `nextCursor`; a responder MUST NOT accept a cursor it did not issue. Consumers MUST treat it as opaque: never construct, decode, mutate, or infer meaning from one.
+   */
+  cursor?: string;
+  /**
+   * The most records to return; the responder chooses a default and MAY return fewer. The maintainer applies its own ceiling, and fewer is likely when `includeValues` is set and the values are large.
+   */
+  limit?: number;
+  /**
+   * Ecosystem-defined extension members per SPEC.md §4.5.1.
+   */
+  ext?: Ext;
+}
+/**
+ * Success response to vta/app-state/list. Type https://trusttasks.org/spec/vta/app-state/list/1.1#response.
+ */
+export interface VTAApplicationStateListResponsePayload {
+  /**
+   * Matching records in ascending key order in snapshot mode, and ascending version order in change-feed mode — the latter so that a consumer applying them in order reaches the same state as the maintainer. May be empty.
+   */
+  records: AppStateRecord[];
+  /**
+   * Opaque continuation token for the next page, sent back as the request's `cursor`. Present when more matching records exist beyond this page; absent on the last page.
+   */
+  nextCursor?: string;
+  /**
+   * The namespace's current counter value. Present whenever `namespace` was supplied. This is what a consumer stores as its next `sinceVersion` — NOT the maximum version among `records`, which is wrong whenever a `prefix` filtered a later change out, and undefined when the page is empty. A paginating consumer MUST NOT advance its stored watermark until it has drained the final page — the one with no `nextCursor` — because the pages of one feed share this value and adopting it early would skip the records still to come.
+   */
+  highWatermark?: Version;
+  /**
+   * How long this maintainer retains tombstones before reaping them. Advisory, and present at the maintainer's discretion, so a consumer can schedule its syncs to stay inside the window rather than discovering it has fallen out of it via vta/app-state/list:watermarkTooOld.
+   */
+  tombstoneRetentionSeconds?: number;
+  /**
+   * Ecosystem-defined extension members per SPEC.md §4.5.1.
+   */
+  ext?: Ext;
+}
+
+/** Shared definitions this specification references, re-exported under the names it used to declare them with. */
+export type { AppStateRecord, Ext, Key, Namespace, Version };
+
+/** Trust Task type URI. */
+export const TYPE_URI = "https://trusttasks.org/spec/vta/app-state/list/1.1" as const;
+
+/** Stable alias for this specification's request payload shape. */
+export type Payload = VTAApplicationStateListPayload;
+
+/** Trust Task response type URI (request type URI + "#response"). */
+export const RESPONSE_TYPE_URI = "https://trusttasks.org/spec/vta/app-state/list/1.1#response" as const;
+
+/** Stable alias for this specification's success-response payload shape. */
+export type Response = VTAApplicationStateListResponsePayload;
+
+/**
+ * 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/vta/app-state/list/1.1",
+  "title": "VTA Application State List — payload",
+  "description": "Enumerate application-state records in a context. Two modes, distinguished by whether `sinceVersion` is supplied. Without it this is a SNAPSHOT of live records, optionally narrowed by `prefix`. With it this is a CHANGE FEED: every record in the namespace whose version exceeds the watermark, tombstones included, which is what lets an incremental consumer converge. Pagination is opaque-cursor based.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "contextId"
+  ],
+  "properties": {
+    "contextId": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The VTA context to enumerate; the isolation boundary."
+    },
+    "namespace": {
+      "$ref": "#/$defs/Namespace",
+      "description": "Restrict to one namespace. Optional in snapshot mode, where omitting it enumerates every namespace the caller can read in the context. REQUIRED in change-feed mode, because the version counter `sinceVersion` is compared against is maintained per (contextId, namespace) and a watermark spanning namespaces would name no single point in time."
+    },
+    "prefix": {
+      "type": "string",
+      "maxLength": 512,
+      "description": "Restrict to records whose `key` begins with this byte prefix, compared over the UTF-8 encoding. Lets a consumer read one record family — `community/`, `contact/` — without dragging every record in the namespace through the response."
+    },
+    "sinceVersion": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Watermark. Selects change-feed mode: only records whose `version` is strictly greater are returned, tombstones included. Supply the `highWatermark` from the previous sync, or 0 for a first full pull in change-feed form. Requires `namespace`."
+    },
+    "includeValues": {
+      "type": "boolean",
+      "description": "When true, each returned record carries its `value`. Defaults to false, which returns the metadata view — address, version, timestamps, `valueBytes` — so a prefix scan is cheap. Setting it makes a scan one round trip rather than a scan plus N gets, at the cost of the response carrying every value."
+    },
+    "includeDeleted": {
+      "type": "boolean",
+      "description": "Snapshot mode only: when true, tombstones still inside the retention window are returned alongside live records. Defaults to false. In change-feed mode tombstones are always returned and this member MUST NOT be set to false — a change feed that omits deletions cannot converge, so asking for one is a contradiction rather than a preference."
+    },
+    "cursor": {
+      "type": "string",
+      "description": "An opaque continuation token from a previous response's `nextCursor`; a responder MUST NOT accept a cursor it did not issue. Consumers MUST treat it as opaque: never construct, decode, mutate, or infer meaning from one."
+    },
+    "limit": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 1000,
+      "description": "The most records to return; the responder chooses a default and MAY return fewer. The maintainer applies its own ceiling, and fewer is likely when `includeValues` is set and the values are large."
+    },
+    "ext": {
+      "$ref": "#/$defs/Ext",
+      "description": "Ecosystem-defined extension members per SPEC.md §4.5.1."
+    }
+  },
+  "$defs": {
+    "Response": {
+      "$anchor": "response",
+      "title": "VTA Application State List — response payload",
+      "description": "Success response to vta/app-state/list. Type https://trusttasks.org/spec/vta/app-state/list/1.1#response.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "records"
+      ],
+      "properties": {
+        "records": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/AppStateRecord"
+          },
+          "description": "Matching records in ascending key order in snapshot mode, and ascending version order in change-feed mode — the latter so that a consumer applying them in order reaches the same state as the maintainer. May be empty."
+        },
+        "nextCursor": {
+          "type": "string",
+          "description": "Opaque continuation token for the next page, sent back as the request's `cursor`. Present when more matching records exist beyond this page; absent on the last page."
+        },
+        "highWatermark": {
+          "$ref": "#/$defs/Version",
+          "description": "The namespace's current counter value. Present whenever `namespace` was supplied. This is what a consumer stores as its next `sinceVersion` — NOT the maximum version among `records`, which is wrong whenever a `prefix` filtered a later change out, and undefined when the page is empty. A paginating consumer MUST NOT advance its stored watermark until it has drained the final page — the one with no `nextCursor` — because the pages of one feed share this value and adopting it early would skip the records still to come."
+        },
+        "tombstoneRetentionSeconds": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "How long this maintainer retains tombstones before reaping them. Advisory, and present at the maintainer's discretion, so a consumer can schedule its syncs to stay inside the window rather than discovering it has fallen out of it via vta/app-state/list:watermarkTooOld."
+        },
+        "ext": {
+          "$ref": "#/$defs/Ext",
+          "description": "Ecosystem-defined extension members per SPEC.md §4.5.1."
+        }
+      }
+    },
+    "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-]+)+$"
+      }
+    },
+    "Version": {
+      "title": "Version",
+      "description": "A value of the namespace's monotonic write counter (see this schema's description). Server-assigned; a producer never chooses one.",
+      "type": "integer",
+      "minimum": 1
+    },
+    "AppStateRecord": {
+      "title": "AppStateRecord",
+      "description": "A record as the maintainer holds it. `value` is absent in three distinct situations and a consumer MUST NOT conflate them: the record is a tombstone (`deleted` is true); the caller asked for a metadata-only view (`list` without `includeValues`); or the value genuinely is the JSON literal `null`, in which case `value` is PRESENT and null. This is why `deleted` is required rather than defaulted — a consumer that has to infer deletion from an absent value gets the tombstone case wrong exactly when convergence depends on it.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "contextId",
+        "namespace",
+        "key",
+        "version",
+        "deleted",
+        "updatedAt"
+      ],
+      "properties": {
+        "contextId": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The VTA context the record is scoped to; the isolation boundary."
+        },
+        "namespace": {
+          "$ref": "#/$defs/Namespace"
+        },
+        "key": {
+          "$ref": "#/$defs/Key"
+        },
+        "version": {
+          "$ref": "#/$defs/Version",
+          "description": "The namespace counter value this record's most recent write took. Supply it as `expectedVersion` on the next write to make that write conditional on nothing having changed in between."
+        },
+        "value": {
+          "description": "The stored JSON, in whatever shape the owning application chose. Any JSON value, including `null`. The maintainer neither validates nor interprets it. Absent when this is a tombstone or a metadata-only view — see this definition's description for why that is not the same as a null value."
+        },
+        "valueBytes": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Size of the stored value in bytes, measured as the maintainer measures it for the per-record cap (see `vta/app-state/put`). Present in metadata-only views so a consumer can decide what to fetch without fetching it; absent on a tombstone."
+        },
+        "deleted": {
+          "type": "boolean",
+          "description": "True when this is a tombstone: the record was deleted, and this entry exists so that a consumer syncing incrementally learns of the deletion. Tombstones are reaped after the maintainer's retention window; see `vta/app-state/list`."
+        },
+        "createdAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "When the record was first created at this address. MAY be absent on a tombstone whose body has been discarded."
+        },
+        "updatedAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "When the write that produced this `version` was applied. For a tombstone, when the delete was applied."
+        },
+        "deletedAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "When the record was deleted. Present only when `deleted` is true; equal to `updatedAt` for a tombstone the maintainer has not since rewritten."
+        }
+      }
+    },
+    "Key": {
+      "title": "Key",
+      "description": "Application-chosen identifier for a record within a namespace. Opaque to the maintainer: it MUST NOT be parsed, normalized, or case-folded, and prefix matching in `list` is a byte-prefix comparison over the UTF-8 encoding. Applications SHOULD use `/`-delimited hierarchical keys (`community/acme`, `contact/z6Mk…`) so that `prefix` can address a record family, but the delimiter is a convention between an application and itself — the maintainer attaches no meaning to it.",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 512,
+      "pattern": "^[^\\u0000]+$"
+    },
+    "Namespace": {
+      "title": "Namespace",
+      "description": "Scopes one application's records within a context, so several tools can share a context without colliding — `openvtc`, `cnm`, an agent runtime. The maintainer MUST NOT interpret the value; it is an opaque partition name. Namespaces are first-come and unreserved, so an application SHOULD pick a stable, specific one: a future per-namespace ACL would grant on this exact string, which makes renaming a namespace a migration rather than an edit.",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 64,
+      "pattern": "^[a-z][a-z0-9]*(-[a-z0-9]+)*$"
+    }
+  }
+} 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",
+      "title": "VTA Application State List — response payload",
+      "description": "Success response to vta/app-state/list. Type https://trusttasks.org/spec/vta/app-state/list/1.1#response.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "records"
+      ],
+      "properties": {
+        "records": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/AppStateRecord"
+          },
+          "description": "Matching records in ascending key order in snapshot mode, and ascending version order in change-feed mode — the latter so that a consumer applying them in order reaches the same state as the maintainer. May be empty."
+        },
+        "nextCursor": {
+          "type": "string",
+          "description": "Opaque continuation token for the next page, sent back as the request's `cursor`. Present when more matching records exist beyond this page; absent on the last page."
+        },
+        "highWatermark": {
+          "$ref": "#/$defs/Version",
+          "description": "The namespace's current counter value. Present whenever `namespace` was supplied. This is what a consumer stores as its next `sinceVersion` — NOT the maximum version among `records`, which is wrong whenever a `prefix` filtered a later change out, and undefined when the page is empty. A paginating consumer MUST NOT advance its stored watermark until it has drained the final page — the one with no `nextCursor` — because the pages of one feed share this value and adopting it early would skip the records still to come."
+        },
+        "tombstoneRetentionSeconds": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "How long this maintainer retains tombstones before reaping them. Advisory, and present at the maintainer's discretion, so a consumer can schedule its syncs to stay inside the window rather than discovering it has fallen out of it via vta/app-state/list:watermarkTooOld."
+        },
+        "ext": {
+          "$ref": "#/$defs/Ext",
+          "description": "Ecosystem-defined extension members per SPEC.md §4.5.1."
+        }
+      }
+    },
+    "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-]+)+$"
+      }
+    },
+    "Version": {
+      "title": "Version",
+      "description": "A value of the namespace's monotonic write counter (see this schema's description). Server-assigned; a producer never chooses one.",
+      "type": "integer",
+      "minimum": 1
+    },
+    "AppStateRecord": {
+      "title": "AppStateRecord",
+      "description": "A record as the maintainer holds it. `value` is absent in three distinct situations and a consumer MUST NOT conflate them: the record is a tombstone (`deleted` is true); the caller asked for a metadata-only view (`list` without `includeValues`); or the value genuinely is the JSON literal `null`, in which case `value` is PRESENT and null. This is why `deleted` is required rather than defaulted — a consumer that has to infer deletion from an absent value gets the tombstone case wrong exactly when convergence depends on it.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "contextId",
+        "namespace",
+        "key",
+        "version",
+        "deleted",
+        "updatedAt"
+      ],
+      "properties": {
+        "contextId": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The VTA context the record is scoped to; the isolation boundary."
+        },
+        "namespace": {
+          "$ref": "#/$defs/Namespace"
+        },
+        "key": {
+          "$ref": "#/$defs/Key"
+        },
+        "version": {
+          "$ref": "#/$defs/Version",
+          "description": "The namespace counter value this record's most recent write took. Supply it as `expectedVersion` on the next write to make that write conditional on nothing having changed in between."
+        },
+        "value": {
+          "description": "The stored JSON, in whatever shape the owning application chose. Any JSON value, including `null`. The maintainer neither validates nor interprets it. Absent when this is a tombstone or a metadata-only view — see this definition's description for why that is not the same as a null value."
+        },
+        "valueBytes": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Size of the stored value in bytes, measured as the maintainer measures it for the per-record cap (see `vta/app-state/put`). Present in metadata-only views so a consumer can decide what to fetch without fetching it; absent on a tombstone."
+        },
+        "deleted": {
+          "type": "boolean",
+          "description": "True when this is a tombstone: the record was deleted, and this entry exists so that a consumer syncing incrementally learns of the deletion. Tombstones are reaped after the maintainer's retention window; see `vta/app-state/list`."
+        },
+        "createdAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "When the record was first created at this address. MAY be absent on a tombstone whose body has been discarded."
+        },
+        "updatedAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "When the write that produced this `version` was applied. For a tombstone, when the delete was applied."
+        },
+        "deletedAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "When the record was deleted. Present only when `deleted` is true; equal to `updatedAt` for a tombstone the maintainer has not since rewritten."
+        }
+      }
+    },
+    "Key": {
+      "title": "Key",
+      "description": "Application-chosen identifier for a record within a namespace. Opaque to the maintainer: it MUST NOT be parsed, normalized, or case-folded, and prefix matching in `list` is a byte-prefix comparison over the UTF-8 encoding. Applications SHOULD use `/`-delimited hierarchical keys (`community/acme`, `contact/z6Mk…`) so that `prefix` can address a record family, but the delimiter is a convention between an application and itself — the maintainer attaches no meaning to it.",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 512,
+      "pattern": "^[^\\u0000]+$"
+    },
+    "Namespace": {
+      "title": "Namespace",
+      "description": "Scopes one application's records within a context, so several tools can share a context without colliding — `openvtc`, `cnm`, an agent runtime. The maintainer MUST NOT interpret the value; it is an opaque partition name. Namespaces are first-come and unreserved, so an application SHOULD pick a stable, specific one: a future per-namespace ACL would grant on this exact string, which makes renaming a namespace a migration rather than an edit.",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 64,
+      "pattern": "^[a-z][a-z0-9]*(-[a-z0-9]+)*$"
+    }
+  }
+} 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: false,
+  isRecipientRequired: true,
+  isIssuedAtRequired: false,
+  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: false,
+  isRecipientRequired: true,
+  isIssuedAtRequired: false,
+  payloadSchema: RESPONSE_PAYLOAD_SCHEMA,
+} as const;