diff --git a/CHANGELOG.md b/CHANGELOG.md index 4f7d28d..78e6344 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,16 @@ ### Added +- PAM 0.6.3 bounded Fabric proposal drain, immutable proposal/digest binding, + authenticated HTTPS decision/apply receipts with separate credentials, + atomic record-index refresh, and verifier-only apply receipt checks. +- Opt-in scoped Git delivery with repository/branch/remote allowlists, exclusive + locking, unrelated-change refusal, commit recovery, and non-forced + fast-forward push. Commit and push remain disabled by default. +- Scope-bound Fabric receipts, starvation-free authenticated replay cursors, + repository/branch/remote/target-bound Git state, and parent-dirfd private-file + reads for config, bearer tokens, and applicator state keys. + - PAM 0.6.2 decision receipts and a separately authorized deterministic applicator with durable apply-receipt outbox and crash recovery. diff --git a/docs/amf-curator.md b/docs/amf-curator.md index 9fb5c28..4c5dafe 100644 --- a/docs/amf-curator.md +++ b/docs/amf-curator.md @@ -77,11 +77,41 @@ 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. +The default inline transport remains disabled. The separate Fabric worker uses +bounded HTTPS requests, forbids redirects, and reads curator/applicator bearer +tokens from distinct owner-owned mode-`0600` files. A failed or ambiguous +request leaves the authenticated outbox queued for exact replay. + +The curator polls metadata-only pages (`limit <= 100`, bounded page count), then +decrypts one exact proposal. `replay-decisions` recovers a crash after a durable +Fabric ACK. Replay scans a bounded circular window and persists an authenticated +cursor, so an ACKed filename prefix cannot starve later queued receipts. The +applicator dispatch command uses only the applicator credential and similarly +retries after an apply ACK without repeating PAM mutation. + +Decision and apply receipts bind `proposalScope` as well as proposal digest. +Fabric re-authorizes that scope against the current curator/applicator ACL before +decrypting or advancing proposal state. + +After apply, PAM atomically updates `memory/amf/record-index.json`. Sensitive +entries carry non-secret `contextRefs`; Fabric derives opaque HMAC tags with its +dedicated routing key and fails closed if either refs or key are unavailable. + +Git delivery is a separate applicator-only gate. It is off by default and +requires an exact repository root, current branch allowlist, exclusive writer +lock, and a worktree containing no changes outside the canonical record and +record index. `git-deliver` commits only those paths. `--push` is explicit, +allows only configured remote names, verifies the remote head is an ancestor, +and uses a normal non-forced push. Failed commits unstage only the scoped paths; +committed/pushed state is authenticated and retryable. +The authenticated state also binds the repository identity, current branch, +remote URL digest and target ref. A retry from another allowlisted branch or +after remote retargeting fails closed. + +External workspace config, Fabric token files and the applicator state-key file +are opened through an owner-owned, non-group/world-writable parent dirfd with +`O_DIRECTORY|O_NOFOLLOW`, then read through `/proc/self/fd`. Both the parent and +the mode-`0600` regular file are checked with `fstat`. ## Configuration @@ -103,6 +133,15 @@ an audited Fabric transport is integrated. "amfApplicator": { "version": "amf-receipt-applicator/v1", "tokenEnv": "PAM_APPLICATOR_TOKEN", + "stateKeyEnv": "PAM_APPLICATOR_STATE_KEY", + "stateKeyFileEnv": "PAM_APPLICATOR_STATE_KEY_FILE", + "recordIndexPath": "memory/amf/record-index.json", + "gitWriter": { + "enabled": false, + "repoRootEnv": "PAM_GIT_WRITER_REPO_ROOT", + "allowedBranches": [], + "push": { "enabled": false, "remote": null, "allowedRemotes": [] } + }, "applicators": [{ "tokenSha256": "", "actorId": "service:memory-applicator", @@ -112,6 +151,12 @@ an audited Fabric transport is integrated. "kind": "disabled", "endpointEnv": "PAM_FABRIC_RECEIPT_ENDPOINT" } + }, + "amfFabricTransport": { + "version": "amf-fabric-transport/v1", + "baseUrlEnv": "PAM_FABRIC_BASE_URL", + "curatorTokenFileEnv": "PAM_FABRIC_CURATOR_TOKEN_FILE", + "applicatorTokenFileEnv": "PAM_FABRIC_APPLICATOR_TOKEN_FILE" } } ``` @@ -128,6 +173,11 @@ 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 +npm run memory:fabric-worker -- drain --limit 10 --max-pages 2 +npm run memory:fabric-worker -- replay-decisions --limit 50 +npm run memory:fabric-worker -- dispatch-apply --decision-id +npm run memory:fabric-worker -- git-deliver --decision-id +npm run memory:fabric-worker -- git-deliver --decision-id --push ``` MCP adds `memory_receipt_apply` alongside `memory_curator_submit`, diff --git a/memory/pam.version.json b/memory/pam.version.json index c061828..2e4cbf2 100644 --- a/memory/pam.version.json +++ b/memory/pam.version.json @@ -1,5 +1,5 @@ { - "pamVersion": "0.6.2", + "pamVersion": "0.6.3", "memoryFormat": "graph-v1", "graphSchemaVersion": "pam-graph-v1", "features": { @@ -28,7 +28,16 @@ "curatorForwardRecovery": true, "curatorDecisionReceipts": true, "separateReceiptApplicator": true, - "durableApplyReceiptOutbox": true + "durableApplyReceiptOutbox": true, + "fabricProposalBinding": true, + "authenticatedHttpsReceiptTransport": true, + "atomicAmfRecordIndex": true, + "applyReceiptVerification": true, + "scopedGitDelivery": true, + "scopeAuthorizedFabricReceipts": true, + "persistentBoundedReceiptReplay": true, + "gitDeliveryContextBinding": true, + "dirfdPrivateFileReads": true }, "updated": "2026-07-12" } diff --git a/migrations/0.6.2-to-0.6.3-fabric-promotion-transport.md b/migrations/0.6.2-to-0.6.3-fabric-promotion-transport.md new file mode 100644 index 0000000..b88f364 --- /dev/null +++ b/migrations/0.6.2-to-0.6.3-fabric-promotion-transport.md @@ -0,0 +1,35 @@ +# PAM 0.6.2 → 0.6.3: Fabric promotion transport + +PAM 0.6.3 binds curator candidates to the immutable Fabric `proposalId` and +canonical proposal digest, adds bounded HTTPS intake/receipt delivery with +separate curator and applicator token files, and maintains +`memory/amf/record-index.json` atomically after apply. + +Receipts bind the canonical proposal scope and digest. Fabric must authorize +that scope against the current actor ACL before reading or advancing a proposal. +Decision replay uses an authenticated persistent cursor and bounded circular +scan so terminal ACK entries cannot starve queued work. + +An opt-in Git adapter can commit only the applied record and index and can push +only when repository, branch, remote, fast-forward ancestry, and explicit +`--push` all pass. It never force-pushes and is disabled by default. +Authenticated Git state binds repository identity, branch, remote URL digest and +target ref; changing any of them requires explicit recovery rather than retry. + +Before enabling automatic promotion: + +1. provision an external owner-only `0600` workspace config with reviewer and + applicator token hashes; +2. provision distinct `0600` Fabric bearer-token files for the curator and + applicator plus a separate applicator state-verification key; + each file's parent directory must be owner-owned and not writable by group or + others because private files are opened through a no-follow parent dirfd; +3. configure an HTTPS Fabric origin and leave redirects disabled; +4. drain one proposal without dispatch, inspect the decision outbox, then + repeat with authenticated dispatch; +5. verify the generated record index and Fabric hot reload before increasing + the bounded page and page-count limits. + +Rollback disables the worker first. Preserve curator/applicator state, outboxes, +canonical records, and the record index. Repoint Fabric to the pre-change +read-only index snapshot; do not delete receipts or rewrite promoted records. diff --git a/package.json b/package.json index 980b4e4..441c84c 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "portable-agent-memory", - "version": "0.6.2", + "version": "0.6.3", "private": false, "description": "Markdown-first portable memory, wiki, and maintenance toolkit for AI agents.", "type": "module", @@ -22,6 +22,7 @@ "memory:index": "node tools/memory-maintenance.mjs index", "memory:synthesis": "node tools/memory-maintenance.mjs synthesis", "memory:curator": "node tools/memory-curator.mjs", + "memory:fabric-worker": "node tools/amf-fabric-worker.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/amf-fabric-worker.mjs b/tools/amf-fabric-worker.mjs new file mode 100644 index 0000000..7013af1 --- /dev/null +++ b/tools/amf-fabric-worker.mjs @@ -0,0 +1,43 @@ +#!/usr/bin/env node +import { + dispatchFabricApplyReceipt, + drainFabricProposals, + intakeFabricProposal, + replayFabricDecisionOutbox +} from "./lib/amf-fabric-transport.mjs"; +import { deliverAppliedMemoryToGit } from "./lib/memory-receipt-applicator.mjs"; +import { loadWorkspaceConfig, resolveWorkspaceRoot } from "./lib/workspace.mjs"; + +function args(argv) { + const result = { command: argv[0], workspace: process.cwd(), proposalId: null, decisionId: null, cursor: null, limit: 50, maxPages: 10, dispatch: false, push: false }; + for (let index = 1; index < argv.length; index += 1) { + const key = argv[index]; const value = argv[index + 1]; + if (key === "--workspace") { result.workspace = value; index += 1; } + else if (key === "--proposal-id") { result.proposalId = value; index += 1; } + else if (key === "--decision-id") { result.decisionId = value; index += 1; } + else if (key === "--cursor") { result.cursor = value; index += 1; } + else if (key === "--limit") { result.limit = Number(value); index += 1; } + else if (key === "--max-pages") { result.maxPages = Number(value); index += 1; } + else if (key === "--dispatch") result.dispatch = true; + else if (key === "--push") result.push = true; + else throw new Error(`unknown argument: ${key}`); + } + return result; +} + +async function main() { + const input = args(process.argv.slice(2)); + const root = resolveWorkspaceRoot(input.workspace); + const config = loadWorkspaceConfig(root); + let result; + if (input.command === "drain") result = await drainFabricProposals(root, config, { limit: input.limit, maxPages: input.maxPages, cursor: input.cursor, dispatch: input.dispatch }); + else if (input.command === "intake") result = await intakeFabricProposal(root, config, { proposalId: input.proposalId, dispatch: input.dispatch }); + else if (input.command === "dispatch-apply") result = await dispatchFabricApplyReceipt(root, config, { decisionId: input.decisionId }); + else if (input.command === "replay-decisions") result = await replayFabricDecisionOutbox(root, config, { limit: input.limit, maxPages: input.maxPages, cursor: input.cursor }); + else if (input.command === "git-deliver") result = deliverAppliedMemoryToGit(root, config, { decisionId: input.decisionId, push: input.push }); + else throw new Error("command must be drain, intake, replay-decisions, dispatch-apply, or git-deliver"); + process.stdout.write(`${JSON.stringify(result, null, 2)}\n`); + if (!result.ok) process.exitCode = 1; +} + +main().catch(error => { process.stderr.write(`amf-fabric-worker: ${error.message}\n`); process.exitCode = 1; }); diff --git a/tools/lib/amf-fabric-transport.mjs b/tools/lib/amf-fabric-transport.mjs new file mode 100644 index 0000000..45bf4af --- /dev/null +++ b/tools/lib/amf-fabric-transport.mjs @@ -0,0 +1,266 @@ +import crypto from "node:crypto"; +import fs from "node:fs"; +import https from "node:https"; +import path from "node:path"; + +import { canonicalize, renderMemoryRecord } from "./amf-memory-record.mjs"; +import { submitCuratorCandidate } from "./memory-curator.mjs"; +import { loadFabricApplyReceiptForDispatch, recordFabricApplyAck } from "./memory-receipt-applicator.mjs"; +import { assertNoSymlinkPath, atomicWriteFileSync, readFileNoFollowSync, readOwnerOnlyFileSync } from "./secure-fs.mjs"; + +const TRANSPORT_SCHEMA = "amf-fabric-transport/v1"; +const HASH_RE = /^[a-f0-9]{64}$/; +const REPLAY_CURSOR_PATH = path.join("memory", "amf", "curator", "fabric-replay-cursor.json"); +const DEFAULT_TRANSPORT = Object.freeze({ + version: TRANSPORT_SCHEMA, + baseUrlEnv: "PAM_FABRIC_BASE_URL", + curatorTokenFileEnv: "PAM_FABRIC_CURATOR_TOKEN_FILE", + applicatorTokenFileEnv: "PAM_FABRIC_APPLICATOR_TOKEN_FILE", + timeoutMs: 10000, + maxResponseBytes: 1024 * 1024 +}); + +function sha256(value) { return crypto.createHash("sha256").update(String(value), "utf8").digest("hex"); } +function hmac(key, value) { return crypto.createHmac("sha256", key).update(canonicalize(value), "utf8").digest("hex"); } +function artifactMac(key, value) { const copy = { ...value }; delete copy.artifactMac; return hmac(key, copy); } +function object(value) { return Boolean(value) && typeof value === "object" && !Array.isArray(value); } +function exact(value, fields) { return object(value) && Object.keys(value).sort().join("\0") === [...fields].sort().join("\0"); } + +function transportPolicy(config = {}) { + const input = object(config.amfFabricTransport) ? config.amfFabricTransport : {}; + const policy = { ...DEFAULT_TRANSPORT, ...input }; + if (policy.version !== TRANSPORT_SCHEMA) throw new Error(`unsupported Fabric transport: ${policy.version}`); + for (const field of ["baseUrlEnv", "curatorTokenFileEnv", "applicatorTokenFileEnv"]) { + if (typeof policy[field] !== "string" || !/^[A-Z][A-Z0-9_]{2,63}$/.test(policy[field])) throw new Error(`amfFabricTransport.${field} is invalid`); + } + if (!Number.isSafeInteger(policy.timeoutMs) || policy.timeoutMs < 100 || policy.timeoutMs > 120000 + || !Number.isSafeInteger(policy.maxResponseBytes) || policy.maxResponseBytes < 1024 || policy.maxResponseBytes > 8 * 1024 * 1024) throw new Error("Fabric transport limits are invalid"); + return policy; +} + +function privateTokenFile(filename) { + const value = readOwnerOnlyFileSync(filename, { label: "Fabric token file", maxBytes: 4096 }).trim(); + if (value.length < 16 || value.length > 4096 || /[\r\n\0]/.test(value)) throw new Error("Fabric token file is invalid"); + return value; +} + +function endpoint(policy, env) { + const raw = env[policy.baseUrlEnv]; + const url = new URL(String(raw || "")); + if (url.protocol !== "https:" || url.username || url.password || url.search || url.hash || !["", "/"].includes(url.pathname)) throw new Error("Fabric base URL must be an HTTPS origin"); + return url; +} + +function nodeRequestJson({ url, method, pathname, token, body, timeoutMs, maxResponseBytes }) { + return new Promise((resolve, reject) => { + let settled = false; + const fail = error => { if (!settled) { settled = true; reject(error); } }; + const succeed = value => { if (!settled) { settled = true; resolve(value); } }; + const encoded = body === undefined ? null : Buffer.from(JSON.stringify(body), "utf8"); + const request = https.request(new URL(pathname, url), { + method, + headers: { + authorization: `Bearer ${token}`, + accept: "application/json", + ...(encoded ? { "content-type": "application/json", "content-length": String(encoded.length) } : {}) + }, + timeout: timeoutMs + }, response => { + const chunks = []; let size = 0; + if (!String(response.headers['content-type'] || '').toLowerCase().startsWith('application/json')) { + response.resume(); fail(new Error("Fabric response content-type is not JSON")); return; + } + response.on("data", chunk => { + size += chunk.length; + if (size > maxResponseBytes) { request.destroy(new Error("Fabric response exceeds configured limit")); return; } + chunks.push(chunk); + }); + response.on("aborted", () => fail(new Error("Fabric response was aborted"))); + response.on("error", fail); + response.on("close", () => { if (!response.complete) fail(new Error("Fabric response closed before completion")); }); + response.on("end", () => { + let parsed; + try { parsed = JSON.parse(Buffer.concat(chunks).toString("utf8")); } catch { fail(new Error("Fabric response is not valid JSON")); return; } + if (response.statusCode >= 300 && response.statusCode < 400) { fail(new Error("Fabric redirects are forbidden")); return; } + if (response.statusCode < 200 || response.statusCode >= 300 || parsed?.ok !== true || !object(parsed.data) || typeof parsed.meta?.requestId !== "string") { + fail(new Error(`Fabric request failed with status ${response.statusCode}`)); return; + } + succeed(parsed); + }); + }); + request.on("timeout", () => request.destroy(new Error("Fabric request timed out"))); + request.on("error", fail); + if (encoded) request.write(encoded); + request.end(); + }); +} + +async function requestFabric(config, role, request, runtime = {}) { + const policy = transportPolicy(config); + const env = runtime.env || process.env; + const tokenFileEnv = role === "curator" ? policy.curatorTokenFileEnv : policy.applicatorTokenFileEnv; + const token = privateTokenFile(env[tokenFileEnv]); + const send = runtime.requestJson || nodeRequestJson; + return send({ url: endpoint(policy, env), token, timeoutMs: policy.timeoutMs, maxResponseBytes: policy.maxResponseBytes, ...request }); +} + +async function listFabricProposals(config, input = {}, runtime = {}) { + const limit = input.limit ?? 50; + if (!Number.isSafeInteger(limit) || limit < 1 || limit > 100 || (input.cursor != null && typeof input.cursor !== "string")) throw new Error("Fabric poll input is invalid"); + const query = new URLSearchParams({ status: "queued", limit: String(limit) }); + if (input.cursor) query.set("cursor", input.cursor); + const response = await requestFabric(config, "curator", { method: "GET", pathname: `/v2/internal/curation/proposals?${query}` }, runtime); + if (!Array.isArray(response.data.items) || response.data.items.length > limit) throw new Error("Fabric proposal page is invalid"); + return response.data; +} + +async function readFabricProposal(config, proposalId, runtime = {}) { + if (typeof proposalId !== "string" || !/^[A-Za-z0-9][A-Za-z0-9-]{0,127}$/.test(proposalId)) throw new Error("Fabric proposalId is invalid"); + const response = await requestFabric(config, "curator", { method: "GET", pathname: `/v2/internal/curation/proposals/${encodeURIComponent(proposalId)}` }, runtime); + const data = response.data; + if (data.proposalId !== proposalId || !["queued", "review", "promoted"].includes(data.status) || !object(data.payload) || !HASH_RE.test(String(data.proposalDigest ?? "")) + || sha256(canonicalize(data.payload)) !== data.proposalDigest) throw new Error("Fabric proposal payload binding is invalid"); + return data; +} + +function outboxKey(config, runtime = {}) { + const envName = config.amfCurator?.ledgerKeyEnv || "PAM_CURATOR_LEDGER_KEY"; + const value = runtime.ledgerKey ?? (runtime.env || process.env)[envName]; + if (typeof value !== "string" || Buffer.byteLength(value, "utf8") < 32) throw new Error("curator ledger key is unavailable for Fabric outbox"); + return Buffer.from(value, "utf8"); +} + +function writeDecisionOutbox(workspaceRoot, config, receipt, ack, runtime = {}) { + const directory = path.join(workspaceRoot, "memory/amf/curator/fabric-outbox"); + assertNoSymlinkPath(workspaceRoot, directory); + fs.mkdirSync(directory, { recursive: true, mode: 0o700 }); + const absolute = path.join(directory, `${receipt.decisionId}.json`); + const value = { schema: `${TRANSPORT_SCHEMA}/decision-outbox`, phase: ack ? "fabric_acked" : "queued", receipt, ack: ack || null }; + const key = outboxKey(config, runtime); + value.artifactMac = artifactMac(key, value); + if (fs.existsSync(absolute)) { + const current = JSON.parse(readFileNoFollowSync(workspaceRoot, absolute)); + if (!HASH_RE.test(String(current.artifactMac ?? "")) || artifactMac(key, current) !== current.artifactMac) throw new Error("Fabric decision outbox authentication failed"); + if (current.phase === "fabric_acked" && canonicalize(current.receipt) === canonicalize(receipt)) return current; + if (current.phase !== "queued" || canonicalize(current.receipt) !== canonicalize(receipt)) throw new Error("Fabric decision outbox conflict"); + } + atomicWriteFileSync(workspaceRoot, absolute, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 }); + return value; +} + +async function postReceipt(config, role, receipt, runtime = {}) { + const response = await requestFabric(config, role, { method: "POST", pathname: "/v2/internal/curation/receipts", body: receipt }, runtime); + const exactStatus = receipt.kind === "apply" ? response.data.status === "promoted" : response.data.status === receipt.status; + const alreadyPromoted = receipt.kind === "decision" && response.data.status === "promoted" + && response.data.decision?.decisionId === receipt.decisionId && response.data.apply?.decisionId === receipt.decisionId; + if (response.data.proposalId !== receipt.proposalId || (!exactStatus && !alreadyPromoted)) throw new Error("Fabric receipt ACK does not match the submitted transition"); + return { ackId: response.meta.requestId, acknowledgedAt: new Date().toISOString() }; +} + +function readReplayCursor(workspaceRoot, config, runtime = {}) { + const absolute = path.join(workspaceRoot, REPLAY_CURSOR_PATH); + if (!fs.existsSync(absolute)) return null; + const current = JSON.parse(readFileNoFollowSync(workspaceRoot, absolute)); + const key = outboxKey(config, runtime); + if (!exact(current, new Set(["schema", "cursor", "artifactMac"])) + || current.schema !== `${TRANSPORT_SCHEMA}/replay-cursor` + || !/^decision-[0-9a-f]{40}$/.test(String(current.cursor ?? "")) + || !HASH_RE.test(String(current.artifactMac ?? "")) + || artifactMac(key, current) !== current.artifactMac) throw new Error("Fabric replay cursor authentication failed"); + return current.cursor; +} + +function writeReplayCursor(workspaceRoot, config, cursor, runtime = {}) { + const absolute = path.join(workspaceRoot, REPLAY_CURSOR_PATH); + const value = { schema: `${TRANSPORT_SCHEMA}/replay-cursor`, cursor }; + value.artifactMac = artifactMac(outboxKey(config, runtime), value); + atomicWriteFileSync(workspaceRoot, absolute, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 }); +} + +async function replayFabricDecisionOutbox(workspaceRoot, config, input = {}, runtime = {}) { + const limit = input.limit ?? 50; + const maxPages = input.maxPages ?? 10; + if (!Number.isSafeInteger(limit) || limit < 1 || limit > 100 || !Number.isSafeInteger(maxPages) || maxPages < 1 || maxPages > 20 + || (input.cursor != null && !/^decision-[0-9a-f]{40}$/.test(input.cursor))) throw new Error("decision replay bounds are invalid"); + const directory = path.join(workspaceRoot, "memory/amf/curator/fabric-outbox"); + if (!fs.existsSync(directory)) return { ok: true, processed: 0, results: [] }; + assertNoSymlinkPath(workspaceRoot, directory, { allowMissing: false }); + const key = outboxKey(config, runtime); const results = []; + const names = fs.readdirSync(directory).filter(name => /^decision-[0-9a-f]{40}\.json$/.test(name)).sort(); + if (!names.length) return { ok: true, processed: 0, scanned: 0, results: [], nextCursor: null }; + const cursor = input.cursor ?? readReplayCursor(workspaceRoot, config, runtime); + let start = cursor ? names.findIndex(name => name > `${cursor}.json`) : 0; + if (start < 0) start = 0; + const scanBudget = Math.min(names.length, limit * maxPages); + let scanned = 0; let lastCursor = cursor; + while (scanned < scanBudget && results.length < limit) { + const name = names[(start + scanned) % names.length]; + const current = JSON.parse(readFileNoFollowSync(workspaceRoot, path.join(directory, name))); + if (!HASH_RE.test(String(current.artifactMac ?? "")) || artifactMac(key, current) !== current.artifactMac) throw new Error("Fabric decision outbox authentication failed"); + if (current.phase === "queued") { + const ack = await postReceipt(config, "curator", current.receipt, runtime); + writeDecisionOutbox(workspaceRoot, config, current.receipt, ack, runtime); + results.push({ decisionId: current.receipt.decisionId, status: "fabric_acked", duplicate: false }); + } else if (current.phase !== "fabric_acked") throw new Error("Fabric decision outbox phase is invalid"); + scanned += 1; + lastCursor = name.slice(0, -5); + writeReplayCursor(workspaceRoot, config, lastCursor, runtime); + } + return { ok: true, processed: results.length, scanned, results, nextCursor: lastCursor }; +} + +async function intakeFabricProposal(workspaceRoot, config, input, runtime = {}) { + if (!exact(input, new Set(["proposalId", "dispatch"]))) throw new Error("Fabric intake input is invalid"); + const remote = await readFabricProposal(config, input.proposalId, runtime); + if (remote.payload.type !== "canonical-memory-proposal" || !object(remote.payload.record) + || typeof remote.payload.rationale !== "string") throw new Error("Fabric proposal is not a canonical memory candidate"); + const result = submitCuratorCandidate(workspaceRoot, config, { + content: renderMemoryRecord(remote.payload.record), + rationale: remote.payload.rationale, + idempotencyKey: `fabric-proposal:${remote.proposalId}`, + confidence: remote.payload.record.confidence?.score, + source: { type: "fabric", id: remote.proposalId }, + fabricProposal: { proposalId: remote.proposalId, proposalDigest: remote.proposalDigest } + }, runtime); + if (!result.ok || !result.fabricReceipt) return { ok: false, status: result.status || "rejected", error: result.error || "curator intake failed" }; + writeDecisionOutbox(workspaceRoot, config, result.fabricReceipt, null, runtime); + const safe = { ok: true, status: result.status, candidateId: result.candidateId, decisionId: result.decisionId, decisionDigest: result.decisionDigest, duplicateSubmission: result.duplicateSubmission, fabricReceipt: result.fabricReceipt }; + if (input.dispatch !== true) return { ...safe, transportStatus: "queued" }; + const ack = await postReceipt(config, "curator", result.fabricReceipt, runtime); + if (runtime.faultAt === "after-decision-ack") throw new Error("injected transport fault after decision ACK"); + writeDecisionOutbox(workspaceRoot, config, result.fabricReceipt, ack, runtime); + return { ...safe, transportStatus: "fabric_acked", ack }; +} + +async function drainFabricProposals(workspaceRoot, config, input = {}, runtime = {}) { + const maxPages = input.maxPages ?? 10; + if (!Number.isSafeInteger(maxPages) || maxPages < 1 || maxPages > 20) throw new Error("Fabric drain maxPages is invalid"); + const results = []; let cursor = input.cursor || null; let pages = 0; + do { + const page = await listFabricProposals(config, { limit: input.limit ?? 50, cursor }, runtime); pages += 1; + for (const item of page.items) results.push(await intakeFabricProposal(workspaceRoot, config, { proposalId: item.proposalId, dispatch: input.dispatch === true }, runtime)); + cursor = page.nextCursor || null; + } while (cursor && pages < maxPages); + return { ok: results.every(item => item.ok), processed: results.length, pages, results, nextCursor: cursor }; +} + +async function dispatchFabricApplyReceipt(workspaceRoot, config, input, runtime = {}) { + const loaded = loadFabricApplyReceiptForDispatch(workspaceRoot, config, { decisionId: input.decisionId }, runtime); + if (!loaded.ok) return loaded; + if (loaded.status === "fabric_acked") return { ok: true, duplicate: true, status: "fabric_acked" }; + const ack = await postReceipt(config, "applicator", loaded.receipt, runtime); + if (runtime.faultAt === "after-apply-ack") throw new Error("injected transport fault after apply ACK"); + return recordFabricApplyAck(workspaceRoot, config, { decisionId: input.decisionId, receipt: loaded.receipt, ...ack }, runtime); +} + +export { + DEFAULT_TRANSPORT, + TRANSPORT_SCHEMA, + dispatchFabricApplyReceipt, + drainFabricProposals, + intakeFabricProposal, + listFabricProposals, + readFabricProposal, + replayFabricDecisionOutbox, + transportPolicy +}; diff --git a/tools/lib/amf-memory-record.mjs b/tools/lib/amf-memory-record.mjs index bf623f7..ecfcf33 100644 --- a/tools/lib/amf-memory-record.mjs +++ b/tools/lib/amf-memory-record.mjs @@ -38,7 +38,7 @@ 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}$/; -const OPAQUE_REF_RE = /^(?:agent|person|relationship|room|domain):[A-Za-z0-9][A-Za-z0-9._-]{2,127}$/; +const OPAQUE_REF_RE = /^(?:agent|person|relationship|room|domain):[A-Za-z0-9][A-Za-z0-9._:-]{2,127}$/; const HASH_RE = /^[0-9a-f]{64}$/i; const RFC3339_UTC_RE = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.(\d{1,9}))?Z$/; const NAMESPACED_TYPE_RE = /^[a-z][a-z0-9_-]{0,31}:[a-z][a-z0-9._-]{0,63}$/; @@ -127,6 +127,13 @@ function recordSha256(content) { return sha256(String(content)); } +function renderMemoryRecord(metadata) { + return `---\n${REQUIRED_FIELDS.map((key) => { + const value = metadata[key]; + return `${key}: ${value !== null && typeof value === "object" ? JSON.stringify(value) : String(value)}`; + }).join("\n")}\n---\n`; +} + function isRfc3339Utc(value) { if (typeof value !== "string") return false; const match = RFC3339_UTC_RE.exec(value); @@ -635,6 +642,7 @@ export { projectMemoryRecord, recordPathFor, recordSha256, + renderMemoryRecord, validateMemoryRecord, validateMemoryRecordTransition }; diff --git a/tools/lib/mcp-tools.mjs b/tools/lib/mcp-tools.mjs index 883fb58..7026f69 100644 --- a/tools/lib/mcp-tools.mjs +++ b/tools/lib/mcp-tools.mjs @@ -20,7 +20,7 @@ import { reviewCuratorCandidate, submitCuratorCandidate } from "./memory-curator.mjs"; -import { applyDecisionReceipt } from "./memory-receipt-applicator.mjs"; +import { applyDecisionReceipt, deliverAppliedMemoryToGit, verifyFabricApplyReceipt } 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"; @@ -335,6 +335,12 @@ function buildToolRegistry({ workspaceRoot, serverVersion }) { properties: { type: { type: "string" }, id: { type: "string" } }, required: ["type", "id"], additionalProperties: false + }, + fabricProposal: { + type: "object", + properties: { proposalId: { type: "string" }, proposalDigest: { type: "string", pattern: "^[a-f0-9]{64}$" } }, + required: ["proposalId", "proposalDigest"], + additionalProperties: false } }, required: ["content", "rationale", "idempotencyKey", "confidence", "source"], @@ -375,6 +381,28 @@ function buildToolRegistry({ workspaceRoot, serverVersion }) { }, handler: async (args) => jsonResultContent(applyDecisionReceipt(workspaceRoot, loadConfig(), args ?? {})) }, + { + name: "memory_verify_apply_receipt", + description: "Verifier-only check that a Fabric apply receipt matches authenticated applicator state, the applied archive, the canonical target, and the atomic PAM record index.", + inputSchema: { + type: "object", + properties: { receipt: { type: "object" } }, + required: ["receipt"], + additionalProperties: false + }, + handler: async (args) => jsonResultContent(verifyFabricApplyReceipt(workspaceRoot, loadConfig(), args?.receipt ?? {})) + }, + { + name: "memory_git_deliver", + description: "Applicator-only opt-in scoped Git commit and optional fast-forward push for one applied AMF record plus its canonical index entry.", + inputSchema: { + type: "object", + properties: { decisionId: { type: "string" }, push: { type: "boolean" } }, + required: ["decisionId"], + additionalProperties: false + }, + handler: async (args) => jsonResultContent(deliverAppliedMemoryToGit(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.", diff --git a/tools/lib/memory-curator.mjs b/tools/lib/memory-curator.mjs index 3df572f..611f635 100644 --- a/tools/lib/memory-curator.mjs +++ b/tools/lib/memory-curator.mjs @@ -83,7 +83,8 @@ const REVIEW_ARTIFACT_FIELDS = new Set([ const DECISION_RECEIPT_FIELDS = new Set([ "schema", "receiptType", "outcome", "decisionId", "candidateId", "candidateRecordSha256", "candidateRevision", "canonicalRecordId", - "canonicalLifecycleAtDecision", "policyDigest", "createdAt", "decisionDigest", + "canonicalLifecycleAtDecision", "fabricProposalId", "fabricProposalScope", "fabricProposalDigest", + "policyDigest", "createdAt", "decisionDigest", "artifactMac" ]); const DECISION_OUTCOMES = new Set(["review_required", "rejected", "approved_pending_apply"]); @@ -213,6 +214,19 @@ function normalizeSource(input) { return { ok: true, source: { type: source.type, id: source.id } }; } +function normalizeFabricProposal(input, source) { + const binding = input?.fabricProposal; + if (source.type !== "fabric") { + return binding === undefined ? { ok: true, binding: null } : { ok: false, error: "fabricProposal is accepted only for source.type=fabric" }; + } + if (!exactKeys(binding, new Set(["proposalId", "proposalDigest"])) + || typeof binding.proposalId !== "string" || !/^[A-Za-z0-9][A-Za-z0-9-]{0,127}$/.test(binding.proposalId) + || !HASH_RE.test(String(binding.proposalDigest ?? ""))) { + return { ok: false, error: "source.type=fabric requires an exact proposalId/proposalDigest binding" }; + } + return { ok: true, binding: { proposalId: binding.proposalId, proposalDigest: binding.proposalDigest } }; +} + function curatorPolicy(config = {}) { const configured = isPlainObject(config.amfCurator) ? config.amfCurator : {}; const gitWriter = isPlainObject(configured.gitWriter) ? configured.gitWriter : {}; @@ -433,7 +447,8 @@ function readCandidate(workspaceRoot, candidateId, key) { recordSha256: record.recordSha256, rationale: record.rationale, source: record.source, - confidence: record.confidence + confidence: record.confidence, + fabricProposal: record.fabricProposal }; if (sha256(canonicalize(inputIdentity)) !== record.inputSha256) { return { ok: false, error: "candidate artifact input hash is invalid" }; @@ -1129,6 +1144,9 @@ function decisionReceiptPayload(receipt) { candidateRevision: receipt.candidateRevision, canonicalRecordId: receipt.canonicalRecordId, canonicalLifecycleAtDecision: receipt.canonicalLifecycleAtDecision, + fabricProposalId: receipt.fabricProposalId, + fabricProposalScope: receipt.fabricProposalScope, + fabricProposalDigest: receipt.fabricProposalDigest, policyDigest: receipt.policyDigest, createdAt: receipt.createdAt }; @@ -1147,6 +1165,9 @@ function validateDecisionReceipt(receipt, key, candidate, review) { && receipt.candidateRevision === candidate.record.revision && receipt.canonicalRecordId === candidate.record.id && receipt.canonicalLifecycleAtDecision === candidate.record.lifecycleStatus + && receipt.fabricProposalId === (candidate.fabricProposal?.proposalId ?? null) + && receipt.fabricProposalScope === (candidate.fabricProposal ? candidate.record.scope.id : null) + && receipt.fabricProposalDigest === (candidate.fabricProposal?.proposalDigest ?? null) && HASH_RE.test(String(receipt.policyDigest ?? "")) && receipt.createdAt === review.createdAt && receipt.decisionDigest === sha256(canonicalize(payload)) @@ -1166,6 +1187,9 @@ function ensureDecisionReceipt(workspaceRoot, key, policy, candidate, review, ru candidateRevision: candidate.record.revision, canonicalRecordId: candidate.record.id, canonicalLifecycleAtDecision: candidate.record.lifecycleStatus, + fabricProposalId: candidate.fabricProposal?.proposalId ?? null, + fabricProposalScope: candidate.fabricProposal ? candidate.record.scope.id : null, + fabricProposalDigest: candidate.fabricProposal?.proposalDigest ?? null, policyDigest: curatorPolicyDigest(policy), createdAt: review.createdAt }; @@ -1590,8 +1614,8 @@ function recoverExactPolicyBoundary(workspaceRoot, policy, key, state, candidate } 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" }; + const submitFields = new Set(["content", "rationale", "idempotencyKey", "confidence", "source", "fabricProposal"]); + if (!exactKeys(input, submitFields, new Set(["content", "rationale", "idempotencyKey", "confidence", "source"]))) return { ok: false, error: "submit input contains missing or unknown fields" }; let policy; try { policy = curatorPolicy(config); @@ -1617,6 +1641,8 @@ function submitCuratorCandidate(workspaceRoot, config, input, runtime = {}) { if (confidence === null) return { ok: false, error: "confidence must be between 0 and 1" }; const source = normalizeSource(input); if (!source.ok) return source; + const fabricProposal = normalizeFabricProposal(input, source.source); + if (!fabricProposal.ok) return fabricProposal; ensureCuratorLayout(workspaceRoot); const earlyKeySha256 = sha256(input.idempotencyKey); const earlyCandidateId = safeStableId("candidate", earlyKeySha256); @@ -1624,7 +1650,8 @@ function submitCuratorCandidate(workspaceRoot, config, input, runtime = {}) { recordSha256: recordSha256(input.content), rationale: input.rationale, source: source.source, - confidence + confidence, + fabricProposal: fabricProposal.binding })); const earlyAbsolute = candidatePath(workspaceRoot, earlyCandidateId); let preflightLedger = readDecisionLedger(workspaceRoot, key, state); @@ -1707,7 +1734,8 @@ function submitCuratorCandidate(workspaceRoot, config, input, runtime = {}) { recordSha256: recordSha256(input.content), rationale: input.rationale, source: source.source, - confidence: recordConfidence + confidence: recordConfidence, + fabricProposal: fabricProposal.binding }; const inputSha256 = sha256(canonicalize(inputIdentity)); let candidate; @@ -1733,6 +1761,7 @@ function submitCuratorCandidate(workspaceRoot, config, input, runtime = {}) { recordContent: input.content, rationale: input.rationale, source: source.source, + fabricProposal: fabricProposal.binding, confidence: recordConfidence, targetPath: inspected.targetPath, targetExists: inspected.targetExists, @@ -1817,7 +1846,8 @@ function submitCuratorCandidate(workspaceRoot, config, input, runtime = {}) { candidatePath: workspaceRelative(workspaceRoot, absolute), decisionId: latest.decisionId, decisionDigest: receipt.decisionDigest, - duplicateSubmission: true + duplicateSubmission: true, + fabricReceipt: buildFabricDecisionReceipt(receipt).ok ? buildFabricDecisionReceipt(receipt).receipt : null }; } } @@ -1849,7 +1879,8 @@ function submitCuratorCandidate(workspaceRoot, config, input, runtime = {}) { decisionDigest: receipt.receipt.decisionDigest, duplicateSubmission, duplicateOf: duplicate, - policy: evaluation + policy: evaluation, + fabricReceipt: buildFabricDecisionReceipt(receipt.receipt).ok ? buildFabricDecisionReceipt(receipt.receipt).receipt : null }; } @@ -2178,11 +2209,33 @@ function planCuratorGitWrite(config, input = {}) { }; } +function buildFabricDecisionReceipt(decisionReceipt) { + if (!decisionReceipt || !DECISION_OUTCOMES.has(decisionReceipt.outcome) + || typeof decisionReceipt.fabricProposalId !== "string" + || typeof decisionReceipt.fabricProposalScope !== "string" + || !HASH_RE.test(String(decisionReceipt.fabricProposalDigest ?? "")) + || !DECISION_ID_RE.test(String(decisionReceipt.decisionId ?? "")) + || !HASH_RE.test(String(decisionReceipt.policyDigest ?? "")) + || !isTimestamp(decisionReceipt.createdAt)) { + return { ok: false, error: "decision receipt is not bound to a Fabric proposal" }; + } + const base = { + proposalId: decisionReceipt.fabricProposalId, + proposalScope: decisionReceipt.fabricProposalScope, + decisionId: decisionReceipt.decisionId, + status: decisionReceipt.outcome, + proposalDigest: decisionReceipt.fabricProposalDigest, + policyDigest: decisionReceipt.policyDigest + }; + return { ok: true, receipt: { kind: "decision", ...base, decisionDigest: sha256(canonicalize(base)), timestamp: decisionReceipt.createdAt } }; +} + export { CURATOR_ROOT, CURATOR_SCHEMA, DEFAULT_POLICY, appendDecisionEvent, + buildFabricDecisionReceipt, curatorPolicy, curatorStatus, inspectCandidate, diff --git a/tools/lib/memory-receipt-applicator.mjs b/tools/lib/memory-receipt-applicator.mjs index 554fc64..9f30fa6 100644 --- a/tools/lib/memory-receipt-applicator.mjs +++ b/tools/lib/memory-receipt-applicator.mjs @@ -1,19 +1,22 @@ import crypto from "node:crypto"; +import { spawnSync } from "node:child_process"; import fs from "node:fs"; import path from "node:path"; -import { canonicalize } from "./amf-memory-record.mjs"; +import { canonicalize, isAmfRecordPath, parseMemoryRecord } from "./amf-memory-record.mjs"; import { applyProposal, proposalArtifactDigest } from "./memory-apply-proposal.mjs"; import { ensureCuratorProposal, loadApprovedDecisionBundle, + buildFabricDecisionReceipt, verifyAppliedCandidate } from "./memory-curator.mjs"; import { acquireExclusiveLock, assertNoSymlinkPath, atomicWriteFileSync, - readFileNoFollowSync + readFileNoFollowSync, + readOwnerOnlyFileSync } from "./secure-fs.mjs"; import { workspaceRelative } from "./workspace.mjs"; @@ -21,13 +24,24 @@ 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 DECISION_MAP_DIR = path.join(APPLICATOR_ROOT, "decision-map"); +const GIT_DELIVERY_DIR = path.join(APPLICATOR_ROOT, "git-delivery"); 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", + stateKeyEnv: "PAM_APPLICATOR_STATE_KEY", + stateKeyFileEnv: "PAM_APPLICATOR_STATE_KEY_FILE", applicators: [], + recordIndexPath: "memory/amf/record-index.json", + gitWriter: { + enabled: false, + repoRootEnv: "PAM_GIT_WRITER_REPO_ROOT", + allowedBranches: [], + push: { enabled: false, remote: null, allowedRemotes: [] } + }, transport: { kind: "disabled", endpointEnv: "PAM_FABRIC_RECEIPT_ENDPOINT" @@ -60,16 +74,28 @@ function exactKeys(value, allowed, required = allowed) { function applicatorPolicy(config = {}) { const configured = isPlainObject(config.amfApplicator) ? config.amfApplicator : {}; const transport = isPlainObject(configured.transport) ? configured.transport : {}; + const gitWriter = isPlainObject(configured.gitWriter) ? configured.gitWriter : {}; + const gitPush = isPlainObject(gitWriter.push) ? gitWriter.push : {}; const policy = { ...DEFAULT_APPLICATOR, ...configured, applicators: Array.isArray(configured.applicators) ? configured.applicators.map((row) => ({ ...row })) : [], - transport: { ...DEFAULT_APPLICATOR.transport, ...transport } + transport: { ...DEFAULT_APPLICATOR.transport, ...transport }, + gitWriter: { + ...DEFAULT_APPLICATOR.gitWriter, + ...gitWriter, + allowedBranches: Array.isArray(gitWriter.allowedBranches) ? [...gitWriter.allowedBranches] : [], + push: { ...DEFAULT_APPLICATOR.gitWriter.push, ...gitPush, allowedRemotes: Array.isArray(gitPush.allowedRemotes) ? [...gitPush.allowedRemotes] : [] } + } }; if (policy.version !== APPLICATOR_SCHEMA) throw new Error(`unsupported applicator policy: ${policy.version}`); + if (typeof policy.recordIndexPath !== "string" || !/^memory\/amf\/[A-Za-z0-9][A-Za-z0-9._/-]{1,127}$/.test(policy.recordIndexPath) + || policy.recordIndexPath.split("/").includes("..")) throw new Error("amfApplicator.recordIndexPath is invalid"); if (typeof policy.tokenEnv !== "string" || !/^[A-Z][A-Z0-9_]{2,63}$/.test(policy.tokenEnv)) { throw new Error("amfApplicator.tokenEnv is invalid"); } + if (typeof policy.stateKeyEnv !== "string" || !/^[A-Z][A-Z0-9_]{2,63}$/.test(policy.stateKeyEnv)) throw new Error("amfApplicator.stateKeyEnv is invalid"); + if (typeof policy.stateKeyFileEnv !== "string" || !/^[A-Z][A-Z0-9_]{2,63}$/.test(policy.stateKeyFileEnv)) throw new Error("amfApplicator.stateKeyFileEnv is invalid"); for (const actor of policy.applicators) { if (!exactKeys(actor, new Set(["tokenSha256", "actorId", "capabilities"])) || !HASH_RE.test(String(actor.tokenSha256 ?? "")) @@ -82,6 +108,12 @@ function applicatorPolicy(config = {}) { if (!new Set(["disabled", "http"]).has(policy.transport.kind)) { throw new Error("amfApplicator.transport.kind must be disabled or http"); } + if (typeof policy.gitWriter.enabled !== "boolean" || typeof policy.gitWriter.repoRootEnv !== "string" + || !/^[A-Z][A-Z0-9_]{2,63}$/.test(policy.gitWriter.repoRootEnv) + || policy.gitWriter.allowedBranches.some(value => typeof value !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._/-]{0,127}$/.test(value) || value.includes("..")) + || typeof policy.gitWriter.push.enabled !== "boolean" + || (policy.gitWriter.push.enabled && (typeof policy.gitWriter.push.remote !== "string" || !policy.gitWriter.push.allowedRemotes.includes(policy.gitWriter.push.remote))) + || policy.gitWriter.push.allowedRemotes.some(value => typeof value !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/.test(value))) throw new Error("amfApplicator.gitWriter is invalid"); if (policy.transport.kind === "http" && (typeof policy.transport.endpointEnv !== "string" || !/^[A-Z][A-Z0-9_]{2,63}$/.test(policy.transport.endpointEnv))) { @@ -100,7 +132,19 @@ function authorizeApplicator(policy, runtime = {}) { 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") }; + const stateKey = resolveStateKey(policy, runtime); + if (typeof stateKey !== "string" || Buffer.byteLength(stateKey, "utf8") < 32) return { ok: false, error: "applicator state authentication key is not configured" }; + return { ok: true, actorId: actor.actorId, key: Buffer.from(stateKey, "utf8") }; +} + +function resolveStateKey(policy, runtime = {}) { + if (typeof runtime.stateKey === "string") return runtime.stateKey; + const filename = (runtime.env || process.env)[policy.stateKeyFileEnv]; + if (filename) { + try { return readOwnerOnlyFileSync(filename, { label: "applicator state key", maxBytes: 4096 }).trim(); } + catch { return null; } + } + return (runtime.env || process.env)[policy.stateKeyEnv]; } function ensureLayout(workspaceRoot) { @@ -108,11 +152,191 @@ function ensureLayout(workspaceRoot) { 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 }); + fs.mkdirSync(path.join(workspaceRoot, DECISION_MAP_DIR), { recursive: true, mode: 0o700 }); + fs.mkdirSync(path.join(workspaceRoot, GIT_DELIVERY_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 gitRun(root, args) { + return spawnSync("git", args, { cwd: root, encoding: "utf8", shell: false, maxBuffer: 1024 * 1024 }); +} + +function gitOutput(root, args, code = 0) { + const result = gitRun(root, args); + if (result.status !== code) throw new Error("Git delivery command failed"); + return result.stdout; +} + +function gitDeliveryPath(workspaceRoot, decisionId) { return path.join(workspaceRoot, GIT_DELIVERY_DIR, `${decisionId}.json`); } + +function writeGitDelivery(workspaceRoot, key, value) { + const next = { ...value }; next.artifactMac = artifactMac(key, next); + atomicWriteFileSync(workspaceRoot, gitDeliveryPath(workspaceRoot, value.decisionId), `${JSON.stringify(next, null, 2)}\n`, { mode: 0o600 }); + return next; +} + +function commitPaths(root, revision) { + return gitOutput(root, ["diff-tree", "--no-commit-id", "--name-only", "-r", revision]).trim().split("\n").filter(Boolean).sort(); +} + +function recoverDeliveryCommit(root, decisionId, expectedPaths) { + const result = gitRun(root, ["log", "-1", "--format=%H%x00%B"]); + if (result.status !== 0) return null; + const [commit, message = ""] = result.stdout.split("\0"); + if (!message.includes(`AMF-Decision: ${decisionId}`) || canonicalize(commitPaths(root, commit)) !== canonicalize([...expectedPaths].sort())) return null; + return commit.trim(); +} + +function gitRepositoryIdentity(root) { + const common = gitOutput(root, ["rev-parse", "--git-common-dir"]).trim(); + const commonRealpath = fs.realpathSync(path.isAbsolute(common) ? common : path.resolve(root, common)); + return sha256(canonicalize({ root: fs.realpathSync(root), commonGitDir: commonRealpath })); +} + +function gitPushBinding(root, writer, branch) { + const targetRef = `refs/heads/${branch}`; + if (!writer.push.enabled) return { enabled: false, remote: null, remoteUrlSha256: null, targetRef }; + const remote = writer.push.remote; + if (!writer.push.allowedRemotes.includes(remote)) throw new Error("Git remote is not allowlisted"); + const remoteUrl = gitOutput(root, ["remote", "get-url", "--push", remote]).trim(); + if (!remoteUrl || /[\r\n\0]/.test(remoteUrl)) throw new Error("Git push remote is invalid"); + return { enabled: true, remote, remoteUrlSha256: sha256(remoteUrl), targetRef }; +} + +function pushCommit(root, writer, binding, commit) { + if (!writer.push.enabled) throw new Error("Git push is disabled by policy"); + const remote = binding.remote; + const branch = binding.targetRef.slice("refs/heads/".length); + if (canonicalize(gitPushBinding(root, writer, branch)) !== canonicalize(binding)) throw new Error("Git push target binding changed"); + const remoteHead = gitRun(root, ["ls-remote", "--exit-code", "--heads", remote, binding.targetRef]); + if (remoteHead.status === 0) { + const remoteCommit = remoteHead.stdout.trim().split(/\s+/)[0]; + if (!/^[a-f0-9]{40}$/.test(remoteCommit) || gitRun(root, ["fetch", "--no-tags", remote, remoteCommit]).status !== 0 + || gitRun(root, ["merge-base", "--is-ancestor", remoteCommit, commit]).status !== 0) throw new Error("Git push is not fast-forward"); + } else if (remoteHead.status !== 2) throw new Error("Git remote inspection failed"); + if (gitRun(root, ["push", remote, `${commit}:${binding.targetRef}`]).status !== 0) throw new Error("Git push was rejected"); + return remote; +} + +function loadGitDeliveryReadyState(workspaceRoot, config, decisionId, bundle, key) { + const map = readJson(workspaceRoot, decisionMapPath(workspaceRoot, decisionId), "applicator decision map"); + if (!map.ok || map.record.schema !== `${APPLICATOR_SCHEMA}/decision-map` + || map.record.decisionId !== decisionId + || !/^apply-[0-9a-f]{40}$/.test(String(map.record.applyId ?? "")) + || !secureDigestEqual(artifactMac(key, map.record), map.record.artifactMac)) { + return { ok: false, error: "Git delivery requires an authenticated receipt-ready apply state" }; + } + const loaded = readJson(workspaceRoot, statePath(workspaceRoot, map.record.applyId), "applicator state"); + if (!loaded.ok || !validState(loaded.record, key) + || !["receipt_queued", "fabric_acked"].includes(loaded.record.phase) + || loaded.record.decisionId !== decisionId + || loaded.record.candidateId !== bundle.candidate.candidateId) { + return { ok: false, error: "Git delivery requires an authenticated receipt-ready apply state" }; + } + const fabric = buildFabricApplyReceipt(loaded.record.receipt); + const verified = fabric.ok + ? verifyFabricApplyReceipt(workspaceRoot, config, fabric.receipt, { stateKey: key.toString("utf8") }) + : fabric; + if (!verified.ok || verified.verified !== true) { + return { ok: false, error: "Git delivery canonical artifacts do not match the authenticated apply receipt" }; + } + return { ok: true, state: loaded.record }; +} + +function deliverAppliedMemoryToGit(workspaceRoot, config, input, runtime = {}) { + if (!exactKeys(input, new Set(["decisionId", "push"]), new Set(["decisionId"])) + || !/^decision-[0-9a-f]{40}$/.test(String(input.decisionId ?? "")) + || (input.push !== undefined && typeof input.push !== "boolean")) return { ok: false, error: "Git delivery input is invalid" }; + 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 writer = policy.gitWriter; + if (!writer.enabled) return { ok: false, status: "disabled", error: "Git writer is disabled by policy" }; + const configuredRoot = (runtime.env || process.env)[writer.repoRootEnv]; + let root; + try { root = fs.realpathSync(configuredRoot); } catch { return { ok: false, error: "Git repository root is unavailable" }; } + if (root !== fs.realpathSync(workspaceRoot) || gitRun(root, ["rev-parse", "--show-toplevel"]).stdout.trim() !== root) return { ok: false, error: "Git repository root is not the PAM workspace" }; + const branch = gitOutput(root, ["symbolic-ref", "--quiet", "--short", "HEAD"]).trim(); + if (!writer.allowedBranches.includes(branch)) return { ok: false, error: "Git branch is not allowlisted" }; + let repoIdentity; let pushBinding; + try { repoIdentity = gitRepositoryIdentity(root); pushBinding = gitPushBinding(root, writer, branch); } + catch (error) { return { ok: false, error: error.message }; } + const bundle = loadApprovedDecisionBundle(workspaceRoot, config, { decisionId: input.decisionId }, runtime); + if (!bundle.ok) return bundle; + const expectedPaths = [bundle.candidate.targetPath, policy.recordIndexPath].sort(); + ensureLayout(workspaceRoot); + const lock = acquireExclusiveLock(workspaceRoot, path.join(workspaceRoot, APPLICATOR_ROOT, "git-writer.lock")); + try { + const ready = loadGitDeliveryReadyState(workspaceRoot, config, input.decisionId, bundle, authorized.key); + if (!ready.ok) return ready; + const stateAbsolute = gitDeliveryPath(workspaceRoot, input.decisionId); + let delivery = null; + const stateExisted = fs.existsSync(stateAbsolute); + if (stateExisted) { + const loaded = readJson(workspaceRoot, stateAbsolute, "Git delivery state"); + if (!loaded.ok || !secureDigestEqual(artifactMac(authorized.key, loaded.record), loaded.record.artifactMac) + || loaded.record.schema !== `${APPLICATOR_SCHEMA}/git-delivery` + || loaded.record.decisionId !== input.decisionId || loaded.record.repoIdentity !== repoIdentity + || !["committed", "pushed"].includes(loaded.record.phase) || !/^[a-f0-9]{40,64}$/.test(String(loaded.record.commit ?? "")) + || loaded.record.branch !== branch || canonicalize(loaded.record.pushBinding) !== canonicalize(pushBinding) + || (loaded.record.phase === "committed" ? loaded.record.remote !== null : loaded.record.remote !== pushBinding.remote) + || canonicalize(loaded.record.paths) !== canonicalize(expectedPaths) + || canonicalize(commitPaths(root, loaded.record.commit)) !== canonicalize(expectedPaths)) return { ok: false, error: "Git delivery state is invalid" }; + delivery = loaded.record; + } + if (!delivery) { + const records = gitOutput(root, ["status", "--porcelain=v1", "-z", "--untracked-files=all"]).split("\0").filter(Boolean); + const changed = records.map(record => { + const status = record.slice(0, 2); + if (record.length < 4 || ["R", "C"].some(code => status.includes(code))) throw new Error("Git rename/copy state is not allowed"); + if (status.includes("U") || status === "AA" || status === "DD") throw new Error("Git unmerged state is not allowed"); + return record.slice(3); + }).sort(); + if (changed.some(filename => !expectedPaths.includes(filename))) return { ok: false, error: "Git worktree contains unrelated changes" }; + let commit = changed.length ? null : recoverDeliveryCommit(root, input.decisionId, expectedPaths); + if (!commit) { + if (!changed.length) return { ok: false, error: "Git delivery has no scoped changes" }; + if (gitRun(root, ["add", "--", ...expectedPaths]).status !== 0) return { ok: false, error: "Git staging failed" }; + const message = `chore(memory): promote ${bundle.candidate.record.id}\n\nAMF-Decision: ${input.decisionId}`; + const committed = gitRun(root, ["commit", "-m", message, "--", ...expectedPaths]); + if (committed.status !== 0) { + gitRun(root, ["restore", "--staged", "--", ...expectedPaths]); + return { ok: false, error: "Git commit failed; scoped staging rolled back" }; + } + commit = gitOutput(root, ["rev-parse", "HEAD"]).trim(); + } + if (canonicalize(commitPaths(root, commit)) !== canonicalize(expectedPaths)) return { ok: false, error: "Git commit scope verification failed" }; + delivery = writeGitDelivery(workspaceRoot, authorized.key, { + schema: `${APPLICATOR_SCHEMA}/git-delivery`, decisionId: input.decisionId, phase: "committed", + commit, repoIdentity, branch, pushBinding, remote: null, paths: expectedPaths + }); + } + if (input.push === true && delivery.phase !== "pushed") { + const remote = pushCommit(root, writer, delivery.pushBinding, delivery.commit); + delivery = writeGitDelivery(workspaceRoot, authorized.key, { ...delivery, phase: "pushed", remote }); + } + return { ok: true, status: delivery.phase, decisionId: input.decisionId, commit: delivery.commit, branch, remote: delivery.remote, duplicate: stateExisted }; + } catch (error) { return { ok: false, error: error.message }; } + finally { lock.release(); } +} + +function decisionMapPath(workspaceRoot, decisionId) { return path.join(workspaceRoot, DECISION_MAP_DIR, `${decisionId}.json`); } + +function writeDecisionMap(workspaceRoot, key, decisionId, applyId) { + const absolute = decisionMapPath(workspaceRoot, decisionId); + const value = { schema: `${APPLICATOR_SCHEMA}/decision-map`, decisionId, applyId }; + value.artifactMac = artifactMac(key, value); + if (fs.existsSync(absolute)) { + const loaded = readJson(workspaceRoot, absolute, "applicator decision map"); + if (!loaded.ok || canonicalize(loaded.record) !== canonicalize(value)) return { ok: false, error: "applicator decision map conflict" }; + return { ok: true }; + } + atomicWriteFileSync(workspaceRoot, absolute, `${JSON.stringify(value, null, 2)}\n`, { exclusive: true, mode: 0o600 }); + return { ok: true }; +} + function artifactMac(key, value) { const copy = { ...value }; delete copy.artifactMac; @@ -151,6 +375,9 @@ function validState(state, key) { && 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 ?? "")) + && /^[A-Za-z0-9][A-Za-z0-9-]{0,127}$/.test(String(state.fabricProposalId ?? "")) + && typeof state.fabricProposalScope === "string" && state.fabricProposalScope.length >= 3 && state.fabricProposalScope.length <= 256 + && HASH_RE.test(String(state.fabricProposalDigest ?? "")) && PHASES.has(state.phase) && (state.receipt === null || isPlainObject(state.receipt)) && (state.ack === null || isPlainObject(state.ack)) @@ -170,24 +397,56 @@ function proposalArtifactPath(workspaceRoot, proposalId) { } function buildReceipt(state, bundle, verified) { + const metadata = parseMemoryRecord(bundle.candidate.recordContent).metadata; return { schema: `${APPLICATOR_SCHEMA}/apply-receipt`, receiptType: "memory_apply_receipt", applyId: state.applyId, - proposalId: state.proposalId, + proposalId: state.fabricProposalId, + proposalScope: state.fabricProposalScope, decisionId: bundle.decisionReceipt.decisionId, - decisionDigest: bundle.decisionReceipt.decisionDigest, + decisionDigest: state.decisionDigest, policyDigestAtApply: state.policyDigestAtApply, canonicalRecordId: bundle.decisionReceipt.canonicalRecordId, revision: bundle.decisionReceipt.candidateRevision, canonicalLifecycleAtDecision: bundle.decisionReceipt.canonicalLifecycleAtDecision, - proposalDigest: state.proposalDigest, + proposalDigest: state.fabricProposalDigest, archiveDigest: verified.appliedArchiveSha256, - targetDigest: bundle.candidate.recordSha256, + targetDigest: sha256(canonicalize(metadata)), appliedAt: verified.archive.appliedAt }; } +function contextRefsForScope(scope) { + if (scope.type === "room") return { conversation: [scope.id], room: [scope.id] }; + if (scope.type === "person") return { person: [scope.id] }; + if (scope.type === "relationship") return { relationship: [scope.id] }; + return null; +} + +function updateRecordIndex(workspaceRoot, policy, candidate) { + const absolute = path.join(workspaceRoot, policy.recordIndexPath); + const lock = acquireExclusiveLock(workspaceRoot, `${absolute}.lock`); + try { + let index = { schema: "amf-record-index/v1", records: {} }; + if (fs.existsSync(absolute)) { + const loaded = readJson(workspaceRoot, absolute, "AMF record index"); + if (!loaded.ok || loaded.record.schema !== "amf-record-index/v1" + || !isPlainObject(loaded.record.records)) return { ok: false, error: "AMF record index is invalid" }; + index = loaded.record; + } + const metadata = parseMemoryRecord(candidate.recordContent).metadata; + const entry = { path: candidate.targetPath, scope: metadata.scope.id }; + const contextRefs = contextRefsForScope(metadata.scope); + if (contextRefs) entry.contextRefs = contextRefs; + const next = { schema: "amf-record-index/v1", records: { ...index.records, [metadata.id]: entry } }; + atomicWriteFileSync(workspaceRoot, absolute, `${JSON.stringify(next, null, 2)}\n`, { mode: 0o600 }); + return { ok: true, entry }; + } finally { + lock.release(); + } +} + function writeOutbox(workspaceRoot, key, receipt) { const absolute = outboxPath(workspaceRoot, receipt.applyId); const artifact = { ...receipt }; @@ -204,6 +463,12 @@ function writeOutbox(workspaceRoot, key, receipt) { return { ok: true, artifact, duplicate: false }; } +function buildFabricApplyReceipt(receipt) { + const fields = ["proposalId", "proposalScope", "decisionId", "decisionDigest", "policyDigestAtApply", "canonicalRecordId", "revision", "canonicalLifecycleAtDecision", "proposalDigest", "archiveDigest", "targetDigest"]; + if (!isPlainObject(receipt) || fields.some(field => receipt[field] === undefined)) return { ok: false, error: "apply receipt is incomplete" }; + return { ok: true, receipt: { kind: "apply", ...Object.fromEntries(fields.map(field => [field, receipt[field]])), timestamp: receipt.appliedAt } }; +} + function dispatchReceipt(policy, state, runtime = {}) { if (typeof runtime.transportSink === "function") { const response = runtime.transportSink(state.receipt); @@ -238,6 +503,8 @@ function applyDecisionReceipt(workspaceRoot, config, input, runtime = {}) { if (!authorized.ok) return authorized; const bundle = loadApprovedDecisionBundle(workspaceRoot, config, { decisionId: input.decisionId }, runtime); if (!bundle.ok) return bundle; + const fabricDecision = buildFabricDecisionReceipt(bundle.decisionReceipt); + const boundDecisionDigest = fabricDecision.ok ? fabricDecision.receipt.decisionDigest : bundle.decisionReceipt.decisionDigest; ensureLayout(workspaceRoot); const applyId = applyIdFor(input.decisionId, input.idempotencyKey); const inputDigest = sha256(canonicalize({ @@ -256,7 +523,7 @@ function applyDecisionReceipt(workspaceRoot, config, input, runtime = {}) { if (!loaded.ok || !validState(loaded.record, authorized.key) || loaded.record.inputDigest !== inputDigest || loaded.record.decisionId !== input.decisionId - || loaded.record.decisionDigest !== bundle.decisionReceipt.decisionDigest) { + || loaded.record.decisionDigest !== boundDecisionDigest) { return { ok: false, error: `applicator idempotency or decision conflict: ${applyId}` }; } state = loaded.record; @@ -275,10 +542,13 @@ function applyDecisionReceipt(workspaceRoot, config, input, runtime = {}) { inputDigest, decisionId: input.decisionId, candidateId: bundle.candidate.candidateId, - decisionDigest: bundle.decisionReceipt.decisionDigest, + decisionDigest: boundDecisionDigest, policyDigestAtApply: bundle.policyDigestAtApply, proposalId: proposed.proposalId, proposalDigest: proposalArtifactDigest(proposalRecord), + fabricProposalId: bundle.candidate.fabricProposal?.proposalId ?? proposed.proposalId, + fabricProposalScope: bundle.candidate.record.scope.id, + fabricProposalDigest: bundle.candidate.fabricProposal?.proposalDigest ?? proposalArtifactDigest(proposalRecord), phase: "prepared", receipt: null, ack: null, @@ -287,6 +557,9 @@ function applyDecisionReceipt(workspaceRoot, config, input, runtime = {}) { if (runtime.faultAt === "after-prepared") throw new Error("injected applicator fault after prepared state"); } + const mapped = writeDecisionMap(workspaceRoot, authorized.key, input.decisionId, applyId); + if (!mapped.ok) return mapped; + if (state.phase === "prepared") { const applied = applyProposal(workspaceRoot, config, { proposalId: state.proposalId }, { expectedProposalDigest: state.proposalDigest, @@ -305,6 +578,8 @@ function applyDecisionReceipt(workspaceRoot, config, input, runtime = {}) { { sourcePrefix: "pam-amf-applicator" } ); if (!verified.ok) return verified; + const indexed = updateRecordIndex(workspaceRoot, policy, bundle.candidate); + if (!indexed.ok) return indexed; state = writeState(workspaceRoot, authorized.key, { ...state, phase: "pam_applied", @@ -348,10 +623,90 @@ function applyDecisionReceipt(workspaceRoot, config, input, runtime = {}) { } } +function verifyFabricApplyReceipt(workspaceRoot, config, receipt, runtime = {}) { + let policy; + try { policy = applicatorPolicy(config); } catch (error) { return { ok: false, error: error.message }; } + const stateKey = resolveStateKey(policy, runtime); + if (typeof stateKey !== "string" || Buffer.byteLength(stateKey, "utf8") < 32) return { ok: false, error: "applicator verifier key is not configured" }; + const key = Buffer.from(stateKey, "utf8"); + if (!isPlainObject(receipt) || receipt.kind !== "apply" || !/^decision-[0-9a-f]{40}$/.test(String(receipt.decisionId ?? ""))) return { ok: false, error: "apply receipt is invalid" }; + const map = readJson(workspaceRoot, decisionMapPath(workspaceRoot, receipt.decisionId), "applicator decision map"); + if (!map.ok || map.record.schema !== `${APPLICATOR_SCHEMA}/decision-map` + || map.record.decisionId !== receipt.decisionId || !/^apply-[0-9a-f]{40}$/.test(String(map.record.applyId ?? "")) + || !secureDigestEqual(artifactMac(key, map.record), map.record.artifactMac)) return { ok: false, error: "applicator decision map is invalid" }; + const loaded = readJson(workspaceRoot, statePath(workspaceRoot, map.record.applyId), "applicator state"); + if (!loaded.ok || !validState(loaded.record, key) || !["receipt_queued", "fabric_acked"].includes(loaded.record.phase)) return { ok: false, error: "applicator state is not receipt-ready" }; + const expected = buildFabricApplyReceipt(loaded.record.receipt); + if (!expected.ok || canonicalize(expected.receipt) !== canonicalize(receipt)) return { ok: false, error: "apply receipt does not match authenticated state" }; + const archiveAbsolute = path.join(workspaceRoot, "memory", "maintenance", "proposals", `${loaded.record.proposalId}.applied.json`); + let archiveText; + try { archiveText = readFileNoFollowSync(workspaceRoot, archiveAbsolute); } + catch { return { ok: false, error: "apply archive is unavailable" }; } + if (sha256(archiveText) !== receipt.archiveDigest) return { ok: false, error: "apply archive digest mismatch" }; + const index = readJson(workspaceRoot, path.join(workspaceRoot, policy.recordIndexPath), "AMF record index"); + const entry = index.ok && index.record.schema === "amf-record-index/v1" && isPlainObject(index.record.records) + ? index.record.records[receipt.canonicalRecordId] + : null; + if (!isPlainObject(entry) || !isAmfRecordPath(entry.path)) return { ok: false, error: "canonical record index entry is missing" }; + let metadata; + try { metadata = parseMemoryRecord(readFileNoFollowSync(workspaceRoot, path.join(workspaceRoot, entry.path))).metadata; } + catch { return { ok: false, error: "canonical target is unavailable or invalid" }; } + if (metadata.id !== receipt.canonicalRecordId || metadata.revision !== receipt.revision + || entry.scope !== metadata.scope.id + || metadata.lifecycle.status !== receipt.canonicalLifecycleAtDecision + || sha256(canonicalize(metadata)) !== receipt.targetDigest) return { ok: false, error: "canonical target digest mismatch" }; + return { ok: true, verified: true, archiveDigest: receipt.archiveDigest, targetDigest: receipt.targetDigest, revision: receipt.revision }; +} + +function loadFabricApplyReceiptForDispatch(workspaceRoot, config, input, runtime = {}) { + if (!exactKeys(input, new Set(["decisionId"])) || !/^decision-[0-9a-f]{40}$/.test(String(input.decisionId ?? ""))) return { ok: false, error: "decisionId is invalid" }; + 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 map = readJson(workspaceRoot, decisionMapPath(workspaceRoot, input.decisionId), "applicator decision map"); + if (!map.ok || !secureDigestEqual(artifactMac(authorized.key, map.record), map.record.artifactMac)) return { ok: false, error: "applicator decision map is invalid" }; + const loaded = readJson(workspaceRoot, statePath(workspaceRoot, map.record.applyId), "applicator state"); + if (!loaded.ok || !validState(loaded.record, authorized.key) || !["receipt_queued", "fabric_acked"].includes(loaded.record.phase)) return { ok: false, error: "apply receipt is not ready" }; + const fabric = buildFabricApplyReceipt(loaded.record.receipt); + return fabric.ok ? { ok: true, applyId: loaded.record.applyId, status: loaded.record.phase, receipt: fabric.receipt } : fabric; +} + +function recordFabricApplyAck(workspaceRoot, config, input, runtime = {}) { + if (!exactKeys(input, new Set(["decisionId", "receipt", "ackId", "acknowledgedAt"])) + || !/^decision-[0-9a-f]{40}$/.test(String(input.decisionId ?? "")) + || typeof input.ackId !== "string" || input.ackId.length < 1 || input.ackId.length > 256 + || typeof input.acknowledgedAt !== "string" || !Number.isFinite(Date.parse(input.acknowledgedAt))) return { ok: false, error: "Fabric apply ack is invalid" }; + 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 map = readJson(workspaceRoot, decisionMapPath(workspaceRoot, input.decisionId), "applicator decision map"); + if (!map.ok || !secureDigestEqual(artifactMac(authorized.key, map.record), map.record.artifactMac)) return { ok: false, error: "applicator decision map is invalid" }; + const lock = acquireExclusiveLock(workspaceRoot, path.join(workspaceRoot, APPLICATOR_ROOT, `${map.record.applyId}.lock`)); + try { + const loaded = readJson(workspaceRoot, statePath(workspaceRoot, map.record.applyId), "applicator state"); + if (!loaded.ok || !validState(loaded.record, authorized.key) || !["receipt_queued", "fabric_acked"].includes(loaded.record.phase)) return { ok: false, error: "apply receipt is not ready" }; + const fabric = buildFabricApplyReceipt(loaded.record.receipt); + if (!fabric.ok || canonicalize(fabric.receipt) !== canonicalize(input.receipt)) return { ok: false, error: "Fabric apply ack receipt mismatch" }; + const ack = { ackId: input.ackId, acknowledgedAt: input.acknowledgedAt }; + if (loaded.record.phase === "fabric_acked") { + return canonicalize(loaded.record.ack) === canonicalize(ack) ? { ok: true, duplicate: true, status: "fabric_acked" } : { ok: false, error: "Fabric apply ack conflict" }; + } + writeState(workspaceRoot, authorized.key, { ...loaded.record, phase: "fabric_acked", ack }); + return { ok: true, duplicate: false, status: "fabric_acked" }; + } finally { lock.release(); } +} + export { APPLICATOR_ROOT, APPLICATOR_SCHEMA, DEFAULT_APPLICATOR, applicatorPolicy, - applyDecisionReceipt + applyDecisionReceipt, + buildFabricApplyReceipt, + deliverAppliedMemoryToGit, + loadFabricApplyReceiptForDispatch, + recordFabricApplyAck, + verifyFabricApplyReceipt }; diff --git a/tools/lib/secure-fs.mjs b/tools/lib/secure-fs.mjs index a84e8b6..c306c87 100644 --- a/tools/lib/secure-fs.mjs +++ b/tools/lib/secure-fs.mjs @@ -44,6 +44,35 @@ function readFileNoFollowSync(workspaceRoot, absolutePath, encoding = "utf8") { } } +function readOwnerOnlyFileSync(filename, options = {}) { + if (typeof filename !== "string" || !path.isAbsolute(filename)) throw new Error(`${options.label ?? "private file"} path must be absolute`); + const absolute = path.resolve(filename); + const parent = path.dirname(absolute); + const basename = path.basename(absolute); + const maxBytes = options.maxBytes ?? 8 * 1024 * 1024; + let parentFd; + let fd; + try { + parentFd = fs.openSync(parent, fs.constants.O_RDONLY | (fs.constants.O_DIRECTORY ?? 0) | (fs.constants.O_NOFOLLOW ?? 0)); + const parentStat = fs.fstatSync(parentFd); + const parentHandle = `/proc/self/fd/${parentFd}`; + if (!parentStat.isDirectory() || (parentStat.mode & 0o022) !== 0 + || (typeof process.geteuid === "function" && parentStat.uid !== process.geteuid()) + || fs.realpathSync(parentHandle) !== parent) throw new Error("parent is unsafe"); + fd = fs.openSync(`${parentHandle}/${basename}`, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0)); + const stat = fs.fstatSync(fd); + if (!stat.isFile() || stat.nlink !== 1 || (stat.mode & 0o777) !== 0o600 + || (typeof process.geteuid === "function" && stat.uid !== process.geteuid()) + || stat.size < 1 || stat.size > maxBytes) throw new Error("file is unsafe"); + return fs.readFileSync(fd, options.encoding ?? "utf8"); + } catch { + throw new Error(`${options.label ?? "private file"} must be read through an owner-owned non-writable parent and a mode 0600 regular file`); + } finally { + if (fd !== undefined) fs.closeSync(fd); + if (parentFd !== undefined) fs.closeSync(parentFd); + } +} + function atomicWriteFileSync(workspaceRoot, absolutePath, content, options = {}) { const target = assertNoSymlinkPath(workspaceRoot, absolutePath); const parent = path.dirname(target); @@ -350,5 +379,6 @@ export { assertNoSymlinkPath, atomicWriteFileSync, readFileNoFollowSync, + readOwnerOnlyFileSync, removeRegularFileNoFollowSync }; diff --git a/tools/lib/workspace.mjs b/tools/lib/workspace.mjs index 95ff1f8..fa88e76 100644 --- a/tools/lib/workspace.mjs +++ b/tools/lib/workspace.mjs @@ -2,7 +2,8 @@ import fs from "node:fs"; import path from "node:path"; import { fileURLToPath } from "node:url"; -import { loadConfig } from "../memory-maintenance.mjs"; +import { loadConfig, parseConfig } from "../memory-maintenance.mjs"; +import { readOwnerOnlyFileSync } from "./secure-fs.mjs"; const __filename = fileURLToPath(import.meta.url); const __dirname = path.dirname(__filename); @@ -18,6 +19,10 @@ function workspaceConfigPath(workspaceRoot) { } function loadWorkspaceConfig(workspaceRoot = DEFAULT_WORKSPACE_ROOT) { + const external = process.env.PAM_WORKSPACE_CONFIG; + if (external) { + return parseConfig(readOwnerOnlyFileSync(external, { label: "PAM_WORKSPACE_CONFIG", maxBytes: 1024 * 1024 })); + } const configPath = workspaceConfigPath(workspaceRoot); if (fs.existsSync(configPath)) { return loadConfig(configPath); diff --git a/tools/memory-maintenance.config.json b/tools/memory-maintenance.config.json index b30e2d8..7ecce89 100644 --- a/tools/memory-maintenance.config.json +++ b/tools/memory-maintenance.config.json @@ -80,12 +80,29 @@ "amfApplicator": { "version": "amf-receipt-applicator/v1", "tokenEnv": "PAM_APPLICATOR_TOKEN", + "stateKeyEnv": "PAM_APPLICATOR_STATE_KEY", + "stateKeyFileEnv": "PAM_APPLICATOR_STATE_KEY_FILE", + "recordIndexPath": "memory/amf/record-index.json", "applicators": [], + "gitWriter": { + "enabled": false, + "repoRootEnv": "PAM_GIT_WRITER_REPO_ROOT", + "allowedBranches": [], + "push": { "enabled": false, "remote": null, "allowedRemotes": [] } + }, "transport": { "kind": "disabled", "endpointEnv": "PAM_FABRIC_RECEIPT_ENDPOINT" } }, + "amfFabricTransport": { + "version": "amf-fabric-transport/v1", + "baseUrlEnv": "PAM_FABRIC_BASE_URL", + "curatorTokenFileEnv": "PAM_FABRIC_CURATOR_TOKEN_FILE", + "applicatorTokenFileEnv": "PAM_FABRIC_APPLICATOR_TOKEN_FILE", + "timeoutMs": 10000, + "maxResponseBytes": 1048576 + }, "workspace": { "name": "Example Memory Workspace", "description": "Markdown-based memory workspace maintained by an AI agent.", diff --git a/tools/memory-maintenance.mjs b/tools/memory-maintenance.mjs index 8cd6db0..3858f33 100644 --- a/tools/memory-maintenance.mjs +++ b/tools/memory-maintenance.mjs @@ -15,8 +15,7 @@ const ISO_DATE_TITLE_RE = /^## (\d{4}-\d{2}-\d{2}) - .+$/; const TEMP_WORKSPACE_IGNORED_PREFIXES = [".codex/", ".claude/", ".opencode/"]; const TEMP_WORKSPACE_IGNORED_PATHS = new Set([".codex", ".claude", ".opencode"]); -function loadConfig(configPath = CONFIG_PATH) { - const raw = fs.readFileSync(configPath, "utf8"); +function parseConfig(raw) { const config = JSON.parse(raw); if (!Array.isArray(config.managedLogs) || config.managedLogs.length === 0) { @@ -28,6 +27,10 @@ function loadConfig(configPath = CONFIG_PATH) { return config; } +function loadConfig(configPath = CONFIG_PATH) { + return parseConfig(fs.readFileSync(configPath, "utf8")); +} + function normalizeSynthesisConfig(input) { const synthesis = input && typeof input === "object" ? { ...input } : {}; @@ -1135,6 +1138,7 @@ export { getArchiveRelativePath, getQuarterInfo, loadConfig, + parseConfig, parseLogSections, regenerateArchiveIndexes, renderRunReport, diff --git a/tools/test-amf-fabric-transport.mjs b/tools/test-amf-fabric-transport.mjs new file mode 100644 index 0000000..837b747 --- /dev/null +++ b/tools/test-amf-fabric-transport.mjs @@ -0,0 +1,221 @@ +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 { aadSha256For, canonicalize, renderMemoryRecord } from "./lib/amf-memory-record.mjs"; +import { dispatchFabricApplyReceipt, drainFabricProposals, intakeFabricProposal, replayFabricDecisionOutbox } from "./lib/amf-fabric-transport.mjs"; +import { applyDecisionReceipt, buildFabricApplyReceipt, deliverAppliedMemoryToGit, verifyFabricApplyReceipt } from "./lib/memory-receipt-applicator.mjs"; + +const LEDGER_KEY = "fabric-transport-ledger-key-0000000000000000000000001"; +const REVIEWER_TOKEN = "fabric-transport-reviewer-token-0001"; +const APPLICATOR_TOKEN = "fabric-transport-applicator-token-0001"; +const STATE_KEY = "fabric-transport-state-key-0000000000000000000000001"; +const PROPOSAL_ID = "proposal-transport-0001"; + +function sha(value) { return crypto.createHash("sha256").update(String(value)).digest("hex"); } +function workspace() { + const root = fs.mkdtempSync(path.join(os.tmpdir(), "pam-fabric-transport-")); + 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), ""); + return root; +} +function privateFile(root, name, value, mode = 0o600) { const file = path.join(root, name); fs.writeFileSync(file, `${value}\n`, { mode }); fs.chmodSync(file, mode); return file; } +function git(root, args) { const result = spawnSync("git", args, { cwd: root, encoding: "utf8" }); if (result.status !== 0) throw new Error(`git failed: ${args[0]}`); return result.stdout.trim(); } +function initializeGit(root) { + const remote = fs.mkdtempSync(path.join(os.tmpdir(), "pam-fabric-remote-")); git(remote, ["init", "--bare"]); + git(root, ["init", "-b", "curated"]); git(root, ["config", "user.name", "PAM Test"]); git(root, ["config", "user.email", "pam@example.invalid"]); + fs.writeFileSync(path.join(root, ".gitignore"), "memory/amf/curator/\nmemory/amf/curator.initialized.json\nmemory/amf/applicator/\nmemory/maintenance/\n"); + git(root, ["add", ".gitignore", "memory/graph"]); git(root, ["commit", "-m", "test: baseline"]); git(root, ["remote", "add", "origin", remote]); + return remote; +} +function record() { + const timestamp = "2026-07-12T12:00:00Z"; + const value = { + schema: "amf-memory/v1", id: "mem_transport_00000001", revision: 1, claimType: "fact", + scope: { type: "room", id: "room:vitae:joseph-dm" }, visibility: "shared", + confidence: { score: 0.995, basis: "reviewed", assessedAt: timestamp }, + subjects: [{ identityId: "agent:vitae", role: "owner" }], + claim: { encoding: "sealed", alg: "AES-256-GCM", kekId: "kek:transport-v1", keyRef: "key:transport-v1", iv: Buffer.alloc(12, 1).toString("base64"), ciphertext: Buffer.from("A bounded synthetic transport fact.").toString("base64"), tag: Buffer.alloc(16, 2).toString("base64"), aadSha256: "" }, + lifecycle: { status: "active", validFrom: timestamp, validTo: null, supersedes: [], revokedAt: null, revocationReason: null }, + provenance: [{ sourceType: "synthetic-test", sourceId: "transport-test", eventId: "event-transport-0001", contentSha256: "a".repeat(64), capturedAt: timestamp }], + createdAt: timestamp, updatedAt: timestamp + }; + value.claim.aadSha256 = aadSha256For(value); + return value; +} +function config(root) { + const secretRoot = fs.mkdtempSync(path.join(os.tmpdir(), "pam-fabric-secrets-")); + const curator = privateFile(secretRoot, "curator.token", "curator-fabric-bearer-0001"); + const applicator = privateFile(secretRoot, "applicator.token", "applicator-fabric-bearer-0001"); + const stateKey = privateFile(secretRoot, "applicator-state.key", STATE_KEY); + return { + config: { + managedLogs: [{ source: "memory/knowledge-log.md", archiveKey: "knowledge", activeEntryLimit: 10 }], + protectedPaths: ["AGENTS.md", "memory/agent-memory", "memory/sources"], + amfCurator: { + version: "amf-curator-policy/v1", autoPromote: true, minimumConfidence: 0.98, + autoScopes: ["room"], autoVisibilities: ["shared"], requireReviewForLifecycleChange: false, + requireReviewForSupersession: true, rejectOnWarnings: true, ledgerKeyEnv: "PAM_CURATOR_LEDGER_KEY", + stateDirEnv: "PAM_CURATOR_STATE_DIR", reviewerTokenEnv: "PAM_CURATOR_REVIEWER_TOKEN", + reviewers: [{ tokenSha256: sha(REVIEWER_TOKEN), actorId: "service:transport-curator", capabilities: ["memory:curate"] }], + gitWriter: { enabled: false, dryRunOnly: true, protectedBranches: ["main"] } + }, + amfApplicator: { + version: "amf-receipt-applicator/v1", tokenEnv: "PAM_APPLICATOR_TOKEN", stateKeyEnv: "PAM_APPLICATOR_STATE_KEY", + recordIndexPath: "memory/amf/record-index.json", + applicators: [{ tokenSha256: sha(APPLICATOR_TOKEN), actorId: "service:transport-applicator", capabilities: ["memory:apply-receipt"] }], + transport: { kind: "disabled", endpointEnv: "PAM_FABRIC_RECEIPT_ENDPOINT" } + }, + amfFabricTransport: { + version: "amf-fabric-transport/v1", baseUrlEnv: "PAM_FABRIC_BASE_URL", + curatorTokenFileEnv: "PAM_FABRIC_CURATOR_TOKEN_FILE", applicatorTokenFileEnv: "PAM_FABRIC_APPLICATOR_TOKEN_FILE", + timeoutMs: 1000, maxResponseBytes: 65536 + } + }, + env: { PAM_FABRIC_BASE_URL: "https://fabric.example.test", PAM_FABRIC_CURATOR_TOKEN_FILE: curator, PAM_FABRIC_APPLICATOR_TOKEN_FILE: applicator, PAM_APPLICATOR_STATE_KEY_FILE: stateKey } + }; +} + +test("bounded curator drain, separate applicator, atomic index and Fabric receipts converge", async () => { + const root = workspace(); const state = fs.mkdtempSync(path.join(os.tmpdir(), "pam-fabric-state-")); fs.chmodSync(state, 0o700); + const remote = initializeGit(root); const fixture = config(root); + fixture.config.amfApplicator.gitWriter = { enabled: true, repoRootEnv: "PAM_GIT_WRITER_REPO_ROOT", allowedBranches: ["curated"], push: { enabled: true, remote: "origin", allowedRemotes: ["origin"] } }; + fixture.env.PAM_GIT_WRITER_REPO_ROOT = root; + const payload = { type: "canonical-memory-proposal", actor: "agent:vitae", scope: record().scope.id, record: record(), rationale: "synthetic evidence", expectedRevision: 0 }; + const proposalDigest = sha(canonicalize(payload)); const roles = []; + const runtime = { + env: fixture.env, ledgerKey: LEDGER_KEY, reviewerToken: REVIEWER_TOKEN, stateDir: state, + requestJson: async request => { + roles.push(request.token); + if (request.method === "GET" && request.pathname.startsWith("/v2/internal/curation/proposals?")) return { ok: true, data: { items: [{ proposalId: PROPOSAL_ID, status: "queued", createdAt: "2026-07-12T12:00:00Z" }], nextCursor: null }, meta: { requestId: "ack-list" } }; + if (request.method === "GET") return { ok: true, data: { proposalId: PROPOSAL_ID, status: "queued", payload, proposalDigest }, meta: { requestId: "ack-read" } }; + const expectedStatus = request.body.kind === "decision" ? request.body.status : "promoted"; + return { ok: true, data: { proposalId: PROPOSAL_ID, status: expectedStatus }, meta: { requestId: `ack-${request.body.kind}` } }; + } + }; + const drained = await drainFabricProposals(root, fixture.config, { limit: 1, dispatch: true }, runtime); + assert.equal(drained.ok, true, JSON.stringify(drained)); assert.equal(drained.processed, 1); + const decisionId = drained.results[0].decisionId; + assert.equal(drained.results[0].status, "approved_pending_apply"); + assert.equal(fs.existsSync(path.join(root, `memory/amf/records/${record().id}.md`)), false); + const prematureDelivery = deliverAppliedMemoryToGit(root, fixture.config, { decisionId, push: false }, { ...runtime, applicatorToken: APPLICATOR_TOKEN, stateKey: STATE_KEY }); + assert.equal(prematureDelivery.ok, false); + assert.match(prematureDelivery.error, /receipt-ready/); + + const applied = applyDecisionReceipt(root, fixture.config, { decisionId, idempotencyKey: "fabric-apply-transport-0001" }, { ...runtime, applicatorToken: APPLICATOR_TOKEN }); + assert.equal(applied.ok, true, applied.error); assert.equal(applied.status, "receipt_queued"); + const index = JSON.parse(fs.readFileSync(path.join(root, "memory/amf/record-index.json"), "utf8")); + assert.deepEqual(index.records[record().id].contextRefs, { conversation: ["room:vitae:joseph-dm"], room: ["room:vitae:joseph-dm"] }); + const fabricApply = buildFabricApplyReceipt(applied.receipt); + assert.equal(fabricApply.ok, true); + assert.equal(verifyFabricApplyReceipt(root, fixture.config, fabricApply.receipt, { stateKey: STATE_KEY }).verified, true); + fs.writeFileSync(path.join(root, "unrelated.txt"), "unrelated\n"); + const unrelated = deliverAppliedMemoryToGit(root, fixture.config, { decisionId, push: false }, { ...runtime, applicatorToken: APPLICATOR_TOKEN, stateKey: STATE_KEY }); + assert.equal(unrelated.ok, false); assert.match(unrelated.error, /unrelated/); fs.unlinkSync(path.join(root, "unrelated.txt")); + const hook = path.join(root, ".git/hooks/pre-commit"); fs.writeFileSync(hook, "#!/bin/sh\nexit 1\n", { mode: 0o700 }); + const failedCommit = deliverAppliedMemoryToGit(root, fixture.config, { decisionId, push: false }, { ...runtime, applicatorToken: APPLICATOR_TOKEN, stateKey: STATE_KEY }); + assert.equal(failedCommit.ok, false); assert.match(failedCommit.error, /staging rolled back/); assert.equal(spawnSync("git", ["diff", "--cached", "--quiet"], { cwd: root }).status, 0); + fs.unlinkSync(hook); + const committed = deliverAppliedMemoryToGit(root, fixture.config, { decisionId, push: false }, { ...runtime, applicatorToken: APPLICATOR_TOKEN, stateKey: STATE_KEY }); + assert.equal(committed.ok, true, committed.error); assert.equal(committed.status, "committed"); + git(root, ["checkout", "-b", "curated-alt"]); + const branchRetryConfig = structuredClone(fixture.config); branchRetryConfig.amfApplicator.gitWriter.allowedBranches.push("curated-alt"); + const wrongAllowlistedBranch = deliverAppliedMemoryToGit(root, branchRetryConfig, { decisionId, push: false }, { ...runtime, applicatorToken: APPLICATOR_TOKEN, stateKey: STATE_KEY }); + assert.equal(wrongAllowlistedBranch.ok, false); assert.match(wrongAllowlistedBranch.error, /delivery state/); + git(root, ["checkout", "curated"]); + assert.equal(git(root, ["ls-remote", "--heads", remote, "refs/heads/curated"]), "", "push must never be implicit"); + const competing = fs.mkdtempSync(path.join(os.tmpdir(), "pam-fabric-competing-")); git(competing, ["init", "-b", "curated"]); git(competing, ["config", "user.name", "Other"]); git(competing, ["config", "user.email", "other@example.invalid"]); fs.writeFileSync(path.join(competing, "other.txt"), "other\n"); git(competing, ["add", "other.txt"]); git(competing, ["commit", "-m", "other root"]); git(competing, ["remote", "add", "origin", remote]); git(competing, ["push", "origin", "curated"]); + const nonFastForward = deliverAppliedMemoryToGit(root, fixture.config, { decisionId, push: true }, { ...runtime, applicatorToken: APPLICATOR_TOKEN, stateKey: STATE_KEY }); + assert.equal(nonFastForward.ok, false); assert.match(nonFastForward.error, /not fast-forward/); + git(competing, ["push", "origin", "--delete", "curated"]); + const pushed = deliverAppliedMemoryToGit(root, fixture.config, { decisionId, push: true }, { ...runtime, applicatorToken: APPLICATOR_TOKEN, stateKey: STATE_KEY }); + assert.equal(pushed.ok, true, pushed.error); assert.equal(pushed.status, "pushed"); assert.equal(git(remote, ["rev-parse", "refs/heads/curated"]), pushed.commit); + const deliveryRetry = deliverAppliedMemoryToGit(root, fixture.config, { decisionId, push: true }, { ...runtime, applicatorToken: APPLICATOR_TOKEN, stateKey: STATE_KEY }); + assert.equal(deliveryRetry.ok, true); assert.equal(deliveryRetry.duplicate, true); assert.equal(deliveryRetry.commit, pushed.commit); + const wrongBranchConfig = structuredClone(fixture.config); wrongBranchConfig.amfApplicator.gitWriter.allowedBranches = ["other"]; + assert.match(deliverAppliedMemoryToGit(root, wrongBranchConfig, { decisionId, push: false }, { ...runtime, applicatorToken: APPLICATOR_TOKEN, stateKey: STATE_KEY }).error, /branch/); + await assert.rejects(() => dispatchFabricApplyReceipt(root, fixture.config, { decisionId }, { ...runtime, applicatorToken: APPLICATOR_TOKEN, stateKey: STATE_KEY, faultAt: "after-apply-ack" }), /after apply ACK/); + const acked = await dispatchFabricApplyReceipt(root, fixture.config, { decisionId }, { ...runtime, applicatorToken: APPLICATOR_TOKEN, stateKey: STATE_KEY }); + assert.equal(acked.ok, true, acked.error); assert.equal(acked.status, "fabric_acked"); + assert.ok(roles.includes("curator-fabric-bearer-0001")); assert.ok(roles.includes("applicator-fabric-bearer-0001")); +}); + +test("multi-page drain is bounded, redacted, and replays a crash after decision ACK", async () => { + const root = workspace(); const state = fs.mkdtempSync(path.join(os.tmpdir(), "pam-fabric-state-")); fs.chmodSync(state, 0o700); + const fixture = config(root); const payload = { type: "canonical-memory-proposal", actor: "agent:vitae", scope: record().scope.id, record: record(), rationale: "synthetic evidence", expectedRevision: 0 }; + const digest = sha(canonicalize(payload)); let decisionPosts = 0; + const requestJson = async request => { + if (request.method === "GET" && request.pathname.startsWith("/v2/internal/curation/proposals?")) { + const second = request.pathname.includes("cursor=page-two"); + return { ok: true, data: { items: [{ proposalId: second ? "proposal-page-0002" : "proposal-page-0001", status: "queued", createdAt: "2026-07-12T12:00:00Z" }], nextCursor: second ? null : "page-two" }, meta: { requestId: "ack-list" } }; + } + if (request.method === "GET") { + const proposalId = request.pathname.endsWith("0002") ? "proposal-page-0002" : "proposal-page-0001"; + return { ok: true, data: { proposalId, status: "queued", payload, proposalDigest: digest }, meta: { requestId: "ack-read" } }; + } + decisionPosts += 1; + return { ok: true, data: { proposalId: request.body.proposalId, status: request.body.status, decision: request.body }, meta: { requestId: `ack-decision-${decisionPosts}` } }; + }; + const runtime = { env: fixture.env, ledgerKey: LEDGER_KEY, reviewerToken: REVIEWER_TOKEN, stateDir: state, requestJson }; + const drained = await drainFabricProposals(root, fixture.config, { limit: 1, maxPages: 2, dispatch: false }, runtime); + assert.equal(drained.processed, 2); assert.equal(drained.pages, 2); assert.equal(drained.nextCursor, null); + assert.equal(JSON.stringify(drained).includes("ciphertext"), false); assert.equal(JSON.stringify(drained).includes("claim"), false); + await assert.rejects(() => intakeFabricProposal(root, fixture.config, { proposalId: "proposal-page-0001", dispatch: true }, { ...runtime, faultAt: "after-decision-ack" }), /after decision ACK/); + const replayed = await replayFabricDecisionOutbox(root, fixture.config, { limit: 10 }, runtime); + assert.equal(replayed.ok, true); assert.ok(replayed.results.some(item => item.duplicate === false)); +}); + +test("Fabric binding retry, token file modes and response digests fail closed", async () => { + const root = workspace(); const state = fs.mkdtempSync(path.join(os.tmpdir(), "pam-fabric-state-")); fs.chmodSync(state, 0o700); + const fixture = config(root); const payload = { type: "canonical-memory-proposal", actor: "agent:vitae", scope: record().scope.id, record: record(), rationale: "synthetic evidence", expectedRevision: 0 }; + const runtime = { env: fixture.env, ledgerKey: LEDGER_KEY, reviewerToken: REVIEWER_TOKEN, stateDir: state, requestJson: async request => ({ ok: true, data: request.method === "GET" ? { proposalId: PROPOSAL_ID, status: "queued", payload, proposalDigest: "b".repeat(64) } : {}, meta: { requestId: "ack" } }) }; + await assert.rejects(() => intakeFabricProposal(root, fixture.config, { proposalId: PROPOSAL_ID, dispatch: false }, runtime), /binding/); + fs.chmodSync(fixture.env.PAM_FABRIC_CURATOR_TOKEN_FILE, 0o644); + await assert.rejects(() => intakeFabricProposal(root, fixture.config, { proposalId: PROPOSAL_ID, dispatch: false }, runtime), /0600/); + fs.chmodSync(fixture.env.PAM_FABRIC_CURATOR_TOKEN_FILE, 0o600); + const secretParent = path.dirname(fixture.env.PAM_FABRIC_CURATOR_TOKEN_FILE); + fs.chmodSync(secretParent, 0o777); + await assert.rejects(() => intakeFabricProposal(root, fixture.config, { proposalId: PROPOSAL_ID, dispatch: false }, runtime), /non-writable parent/); + fs.chmodSync(secretParent, 0o700); + const linkedParent = path.join(os.tmpdir(), `pam-secret-link-${crypto.randomBytes(6).toString("hex")}`); + fs.symlinkSync(secretParent, linkedParent); + const linkedFixture = structuredClone(fixture); linkedFixture.env.PAM_FABRIC_CURATOR_TOKEN_FILE = path.join(linkedParent, path.basename(fixture.env.PAM_FABRIC_CURATOR_TOKEN_FILE)); + await assert.rejects(() => intakeFabricProposal(root, linkedFixture.config, { proposalId: PROPOSAL_ID, dispatch: false }, { ...runtime, env: linkedFixture.env }), /non-writable parent/); + fs.unlinkSync(linkedParent); + assert.equal(renderMemoryRecord(record()).includes("A bounded synthetic transport fact"), false); +}); + +test("decision replay scans past an ACK prefix and persists an authenticated bounded cursor", async () => { + const root = workspace(); const state = fs.mkdtempSync(path.join(os.tmpdir(), "pam-fabric-state-")); fs.chmodSync(state, 0o700); + const fixture = config(root); const proposals = new Map(); let posts = 0; + for (let index = 1; index <= 4; index += 1) { + const proposalId = `proposal-starvation-000${index}`; + const candidate = record(); candidate.id = `mem_transport_0000000${index}`; + candidate.claim.ciphertext = Buffer.from(`bounded-${index}`).toString("base64"); + candidate.provenance[0].eventId = `event-transport-000${index}`; + candidate.provenance[0].contentSha256 = String(index).repeat(64); + candidate.claim.aadSha256 = aadSha256For(candidate); + const payload = { type: "canonical-memory-proposal", actor: "agent:vitae", scope: candidate.scope.id, record: candidate, rationale: `synthetic evidence ${index}`, expectedRevision: 0 }; + proposals.set(proposalId, { proposalId, status: "queued", payload, proposalDigest: sha(canonicalize(payload)) }); + } + const runtime = { + env: fixture.env, ledgerKey: LEDGER_KEY, reviewerToken: REVIEWER_TOKEN, stateDir: state, + requestJson: async request => { + if (request.method === "GET") return { ok: true, data: proposals.get(decodeURIComponent(request.pathname.split("/").at(-1))), meta: { requestId: "ack-read" } }; + posts += 1; return { ok: true, data: { proposalId: request.body.proposalId, status: request.body.status }, meta: { requestId: `ack-${posts}` } }; + } + }; + for (const proposalId of proposals.keys()) assert.equal((await intakeFabricProposal(root, fixture.config, { proposalId, dispatch: false }, runtime)).ok, true); + const first = await replayFabricDecisionOutbox(root, fixture.config, { limit: 3, maxPages: 1 }, runtime); + assert.equal(first.processed, 3); assert.equal(first.scanned, 3); + const cursorPath = path.join(root, "memory/amf/curator/fabric-replay-cursor.json"); + assert.equal(fs.existsSync(cursorPath), true); + fs.unlinkSync(cursorPath); // Force the repro shape: ACK prefix larger than the next action limit. + const second = await replayFabricDecisionOutbox(root, fixture.config, { limit: 1, maxPages: 4 }, runtime); + assert.equal(second.processed, 1); assert.equal(second.scanned, 4); assert.equal(second.results[0].duplicate, false); + assert.equal(posts, 4); +}); diff --git a/tools/test-memory-curator.mjs b/tools/test-memory-curator.mjs index 2ad2022..5b026be 100644 --- a/tools/test-memory-curator.mjs +++ b/tools/test-memory-curator.mjs @@ -17,6 +17,7 @@ import { submitCuratorCandidate } from "./lib/memory-curator.mjs"; import { applyDecisionReceipt } from "./lib/memory-receipt-applicator.mjs"; +import { canonicalize, parseMemoryRecord } from "./lib/amf-memory-record.mjs"; const IDS = { first: "mem_11111111-1111-4111-8111-111111111111", @@ -27,11 +28,13 @@ const IDS = { 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 APPLICATOR_STATE_KEY = "synthetic-applicator-state-key-0000000000000000000001"; 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_APPLICATOR_STATE_KEY = APPLICATOR_STATE_KEY; 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"); @@ -60,6 +63,8 @@ const defaultConfig = { amfApplicator: { version: "amf-receipt-applicator/v1", tokenEnv: "PAM_APPLICATOR_TOKEN", + stateKeyEnv: "PAM_APPLICATOR_STATE_KEY", + recordIndexPath: "memory/amf/record-index.json", applicators: [{ tokenSha256: applicatorTokenSha256, actorId: "service:synthetic-applicator", @@ -489,7 +494,7 @@ test("applicator receipt binds the exact archive and canonical target", () => { 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.targetDigest, crypto.createHash("sha256").update(canonicalize(parseMemoryRecord(submission().content).metadata)).digest("hex")); assert.equal(applied.receipt.decisionDigest, approved.decisionDigest); assert.equal(applied.receipt.canonicalLifecycleAtDecision, "active"); }); diff --git a/tools/test-pam-mcp-server.mjs b/tools/test-pam-mcp-server.mjs index ff1fa2c..2483fef 100644 --- a/tools/test-pam-mcp-server.mjs +++ b/tools/test-pam-mcp-server.mjs @@ -18,6 +18,7 @@ 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_APPLICATOR_STATE_KEY = "synthetic-applicator-state-key-0000000000000000000001"; process.env.PAM_CURATOR_STATE_DIR = CURATOR_STATE_DIR; function makeWorkspace() { @@ -98,6 +99,8 @@ function makeWorkspace() { amfApplicator: { version: "amf-receipt-applicator/v1", tokenEnv: "PAM_APPLICATOR_TOKEN", + stateKeyEnv: "PAM_APPLICATOR_STATE_KEY", + recordIndexPath: "memory/amf/record-index.json", applicators: [{ tokenSha256: crypto.createHash("sha256").update(APPLICATOR_TOKEN).digest("hex"), actorId: "service:mcp-applicator",