@unbrained/pm-cli 2026.7.13 → 2026.7.14

package/dist/sdk/context-usage.d.ts

@@ -0,0 +1,79 @@
+import type { ContextRelevanceSurface } from "./context-relevance.js";
+/** One propensity row disclosed when context or next serves a candidate. */
+export interface ContextUsageServingRow {
+    /** Served item identifier. */
+    id: string;
+    /** One-based scorer rank. */
+    rank: number;
+    /** Whether the packer included the item. */
+    included: boolean;
+}
+/** Append-only serving or subsequent-touch event. */
+export type ContextUsageEvent = {
+    kind: "serve";
+    at: string;
+    author: string;
+    surface: ContextRelevanceSurface;
+    profile: string;
+    rows: ContextUsageServingRow[];
+} | {
+    kind: "touch";
+    at: string;
+    author: string;
+    item_id: string;
+    intent: string;
+};
+/** Runtime controls for the bounded derived ledger. */
+export interface ContextUsageLedgerOptions {
+    /** Tracker root containing the runtime directory. */
+    pmRoot: string;
+    /** Disable all reads and writes with zero filesystem work. */
+    enabled?: boolean;
+    /** Maximum retained event rows. */
+    maxEvents?: number;
+    /** Retention horizon in days. */
+    retentionDays?: number;
+    /** Deterministic timestamp override. */
+    now?: string;
+}
+/** Decayed per-item affinity derived for one author. */
+export interface ContextUsageAffinity {
+    /** Normalized affinity by item id. */
+    affinity: Record<string, number>;
+    /** Number of eligible served-then-touched judgments. */
+    positive_judgments: number;
+    /** Number of retained serving events inspected. */
+    serving_events: number;
+}
+/** Records a propensity-complete context/next serving event. */
+export declare function recordContextUsageServing(options: ContextUsageLedgerOptions & {
+    author: string;
+    surface: ContextRelevanceSurface;
+    profile: string;
+    rows: ContextUsageServingRow[];
+}): Promise<void>;
+/** Records one subsequent item read or mutation outcome. */
+export declare function recordContextUsageTouch(options: ContextUsageLedgerOptions & {
+    author: string;
+    itemId: string;
+    intent: string;
+}): Promise<void>;
+/**
+ * Records mutation outcomes as one append and one optional compaction pass.
+ */
+export declare function recordContextUsageTouches(options: ContextUsageLedgerOptions & {
+    /** Stable caller identity used to isolate affinity. */
+    author: string;
+    /** Item identifiers affected by the completed command. */
+    itemIds: readonly string[];
+    /** Command or workflow intent associated with the touches. */
+    intent: string;
+}): Promise<void>;
+/**
+ * Derives decayed served-then-touched affinity. A small exploration floor keeps
+ * ignored and unseen items eligible, preventing a popularity feedback lock-in.
+ */
+export declare function readContextUsageAffinity(options: ContextUsageLedgerOptions & {
+    author: string;
+    horizonHours?: number;
+}): Promise<ContextUsageAffinity>;

package/dist/sdk/context-usage.js

@@ -0,0 +1,193 @@
+/**
+ * @module sdk/context-usage
+ *
+ * Privacy-minimal, derived context-usage feedback primitives. The JSONL ledger
+ * contains only item ids, timestamps, authors, ranks, profiles, and command
+ * intents; it never enters item history and is safe to delete or rebuild.
+ */
+
+!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]="2f1439c6-25a5-526f-a491-d50ee348463f")}catch(e){}}();
+import { randomUUID } from "node:crypto";
+import { appendFile, mkdir, readFile, rename, stat, writeFile, } from "node:fs/promises";
+import path from "node:path";
+import { acquireLock } from "../core/lock/lock.js";
+const DEFAULT_MAX_EVENTS = 2_048;
+const DEFAULT_RETENTION_DAYS = 30;
+const DAY_MS = 86_400_000;
+const DEFAULT_COMPACTION_BYTES = 262_144;
+const CONTEXT_USAGE_LOCK_ID = "context-usage-ledger";
+function ledgerPath(pmRoot) {
+    return path.join(pmRoot, "runtime", "context-usage.jsonl");
+}
+function resolveNow(options) {
+    const iso = options.now ?? new Date().toISOString();
+    const ms = Date.parse(iso);
+    if (!Number.isFinite(ms))
+        throw new TypeError("Context usage now must be a valid timestamp");
+    return { iso: new Date(ms).toISOString(), ms };
+}
+async function readEvents(options) {
+    try {
+        const text = await readFile(ledgerPath(options.pmRoot), "utf8");
+        const events = text
+            .split("\n")
+            .filter(Boolean)
+            .flatMap((line) => {
+            try {
+                return [JSON.parse(line)];
+            }
+            catch {
+                return [];
+            }
+        });
+        const maxEvents = options.maxEvents ?? DEFAULT_MAX_EVENTS;
+        const retentionDays = options.retentionDays ?? DEFAULT_RETENTION_DAYS;
+        const cutoff = resolveNow(options).ms - retentionDays * DAY_MS;
+        return events
+            .filter((entry) => Date.parse(entry.at) >= cutoff)
+            .slice(-maxEvents);
+    }
+    catch {
+        return [];
+    }
+}
+async function appendEvents(options, events) {
+    const maxEvents = options.maxEvents ?? DEFAULT_MAX_EVENTS;
+    const retentionDays = options.retentionDays ?? DEFAULT_RETENTION_DAYS;
+    if (!Number.isInteger(maxEvents) ||
+        maxEvents < 1 ||
+        !Number.isFinite(retentionDays) ||
+        retentionDays <= 0) {
+        throw new TypeError("Context usage retention requires positive maxEvents and retentionDays");
+    }
+    const target = ledgerPath(options.pmRoot);
+    const runtimeDirectory = path.dirname(target);
+    const releaseLock = await acquireLock(options.pmRoot, CONTEXT_USAGE_LOCK_ID, 30, `context-usage:${process.pid}`, false, false, 3_000);
+    try {
+        await mkdir(runtimeDirectory, { recursive: true });
+        await appendFile(target, events.map((event) => `${JSON.stringify(event)}\n`).join(""), "utf8");
+        const customBounds = options.maxEvents !== undefined || options.retentionDays !== undefined;
+        if (!customBounds && (await stat(target)).size <= DEFAULT_COMPACTION_BYTES)
+            return;
+        const retained = await readEvents(options);
+        const temporary = `${target}.${process.pid}.${randomUUID()}.tmp`;
+        await writeFile(temporary, `${retained.map((entry) => JSON.stringify(entry)).join("\n")}\n`, "utf8");
+        await rename(temporary, target);
+    }
+    finally {
+        await releaseLock();
+    }
+}
+async function appendEvent(options, event) {
+    await appendEvents(options, [event]);
+}
+/** Records a propensity-complete context/next serving event. */
+export async function recordContextUsageServing(options) {
+    if (process.env.PM_CONTEXT_USAGE_DISABLED === "1" || options.enabled === false)
+        return;
+    if (!options.author.trim() ||
+        options.rows.some((row) => !row.id.trim() || !Number.isInteger(row.rank) || row.rank < 1)) {
+        throw new TypeError("Context usage serving requires an author and valid ranked rows");
+    }
+    await appendEvent(options, {
+        kind: "serve",
+        at: resolveNow(options).iso,
+        author: options.author.trim(),
+        surface: options.surface,
+        profile: options.profile.trim() || "balanced",
+        rows: options.rows,
+    });
+}
+/** Records one subsequent item read or mutation outcome. */
+export async function recordContextUsageTouch(options) {
+    if (process.env.PM_CONTEXT_USAGE_DISABLED === "1" || options.enabled === false)
+        return;
+    if (!options.author.trim() ||
+        !options.itemId.trim() ||
+        !options.intent.trim()) {
+        throw new TypeError("Context usage touch requires author, itemId, and intent");
+    }
+    await appendEvent(options, {
+        kind: "touch",
+        at: resolveNow(options).iso,
+        author: options.author.trim(),
+        item_id: options.itemId.trim(),
+        intent: options.intent.trim(),
+    });
+}
+/**
+ * Records mutation outcomes as one append and one optional compaction pass.
+ */
+export async function recordContextUsageTouches(options) {
+    if (process.env.PM_CONTEXT_USAGE_DISABLED === "1" || options.enabled === false || options.itemIds.length === 0)
+        return;
+    const author = options.author.trim();
+    const intent = options.intent.trim();
+    if (!author || !intent) {
+        throw new TypeError("Context usage touch requires author and intent");
+    }
+    const itemIds = new Set();
+    for (const itemId of options.itemIds) {
+        if (typeof itemId !== "string") {
+            throw new TypeError("Context usage touch requires string itemIds");
+        }
+        const trimmedId = itemId.trim();
+        if (!trimmedId)
+            throw new TypeError("Context usage touch requires non-empty itemId");
+        itemIds.add(trimmedId);
+    }
+    const at = resolveNow(options).iso;
+    const events = [...itemIds].map((itemId) => ({ kind: "touch", at, author, item_id: itemId, intent }));
+    await appendEvents(options, events);
+}
+function findTouchTimeInHorizon(touches, itemId, servedAt, horizonMs) {
+    return touches.find(({ entry, time }) => entry.item_id === itemId && time >= servedAt && time - servedAt <= horizonMs)?.time;
+}
+/**
+ * Derives decayed served-then-touched affinity. A small exploration floor keeps
+ * ignored and unseen items eligible, preventing a popularity feedback lock-in.
+ */
+export async function readContextUsageAffinity(options) {
+    if (process.env.PM_CONTEXT_USAGE_DISABLED === "1" || options.enabled === false)
+        return { affinity: {}, positive_judgments: 0, serving_events: 0 };
+    const events = await readEvents(options);
+    const now = resolveNow(options).ms;
+    const horizonMs = (options.horizonHours ?? 24) * 3_600_000;
+    if (!Number.isFinite(horizonMs) || horizonMs <= 0)
+        throw new TypeError("Context usage horizonHours must be positive");
+    const author = options.author.trim();
+    const touches = events
+        .filter((event) => event.kind === "touch" && event.author === author)
+        .map((entry) => ({ entry, time: Date.parse(entry.at) }));
+    const scores = new Map();
+    let servingEvents = 0;
+    let positiveJudgments = 0;
+    for (const event of events) {
+        if (event.kind !== "serve" || event.author !== author)
+            continue;
+        servingEvents += 1;
+        const servedAt = Date.parse(event.at);
+        for (const row of event.rows) {
+            if (!row.included)
+                continue;
+            const touchTime = findTouchTimeInHorizon(touches, row.id, servedAt, horizonMs);
+            if (touchTime === undefined)
+                continue;
+            positiveJudgments += 1;
+            const ageDays = Math.max(0, (now - touchTime) / DAY_MS);
+            scores.set(row.id, (scores.get(row.id) ?? 0) + Math.exp(-ageDays / 14));
+        }
+    }
+    const maximum = Math.max(0, ...scores.values());
+    const affinity = Object.fromEntries([...scores.entries()].map(([id, score]) => [
+        id,
+        0.05 + 0.95 * (maximum > 0 ? score / maximum : 0),
+    ]));
+    return {
+        affinity,
+        positive_judgments: positiveJudgments,
+        serving_events: servingEvents,
+    };
+}
+//# sourceMappingURL=context-usage.js.map
+//# debugId=2f1439c6-25a5-526f-a491-d50ee348463f

package/dist/sdk/context-usage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-usage.js","sources":["sdk/context-usage.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module sdk/context-usage\n *\n * Privacy-minimal, derived context-usage feedback primitives. The JSONL ledger\n * contains only item ids, timestamps, authors, ranks, profiles, and command\n * intents; it never enters item history and is safe to delete or rebuild.\n */\nimport { randomUUID } from \"node:crypto\";\nimport {\n  appendFile,\n  mkdir,\n  readFile,\n  rename,\n  stat,\n  writeFile,\n} from \"node:fs/promises\";\nimport path from \"node:path\";\nimport { acquireLock } from \"../core/lock/lock.js\";\nimport type { ContextRelevanceSurface } from \"./context-relevance.js\";\n\n/** One propensity row disclosed when context or next serves a candidate. */\nexport interface ContextUsageServingRow {\n  /** Served item identifier. */\n  id: string;\n  /** One-based scorer rank. */\n  rank: number;\n  /** Whether the packer included the item. */\n  included: boolean;\n}\n\n/** Append-only serving or subsequent-touch event. */\nexport type ContextUsageEvent =\n  | {\n      kind: \"serve\";\n      at: string;\n      author: string;\n      surface: ContextRelevanceSurface;\n      profile: string;\n      rows: ContextUsageServingRow[];\n    }\n  | {\n      kind: \"touch\";\n      at: string;\n      author: string;\n      item_id: string;\n      intent: string;\n    };\n\n/** Runtime controls for the bounded derived ledger. */\nexport interface ContextUsageLedgerOptions {\n  /** Tracker root containing the runtime directory. */\n  pmRoot: string;\n  /** Disable all reads and writes with zero filesystem work. */\n  enabled?: boolean;\n  /** Maximum retained event rows. */\n  maxEvents?: number;\n  /** Retention horizon in days. */\n  retentionDays?: number;\n  /** Deterministic timestamp override. */\n  now?: string;\n}\n\n/** Decayed per-item affinity derived for one author. */\nexport interface ContextUsageAffinity {\n  /** Normalized affinity by item id. */\n  affinity: Record<string, number>;\n  /** Number of eligible served-then-touched judgments. */\n  positive_judgments: number;\n  /** Number of retained serving events inspected. */\n  serving_events: number;\n}\n\nconst DEFAULT_MAX_EVENTS = 2_048;\nconst DEFAULT_RETENTION_DAYS = 30;\nconst DAY_MS = 86_400_000;\nconst DEFAULT_COMPACTION_BYTES = 262_144;\nconst CONTEXT_USAGE_LOCK_ID = \"context-usage-ledger\";\n\nfunction ledgerPath(pmRoot: string): string {\n  return path.join(pmRoot, \"runtime\", \"context-usage.jsonl\");\n}\n\nfunction resolveNow(options: ContextUsageLedgerOptions): {\n  iso: string;\n  ms: number;\n} {\n  const iso = options.now ?? new Date().toISOString();\n  const ms = Date.parse(iso);\n  if (!Number.isFinite(ms))\n    throw new TypeError(\"Context usage now must be a valid timestamp\");\n  return { iso: new Date(ms).toISOString(), ms };\n}\n\nasync function readEvents(\n  options: ContextUsageLedgerOptions,\n): Promise<ContextUsageEvent[]> {\n  try {\n    const text = await readFile(ledgerPath(options.pmRoot), \"utf8\");\n    const events = text\n      .split(\"\\n\")\n      .filter(Boolean)\n      .flatMap((line) => {\n        try {\n          return [JSON.parse(line) as ContextUsageEvent];\n        } catch {\n          return [];\n        }\n      });\n    const maxEvents = options.maxEvents ?? DEFAULT_MAX_EVENTS;\n    const retentionDays = options.retentionDays ?? DEFAULT_RETENTION_DAYS;\n    const cutoff = resolveNow(options).ms - retentionDays * DAY_MS;\n    return events\n      .filter((entry) => Date.parse(entry.at) >= cutoff)\n      .slice(-maxEvents);\n  } catch {\n    return [];\n  }\n}\n\nasync function appendEvents(\n  options: ContextUsageLedgerOptions,\n  events: readonly ContextUsageEvent[],\n): Promise<void> {\n  const maxEvents = options.maxEvents ?? DEFAULT_MAX_EVENTS;\n  const retentionDays = options.retentionDays ?? DEFAULT_RETENTION_DAYS;\n  if (\n    !Number.isInteger(maxEvents) ||\n    maxEvents < 1 ||\n    !Number.isFinite(retentionDays) ||\n    retentionDays <= 0\n  ) {\n    throw new TypeError(\n      \"Context usage retention requires positive maxEvents and retentionDays\",\n    );\n  }\n  const target = ledgerPath(options.pmRoot);\n  const runtimeDirectory = path.dirname(target);\n  const releaseLock = await acquireLock(\n    options.pmRoot,\n    CONTEXT_USAGE_LOCK_ID,\n    30,\n    `context-usage:${process.pid}`,\n    false,\n    false,\n    3_000,\n  );\n  try {\n    await mkdir(runtimeDirectory, { recursive: true });\n    await appendFile(target, events.map((event) => `${JSON.stringify(event)}\\n`).join(\"\"), \"utf8\");\n    const customBounds =\n      options.maxEvents !== undefined || options.retentionDays !== undefined;\n    if (!customBounds && (await stat(target)).size <= DEFAULT_COMPACTION_BYTES)\n      return;\n    const retained = await readEvents(options);\n    const temporary = `${target}.${process.pid}.${randomUUID()}.tmp`;\n    await writeFile(\n      temporary,\n      `${retained.map((entry) => JSON.stringify(entry)).join(\"\\n\")}\\n`,\n      \"utf8\",\n    );\n    await rename(temporary, target);\n  } finally {\n    await releaseLock();\n  }\n}\n\nasync function appendEvent(\n  options: ContextUsageLedgerOptions,\n  event: ContextUsageEvent,\n): Promise<void> {\n  await appendEvents(options, [event]);\n}\n\n/** Records a propensity-complete context/next serving event. */\nexport async function recordContextUsageServing(\n  options: ContextUsageLedgerOptions & {\n    author: string;\n    surface: ContextRelevanceSurface;\n    profile: string;\n    rows: ContextUsageServingRow[];\n  },\n): Promise<void> {\n  if (process.env.PM_CONTEXT_USAGE_DISABLED === \"1\" || options.enabled === false) return;\n  if (\n    !options.author.trim() ||\n    options.rows.some(\n      (row) => !row.id.trim() || !Number.isInteger(row.rank) || row.rank < 1,\n    )\n  ) {\n    throw new TypeError(\n      \"Context usage serving requires an author and valid ranked rows\",\n    );\n  }\n  await appendEvent(options, {\n    kind: \"serve\",\n    at: resolveNow(options).iso,\n    author: options.author.trim(),\n    surface: options.surface,\n    profile: options.profile.trim() || \"balanced\",\n    rows: options.rows,\n  });\n}\n\n/** Records one subsequent item read or mutation outcome. */\nexport async function recordContextUsageTouch(\n  options: ContextUsageLedgerOptions & {\n    author: string;\n    itemId: string;\n    intent: string;\n  },\n): Promise<void> {\n  if (process.env.PM_CONTEXT_USAGE_DISABLED === \"1\" || options.enabled === false) return;\n  if (\n    !options.author.trim() ||\n    !options.itemId.trim() ||\n    !options.intent.trim()\n  ) {\n    throw new TypeError(\n      \"Context usage touch requires author, itemId, and intent\",\n    );\n  }\n  await appendEvent(options, {\n    kind: \"touch\",\n    at: resolveNow(options).iso,\n    author: options.author.trim(),\n    item_id: options.itemId.trim(),\n    intent: options.intent.trim(),\n  });\n}\n\n/**\n * Records mutation outcomes as one append and one optional compaction pass.\n */\nexport async function recordContextUsageTouches(\n  options: ContextUsageLedgerOptions & {\n    /** Stable caller identity used to isolate affinity. */\n    author: string;\n    /** Item identifiers affected by the completed command. */\n    itemIds: readonly string[];\n    /** Command or workflow intent associated with the touches. */\n    intent: string;\n  },\n): Promise<void> {\n  if (process.env.PM_CONTEXT_USAGE_DISABLED === \"1\" || options.enabled === false || options.itemIds.length === 0) return;\n  const author = options.author.trim();\n  const intent = options.intent.trim();\n  if (!author || !intent) {\n    throw new TypeError(\"Context usage touch requires author and intent\");\n  }\n  const itemIds = new Set<string>();\n  for (const itemId of options.itemIds) {\n    if (typeof itemId !== \"string\") {\n      throw new TypeError(\"Context usage touch requires string itemIds\");\n    }\n    const trimmedId = itemId.trim();\n    if (!trimmedId) throw new TypeError(\"Context usage touch requires non-empty itemId\");\n    itemIds.add(trimmedId);\n  }\n  const at = resolveNow(options).iso;\n  const events = [...itemIds].map(\n    (itemId): ContextUsageEvent => ({ kind: \"touch\", at, author, item_id: itemId, intent }),\n  );\n  await appendEvents(options, events);\n}\n\nfunction findTouchTimeInHorizon(\n  touches: readonly { entry: Extract<ContextUsageEvent, { kind: \"touch\" }>; time: number }[],\n  itemId: string,\n  servedAt: number,\n  horizonMs: number,\n): number | undefined {\n  return touches.find(({ entry, time }) =>\n    entry.item_id === itemId && time >= servedAt && time - servedAt <= horizonMs\n  )?.time;\n}\n\n/**\n * Derives decayed served-then-touched affinity. A small exploration floor keeps\n * ignored and unseen items eligible, preventing a popularity feedback lock-in.\n */\nexport async function readContextUsageAffinity(\n  options: ContextUsageLedgerOptions & {\n    author: string;\n    horizonHours?: number;\n  },\n): Promise<ContextUsageAffinity> {\n  if (process.env.PM_CONTEXT_USAGE_DISABLED === \"1\" || options.enabled === false)\n    return { affinity: {}, positive_judgments: 0, serving_events: 0 };\n  const events = await readEvents(options);\n  const now = resolveNow(options).ms;\n  const horizonMs = (options.horizonHours ?? 24) * 3_600_000;\n  if (!Number.isFinite(horizonMs) || horizonMs <= 0)\n    throw new TypeError(\"Context usage horizonHours must be positive\");\n  const author = options.author.trim();\n  const touches = events\n    .filter(\n      (event): event is Extract<ContextUsageEvent, { kind: \"touch\" }> =>\n        event.kind === \"touch\" && event.author === author,\n    )\n    .map((entry) => ({ entry, time: Date.parse(entry.at) }));\n  const scores = new Map<string, number>();\n  let servingEvents = 0;\n  let positiveJudgments = 0;\n  for (const event of events) {\n    if (event.kind !== \"serve\" || event.author !== author) continue;\n    servingEvents += 1;\n    const servedAt = Date.parse(event.at);\n    for (const row of event.rows) {\n      if (!row.included) continue;\n      const touchTime = findTouchTimeInHorizon(touches, row.id, servedAt, horizonMs);\n      if (touchTime === undefined) continue;\n      positiveJudgments += 1;\n      const ageDays = Math.max(0, (now - touchTime) / DAY_MS);\n      scores.set(row.id, (scores.get(row.id) ?? 0) + Math.exp(-ageDays / 14));\n    }\n  }\n  const maximum = Math.max(0, ...scores.values());\n  const affinity = Object.fromEntries(\n    [...scores.entries()].map(([id, score]) => [\n      id,\n      0.05 + 0.95 * (maximum > 0 ? score / maximum : 0),\n    ]),\n  );\n  return {\n    affinity,\n    positive_judgments: positiveJudgments,\n    serving_events: servingEvents,\n  };\n}\n"],"names":[],"mappings":"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","debugId":"2f1439c6-25a5-526f-a491-d50ee348463f"}

package/dist/sdk/dependencies.d.ts

@@ -0,0 +1,145 @@
+import type { GlobalOptions } from "../core/shared/command-types.js";
+import type { Dependency, ItemStatus, ItemType } from "../types/index.js";
+/** Supported values accepted by the deps format contract. */
+export declare const DEPS_FORMAT_VALUES: readonly ["tree", "graph"];
+/** Restricts deps format values accepted by command, SDK, and storage contracts. */
+export type DepsFormat = (typeof DEPS_FORMAT_VALUES)[number];
+/** Supported values accepted by the deps collapse contract. */
+export declare const DEPS_COLLAPSE_VALUES: readonly ["none", "repeated"];
+/** Restricts deps collapse mode values accepted by command, SDK, and storage contracts. */
+export type DepsCollapseMode = (typeof DEPS_COLLAPSE_VALUES)[number];
+/** Documents the deps command options payload exchanged by command, SDK, and package integrations. */
+export interface DepsCommandOptions {
+    /** Value that configures or reports format for this contract. */
+    format?: string;
+    /** Value that configures or reports max depth for this contract. */
+    maxDepth?: string | number;
+    /** Value that configures or reports collapse for this contract. */
+    collapse?: string;
+    /** Value that configures or reports summary for this contract. */
+    summary?: boolean;
+}
+/** Minimal item shape inspected by dependency-reference governance. */
+export interface DependencyReferenceHolder {
+    /** Stable item identifier. */
+    id: string;
+    /** Lifecycle status used to separate actionable work from historical debt. */
+    status: ItemStatus;
+    /** Optional hierarchy parent reference. */
+    parent?: string;
+    /** Optional legacy scalar blocker reference. */
+    blocked_by?: string;
+    /** Structured dependency edges. */
+    dependencies?: Dependency[];
+}
+/** Storage surface that contributed a normalized dependency reference. */
+export type DependencyReferenceSource = "parent" | "blocked_by" | "dependency";
+/** One normalized dependency reference whose target is absent from the tracker. */
+export interface DanglingDependencyReference {
+    /** Item that owns the reference. */
+    holder_id: string;
+    /** Missing referenced item id or legacy sentinel. */
+    target_id: string;
+    /** Relationship field or dependency kind. */
+    kind: string;
+    /** Storage surface that owns the reference and determines its remediation. */
+    source: DependencyReferenceSource;
+    /** Current lifecycle status of the holder. */
+    holder_status: ItemStatus;
+    /** Whether the holder is terminal and therefore historical, non-actionable debt. */
+    legacy_terminal: boolean;
+    /** Whether the target is the pre-structured-dependency `no-active-blocker` sentinel. */
+    no_active_blocker_sentinel: boolean;
+}
+/** Actionable and historical partitions returned by dependency-reference governance. */
+export interface DanglingDependencyReferenceSummary {
+    /** Missing references held by active items; these may affect scheduling and should gate validation. */
+    active: DanglingDependencyReference[];
+    /** Missing references held only by terminal items; retained as informational history debt. */
+    legacy_terminal: DanglingDependencyReference[];
+    /** Legacy sentinel rows across active and terminal holders, called out separately from typo-like ids. */
+    no_active_blocker_sentinels: DanglingDependencyReference[];
+}
+/**
+ * Classify missing hierarchy and dependency targets without mutating their holders.
+ *
+ * Consumers provide the workspace's terminal-status predicate so custom lifecycle
+ * schemas receive the same active-versus-historical behavior as the built-in
+ * closed/canceled statuses.
+ */
+export declare function collectDanglingDependencyReferences(items: readonly DependencyReferenceHolder[], isTerminal?: (status: ItemStatus) => boolean): DanglingDependencyReferenceSummary;
+/** Documents the deps tree node payload exchanged by command, SDK, and package integrations. */
+export interface DepsTreeNode {
+    /** Stable identifier used to reference this record across commands and storage. */
+    id: string;
+    /** Value that configures or reports title for this contract. */
+    title?: string;
+    /** Schema type that determines the shape and validation rules for this value. */
+    type?: ItemType;
+    /** Lifecycle state reported for status. */
+    status?: ItemStatus;
+    /** Value that configures or reports via for this contract. */
+    via?: string;
+    /** Value that configures or reports missing for this contract. */
+    missing: boolean;
+    /** Value that configures or reports cycle for this contract. */
+    cycle: boolean;
+    /** Value that configures or reports truncated for this contract. */
+    truncated?: boolean;
+    /** Value that configures or reports collapsed for this contract. */
+    collapsed?: boolean;
+    /** Value that configures or reports dependencies for this contract. */
+    dependencies: DepsTreeNode[];
+}
+/** Documents the deps graph node payload exchanged by command, SDK, and package integrations. */
+export interface DepsGraphNode {
+    /** Stable identifier used to reference this record across commands and storage. */
+    id: string;
+    /** Value that configures or reports title for this contract. */
+    title?: string;
+    /** Schema type that determines the shape and validation rules for this value. */
+    type?: ItemType;
+    /** Lifecycle state reported for status. */
+    status?: ItemStatus;
+    /** Value that configures or reports missing for this contract. */
+    missing: boolean;
+}
+/** Documents the deps graph edge payload exchanged by command, SDK, and package integrations. */
+export interface DepsGraphEdge {
+    /** Value that configures or reports from for this contract. */
+    from: string;
+    /** Value that configures or reports to for this contract. */
+    to: string;
+    /** Value that configures or reports kind for this contract. */
+    kind: string;
+}
+/** Documents the deps graph result payload exchanged by command, SDK, and package integrations. */
+export interface DepsGraphResult {
+    /** Value that configures or reports root id for this contract. */
+    root_id: string;
+    /** Value that configures or reports nodes for this contract. */
+    nodes: DepsGraphNode[];
+    /** Value that configures or reports edges for this contract. */
+    edges: DepsGraphEdge[];
+    /** Value that configures or reports missing ids for this contract. */
+    missing_ids: string[];
+}
+/** Documents the deps result payload exchanged by command, SDK, and package integrations. */
+export interface DepsResult {
+    /** Stable identifier used to reference this record across commands and storage. */
+    id: string;
+    /** Value that configures or reports format for this contract. */
+    format: DepsFormat;
+    /** Number of node entries represented by this result. */
+    node_count: number;
+    /** Number of edge entries represented by this result. */
+    edge_count: number;
+    /** Number of missing entries represented by this result. */
+    missing_count: number;
+    /** Value that configures or reports tree for this contract. */
+    tree?: DepsTreeNode;
+    /** Value that configures or reports graph for this contract. */
+    graph?: DepsGraphResult;
+}
+/** Implements run deps for the public runtime surface of this module. */
+export declare function runDeps(id: string, options: DepsCommandOptions, global: GlobalOptions): Promise<DepsResult>;