@unbrained/pm-cli 2026.7.14 → 2026.7.15

package/dist/cli/commands/gc.js

@@ -1,276 +1,10 @@
 /**
  * @module cli/commands/gc
  *
- * Implements the pm gc command surface and its agent-facing runtime behavior.
+ * Compatibility adapter for the SDK-owned maintenance and garbage-collection engine.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="710fdc3d-a93c-57dc-a014-61c41b8be67a")}catch(e){}}();
-import fs from "node:fs/promises";
-import path from "node:path";
-import { runCheckpointGc } from "../../core/checkpoint/checkpoint-gc.js";
-import { runActiveOnIndexHooks, runActiveOnReadHooks, runActiveOnWriteHooks, } from "../../core/extensions/index.js";
-import { pathExists } from "../../core/fs/fs-utils.js";
-import { runLockGc } from "../../core/lock/lock-gc.js";
-import { EXIT_CODE } from "../../core/shared/constants.js";
-import { PmCliError } from "../../core/shared/errors.js";
-import { nowIso } from "../../core/shared/time.js";
-import { getSettingsPath, resolvePmRoot } from "../../core/store/paths.js";
-import { readSettings } from "../../core/store/settings.js";
-const GC_SCOPE_VALUES = [
-    "index",
-    "embeddings",
-    "runtime",
-    "locks",
-    "checkpoints",
-];
-const GC_TARGETS = [
-    {
-        scope: "index",
-        relativePath: "index/manifest.json",
-        kind: "file",
-    },
-    {
-        scope: "embeddings",
-        relativePath: "search/embeddings.jsonl",
-        kind: "file",
-    },
-    {
-        scope: "embeddings",
-        relativePath: "search/vectorization-status.json",
-        kind: "file",
-    },
-    {
-        scope: "embeddings",
-        relativePath: "search/lancedb",
-        kind: "directory",
-    },
-    {
-        // Removing embeddings invalidates the whole semantic index, so the queued
-        // background-refresh work is also meaningless: a worker draining a stale
-        // queue against an empty ledger would rebuild a partial, inconsistent index
-        // (only the queued items vectorized). Clear the queue and its gate so the
-        // next mutation re-seeds from a clean slate. See core/search/background-refresh.ts.
-        scope: "embeddings",
-        relativePath: "search/pending-refresh.json",
-        kind: "file",
-    },
-    {
-        scope: "embeddings",
-        relativePath: "search/pending-refresh.gate.lock",
-        kind: "directory",
-    },
-    {
-        scope: "runtime",
-        relativePath: "runtime/test-runs",
-        kind: "directory",
-    },
-    {
-        scope: "runtime",
-        relativePath: "runtime/history-drift-cache.json",
-        kind: "file",
-    },
-];
-function isErrno(error, code) {
-    return (typeof error === "object" &&
-        error !== null &&
-        "code" in error &&
-        error.code === code);
-}
-async function removeCacheFile(pmRoot, target, dryRun) {
-    const relativePath = target.relativePath;
-    const absolutePath = path.join(pmRoot, relativePath);
-    const warnings = await runActiveOnReadHooks({
-        path: absolutePath,
-        scope: "project",
-    });
-    try {
-        const stats = await fs.stat(absolutePath);
-        if (target.kind === "file" && !stats.isFile()) {
-            return {
-                removed: false,
-                warnings: [...warnings, `not_a_file:${relativePath}`],
-            };
-        }
-        if (target.kind === "directory" && !stats.isDirectory()) {
-            return {
-                removed: false,
-                warnings: [...warnings, `not_a_directory:${relativePath}`],
-            };
-        }
-        if (dryRun) {
-            return {
-                removed: true,
-                warnings,
-            };
-        }
-        if (target.kind === "file") {
-            await fs.unlink(absolutePath);
-        }
-        else {
-            await fs.rm(absolutePath, { recursive: true, force: true });
-        }
-        const writeWarnings = await runActiveOnWriteHooks({
-            path: absolutePath,
-            scope: "project",
-            op: "gc:remove",
-        });
-        return {
-            removed: true,
-            warnings: [...warnings, ...writeWarnings],
-        };
-    }
-    catch (error) {
-        if (isErrno(error, "ENOENT")) {
-            return {
-                removed: false,
-                warnings,
-            };
-        }
-        throw error;
-    }
-}
-function parseScopes(raw) {
-    if (!raw || raw.length === 0) {
-        return [...GC_SCOPE_VALUES];
-    }
-    const tokens = raw
-        .flatMap((entry) => entry.split(","))
-        .map((entry) => entry.trim().toLowerCase())
-        .filter((entry) => entry.length > 0);
-    if (tokens.length === 0) {
-        throw new PmCliError(`--scope requires at least one value (${GC_SCOPE_VALUES.join(",")})`, EXIT_CODE.USAGE);
-    }
-    const resolved = new Set();
-    for (const token of tokens) {
-        if (!GC_SCOPE_VALUES.includes(token)) {
-            throw new PmCliError(`Invalid --scope value "${token}". Expected one or more of: ${GC_SCOPE_VALUES.join(", ")}`, EXIT_CODE.USAGE);
-        }
-        resolved.add(token);
-    }
-    return GC_SCOPE_VALUES.filter((scope) => resolved.has(scope));
-}
-function buildGcGuidance(params) {
-    const guidance = [];
-    if (params.dryRun) {
-        guidance.push("Dry-run preview only: no cache artifacts were deleted.");
-    }
-    const searchScopeSelected = params.scopes.includes("index") || params.scopes.includes("embeddings");
-    const searchArtifactsAffected = params.removed.some((entry) => entry === "index/manifest.json" ||
-        entry === "search/embeddings.jsonl" ||
-        entry === "search/vectorization-status.json" ||
-        entry === "search/lancedb" ||
-        entry === "search/pending-refresh.json" ||
-        entry === "search/pending-refresh.gate.lock");
-    if (searchScopeSelected && searchArtifactsAffected) {
-        guidance.push('Search artifacts were removed; the semantic index (including any queued background refresh) is invalidated. Run "pm install search-advanced --project" if reindex is unavailable, then "pm reindex --mode keyword" (and "--mode semantic" when semantic search is enabled) before search-heavy workflows.');
-    }
-    if (params.removed.includes("runtime/history-drift-cache.json")) {
-        guidance.push('History drift cache was removed; the next "pm health" run performs a full history-drift re-scan.');
-    }
-    if (!params.dryRun &&
-        params.removed.some((entry) => entry.startsWith("checkpoints/"))) {
-        guidance.push('Aged rollback checkpoints were removed; their "pm update-many"/"pm close-many --rollback" windows are no longer recoverable.');
-    }
-    return guidance;
-}
-/** Implements run gc for the public runtime surface of this module. */
-export async function runGc(global, options = {}) {
-    const pmRoot = resolvePmRoot(process.cwd(), global.path);
-    if (!(await pathExists(getSettingsPath(pmRoot)))) {
-        throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);
-    }
-    const settings = await readSettings(pmRoot);
-    const dryRun = options.dryRun === true;
-    const scopes = parseScopes(options.scope);
-    const selectedTargets = GC_TARGETS.filter((target) => scopes.includes(target.scope));
-    const removed = [];
-    const retained = [];
-    const warnings = [];
-    for (const target of selectedTargets) {
-        const result = await removeCacheFile(pmRoot, target, dryRun);
-        if (result.removed) {
-            removed.push(target.relativePath);
-        }
-        else {
-            retained.push(target.relativePath);
-        }
-        warnings.push(...result.warnings);
-    }
-    // The locks scope is not a path-based GC_TARGET: it sweeps the locks/ directory
-    // and removes only locks whose own embedded ttl has expired (crashed-process
-    // debris), retaining active and unparseable locks. See core/lock/lock-gc.ts.
-    let locksSummary;
-    if (scopes.includes("locks")) {
-        const lockResult = await runLockGc(pmRoot, {
-            dryRun,
-            hooks: {
-                onRead: (lockPath) => runActiveOnReadHooks({ path: lockPath, scope: "project" }),
-                onWrite: (lockPath) => runActiveOnWriteHooks({
-                    path: lockPath,
-                    scope: "project",
-                    op: "gc:lock_remove",
-                }),
-            },
-        });
-        removed.push(...lockResult.removed);
-        retained.push(...lockResult.retained);
-        warnings.push(...lockResult.warnings);
-        locksSummary = {
-            scanned: lockResult.scanned,
-            removed: lockResult.removed.length,
-            retained: lockResult.retained.length,
-        };
-    }
-    // The checkpoints scope is also not a path-based GC_TARGET: it sweeps
-    // checkpoints/ and removes only rollback checkpoints older than the configured
-    // checkpoints.retention_days, retaining active and unparseable files. See
-    // core/checkpoint/checkpoint-gc.ts.
-    let checkpointsSummary;
-    if (scopes.includes("checkpoints")) {
-        const retentionDays = settings.checkpoints.retention_days;
-        const checkpointResult = await runCheckpointGc(pmRoot, {
-            dryRun,
-            retentionDays,
-            hooks: {
-                onRead: (checkpointPath) => runActiveOnReadHooks({ path: checkpointPath, scope: "project" }),
-                onWrite: (checkpointPath) => runActiveOnWriteHooks({
-                    path: checkpointPath,
-                    scope: "project",
-                    op: "gc:checkpoint_remove",
-                }),
-            },
-        });
-        removed.push(...checkpointResult.removed);
-        retained.push(...checkpointResult.retained);
-        warnings.push(...checkpointResult.warnings);
-        checkpointsSummary = {
-            scanned: checkpointResult.scanned,
-            removed: checkpointResult.removed.length,
-            retained: checkpointResult.retained.length,
-            retention_days: retentionDays,
-        };
-    }
-    warnings.push(...(await runActiveOnIndexHooks({
-        mode: dryRun ? "gc:dry-run" : "gc",
-        total_items: selectedTargets.length,
-    })));
-    const guidance = buildGcGuidance({
-        dryRun,
-        scopes,
-        removed,
-    });
-    return {
-        ok: warnings.length === 0,
-        dry_run: dryRun,
-        scope: scopes,
-        removed,
-        retained,
-        warnings,
-        ...(locksSummary ? { locks: locksSummary } : {}),
-        ...(checkpointsSummary ? { checkpoints: checkpointsSummary } : {}),
-        guidance,
-        generated_at: nowIso(),
-    };
-}
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="f8fdc0cf-cf97-5a26-95c9-58a3eadc911b")}catch(e){}}();
+export * from "../../sdk/governance/gc.js";
 //# sourceMappingURL=gc.js.map
-//# debugId=710fdc3d-a93c-57dc-a014-61c41b8be67a
+//# debugId=f8fdc0cf-cf97-5a26-95c9-58a3eadc911b

package/dist/cli/commands/gc.js.map

@@ -1 +1 @@
-{"version":3,"file":"gc.js","sources":["cli/commands/gc.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module cli/commands/gc\n *\n * Implements the pm gc command surface and its agent-facing runtime behavior.\n */\nimport fs from \"node:fs/promises\";\nimport path from \"node:path\";\nimport { runCheckpointGc } from \"../../core/checkpoint/checkpoint-gc.js\";\nimport {\n  runActiveOnIndexHooks,\n  runActiveOnReadHooks,\n  runActiveOnWriteHooks,\n} from \"../../core/extensions/index.js\";\nimport { pathExists } from \"../../core/fs/fs-utils.js\";\nimport { runLockGc } from \"../../core/lock/lock-gc.js\";\nimport { EXIT_CODE } from \"../../core/shared/constants.js\";\nimport type { GlobalOptions } from \"../../core/shared/command-types.js\";\nimport { PmCliError } from \"../../core/shared/errors.js\";\nimport { nowIso } from \"../../core/shared/time.js\";\nimport { getSettingsPath, resolvePmRoot } from \"../../core/store/paths.js\";\nimport { readSettings } from \"../../core/store/settings.js\";\n\nconst GC_SCOPE_VALUES = [\n  \"index\",\n  \"embeddings\",\n  \"runtime\",\n  \"locks\",\n  \"checkpoints\",\n] as const;\ntype GcScope = (typeof GC_SCOPE_VALUES)[number];\n\ninterface GcTarget {\n  scope: GcScope;\n  relativePath: string;\n  kind: \"file\" | \"directory\";\n}\n\nconst GC_TARGETS: readonly GcTarget[] = [\n  {\n    scope: \"index\",\n    relativePath: \"index/manifest.json\",\n    kind: \"file\",\n  },\n  {\n    scope: \"embeddings\",\n    relativePath: \"search/embeddings.jsonl\",\n    kind: \"file\",\n  },\n  {\n    scope: \"embeddings\",\n    relativePath: \"search/vectorization-status.json\",\n    kind: \"file\",\n  },\n  {\n    scope: \"embeddings\",\n    relativePath: \"search/lancedb\",\n    kind: \"directory\",\n  },\n  {\n    // Removing embeddings invalidates the whole semantic index, so the queued\n    // background-refresh work is also meaningless: a worker draining a stale\n    // queue against an empty ledger would rebuild a partial, inconsistent index\n    // (only the queued items vectorized). Clear the queue and its gate so the\n    // next mutation re-seeds from a clean slate. See core/search/background-refresh.ts.\n    scope: \"embeddings\",\n    relativePath: \"search/pending-refresh.json\",\n    kind: \"file\",\n  },\n  {\n    scope: \"embeddings\",\n    relativePath: \"search/pending-refresh.gate.lock\",\n    kind: \"directory\",\n  },\n  {\n    scope: \"runtime\",\n    relativePath: \"runtime/test-runs\",\n    kind: \"directory\",\n  },\n  {\n    scope: \"runtime\",\n    relativePath: \"runtime/history-drift-cache.json\",\n    kind: \"file\",\n  },\n] as const;\n\n/** Documents the gc command options payload exchanged by command, SDK, and package integrations. */\nexport interface GcCommandOptions {\n  /** Value that configures or reports dry run for this contract. */\n  dryRun?: boolean;\n  /** Value that configures or reports scope for this contract. */\n  scope?: string[];\n}\n\n/** Documents the gc locks summary payload exchanged by command, SDK, and package integrations. */\nexport interface GcLocksSummary {\n  /** Value that configures or reports scanned for this contract. */\n  scanned: number;\n  /** Value that configures or reports removed for this contract. */\n  removed: number;\n  /** Value that configures or reports retained for this contract. */\n  retained: number;\n}\n\n/** Documents the gc checkpoints summary payload exchanged by command, SDK, and package integrations. */\nexport interface GcCheckpointsSummary {\n  /** Value that configures or reports scanned for this contract. */\n  scanned: number;\n  /** Value that configures or reports removed for this contract. */\n  removed: number;\n  /** Value that configures or reports retained for this contract. */\n  retained: number;\n  /** Value that configures or reports retention days for this contract. */\n  retention_days: number;\n}\n\n/** Documents the gc result payload exchanged by command, SDK, and package integrations. */\nexport interface GcResult {\n  /** Whether the operation completed without a blocking failure. */\n  ok: boolean;\n  /** Value that configures or reports dry run for this contract. */\n  dry_run: boolean;\n  /** Value that configures or reports scope for this contract. */\n  scope: GcScope[];\n  /** Value that configures or reports removed for this contract. */\n  removed: string[];\n  /** Value that configures or reports retained for this contract. */\n  retained: string[];\n  /** Value that configures or reports warnings for this contract. */\n  warnings: string[];\n  /** Value that configures or reports guidance for this contract. */\n  guidance: string[];\n  /** Present only when the locks scope was selected. Summarizes the stale-lock sweep. */\n  locks?: GcLocksSummary;\n  /** Present only when the checkpoints scope was selected. Summarizes the rollback-checkpoint sweep. */\n  checkpoints?: GcCheckpointsSummary;\n  /** ISO 8601 timestamp recording when generated occurred. */\n  generated_at: string;\n}\n\nfunction isErrno(error: unknown, code: string): boolean {\n  return (\n    typeof error === \"object\" &&\n    error !== null &&\n    \"code\" in error &&\n    (error as { code?: string }).code === code\n  );\n}\n\nasync function removeCacheFile(\n  pmRoot: string,\n  target: GcTarget,\n  dryRun: boolean,\n): Promise<{ removed: boolean; warnings: string[] }> {\n  const relativePath = target.relativePath;\n  const absolutePath = path.join(pmRoot, relativePath);\n  const warnings = await runActiveOnReadHooks({\n    path: absolutePath,\n    scope: \"project\",\n  });\n  try {\n    const stats = await fs.stat(absolutePath);\n    if (target.kind === \"file\" && !stats.isFile()) {\n      return {\n        removed: false,\n        warnings: [...warnings, `not_a_file:${relativePath}`],\n      };\n    }\n    if (target.kind === \"directory\" && !stats.isDirectory()) {\n      return {\n        removed: false,\n        warnings: [...warnings, `not_a_directory:${relativePath}`],\n      };\n    }\n    if (dryRun) {\n      return {\n        removed: true,\n        warnings,\n      };\n    }\n    if (target.kind === \"file\") {\n      await fs.unlink(absolutePath);\n    } else {\n      await fs.rm(absolutePath, { recursive: true, force: true });\n    }\n    const writeWarnings = await runActiveOnWriteHooks({\n      path: absolutePath,\n      scope: \"project\",\n      op: \"gc:remove\",\n    });\n    return {\n      removed: true,\n      warnings: [...warnings, ...writeWarnings],\n    };\n  } catch (error: unknown) {\n    if (isErrno(error, \"ENOENT\")) {\n      return {\n        removed: false,\n        warnings,\n      };\n    }\n    throw error;\n  }\n}\n\nfunction parseScopes(raw: string[] | undefined): GcScope[] {\n  if (!raw || raw.length === 0) {\n    return [...GC_SCOPE_VALUES];\n  }\n  const tokens = raw\n    .flatMap((entry) => entry.split(\",\"))\n    .map((entry) => entry.trim().toLowerCase())\n    .filter((entry) => entry.length > 0);\n  if (tokens.length === 0) {\n    throw new PmCliError(\n      `--scope requires at least one value (${GC_SCOPE_VALUES.join(\",\")})`,\n      EXIT_CODE.USAGE,\n    );\n  }\n  const resolved = new Set<GcScope>();\n  for (const token of tokens) {\n    if (!(GC_SCOPE_VALUES as readonly string[]).includes(token)) {\n      throw new PmCliError(\n        `Invalid --scope value \"${token}\". Expected one or more of: ${GC_SCOPE_VALUES.join(\", \")}`,\n        EXIT_CODE.USAGE,\n      );\n    }\n    resolved.add(token as GcScope);\n  }\n  return GC_SCOPE_VALUES.filter((scope) => resolved.has(scope));\n}\n\nfunction buildGcGuidance(params: {\n  dryRun: boolean;\n  scopes: GcScope[];\n  removed: string[];\n}): string[] {\n  const guidance: string[] = [];\n  if (params.dryRun) {\n    guidance.push(\"Dry-run preview only: no cache artifacts were deleted.\");\n  }\n  const searchScopeSelected =\n    params.scopes.includes(\"index\") || params.scopes.includes(\"embeddings\");\n  const searchArtifactsAffected = params.removed.some(\n    (entry) =>\n      entry === \"index/manifest.json\" ||\n      entry === \"search/embeddings.jsonl\" ||\n      entry === \"search/vectorization-status.json\" ||\n      entry === \"search/lancedb\" ||\n      entry === \"search/pending-refresh.json\" ||\n      entry === \"search/pending-refresh.gate.lock\",\n  );\n  if (searchScopeSelected && searchArtifactsAffected) {\n    guidance.push(\n      'Search artifacts were removed; the semantic index (including any queued background refresh) is invalidated. Run \"pm install search-advanced --project\" if reindex is unavailable, then \"pm reindex --mode keyword\" (and \"--mode semantic\" when semantic search is enabled) before search-heavy workflows.',\n    );\n  }\n  if (params.removed.includes(\"runtime/history-drift-cache.json\")) {\n    guidance.push(\n      'History drift cache was removed; the next \"pm health\" run performs a full history-drift re-scan.',\n    );\n  }\n  if (\n    !params.dryRun &&\n    params.removed.some((entry) => entry.startsWith(\"checkpoints/\"))\n  ) {\n    guidance.push(\n      'Aged rollback checkpoints were removed; their \"pm update-many\"/\"pm close-many --rollback\" windows are no longer recoverable.',\n    );\n  }\n  return guidance;\n}\n\n/** Implements run gc for the public runtime surface of this module. */\nexport async function runGc(\n  global: GlobalOptions,\n  options: GcCommandOptions = {},\n): Promise<GcResult> {\n  const pmRoot = resolvePmRoot(process.cwd(), global.path);\n  if (!(await pathExists(getSettingsPath(pmRoot)))) {\n    throw new PmCliError(\n      `Tracker is not initialized at ${pmRoot}. Run pm init first.`,\n      EXIT_CODE.NOT_FOUND,\n    );\n  }\n\n  const settings = await readSettings(pmRoot);\n  const dryRun = options.dryRun === true;\n  const scopes = parseScopes(options.scope);\n  const selectedTargets = GC_TARGETS.filter((target) =>\n    scopes.includes(target.scope),\n  );\n\n  const removed: string[] = [];\n  const retained: string[] = [];\n  const warnings: string[] = [];\n\n  for (const target of selectedTargets) {\n    const result = await removeCacheFile(pmRoot, target, dryRun);\n    if (result.removed) {\n      removed.push(target.relativePath);\n    } else {\n      retained.push(target.relativePath);\n    }\n    warnings.push(...result.warnings);\n  }\n\n  // The locks scope is not a path-based GC_TARGET: it sweeps the locks/ directory\n  // and removes only locks whose own embedded ttl has expired (crashed-process\n  // debris), retaining active and unparseable locks. See core/lock/lock-gc.ts.\n  let locksSummary: GcLocksSummary | undefined;\n  if (scopes.includes(\"locks\")) {\n    const lockResult = await runLockGc(pmRoot, {\n      dryRun,\n      hooks: {\n        onRead: (lockPath) =>\n          runActiveOnReadHooks({ path: lockPath, scope: \"project\" }),\n        onWrite: (lockPath) =>\n          runActiveOnWriteHooks({\n            path: lockPath,\n            scope: \"project\",\n            op: \"gc:lock_remove\",\n          }),\n      },\n    });\n    removed.push(...lockResult.removed);\n    retained.push(...lockResult.retained);\n    warnings.push(...lockResult.warnings);\n    locksSummary = {\n      scanned: lockResult.scanned,\n      removed: lockResult.removed.length,\n      retained: lockResult.retained.length,\n    };\n  }\n\n  // The checkpoints scope is also not a path-based GC_TARGET: it sweeps\n  // checkpoints/ and removes only rollback checkpoints older than the configured\n  // checkpoints.retention_days, retaining active and unparseable files. See\n  // core/checkpoint/checkpoint-gc.ts.\n  let checkpointsSummary: GcCheckpointsSummary | undefined;\n  if (scopes.includes(\"checkpoints\")) {\n    const retentionDays = settings.checkpoints.retention_days;\n    const checkpointResult = await runCheckpointGc(pmRoot, {\n      dryRun,\n      retentionDays,\n      hooks: {\n        onRead: (checkpointPath) =>\n          runActiveOnReadHooks({ path: checkpointPath, scope: \"project\" }),\n        onWrite: (checkpointPath) =>\n          runActiveOnWriteHooks({\n            path: checkpointPath,\n            scope: \"project\",\n            op: \"gc:checkpoint_remove\",\n          }),\n      },\n    });\n    removed.push(...checkpointResult.removed);\n    retained.push(...checkpointResult.retained);\n    warnings.push(...checkpointResult.warnings);\n    checkpointsSummary = {\n      scanned: checkpointResult.scanned,\n      removed: checkpointResult.removed.length,\n      retained: checkpointResult.retained.length,\n      retention_days: retentionDays,\n    };\n  }\n\n  warnings.push(\n    ...(await runActiveOnIndexHooks({\n      mode: dryRun ? \"gc:dry-run\" : \"gc\",\n      total_items: selectedTargets.length,\n    })),\n  );\n  const guidance = buildGcGuidance({\n    dryRun,\n    scopes,\n    removed,\n  });\n\n  return {\n    ok: warnings.length === 0,\n    dry_run: dryRun,\n    scope: scopes,\n    removed,\n    retained,\n    warnings,\n    ...(locksSummary ? { locks: locksSummary } : {}),\n    ...(checkpointsSummary ? { checkpoints: checkpointsSummary } : {}),\n    guidance,\n    generated_at: nowIso(),\n  };\n}\n"],"names":[],"mappings":"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","debugId":"710fdc3d-a93c-57dc-a014-61c41b8be67a"}
+{"version":3,"file":"gc.js","sources":["cli/commands/gc.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module cli/commands/gc\n *\n * Compatibility adapter for the SDK-owned maintenance and garbage-collection engine.\n */\nexport * from \"../../sdk/governance/gc.js\";\n"],"names":[],"mappings":"AAAA;;;;GAIG;;;AACH,cAAc,4BAA4B,CAAC","debugId":"f8fdc0cf-cf97-5a26-95c9-58a3eadc911b"}

package/dist/cli/commands/get.d.ts

@@ -1,4 +1,6 @@
 import type { GlobalOptions } from "../../core/shared/command-types.js";
+import { type ChildRollupContext } from "../../sdk/item-children.js";
+import { type ItemScheduleContext } from "../../sdk/item-schedule.js";
 import type { ItemMetadata, LinkedDoc, LinkedFile, LinkedTest } from "../../types/index.js";
 interface ClaimHistoryContext {
     ts: string;
@@ -11,11 +13,6 @@ interface ClaimStateContext {
     last_claim: ClaimHistoryContext | null;
     last_release: ClaimHistoryContext | null;
 }
-interface ChildRollupContext {
-    count: number;
-    active: number;
-    by_status: Record<string, number>;
-}
 /** Documents the get result payload exchanged by command, SDK, and package integrations. */
 export interface GetResult {
     /** Value that configures or reports item for this contract. */
@@ -32,6 +29,14 @@ export interface GetResult {
     claim_state?: ClaimStateContext;
     /** Value that configures or reports children for this contract. */
     children?: ChildRollupContext;
+    /** Normalized scheduling data for scheduled item types and metadata. */
+    schedule?: Partial<ItemScheduleContext>;
+    /** True when the item was reconstructed from immutable history. */
+    reconstructed?: true;
+    /** One-based history version represented by a reconstructed read. */
+    as_of_version?: number;
+    /** Timestamp of the last history entry included in a reconstructed read. */
+    as_of_timestamp?: string;
     /** Value that configures or reports tree for this contract. */
     tree?: {
         root_id: string;
@@ -41,6 +46,8 @@ export interface GetResult {
         items: Record<string, unknown>[];
     };
 }
+/** Decide whether a normal read should pay for a workspace-wide child projection. */
+declare function shouldAutoIncludeGetChildren(itemType: string): boolean;
 /** Documents the get options payload exchanged by command, SDK, and package integrations. */
 export interface GetOptions {
     /** Value that configures or reports depth for this contract. */
@@ -53,7 +60,13 @@ export interface GetOptions {
     tree?: boolean;
     /** Value that configures or reports tree depth for this contract. */
     treeDepth?: string;
+    /** One-based history version or ISO timestamp for a mutation-free read. */
+    at?: string;
 }
 /** Implements run get for the public runtime surface of this module. */
 export declare function runGet(id: string, global: GlobalOptions, options?: GetOptions): Promise<GetResult>;
+/** Public contract for test-only get command policy helpers. */
+export declare const _testOnlyGetCommand: {
+    shouldAutoIncludeGetChildren: typeof shouldAutoIncludeGetChildren;
+};
 export {};