@openwop/spec-artifacts 2.0.0-rc.0

package/schemas/v2/goal.schema.json

@@ -0,0 +1,188 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v2/goal.schema.json",
+  "title": "Goal",
+  "description": "RFC 0097 §B. A standing goal — a durable objective with explicit completion criteria, evaluated by a host-side judge (RFC 0090 verifier verdict or an opaque host evaluator), that keeps an agent working across turns and runs until the judge is satisfied, a declared RFC 0058 bound is crossed, or the agent escalates (RFC 0044). Completion MUST be the judge's verdict — a client MUST NOT set `state: satisfied` directly. Continuation MUST be bounded. `objective` and any verdict payload are SR-1 redaction-safe. Gated on the `agents.goals` capability.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "id",
+    "objective",
+    "state",
+    "completion",
+    "continuation",
+    "bounds",
+    "owner",
+    "createdAt"
+  ],
+  "properties": {
+    "id": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Host-assigned identifier."
+    },
+    "objective": {
+      "type": "string",
+      "description": "The standing objective. SR-1 redaction-safe — no secrets/PII."
+    },
+    "state": {
+      "type": "string",
+      "enum": [
+        "active",
+        "satisfied",
+        "escalated",
+        "abandoned",
+        "bound-exceeded"
+      ],
+      "description": "Lifecycle state. `satisfied` is set ONLY by the host on a judge verdict, never by a client. `bound-exceeded` is set when a declared bound is crossed; `escalated` when an RFC 0044 confidence-escalation interrupt fires against the goal; `abandoned` on explicit abandon."
+    },
+    "completion": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "check"
+      ],
+      "description": "How the goal's completion is judged.",
+      "properties": {
+        "check": {
+          "type": "string",
+          "enum": [
+            "verifier",
+            "host"
+          ],
+          "description": "`verifier`: completion is an RFC 0090 verifier verdict. `host`: an opaque host evaluator."
+        },
+        "verifierRef": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "default": null,
+          "description": "RFC 0090 verifier id when `check = verifier`."
+        },
+        "lastVerdict": {
+          "type": [
+            "object",
+            "null"
+          ],
+          "default": null,
+          "additionalProperties": false,
+          "description": "Most recent judge verdict. Content-free re: objective text. Non-deterministic judge output — MUST be persisted (carried in the `goal.evaluated` event / checkpoint) and never recomputed on replay/fork.",
+          "properties": {
+            "satisfied": {
+              "type": "boolean"
+            },
+            "confidence": {
+              "type": "number",
+              "minimum": 0,
+              "maximum": 1
+            },
+            "runId": {
+              "$ref": "ids.schema.json#/$defs/runId",
+              "description": "The run this verdict evaluated (RFC 0040 causation-compatible)."
+            }
+          }
+        }
+      }
+    },
+    "continuation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "mode"
+      ],
+      "description": "How the goal re-engages work between judge checks.",
+      "properties": {
+        "mode": {
+          "type": "string",
+          "enum": [
+            "schedule",
+            "commitment",
+            "heartbeat",
+            "manual"
+          ],
+          "description": "`schedule` (RFC 0052), `commitment` (RFC 0068), `heartbeat` (RFC 0060), `manual`."
+        },
+        "armRef": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "default": null,
+          "description": "The RFC 0052 job / RFC 0068 commitment / RFC 0060 heartbeat that re-engages work for this goal."
+        }
+      }
+    },
+    "bounds": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "RFC 0058 execution bounds. The host MUST stop continuation and set `state: bound-exceeded` when any declared bound is crossed. When `agents.goals.requiresBounds` is true, at least one bound MUST be present before the goal may activate.",
+      "properties": {
+        "maxLoopIterations": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "RFC 0058. Max contributing iterations before the goal is bound-exceeded."
+        },
+        "runTimeoutMs": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "RFC 0058. Wall-clock deadline (ms) for the standing goal."
+        },
+        "maxCostUsd": {
+          "type": "number",
+          "minimum": 0,
+          "description": "RFC 0084. Accumulated cost ceiling across contributing runs."
+        }
+      }
+    },
+    "progress": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Continuation progress so far.",
+      "properties": {
+        "iterations": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "contributingRunIds": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "RFC 0040 causation-compatible."
+        }
+      }
+    },
+    "owner": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "tenant"
+      ],
+      "description": "RFC 0048 identity triple. Redaction-safe — `principal` is an opaque id, never PII or credential material.",
+      "properties": {
+        "tenant": {
+          "type": "string",
+          "minLength": 1
+        },
+        "workspace": {
+          "type": "string",
+          "minLength": 1
+        },
+        "principal": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "createdAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "updatedAt": {
+      "type": "string",
+      "format": "date-time"
+    }
+  },
+  "x-openwop-seeded-from": "v1"
+}

package/schemas/v2/heartbeat-evaluated.schema.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v2/heartbeat-evaluated.schema.json",
+  "title": "HeartbeatEvaluated",
+  "description": "RFC 0060. Emitted every tick by a host advertising `capabilities.heartbeat.supported: true` — the observability record of a heartbeat predicate evaluation. Heartbeat-scoped (NOT a replayable run-event-log entry). Carries no external state or secret material; `changed` gates whether a `heartbeat.stateChanged` + enqueued run follow.",
+  "type": "object",
+  "required": [
+    "heartbeatId",
+    "status",
+    "changed"
+  ],
+  "properties": {
+    "heartbeatId": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Host-assigned identifier for the heartbeat whose tick this records."
+    },
+    "status": {
+      "type": "string",
+      "enum": [
+        "ok",
+        "timeout",
+        "error"
+      ],
+      "description": "`ok` — predicate evaluated within `maxRuntimeMs`. `timeout` — terminated at the budget (RFC 0060 §B.2). `error` — the predicate threw."
+    },
+    "changed": {
+      "type": "boolean",
+      "description": "Whether the predicate's state transitioned vs. the prior tick. `true` is the only path that may emit `heartbeat.stateChanged` and enqueue a run."
+    }
+  },
+  "additionalProperties": false,
+  "x-openwop-seeded-from": "v1"
+}

package/schemas/v2/heartbeat-state-changed.schema.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v2/heartbeat-state-changed.schema.json",
+  "title": "HeartbeatStateChanged",
+  "description": "RFC 0060. Emitted ONLY on a predicate-state transition — an unchanged tick MUST NOT emit it (this is what prevents notification spam). Heartbeat-scoped (NOT a replayable run-event-log entry). `from`/`to` are opaque host-persisted predicate-state tokens; they MUST NOT carry secret or external-content material beyond the minimal state needed to detect a transition.",
+  "type": "object",
+  "required": [
+    "heartbeatId",
+    "from",
+    "to"
+  ],
+  "properties": {
+    "heartbeatId": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Host-assigned identifier for the heartbeat that transitioned."
+    },
+    "from": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "Prior tick's predicate state (opaque, host-defined)."
+    },
+    "to": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "Current tick's predicate state — the transition target (opaque, host-defined)."
+    }
+  },
+  "additionalProperties": false,
+  "x-openwop-seeded-from": "v1"
+}

package/schemas/v2/ids.schema.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v2/ids.schema.json",
+  "title": "OpenWOP v2 identifier grammars (RFC 0170 §D.1)",
+  "description": "One $defs entry per id kind. Every id field in every v2 schema, OpenAPI parameter and response body $refs its kind. `minted` records who mints the id: host (opaque, checkable: `^[A-Za-z0-9._~-]{16,128}$` after any tenant segment), author (a workflow/pack author chooses it; the v1 grammar stands), registry (the pack registry mints it). Tenant-bound kinds (runId, interruptId, subscriptionId, deliveryId, effectId) carry the tenant segment: a host MUST reject an id whose tenant segment is not the caller's.",
+  "type": "object",
+  "additionalProperties": false,
+  "$defs": {
+    "opaque": { "type": "string", "pattern": "^[A-Za-z0-9._~-]{16,128}$", "description": "Host-minted opaque token: no `@`, no whitespace, no `/`; 16–128 characters." },
+    "tenantId": { "type": "string", "pattern": "^[A-Za-z0-9._~-]{1,128}$", "x-openwop-minted": "host" },
+    "workspaceId": { "type": "string", "pattern": "^[A-Za-z0-9._~-]{1,128}$", "x-openwop-minted": "host" },
+    "subjectId": { "type": "string", "pattern": "^[^\\s/]{1,256}$", "description": "Issuer-scoped, stable, opaque (RFC 0170 §A); the issuer's grammar, never PII.", "x-openwop-minted": "host" },
+    "runId": { "type": "string", "pattern": "^[A-Za-z0-9._~-]{1,128}/[A-Za-z0-9._~-]{16,128}$", "description": "Tenant-bound: `<tenantId>/<opaque>`.", "x-openwop-minted": "host", "x-openwop-tenant-bound": true },
+    "interruptId": { "type": "string", "pattern": "^[A-Za-z0-9._~-]{1,128}/[A-Za-z0-9._~-]{16,128}$", "x-openwop-minted": "host", "x-openwop-tenant-bound": true },
+    "subscriptionId": { "type": "string", "pattern": "^[A-Za-z0-9._~-]{1,128}/[A-Za-z0-9._~-]{16,128}$", "x-openwop-minted": "host", "x-openwop-tenant-bound": true },
+    "deliveryId": { "type": "string", "pattern": "^[A-Za-z0-9._~-]{1,128}/[A-Za-z0-9._~-]{16,128}$", "x-openwop-minted": "host", "x-openwop-tenant-bound": true },
+    "effectId": { "type": "string", "pattern": "^[A-Za-z0-9._~-]{1,128}/[A-Za-z0-9._~-]{16,128}$", "x-openwop-minted": "host", "x-openwop-tenant-bound": true },
+    "eventId": { "type": "string", "pattern": "^[A-Za-z0-9._~-]{16,128}$", "x-openwop-minted": "host" },
+    "traceId": { "type": "string", "pattern": "^[0-9a-f]{32}$", "description": "W3C trace-context trace-id.", "x-openwop-minted": "host" },
+    "spanId": { "type": "string", "pattern": "^[0-9a-f]{16}$", "description": "W3C trace-context parent-id.", "x-openwop-minted": "host" },
+    "keyId": { "type": "string", "pattern": "^[A-Za-z0-9._~-]{1,128}$", "description": "A signing-key identifier (registry `signingKeys[].keyId`, resume-token `kid`, bundle signature `keyId`).", "x-openwop-minted": "registry" },
+    "nodeId": { "type": "string", "pattern": "^[A-Za-z0-9._~:-]{1,128}$", "description": "Author-chosen within a workflow definition.", "x-openwop-minted": "author" },
+    "workflowId": { "type": "string", "pattern": "^[A-Za-z0-9._~:-]{1,128}$", "x-openwop-minted": "author" },
+    "agentId": { "type": "string", "pattern": "^[A-Za-z0-9._~:-]{1,128}$", "x-openwop-minted": "author" },
+    "chainId": { "type": "string", "pattern": "^[A-Za-z0-9._~:-]{1,128}$", "x-openwop-minted": "author" },
+    "pluginId": { "type": "string", "pattern": "^[A-Za-z0-9._~:-]{1,128}$", "x-openwop-minted": "author" },
+    "templateId": { "type": "string", "pattern": "^[A-Za-z0-9._~:-]{1,128}$", "x-openwop-minted": "author" },
+    "libraryId": { "type": "string", "pattern": "^[A-Za-z0-9._~:-]{1,128}$", "x-openwop-minted": "author" },
+    "typeId": { "type": "string", "pattern": "^[a-z][a-z0-9-]*(\\.[a-z][a-zA-Z0-9-]*)+$", "description": "A node type id (`core.ai.callPrompt`); the RFC 0107 grammar.", "x-openwop-minted": "author" }
+  }
+}

package/schemas/v2/localized-content-language-settings.schema.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v2/localized-content-language-settings.schema.json",
+  "title": "LocalizedContentLanguageSettings",
+  "description": "RFC 0103 (spec/v1/localized-content.md §B). Per-tenant authoring configuration for the content surface. Invariant: `baseLocale` MUST NOT appear in `supportedLocales` (the base locale is carried by section `data`, supported locales by `localizations`). This object is the source of truth for the host's advertised `content` capability block; the advertisement MUST reflect it (`baseLocale` equal, advertised `supportedLocales` equal or a subset).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "baseLocale",
+    "supportedLocales",
+    "autoTranslateOnPublish"
+  ],
+  "properties": {
+    "baseLocale": {
+      "type": "string",
+      "pattern": "^[a-z]{2}(-[A-Z]{2})?$",
+      "description": "The locale section `data` is authored in. MUST equal `capabilities.i18n.defaultLocale`."
+    },
+    "supportedLocales": {
+      "type": "array",
+      "description": "BCP-47 tags the tenant authors content translations for. MUST NOT contain `baseLocale`.",
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z]{2}(-[A-Z]{2})?$"
+      },
+      "uniqueItems": true
+    },
+    "autoTranslateOnPublish": {
+      "type": "boolean",
+      "description": "Whether the host auto-translates missing locale fields on publish (host-extension behavior; informational at the protocol layer)."
+    }
+  },
+  "x-openwop-seeded-from": "v1"
+}

package/schemas/v2/localized-content-page-response.schema.json

@@ -0,0 +1,94 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v2/localized-content-page-response.schema.json",
+  "title": "LocalizedContentPageResponse",
+  "description": "RFC 0103 (spec/v1/localized-content.md §D). The resolved delivery response for `GET /v1/content/pages/{slug}`. `locale` is the negotiated locale (equals the `Content-Language` response header). `sections[]` carry the ALREADY-MERGED section bodies — resolution (the per-section field merge §C) happened server-side, so no `localizations` map appears in the response. Only `published`, `enabled` sections are present, in render order.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "version",
+    "generatedAt",
+    "locale",
+    "slug",
+    "page",
+    "sections"
+  ],
+  "properties": {
+    "version": {
+      "type": "string",
+      "description": "Response schema version marker (e.g. `\"1\"`)."
+    },
+    "generatedAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "When the resolved response was generated."
+    },
+    "locale": {
+      "type": "string",
+      "pattern": "^[a-zA-Z]{2,3}(-[a-zA-Z0-9]{2,8}){0,3}$",
+      "description": "The negotiated locale actually used (BCP-47). Equals the `Content-Language` response header."
+    },
+    "slug": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*$",
+      "description": "The requested page slug."
+    },
+    "page": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "pageId",
+        "slug",
+        "name"
+      ],
+      "description": "Resolved page metadata (status omitted — only published pages are delivered).",
+      "properties": {
+        "pageId": {
+          "type": "string",
+          "minLength": 1
+        },
+        "slug": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9-]*$"
+        },
+        "name": {
+          "type": "string",
+          "minLength": 1
+        },
+        "seo": {
+          "type": "object",
+          "additionalProperties": true
+        }
+      }
+    },
+    "sections": {
+      "type": "array",
+      "description": "Resolved sections in render order; each body is the merged result, not the raw record.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "sectionId",
+          "sectionType",
+          "data"
+        ],
+        "properties": {
+          "sectionId": {
+            "type": "string",
+            "minLength": 1
+          },
+          "sectionType": {
+            "type": "string",
+            "minLength": 1
+          },
+          "data": {
+            "type": "object",
+            "additionalProperties": true,
+            "description": "The merged section body for the negotiated locale (exact → family → base shallow overlay)."
+          }
+        }
+      }
+    }
+  },
+  "x-openwop-seeded-from": "v1"
+}

package/schemas/v2/localized-content-page.schema.json

@@ -0,0 +1,87 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v2/localized-content-page.schema.json",
+  "title": "LocalizedContentPage",
+  "description": "RFC 0103 (spec/v1/localized-content.md §B). An authored content page: an ordered composition of sections addressed by a URL `slug`. Publication status is atomic across locales for v1. SEO carries hreflang + og:locale alternates so a renderer can emit per-locale link relations.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "pageId",
+    "slug",
+    "name",
+    "status",
+    "sectionOrder"
+  ],
+  "properties": {
+    "pageId": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Stable identifier of the page within its tenant."
+    },
+    "slug": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*$",
+      "description": "URL slug for public delivery (`GET /v1/content/pages/{slug}`). Lowercase, hyphen-separated."
+    },
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Human-facing page name (admin/authoring label)."
+    },
+    "status": {
+      "type": "string",
+      "enum": [
+        "draft",
+        "published"
+      ],
+      "description": "Publication status, atomic across locales for v1. A `draft` page MUST NOT be served on the public delivery path."
+    },
+    "sectionOrder": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "description": "Ordered list of `sectionId`s defining the page's render order."
+    },
+    "seo": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Optional SEO metadata for per-locale link relations.",
+      "properties": {
+        "hreflang": {
+          "type": "array",
+          "description": "hreflang alternates: per-locale canonical URLs.",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "locale",
+              "href"
+            ],
+            "properties": {
+              "locale": {
+                "type": "string",
+                "pattern": "^[a-z]{2}(-[A-Z]{2})?$"
+              },
+              "href": {
+                "type": "string",
+                "format": "uri"
+              }
+            }
+          }
+        },
+        "ogLocaleAlternates": {
+          "type": "array",
+          "description": "og:locale:alternate values.",
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z]{2}(-[A-Z]{2})?$"
+          },
+          "uniqueItems": true
+        }
+      }
+    }
+  },
+  "x-openwop-seeded-from": "v1"
+}

package/schemas/v2/localized-content-section.schema.json

@@ -0,0 +1,63 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v2/localized-content-section.schema.json",
+  "title": "LocalizedContentSection",
+  "description": "RFC 0103 (spec/v1/localized-content.md §B). One section record of an authored content page. A section is ONE record carrying a base `data` payload (authored in the host's `content.baseLocale`) plus a sparse `localizations` map of partial per-locale field overrides — never one record per locale. The negotiated locale's resolved body is computed by the normative per-section field merge (exact-locale → language-family → base `data`, shallow overlay; §C). Body field shapes inside `data`/`localizations` are open and host/section-type-defined; this schema closes the envelope, not the body.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "sectionId",
+    "sectionType",
+    "data",
+    "localizations",
+    "status",
+    "enabled",
+    "order"
+  ],
+  "properties": {
+    "sectionId": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Stable identifier of the section within its page."
+    },
+    "sectionType": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The section-type discriminator (e.g. `hero`, `features`). The host/section-type defines the body field shape; the protocol does not."
+    },
+    "data": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "The base/default-locale fields, authored in `content.baseLocale`. Open object — body shapes are the host/section-type's concern."
+    },
+    "localizations": {
+      "type": "object",
+      "description": "Sparse map of per-locale partial field overrides. MAY be empty (`{}`). Each key is a BCP-47 tag matching `^[a-z]{2}(-[A-Z]{2})?$` and MUST NOT equal `content.baseLocale` (the base locale is carried by `data`). Each value is a partial overlay of `data` fields; missing fields fall through to `data` (per-section merge §C).",
+      "propertyNames": {
+        "pattern": "^[a-z]{2}(-[A-Z]{2})?$"
+      },
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": true,
+        "description": "Partial field overrides for one locale; shallow-overlaid onto `data`."
+      }
+    },
+    "status": {
+      "type": "string",
+      "enum": [
+        "draft",
+        "published"
+      ],
+      "description": "Publication status. Atomic across all locales for v1 (no per-locale publish). The public delivery path serves `published` only."
+    },
+    "enabled": {
+      "type": "boolean",
+      "description": "Whether the section participates in delivery when its page is rendered."
+    },
+    "order": {
+      "type": "integer",
+      "description": "Render order of the section within its page (lower first). `sectionOrder` on the page is authoritative; `order` is the per-section tiebreak/sort hint."
+    }
+  },
+  "x-openwop-seeded-from": "v1"
+}

package/schemas/v2/memory-entry.schema.json

@@ -0,0 +1,45 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v2/memory-entry.schema.json",
+  "title": "MemoryEntry",
+  "description": "A single memory entry returned by `MemoryAdapter.list` or `MemoryAdapter.get` (RFC 0004). Hosts that ship cross-run memory expose entries in this shape regardless of their internal storage format. Mid-run mutations to the underlying store are NOT visible to the same run — `list` returns entries that existed at run start (preserves replay determinism per RFC 0004 §A).",
+  "type": "object",
+  "required": [
+    "id",
+    "content",
+    "tags",
+    "createdAt"
+  ],
+  "properties": {
+    "id": {
+      "type": "string",
+      "description": "Memory entry id. Stable for the lifetime of the entry. Hosts MAY tenant-prefix (`mem_<wsId>_<id>`) for defense in depth, but the protocol is silent on the id shape — see RFC 0004 §Unresolved questions #1. Length cap matches Firestore document-id limit (1500 octets) so adapters that pass-through native Firestore IDs validate cleanly.",
+      "minLength": 1,
+      "maxLength": 1500
+    },
+    "content": {
+      "type": "string",
+      "description": "Memory body. UTF-8 plaintext. Hosts MUST honor the redaction invariant SR-1 (RFC 0004 §D) at write time — content reaching this projection MUST NOT contain plaintext secret values that flowed through the run's BYOK harness."
+    },
+    "tags": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "maxLength": 256
+      },
+      "description": "Free-form tags for filtering. Hosts MAY enforce caps. Empty strings are tolerated by the schema (matches reference-impl behavior) but hosts SHOULD filter them at write time. The `MemoryListOptions.tag` filter is a set-membership check against this array. Hosts that want to surface their internal `MemorySource` (or similar host-defined classification) MAY do so via tags (e.g., `tags: ['source:session']`) per RFC 0004 §G."
+    },
+    "createdAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp of entry creation. Never mutated post-create; subsequent edits to the entry are out-of-spec at the read-path layer."
+    },
+    "expiresAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Optional TTL. When the host's clock passes this value, the entry MUST NOT be returned by `list` / `get`. Hosts MAY also delete expired entries from storage as a side effect."
+    }
+  },
+  "additionalProperties": false,
+  "x-openwop-seeded-from": "v1"
+}

package/schemas/v2/memory-list-options.schema.json

@@ -0,0 +1,41 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v2/memory-list-options.schema.json",
+  "title": "MemoryListOptions",
+  "description": "Options accepted by `MemoryAdapter.list` (RFC 0004). All fields optional; default is \"all entries, newest first.\" Hosts MAY further bound results per their scale-profile.",
+  "type": "object",
+  "properties": {
+    "limit": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Cap on entries returned. `0` means \"no limit\" (treated identically to omission); positive integers cap the result. Hosts MAY further bound the effective cap per their scale-profile. When omitted, the host applies its own default cap (typical: 100 entries)."
+    },
+    "tag": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 256,
+      "description": "Filter to entries whose `tags` array contains this string (set-membership check). Hosts MAY support more advanced filtering as a host extension under a `vendor.<host>.*` field."
+    },
+    "tokenBudget": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "RFC 0113. Max cumulative tokens across returned entries, denominated in the unit named by `capabilities.memory.injectionBudget.tokenCounter`. The adapter MUST return a prefix of the ranked entry list whose cumulative token count does not exceed this; a single entry exceeding the budget on its own MUST be omitted (not truncated mid-entry). MAY combine with `limit` — the adapter honors whichever yields fewer entries. Requires the host to advertise `memory.injectionBudget.supported`."
+    },
+    "rank": {
+      "type": "string",
+      "enum": [
+        "recency",
+        "relevance"
+      ],
+      "description": "RFC 0113. Selection order for the (optionally `tokenBudget`-bounded) read. `recency` (default when absent) orders most-recent-first — today's behavior. `relevance` DELEGATES to the existing `memory.search` semantic mode (RFC 0080): it requires `query` AND that the host advertise `capabilities.memory.search` with `semantic` mode, and is the budgeted projection OVER that existing search surface — NOT a new ranking capability. A host that does not advertise `memory.search` semantic mode MUST reject `rank:'relevance'` (or fall back to `'recency'` per its documented behavior)."
+    },
+    "query": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 4096,
+      "description": "RFC 0113. Free-text relevance anchor (the `memory.search` semantic query) — REQUIRED when `rank:'relevance'`, ignored otherwise."
+    }
+  },
+  "additionalProperties": false,
+  "x-openwop-seeded-from": "v1"
+}