@aiwg/cli 2026.10.5 → 2026.10.7

package/dist/src/memory/cli.js

@@ -10,7 +10,52 @@
  * @issue #966
  */
 import { runSubsystemCli } from '../storage/subsystem-cli.js';
+import { memoryUsage, memoryInput, MEMORY_EXIT_USAGE } from './cli-result.js';
+import { listProviderMemoryAdapters } from './provider-memory-adapter.js';
 export async function main(args) {
+    if (args[0] === 'recommend') {
+        const { runMemoryRecommendCli } = await import('./recommend-cli.js');
+        return runMemoryRecommendCli(args.slice(1));
+    }
+    if (['plan', 'apply', 'verify', 'restore'].includes(args[0])) {
+        const { runMemoryMaintenanceCli } = await import('./maintenance-cli.js');
+        return runMemoryMaintenanceCli(args[0], args.slice(1));
+    }
+    if (args[0] === 'audit') {
+        const { auditMemory, formatMemoryAudit } = await import('./audit.js');
+        const opts = memoryUsage(() => parseMemoryAuditOptions(args.slice(1)));
+        if (opts.help) {
+            console.log(MEMORY_AUDIT_USAGE);
+            return;
+        }
+        const report = await auditMemory(opts);
+        if (opts.cost) {
+            const { costMemory, formatMemoryCost } = await import('./cost.js');
+            const cost = costMemory(report);
+            console.log(opts.json ? JSON.stringify(cost, null, 2) : formatMemoryCost(cost));
+            return report.findings.length ? 1 : 0;
+        }
+        console.log(opts.json ? JSON.stringify(report, null, 2) : formatMemoryAudit(report));
+        return report.findings.length ? 1 : 0;
+    }
+    if (args[0] === 'cost') {
+        const { auditMemory } = await import('./audit.js');
+        const { costMemory, formatMemoryCost } = await import('./cost.js');
+        const opts = memoryUsage(() => parseMemoryCostOptions(args.slice(1)));
+        if (opts.help) {
+            console.log(MEMORY_COST_USAGE);
+            return;
+        }
+        const report = await auditMemory(opts);
+        const cost = costMemory(report, await memoryInput(() => resolveMemoryCostInputs(opts)));
+        console.log(opts.json ? JSON.stringify(cost, null, 2) : formatMemoryCost(cost));
+        return report.findings.length ? 1 : 0;
+    }
+    if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
+        console.log(MEMORY_AUDIT_USAGE);
+        if (args.length)
+            return;
+    }
     if (args[0] === 'project') {
         await runProjectMemoryCli(args.slice(1));
         return;
@@ -163,4 +208,135 @@ Subcommands:
 The manifest lives at ~/.aiwg/projects/manifest.json and each registered
 project memory root uses a private .aiwg layout under ~/.aiwg/projects/<id>/.aiwg.`);
 }
+export const MEMORY_AUDIT_USAGE = `Usage: aiwg memory audit [--scope global|project|provider] [--provider <id>] [--json] [--cost]
+       aiwg memory cost [--scope global|project|provider] [--provider <id>] [--json] [--demote <id|path> ...] [--startup-measurement <file>] [--usage <file>]
+
+Read-only static memory and instruction inventory. Defaults to this workspace;
+global roots require --scope global. --scope provider requires --provider <id>.
+Reports include exposure chains, unavailable/opaque surfaces and scan bounds.
+Static eligibility does not establish live context loading. JSON: aiwg.memory-audit.v1.
+--cost renders the same inventory through the resident-cost view (JSON: aiwg.memory-cost.v1).
+The cost subcommand adds --demote previews, a #2936 startup-measurement report
+and caller-supplied usage evidence; all views are read-only and write nothing.
+Read-only recommendations: recommend (use --help for evidence and review export).
+Reviewed lifecycle: plan, apply, verify, restore (use --help for exact-plan options).
+Other memory subcommands: path, list, get, put, delete, append-log, project.
+${MEMORY_EXIT_USAGE}`;
+export const MEMORY_COST_USAGE = `Usage: aiwg memory cost [--scope global|project|provider] [--provider <id>] [--json] [--demote <id|path> ...] [--startup-measurement <file>] [--usage <file>]
+
+Read-only resident context cost and memory utility over the static audit inventory.
+Token estimates reuse the existing UTF-8 bytes estimators (#2936 startup measure,
+#2938 inline-budget guard); no new tokenizer. Anything not measurable locally
+stays unknown, never guessed. --demote previews before/after cost with the
+retrieval anchors required to keep demoted content reachable. --usage reads a
+JSON object of { "<item-id>": { retrieved, used, rejected, evidence } } held in
+memory only. JSON: aiwg.memory-cost.v1. Writes nothing.
+${MEMORY_EXIT_USAGE}`;
+export function parseMemoryAuditOptions(args) {
+    const opts = {};
+    const seen = new Set();
+    for (let index = 0; index < args.length; index++) {
+        const [flag, inline, ...extra] = args[index].split('=');
+        if (!['--scope', '--provider', '--json', '--cost', '--help', '-h'].includes(flag) || extra.length)
+            throw new Error(`Unknown memory audit argument: ${args[index]}`);
+        if (seen.has(flag))
+            throw new Error(`Duplicate memory audit option: ${flag}`);
+        seen.add(flag);
+        if (flag === '--json' || flag === '--cost' || flag === '--help' || flag === '-h') {
+            if (inline !== undefined)
+                throw new Error(`${flag} takes no value`);
+            if (flag === '--json')
+                opts.json = true;
+            else if (flag === '--cost')
+                opts.cost = true;
+            else
+                opts.help = true;
+            continue;
+        }
+        const value = inline ?? args[++index];
+        if (!value || value.startsWith('-'))
+            throw new Error(`${flag} requires a value`);
+        if (flag === '--scope') {
+            if (!['global', 'project', 'provider'].includes(value))
+                throw new Error('--scope must be global, project or provider');
+            opts.scope = value;
+        }
+        else
+            opts.provider = value;
+    }
+    if (opts.scope === 'provider' && !opts.provider && !opts.help)
+        throw new Error('--scope provider requires --provider <id>');
+    if (!opts.help && opts.provider && !listProviderMemoryAdapters().some(adapter => adapter.providerId === opts.provider))
+        throw new Error(`Unknown memory provider '${opts.provider}'`);
+    return opts;
+}
+export function parseMemoryCostOptions(args) {
+    const opts = { demote: [] };
+    const once = new Set();
+    for (let index = 0; index < args.length; index++) {
+        const [flag, inline, ...extra] = args[index].split('=');
+        if (!['--scope', '--provider', '--json', '--demote', '--startup-measurement', '--usage', '--help', '-h'].includes(flag) || extra.length) {
+            throw new Error(`Unknown memory cost argument: ${args[index]}`);
+        }
+        if (flag !== '--demote') {
+            if (once.has(flag))
+                throw new Error(`Duplicate memory cost option: ${flag}`);
+            once.add(flag);
+        }
+        if (flag === '--json' || flag === '--help' || flag === '-h') {
+            if (inline !== undefined)
+                throw new Error(`${flag} takes no value`);
+            if (flag === '--json')
+                opts.json = true;
+            else
+                opts.help = true;
+            continue;
+        }
+        const value = inline ?? args[++index];
+        if (!value || value.startsWith('-'))
+            throw new Error(`${flag} requires a value`);
+        if (flag === '--scope') {
+            if (!['global', 'project', 'provider'].includes(value))
+                throw new Error('--scope must be global, project or provider');
+            opts.scope = value;
+        }
+        else if (flag === '--provider')
+            opts.provider = value;
+        else if (flag === '--demote')
+            opts.demote.push(value);
+        else if (flag === '--startup-measurement')
+            opts.startupMeasurement = value;
+        else
+            opts.usage = value;
+    }
+    if (opts.scope === 'provider' && !opts.provider && !opts.help)
+        throw new Error('--scope provider requires --provider <id>');
+    if (!opts.help && opts.provider && !listProviderMemoryAdapters().some(adapter => adapter.providerId === opts.provider))
+        throw new Error(`Unknown memory provider '${opts.provider}'`);
+    return opts;
+}
+/** Read-only input resolution for the cost view. Reads input files; writes nothing. */
+export async function resolveMemoryCostInputs(opts) {
+    const fs = await import('node:fs/promises');
+    const readJson = async (file, label) => {
+        let text;
+        try {
+            text = await fs.readFile(file, 'utf8');
+        }
+        catch (error) {
+            throw new Error(`${label} could not be read: ${error.message}`);
+        }
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            throw new Error(`${label} is not valid JSON: ${file}`);
+        }
+    };
+    return {
+        usage: opts.usage ? (await readJson(opts.usage, 'Usage evidence')) : undefined,
+        startupMeasurement: opts.startupMeasurement ? await readJson(opts.startupMeasurement, 'Startup measurement') : undefined,
+        demote: opts.demote.length ? [...opts.demote] : undefined,
+    };
+}
 //# sourceMappingURL=cli.js.map

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

@@ -1,7 +1,8 @@
-import { existsSync, readFileSync, readdirSync, realpathSync, statSync, } from 'node:fs';
+import { closeSync, existsSync, openSync, readSync, readFileSync, readdirSync, realpathSync, statSync, } from 'node:fs';
 import { createHash } from 'node:crypto';
 import { relative, resolve, sep } from 'node:path';
 import { loadFortemiCoreMetadataEntries } from '../artifacts/fortemi-core-query-adapter.js';
+import { load as loadYaml } from 'js-yaml';
 const DEFAULT_BUDGET = {
     totalCharacters: 8000,
     lineCharacters: 2000,
@@ -12,7 +13,7 @@ const DEFAULT_BUDGET = {
 const EXCLUDED_STATES = new Set([
     'contradicted', 'superseded', 'revoked', 'origin-unavailable',
 ]);
-function sha256(value) {
+export function sha256(value) {
     return `sha256:${createHash('sha256').update(value).digest('hex')}`;
 }
 function projectLocator(root, target) {
@@ -63,8 +64,16 @@ function lineCandidates(root, taskTerms) {
         const parsed = JSON.parse(readFileSync(metadataPath, 'utf8'));
         entries = parsed.entries ?? {};
     }
-    return values.map((text, index) => {
-        const entry = Object.values(entries).find(candidate => candidate.value === text && candidate.status === 'active');
+    const activeEntry = (entry) => {
+        const maintenance = entry.maintenance;
+        return entry.status === 'active' && (!maintenance?.placement || maintenance.placement === 'resident')
+            && (!maintenance?.lifecycle || maintenance.lifecycle === 'active');
+    };
+    return values.filter(text => {
+        const matching = Object.values(entries).filter(entry => entry.value === text);
+        return matching.length === 0 || matching.some(activeEntry);
+    }).map((text, index) => {
+        const entry = Object.values(entries).find(candidate => candidate.value === text && activeEntry(candidate));
         const sources = Array.isArray(entry?.sources) ? entry.sources : [];
         const score = lexicalScore(taskTerms, text);
         return {
@@ -90,6 +99,44 @@ function markdownText(raw) {
         .replace(/\s+/g, ' ')
         .trim();
 }
+const WIKI_HEAD_BYTES = 64 * 1024;
+function readWikiHead(target) {
+    const descriptor = openSync(target, 'r');
+    try {
+        const buffer = Buffer.alloc(WIKI_HEAD_BYTES);
+        const length = readSync(descriptor, buffer, 0, buffer.length, 0);
+        return buffer.toString('utf8', 0, length);
+    }
+    finally {
+        closeSync(descriptor);
+    }
+}
+/** Canonical dispositions override a stale local or remote index snapshot. */
+function ordinaryWikiSource(raw, locator, indexed) {
+    if (indexed && (indexed.lifecycle !== 'active' || indexed.placement === 'archived'))
+        return false;
+    const frontmatter = raw.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+    if (!frontmatter) {
+        if (/^---\r?\n/.test(raw) && Buffer.byteLength(raw) >= WIKI_HEAD_BYTES) {
+            console.warn(`context-pack: ${locator}: frontmatter exceeds the 64 KiB scan limit; disposition cannot be verified`);
+            return false;
+        }
+        if (/^---\r?\n/.test(raw)) {
+            console.warn(`context-pack: ${locator}: malformed frontmatter without a closing delimiter; including page`);
+            return true;
+        }
+        return !indexed;
+    }
+    try {
+        const data = loadYaml(frontmatter[1]);
+        const record = data?.memoryRecord;
+        return record ? record.lifecycle === 'active' && record.placement !== 'archived' : !indexed;
+    }
+    catch (error) {
+        console.warn(`context-pack: ${locator}: malformed frontmatter; including page (${error instanceof Error ? error.message : String(error)})`);
+        return true;
+    }
+}
 function wikiCandidates(root, taskTerms, maxFiles) {
     const wikiRoot = resolve(root, '.aiwg/wiki');
     if (!existsSync(wikiRoot))
@@ -115,7 +162,9 @@ function wikiCandidates(root, taskTerms, maxFiles) {
                 continue;
             visited += 1;
             const locator = projectLocator(root, target);
-            const raw = readFileSync(target, 'utf8').slice(0, 65536);
+            const raw = readWikiHead(target);
+            if (!ordinaryWikiSource(raw, locator))
+                continue;
             const text = markdownText(raw).slice(0, 1200);
             const score = lexicalScore(taskTerms, text);
             if (score <= 0)
@@ -149,7 +198,9 @@ function fortemiWikiCandidates(root, taskTerms, maxFiles) {
         if (!existsSync(target))
             continue;
         const locator = projectLocator(root, target);
-        const raw = readFileSync(target, 'utf8').slice(0, 65536);
+        const raw = readWikiHead(target);
+        if (!ordinaryWikiSource(raw, locator, entry.memoryRecord))
+            continue;
         const text = markdownText(raw).slice(0, 1200);
         const score = lexicalScore(taskTerms, [entry.title, entry.summary, text].join(' '));
         if (score <= 0)