@graphorin/cli 0.5.0

package/dist/commands/index.js

@@ -0,0 +1,22 @@
+import { runAuditExport, runAuditPrune, runAuditVerify } from "./audit.js";
+import { runAuthList, runAuthLogin, runAuthRefresh, runAuthRevoke, runAuthStatus } from "./auth.js";
+import { CONSOLIDATOR_INVALID_TIER_EXIT, runConsolidatorSetTier, runConsolidatorStatus, runConsolidatorStop } from "./consolidator.js";
+import { expectedFileModes, runDoctor } from "./doctor.js";
+import { runGuardExplain, runGuardStatus } from "./guard.js";
+import { runInit } from "./init.js";
+import { runMemoryActivity, runMemoryInspect, runMemoryMigrate, runMemoryReview, runMemoryStatus, runMemoryWhy } from "./memory.js";
+import { runStart } from "./start.js";
+import { runMigrate } from "./migrate.js";
+import { runMigrateConfig } from "./migrate-config.js";
+import { runMigrateExport } from "./migrate-export.js";
+import { runPricingDiff, runPricingLookup, runPricingMissing, runPricingRefresh, runPricingStatus } from "./pricing.js";
+import { runSecretsDelete, runSecretsGet, runSecretsList, runSecretsRef, runSecretsRotate, runSecretsSet } from "./secrets.js";
+import { runSkillsAudit, runSkillsInspect, runSkillsInstall, runSkillsMigrateFrontmatter } from "./skills.js";
+import { runStorageCleanupBackups, runStorageEncrypt, runStorageRekey, runStorageStatus } from "./storage.js";
+import { runTelemetryDisable, runTelemetryEnable, runTelemetryInspect, runTelemetryStatus } from "./telemetry.js";
+import { parseDuration, runTokenCreate, runTokenList, runTokenRekey, runTokenRevoke, runTokenRotate, runTokenVerify } from "./token.js";
+import { runToolsLint } from "./tools-lint.js";
+import { runTracesPrune, runTracesStatus } from "./traces.js";
+import { runTriggersDisable, runTriggersFire, runTriggersList, runTriggersPrune, runTriggersStatus } from "./triggers.js";
+
+export { CONSOLIDATOR_INVALID_TIER_EXIT, expectedFileModes, parseDuration, runAuditExport, runAuditPrune, runAuditVerify, runAuthList, runAuthLogin, runAuthRefresh, runAuthRevoke, runAuthStatus, runConsolidatorSetTier, runConsolidatorStatus, runConsolidatorStop, runDoctor, runGuardExplain, runGuardStatus, runInit, runMemoryActivity, runMemoryInspect, runMemoryMigrate, runMemoryReview, runMemoryStatus, runMemoryWhy, runMigrate, runMigrateConfig, runMigrateExport, runPricingDiff, runPricingLookup, runPricingMissing, runPricingRefresh, runPricingStatus, runSecretsDelete, runSecretsGet, runSecretsList, runSecretsRef, runSecretsRotate, runSecretsSet, runSkillsAudit, runSkillsInspect, runSkillsInstall, runSkillsMigrateFrontmatter, runStart, runStorageCleanupBackups, runStorageEncrypt, runStorageRekey, runStorageStatus, runTelemetryDisable, runTelemetryEnable, runTelemetryInspect, runTelemetryStatus, runTokenCreate, runTokenList, runTokenRekey, runTokenRevoke, runTokenRotate, runTokenVerify, runToolsLint, runTracesPrune, runTracesStatus, runTriggersDisable, runTriggersFire, runTriggersList, runTriggersPrune, runTriggersStatus };

package/dist/commands/init.d.ts

@@ -0,0 +1,46 @@
+//#region src/commands/init.d.ts
+/**
+ * `graphorin init` — interactive bootstrap.
+ *
+ * Writes a fresh `graphorin.config.ts` to the current working
+ * directory (or `--out`), prompts the operator for the cloud-upload
+ * sensitivity tier + storage encryption opt-in, and prints exactly
+ * one bootstrap admin token (held by the operator from this point
+ * onward — the tool never persists nor logs the raw value).
+ *
+ * `--non-interactive` accepts every choice through flags or env vars
+ * so the command works equally well in CI / image-build pipelines.
+ *
+ * @packageDocumentation
+ */
+/**
+ * @stable
+ */
+interface InitCommandOptions {
+  readonly out?: string;
+  readonly nonInteractive?: boolean;
+  readonly cloudConsent?: 'public-only' | 'public-and-internal' | 'all-with-warnings';
+  readonly encrypted?: boolean;
+  readonly cwd?: string;
+  /** Test seam: skip writing files (only print the report). */
+  readonly dryRun?: boolean;
+  /** Test seam: redirect stdout/err. */
+  readonly print?: (line: string) => void;
+}
+/**
+ * @stable
+ */
+interface InitCommandResult {
+  readonly configPath: string;
+  readonly bootstrapToken: string;
+  readonly serverPepperHex: string;
+  readonly cloudConsent: 'public-only' | 'public-and-internal' | 'all-with-warnings';
+  readonly storageEncrypted: boolean;
+}
+/**
+ * @stable
+ */
+declare function runInit(options?: InitCommandOptions): Promise<InitCommandResult>;
+//#endregion
+export { InitCommandOptions, InitCommandResult, runInit };
+//# sourceMappingURL=init.d.ts.map

package/dist/commands/init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.d.ts","names":[],"sources":["../../src/commands/init.ts"],"sourcesContent":[],"mappings":";;AA0BA;AAeA;AAWA;;;;;;;;;;;;;;UA1BiB,kBAAA;;;;;;;;;;;;;;UAeA,iBAAA;;;;;;;;;;iBAWK,OAAA,WAAiB,qBAA0B,QAAQ"}

package/dist/commands/init.js

@@ -0,0 +1,131 @@
+import { confirm, select } from "../internal/prompts.js";
+import { mkdir, stat, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, resolve } from "node:path";
+import process from "node:process";
+import { generatePepper, generateRawToken } from "@graphorin/security";
+
+//#region src/commands/init.ts
+/**
+* `graphorin init` — interactive bootstrap.
+*
+* Writes a fresh `graphorin.config.ts` to the current working
+* directory (or `--out`), prompts the operator for the cloud-upload
+* sensitivity tier + storage encryption opt-in, and prints exactly
+* one bootstrap admin token (held by the operator from this point
+* onward — the tool never persists nor logs the raw value).
+*
+* `--non-interactive` accepts every choice through flags or env vars
+* so the command works equally well in CI / image-build pipelines.
+*
+* @packageDocumentation
+*/
+/**
+* @stable
+*/
+async function runInit(options = {}) {
+	const target = resolveOutPath(options.cwd ?? process.cwd(), options.out);
+	const print = options.print ?? ((line) => process.stderr.write(`${line}\n`));
+	const cloudConsent = await resolveCloudConsent(options);
+	const storageEncrypted = await resolveEncryption(options);
+	const pepperHex = await generatePepper().useBuffer((buf) => buf.toString("hex"));
+	const bootstrap = generateRawToken({ env: "live" });
+	if (options.dryRun !== true) {
+		if (await fileExists(target)) throw new Error(`[graphorin/cli] refusing to overwrite existing '${target}'. Move it aside or pass --out <path>.`);
+		await mkdir(dirname(target), { recursive: true });
+		await writeFile(target, renderConfig({
+			cloudConsent,
+			storageEncrypted
+		}), { mode: 384 });
+	}
+	print(`[graphorin/cli] wrote ${target}`);
+	print(`[graphorin/cli] bootstrap admin token (shown ONCE):`);
+	print(`  ${bootstrap.raw}`);
+	print(`[graphorin/cli] server pepper hex (store in your keyring as 'graphorin_server_pepper'):`);
+	print(`  ${pepperHex}`);
+	print("");
+	print("Next steps:");
+	print(`  1. Persist the pepper: graphorin secrets set graphorin_server_pepper --value ${pepperHex}`);
+	print(`  2. Persist the bootstrap token securely; do NOT commit it.`);
+	print(`  3. Run \`graphorin migrate --config ${target}\` to apply storage migrations.`);
+	print(`  4. Run \`graphorin start --config ${target}\` to launch the server.`);
+	return Object.freeze({
+		configPath: target,
+		bootstrapToken: bootstrap.raw,
+		serverPepperHex: pepperHex,
+		cloudConsent,
+		storageEncrypted
+	});
+}
+function resolveOutPath(cwd, out) {
+	if (out === void 0 || out.length === 0) return resolve(cwd, "graphorin.config.ts");
+	return isAbsolute(out) ? out : resolve(cwd, out);
+}
+async function fileExists(path) {
+	try {
+		await stat(path);
+		return true;
+	} catch {
+		return false;
+	}
+}
+async function resolveCloudConsent(options) {
+	if (options.cloudConsent !== void 0) return options.cloudConsent;
+	const envValue = process.env.GRAPHORIN_CLOUD_CONSENT;
+	if (envValue === "public-only" || envValue === "public-and-internal" || envValue === "all-with-warnings") return envValue;
+	if (options.nonInteractive === true) return "public-and-internal";
+	return await select("Cloud-upload consent for context sent to providers:", [
+		"public-only",
+		"public-and-internal",
+		"all-with-warnings"
+	], "public-and-internal");
+}
+async function resolveEncryption(options) {
+	if (options.encrypted !== void 0) return options.encrypted;
+	if (process.env.GRAPHORIN_STORAGE_ENCRYPTED === "1") return true;
+	if (process.env.GRAPHORIN_STORAGE_ENCRYPTED === "0") return false;
+	if (options.nonInteractive === true) return false;
+	return await confirm("Enable storage encryption (defense-in-depth on top of FDE)?", false);
+}
+function renderConfig(input) {
+	return `import { defineConfig } from '@graphorin/server';
+
+export default defineConfig({
+  server: {
+    host: '127.0.0.1',
+    port: 8080,
+  },
+  auth: {
+    kind: 'token',
+    pepperRef: 'keyring:graphorin_server_pepper',
+  },
+  storage: {
+    path: './.graphorin/data.db',
+    mode: 'server',
+    encryption: ${input.storageEncrypted ? `{
+      enabled: true,
+      passphraseRef: 'keyring:graphorin_db_passphrase',
+    }` : `{ enabled: false }`},
+  },
+  audit: {
+    enabled: ${input.storageEncrypted ? "true" : "false"},
+  },
+  secrets: {
+    source: 'auto',
+    strict: false,
+  },
+  observability: {
+    logger: 'json',
+  },
+  // IP-5: no top-level 'defaults' block — the strict server-config
+  // parser rejects unknown keys, so the old render made a fresh
+  // 'graphorin init' fail on the very next migrate/start. The tier you
+  // chose at init is recorded below; enforce it via the memory
+  // package (createMemory contextEngine privacy options):
+  // cloudUploadConsent: ${JSON.stringify(input.cloudConsent)}
+});
+`;
+}
+
+//#endregion
+export { runInit };
+//# sourceMappingURL=init.js.map

package/dist/commands/init.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.js","names":[],"sources":["../../src/commands/init.ts"],"sourcesContent":["/**\n * `graphorin init` — interactive bootstrap.\n *\n * Writes a fresh `graphorin.config.ts` to the current working\n * directory (or `--out`), prompts the operator for the cloud-upload\n * sensitivity tier + storage encryption opt-in, and prints exactly\n * one bootstrap admin token (held by the operator from this point\n * onward — the tool never persists nor logs the raw value).\n *\n * `--non-interactive` accepts every choice through flags or env vars\n * so the command works equally well in CI / image-build pipelines.\n *\n * @packageDocumentation\n */\n\nimport { mkdir, stat, writeFile } from 'node:fs/promises';\nimport { dirname, isAbsolute, resolve } from 'node:path';\nimport process from 'node:process';\n\nimport { generatePepper, generateRawToken } from '@graphorin/security';\n\nimport { confirm, select } from '../internal/prompts.js';\n\n/**\n * @stable\n */\nexport interface InitCommandOptions {\n  readonly out?: string;\n  readonly nonInteractive?: boolean;\n  readonly cloudConsent?: 'public-only' | 'public-and-internal' | 'all-with-warnings';\n  readonly encrypted?: boolean;\n  readonly cwd?: string;\n  /** Test seam: skip writing files (only print the report). */\n  readonly dryRun?: boolean;\n  /** Test seam: redirect stdout/err. */\n  readonly print?: (line: string) => void;\n}\n\n/**\n * @stable\n */\nexport interface InitCommandResult {\n  readonly configPath: string;\n  readonly bootstrapToken: string;\n  readonly serverPepperHex: string;\n  readonly cloudConsent: 'public-only' | 'public-and-internal' | 'all-with-warnings';\n  readonly storageEncrypted: boolean;\n}\n\n/**\n * @stable\n */\nexport async function runInit(options: InitCommandOptions = {}): Promise<InitCommandResult> {\n  const cwd = options.cwd ?? process.cwd();\n  const target = resolveOutPath(cwd, options.out);\n  const print = options.print ?? ((line: string) => process.stderr.write(`${line}\\n`));\n\n  const cloudConsent = await resolveCloudConsent(options);\n  const storageEncrypted = await resolveEncryption(options);\n\n  const pepper = generatePepper();\n  const pepperHex = await pepper.useBuffer((buf) => buf.toString('hex'));\n\n  const bootstrap = generateRawToken({ env: 'live' });\n\n  if (options.dryRun !== true) {\n    if (await fileExists(target)) {\n      throw new Error(\n        `[graphorin/cli] refusing to overwrite existing '${target}'. Move it aside or pass --out <path>.`,\n      );\n    }\n    await mkdir(dirname(target), { recursive: true });\n    await writeFile(target, renderConfig({ cloudConsent, storageEncrypted }), { mode: 0o600 });\n  }\n\n  print(`[graphorin/cli] wrote ${target}`);\n  print(`[graphorin/cli] bootstrap admin token (shown ONCE):`);\n  print(`  ${bootstrap.raw}`);\n  print(`[graphorin/cli] server pepper hex (store in your keyring as 'graphorin_server_pepper'):`);\n  print(`  ${pepperHex}`);\n  print('');\n  print('Next steps:');\n  print(\n    `  1. Persist the pepper: graphorin secrets set graphorin_server_pepper --value ${pepperHex}`,\n  );\n  print(`  2. Persist the bootstrap token securely; do NOT commit it.`);\n  print(`  3. Run \\`graphorin migrate --config ${target}\\` to apply storage migrations.`);\n  print(`  4. Run \\`graphorin start --config ${target}\\` to launch the server.`);\n\n  return Object.freeze({\n    configPath: target,\n    bootstrapToken: bootstrap.raw,\n    serverPepperHex: pepperHex,\n    cloudConsent,\n    storageEncrypted,\n  });\n}\n\nfunction resolveOutPath(cwd: string, out: string | undefined): string {\n  if (out === undefined || out.length === 0) return resolve(cwd, 'graphorin.config.ts');\n  return isAbsolute(out) ? out : resolve(cwd, out);\n}\n\nasync function fileExists(path: string): Promise<boolean> {\n  try {\n    await stat(path);\n    return true;\n  } catch {\n    return false;\n  }\n}\n\nasync function resolveCloudConsent(\n  options: InitCommandOptions,\n): Promise<'public-only' | 'public-and-internal' | 'all-with-warnings'> {\n  if (options.cloudConsent !== undefined) return options.cloudConsent;\n  const envValue = process.env.GRAPHORIN_CLOUD_CONSENT;\n  if (\n    envValue === 'public-only' ||\n    envValue === 'public-and-internal' ||\n    envValue === 'all-with-warnings'\n  ) {\n    return envValue;\n  }\n  if (options.nonInteractive === true) return 'public-and-internal';\n  const choice = await select(\n    'Cloud-upload consent for context sent to providers:',\n    ['public-only', 'public-and-internal', 'all-with-warnings'],\n    'public-and-internal',\n  );\n  return choice as 'public-only' | 'public-and-internal' | 'all-with-warnings';\n}\n\nasync function resolveEncryption(options: InitCommandOptions): Promise<boolean> {\n  if (options.encrypted !== undefined) return options.encrypted;\n  if (process.env.GRAPHORIN_STORAGE_ENCRYPTED === '1') return true;\n  if (process.env.GRAPHORIN_STORAGE_ENCRYPTED === '0') return false;\n  if (options.nonInteractive === true) return false;\n  return await confirm('Enable storage encryption (defense-in-depth on top of FDE)?', false);\n}\n\nfunction renderConfig(input: {\n  readonly cloudConsent: 'public-only' | 'public-and-internal' | 'all-with-warnings';\n  readonly storageEncrypted: boolean;\n}): string {\n  return `import { defineConfig } from '@graphorin/server';\n\nexport default defineConfig({\n  server: {\n    host: '127.0.0.1',\n    port: 8080,\n  },\n  auth: {\n    kind: 'token',\n    pepperRef: 'keyring:graphorin_server_pepper',\n  },\n  storage: {\n    path: './.graphorin/data.db',\n    mode: 'server',\n    encryption: ${\n      input.storageEncrypted\n        ? `{\n      enabled: true,\n      passphraseRef: 'keyring:graphorin_db_passphrase',\n    }`\n        : `{ enabled: false }`\n    },\n  },\n  audit: {\n    enabled: ${input.storageEncrypted ? 'true' : 'false'},\n  },\n  secrets: {\n    source: 'auto',\n    strict: false,\n  },\n  observability: {\n    logger: 'json',\n  },\n  // IP-5: no top-level 'defaults' block — the strict server-config\n  // parser rejects unknown keys, so the old render made a fresh\n  // 'graphorin init' fail on the very next migrate/start. The tier you\n  // chose at init is recorded below; enforce it via the memory\n  // package (createMemory contextEngine privacy options):\n  // cloudUploadConsent: ${JSON.stringify(input.cloudConsent)}\n});\n`;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;AAoDA,eAAsB,QAAQ,UAA8B,EAAE,EAA8B;CAE1F,MAAM,SAAS,eADH,QAAQ,OAAO,QAAQ,KAAK,EACL,QAAQ,IAAI;CAC/C,MAAM,QAAQ,QAAQ,WAAW,SAAiB,QAAQ,OAAO,MAAM,GAAG,KAAK,IAAI;CAEnF,MAAM,eAAe,MAAM,oBAAoB,QAAQ;CACvD,MAAM,mBAAmB,MAAM,kBAAkB,QAAQ;CAGzD,MAAM,YAAY,MADH,gBAAgB,CACA,WAAW,QAAQ,IAAI,SAAS,MAAM,CAAC;CAEtE,MAAM,YAAY,iBAAiB,EAAE,KAAK,QAAQ,CAAC;AAEnD,KAAI,QAAQ,WAAW,MAAM;AAC3B,MAAI,MAAM,WAAW,OAAO,CAC1B,OAAM,IAAI,MACR,mDAAmD,OAAO,wCAC3D;AAEH,QAAM,MAAM,QAAQ,OAAO,EAAE,EAAE,WAAW,MAAM,CAAC;AACjD,QAAM,UAAU,QAAQ,aAAa;GAAE;GAAc;GAAkB,CAAC,EAAE,EAAE,MAAM,KAAO,CAAC;;AAG5F,OAAM,yBAAyB,SAAS;AACxC,OAAM,sDAAsD;AAC5D,OAAM,KAAK,UAAU,MAAM;AAC3B,OAAM,0FAA0F;AAChG,OAAM,KAAK,YAAY;AACvB,OAAM,GAAG;AACT,OAAM,cAAc;AACpB,OACE,kFAAkF,YACnF;AACD,OAAM,+DAA+D;AACrE,OAAM,yCAAyC,OAAO,iCAAiC;AACvF,OAAM,uCAAuC,OAAO,0BAA0B;AAE9E,QAAO,OAAO,OAAO;EACnB,YAAY;EACZ,gBAAgB,UAAU;EAC1B,iBAAiB;EACjB;EACA;EACD,CAAC;;AAGJ,SAAS,eAAe,KAAa,KAAiC;AACpE,KAAI,QAAQ,UAAa,IAAI,WAAW,EAAG,QAAO,QAAQ,KAAK,sBAAsB;AACrF,QAAO,WAAW,IAAI,GAAG,MAAM,QAAQ,KAAK,IAAI;;AAGlD,eAAe,WAAW,MAAgC;AACxD,KAAI;AACF,QAAM,KAAK,KAAK;AAChB,SAAO;SACD;AACN,SAAO;;;AAIX,eAAe,oBACb,SACsE;AACtE,KAAI,QAAQ,iBAAiB,OAAW,QAAO,QAAQ;CACvD,MAAM,WAAW,QAAQ,IAAI;AAC7B,KACE,aAAa,iBACb,aAAa,yBACb,aAAa,oBAEb,QAAO;AAET,KAAI,QAAQ,mBAAmB,KAAM,QAAO;AAM5C,QALe,MAAM,OACnB,uDACA;EAAC;EAAe;EAAuB;EAAoB,EAC3D,sBACD;;AAIH,eAAe,kBAAkB,SAA+C;AAC9E,KAAI,QAAQ,cAAc,OAAW,QAAO,QAAQ;AACpD,KAAI,QAAQ,IAAI,gCAAgC,IAAK,QAAO;AAC5D,KAAI,QAAQ,IAAI,gCAAgC,IAAK,QAAO;AAC5D,KAAI,QAAQ,mBAAmB,KAAM,QAAO;AAC5C,QAAO,MAAM,QAAQ,+DAA+D,MAAM;;AAG5F,SAAS,aAAa,OAGX;AACT,QAAO;;;;;;;;;;;;;;kBAeH,MAAM,mBACF;;;SAIA,qBACL;;;eAGU,MAAM,mBAAmB,SAAS,QAAQ;;;;;;;;;;;;;;2BAc9B,KAAK,UAAU,MAAM,aAAa,CAAC"}

package/dist/commands/memory.d.ts

@@ -0,0 +1,243 @@
+import { CommonOutputOptions } from "../internal/output.js";
+
+//#region src/commands/memory.d.ts
+
+/** @stable */
+interface MemoryCommonOptions extends CommonOutputOptions {
+  readonly config?: string;
+}
+/** @stable */
+interface MemoryStatusEmbedder {
+  readonly id: string;
+  readonly model: string;
+  readonly dim: number;
+  readonly distanceMetric: string;
+  readonly retired: boolean;
+  readonly createdAt: string;
+  readonly retiredAt?: string;
+}
+/** @stable */
+interface MemoryStatusResult {
+  readonly storagePath: string;
+  readonly embedders: ReadonlyArray<MemoryStatusEmbedder>;
+  readonly counts: {
+    readonly facts: number;
+    readonly episodes: number;
+    readonly sessionMessages: number;
+    readonly procedures: number;
+  };
+}
+/** @stable */
+declare function runMemoryStatus(options?: MemoryCommonOptions): Promise<MemoryStatusResult>;
+/** @stable */
+interface MemoryMigrateOptions extends MemoryCommonOptions {
+  readonly from: string;
+  readonly to: string;
+  readonly strategy: 'lock-on-first' | 'auto-migrate' | 'multi-active';
+  /**
+   * Optional path to a JS / TS module exporting an
+   * `embedders` object: `{ <id>: () => EmbedderProvider }`. The CLI
+   * imports this module so it can construct the source / target
+   * embedder instances the runner needs. Without the module the
+   * command exits `2` with a pointer to the documentation.
+   */
+  readonly embeddersModule?: string;
+}
+/**
+ * `graphorin memory migrate` — embedder swap. The migration logic lives
+ * in `@graphorin/memory`'s `migrateEmbedder(...)`; the CLI prints a
+ * pointer when the operator did not supply the embedder factory module
+ * (the framework cannot guess the operator's embedder configuration).
+ *
+ * @stable
+ */
+declare function runMemoryMigrate(options: MemoryMigrateOptions): Promise<never>;
+/** @stable */
+interface MemoryInspectFact {
+  readonly id: string;
+  readonly text: string;
+  readonly status: string;
+  readonly provenance: string | null;
+  /** X-1 / migration 015: per-fact importance (salience hint), if set. */
+  readonly importance: number | null;
+  readonly validFrom: string | null;
+  readonly validTo: string | null;
+  readonly supersedes: string | null;
+  readonly supersededBy: string | null;
+  readonly createdAt: string;
+}
+/**
+ * A canonical entity a fact links to (P2-1 / migration 016). `name` follows
+ * `merged_into` to the surviving entity, so a merged link shows its canonical.
+ *
+ * @stable
+ */
+interface MemoryInspectEntity {
+  readonly entityId: string;
+  readonly name: string;
+  readonly role: string;
+  /** Set when the linked entity was merged into `entityId`/`name`. */
+  readonly mergedFrom: string | null;
+}
+/** @stable */
+interface MemoryHistoryEntry {
+  readonly event: string;
+  readonly source: string;
+  readonly createdAt: string;
+}
+/** @stable */
+interface MemoryConflictEntry {
+  readonly candidateId: string;
+  readonly existingId: string | null;
+  readonly decision: string;
+  readonly stage: string;
+  readonly similarity: number | null;
+  readonly detectedAt: string;
+}
+/** @stable */
+interface MemoryCitingInsight {
+  readonly id: string;
+  readonly text: string;
+  readonly status: string;
+  readonly salience: number;
+}
+/** @stable */
+interface MemoryInspectResult {
+  readonly found: boolean;
+  readonly fact: MemoryInspectFact | null;
+  readonly chain: ReadonlyArray<MemoryInspectFact>;
+  readonly history: ReadonlyArray<MemoryHistoryEntry>;
+  readonly conflicts: ReadonlyArray<MemoryConflictEntry>;
+  readonly citingInsights: ReadonlyArray<MemoryCitingInsight>;
+  /** Canonical entities this fact links to (P2-1 / migration 016). */
+  readonly linkedEntities: ReadonlyArray<MemoryInspectEntity>;
+}
+/** @stable */
+interface MemoryInspectOptions extends MemoryCommonOptions {
+  readonly factId: string;
+}
+/**
+ * `graphorin memory inspect <factId>` — surface everything the store
+ * knows about one fact: its retrieval-trust status + provenance, the
+ * full bi-temporal supersede chain it belongs to, the audit-log events
+ * recorded against it, the conflict decisions that referenced it, and
+ * the (quarantined) insights that cite it. Pure read-only inspection.
+ *
+ * @stable
+ */
+declare function runMemoryInspect(options: MemoryInspectOptions): Promise<MemoryInspectResult>;
+/** @stable */
+interface MemoryActivityEvent {
+  readonly memoryKind: string;
+  readonly memoryId: string;
+  readonly event: string;
+  readonly source: string;
+  readonly createdAt: string;
+}
+/** @stable */
+interface MemoryActivityConflict {
+  readonly candidateId: string;
+  readonly existingId: string | null;
+  readonly decision: string;
+  readonly stage: string;
+  readonly detectedAt: string;
+}
+/** @stable */
+interface MemoryActivityResult {
+  readonly quarantine: {
+    readonly facts: number;
+    readonly episodes: number;
+    readonly insights: number;
+  };
+  readonly recentHistory: ReadonlyArray<MemoryActivityEvent>;
+  readonly recentConflicts: ReadonlyArray<MemoryActivityConflict>;
+}
+/** @stable */
+interface MemoryActivityOptions extends MemoryCommonOptions {
+  /** Cap on the recent-history / recent-conflict rows returned. Default 20. */
+  readonly limit?: number;
+}
+/**
+ * `graphorin memory activity` — a store-wide view of what the
+ * consolidator and reflection passes have been doing: how many facts /
+ * episodes / insights currently sit in quarantine, the most recent
+ * audit-log events (supersede / validate / quarantine / archive), and
+ * the most recent conflict decisions. Pure read-only inspection.
+ *
+ * @stable
+ */
+declare function runMemoryActivity(options?: MemoryActivityOptions): Promise<MemoryActivityResult>;
+/** A single decoded recall explanation surfaced by `graphorin memory why`. */
+interface MemoryWhyRecall {
+  readonly spanId: string;
+  /** Span start time (unix nanos) of the recall. */
+  readonly at: number;
+  readonly results: ReadonlyArray<{
+    readonly id: string;
+    readonly rank: number;
+    readonly score: number;
+    readonly signals: Readonly<Record<string, number>>;
+  }>;
+}
+/** @stable */
+interface MemoryWhyResult {
+  readonly recalls: ReadonlyArray<MemoryWhyRecall>;
+}
+/** @stable */
+interface MemoryWhyOptions extends MemoryCommonOptions {
+  /** Restrict to one session's recall spans. */
+  readonly sessionId?: string;
+  /** Cap on the most-recent recall spans returned. Default 5. */
+  readonly limit?: number;
+}
+/**
+ * `graphorin memory why` — explain why facts were recalled, by decoding the
+ * `memory.search.semantic.explain` attribute off the persisted recall spans.
+ * Pure read-only inspection; requires the SQLite span exporter to have recorded
+ * spans (RP-17). Empty when nothing was recorded.
+ *
+ * @stable
+ */
+declare function runMemoryWhy(options: MemoryWhyOptions): Promise<MemoryWhyResult>;
+/** A single quarantined memory row surfaced by `graphorin memory review`. */
+interface MemoryReviewItem {
+  readonly id: string;
+  readonly text: string;
+  readonly provenance: string | null;
+}
+/** @stable */
+interface MemoryReviewResult {
+  /** Set when `--promote <id>` succeeded. */
+  readonly promoted?: {
+    readonly id: string;
+    readonly type: string;
+  };
+  readonly facts: ReadonlyArray<MemoryReviewItem>;
+  readonly episodes: ReadonlyArray<MemoryReviewItem>;
+  readonly insights: ReadonlyArray<MemoryReviewItem>;
+  readonly procedures: ReadonlyArray<MemoryReviewItem>;
+}
+/** @stable */
+interface MemoryReviewOptions extends MemoryCommonOptions {
+  /** Cap on the rows listed per type. Default 20. */
+  readonly limit?: number;
+  /** Promote this id out of quarantine instead of listing. */
+  readonly promote?: string;
+  /** Audit reason recorded with the promotion. */
+  readonly reason?: string;
+  /** Override the injection-refusal gate (operator action, after review). */
+  readonly force?: boolean;
+}
+/**
+ * `graphorin memory review` — list the facts / episodes / insights / induced
+ * procedures the consolidator left in quarantine (read-only), or promote a
+ * reviewed item out of quarantine with `--promote <id>`. The promote path runs
+ * through the tier `validate(...)`, so an injection-flagged memory is refused
+ * unless `--force` is supplied after review (MCON-2).
+ *
+ * @stable
+ */
+declare function runMemoryReview(options?: MemoryReviewOptions): Promise<MemoryReviewResult>;
+//#endregion
+export { MemoryActivityConflict, MemoryActivityEvent, MemoryActivityOptions, MemoryActivityResult, MemoryCitingInsight, MemoryCommonOptions, MemoryConflictEntry, MemoryHistoryEntry, MemoryInspectEntity, MemoryInspectFact, MemoryInspectOptions, MemoryInspectResult, MemoryMigrateOptions, MemoryReviewItem, MemoryReviewOptions, MemoryReviewResult, MemoryStatusEmbedder, MemoryStatusResult, MemoryWhyOptions, MemoryWhyRecall, MemoryWhyResult, runMemoryActivity, runMemoryInspect, runMemoryMigrate, runMemoryReview, runMemoryStatus, runMemoryWhy };
+//# sourceMappingURL=memory.d.ts.map

package/dist/commands/memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","names":[],"sources":["../../src/commands/memory.ts"],"sourcesContent":[],"mappings":";;;;;AAyPgC,UAxNf,mBAAA,SAA4B,mBAwNb,CAAA;EAAd,SAAA,MAAA,CAAA,EAAA,MAAA;;;AAEkB,UArNnB,oBAAA,CAqNmB;EAAd,SAAA,EAAA,EAAA,MAAA;EACmB,SAAA,KAAA,EAAA,MAAA;EAAd,SAAA,GAAA,EAAA,MAAA;EAEc,SAAA,cAAA,EAAA,MAAA;EAAd,SAAA,OAAA,EAAA,OAAA;EAAa,SAAA,SAAA,EAAA,MAAA;EAIvB,SAAA,SAAA,CAAA,EAAA,MAAqB;AAatC;;AAEW,UAhOM,kBAAA,CAgON;EAAR,SAAA,WAAA,EAAA,MAAA;EAAO,SAAA,SAAA,EA9NY,aA8NZ,CA9N0B,oBA8N1B,CAAA;EAwJO,SAAA,MAAA,EAAA;IASA,SAAA,KAAA,EAAA,MAAsB;IAStB,SAAA,QAAA,EAAoB,MAAA;IAMG,SAAA,eAAA,EAAA,MAAA;IAAd,SAAA,UAAA,EAAA,MAAA;EACgB,CAAA;;;AAIzB,iBAzYK,eAAA,CAyYyB,OAAmB,CAAnB,EAxYpC,mBAwYuD,CAAA,EAvY/D,OAuY+D,CAvYvD,kBAuYuD,CAAA;AAclE;AACW,UAtWM,oBAAA,SAA6B,mBAsWnC,CAAA;EACA,SAAA,IAAA,EAAA,MAAA;EAAR,SAAA,EAAA,EAAA,MAAA;EAAO,SAAA,QAAA,EAAA,eAAA,GAAA,cAAA,GAAA,cAAA;EAiGO;;;;;AAajB;AAKA;EAqBsB,SAAA,eAAY,CAAA,EAAA,MAAA;;;;;AAyElC;AAOA;;;;AAIqB,iBA7iBC,gBAAA,CA6iBD,OAAA,EA7iB2B,oBA6iB3B,CAAA,EA7iBkD,OA6iBlD,CAAA,KAAA,CAAA;;AACA,UAnfJ,iBAAA,CAmfI;EACgB,SAAA,EAAA,EAAA,MAAA;EAAd,SAAA,IAAA,EAAA,MAAA;EAAa,SAAA,MAAA,EAAA,MAAA;EAInB,SAAA,UAAA,EAAA,MAAoB,GAAA,IAAQ;EA2BvB;EACX,SAAA,UAAA,EAAA,MAAA,GAAA,IAAA;EACA,SAAA,SAAA,EAAA,MAAA,GAAA,IAAA;EAAR,SAAA,OAAA,EAAA,MAAA,GAAA,IAAA;EAAO,SAAA,UAAA,EAAA,MAAA,GAAA,IAAA;;;;;;;;;;UAjgBO,mBAAA;;;;;;;;UASA,kBAAA;;;;;;UAOA,mBAAA;;;;;;;;;UAUA,mBAAA;;;;;;;UAQA,mBAAA;;iBAEA;kBACC,cAAc;oBACZ,cAAc;sBACZ,cAAc;2BACT,cAAc;;2BAEd,cAAc;;;UAIxB,oBAAA,SAA6B;;;;;;;;;;;;iBAaxB,gBAAA,UACX,uBACR,QAAQ;;UAwJM,mBAAA;;;;;;;;UASA,sBAAA;;;;;;;;UASA,oBAAA;;;;;;0BAMS,cAAc;4BACZ,cAAc;;;UAIzB,qBAAA,SAA8B;;;;;;;;;;;;;iBAczB,iBAAA,WACX,wBACR,QAAQ;;UAiGM,eAAA;;;;oBAIG;;;;sBAIE,SAAS;;;;UAKd,eAAA;oBACG,cAAc;;;UAIjB,gBAAA,SAAyB;;;;;;;;;;;;;;iBAqBpB,YAAA,UAAsB,mBAAmB,QAAQ;;UAyEtD,gBAAA;;;;;;UAOA,kBAAA;;;;;;kBAGC,cAAc;qBACX,cAAc;qBACd,cAAc;uBACZ,cAAc;;;UAIpB,mBAAA,SAA4B;;;;;;;;;;;;;;;;;;;iBA2BvB,eAAA,WACX,sBACR,QAAQ"}