@unbrained/pm-cli 2026.6.12 → 2026.6.16

package/dist/core/governance/metadata-coverage.js

@@ -0,0 +1,362 @@
+/**
+ * Metadata governance & coverage observability primitives.
+ *
+ * One dependency-light module that powers the whole metadata-governance
+ * surface: missing-field selection (pm list / pm update-many), coverage
+ * percentages (pm stats --metadata-coverage / pm validate), and grouped
+ * lifecycle breakdowns (pm stats --by-assignee/--by-tag/--by-priority,
+ * pm aggregate explicit labels).
+ *
+ * The module is pure: it performs no IO and imports no heavy runtime
+ * dependencies. Lifecycle semantics are injected via a {@link LifecycleClassifier}
+ * so callers map their runtime status registry to lifecycle buckets while the
+ * pure logic here stays trivially testable with a fake classifier.
+ */
+
+!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]="53dbd46b-5d5b-56ac-9e84-8139d30d84ac")}catch(e){}}();
+import { toNonEmptyStringOrUndefined } from "../shared/primitives.js";
+/** Stable rendering order for lifecycle buckets. */
+export const LIFECYCLE_BUCKET_ORDER = [
+    "open",
+    "in_progress",
+    "blocked",
+    "draft",
+    "closed",
+    "canceled",
+    "other",
+];
+function normalizeStatus(status, registry) {
+    const trimmed = status.trim().toLowerCase();
+    return registry.alias_to_id.get(trimmed) ?? trimmed;
+}
+/**
+ * Adapt a resolved runtime status registry into a {@link LifecycleClassifier}.
+ *
+ * Precedence is deliberate and disjoint: canceled → closed → blocked → draft →
+ * open → in_progress (active but not the default open status) → other.
+ */
+export function lifecycleClassifierFromStatusRegistry(registry) {
+    return {
+        isTerminal(status) {
+            return registry.terminal_statuses.has(normalizeStatus(status, registry));
+        },
+        classify(status) {
+            const id = normalizeStatus(status, registry);
+            if (registry.terminal_canceled_statuses.has(id)) {
+                return "canceled";
+            }
+            if (registry.terminal_statuses.has(id)) {
+                return "closed";
+            }
+            if (registry.blocked_statuses.has(id)) {
+                return "blocked";
+            }
+            if (registry.draft_statuses.has(id)) {
+                return "draft";
+            }
+            if (id === registry.open_status) {
+                return "open";
+            }
+            if (registry.active_statuses.has(id)) {
+                return "in_progress";
+            }
+            return "other";
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Missing-metadata predicates
+// ---------------------------------------------------------------------------
+/** True when an item has no non-empty acceptance_criteria. */
+export function isAcMissing(item) {
+    return toNonEmptyStringOrUndefined(item.acceptance_criteria) === undefined;
+}
+/** True when an item has no finite estimated_minutes. */
+export function isEstimateMissing(item) {
+    return !Number.isFinite(item.estimated_minutes);
+}
+/**
+ * True when a terminal (closed/canceled) item has no non-empty resolution.
+ * Resolution is only expected on terminal items, so open items are never
+ * considered "resolution-missing".
+ */
+export function isResolutionMissing(item, classifier) {
+    if (!classifier.isTerminal(item.status)) {
+        return false;
+    }
+    return toNonEmptyStringOrUndefined(item.resolution) === undefined;
+}
+/** True when an item has no non-empty reviewer. */
+export function isReviewerMissing(item) {
+    return toNonEmptyStringOrUndefined(item.reviewer) === undefined;
+}
+/** True when an item has no non-empty risk level. */
+export function isRiskMissing(item) {
+    return toNonEmptyStringOrUndefined(item.risk) === undefined;
+}
+/**
+ * True when an item has no confidence value. Confidence is a string-like enum
+ * or a numeric score depending on workspace, so a finite number counts as
+ * present and only blank/absent values are treated as missing.
+ */
+export function isConfidenceMissing(item) {
+    if (typeof item.confidence === "number") {
+        return !Number.isFinite(item.confidence);
+    }
+    return toNonEmptyStringOrUndefined(item.confidence) === undefined;
+}
+/** True when an item has no non-empty sprint. */
+export function isSprintMissing(item) {
+    return toNonEmptyStringOrUndefined(item.sprint) === undefined;
+}
+/** True when an item has no non-empty release. */
+export function isReleaseMissing(item) {
+    return toNonEmptyStringOrUndefined(item.release) === undefined;
+}
+/** True when any missing-metadata filter is requested. */
+export function hasMissingMetadataFilter(filters) {
+    return Boolean(filters.acMissing ||
+        filters.estimatesMissing ||
+        filters.resolutionMissing ||
+        filters.reviewerMissing ||
+        filters.riskMissing ||
+        filters.confidenceMissing ||
+        filters.sprintMissing ||
+        filters.releaseMissing ||
+        filters.metadataMissing);
+}
+/**
+ * Does a single item satisfy the requested missing-metadata filters?
+ *
+ * Specific flags (acMissing/estimatesMissing/resolutionMissing plus the
+ * governance flags reviewerMissing/riskMissing/confidenceMissing/sprintMissing/
+ * releaseMissing) are ANDed together so callers can narrow precisely.
+ * `metadataMissing` is ORed in as a union shortcut for "missing any of the
+ * core tracked fields" (acceptance_criteria/estimated_minutes/resolution); it
+ * deliberately excludes the governance fields so the long-standing flag keeps
+ * its original meaning. When no filter is requested the item passes.
+ */
+export function itemMatchesMissingMetadata(item, filters, classifier) {
+    if (!hasMissingMetadataFilter(filters)) {
+        return true;
+    }
+    if (filters.acMissing && !isAcMissing(item)) {
+        return false;
+    }
+    if (filters.estimatesMissing && !isEstimateMissing(item)) {
+        return false;
+    }
+    if (filters.resolutionMissing && !isResolutionMissing(item, classifier)) {
+        return false;
+    }
+    if (filters.reviewerMissing && !isReviewerMissing(item)) {
+        return false;
+    }
+    if (filters.riskMissing && !isRiskMissing(item)) {
+        return false;
+    }
+    if (filters.confidenceMissing && !isConfidenceMissing(item)) {
+        return false;
+    }
+    if (filters.sprintMissing && !isSprintMissing(item)) {
+        return false;
+    }
+    if (filters.releaseMissing && !isReleaseMissing(item)) {
+        return false;
+    }
+    if (filters.metadataMissing) {
+        const anyMissing = isAcMissing(item) || isEstimateMissing(item) || isResolutionMissing(item, classifier);
+        if (!anyMissing) {
+            return false;
+        }
+    }
+    return true;
+}
+/** Filter a list of items by the requested missing-metadata predicates. */
+export function filterMissingMetadata(items, filters, classifier) {
+    if (!hasMissingMetadataFilter(filters)) {
+        return [...items];
+    }
+    return items.filter((item) => itemMatchesMissingMetadata(item, filters, classifier));
+}
+/** Stable ordering of coverage fields for rendering. */
+export const COVERAGE_FIELD_ORDER = [
+    "acceptance_criteria",
+    "estimated_minutes",
+    "resolution",
+    "tags",
+    "parent",
+];
+function isFieldPresent(item, field) {
+    switch (field) {
+        case "acceptance_criteria":
+            return !isAcMissing(item);
+        case "estimated_minutes":
+            return !isEstimateMissing(item);
+        case "resolution":
+            return toNonEmptyStringOrUndefined(item.resolution) !== undefined;
+        case "tags":
+            return Array.isArray(item.tags) && item.tags.length > 0;
+        default:
+            return toNonEmptyStringOrUndefined(item.parent) !== undefined;
+    }
+}
+/** Whether a field applies to a given item (resolution only applies to terminal items). */
+function isFieldApplicable(item, field, classifier) {
+    if (field === "resolution") {
+        return classifier.isTerminal(item.status);
+    }
+    return true;
+}
+function roundPercent(present, applicable) {
+    if (applicable === 0) {
+        return 100;
+    }
+    return Math.round((present / applicable) * 1000) / 10;
+}
+function emptyFieldCoverage() {
+    const record = {};
+    for (const field of COVERAGE_FIELD_ORDER) {
+        record[field] = { present: 0, applicable: 0, percent: 100 };
+    }
+    return record;
+}
+function accumulateCoverage(target, item, classifier) {
+    for (const field of COVERAGE_FIELD_ORDER) {
+        if (!isFieldApplicable(item, field, classifier)) {
+            continue;
+        }
+        const entry = target[field];
+        entry.applicable += 1;
+        if (isFieldPresent(item, field)) {
+            entry.present += 1;
+        }
+    }
+}
+function finalizePercentages(record) {
+    for (const field of COVERAGE_FIELD_ORDER) {
+        const entry = record[field];
+        entry.percent = roundPercent(entry.present, entry.applicable);
+    }
+}
+/**
+ * Compute metadata coverage overall and per item type. For each tracked field
+ * we report present/applicable counts and a rounded percentage. Resolution is
+ * scoped to terminal items (its only applicable population).
+ */
+export function computeMetadataCoverage(items, classifier) {
+    const overall = emptyFieldCoverage();
+    const byType = {};
+    for (const item of items) {
+        accumulateCoverage(overall, item, classifier);
+        const typeRecord = byType[item.type] ?? (byType[item.type] = emptyFieldCoverage());
+        accumulateCoverage(typeRecord, item, classifier);
+    }
+    finalizePercentages(overall);
+    for (const typeRecord of Object.values(byType)) {
+        finalizePercentages(typeRecord);
+    }
+    return { overall, by_type: byType };
+}
+/** Explicit labels for empty/blank group keys, by dimension. */
+const EMPTY_GROUP_LABELS = {
+    assignee: "(unassigned)",
+    priority: "(no priority)",
+    tag: "(untagged)",
+    parent: "(unparented)",
+    type: "(untyped)",
+    status: "(no status)",
+};
+/** Explicit label for an empty/blank group value for a given dimension. */
+export function emptyGroupLabel(dimension) {
+    return EMPTY_GROUP_LABELS[dimension];
+}
+function emptyBuckets() {
+    return {
+        open: 0,
+        in_progress: 0,
+        blocked: 0,
+        draft: 0,
+        closed: 0,
+        canceled: 0,
+        other: 0,
+    };
+}
+/**
+ * Resolve the group keys an item belongs to for a dimension. Most dimensions
+ * yield exactly one key (possibly null for blank); tag yields one key per
+ * matching tag (or [null] when none match), so an item can span multiple rows.
+ */
+function groupKeysForItem(item, dimension, options) {
+    switch (dimension) {
+        case "assignee":
+            return [toNonEmptyStringOrUndefined(item.assignee) ?? null];
+        case "parent":
+            return [toNonEmptyStringOrUndefined(item.parent) ?? null];
+        case "type":
+            return [toNonEmptyStringOrUndefined(item.type) ?? null];
+        case "status":
+            return [toNonEmptyStringOrUndefined(item.status) ?? null];
+        case "priority":
+            return [typeof item.priority === "number" ? `P${item.priority}` : null];
+        default: {
+            const prefix = options.tagPrefix?.trim();
+            const tags = Array.isArray(item.tags) ? item.tags : [];
+            const matching = tags.filter((tag) => typeof tag === "string" && tag.length > 0 && (!prefix || tag.startsWith(prefix)));
+            return matching.length > 0 ? matching : [null];
+        }
+    }
+}
+/**
+ * Group items by a dimension into lifecycle-bucketed rows. Blank keys render
+ * with an explicit "(unassigned)"-style label. Rows are sorted by total
+ * descending, then label ascending, with the empty group sorted last on ties.
+ */
+export function groupItemsByDimension(items, dimension, classifier, options = {}) {
+    const rows = new Map();
+    let totalItems = 0;
+    for (const item of items) {
+        totalItems += 1;
+        const bucket = classifier.classify(item.status);
+        for (const key of groupKeysForItem(item, dimension, options)) {
+            const mapKey = key ?? "empty";
+            let row = rows.get(mapKey);
+            if (!row) {
+                row = {
+                    label: key ?? emptyGroupLabel(dimension),
+                    key,
+                    buckets: emptyBuckets(),
+                    total: 0,
+                };
+                rows.set(mapKey, row);
+            }
+            row.buckets[bucket] += 1;
+            row.total += 1;
+        }
+    }
+    const sorted = [...rows.values()].sort((left, right) => {
+        if (right.total !== left.total) {
+            return right.total - left.total;
+        }
+        // All blank-key items collapse into a single row per dimension, so at most
+        // one row has key === null; it sorts last on ties.
+        if (left.key === null) {
+            return 1;
+        }
+        if (right.key === null) {
+            return -1;
+        }
+        return left.label.localeCompare(right.label);
+    });
+    return { dimension, rows: sorted, total_items: totalItems };
+}
+/** Lifecycle-bucket distribution across all items (for stats lifecycle section). */
+export function computeLifecycleDistribution(items, classifier) {
+    const buckets = emptyBuckets();
+    for (const item of items) {
+        buckets[classifier.classify(item.status)] += 1;
+    }
+    return buckets;
+}
+//# sourceMappingURL=metadata-coverage.js.map
+//# debugId=53dbd46b-5d5b-56ac-9e84-8139d30d84ac

package/dist/core/governance/metadata-coverage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata-coverage.js","sources":["core/governance/metadata-coverage.ts"],"sourceRoot":"/","sourcesContent":["/**\n * Metadata governance & coverage observability primitives.\n *\n * One dependency-light module that powers the whole metadata-governance\n * surface: missing-field selection (pm list / pm update-many), coverage\n * percentages (pm stats --metadata-coverage / pm validate), and grouped\n * lifecycle breakdowns (pm stats --by-assignee/--by-tag/--by-priority,\n * pm aggregate explicit labels).\n *\n * The module is pure: it performs no IO and imports no heavy runtime\n * dependencies. Lifecycle semantics are injected via a {@link LifecycleClassifier}\n * so callers map their runtime status registry to lifecycle buckets while the\n * pure logic here stays trivially testable with a fake classifier.\n */\n\nimport { toNonEmptyStringOrUndefined } from \"../shared/primitives.js\";\n\n/** Minimal structural shape this module needs from an item's front matter. */\nexport interface CoverageItem {\n  type: string;\n  status: string;\n  assignee?: string;\n  tags?: string[];\n  parent?: string;\n  priority?: number;\n  acceptance_criteria?: string;\n  estimated_minutes?: number;\n  resolution?: string;\n  reviewer?: string;\n  risk?: string;\n  /** Confidence is a string-like enum or a numeric score depending on workspace. */\n  confidence?: string | number;\n  sprint?: string;\n  release?: string;\n  [key: string]: unknown;\n}\n\n/** Lifecycle buckets used by grouped breakdowns and distributions. */\nexport type LifecycleBucket =\n  | \"open\"\n  | \"in_progress\"\n  | \"blocked\"\n  | \"draft\"\n  | \"closed\"\n  | \"canceled\"\n  | \"other\";\n\n/** Stable rendering order for lifecycle buckets. */\nexport const LIFECYCLE_BUCKET_ORDER: readonly LifecycleBucket[] = [\n  \"open\",\n  \"in_progress\",\n  \"blocked\",\n  \"draft\",\n  \"closed\",\n  \"canceled\",\n  \"other\",\n] as const;\n\n/**\n * Classifies a raw status string into a lifecycle bucket and reports whether a\n * status is terminal (closed/canceled). Callers build this from their resolved\n * runtime status registry via {@link lifecycleClassifierFromStatusRegistry}.\n */\nexport interface LifecycleClassifier {\n  classify(status: string): LifecycleBucket;\n  isTerminal(status: string): boolean;\n}\n\n/** The subset of a resolved runtime status registry this module consumes. */\nexport interface StatusRegistryLike {\n  alias_to_id: Map<string, string>;\n  terminal_statuses: Set<string>;\n  terminal_canceled_statuses: Set<string>;\n  blocked_statuses: Set<string>;\n  draft_statuses: Set<string>;\n  active_statuses: Set<string>;\n  open_status: string;\n}\n\nfunction normalizeStatus(status: string, registry: StatusRegistryLike): string {\n  const trimmed = status.trim().toLowerCase();\n  return registry.alias_to_id.get(trimmed) ?? trimmed;\n}\n\n/**\n * Adapt a resolved runtime status registry into a {@link LifecycleClassifier}.\n *\n * Precedence is deliberate and disjoint: canceled → closed → blocked → draft →\n * open → in_progress (active but not the default open status) → other.\n */\nexport function lifecycleClassifierFromStatusRegistry(registry: StatusRegistryLike): LifecycleClassifier {\n  return {\n    isTerminal(status: string): boolean {\n      return registry.terminal_statuses.has(normalizeStatus(status, registry));\n    },\n    classify(status: string): LifecycleBucket {\n      const id = normalizeStatus(status, registry);\n      if (registry.terminal_canceled_statuses.has(id)) {\n        return \"canceled\";\n      }\n      if (registry.terminal_statuses.has(id)) {\n        return \"closed\";\n      }\n      if (registry.blocked_statuses.has(id)) {\n        return \"blocked\";\n      }\n      if (registry.draft_statuses.has(id)) {\n        return \"draft\";\n      }\n      if (id === registry.open_status) {\n        return \"open\";\n      }\n      if (registry.active_statuses.has(id)) {\n        return \"in_progress\";\n      }\n      return \"other\";\n    },\n  };\n}\n\n// ---------------------------------------------------------------------------\n// Missing-metadata predicates\n// ---------------------------------------------------------------------------\n\n/** True when an item has no non-empty acceptance_criteria. */\nexport function isAcMissing(item: CoverageItem): boolean {\n  return toNonEmptyStringOrUndefined(item.acceptance_criteria) === undefined;\n}\n\n/** True when an item has no finite estimated_minutes. */\nexport function isEstimateMissing(item: CoverageItem): boolean {\n  return !Number.isFinite(item.estimated_minutes);\n}\n\n/**\n * True when a terminal (closed/canceled) item has no non-empty resolution.\n * Resolution is only expected on terminal items, so open items are never\n * considered \"resolution-missing\".\n */\nexport function isResolutionMissing(item: CoverageItem, classifier: LifecycleClassifier): boolean {\n  if (!classifier.isTerminal(item.status)) {\n    return false;\n  }\n  return toNonEmptyStringOrUndefined(item.resolution) === undefined;\n}\n\n/** True when an item has no non-empty reviewer. */\nexport function isReviewerMissing(item: CoverageItem): boolean {\n  return toNonEmptyStringOrUndefined(item.reviewer) === undefined;\n}\n\n/** True when an item has no non-empty risk level. */\nexport function isRiskMissing(item: CoverageItem): boolean {\n  return toNonEmptyStringOrUndefined(item.risk) === undefined;\n}\n\n/**\n * True when an item has no confidence value. Confidence is a string-like enum\n * or a numeric score depending on workspace, so a finite number counts as\n * present and only blank/absent values are treated as missing.\n */\nexport function isConfidenceMissing(item: CoverageItem): boolean {\n  if (typeof item.confidence === \"number\") {\n    return !Number.isFinite(item.confidence);\n  }\n  return toNonEmptyStringOrUndefined(item.confidence) === undefined;\n}\n\n/** True when an item has no non-empty sprint. */\nexport function isSprintMissing(item: CoverageItem): boolean {\n  return toNonEmptyStringOrUndefined(item.sprint) === undefined;\n}\n\n/** True when an item has no non-empty release. */\nexport function isReleaseMissing(item: CoverageItem): boolean {\n  return toNonEmptyStringOrUndefined(item.release) === undefined;\n}\n\n/** Selection flags for {@link filterMissingMetadata}. */\nexport interface MissingMetadataFilters {\n  acMissing?: boolean;\n  estimatesMissing?: boolean;\n  resolutionMissing?: boolean;\n  reviewerMissing?: boolean;\n  riskMissing?: boolean;\n  confidenceMissing?: boolean;\n  sprintMissing?: boolean;\n  releaseMissing?: boolean;\n  /** Match items missing ANY of the tracked metadata fields (union). */\n  metadataMissing?: boolean;\n}\n\n/** True when any missing-metadata filter is requested. */\nexport function hasMissingMetadataFilter(filters: MissingMetadataFilters): boolean {\n  return Boolean(\n    filters.acMissing ||\n      filters.estimatesMissing ||\n      filters.resolutionMissing ||\n      filters.reviewerMissing ||\n      filters.riskMissing ||\n      filters.confidenceMissing ||\n      filters.sprintMissing ||\n      filters.releaseMissing ||\n      filters.metadataMissing,\n  );\n}\n\n/**\n * Does a single item satisfy the requested missing-metadata filters?\n *\n * Specific flags (acMissing/estimatesMissing/resolutionMissing plus the\n * governance flags reviewerMissing/riskMissing/confidenceMissing/sprintMissing/\n * releaseMissing) are ANDed together so callers can narrow precisely.\n * `metadataMissing` is ORed in as a union shortcut for \"missing any of the\n * core tracked fields\" (acceptance_criteria/estimated_minutes/resolution); it\n * deliberately excludes the governance fields so the long-standing flag keeps\n * its original meaning. When no filter is requested the item passes.\n */\nexport function itemMatchesMissingMetadata(\n  item: CoverageItem,\n  filters: MissingMetadataFilters,\n  classifier: LifecycleClassifier,\n): boolean {\n  if (!hasMissingMetadataFilter(filters)) {\n    return true;\n  }\n  if (filters.acMissing && !isAcMissing(item)) {\n    return false;\n  }\n  if (filters.estimatesMissing && !isEstimateMissing(item)) {\n    return false;\n  }\n  if (filters.resolutionMissing && !isResolutionMissing(item, classifier)) {\n    return false;\n  }\n  if (filters.reviewerMissing && !isReviewerMissing(item)) {\n    return false;\n  }\n  if (filters.riskMissing && !isRiskMissing(item)) {\n    return false;\n  }\n  if (filters.confidenceMissing && !isConfidenceMissing(item)) {\n    return false;\n  }\n  if (filters.sprintMissing && !isSprintMissing(item)) {\n    return false;\n  }\n  if (filters.releaseMissing && !isReleaseMissing(item)) {\n    return false;\n  }\n  if (filters.metadataMissing) {\n    const anyMissing =\n      isAcMissing(item) || isEstimateMissing(item) || isResolutionMissing(item, classifier);\n    if (!anyMissing) {\n      return false;\n    }\n  }\n  return true;\n}\n\n/** Filter a list of items by the requested missing-metadata predicates. */\nexport function filterMissingMetadata<T extends CoverageItem>(\n  items: readonly T[],\n  filters: MissingMetadataFilters,\n  classifier: LifecycleClassifier,\n): T[] {\n  if (!hasMissingMetadataFilter(filters)) {\n    return [...items];\n  }\n  return items.filter((item) => itemMatchesMissingMetadata(item, filters, classifier));\n}\n\n// ---------------------------------------------------------------------------\n// Metadata coverage percentages\n// ---------------------------------------------------------------------------\n\n/** Coverage-tracked metadata fields. */\nexport type CoverageField =\n  | \"acceptance_criteria\"\n  | \"estimated_minutes\"\n  | \"resolution\"\n  | \"tags\"\n  | \"parent\";\n\n/** Stable ordering of coverage fields for rendering. */\nexport const COVERAGE_FIELD_ORDER: readonly CoverageField[] = [\n  \"acceptance_criteria\",\n  \"estimated_minutes\",\n  \"resolution\",\n  \"tags\",\n  \"parent\",\n] as const;\n\n/** Coverage of a single field: present vs applicable, with a rounded percent. */\nexport interface FieldCoverage {\n  present: number;\n  /** Items for which the field is expected (all items, except resolution = terminal only). */\n  applicable: number;\n  /** present/applicable * 100, rounded to one decimal; 100 when applicable is 0. */\n  percent: number;\n}\n\nexport interface MetadataCoverageReport {\n  overall: Record<CoverageField, FieldCoverage>;\n  by_type: Record<string, Record<CoverageField, FieldCoverage>>;\n}\n\nfunction isFieldPresent(item: CoverageItem, field: CoverageField): boolean {\n  switch (field) {\n    case \"acceptance_criteria\":\n      return !isAcMissing(item);\n    case \"estimated_minutes\":\n      return !isEstimateMissing(item);\n    case \"resolution\":\n      return toNonEmptyStringOrUndefined(item.resolution) !== undefined;\n    case \"tags\":\n      return Array.isArray(item.tags) && item.tags.length > 0;\n    default:\n      return toNonEmptyStringOrUndefined(item.parent) !== undefined;\n  }\n}\n\n/** Whether a field applies to a given item (resolution only applies to terminal items). */\nfunction isFieldApplicable(item: CoverageItem, field: CoverageField, classifier: LifecycleClassifier): boolean {\n  if (field === \"resolution\") {\n    return classifier.isTerminal(item.status);\n  }\n  return true;\n}\n\nfunction roundPercent(present: number, applicable: number): number {\n  if (applicable === 0) {\n    return 100;\n  }\n  return Math.round((present / applicable) * 1000) / 10;\n}\n\nfunction emptyFieldCoverage(): Record<CoverageField, FieldCoverage> {\n  const record = {} as Record<CoverageField, FieldCoverage>;\n  for (const field of COVERAGE_FIELD_ORDER) {\n    record[field] = { present: 0, applicable: 0, percent: 100 };\n  }\n  return record;\n}\n\nfunction accumulateCoverage(\n  target: Record<CoverageField, FieldCoverage>,\n  item: CoverageItem,\n  classifier: LifecycleClassifier,\n): void {\n  for (const field of COVERAGE_FIELD_ORDER) {\n    if (!isFieldApplicable(item, field, classifier)) {\n      continue;\n    }\n    const entry = target[field];\n    entry.applicable += 1;\n    if (isFieldPresent(item, field)) {\n      entry.present += 1;\n    }\n  }\n}\n\nfunction finalizePercentages(record: Record<CoverageField, FieldCoverage>): void {\n  for (const field of COVERAGE_FIELD_ORDER) {\n    const entry = record[field];\n    entry.percent = roundPercent(entry.present, entry.applicable);\n  }\n}\n\n/**\n * Compute metadata coverage overall and per item type. For each tracked field\n * we report present/applicable counts and a rounded percentage. Resolution is\n * scoped to terminal items (its only applicable population).\n */\nexport function computeMetadataCoverage(\n  items: readonly CoverageItem[],\n  classifier: LifecycleClassifier,\n): MetadataCoverageReport {\n  const overall = emptyFieldCoverage();\n  const byType: Record<string, Record<CoverageField, FieldCoverage>> = {};\n  for (const item of items) {\n    accumulateCoverage(overall, item, classifier);\n    const typeRecord = byType[item.type] ?? (byType[item.type] = emptyFieldCoverage());\n    accumulateCoverage(typeRecord, item, classifier);\n  }\n  finalizePercentages(overall);\n  for (const typeRecord of Object.values(byType)) {\n    finalizePercentages(typeRecord);\n  }\n  return { overall, by_type: byType };\n}\n\n// ---------------------------------------------------------------------------\n// Grouped lifecycle breakdowns\n// ---------------------------------------------------------------------------\n\n/** Dimensions a breakdown can group by. */\nexport type GroupDimension = \"assignee\" | \"priority\" | \"tag\" | \"parent\" | \"type\" | \"status\";\n\n/** Explicit labels for empty/blank group keys, by dimension. */\nconst EMPTY_GROUP_LABELS: Record<GroupDimension, string> = {\n  assignee: \"(unassigned)\",\n  priority: \"(no priority)\",\n  tag: \"(untagged)\",\n  parent: \"(unparented)\",\n  type: \"(untyped)\",\n  status: \"(no status)\",\n};\n\n/** Explicit label for an empty/blank group value for a given dimension. */\nexport function emptyGroupLabel(dimension: GroupDimension): string {\n  return EMPTY_GROUP_LABELS[dimension];\n}\n\nexport interface GroupRow {\n  /** Display label; explicit \"(unassigned)\"-style label for blank keys. */\n  label: string;\n  /** Stable structured key (null for the empty/blank group). */\n  key: string | null;\n  buckets: Record<LifecycleBucket, number>;\n  total: number;\n}\n\nexport interface GroupedBreakdown {\n  dimension: GroupDimension;\n  rows: GroupRow[];\n  /** Distinct items observed (an item can contribute to multiple tag rows). */\n  total_items: number;\n}\n\nexport interface GroupOptions {\n  /** For dimension=\"tag\": only consider tags starting with this prefix. */\n  tagPrefix?: string;\n}\n\nfunction emptyBuckets(): Record<LifecycleBucket, number> {\n  return {\n    open: 0,\n    in_progress: 0,\n    blocked: 0,\n    draft: 0,\n    closed: 0,\n    canceled: 0,\n    other: 0,\n  };\n}\n\n/**\n * Resolve the group keys an item belongs to for a dimension. Most dimensions\n * yield exactly one key (possibly null for blank); tag yields one key per\n * matching tag (or [null] when none match), so an item can span multiple rows.\n */\nfunction groupKeysForItem(item: CoverageItem, dimension: GroupDimension, options: GroupOptions): (string | null)[] {\n  switch (dimension) {\n    case \"assignee\":\n      return [toNonEmptyStringOrUndefined(item.assignee) ?? null];\n    case \"parent\":\n      return [toNonEmptyStringOrUndefined(item.parent) ?? null];\n    case \"type\":\n      return [toNonEmptyStringOrUndefined(item.type) ?? null];\n    case \"status\":\n      return [toNonEmptyStringOrUndefined(item.status) ?? null];\n    case \"priority\":\n      return [typeof item.priority === \"number\" ? `P${item.priority}` : null];\n    default: {\n      const prefix = options.tagPrefix?.trim();\n      const tags = Array.isArray(item.tags) ? item.tags : [];\n      const matching = tags.filter(\n        (tag) => typeof tag === \"string\" && tag.length > 0 && (!prefix || tag.startsWith(prefix)),\n      );\n      return matching.length > 0 ? matching : [null];\n    }\n  }\n}\n\n/**\n * Group items by a dimension into lifecycle-bucketed rows. Blank keys render\n * with an explicit \"(unassigned)\"-style label. Rows are sorted by total\n * descending, then label ascending, with the empty group sorted last on ties.\n */\nexport function groupItemsByDimension(\n  items: readonly CoverageItem[],\n  dimension: GroupDimension,\n  classifier: LifecycleClassifier,\n  options: GroupOptions = {},\n): GroupedBreakdown {\n  const rows = new Map<string, GroupRow>();\n  let totalItems = 0;\n  for (const item of items) {\n    totalItems += 1;\n    const bucket = classifier.classify(item.status);\n    for (const key of groupKeysForItem(item, dimension, options)) {\n      const mapKey = key ?? \"\u0000empty\";\n      let row = rows.get(mapKey);\n      if (!row) {\n        row = {\n          label: key ?? emptyGroupLabel(dimension),\n          key,\n          buckets: emptyBuckets(),\n          total: 0,\n        };\n        rows.set(mapKey, row);\n      }\n      row.buckets[bucket] += 1;\n      row.total += 1;\n    }\n  }\n  const sorted = [...rows.values()].sort((left, right) => {\n    if (right.total !== left.total) {\n      return right.total - left.total;\n    }\n    // All blank-key items collapse into a single row per dimension, so at most\n    // one row has key === null; it sorts last on ties.\n    if (left.key === null) {\n      return 1;\n    }\n    if (right.key === null) {\n      return -1;\n    }\n    return left.label.localeCompare(right.label);\n  });\n  return { dimension, rows: sorted, total_items: totalItems };\n}\n\n/** Lifecycle-bucket distribution across all items (for stats lifecycle section). */\nexport function computeLifecycleDistribution(\n  items: readonly CoverageItem[],\n  classifier: LifecycleClassifier,\n): Record<LifecycleBucket, number> {\n  const buckets = emptyBuckets();\n  for (const item of items) {\n    buckets[classifier.classify(item.status)] += 1;\n  }\n  return buckets;\n}\n"],"names":[],"mappings":"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","debugId":"53dbd46b-5d5b-56ac-9e84-8139d30d84ac"}

package/dist/core/history/history-rewrite.d.ts

@@ -40,4 +40,26 @@ export interface VerifiedHistoryRewriteState {
  * diverged while waiting for the lock so the caller surfaces an actionable retry.
  */
 export declare function verifyHistoryRewriteNoDrift(params: VerifyHistoryRewriteDriftParams): Promise<VerifiedHistoryRewriteState>;
+export interface ExecuteHistoryRewriteParams {
+    pmRoot: string;
+    subject: HistoryRewriteSubject;
+    settings: PmSettings;
+    typeRegistry: ItemTypeRegistry;
+    historyRawBeforeLock: string | null;
+    currentItemRawBeforeLock: string | null;
+    /** Short operation name used in conflict guidance (e.g. "history-redact"). */
+    operation: string;
+    author: string;
+    force: boolean | undefined;
+    itemDocument: ItemDocument | null;
+    applyRewrite: (verified: VerifiedHistoryRewriteState) => Promise<void>;
+    applyPostRewrite?: (verified: VerifiedHistoryRewriteState) => Promise<string[]>;
+}
+/**
+ * Shared lock/verify/ownership orchestration for history-rewrite commands.
+ * Callers provide the operation-specific write/rollback logic and optional
+ * post-write hook execution while this helper enforces the common governance +
+ * lock sequencing contract.
+ */
+export declare function executeHistoryRewrite(params: ExecuteHistoryRewriteParams): Promise<string[]>;
 export {};

package/dist/core/history/history-rewrite.js

@@ -1,6 +1,7 @@
 
-!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]="6929fbcd-89b7-580d-93fc-f647b086b95f")}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]="5c9d33cb-2601-55e4-9134-acae94c017c0")}catch(e){}}();
 import { readFileIfExists } from "../fs/fs-utils.js";
+import { acquireLock } from "../lock/lock.js";
 import { EXIT_CODE } from "../shared/constants.js";
 import { PmCliError } from "../shared/errors.js";
 import { locateItem, readLocatedItem } from "../store/item-store.js";
@@ -44,5 +45,40 @@ export async function verifyHistoryRewriteNoDrift(params) {
     }
     return { historyRawUnderLock, locatedUnderLock, loadedItemUnderLock };
 }
+/**
+ * Shared lock/verify/ownership orchestration for history-rewrite commands.
+ * Callers provide the operation-specific write/rollback logic and optional
+ * post-write hook execution while this helper enforces the common governance +
+ * lock sequencing contract.
+ */
+export async function executeHistoryRewrite(params) {
+    const warnings = [...checkHistoryRewriteOwnership({
+            itemDocument: params.itemDocument,
+            subjectId: params.subject.id,
+            author: params.author,
+            force: params.force,
+            settings: params.settings,
+        })];
+    const releaseLock = await acquireLock(params.pmRoot, params.subject.id, params.settings.locks.ttl_seconds, params.author, Boolean(params.force), params.settings.governance.force_required_for_stale_lock);
+    try {
+        const verified = await verifyHistoryRewriteNoDrift({
+            pmRoot: params.pmRoot,
+            subject: params.subject,
+            settings: params.settings,
+            typeRegistry: params.typeRegistry,
+            historyRawBeforeLock: params.historyRawBeforeLock,
+            currentItemRawBeforeLock: params.currentItemRawBeforeLock,
+            operation: params.operation,
+        });
+        await params.applyRewrite(verified);
+        if (params.applyPostRewrite) {
+            warnings.push(...(await params.applyPostRewrite(verified)));
+        }
+        return warnings;
+    }
+    finally {
+        await releaseLock();
+    }
+}
 //# sourceMappingURL=history-rewrite.js.map
-//# debugId=6929fbcd-89b7-580d-93fc-f647b086b95f
+//# debugId=5c9d33cb-2601-55e4-9134-acae94c017c0

package/dist/core/history/history-rewrite.js.map

@@ -1 +1 @@
-{"version":3,"file":"history-rewrite.js","sources":["core/history/history-rewrite.ts"],"sourceRoot":"/","sourcesContent":["import { readFileIfExists } from \"../fs/fs-utils.js\";\nimport type { ItemTypeRegistry } from \"../item/type-registry.js\";\nimport { EXIT_CODE } from \"../shared/constants.js\";\nimport { PmCliError } from \"../shared/errors.js\";\nimport { locateItem, readLocatedItem } from \"../store/item-store.js\";\nimport { resolveGovernanceKnobs } from \"../store/settings.js\";\nimport type { ItemDocument, PmSettings } from \"../../types/index.js\";\n\ntype LoadedItem = Awaited<ReturnType<typeof readLocatedItem>>;\n\nexport interface HistoryRewriteSubject {\n  id: string;\n  historyPath: string;\n}\n\nexport interface HistoryRewriteOwnershipParams {\n  itemDocument: ItemDocument | null;\n  subjectId: string;\n  author: string;\n  force: boolean | undefined;\n  settings: PmSettings;\n}\n\n/**\n * Apply ownership_enforcement governance to a history-rewriting operation.\n * Returns the warning(s) the caller should append (empty when no conflict or strict-throws).\n * Throws PmCliError(CONFLICT) in strict mode when the assignee conflicts and --force is not set.\n */\nexport function checkHistoryRewriteOwnership(params: HistoryRewriteOwnershipParams): string[] {\n  if (!params.itemDocument) return [];\n  const assigned = params.itemDocument.metadata?.assignee?.trim();\n  if (!assigned || assigned === params.author || params.force) return [];\n\n  const governance = resolveGovernanceKnobs(params.settings);\n  if (governance.ownership_enforcement === \"strict\") {\n    throw new PmCliError(\n      `Item ${params.subjectId} is assigned to ${assigned}. Use --force to override.`,\n      EXIT_CODE.CONFLICT,\n    );\n  }\n  if (governance.ownership_enforcement === \"warn\") {\n    return [`ownership_warning:assignee_conflict:${params.subjectId}:${assigned}`];\n  }\n  return [];\n}\n\nexport interface VerifyHistoryRewriteDriftParams {\n  pmRoot: string;\n  subject: HistoryRewriteSubject;\n  settings: PmSettings;\n  typeRegistry: ItemTypeRegistry;\n  historyRawBeforeLock: string | null;\n  currentItemRawBeforeLock: string | null;\n  /** Short operation name used in the conflict message (e.g. \"history-redact\"). */\n  operation: string;\n}\n\nexport interface VerifiedHistoryRewriteState {\n  historyRawUnderLock: string | null;\n  locatedUnderLock: Awaited<ReturnType<typeof locateItem>>;\n  loadedItemUnderLock: LoadedItem | null;\n}\n\n/**\n * Re-read the history stream and the located item document under the acquired lock and\n * compare both with the pre-lock raw snapshots. Throws PmCliError(CONFLICT) if either\n * diverged while waiting for the lock so the caller surfaces an actionable retry.\n */\nexport async function verifyHistoryRewriteNoDrift(\n  params: VerifyHistoryRewriteDriftParams,\n): Promise<VerifiedHistoryRewriteState> {\n  const historyRawUnderLock = await readFileIfExists(params.subject.historyPath);\n  if (historyRawUnderLock !== params.historyRawBeforeLock) {\n    throw new PmCliError(\n      `History for ${params.subject.id} changed while waiting for lock; retry ${params.operation}.`,\n      EXIT_CODE.CONFLICT,\n    );\n  }\n  const locatedUnderLock = await locateItem(\n    params.pmRoot,\n    params.subject.id,\n    params.settings.id_prefix,\n    params.settings.item_format,\n    params.typeRegistry.type_to_folder,\n  );\n  const loadedItemUnderLock = locatedUnderLock\n    ? await readLocatedItem(locatedUnderLock, { schema: params.settings.schema })\n    : null;\n  if ((loadedItemUnderLock?.raw ?? null) !== (params.currentItemRawBeforeLock ?? null)) {\n    throw new PmCliError(\n      `Item ${params.subject.id} changed while waiting for lock; retry ${params.operation}.`,\n      EXIT_CODE.CONFLICT,\n    );\n  }\n  return { historyRawUnderLock, locatedUnderLock, loadedItemUnderLock };\n}\n"],"names":[],"mappings":";;AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAErD,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACrE,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAkB9D;;;;GAIG;AACH,MAAM,UAAU,4BAA4B,CAAC,MAAqC;IAChF,IAAI,CAAC,MAAM,CAAC,YAAY;QAAE,OAAO,EAAE,CAAC;IACpC,MAAM,QAAQ,GAAG,MAAM,CAAC,YAAY,CAAC,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IAChE,IAAI,CAAC,QAAQ,IAAI,QAAQ,KAAK,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC,KAAK;QAAE,OAAO,EAAE,CAAC;IAEvE,MAAM,UAAU,GAAG,sBAAsB,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC3D,IAAI,UAAU,CAAC,qBAAqB,KAAK,QAAQ,EAAE,CAAC;QAClD,MAAM,IAAI,UAAU,CAClB,QAAQ,MAAM,CAAC,SAAS,mBAAmB,QAAQ,4BAA4B,EAC/E,SAAS,CAAC,QAAQ,CACnB,CAAC;IACJ,CAAC;IACD,IAAI,UAAU,CAAC,qBAAqB,KAAK,MAAM,EAAE,CAAC;QAChD,OAAO,CAAC,uCAAuC,MAAM,CAAC,SAAS,IAAI,QAAQ,EAAE,CAAC,CAAC;IACjF,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC;AAmBD;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,2BAA2B,CAC/C,MAAuC;IAEvC,MAAM,mBAAmB,GAAG,MAAM,gBAAgB,CAAC,MAAM,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IAC/E,IAAI,mBAAmB,KAAK,MAAM,CAAC,oBAAoB,EAAE,CAAC;QACxD,MAAM,IAAI,UAAU,CAClB,eAAe,MAAM,CAAC,OAAO,CAAC,EAAE,0CAA0C,MAAM,CAAC,SAAS,GAAG,EAC7F,SAAS,CAAC,QAAQ,CACnB,CAAC;IACJ,CAAC;IACD,MAAM,gBAAgB,GAAG,MAAM,UAAU,CACvC,MAAM,CAAC,MAAM,EACb,MAAM,CAAC,OAAO,CAAC,EAAE,EACjB,MAAM,CAAC,QAAQ,CAAC,SAAS,EACzB,MAAM,CAAC,QAAQ,CAAC,WAAW,EAC3B,MAAM,CAAC,YAAY,CAAC,cAAc,CACnC,CAAC;IACF,MAAM,mBAAmB,GAAG,gBAAgB;QAC1C,CAAC,CAAC,MAAM,eAAe,CAAC,gBAAgB,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC;QAC7E,CAAC,CAAC,IAAI,CAAC;IACT,IAAI,CAAC,mBAAmB,EAAE,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,wBAAwB,IAAI,IAAI,CAAC,EAAE,CAAC;QACrF,MAAM,IAAI,UAAU,CAClB,QAAQ,MAAM,CAAC,OAAO,CAAC,EAAE,0CAA0C,MAAM,CAAC,SAAS,GAAG,EACtF,SAAS,CAAC,QAAQ,CACnB,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,CAAC;AACxE,CAAC","debugId":"6929fbcd-89b7-580d-93fc-f647b086b95f"}
+{"version":3,"file":"history-rewrite.js","sources":["core/history/history-rewrite.ts"],"sourceRoot":"/","sourcesContent":["import { readFileIfExists } from \"../fs/fs-utils.js\";\nimport type { ItemTypeRegistry } from \"../item/type-registry.js\";\nimport { acquireLock } from \"../lock/lock.js\";\nimport { EXIT_CODE } from \"../shared/constants.js\";\nimport { PmCliError } from \"../shared/errors.js\";\nimport { locateItem, readLocatedItem } from \"../store/item-store.js\";\nimport { resolveGovernanceKnobs } from \"../store/settings.js\";\nimport type { ItemDocument, PmSettings } from \"../../types/index.js\";\n\ntype LoadedItem = Awaited<ReturnType<typeof readLocatedItem>>;\n\nexport interface HistoryRewriteSubject {\n  id: string;\n  historyPath: string;\n}\n\nexport interface HistoryRewriteOwnershipParams {\n  itemDocument: ItemDocument | null;\n  subjectId: string;\n  author: string;\n  force: boolean | undefined;\n  settings: PmSettings;\n}\n\n/**\n * Apply ownership_enforcement governance to a history-rewriting operation.\n * Returns the warning(s) the caller should append (empty when no conflict or strict-throws).\n * Throws PmCliError(CONFLICT) in strict mode when the assignee conflicts and --force is not set.\n */\nexport function checkHistoryRewriteOwnership(params: HistoryRewriteOwnershipParams): string[] {\n  if (!params.itemDocument) return [];\n  const assigned = params.itemDocument.metadata?.assignee?.trim();\n  if (!assigned || assigned === params.author || params.force) return [];\n\n  const governance = resolveGovernanceKnobs(params.settings);\n  if (governance.ownership_enforcement === \"strict\") {\n    throw new PmCliError(\n      `Item ${params.subjectId} is assigned to ${assigned}. Use --force to override.`,\n      EXIT_CODE.CONFLICT,\n    );\n  }\n  if (governance.ownership_enforcement === \"warn\") {\n    return [`ownership_warning:assignee_conflict:${params.subjectId}:${assigned}`];\n  }\n  return [];\n}\n\nexport interface VerifyHistoryRewriteDriftParams {\n  pmRoot: string;\n  subject: HistoryRewriteSubject;\n  settings: PmSettings;\n  typeRegistry: ItemTypeRegistry;\n  historyRawBeforeLock: string | null;\n  currentItemRawBeforeLock: string | null;\n  /** Short operation name used in the conflict message (e.g. \"history-redact\"). */\n  operation: string;\n}\n\nexport interface VerifiedHistoryRewriteState {\n  historyRawUnderLock: string | null;\n  locatedUnderLock: Awaited<ReturnType<typeof locateItem>>;\n  loadedItemUnderLock: LoadedItem | null;\n}\n\n/**\n * Re-read the history stream and the located item document under the acquired lock and\n * compare both with the pre-lock raw snapshots. Throws PmCliError(CONFLICT) if either\n * diverged while waiting for the lock so the caller surfaces an actionable retry.\n */\nexport async function verifyHistoryRewriteNoDrift(\n  params: VerifyHistoryRewriteDriftParams,\n): Promise<VerifiedHistoryRewriteState> {\n  const historyRawUnderLock = await readFileIfExists(params.subject.historyPath);\n  if (historyRawUnderLock !== params.historyRawBeforeLock) {\n    throw new PmCliError(\n      `History for ${params.subject.id} changed while waiting for lock; retry ${params.operation}.`,\n      EXIT_CODE.CONFLICT,\n    );\n  }\n  const locatedUnderLock = await locateItem(\n    params.pmRoot,\n    params.subject.id,\n    params.settings.id_prefix,\n    params.settings.item_format,\n    params.typeRegistry.type_to_folder,\n  );\n  const loadedItemUnderLock = locatedUnderLock\n    ? await readLocatedItem(locatedUnderLock, { schema: params.settings.schema })\n    : null;\n  if ((loadedItemUnderLock?.raw ?? null) !== (params.currentItemRawBeforeLock ?? null)) {\n    throw new PmCliError(\n      `Item ${params.subject.id} changed while waiting for lock; retry ${params.operation}.`,\n      EXIT_CODE.CONFLICT,\n    );\n  }\n  return { historyRawUnderLock, locatedUnderLock, loadedItemUnderLock };\n}\n\nexport interface ExecuteHistoryRewriteParams {\n  pmRoot: string;\n  subject: HistoryRewriteSubject;\n  settings: PmSettings;\n  typeRegistry: ItemTypeRegistry;\n  historyRawBeforeLock: string | null;\n  currentItemRawBeforeLock: string | null;\n  /** Short operation name used in conflict guidance (e.g. \"history-redact\"). */\n  operation: string;\n  author: string;\n  force: boolean | undefined;\n  itemDocument: ItemDocument | null;\n  applyRewrite: (verified: VerifiedHistoryRewriteState) => Promise<void>;\n  applyPostRewrite?: (verified: VerifiedHistoryRewriteState) => Promise<string[]>;\n}\n\n/**\n * Shared lock/verify/ownership orchestration for history-rewrite commands.\n * Callers provide the operation-specific write/rollback logic and optional\n * post-write hook execution while this helper enforces the common governance +\n * lock sequencing contract.\n */\nexport async function executeHistoryRewrite(params: ExecuteHistoryRewriteParams): Promise<string[]> {\n  const warnings = [...checkHistoryRewriteOwnership({\n    itemDocument: params.itemDocument,\n    subjectId: params.subject.id,\n    author: params.author,\n    force: params.force,\n    settings: params.settings,\n  })];\n  const releaseLock = await acquireLock(\n    params.pmRoot,\n    params.subject.id,\n    params.settings.locks.ttl_seconds,\n    params.author,\n    Boolean(params.force),\n    params.settings.governance.force_required_for_stale_lock,\n  );\n  try {\n    const verified = await verifyHistoryRewriteNoDrift({\n      pmRoot: params.pmRoot,\n      subject: params.subject,\n      settings: params.settings,\n      typeRegistry: params.typeRegistry,\n      historyRawBeforeLock: params.historyRawBeforeLock,\n      currentItemRawBeforeLock: params.currentItemRawBeforeLock,\n      operation: params.operation,\n    });\n    await params.applyRewrite(verified);\n    if (params.applyPostRewrite) {\n      warnings.push(...(await params.applyPostRewrite(verified)));\n    }\n    return warnings;\n  } finally {\n    await releaseLock();\n  }\n}\n"],"names":[],"mappings":"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","debugId":"5c9d33cb-2601-55e4-9134-acae94c017c0"}

package/dist/core/history/history.d.ts

@@ -1,4 +1,6 @@
 import type { HistoryEntry, ItemDocument } from "../../types/index.js";
+declare function decodeJsonPointer(path: string): string[];
+declare function isDefinedPointerPath(document: unknown, path: string): boolean;
 export declare function hashDocument(document: ItemDocument): string;
 export declare function hashEmptyDocument(): string;
 export declare function createHistoryEntry(params: {
@@ -10,3 +12,8 @@ export declare function createHistoryEntry(params: {
     message?: string;
 }): HistoryEntry;
 export declare function appendHistoryEntry(historyPath: string, entry: HistoryEntry): Promise<void>;
+export declare const _testOnly: {
+    decodeJsonPointer: typeof decodeJsonPointer;
+    isDefinedPointerPath: typeof isDefinedPointerPath;
+};
+export {};

package/dist/core/history/history.js

@@ -1,5 +1,5 @@
 
-!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]="9a356560-3dec-5529-a2b5-1b4224116c14")}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]="b165ab2e-26f4-5ccd-83f4-39b5cf86c2cf")}catch(e){}}();
 import jsonPatch from "fast-json-patch";
 import { FRONT_MATTER_KEY_ORDER } from "../shared/constants.js";
 import { runActiveServiceOverride } from "../extensions/index.js";
@@ -154,5 +154,9 @@ export async function appendHistoryEntry(historyPath, entry) {
     }
     await appendLineAtomic(historyPath, JSON.stringify(entry));
 }
+export const _testOnly = {
+    decodeJsonPointer,
+    isDefinedPointerPath,
+};
 //# sourceMappingURL=history.js.map
-//# debugId=9a356560-3dec-5529-a2b5-1b4224116c14
+//# debugId=b165ab2e-26f4-5ccd-83f4-39b5cf86c2cf

package/dist/core/history/history.js.map

@@ -1 +1 @@
-{"version":3,"file":"history.js","sources":["core/history/history.ts"],"sourceRoot":"/","sourcesContent":["import jsonPatch from \"fast-json-patch\";\nimport { FRONT_MATTER_KEY_ORDER } from \"../shared/constants.js\";\nimport { runActiveServiceOverride } from \"../extensions/index.js\";\nimport { appendLineAtomic } from \"../fs/fs-utils.js\";\nimport { canonicalDocument } from \"../item/item-format.js\";\nimport { toItemRecord } from \"../item/item-record.js\";\nimport { orderObject, sha256Hex, stableStringify } from \"../shared/serialization.js\";\nimport type { HistoryEntry, HistoryPatchOp, ItemDocument } from \"../../types/index.js\";\n\nconst EMPTY_LEGACY_HASH_DOCUMENT = {\n  front_matter: {},\n  body: \"\",\n};\n\nfunction decodeJsonPointer(path: string): string[] {\n  if (!path || path === \"/\") {\n    return [];\n  }\n  if (!path.startsWith(\"/\")) {\n    return [];\n  }\n  return path\n    .slice(1)\n    .split(\"/\")\n    .map((segment) => segment.replaceAll(\"~1\", \"/\").replaceAll(\"~0\", \"~\"));\n}\n\nfunction isDefinedPointerPath(document: unknown, path: string): boolean {\n  const segments = decodeJsonPointer(path);\n  if (segments.length === 0) {\n    return true;\n  }\n  let cursor: unknown = document;\n  for (const segment of segments) {\n    if (Array.isArray(cursor)) {\n      if (segment === \"-\" || !/^(0|[1-9]\\d*)$/.test(segment)) {\n        return false;\n      }\n      const index = Number(segment);\n      if (!Number.isInteger(index) || index < 0 || index >= cursor.length) {\n        return false;\n      }\n      const next = cursor[index];\n      if (next === undefined) {\n        return false;\n      }\n      cursor = next;\n      continue;\n    }\n    if (typeof cursor !== \"object\" || cursor === null) {\n      return false;\n    }\n    if (!Object.prototype.hasOwnProperty.call(cursor, segment)) {\n      return false;\n    }\n    const next = (cursor as Record<string, unknown>)[segment];\n    if (next === undefined) {\n      return false;\n    }\n    cursor = next;\n  }\n  return true;\n}\n\nfunction normalizeHistoryPatchOps(\n  beforeDocument: { metadata: Record<string, unknown>; body: string },\n  patch: HistoryPatchOp[],\n): HistoryPatchOp[] {\n  const normalized: HistoryPatchOp[] = [];\n  let replayCursor: unknown = structuredClone(beforeDocument);\n  for (const operation of patch) {\n    const normalizedOperation =\n      operation.op === \"replace\" && !isDefinedPointerPath(replayCursor, operation.path)\n        ? ({ ...operation, op: \"add\" } as HistoryPatchOp)\n        : operation;\n    normalized.push(normalizedOperation);\n    replayCursor = jsonPatch.applyPatch(\n      replayCursor,\n      [normalizedOperation as jsonPatch.Operation],\n      true,\n      true,\n    ).newDocument as unknown;\n  }\n  return normalized;\n}\n\nfunction canonicalHashDocument(document: ItemDocument): { front_matter: Record<string, unknown>; body: string } {\n  const hasMetadata = document.metadata && Object.keys(document.metadata).length > 0;\n  if (!hasMetadata) {\n    return {\n      front_matter: {},\n      body: document.body ?? \"\",\n    };\n  }\n  const canonical = canonicalDocument(document);\n  const orderedFrontMatter = orderObject(toItemRecord(canonical.metadata), FRONT_MATTER_KEY_ORDER);\n  return {\n    front_matter: orderedFrontMatter,\n    body: canonical.body,\n  };\n}\n\nfunction canonicalPatchDocument(document: ItemDocument): { metadata: Record<string, unknown>; body: string } {\n  const hasMetadata = document.metadata && Object.keys(document.metadata).length > 0;\n  if (!hasMetadata) {\n    return {\n      metadata: {},\n      body: document.body ?? \"\",\n    };\n  }\n  const canonical = canonicalDocument(document);\n  const orderedMetadata = orderObject(toItemRecord(canonical.metadata), FRONT_MATTER_KEY_ORDER);\n  return {\n    metadata: orderedMetadata,\n    body: canonical.body,\n  };\n}\n\nexport function hashDocument(document: ItemDocument): string {\n  return sha256Hex(stableStringify(canonicalHashDocument(document)));\n}\n\nexport function hashEmptyDocument(): string {\n  return sha256Hex(stableStringify(EMPTY_LEGACY_HASH_DOCUMENT));\n}\n\nexport function createHistoryEntry(params: {\n  nowIso: string;\n  author: string;\n  op: string;\n  before: ItemDocument;\n  after: ItemDocument;\n  message?: string;\n}): HistoryEntry {\n  const beforeHashCanonical = canonicalHashDocument(params.before);\n  const afterHashCanonical = canonicalHashDocument(params.after);\n  const beforePatchCanonical = canonicalPatchDocument(params.before);\n  const afterPatchCanonical = canonicalPatchDocument(params.after);\n  const rawPatch = jsonPatch.compare(beforePatchCanonical, afterPatchCanonical) as HistoryPatchOp[];\n  const patch = normalizeHistoryPatchOps(beforePatchCanonical, rawPatch);\n\n  return {\n    ts: params.nowIso,\n    author: params.author,\n    op: params.op,\n    patch,\n    before_hash: sha256Hex(stableStringify(beforeHashCanonical)),\n    after_hash: sha256Hex(stableStringify(afterHashCanonical)),\n    message: params.message === undefined ? undefined : params.message,\n  };\n}\n\nexport async function appendHistoryEntry(historyPath: string, entry: HistoryEntry): Promise<void> {\n  const override = await runActiveServiceOverride(\"history_append\", {\n    history_path: historyPath,\n    entry,\n  });\n  if (override.handled) {\n    if (override.result === false) {\n      return;\n    }\n    if (typeof override.result === \"string\") {\n      await appendLineAtomic(historyPath, override.result);\n      return;\n    }\n    if (typeof override.result === \"object\" && override.result !== null) {\n      const record = override.result as {\n        history_path?: unknown;\n        entry?: unknown;\n        line?: unknown;\n        skip?: unknown;\n      };\n      if (record.skip === true) {\n        return;\n      }\n      const nextHistoryPath = typeof record.history_path === \"string\" ? record.history_path : historyPath;\n      if (typeof record.line === \"string\") {\n        await appendLineAtomic(nextHistoryPath, record.line);\n        return;\n      }\n      const nextEntry = (record.entry ?? entry) as HistoryEntry;\n      await appendLineAtomic(nextHistoryPath, JSON.stringify(nextEntry));\n      return;\n    }\n  }\n  await appendLineAtomic(historyPath, JSON.stringify(entry));\n}\n"],"names":[],"mappings":"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","debugId":"9a356560-3dec-5529-a2b5-1b4224116c14"}
+{"version":3,"file":"history.js","sources":["core/history/history.ts"],"sourceRoot":"/","sourcesContent":["import jsonPatch from \"fast-json-patch\";\nimport { FRONT_MATTER_KEY_ORDER } from \"../shared/constants.js\";\nimport { runActiveServiceOverride } from \"../extensions/index.js\";\nimport { appendLineAtomic } from \"../fs/fs-utils.js\";\nimport { canonicalDocument } from \"../item/item-format.js\";\nimport { toItemRecord } from \"../item/item-record.js\";\nimport { orderObject, sha256Hex, stableStringify } from \"../shared/serialization.js\";\nimport type { HistoryEntry, HistoryPatchOp, ItemDocument } from \"../../types/index.js\";\n\nconst EMPTY_LEGACY_HASH_DOCUMENT = {\n  front_matter: {},\n  body: \"\",\n};\n\nfunction decodeJsonPointer(path: string): string[] {\n  if (!path || path === \"/\") {\n    return [];\n  }\n  if (!path.startsWith(\"/\")) {\n    return [];\n  }\n  return path\n    .slice(1)\n    .split(\"/\")\n    .map((segment) => segment.replaceAll(\"~1\", \"/\").replaceAll(\"~0\", \"~\"));\n}\n\nfunction isDefinedPointerPath(document: unknown, path: string): boolean {\n  const segments = decodeJsonPointer(path);\n  if (segments.length === 0) {\n    return true;\n  }\n  let cursor: unknown = document;\n  for (const segment of segments) {\n    if (Array.isArray(cursor)) {\n      if (segment === \"-\" || !/^(0|[1-9]\\d*)$/.test(segment)) {\n        return false;\n      }\n      const index = Number(segment);\n      if (!Number.isInteger(index) || index < 0 || index >= cursor.length) {\n        return false;\n      }\n      const next = cursor[index];\n      if (next === undefined) {\n        return false;\n      }\n      cursor = next;\n      continue;\n    }\n    if (typeof cursor !== \"object\" || cursor === null) {\n      return false;\n    }\n    if (!Object.prototype.hasOwnProperty.call(cursor, segment)) {\n      return false;\n    }\n    const next = (cursor as Record<string, unknown>)[segment];\n    if (next === undefined) {\n      return false;\n    }\n    cursor = next;\n  }\n  return true;\n}\n\nfunction normalizeHistoryPatchOps(\n  beforeDocument: { metadata: Record<string, unknown>; body: string },\n  patch: HistoryPatchOp[],\n): HistoryPatchOp[] {\n  const normalized: HistoryPatchOp[] = [];\n  let replayCursor: unknown = structuredClone(beforeDocument);\n  for (const operation of patch) {\n    const normalizedOperation =\n      operation.op === \"replace\" && !isDefinedPointerPath(replayCursor, operation.path)\n        ? ({ ...operation, op: \"add\" } as HistoryPatchOp)\n        : operation;\n    normalized.push(normalizedOperation);\n    replayCursor = jsonPatch.applyPatch(\n      replayCursor,\n      [normalizedOperation as jsonPatch.Operation],\n      true,\n      true,\n    ).newDocument as unknown;\n  }\n  return normalized;\n}\n\nfunction canonicalHashDocument(document: ItemDocument): { front_matter: Record<string, unknown>; body: string } {\n  const hasMetadata = document.metadata && Object.keys(document.metadata).length > 0;\n  if (!hasMetadata) {\n    return {\n      front_matter: {},\n      body: document.body ?? \"\",\n    };\n  }\n  const canonical = canonicalDocument(document);\n  const orderedFrontMatter = orderObject(toItemRecord(canonical.metadata), FRONT_MATTER_KEY_ORDER);\n  return {\n    front_matter: orderedFrontMatter,\n    body: canonical.body,\n  };\n}\n\nfunction canonicalPatchDocument(document: ItemDocument): { metadata: Record<string, unknown>; body: string } {\n  const hasMetadata = document.metadata && Object.keys(document.metadata).length > 0;\n  if (!hasMetadata) {\n    return {\n      metadata: {},\n      body: document.body ?? \"\",\n    };\n  }\n  const canonical = canonicalDocument(document);\n  const orderedMetadata = orderObject(toItemRecord(canonical.metadata), FRONT_MATTER_KEY_ORDER);\n  return {\n    metadata: orderedMetadata,\n    body: canonical.body,\n  };\n}\n\nexport function hashDocument(document: ItemDocument): string {\n  return sha256Hex(stableStringify(canonicalHashDocument(document)));\n}\n\nexport function hashEmptyDocument(): string {\n  return sha256Hex(stableStringify(EMPTY_LEGACY_HASH_DOCUMENT));\n}\n\nexport function createHistoryEntry(params: {\n  nowIso: string;\n  author: string;\n  op: string;\n  before: ItemDocument;\n  after: ItemDocument;\n  message?: string;\n}): HistoryEntry {\n  const beforeHashCanonical = canonicalHashDocument(params.before);\n  const afterHashCanonical = canonicalHashDocument(params.after);\n  const beforePatchCanonical = canonicalPatchDocument(params.before);\n  const afterPatchCanonical = canonicalPatchDocument(params.after);\n  const rawPatch = jsonPatch.compare(beforePatchCanonical, afterPatchCanonical) as HistoryPatchOp[];\n  const patch = normalizeHistoryPatchOps(beforePatchCanonical, rawPatch);\n\n  return {\n    ts: params.nowIso,\n    author: params.author,\n    op: params.op,\n    patch,\n    before_hash: sha256Hex(stableStringify(beforeHashCanonical)),\n    after_hash: sha256Hex(stableStringify(afterHashCanonical)),\n    message: params.message === undefined ? undefined : params.message,\n  };\n}\n\nexport async function appendHistoryEntry(historyPath: string, entry: HistoryEntry): Promise<void> {\n  const override = await runActiveServiceOverride(\"history_append\", {\n    history_path: historyPath,\n    entry,\n  });\n  if (override.handled) {\n    if (override.result === false) {\n      return;\n    }\n    if (typeof override.result === \"string\") {\n      await appendLineAtomic(historyPath, override.result);\n      return;\n    }\n    if (typeof override.result === \"object\" && override.result !== null) {\n      const record = override.result as {\n        history_path?: unknown;\n        entry?: unknown;\n        line?: unknown;\n        skip?: unknown;\n      };\n      if (record.skip === true) {\n        return;\n      }\n      const nextHistoryPath = typeof record.history_path === \"string\" ? record.history_path : historyPath;\n      if (typeof record.line === \"string\") {\n        await appendLineAtomic(nextHistoryPath, record.line);\n        return;\n      }\n      const nextEntry = (record.entry ?? entry) as HistoryEntry;\n      await appendLineAtomic(nextHistoryPath, JSON.stringify(nextEntry));\n      return;\n    }\n  }\n  await appendLineAtomic(historyPath, JSON.stringify(entry));\n}\n\nexport const _testOnly = {\n  decodeJsonPointer,\n  isDefinedPointerPath,\n};\n"],"names":[],"mappings":"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","debugId":"b165ab2e-26f4-5ccd-83f4-39b5cf86c2cf"}