@mrciphersmith/keryx 0.2.34 → 0.2.36

package/docs/requirements/shared-agent-context/schemas/README.md

@@ -0,0 +1,65 @@
+# Shared Agent Context — Schemas and Fixtures
+Version: 1.4.0
+
+## Purpose
+
+These are the normative data contracts used by the implemented SAC phases.
+They use JSON Schema Draft 2020-12. Fixtures define the minimum validator and
+integration-test corpus. The
+implementation must enable format assertion and run the semantic validator for
+the declared `x-` invariants: canonical SubjectId topology, realpath/root
+containment, timestamp ordering and ledger-level idempotency.
+
+## Schemas
+
+- [Workspace manifest](workspace-manifest.schema.json)
+- [FWK receipt](fwk-receipt.schema.json)
+- [Access receipt](access-receipt.schema.json)
+- [Workspace proposal](workspace-proposal.schema.json)
+- [Review decision](review-decision.schema.json)
+
+## Fixtures
+
+- [Valid workspace](fixtures/valid-workspace.json)
+- [Invalid workspace](fixtures/invalid-workspace.json)
+- [Valid FWK receipt](fixtures/valid-fwk-receipt.json)
+- [Invalid evidence without revision](fixtures/invalid-evidence-missing-revision.json)
+- [Invalid bound Work without Flow reference](fixtures/invalid-bound-work-no-flow-ref.json)
+- [Valid proposal](fixtures/valid-proposal.json)
+- [Invalid proposal](fixtures/invalid-proposal.json)
+- [Valid accepted transition](fixtures/valid-accepted-transition.json)
+- [Accepted transition with failed security gate](fixtures/invalid-accepted-transition-failed-gate.json)
+- [Accepted transition without target write](fixtures/invalid-accepted-transition-no-target-write.json)
+- [Valid review decision](fixtures/valid-review-decision.json)
+- [Valid access receipt](fixtures/valid-access-receipt.json)
+- [Invalid duplicate roles](fixtures/invalid-duplicate-roles.json)
+- [Invalid unsafe URI](fixtures/invalid-unsafe-uri.json)
+- [Invalid timestamp order](fixtures/invalid-time-order.json)
+- [Invalid stale evidence](fixtures/invalid-stale-evidence.json)
+- [Spoofed viewer mutation](fixtures/invalid-spoofed-viewer-mutation.json)
+- [Denied resource egress](fixtures/invalid-resource-egress.json)
+- [Replay/idempotency corpus](fixtures/replay-idempotency-corpus.json)
+
+Positive fixtures must validate against their named schema. Negative fixtures
+must fail for the documented contract reason. The replay corpus is evaluated by
+the append-only ledger validator, not by an isolated JSON document. All schemas
+forbid raw transcript, prompt, hidden-reasoning and secret payload fields by
+using closed objects.
+
+Phase 5 publishes its minimized learning/evaluation fixtures separately under
+[`fixtures/sac-policy-experiment`](../../../../fixtures/sac-policy-experiment/).
+The manifest is a closed TypeScript/runtime contract rather than an extension
+of AccessReceipt: it records receipt-chain provenance, independent verifier
+artifact hashes, selection/redaction/quarantine rules and deterministic
+train/holdout/adversarial splits. Receipt self-report is never ground truth.
+
+`workspace-proposal` creation also requires minimal `wrapUp` metadata. It is
+only an audit pointer: runtime authorization requires the corresponding
+server-issued, one-time trusted provenance capability bound to its session or
+read-only Flow wrap-up source, actor, workspace, evidence and expiry.
+
+For an accepted transition, `acceptance.targetWrite.binding` is normative and
+retains the exact immutable owner receipt binding. It must repeat the proposal,
+workspace, correlation/idempotency, reviewer-authority and policy-revision
+values of that transition; implementations must not reduce it to a hash after
+verification.

package/docs/requirements/shared-agent-context/schemas/access-receipt.schema.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "keryx/shared-agent-context/access-receipt/v1",
+  "$vocabulary": {"https://json-schema.org/draft/2020-12/vocab/format-assertion": true},
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "id", "workspaceId", "actor", "action", "decision", "recordedAt", "cost", "contextAssembly", "policy", "integrity"],
+  "properties": {
+    "schemaVersion": {"const": "1.0"}, "id": {"type": "string", "pattern": "^[a-z][a-z0-9-]{2,63}$"}, "workspaceId": {"type": "string", "pattern": "^[a-z][a-z0-9-]{2,63}$"}, "actor": {"type": "string", "pattern": "^(?:user|team|service|agent):[a-z0-9][a-z0-9._-]{0,127}$"}, "action": {"enum": ["overview", "fwk", "resource"]}, "decision": {"enum": ["allowed", "denied", "budget-exhausted", "stale"]}, "recordedAt": {"$ref": "#/$defs/utcTimestamp"}, "cost": {"type": "object", "additionalProperties": false, "required": ["toolCalls", "elapsedMs"], "properties": {"tokens": {"type": "integer", "minimum": 0}, "toolCalls": {"type": "integer", "minimum": 0}, "elapsedMs": {"type": "integer", "minimum": 0}}}, "contextAssembly": {"type": "object", "additionalProperties": false, "required": ["traceRef", "configurationRevision", "selected", "omittedOptional"], "properties": {"traceRef": {"$ref": "#/$defs/workspacePath"}, "configurationRevision": {"$ref": "#/$defs/revision"}, "selected": {"type": "array", "items": {"$ref": "#/$defs/workspacePath"}}, "omittedOptional": {"type": "array", "items": {"$ref": "#/$defs/workspacePath"}}}}, "policy": {"type": "object", "additionalProperties": false, "required": ["ref", "revision"], "properties": {"ref": {"$ref": "#/$defs/workspacePath"}, "revision": {"$ref": "#/$defs/revision"}}}, "integrity": {"type": "object", "additionalProperties": false, "required": ["recordHash", "previousRecordHash"], "properties": {"recordHash": {"type": "string", "pattern": "^[a-f0-9]{64}$"}, "previousRecordHash": {"type": "string", "pattern": "^(?:[a-f0-9]{64}|GENESIS)$"}}}, "resourceRef": {"$ref": "#/$defs/workspacePath"}, "outcome": {"enum": ["unknown", "useful", "not-useful"]}},
+  "allOf": [{"if": {"properties": {"action": {"const": "resource"}}, "required": ["action"]}, "then": {"required": ["resourceRef"]}, "else": {"not": {"required": ["resourceRef"]}}}],
+  "x-rootContainment": {"fields": ["resourceRef", "contextAssembly.traceRef", "contextAssembly.selected[]", "contextAssembly.omittedOptional[]", "policy.ref"], "root": "workspace root", "resolveSymlinks": true, "rejectEscapes": true}, "x-integrity": {"appendOnlyLedger": true, "verifyRecordHash": true, "owner": "trusted local service"},
+  "$defs": {"utcTimestamp": {"type": "string", "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(?:\\.[0-9]+)?Z$", "x-formatAssertionRequired": true}, "revision": {"type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,255}$", "x-immutable": true}, "workspacePath": {"type": "string", "pattern": "^\\./(?!.*(?:^|/)\\.\\.(?:/|$))(?:[A-Za-z0-9._-]+/)*[A-Za-z0-9._-]+$"}}
+}

package/docs/requirements/shared-agent-context/schemas/fixtures/invalid-accepted-transition-failed-gate.json

@@ -0,0 +1 @@
+{"schemaVersion":"1.0","recordType":"proposal-transition","eventId":"event-accepted-1","proposalId":"proposal-1","proposalRevision":"1","correlationId":"proposal-correlation-0001","workspaceId":"payments-work","sequence":1,"priorEventHash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","fromStatus":"proposed","toStatus":"accepted","occurredAt":"2026-08-11T00:10:00Z","idempotencyKey":"accepted-transition-0001","acceptance":{"reviewDecisionRef":"./reviews/decision-1","writeIntentRef":"./proposals/proposal-1.intent-1","reviewer":{"subject":"user:reviewer","authority":"owner","trustedPrincipalRef":"./identity/principal-1"},"security":{"gate":"fail","policyRef":"./policies/default","policyRevision":"1"},"freshness":{"state":"fresh","verifiedAt":"2026-08-11T00:05:00Z","maxEvidenceAgeSeconds":3600},"targetWrite":{"receiptRef":"./writes/receipt-1","targetRef":"./memory/constraint","completedAt":"2026-08-11T00:06:00Z"},"evidence":[{"kind":"memory","uri":"./memory/constraint","revision":"1","observedAt":"2026-08-11T00:00:00Z"}],"idempotencyKey":"accepted-transition-0001"}}

package/docs/requirements/shared-agent-context/schemas/fixtures/invalid-accepted-transition-no-target-write.json

@@ -0,0 +1 @@
+{"schemaVersion":"1.0","recordType":"proposal-transition","eventId":"event-accepted-1","proposalId":"proposal-1","proposalRevision":"1","correlationId":"proposal-correlation-0001","workspaceId":"payments-work","sequence":1,"priorEventHash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","fromStatus":"proposed","toStatus":"accepted","occurredAt":"2026-08-11T00:10:00Z","idempotencyKey":"accepted-transition-0001","acceptance":{"reviewDecisionRef":"./reviews/decision-1","reviewer":{"subject":"user:reviewer","authority":"owner","trustedPrincipalRef":"./identity/principal-1"},"security":{"gate":"pass","policyRef":"./policies/default","policyRevision":"1"},"freshness":{"state":"fresh","verifiedAt":"2026-08-11T00:05:00Z","maxEvidenceAgeSeconds":3600},"evidence":[{"kind":"memory","uri":"./memory/constraint","revision":"1","observedAt":"2026-08-11T00:00:00Z"}],"idempotencyKey":"accepted-transition-0001"}}

package/docs/requirements/shared-agent-context/schemas/fixtures/invalid-bound-work-no-flow-ref.json

@@ -0,0 +1 @@
+{"schemaVersion":"1.0","workspaceId":"payments-work","generatedAt":"2026-08-11T00:00:00Z","facts":[],"work":{"state":"bound","completed":["task-1"]},"knowHow":[],"freshness":"fresh"}

package/docs/requirements/shared-agent-context/schemas/fixtures/invalid-duplicate-roles.json

@@ -0,0 +1 @@
+{"schemaVersion":"1.0","id":"payments-work","title":"Payments work","status":"active","members":[{"subject":"team:payments","role":"owner"},{"subject":"team:payments","role":"editor"}],"resources":[],"createdAt":"2026-08-11T00:00:00Z","updatedAt":"2026-08-11T00:00:00Z"}

package/docs/requirements/shared-agent-context/schemas/fixtures/invalid-evidence-missing-revision.json

@@ -0,0 +1 @@
+{"schemaVersion":"1.0","workspaceId":"payments-work","generatedAt":"2026-08-11T00:00:00Z","facts":[{"statement":"Flow is ready","evidence":[{"kind":"flow","uri":"./.metaproject/flows/001","observedAt":"2026-08-11T00:00:00Z","trust":"primary"}],"observedAt":"2026-08-11T00:00:00Z","expiresAt":"2026-08-12T00:00:00Z","freshness":"fresh"}],"work":{"state":"unbound"},"knowHow":[],"freshness":"fresh"}

package/docs/requirements/shared-agent-context/schemas/fixtures/invalid-proposal.json

@@ -0,0 +1 @@
+{"schemaVersion":"1.0","recordType":"proposal-created","id":"proposal-1","proposalRevision":"1","correlationId":"proposal-correlation-0001","workspaceId":"payments-work","kind":"memory-entry","status":"accepted","summary":"redacted summary","evidence":[{"kind":"memory","uri":"./memory/constraint","revision":"1","observedAt":"2026-08-11T00:00:00Z"}],"author":"agent:writer","security":{"gate":"pass","redacted":true,"policyRef":"./policies/default","policyRevision":"1"},"createdAt":"2026-08-11T00:00:00Z"}

package/docs/requirements/shared-agent-context/schemas/fixtures/invalid-resource-egress.json

@@ -0,0 +1 @@
+{"schemaVersion":"1.0","id":"access-1","workspaceId":"payments-work","actor":"agent:release-bot","action":"resource","decision":"allowed","recordedAt":"2026-08-11T00:05:00Z","cost":{"toolCalls":1,"elapsedMs":12},"contextAssembly":{"traceRef":"./context/trace-1","configurationRevision":"1","selected":["./src/payments"],"omittedOptional":[]},"policy":{"ref":"./policies/default","revision":"1"},"integrity":{"recordHash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","previousRecordHash":"GENESIS"},"resourceRef":"https://outside.invalid/resource"}

package/docs/requirements/shared-agent-context/schemas/fixtures/invalid-spoofed-viewer-mutation.json

@@ -0,0 +1 @@
+{"schemaVersion":"1.0","id":"decision-1","proposalId":"proposal-1","proposalRevision":"1","correlationId":"proposal-correlation-0001","workspaceId":"payments-work","decision":"accepted","reviewer":{"subject":"user:viewer","authority":"viewer","trustedPrincipalRef":"./identity/principal-1"},"decidedAt":"2026-08-11T00:05:00Z","idempotencyKey":"review-decision-0001","security":{"gate":"pass","policyRef":"./policies/default","policyRevision":"1"},"freshness":{"state":"fresh","verifiedAt":"2026-08-11T00:05:00Z","evidenceRevision":"1"},"targetWrite":{"receiptRef":"./writes/receipt-1","targetRef":"./memory/constraint","completedAt":"2026-08-11T00:06:00Z"}}

package/docs/requirements/shared-agent-context/schemas/fixtures/invalid-stale-evidence.json

@@ -0,0 +1 @@
+{"schemaVersion":"1.0","id":"decision-1","proposalId":"proposal-1","proposalRevision":"1","correlationId":"proposal-correlation-0001","workspaceId":"payments-work","decision":"accepted","reviewer":{"subject":"user:reviewer","authority":"owner","trustedPrincipalRef":"./identity/principal-1"},"decidedAt":"2026-08-11T00:05:00Z","idempotencyKey":"review-decision-0001","security":{"gate":"pass","policyRef":"./policies/default","policyRevision":"1"},"freshness":{"state":"stale","verifiedAt":"2026-08-11T00:05:00Z","evidenceRevision":"1"},"targetWrite":{"receiptRef":"./writes/receipt-1","targetRef":"./memory/constraint","completedAt":"2026-08-11T00:06:00Z"}}

package/docs/requirements/shared-agent-context/schemas/fixtures/invalid-time-order.json

@@ -0,0 +1 @@
+{"schemaVersion":"1.0","id":"payments-work","title":"Payments work","status":"active","members":[{"subject":"team:payments","role":"owner"}],"resources":[],"createdAt":"2026-08-12T00:00:00Z","updatedAt":"2026-08-11T00:00:00Z"}

package/docs/requirements/shared-agent-context/schemas/fixtures/invalid-unsafe-uri.json

@@ -0,0 +1 @@
+{"schemaVersion":"1.0","id":"payments-work","title":"Payments work","status":"active","members":[{"subject":"team:payments","role":"owner"}],"resources":[{"kind":"component","uri":"https://outside.invalid/resource"}],"createdAt":"2026-08-11T00:00:00Z","updatedAt":"2026-08-11T00:00:00Z"}

package/docs/requirements/shared-agent-context/schemas/fixtures/invalid-workspace.json

@@ -0,0 +1 @@
+{"schemaVersion":"1.0","id":"payments-work","title":"Payments work","status":"active","members":[{"subject":"team:payments","role":"owner"}],"resources":[{"kind":"component","uri":"src/no-prefix"}],"createdAt":"2026-08-11T00:00:00Z","updatedAt":"2026-08-11T00:00:00Z"}

package/docs/requirements/shared-agent-context/schemas/fixtures/replay-idempotency-corpus.json

@@ -0,0 +1 @@
+{"x-fixturePurpose":"integration negative corpus for x-appendOnly and x-idempotencyScope; each event is individually schema-valid but the pair must be rejected by the ledger validator as a replay","events":[{"schemaVersion":"1.0","recordType":"proposal-transition","eventId":"event-accepted-1","proposalId":"proposal-1","proposalRevision":"1","correlationId":"proposal-correlation-0001","workspaceId":"payments-work","sequence":1,"priorEventHash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","fromStatus":"proposed","toStatus":"accepted","occurredAt":"2026-08-11T00:10:00Z","idempotencyKey":"accepted-transition-0001","acceptance":{"reviewDecisionRef":"./reviews/decision-1","reviewer":{"subject":"user:reviewer","authority":"owner","trustedPrincipalRef":"./identity/principal-1"},"security":{"gate":"pass","policyRef":"./policies/default","policyRevision":"1"},"freshness":{"state":"fresh","verifiedAt":"2026-08-11T00:05:00Z","maxEvidenceAgeSeconds":3600},"targetWrite":{"receiptRef":"./writes/receipt-1","targetRef":"./memory/constraint","completedAt":"2026-08-11T00:06:00Z"},"evidence":[{"kind":"memory","uri":"./memory/constraint","revision":"1","observedAt":"2026-08-11T00:00:00Z"}],"idempotencyKey":"accepted-transition-0001"}},{"schemaVersion":"1.0","recordType":"proposal-transition","eventId":"event-accepted-2","proposalId":"proposal-1","proposalRevision":"1","correlationId":"proposal-correlation-0001","workspaceId":"payments-work","sequence":2,"priorEventHash":"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb","fromStatus":"proposed","toStatus":"accepted","occurredAt":"2026-08-11T00:11:00Z","idempotencyKey":"accepted-transition-0001","acceptance":{"reviewDecisionRef":"./reviews/decision-2","reviewer":{"subject":"user:reviewer","authority":"owner","trustedPrincipalRef":"./identity/principal-1"},"security":{"gate":"pass","policyRef":"./policies/default","policyRevision":"1"},"freshness":{"state":"fresh","verifiedAt":"2026-08-11T00:05:00Z","maxEvidenceAgeSeconds":3600},"targetWrite":{"receiptRef":"./writes/receipt-2","targetRef":"./memory/constraint","completedAt":"2026-08-11T00:06:00Z"},"evidence":[{"kind":"memory","uri":"./memory/constraint","revision":"1","observedAt":"2026-08-11T00:00:00Z"}],"idempotencyKey":"accepted-transition-0001"}}]}

package/docs/requirements/shared-agent-context/schemas/fixtures/valid-accepted-transition.json

@@ -0,0 +1 @@
+{"schemaVersion":"1.0","recordType":"proposal-transition","eventId":"event-accepted-1","proposalId":"proposal-1","proposalRevision":"1","correlationId":"proposal-correlation-0001","workspaceId":"payments-work","sequence":1,"priorEventHash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","fromStatus":"proposed","toStatus":"accepted","occurredAt":"2026-08-11T00:10:00Z","idempotencyKey":"accepted-transition-0001","acceptance":{"reviewDecisionRef":"./reviews/decision-1","writeIntentRef":"./proposals/proposal-1.intent-1","reviewer":{"subject":"user:reviewer","authority":"owner","trustedPrincipalRef":"./identity/principal-1"},"security":{"gate":"pass","policyRef":"./policies/default","policyRevision":"1"},"freshness":{"state":"fresh","verifiedAt":"2026-08-11T00:05:00Z","maxEvidenceAgeSeconds":3600},"targetWrite":{"receiptRef":"./writes/receipt-1","targetRef":"./memory/constraint","completedAt":"2026-08-11T00:06:00Z","binding":{"owner":"memory","bindingHash":"a62eb99d2270853152d5bc625268f384905b8c558ad704e8e77f2d601c60f66f","intentRef":"./proposals/proposal-1.intent-1","proposalId":"proposal-1","proposalRevision":"1","workspaceId":"payments-work","correlationId":"proposal-correlation-0001","idempotencyKey":"accepted-transition-0001","reviewerSubject":"user:reviewer","reviewerAuthority":"owner","policyRevision":"1"}},"evidence":[{"kind":"memory","uri":"./memory/constraint","revision":"1","observedAt":"2026-08-11T00:00:00Z"}],"idempotencyKey":"accepted-transition-0001"}}

package/docs/requirements/shared-agent-context/schemas/fixtures/valid-access-receipt.json

@@ -0,0 +1 @@
+{"schemaVersion":"1.0","id":"access-1","workspaceId":"payments-work","actor":"agent:release-bot","action":"resource","decision":"allowed","recordedAt":"2026-08-11T00:05:00Z","cost":{"toolCalls":1,"elapsedMs":12},"contextAssembly":{"traceRef":"./context/trace-1","configurationRevision":"1","selected":["./src/payments"],"omittedOptional":[]},"policy":{"ref":"./policies/default","revision":"1"},"integrity":{"recordHash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","previousRecordHash":"GENESIS"},"resourceRef":"./src/payments"}

package/docs/requirements/shared-agent-context/schemas/fixtures/valid-fwk-receipt.json

@@ -0,0 +1 @@
+{"schemaVersion":"1.0","workspaceId":"payments-work","generatedAt":"2026-08-11T00:00:00Z","facts":[{"statement":"Flow is ready","evidence":[{"kind":"flow","uri":"./.metaproject/flows/001","revision":"1","observedAt":"2026-08-11T00:00:00Z","trust":"primary"}],"observedAt":"2026-08-11T00:00:00Z","expiresAt":"2026-08-12T00:00:00Z","freshness":"fresh"}],"work":{"state":"unbound"},"knowHow":[{"kind":"memory","uri":"./.metaproject/memory/constraint","revision":"2","trust":"accepted","status":"fresh"}],"freshness":"fresh"}

package/docs/requirements/shared-agent-context/schemas/fixtures/valid-proposal.json

@@ -0,0 +1 @@
+{"schemaVersion":"1.0","recordType":"proposal-created","id":"proposal-1","proposalRevision":"1","correlationId":"proposal-correlation-0001","workspaceId":"payments-work","kind":"memory-entry","status":"proposed","summary":"Redacted reusable constraint","evidence":[{"kind":"memory","uri":"./memory/constraint","revision":"1","observedAt":"2026-08-11T00:00:00Z"}],"wrapUp":{"id":"wrapup-1","source":"flow","sourceRef":"./flows/payments-wrapup","sourceRevision":"1","issuedAt":"2026-08-11T00:00:00Z","expiresAt":"2026-08-11T01:00:00Z"},"author":"agent:writer","security":{"gate":"pass","redacted":true,"policyRef":"./policies/default","policyRevision":"1"},"createdAt":"2026-08-11T00:00:00Z"}

package/docs/requirements/shared-agent-context/schemas/fixtures/valid-review-decision.json

@@ -0,0 +1 @@
+{"schemaVersion":"1.0","id":"decision-1","proposalId":"proposal-1","proposalRevision":"1","correlationId":"proposal-correlation-0001","workspaceId":"payments-work","decision":"accepted","reviewer":{"subject":"user:reviewer","authority":"owner","trustedPrincipalRef":"./identity/principal-1"},"decidedAt":"2026-08-11T00:05:00Z","idempotencyKey":"review-decision-0001","security":{"gate":"pass","policyRef":"./policies/default","policyRevision":"1"},"freshness":{"state":"fresh","verifiedAt":"2026-08-11T00:05:00Z","evidenceRevision":"1"},"targetWrite":{"receiptRef":"./writes/receipt-1","targetRef":"./memory/constraint","completedAt":"2026-08-11T00:06:00Z"}}

package/docs/requirements/shared-agent-context/schemas/fixtures/valid-workspace.json

@@ -0,0 +1 @@
+{"schemaVersion":"1.0","id":"payments-work","title":"Payments work","status":"active","members":[{"subject":"team:payments","role":"owner"},{"subject":"agent:release-bot","role":"editor"}],"resources":[{"kind":"component","uri":"./src/payments","revision":"abc123"}],"createdAt":"2026-08-11T00:00:00Z","updatedAt":"2026-08-11T00:00:00Z"}

package/docs/requirements/shared-agent-context/schemas/fwk-receipt.schema.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "keryx/shared-agent-context/fwk-receipt/v1",
+  "$vocabulary": {"https://json-schema.org/draft/2020-12/vocab/format-assertion": true},
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "workspaceId", "generatedAt", "facts", "work", "knowHow", "freshness"],
+  "properties": {
+    "schemaVersion": {"const": "1.0"},
+    "workspaceId": {"type": "string", "pattern": "^[a-z][a-z0-9-]{2,63}$"},
+    "generatedAt": {"$ref": "#/$defs/utcTimestamp"},
+    "facts": {"type": "array", "items": {"$ref": "#/$defs/fact"}},
+    "work": {"$ref": "#/$defs/work"},
+    "knowHow": {"type": "array", "items": {"$ref": "#/$defs/knowHow"}},
+    "freshness": {"enum": ["fresh", "stale", "partial", "denied"]}
+  },
+  "x-temporalOrder": [{"earlier": "facts[].observedAt", "laterOrEqual": "facts[].expiresAt"}, {"earlier": "facts[].observedAt", "laterOrEqual": "generatedAt"}],
+  "$defs": {
+    "utcTimestamp": {"type": "string", "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(?:\\.[0-9]+)?Z$", "x-formatAssertionRequired": true},
+    "immutableRevision": {"type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,255}$", "x-immutable": true},
+    "workspacePath": {"type": "string", "pattern": "^\\./(?!.*(?:^|/)\\.\\.(?:/|$))(?:[A-Za-z0-9._-]+/)*[A-Za-z0-9._-]+$", "x-rootContainment": "workspace root realpath"},
+    "evidence": {"type": "object", "additionalProperties": false, "required": ["kind", "uri", "revision", "observedAt", "trust"], "properties": {"kind": {"enum": ["code", "flow", "wiki", "memory", "test", "health", "artifact"]}, "uri": {"$ref": "#/$defs/workspacePath"}, "revision": {"$ref": "#/$defs/immutableRevision"}, "observedAt": {"$ref": "#/$defs/utcTimestamp"}, "trust": {"enum": ["primary", "accepted", "reviewed"]}}},
+    "fact": {"type": "object", "additionalProperties": false, "required": ["statement", "evidence", "observedAt", "expiresAt", "freshness"], "properties": {"statement": {"type": "string", "minLength": 1, "maxLength": 4000}, "evidence": {"type": "array", "minItems": 1, "items": {"$ref": "#/$defs/evidence"}}, "observedAt": {"$ref": "#/$defs/utcTimestamp"}, "expiresAt": {"$ref": "#/$defs/utcTimestamp"}, "freshness": {"enum": ["fresh", "stale", "expired", "denied"]}, "confidence": {"type": "number", "minimum": 0, "maximum": 1}}},
+    "flowRef": {"type": "object", "additionalProperties": false, "required": ["uri", "snapshot", "revision"], "properties": {"uri": {"$ref": "#/$defs/workspacePath"}, "snapshot": {"type": "string", "minLength": 1, "maxLength": 256}, "revision": {"$ref": "#/$defs/immutableRevision"}}},
+    "work": {"oneOf": [{"type": "object", "additionalProperties": false, "required": ["state", "flowRef"], "properties": {"state": {"const": "bound"}, "flowRef": {"$ref": "#/$defs/flowRef"}, "completed": {"type": "array", "items": {"type": "string"}}, "next": {"type": "array", "items": {"type": "string"}}, "blocked": {"type": "array", "items": {"type": "string"}}, "evidence": {"type": "array", "items": {"$ref": "#/$defs/evidence"}}}}, {"type": "object", "additionalProperties": false, "required": ["state"], "properties": {"state": {"const": "unbound"}}, "x-forbids": ["flowRef", "completed", "next", "blocked", "evidence"]}]},
+    "knowHow": {"type": "object", "additionalProperties": false, "required": ["kind", "uri", "revision", "trust", "status"], "properties": {"kind": {"enum": ["wiki", "memory", "skill"]}, "uri": {"$ref": "#/$defs/workspacePath"}, "revision": {"$ref": "#/$defs/immutableRevision"}, "trust": {"enum": ["accepted", "reviewed"]}, "status": {"enum": ["fresh", "stale", "withdrawn", "denied"]}, "applicability": {"type": "string", "maxLength": 1000}}}
+  }
+}

package/docs/requirements/shared-agent-context/schemas/review-decision.schema.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "keryx/shared-agent-context/review-decision/v1",
+  "$vocabulary": {"https://json-schema.org/draft/2020-12/vocab/format-assertion": true},
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "id", "proposalId", "proposalRevision", "correlationId", "workspaceId", "decision", "reviewer", "decidedAt", "idempotencyKey"],
+  "properties": {
+    "schemaVersion": {"const": "1.0"}, "id": {"$ref": "#/$defs/id"}, "proposalId": {"$ref": "#/$defs/id"}, "proposalRevision": {"$ref": "#/$defs/revision"}, "correlationId": {"$ref": "#/$defs/correlationId"}, "workspaceId": {"$ref": "#/$defs/id"}, "decision": {"enum": ["accepted", "rejected", "dismissed"]}, "reviewer": {"$ref": "#/$defs/actorContext"}, "decidedAt": {"$ref": "#/$defs/utcTimestamp"}, "idempotencyKey": {"$ref": "#/$defs/idempotencyKey"}, "security": {"$ref": "#/$defs/security"}, "freshness": {"$ref": "#/$defs/freshness"}, "targetWrite": {"$ref": "#/$defs/targetWrite"}, "reason": {"type": "string", "minLength": 1, "maxLength": 2000}
+  },
+  "allOf": [{"if": {"properties": {"decision": {"const": "accepted"}}, "required": ["decision"]}, "then": {"required": ["security", "freshness", "targetWrite"]}, "else": {"required": ["reason"], "not": {"anyOf": [{"required": ["targetWrite"]}, {"required": ["freshness"]}]}}}],
+  "x-appendOnly": {"stream": "proposalId", "idempotencyScope": "workspaceId+proposalId", "authoritativeTransition": true},
+  "$defs": {
+    "id": {"type": "string", "pattern": "^[a-z][a-z0-9-]{2,63}$"}, "revision": {"type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,255}$", "x-immutable": true}, "correlationId": {"type": "string", "minLength": 16, "maxLength": 256, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{15,255}$", "x-immutable": true}, "utcTimestamp": {"type": "string", "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(?:\\.[0-9]+)?Z$", "x-formatAssertionRequired": true}, "workspacePath": {"type": "string", "pattern": "^\\./(?!.*(?:^|/)\\.\\.(?:/|$))(?:[A-Za-z0-9._-]+/)*[A-Za-z0-9._-]+$", "x-rootContainment": "workspace root realpath"}, "idempotencyKey": {"type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{15,255}$"},
+    "actorContext": {"type": "object", "additionalProperties": false, "required": ["subject", "authority", "trustedPrincipalRef"], "properties": {"subject": {"type": "string", "pattern": "^(?:user|team|service|agent):[a-z0-9][a-z0-9._-]{0,127}$"}, "authority": {"enum": ["owner", "editor"]}, "trustedPrincipalRef": {"$ref": "#/$defs/workspacePath"}}},
+    "security": {"type": "object", "additionalProperties": false, "required": ["gate", "policyRef", "policyRevision"], "properties": {"gate": {"const": "pass"}, "policyRef": {"$ref": "#/$defs/workspacePath"}, "policyRevision": {"$ref": "#/$defs/revision"}}}, "freshness": {"type": "object", "additionalProperties": false, "required": ["state", "verifiedAt", "evidenceRevision"], "properties": {"state": {"const": "fresh"}, "verifiedAt": {"$ref": "#/$defs/utcTimestamp"}, "evidenceRevision": {"$ref": "#/$defs/revision"}}}, "targetWrite": {"type": "object", "additionalProperties": false, "required": ["receiptRef", "targetRef", "completedAt"], "properties": {"receiptRef": {"$ref": "#/$defs/workspacePath"}, "targetRef": {"$ref": "#/$defs/workspacePath"}, "completedAt": {"$ref": "#/$defs/utcTimestamp"}}}
+  }
+}

package/docs/requirements/shared-agent-context/schemas/workspace-manifest.schema.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "keryx/shared-agent-context/workspace-manifest/v1",
+  "$vocabulary": {"https://json-schema.org/draft/2020-12/vocab/format-assertion": true},
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "id", "title", "status", "members", "resources", "createdAt", "updatedAt"],
+  "properties": {
+    "schemaVersion": {"const": "1.0"},
+    "id": {"type": "string", "pattern": "^[a-z][a-z0-9-]{2,63}$"},
+    "title": {"type": "string", "minLength": 1, "maxLength": 160},
+    "status": {"enum": ["active", "archived"]},
+    "members": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": {"$ref": "#/$defs/member"},
+      "contains": {"properties": {"role": {"const": "owner"}}, "required": ["role"]},
+      "minContains": 1,
+      "maxContains": 1,
+      "x-uniqueBy": "subject",
+      "x-roleTopology": "exactly-one-owner; each canonical subject has one role"
+    },
+    "resources": {"type": "array", "items": {"$ref": "#/$defs/resourceRef"}, "x-uniqueBy": "uri"},
+    "createdAt": {"$ref": "#/$defs/utcTimestamp"},
+    "updatedAt": {"$ref": "#/$defs/utcTimestamp"}
+  },
+  "x-temporalOrder": [{"earlier": "createdAt", "laterOrEqual": "updatedAt"}],
+  "x-rootContainment": {"fields": ["resources[].uri"], "root": "workspace root", "resolveSymlinks": true, "rejectEscapes": true},
+  "$defs": {
+    "utcTimestamp": {"type": "string", "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(?:\\.[0-9]+)?Z$", "x-formatAssertionRequired": true},
+    "subjectId": {"type": "string", "pattern": "^(?:user|team|service|agent):[a-z0-9][a-z0-9._-]{0,127}$"},
+    "member": {"type": "object", "additionalProperties": false, "required": ["subject", "role"], "properties": {"subject": {"$ref": "#/$defs/subjectId"}, "role": {"enum": ["owner", "editor", "viewer"]}}},
+    "workspacePath": {"type": "string", "pattern": "^\\./(?!.*(?:^|/)\\.\\.(?:/|$))(?:[A-Za-z0-9._-]+/)*[A-Za-z0-9._-]+$", "x-canonicalize": "realpath within workspace root"},
+    "resourceRef": {"type": "object", "additionalProperties": false, "required": ["kind", "uri"], "properties": {"kind": {"enum": ["component", "repository", "flow", "wiki", "memory", "skill", "evidence", "worktree", "session"]}, "uri": {"$ref": "#/$defs/workspacePath"}, "revision": {"type": "string", "minLength": 1, "maxLength": 256}}}
+  }
+}

package/docs/requirements/shared-agent-context/schemas/workspace-proposal.schema.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "keryx/shared-agent-context/workspace-proposal/v1",
+  "$vocabulary": {"https://json-schema.org/draft/2020-12/vocab/format-assertion": true},
+  "oneOf": [{"$ref":"#/$defs/creation"},{"$ref":"#/$defs/writeIntent"},{"$ref":"#/$defs/transition"}],
+  "$defs": {
+    "id":{"type":"string","pattern":"^[a-z][a-z0-9-]{2,63}$"},
+    "utc":{"type":"string","format":"date-time","pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(?:\\.[0-9]+)?Z$","x-formatAssertionRequired":true},
+    "revision":{"type":"string","minLength":1,"maxLength":256,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,255}$","x-immutable":true},
+    "correlationId":{"type":"string","minLength":16,"maxLength":256,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{15,255}$","x-immutable":true},
+    "key":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{15,255}$"},
+    "path":{"type":"string","pattern":"^\\./(?!.*(?:^|/)\\.\\.(?:/|$))(?:[A-Za-z0-9._-]+/)*[A-Za-z0-9._-]+$","x-rootContainment":"workspace root realpath"},
+    "evidence":{"type":"object","additionalProperties":false,"required":["kind","uri","revision","observedAt"],"properties":{"kind":{"type":"string","minLength":1,"maxLength":64},"uri":{"$ref":"#/$defs/path"},"revision":{"$ref":"#/$defs/revision"},"observedAt":{"$ref":"#/$defs/utc"}}},
+    "actor":{"type":"object","additionalProperties":false,"required":["subject","authority","trustedPrincipalRef"],"properties":{"subject":{"type":"string","pattern":"^(?:user|team|service|agent):[a-z0-9][a-z0-9._-]{0,127}$"},"authority":{"enum":["owner","editor"]},"trustedPrincipalRef":{"$ref":"#/$defs/path"}}},
+    "security":{"type":"object","additionalProperties":false,"required":["gate","policyRef","policyRevision"],"properties":{"gate":{"const":"pass"},"policyRef":{"$ref":"#/$defs/path"},"policyRevision":{"$ref":"#/$defs/revision"}}},
+    "creation":{"type":"object","additionalProperties":false,"required":["schemaVersion","recordType","id","proposalRevision","correlationId","workspaceId","kind","status","summary","evidence","wrapUp","author","security","createdAt"],"properties":{"schemaVersion":{"const":"1.0"},"recordType":{"const":"proposal-created"},"id":{"$ref":"#/$defs/id"},"proposalRevision":{"$ref":"#/$defs/revision"},"correlationId":{"$ref":"#/$defs/correlationId"},"workspaceId":{"$ref":"#/$defs/id"},"kind":{"enum":["decision","wiki-update","memory-entry","follow-up","contract-change","risk"]},"status":{"const":"proposed"},"summary":{"type":"string","minLength":1,"maxLength":8000},"evidence":{"type":"array","minItems":1,"items":{"$ref":"#/$defs/evidence"}},"wrapUp":{"type":"object","additionalProperties":false,"required":["id","source","sourceRef","sourceRevision","issuedAt","expiresAt"],"properties":{"id":{"$ref":"#/$defs/id"},"source":{"enum":["session","flow"]},"sourceRef":{"$ref":"#/$defs/path"},"sourceRevision":{"$ref":"#/$defs/revision"},"issuedAt":{"$ref":"#/$defs/utc"},"expiresAt":{"$ref":"#/$defs/utc"}}},"author":{"type":"string","pattern":"^(?:user|team|service|agent):[a-z0-9][a-z0-9._-]{0,127}$"},"security":{"type":"object","additionalProperties":false,"required":["gate","redacted","policyRef","policyRevision"],"properties":{"gate":{"enum":["pass","needs-approval"]},"redacted":{"const":true},"policyRef":{"$ref":"#/$defs/path"},"policyRevision":{"$ref":"#/$defs/revision"}}},"createdAt":{"$ref":"#/$defs/utc"}},"x-immutableRecord":true},
+    "writeIntent":{"type":"object","additionalProperties":false,"required":["schemaVersion","recordType","intentId","proposalId","proposalRevision","correlationId","workspaceId","sequence","priorEventHash","idempotencyKey","reviewer","approvalRef","security","evidence","createdAt"],"properties":{"schemaVersion":{"const":"1.0"},"recordType":{"const":"proposal-write-intent"},"intentId":{"$ref":"#/$defs/id"},"proposalId":{"$ref":"#/$defs/id"},"proposalRevision":{"$ref":"#/$defs/revision"},"correlationId":{"$ref":"#/$defs/correlationId"},"workspaceId":{"$ref":"#/$defs/id"},"sequence":{"type":"integer","minimum":1},"priorEventHash":{"type":"string","pattern":"^[a-f0-9]{64}$"},"idempotencyKey":{"$ref":"#/$defs/key"},"reviewer":{"$ref":"#/$defs/actor"},"approvalRef":{"$ref":"#/$defs/path"},"security":{"$ref":"#/$defs/security"},"evidence":{"type":"array","minItems":1,"items":{"$ref":"#/$defs/evidence"}},"createdAt":{"$ref":"#/$defs/utc"}},"x-appendOnly":{"stream":"proposalId","strictSequence":true,"recovery":"owner-idempotency-key"}},
+    "transition":{"type":"object","additionalProperties":false,"required":["schemaVersion","recordType","eventId","proposalId","proposalRevision","correlationId","workspaceId","sequence","priorEventHash","fromStatus","toStatus","occurredAt","idempotencyKey"],"properties":{"schemaVersion":{"const":"1.0"},"recordType":{"const":"proposal-transition"},"eventId":{"$ref":"#/$defs/id"},"proposalId":{"$ref":"#/$defs/id"},"proposalRevision":{"$ref":"#/$defs/revision"},"correlationId":{"$ref":"#/$defs/correlationId"},"workspaceId":{"$ref":"#/$defs/id"},"sequence":{"type":"integer","minimum":1},"priorEventHash":{"type":"string","pattern":"^[a-f0-9]{64}$"},"fromStatus":{"const":"proposed"},"toStatus":{"enum":["accepted","rejected","dismissed","stale"]},"occurredAt":{"$ref":"#/$defs/utc"},"idempotencyKey":{"$ref":"#/$defs/key"},"acceptance":{"$ref":"#/$defs/acceptance"},"reason":{"type":"string","minLength":1,"maxLength":2000}},"allOf":[{"if":{"properties":{"toStatus":{"const":"accepted"}},"required":["toStatus"]},"then":{"required":["acceptance"]},"else":{"required":["reason"],"not":{"required":["acceptance"]}}}]},
+    "receiptBinding":{"type":"object","additionalProperties":false,"required":["owner","bindingHash","intentRef","proposalId","proposalRevision","workspaceId","correlationId","idempotencyKey","reviewerSubject","reviewerAuthority","policyRevision"],"properties":{"owner":{"enum":["wiki","memory","skill"]},"bindingHash":{"type":"string","pattern":"^[a-f0-9]{64}$"},"intentRef":{"$ref":"#/$defs/path"},"proposalId":{"$ref":"#/$defs/id"},"proposalRevision":{"$ref":"#/$defs/revision"},"workspaceId":{"$ref":"#/$defs/id"},"correlationId":{"$ref":"#/$defs/correlationId"},"idempotencyKey":{"$ref":"#/$defs/key"},"reviewerSubject":{"type":"string","pattern":"^(?:user|team|service|agent):[a-z0-9][a-z0-9._-]{0,127}$"},"reviewerAuthority":{"enum":["owner","editor"]},"policyRevision":{"$ref":"#/$defs/revision"}}},
+    "acceptance":{"type":"object","additionalProperties":false,"required":["reviewDecisionRef","writeIntentRef","reviewer","security","freshness","targetWrite","evidence","idempotencyKey"],"properties":{"reviewDecisionRef":{"$ref":"#/$defs/path"},"writeIntentRef":{"$ref":"#/$defs/path"},"reviewer":{"$ref":"#/$defs/actor"},"security":{"$ref":"#/$defs/security"},"freshness":{"type":"object","additionalProperties":false,"required":["state","verifiedAt","maxEvidenceAgeSeconds"],"properties":{"state":{"const":"fresh"},"verifiedAt":{"$ref":"#/$defs/utc"},"maxEvidenceAgeSeconds":{"type":"integer","minimum":1,"maximum":86400}}},"targetWrite":{"type":"object","additionalProperties":false,"required":["receiptRef","targetRef","completedAt","binding"],"properties":{"receiptRef":{"$ref":"#/$defs/path"},"targetRef":{"$ref":"#/$defs/path"},"completedAt":{"$ref":"#/$defs/utc"},"binding":{"$ref":"#/$defs/receiptBinding"}}},"evidence":{"type":"array","minItems":1,"items":{"$ref":"#/$defs/evidence"}},"idempotencyKey":{"$ref":"#/$defs/key"}},"x-temporalOrder":[{"earlier":"evidence[].observedAt","laterOrEqual":"freshness.verifiedAt"},{"earlier":"freshness.verifiedAt","laterOrEqual":"targetWrite.completedAt"}]}
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrciphersmith/keryx",
-  "version": "0.2.34",
+  "version": "0.2.36",
   "description": "Version-controlled project context for AI coding agents: code graph, architecture wiki, project memory, relevant tests, quality signals, and task flows.",
   "private": false,
   "publishConfig": {
@@ -45,6 +45,7 @@
   },
   "files": [
     "dist",
+    "docs/requirements/shared-agent-context/schemas",
     "src/gdgraph",
     "src/gdskills/bundled",
     "src/gdskills/contracts",
@@ -60,10 +61,15 @@
   },
   "devDependencies": {
     "@types/bun": "latest",
+    "@xenova/transformers": "^2.17.2",
     "bun-types": "latest",
     "typescript": "^5"
   },
   "engines": {
     "bun": ">=1.1.0"
-  }
+  },
+  "trustedDependencies": [
+    "protobufjs",
+    "sharp"
+  ]
 }