@unbrained/pm-cli 2026.8.20 → 2026.8.22

package/dist/sdk/query/list.js

@@ -4,8 +4,8 @@
  * Implements the pm list command surface and its agent-facing runtime behavior.
  */
 
-!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]="67c5ff91-1c04-5506-ae5b-32f6552f1d07")}catch(e){}}();
-import { pathExists } from "../../core/fs/fs-utils.js";
+!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]="93e8c187-e198-50fc-bf2c-7dae2ea42219")}catch(e){}}();
+import { assertInitializedTracker } from "../environment/tracker-preflight.js";
 import { getActiveExtensionRegistrations, hasActiveOnReadHooks, } from "../../core/extensions/index.js";
 import { toItemRecord } from "../../core/item/item-record.js";
 import { isTerminalStatus } from "../../core/item/status.js";
@@ -24,9 +24,11 @@ import { compareTimestampStrings, matchesTimestampFilters, nowIso, resolveIsoOrR
 import { listAllItemMetadata, listAllItemMetadataLight, listAllItemMetadataWithBody, } from "../../core/store/item-store.js";
 import { HEAVY_METADATA_KEYS, readItemMetadataDerivedIndexState, } from "../../core/store/item-metadata-cache.js";
 import { queryItemMetadataIndex } from "../../core/store/item-metadata-query-index.js";
-import { getSettingsPath, resolvePmRoot } from "../../core/store/paths.js";
+import { resolvePmRoot } from "../../core/store/paths.js";
 import { readSettings } from "../../core/store/settings.js";
 import { LIST_FILTER_FLAG_CONTRACTS } from "../cli-contracts/flag-contracts.js";
+import { resolveWorkspaceRelationshipKindRegistry } from "../graph/assembly.js";
+import { collectHierarchyRelations, indexHierarchyRelations, } from "../graph/hierarchy-integrity.js";
 import { createQueryFingerprint, encodeQueryCursor, resolveQueryCursorStart, selectCursorSemanticOptions, } from "../pagination.js";
 import { BRIEF_LIST_FIELDS, DEFAULT_COMPACT_LIST_FIELDS, listListProjectionFields, } from "./projection-contracts.js";
 export { BRIEF_LIST_FIELDS, DEFAULT_COMPACT_LIST_FIELDS, LIST_COMMAND_DEFAULT_PROJECTIONS, listListProjectionFields, } from "./projection-contracts.js";
@@ -640,7 +642,9 @@ function resolveListFilterSet(status, options, typeRegistry, statusRegistry) {
         parentFilter: options.parent?.trim(),
         treeEnabled: options.tree === true,
         sprintFilter: parseStringFilterSet(options.sprint, { label: "--sprint" }),
-        releaseFilter: parseStringFilterSet(options.release, { label: "--release" }),
+        releaseFilter: parseStringFilterSet(options.release, {
+            label: "--release",
+        }),
         missingMetadataFilters,
         missingMetadataActive: hasMissingMetadataFilter(missingMetadataFilters),
         lifecycleClassifier: lifecycleClassifierFromStatusRegistry(statusRegistry),
@@ -648,12 +652,6 @@ function resolveListFilterSet(status, options, typeRegistry, statusRegistry) {
         contentFiltersActive: hasContentFieldFilter(contentFieldFilters),
     };
 }
-function matchesListScalarFilters(item, filters, statusRegistry) {
-    return (matchesListIdentityFilters(item, filters, statusRegistry) &&
-        matchesListDateFilters(item, filters) &&
-        matchesListAssigneeFilterSet(item, filters) &&
-        matchesListScopeFilters(item, filters));
-}
 function matchesListIdentityFilters(item, filters, statusRegistry) {
     if (filters.idsFilter && !filters.idsFilter.has(item.id))
         return false;
@@ -681,10 +679,17 @@ function matchesListAssigneeFilterSet(item, filters) {
     return (filters.assigneeFilter === undefined ||
         (item.assignee !== undefined && filters.assigneeFilter.has(item.assignee)));
 }
-function matchesListScopeFilters(item, filters) {
+function matchesListScopeFilters(item, filters, parentsByChild) {
+    const scalarParent = item.parent?.trim().toLowerCase();
+    const logicalParentIds = [
+        ...new Set([
+            ...(parentsByChild?.get(item.id.trim().toLowerCase()) ?? []),
+            ...(scalarParent ? [scalarParent] : []),
+        ]),
+    ];
     if (filters.parentFilter !== undefined &&
         !filters.treeEnabled &&
-        item.parent !== filters.parentFilter)
+        !logicalParentIds.includes(filters.parentFilter.trim().toLowerCase()))
         return false;
     if (filters.sprintFilter !== undefined &&
         (item.sprint === undefined || !filters.sprintFilter.has(item.sprint)))
@@ -692,8 +697,11 @@ function matchesListScopeFilters(item, filters) {
     return (filters.releaseFilter === undefined ||
         (item.release !== undefined && filters.releaseFilter.has(item.release)));
 }
-function matchesListFilterSet(item, filters, statusRegistry, runtimeFieldFilters) {
-    if (!matchesListScalarFilters(item, filters, statusRegistry)) {
+function matchesListFilterSet(item, filters, statusRegistry, runtimeFieldFilters, parentsByChild) {
+    if (!matchesListIdentityFilters(item, filters, statusRegistry) ||
+        !matchesListDateFilters(item, filters) ||
+        !matchesListAssigneeFilterSet(item, filters) ||
+        !matchesListScopeFilters(item, filters, parentsByChild)) {
         return false;
     }
     if (filters.missingMetadataActive &&
@@ -709,9 +717,9 @@ function matchesListFilterSet(item, filters, statusRegistry, runtimeFieldFilters
     }
     return true;
 }
-function applyFilters(items, status, options, typeRegistry, statusRegistry, runtimeFieldFilters) {
+function applyFilters(items, status, options, typeRegistry, statusRegistry, runtimeFieldFilters, parentsByChild) {
     const filters = resolveListFilterSet(status, options, typeRegistry, statusRegistry);
-    return items.filter((item) => matchesListFilterSet(item, filters, statusRegistry, runtimeFieldFilters));
+    return items.filter((item) => matchesListFilterSet(item, filters, statusRegistry, runtimeFieldFilters, parentsByChild));
 }
 function trimNonEmpty(value) {
     if (typeof value !== "string") {
@@ -720,10 +728,12 @@ function trimNonEmpty(value) {
     const trimmed = value.trim();
     return trimmed.length > 0 ? trimmed : undefined;
 }
-function withTreeMetadata(item, depth, childCount) {
+function withTreeMetadata(item, depth, childCount, parentId) {
     const itemRecord = toItemRecord(item);
     const title = typeof itemRecord.title === "string" ? itemRecord.title : "";
-    const parent = trimNonEmpty(typeof itemRecord.parent === "string" ? itemRecord.parent : undefined) ?? null;
+    const parent = parentId ??
+        trimNonEmpty(typeof itemRecord.parent === "string" ? itemRecord.parent : undefined) ??
+        null;
     return {
         ...item,
         tree_depth: depth,
@@ -732,47 +742,73 @@ function withTreeMetadata(item, depth, childCount) {
         tree_title: `${"  ".repeat(depth)}${title}`,
     };
 }
-function orderItemsAsTree(sortedItems, parentRoot, maxDepth) {
+function buildListTreeIndexes(sortedItems, hierarchyIndexes) {
     const byId = new Map();
     const childrenByParent = new Map();
     for (const item of sortedItems) {
-        byId.set(item.id, item);
-        const parentId = trimNonEmpty(item.parent);
-        if (!parentId) {
-            continue;
-        }
-        const bucket = childrenByParent.get(parentId);
-        if (bucket) {
-            bucket.push(item);
-        }
-        else {
-            childrenByParent.set(parentId, [item]);
+        const itemId = item.id.trim().toLowerCase();
+        byId.set(itemId, item);
+        const parentIds = hierarchyIndexes
+            ? (hierarchyIndexes.parents_by_child.get(itemId) ?? [])
+            : [trimNonEmpty(item.parent)?.toLowerCase()].filter((value) => value !== undefined);
+        for (const parentId of parentIds) {
+            const children = childrenByParent.get(parentId) ?? [];
+            children.push(item);
+            childrenByParent.set(parentId, children);
         }
     }
-    const roots = parentRoot
-        ? [...(childrenByParent.get(parentRoot) ?? [])]
+    return { byId, childrenByParent };
+}
+function resolveListTreeRoots(sortedItems, parentRoot, byId, childrenByParent, hierarchyIndexes) {
+    return parentRoot
+        ? [...(childrenByParent.get(parentRoot.toLowerCase()) ?? [])]
         : sortedItems.filter((item) => {
-            const parentId = trimNonEmpty(item.parent);
-            return !parentId || !byId.has(parentId);
+            const parentIds = hierarchyIndexes
+                ? (hierarchyIndexes.parents_by_child.get(item.id.trim().toLowerCase()) ?? [])
+                : [trimNonEmpty(item.parent)?.toLowerCase()].filter((value) => value !== undefined);
+            return parentIds.every((parentId) => !byId.has(parentId));
         });
+}
+function orderItemsAsTree(sortedItems, parentRoot, maxDepth, hierarchyIndexes, completeItems = sortedItems) {
+    const { byId, childrenByParent } = buildListTreeIndexes(sortedItems, hierarchyIndexes);
+    const roots = resolveListTreeRoots(sortedItems, parentRoot, byId, childrenByParent, hierarchyIndexes);
     const ordered = [];
     const visited = new Set();
-    const pushNode = (node, depth) => {
-        if (visited.has(node.id)) {
-            return;
-        }
-        visited.add(node.id);
-        const children = childrenByParent.get(node.id) ?? [];
-        ordered.push(withTreeMetadata(node, depth, children.length));
-        if (maxDepth !== undefined && depth >= maxDepth) {
-            return;
+    const canonicalIdByLowercase = new Map(completeItems.map((item) => [item.id.trim().toLowerCase(), item.id.trim()]));
+    const pending = [...roots].reverse().map((node) => ({
+        node,
+        depth: 0,
+        parentId: parentRoot === undefined
+            ? undefined
+            : (canonicalIdByLowercase.get(parentRoot.trim().toLowerCase()) ??
+                parentRoot.trim()),
+    }));
+    while (pending.length > 0) {
+        const { node, depth, parentId } = pending.pop();
+        const nodeId = node.id.trim().toLowerCase();
+        if (visited.has(nodeId))
+            continue;
+        visited.add(nodeId);
+        const children = childrenByParent.get(nodeId) ?? [];
+        ordered.push(withTreeMetadata(node, depth, children.length, parentId));
+        if (maxDepth !== undefined && depth >= maxDepth)
+            continue;
+        for (const child of [...children].reverse()) {
+            pending.push({
+                node: child,
+                depth: depth + 1,
+                parentId: canonicalIdByLowercase.get(nodeId),
+            });
         }
-        for (const child of children) {
-            pushNode(child, depth + 1);
+    }
+    if (parentRoot === undefined && maxDepth === undefined) {
+        for (const item of sortedItems) {
+            const itemId = item.id.trim().toLowerCase();
+            if (visited.has(itemId))
+                continue;
+            visited.add(itemId);
+            ordered.push(withTreeMetadata(item, 0, childrenByParent.get(itemId)?.length ?? 0));
         }
-    };
-    for (const root of roots) {
-        pushNode(root, 0);
     }
     return ordered;
 }
@@ -891,9 +927,7 @@ function buildListPageExtras(limit, hasMore, nextCursor) {
 }
 async function resolveListRuntimeContext(options, global) {
     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);
-    }
+    await assertInitializedTracker(pmRoot);
     const settings = await readSettings(pmRoot);
     const statusRegistry = resolveRuntimeStatusRegistry(settings.schema);
     const runtimeFieldRegistry = resolveRuntimeFieldRegistry(settings.schema);
@@ -1138,8 +1172,12 @@ export async function runList(status, options, global) {
     let page = indexedPage;
     if (!page) {
         const items = await loadListItems(options, runtime, listWarnings);
+        const needsHierarchyIndexes = ordering.treeEnabled || trimNonEmpty(options.parent) !== undefined;
+        const hierarchyIndexes = needsHierarchyIndexes
+            ? indexHierarchyRelations(collectHierarchyRelations(items, resolveWorkspaceRelationshipKindRegistry()))
+            : undefined;
         appendUnknownTagWarning(items, options.tag, listWarnings);
-        const filtered = applyFilters(items, statusSelection.resolvedStatus, statusSelection.effectiveOptions, runtime.typeRegistry, runtime.statusRegistry, runtime.runtimeFieldFilters);
+        const filtered = applyFilters(items, statusSelection.resolvedStatus, statusSelection.effectiveOptions, runtime.typeRegistry, runtime.statusRegistry, runtime.runtimeFieldFilters, hierarchyIndexes?.parents_by_child);
         // Edge-aware blocked selection (GH-578): classify against the complete
         // loaded corpus so terminal blocker targets count as satisfied, then narrow
         // the already-filtered rows to the shared blocked set.
@@ -1151,7 +1189,7 @@ export async function runList(status, options, global) {
             : filtered;
         const sorted = sortItems(scoped, ordering.sortField, ordering.sortOrder, runtime.statusRegistry);
         const ordered = ordering.treeEnabled
-            ? orderItemsAsTree(sorted, ordering.parentRoot, ordering.treeDepth)
+            ? orderItemsAsTree(sorted, ordering.parentRoot, ordering.treeDepth, hierarchyIndexes, items)
             : sorted;
         page = pageAndProjectListItems(ordered, options, runtime.projection, ordering.treeEnabled, buildListCursorFingerprint(statusSelection.filtersStatus, options, ordering));
     }
@@ -1243,4 +1281,4 @@ export const _testOnly = {
     withTreeMetadata,
 };
 //# sourceMappingURL=list.js.map
-//# debugId=67c5ff91-1c04-5506-ae5b-32f6552f1d07
+//# debugId=93e8c187-e198-50fc-bf2c-7dae2ea42219

package/dist/sdk/query/search.js

@@ -4,7 +4,8 @@
  * Implements the pm search command surface and its agent-facing runtime behavior.
  */
 
-!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]="c650f22f-5fcd-5489-aa9b-da11c2d1db63")}catch(e){}}();
+!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]="a4117e19-af3e-50f5-b3cc-86c39aa4b439")}catch(e){}}();
+import { assertInitializedTracker } from "../environment/tracker-preflight.js";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { toNonEmptyStringOrUndefined } from "../../core/shared/primitives.js";
@@ -23,7 +24,6 @@ import { readVectorizationStatusLedger } from "../../core/search/cache.js";
 import { buildEventCorpus, buildPlanFlatCorpus, buildReminderCorpus, buildSearchCorpus, resolveSearchCorpusFields, } from "../../core/search/corpus.js";
 import { buildBm25Index, flattenSearchCorpusText, resolveBm25Params, scoreBm25Query, tokenizeBm25, } from "../../core/search/bm25.js";
 import { collectStaleVectorizationIds } from "../../core/search/staleness.js";
-import { pathExists } from "../../core/fs/fs-utils.js";
 import { parseItemDocument } from "../../core/item/item-format.js";
 import { toItemRecord } from "../../core/item/item-record.js";
 import { isTerminalStatus } from "../../core/item/status.js";
@@ -40,7 +40,7 @@ import { tokenizeAlphaNumeric } from "../../core/shared/text-normalization.js";
 import { compareTimestampStrings, matchesTimestampFilters, nowIso, } from "../../core/shared/time.js";
 import { listAllDocumentCandidatesCached } from "../../core/store/item-metadata-cache.js";
 import { listAllItemMetadata } from "../../core/store/item-store.js";
-import { getItemPath, getSettingsPath, resolveGlobalPmRoot, resolvePmRoot, } from "../../core/store/paths.js";
+import { getItemPath, resolveGlobalPmRoot, resolvePmRoot, } from "../../core/store/paths.js";
 import { readSettings } from "../../core/store/settings.js";
 import { resolveSearchPage } from "./search-pagination.js";
 import { normalizeSearchPhrase, parseMinScoreOverride, parseSearchBoolean, parseSearchDeadline, parseSearchMatchMode, parseSearchMode, parseSearchProjection, parseSearchTokens, parseSemanticWeightOverride, parseTimestampWindow, resolveHybridSemanticWeight, resolveSearchMaxResults, resolveSearchScoreThreshold, resolveSearchTuning, validateSearchProjectionFields, } from "./search-contracts.js";
@@ -1571,9 +1571,7 @@ function prepareSearchInput(rawQuery, rawOptions) {
 }
 async function resolveSearchRuntimeContext(prepared, global) {
     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);
-    }
+    await assertInitializedTracker(pmRoot);
     const storedSettings = await readSettings(pmRoot);
     const settings = resolveSettingsWithSemanticRuntimeDefaults(storedSettings).settings;
     const statusRegistry = resolveRuntimeStatusRegistry(settings.schema);
@@ -1987,4 +1985,4 @@ export async function runSearch(rawQuery, rawOptions, global) {
     return withSearchWorkspaceMemory(buildSearchResultForHits(response, projectedItems, total, page.limited.length, effectiveProjection, page.pageExtras), workspaceMemoryResult);
 }
 //# sourceMappingURL=search.js.map
-//# debugId=c650f22f-5fcd-5489-aa9b-da11c2d1db63
+//# debugId=a4117e19-af3e-50f5-b3cc-86c39aa4b439

package/dist/sdk/read-output-contracts.d.ts

@@ -5,7 +5,7 @@ export declare const PM_READ_OUTPUT_DIMENSIONS: readonly ["include", "amount", "
 /** One member of the universal read-output dimension set. */
 export type PmReadOutputDimension = (typeof PM_READ_OUTPUT_DIMENSIONS)[number];
 /** Built-in command roots whose primary operation is a read. */
-export declare const PM_READ_OUTPUT_SURFACES: readonly ["list", "context", "search", "get", "next", "health", "deps", "graph", "history", "activity", "validate", "events", "contracts", "comments", "notes", "files", "docs", "stats", "aggregate", "package-catalog", "package-manage", "comments-audit", "assurance"];
+export declare const PM_READ_OUTPUT_SURFACES: readonly ["list", "context", "search", "get", "next", "health", "deps", "graph", "history", "activity", "validate", "events", "contracts", "comments", "notes", "files", "docs", "stats", "aggregate", "duplicates", "package-catalog", "package-manage", "comments-audit", "assurance"];
 /** Built-in read command supported by the universal output contract. */
 export type PmReadOutputSurface = (typeof PM_READ_OUTPUT_SURFACES)[number];
 /** Canonical output controls accepted by every built-in read action. */
@@ -81,6 +81,8 @@ export interface PmResolvedReadOutputDimensions {
     cost?: PmResolvedReadOutputDimension<number | "unbounded">;
     /** Requested static encoding or a retained legacy streaming behavior. */
     encoding?: PmResolvedReadOutputDimension<"json" | "toon" | "stream">;
+    /** Canonical CLI options observed on the invocation. */
+    canonical_options_used?: string[];
     /** Compatibility flags observed on the invocation. */
     legacy_aliases_used: string[];
     /** One-line migration instructions for observed compatibility flags. */
@@ -102,6 +104,8 @@ export interface PmReadOutputReceipt {
     budget_tokens?: number;
     /** Deterministic precedence used during resolution. */
     precedence: readonly ["canonical", "legacy", "intent", "default"];
+    /** Canonical CLI options observed on the invocation. */
+    canonical_options_used?: string[];
     /** Compatibility options observed on the invocation. */
     legacy_aliases_used: string[];
     /** One-line migration instructions for compatibility options. */

package/dist/sdk/read-output-contracts.js

@@ -5,7 +5,7 @@
  * surface without coupling package authors to command-specific option names.
  */
 
-!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]="b3c001df-9891-5cf7-990b-8d9da7b51801")}catch(e){}}();
+!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]="a1272c1f-c03e-580c-8c44-6b3ddeedd240")}catch(e){}}();
 import { EXIT_CODE } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
 import { compactReadOutputToBudget, estimateReadOutputTokens, updateReadOutputReceiptEstimate, } from "./read-output-budget.js";
@@ -43,6 +43,7 @@ export const PM_READ_OUTPUT_SURFACES = [
     "docs",
     "stats",
     "aggregate",
+    "duplicates",
     "package-catalog",
     "package-manage",
     "comments-audit",
@@ -60,6 +61,7 @@ const CANONICAL_OPTIONS = {
     cost: "--output-budget",
     encoding: "--output-format",
 };
+const READ_OUTPUT_INVOCATION_PROVENANCE = Symbol.for("pm.readOutputInvocationProvenance");
 /** Canonical CLI flags that opt a read invocation into universal output shaping. */
 export const PM_READ_OUTPUT_OPTION_FLAGS = Object.freeze(PM_READ_OUTPUT_DIMENSIONS.map((dimension) => CANONICAL_OPTIONS[dimension]));
 /** Canonical control that composes the four per-call dimensions across reads. */
@@ -136,6 +138,7 @@ const LEGACY_FLAGS_BY_COMMAND = {
     docs: {},
     stats: {},
     aggregate: {},
+    duplicates: { amount: ["--limit"] },
     "package-catalog": {},
     "package-manage": {},
     "comments-audit": {},
@@ -363,14 +366,32 @@ export function applyReadOutputIncludeModes(command, includeValue, commandOption
     const modeOptions = readOutputIncludeModeOptions(command);
     const selectors = [];
     const modes = [];
+    const optionsWithProvenance = commandOptions;
+    const existingProvenance = optionsWithProvenance[READ_OUTPUT_INVOCATION_PROVENANCE];
+    const canonicalModes = new Set(existingProvenance?.canonical_include_modes ?? []);
+    const explicitLegacyAliases = new Set(existingProvenance?.explicit_legacy_aliases ?? []);
     for (const token of requested) {
         const option = modeOptions.get(token);
         if (option === undefined) {
             selectors.push(token);
             continue;
         }
+        const legacyFlag = `--${token.replaceAll("_", "-")}`;
+        if (isRequestedOption(readOption(commandOptions, legacyFlag))) {
+            explicitLegacyAliases.add(legacyFlag);
+        }
         commandOptions[option] = true;
         modes.push(token);
+        canonicalModes.add(token);
+    }
+    if (modes.length > 0) {
+        optionsWithProvenance[READ_OUTPUT_INVOCATION_PROVENANCE] = {
+            canonical_include_modes: [...canonicalModes],
+            explicit_legacy_aliases: [...explicitLegacyAliases],
+            ...(existingProvenance?.cli_invocation_observed === true
+                ? { cli_invocation_observed: true }
+                : {}),
+        };
     }
     return { selectors, modes };
 }
@@ -430,8 +451,10 @@ function positiveInteger(value) {
             : Number.NaN;
     return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : undefined;
 }
-function resolveLegacyDimension(contract, options, usable) {
+function resolveLegacyDimension(contract, options, usable, ignore) {
     for (const alias of contract.legacy_aliases) {
+        if (ignore(alias.flag))
+            continue;
         const value = readOption(options, alias.flag);
         const candidate = { value, flag: alias.flag };
         if (isRequestedOption(value) && usable(candidate))
@@ -496,12 +519,43 @@ function resolveEncodingValue(canonical, legacy) {
         ? { source: "legacy", value: legacy.value }
         : undefined;
 }
+function shouldIgnoreReadOutputLegacyAlias(provenance, dimension, flag) {
+    if (!provenance)
+        return false;
+    const explicitLegacyAliases = new Set(provenance.explicit_legacy_aliases);
+    if (provenance.cli_invocation_observed === true) {
+        return !explicitLegacyAliases.has(flag);
+    }
+    const forwardedIncludeAliases = new Set(provenance.canonical_include_modes.map((mode) => `--${mode.replaceAll("_", "-")}`));
+    return (dimension === "include" &&
+        forwardedIncludeAliases.has(flag) &&
+        !explicitLegacyAliases.has(flag));
+}
+function hasCompleteReadOutputIntent(command, legacyByDimension, provenance) {
+    const root = command
+        .trim()
+        .toLowerCase()
+        .replaceAll(/\s+/gu, " ")
+        .split(" ")[0];
+    return (root === "list-all" ||
+        legacyByDimension.amount?.flag === "--no-truncate" ||
+        legacyByDimension.include?.flag === "--full" ||
+        provenance?.canonical_include_modes.includes("full") === true);
+}
+function canonicalReadOutputOptionsUsed(resolvedByDimension, provenance) {
+    return PM_READ_OUTPUT_DIMENSIONS.flatMap((dimension) => resolvedByDimension[dimension]?.source === "canonical" ||
+        (dimension === "include" &&
+            (provenance?.canonical_include_modes.length ?? 0) > 0)
+        ? [CANONICAL_OPTIONS[dimension]]
+        : []);
+}
 /** Resolve canonical and compatibility controls into the universal dimension set. */
 export function resolveReadOutputDimensions(command, options) {
     const normalizedCommand = resolveReadOutputSurface(command, options);
     if (!normalizedCommand)
         return undefined;
     const contract = SURFACE_CONTRACT_BY_COMMAND.get(normalizedCommand);
+    const invocationProvenance = options[READ_OUTPUT_INVOCATION_PROVENANCE];
     const legacyResolvers = {
         include: (candidate) => resolveIncludeValue(undefined, candidate),
         amount: (candidate) => resolveAmountValue(undefined, candidate),
@@ -510,7 +564,7 @@ export function resolveReadOutputDimensions(command, options) {
     };
     const legacyByDimension = Object.fromEntries(PM_READ_OUTPUT_DIMENSIONS.map((dimension) => [
         dimension,
-        resolveLegacyDimension(contract.dimensions[dimension], options, (candidate) => legacyResolvers[dimension](candidate) !== undefined),
+        resolveLegacyDimension(contract.dimensions[dimension], options, (candidate) => legacyResolvers[dimension](candidate) !== undefined, (flag) => shouldIgnoreReadOutputLegacyAlias(invocationProvenance, dimension, flag)),
     ]));
     const legacyAliasesUsed = PM_READ_OUTPUT_DIMENSIONS.flatMap((dimension) => {
         const resolved = legacyByDimension[dimension];
@@ -524,29 +578,31 @@ export function resolveReadOutputDimensions(command, options) {
         return [alias.migration_hint];
     });
     const encoding = resolveEncodingValue(options.outputFormat ?? options.output_format, legacyByDimension.encoding);
+    const include = resolveIncludeValue(options.outputInclude ?? options.output_include, legacyByDimension.include);
+    const amount = resolveAmountValue(options.outputLimit ?? options.output_limit, legacyByDimension.amount);
     const explicitCost = resolveCostValue(options.outputBudget ?? options.output_budget, legacyByDimension.cost);
-    const completeResultIntent = command.trim().toLowerCase().replaceAll(/\s+/gu, " ").split(" ")[0] ===
-        "list-all" ||
-        legacyByDimension.amount?.flag === "--no-truncate" ||
-        legacyByDimension.include?.flag === "--full";
+    const completeResultIntent = hasCompleteReadOutputIntent(command, legacyByDimension, invocationProvenance);
     const budget = resolvePmCommandOutputBudget(command, {
         generateFallback: true,
     });
     const resolvedOutputFormat = encoding?.value === "json" || options.resolvedOutputFormat === "json"
         ? "json"
         : "toon";
+    const cost = explicitCost ??
+        (completeResultIntent
+            ? { source: "intent", value: "unbounded" }
+            : {
+                source: "default",
+                value: budget.default_max_estimated_tokens_by_format[resolvedOutputFormat],
+            });
+    const resolvedByDimension = { include, amount, cost, encoding };
     return {
         command: normalizedCommand,
-        include: resolveIncludeValue(options.outputInclude ?? options.output_include, legacyByDimension.include),
-        amount: resolveAmountValue(options.outputLimit ?? options.output_limit, legacyByDimension.amount),
-        cost: explicitCost ??
-            (completeResultIntent
-                ? { source: "intent", value: "unbounded" }
-                : {
-                    source: "default",
-                    value: budget.default_max_estimated_tokens_by_format[resolvedOutputFormat],
-                }),
+        include,
+        amount,
+        cost,
         encoding,
+        canonical_options_used: canonicalReadOutputOptionsUsed(resolvedByDimension, invocationProvenance),
         legacy_aliases_used: legacyAliasesUsed,
         migration_hints: migrationHints,
         precedence: READ_OUTPUT_PRECEDENCE,
@@ -732,8 +788,9 @@ function applyAmountBound(result, amount) {
     return bounded;
 }
 function requestedDimensions(resolved) {
-    return PM_READ_OUTPUT_DIMENSIONS.filter((dimension) => resolved[dimension] !== undefined &&
-        resolved[dimension]?.source !== "default");
+    return PM_READ_OUTPUT_DIMENSIONS.filter((dimension) => (resolved[dimension] !== undefined &&
+        resolved[dimension]?.source !== "default") ||
+        resolved.canonical_options_used.includes(CANONICAL_OPTIONS[dimension]));
 }
 /** Stabilize the per-call and cross-call receipts in one complete envelope. */
 function attachReadOutputSessionContracts(result, state, receipt) {
@@ -847,6 +904,12 @@ function resolveBindingReadOutputBudget(resolved, session) {
     ];
     return budgets.sort((left, right) => left.tokens - right.tokens)[0];
 }
+function canonicalReadOutputReceiptFields(resolved) {
+    const canonicalOptions = resolved.canonical_options_used;
+    return canonicalOptions && canonicalOptions.length > 0
+        ? { canonical_options_used: canonicalOptions }
+        : {};
+}
 /** Build the smallest truthful omission envelope or reject an exhausted session. */
 function omitReadOutputForBudget(resolved, requested, session, bindingBudget, omittedResultEstimatedTokens) {
     const minimalReceipt = {
@@ -860,6 +923,7 @@ function omitReadOutputForBudget(resolved, requested, session, bindingBudget, om
             }
             : {}),
         precedence: resolved.precedence,
+        ...canonicalReadOutputReceiptFields(resolved),
         legacy_aliases_used: [],
         migration_hints: [],
         estimated_tokens: 0,
@@ -893,10 +957,10 @@ function omitReadOutputForBudget(resolved, requested, session, bindingBudget, om
     return boundedOmission;
 }
 /** Decide whether shaping would add no value to an already-bounded result. */
-function canReturnReadOutputUnchanged(resolved, requested, session, result) {
+function canReturnReadOutputUnchanged(resolved, session, result) {
     if (session !== undefined)
         return false;
-    const canonicalRequestedCount = requested.filter((dimension) => resolved[dimension]?.source === "canonical").length;
+    const canonicalRequestedCount = resolved.canonical_options_used.length;
     if (resolved.cost?.value === "unbounded") {
         return (canonicalRequestedCount === (resolved.cost.source === "canonical" ? 1 : 0));
     }
@@ -1077,7 +1141,7 @@ export function applyReadOutputDimensions(command, options, result) {
         : undefined;
     const requested = requestedDimensions(resolved);
     if (cursor === undefined &&
-        canReturnReadOutputUnchanged(resolved, requested, session, result)) {
+        canReturnReadOutputUnchanged(resolved, session, result)) {
         return result;
     }
     const continuationReadyResult = attachValidateDiagnosticRowContract(resolved.command, result);
@@ -1095,6 +1159,7 @@ export function applyReadOutputDimensions(command, options, result) {
             }
             : {}),
         precedence: resolved.precedence,
+        ...canonicalReadOutputReceiptFields(resolved),
         legacy_aliases_used: resolved.legacy_aliases_used,
         migration_hints: resolved.migration_hints,
         estimated_tokens: 0,
@@ -1134,4 +1199,4 @@ export function resolveReadOutputEncoding(command, options) {
         : undefined;
 }
 //# sourceMappingURL=read-output-contracts.js.map
-//# debugId=b3c001df-9891-5cf7-990b-8d9da7b51801
+//# debugId=a1272c1f-c03e-580c-8c44-6b3ddeedd240

package/dist/sdk/relationship-context.js

@@ -5,7 +5,7 @@
  * packet for agents, custom tools, and presentation-layer adapters.
  */
 
-!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]="31a800f7-1374-5e7c-ad23-ae3d8ebcebe0")}catch(e){}}();
+!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]="afdba960-ae43-52be-b21d-282dac1f22ff")}catch(e){}}();
 import { createQueryFingerprint, encodeQueryCursor, resolveQueryCursorStart, } from "./pagination.js";
 import { createRelationshipKindRegistry, } from "./relationships.js";
 /** Deterministic priority used when one node matches several semantic families. */
@@ -37,8 +37,7 @@ function explainDirectEdge(edge, node, registry) {
         return node === before ? "prerequisite" : "dependent";
     }
     if (definition?.hierarchy) {
-        // Legacy and JSON-parsed definitions may predate explicit hierarchy direction.
-        const sourceIsParent = (definition.hierarchyDirection ?? "source_parent") === "source_parent";
+        const sourceIsParent = definition.hierarchyDirection === "source_parent";
         const parent = sourceIsParent ? edge.source : edge.target;
         return node === parent ? "ancestor" : "descendant";
     }
@@ -283,4 +282,4 @@ export function buildRelationshipContext(graph, rootId, details, options = {}) {
     };
 }
 //# sourceMappingURL=relationship-context.js.map
-//# debugId=31a800f7-1374-5e7c-ad23-ae3d8ebcebe0
+//# debugId=afdba960-ae43-52be-b21d-282dac1f22ff

package/dist/sdk/relationship-kinds/contract.d.ts

@@ -15,12 +15,20 @@ export type RelationshipTemporalOrder = "source_after_target";
 export type RelationshipPrecedence = "source_before_target" | "target_before_source";
 /** Endpoint that represents the structural parent for hierarchy kinds. */
 export type RelationshipHierarchyDirection = "source_parent" | "target_parent";
+/** Closure family that gives a relationship its default traversal vocabulary. */
+export type RelationshipTraversalFamily = "hierarchy" | "ordering" | "semantic" | "association";
+/** Direction in which an edge can carry a node toward a declared outcome. */
+export type RelationshipOutcomeTraversal = "source_to_target" | "target_to_source" | "both";
 /** Versioned semantic definition for a built-in or application-defined edge kind. */
 export interface RelationshipKindDefinition {
     /** Canonical, case-insensitive kind identifier. */
     kind: string;
     /** Whether traversing source to target has distinct meaning from the reverse. */
     direction: RelationshipDirection;
+    /** Default closure vocabulary; omitted custom definitions infer it from legacy flags. */
+    traversal?: RelationshipTraversalFamily;
+    /** Direction this kind contributes to typed outcome reachability, when any. */
+    outcomeTraversal?: RelationshipOutcomeTraversal;
     /** Optional canonical kind used when traversing a directed edge in reverse. */
     inverse?: string;
     /** Whether the kind participates in execution-order cycle checks. */