Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
60 changes: 55 additions & 5 deletions docs/amf-curator.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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": "<sha256>",
"actorId": "service:memory-applicator",
Expand All @@ -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"
}
}
```
Expand All @@ -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 <decision-id>
npm run memory:fabric-worker -- git-deliver --decision-id <decision-id>
npm run memory:fabric-worker -- git-deliver --decision-id <decision-id> --push
```

MCP adds `memory_receipt_apply` alongside `memory_curator_submit`,
Expand Down
13 changes: 11 additions & 2 deletions memory/pam.version.json
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
{
"pamVersion": "0.6.2",
"pamVersion": "0.6.3",
"memoryFormat": "graph-v1",
"graphSchemaVersion": "pam-graph-v1",
"features": {
Expand Down Expand Up @@ -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"
}
35 changes: 35 additions & 0 deletions migrations/0.6.2-to-0.6.3-fabric-promotion-transport.md
Original file line number Diff line number Diff line change
@@ -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.
3 changes: 2 additions & 1 deletion package.json
Original file line number Diff line number Diff line change
@@ -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",
Expand All @@ -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",
Expand Down
43 changes: 43 additions & 0 deletions tools/amf-fabric-worker.mjs
Original file line number Diff line number Diff line change
@@ -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; });
Loading