@aiwg/cli 2026.10.5 → 2026.10.7

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

@@ -0,0 +1,286 @@
+import { memoryUsage, MEMORY_EXIT_USAGE } from './cli-result.js';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { createInterface } from 'node:readline/promises';
+import { sha256 } from './context-pack.js';
+import { MemoryRecommendationsSchema } from './recommend.js';
+import { MaintenanceOpSchema, MaintenancePlanSchema } from './maintenance-contract.js';
+import { MemoryPlacementSchema } from './taxonomy.js';
+import { indexMemoryAliases } from './maintenance-record.js';
+import { applyMaintenancePlan, maintenancePath, maintenancePlanDigest, previewMaintenancePlan, verifyMaintenancePlan } from './maintenance.js';
+import { providerCopiesStatus } from '../smiths/context-pipeline/workspace-context.js';
+export const MEMORY_MAINTENANCE_USAGE = `Usage:
+  aiwg memory plan --owner <owner> --target <handle> --op <operation> --rationale <text> --reviewer <name> --out <file>
+      [--placement resident|indexed|task-context|archived] [--category <category>]
+      [--replacements <json-file>] [--related <json-file>] [--link <indexed-path> ...]
+      [--retirement-basis age|review] [--json]
+  aiwg memory plan --recommendation <selected-candidate-file> --reviewer <name> --out <file> [--category <category>] [--replacements <json-file>] [--link <indexed-path> ...]
+  aiwg memory plan --input <exact-plan-file> [--out <file> | --preview] [--json]
+  aiwg memory apply --plan <file> [--confirm <plan-digest> | --yes] [--preview] [--json]
+  aiwg memory verify --plan <applied-plan-file> [--json]
+  aiwg memory restore --plan <restore-plan-file> [--confirm <plan-digest> | --yes] [--preview] [--json]
+Operations: promote, demote, recategorize, merge, split, supersede, retire, restore.
+Owners: line-memory, compound-memory, semantic-memory. Scope: this project (--scope project); global writes unsupported.
+Verify checks recorded end states, receipts, history and indexed retrieval without writes.
+Plan writes only the requested new plan file; preview writes nothing.
+Noninteractive apply requires --yes or --confirm with the exact plan digest.
+Changes affect the next session. Provider adapters must be regenerated by their existing owner.
+${MEMORY_EXIT_USAGE}`;
+export function parseMemoryMaintenanceOptions(command, args) {
+    const opts = { values: {}, links: [], yes: false, json: false, preview: false, help: false };
+    const valueFlags = command === 'plan'
+        ? ['--owner', '--target', '--op', '--rationale', '--reviewer', '--out', '--input', '--recommendation', '--placement', '--category', '--replacements', '--related', '--link', '--retirement-basis']
+        : command === 'verify' ? ['--plan'] : ['--plan', '--confirm'];
+    valueFlags.push('--scope');
+    const booleanFlags = ['--json', '--help', '-h', ...(command === 'verify' ? [] : ['--preview']), ...(['apply', 'restore'].includes(command) ? ['--yes'] : [])];
+    const seen = new Set();
+    for (let index = 0; index < args.length; index++) {
+        const equal = args[index].indexOf('=');
+        const flag = equal < 0 ? args[index] : args[index].slice(0, equal);
+        const inline = equal < 0 ? undefined : args[index].slice(equal + 1);
+        if (!valueFlags.includes(flag) && !booleanFlags.includes(flag))
+            throw new Error(`Unknown memory ${command} argument: ${args[index]}`);
+        const key = flag === '-h' ? '--help' : flag;
+        if (seen.has(key) && flag !== '--link')
+            throw new Error(`Duplicate memory ${command} option: ${flag}`);
+        seen.add(key);
+        if (booleanFlags.includes(flag)) {
+            if (inline !== undefined)
+                throw new Error(`${flag} takes no value`);
+            if (key === '--help')
+                opts.help = true;
+            else if (flag === '--yes')
+                opts.yes = true;
+            else if (flag === '--json')
+                opts.json = true;
+            else
+                opts.preview = true;
+        }
+        else {
+            const value = inline ?? args[++index];
+            if (!value || value.startsWith('-'))
+                throw new Error(`${flag} requires a value`);
+            if (flag === '--link')
+                opts.links.push(value);
+            else
+                opts.values[flag.slice(2)] = value;
+        }
+    }
+    if (opts.help)
+        return opts;
+    if (opts.values.scope && opts.values.scope !== 'project')
+        throw new Error('Executable maintenance supports --scope project only; use audit --scope global for global inventory');
+    if (opts.yes && opts.values.confirm)
+        throw new Error('--yes and --confirm are mutually exclusive');
+    if (command === 'plan') {
+        if (opts.values.recommendation) {
+            if (!opts.values.reviewer)
+                throw new Error('--reviewer is required for recommendation review');
+            if (Object.keys(opts.values).some(key => !['recommendation', 'reviewer', 'out', 'category', 'replacements', 'scope'].includes(key)))
+                throw new Error('--recommendation cannot be combined with operation or exact-plan flags');
+        }
+        else if (opts.values.input) {
+            if (Object.keys(opts.values).some(key => !['input', 'out', 'scope'].includes(key)) || opts.links.length)
+                throw new Error('--input cannot be combined with operation flags');
+        }
+        else {
+            for (const required of ['owner', 'target', 'op', 'rationale', 'reviewer'])
+                if (!opts.values[required])
+                    throw new Error(`--${required} is required`);
+        }
+        if (opts.preview && opts.values.out)
+            throw new Error('--preview and --out are mutually exclusive');
+        if (!opts.preview && !opts.values.out)
+            throw new Error('--out is required unless --preview is selected');
+    }
+    else {
+        if (!opts.values.plan)
+            throw new Error('--plan is required');
+        if (opts.preview && (opts.yes || opts.values.confirm))
+            throw new Error('--preview cannot be combined with confirmation');
+    }
+    return opts;
+}
+export async function createMaintenanceOwners(root) {
+    const [{ LineMaintenanceOwner }, { CanonicalMaintenanceOwner }, { ArtifactMaintenanceOwner }] = await Promise.all([
+        import('./line-maintenance.js'), import('./canonical-maintenance.js'), import('../artifacts/memory-maintenance.js'),
+    ]);
+    const artifact = new ArtifactMaintenanceOwner(root);
+    // These resident owners do not yet publish an owner-native indexed projection.
+    // Their default verifier explicitly refuses resident removal; an unrelated
+    // artifact copy must not turn that unsupported operation into a valid plan.
+    return [new LineMaintenanceOwner(root), new CanonicalMaintenanceOwner(root), artifact];
+}
+export async function runMemoryMaintenanceCli(command, args, dependencies = {}) {
+    const opts = memoryUsage(() => parseMemoryMaintenanceOptions(command, args));
+    if (opts.help) {
+        console.log(MEMORY_MAINTENANCE_USAGE);
+        return;
+    }
+    const root = dependencies.root ?? process.cwd();
+    const owners = dependencies.owners ?? await createMaintenanceOwners(root);
+    const readJson = (path) => memoryUsage(() => JSON.parse(readFileSync(maintenancePath(root, path), 'utf8')));
+    let recommendationRelated;
+    let recommendationUncertainty;
+    if (command === 'plan' && opts.values.recommendation) {
+        const report = memoryUsage(() => MemoryRecommendationsSchema.parse(readJson(opts.values.recommendation)));
+        if (report.workspace !== root || report.candidates.length !== 1)
+            throw new Error('Review input requires one candidate from this workspace');
+        const candidate = report.candidates[0];
+        if (candidate.status !== 'advisory' || candidate.blockedReasons.length)
+            throw new Error('Blocked, rejected or conflicting recommendations cannot become plans');
+        if (candidate.kind === 'conflict')
+            throw new Error('Conflicts require explicit source resolution');
+        if (['merge', 'supersede'].includes(candidate.kind) && !opts.values.replacements)
+            throw new Error('Lineage recommendations require explicit owner review with --replacements');
+        const target = candidate.target;
+        if (target.scope !== 'project')
+            throw new Error('Executable recommendation review requires a project-owned source');
+        const file = maintenancePath(root, target.sourcePath);
+        if (sha256(readFileSync(file, 'utf8')) !== candidate.sourceDigest)
+            throw new Error('Stale recommendation source digest; rerun recommend');
+        const owner = owners.find(value => value.name === target.authority.owner);
+        if (!owner)
+            throw new Error('Recommendation source has no executable maintenance owner');
+        // Audit fingerprints whole files. The owner binds its native body/revision and
+        // snapshot only after the reviewer selects this exact unchanged source.
+        const record = (await owner.records()).find(value => value.sourcePath === target.sourcePath);
+        if (!record)
+            throw new Error('Recommendation source is not an individual owner target; review an owner handle explicitly');
+        if (candidate.kind === 'merge') {
+            if (candidate.related.length !== candidate.relatedTargets.length)
+                throw new Error('Merge review requires every related source revision');
+            const records = await owner.records();
+            recommendationRelated = candidate.relatedTargets.map(binding => {
+                const related = binding.record;
+                if (related.scope !== target.scope || related.authority.owner !== owner.name)
+                    throw new Error('Merge recommendation cannot cross scope or owners');
+                if (sha256(readFileSync(maintenancePath(root, related.sourcePath), 'utf8')) !== binding.sourceDigest)
+                    throw new Error('Stale related recommendation source digest');
+                const input = records.find(value => value.sourcePath === related.sourcePath);
+                if (!input)
+                    throw new Error('Related recommendation source is not an individual owner target');
+                return input.id;
+            });
+        }
+        recommendationUncertainty = candidate.uncertainty.join('; ');
+        opts.values.owner = owner.name;
+        opts.values.target = record.id;
+        opts.values.op = candidate.kind;
+        opts.values.rationale = candidate.rationale + (candidate.residentJustification ? `; Resident justification: ${JSON.stringify(candidate.residentJustification)}` : '');
+        if (candidate.retrievalImpact.proposedPlacement)
+            opts.values.placement = candidate.retrievalImpact.proposedPlacement;
+        opts.values.category ??= candidate.retrievalImpact.category ?? '';
+        opts.values['retirement-basis'] = 'review';
+    }
+    let plan;
+    if (command === 'plan' && !opts.values.input) {
+        const owner = owners.find(value => value.name === opts.values.owner);
+        if (!owner)
+            throw new Error(`Unavailable maintenance owner: ${opts.values.owner}`);
+        const records = await owner.records();
+        const aliases = indexMemoryAliases(records);
+        const record = aliases.get(opts.values.target);
+        if (!record)
+            throw new Error('Maintenance target is missing');
+        const op = memoryUsage(() => MaintenanceOpSchema.parse(opts.values.op));
+        const lifecycle = op === 'retire' ? 'retired' : ['merge', 'split', 'supersede'].includes(op) ? 'superseded' : op === 'restore' ? 'active' : record.lifecycle;
+        const placement = opts.values.placement ? memoryUsage(() => MemoryPlacementSchema.parse(opts.values.placement)) : record.placement;
+        const relatedInput = recommendationRelated ?? (opts.values.related ? readJson(opts.values.related) : []);
+        if (!Array.isArray(relatedInput) || relatedInput.some(value => typeof value !== 'string'))
+            throw new Error('--related requires a JSON array of existing owner handles');
+        const related = relatedInput.map(handle => {
+            const input = aliases.get(handle);
+            if (!input)
+                throw new Error(`Related target is missing: ${handle}`);
+            return { id: input.id, digest: input.digest, version: input.version };
+        });
+        plan = { schemaVersion: 'aiwg.maintenance-plan.v1', operations: [{
+                    op, target: { id: record.id, digest: record.digest, version: record.version },
+                    from: { placement: record.placement, lifecycle: record.lifecycle }, to: { placement, lifecycle },
+                    scope: record.scope, rationale: opts.values.rationale, uncertainty: recommendationUncertainty ?? 'Static review; live session loading is unobserved',
+                    impactedLinks: opts.links, sessionEffect: 'next-session', precondition: { digest: record.digest, version: record.version },
+                    owner: { name: owner.name, handle: record.aliases[0] ?? record.id, snapshot: await owner.snapshot() },
+                    review: { reviewer: opts.values.reviewer, retirementBasis: (opts.values['retirement-basis'] ?? 'age') },
+                    ...(related.length ? { related } : {}), ...(opts.values.category ? { category: opts.values.category } : {}),
+                    ...(opts.values.replacements ? { replacements: readJson(opts.values.replacements) } : {}),
+                }] };
+    }
+    else
+        plan = readJson(opts.values.input ?? opts.values.plan);
+    plan = memoryUsage(() => MaintenancePlanSchema.parse(plan));
+    if (command === 'verify') {
+        const report = await verifyMaintenancePlan(plan, owners);
+        const providerCopies = await providerCopiesStatus(root);
+        const review = maintenanceReview(plan, root);
+        console.log(opts.json ? JSON.stringify({ ...report, providerCopies, review }, null, 2) : `${report.planDigest}: ${report.findings.length ? report.findings.join('; ') : 'verified recorded owner end states, history and required retrieval'}\nProvider copies: ${providerCopies.status}; regenerate: ${providerCopies.regenerate}\n${formatMaintenanceReview(review)}`);
+        return report.findings.length ? 1 : 0;
+    }
+    if (command === 'restore' && plan.operations?.some(op => op.op !== 'restore'))
+        throw new Error('memory restore requires a plan containing only restore operations');
+    if (command === 'plan' || opts.preview) {
+        plan = await previewMaintenancePlan(plan, owners);
+        const digest = maintenancePlanDigest(plan);
+        const review = maintenanceReview(plan, root);
+        if (command === 'plan' && !opts.preview) {
+            const path = maintenancePath(root, opts.values.out);
+            if (existsSync(path))
+                throw new Error('Plan output exists; choose a new file to preserve the reviewed preview');
+            console.error(opts.json ? JSON.stringify({ event: 'maintenance-review', planDigest: digest, review }) : formatMaintenanceReview(review));
+            writeFileSync(path, `${JSON.stringify(plan, null, 2)}\n`, { flag: 'wx', mode: 0o600 });
+        }
+        console.log(opts.json ? JSON.stringify({ planDigest: digest, plan, review }, null, 2) : `${digest}\n${formatMaintenanceReview(review)}`);
+        return;
+    }
+    const digest = maintenancePlanDigest(plan);
+    const review = maintenanceReview(plan, root);
+    console.error(opts.json ? JSON.stringify({ event: 'maintenance-review', planDigest: digest, review }) : formatMaintenanceReview(review));
+    let confirmed = opts.values.confirm;
+    if (opts.yes)
+        confirmed = digest;
+    if (!confirmed) {
+        if (!(dependencies.isTTY ?? (process.stdin.isTTY && process.stdout.isTTY)) || opts.json)
+            memoryUsage(() => { throw new Error('Noninteractive apply requires --yes or --confirm <exact-plan-digest>'); });
+        console.log(JSON.stringify(plan, null, 2));
+        if (dependencies.confirm)
+            confirmed = await dependencies.confirm(digest);
+        else {
+            const readline = createInterface({ input: process.stdin, output: process.stdout });
+            try {
+                confirmed = await readline.question(`Type the exact plan digest to apply ${digest}: `);
+            }
+            finally {
+                readline.close();
+            }
+        }
+    }
+    const receipt = await applyMaintenancePlan(plan, { root, owners, confirmedDigest: confirmed });
+    const providerCopies = await providerCopiesStatus(root);
+    console.log(opts.json ? JSON.stringify({ ...receipt, providerCopies }, null, 2) : `${receipt.planDigest}: ${receipt.ownerReceipts.length} owner operation(s) completed; next-session effect\nProvider copies: ${providerCopies.status}; regenerate: ${providerCopies.regenerate}`);
+}
+/** Review envelope shared by human output, JSON previews and pre-mutation events. */
+export function maintenanceReview(plan, root) {
+    const scopes = [...new Set(plan.operations.map(operation => operation.scope))];
+    return {
+        targeting: { workspace: root, scope: scopes.join(', '), global: scopes.includes('global'), globalMutationSupported: false },
+        diff: plan.operations.map(operation => ({ ...operation })),
+        ownerReview: plan.operations.map(operation => ({ owner: operation.owner, review: operation.review,
+            requirement: 'Exact owner snapshot and reviewer required; confirmation never bypasses owner validation' })),
+        limitations: ['Static durable state only; live native/session loading is unobserved',
+            'Changes take effect next-session; running sessions are unchanged',
+            'Provider-native files require regeneration by their existing owner',
+            'Line-memory and compound-memory resident removal requires an owner-native indexed projection and is currently unsupported'],
+    };
+}
+function formatMaintenanceReview(review) {
+    return [`Target: ${review.targeting.scope} ${review.targeting.workspace}; global mutation unsupported`,
+        ...review.diff.flatMap(operation => [
+            `${operation.op} ${operation.owner?.name}:${operation.owner?.handle}: ${operation.from.placement}/${operation.from.lifecycle} -> ${operation.to.placement}/${operation.to.lifecycle}${operation.category ? `; category -> ${operation.category}` : ''}; ${operation.scope}; ${operation.sessionEffect}; reviewer ${operation.review?.reviewer}; rationale: ${operation.rationale}`,
+            `  revision ${operation.target.version}; digest ${operation.target.digest}; owner snapshot ${operation.owner?.snapshot}; retirement basis ${operation.review?.retirementBasis}`,
+            `  uncertainty: ${operation.uncertainty}; links: ${JSON.stringify(operation.impactedLinks)}`,
+            ...(operation.related?.length ? [`  related revisions: ${JSON.stringify(operation.related)}`] : []),
+            ...(operation.replacements?.length ? [`  replacements: ${JSON.stringify(operation.replacements)}`] : []),
+        ]),
+        'Owner review: exact snapshot, source revision and reviewer required.',
+        ...review.limitations].join('\n');
+}
+//# sourceMappingURL=maintenance-cli.js.map

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

@@ -0,0 +1,136 @@
+import { z } from 'zod';
+import { integer } from '../schema/zod-validation.mjs';
+import { isDeepStrictEqual } from 'node:util';
+import { indexMemoryAliases, MemoryDigestSchema } from './maintenance-record.js';
+import { MemoryLifecycleSchema, MemoryPlacementSchema, MemoryScopeSchema } from './taxonomy.js';
+export const MaintenanceOpSchema = z.enum([
+    'promote', 'demote', 'recategorize', 'merge', 'split', 'supersede', 'retire', 'restore',
+]);
+const VersionSchema = integer().min(1).max(Number.MAX_SAFE_INTEGER);
+const TargetSchema = z.strictObject({ id: z.string().min(1), digest: MemoryDigestSchema, version: VersionSchema });
+const StateSchema = z.strictObject({ placement: MemoryPlacementSchema, lifecycle: MemoryLifecycleSchema });
+export const MaintenanceOperationSchema = z.strictObject({
+    op: MaintenanceOpSchema,
+    target: TargetSchema,
+    related: z.array(TargetSchema).optional(),
+    owner: z.strictObject({ name: z.string().min(1), handle: z.string().min(1), snapshot: MemoryDigestSchema }).optional(),
+    review: z.strictObject({ reviewer: z.string().min(1), retirementBasis: z.enum(['age', 'review']) }).optional(),
+    category: z.string().min(1).optional(),
+    replacements: z.array(z.strictObject({ key: z.string().min(1), value: z.string().min(1), sourcePath: z.string().min(1).optional(), category: z.string().min(1).optional() })).optional(),
+    from: StateSchema,
+    to: StateSchema,
+    scope: MemoryScopeSchema,
+    rationale: z.string().min(1),
+    uncertainty: z.string().min(1),
+    impactedLinks: z.array(z.string().min(1)),
+    sessionEffect: z.enum(['current', 'next-session']),
+    precondition: z.strictObject({ digest: MemoryDigestSchema, version: VersionSchema }),
+}).superRefine((operation, context) => {
+    if (operation.from.placement !== operation.to.placement && operation.from.lifecycle !== operation.to.lifecycle) {
+        context.addIssue({ code: 'custom', message: 'An operation cannot implicitly change a second axis' });
+    }
+    if (operation.target.digest !== operation.precondition.digest || operation.target.version !== operation.precondition.version) {
+        context.addIssue({ code: 'custom', message: 'Target and precondition must identify the same revision' });
+    }
+    const lineage = ['merge', 'split', 'supersede'].includes(operation.op);
+    if (!lineage && (operation.related?.length || operation.replacements?.length)) {
+        context.addIssue({ code: 'custom', message: 'Only lineage operations accept replacements or related inputs' });
+    }
+    if (operation.replacements && ((['merge', 'supersede'].includes(operation.op) && operation.replacements.length !== 1)
+        || (operation.op === 'split' && operation.replacements.length < 2))) {
+        context.addIssue({ code: 'custom', message: 'Lineage operation requires the exact replacement count' });
+    }
+    if (operation.related?.length && operation.op !== 'merge')
+        context.addIssue({ code: 'custom', message: 'Only merge accepts related inputs' });
+    if (['promote', 'demote', 'recategorize'].includes(operation.op) && operation.from.lifecycle !== operation.to.lifecycle) {
+        context.addIssue({ code: 'custom', message: 'Placement and category operations cannot change lifecycle' });
+    }
+    if (!['promote', 'demote'].includes(operation.op) && operation.from.placement !== operation.to.placement) {
+        context.addIssue({ code: 'custom', message: 'Lifecycle and category operations cannot change placement' });
+    }
+    const rank = { archived: 0, indexed: 1, 'task-context': 2, resident: 3 };
+    if ((operation.op === 'promote' && rank[operation.to.placement] <= rank[operation.from.placement])
+        || (operation.op === 'demote' && rank[operation.to.placement] >= rank[operation.from.placement])) {
+        context.addIssue({ code: 'custom', message: 'Promotion or demotion must move in the requested placement direction' });
+    }
+    if (lineage && (operation.from.lifecycle !== 'active' || operation.to.lifecycle !== 'superseded')) {
+        context.addIssue({ code: 'custom', message: 'Lineage operations supersede active originals' });
+    }
+    if (operation.from.lifecycle === 'purged')
+        context.addIssue({ code: 'custom', message: 'Purged sources cannot be maintained' });
+    if (operation.to.lifecycle === 'purged') {
+        context.addIssue({ code: 'custom', message: 'Maintenance cannot purge sources' });
+    }
+});
+export const MaintenancePlanSchema = z.strictObject({
+    schemaVersion: z.literal('aiwg.maintenance-plan.v1'),
+    operations: z.array(MaintenanceOperationSchema),
+});
+export const ProviderCopiesSchema = z.strictObject({
+    status: z.enum(['current', 'stale', 'not-applicable']),
+    regenerate: z.literal('aiwg regenerate --workspace --provider generic'),
+});
+export const MaintenanceReceiptSchema = z.strictObject({
+    schemaVersion: z.literal('aiwg.maintenance-receipt.v1'),
+    planDigest: MemoryDigestSchema,
+    ownerReceipts: z.array(z.unknown()),
+    partial: z.strictObject({ completed: z.array(z.string().min(1)), pending: z.array(z.string().min(1)) }).optional(),
+    resumedFrom: z.string().min(1).optional(),
+    providerCopies: ProviderCopiesSchema.optional(),
+});
+/** Validate a preview against current owner metadata. Does not apply, retire or restore anything.
+ * Retirement defaults to age eligibility; explicit review policy is supplied by the caller.
+ */
+export function validateMaintenancePlan(input, records, policy = { retirementBasis: 'age' }) {
+    const plan = MaintenancePlanSchema.parse(input);
+    const index = indexMemoryAliases(records);
+    const targets = new Set();
+    for (const operation of plan.operations) {
+        const record = index.get(operation.target.id);
+        if (!record)
+            throw new Error('Maintenance target is missing');
+        if (targets.has(record.id))
+            throw new Error('Multiple operations require separate revision previews for the same target');
+        targets.add(record.id);
+        if (operation.precondition.digest !== record.digest || operation.precondition.version !== record.version) {
+            throw new Error('Stale memory digest or version precondition');
+        }
+        if (record.version >= Number.MAX_SAFE_INTEGER)
+            throw new Error('Maintenance revision is exhausted');
+        if (operation.scope !== record.scope)
+            throw new Error('Maintenance cannot implicitly change scope');
+        if (operation.from.placement !== record.placement || operation.from.lifecycle !== record.lifecycle) {
+            throw new Error('Stale memory placement or lifecycle precondition');
+        }
+        if (policy.retirementBasis === 'age' && record.authority.protection === 'pinned'
+            && (operation.op === 'retire' || operation.to.lifecycle === 'retired')) {
+            throw new Error('Pinned rare obligations cannot be retired by age');
+        }
+        if (operation.op === 'retire' && operation.to.lifecycle !== 'retired')
+            throw new Error('Retire requires retired lifecycle');
+        if (operation.op === 'supersede' && operation.to.lifecycle !== 'superseded')
+            throw new Error('Supersede requires superseded lifecycle');
+        if (operation.op === 'restore' && operation.to.lifecycle !== 'active')
+            throw new Error('Restore requires active lifecycle');
+    }
+    for (const operation of plan.operations) {
+        for (const input of operation.related ?? []) {
+            const record = index.get(input.id);
+            const target = index.get(operation.target.id);
+            if (!record)
+                throw new Error('Related maintenance target is missing');
+            if (targets.has(record.id))
+                throw new Error('Multiple operations overlap a maintenance target');
+            targets.add(record.id);
+            if (input.digest !== record.digest || input.version !== record.version)
+                throw new Error('Stale related digest or version precondition');
+            if (record.scope !== target.scope || !isDeepStrictEqual(record.authority, target.authority)) {
+                throw new Error('Merge cannot implicitly change scope or authority');
+            }
+            if (record.lifecycle !== 'active')
+                throw new Error('Merge inputs must be active');
+        }
+    }
+    return plan;
+}
+//# sourceMappingURL=maintenance-contract.js.map

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

@@ -0,0 +1,18 @@
+import { existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { getProjectIndexRoot } from '../artifacts/types.js';
+/** Refresh every existing local retrieval graph after an owner commit or recovery. */
+export async function refreshMaintenanceIndexes(root) {
+    const directory = getProjectIndexRoot(root);
+    const graphs = existsSync(directory)
+        ? readdirSync(directory, { withFileTypes: true })
+            .filter(entry => entry.isDirectory() && !entry.name.startsWith('.')
+            && existsSync(join(directory, entry.name, 'metadata.json')))
+            .map(entry => entry.name)
+        : [];
+    const { buildIndex } = await import('../artifacts/index-builder.js');
+    for (const graph of ['', ...graphs]) {
+        await buildIndex(root, { ...(graph ? { graph } : {}), force: true, quiet: true, workers: 0 });
+    }
+}
+//# sourceMappingURL=maintenance-index.js.map

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

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=maintenance-owner.js.map

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

@@ -0,0 +1,138 @@
+import { z } from 'zod';
+import { integer, dateTime } from '../schema/zod-validation.mjs';
+import { load } from 'js-yaml';
+import { sha256 } from './context-pack.js';
+import { MemoryLifecycleSchema, MemoryTaxonomySchema } from './taxonomy.js';
+export const MemoryDigestSchema = z.string().regex(/^sha256:[0-9a-f]{64}$/);
+const HandleSchema = z.string().min(1);
+const HandlesSchema = z.array(HandleSchema).refine(values => new Set(values).size === values.length, 'Duplicate handles');
+export const MemoryTombstoneSchema = z.strictObject({
+    id: HandleSchema,
+    digest: MemoryDigestSchema,
+    disposition: MemoryLifecycleSchema.exclude(['active']),
+    reason: z.string().min(1),
+    reviewer: z.string().min(1),
+    at: dateTime(),
+    successor: HandleSchema.optional(),
+});
+export const MemoryRecordSchema = z.strictObject({
+    ...MemoryTaxonomySchema.omit({ schemaVersion: true }).shape,
+    schemaVersion: z.literal('aiwg.memory-record.v1'),
+    id: MemoryDigestSchema,
+    sourcePath: z.string().min(1).refine(value => !/[\r\n\0]/.test(value)),
+    digest: MemoryDigestSchema,
+    version: integer().min(1).max(Number.MAX_SAFE_INTEGER),
+    aliases: HandlesSchema,
+    supersedes: HandlesSchema,
+    mergedFrom: HandlesSchema,
+    splitFrom: HandlesSchema,
+    sourceWorkspaceId: HandleSchema.optional(),
+    tombstone: MemoryTombstoneSchema.optional(),
+}).superRefine((record, context) => {
+    if (record.lifecycle === 'retired' && !record.tombstone) {
+        context.addIssue({ code: 'custom', message: 'Retired memory requires an owner tombstone', path: ['tombstone'] });
+    }
+});
+/** Locator spelling is significant. Compatibility spellings belong in aliases. */
+export function memoryRecordId(sourcePath, digest) {
+    MemoryDigestSchema.parse(digest);
+    return sha256(JSON.stringify({ sourcePath, digest }));
+}
+/** Refuse unknown versions rather than silently assigning current semantics. */
+export function loadMemoryRecord(input) {
+    const record = MemoryRecordSchema.parse(input);
+    if (record.id !== memoryRecordId(record.sourcePath, record.digest)) {
+        throw new Error('Memory record identity does not match locator and digest');
+    }
+    if (record.aliases.includes(record.id))
+        throw new Error('Memory record cannot alias itself');
+    if (record.tombstone && (record.tombstone.id !== record.id || record.tombstone.digest !== record.digest
+        || record.tombstone.disposition !== record.lifecycle)) {
+        throw new Error('Memory tombstone must match its record identity and lifecycle');
+    }
+    return record;
+}
+export function indexMemoryAliases(records) {
+    const index = new Map();
+    const parsed = records.map(loadMemoryRecord);
+    const canonicalIds = new Set();
+    for (const record of parsed) {
+        if (index.has(record.id))
+            throw new Error(`Memory alias collision: ${record.id}`);
+        index.set(record.id, record);
+        canonicalIds.add(record.id);
+    }
+    for (const record of parsed) {
+        for (const handle of record.aliases) {
+            const prior = index.get(handle);
+            if (prior) {
+                // Prior IDs may be compatibility aliases on successors, but an exact
+                // canonical ID must still address its immutable retained history.
+                const lineage = [...record.supersedes, ...record.mergedFrom, ...record.splitFrom];
+                if (canonicalIds.has(handle) && lineage.includes(handle))
+                    continue;
+                throw new Error(`Memory alias collision: ${handle}`);
+            }
+            index.set(handle, record);
+        }
+    }
+    return index;
+}
+/** Explicit metadata projection from the existing intake v1 receipt; no owner data is rewritten. */
+export function memoryRecordFromIntake(receipt, owner) {
+    if (receipt.schemaVersion !== 'aiwg.compound-memory.intake-receipt.v1') {
+        throw new Error('Unsupported memory intake receipt version');
+    }
+    return loadMemoryRecord({
+        schemaVersion: 'aiwg.memory-record.v1',
+        id: memoryRecordId(receipt.sourceLocator, receipt.sourceDigest),
+        sourcePath: receipt.sourceLocator,
+        digest: receipt.sourceDigest,
+        version: 1,
+        aliases: [receipt.receiptId],
+        supersedes: [], mergedFrom: [], splitFrom: [],
+        scope: 'project', placement: 'indexed', lifecycle: 'active',
+        authority: { owner, source: 'import', protection: 'unprotected' },
+        observation: {
+            status: 'on-disk',
+            evidence: { source: receipt.receiptId, at: receipt.registeredAt, session: null, provider: null, version: null },
+        },
+    });
+}
+/** Validate supplied include edges only. Discovery and file loading belong to the audit owner. */
+export function detectMemoryIncludeCycles(graph) {
+    const done = new Set();
+    const stack = [];
+    const active = new Map();
+    const cycles = [];
+    function visit(locator) {
+        const position = active.get(locator);
+        if (position !== undefined) {
+            cycles.push([...stack.slice(position), locator]);
+            return;
+        }
+        if (done.has(locator))
+            return;
+        active.set(locator, stack.length);
+        stack.push(locator);
+        for (const included of Object.hasOwn(graph, locator) ? graph[locator] : [])
+            visit(included);
+        stack.pop();
+        active.delete(locator);
+        done.add(locator);
+    }
+    for (const locator of Object.keys(graph).sort())
+        visit(locator);
+    return cycles;
+}
+/** Shared canonical Markdown parsing for inventory and the existing artifact owner. */
+export function parseMemoryMarkdown(content) {
+    const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/);
+    if (!match)
+        return { data: {}, body: content };
+    const data = load(match[1]) ?? {};
+    if (typeof data !== 'object' || Array.isArray(data))
+        throw new Error('Memory source frontmatter must be an object');
+    return { data: data, body: match[2] };
+}
+//# sourceMappingURL=maintenance-record.js.map