From 8be7685a52f05eb012fbdc1f139384b692f671e0 Mon Sep 17 00:00:00 2001 From: Yehonal Date: Sun, 12 Jul 2026 10:51:46 +0000 Subject: [PATCH] Add authenticated memory curator --- CHANGELOG.md | 50 + README.md | 6 +- docs/amf-curator.md | 158 ++ docs/amf-memory-v1.md | 20 +- docs/mcp-server.md | 33 +- memory/pam.version.json | 15 +- ....3-to-0.6.0-agent-memory-fabric-records.md | 7 + migrations/0.6.0-to-0.6.1-amf-confidence.md | 32 + .../0.6.1-to-0.6.2-receipt-applicator.md | 28 + package.json | 3 +- tools/check-benchmark-thresholds.mjs | 8 +- tools/lib/amf-memory-record.mjs | 36 +- tools/lib/mcp-tools.mjs | 121 + tools/lib/memory-apply-proposal.mjs | 39 +- tools/lib/memory-curator.mjs | 2197 +++++++++++++++++ tools/lib/memory-receipt-applicator.mjs | 357 +++ tools/memory-curator.mjs | 79 + tools/memory-maintenance.config.json | 36 + tools/test-amf-memory-record.mjs | 68 + tools/test-memory-apply-proposal.mjs | 51 +- tools/test-memory-curator.mjs | 1144 +++++++++ tools/test-pam-mcp-server.mjs | 112 +- 22 files changed, 4574 insertions(+), 26 deletions(-) create mode 100644 docs/amf-curator.md create mode 100644 migrations/0.6.0-to-0.6.1-amf-confidence.md create mode 100644 migrations/0.6.1-to-0.6.2-receipt-applicator.md create mode 100644 tools/lib/memory-curator.mjs create mode 100644 tools/lib/memory-receipt-applicator.mjs create mode 100644 tools/memory-curator.mjs create mode 100644 tools/test-memory-curator.mjs diff --git a/CHANGELOG.md b/CHANGELOG.md index 541e0b0..4f7d28d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,56 @@ ## Unreleased +### Added + +- PAM 0.6.2 decision receipts and a separately authorized deterministic + applicator with durable apply-receipt outbox and crash recovery. + +- Mandatory exact `amf-memory/v1` confidence metadata with finite score, + evidence basis, UTC assessment time, AAD binding, and revision-safe changes. + +- Deterministic AMF candidate queue, versioned reviews, deduplication, policy + decisions, and `approved_pending_apply` receipts. +- Strict, HMAC-chained append-only curator decision ledger with an authenticated + sequence/length/head anchor and redacted fail-closed status output. +- `memory_curator_submit`, `memory_curator_review`, + `memory_curator_status`, and `memory_curator_git_plan` MCP tools plus the + `memory:curator` CLI. +- Fail-closed Git writer plan abstraction, disabled and dry-run-only by default; + it refuses protected branches and direct push. + +### Safety + +- Applicator proposal digests are now enforced inside `applyProposal` after the + per-target lock and before archive reservation or target persistence, closing + the post-`prepared` proposal-swap TOCTOU window. + +- The curator accepts complete `amf-memory/v1` records only, never RAW + transcripts or arbitrary source payloads, and has no direct canonical write + path. +- Automatic approval is disabled by default. Explicitly enabled eligible + candidates still require the separate `memory:apply-receipt` applicator. +- Candidate/review artifacts require an external ledger key; manual review and + apply require a separately allowlisted server-side capability. Recovery + verifies the exact applied archive and canonical target before success. +- The head anchor lives outside the curator queue tree and is never recreated + for a non-empty ledger. Dedup/status fail on any unverified artifact and + reconcile promotion events with applied-archive history. Ledger record, + source, and target references are HMAC-only. +- The anchor and initialized marker now live in a pre-provisioned external + `0700` state root outside the workspace, paired with a workspace sentinel. + Deterministic crash recovery covers candidate-fsync and ledger-before-anchor + boundaries; strict-prefix anchor advancement requires an allowlisted admin + capability through CLI/MCP. +- Review-fsync and apply-before-ledger boundaries now recover only from one + exact MAC-authenticated candidate-version decision or applied archive. Exact + retries converge; explicit admin recovery remains capability-gated and + refuses forged, unrelated, or ambiguous external-ahead state. +- Automatic-policy retries additionally bind the normalized policy snapshot, + deterministic actor/action/idempotency, and exact original submission. Both + queued-review and auto-promote crash boundaries converge without weakening + the manual-review contract. + ## 0.6.0 - 2026-07-11 PAM 0.6.0 adds the optional `amf-memory/v1` Markdown record contract for diff --git a/README.md b/README.md index bac457a..cfa837d 100644 --- a/README.md +++ b/README.md @@ -43,7 +43,11 @@ The important pieces are: directly without Node, npm, a database, or embeddings. - [docs/amf-memory-v1.md](docs/amf-memory-v1.md): optional source-traceable, scope-aware Markdown record contract with sealed private bodies and safe - graph projections. + graph projections; PAM 0.6.1 requires structured confidence and binds it + into sealed-record AAD. +- [docs/amf-curator.md](docs/amf-curator.md): deterministic candidate queue, + versioned decision receipts, separately authorized receipt application, and fail-closed + dry-run Git writer plan. - [memory/agent-memory/pam.md](memory/agent-memory/pam.md): the Portable Agent Memory constitution. This is the setup/protocol reference agents should follow when changing or auditing PAM itself. diff --git a/docs/amf-curator.md b/docs/amf-curator.md new file mode 100644 index 0000000..9fb5c28 --- /dev/null +++ b/docs/amf-curator.md @@ -0,0 +1,158 @@ +# AMF curator and receipt applicator + +PAM 0.6.2 separates memory judgment from canonical mutation. Both components +accept complete `amf-memory/v1` records only; neither accepts RAW transcripts, +message bodies, decryption keys, or arbitrary source payloads. + +## Authority boundary + +The curator has only `memory:curate`. It validates, deduplicates, records a +versioned review, and emits an authenticated decision receipt with exactly one +outcome: + +- `review_required`; +- `rejected`; +- `approved_pending_apply`. + +The curator never calls PAM proposal/apply, never reports `promoted`, and never +writes `memory/amf/records/`. `autoPromote` is retained as the compatibility +name for policy-based automatic approval, but it only emits +`approved_pending_apply`. Confidence selects a policy route; it grants no +capability and cannot expand scope or visibility. + +The applicator has a distinct `memory:apply-receipt` credential. It accepts only +the latest authenticated `approved_pending_apply` receipt, verifies its +candidate, revision, decision digest, policy digest, and lifecycle-at-decision, +then uses the existing `memory_propose_record`/`memory_propose_edit` and +`memory_apply_proposal` implementation. Auto-approval cannot bypass it. + +## Durable artifacts + +Curator artifacts are HMAC-authenticated and mode `0600`: + +```text +memory/amf/curator/ +├── queue/.json +├── reviews/.json +├── decision-receipts/.json +└── decisions.jsonl +memory/amf/curator.initialized.json +``` + +The append-only decision ledger is typed, sequence-numbered, HMAC-chained, and +anchored in a pre-provisioned external `0700` state directory. IDs are derived +from stable idempotency keys. An exact retry returns the existing artifact; +altered content, decision, policy, or authenticated artifact fails closed. + +Applicator state and its transport outbox are independently authenticated: + +```text +memory/amf/applicator/ +├── state/.json +└── outbox/.json +``` + +The recoverable state machine is: + +```text +prepared -> pam_applied -> receipt_queued -> fabric_acked +``` + +The apply receipt is discriminated as `memory_apply_receipt` and binds +`proposalId`, `decisionId`, `decisionDigest`, `policyDigestAtApply`, +`canonicalRecordId`, `revision`, `canonicalLifecycleAtDecision`, and SHA-256 +digests of the proposal, applied archive, and canonical target. PAM verifies the +archive and target before queuing the receipt. + +The `prepared` state stores the canonical proposal digest. `applyProposal` +re-reads the proposal after acquiring both its proposal lock and the canonical +target lock, then compares that digest before reservation or persistence. A +valid proposal altered after `prepared`, or swapped while the target lock is +being acquired, fails closed without changing the target or archive. + +Crashes after every state boundary converge under the exact idempotency key. +A crash after PAM apply is recovered through PAM's applied archive; a crash +after Fabric ACK relies on the sink treating `applyId` as its idempotency key. +Outbox or state alteration fails authentication. + +## Transport + +The default transport is disabled, leaving a durable `receipt_queued` outbox. +Tests may inject a synchronous idempotent sink. HTTP configuration requires an +HTTPS endpoint from the configured environment variable, but this release does +not perform live HTTP: dispatch fails closed and leaves the receipt queued until +an audited Fabric transport is integrated. + +## Configuration + +```json +{ + "amfCurator": { + "version": "amf-curator-policy/v1", + "autoPromote": false, + "ledgerKeyEnv": "PAM_CURATOR_LEDGER_KEY", + "stateDirEnv": "PAM_CURATOR_STATE_DIR", + "reviewerTokenEnv": "PAM_CURATOR_REVIEWER_TOKEN", + "reviewers": [{ + "tokenSha256": "", + "actorId": "service:memory-curator", + "capabilities": ["memory:curate"] + }], + "gitWriter": { "enabled": false, "dryRunOnly": true } + }, + "amfApplicator": { + "version": "amf-receipt-applicator/v1", + "tokenEnv": "PAM_APPLICATOR_TOKEN", + "applicators": [{ + "tokenSha256": "", + "actorId": "service:memory-applicator", + "capabilities": ["memory:apply-receipt"] + }], + "transport": { + "kind": "disabled", + "endpointEnv": "PAM_FABRIC_RECEIPT_ENDPOINT" + } + } +} +``` + +The Git writer remains disabled and dry-run-only. It cannot push, write a +protected branch, merge, or deploy. + +## CLI and MCP + +```bash +npm run memory:curator -- submit --input candidate.json +npm run memory:curator -- review --input review.json +npm run memory:curator -- apply --input application.json +npm run memory:curator -- status +npm run memory:curator -- recover --input recovery.json +npm run memory:curator -- git-plan --input git-plan.json +``` + +MCP adds `memory_receipt_apply` alongside `memory_curator_submit`, +`memory_curator_review`, `memory_curator_status`, `memory_curator_recover`, and +`memory_curator_git_plan`. Curator recovery supports only `advance-anchor` and +`recover-review`; apply recovery is the applicator's exact retry path. + +## Recovery checks + +1. Stop on an invalid candidate/review/receipt MAC, ledger chain, anchor, state, + or outbox. +2. Retry candidate or review writes with the exact original input. +3. Use `advance-anchor` only for a verified strict-prefix anchor. +4. Retry application with the exact `decisionId` and idempotency key. PAM's + proposal/archive checks determine whether to apply or recover. +5. Never delete ledgers, sentinels, state, or outbox files to clear an error. +6. Treat commit, push, PR, deploy, restart, and live transport as separate + approval gates. + +Validation: + +```bash +node --test tools/test-memory-curator.mjs +npm test +npm run migrations:check +npm run mcp:smoke +git diff --check +``` diff --git a/docs/amf-memory-v1.md b/docs/amf-memory-v1.md index 19be564..b88c414 100644 --- a/docs/amf-memory-v1.md +++ b/docs/amf-memory-v1.md @@ -1,6 +1,6 @@ # AMF memory record v1 -PAM 0.6.0 implements the public `amf-memory/v1` file-first contract used by +PAM 0.6.1 implements the public `amf-memory/v1` file-first contract used by Agent Memory Fabric. It is additive: existing PAM logs and graph-v1 workspaces continue to work unchanged. @@ -26,6 +26,7 @@ revision: 1 claimType: decision scope: {"type":"shared","id":"shared:global"} visibility: shared +confidence: {"score":0.99,"basis":"reviewed","assessedAt":"2026-07-11T10:00:00Z"} subjects: [{"identityId":"agent:22222222-2222-4222-8222-222222222222","role":"owner"}] claim: {"encoding":"plain","text":"A portable source-backed decision."} lifecycle: {"status":"active","validFrom":"2026-07-11T10:00:00Z","validTo":null,"supersedes":[],"revokedAt":null,"revocationReason":null} @@ -40,6 +41,13 @@ Unknown fields and unknown major schemas fail validation. Timestamps are strict RFC 3339 UTC (`Z`), not local offsets. Provenance is non-empty and contains pointers and hashes, never embedded RAW. +`confidence` is mandatory and contains exactly `score`, `basis`, and +`assessedAt`. `score` is a finite number from `0` through `1`; `basis` is one +of `observed`, `asserted`, `inferred`, or `reviewed`; `assessedAt` is RFC 3339 +UTC and falls between `createdAt` and `updatedAt`. Unknown or missing fields +fail closed. A revision may reassess confidence, but any change requires a +strictly newer `assessedAt`, which may never move backwards. + ## Sealed claims A claim must be sealed when any of these is true: @@ -73,7 +81,7 @@ UTF-8. In addition to record routing fields, it binds the envelope algorithm and external key identifiers: ```json -{"schema":"...","id":"...","revision":1,"claimType":"...","scope":{},"visibility":"...","subjects":[],"envelope":{"alg":"AES-256-GCM","kekId":"kek:...","keyRef":"key:..."}} +{"schema":"...","id":"...","revision":1,"claimType":"...","scope":{},"visibility":"...","confidence":{"score":0.99,"basis":"reviewed","assessedAt":"2026-07-11T10:00:00Z"},"subjects":[],"envelope":{"alg":"AES-256-GCM","kekId":"kek:...","keyRef":"key:..."}} ``` PAM recomputes its SHA-256 and requires an exact `aadSha256` match. An IV of any @@ -95,6 +103,7 @@ recording and applying the proposal: - ID, creation time, claim type, scope, and subjects are immutable; plaintext claims are byte-for-byte immutable; - visibility can narrow but cannot widen; +- confidence reassessment requires a strictly newer assessment timestamp; - provenance and `lifecycle.supersedes` are append-only; - only `active` may transition to a terminal lifecycle state; - `updatedAt` strictly increases. @@ -151,6 +160,13 @@ artifacts, applied archives, and apply results expose `graphProjectionStale`, `regenerateAfterApply`, and a required `npm run memory:graph:index` follow-up. An apply coordinator must not discard that follow-up when marking its task done. +## Optional curator + +The deterministic AMF curator adds an idempotent queue, policy/review decisions, +deduplication, and proposal/apply orchestration without changing this record +contract. It is disabled for automatic promotion by default and never accepts +RAW transcripts. See [AMF deterministic curator](amf-curator.md). + ## Validation ```bash diff --git a/docs/mcp-server.md b/docs/mcp-server.md index 67a9c25..1296abc 100644 --- a/docs/mcp-server.md +++ b/docs/mcp-server.md @@ -7,7 +7,7 @@ markdown + JSONL contract is unchanged; the server is purely additive runtime. ## What you get The server runs locally over stdio (no network, no daemon, no port) and exposes -17 tools under the `pam` namespace: +22 tools under the `pam` namespace: - `pam_version`, `memory_state`, `maintenance_config`: context tools - `memory_list`, `memory_read`, `memory_search`: safe filesystem reads under `memory/` @@ -20,6 +20,18 @@ The server runs locally over stdio (no network, no daemon, no port) and exposes - `memory_apply_proposal`: applies a recorded proposal through an exclusive `applying` reservation, atomic target persistence, `applied` finalization, and idempotent recovery +- `memory_curator_submit`, `memory_curator_review`, and + `memory_curator_status`: deterministic AMF candidate/review orchestration + with authenticated artifacts, a redacted HMAC-chained decision ledger, and a + sequence/length/head anchor +- `memory_receipt_apply`: separately authorized receipt applicator; verifies an + `approved_pending_apply` decision, uses PAM proposal/apply, and queues a + digest-bound `memory_apply_receipt` +- `memory_curator_git_plan`: fail-closed Git writer planning; disabled and + dry-run-only by default, with no Git execution or push path +- `memory_curator_recover`: curator-only recovery for an existing strict-prefix + external anchor or one exact review artifact; apply recovery is an exact + `memory_receipt_apply` retry - `maintenance_run`: wraps the maintenance CLI (defaults to dry-run) Write paths through the server are bounded: @@ -31,8 +43,13 @@ Write paths through the server are bounded: re-validates everything (protected paths, drift, graph integrity) before applying. Archive collisions and proposal-identity mismatches fail closed before target persistence. -- `memory_propose_record` is the only MCP path for creating an AMF record; - creation remains pending until `memory_apply_proposal` re-validates it. +- `memory_propose_record` is the only underlying proposal path for creating an + AMF record. Only the receipt applicator delegates to it. +- The curator emits `review_required`, `rejected`, or + `approved_pending_apply`; it never applies or reports promotion. +- Curator decisions require `memory:curate`; canonical application requires a + distinct server-side `memory:apply-receipt` capability. Client-supplied + reviewer labels never authorize a change. - `graph_reindex` writes only the derived `memory/graph/catalog.json`. - `maintenance_run` is gated by `config` and defaults to dry-run. @@ -142,7 +159,7 @@ set to the repo root. The exact config file location depends on your client. Each host prefixes MCP tools with the server name. Claude Code surfaces them as `mcp__pam__memory_audit`, `mcp__pam__graph_validate`, and so on. Cursor and Codex use similar prefixes. The unprefixed tool name within the server is -always one of the 17 listed above. +always one of the 22 listed above. ## Workspace selection @@ -169,8 +186,10 @@ one-file change in `tools/lib/mcp-transport.mjs`. ## Safety surface -`memory_propose_edit` and `memory_propose_record` are the only tools that -produce artifacts intended for review. They reject, with a clear error message: +`memory_propose_edit`, `memory_propose_record`, and the curator tools produce +artifacts intended for review. The separate receipt applicator delegates +canonical changes to the proposal/apply tools. They reject, with a clear error +message: - paths matching `config.protectedPaths` (`AGENTS.md`, `CLAUDE.md`, `memory/agent-memory/`, `memory/sources/`); - paths that resolve outside the workspace; @@ -188,6 +207,8 @@ typically via `memory_apply_proposal` below. For the record schema, sealed-claim rules, lifecycle constraints, and safe graph projection, see [AMF memory record v1](amf-memory-v1.md). +For curator policy, idempotency, recovery, and the redacted decision ledger, +see [AMF deterministic curator](amf-curator.md). ## Write tools diff --git a/memory/pam.version.json b/memory/pam.version.json index 96d5618..c061828 100644 --- a/memory/pam.version.json +++ b/memory/pam.version.json @@ -1,5 +1,5 @@ { - "pamVersion": "0.6.0", + "pamVersion": "0.6.2", "memoryFormat": "graph-v1", "graphSchemaVersion": "pam-graph-v1", "features": { @@ -19,7 +19,16 @@ "tightBenchmarkRegressionGate": true, "amfMemoryV1": true, "sealedMemoryRecords": true, - "memoryRecordMcpTools": true + "memoryRecordMcpTools": true, + "memoryRecordConfidence": true, + "deterministicMemoryCurator": true, + "curatorDecisionLedger": true, + "curatorGitWriterDryRun": true, + "curatorExternalStateAnchor": true, + "curatorForwardRecovery": true, + "curatorDecisionReceipts": true, + "separateReceiptApplicator": true, + "durableApplyReceiptOutbox": true }, - "updated": "2026-07-11" + "updated": "2026-07-12" } diff --git a/migrations/0.5.3-to-0.6.0-agent-memory-fabric-records.md b/migrations/0.5.3-to-0.6.0-agent-memory-fabric-records.md index f11be55..2a54873 100644 --- a/migrations/0.5.3-to-0.6.0-agent-memory-fabric-records.md +++ b/migrations/0.5.3-to-0.6.0-agent-memory-fabric-records.md @@ -21,3 +21,10 @@ continue using classic PAM only. `memoryFormat` remains `graph-v1`. Person, relationship, confidential, and restricted records must be sealed before proposal. PAM validates but does not manage encryption keys. + +As of PAM 0.6.1 every `amf-memory/v1` record also requires exact structured +`confidence: {score,basis,assessedAt}` metadata. Before activating the 0.6.1 +validator, records drafted against the initial 0.6.0 shape require the reviewed +offline bootstrap described in `0.6.0-to-0.6.1-amf-confidence.md`; afterward, +missing confidence fails closed. Confidence changes require a newer assessment +timestamp. Sealed revisions must refresh AAD and IV. diff --git a/migrations/0.6.0-to-0.6.1-amf-confidence.md b/migrations/0.6.0-to-0.6.1-amf-confidence.md new file mode 100644 index 0000000..3b99d6c --- /dev/null +++ b/migrations/0.6.0-to-0.6.1-amf-confidence.md @@ -0,0 +1,32 @@ +# 0.6.0 to 0.6.1 - AMF record confidence + +## Summary + +PAM 0.6.1 makes structured confidence mandatory for every +`amf-memory/v1` record: + +```json +{"score":0.99,"basis":"reviewed","assessedAt":"2026-07-12T10:00:00Z"} +``` + +`score` is finite and between `0` and `1`; `basis` is `observed`, `asserted`, +`inferred`, or `reviewed`; `assessedAt` is RFC 3339 UTC between the record's +creation and update timestamps. + +## Existing AMF records + +An existing 0.6.0 record without confidence is not silently rewritten. Before +enabling the 0.6.1 validator, migrate it through an explicitly reviewed offline +step that adds the confidence object, increments `revision`, advances +`updatedAt`, and preserves immutable claim and append-only provenance rules. +The normal proposal transition cannot perform this bootstrap after 0.6.1 is +active because a current record with missing confidence is intentionally +invalid. For a sealed record, confidence is authenticated AAD: create a fresh +AES-256-GCM envelope and IV for the migrated revision. + +## Curator behavior + +Curator submissions retain the numeric compatibility field, but it must equal +the validated record's `confidence.score`. The record is authoritative. +Confidence cannot grant review/apply capability and cannot expand scope or +visibility policy. diff --git a/migrations/0.6.1-to-0.6.2-receipt-applicator.md b/migrations/0.6.1-to-0.6.2-receipt-applicator.md new file mode 100644 index 0000000..a7ce449 --- /dev/null +++ b/migrations/0.6.1-to-0.6.2-receipt-applicator.md @@ -0,0 +1,28 @@ +# 0.6.1 to 0.6.2 - separate receipt applicator + +## Summary + +PAM 0.6.2 separates curator judgment from canonical application. Curator +decisions now end as `review_required`, `rejected`, or +`approved_pending_apply`. The curator never calls proposal/apply and never +attests `promoted`. + +## Capability migration + +- Replace curator capabilities with `memory:curate`. +- Provision a different token and allowlist entry with + `memory:apply-receipt` under `amfApplicator`. +- Do not reuse the curator credential for the applicator. + +Existing `apply: true` review requests and `recover-apply` curator requests are +invalid. Record approval first, then call `memory_receipt_apply` with the +decision ID and a stable application idempotency key. + +## Recovery and transport + +Application state is durable under `memory/amf/applicator/` and advances from +`prepared` through PAM apply and receipt queueing to Fabric ACK. Retry the exact +application after a crash. The default transport is disabled; HTTP dispatch is +fail-closed until an audited Fabric endpoint/sink is integrated. + +The Git writer remains disabled and dry-run-only. diff --git a/package.json b/package.json index 77960e4..980b4e4 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "portable-agent-memory", - "version": "0.6.0", + "version": "0.6.2", "private": false, "description": "Markdown-first portable memory, wiki, and maintenance toolkit for AI agents.", "type": "module", @@ -21,6 +21,7 @@ "memory:rotate": "node tools/memory-maintenance.mjs rotate", "memory:index": "node tools/memory-maintenance.mjs index", "memory:synthesis": "node tools/memory-maintenance.mjs synthesis", + "memory:curator": "node tools/memory-curator.mjs", "memory:schedule:install": "node tools/install-memory-maintenance-schedule.mjs", "migrations:check": "node tools/check-migrations.mjs", "mcp:serve": "node tools/pam-mcp-server.mjs", diff --git a/tools/check-benchmark-thresholds.mjs b/tools/check-benchmark-thresholds.mjs index 10adb75..1e7bfe1 100644 --- a/tools/check-benchmark-thresholds.mjs +++ b/tools/check-benchmark-thresholds.mjs @@ -2,10 +2,10 @@ import { collectLargeCorpusBenchmark } from "./large-corpus-benchmark.mjs"; import { collectLlmRetrievalBenchmark } from "./llm-retrieval-benchmark.mjs"; const DEFAULT_BASELINES = { - pam04PromptReduction: 63.77, - pam05PromptReduction: 62.71, - pam04ReadReduction: 65.17, - pam05ReadReduction: 64.17, + pam04PromptReduction: 62.97, + pam05PromptReduction: 61.93, + pam04ReadReduction: 64.39, + pam05ReadReduction: 63.42, pam04NodeHitRate: 100, pam05NodeHitRate: 100, pam05CoverageQueries: 5, diff --git a/tools/lib/amf-memory-record.mjs b/tools/lib/amf-memory-record.mjs index 0a8586e..bf623f7 100644 --- a/tools/lib/amf-memory-record.mjs +++ b/tools/lib/amf-memory-record.mjs @@ -14,6 +14,7 @@ const RECORD_FIELDS = new Set([ "claimType", "scope", "visibility", + "confidence", "subjects", "claim", "lifecycle", @@ -33,6 +34,7 @@ const RESERVED_CLAIM_TYPES = new Set([ ]); const SCOPE_TYPES = new Set(["agent", "person", "relationship", "room", "domain", "shared"]); const VISIBILITIES = new Set(["private", "restricted", "shared", "confidential"]); +const CONFIDENCE_BASES = new Set(["observed", "asserted", "inferred", "reviewed"]); const SUBJECT_ROLES = new Set(["subject", "object", "participant", "owner"]); const LIFECYCLE_STATUSES = new Set(["active", "superseded", "revoked", "expired"]); const MEMORY_ID_RE = /^mem_[A-Za-z0-9][A-Za-z0-9_-]{7,127}$/; @@ -60,6 +62,7 @@ const PROVENANCE_FIELDS = new Set([ "capturedAt" ]); const SUBJECT_FIELDS = new Set(["identityId", "role"]); +const CONFIDENCE_FIELDS = new Set(["score", "basis", "assessedAt"]); function parseScalar(raw, lineNumber, errors) { const value = raw.trim(); @@ -181,6 +184,7 @@ function aadObjectFor(metadata) { claimType: metadata.claimType, scope: metadata.scope, visibility: metadata.visibility, + confidence: metadata.confidence, subjects: metadata.subjects }; if (metadata.claim?.encoding === "sealed") { @@ -305,6 +309,28 @@ function validateLifecycle(metadata, errors) { } } +function validateConfidence(metadata, errors) { + const confidence = metadata.confidence; + if (!validateExactObject(confidence, "confidence", CONFIDENCE_FIELDS, errors)) return; + if (typeof confidence.score !== "number" || !Number.isFinite(confidence.score) + || confidence.score < 0 || confidence.score > 1) { + errors.push("confidence.score must be a finite number between 0 and 1"); + } + if (!CONFIDENCE_BASES.has(confidence.basis)) { + errors.push("confidence.basis must be observed, asserted, inferred, or reviewed"); + } + if (!isRfc3339Utc(confidence.assessedAt)) { + errors.push("confidence.assessedAt must be RFC 3339 UTC"); + } else { + if (isRfc3339Utc(metadata.createdAt) && Date.parse(confidence.assessedAt) < Date.parse(metadata.createdAt)) { + errors.push("confidence.assessedAt must not be earlier than createdAt"); + } + if (isRfc3339Utc(metadata.updatedAt) && Date.parse(confidence.assessedAt) > Date.parse(metadata.updatedAt)) { + errors.push("confidence.assessedAt must not be later than updatedAt"); + } + } +} + function validateClaim(metadata, body, errors) { const claim = metadata.claim; if (!claim || typeof claim !== "object" || Array.isArray(claim)) { @@ -383,7 +409,7 @@ function projectMemoryRecord(metadata, sourcePath = null) { n: mayProjectClaim ? (digest.slice(0, 80) || `${metadata.claimType} memory`) : "Protected memory record", d: digest, st: statusForProjection(metadata), - c: "high", + c: metadata.confidence.score >= 0.8 ? "high" : metadata.confidence.score >= 0.5 ? "medium" : "low", u: metadata.updatedAt.slice(0, 10), src: sourcePath ?? recordPathFor(metadata), tags: [SCHEMA, metadata.claimType, metadata.scope.type, metadata.lifecycle.status, metadata.claim.encoding] @@ -477,6 +503,7 @@ function validateMemoryRecord(content, options = {}) { if (!isScopeId(metadata.scope.type, metadata.scope.id)) errors.push("scope.id must be canonical and match scope.type"); } if (!VISIBILITIES.has(metadata.visibility)) errors.push("visibility is invalid"); + validateConfidence(metadata, errors); validateSubjects(metadata.subjects, errors); validateClaim(metadata, parsed.body, errors); validateLifecycle(metadata, errors); @@ -561,6 +588,13 @@ function validateMemoryRecordTransition(currentContent, proposedContent, options if (newRecord.claim.iv === oldRecord.claim.iv) errors.push("sealed claim must use a new IV for every revision"); } if (!visibilityCanNarrow(oldRecord.visibility, newRecord.visibility)) errors.push("visibility must not widen across revisions"); + const confidenceChanged = canonicalize(oldRecord.confidence) !== canonicalize(newRecord.confidence); + if (Date.parse(newRecord.confidence.assessedAt) < Date.parse(oldRecord.confidence.assessedAt)) { + errors.push("confidence.assessedAt must not move backwards across revisions"); + } + if (confidenceChanged && Date.parse(newRecord.confidence.assessedAt) <= Date.parse(oldRecord.confidence.assessedAt)) { + errors.push("a confidence change requires a strictly newer confidence.assessedAt"); + } if (newRecord.provenance.length < oldRecord.provenance.length || oldRecord.provenance.some((item, index) => canonicalize(item) !== canonicalize(newRecord.provenance[index]))) { errors.push("provenance is append-only and existing entries must remain unchanged and ordered"); diff --git a/tools/lib/mcp-tools.mjs b/tools/lib/mcp-tools.mjs index d1195fa..883fb58 100644 --- a/tools/lib/mcp-tools.mjs +++ b/tools/lib/mcp-tools.mjs @@ -13,6 +13,14 @@ import { detectMemoryState } from "../memory-migration.mjs"; import { appendEntry } from "./memory-append.mjs"; import { applyProposal } from "./memory-apply-proposal.mjs"; +import { + curatorStatus, + planCuratorGitWrite, + recoverCuratorLedger, + reviewCuratorCandidate, + submitCuratorCandidate +} from "./memory-curator.mjs"; +import { applyDecisionReceipt } from "./memory-receipt-applicator.mjs"; import { validateMemoryRecord } from "./amf-memory-record.mjs"; import { runAudit } from "./memory-audit.mjs"; import { memoryList, memoryRead, memorySearch } from "./memory-fs.mjs"; @@ -311,6 +319,119 @@ function buildToolRegistry({ workspaceRoot, serverVersion }) { } return jsonResultContent(result); } + }, + { + name: "memory_curator_submit", + description: "Validates and queues a complete amf-memory/v1 candidate. It emits only a review_required, rejected, or approved_pending_apply decision receipt and never applies canonical memory.", + inputSchema: { + type: "object", + properties: { + content: { type: "string", description: "Complete amf-memory/v1 Markdown record; never a transcript or RAW event" }, + rationale: { type: "string" }, + idempotencyKey: { type: "string", minLength: 8, maxLength: 256 }, + confidence: { type: "number", minimum: 0, maximum: 1 }, + source: { + type: "object", + properties: { type: { type: "string" }, id: { type: "string" } }, + required: ["type", "id"], + additionalProperties: false + } + }, + required: ["content", "rationale", "idempotencyKey", "confidence", "source"], + additionalProperties: false + }, + handler: async (args) => jsonResultContent(submitCuratorCandidate(workspaceRoot, loadConfig(), args ?? {})) + }, + { + name: "memory_curator_review", + description: "Records a versioned approve/reject review and emits a decision receipt. Approval remains approved_pending_apply and cannot write canonical memory.", + inputSchema: { + type: "object", + properties: { + candidateId: { type: "string" }, + action: { type: "string", enum: ["approve", "reject"] }, + rationale: { type: "string" }, + reviewer: { type: "string" }, + idempotencyKey: { type: "string", minLength: 8, maxLength: 256 }, + confidence: { type: "number", minimum: 0, maximum: 1 } + }, + required: ["candidateId", "action", "rationale", "reviewer", "idempotencyKey"], + additionalProperties: false + }, + handler: async (args) => jsonResultContent(reviewCuratorCandidate(workspaceRoot, loadConfig(), args ?? {})) + }, + { + name: "memory_receipt_apply", + description: "Applicator-only deterministic transition for an approved decision receipt. It verifies policy/revision, uses PAM proposal/apply, queues an apply receipt, and dispatches only through a configured injected sink.", + inputSchema: { + type: "object", + properties: { + decisionId: { type: "string" }, + idempotencyKey: { type: "string", minLength: 8, maxLength: 256 }, + dispatch: { type: "boolean" } + }, + required: ["decisionId", "idempotencyKey"], + additionalProperties: false + }, + handler: async (args) => jsonResultContent(applyDecisionReceipt(workspaceRoot, loadConfig(), args ?? {})) + }, + { + name: "memory_curator_status", + description: "Returns redacted curator queue/review state and verifies the append-only decision ledger hash chain. It never returns claim content.", + inputSchema: { + type: "object", + properties: { candidateId: { type: "string" } }, + additionalProperties: false + }, + handler: async (args) => jsonResultContent(curatorStatus(workspaceRoot, loadConfig(), args ?? {})) + }, + { + name: "memory_curator_git_plan", + description: "Produces a fail-closed dry-run Git writer plan. The writer is disabled by default and always refuses direct push and protected branches.", + inputSchema: { + type: "object", + properties: { + branch: { type: "string" }, + baseBranch: { type: "string" }, + remote: { type: "string" }, + dryRun: { type: "boolean" }, + push: { type: "boolean" } + }, + required: ["branch"], + additionalProperties: false + }, + handler: async (args) => jsonResultContent(planCuratorGitWrite(loadConfig(), args ?? {})) + }, + { + name: "memory_curator_recover", + description: "Curator-only deterministic recovery for a strict-prefix anchor or one exact review artifact. Apply recovery belongs to memory_receipt_apply.", + inputSchema: { + type: "object", + properties: { + action: { type: "string", enum: ["advance-anchor", "recover-review"] }, + candidateId: { type: "string" }, + decisionAction: { type: "string", enum: ["approve", "reject"] }, + rationale: { type: "string" }, + reviewer: { type: "string" }, + idempotencyKey: { type: "string" }, + confidence: { type: "number", minimum: 0, maximum: 1 } + }, + required: ["action"], + oneOf: [ + { + properties: { action: { const: "advance-anchor" } }, + required: ["action"] + }, + { + properties: { + action: { const: "recover-review" } + }, + required: ["action", "candidateId", "decisionAction", "rationale", "reviewer", "idempotencyKey"] + } + ], + additionalProperties: false + }, + handler: async (args) => jsonResultContent(recoverCuratorLedger(workspaceRoot, loadConfig(), args ?? {})) } ]; diff --git a/tools/lib/memory-apply-proposal.mjs b/tools/lib/memory-apply-proposal.mjs index dddc91d..802e9ea 100644 --- a/tools/lib/memory-apply-proposal.mjs +++ b/tools/lib/memory-apply-proposal.mjs @@ -69,6 +69,10 @@ function proposalIdentity(record) { }; } +function proposalArtifactDigest(record) { + return crypto.createHash("sha256").update(canonicalJson(proposalIdentity(record)), "utf8").digest("hex"); +} + function validationWarningSummary(validation) { const summary = validation?.amfMemory ?? validation ?? {}; return { @@ -212,8 +216,12 @@ function reservationMatches(reservation, proposal) { function applyProposal(workspaceRoot, config, input, runtimeOptions = {}) { const proposalId = input?.proposalId; const lockOptions = runtimeOptions.lockOptions ?? {}; + const expectedProposalDigest = runtimeOptions.expectedProposalDigest; const invalid = validateProposalId(proposalId); if (invalid) return { ok: false, error: invalid }; + if (expectedProposalDigest !== undefined && !/^[0-9a-f]{64}$/.test(String(expectedProposalDigest))) { + return { ok: false, error: "expectedProposalDigest must be a lowercase SHA-256 digest" }; + } const proposalAbsolute = proposalPathFor(workspaceRoot, proposalId); const archivedAbsolute = appliedPathFor(workspaceRoot, proposalId); @@ -242,6 +250,10 @@ function applyProposal(workspaceRoot, config, input, runtimeOptions = {}) { const initialArchive = loadArchive(workspaceRoot, proposalId); if (!initialArchive.ok) return initialArchive; if (initialArchive.exists && initialArchive.record.status === "applied") { + if (expectedProposalDigest !== undefined + && proposalArtifactDigest(initialArchive.record) !== expectedProposalDigest) { + return { ok: false, error: "immutable proposal digest conflict" }; + } let liveProposal = null; if (fs.existsSync(proposalAbsolute)) { const loaded = loadProposal(workspaceRoot, proposalId); @@ -253,12 +265,11 @@ function applyProposal(workspaceRoot, config, input, runtimeOptions = {}) { return recoverAppliedArchive(workspaceRoot, config, proposalId, initialArchive.record, liveProposal); } - const loaded = loadProposal(workspaceRoot, proposalId); - if (!loaded.ok) return loaded; - const { record } = loaded; - const { targetPath, diff } = record; + const preliminary = loadProposal(workspaceRoot, proposalId); + if (!preliminary.ok) return preliminary; + const preliminaryDigest = proposalArtifactDigest(preliminary.record); + const { targetPath } = preliminary.record; if (typeof targetPath !== "string" || targetPath.trim() === "") return { ok: false, error: "proposal missing targetPath" }; - if (!diff || typeof diff !== "object") return { ok: false, error: "proposal missing diff" }; const targetLockId = crypto.createHash("sha256").update(toPosixPath(targetPath)).digest("hex"); const targetLockAbsolute = path.join(workspaceRoot, PROPOSALS_DIRNAME, `target-${targetLockId}.lock`); try { @@ -267,6 +278,22 @@ function applyProposal(workspaceRoot, config, input, runtimeOptions = {}) { return { ok: false, error: `target is already being modified: ${error.message}` }; } + if (typeof runtimeOptions.onTargetLockAcquired === "function") { + runtimeOptions.onTargetLockAcquired({ proposalId, proposalAbsolute, targetPath }); + } + const locked = loadProposal(workspaceRoot, proposalId); + if (!locked.ok) return locked; + const lockedDigest = proposalArtifactDigest(locked.record); + if (lockedDigest !== preliminaryDigest) { + return { ok: false, error: "proposal changed while acquiring the target lock" }; + } + if (expectedProposalDigest !== undefined && lockedDigest !== expectedProposalDigest) { + return { ok: false, error: "immutable proposal digest conflict" }; + } + const { record } = locked; + const { diff } = record; + if (!diff || typeof diff !== "object") return { ok: false, error: "proposal missing diff" }; + const pathCheck = validatePathSafety(workspaceRoot, targetPath, config); if (!pathCheck.ok) return { ok: false, error: pathCheck.error }; if (!/^[0-9a-f]{64}$/i.test(String(record.proposedContentSha256 ?? ""))) { @@ -403,4 +430,4 @@ function applyProposal(workspaceRoot, config, input, runtimeOptions = {}) { } } -export { applyProposal }; +export { applyProposal, proposalArtifactDigest }; diff --git a/tools/lib/memory-curator.mjs b/tools/lib/memory-curator.mjs new file mode 100644 index 0000000..3df572f --- /dev/null +++ b/tools/lib/memory-curator.mjs @@ -0,0 +1,2197 @@ +import crypto from "node:crypto"; +import fs from "node:fs"; +import path from "node:path"; + +import { + canonicalize, + parseMemoryRecord, + recordPathFor, + recordSha256, + validateMemoryRecord, + validateMemoryRecordTransition +} from "./amf-memory-record.mjs"; +import { proposeEdit, proposeMemoryRecord } from "./memory-proposals.mjs"; +import { + acquireExclusiveLock, + assertNoSymlinkPath, + atomicWriteFileSync, + readFileNoFollowSync +} from "./secure-fs.mjs"; +import { toPosixPath, workspaceRelative } from "./workspace.mjs"; + +const CURATOR_SCHEMA = "amf-curator/v1"; +const CURATOR_ROOT = path.join("memory", "amf", "curator"); +const QUEUE_DIR = path.join(CURATOR_ROOT, "queue"); +const REVIEWS_DIR = path.join(CURATOR_ROOT, "reviews"); +const DECISION_RECEIPTS_DIR = path.join(CURATOR_ROOT, "decision-receipts"); +const LEDGER_PATH = path.join(CURATOR_ROOT, "decisions.jsonl"); +const WORKSPACE_SENTINEL_PATH = path.join("memory", "amf", "curator.initialized.json"); +const CANDIDATE_ID_RE = /^candidate-[0-9a-f]{40}$/; +const DECISION_ID_RE = /^decision-[0-9a-f]{40}$/; +const HASH_RE = /^[0-9a-f]{64}$/; +const DEFAULT_POLICY = Object.freeze({ + version: "amf-curator-policy/v1", + autoPromote: false, + minimumConfidence: 0.98, + autoScopes: ["shared"], + autoVisibilities: ["shared"], + requireReviewForLifecycleChange: true, + requireReviewForSupersession: true, + rejectOnWarnings: true, + ledgerKeyEnv: "PAM_CURATOR_LEDGER_KEY", + stateDirEnv: "PAM_CURATOR_STATE_DIR", + reviewerTokenEnv: "PAM_CURATOR_REVIEWER_TOKEN", + reviewers: [], + gitWriter: { + enabled: false, + dryRunOnly: true, + protectedBranches: ["main", "master", "main-integration"] + } +}); + +const EVENT_FIELDS = new Set([ + "schema", "eventId", "sequence", "occurredAt", "type", "candidateId", + "decisionId", "details", "previousEventMac", "eventMac" +]); +const EVENT_DETAIL_FIELDS = Object.freeze({ + "candidate-received": new Set([ + "recordRefHmac", "revision", "scopeType", "visibility", "changeKind", + "recordSha256", "sourceClass", "sourceRefHmac" + ]), + "decision-recorded": new Set([ + "action", "confidence", "apply", "actorIdSha256", "reviewerLabelSha256", + "supersedesDecisionId", "reasonCodes" + ]), + "proposal-recorded": new Set([ + "proposalId", "targetRefHmac", "proposedContentSha256", "expectedRevision" + ]), + "proposal-applied": new Set([ + "proposalId", "targetRefHmac", "persistedContentSha256", "recordRefHmac", + "revision", "appliedArchiveSha256" + ]) +}); +const SCOPE_TYPES = new Set(["agent", "person", "relationship", "room", "domain", "shared"]); +const VISIBILITIES = new Set(["private", "restricted", "shared", "confidential"]); +const CHANGE_KINDS = new Set(["create", "revision", "revoke", "supersede", "expire", "superseding-create"]); +const REVIEW_ACTIONS = new Set(["review", "duplicate", "approve", "reject"]); +const REVIEW_ARTIFACT_FIELDS = new Set([ + "schema", "decisionId", "candidateId", "candidateRecordSha256", "candidateRevision", + "createdAt", "inputSha256", "decisionKeySha256", "supersedesDecisionId", + "action", "rationale", "reviewerLabel", "actorId", "confidence", "apply", + "reasons", "artifactMac" +]); +const DECISION_RECEIPT_FIELDS = new Set([ + "schema", "receiptType", "outcome", "decisionId", "candidateId", + "candidateRecordSha256", "candidateRevision", "canonicalRecordId", + "canonicalLifecycleAtDecision", "policyDigest", "createdAt", "decisionDigest", + "artifactMac" +]); +const DECISION_OUTCOMES = new Set(["review_required", "rejected", "approved_pending_apply"]); +const SOURCE_CLASSES = new Set(["codex", "claude", "hermes", "openclaw", "principia", "fabric", "operator", "migration", "synthetic", "other"]); +const SAFE_CODE_RE = /^[a-z][a-z0-9-]{1,63}$/; +const SAFE_ACTOR_RE = /^(?:agent|person|service):[A-Za-z0-9][A-Za-z0-9._-]{2,127}$/; +const MAX_RECORD_BYTES = 256 * 1024; +const MAX_RATIONALE_BYTES = 4 * 1024; + +function sha256(value) { + return crypto.createHash("sha256").update(String(value), "utf8").digest("hex"); +} + +function hmacSha256(key, value) { + return crypto.createHmac("sha256", key).update(String(value), "utf8").digest("hex"); +} + +function secureDigestEqual(left, right) { + if (!HASH_RE.test(String(left ?? "")) || !HASH_RE.test(String(right ?? ""))) return false; + return crypto.timingSafeEqual(Buffer.from(left, "hex"), Buffer.from(right, "hex")); +} + +function exactKeys(value, allowed, required = allowed) { + if (!isPlainObject(value)) return false; + const keys = Object.keys(value); + return keys.every((key) => allowed.has(key)) && [...required].every((key) => Object.hasOwn(value, key)); +} + +function isTimestamp(value) { + return typeof value === "string" && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$/.test(value) + && Number.isFinite(Date.parse(value)); +} + +function resolveLedgerKey(policy, runtime = {}) { + const value = runtime.ledgerKey ?? process.env[policy.ledgerKeyEnv]; + if (typeof value !== "string" || Buffer.byteLength(value, "utf8") < 32) { + return { ok: false, error: `authoritative curator operation requires a >=32-byte key in ${policy.ledgerKeyEnv}` }; + } + return { ok: true, key: Buffer.from(value, "utf8") }; +} + +function pathIsInside(root, target) { + const relative = path.relative(root, target); + return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative)); +} + +function resolveStateContext(workspaceRoot, policy, runtime = {}) { + const configured = runtime.stateDir ?? process.env[policy.stateDirEnv]; + if (typeof configured !== "string" || !path.isAbsolute(configured)) { + return { ok: false, error: `authoritative curator operation requires an absolute provisioned state root in ${policy.stateDirEnv}` }; + } + const requested = path.resolve(configured); + let realState; + let realWorkspace; + try { + const stats = fs.lstatSync(requested); + if (!stats.isDirectory() || stats.isSymbolicLink() || (stats.mode & 0o777) !== 0o700 + || (typeof process.getuid === "function" && stats.uid !== process.getuid())) { + return { ok: false, error: "curator state root must be a real 0700 directory" }; + } + realState = fs.realpathSync(requested); + realWorkspace = fs.realpathSync(workspaceRoot); + } catch (error) { + return { ok: false, error: `curator state root is not provisioned: ${error.message}` }; + } + if (realState !== requested) return { ok: false, error: "curator state root contains a symlink component" }; + if (pathIsInside(realWorkspace, realState) || pathIsInside(realState, realWorkspace)) { + return { ok: false, error: "curator state root must be outside the workspace/repository" }; + } + const workspaceId = sha256(realWorkspace); + return { + ok: true, + root: realState, + workspaceId, + anchorPath: path.join(realState, `${workspaceId}.anchor.json`), + initializedPath: path.join(realState, `${workspaceId}.initialized.json`), + workspaceSentinelPath: path.join(realWorkspace, WORKSPACE_SENTINEL_PATH) + }; +} + +function authorizeReviewer(policy, runtime, capabilities) { + const token = runtime?.reviewerToken ?? process.env[policy.reviewerTokenEnv]; + if (typeof token !== "string" || token.length < 16) return { ok: false, error: "reviewer capability is not configured server-side" }; + const tokenSha256 = sha256(token); + const actor = policy.reviewers.find((entry) => secureDigestEqual(entry.tokenSha256, tokenSha256)); + if (!actor) return { ok: false, error: "reviewer capability is unauthorized" }; + if (!SAFE_ACTOR_RE.test(String(actor.actorId ?? "")) || !Array.isArray(actor.capabilities)) { + return { ok: false, error: "reviewer allowlist entry is malformed" }; + } + const missing = capabilities.filter((capability) => !actor.capabilities.includes(capability)); + if (missing.length > 0) return { ok: false, error: `reviewer capability missing: ${missing.join(",")}` }; + return { ok: true, actorId: actor.actorId, capabilities: [...actor.capabilities] }; +} + +function safeStableId(prefix, seed) { + return `${prefix}-${sha256(`${CURATOR_SCHEMA}\0${seed}`).slice(0, 40)}`; +} + +function isPlainObject(value) { + return Boolean(value) && typeof value === "object" && !Array.isArray(value); +} + +function validateStableKey(value, label) { + if (typeof value !== "string" || value.length < 8 || value.length > 256 || /[\r\n\0]/.test(value)) { + return `${label} must be a stable string of 8-256 characters without control newlines`; + } + return null; +} + +function normalizeConfidence(value) { + if (value === undefined || value === null) return 0; + if (typeof value !== "number" || !Number.isFinite(value) || value < 0 || value > 1) return null; + return value; +} + +function normalizeSource(input) { + const source = input?.source; + if (!isPlainObject(source) + || typeof source.type !== "string" || !/^[a-z][a-z0-9._-]{1,63}$/.test(source.type) + || typeof source.id !== "string" || source.id.length < 1 || source.id.length > 256 + || /[\r\n\0]/.test(source.id)) { + return { ok: false, error: "source must contain a stable type and id; RAW payloads are not accepted" }; + } + if (Object.keys(source).sort().join(",") !== "id,type") { + return { ok: false, error: "source accepts exactly type and id; RAW payloads are not accepted" }; + } + return { ok: true, source: { type: source.type, id: source.id } }; +} + +function curatorPolicy(config = {}) { + const configured = isPlainObject(config.amfCurator) ? config.amfCurator : {}; + const gitWriter = isPlainObject(configured.gitWriter) ? configured.gitWriter : {}; + const policy = { + ...DEFAULT_POLICY, + ...configured, + autoScopes: Array.isArray(configured.autoScopes) ? [...configured.autoScopes] : [...DEFAULT_POLICY.autoScopes], + autoVisibilities: Array.isArray(configured.autoVisibilities) + ? [...configured.autoVisibilities] + : [...DEFAULT_POLICY.autoVisibilities], + reviewers: Array.isArray(configured.reviewers) ? configured.reviewers.map((entry) => ({ ...entry })) : [], + gitWriter: { + ...DEFAULT_POLICY.gitWriter, + ...gitWriter, + protectedBranches: Array.isArray(gitWriter.protectedBranches) + ? [...gitWriter.protectedBranches] + : [...DEFAULT_POLICY.gitWriter.protectedBranches] + } + }; + if (policy.version !== DEFAULT_POLICY.version) throw new Error(`unsupported curator policy: ${policy.version}`); + if (typeof policy.autoPromote !== "boolean") throw new Error("amfCurator.autoPromote must be boolean"); + if (typeof policy.minimumConfidence !== "number" || policy.minimumConfidence < 0 || policy.minimumConfidence > 1) { + throw new Error("amfCurator.minimumConfidence must be between 0 and 1"); + } + for (const [label, values] of [["autoScopes", policy.autoScopes], ["autoVisibilities", policy.autoVisibilities]]) { + if (!Array.isArray(values) || values.some((value) => typeof value !== "string" || value === "")) { + throw new Error(`amfCurator.${label} must be a string array`); + } + } + if (typeof policy.ledgerKeyEnv !== "string" || !/^[A-Z][A-Z0-9_]{2,63}$/.test(policy.ledgerKeyEnv) + || typeof policy.stateDirEnv !== "string" || !/^[A-Z][A-Z0-9_]{2,63}$/.test(policy.stateDirEnv) + || typeof policy.reviewerTokenEnv !== "string" || !/^[A-Z][A-Z0-9_]{2,63}$/.test(policy.reviewerTokenEnv)) { + throw new Error("curator security environment variable names are invalid"); + } + for (const reviewer of policy.reviewers) { + if (!isPlainObject(reviewer) || !exactKeys(reviewer, new Set(["tokenSha256", "actorId", "capabilities"])) + || !HASH_RE.test(String(reviewer.tokenSha256 ?? "")) || !SAFE_ACTOR_RE.test(String(reviewer.actorId ?? "")) + || !Array.isArray(reviewer.capabilities) + || reviewer.capabilities.some((value) => !new Set(["memory:curate"]).has(value))) { + throw new Error("amfCurator.reviewers contains an invalid allowlist entry"); + } + } + return policy; +} + +function ensureCuratorLayout(workspaceRoot) { + const root = path.join(workspaceRoot, CURATOR_ROOT); + assertNoSymlinkPath(workspaceRoot, root); + fs.mkdirSync(path.join(workspaceRoot, QUEUE_DIR), { recursive: true, mode: 0o700 }); + fs.mkdirSync(path.join(workspaceRoot, REVIEWS_DIR), { recursive: true, mode: 0o700 }); + fs.mkdirSync(path.join(workspaceRoot, DECISION_RECEIPTS_DIR), { recursive: true, mode: 0o700 }); + assertNoSymlinkPath(workspaceRoot, root, { allowMissing: false }); + assertNoSymlinkPath(workspaceRoot, path.join(workspaceRoot, QUEUE_DIR), { allowMissing: false }); + assertNoSymlinkPath(workspaceRoot, path.join(workspaceRoot, REVIEWS_DIR), { allowMissing: false }); + assertNoSymlinkPath(workspaceRoot, path.join(workspaceRoot, DECISION_RECEIPTS_DIR), { allowMissing: false }); +} + +function readJsonArtifact(workspaceRoot, absolute, label) { + try { + const parsed = JSON.parse(readFileNoFollowSync(workspaceRoot, absolute)); + if (!isPlainObject(parsed)) throw new Error("top-level JSON must be an object"); + return { ok: true, record: parsed }; + } catch (error) { + return { ok: false, error: `${label} is not valid safe JSON: ${error.message}` }; + } +} + +function candidatePath(workspaceRoot, candidateId) { + return path.join(workspaceRoot, QUEUE_DIR, `${candidateId}.json`); +} + +function reviewPath(workspaceRoot, decisionId) { + return path.join(workspaceRoot, REVIEWS_DIR, `${decisionId}.json`); +} + +function decisionReceiptPath(workspaceRoot, decisionId) { + return path.join(workspaceRoot, DECISION_RECEIPTS_DIR, `${decisionId}.json`); +} + +function artifactMac(key, artifact) { + const copy = { ...artifact }; + delete copy.artifactMac; + return hmacSha256(key, canonicalize(copy)); +} + +function listSafeJson(workspaceRoot, relativeDir) { + const absoluteDir = path.join(workspaceRoot, relativeDir); + if (!fs.existsSync(absoluteDir)) return []; + assertNoSymlinkPath(workspaceRoot, absoluteDir, { allowMissing: false }); + const rows = []; + for (const name of fs.readdirSync(absoluteDir).sort()) { + if (!name.endsWith(".json")) throw new Error(`bogus curator artifact: ${toPosixPath(path.join(relativeDir, name))}`); + const absolute = path.join(absoluteDir, name); + const stat = fs.lstatSync(absolute); + if (!stat.isFile() || stat.isSymbolicLink()) throw new Error(`unsafe curator artifact: ${toPosixPath(path.relative(workspaceRoot, absolute))}`); + const loaded = readJsonArtifact(workspaceRoot, absolute, "curator artifact"); + if (!loaded.ok) throw new Error(loaded.error); + rows.push(loaded.record); + } + return rows; +} + +function claimFingerprint(metadata) { + const claimMaterial = metadata.claim.encoding === "plain" + ? metadata.claim.text.normalize("NFC").replace(/\s+/g, " ").trim().toLocaleLowerCase("en-US") + : metadata.provenance.map((item) => ({ + sourceType: item.sourceType, + eventId: item.eventId, + contentSha256: item.contentSha256 + })); + return sha256(canonicalize({ + claimType: metadata.claimType, + scope: metadata.scope, + subjects: metadata.subjects, + claimMaterial + })); +} + +function recordSummary(validation) { + const metadata = validation.metadata; + return { + id: metadata.id, + revision: metadata.revision, + claimType: metadata.claimType, + scope: metadata.scope, + visibility: metadata.visibility, + confidence: { ...metadata.confidence }, + lifecycleStatus: metadata.lifecycle.status, + supersedes: [...metadata.lifecycle.supersedes], + claimEncoding: metadata.claim.encoding + }; +} + +function redactedRecordSummary(record) { + return { + id: record.id, + revision: record.revision, + claimType: record.claimType, + scopeType: record.scope.type, + visibility: record.visibility, + confidence: { ...record.confidence }, + lifecycleStatus: record.lifecycleStatus, + supersedes: [...record.supersedes], + claimEncoding: record.claimEncoding + }; +} + +function inspectCandidate(workspaceRoot, content) { + if (typeof content !== "string" || content.trim() === "") { + return { ok: false, error: "content must be a complete amf-memory/v1 record; RAW payloads are not accepted" }; + } + const validation = validateMemoryRecord(content, { workspaceRoot }); + if (!validation.ok) { + return { ok: false, error: `candidate record fails validation: ${validation.errors.join("; ")}`, validation }; + } + const targetPath = recordPathFor(validation.metadata); + const absolute = path.join(workspaceRoot, targetPath); + assertNoSymlinkPath(workspaceRoot, absolute); + const targetExists = fs.existsSync(absolute); + let currentContent = null; + let transition = null; + let duplicateExisting = false; + if (targetExists) { + currentContent = readFileNoFollowSync(workspaceRoot, absolute); + duplicateExisting = recordSha256(currentContent) === recordSha256(content); + if (!duplicateExisting) { + transition = validateMemoryRecordTransition(currentContent, content, { + expectedPath: targetPath, + workspaceRoot + }); + if (!transition.ok) { + return { ok: false, error: `candidate revision fails transition validation: ${transition.errors.join("; ")}`, validation, transition }; + } + } + } else if (validation.metadata.revision !== 1) { + return { ok: false, error: "a candidate without a canonical target must start at revision 1", validation }; + } + const summary = recordSummary(validation); + let changeKind = targetExists ? "revision" : "create"; + if (targetExists && summary.lifecycleStatus === "revoked") changeKind = "revoke"; + else if (targetExists && summary.lifecycleStatus === "superseded") changeKind = "supersede"; + else if (targetExists && summary.lifecycleStatus === "expired") changeKind = "expire"; + else if (!targetExists && summary.supersedes.length > 0) changeKind = "superseding-create"; + return { + ok: true, + validation, + targetPath, + targetExists, + currentContent, + transition, + duplicateExisting, + changeKind, + summary, + semanticFingerprint: claimFingerprint(validation.metadata) + }; +} + +function readCandidate(workspaceRoot, candidateId, key) { + if (!CANDIDATE_ID_RE.test(String(candidateId ?? ""))) return { ok: false, error: "invalid candidateId" }; + const absolute = candidatePath(workspaceRoot, candidateId); + if (!fs.existsSync(absolute)) return { ok: false, error: `candidate not found: ${candidateId}` }; + const loaded = readJsonArtifact(workspaceRoot, absolute, "candidate"); + if (!loaded.ok) return loaded; + if (loaded.record.schema !== `${CURATOR_SCHEMA}/candidate` || loaded.record.candidateId !== candidateId) { + return { ok: false, error: "candidate artifact identity is invalid" }; + } + const record = loaded.record; + if (typeof record.recordContent !== "string" || recordSha256(record.recordContent) !== record.recordSha256 + || !HASH_RE.test(String(record.inputSha256 ?? "")) + || !HASH_RE.test(String(record.idempotencyKeySha256 ?? "")) + || !HASH_RE.test(String(record.semanticFingerprint ?? "")) + || !HASH_RE.test(String(record.artifactMac ?? "")) + || !secureDigestEqual(artifactMac(key, record), record.artifactMac) + || safeStableId("candidate", record.idempotencyKeySha256) !== candidateId) { + return { ok: false, error: "candidate artifact hashes are invalid" }; + } + const inputIdentity = { + recordSha256: record.recordSha256, + rationale: record.rationale, + source: record.source, + confidence: record.confidence + }; + if (sha256(canonicalize(inputIdentity)) !== record.inputSha256) { + return { ok: false, error: "candidate artifact input hash is invalid" }; + } + const validation = validateMemoryRecord(record.recordContent, { + expectedPath: recordPathFor(parseMemoryRecord(record.recordContent).metadata), + workspaceRoot, + resolveSupersedes: false, + checkWorkspaceGraph: false + }); + if (!validation.ok) return { ok: false, error: `candidate artifact record is invalid: ${validation.errors.join("; ")}` }; + const derivedSummary = recordSummary(validation); + const derivedPath = recordPathFor(validation.metadata); + const derivedFingerprint = claimFingerprint(validation.metadata); + if (canonicalize(record.record) !== canonicalize(derivedSummary) + || record.confidence !== derivedSummary.confidence.score + || record.targetPath !== derivedPath || record.semanticFingerprint !== derivedFingerprint) { + return { ok: false, error: "candidate artifact derived fields do not match validated recordContent" }; + } + const derived = { + ...record, + record: derivedSummary, + targetPath: derivedPath, + semanticFingerprint: derivedFingerprint + }; + return { ok: true, record: derived, absolute }; +} + +function eventMac(key, event) { + const copy = { ...event }; + delete copy.eventMac; + return hmacSha256(key, canonicalize(copy)); +} + +function anchorMac(key, anchor) { + const copy = { ...anchor }; + delete copy.anchorMac; + return hmacSha256(key, canonicalize(copy)); +} + +function validateEventDetails(type, details) { + const fields = EVENT_DETAIL_FIELDS[type]; + if (!fields || !exactKeys(details, fields)) return false; + if (type === "candidate-received") { + return HASH_RE.test(details.recordRefHmac) && Number.isInteger(details.revision) && details.revision > 0 + && SCOPE_TYPES.has(details.scopeType) && VISIBILITIES.has(details.visibility) + && CHANGE_KINDS.has(details.changeKind) && HASH_RE.test(details.recordSha256) + && SOURCE_CLASSES.has(details.sourceClass) && HASH_RE.test(details.sourceRefHmac); + } + if (type === "decision-recorded") { + return REVIEW_ACTIONS.has(details.action) + && typeof details.confidence === "number" && details.confidence >= 0 && details.confidence <= 1 + && typeof details.apply === "boolean" && HASH_RE.test(details.actorIdSha256) + && HASH_RE.test(details.reviewerLabelSha256) + && (details.supersedesDecisionId === null || DECISION_ID_RE.test(details.supersedesDecisionId)) + && Array.isArray(details.reasonCodes) && details.reasonCodes.length <= 16 + && new Set(details.reasonCodes).size === details.reasonCodes.length + && details.reasonCodes.every((code) => SAFE_CODE_RE.test(code)); + } + if (type === "proposal-recorded") { + return /^[A-Za-z0-9][A-Za-z0-9-]{0,127}$/.test(details.proposalId) + && HASH_RE.test(details.targetRefHmac) + && HASH_RE.test(details.proposedContentSha256) + && (details.expectedRevision === null || (Number.isInteger(details.expectedRevision) && details.expectedRevision > 0)); + } + return /^[A-Za-z0-9][A-Za-z0-9-]{0,127}$/.test(details.proposalId) + && HASH_RE.test(details.targetRefHmac) + && HASH_RE.test(details.persistedContentSha256) && HASH_RE.test(details.appliedArchiveSha256) + && HASH_RE.test(details.recordRefHmac) + && Number.isInteger(details.revision) && details.revision > 0; +} + +function validateDecisionEvent(key, event, sequence, previousEventMac) { + return exactKeys(event, EVENT_FIELDS) + && event.schema === `${CURATOR_SCHEMA}/decision-event` + && typeof event.eventId === "string" && /^event-[A-Za-z0-9-]{8,240}$/.test(event.eventId) + && event.sequence === sequence && isTimestamp(event.occurredAt) + && Object.hasOwn(EVENT_DETAIL_FIELDS, event.type) + && CANDIDATE_ID_RE.test(String(event.candidateId ?? "")) + && (event.decisionId === null || DECISION_ID_RE.test(event.decisionId)) + && event.previousEventMac === previousEventMac + && HASH_RE.test(String(event.eventMac ?? "")) && secureDigestEqual(eventMac(key, event), event.eventMac) + && validateEventDetails(event.type, event.details) + && (event.type === "candidate-received" ? event.decisionId === null : event.decisionId !== null); +} + +function buildLedgerAnchor(key, events, byteLength) { + const anchor = { + schema: `${CURATOR_SCHEMA}/ledger-anchor`, + sequence: events.length, + headEventMac: events.at(-1)?.eventMac ?? null, + byteLength + }; + anchor.anchorMac = anchorMac(key, anchor); + return anchor; +} + +function readLedgerAnchor(state, key) { + const absolute = state.anchorPath; + if (!fs.existsSync(absolute)) return { ok: true, exists: false, record: null, absolute }; + const loaded = readJsonArtifact(state.root, absolute, "ledger anchor"); + if (!loaded.ok) return loaded; + const anchor = loaded.record; + const fields = new Set(["schema", "sequence", "headEventMac", "byteLength", "anchorMac"]); + if (!exactKeys(anchor, fields) || anchor.schema !== `${CURATOR_SCHEMA}/ledger-anchor` + || !Number.isInteger(anchor.sequence) || anchor.sequence < 0 + || (anchor.headEventMac !== null && !HASH_RE.test(String(anchor.headEventMac))) + || !Number.isInteger(anchor.byteLength) || anchor.byteLength < 0 + || !HASH_RE.test(String(anchor.anchorMac ?? "")) || !secureDigestEqual(anchorMac(key, anchor), anchor.anchorMac)) { + return { ok: false, error: "ledger anchor authentication failed" }; + } + return { ok: true, exists: true, record: anchor, absolute }; +} + +function writeLedgerAnchor(state, key, events, byteLength, options = {}) { + const absolute = state.anchorPath; + const anchor = buildLedgerAnchor(key, events, byteLength); + atomicWriteFileSync(state.root, absolute, `${JSON.stringify(anchor, null, 2)}\n`, { + mode: 0o600, + exclusive: options.exclusive === true + }); + return anchor; +} + +function initializedMarkerMac(key, marker) { + const copy = { ...marker }; + delete copy.markerMac; + return hmacSha256(key, canonicalize(copy)); +} + +function readInitializedMarker(root, absolute, key, label) { + if (!fs.existsSync(absolute)) return { ok: true, exists: false, record: null }; + const loaded = readJsonArtifact(root, absolute, label); + if (!loaded.ok) return loaded; + const marker = loaded.record; + const fields = new Set(["schema", "workspaceId", "initializedAt", "markerMac"]); + if (!exactKeys(marker, fields) || marker.schema !== `${CURATOR_SCHEMA}/initialized` + || !HASH_RE.test(String(marker.workspaceId ?? "")) || !isTimestamp(marker.initializedAt) + || !secureDigestEqual(initializedMarkerMac(key, marker), marker.markerMac)) { + return { ok: false, error: `${label} authentication failed` }; + } + return { ok: true, exists: true, record: marker }; +} + +function stateInitializationStatus(workspaceRoot, state, key) { + const external = readInitializedMarker(state.root, state.initializedPath, key, "external initialized marker"); + if (!external.ok) return external; + const sentinel = readInitializedMarker(workspaceRoot, state.workspaceSentinelPath, key, "workspace initialized sentinel"); + if (!sentinel.ok) return sentinel; + const anchor = readLedgerAnchor(state, key); + if (!anchor.ok) return anchor; + if (!external.exists && !sentinel.exists && !anchor.exists) { + const applicatorRoot = path.join(workspaceRoot, "memory", "amf", "applicator"); + const hasApplicatorEvidence = fs.existsSync(applicatorRoot) + && fs.readdirSync(applicatorRoot, { recursive: true }).length > 0; + if (hasApplicatorEvidence) { + return { ok: false, error: "curator state was deleted while durable applicator history remains; manual recovery required" }; + } + return { ok: true, initialized: false, anchor }; + } + if (!external.exists || !sentinel.exists || !anchor.exists) { + return { ok: false, error: "curator external state is partial or was deleted; manual recovery required" }; + } + if (external.record.workspaceId !== state.workspaceId || sentinel.record.workspaceId !== state.workspaceId + || canonicalize(external.record) !== canonicalize(sentinel.record)) { + return { ok: false, error: "curator initialized markers do not match this workspace" }; + } + return { ok: true, initialized: true, anchor, marker: external.record }; +} + +function initializeExternalState(workspaceRoot, state, key) { + const status = stateInitializationStatus(workspaceRoot, state, key); + if (!status.ok) return status; + if (status.initialized) return { ok: true, initialized: true, duplicate: true }; + const marker = { + schema: `${CURATOR_SCHEMA}/initialized`, + workspaceId: state.workspaceId, + initializedAt: new Date().toISOString() + }; + marker.markerMac = initializedMarkerMac(key, marker); + try { + atomicWriteFileSync(state.root, state.initializedPath, `${JSON.stringify(marker, null, 2)}\n`, { mode: 0o600, exclusive: true }); + writeLedgerAnchor(state, key, [], 0, { exclusive: true }); + atomicWriteFileSync(workspaceRoot, state.workspaceSentinelPath, `${JSON.stringify(marker, null, 2)}\n`, { mode: 0o600, exclusive: true }); + } catch (error) { + return { ok: false, error: `could not initialize external curator state atomically: ${error.message}` }; + } + return { ok: true, initialized: true, duplicate: false }; +} + +function readDecisionLedger(workspaceRoot, key, state, options = {}) { + if (!key) return { ok: false, error: "authoritative curator ledger key is required" }; + if (!state?.root) { + const resolved = resolveStateContext(workspaceRoot, DEFAULT_POLICY, {}); + if (!resolved.ok) return resolved; + state = resolved; + } + const absolute = path.join(workspaceRoot, LEDGER_PATH); + const initialization = stateInitializationStatus(workspaceRoot, state, key); + if (!initialization.ok) return initialization; + const anchor = initialization.anchor; + if (!anchor.ok) return anchor; + if (!fs.existsSync(absolute)) { + if (anchor.exists) { + if (anchor.record.sequence === 0 && anchor.record.headEventMac === null && anchor.record.byteLength === 0) { + return { ok: true, events: [], headMac: null, byteLength: 0 }; + } + return { ok: false, error: "ledger truncation detected: anchor exists without ledger" }; + } + return { ok: true, events: [], headMac: null, byteLength: 0 }; + } + let content; + try { + content = readFileNoFollowSync(workspaceRoot, absolute); + } catch (error) { + return { ok: false, error: `could not read curator ledger: ${error.message}` }; + } + const events = []; + const offsets = []; + let previous = null; + let consumed = 0; + const ids = new Set(); + for (const [index, rawLine] of content.match(/.*(?:\n|$)/g).entries()) { + if (rawLine === "") continue; + consumed += Buffer.byteLength(rawLine, "utf8"); + const line = rawLine.replace(/\n$/, "").replace(/\r$/, ""); + if (line === "") continue; + let event; + try { + event = JSON.parse(line); + } catch (error) { + return { ok: false, error: `curator ledger line ${index + 1} is invalid JSON: ${error.message}` }; + } + if (ids.has(event?.eventId) || !validateDecisionEvent(key, event, events.length + 1, previous)) { + return { ok: false, error: `curator ledger line ${index + 1} fails strict schema or authentication` }; + } + ids.add(event.eventId); + events.push(event); + offsets.push(consumed); + previous = event.eventMac; + } + const byteLength = Buffer.byteLength(content, "utf8"); + if (!anchor.exists) return { ok: false, error: "ledger anchor is missing" }; + const anchored = anchor.record; + if (anchored.sequence > events.length) return { ok: false, error: "ledger truncation detected: authenticated anchor is ahead" }; + const anchoredMac = anchored.sequence === 0 ? null : events[anchored.sequence - 1]?.eventMac; + const anchoredLength = anchored.sequence === 0 ? 0 : offsets[anchored.sequence - 1]; + if (anchored.headEventMac !== anchoredMac || anchored.byteLength !== anchoredLength) { + return { ok: false, error: "ledger anchor does not match the authenticated prefix" }; + } + const anchorBehind = anchored.sequence < events.length; + if (anchorBehind && options.allowBehind !== true) return { ok: false, error: "ledger anchor mismatch: authenticated anchor is behind" }; + return { ok: true, events, headMac: previous, byteLength, anchorBehind, anchoredSequence: anchored.sequence }; +} + +function appendDecisionEvent(workspaceRoot, key, state, input, options = {}) { + ensureCuratorLayout(workspaceRoot); + const lockAbsolute = path.join(workspaceRoot, CURATOR_ROOT, "decisions.lock"); + const lock = acquireExclusiveLock(workspaceRoot, lockAbsolute); + try { + const ledger = readDecisionLedger(workspaceRoot, key, state); + if (!ledger.ok) return ledger; + const base = { + schema: `${CURATOR_SCHEMA}/decision-event`, + eventId: input.eventId, + sequence: ledger.events.length + 1, + occurredAt: input.occurredAt, + type: input.type, + candidateId: input.candidateId, + decisionId: input.decisionId ?? null, + details: input.details ?? {}, + previousEventMac: ledger.headMac + }; + const existing = ledger.events.find((event) => event.eventId === input.eventId); + if (existing) { + const comparable = { ...existing }; + delete comparable.eventMac; + const desired = { ...base, sequence: existing.sequence, previousEventMac: existing.previousEventMac }; + if (canonicalize(comparable) !== canonicalize(desired)) { + return { ok: false, error: `ledger event idempotency conflict: ${input.eventId}` }; + } + return { ok: true, duplicate: true, event: existing }; + } + const event = { ...base }; + event.eventMac = eventMac(key, event); + if (!validateDecisionEvent(key, event, event.sequence, ledger.headMac)) { + return { ok: false, error: "refusing ledger event that fails strict schema" }; + } + const absolute = path.join(workspaceRoot, LEDGER_PATH); + assertNoSymlinkPath(workspaceRoot, absolute); + const ledgerExisted = fs.existsSync(absolute); + const flags = fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_APPEND | (fs.constants.O_NOFOLLOW ?? 0); + const fd = fs.openSync(absolute, flags, 0o600); + const line = `${JSON.stringify(event)}\n`; + try { + fs.writeFileSync(fd, line, "utf8"); + fs.fsyncSync(fd); + } finally { + fs.closeSync(fd); + } + const nextEvents = [...ledger.events, event]; + const nextLength = ledger.byteLength + Buffer.byteLength(line, "utf8"); + if (options.faultAt === "after-ledger-append") throw new Error("injected curator fault after ledger append before anchor replace"); + writeLedgerAnchor(state, key, nextEvents, nextLength); + if (!ledgerExisted) { + const dirFd = fs.openSync(path.dirname(absolute), fs.constants.O_RDONLY); + try { fs.fsyncSync(dirFd); } finally { fs.closeSync(dirFd); } + } + return { ok: true, duplicate: false, event }; + } finally { + lock.release(); + } +} + +function findCandidateDuplicate(workspaceRoot, candidate, index, options = {}) { + if (candidate.duplicateExisting) { + return { kind: "canonical-exact", recordId: candidate.summary.id }; + } + if (candidate.targetExists) return null; + const recordsDir = path.join(workspaceRoot, "memory", "amf", "records"); + if (fs.existsSync(recordsDir)) { + assertNoSymlinkPath(workspaceRoot, recordsDir, { allowMissing: false }); + for (const name of fs.readdirSync(recordsDir).sort()) { + if (!name.endsWith(".md")) continue; + const absolute = path.join(recordsDir, name); + const relative = toPosixPath(path.relative(workspaceRoot, absolute)); + if (options.ignoreCanonicalPath === relative) continue; + if (!fs.lstatSync(absolute).isFile()) throw new Error(`unsafe AMF record: ${name}`); + const content = readFileNoFollowSync(workspaceRoot, absolute); + const validation = validateMemoryRecord(content, { + expectedPath: relative, + workspaceRoot, + resolveSupersedes: false, + checkWorkspaceGraph: false + }); + if (!validation.ok || validation.metadata.lifecycle.status !== "active") continue; + if (candidate.summary.supersedes.includes(validation.metadata.id)) continue; + if (claimFingerprint(validation.metadata) === candidate.semanticFingerprint) { + return { kind: "canonical-semantic", recordId: validation.metadata.id }; + } + const candidateEvents = new Set(candidate.validation.metadata.provenance.map((item) => `${item.eventId}\0${item.contentSha256}`)); + if (validation.metadata.provenance.some((item) => candidateEvents.has(`${item.eventId}\0${item.contentSha256}`))) { + return { kind: "canonical-provenance", recordId: validation.metadata.id }; + } + } + } + for (const queued of index.candidates) { + if (queued.candidateId !== candidate.candidateId + && queued.semanticFingerprint === candidate.semanticFingerprint + && !candidate.summary.supersedes.includes(queued.record?.id)) { + return { kind: "queued-semantic", candidateId: queued.candidateId, recordId: queued.record?.id ?? null }; + } + } + return null; +} + +function deduplicateCandidate(workspaceRoot, candidate, key, state) { + const ledger = readDecisionLedger(workspaceRoot, key, state); + if (!ledger.ok) throw new Error(ledger.error); + const index = loadVerifiedCuratorIndex(workspaceRoot, key, ledger); + assertAppliedArchiveHistory(workspaceRoot, ledger); + return findCandidateDuplicate(workspaceRoot, candidate, index); +} + +function policyDecision(candidate, duplicate, policy) { + const reasons = []; + if (duplicate) return { action: "duplicate", reasons: [`duplicate-${duplicate.kind}`], eligible: false }; + if (!policy.autoPromote) reasons.push("auto-promotion-disabled"); + if (candidate.record.confidence.score < policy.minimumConfidence) reasons.push("below-confidence-threshold"); + if (!policy.autoScopes.includes(candidate.record.scope.type)) reasons.push("scope-requires-review"); + if (!policy.autoVisibilities.includes(candidate.record.visibility)) reasons.push("visibility-requires-review"); + if (policy.requireReviewForLifecycleChange && candidate.changeKind !== "create") reasons.push("lifecycle-change-requires-review"); + if (policy.requireReviewForSupersession && candidate.record.supersedes.length > 0) reasons.push("supersession-requires-review"); + if (policy.rejectOnWarnings && candidate.validationWarnings.length > 0) reasons.push("validation-warning-requires-review"); + return { + action: reasons.length === 0 ? "promote" : "review", + reasons, + eligible: reasons.length === 0 + }; +} + +function policyDecisionKey(policy) { + return `policy:${sha256(canonicalize(policy))}`; +} + +function policyReviewInput(candidate, policy, evaluation, actorId) { + return { + idempotencyKey: policyDecisionKey(policy), + action: evaluation.action === "promote" ? "approve" : evaluation.action, + rationale: evaluation.action === "promote" + ? "Candidate satisfied the explicitly enabled high-confidence policy." + : `Policy routed candidate to ${evaluation.action}.`, + reviewerLabel: "service:amf-curator-policy", + actorId, + confidence: candidate.record.confidence.score, + apply: false, + reasons: evaluation.reasons + }; +} + +function sourceClassFor(sourceType) { + const prefix = String(sourceType).split(/[._-]/, 1)[0]; + return SOURCE_CLASSES.has(prefix) && prefix !== "other" ? prefix : "other"; +} + +function candidateReceivedDetails(candidate, key) { + return { + recordRefHmac: hmacSha256(key, `record\0${candidate.record.id}`), + revision: candidate.record.revision, + scopeType: candidate.record.scope.type, + visibility: candidate.record.visibility, + changeKind: candidate.changeKind, + recordSha256: candidate.recordSha256, + sourceClass: sourceClassFor(candidate.source.type), + sourceRefHmac: hmacSha256(key, `source\0${candidate.source.type}\0${candidate.source.id}`) + }; +} + +function reviewDecisionDetails(review) { + return { + action: review.action, + confidence: review.confidence, + apply: review.apply, + actorIdSha256: sha256(review.actorId), + reviewerLabelSha256: sha256(review.reviewerLabel), + supersedesDecisionId: review.supersedesDecisionId, + reasonCodes: review.reasons + }; +} + +function reviewMatchesLedger(review, ledger) { + const event = ledger.events.find((entry) => entry.type === "decision-recorded" && entry.decisionId === review.decisionId); + return Boolean(event) && event.candidateId === review.candidateId + && canonicalize(event.details) === canonicalize(reviewDecisionDetails(review)); +} + +function loadVerifiedCuratorIndex(workspaceRoot, key, ledger) { + const candidates = []; + const queueAbsolute = path.join(workspaceRoot, QUEUE_DIR); + if (fs.existsSync(queueAbsolute)) { + for (const name of fs.readdirSync(queueAbsolute).sort()) { + if (!name.endsWith(".json")) throw new Error(`bogus queue artifact: ${name}`); + const loaded = readCandidate(workspaceRoot, name.slice(0, -5), key); + if (!loaded.ok) throw new Error(loaded.error); + candidates.push(loaded.record); + } + } + const candidateById = new Map(candidates.map((candidate) => [candidate.candidateId, candidate])); + const reviews = listSafeJson(workspaceRoot, REVIEWS_DIR); + if (reviews.some((review) => { + const candidate = candidateById.get(review.candidateId); + return !candidate || !validateReviewArtifact(review, key) || !reviewMatchesCandidate(review, candidate) + || !reviewMatchesLedger(review, ledger); + })) { + throw new Error("unverified review artifact in curator index"); + } + if (ledger.events.filter((event) => event.type === "decision-recorded").length !== reviews.length) { + throw new Error("review index and authenticated ledger differ"); + } + const received = ledger.events.filter((event) => event.type === "candidate-received"); + if (received.length !== candidates.length || received.some((event) => { + const candidate = candidateById.get(event.candidateId); + return !candidate || canonicalize(event.details) !== canonicalize(candidateReceivedDetails(candidate, key)); + })) { + throw new Error("candidate index and authenticated ledger differ"); + } + return { candidates, reviews }; +} + +function verifyIndexWithSingleMissingReceived(workspaceRoot, key, ledger, missingCandidateId) { + const candidates = []; + const queueAbsolute = path.join(workspaceRoot, QUEUE_DIR); + for (const name of fs.readdirSync(queueAbsolute).sort()) { + if (!name.endsWith(".json")) throw new Error(`bogus queue artifact: ${name}`); + const loaded = readCandidate(workspaceRoot, name.slice(0, -5), key); + if (!loaded.ok) throw new Error(loaded.error); + candidates.push(loaded.record); + } + const missing = candidates.filter((candidate) => candidate.candidateId === missingCandidateId); + if (missing.length !== 1) throw new Error("candidate recovery identity is not unique"); + const received = ledger.events.filter((event) => event.type === "candidate-received"); + const expected = candidates.filter((candidate) => candidate.candidateId !== missingCandidateId); + const expectedById = new Map(expected.map((candidate) => [candidate.candidateId, candidate])); + if (received.length !== expected.length || received.some((event) => { + const candidate = expectedById.get(event.candidateId); + return !candidate || canonicalize(event.details) !== canonicalize(candidateReceivedDetails(candidate, key)); + })) throw new Error("candidate recovery would hide unrelated queue/ledger drift"); + const reviews = listSafeJson(workspaceRoot, REVIEWS_DIR); + const candidateById = new Map(candidates.map((candidate) => [candidate.candidateId, candidate])); + if (reviews.some((review) => { + const candidate = candidateById.get(review.candidateId); + return !candidate || !validateReviewArtifact(review, key) || !reviewMatchesCandidate(review, candidate) + || !reviewMatchesLedger(review, ledger); + }) + || ledger.events.filter((event) => event.type === "decision-recorded").length !== reviews.length) { + throw new Error("candidate recovery found unverified review history"); + } + assertAppliedArchiveHistory(workspaceRoot, ledger); + return missing[0]; +} + +function exactReviewForInput(workspaceRoot, candidate, key, ledger, input) { + const keyError = validateStableKey(input.idempotencyKey, "decision idempotencyKey"); + if (keyError) return { ok: false, error: keyError }; + const confidence = normalizeConfidence(input.confidence); + if (confidence === null) return { ok: false, error: "confidence must be between 0 and 1" }; + if (!REVIEW_ACTIONS.has(input.action)) return { ok: false, error: "decision action is invalid" }; + if (typeof input.rationale !== "string" || input.rationale.trim() === "" + || Buffer.byteLength(input.rationale, "utf8") > MAX_RATIONALE_BYTES) { + return { ok: false, error: `decision rationale is required and limited to ${MAX_RATIONALE_BYTES} bytes` }; + } + const reviewerLabel = input.reviewerLabel ?? "service:amf-curator-policy"; + const actorId = input.actorId ?? "service:amf-curator-policy"; + const reasons = Array.isArray(input.reasons) ? input.reasons.map(String) : []; + if (!SAFE_ACTOR_RE.test(reviewerLabel) || !SAFE_ACTOR_RE.test(actorId) + || reasons.length > 16 || new Set(reasons).size !== reasons.length + || reasons.some((code) => !SAFE_CODE_RE.test(code))) { + return { ok: false, error: "review recovery identity is invalid" }; + } + const decisionKeySha256 = sha256(input.idempotencyKey); + const decisionId = safeStableId("decision", `${candidate.candidateId}\0${decisionKeySha256}`); + const absolute = reviewPath(workspaceRoot, decisionId); + if (!fs.existsSync(absolute)) return { ok: true, exists: false, decisionId }; + const loaded = readJsonArtifact(workspaceRoot, absolute, "review"); + if (!loaded.ok) return loaded; + const review = loaded.record; + const identity = { + candidateId: candidate.candidateId, + candidateRecordSha256: candidate.recordSha256, + candidateRevision: candidate.record.revision, + action: input.action, + rationale: input.rationale, + reviewerLabel, + actorId, + confidence, + apply: input.apply === true, + reasons + }; + const decisionEvents = ledger.events.filter((event) => event.type === "decision-recorded" + && event.candidateId === candidate.candidateId); + const existingIndex = decisionEvents.findIndex((event) => event.decisionId === decisionId); + const previousDecisionId = existingIndex >= 0 + ? decisionEvents[existingIndex - 1]?.decisionId ?? null + : decisionEvents.at(-1)?.decisionId ?? null; + if (!validateReviewArtifact(review, key) || !reviewMatchesCandidate(review, candidate) + || review.decisionId !== decisionId || review.decisionKeySha256 !== decisionKeySha256 + || review.inputSha256 !== sha256(canonicalize(identity)) + || review.supersedesDecisionId !== previousDecisionId + || canonicalize(Object.fromEntries(Object.keys(identity).map((name) => [name, review[name]]))) !== canonicalize(identity)) { + return { ok: false, error: `decision idempotency or candidate-version conflict: ${decisionId}` }; + } + return { ok: true, exists: true, review, decisionId, logged: existingIndex >= 0 }; +} + +function verifyIndexWithSingleMissingReview(workspaceRoot, key, ledger, expectedReview) { + const candidates = []; + const queueAbsolute = path.join(workspaceRoot, QUEUE_DIR); + for (const name of fs.readdirSync(queueAbsolute).sort()) { + if (!name.endsWith(".json")) throw new Error(`bogus queue artifact: ${name}`); + const loaded = readCandidate(workspaceRoot, name.slice(0, -5), key); + if (!loaded.ok) throw new Error(loaded.error); + candidates.push(loaded.record); + } + const candidateById = new Map(candidates.map((candidate) => [candidate.candidateId, candidate])); + const received = ledger.events.filter((event) => event.type === "candidate-received"); + if (received.length !== candidates.length || received.some((event) => { + const candidate = candidateById.get(event.candidateId); + return !candidate || canonicalize(event.details) !== canonicalize(candidateReceivedDetails(candidate, key)); + })) throw new Error("review recovery found candidate queue/ledger drift"); + + const reviews = listSafeJson(workspaceRoot, REVIEWS_DIR); + const decisionIds = new Set(); + for (const review of reviews) { + const candidate = candidateById.get(review.candidateId); + if (!candidate || !validateReviewArtifact(review, key) || !reviewMatchesCandidate(review, candidate) + || decisionIds.has(review.decisionId)) { + throw new Error("review recovery found an invalid, duplicate, or version-unbound artifact"); + } + decisionIds.add(review.decisionId); + } + const missing = reviews.filter((review) => !reviewMatchesLedger(review, ledger)); + if (missing.length !== 1 || missing[0].decisionId !== expectedReview.decisionId + || canonicalize(missing[0]) !== canonicalize(expectedReview)) { + throw new Error("review recovery identity is not unique or exact"); + } + const loggedReviews = reviews.filter((review) => review.decisionId !== expectedReview.decisionId); + const decisions = ledger.events.filter((event) => event.type === "decision-recorded"); + if (loggedReviews.length !== decisions.length + || loggedReviews.some((review) => !reviewMatchesLedger(review, ledger))) { + throw new Error("review recovery would hide unrelated review/ledger drift"); + } + assertAppliedArchiveHistory(workspaceRoot, ledger); + return { candidates, reviews }; +} + +function loadPolicyRecoveryIndex(workspaceRoot, key, ledger, candidateId, expectedDecisionId) { + const candidates = []; + const queueAbsolute = path.join(workspaceRoot, QUEUE_DIR); + for (const name of fs.readdirSync(queueAbsolute).sort()) { + if (!name.endsWith(".json")) throw new Error(`bogus queue artifact: ${name}`); + const loaded = readCandidate(workspaceRoot, name.slice(0, -5), key); + if (!loaded.ok) throw new Error(loaded.error); + candidates.push(loaded.record); + } + const candidateById = new Map(candidates.map((candidate) => [candidate.candidateId, candidate])); + if (!candidateById.has(candidateId)) throw new Error("policy recovery candidate is missing from the authenticated queue"); + const received = ledger.events.filter((event) => event.type === "candidate-received"); + if (received.length !== candidates.length || received.some((event) => { + const candidate = candidateById.get(event.candidateId); + return !candidate || canonicalize(event.details) !== canonicalize(candidateReceivedDetails(candidate, key)); + })) throw new Error("policy recovery found candidate queue/ledger drift"); + + const reviews = listSafeJson(workspaceRoot, REVIEWS_DIR); + const decisionIds = new Set(); + for (const review of reviews) { + const candidate = candidateById.get(review.candidateId); + if (!candidate || !validateReviewArtifact(review, key) || !reviewMatchesCandidate(review, candidate) + || decisionIds.has(review.decisionId)) { + throw new Error("policy recovery found an invalid, duplicate, or version-unbound review"); + } + decisionIds.add(review.decisionId); + } + const unlogged = reviews.filter((review) => !reviewMatchesLedger(review, ledger)); + if (unlogged.length > 1 || (unlogged.length === 1 + && (unlogged[0].candidateId !== candidateId || unlogged[0].decisionId !== expectedDecisionId))) { + throw new Error("policy recovery found an unrelated or ambiguous unlogged review"); + } + const logged = reviews.filter((review) => !unlogged.includes(review)); + const decisions = ledger.events.filter((event) => event.type === "decision-recorded"); + if (logged.length !== decisions.length || logged.some((review) => !reviewMatchesLedger(review, ledger))) { + throw new Error("policy recovery would hide unrelated review/ledger drift"); + } + return { candidates, reviews, unloggedReview: unlogged[0] ?? null }; +} + +function validateReviewArtifact(review, key) { + const identity = { + candidateId: review.candidateId, + candidateRecordSha256: review.candidateRecordSha256, + candidateRevision: review.candidateRevision, + action: review.action, + rationale: review.rationale, + reviewerLabel: review.reviewerLabel, + actorId: review.actorId, + confidence: review.confidence, + apply: review.apply, + reasons: review.reasons + }; + return exactKeys(review, REVIEW_ARTIFACT_FIELDS) + && review.schema === `${CURATOR_SCHEMA}/review` + && CANDIDATE_ID_RE.test(String(review.candidateId ?? "")) + && DECISION_ID_RE.test(String(review.decisionId ?? "")) + && HASH_RE.test(String(review.candidateRecordSha256 ?? "")) + && Number.isInteger(review.candidateRevision) && review.candidateRevision > 0 + && isTimestamp(review.createdAt) + && HASH_RE.test(String(review.decisionKeySha256 ?? "")) + && HASH_RE.test(String(review.inputSha256 ?? "")) + && HASH_RE.test(String(review.artifactMac ?? "")) + && review.decisionId === safeStableId("decision", `${review.candidateId}\0${review.decisionKeySha256}`) + && review.inputSha256 === sha256(canonicalize(identity)) + && secureDigestEqual(artifactMac(key, review), review.artifactMac) + && REVIEW_ACTIONS.has(review.action) + && typeof review.rationale === "string" && review.rationale.trim() !== "" + && Buffer.byteLength(review.rationale, "utf8") <= MAX_RATIONALE_BYTES + && SAFE_ACTOR_RE.test(String(review.reviewerLabel ?? "")) + && SAFE_ACTOR_RE.test(String(review.actorId ?? "")) + && typeof review.confidence === "number" && review.confidence >= 0 && review.confidence <= 1 + && typeof review.apply === "boolean" + && (review.supersedesDecisionId === null || DECISION_ID_RE.test(String(review.supersedesDecisionId))) + && Array.isArray(review.reasons) && review.reasons.length <= 16 + && new Set(review.reasons).size === review.reasons.length + && review.reasons.every((code) => SAFE_CODE_RE.test(code)); +} + +function curatorPolicyDigest(policy) { + return sha256(canonicalize(policy)); +} + +function decisionOutcome(action) { + if (action === "approve") return "approved_pending_apply"; + if (action === "reject") return "rejected"; + return "review_required"; +} + +function decisionReceiptPayload(receipt) { + return { + schema: receipt.schema, + receiptType: receipt.receiptType, + outcome: receipt.outcome, + decisionId: receipt.decisionId, + candidateId: receipt.candidateId, + candidateRecordSha256: receipt.candidateRecordSha256, + candidateRevision: receipt.candidateRevision, + canonicalRecordId: receipt.canonicalRecordId, + canonicalLifecycleAtDecision: receipt.canonicalLifecycleAtDecision, + policyDigest: receipt.policyDigest, + createdAt: receipt.createdAt + }; +} + +function validateDecisionReceipt(receipt, key, candidate, review) { + const payload = decisionReceiptPayload(receipt); + return exactKeys(receipt, DECISION_RECEIPT_FIELDS) + && receipt.schema === `${CURATOR_SCHEMA}/decision-receipt` + && receipt.receiptType === "memory_curator_decision" + && DECISION_OUTCOMES.has(receipt.outcome) + && receipt.outcome === decisionOutcome(review.action) + && receipt.decisionId === review.decisionId + && receipt.candidateId === candidate.candidateId + && receipt.candidateRecordSha256 === candidate.recordSha256 + && receipt.candidateRevision === candidate.record.revision + && receipt.canonicalRecordId === candidate.record.id + && receipt.canonicalLifecycleAtDecision === candidate.record.lifecycleStatus + && HASH_RE.test(String(receipt.policyDigest ?? "")) + && receipt.createdAt === review.createdAt + && receipt.decisionDigest === sha256(canonicalize(payload)) + && HASH_RE.test(String(receipt.artifactMac ?? "")) + && secureDigestEqual(artifactMac(key, receipt), receipt.artifactMac); +} + +function ensureDecisionReceipt(workspaceRoot, key, policy, candidate, review, runtime = {}) { + const absolute = decisionReceiptPath(workspaceRoot, review.decisionId); + const payload = { + schema: `${CURATOR_SCHEMA}/decision-receipt`, + receiptType: "memory_curator_decision", + outcome: decisionOutcome(review.action), + decisionId: review.decisionId, + candidateId: candidate.candidateId, + candidateRecordSha256: candidate.recordSha256, + candidateRevision: candidate.record.revision, + canonicalRecordId: candidate.record.id, + canonicalLifecycleAtDecision: candidate.record.lifecycleStatus, + policyDigest: curatorPolicyDigest(policy), + createdAt: review.createdAt + }; + const receipt = { ...payload, decisionDigest: sha256(canonicalize(payload)) }; + receipt.artifactMac = artifactMac(key, receipt); + if (fs.existsSync(absolute)) { + const loaded = readJsonArtifact(workspaceRoot, absolute, "decision receipt"); + if (!loaded.ok || !validateDecisionReceipt(loaded.record, key, candidate, review) + || canonicalize(loaded.record) !== canonicalize(receipt)) { + return { ok: false, error: `decision receipt conflict: ${review.decisionId}` }; + } + return { ok: true, duplicate: true, receipt: loaded.record }; + } + atomicWriteFileSync(workspaceRoot, absolute, `${JSON.stringify(receipt, null, 2)}\n`, { + exclusive: true, + mode: 0o600 + }); + if (runtime.faultAt === "after-decision-receipt-write") { + throw new Error("injected curator fault after decision receipt fsync"); + } + return { ok: true, duplicate: false, receipt }; +} + +function reviewMatchesCandidate(review, candidate) { + return review.candidateId === candidate.candidateId + && review.candidateRecordSha256 === candidate.recordSha256 + && review.candidateRevision === candidate.record.revision; +} + +function latestReview(workspaceRoot, candidateId, key, state) { + const candidate = readCandidate(workspaceRoot, candidateId, key); + if (!candidate.ok) throw new Error(candidate.error); + const reviews = listSafeJson(workspaceRoot, REVIEWS_DIR).filter((row) => row.candidateId === candidateId); + if (reviews.some((review) => !validateReviewArtifact(review, key) + || !reviewMatchesCandidate(review, candidate.record))) { + throw new Error(`invalid review artifact for ${candidateId}`); + } + if (reviews.length === 0) return null; + const ledger = readDecisionLedger(workspaceRoot, key, state); + if (!ledger.ok) throw new Error(ledger.error); + if (reviews.some((review) => !reviewMatchesLedger(review, ledger))) { + throw new Error(`review ledger binding is invalid for ${candidateId}`); + } + const order = new Map(); + ledger.events.filter((event) => event.type === "decision-recorded").forEach((event, index) => order.set(event.decisionId, index)); + reviews.sort((left, right) => (order.get(left.decisionId) ?? -1) - (order.get(right.decisionId) ?? -1)); + return reviews.at(-1); +} + +function recordReviewUnlocked(workspaceRoot, candidate, key, state, input, runtime = {}) { + const keyError = validateStableKey(input.idempotencyKey, "decision idempotencyKey"); + if (keyError) return { ok: false, error: keyError }; + const confidence = normalizeConfidence(input.confidence); + if (confidence === null) return { ok: false, error: "confidence must be between 0 and 1" }; + if (!REVIEW_ACTIONS.has(input.action)) { + return { ok: false, error: "decision action must be review, duplicate, approve, or reject" }; + } + if (typeof input.rationale !== "string" || input.rationale.trim() === "") { + return { ok: false, error: "decision rationale is required" }; + } + const reviewerLabel = input.reviewerLabel ?? "service:amf-curator-policy"; + const actorId = input.actorId ?? "service:amf-curator-policy"; + if (!SAFE_ACTOR_RE.test(reviewerLabel) || !SAFE_ACTOR_RE.test(actorId)) { + return { ok: false, error: "reviewerLabel and authenticated actorId must be canonical identifiers" }; + } + const reasons = Array.isArray(input.reasons) ? input.reasons.map(String) : []; + if (reasons.some((code) => !SAFE_CODE_RE.test(code))) return { ok: false, error: "decision reason codes are invalid" }; + const decisionKeySha256 = sha256(input.idempotencyKey); + const decisionId = safeStableId("decision", `${candidate.candidateId}\0${decisionKeySha256}`); + const absolute = reviewPath(workspaceRoot, decisionId); + const inputIdentity = { + candidateId: candidate.candidateId, + candidateRecordSha256: candidate.recordSha256, + candidateRevision: candidate.record.revision, + action: input.action, + rationale: input.rationale, + reviewerLabel, + actorId, + confidence, + apply: input.apply === true, + reasons + }; + const inputSha256 = sha256(canonicalize(inputIdentity)); + const logReview = (review) => appendDecisionEvent(workspaceRoot, key, state, { + eventId: `event-${decisionId}`, + occurredAt: review.createdAt, + type: "decision-recorded", + candidateId: candidate.candidateId, + decisionId, + details: reviewDecisionDetails(review) + }, runtime); + if (fs.existsSync(absolute)) { + const loaded = readJsonArtifact(workspaceRoot, absolute, "review"); + if (!loaded.ok) return loaded; + const stored = loaded.record; + if (!validateReviewArtifact(stored, key) || stored.decisionId !== decisionId + || stored.candidateId !== candidate.candidateId + || stored.decisionKeySha256 !== decisionKeySha256 + || stored.inputSha256 !== inputSha256) { + return { ok: false, error: `decision idempotency conflict: ${decisionId}` }; + } + const logged = logReview(stored); + if (!logged.ok) return logged; + return { ok: true, duplicate: true, review: loaded.record }; + } + const previous = latestReview(workspaceRoot, candidate.candidateId, key, state); + const createdAt = new Date().toISOString(); + const review = { + schema: `${CURATOR_SCHEMA}/review`, + decisionId, + candidateId: candidate.candidateId, + createdAt, + inputSha256, + decisionKeySha256, + supersedesDecisionId: previous?.decisionId ?? null, + ...inputIdentity + }; + review.artifactMac = artifactMac(key, review); + try { + atomicWriteFileSync(workspaceRoot, absolute, `${JSON.stringify(review, null, 2)}\n`, { + exclusive: true, + mode: 0o600 + }); + if (runtime.faultAt === "after-review-write") { + throw new Error("injected curator fault after review artifact fsync before decision ledger event"); + } + } catch (error) { + if (String(error.message).startsWith("injected curator fault")) throw error; + return { ok: false, error: `could not record curator review: ${error.message}` }; + } + const logged = logReview(review); + if (!logged.ok) return logged; + return { ok: true, duplicate: false, review }; +} + +function recordReview(workspaceRoot, candidate, key, state, input, runtime = {}) { + const lockAbsolute = path.join(workspaceRoot, CURATOR_ROOT, `review-${candidate.candidateId}.lock`); + let lock; + try { + lock = acquireExclusiveLock(workspaceRoot, lockAbsolute); + } catch (error) { + return { ok: false, error: `candidate review is already being modified: ${error.message}` }; + } + try { + return recordReviewUnlocked(workspaceRoot, candidate, key, state, input, runtime); + } finally { + lock.release(); + } +} + +function recoverExactReviewBoundary(workspaceRoot, candidate, key, state, ledger, input, runtime = {}) { + const exact = exactReviewForInput(workspaceRoot, candidate, key, ledger, input); + if (!exact.ok) return exact; + if (!exact.exists) return { ok: true, handled: false, ledger }; + let current = ledger; + if (!exact.logged) { + try { + verifyIndexWithSingleMissingReview(workspaceRoot, key, current, exact.review); + } catch (error) { + return { ok: false, error: error.message }; + } + const appended = appendDecisionEvent(workspaceRoot, key, state, { + eventId: `event-${exact.review.decisionId}`, + occurredAt: exact.review.createdAt, + type: "decision-recorded", + candidateId: candidate.candidateId, + decisionId: exact.review.decisionId, + details: reviewDecisionDetails(exact.review) + }, runtime); + if (!appended.ok) return appended; + current = readDecisionLedger(workspaceRoot, key, state); + if (!current.ok) return current; + } + return { ok: true, handled: !exact.logged, reviewRecovered: !exact.logged, review: exact.review, ledger: current }; +} + +function findExistingProposal(workspaceRoot, candidate, sourcePrefix = "pam-amf-curator") { + const dir = path.join(workspaceRoot, "memory", "maintenance", "proposals"); + if (!fs.existsSync(dir)) return null; + assertNoSymlinkPath(workspaceRoot, dir, { allowMissing: false }); + const source = `${sourcePrefix}:${candidate.candidateId}`; + const matches = []; + for (const name of fs.readdirSync(dir).sort()) { + if (!name.endsWith(".json")) continue; + const absolute = path.join(dir, name); + if (!fs.lstatSync(absolute).isFile()) throw new Error(`unsafe proposal artifact: ${name}`); + const loaded = readJsonArtifact(workspaceRoot, absolute, "proposal"); + if (!loaded.ok) throw new Error(loaded.error); + if (loaded.record.source === source) matches.push(loaded.record); + } + if (matches.length === 0) return null; + const proposalIds = new Set(matches.map((match) => match.proposalId)); + if (proposalIds.size !== 1) throw new Error(`multiple proposal identities exist for ${candidate.candidateId}`); + for (const match of matches) { + if (match.proposedContentSha256 !== candidate.recordSha256 || match.targetPath !== candidate.targetPath) { + throw new Error("curator proposal identity conflicts with candidate"); + } + } + return matches.find((match) => match.status === "applied") ?? matches[0]; +} + +function listCuratorAppliedArchives(workspaceRoot) { + const dir = path.join(workspaceRoot, "memory", "maintenance", "proposals"); + if (!fs.existsSync(dir)) return []; + assertNoSymlinkPath(workspaceRoot, dir, { allowMissing: false }); + const archives = []; + for (const name of fs.readdirSync(dir).sort()) { + if (!name.endsWith(".applied.json")) continue; + const absolute = path.join(dir, name); + const loaded = readJsonArtifact(workspaceRoot, absolute, "applied proposal archive"); + if (!loaded.ok) throw new Error(loaded.error); + if (typeof loaded.record.source === "string" && loaded.record.source.startsWith("pam-amf-curator:")) { + archives.push(loaded.record); + } + } + return archives; +} + +function assertAppliedArchiveHistory(workspaceRoot, ledger) { + const archives = listCuratorAppliedArchives(workspaceRoot); + const appliedEvents = ledger.events.filter((event) => event.type === "proposal-applied"); + const archiveIds = new Set(archives.map((archive) => archive.proposalId)); + const eventIds = new Set(appliedEvents.map((event) => event.details.proposalId)); + if (archiveIds.size !== archives.length || eventIds.size !== appliedEvents.length + || archiveIds.size !== eventIds.size || [...archiveIds].some((id) => !eventIds.has(id))) { + throw new Error("authenticated ledger and curator applied-archive history differ"); + } + return archives; +} + +function crossCheckLedgerHistory(workspaceRoot, key, ledger) { + const index = loadVerifiedCuratorIndex(workspaceRoot, key, ledger); + assertAppliedArchiveHistory(workspaceRoot, ledger); + const candidates = new Map(index.candidates.map((candidate) => [candidate.candidateId, candidate])); + for (const event of ledger.events.filter((entry) => entry.type === "proposal-recorded")) { + const candidate = candidates.get(event.candidateId); + if (!candidate) throw new Error("proposal ledger event has no authenticated candidate"); + const proposal = findExistingProposal(workspaceRoot, candidate); + const expected = { + proposalId: proposal?.proposalId, + targetRefHmac: hmacSha256(key, `target\0${candidate.targetPath}`), + proposedContentSha256: candidate.recordSha256, + expectedRevision: candidate.targetExists ? candidate.record.revision - 1 : null + }; + if (!proposal || canonicalize(event.details) !== canonicalize(expected)) { + throw new Error("proposal ledger event does not match proposal artifact"); + } + } + for (const event of ledger.events.filter((entry) => entry.type === "proposal-applied")) { + const candidate = candidates.get(event.candidateId); + if (!candidate) throw new Error("applied ledger event has no authenticated candidate"); + const verified = verifyAppliedCandidate(workspaceRoot, key, candidate, event.details.proposalId, event); + if (!verified.ok) throw new Error(verified.error); + } + return index; +} + +function ensureProposal(workspaceRoot, config, candidate, options = {}) { + const sourcePrefix = options.sourcePrefix ?? "pam-amf-curator"; + const existing = findExistingProposal(workspaceRoot, candidate, sourcePrefix); + if (existing) return { ok: true, duplicate: true, proposalId: existing.proposalId }; + const source = `${sourcePrefix}:${candidate.candidateId}`; + const result = candidate.targetExists + ? proposeEdit(workspaceRoot, config, { + path: candidate.targetPath, + rationale: candidate.rationale, + source, + findingIds: [candidate.candidateId], + diff: { kind: "replace", before: candidate.currentContent, after: candidate.recordContent } + }) + : proposeMemoryRecord(workspaceRoot, config, { + content: candidate.recordContent, + rationale: candidate.rationale, + source, + findingIds: [candidate.candidateId] + }); + if (!result.ok) return result; + return { ok: true, duplicate: false, proposalId: result.proposalId, proposalPath: result.proposalPath }; +} + +function verifyAppliedCandidate(workspaceRoot, key, candidate, proposalId, event = null, options = {}) { + const archiveAbsolute = path.join(workspaceRoot, "memory", "maintenance", "proposals", `${proposalId}.applied.json`); + if (!fs.existsSync(archiveAbsolute)) return { ok: false, error: "applied state is missing its proposal archive" }; + let archiveText; + let archive; + try { + archiveText = readFileNoFollowSync(workspaceRoot, archiveAbsolute); + archive = JSON.parse(archiveText); + } catch (error) { + return { ok: false, error: `applied archive is invalid: ${error.message}` }; + } + const expectedSource = `${options.sourcePrefix ?? "pam-amf-curator"}:${candidate.candidateId}`; + const proposedBody = archive?.diff?.kind === "create" ? archive.diff.content : archive?.diff?.after; + const expectedRevision = candidate.targetExists ? candidate.record.revision - 1 : null; + const expectedTargetSha256 = candidate.targetExists ? recordSha256(candidate.currentContent) : null; + if (!isPlainObject(archive) || archive.status !== "applied" || archive.proposalId !== proposalId + || !isTimestamp(archive.appliedAt) + || archive.source !== expectedSource || archive.targetPath !== candidate.targetPath + || archive.proposedContentSha256 !== candidate.recordSha256 + || archive.persistedContentSha256 !== candidate.recordSha256 + || archive.proposedContentLength !== candidate.recordContent.length + || archive.rationale !== candidate.rationale + || canonicalize(archive.findingIds) !== canonicalize([candidate.candidateId]) + || archive.expectedRevision !== expectedRevision + || archive.expectedTargetSha256 !== expectedTargetSha256 + || archive.validation?.schema !== "amf-memory/v1" + || proposedBody !== candidate.recordContent) { + return { ok: false, error: "applied archive identity does not match the authenticated candidate" }; + } + const targetAbsolute = path.join(workspaceRoot, candidate.targetPath); + if (!fs.existsSync(targetAbsolute)) return { ok: false, error: "applied canonical target is missing" }; + let targetContent; + try { + targetContent = readFileNoFollowSync(workspaceRoot, targetAbsolute); + } catch (error) { + return { ok: false, error: `applied canonical target is unsafe: ${error.message}` }; + } + if (recordSha256(targetContent) !== candidate.recordSha256 || targetContent !== candidate.recordContent) { + return { ok: false, error: "applied canonical target hash/content mismatch" }; + } + const validation = validateMemoryRecord(targetContent, { + expectedPath: candidate.targetPath, + workspaceRoot, + resolveSupersedes: false, + checkWorkspaceGraph: false + }); + if (!validation.ok || validation.metadata.id !== candidate.record.id + || validation.metadata.revision !== candidate.record.revision) { + return { ok: false, error: "applied canonical target schema/revision mismatch" }; + } + const appliedArchiveSha256 = sha256(archiveText); + if (event && (event.type !== "proposal-applied" || event.details.proposalId !== proposalId + || event.details.targetRefHmac !== hmacSha256(key, `target\0${candidate.targetPath}`) + || event.details.persistedContentSha256 !== candidate.recordSha256 + || event.details.recordRefHmac !== hmacSha256(key, `record\0${candidate.record.id}`) + || event.details.revision !== candidate.record.revision + || event.details.appliedArchiveSha256 !== appliedArchiveSha256)) { + return { ok: false, error: "applied ledger event does not match archive and canonical target" }; + } + return { ok: true, archive, archiveText, appliedArchiveSha256, validation }; +} + +function candidatePolicyContext(workspaceRoot, candidate) { + const validation = validateMemoryRecord(candidate.recordContent, { + expectedPath: candidate.targetPath, + workspaceRoot, + resolveSupersedes: false, + checkWorkspaceGraph: false + }); + if (!validation.ok || validation.metadata.id !== candidate.record.id + || validation.metadata.revision !== candidate.record.revision) { + throw new Error("policy recovery candidate record/version validation failed"); + } + return { + ...candidate, + summary: candidate.record, + validation, + duplicateExisting: candidate.targetExists === true && candidate.currentContent === candidate.recordContent + }; +} + +function recoverExactPolicyBoundary(workspaceRoot, policy, key, state, candidate, ledger, runtime = {}) { + const decisionKey = policyDecisionKey(policy); + const decisionId = safeStableId("decision", `${candidate.candidateId}\0${sha256(decisionKey)}`); + if (!fs.existsSync(reviewPath(workspaceRoot, decisionId))) { + return { ok: true, handled: false, ledger }; + } + let index; + try { + index = loadPolicyRecoveryIndex(workspaceRoot, key, ledger, candidate.candidateId, decisionId); + } catch (error) { + return { ok: false, error: error.message }; + } + const proposal = ledger.events.find((event) => event.type === "proposal-recorded" + && event.candidateId === candidate.candidateId && event.decisionId === decisionId); + const applied = ledger.events.find((event) => event.type === "proposal-applied" + && event.candidateId === candidate.candidateId && event.decisionId === decisionId); + const archiveAbsolute = proposal + ? path.join(workspaceRoot, "memory", "maintenance", "proposals", `${proposal.details.proposalId}.applied.json`) + : null; + const externalAheadApply = Boolean(proposal && !applied && fs.existsSync(archiveAbsolute)); + if (!index.unloggedReview && !externalAheadApply) { + return { ok: true, handled: false, ledger }; + } + if (!externalAheadApply) { + try { assertAppliedArchiveHistory(workspaceRoot, ledger); } + catch (error) { return { ok: false, error: error.message }; } + } + let context; + let duplicate; + try { + context = candidatePolicyContext(workspaceRoot, candidate); + duplicate = findCandidateDuplicate(workspaceRoot, context, index, { + ignoreCanonicalPath: externalAheadApply ? candidate.targetPath : null + }); + } catch (error) { + return { ok: false, error: error.message }; + } + const evaluation = policyDecision(candidate, duplicate, policy); + let actorId = "service:amf-curator-policy"; + if (evaluation.action === "promote") { + const authorized = authorizeReviewer(policy, runtime, ["memory:curate"]); + if (!authorized.ok) return authorized; + actorId = authorized.actorId; + } + const reviewInput = policyReviewInput(candidate, policy, evaluation, actorId); + const exact = exactReviewForInput(workspaceRoot, candidate, key, ledger, reviewInput); + if (!exact.ok) return exact; + if (!exact.exists || exact.decisionId !== decisionId) { + return { ok: false, error: "policy recovery review does not match the deterministic policy snapshot" }; + } + const recovered = recoverExactReviewBoundary(workspaceRoot, candidate, key, state, ledger, reviewInput, runtime); + if (!recovered.ok) return recovered; + return { + ok: true, + handled: recovered.reviewRecovered === true, + policyRecovery: recovered.reviewRecovered === true, + review: exact.review, + policy: evaluation, + ledger: recovered.ledger ?? readDecisionLedger(workspaceRoot, key, state) + }; +} + +function submitCuratorCandidate(workspaceRoot, config, input, runtime = {}) { + const submitFields = new Set(["content", "rationale", "idempotencyKey", "confidence", "source"]); + if (!exactKeys(input, submitFields)) return { ok: false, error: "submit input contains missing or unknown fields" }; + let policy; + try { + policy = curatorPolicy(config); + } catch (error) { + return { ok: false, error: error.message }; + } + const security = resolveLedgerKey(policy, runtime); + if (!security.ok) return security; + const stateResult = resolveStateContext(workspaceRoot, policy, runtime); + if (!stateResult.ok) return stateResult; + const state = stateResult; + const key = security.key; + const keyError = validateStableKey(input?.idempotencyKey, "idempotencyKey"); + if (keyError) return { ok: false, error: keyError }; + if (typeof input.content !== "string" || Buffer.byteLength(input.content, "utf8") > MAX_RECORD_BYTES) { + return { ok: false, error: `content must be a record no larger than ${MAX_RECORD_BYTES} bytes` }; + } + if (typeof input.rationale !== "string" || input.rationale.trim() === "" + || Buffer.byteLength(input.rationale, "utf8") > MAX_RATIONALE_BYTES) { + return { ok: false, error: `rationale is required and limited to ${MAX_RATIONALE_BYTES} bytes` }; + } + const confidence = normalizeConfidence(input.confidence); + if (confidence === null) return { ok: false, error: "confidence must be between 0 and 1" }; + const source = normalizeSource(input); + if (!source.ok) return source; + ensureCuratorLayout(workspaceRoot); + const earlyKeySha256 = sha256(input.idempotencyKey); + const earlyCandidateId = safeStableId("candidate", earlyKeySha256); + const earlyInputSha256 = sha256(canonicalize({ + recordSha256: recordSha256(input.content), + rationale: input.rationale, + source: source.source, + confidence + })); + const earlyAbsolute = candidatePath(workspaceRoot, earlyCandidateId); + let preflightLedger = readDecisionLedger(workspaceRoot, key, state); + if (!preflightLedger.ok) return { ...preflightLedger, status: "unhealthy", candidates: [] }; + if (fs.existsSync(earlyAbsolute)) { + const loaded = readCandidate(workspaceRoot, earlyCandidateId, key); + if (!loaded.ok) return { ...loaded, status: "unhealthy", candidates: [] }; + if (loaded.record.inputSha256 !== earlyInputSha256 + || loaded.record.recordContent !== input.content + || loaded.record.idempotencyKeySha256 !== earlyKeySha256) { + return { ok: false, error: `candidate idempotency conflict: ${earlyCandidateId}` }; + } + const receivedAlready = preflightLedger.events.some((event) => event.type === "candidate-received" && event.candidateId === earlyCandidateId); + if (!receivedAlready) { + try { + verifyIndexWithSingleMissingReceived(workspaceRoot, key, preflightLedger, earlyCandidateId); + } catch (error) { + return { ok: false, status: "unhealthy", error: error.message, candidates: [] }; + } + const initialization = stateInitializationStatus(workspaceRoot, state, key); + if (!initialization.ok) return { ...initialization, status: "unhealthy", candidates: [] }; + if (!initialization.initialized) { + if (preflightLedger.events.length !== 0 || listCuratorAppliedArchives(workspaceRoot).length !== 0) { + return { ok: false, status: "unhealthy", error: "refusing curator state rebootstrap over existing history", candidates: [] }; + } + const initialized = initializeExternalState(workspaceRoot, state, key); + if (!initialized.ok) return { ...initialized, status: "unhealthy", candidates: [] }; + } + const recoveredReceived = appendDecisionEvent(workspaceRoot, key, state, { + eventId: `event-${earlyCandidateId}-received`, + occurredAt: loaded.record.receivedAt, + type: "candidate-received", + candidateId: earlyCandidateId, + details: candidateReceivedDetails(loaded.record, key) + }, runtime); + if (!recoveredReceived.ok) return recoveredReceived; + preflightLedger = readDecisionLedger(workspaceRoot, key, state); + if (!preflightLedger.ok) return { ...preflightLedger, status: "unhealthy", candidates: [] }; + } + const policyRecovery = recoverExactPolicyBoundary( + workspaceRoot, policy, key, state, loaded.record, preflightLedger, runtime + ); + if (!policyRecovery.ok) { + return { ...policyRecovery, status: "unhealthy", candidates: [] }; + } + preflightLedger = policyRecovery.ledger ?? preflightLedger; + if (!preflightLedger.ok) return { ...preflightLedger, status: "unhealthy", candidates: [] }; + try { + loadVerifiedCuratorIndex(workspaceRoot, key, preflightLedger); + assertAppliedArchiveHistory(workspaceRoot, preflightLedger); + } catch (error) { + return { ok: false, status: "unhealthy", error: error.message, candidates: [] }; + } + if (preflightLedger.events.some((event) => event.candidateId === earlyCandidateId && event.type === "proposal-applied")) { + return { ok: false, error: "legacy curator-applied state requires applicator migration" }; + } + } else { + try { + loadVerifiedCuratorIndex(workspaceRoot, key, preflightLedger); + assertAppliedArchiveHistory(workspaceRoot, preflightLedger); + } catch (error) { + return { ok: false, status: "unhealthy", error: error.message, candidates: [] }; + } + } + let inspected; + try { + inspected = inspectCandidate(workspaceRoot, input.content); + } catch (error) { + return { ok: false, error: error.message }; + } + if (!inspected.ok) return inspected; + const recordConfidence = inspected.summary.confidence.score; + if (confidence !== recordConfidence) { + return { ok: false, error: "candidate confidence must exactly match record.confidence.score" }; + } + const idempotencyKeySha256 = sha256(input.idempotencyKey); + const candidateId = safeStableId("candidate", idempotencyKeySha256); + const absolute = candidatePath(workspaceRoot, candidateId); + const inputIdentity = { + recordSha256: recordSha256(input.content), + rationale: input.rationale, + source: source.source, + confidence: recordConfidence + }; + const inputSha256 = sha256(canonicalize(inputIdentity)); + let candidate; + let duplicateSubmission = false; + if (fs.existsSync(absolute)) { + const loaded = readCandidate(workspaceRoot, candidateId, key); + if (!loaded.ok) return loaded; + if (loaded.record.inputSha256 !== inputSha256 + || loaded.record.recordContent !== input.content + || loaded.record.idempotencyKeySha256 !== idempotencyKeySha256) { + return { ok: false, error: `candidate idempotency conflict: ${candidateId}` }; + } + candidate = loaded.record; + duplicateSubmission = true; + } else { + candidate = { + schema: `${CURATOR_SCHEMA}/candidate`, + candidateId, + receivedAt: new Date().toISOString(), + idempotencyKeySha256, + inputSha256, + recordSha256: inputIdentity.recordSha256, + recordContent: input.content, + rationale: input.rationale, + source: source.source, + confidence: recordConfidence, + targetPath: inspected.targetPath, + targetExists: inspected.targetExists, + currentContent: inspected.currentContent, + changeKind: inspected.changeKind, + semanticFingerprint: inspected.semanticFingerprint, + record: inspected.summary, + validationWarnings: inspected.validation.warnings + }; + candidate.artifactMac = artifactMac(key, candidate); + try { + atomicWriteFileSync(workspaceRoot, absolute, `${JSON.stringify(candidate, null, 2)}\n`, { + exclusive: true, + mode: 0o600 + }); + if (runtime.faultAt === "after-candidate-write") throw new Error("injected curator fault after candidate artifact fsync before first ledger event"); + } catch (error) { + if (String(error.message).startsWith("injected curator fault")) throw error; + if (!fs.existsSync(absolute)) return { ok: false, error: `could not queue curator candidate: ${error.message}` }; + const recovered = readCandidate(workspaceRoot, candidateId, key); + if (!recovered.ok || recovered.record.inputSha256 !== inputSha256 + || recovered.record.recordContent !== input.content + || recovered.record.idempotencyKeySha256 !== idempotencyKeySha256) { + return { ok: false, error: `could not queue curator candidate: ${error.message}` }; + } + candidate = recovered.record; + duplicateSubmission = true; + } + } + const initialization = stateInitializationStatus(workspaceRoot, state, key); + if (!initialization.ok) return { ...initialization, status: "unhealthy", candidates: [] }; + if (!initialization.initialized) { + if (preflightLedger.events.length !== 0 || listCuratorAppliedArchives(workspaceRoot).length !== 0) { + return { ok: false, status: "unhealthy", error: "refusing curator state rebootstrap over existing history", candidates: [] }; + } + const initialized = initializeExternalState(workspaceRoot, state, key); + if (!initialized.ok) return { ...initialized, status: "unhealthy", candidates: [] }; + } + const received = appendDecisionEvent(workspaceRoot, key, state, { + eventId: `event-${candidateId}-received`, + occurredAt: candidate.receivedAt, + type: "candidate-received", + candidateId, + details: candidateReceivedDetails(candidate, key) + }, runtime); + if (!received.ok) return received; + if (duplicateSubmission) { + const ledger = readDecisionLedger(workspaceRoot, key, state); + if (!ledger.ok) return ledger; + if (ledger.events.some((event) => event.candidateId === candidateId && event.type === "proposal-applied")) { + return { ok: false, error: "legacy curator-applied state requires applicator migration" }; + } + const latest = latestReview(workspaceRoot, candidateId, key, state); + if (latest) { + const receiptAbsolute = decisionReceiptPath(workspaceRoot, latest.decisionId); + let receipt; + if (fs.existsSync(receiptAbsolute)) { + const loadedReceipt = readJsonArtifact(workspaceRoot, receiptAbsolute, "decision receipt"); + if (!loadedReceipt.ok || !validateDecisionReceipt(loadedReceipt.record, key, candidate, latest)) { + return { ok: false, status: "unhealthy", error: "existing decision receipt is invalid", candidates: [] }; + } + receipt = loadedReceipt.record; + } else { + const expectedPolicyDecisionId = safeStableId( + "decision", + `${candidate.candidateId}\0${sha256(policyDecisionKey(policy))}` + ); + if (latest.decisionId !== expectedPolicyDecisionId) { + return { ok: false, status: "unhealthy", error: "missing non-policy decision receipt requires exact review retry", candidates: [] }; + } + const ensuredReceipt = ensureDecisionReceipt(workspaceRoot, key, policy, candidate, latest, runtime); + if (!ensuredReceipt.ok) return { ...ensuredReceipt, status: "unhealthy", candidates: [] }; + receipt = ensuredReceipt.receipt; + } + if (receipt.policyDigest !== curatorPolicyDigest(policy)) { + return { ok: false, error: "curator policy changed after the existing decision; a new review is required" }; + } + return { + ok: true, + status: receipt.outcome, + candidateId, + candidatePath: workspaceRelative(workspaceRoot, absolute), + decisionId: latest.decisionId, + decisionDigest: receipt.decisionDigest, + duplicateSubmission: true + }; + } + } + let duplicate; + try { + duplicate = deduplicateCandidate(workspaceRoot, { ...inspected, ...candidate, validation: inspected.validation }, key, state); + } catch (error) { + return { ok: false, status: "unhealthy", error: error.message, candidates: [] }; + } + const evaluation = policyDecision(candidate, duplicate, policy); + let actorId = "service:amf-curator-policy"; + if (evaluation.action === "promote") { + const authorized = authorizeReviewer(policy, runtime, ["memory:curate"]); + if (!authorized.ok) return authorized; + actorId = authorized.actorId; + } + const decision = recordReview( + workspaceRoot, candidate, key, state, policyReviewInput(candidate, policy, evaluation, actorId), runtime + ); + if (!decision.ok) return decision; + const receipt = ensureDecisionReceipt(workspaceRoot, key, policy, candidate, decision.review, runtime); + if (!receipt.ok) return receipt; + return { + ok: true, + status: receipt.receipt.outcome, + candidateId, + candidatePath: workspaceRelative(workspaceRoot, absolute), + decisionId: decision.review.decisionId, + decisionDigest: receipt.receipt.decisionDigest, + duplicateSubmission, + duplicateOf: duplicate, + policy: evaluation + }; +} + +function reviewCuratorCandidate(workspaceRoot, config, input, runtime = {}) { + const allowed = new Set(["candidateId", "action", "rationale", "reviewer", "idempotencyKey", "confidence"]); + const required = new Set(["candidateId", "action", "rationale", "reviewer", "idempotencyKey"]); + if (!exactKeys(input, allowed, required)) return { ok: false, error: "review input contains missing or unknown fields" }; + if (!new Set(["approve", "reject"]).has(input.action)) return { ok: false, error: "manual action must be approve or reject" }; + if (input.confidence !== undefined && normalizeConfidence(input.confidence) === null) return { ok: false, error: "confidence must be between 0 and 1" }; + if (!SAFE_ACTOR_RE.test(String(input.reviewer ?? ""))) return { ok: false, error: "reviewer must be a canonical declarative identifier" }; + if (typeof input.rationale !== "string" || input.rationale.trim() === "" + || Buffer.byteLength(input.rationale, "utf8") > MAX_RATIONALE_BYTES) { + return { ok: false, error: `rationale is required and limited to ${MAX_RATIONALE_BYTES} bytes` }; + } + let policy; + try { policy = curatorPolicy(config); } catch (error) { return { ok: false, error: error.message }; } + const security = resolveLedgerKey(policy, runtime); + if (!security.ok) return security; + const stateResult = resolveStateContext(workspaceRoot, policy, runtime); + if (!stateResult.ok) return stateResult; + const state = stateResult; + const authorized = authorizeReviewer(policy, runtime, ["memory:curate"]); + if (!authorized.ok) return authorized; + ensureCuratorLayout(workspaceRoot); + let ledger = readDecisionLedger(workspaceRoot, security.key, state); + if (!ledger.ok) return ledger; + const loaded = readCandidate(workspaceRoot, input.candidateId, security.key); + if (!loaded.ok) return loaded; + const candidate = loaded.record; + const reviewInput = { + idempotencyKey: input.idempotencyKey, + action: input.action, + rationale: input.rationale, + reviewerLabel: input.reviewer, + actorId: authorized.actorId, + confidence: input.confidence ?? candidate.confidence, + apply: false, + reasons: input.action === "reject" ? ["manual-rejection"] : ["manual-approval"] + }; + const recovered = recoverExactReviewBoundary(workspaceRoot, candidate, security.key, state, ledger, reviewInput, runtime); + if (!recovered.ok) return { ...recovered, status: "unhealthy", candidates: [] }; + ledger = recovered.ledger ?? readDecisionLedger(workspaceRoot, security.key, state); + if (!ledger.ok) return ledger; + try { + loadVerifiedCuratorIndex(workspaceRoot, security.key, ledger); + assertAppliedArchiveHistory(workspaceRoot, ledger); + } catch (error) { + return { ok: false, status: "unhealthy", error: error.message, candidates: [] }; + } + const decision = recordReview(workspaceRoot, candidate, security.key, state, reviewInput, runtime); + if (!decision.ok) return decision; + const receipt = ensureDecisionReceipt(workspaceRoot, security.key, policy, candidate, decision.review, runtime); + if (!receipt.ok) return receipt; + return { + ok: true, + status: receipt.receipt.outcome, + candidateId: candidate.candidateId, + decisionId: decision.review.decisionId, + decisionDigest: receipt.receipt.decisionDigest, + duplicate: decision.duplicate + }; +} + +function curatorStatus(workspaceRoot, config, input = {}, runtime = {}) { + const allowed = new Set(["candidateId"]); + if (!exactKeys(input, allowed, new Set())) return { ok: false, status: "unhealthy", error: "status input contains unknown fields", candidates: [] }; + if (input.candidateId !== undefined && !CANDIDATE_ID_RE.test(String(input.candidateId))) { + return { ok: false, status: "unhealthy", error: "invalid candidateId", candidates: [] }; + } + let policy; + try { policy = curatorPolicy(config); } catch (error) { return { ok: false, status: "unhealthy", error: error.message, candidates: [] }; } + const security = resolveLedgerKey(policy, runtime); + if (!security.ok) return { ...security, status: "unhealthy", candidates: [] }; + const stateResult = resolveStateContext(workspaceRoot, policy, runtime); + if (!stateResult.ok) return { ...stateResult, status: "unhealthy", candidates: [] }; + const state = stateResult; + const ledger = readDecisionLedger(workspaceRoot, security.key, state); + if (!ledger.ok) return { ...ledger, status: "unhealthy", candidates: [] }; + const queueAbsolute = path.join(workspaceRoot, QUEUE_DIR); + let candidates = []; + let reviews = []; + try { + assertAppliedArchiveHistory(workspaceRoot, ledger); + if (fs.existsSync(queueAbsolute)) { + for (const name of fs.readdirSync(queueAbsolute).sort()) { + if (!name.endsWith(".json")) throw new Error(`bogus queue artifact: ${name}`); + const candidateId = name.slice(0, -5); + const loaded = readCandidate(workspaceRoot, candidateId, security.key); + if (!loaded.ok) throw new Error(loaded.error); + candidates.push(loaded.record); + } + } + reviews = listSafeJson(workspaceRoot, REVIEWS_DIR); + const candidateById = new Map(candidates.map((candidate) => [candidate.candidateId, candidate])); + if (reviews.some((review) => { + const candidate = candidateById.get(review.candidateId); + return !candidate || !validateReviewArtifact(review, security.key) + || !reviewMatchesCandidate(review, candidate); + })) throw new Error("review artifact authentication or candidate-version binding failed"); + const receivedEvents = ledger.events.filter((event) => event.type === "candidate-received"); + if (receivedEvents.length !== candidates.length) throw new Error("candidate queue and authenticated ledger cardinality differ"); + for (const event of receivedEvents) { + const candidate = candidateById.get(event.candidateId); + if (!candidate || canonicalize(event.details) !== canonicalize(candidateReceivedDetails(candidate, security.key))) { + throw new Error("candidate queue is not bound to the authenticated ledger"); + } + } + const decisionEvents = ledger.events.filter((event) => event.type === "decision-recorded"); + if (decisionEvents.length !== reviews.length || reviews.some((review) => !reviewMatchesLedger(review, ledger))) { + throw new Error("review artifacts are not bound to the authenticated ledger"); + } + if (ledger.events.some((event) => event.type === "proposal-recorded" || event.type === "proposal-applied")) { + throw new Error("legacy curator apply events require applicator migration"); + } + for (const review of reviews) { + const candidate = candidateById.get(review.candidateId); + const loaded = readJsonArtifact(workspaceRoot, decisionReceiptPath(workspaceRoot, review.decisionId), "decision receipt"); + if (!loaded.ok || !validateDecisionReceipt(loaded.record, security.key, candidate, review)) { + throw new Error(`decision receipt is missing or invalid: ${review.decisionId}`); + } + } + if (input.candidateId) candidates = candidates.filter((candidate) => candidate.candidateId === input.candidateId); + } catch (error) { + return { ok: false, status: "unhealthy", error: error.message, candidates: [] }; + } + return { + ok: true, + status: "healthy", + ledger: { + path: toPosixPath(LEDGER_PATH), + events: ledger.events.length, + headMac: ledger.headMac + }, + candidates: candidates.map((candidate) => { + const candidateReviews = reviews.filter((review) => review.candidateId === candidate.candidateId); + const latest = latestReview(workspaceRoot, candidate.candidateId, security.key, state); + const receipt = latest + ? readJsonArtifact(workspaceRoot, decisionReceiptPath(workspaceRoot, latest.decisionId), "decision receipt").record + : null; + return { + candidateId: candidate.candidateId, + record: redactedRecordSummary(candidate.record), + changeKind: candidate.changeKind, + receivedAt: candidate.receivedAt, + decisions: candidateReviews.length, + latestDecision: latest ? { + decisionId: latest.decisionId, + action: latest.action, + outcome: receipt.outcome, + decisionDigest: receipt.decisionDigest, + actorIdSha256: sha256(latest.actorId), + reviewerLabelSha256: sha256(latest.reviewerLabel) + } : null + }; + }) + }; +} + +function recoverCuratorLedger(workspaceRoot, config, input, runtime = {}) { + if (!isPlainObject(input) || !new Set(["advance-anchor", "recover-review"]).has(input.action)) { + return { ok: false, error: "recovery action must be advance-anchor or recover-review" }; + } + let policy; + try { policy = curatorPolicy(config); } catch (error) { return { ok: false, error: error.message }; } + const security = resolveLedgerKey(policy, runtime); + if (!security.ok) return security; + const state = resolveStateContext(workspaceRoot, policy, runtime); + if (!state.ok) return state; + const authorized = authorizeReviewer(policy, runtime, ["memory:curate"]); + if (!authorized.ok) return authorized; + if (input.action === "recover-review") { + const allowed = new Set([ + "action", "candidateId", "decisionAction", "rationale", "reviewer", + "idempotencyKey", "confidence" + ]); + const required = new Set(["action", "candidateId", "decisionAction", "rationale", "reviewer", "idempotencyKey"]); + if (!exactKeys(input, allowed, required) || !new Set(["approve", "reject"]).has(input.decisionAction) + || (input.confidence !== undefined && normalizeConfidence(input.confidence) === null) + || !SAFE_ACTOR_RE.test(String(input.reviewer ?? ""))) { + return { ok: false, error: "recover-review input is invalid or contains unknown fields" }; + } + const ledger = readDecisionLedger(workspaceRoot, security.key, state); + if (!ledger.ok) return ledger; + const loaded = readCandidate(workspaceRoot, input.candidateId, security.key); + if (!loaded.ok) return loaded; + const reviewInput = { + idempotencyKey: input.idempotencyKey, + action: input.decisionAction, + rationale: input.rationale, + reviewerLabel: input.reviewer, + actorId: authorized.actorId, + confidence: input.confidence ?? loaded.record.confidence, + apply: false, + reasons: input.decisionAction === "reject" ? ["manual-rejection"] : ["manual-approval"] + }; + const exact = exactReviewForInput(workspaceRoot, loaded.record, security.key, ledger, reviewInput); + if (!exact.ok) return exact; + if (!exact.exists || exact.logged) { + return { ok: false, error: "recover-review requires exactly one existing unlogged review artifact" }; + } + const recovered = recoverExactReviewBoundary( + workspaceRoot, loaded.record, security.key, state, ledger, reviewInput, runtime + ); + if (!recovered.ok) return recovered; + const receipt = ensureDecisionReceipt(workspaceRoot, security.key, policy, loaded.record, exact.review, runtime); + if (!receipt.ok) return receipt; + return { + ok: true, + status: "recovered", + action: "recover-review", + recovery: "review-event", + candidateId: loaded.record.candidateId, + decisionId: exact.decisionId, + actorIdSha256: sha256(authorized.actorId) + }; + } + if (!exactKeys(input, new Set(["action"]))) { + return { ok: false, error: "advance-anchor accepts no fields other than action" }; + } + const ledger = readDecisionLedger(workspaceRoot, security.key, state, { allowBehind: true }); + if (!ledger.ok) return ledger; + if (!ledger.anchorBehind) return { ok: false, error: "recovery refused: external anchor is not a strict prefix" }; + try { + crossCheckLedgerHistory(workspaceRoot, security.key, ledger); + } catch (error) { + return { ok: false, error: `recovery cross-check failed: ${error.message}` }; + } + writeLedgerAnchor(state, security.key, ledger.events, ledger.byteLength); + const verified = readDecisionLedger(workspaceRoot, security.key, state); + if (!verified.ok) return verified; + return { + ok: true, + status: "recovered", + action: "advance-anchor", + advancedBy: ledger.events.length - ledger.anchoredSequence, + sequence: verified.events.length, + headMac: verified.headMac, + actorIdSha256: sha256(authorized.actorId) + }; +} + +function loadApprovedDecisionBundle(workspaceRoot, config, input, runtime = {}) { + if (!exactKeys(input, new Set(["decisionId"]))) { + return { ok: false, error: "decision lookup requires exactly decisionId" }; + } + if (!DECISION_ID_RE.test(String(input.decisionId ?? ""))) return { ok: false, error: "decisionId is invalid" }; + let policy; + try { policy = curatorPolicy(config); } catch (error) { return { ok: false, error: error.message }; } + const security = resolveLedgerKey(policy, runtime); + if (!security.ok) return security; + const state = resolveStateContext(workspaceRoot, policy, runtime); + if (!state.ok) return state; + const ledger = readDecisionLedger(workspaceRoot, security.key, state); + if (!ledger.ok) return ledger; + let index; + try { index = loadVerifiedCuratorIndex(workspaceRoot, security.key, ledger); } + catch (error) { return { ok: false, error: error.message }; } + const review = index.reviews.find((entry) => entry.decisionId === input.decisionId); + if (!review) return { ok: false, error: "decision is not authenticated and ledger-bound" }; + const candidate = index.candidates.find((entry) => entry.candidateId === review.candidateId); + if (!candidate) return { ok: false, error: "decision candidate is missing" }; + const latest = latestReview(workspaceRoot, candidate.candidateId, security.key, state); + if (!latest || latest.decisionId !== review.decisionId) { + return { ok: false, error: "decision is superseded and cannot be applied" }; + } + const loaded = readJsonArtifact(workspaceRoot, decisionReceiptPath(workspaceRoot, review.decisionId), "decision receipt"); + if (!loaded.ok || !validateDecisionReceipt(loaded.record, security.key, candidate, review)) { + return { ok: false, error: "decision receipt is missing, altered, or not bound to the candidate" }; + } + if (loaded.record.outcome !== "approved_pending_apply") { + return { ok: false, error: `decision outcome is not applicable: ${loaded.record.outcome}` }; + } + const policyDigestAtApply = curatorPolicyDigest(policy); + if (loaded.record.policyDigest !== policyDigestAtApply) { + return { ok: false, error: "curator policy changed after the decision; a new review is required" }; + } + return { + ok: true, + candidate, + review, + decisionReceipt: loaded.record, + policy, + policyDigestAtApply + }; +} + +function planCuratorGitWrite(config, input = {}) { + const allowed = new Set(["branch", "baseBranch", "remote", "dryRun", "push"]); + if (!exactKeys(input, allowed, new Set(["branch"]))) return { ok: false, error: "git plan input contains missing or unknown fields" }; + let policy; + try { + policy = curatorPolicy(config); + } catch (error) { + return { ok: false, error: error.message }; + } + const writer = policy.gitWriter; + if (writer.enabled !== true) return { ok: false, status: "disabled", error: "curator Git writer is disabled by policy" }; + if (input.dryRun === false || writer.dryRunOnly !== true) { + return { ok: false, error: "curator Git writer supports dry-run planning only in this release" }; + } + if (input.push === true) return { ok: false, error: "curator Git writer refuses direct push" }; + if (input.push !== undefined && typeof input.push !== "boolean") return { ok: false, error: "push must be boolean" }; + if (input.dryRun !== undefined && typeof input.dryRun !== "boolean") return { ok: false, error: "dryRun must be boolean" }; + const branch = String(input.branch ?? ""); + if (!/^[A-Za-z0-9][A-Za-z0-9._/-]{2,127}$/.test(branch) || branch.includes("..")) { + return { ok: false, error: "a safe feature branch is required" }; + } + if (writer.protectedBranches.includes(branch) || /(^|\/)main$/.test(branch)) { + return { ok: false, error: `curator Git writer refuses protected branch: ${branch}` }; + } + for (const [label, value] of [["baseBranch", input.baseBranch ?? "main"], ["remote", input.remote ?? "origin"]]) { + if (typeof value !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._/-]{0,127}$/.test(value) || value.includes("..")) { + return { ok: false, error: `${label} is invalid` }; + } + } + return { + ok: true, + status: "dry-run", + enabled: true, + branch, + baseBranch: input.baseBranch ?? "main", + remote: input.remote ?? "origin", + operations: ["validate-clean-worktree", "stage-curator-owned-paths", "commit-on-feature-branch"], + excludedOperations: ["push", "force-push", "direct-main-write", "merge", "deploy"], + requiresApproval: ["commit", "push", "pull-request"] + }; +} + +export { + CURATOR_ROOT, + CURATOR_SCHEMA, + DEFAULT_POLICY, + appendDecisionEvent, + curatorPolicy, + curatorStatus, + inspectCandidate, + loadApprovedDecisionBundle, + planCuratorGitWrite, + readDecisionLedger, + recoverCuratorLedger, + reviewCuratorCandidate, + submitCuratorCandidate, + ensureProposal as ensureCuratorProposal, + verifyAppliedCandidate +}; diff --git a/tools/lib/memory-receipt-applicator.mjs b/tools/lib/memory-receipt-applicator.mjs new file mode 100644 index 0000000..554fc64 --- /dev/null +++ b/tools/lib/memory-receipt-applicator.mjs @@ -0,0 +1,357 @@ +import crypto from "node:crypto"; +import fs from "node:fs"; +import path from "node:path"; + +import { canonicalize } from "./amf-memory-record.mjs"; +import { applyProposal, proposalArtifactDigest } from "./memory-apply-proposal.mjs"; +import { + ensureCuratorProposal, + loadApprovedDecisionBundle, + verifyAppliedCandidate +} from "./memory-curator.mjs"; +import { + acquireExclusiveLock, + assertNoSymlinkPath, + atomicWriteFileSync, + readFileNoFollowSync +} from "./secure-fs.mjs"; +import { workspaceRelative } from "./workspace.mjs"; + +const APPLICATOR_SCHEMA = "amf-receipt-applicator/v1"; +const APPLICATOR_ROOT = path.join("memory", "amf", "applicator"); +const STATE_DIR = path.join(APPLICATOR_ROOT, "state"); +const OUTBOX_DIR = path.join(APPLICATOR_ROOT, "outbox"); +const HASH_RE = /^[0-9a-f]{64}$/; +const SAFE_ACTOR_RE = /^(?:agent|person|service):[A-Za-z0-9][A-Za-z0-9._-]{2,127}$/; +const PHASES = new Set(["prepared", "pam_applied", "receipt_queued", "fabric_acked"]); +const DEFAULT_APPLICATOR = Object.freeze({ + version: APPLICATOR_SCHEMA, + tokenEnv: "PAM_APPLICATOR_TOKEN", + applicators: [], + transport: { + kind: "disabled", + endpointEnv: "PAM_FABRIC_RECEIPT_ENDPOINT" + } +}); + +function sha256(value) { + return crypto.createHash("sha256").update(String(value), "utf8").digest("hex"); +} + +function hmacSha256(key, value) { + return crypto.createHmac("sha256", key).update(String(value), "utf8").digest("hex"); +} + +function secureDigestEqual(left, right) { + if (!HASH_RE.test(String(left ?? "")) || !HASH_RE.test(String(right ?? ""))) return false; + return crypto.timingSafeEqual(Buffer.from(left, "hex"), Buffer.from(right, "hex")); +} + +function isPlainObject(value) { + return Boolean(value) && typeof value === "object" && !Array.isArray(value); +} + +function exactKeys(value, allowed, required = allowed) { + if (!isPlainObject(value)) return false; + const keys = Object.keys(value); + return keys.every((key) => allowed.has(key)) && [...required].every((key) => Object.hasOwn(value, key)); +} + +function applicatorPolicy(config = {}) { + const configured = isPlainObject(config.amfApplicator) ? config.amfApplicator : {}; + const transport = isPlainObject(configured.transport) ? configured.transport : {}; + const policy = { + ...DEFAULT_APPLICATOR, + ...configured, + applicators: Array.isArray(configured.applicators) ? configured.applicators.map((row) => ({ ...row })) : [], + transport: { ...DEFAULT_APPLICATOR.transport, ...transport } + }; + if (policy.version !== APPLICATOR_SCHEMA) throw new Error(`unsupported applicator policy: ${policy.version}`); + if (typeof policy.tokenEnv !== "string" || !/^[A-Z][A-Z0-9_]{2,63}$/.test(policy.tokenEnv)) { + throw new Error("amfApplicator.tokenEnv is invalid"); + } + for (const actor of policy.applicators) { + if (!exactKeys(actor, new Set(["tokenSha256", "actorId", "capabilities"])) + || !HASH_RE.test(String(actor.tokenSha256 ?? "")) + || !SAFE_ACTOR_RE.test(String(actor.actorId ?? "")) + || !Array.isArray(actor.capabilities) + || actor.capabilities.some((value) => value !== "memory:apply-receipt")) { + throw new Error("amfApplicator.applicators contains an invalid allowlist entry"); + } + } + if (!new Set(["disabled", "http"]).has(policy.transport.kind)) { + throw new Error("amfApplicator.transport.kind must be disabled or http"); + } + if (policy.transport.kind === "http" + && (typeof policy.transport.endpointEnv !== "string" + || !/^[A-Z][A-Z0-9_]{2,63}$/.test(policy.transport.endpointEnv))) { + throw new Error("amfApplicator HTTP endpointEnv is invalid"); + } + return policy; +} + +function authorizeApplicator(policy, runtime = {}) { + const token = runtime.applicatorToken ?? process.env[policy.tokenEnv]; + if (typeof token !== "string" || token.length < 16) { + return { ok: false, error: "memory applicator capability is not configured server-side" }; + } + const digest = sha256(token); + const actor = policy.applicators.find((row) => secureDigestEqual(row.tokenSha256, digest)); + if (!actor || !actor.capabilities.includes("memory:apply-receipt")) { + return { ok: false, error: "memory applicator lacks memory:apply-receipt" }; + } + return { ok: true, actorId: actor.actorId, key: Buffer.from(token, "utf8") }; +} + +function ensureLayout(workspaceRoot) { + const root = path.join(workspaceRoot, APPLICATOR_ROOT); + assertNoSymlinkPath(workspaceRoot, root); + fs.mkdirSync(path.join(workspaceRoot, STATE_DIR), { recursive: true, mode: 0o700 }); + fs.mkdirSync(path.join(workspaceRoot, OUTBOX_DIR), { recursive: true, mode: 0o700 }); + assertNoSymlinkPath(workspaceRoot, root, { allowMissing: false }); + assertNoSymlinkPath(workspaceRoot, path.join(workspaceRoot, STATE_DIR), { allowMissing: false }); + assertNoSymlinkPath(workspaceRoot, path.join(workspaceRoot, OUTBOX_DIR), { allowMissing: false }); +} + +function artifactMac(key, value) { + const copy = { ...value }; + delete copy.artifactMac; + return hmacSha256(key, canonicalize(copy)); +} + +function applyIdFor(decisionId, idempotencyKey) { + return `apply-${sha256(`${APPLICATOR_SCHEMA}\0${decisionId}\0${sha256(idempotencyKey)}`).slice(0, 40)}`; +} + +function statePath(workspaceRoot, applyId) { + return path.join(workspaceRoot, STATE_DIR, `${applyId}.json`); +} + +function outboxPath(workspaceRoot, applyId) { + return path.join(workspaceRoot, OUTBOX_DIR, `${applyId}.json`); +} + +function readJson(workspaceRoot, absolute, label) { + try { + const parsed = JSON.parse(readFileNoFollowSync(workspaceRoot, absolute)); + if (!isPlainObject(parsed)) throw new Error("top-level JSON must be an object"); + return { ok: true, record: parsed }; + } catch (error) { + return { ok: false, error: `${label} is invalid: ${error.message}` }; + } +} + +function validState(state, key) { + return state?.schema === `${APPLICATOR_SCHEMA}/state` + && /^apply-[0-9a-f]{40}$/.test(String(state.applyId ?? "")) + && HASH_RE.test(String(state.inputDigest ?? "")) + && /^decision-[0-9a-f]{40}$/.test(String(state.decisionId ?? "")) + && /^candidate-[0-9a-f]{40}$/.test(String(state.candidateId ?? "")) + && HASH_RE.test(String(state.decisionDigest ?? "")) + && HASH_RE.test(String(state.policyDigestAtApply ?? "")) + && /^[A-Za-z0-9][A-Za-z0-9-]{0,127}$/.test(String(state.proposalId ?? "")) + && HASH_RE.test(String(state.proposalDigest ?? "")) + && PHASES.has(state.phase) + && (state.receipt === null || isPlainObject(state.receipt)) + && (state.ack === null || isPlainObject(state.ack)) + && HASH_RE.test(String(state.artifactMac ?? "")) + && secureDigestEqual(artifactMac(key, state), state.artifactMac); +} + +function writeState(workspaceRoot, key, state) { + const next = { ...state, updatedAt: new Date().toISOString() }; + next.artifactMac = artifactMac(key, next); + atomicWriteFileSync(workspaceRoot, statePath(workspaceRoot, state.applyId), `${JSON.stringify(next, null, 2)}\n`, { mode: 0o600 }); + return next; +} + +function proposalArtifactPath(workspaceRoot, proposalId) { + return path.join(workspaceRoot, "memory", "maintenance", "proposals", `${proposalId}.json`); +} + +function buildReceipt(state, bundle, verified) { + return { + schema: `${APPLICATOR_SCHEMA}/apply-receipt`, + receiptType: "memory_apply_receipt", + applyId: state.applyId, + proposalId: state.proposalId, + decisionId: bundle.decisionReceipt.decisionId, + decisionDigest: bundle.decisionReceipt.decisionDigest, + policyDigestAtApply: state.policyDigestAtApply, + canonicalRecordId: bundle.decisionReceipt.canonicalRecordId, + revision: bundle.decisionReceipt.candidateRevision, + canonicalLifecycleAtDecision: bundle.decisionReceipt.canonicalLifecycleAtDecision, + proposalDigest: state.proposalDigest, + archiveDigest: verified.appliedArchiveSha256, + targetDigest: bundle.candidate.recordSha256, + appliedAt: verified.archive.appliedAt + }; +} + +function writeOutbox(workspaceRoot, key, receipt) { + const absolute = outboxPath(workspaceRoot, receipt.applyId); + const artifact = { ...receipt }; + artifact.artifactMac = artifactMac(key, artifact); + if (fs.existsSync(absolute)) { + const loaded = readJson(workspaceRoot, absolute, "apply receipt outbox"); + if (!loaded.ok || !secureDigestEqual(artifactMac(key, loaded.record), loaded.record.artifactMac) + || canonicalize(loaded.record) !== canonicalize(artifact)) { + return { ok: false, error: "apply receipt outbox conflict" }; + } + return { ok: true, artifact: loaded.record, duplicate: true }; + } + atomicWriteFileSync(workspaceRoot, absolute, `${JSON.stringify(artifact, null, 2)}\n`, { exclusive: true, mode: 0o600 }); + return { ok: true, artifact, duplicate: false }; +} + +function dispatchReceipt(policy, state, runtime = {}) { + if (typeof runtime.transportSink === "function") { + const response = runtime.transportSink(state.receipt); + if (!isPlainObject(response) || response.ok !== true + || typeof response.ackId !== "string" || response.ackId.trim() === "") { + return { ok: false, error: "Fabric receipt sink did not return a durable ack" }; + } + return { ok: true, ack: { ackId: response.ackId, acknowledgedAt: response.acknowledgedAt ?? new Date().toISOString() } }; + } + if (policy.transport.kind === "http") { + const endpoint = process.env[policy.transport.endpointEnv]; + if (typeof endpoint !== "string" || !endpoint.startsWith("https://")) { + return { ok: false, error: "Fabric HTTP receipt endpoint is missing or not HTTPS; receipt remains queued" }; + } + return { ok: false, error: "live HTTP dispatch is disabled in PAM; inject an audited transport sink" }; + } + return { ok: true, queued: true }; +} + +function applyDecisionReceipt(workspaceRoot, config, input, runtime = {}) { + const allowed = new Set(["decisionId", "idempotencyKey", "dispatch"]); + const required = new Set(["decisionId", "idempotencyKey"]); + if (!exactKeys(input, allowed, required) + || !/^decision-[0-9a-f]{40}$/.test(String(input.decisionId ?? "")) + || typeof input.idempotencyKey !== "string" || input.idempotencyKey.length < 8 || input.idempotencyKey.length > 256 + || (input.dispatch !== undefined && typeof input.dispatch !== "boolean")) { + return { ok: false, error: "applicator input is invalid or contains unknown fields" }; + } + let policy; + try { policy = applicatorPolicy(config); } catch (error) { return { ok: false, error: error.message }; } + const authorized = authorizeApplicator(policy, runtime); + if (!authorized.ok) return authorized; + const bundle = loadApprovedDecisionBundle(workspaceRoot, config, { decisionId: input.decisionId }, runtime); + if (!bundle.ok) return bundle; + ensureLayout(workspaceRoot); + const applyId = applyIdFor(input.decisionId, input.idempotencyKey); + const inputDigest = sha256(canonicalize({ + decisionId: input.decisionId, + idempotencyKeySha256: sha256(input.idempotencyKey) + })); + const lockAbsolute = path.join(workspaceRoot, APPLICATOR_ROOT, `${applyId}.lock`); + let lock; + try { lock = acquireExclusiveLock(workspaceRoot, lockAbsolute); } + catch (error) { return { ok: false, error: `applicator is already running: ${error.message}` }; } + try { + let state; + const absolute = statePath(workspaceRoot, applyId); + if (fs.existsSync(absolute)) { + const loaded = readJson(workspaceRoot, absolute, "applicator state"); + if (!loaded.ok || !validState(loaded.record, authorized.key) + || loaded.record.inputDigest !== inputDigest + || loaded.record.decisionId !== input.decisionId + || loaded.record.decisionDigest !== bundle.decisionReceipt.decisionDigest) { + return { ok: false, error: `applicator idempotency or decision conflict: ${applyId}` }; + } + state = loaded.record; + } else { + const proposed = ensureCuratorProposal(workspaceRoot, config, bundle.candidate, { sourcePrefix: "pam-amf-applicator" }); + if (!proposed.ok) return proposed; + const proposalAbsolute = proposalArtifactPath(workspaceRoot, proposed.proposalId); + if (!fs.existsSync(proposalAbsolute)) return { ok: false, error: "prepared proposal artifact is missing" }; + const proposalText = readFileNoFollowSync(workspaceRoot, proposalAbsolute); + let proposalRecord; + try { proposalRecord = JSON.parse(proposalText); } + catch (error) { return { ok: false, error: `prepared proposal is invalid JSON: ${error.message}` }; } + state = writeState(workspaceRoot, authorized.key, { + schema: `${APPLICATOR_SCHEMA}/state`, + applyId, + inputDigest, + decisionId: input.decisionId, + candidateId: bundle.candidate.candidateId, + decisionDigest: bundle.decisionReceipt.decisionDigest, + policyDigestAtApply: bundle.policyDigestAtApply, + proposalId: proposed.proposalId, + proposalDigest: proposalArtifactDigest(proposalRecord), + phase: "prepared", + receipt: null, + ack: null, + updatedAt: new Date().toISOString() + }); + if (runtime.faultAt === "after-prepared") throw new Error("injected applicator fault after prepared state"); + } + + if (state.phase === "prepared") { + const applied = applyProposal(workspaceRoot, config, { proposalId: state.proposalId }, { + expectedProposalDigest: state.proposalDigest, + ...(typeof runtime.onTargetLockAcquired === "function" + ? { onTargetLockAcquired: runtime.onTargetLockAcquired } + : {}) + }); + if (!applied.ok) return { ...applied, applyId, proposalId: state.proposalId }; + if (runtime.faultAt === "after-pam-apply") throw new Error("injected applicator fault after PAM apply"); + const verified = verifyAppliedCandidate( + workspaceRoot, + Buffer.from(runtime.ledgerKey ?? process.env[bundle.policy.ledgerKeyEnv], "utf8"), + bundle.candidate, + state.proposalId, + null, + { sourcePrefix: "pam-amf-applicator" } + ); + if (!verified.ok) return verified; + state = writeState(workspaceRoot, authorized.key, { + ...state, + phase: "pam_applied", + receipt: buildReceipt(state, bundle, verified) + }); + if (runtime.faultAt === "after-pam-applied-state") throw new Error("injected applicator fault after PAM applied state"); + } + + if (state.phase === "pam_applied") { + const queued = writeOutbox(workspaceRoot, authorized.key, state.receipt); + if (!queued.ok) return queued; + state = writeState(workspaceRoot, authorized.key, { ...state, phase: "receipt_queued" }); + if (runtime.faultAt === "after-receipt-queued") throw new Error("injected applicator fault after receipt queued"); + } + + if (state.phase === "receipt_queued" || state.phase === "fabric_acked") { + const verifiedOutbox = writeOutbox(workspaceRoot, authorized.key, state.receipt); + if (!verifiedOutbox.ok) return verifiedOutbox; + } + + if (state.phase === "receipt_queued" && input.dispatch === true) { + const dispatched = dispatchReceipt(policy, state, runtime); + if (!dispatched.ok) return { ...dispatched, applyId, status: "receipt_queued" }; + if (dispatched.queued) return { ok: true, status: "receipt_queued", applyId, proposalId: state.proposalId, receipt: state.receipt }; + if (runtime.faultAt === "after-fabric-ack") throw new Error("injected applicator fault after Fabric ack before state update"); + state = writeState(workspaceRoot, authorized.key, { ...state, phase: "fabric_acked", ack: dispatched.ack }); + } + + return { + ok: true, + status: state.phase, + applyId, + proposalId: state.proposalId, + receipt: state.receipt, + ack: state.ack, + outboxPath: workspaceRelative(workspaceRoot, outboxPath(workspaceRoot, applyId)), + actorIdSha256: sha256(authorized.actorId) + }; + } finally { + lock.release(); + } +} + +export { + APPLICATOR_ROOT, + APPLICATOR_SCHEMA, + DEFAULT_APPLICATOR, + applicatorPolicy, + applyDecisionReceipt +}; diff --git a/tools/memory-curator.mjs b/tools/memory-curator.mjs new file mode 100644 index 0000000..f9c7176 --- /dev/null +++ b/tools/memory-curator.mjs @@ -0,0 +1,79 @@ +#!/usr/bin/env node +import fs from "node:fs"; + +import { + curatorStatus, + planCuratorGitWrite, + recoverCuratorLedger, + reviewCuratorCandidate, + submitCuratorCandidate +} from "./lib/memory-curator.mjs"; +import { applyDecisionReceipt } from "./lib/memory-receipt-applicator.mjs"; +import { DEFAULT_WORKSPACE_ROOT, loadWorkspaceConfig, resolveWorkspaceRoot } from "./lib/workspace.mjs"; + +function usage() { + return `Usage: + node tools/memory-curator.mjs submit --input [--workspace ] + node tools/memory-curator.mjs review --input [--workspace ] + node tools/memory-curator.mjs apply --input [--workspace ] + node tools/memory-curator.mjs status [--candidate-id ] [--workspace ] + node tools/memory-curator.mjs recover --input [--workspace ] + node tools/memory-curator.mjs git-plan --input [--workspace ] + +Input files contain canonical AMF records or review metadata only. RAW transcripts/events are not accepted. +`; +} + +function parseArgs(argv) { + const result = { + command: argv[0] ?? null, + workspace: null, + input: null, + candidateId: null, + help: argv[0] === "--help" || argv[0] === "-h" + }; + for (let index = 1; index < argv.length; index += 1) { + const arg = argv[index]; + const next = argv[index + 1]; + if (arg === "--workspace") { result.workspace = next; index += 1; } + else if (arg === "--input") { result.input = next; index += 1; } + else if (arg === "--candidate-id") { result.candidateId = next; index += 1; } + else if (arg === "--help" || arg === "-h") result.help = true; + else throw new Error(`unknown argument: ${arg}`); + } + return result; +} + +function readInput(filename) { + if (!filename) throw new Error("--input is required"); + const parsed = JSON.parse(fs.readFileSync(filename, "utf8")); + if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("input must be a JSON object"); + return parsed; +} + +function main() { + const args = parseArgs(process.argv.slice(2)); + if (args.help || !args.command) { + process.stdout.write(usage()); + return; + } + const root = args.workspace ? resolveWorkspaceRoot(args.workspace) : DEFAULT_WORKSPACE_ROOT; + const config = loadWorkspaceConfig(root); + let result; + if (args.command === "submit") result = submitCuratorCandidate(root, config, readInput(args.input)); + else if (args.command === "review") result = reviewCuratorCandidate(root, config, readInput(args.input)); + else if (args.command === "apply") result = applyDecisionReceipt(root, config, readInput(args.input)); + else if (args.command === "status") result = curatorStatus(root, config, args.candidateId ? { candidateId: args.candidateId } : {}); + else if (args.command === "recover") result = recoverCuratorLedger(root, config, readInput(args.input)); + else if (args.command === "git-plan") result = planCuratorGitWrite(config, readInput(args.input)); + else throw new Error(`unknown command: ${args.command}`); + process.stdout.write(`${JSON.stringify(result, null, 2)}\n`); + if (!result.ok) process.exitCode = 1; +} + +try { + main(); +} catch (error) { + process.stderr.write(`memory-curator: ${error.message}\n`); + process.exitCode = 1; +} diff --git a/tools/memory-maintenance.config.json b/tools/memory-maintenance.config.json index 7dbd925..b30e2d8 100644 --- a/tools/memory-maintenance.config.json +++ b/tools/memory-maintenance.config.json @@ -50,6 +50,42 @@ } } }, + "amfCurator": { + "version": "amf-curator-policy/v1", + "autoPromote": false, + "minimumConfidence": 0.98, + "autoScopes": [ + "shared" + ], + "autoVisibilities": [ + "shared" + ], + "requireReviewForLifecycleChange": true, + "requireReviewForSupersession": true, + "rejectOnWarnings": true, + "ledgerKeyEnv": "PAM_CURATOR_LEDGER_KEY", + "stateDirEnv": "PAM_CURATOR_STATE_DIR", + "reviewerTokenEnv": "PAM_CURATOR_REVIEWER_TOKEN", + "reviewers": [], + "gitWriter": { + "enabled": false, + "dryRunOnly": true, + "protectedBranches": [ + "main", + "master", + "main-integration" + ] + } + }, + "amfApplicator": { + "version": "amf-receipt-applicator/v1", + "tokenEnv": "PAM_APPLICATOR_TOKEN", + "applicators": [], + "transport": { + "kind": "disabled", + "endpointEnv": "PAM_FABRIC_RECEIPT_ENDPOINT" + } + }, "workspace": { "name": "Example Memory Workspace", "description": "Markdown-based memory workspace maintained by an AI agent.", diff --git a/tools/test-amf-memory-record.mjs b/tools/test-amf-memory-record.mjs index 1cb1123..a4b73f1 100644 --- a/tools/test-amf-memory-record.mjs +++ b/tools/test-amf-memory-record.mjs @@ -31,6 +31,7 @@ function baseRecord(overrides = {}) { claimType: "decision", scope: { type: "shared", id: "shared:global" }, visibility: "shared", + confidence: { score: 0.99, basis: "reviewed", assessedAt: "2026-07-11T10:00:00Z" }, subjects: [{ identityId: IDS.agent, role: "owner" }], claim: { encoding: "plain", text: "A reusable source-backed decision." }, lifecycle: { @@ -108,6 +109,7 @@ test("validates the exact contract-v1 shape, canonical path, and graph projectio assert.equal(validation.ok, true, validation.errors.join("\n")); assert.equal(validation.expectedPath, `memory/amf/records/${IDS.memory}.md`); assert.equal(validation.projection.k, "memory-record"); + assert.equal(validation.projection.c, "high"); assert.match(validation.projection.d, /source-backed decision/); assert.equal(JSON.stringify(validation.projection).includes(IDS.agent), false); @@ -116,6 +118,32 @@ test("validates the exact contract-v1 shape, canonical path, and graph projectio assert.match(legacy.errors.join("\n"), /unknown frontmatter key: scope_kind/); }); +test("requires exact structured confidence with finite score, known basis, and bounded UTC assessment", () => { + const missing = { ...baseRecord() }; + delete missing.confidence; + assert.match(validateMemoryRecord(recordContent(missing)).errors.join("\n"), /missing frontmatter key: confidence/); + + for (const confidence of [ + { score: -0.1, basis: "observed", assessedAt: "2026-07-11T10:00:00Z" }, + { score: 1.1, basis: "observed", assessedAt: "2026-07-11T10:00:00Z" }, + { score: null, basis: "observed", assessedAt: "2026-07-11T10:00:00Z" }, + { score: 0.8, basis: "unknown", assessedAt: "2026-07-11T10:00:00Z" }, + { score: 0.8, basis: "asserted", assessedAt: "2026-07-11T11:00:00Z" }, + { score: 0.8, basis: "asserted", assessedAt: "2026-07-11T10:00:00Z", extra: true } + ]) { + const validation = validateMemoryRecord(recordContent(baseRecord({ confidence }))); + assert.equal(validation.ok, false, JSON.stringify(confidence)); + assert.match(validation.errors.join("\n"), /confidence/); + } + for (const basis of ["observed", "asserted", "inferred", "reviewed"]) { + const validation = validateMemoryRecord(recordContent(baseRecord({ + confidence: { score: 0.5, basis, assessedAt: "2026-07-11T10:00:00Z" } + }))); + assert.equal(validation.ok, true, validation.errors.join("\n")); + assert.equal(validation.projection.c, "medium"); + } +}); + test("seals person and relationship scopes, claim types, and related subjects", () => { for (const overrides of [ { scope: { type: "person", id: IDS.person }, visibility: "private" }, @@ -141,6 +169,11 @@ test("seals person and relationship scopes, claim types, and related subjects", assert.equal(sealed.projection.n, "Protected memory record"); assert.equal(JSON.stringify(sealed.projection).includes(IDS.person), false); assert.equal(JSON.stringify(sealed.projection).includes(metadata.claim.ciphertext), false); + + const restricted = baseRecord({ visibility: "restricted" }); + restricted.claim = sealedClaimFor(restricted); + const restrictedValidation = validateMemoryRecord(recordContent(restricted)); + assert.equal(restrictedValidation.ok, true, restrictedValidation.errors.join("\n")); }); test("validates keyRef, AES-GCM sizes, non-empty ciphertext, and canonical AAD hash", () => { @@ -185,6 +218,13 @@ test("canonical AAD binds algorithm and external key identifiers", () => { assert.equal(rejected.ok, false); assert.match(rejected.errors.join("\n"), /canonical AAD|alg/); } + const confidenceChanged = { + ...metadata, + confidence: { score: 0.5, basis: "reviewed", assessedAt: metadata.confidence.assessedAt } + }; + const rejectedConfidence = validateMemoryRecord(recordContent(confidenceChanged)); + assert.equal(rejectedConfidence.ok, false); + assert.match(rejectedConfidence.errors.join("\n"), /canonical AAD/); }); test("requires real RFC 3339 UTC timestamps", () => { @@ -262,6 +302,32 @@ test("enforces revision, base hash, immutable claim, append-only provenance, and assert.match(errors, /base hash/); }); +test("confidence changes are revision-aware and require a newer assessment", () => { + const current = recordContent(baseRecord()); + const changed = baseRecord({ + revision: 2, + updatedAt: "2026-07-11T11:00:00Z", + confidence: { score: 0.75, basis: "asserted", assessedAt: "2026-07-11T11:00:00Z" }, + provenance: [ + ...baseRecord().provenance, + { + sourceType: "operator-decision", + sourceId: "decision-stable-0002", + eventId: "event-stable-0002", + contentSha256: "b".repeat(64), + capturedAt: "2026-07-11T11:00:00Z" + } + ] + }); + const valid = validateMemoryRecordTransition(current, recordContent(changed)); + assert.equal(valid.ok, true, valid.errors.join("\n")); + + const staleAssessment = { ...changed, confidence: { ...changed.confidence, assessedAt: baseRecord().confidence.assessedAt } }; + const rejected = validateMemoryRecordTransition(current, recordContent(staleAssessment)); + assert.equal(rejected.ok, false); + assert.match(rejected.errors.join("\n"), /strictly newer/); +}); + test("sealed revisions refresh canonical AAD and reject IV reuse or downgrade", () => { const currentMetadata = baseRecord({ scope: { type: "person", id: IDS.person }, @@ -275,6 +341,7 @@ test("sealed revisions refresh canonical AAD and reject IV reuse or downgrade", ...currentMetadata, revision: 2, updatedAt: "2026-07-11T11:00:00Z", + confidence: { score: 0.8, basis: "reviewed", assessedAt: "2026-07-11T11:00:00Z" }, provenance: [ ...currentMetadata.provenance, { @@ -324,6 +391,7 @@ test("resolves every supersedes target through the workspace", () => { const replacementMetadata = baseRecord({ id: IDS.replacement, claim: { encoding: "plain", text: "Corrected source-backed decision." }, + confidence: { score: 0.99, basis: "reviewed", assessedAt: "2026-07-11T12:00:00Z" }, lifecycle: { ...baseRecord().lifecycle, supersedes: [IDS.memory] }, createdAt: "2026-07-11T12:00:00Z", updatedAt: "2026-07-11T12:00:00Z" diff --git a/tools/test-memory-apply-proposal.mjs b/tools/test-memory-apply-proposal.mjs index 4789499..78121f6 100644 --- a/tools/test-memory-apply-proposal.mjs +++ b/tools/test-memory-apply-proposal.mjs @@ -4,7 +4,7 @@ import os from "node:os"; import path from "node:path"; import test from "node:test"; -import { applyProposal } from "./lib/memory-apply-proposal.mjs"; +import { applyProposal, proposalArtifactDigest } from "./lib/memory-apply-proposal.mjs"; import { proposeEdit } from "./lib/memory-proposals.mjs"; function makeWorkspace() { @@ -152,3 +152,52 @@ test("applyProposal applies a unified-diff proposal", () => { const target = fs.readFileSync(path.join(root, "memory", "knowledge-log.md"), "utf8"); assert.ok(target.includes("Five retries per upstream timeout.")); }); + +test("expected proposal digest is checked under the target lock", () => { + const root = makeWorkspace(); + const proposalId = recordProposal(root, { + path: "memory/knowledge-log.md", + rationale: "immutable proposal", + diff: { + kind: "replace", + anchor: { headerLine: "## 2026-04-12 - Worker retries" }, + before: "## 2026-04-12 - Worker retries\n\nFive retries.\n", + after: "## 2026-04-12 - Worker retries\n\nFive immutable retries.\n" + } + }); + const proposalPath = path.join(root, "memory", "maintenance", "proposals", `${proposalId}.json`); + const original = JSON.parse(fs.readFileSync(proposalPath, "utf8")); + const expectedProposalDigest = proposalArtifactDigest(original); + const result = applyProposal(root, defaultConfig(), { proposalId }, { + expectedProposalDigest, + onTargetLockAcquired: () => { + const altered = { ...original, rationale: "valid but altered after preliminary read" }; + fs.writeFileSync(proposalPath, `${JSON.stringify(altered, null, 2)}\n`, "utf8"); + } + }); + assert.equal(result.ok, false); + assert.match(result.error, /changed while acquiring|digest conflict/); + assert.match(fs.readFileSync(path.join(root, "memory", "knowledge-log.md"), "utf8"), /Five retries\./); + assert.equal(fs.existsSync(path.join(root, "memory", "maintenance", "proposals", `${proposalId}.applied.json`)), false); +}); + +test("unchanged expected proposal digest applies and recovers normally", () => { + const root = makeWorkspace(); + const proposalId = recordProposal(root, { + path: "memory/knowledge-log.md", + rationale: "stable digest", + diff: { + kind: "replace", + anchor: { headerLine: "## 2026-04-12 - Worker retries" }, + before: "## 2026-04-12 - Worker retries\n\nFive retries.\n", + after: "## 2026-04-12 - Worker retries\n\nFive stable retries.\n" + } + }); + const proposalPath = path.join(root, "memory", "maintenance", "proposals", `${proposalId}.json`); + const expectedProposalDigest = proposalArtifactDigest(JSON.parse(fs.readFileSync(proposalPath, "utf8"))); + const applied = applyProposal(root, defaultConfig(), { proposalId }, { expectedProposalDigest }); + assert.equal(applied.ok, true, applied.error); + const recovered = applyProposal(root, defaultConfig(), { proposalId }, { expectedProposalDigest }); + assert.equal(recovered.ok, true, recovered.error); + assert.equal(recovered.recovered, true); +}); diff --git a/tools/test-memory-curator.mjs b/tools/test-memory-curator.mjs new file mode 100644 index 0000000..2ad2022 --- /dev/null +++ b/tools/test-memory-curator.mjs @@ -0,0 +1,1144 @@ +import assert from "node:assert/strict"; +import { spawnSync } from "node:child_process"; +import crypto from "node:crypto"; +import fs from "node:fs"; +import os from "node:os"; +import path from "node:path"; +import test from "node:test"; +import { fileURLToPath } from "node:url"; + +import { + appendDecisionEvent, + curatorStatus, + planCuratorGitWrite, + readDecisionLedger, + recoverCuratorLedger, + reviewCuratorCandidate, + submitCuratorCandidate +} from "./lib/memory-curator.mjs"; +import { applyDecisionReceipt } from "./lib/memory-receipt-applicator.mjs"; + +const IDS = { + first: "mem_11111111-1111-4111-8111-111111111111", + second: "mem_99999999-9999-4999-8999-999999999999", + agent: "agent:22222222-2222-4222-8222-222222222222" +}; + +const LEDGER_KEY = "synthetic-ledger-key-material-00000000000000000000000000000001"; +const REVIEWER_TOKEN = "synthetic-reviewer-capability-token-0001"; +const APPLICATOR_TOKEN = "synthetic-applicator-capability-token-0001"; +const STATE_DIR = fs.mkdtempSync(path.join(os.tmpdir(), "pam-curator-state-")); +fs.chmodSync(STATE_DIR, 0o700); +process.env.PAM_CURATOR_LEDGER_KEY = LEDGER_KEY; +process.env.PAM_CURATOR_REVIEWER_TOKEN = REVIEWER_TOKEN; +process.env.PAM_APPLICATOR_TOKEN = APPLICATOR_TOKEN; +process.env.PAM_CURATOR_STATE_DIR = STATE_DIR; +const reviewerTokenSha256 = crypto.createHash("sha256").update(REVIEWER_TOKEN).digest("hex"); +const applicatorTokenSha256 = crypto.createHash("sha256").update(APPLICATOR_TOKEN).digest("hex"); + +const defaultConfig = { + protectedPaths: ["AGENTS.md", "memory/agent-memory", "memory/sources"], + amfCurator: { + version: "amf-curator-policy/v1", + autoPromote: false, + minimumConfidence: 0.98, + autoScopes: ["shared"], + autoVisibilities: ["shared"], + requireReviewForLifecycleChange: true, + requireReviewForSupersession: true, + rejectOnWarnings: true, + ledgerKeyEnv: "PAM_CURATOR_LEDGER_KEY", + stateDirEnv: "PAM_CURATOR_STATE_DIR", + reviewerTokenEnv: "PAM_CURATOR_REVIEWER_TOKEN", + reviewers: [{ + tokenSha256: reviewerTokenSha256, + actorId: "service:synthetic-reviewer", + capabilities: ["memory:curate"] + }], + gitWriter: { enabled: false, dryRunOnly: true, protectedBranches: ["main", "master", "main-integration"] } + }, + amfApplicator: { + version: "amf-receipt-applicator/v1", + tokenEnv: "PAM_APPLICATOR_TOKEN", + applicators: [{ + tokenSha256: applicatorTokenSha256, + actorId: "service:synthetic-applicator", + capabilities: ["memory:apply-receipt"] + }], + transport: { kind: "disabled", endpointEnv: "PAM_FABRIC_RECEIPT_ENDPOINT" } + } +}; + +const ledger = (root) => readDecisionLedger(root, Buffer.from(LEDGER_KEY)); +function statePaths(root, stateDir = STATE_DIR) { + const workspaceId = crypto.createHash("sha256").update(fs.realpathSync(root)).digest("hex"); + return { + root: stateDir, + workspaceId, + anchorPath: path.join(stateDir, `${workspaceId}.anchor.json`), + initializedPath: path.join(stateDir, `${workspaceId}.initialized.json`), + workspaceSentinelPath: path.join(root, "memory/amf/curator.initialized.json") + }; +} + +function workspace() { + const root = fs.mkdtempSync(path.join(os.tmpdir(), "pam-curator-")); + fs.mkdirSync(path.join(root, "memory", "graph"), { recursive: true }); + for (const name of ["nodes.jsonl", "edges.jsonl", "aliases.jsonl"]) { + fs.writeFileSync(path.join(root, "memory", "graph", name), "", "utf8"); + } + return root; +} + +function metadata(overrides = {}) { + return { + schema: "amf-memory/v1", + id: IDS.first, + revision: 1, + claimType: "decision", + scope: { type: "shared", id: "shared:global" }, + visibility: "shared", + confidence: { score: 0.99, basis: "reviewed", assessedAt: "2026-07-11T10:00:00Z" }, + subjects: [{ identityId: IDS.agent, role: "owner" }], + claim: { encoding: "plain", text: "Use deterministic, reviewable memory promotion." }, + lifecycle: { + status: "active", + validFrom: "2026-07-11T10:00:00Z", + validTo: null, + supersedes: [], + revokedAt: null, + revocationReason: null + }, + provenance: [{ + sourceType: "synthetic-test", + sourceId: "session-stable-0001", + eventId: "event-stable-0001", + contentSha256: "a".repeat(64), + capturedAt: "2026-07-11T10:00:00Z" + }], + createdAt: "2026-07-11T10:00:00Z", + updatedAt: "2026-07-11T10:00:00Z", + ...overrides + }; +} + +function render(record, body = "") { + return `---\n${Object.entries(record).map(([key, value]) => { + const rendered = value !== null && typeof value === "object" ? JSON.stringify(value) : String(value); + return `${key}: ${rendered}`; + }).join("\n")}\n---\n${body}`; +} + +function submission(content = render(metadata()), overrides = {}) { + return { + content, + rationale: "Synthetic reviewed candidate.", + idempotencyKey: "synthetic-candidate-key-0001", + confidence: 0.99, + source: { type: "synthetic-test", id: "session-stable-0001" }, + ...overrides + }; +} + +function applyApproved(root, decisionId, idempotencyKey = "synthetic-apply-key-0001", runtime = {}, config = defaultConfig) { + return applyDecisionReceipt(root, config, { decisionId, idempotencyKey }, runtime); +} + +test("default policy queues deterministically, redacts status, and makes retry idempotent", () => { + const root = workspace(); + const first = submitCuratorCandidate(root, defaultConfig, submission()); + assert.equal(first.ok, true, first.error); + assert.equal(first.status, "review_required"); + assert.equal(fs.existsSync(path.join(root, `memory/amf/records/${IDS.first}.md`)), false); + + const again = submitCuratorCandidate(root, defaultConfig, submission()); + assert.equal(again.ok, true, again.error); + assert.equal(again.candidateId, first.candidateId); + assert.equal(again.decisionId, first.decisionId); + assert.equal(again.duplicateSubmission, true); + const ledgerState = ledger(root); + assert.equal(ledgerState.ok, true, ledgerState.error); + assert.equal(ledgerState.events.length, 2); + const ledgerText = fs.readFileSync(path.join(root, "memory/amf/curator/decisions.jsonl"), "utf8"); + assert.equal(ledgerText.includes("deterministic, reviewable"), false); + + const status = curatorStatus(root, defaultConfig); + assert.equal(status.ok, true, status.error); + assert.equal(status.candidates.length, 1); + assert.deepEqual(status.candidates[0].record.confidence, metadata().confidence); + assert.equal(JSON.stringify(status).includes("deterministic, reviewable"), false); + + const conflict = submitCuratorCandidate(root, defaultConfig, submission(render(metadata({ + claim: { encoding: "plain", text: "Different payload under the same key." } + })))); + assert.equal(conflict.ok, false); + assert.match(conflict.error, /idempotency conflict/); +}); + +test("curator derives candidate confidence from the record without granting scope or authority", () => { + const mismatchRoot = workspace(); + const lowRecord = metadata({ + confidence: { score: 0.4, basis: "inferred", assessedAt: "2026-07-11T10:00:00Z" } + }); + const mismatch = submitCuratorCandidate(mismatchRoot, defaultConfig, submission(render(lowRecord), { + confidence: 0.99, + idempotencyKey: "confidence-mismatch-0001" + })); + assert.equal(mismatch.ok, false); + assert.match(mismatch.error, /exactly match record\.confidence\.score/); + + const scopedRoot = workspace(); + const scopedConfig = structuredClone(defaultConfig); + scopedConfig.amfCurator.autoPromote = true; + scopedConfig.amfCurator.autoScopes = ["domain"]; + const scoped = submitCuratorCandidate(scopedRoot, scopedConfig, submission(undefined, { + idempotencyKey: "confidence-cannot-widen-scope-0001" + })); + assert.equal(scoped.ok, true, scoped.error); + assert.equal(scoped.status, "review_required"); + assert.ok(scoped.policy.reasons.includes("scope-requires-review")); + assert.equal(fs.existsSync(path.join(scopedRoot, `memory/amf/records/${IDS.first}.md`)), false); +}); + +test("explicit high-confidence policy approves but cannot bypass the applicator", () => { + const root = workspace(); + const config = structuredClone(defaultConfig); + config.amfCurator.autoPromote = true; + const result = submitCuratorCandidate(root, config, submission()); + assert.equal(result.ok, true, result.error); + assert.equal(result.status, "approved_pending_apply"); + const canonical = path.join(root, `memory/amf/records/${IDS.first}.md`); + assert.equal(fs.existsSync(canonical), false); + const appliedResult = applyApproved(root, result.decisionId, "synthetic-apply-key-0001", {}, config); + assert.equal(appliedResult.ok, true, appliedResult.error); + assert.equal(appliedResult.status, "receipt_queued"); + assert.equal(fs.existsSync(canonical), true); + assert.equal(fs.readFileSync(canonical, "utf8"), submission().content); + const proposalDir = path.join(root, "memory", "maintenance", "proposals"); + const applied = fs.readdirSync(proposalDir).filter((name) => name.endsWith(".applied.json")); + assert.equal(applied.length, 1); + const archive = JSON.parse(fs.readFileSync(path.join(proposalDir, applied[0]), "utf8")); + assert.equal(archive.status, "applied"); + assert.match(archive.source, /^pam-amf-applicator:candidate-/); + const ledgerState = ledger(root); + assert.deepEqual(ledgerState.events.map((event) => event.type), ["candidate-received", "decision-recorded"]); + + const retry = submitCuratorCandidate(root, config, submission()); + assert.equal(retry.ok, true, retry.error); + assert.equal(retry.status, "approved_pending_apply"); + assert.equal(fs.readdirSync(proposalDir).filter((name) => name.endsWith(".applied.json")).length, 1); + assert.equal(ledger(root).events.length, 2); +}); + +test("manual rejection is reversible by a later versioned approval", () => { + const root = workspace(); + const queued = submitCuratorCandidate(root, defaultConfig, submission()); + const rejected = reviewCuratorCandidate(root, defaultConfig, { + candidateId: queued.candidateId, + action: "reject", + rationale: "Evidence needs a human check.", + reviewer: "person:synthetic-reviewer", + idempotencyKey: "manual-reject-0001", + confidence: 0.7 + }); + assert.equal(rejected.ok, true, rejected.error); + assert.equal(rejected.status, "rejected"); + assert.equal(fs.existsSync(path.join(root, `memory/amf/records/${IDS.first}.md`)), false); + + const approved = reviewCuratorCandidate(root, defaultConfig, { + candidateId: queued.candidateId, + action: "approve", + rationale: "Independent evidence was verified.", + reviewer: "person:synthetic-reviewer", + idempotencyKey: "manual-approve-0001", + confidence: 0.99 + }); + assert.equal(approved.ok, true, approved.error); + assert.equal(approved.status, "approved_pending_apply"); + const applied = applyApproved(root, approved.decisionId, "manual-approved-apply-0001"); + assert.equal(applied.ok, true, applied.error); + assert.equal(fs.existsSync(path.join(root, `memory/amf/records/${IDS.first}.md`)), true); + const reviews = fs.readdirSync(path.join(root, "memory/amf/curator/reviews")) + .map((name) => JSON.parse(fs.readFileSync(path.join(root, "memory/amf/curator/reviews", name), "utf8"))); + const approveReview = reviews.find((review) => review.decisionId === approved.decisionId); + assert.equal(approveReview.supersedesDecisionId, rejected.decisionId); + + const retry = reviewCuratorCandidate(root, defaultConfig, { + candidateId: queued.candidateId, + action: "approve", + rationale: "Independent evidence was verified.", + reviewer: "person:synthetic-reviewer", + idempotencyKey: "manual-approve-0001", + confidence: 0.99 + }); + assert.equal(retry.ok, true, retry.error); + assert.equal(retry.decisionId, approved.decisionId); +}); + +test("revoke and superseding correction are proposal-driven and preserve history", () => { + const root = workspace(); + const autoConfig = { ...defaultConfig, amfCurator: { ...defaultConfig.amfCurator, autoPromote: true } }; + const created = submitCuratorCandidate(root, autoConfig, submission()); + assert.equal(created.ok, true, created.error); + assert.equal(applyApproved(root, created.decisionId, "initial-record-apply-0001", {}, autoConfig).ok, true); + + const revokedMetadata = metadata({ + revision: 2, + updatedAt: "2026-07-11T11:00:00Z", + lifecycle: { + ...metadata().lifecycle, + status: "revoked", + revokedAt: "2026-07-11T11:00:00Z", + revocationReason: "The source was corrected." + }, + provenance: [ + ...metadata().provenance, + { + sourceType: "synthetic-review", + sourceId: "review-stable-0002", + eventId: "event-stable-0002", + contentSha256: "b".repeat(64), + capturedAt: "2026-07-11T11:00:00Z" + } + ] + }); + const revokeCandidate = submitCuratorCandidate(root, defaultConfig, submission(render(revokedMetadata), { + idempotencyKey: "synthetic-revoke-key-0001", + source: { type: "synthetic-review", id: "review-stable-0002" } + })); + assert.equal(revokeCandidate.ok, true, revokeCandidate.error); + assert.equal(revokeCandidate.status, "review_required"); + const revoked = reviewCuratorCandidate(root, defaultConfig, { + candidateId: revokeCandidate.candidateId, + action: "approve", + rationale: "Verified correction revokes the old record.", + reviewer: "person:synthetic-reviewer", + idempotencyKey: "approve-revoke-0001" + }); + assert.equal(revoked.ok, true, revoked.error); + assert.equal(applyApproved(root, revoked.decisionId, "revoke-record-apply-0001").ok, true); + const current = fs.readFileSync(path.join(root, `memory/amf/records/${IDS.first}.md`), "utf8"); + assert.match(current, /"status":"revoked"/); + + const corrected = metadata({ + id: IDS.second, + claim: { encoding: "plain", text: "Use reviewed, deterministic memory promotion." }, + confidence: { score: 0.99, basis: "reviewed", assessedAt: "2026-07-11T12:00:00Z" }, + lifecycle: { ...metadata().lifecycle, supersedes: [IDS.first] }, + provenance: [{ + sourceType: "synthetic-review", + sourceId: "review-stable-0003", + eventId: "event-stable-0003", + contentSha256: "c".repeat(64), + capturedAt: "2026-07-11T12:00:00Z" + }], + createdAt: "2026-07-11T12:00:00Z", + updatedAt: "2026-07-11T12:00:00Z" + }); + const correction = submitCuratorCandidate(root, defaultConfig, submission(render(corrected), { + idempotencyKey: "synthetic-correction-key-0001", + source: { type: "synthetic-review", id: "review-stable-0003" } + })); + assert.equal(correction.ok, true, correction.error); + assert.equal(correction.status, "review_required"); + const appliedCorrection = reviewCuratorCandidate(root, defaultConfig, { + candidateId: correction.candidateId, + action: "approve", + rationale: "The correction is source-backed and keeps the revoked record for audit.", + reviewer: "person:synthetic-reviewer", + idempotencyKey: "approve-correction-0001" + }); + assert.equal(appliedCorrection.ok, true, appliedCorrection.error); + assert.equal(applyApproved(root, appliedCorrection.decisionId, "correction-record-apply-0001").ok, true); + assert.equal(fs.existsSync(path.join(root, `memory/amf/records/${IDS.first}.md`)), true); + assert.equal(fs.existsSync(path.join(root, `memory/amf/records/${IDS.second}.md`)), true); +}); + +test("semantic/provenance duplicates are routed without canonical writes", () => { + const root = workspace(); + const config = structuredClone(defaultConfig); + config.amfCurator.autoPromote = true; + const first = submitCuratorCandidate(root, config, submission()); + assert.equal(first.status, "approved_pending_apply"); + assert.equal(applyApproved(root, first.decisionId, "duplicate-seed-apply-0001", {}, config).ok, true); + const sameFact = metadata({ id: IDS.second }); + const duplicate = submitCuratorCandidate(root, config, submission(render(sameFact), { + idempotencyKey: "synthetic-duplicate-key-0001" + })); + assert.equal(duplicate.ok, true, duplicate.error); + assert.equal(duplicate.status, "review_required"); + assert.match(duplicate.duplicateOf.kind, /^canonical-/); + assert.equal(fs.existsSync(path.join(root, `memory/amf/records/${IDS.second}.md`)), false); +}); + +test("ledger detects tampering", () => { + const root = workspace(); + submitCuratorCandidate(root, defaultConfig, submission()); + const ledgerPath = path.join(root, "memory/amf/curator/decisions.jsonl"); + const rows = fs.readFileSync(ledgerPath, "utf8").trim().split("\n").map(JSON.parse); + rows[0].details.recordId = IDS.second; + fs.writeFileSync(ledgerPath, `${rows.map(JSON.stringify).join("\n")}\n`, "utf8"); + const ledgerState = ledger(root); + assert.equal(ledgerState.ok, false); + assert.match(ledgerState.error, /schema|authentication/); + const status = curatorStatus(root, defaultConfig); + assert.equal(status.ok, false); +}); + +test("Git writer is disabled by default and refuses protected branches or push", () => { + assert.equal(planCuratorGitWrite(defaultConfig, { branch: "amf/curated" }).status, "disabled"); + const enabled = structuredClone(defaultConfig); + enabled.amfCurator.gitWriter.enabled = true; + assert.match(planCuratorGitWrite(enabled, { branch: "main" }).error, /protected branch/); + assert.match(planCuratorGitWrite(enabled, { branch: "amf/curated", push: true }).error, /refuses direct push/); + assert.match(planCuratorGitWrite(enabled, { branch: "amf/curated", dryRun: false }).error, /dry-run/); + const plan = planCuratorGitWrite(enabled, { branch: "amf/curated" }); + assert.equal(plan.ok, true); + assert.equal(plan.status, "dry-run"); + assert.ok(plan.excludedOperations.includes("direct-main-write")); +}); + +test("curator rejects RAW-shaped source input and symlinked artifact paths", () => { + const root = workspace(); + const raw = submitCuratorCandidate(root, defaultConfig, submission(undefined, { + source: { type: "synthetic-test", id: "session-stable-0001", transcript: "RAW secret" } + })); + assert.equal(raw.ok, false); + assert.match(raw.error, /RAW payloads/); + + const symlinkRoot = workspace(); + const outside = fs.mkdtempSync(path.join(os.tmpdir(), "pam-curator-outside-")); + fs.mkdirSync(path.join(symlinkRoot, "memory", "amf"), { recursive: true }); + fs.symlinkSync(outside, path.join(symlinkRoot, "memory", "amf", "curator")); + assert.throws(() => submitCuratorCandidate(symlinkRoot, defaultConfig, submission()), /symlink/); +}); + +test("authoritative operations fail closed without the external ledger key", (t) => { + const root = workspace(); + const previous = process.env.PAM_CURATOR_LEDGER_KEY; + delete process.env.PAM_CURATOR_LEDGER_KEY; + t.after(() => { process.env.PAM_CURATOR_LEDGER_KEY = previous; }); + const submitted = submitCuratorCandidate(root, defaultConfig, submission()); + assert.equal(submitted.ok, false); + assert.match(submitted.error, /authoritative curator operation requires/); + assert.equal(fs.existsSync(path.join(root, "memory/amf/curator")), false); + const status = curatorStatus(root, defaultConfig); + assert.equal(status.ok, false); + assert.equal(status.status, "unhealthy"); + assert.deepEqual(status.candidates, []); +}); + +test("ledger HMAC and external anchor detect forgery and suffix truncation", () => { + const forgedRoot = workspace(); + submitCuratorCandidate(forgedRoot, defaultConfig, submission()); + const forgedPath = path.join(forgedRoot, "memory/amf/curator/decisions.jsonl"); + const forgedRows = fs.readFileSync(forgedPath, "utf8").trim().split("\n").map(JSON.parse); + forgedRows[0].details.sourceIdSha256 = "f".repeat(64); + forgedRows[0].eventMac = crypto.createHash("sha256").update(JSON.stringify(forgedRows[0])).digest("hex"); + fs.writeFileSync(forgedPath, `${forgedRows.map(JSON.stringify).join("\n")}\n`, "utf8"); + const forged = ledger(forgedRoot); + assert.equal(forged.ok, false); + assert.match(forged.error, /authentication|schema/); + + const truncatedRoot = workspace(); + submitCuratorCandidate(truncatedRoot, defaultConfig, submission()); + const truncatedPath = path.join(truncatedRoot, "memory/amf/curator/decisions.jsonl"); + const lines = fs.readFileSync(truncatedPath, "utf8").trim().split("\n"); + fs.writeFileSync(truncatedPath, `${lines[0]}\n`, "utf8"); + const truncated = ledger(truncatedRoot); + assert.equal(truncated.ok, false); + assert.match(truncated.error, /truncation|anchor/); +}); + +test("a missing anchor on a non-empty ledger fails closed and is never auto-reanchored", () => { + const root = workspace(); + submitCuratorCandidate(root, defaultConfig, submission()); + const anchorPath = statePaths(root).anchorPath; + fs.rmSync(anchorPath); + assert.equal(curatorStatus(root, defaultConfig).status, "unhealthy"); + const retry = submitCuratorCandidate(root, defaultConfig, submission()); + assert.equal(retry.ok, false); + assert.match(retry.error, /partial|anchor|manual recovery/); + assert.equal(fs.existsSync(anchorPath), false); +}); + +test("status rejects mutated candidate artifacts and returns no candidate data", () => { + const root = workspace(); + const submitted = submitCuratorCandidate(root, defaultConfig, submission()); + const artifactPath = path.join(root, submitted.candidatePath); + const artifact = JSON.parse(fs.readFileSync(artifactPath, "utf8")); + artifact.record.claimType = "RAW-MARKER-FORGED"; + fs.writeFileSync(artifactPath, `${JSON.stringify(artifact, null, 2)}\n`, "utf8"); + const status = curatorStatus(root, defaultConfig); + assert.equal(status.ok, false); + assert.equal(status.status, "unhealthy"); + assert.deepEqual(status.candidates, []); + assert.equal(JSON.stringify(status).includes("RAW-MARKER-FORGED"), false); +}); + +test("applicator receipt binds the exact archive and canonical target", () => { + const root = workspace(); + const queued = submitCuratorCandidate(root, defaultConfig, submission()); + const approved = reviewCuratorCandidate(root, defaultConfig, { + candidateId: queued.candidateId, + action: "approve", + rationale: "The exact record was reviewed.", + reviewer: "person:synthetic-reviewer", + idempotencyKey: "receipt-binding-review-0001" + }); + const applied = applyApproved(root, approved.decisionId, "receipt-binding-apply-0001"); + assert.equal(applied.ok, true, applied.error); + assert.equal(applied.receipt.archiveDigest.length, 64); + assert.equal(applied.receipt.targetDigest, crypto.createHash("sha256").update(submission().content).digest("hex")); + assert.equal(applied.receipt.decisionDigest, approved.decisionDigest); + assert.equal(applied.receipt.canonicalLifecycleAtDecision, "active"); +}); + +test("manual decisions require a server-side allowlisted reviewer capability", (t) => { + const root = workspace(); + const submitted = submitCuratorCandidate(root, defaultConfig, submission()); + const previous = process.env.PAM_CURATOR_REVIEWER_TOKEN; + delete process.env.PAM_CURATOR_REVIEWER_TOKEN; + t.after(() => { process.env.PAM_CURATOR_REVIEWER_TOKEN = previous; }); + const rejected = reviewCuratorCandidate(root, defaultConfig, { + candidateId: submitted.candidateId, + action: "reject", + rationale: "Declarative reviewer text is not authority.", + reviewer: "person:synthetic-reviewer", + idempotencyKey: "unauthorized-review-0001" + }); + assert.equal(rejected.ok, false); + assert.match(rejected.error, /capability/); + assert.equal(curatorStatus(root, defaultConfig, {}, { reviewerToken: previous }).candidates[0].decisions, 1); +}); + +test("curator and applicator credentials cannot substitute for one another", () => { + const root = workspace(); + const submitted = submitCuratorCandidate(root, defaultConfig, submission()); + const wrongCurator = reviewCuratorCandidate(root, defaultConfig, { + candidateId: submitted.candidateId, + action: "approve", + rationale: "Wrong credential must fail.", + reviewer: "person:synthetic-reviewer", + idempotencyKey: "wrong-curator-token-0001" + }, { reviewerToken: APPLICATOR_TOKEN }); + assert.equal(wrongCurator.ok, false); + assert.match(wrongCurator.error, /unauthorized/); + + const approved = reviewCuratorCandidate(root, defaultConfig, { + candidateId: submitted.candidateId, + action: "approve", + rationale: "Correct curator credential approves only.", + reviewer: "person:synthetic-reviewer", + idempotencyKey: "separate-capability-review-0001" + }); + const wrongApplicator = applyDecisionReceipt(root, defaultConfig, { + decisionId: approved.decisionId, + idempotencyKey: "wrong-applicator-token-0001" + }, { applicatorToken: REVIEWER_TOKEN }); + assert.equal(wrongApplicator.ok, false); + assert.match(wrongApplicator.error, /memory:apply-receipt/); +}); + +test("HTTP transport fails closed and preserves the queued receipt", (t) => { + const root = workspace(); + const submitted = submitCuratorCandidate(root, defaultConfig, submission()); + const approved = reviewCuratorCandidate(root, defaultConfig, { + candidateId: submitted.candidateId, + action: "approve", + rationale: "Queue until Fabric transport is audited.", + reviewer: "person:synthetic-reviewer", + idempotencyKey: "http-fail-closed-review-0001" + }); + const config = structuredClone(defaultConfig); + config.amfApplicator.transport.kind = "http"; + const previous = process.env.PAM_FABRIC_RECEIPT_ENDPOINT; + delete process.env.PAM_FABRIC_RECEIPT_ENDPOINT; + t.after(() => { + if (previous === undefined) delete process.env.PAM_FABRIC_RECEIPT_ENDPOINT; + else process.env.PAM_FABRIC_RECEIPT_ENDPOINT = previous; + }); + const input = { decisionId: approved.decisionId, idempotencyKey: "http-fail-closed-apply-0001", dispatch: true }; + const refused = applyDecisionReceipt(root, config, input); + assert.equal(refused.ok, false); + assert.equal(refused.status, "receipt_queued"); + assert.match(refused.error, /missing or not HTTPS/); + const queued = applyDecisionReceipt(root, config, { ...input, dispatch: false }); + assert.equal(queued.ok, true, queued.error); + assert.equal(queued.status, "receipt_queued"); +}); + +test("CLI apply routes an approved decision through the receipt applicator", () => { + const root = workspace(); + const submitted = submitCuratorCandidate(root, defaultConfig, submission(undefined, { + idempotencyKey: "cli-route-candidate-0001" + })); + const approved = reviewCuratorCandidate(root, defaultConfig, { + candidateId: submitted.candidateId, + action: "approve", + rationale: "Exercise CLI applicator routing.", + reviewer: "person:synthetic-reviewer", + idempotencyKey: "cli-route-decision-0001" + }); + fs.mkdirSync(path.join(root, "tools"), { recursive: true }); + const cliConfig = JSON.parse(fs.readFileSync( + fileURLToPath(new URL("./memory-maintenance.config.json", import.meta.url)), + "utf8" + )); + cliConfig.protectedPaths = defaultConfig.protectedPaths; + cliConfig.amfCurator = defaultConfig.amfCurator; + cliConfig.amfApplicator = defaultConfig.amfApplicator; + fs.writeFileSync( + path.join(root, "tools", "memory-maintenance.config.json"), + `${JSON.stringify(cliConfig, null, 2)}\n`, + "utf8" + ); + const inputPath = path.join(root, "application.json"); + fs.writeFileSync(inputPath, `${JSON.stringify({ + decisionId: approved.decisionId, + idempotencyKey: "cli-route-apply-0001" + })}\n`, "utf8"); + const cli = spawnSync(process.execPath, [ + fileURLToPath(new URL("./memory-curator.mjs", import.meta.url)), + "apply", + "--input", + inputPath, + "--workspace", + root + ], { encoding: "utf8", env: process.env }); + assert.equal(cli.status, 0, cli.stderr || cli.stdout); + const result = JSON.parse(cli.stdout); + assert.equal(result.ok, true, result.error); + assert.equal(result.status, "receipt_queued"); + assert.equal(fs.existsSync(path.join(root, `memory/amf/records/${IDS.first}.md`)), true); +}); + +test("ledger and status never expose RAW markers or reviewer/source identifiers", () => { + const marker = "RAW-MARKER-SHOULD-NOT-LEAK"; + const root = workspace(); + const record = metadata({ claim: { encoding: "plain", text: `Shared fact ${marker}.` } }); + const submitted = submitCuratorCandidate(root, defaultConfig, submission(render(record), { + rationale: `Evidence rationale ${marker}`, + source: { type: "synthetic-test", id: `source-${marker}` } + })); + const reviewed = reviewCuratorCandidate(root, defaultConfig, { + candidateId: submitted.candidateId, + action: "reject", + rationale: `Review rationale ${marker}`, + reviewer: "person:synthetic-reviewer", + idempotencyKey: "raw-marker-review-0001" + }); + assert.equal(reviewed.ok, true, reviewed.error); + const ledgerText = fs.readFileSync(path.join(root, "memory/amf/curator/decisions.jsonl"), "utf8"); + const statusText = JSON.stringify(curatorStatus(root, defaultConfig)); + assert.equal(ledgerText.includes(marker), false); + assert.equal(statusText.includes(marker), false); + assert.equal(ledgerText.includes("person:synthetic-reviewer"), false); + assert.equal(ledgerText.includes(`source-${marker}`), false); +}); + +test("curator APIs enforce exact internal argument schemas", () => { + const root = workspace(); + const extraSubmit = submitCuratorCandidate(root, defaultConfig, { ...submission(), rawPayload: "RAW" }); + assert.equal(extraSubmit.ok, false); + assert.match(extraSubmit.error, /unknown fields/); + const submitted = submitCuratorCandidate(root, defaultConfig, submission()); + const extraReview = reviewCuratorCandidate(root, defaultConfig, { + candidateId: submitted.candidateId, + action: "reject", + rationale: "Reject.", + reviewer: "person:synthetic-reviewer", + idempotencyKey: "strict-review-0001", + capabilityToken: REVIEWER_TOKEN + }); + assert.equal(extraReview.ok, false); + assert.match(extraReview.error, /unknown fields/); + assert.equal(curatorStatus(root, defaultConfig, { raw: true }).ok, false); + assert.match(planCuratorGitWrite(defaultConfig, { branch: "amf/test", extra: true }).error, /unknown fields/); + + const state = ledger(root); + const received = state.events.find((event) => event.type === "candidate-received"); + const forgedEvent = appendDecisionEvent(root, Buffer.from(LEDGER_KEY), statePaths(root), { + eventId: "event-forged-extra-0001", + occurredAt: new Date().toISOString(), + type: "candidate-received", + candidateId: submitted.candidateId, + details: { ...received.details, arbitraryText: "RAW" } + }); + assert.equal(forgedEvent.ok, false); + assert.match(forgedEvent.error, /strict schema/); +}); + +test("deleting curator history cannot silently reset decision or applied state", () => { + const config = structuredClone(defaultConfig); + config.amfCurator.autoPromote = true; + + const anchoredRoot = workspace(); + submitCuratorCandidate(anchoredRoot, config, submission()); + fs.rmSync(path.join(anchoredRoot, "memory/amf/curator"), { recursive: true }); + const anchored = curatorStatus(anchoredRoot, config); + assert.equal(anchored.ok, false); + assert.equal(anchored.status, "unhealthy"); + assert.deepEqual(anchored.candidates, []); + assert.match(anchored.error, /truncation|anchor/); + + const archiveRoot = workspace(); + const approved = submitCuratorCandidate(archiveRoot, config, submission()); + assert.equal(applyApproved(archiveRoot, approved.decisionId, "deleted-history-apply-0001", {}, config).ok, true); + fs.rmSync(path.join(archiveRoot, "memory/amf/curator"), { recursive: true }); + const external = statePaths(archiveRoot); + fs.rmSync(external.anchorPath); + fs.rmSync(external.initializedPath); + fs.rmSync(external.workspaceSentinelPath); + const archiveCrossCheck = curatorStatus(archiveRoot, config); + assert.equal(archiveCrossCheck.ok, false); + assert.equal(archiveCrossCheck.status, "unhealthy"); + assert.deepEqual(archiveCrossCheck.candidates, []); + assert.match(archiveCrossCheck.error, /initialized|history|sentinel|anchor|truncation/); + assert.equal(fs.existsSync(path.join(archiveRoot, `memory/amf/records/${IDS.first}.md`)), true); +}); + +test("dedup and status fail closed on unverified queue or review artifacts", () => { + const queueRoot = workspace(); + submitCuratorCandidate(queueRoot, defaultConfig, submission()); + const queuePath = path.join(queueRoot, "memory/amf/curator/queue/candidate-0000000000000000000000000000000000000000.json"); + fs.writeFileSync(queuePath, `${JSON.stringify({ + schema: "amf-curator/v1/candidate", + candidateId: "candidate-0000000000000000000000000000000000000000", + semanticFingerprint: "0".repeat(64), + record: { id: IDS.second } + })}\n`, "utf8"); + const second = metadata({ + id: IDS.second, + claim: { encoding: "plain", text: "A second independently reviewed memory." }, + provenance: [{ + sourceType: "synthetic-test", + sourceId: "session-stable-0002", + eventId: "event-stable-0002", + contentSha256: "b".repeat(64), + capturedAt: "2026-07-11T10:00:00Z" + }] + }); + const dedup = submitCuratorCandidate(queueRoot, defaultConfig, submission(render(second), { + idempotencyKey: "bogus-queue-probe-0001", + source: { type: "synthetic-test", id: "session-stable-0002" } + })); + assert.equal(dedup.ok, false); + assert.equal(dedup.status, "unhealthy"); + assert.match(dedup.error, /artifact|hash|candidateId/); + + const reviewRoot = workspace(); + const submitted = submitCuratorCandidate(reviewRoot, defaultConfig, submission()); + fs.writeFileSync(path.join(reviewRoot, "memory/amf/curator/reviews/decision-0000000000000000000000000000000000000000.json"), `${JSON.stringify({ + schema: "amf-curator/v1/review", + decisionId: "decision-0000000000000000000000000000000000000000", + candidateId: submitted.candidateId, + action: "duplicate" + })}\n`, "utf8"); + const indexed = curatorStatus(reviewRoot, defaultConfig); + assert.equal(indexed.ok, false); + assert.equal(indexed.status, "unhealthy"); + assert.deepEqual(indexed.candidates, []); + assert.match(indexed.error, /review artifact/); + const reviewDedup = submitCuratorCandidate(reviewRoot, defaultConfig, submission(render(second), { + idempotencyKey: "bogus-review-probe-0001", + source: { type: "synthetic-test", id: "session-stable-0002" } + })); + assert.equal(reviewDedup.ok, false); + assert.equal(reviewDedup.status, "unhealthy"); + assert.match(reviewDedup.error, /review artifact/); +}); + +test("all ledger events HMAC record/source refs and enum-classify caller source types", () => { + const marker = "RAWMARKER"; + const recordId = `mem_${marker}_1111111111111111`; + const sourceType = "raw-marker-smuggle"; + const sourceId = `source-${marker}-private-ref`; + const root = workspace(); + const config = structuredClone(defaultConfig); + config.amfCurator.autoPromote = true; + const record = metadata({ + id: recordId, + claim: { encoding: "plain", text: `Shared ${marker} fact.` }, + provenance: [{ + sourceType, + sourceId, + eventId: "event-smuggle-0001", + contentSha256: "d".repeat(64), + capturedAt: "2026-07-11T10:00:00Z" + }] + }); + const promoted = submitCuratorCandidate(root, config, submission(render(record), { + idempotencyKey: "smuggled-ledger-refs-0001", + source: { type: sourceType, id: sourceId } + })); + assert.equal(promoted.ok, true, promoted.error); + assert.equal(promoted.status, "approved_pending_apply"); + const ledgerText = fs.readFileSync(path.join(root, "memory/amf/curator/decisions.jsonl"), "utf8"); + for (const forbidden of [marker, recordId, sourceType, sourceId, "recordId", "sourceType", "targetPath"]) { + assert.equal(ledgerText.includes(forbidden), false, `ledger leaked ${forbidden}`); + } + const events = ledger(root).events; + assert.equal(events[0].details.sourceClass, "other"); + assert.match(events[0].details.recordRefHmac, /^[0-9a-f]{64}$/); + assert.match(events[0].details.sourceRefHmac, /^[0-9a-f]{64}$/); + assert.ok(events.every((event) => !JSON.stringify(event).includes(marker))); +}); + +test("boundary A crash recovers only from the exact MAC-authenticated submitted candidate", () => { + const root = workspace(); + assert.throws( + () => submitCuratorCandidate(root, defaultConfig, submission(), { faultAt: "after-candidate-write" }), + /after candidate artifact fsync/ + ); + assert.equal(curatorStatus(root, defaultConfig).status, "unhealthy"); + const conflict = submitCuratorCandidate(root, defaultConfig, submission(render(metadata({ + claim: { encoding: "plain", text: "Different content under the crashed idempotency key." } + })))); + assert.equal(conflict.ok, false); + assert.match(conflict.error, /idempotency conflict/); + const recovered = submitCuratorCandidate(root, defaultConfig, submission()); + assert.equal(recovered.ok, true, recovered.error); + assert.equal(recovered.status, "review_required"); + assert.equal(ledger(root).events.filter((event) => event.type === "candidate-received").length, 1); +}); + +test("boundary B crash requires admin forward recovery of an existing strict-prefix anchor", () => { + const root = workspace(); + assert.throws( + () => submitCuratorCandidate(root, defaultConfig, submission(), { faultAt: "after-ledger-append" }), + /after ledger append before anchor replace/ + ); + const unhealthy = curatorStatus(root, defaultConfig); + assert.equal(unhealthy.status, "unhealthy"); + assert.match(unhealthy.error, /anchor.*behind/); + const ordinaryRetry = submitCuratorCandidate(root, defaultConfig, submission()); + assert.equal(ordinaryRetry.ok, false); + assert.match(ordinaryRetry.error, /anchor.*behind/); + const recovery = recoverCuratorLedger(root, defaultConfig, { action: "advance-anchor" }); + assert.equal(recovery.ok, true, recovery.error); + assert.equal(recovery.status, "recovered"); + assert.equal(recovery.advancedBy, 1); + const completed = submitCuratorCandidate(root, defaultConfig, submission()); + assert.equal(completed.ok, true, completed.error); + assert.equal(completed.status, "review_required"); + assert.equal(recoverCuratorLedger(root, defaultConfig, { action: "advance-anchor" }).ok, false); +}); + +test("default policy review-fsync boundary converges only under the exact policy snapshot", () => { + const root = workspace(); + assert.throws( + () => submitCuratorCandidate(root, defaultConfig, submission(), { faultAt: "after-review-write" }), + /after review artifact fsync before decision ledger event/ + ); + assert.equal(curatorStatus(root, defaultConfig).status, "unhealthy"); + + const changedPolicy = structuredClone(defaultConfig); + changedPolicy.amfCurator.minimumConfidence = 0.97; + const changedRetry = submitCuratorCandidate(root, changedPolicy, submission()); + assert.equal(changedRetry.ok, false); + assert.equal(changedRetry.status, "unhealthy"); + assert.match(changedRetry.error, /review|policy/); + + const recovered = submitCuratorCandidate(root, defaultConfig, submission()); + assert.equal(recovered.ok, true, recovered.error); + assert.equal(recovered.status, "review_required"); + assert.equal(recovered.duplicateSubmission, true); + const events = ledger(root).events.filter((event) => event.type === "decision-recorded"); + assert.equal(events.length, 1); + assert.equal(events[0].details.action, "review"); + assert.equal(curatorStatus(root, defaultConfig).status, "healthy"); +}); + +test("automatic policy review recovery rejects forged actor, action, and idempotency", () => { + for (const [field, value] of [ + ["actorId", "service:forged-policy-actor"], + ["action", "approve"], + ["decisionKeySha256", "f".repeat(64)] + ]) { + const root = workspace(); + assert.throws( + () => submitCuratorCandidate(root, defaultConfig, submission(), { faultAt: "after-review-write" }), + /after review artifact fsync/ + ); + const reviewFile = path.join( + root, + "memory/amf/curator/reviews", + fs.readdirSync(path.join(root, "memory/amf/curator/reviews"))[0] + ); + const artifact = JSON.parse(fs.readFileSync(reviewFile, "utf8")); + artifact[field] = value; + fs.writeFileSync(reviewFile, `${JSON.stringify(artifact, null, 2)}\n`, "utf8"); + const refused = submitCuratorCandidate(root, defaultConfig, submission()); + assert.equal(refused.ok, false, field); + assert.equal(refused.status, "unhealthy", field); + assert.match(refused.error, /invalid|unlogged|conflict|policy|authentication/, field); + assert.equal(curatorStatus(root, defaultConfig).status, "unhealthy", field); + } +}); + +test("auto-approval review-fsync converges without invoking the applicator", () => { + const config = structuredClone(defaultConfig); + config.amfCurator.autoPromote = true; + + const reviewRoot = workspace(); + assert.throws( + () => submitCuratorCandidate(reviewRoot, config, submission(), { faultAt: "after-review-write" }), + /after review artifact fsync/ + ); + assert.equal(curatorStatus(reviewRoot, config).status, "unhealthy"); + const reviewRecovered = submitCuratorCandidate(reviewRoot, config, submission()); + assert.equal(reviewRecovered.ok, true, reviewRecovered.error); + assert.equal(reviewRecovered.status, "approved_pending_apply"); + assert.equal(reviewRecovered.status, "approved_pending_apply"); + assert.equal(curatorStatus(reviewRoot, config).status, "healthy"); + + assert.equal(fs.existsSync(path.join(reviewRoot, `memory/amf/records/${IDS.first}.md`)), false); +}); + +test("applicator recovers every durable boundary with exact idempotency", () => { + for (const faultAt of ["after-prepared", "after-pam-apply", "after-pam-applied-state", "after-receipt-queued"]) { + const root = workspace(); + const queued = submitCuratorCandidate(root, defaultConfig, submission(undefined, { + idempotencyKey: `candidate-${faultAt}-0001` + })); + const approved = reviewCuratorCandidate(root, defaultConfig, { + candidateId: queued.candidateId, + action: "approve", + rationale: `Approved for ${faultAt}.`, + reviewer: "person:synthetic-reviewer", + idempotencyKey: `decision-${faultAt}-0001` + }); + const applyInput = { decisionId: approved.decisionId, idempotencyKey: `apply-${faultAt}-0001` }; + assert.throws( + () => applyDecisionReceipt(root, defaultConfig, applyInput, { faultAt }), + /injected applicator fault/ + ); + const recovered = applyDecisionReceipt(root, defaultConfig, applyInput); + assert.equal(recovered.ok, true, `${faultAt}: ${recovered.error}`); + assert.equal(recovered.status, "receipt_queued", faultAt); + assert.equal(fs.existsSync(path.join(root, `memory/amf/records/${IDS.first}.md`)), true, faultAt); + assert.equal(fs.readdirSync(path.join(root, "memory/amf/applicator/outbox")).length, 1, faultAt); + } +}); + +test("applicator refuses a valid proposal altered after prepared state", () => { + const root = workspace(); + const queued = submitCuratorCandidate(root, defaultConfig, submission(undefined, { + idempotencyKey: "altered-after-prepared-candidate-0001" + })); + const approved = reviewCuratorCandidate(root, defaultConfig, { + candidateId: queued.candidateId, + action: "approve", + rationale: "Prepared proposal must remain immutable.", + reviewer: "person:synthetic-reviewer", + idempotencyKey: "altered-after-prepared-decision-0001" + }); + const input = { decisionId: approved.decisionId, idempotencyKey: "altered-after-prepared-apply-0001" }; + assert.throws( + () => applyDecisionReceipt(root, defaultConfig, input, { faultAt: "after-prepared" }), + /after prepared state/ + ); + const proposalDir = path.join(root, "memory", "maintenance", "proposals"); + const proposalName = fs.readdirSync(proposalDir).find((name) => /^proposal-.*\.json$/.test(name)); + const proposalPath = path.join(proposalDir, proposalName); + const proposal = JSON.parse(fs.readFileSync(proposalPath, "utf8")); + proposal.rationale = "Valid proposal, altered after the prepared digest."; + fs.writeFileSync(proposalPath, `${JSON.stringify(proposal, null, 2)}\n`, "utf8"); + + const refused = applyDecisionReceipt(root, defaultConfig, input); + assert.equal(refused.ok, false); + assert.match(refused.error, /immutable proposal digest conflict/); + assert.equal(fs.existsSync(path.join(root, `memory/amf/records/${IDS.first}.md`)), false); + assert.equal(fs.readdirSync(proposalDir).some((name) => name.endsWith(".applied.json")), false); +}); + +test("review fsync boundary recovers only the exact authenticated candidate-version decision", () => { + const root = workspace(); + const queued = submitCuratorCandidate(root, defaultConfig, submission()); + const review = { + candidateId: queued.candidateId, + action: "reject", + rationale: "Boundary review was checked independently.", + reviewer: "person:synthetic-reviewer", + idempotencyKey: "review-boundary-reject-0001", + confidence: 0.81 + }; + assert.throws( + () => reviewCuratorCandidate(root, defaultConfig, review, { faultAt: "after-review-write" }), + /after review artifact fsync before decision ledger event/ + ); + const unhealthy = curatorStatus(root, defaultConfig); + assert.equal(unhealthy.ok, false); + assert.equal(unhealthy.status, "unhealthy"); + assert.deepEqual(unhealthy.candidates, []); + assert.match(unhealthy.error, /review/); + + const unrelated = reviewCuratorCandidate(root, defaultConfig, { + ...review, + rationale: "A different decision must not claim the crashed artifact." + }); + assert.equal(unrelated.ok, false); + assert.equal(unrelated.status, "unhealthy"); + assert.match(unrelated.error, /idempotency|candidate-version/); + + const recovered = reviewCuratorCandidate(root, defaultConfig, review); + assert.equal(recovered.ok, true, recovered.error); + assert.equal(recovered.status, "rejected"); + assert.equal(ledger(root).events.filter((event) => event.decisionId === recovered.decisionId).length, 1); + const healthy = curatorStatus(root, defaultConfig); + assert.equal(healthy.ok, true, healthy.error); + assert.equal(healthy.status, "healthy"); + assert.equal(healthy.candidates[0].latestDecision.outcome, "rejected"); +}); + +test("Fabric ack boundary retries through an idempotent injected sink", () => { + const root = workspace(); + const queued = submitCuratorCandidate(root, defaultConfig, submission()); + const review = { + candidateId: queued.candidateId, + action: "approve", + rationale: "The exact candidate and source evidence were verified.", + reviewer: "person:synthetic-reviewer", + idempotencyKey: "apply-boundary-approve-0001", + confidence: 0.99 + }; + const approved = reviewCuratorCandidate(root, defaultConfig, review); + const seen = new Set(); + const sink = (receipt) => { + seen.add(receipt.applyId); + return { ok: true, ackId: `ack-${receipt.applyId}`, acknowledgedAt: "2026-07-12T10:00:00Z" }; + }; + const input = { decisionId: approved.decisionId, idempotencyKey: "fabric-ack-apply-0001", dispatch: true }; + assert.throws( + () => applyDecisionReceipt(root, defaultConfig, input, { transportSink: sink, faultAt: "after-fabric-ack" }), + /after Fabric ack/ + ); + const recovered = applyDecisionReceipt(root, defaultConfig, input, { transportSink: sink }); + assert.equal(recovered.ok, true, recovered.error); + assert.equal(recovered.status, "fabric_acked"); + assert.equal(seen.size, 1); +}); + +test("admin review recovery and applicator outbox reject altered artifacts", () => { + const reviewRoot = workspace(); + const queued = submitCuratorCandidate(reviewRoot, defaultConfig, submission()); + const review = { + candidateId: queued.candidateId, + action: "reject", + rationale: "Admin boundary review is exact.", + reviewer: "person:synthetic-reviewer", + idempotencyKey: "admin-review-boundary-0001", + confidence: 0.76 + }; + assert.throws( + () => reviewCuratorCandidate(reviewRoot, defaultConfig, review, { faultAt: "after-review-write" }), + /after review artifact fsync/ + ); + const repairedReview = recoverCuratorLedger(reviewRoot, defaultConfig, { + action: "recover-review", + candidateId: review.candidateId, + decisionAction: review.action, + rationale: review.rationale, + reviewer: review.reviewer, + idempotencyKey: review.idempotencyKey, + confidence: review.confidence + }); + assert.equal(repairedReview.ok, true, repairedReview.error); + assert.equal(repairedReview.status, "recovered"); + assert.equal(curatorStatus(reviewRoot, defaultConfig).status, "healthy"); + + const forgedReviewRoot = workspace(); + const forgedQueued = submitCuratorCandidate(forgedReviewRoot, defaultConfig, submission()); + const forgedInput = { ...review, candidateId: forgedQueued.candidateId, idempotencyKey: "forged-review-boundary-0001" }; + assert.throws( + () => reviewCuratorCandidate(forgedReviewRoot, defaultConfig, forgedInput, { faultAt: "after-review-write" }), + /after review artifact fsync/ + ); + const reviewFile = fs.readdirSync(path.join(forgedReviewRoot, "memory/amf/curator/reviews")) + .map((name) => path.join(forgedReviewRoot, "memory/amf/curator/reviews", name)) + .find((filename) => JSON.parse(fs.readFileSync(filename, "utf8")).decisionKeySha256 + === crypto.createHash("sha256").update(forgedInput.idempotencyKey).digest("hex")); + const forgedArtifact = JSON.parse(fs.readFileSync(reviewFile, "utf8")); + forgedArtifact.candidateRevision = 999; + fs.writeFileSync(reviewFile, `${JSON.stringify(forgedArtifact, null, 2)}\n`, "utf8"); + const refusedReview = recoverCuratorLedger(forgedReviewRoot, defaultConfig, { + action: "recover-review", + candidateId: forgedInput.candidateId, + decisionAction: forgedInput.action, + rationale: forgedInput.rationale, + reviewer: forgedInput.reviewer, + idempotencyKey: forgedInput.idempotencyKey, + confidence: forgedInput.confidence + }); + assert.equal(refusedReview.ok, false); + assert.match(refusedReview.error, /candidate-version|authentication|conflict/); + assert.equal(curatorStatus(forgedReviewRoot, defaultConfig).status, "unhealthy"); + + const applyRoot = workspace(); + const applyQueued = submitCuratorCandidate(applyRoot, defaultConfig, submission()); + const approved = reviewCuratorCandidate(applyRoot, defaultConfig, { + candidateId: applyQueued.candidateId, + action: "approve", + rationale: "Applicator outbox binding is exact.", + reviewer: "person:synthetic-reviewer", + idempotencyKey: "admin-apply-boundary-0001" + }); + const input = { decisionId: approved.decisionId, idempotencyKey: "admin-apply-run-0001" }; + const applied = applyDecisionReceipt(applyRoot, defaultConfig, input); + assert.equal(applied.ok, true, applied.error); + const outbox = path.join(applyRoot, applied.outboxPath); + const forged = JSON.parse(fs.readFileSync(outbox, "utf8")); + forged.targetDigest = "f".repeat(64); + fs.writeFileSync(outbox, `${JSON.stringify(forged, null, 2)}\n`, "utf8"); + const refused = applyDecisionReceipt(applyRoot, defaultConfig, input); + assert.equal(refused.ok, false); + assert.match(refused.error, /outbox conflict/); +}); + +test("deleting a non-promoted curator tree and its provisioned external state never reboots history", () => { + const root = workspace(); + const isolatedState = fs.mkdtempSync(path.join(os.tmpdir(), "pam-curator-deleted-state-")); + fs.chmodSync(isolatedState, 0o700); + const runtime = { stateDir: isolatedState }; + const submitted = submitCuratorCandidate(root, defaultConfig, submission(), runtime); + assert.equal(submitted.ok, true, submitted.error); + assert.equal(submitted.status, "review_required"); + fs.rmSync(path.join(root, "memory/amf/curator"), { recursive: true }); + fs.rmSync(isolatedState, { recursive: true }); + const status = curatorStatus(root, defaultConfig, {}, runtime); + assert.equal(status.ok, false); + assert.equal(status.status, "unhealthy"); + assert.match(status.error, /not provisioned/); + const retry = submitCuratorCandidate(root, defaultConfig, submission(), runtime); + assert.equal(retry.ok, false); + assert.match(retry.error, /not provisioned/); + assert.equal(fs.existsSync(path.join(root, "memory/amf/curator")), false); +}); + +test("state root must be absolute, external, real, pre-provisioned, and 0700", () => { + const root = workspace(); + const relative = submitCuratorCandidate(root, defaultConfig, submission(), { stateDir: "relative-state" }); + assert.equal(relative.ok, false); + assert.match(relative.error, /absolute provisioned/); + + const inside = path.join(root, "private-state"); + fs.mkdirSync(inside, { mode: 0o700 }); + const inRepo = submitCuratorCandidate(root, defaultConfig, submission(), { stateDir: inside }); + assert.equal(inRepo.ok, false); + assert.match(inRepo.error, /outside the workspace/); + + const permissive = fs.mkdtempSync(path.join(os.tmpdir(), "pam-curator-mode-")); + fs.chmodSync(permissive, 0o755); + const badMode = submitCuratorCandidate(root, defaultConfig, submission(), { stateDir: permissive }); + assert.equal(badMode.ok, false); + assert.match(badMode.error, /0700/); + + const real = fs.mkdtempSync(path.join(os.tmpdir(), "pam-curator-real-state-")); + fs.chmodSync(real, 0o700); + const link = `${real}-link`; + fs.symlinkSync(real, link); + const symlinked = submitCuratorCandidate(root, defaultConfig, submission(), { stateDir: link }); + assert.equal(symlinked.ok, false); + assert.match(symlinked.error, /real 0700|symlink/); +}); diff --git a/tools/test-pam-mcp-server.mjs b/tools/test-pam-mcp-server.mjs index ea97e45..ff1fa2c 100644 --- a/tools/test-pam-mcp-server.mjs +++ b/tools/test-pam-mcp-server.mjs @@ -1,5 +1,6 @@ import assert from "node:assert/strict"; import { spawn } from "node:child_process"; +import crypto from "node:crypto"; import fs from "node:fs"; import os from "node:os"; import path from "node:path"; @@ -9,6 +10,15 @@ import test from "node:test"; const __filename = fileURLToPath(import.meta.url); const __dirname = path.dirname(__filename); const SERVER_PATH = path.join(__dirname, "pam-mcp-server.mjs"); +const CURATOR_LEDGER_KEY = "mcp-ledger-key-material-00000000000000000000000000000000001"; +const CURATOR_REVIEWER_TOKEN = "mcp-reviewer-capability-token-0001"; +const APPLICATOR_TOKEN = "mcp-applicator-capability-token-0001"; +const CURATOR_STATE_DIR = fs.mkdtempSync(path.join(os.tmpdir(), "pam-mcp-curator-state-")); +fs.chmodSync(CURATOR_STATE_DIR, 0o700); +process.env.PAM_CURATOR_LEDGER_KEY = CURATOR_LEDGER_KEY; +process.env.PAM_CURATOR_REVIEWER_TOKEN = CURATOR_REVIEWER_TOKEN; +process.env.PAM_APPLICATOR_TOKEN = APPLICATOR_TOKEN; +process.env.PAM_CURATOR_STATE_DIR = CURATOR_STATE_DIR; function makeWorkspace() { const root = fs.mkdtempSync(path.join(os.tmpdir(), "pam-mcp-e2e-")); @@ -65,7 +75,36 @@ function makeWorkspace() { { source: "memory/conversation-log.md", archiveKey: "conversation-log", activeEntryLimit: 80 } ], readContextPaths: [], - protectedPaths: ["AGENTS.md", "CLAUDE.md", "memory/agent-memory", "memory/sources"] + protectedPaths: ["AGENTS.md", "CLAUDE.md", "memory/agent-memory", "memory/sources"], + amfCurator: { + version: "amf-curator-policy/v1", + autoPromote: false, + minimumConfidence: 0.98, + autoScopes: ["shared"], + autoVisibilities: ["shared"], + requireReviewForLifecycleChange: true, + requireReviewForSupersession: true, + rejectOnWarnings: true, + ledgerKeyEnv: "PAM_CURATOR_LEDGER_KEY", + stateDirEnv: "PAM_CURATOR_STATE_DIR", + reviewerTokenEnv: "PAM_CURATOR_REVIEWER_TOKEN", + reviewers: [{ + tokenSha256: crypto.createHash("sha256").update(CURATOR_REVIEWER_TOKEN).digest("hex"), + actorId: "service:mcp-reviewer", + capabilities: ["memory:curate"] + }], + gitWriter: { enabled: false, dryRunOnly: true, protectedBranches: ["main", "master", "main-integration"] } + }, + amfApplicator: { + version: "amf-receipt-applicator/v1", + tokenEnv: "PAM_APPLICATOR_TOKEN", + applicators: [{ + tokenSha256: crypto.createHash("sha256").update(APPLICATOR_TOKEN).digest("hex"), + actorId: "service:mcp-applicator", + capabilities: ["memory:apply-receipt"] + }], + transport: { kind: "disabled", endpointEnv: "PAM_FABRIC_RECEIPT_ENDPOINT" } + } }, null, 2) + "\n", "utf8" ); @@ -80,6 +119,7 @@ function amfRecordContent() { claimType: "decision", scope: { type: "shared", id: "shared:global" }, visibility: "shared", + confidence: { score: 0.99, basis: "reviewed", assessedAt: "2026-07-11T10:00:00Z" }, subjects: [{ identityId: "agent:22222222-2222-4222-8222-222222222222", role: "owner" }], claim: { encoding: "plain", text: "A portable, source-backed memory record." }, lifecycle: { @@ -179,6 +219,12 @@ test("server responds to initialize + tools/list", async () => { assert.ok(toolNames.includes("memory_propose_edit")); assert.ok(toolNames.includes("memory_record_validate")); assert.ok(toolNames.includes("memory_propose_record")); + assert.ok(toolNames.includes("memory_curator_submit")); + assert.ok(toolNames.includes("memory_curator_review")); + assert.ok(toolNames.includes("memory_curator_status")); + assert.ok(toolNames.includes("memory_curator_git_plan")); + assert.ok(toolNames.includes("memory_curator_recover")); + assert.ok(toolNames.includes("memory_receipt_apply")); assert.ok(toolNames.includes("graph_validate")); }); @@ -265,6 +311,70 @@ test("server validates and records an AMF record proposal without applying it", assert.equal(fs.existsSync(path.join(root, payload.proposalPath)), true); }); +test("server queues and reports a redacted deterministic curator candidate", async () => { + const root = makeWorkspace(); + const content = amfRecordContent(); + const responses = await driveServer(root, [ + { jsonrpc: "2.0", id: 1, method: "initialize", params: {} }, + { + jsonrpc: "2.0", + id: 2, + method: "tools/call", + params: { + name: "memory_curator_submit", + arguments: { + content, + rationale: "Queue a synthetic reviewed record.", + idempotencyKey: "mcp-curator-candidate-0001", + confidence: 0.99, + source: { type: "synthetic-test", id: "session-stable-0001" } + } + } + }, + { + jsonrpc: "2.0", + id: 3, + method: "tools/call", + params: { name: "memory_curator_status", arguments: {} } + } + ]); + const submitted = JSON.parse(responses[1].result.content[0].text); + assert.equal(submitted.ok, true, submitted.error); + assert.equal(submitted.status, "review_required"); + const status = JSON.parse(responses[2].result.content[0].text); + assert.equal(status.ok, true, status.error); + assert.equal(status.candidates.length, 1); + assert.equal(JSON.stringify(status).includes("portable, source-backed"), false); + assert.equal(fs.existsSync(path.join(root, "memory", "amf", "records", "mem_11111111-1111-4111-8111-111111111111.md")), false); +}); + +test("server curator handlers reject unknown arguments even without transport schema enforcement", async () => { + const root = makeWorkspace(); + const responses = await driveServer(root, [ + { jsonrpc: "2.0", id: 1, method: "initialize", params: {} }, + { + jsonrpc: "2.0", + id: 2, + method: "tools/call", + params: { + name: "memory_curator_submit", + arguments: { + content: amfRecordContent(), + rationale: "Must reject the extra field.", + idempotencyKey: "mcp-curator-strict-0001", + confidence: 0.99, + source: { type: "synthetic-test", id: "session-stable-0001" }, + rawPayload: "RAW-MARKER" + } + } + } + ]); + const payload = JSON.parse(responses[1].result.content[0].text); + assert.equal(payload.ok, false); + assert.match(payload.error, /unknown fields/); + assert.equal(fs.existsSync(path.join(root, "memory", "amf", "curator")), false); +}); + test("server returns a safe projection for a canonical AMF record", async () => { const root = makeWorkspace(); const relative = "memory/amf/records/mem_11111111-1111-4111-8111-111111111111.md";