@aiwg/cli 2026.10.5 → 2026.10.7

package/dist/src/memory/canonical-context.js

@@ -1,14 +1,20 @@
-import { closeSync, existsSync, mkdirSync, openSync, readFileSync, realpathSync, renameSync, unlinkSync, writeFileSync, } from 'node:fs';
-import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, linkSync, statSync, readFileSync, realpathSync, renameSync, unlinkSync, writeFileSync, } from 'node:fs';
+import { createHash, randomUUID } from 'node:crypto';
 import { dirname, relative, resolve, sep } from 'node:path';
+import { hostname } from 'node:os';
+import { isDeepStrictEqual } from 'node:util';
 import { z } from 'zod';
+import { dateTime } from '../schema/zod-validation.mjs';
+import { validateMaintenancePlan } from './maintenance-contract.js';
+import { loadMemoryRecord, memoryRecordId } from './maintenance-record.js';
+import { projectAiwgPath, resolveProjectAiwgDir, resolveProjectAiwgDirForWrite, isProjectArtifactRootExternal } from '../config/project-artifacts.js';
 const DigestSchema = z.string().regex(/^sha256:[0-9a-f]{64}$/);
 const LocatorSchema = z.string().min(1).max(512).refine(value => !/[\r\n\0]/.test(value));
 export const CanonicalContextTargetSchema = z.enum([
     'project-fact', 'preference', 'goal', 'project', 'person', 'decision', 'operating-rule',
 ]);
 export const CanonicalContextClassificationSchema = z.enum(['public', 'internal']);
-export const CanonicalContextProposalSchema = z.object({
+export const CanonicalContextProposalSchema = z.strictObject({
     target: CanonicalContextTargetSchema,
     key: z.string().min(1).max(128).regex(/^[a-z0-9][a-z0-9._-]*$/),
     value: z.string().min(1).max(8192),
@@ -18,9 +24,9 @@ export const CanonicalContextProposalSchema = z.object({
     reason: z.string().min(1).max(1024),
     scope: z.string().min(1).max(128),
     classification: CanonicalContextClassificationSchema,
-    reviewAt: z.string().datetime().nullable().default(null),
-    expiresAt: z.string().datetime().nullable().default(null),
-}).strict();
+    reviewAt: dateTime().nullable().default(null),
+    expiresAt: dateTime().nullable().default(null),
+});
 function sha256(value) {
     return `sha256:${createHash('sha256').update(value).digest('hex')}`;
 }
@@ -54,17 +60,20 @@ function assertSafeProposal(proposal) {
     }
 }
 function ensureStorageInsideProject(projectRoot, target) {
-    const root = realpathSync(projectRoot);
+    let rootAncestor = resolve(projectRoot);
+    while (!existsSync(rootAncestor))
+        rootAncestor = dirname(rootAncestor);
+    const root = resolve(realpathSync(rootAncestor), relative(rootAncestor, resolve(projectRoot)));
     const lexicalRoot = resolve(projectRoot);
     const candidate = resolve(target);
     if (candidate !== lexicalRoot && !candidate.startsWith(`${lexicalRoot}${sep}`)) {
-        throw new Error('canonical context storage must remain inside the project');
+        throw new Error('canonical context storage must remain inside the resolved root');
     }
     let ancestor = candidate;
     while (!existsSync(ancestor))
         ancestor = dirname(ancestor);
     const actual = realpathSync(ancestor);
-    if (actual !== root && !actual.startsWith(`${root}${sep}`)) {
+    if (existsSync(projectRoot) && actual !== root && !actual.startsWith(`${root}${sep}`)) {
         throw new Error('canonical context storage cannot traverse a link outside the project');
     }
 }
@@ -107,18 +116,73 @@ function proposalFromEntry(entry) {
 function storeDigest(store) {
     return sha256(JSON.stringify(store));
 }
+/** Project the canonical owner data without creating a second record store. */
+export function canonicalMemoryRecord(entry) {
+    const sourcePath = `.aiwg/context/compound-memory/context.json#${entry.entryId}`;
+    const digest = sha256(entry.value);
+    const id = memoryRecordId(sourcePath, digest);
+    const lifecycle = entry.maintenance?.lifecycle
+        ?? (entry.status === 'revoked' ? 'retired' : entry.status);
+    const tombstone = lifecycle === 'active' ? undefined : entry.maintenance?.tombstone ?? {
+        id, digest, disposition: lifecycle,
+        reason: entry.disposition?.reason ?? entry.reason,
+        reviewer: entry.disposition?.reviewer ?? entry.reviewer,
+        at: entry.disposition?.recordedAt ?? entry.updatedAt,
+    };
+    return loadMemoryRecord({
+        schemaVersion: 'aiwg.memory-record.v1', id, sourcePath, digest,
+        version: entry.maintenance?.version ?? 1,
+        aliases: [...new Set([entry.entryId, ...(entry.maintenance?.aliases ?? [])])],
+        supersedes: entry.maintenance?.supersedes ?? [],
+        mergedFrom: entry.maintenance?.mergedFrom ?? [],
+        splitFrom: entry.maintenance?.splitFrom ?? [],
+        scope: entry.maintenance?.scope ?? 'project',
+        placement: entry.maintenance?.placement ?? 'resident', lifecycle,
+        authority: entry.maintenance?.authority ?? {
+            owner: 'compound-memory', source: 'reviewer', protection: 'unprotected',
+        },
+        observation: {
+            status: 'on-disk', evidence: {
+                source: sourcePath, at: entry.updatedAt, session: null, provider: null, version: null,
+            },
+        },
+        ...(entry.importedFromWorkspace ? { sourceWorkspaceId: entry.importedFromWorkspace } : {}),
+        ...(tombstone ? { tombstone } : {}),
+    });
+}
+function maintenanceMetadata(record, category, prior, recordedAt) {
+    const { version, scope, placement, lifecycle, authority, aliases, supersedes, mergedFrom, splitFrom, tombstone } = record;
+    return { version, scope, placement, lifecycle, authority, aliases, supersedes, mergedFrom, splitFrom,
+        ...(tombstone ? { tombstone } : {}), ...(category ? { category } : {}),
+        ...(prior ? { history: [...(prior.maintenance?.history ?? []), {
+                    record: canonicalMemoryRecord(prior), disposition: prior.disposition,
+                    recordedAt: recordedAt ?? prior.updatedAt,
+                    ...(prior.maintenance?.category ? { category: prior.maintenance.category } : {}),
+                }] } : {}),
+    };
+}
 export class CanonicalContextRepository {
+    projectRoot;
     root;
     statePath;
     receiptRoot;
     lockPath;
     workspaceId;
     constructor(projectRoot) {
-        this.root = resolve(projectRoot, '.aiwg/context/compound-memory');
+        this.projectRoot = projectRoot;
+        this.root = projectAiwgPath(projectRoot, 'context/compound-memory');
         this.statePath = resolve(this.root, 'context.json');
         this.receiptRoot = resolve(this.root, 'receipts');
         this.lockPath = resolve(this.root, '.lock');
-        ensureStorageInsideProject(projectRoot, this.root);
+        if (isProjectArtifactRootExternal(projectRoot)) {
+            // Before artifact routing the store was always repository-local. Never
+            // silently hide that history behind an empty external store.
+            const legacy = resolve(projectRoot, '.aiwg/context/compound-memory');
+            if (existsSync(resolve(legacy, 'context.json')) && !existsSync(this.statePath)) {
+                throw new Error(`Canonical context exists at the repository-local path ${legacy}, but the configured artifact root is external. Move that directory to ${this.root} before using canonical context.`);
+            }
+        }
+        ensureStorageInsideProject(isProjectArtifactRootExternal(projectRoot) ? resolveProjectAiwgDir(projectRoot) : projectRoot, this.root);
         this.workspaceId = workspaceIdentity(projectRoot);
     }
     read() {
@@ -140,6 +204,292 @@ export class CanonicalContextRepository {
         }
         return store;
     }
+    snapshot() { return storeDigest(this.read()); }
+    /** Input to regenerated resident context. History remains available through export(). */
+    residentEntries() {
+        return Object.values(this.read().entries).filter(entry => {
+            const record = canonicalMemoryRecord(entry);
+            return record.lifecycle === 'active' && record.placement === 'resident';
+        });
+    }
+    maintenanceReceipt(key, operation) {
+        const receipt = this.read().maintenanceReceipts?.[key];
+        if (receipt && operation && receipt.operationId !== sha256(JSON.stringify({ operation, snapshot: operation.owner?.snapshot }))) {
+            throw new Error('Maintenance receipt key conflicts with another operation');
+        }
+        return receipt;
+    }
+    previewMaintenance(operation) {
+        const store = this.read();
+        if (!operation.owner || operation.owner.name !== 'compound-memory' || !operation.review) {
+            throw new Error('Canonical maintenance requires an owner binding and explicit review');
+        }
+        if (operation.owner.snapshot !== storeDigest(store))
+            throw new Error('Stale canonical owner snapshot');
+        const entry = store.entries[operation.owner.handle];
+        if (!entry)
+            throw new Error('Canonical maintenance entry was not found');
+        const record = canonicalMemoryRecord(entry);
+        if (record.authority.owner !== 'compound-memory')
+            throw new Error('Canonical maintenance cannot mutate another authority owner');
+        if (operation.target.id !== record.id && !record.aliases.includes(operation.target.id)) {
+            throw new Error('Canonical maintenance target does not match its owner handle');
+        }
+        validateMaintenancePlan({ schemaVersion: 'aiwg.maintenance-plan.v1', operations: [operation] }, Object.values(store.entries).map(canonicalMemoryRecord), { retirementBasis: operation.review.retirementBasis });
+        if (operation.sessionEffect !== 'next-session') {
+            throw new Error('Canonical maintenance can only promise next-session effect');
+        }
+        if (operation.op !== 'merge' && operation.related?.length)
+            throw new Error('Only merge may bind additional sources');
+        if (operation.op === 'restore' && (record.lifecycle === 'active'
+            || Object.values(store.entries).some(candidate => candidate.entryId !== entry.entryId
+                && candidate.target === entry.target && candidate.key === entry.key && candidate.status === 'active'))) {
+            throw new Error('Restore requires inactive history without an active conflicting entry');
+        }
+        if (operation.op === 'recategorize' && !operation.category)
+            throw new Error('Recategorize requires category');
+        if (operation.op === 'promote' || operation.op === 'demote') {
+            const ranks = { archived: 0, indexed: 1, 'task-context': 2, resident: 3 };
+            const direction = ranks[operation.to.placement] - ranks[operation.from.placement];
+            if ((operation.op === 'promote' && direction <= 0) || (operation.op === 'demote' && direction >= 0)
+                || operation.to.lifecycle !== operation.from.lifecycle) {
+                throw new Error('Placement maintenance requires the requested promotion or demotion');
+            }
+        }
+        else if (operation.to.placement !== operation.from.placement) {
+            throw new Error('Lifecycle and category maintenance cannot implicitly change placement');
+        }
+        if (operation.op === 'recategorize' && operation.to.lifecycle !== record.lifecycle) {
+            throw new Error('Recategorize cannot implicitly change lifecycle');
+        }
+        const replacements = operation.replacements ?? [];
+        if (['supersede', 'merge', 'split'].includes(operation.op)) {
+            if (operation.to.lifecycle !== 'superseded')
+                throw new Error('Replacement requires superseded lifecycle');
+            if ((operation.op === 'split' && replacements.length < 2)
+                || (operation.op !== 'split' && replacements.length !== 1)) {
+                throw new Error('Replacement operation requires the exact replacement count');
+            }
+            const keys = new Set();
+            for (const replacement of replacements) {
+                const proposal = CanonicalContextProposalSchema.parse({
+                    ...proposalFromEntry(entry), key: replacement.key, value: replacement.value,
+                    sourceRef: canonicalLocator(replacement.sourcePath ?? entry.sourceRef),
+                    sourceDigest: replacement.sourcePath ? null : entry.sourceDigest,
+                    reviewer: operation.review.reviewer, reason: operation.rationale,
+                });
+                assertSafeProposal(proposal);
+                const replacementId = stableEntryId(proposal);
+                if (keys.has(replacement.key) || store.entries[replacementId]) {
+                    throw new Error('Replacement must have a unique new identity');
+                }
+                keys.add(replacement.key);
+                if (Object.values(store.entries).some(candidate => candidate.status === 'active'
+                    && candidate.entryId !== entry.entryId && candidate.key === replacement.key
+                    && candidate.target === entry.target && !(operation.related ?? []).some(binding => binding.id === candidate.entryId
+                    || binding.id === canonicalMemoryRecord(candidate).id))) {
+                    throw new Error('Replacement conflicts with an unreviewed active canonical entry');
+                }
+            }
+        }
+        else if (replacements.length)
+            throw new Error('This operation cannot replace canonical values');
+        if (operation.op === 'merge' && this.mergeEntries(store, operation).length < 2) {
+            throw new Error('Merge requires additional reviewed canonical sources');
+        }
+        return {
+            schemaVersion: 'aiwg.canonical-context-preview.v1', operation: 'maintenance',
+            operationId: sha256(JSON.stringify({ operation, snapshot: storeDigest(store) })),
+            workspaceId: this.workspaceId, storeDigest: storeDigest(store), duplicate: false,
+            confirmationRequired: true, conflicts: [], proposedEntryId: entry.entryId,
+            importCount: 0, diff: [{ field: entry.entryId, before: JSON.stringify(operation.from), after: JSON.stringify(operation.to) }],
+        };
+    }
+    mergeEntries(store, operation) {
+        const target = store.entries[operation.owner.handle];
+        const related = operation.related ?? [];
+        const sources = [target];
+        for (const binding of related) {
+            const source = Object.values(store.entries).find(candidate => {
+                const record = canonicalMemoryRecord(candidate);
+                return record.id === binding.id || record.aliases.includes(binding.id);
+            });
+            if (!source || sources.includes(source))
+                throw new Error('Merge source is missing or duplicated');
+            const record = canonicalMemoryRecord(source);
+            if (record.digest !== binding.digest || record.version !== binding.version)
+                throw new Error('Stale merge source digest or version');
+            sources.push(source);
+        }
+        for (const entry of sources) {
+            const record = canonicalMemoryRecord(entry);
+            const base = canonicalMemoryRecord(target);
+            if (record.lifecycle !== 'active' || record.scope !== base.scope
+                || !isDeepStrictEqual(record.authority, base.authority)
+                || record.placement !== base.placement || entry.scope !== target.scope || entry.classification !== target.classification) {
+                throw new Error('Merge sources must preserve scope, authority, placement and active lifecycle');
+            }
+        }
+        return sources;
+    }
+    publishOwnerLock(lockPath) {
+        // Publish complete owner identity with one link syscall. A crash before this
+        // point leaves only an unrelated temporary file, never an empty owner lock.
+        const temporary = `${lockPath}.${process.pid}.${randomUUID()}.tmp`;
+        try {
+            writeFileSync(temporary, JSON.stringify({ pid: process.pid, host: hostname() }), { flag: 'wx', mode: 0o600 });
+            linkSync(temporary, lockPath);
+        }
+        finally {
+            if (existsSync(temporary))
+                unlinkSync(temporary);
+        }
+    }
+    openOwnerLock(lockPath = this.lockPath, depth = 0) {
+        try {
+            return this.publishOwnerLock(lockPath);
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST' || depth >= 8)
+                throw error;
+            // The same atomic lease protocol protects recovery for sync legacy and
+            // async maintenance callers, including recovery after a dead reclaimer.
+            const recoveryPath = `${lockPath}.recovery`;
+            this.openOwnerLock(recoveryPath, depth + 1);
+            try {
+                let owner;
+                try {
+                    owner = JSON.parse(readFileSync(lockPath, 'utf8'));
+                }
+                catch (readError) {
+                    if (readError.code === 'ENOENT')
+                        return this.publishOwnerLock(lockPath);
+                }
+                if (!owner || typeof owner !== 'object' || Array.isArray(owner)
+                    || typeof owner.host !== 'string' || !owner.host
+                    || !Number.isSafeInteger(owner.pid) || owner.pid < 1) {
+                    // A legacy writer could crash after exclusive create and before writing.
+                    // Give fresh/partially written locks a bounded grace period.
+                    if (Date.now() - statSync(lockPath).mtimeMs < 60_000)
+                        throw error;
+                }
+                else {
+                    if (owner.host !== hostname())
+                        throw error;
+                    try {
+                        process.kill(owner.pid, 0);
+                        throw error;
+                    }
+                    catch (probe) {
+                        if (probe.code !== 'ESRCH')
+                            throw probe;
+                    }
+                }
+                unlinkSync(lockPath);
+                return this.publishOwnerLock(lockPath);
+            }
+            finally {
+                unlinkSync(recoveryPath);
+            }
+        }
+    }
+    async confirmMaintenance(input) {
+        resolveProjectAiwgDirForWrite(this.projectRoot);
+        mkdirSync(this.root, { recursive: true });
+        this.openOwnerLock();
+        try {
+            const store = this.read();
+            const prior = store.maintenanceReceipts?.[input.key];
+            if (prior) {
+                if (prior.operationId !== input.preview.operationId)
+                    throw new Error('Maintenance receipt key conflicts with another operation');
+                return prior;
+            }
+            const preview = this.previewMaintenance(input.operation);
+            if (JSON.stringify(preview) !== JSON.stringify(input.preview)) {
+                throw new Error('Confirmation requires the exact current canonical maintenance preview');
+            }
+            const removesResident = input.operation.from.placement === 'resident'
+                && (input.operation.to.placement !== 'resident' || input.operation.to.lifecycle !== 'active');
+            if (removesResident && !input.verifyRetrieval) {
+                throw new Error('compound-memory resident removal is unsupported: no owner-native indexed retrieval projection is available');
+            }
+            if (removesResident && !await input.verifyRetrieval(input.operation)) {
+                throw new Error('Indexed retrieval must be verified before resident removal');
+            }
+            if (this.snapshot() !== preview.storeDigest)
+                throw new Error('Stale canonical owner snapshot after retrieval verification');
+            const now = new Date().toISOString();
+            const entry = store.entries[input.operation.owner.handle];
+            const original = canonicalMemoryRecord(entry);
+            const sources = input.operation.op === 'merge' ? this.mergeEntries(store, input.operation) : [entry];
+            const newIds = [];
+            for (const replacement of input.operation.replacements ?? []) {
+                const proposal = CanonicalContextProposalSchema.parse({
+                    ...proposalFromEntry(entry), key: replacement.key, value: replacement.value,
+                    sourceRef: canonicalLocator(replacement.sourcePath ?? entry.sourceRef),
+                    sourceDigest: replacement.sourcePath ? null : entry.sourceDigest,
+                    reviewer: input.operation.review.reviewer, reason: input.operation.rationale,
+                });
+                const entryId = stableEntryId(proposal);
+                const next = {
+                    ...proposal, entryId, status: 'active', createdAt: now, updatedAt: now,
+                    supersedes: entry.entryId, disposition: null, importedFromWorkspace: entry.importedFromWorkspace,
+                };
+                const nextRecord = canonicalMemoryRecord(next);
+                nextRecord.scope = original.scope;
+                nextRecord.authority = { ...original.authority };
+                nextRecord.placement = original.placement;
+                nextRecord.aliases = [...new Set([...nextRecord.aliases, ...sources.map(source => canonicalMemoryRecord(source).id)])];
+                const lineage = sources.map(source => canonicalMemoryRecord(source).id);
+                if (input.operation.op === 'merge')
+                    nextRecord.mergedFrom = lineage;
+                else if (input.operation.op === 'split')
+                    nextRecord.splitFrom = lineage;
+                else
+                    nextRecord.supersedes = lineage;
+                next.maintenance = maintenanceMetadata(nextRecord, replacement.category ?? entry.maintenance?.category);
+                store.entries[entryId] = next;
+                newIds.push(entryId);
+            }
+            for (const source of sources) {
+                const record = canonicalMemoryRecord(source);
+                record.version += 1;
+                record.placement = input.operation.to.placement;
+                record.lifecycle = input.operation.to.lifecycle;
+                if (record.lifecycle !== 'active') {
+                    record.tombstone = {
+                        id: record.id, digest: record.digest, disposition: record.lifecycle,
+                        reviewer: input.operation.review.reviewer, reason: input.operation.rationale, at: now,
+                        ...(newIds[0] ? { successor: canonicalMemoryRecord(store.entries[newIds[0]]).id } : {}),
+                    };
+                }
+                else
+                    delete record.tombstone;
+                source.maintenance = maintenanceMetadata(record, input.operation.category ?? source.maintenance?.category, source, now);
+                source.status = record.lifecycle === 'active' ? 'active' : record.lifecycle === 'superseded' ? 'superseded' : 'revoked';
+                source.updatedAt = now;
+                source.disposition = record.lifecycle === 'active' ? null : {
+                    reviewer: input.operation.review.reviewer, reason: input.operation.rationale, recordedAt: now,
+                };
+            }
+            store.revision += 1;
+            const receipt = {
+                schemaVersion: 'aiwg.canonical-context-receipt.v1',
+                receiptId: sha256(`${preview.operationId}\0${store.revision}`), operationId: preview.operationId,
+                operation: 'maintenance', workspaceId: this.workspaceId,
+                entryIds: [...sources.map(source => source.entryId), ...newIds],
+                revision: store.revision, duplicate: false, completedAt: now,
+            };
+            store.maintenanceReceipts = { ...store.maintenanceReceipts, [input.key]: receipt };
+            // Mutation and recovery receipt are a single atomic owner commit.
+            writeJsonAtomic(this.statePath, store);
+            return receipt;
+        }
+        finally {
+            unlinkSync(this.lockPath);
+        }
+    }
     previewUpsert(raw) {
         const proposal = CanonicalContextProposalSchema.parse({
             ...raw,
@@ -149,6 +499,11 @@ export class CanonicalContextRepository {
         const store = this.read();
         const entryId = stableEntryId(proposal);
         const active = Object.values(store.entries).find(entry => (entry.status === 'active' && entry.target === proposal.target && entry.key === proposal.key));
+        const prior = Object.values(store.entries).filter(entry => entry.target === proposal.target && entry.key === proposal.key);
+        if ((!active && prior.some(entry => canonicalMemoryRecord(entry).lifecycle === 'retired'))
+            || (active && canonicalMemoryRecord(active).placement !== 'resident' && active.entryId !== entryId)) {
+            throw new Error('Canonical retired or demoted content requires reviewed maintenance or restore');
+        }
         const duplicate = active?.entryId === entryId;
         const conflicts = active && !duplicate
             ? [{ entryId: active.entryId, valueDigest: sha256(active.value) }]
@@ -241,8 +596,9 @@ export class CanonicalContextRepository {
         };
     }
     confirm(input) {
+        resolveProjectAiwgDirForWrite(this.projectRoot);
         mkdirSync(this.root, { recursive: true });
-        const lock = openSync(this.lockPath, 'wx', 0o600);
+        this.openOwnerLock();
         try {
             const requestedReceiptPath = resolve(this.receiptRoot, `${input.preview.operationId.replace(':', '_')}.json`);
             if (existsSync(requestedReceiptPath)) {
@@ -273,6 +629,12 @@ export class CanonicalContextRepository {
                 if (!current.duplicate) {
                     const active = Object.values(store.entries).find(entry => (entry.status === 'active' && entry.target === proposal.target && entry.key === proposal.key));
                     if (active) {
+                        const record = canonicalMemoryRecord(active);
+                        record.version += 1;
+                        record.lifecycle = 'superseded';
+                        record.tombstone = { id: record.id, digest: record.digest, disposition: 'superseded',
+                            reviewer: proposal.reviewer, reason: proposal.reason, at: now };
+                        active.maintenance = maintenanceMetadata(record, active.maintenance?.category, active, now);
                         active.status = 'superseded';
                         active.updatedAt = now;
                         active.disposition = { reviewer: proposal.reviewer, reason: proposal.reason, recordedAt: now };
@@ -288,12 +650,30 @@ export class CanonicalContextRepository {
                         disposition: null,
                         importedFromWorkspace: null,
                     };
+                    if (active?.maintenance) {
+                        const successor = canonicalMemoryRecord(store.entries[current.proposedEntryId]);
+                        const predecessor = canonicalMemoryRecord(active);
+                        successor.scope = predecessor.scope;
+                        successor.authority = { ...predecessor.authority };
+                        successor.placement = predecessor.placement;
+                        successor.supersedes = [predecessor.id];
+                        successor.aliases.push(predecessor.id);
+                        store.entries[current.proposedEntryId].maintenance = maintenanceMetadata(successor, active.maintenance.category);
+                        if (active.maintenance.tombstone)
+                            active.maintenance.tombstone.successor = successor.id;
+                    }
                     changed.push(current.proposedEntryId);
                 }
             }
             else if (current.operation === 'revoke' && input.revoke) {
                 const entry = store.entries[input.revoke.entryId];
                 if (!current.duplicate) {
+                    const record = canonicalMemoryRecord(entry);
+                    record.version += 1;
+                    record.lifecycle = 'retired';
+                    record.tombstone = { id: record.id, digest: record.digest, disposition: 'retired',
+                        reviewer: input.revoke.reviewer, reason: input.revoke.reason, at: now };
+                    entry.maintenance = maintenanceMetadata(record, entry.maintenance?.category, entry, now);
                     entry.status = 'revoked';
                     entry.updatedAt = now;
                     entry.disposition = {
@@ -334,7 +714,6 @@ export class CanonicalContextRepository {
             return receipt;
         }
         finally {
-            closeSync(lock);
             unlinkSync(this.lockPath);
         }
     }

package/dist/src/memory/canonical-maintenance.js

@@ -0,0 +1,95 @@
+import { refreshMaintenanceIndexes } from './maintenance-index.js';
+import { CanonicalContextRepository, canonicalMemoryRecord } from './canonical-context.js';
+import { sha256 } from './context-pack.js';
+import { isDeepStrictEqual } from 'node:util';
+/** Routes reviewed placement and lifecycle changes through the canonical owner. */
+export class CanonicalMaintenanceOwner {
+    name = 'compound-memory';
+    repository;
+    projectRoot;
+    options;
+    constructor(projectRoot, options = {}) {
+        this.options = options;
+        this.projectRoot = projectRoot;
+        this.repository = new CanonicalContextRepository(projectRoot);
+    }
+    async records() {
+        return Object.values(this.repository.read().entries).map(canonicalMemoryRecord);
+    }
+    async snapshot() { return this.repository.snapshot(); }
+    async validate(operation) {
+        this.repository.previewMaintenance(operation);
+    }
+    async apply(operation, key) {
+        const prior = this.repository.maintenanceReceipt(key, operation);
+        if (prior) {
+            await this.refreshIndex();
+            return prior;
+        }
+        const preview = this.repository.previewMaintenance(operation);
+        const receipt = await this.repository.confirmMaintenance({
+            preview, operation, key, verifyRetrieval: operation => this.verifyRetrieval(operation),
+        });
+        await this.refreshIndex();
+        return receipt;
+    }
+    async receipt(key, options = {}) {
+        const receipt = this.repository.maintenanceReceipt(key);
+        if (receipt !== undefined && !options.readOnly)
+            await this.refreshIndex();
+        return receipt;
+    }
+    async verifyEndState(operation, key) {
+        const state = this.repository.read();
+        const receipt = this.repository.maintenanceReceipt(key);
+        const findings = [];
+        if (receipt && (receipt.operation !== 'maintenance'
+            || receipt.operationId !== sha256(JSON.stringify({ operation, snapshot: operation.owner?.snapshot })))) {
+            findings.push('Owner receipt does not bind the exact reviewed operation');
+        }
+        for (const target of [operation.target, ...(operation.related ?? [])]) {
+            const entry = Object.values(state.entries).find(item => canonicalMemoryRecord(item).id === target.id);
+            if (!entry)
+                continue;
+            const history = entry.maintenance?.history;
+            if (history !== undefined && !Array.isArray(history))
+                throw new Error('Invalid canonical maintenance history');
+            const prior = history?.find(item => item.record.id === target.id && item.record.version === target.version
+                && item.record.digest === target.digest && item.record.placement === operation.from.placement
+                && item.record.lifecycle === operation.from.lifecycle);
+            if (!prior)
+                findings.push(`Reviewed source history is missing: ${target.id}`);
+            if (operation.category && entry.maintenance?.category !== operation.category)
+                findings.push(`Reviewed category differs: ${target.id}`);
+            if (prior && !isDeepStrictEqual(prior.record.authority, canonicalMemoryRecord(entry).authority)) {
+                findings.push(`Source authority changed: ${target.id}`);
+            }
+            if (operation.op === 'restore' && !prior?.record.tombstone)
+                findings.push(`Recovery tombstone history is missing: ${target.id}`);
+            if (canonicalMemoryRecord(entry).lifecycle !== 'active' && !entry.maintenance?.tombstone)
+                findings.push(`Retained owner tombstone is missing: ${target.id}`);
+            if (receipt && !receipt.entryIds.includes(entry.entryId))
+                findings.push(`Receipt omits retained source: ${target.id}`);
+        }
+        for (const replacement of operation.replacements ?? []) {
+            const entry = Object.values(state.entries).find(item => item.key === replacement.key
+                && receipt?.entryIds.includes(item.entryId));
+            if (!entry || sha256(entry.value) !== sha256(replacement.value))
+                findings.push(`Receipt replacement differs: ${replacement.key}`);
+            if (replacement.category && entry?.maintenance?.category !== replacement.category)
+                findings.push(`Replacement category differs: ${replacement.key}`);
+        }
+        return findings;
+    }
+    async refreshIndex() {
+        await refreshMaintenanceIndexes(this.projectRoot);
+    }
+    async verifyRetrieval(operation) {
+        if (operation.owner?.name !== this.name)
+            return false;
+        if (this.options.verifyRetrieval)
+            return this.options.verifyRetrieval(operation);
+        throw new Error('compound-memory resident removal is unsupported: no owner-native indexed retrieval projection is available');
+    }
+}
+//# sourceMappingURL=canonical-maintenance.js.map

package/dist/src/memory/cli-result.js

@@ -0,0 +1,22 @@
+import { AiwgError } from '../cli/errors.js';
+/** Public maintenance command statuses; legacy storage commands retain their contract. */
+export const MEMORY_EXIT_CODES = { success: 0, findings: 1, usage: 2, failed: 3 };
+export const MEMORY_EXIT_USAGE = 'Exit codes: 0 success/no findings/help; 1 findings; 2 usage or malformed input; 3 stale or failed operation.';
+export function memoryUsage(read) {
+    try {
+        return read();
+    }
+    catch (cause) {
+        throw new AiwgError({ code: 'ERR_USAGE_MEMORY', exitCode: MEMORY_EXIT_CODES.usage,
+            message: cause instanceof Error ? cause.message : String(cause), cause });
+    }
+}
+export async function memoryInput(read) {
+    try {
+        return await read();
+    }
+    catch (cause) {
+        return memoryUsage(() => { throw cause; });
+    }
+}
+//# sourceMappingURL=cli-result.js.map