@unbrained/pm-cli 2026.5.31 → 2026.6.6

package/dist/core/schema/status-defs-file.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"status-defs-file.js","sources":["core/schema/status-defs-file.ts"],"sourceRoot":"/","sourcesContent":["import { RUNTIME_STATUS_ROLE_VALUES } from \"../../types/index.js\";\nimport type { RuntimeStatusDefinition, RuntimeStatusRole } from \"../../types/index.js\";\nimport { DEFAULT_RUNTIME_STATUS_DEFINITIONS } from \"./runtime-schema.js\";\n\nexport type { RuntimeStatusDefinition, RuntimeStatusRole } from \"../../types/index.js\";\n\n/**\n * Pure logic for the `pm schema add-status` / `pm schema remove-status`\n * commands. The CLI command file (schema.ts) owns IO/governance; everything\n * testable and side-effect-free lives here so it can be coverage-gated to 100%.\n *\n * Statuses persist at `.agents/pm/schema/statuses.json` under the shape\n * `{ statuses: RuntimeStatusDefinition[] }`. When the file is absent the runtime\n * merge layer (src/core/store/settings.ts) still supplies the built-in defaults\n * from DEFAULT_RUNTIME_STATUS_DEFINITIONS, so this module never duplicates them\n * into the persisted file.\n */\n\nconst RUNTIME_STATUS_ROLE_SET = new Set<string>(RUNTIME_STATUS_ROLE_VALUES);\n\n/**\n * The 5 lifecycle status ids that ship as built-in defaults and may never be\n * removed (their normalized ids match DEFAULT_RUNTIME_STATUS_DEFINITIONS:\n * open/in_progress/blocked/closed/canceled). `draft` is also a default but the\n * acceptance criteria enumerate the 5 terminal/active ids explicitly, so the\n * guard derives the full set from the canonical defaults to stay in sync.\n */\nexport const BUILTIN_STATUS_IDS: ReadonlySet<string> = new Set(\n  DEFAULT_RUNTIME_STATUS_DEFINITIONS.map((definition) => normalizeStatusToken(definition.id)).filter(\n    (id) => id.length > 0,\n  ),\n);\n\n/**\n * The shape persisted at `.agents/pm/schema/statuses.json`.\n */\nexport interface StatusDefsFile {\n  statuses: RuntimeStatusDefinition[];\n}\n\nexport interface RawAddStatusInput {\n  id: string | undefined;\n  roles?: string[];\n  aliases?: string[];\n  description?: string;\n  order?: number;\n}\n\nexport interface NormalizedAddStatusInput {\n  id: string;\n  /**\n   * Normalized roles, or `undefined` when the raw input did not supply a roles\n   * field at all. `undefined` means \"leave existing roles untouched\" on upsert;\n   * an explicit empty array means \"clear roles\". This distinction is what keeps\n   * `add-status review --description x` from wiping a previously-set role.\n   */\n  roles?: RuntimeStatusRole[];\n  /** Same omitted-vs-explicit-empty semantics as `roles`. */\n  aliases?: string[];\n  description?: string;\n  order?: number;\n}\n\nexport interface UpsertStatusDefResult {\n  file: StatusDefsFile;\n  /** The definition as stored after the upsert (existing fields preserved). */\n  definition: RuntimeStatusDefinition;\n  /** True when an existing definition with the same (normalized) id was replaced. */\n  replaced: boolean;\n}\n\nexport interface RemoveStatusDefResult {\n  file: StatusDefsFile;\n  /** True when a matching definition existed and was dropped from the file. */\n  removed: boolean;\n  /** The removed definition, when one matched the requested id. */\n  definition?: RuntimeStatusDefinition;\n}\n\n/**\n * Normalizes a status token using the same rules as runtime-schema.ts: lowercase\n * and collapse any run of whitespace/hyphens into a single underscore.\n */\nexport function normalizeStatusToken(value: unknown): string {\n  return typeof value === \"string\" ? value.trim().toLowerCase().replaceAll(/[\\s-]+/g, \"_\") : \"\";\n}\n\nfunction dedupeTokens(values: Iterable<string>): string[] {\n  const seen = new Set<string>();\n  for (const value of values) {\n    const token = normalizeStatusToken(value);\n    if (token.length > 0) {\n      seen.add(token);\n    }\n  }\n  return [...seen].sort((left, right) => left.localeCompare(right));\n}\n\n/**\n * Validates and normalizes raw add-status CLI input. Throws a plain Error with a\n * stable message when the id is missing/empty or a role is not one of\n * RUNTIME_STATUS_ROLE_VALUES; the CLI layer maps these to PmCliError exit codes.\n *\n * Omitted vs explicit-empty is preserved end-to-end: when `raw.roles`/`raw.aliases`\n * is `undefined` (flag not supplied) the normalized field is `undefined` so the\n * upsert leaves the existing value untouched; when supplied (even an empty array)\n * the field is normalized to an array so the upsert can apply an explicit clear.\n */\nexport function normalizeAddStatusInput(raw: RawAddStatusInput): NormalizedAddStatusInput {\n  const id = normalizeStatusToken(raw.id);\n  if (id.length === 0) {\n    throw new Error(\"Status id must not be empty.\");\n  }\n  // Built-in lifecycle statuses are reserved and cannot be overridden: an\n  // add-status override would change reserved metadata yet remove-status refuses\n  // to delete a built-in id, leaving no CLI path to undo it. Reject up front,\n  // symmetric with removeStatusDef.\n  if (BUILTIN_STATUS_IDS.has(id)) {\n    throw new Error(\n      `Cannot add-status the built-in status \"${id}\". Built-in statuses are reserved: ${[...BUILTIN_STATUS_IDS].join(\", \")}.`,\n    );\n  }\n  let roles: RuntimeStatusRole[] | undefined;\n  if (raw.roles !== undefined) {\n    roles = [];\n    const seenRoles = new Set<string>();\n    for (const rawRole of raw.roles) {\n      const role = typeof rawRole === \"string\" ? rawRole.trim().toLowerCase() : \"\";\n      if (role.length === 0) {\n        continue;\n      }\n      if (!RUNTIME_STATUS_ROLE_SET.has(role)) {\n        throw new Error(\n          `Invalid status role \"${rawRole}\". Allowed roles: ${RUNTIME_STATUS_ROLE_VALUES.join(\", \")}.`,\n        );\n      }\n      if (!seenRoles.has(role)) {\n        seenRoles.add(role);\n        roles.push(role as RuntimeStatusRole);\n      }\n    }\n  }\n  const aliases =\n    raw.aliases === undefined ? undefined : dedupeTokens(raw.aliases).filter((alias) => alias !== id);\n  const description = raw.description?.trim();\n  const order =\n    typeof raw.order === \"number\" && Number.isFinite(raw.order) ? Math.trunc(raw.order) : undefined;\n  return {\n    id,\n    roles,\n    aliases,\n    description: description && description.length > 0 ? description : undefined,\n    order,\n  };\n}\n\nfunction selectStatusesArray(parsed: unknown): unknown[] | undefined {\n  if (Array.isArray(parsed)) {\n    return parsed;\n  }\n  if (typeof parsed !== \"object\" || parsed === null) {\n    return undefined;\n  }\n  const record = parsed as Record<string, unknown>;\n  if (Array.isArray(record.statuses)) {\n    return record.statuses;\n  }\n  if (Array.isArray(record.definitions)) {\n    return record.definitions;\n  }\n  return undefined;\n}\n\nfunction extractStatusDefinitions(parsed: unknown): RuntimeStatusDefinition[] {\n  const candidate = selectStatusesArray(parsed);\n  if (!candidate) {\n    return [];\n  }\n  const definitions: RuntimeStatusDefinition[] = [];\n  for (const entry of candidate) {\n    if (typeof entry !== \"object\" || entry === null || Array.isArray(entry)) {\n      continue;\n    }\n    const record = entry as Record<string, unknown>;\n    if (typeof record.id !== \"string\" || record.id.trim().length === 0) {\n      continue;\n    }\n    definitions.push(record as unknown as RuntimeStatusDefinition);\n  }\n  return definitions;\n}\n\n/**\n * Coerces an arbitrary parsed value from statuses.json into a StatusDefsFile.\n * Accepts the canonical `{ statuses: [...] }` shape, a bare array of\n * definitions, or a `{ definitions: [...] }` form, and tolerates a\n * missing/invalid file by returning an empty statuses list.\n */\nexport function parseStatusDefsFile(raw: string | null | undefined): StatusDefsFile {\n  if (raw === null || raw === undefined || raw.trim().length === 0) {\n    return { statuses: [] };\n  }\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(raw) as unknown;\n  } catch {\n    throw new Error(\"schema/statuses.json contains invalid JSON.\");\n  }\n  return { statuses: extractStatusDefinitions(parsed) };\n}\n\n/**\n * Serializes the status definitions file with a trailing newline (matches the\n * rest of the schema scaffold files written by pm).\n */\nexport function serializeStatusDefsFile(file: StatusDefsFile): string {\n  return `${JSON.stringify({ statuses: file.statuses }, null, 2)}\\n`;\n}\n\n/**\n * Idempotent UPSERT of a status definition into the parsed file. Matching is by\n * normalized id. When a definition already exists, fields supplied in `input`\n * override the previous values (roles/aliases replace when a non-empty array is\n * given, clear when an explicit empty array is given, and are left UNTOUCHED\n * when the field is `undefined` — i.e. the add-status flag was omitted);\n * description/order override when provided. Fields not addressed by add-status\n * flags are preserved untouched, so `add-status <id> --description x` keeps any\n * previously-set roles/aliases.\n */\nexport function upsertStatusDef(\n  file: StatusDefsFile,\n  input: NormalizedAddStatusInput,\n  baseDefinition?: RuntimeStatusDefinition,\n): UpsertStatusDefResult {\n  const statuses = file.statuses.slice();\n  const existingIndex = statuses.findIndex(\n    (definition) => normalizeStatusToken(definition.id) === input.id,\n  );\n  // A file-backed definition is the primary seed; when the status is not yet in\n  // statuses.json fall back to `baseDefinition` (the resolved settings-backed\n  // definition) so omitting --role/--alias preserves metadata that lives in\n  // settings.schema.statuses rather than the file.\n  const existing = existingIndex >= 0 ? statuses[existingIndex] : baseDefinition;\n\n  const next: RuntimeStatusDefinition = {\n    ...(existing ?? {}),\n    id: input.id,\n  };\n  if (input.roles !== undefined) {\n    if (input.roles.length > 0) {\n      next.roles = [...input.roles];\n    } else if (next.roles !== undefined) {\n      delete next.roles;\n    }\n  }\n  if (input.aliases !== undefined) {\n    if (input.aliases.length > 0) {\n      next.aliases = [...input.aliases];\n    } else if (next.aliases !== undefined) {\n      delete next.aliases;\n    }\n  }\n  if (input.description !== undefined) {\n    next.description = input.description;\n  }\n  if (input.order !== undefined) {\n    next.order = input.order;\n  }\n\n  if (existingIndex >= 0) {\n    statuses[existingIndex] = next;\n  } else {\n    statuses.push(next);\n  }\n\n  return {\n    file: { statuses },\n    definition: next,\n    // \"replaced\" reflects whether the status already existed effectively (in the\n    // file OR in resolved settings), so the CLI reports \"Updated\" vs \"Registered\"\n    // correctly even when the prior definition lived only in settings.\n    replaced: existing !== undefined,\n  };\n}\n\n/**\n * Removes a status definition from the parsed file by id (normalized). Throws a\n * plain Error when `id` is empty or matches a reserved built-in default status\n * (those are never stored in the file and must never be deletable). Returns\n * `removed: false` when no matching definition exists so the CLI layer can treat\n * the call as an idempotent no-op.\n */\nexport function removeStatusDef(file: StatusDefsFile, id: string | undefined): RemoveStatusDefResult {\n  const normalizedId = normalizeStatusToken(id);\n  if (normalizedId.length === 0) {\n    throw new Error(\"Status id must not be empty.\");\n  }\n  if (BUILTIN_STATUS_IDS.has(normalizedId)) {\n    throw new Error(\n      `Cannot remove built-in status \"${normalizedId}\". Built-in statuses are reserved: ${[...BUILTIN_STATUS_IDS].join(\", \")}.`,\n    );\n  }\n  const statuses = file.statuses.slice();\n  const existingIndex = statuses.findIndex(\n    (definition) => normalizeStatusToken(definition.id) === normalizedId,\n  );\n  if (existingIndex < 0) {\n    return { file: { statuses }, removed: false };\n  }\n  const [definition] = statuses.splice(existingIndex, 1);\n  return { file: { statuses }, removed: true, definition };\n}\n\n/**\n * Throws when the new status id or any explicitly-supplied alias collides with a\n * DIFFERENT existing status's id/alias. `resolvedAliasToId` maps a normalized\n * token to its owning status id (the runtime status registry's alias_to_id map,\n * which stores ids and aliases in one namespace). Re-adding the same status\n * (matching id) is allowed — only cross-status collisions throw. This prevents a\n * custom status from shadowing a built-in lifecycle token (for example\n * `add-status review --alias open`, or a custom id `cancelled` that aliases the\n * built-in `canceled`), which would make `pm update --status open` resolve to the\n * wrong status. The CLI layer maps the thrown Error to a USAGE exit code.\n */\nexport function assertStatusTokensAvailable(\n  input: { id: string; aliases?: string[] },\n  resolvedAliasToId: ReadonlyMap<string, string>,\n): void {\n  const candidates = [input.id, ...(input.aliases ?? [])];\n  for (const candidate of candidates) {\n    const token = normalizeStatusToken(candidate);\n    if (token.length === 0) {\n      continue;\n    }\n    const owner = resolvedAliasToId.get(token);\n    if (owner !== undefined && owner !== input.id) {\n      throw new Error(\n        `Status token \"${token}\" already belongs to status \"${owner}\". Choose a different id/alias to avoid shadowing it.`,\n      );\n    }\n  }\n}\n"],"names":[],"mappings":"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","debugId":"d738db07-1d64-5ab0-9ebd-f9c9f6de5706"}

package/dist/core/schema/type-workflows.d.ts

@@ -0,0 +1,64 @@
+import type { RuntimeSchemaSettings } from "../../types/index.js";
+/**
+ * Per-type allowed-transition support (governance.workflow_enforcement).
+ *
+ * Rule semantics:
+ * - A type with NO matching type_workflows entry is UNRESTRICTED (every
+ *   transition is allowed).
+ * - A type WITH an entry allows only the listed [from, to] pairs. from/to are
+ *   compared as normalized status ids (resolved through the status registry's
+ *   alias_to_id map when available, otherwise via token normalization).
+ * - A same-status no-op (from === to) is ALWAYS allowed.
+ *
+ * This module is intentionally dependency-light and fully unit-testable; the
+ * CLI enforcement point (src/cli/commands/update.ts) is the only consumer.
+ */
+export interface NormalizedTypeWorkflow {
+    /** Lower-cased type name used for case-insensitive matching. */
+    type: string;
+    /** Allowed [from, to] pairs as normalized status ids. */
+    allowed_transitions: [string, string][];
+}
+/** Minimal status-registry surface needed to resolve a status token to its id. */
+export interface StatusTokenResolver {
+    alias_to_id: Map<string, string>;
+}
+export interface EvaluateTransitionInput {
+    typeName: string;
+    fromStatus: string;
+    toStatus: string;
+    typeWorkflows: NormalizedTypeWorkflow[];
+    statusRegistry?: StatusTokenResolver;
+}
+export interface EvaluateTransitionResult {
+    /** Whether the transition is permitted. */
+    allowed: boolean;
+    /** Whether a matching per-type rule constrained the transition. */
+    hasRule: boolean;
+    /**
+     * Allowed [from, to] pairs for the matched type (normalized ids). Empty when
+     * the type is unrestricted.
+     */
+    allowedTransitions: [string, string][];
+}
+/** Normalize a status token the same way runtime-schema statuses are normalized. */
+export declare function normalizeStatusToken(value: unknown): string;
+/**
+ * Normalize the raw type_workflows from a runtime schema into a deduped,
+ * lower-cased-type list with normalized status tokens.
+ *
+ * An entry is kept when it has a valid (non-empty) `type` AND its
+ * `allowed_transitions` is an ARRAY — even when that array is empty. An explicit
+ * empty array is a deliberate DENY-ALL rule (only same-status no-ops are
+ * permitted, see evaluateTransition), so it must NOT collapse into "no rule"
+ * (which would leave the type unrestricted). Entries with a missing/empty type
+ * or a non-array `allowed_transitions` are dropped, as are malformed/short pairs.
+ */
+export declare function resolveTypeWorkflows(schema: Pick<RuntimeSchemaSettings, "type_workflows"> | undefined): NormalizedTypeWorkflow[];
+/**
+ * Evaluate whether a status transition is allowed for the given item type.
+ * Returns hasRule=false (allowed) when the type is unrestricted.
+ */
+export declare function evaluateTransition(input: EvaluateTransitionInput): EvaluateTransitionResult;
+/** Render the allowed transitions for an error/warning hint. */
+export declare function describeAllowedTransitions(allowedTransitions: [string, string][]): string;

package/dist/core/schema/type-workflows.js

@@ -0,0 +1,98 @@
+/** Normalize a status token the same way runtime-schema statuses are normalized. */
+
+!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]="70ab7197-566b-52de-8a82-e432b324ad8d")}catch(e){}}();
+export function normalizeStatusToken(value) {
+    return typeof value === "string" ? value.trim().toLowerCase().replaceAll(/[\s-]+/g, "_") : "";
+}
+function normalizeTypeName(value) {
+    return typeof value === "string" ? value.trim().toLowerCase() : "";
+}
+function resolveStatusId(value, statusRegistry) {
+    const token = normalizeStatusToken(value);
+    if (token.length === 0) {
+        return "";
+    }
+    return statusRegistry?.alias_to_id?.get(token) ?? token;
+}
+/**
+ * Normalize the raw type_workflows from a runtime schema into a deduped,
+ * lower-cased-type list with normalized status tokens.
+ *
+ * An entry is kept when it has a valid (non-empty) `type` AND its
+ * `allowed_transitions` is an ARRAY — even when that array is empty. An explicit
+ * empty array is a deliberate DENY-ALL rule (only same-status no-ops are
+ * permitted, see evaluateTransition), so it must NOT collapse into "no rule"
+ * (which would leave the type unrestricted). Entries with a missing/empty type
+ * or a non-array `allowed_transitions` are dropped, as are malformed/short pairs.
+ */
+export function resolveTypeWorkflows(schema) {
+    const rawWorkflows = Array.isArray(schema?.type_workflows) ? schema.type_workflows : [];
+    const byType = new Map();
+    for (const entry of rawWorkflows) {
+        const type = normalizeTypeName(entry?.type);
+        if (type.length === 0) {
+            continue;
+        }
+        if (!Array.isArray(entry?.allowed_transitions)) {
+            continue;
+        }
+        const pairs = entry.allowed_transitions;
+        const record = byType.get(type) ?? { pairs: [], denyAll: false };
+        // Only an explicitly empty array is an intentional deny-all; a nonempty array
+        // whose pairs are all malformed is a typo and must be dropped (not deny-all).
+        if (pairs.length === 0) {
+            record.denyAll = true;
+        }
+        for (const pair of pairs) {
+            if (!Array.isArray(pair) || pair.length !== 2) {
+                continue;
+            }
+            const from = normalizeStatusToken(pair[0]);
+            const to = normalizeStatusToken(pair[1]);
+            if (from.length === 0 || to.length === 0) {
+                continue;
+            }
+            if (record.pairs.some((candidate) => candidate[0] === from && candidate[1] === to)) {
+                continue;
+            }
+            record.pairs.push([from, to]);
+        }
+        byType.set(type, record);
+    }
+    return [...byType.entries()]
+        .filter(([, record]) => record.pairs.length > 0 || record.denyAll)
+        .map(([type, record]) => ({ type, allowed_transitions: record.pairs }))
+        .sort((left, right) => left.type.localeCompare(right.type));
+}
+/**
+ * Evaluate whether a status transition is allowed for the given item type.
+ * Returns hasRule=false (allowed) when the type is unrestricted.
+ */
+export function evaluateTransition(input) {
+    const typeName = normalizeTypeName(input.typeName);
+    const matched = input.typeWorkflows.find((workflow) => workflow.type === typeName);
+    if (!matched) {
+        return { allowed: true, hasRule: false, allowedTransitions: [] };
+    }
+    const from = resolveStatusId(input.fromStatus, input.statusRegistry);
+    const to = resolveStatusId(input.toStatus, input.statusRegistry);
+    // A no-op self-transition is always permitted, even under a restricting rule.
+    if (from.length > 0 && from === to) {
+        return { allowed: true, hasRule: true, allowedTransitions: matched.allowed_transitions };
+    }
+    const allowed = matched.allowed_transitions.some((pair) => {
+        const ruleFrom = resolveStatusId(pair[0], input.statusRegistry);
+        const ruleTo = resolveStatusId(pair[1], input.statusRegistry);
+        return ruleFrom === from && ruleTo === to;
+    });
+    return { allowed, hasRule: true, allowedTransitions: matched.allowed_transitions };
+}
+/** Render the allowed transitions for an error/warning hint. */
+export function describeAllowedTransitions(allowedTransitions) {
+    if (allowedTransitions.length === 0) {
+        return "(no transitions allowed)";
+    }
+    return allowedTransitions.map((pair) => `${pair[0]} -> ${pair[1]}`).join(", ");
+}
+//# sourceMappingURL=type-workflows.js.map
+//# debugId=70ab7197-566b-52de-8a82-e432b324ad8d

package/dist/core/schema/type-workflows.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"type-workflows.js","sources":["core/schema/type-workflows.ts"],"sourceRoot":"/","sourcesContent":["import type { RuntimeSchemaSettings, TypeWorkflowDefinition } from \"../../types/index.js\";\n\n/**\n * Per-type allowed-transition support (governance.workflow_enforcement).\n *\n * Rule semantics:\n * - A type with NO matching type_workflows entry is UNRESTRICTED (every\n *   transition is allowed).\n * - A type WITH an entry allows only the listed [from, to] pairs. from/to are\n *   compared as normalized status ids (resolved through the status registry's\n *   alias_to_id map when available, otherwise via token normalization).\n * - A same-status no-op (from === to) is ALWAYS allowed.\n *\n * This module is intentionally dependency-light and fully unit-testable; the\n * CLI enforcement point (src/cli/commands/update.ts) is the only consumer.\n */\n\nexport interface NormalizedTypeWorkflow {\n  /** Lower-cased type name used for case-insensitive matching. */\n  type: string;\n  /** Allowed [from, to] pairs as normalized status ids. */\n  allowed_transitions: [string, string][];\n}\n\n/** Minimal status-registry surface needed to resolve a status token to its id. */\nexport interface StatusTokenResolver {\n  alias_to_id: Map<string, string>;\n}\n\nexport interface EvaluateTransitionInput {\n  typeName: string;\n  fromStatus: string;\n  toStatus: string;\n  typeWorkflows: NormalizedTypeWorkflow[];\n  statusRegistry?: StatusTokenResolver;\n}\n\nexport interface EvaluateTransitionResult {\n  /** Whether the transition is permitted. */\n  allowed: boolean;\n  /** Whether a matching per-type rule constrained the transition. */\n  hasRule: boolean;\n  /**\n   * Allowed [from, to] pairs for the matched type (normalized ids). Empty when\n   * the type is unrestricted.\n   */\n  allowedTransitions: [string, string][];\n}\n\n/** Normalize a status token the same way runtime-schema statuses are normalized. */\nexport function normalizeStatusToken(value: unknown): string {\n  return typeof value === \"string\" ? value.trim().toLowerCase().replaceAll(/[\\s-]+/g, \"_\") : \"\";\n}\n\nfunction normalizeTypeName(value: unknown): string {\n  return typeof value === \"string\" ? value.trim().toLowerCase() : \"\";\n}\n\nfunction resolveStatusId(value: string, statusRegistry: StatusTokenResolver | undefined): string {\n  const token = normalizeStatusToken(value);\n  if (token.length === 0) {\n    return \"\";\n  }\n  return statusRegistry?.alias_to_id?.get(token) ?? token;\n}\n\n/**\n * Normalize the raw type_workflows from a runtime schema into a deduped,\n * lower-cased-type list with normalized status tokens.\n *\n * An entry is kept when it has a valid (non-empty) `type` AND its\n * `allowed_transitions` is an ARRAY — even when that array is empty. An explicit\n * empty array is a deliberate DENY-ALL rule (only same-status no-ops are\n * permitted, see evaluateTransition), so it must NOT collapse into \"no rule\"\n * (which would leave the type unrestricted). Entries with a missing/empty type\n * or a non-array `allowed_transitions` are dropped, as are malformed/short pairs.\n */\nexport function resolveTypeWorkflows(\n  schema: Pick<RuntimeSchemaSettings, \"type_workflows\"> | undefined,\n): NormalizedTypeWorkflow[] {\n  const rawWorkflows: TypeWorkflowDefinition[] = Array.isArray(schema?.type_workflows) ? schema!.type_workflows! : [];\n  const byType = new Map<string, { pairs: [string, string][]; denyAll: boolean }>();\n  for (const entry of rawWorkflows) {\n    const type = normalizeTypeName(entry?.type);\n    if (type.length === 0) {\n      continue;\n    }\n    if (!Array.isArray(entry?.allowed_transitions)) {\n      continue;\n    }\n    const pairs = entry.allowed_transitions;\n    const record = byType.get(type) ?? { pairs: [], denyAll: false };\n    // Only an explicitly empty array is an intentional deny-all; a nonempty array\n    // whose pairs are all malformed is a typo and must be dropped (not deny-all).\n    if (pairs.length === 0) {\n      record.denyAll = true;\n    }\n    for (const pair of pairs) {\n      if (!Array.isArray(pair) || pair.length !== 2) {\n        continue;\n      }\n      const from = normalizeStatusToken(pair[0]);\n      const to = normalizeStatusToken(pair[1]);\n      if (from.length === 0 || to.length === 0) {\n        continue;\n      }\n      if (record.pairs.some((candidate) => candidate[0] === from && candidate[1] === to)) {\n        continue;\n      }\n      record.pairs.push([from, to]);\n    }\n    byType.set(type, record);\n  }\n  return [...byType.entries()]\n    .filter(([, record]) => record.pairs.length > 0 || record.denyAll)\n    .map(([type, record]) => ({ type, allowed_transitions: record.pairs }))\n    .sort((left, right) => left.type.localeCompare(right.type));\n}\n\n/**\n * Evaluate whether a status transition is allowed for the given item type.\n * Returns hasRule=false (allowed) when the type is unrestricted.\n */\nexport function evaluateTransition(input: EvaluateTransitionInput): EvaluateTransitionResult {\n  const typeName = normalizeTypeName(input.typeName);\n  const matched = input.typeWorkflows.find((workflow) => workflow.type === typeName);\n  if (!matched) {\n    return { allowed: true, hasRule: false, allowedTransitions: [] };\n  }\n  const from = resolveStatusId(input.fromStatus, input.statusRegistry);\n  const to = resolveStatusId(input.toStatus, input.statusRegistry);\n  // A no-op self-transition is always permitted, even under a restricting rule.\n  if (from.length > 0 && from === to) {\n    return { allowed: true, hasRule: true, allowedTransitions: matched.allowed_transitions };\n  }\n  const allowed = matched.allowed_transitions.some((pair) => {\n    const ruleFrom = resolveStatusId(pair[0], input.statusRegistry);\n    const ruleTo = resolveStatusId(pair[1], input.statusRegistry);\n    return ruleFrom === from && ruleTo === to;\n  });\n  return { allowed, hasRule: true, allowedTransitions: matched.allowed_transitions };\n}\n\n/** Render the allowed transitions for an error/warning hint. */\nexport function describeAllowedTransitions(allowedTransitions: [string, string][]): string {\n  if (allowedTransitions.length === 0) {\n    return \"(no transitions allowed)\";\n  }\n  return allowedTransitions.map((pair) => `${pair[0]} -> ${pair[1]}`).join(\", \");\n}\n"],"names":[],"mappings":"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","debugId":"70ab7197-566b-52de-8a82-e432b324ad8d"}

package/dist/core/search/cache.d.ts

@@ -1,4 +1,5 @@
 import { readSettings } from "../store/settings.js";
+import type { VectorizationEmbeddingMetadata } from "./vectorization-metadata.js";
 export declare const SEARCH_CACHE_ARTIFACT_PATHS: readonly ["index/manifest.json", "search/embeddings.jsonl"];
 export declare const VECTORIZATION_STATUS_LEDGER_PATH = "search/vectorization-status.json";
 export interface SearchCacheInvalidationResult {
@@ -31,10 +32,11 @@ export interface SemanticRefreshOptions {
 }
 export interface VectorizationStatusLedgerReadResult {
     entries: Record<string, string>;
+    embedding: VectorizationEmbeddingMetadata | null;
     warnings: string[];
 }
 export declare function readVectorizationStatusLedger(pmRoot: string): Promise<VectorizationStatusLedgerReadResult>;
-export declare function writeVectorizationStatusLedger(pmRoot: string, entries: Record<string, string>): Promise<void>;
+export declare function writeVectorizationStatusLedger(pmRoot: string, entries: Record<string, string>, embedding?: VectorizationEmbeddingMetadata | null): Promise<void>;
 export declare function invalidateSearchCacheArtifacts(pmRoot: string): Promise<SearchCacheInvalidationResult>;
 export declare function refreshSemanticEmbeddingsForMutatedItems(pmRoot: string, itemIds: string[], options?: SemanticRefreshOptions): Promise<SemanticMutationRefreshResult>;
 /**

package/dist/core/search/cache.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]="d04073fd-fa5a-5454-8e71-11bc477005b0")}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]="5d698c95-b557-5c29-bc3f-caf70b5d6d0f")}catch(e){}}();
 import path from "node:path";
 import { getActiveExtensionRegistrations } from "../extensions/index.js";
 import { pathExists, readFileIfExists, removeFileIfExists, writeFileAtomic } from "../fs/fs-utils.js";
@@ -13,7 +13,8 @@ import { buildSemanticCorpusInput } from "./corpus.js";
 import { resolveEmbeddingProviders } from "./providers.js";
 import { resolveSettingsWithSemanticRuntimeDefaults } from "./semantic-defaults.js";
 import { scheduleBackgroundSemanticRefresh } from "./background-refresh.js";
-import { executeVectorDelete, executeVectorUpsert, resolveVectorStores } from "./vector-stores.js";
+import { executeVectorDelete, executeVectorReset, executeVectorUpsert, resolveVectorStores } from "./vector-stores.js";
+import { buildVectorizationEmbeddingIdentity, buildVectorizationEmbeddingMetadata, hasVectorizationEmbeddingIdentityChanged, hasVectorizationVectorDimensionChanged, inferConsistentVectorDimension, normalizeVectorizationEmbeddingMetadata, } from "./vectorization-metadata.js";
 import { nowIso } from "../shared/time.js";
 export const SEARCH_CACHE_ARTIFACT_PATHS = ["index/manifest.json", "search/embeddings.jsonl"];
 export const VECTORIZATION_STATUS_LEDGER_PATH = "search/vectorization-status.json";
@@ -44,6 +45,7 @@ export async function readVectorizationStatusLedger(pmRoot) {
     if (raw === null || raw.trim().length === 0) {
         return {
             entries: {},
+            embedding: null,
             warnings: [],
         };
     }
@@ -54,6 +56,7 @@ export async function readVectorizationStatusLedger(pmRoot) {
     catch {
         return {
             entries: {},
+            embedding: null,
             warnings: ["search_vectorization_status_ledger_invalid"],
         };
     }
@@ -63,6 +66,7 @@ export async function readVectorizationStatusLedger(pmRoot) {
         !Array.isArray(parsed.items)) {
         return {
             entries: {},
+            embedding: null,
             warnings: ["search_vectorization_status_ledger_invalid"],
         };
     }
@@ -71,6 +75,7 @@ export async function readVectorizationStatusLedger(pmRoot) {
         if (typeof entry !== "object" || entry === null) {
             return {
                 entries: {},
+                embedding: null,
                 warnings: ["search_vectorization_status_ledger_invalid"],
             };
         }
@@ -79,22 +84,36 @@ export async function readVectorizationStatusLedger(pmRoot) {
         if (typeof id !== "string" || id.trim().length === 0 || !isValidUpdatedAt(updatedAt)) {
             return {
                 entries: {},
+                embedding: null,
                 warnings: ["search_vectorization_status_ledger_invalid"],
             };
         }
         mapped.set(id.trim(), updatedAt);
     }
+    let embedding = null;
+    try {
+        embedding = normalizeVectorizationEmbeddingMetadata(parsed.embedding);
+    }
+    catch {
+        return {
+            entries: {},
+            embedding: null,
+            warnings: ["search_vectorization_status_ledger_invalid"],
+        };
+    }
     return {
         entries: Object.fromEntries([...mapped.entries()].sort((left, right) => left[0].localeCompare(right[0]))),
+        embedding,
         warnings: [],
     };
 }
-export async function writeVectorizationStatusLedger(pmRoot, entries) {
+export async function writeVectorizationStatusLedger(pmRoot, entries, embedding) {
     const normalizedEntries = normalizeVectorizationLedgerEntries(entries);
     const ledgerPath = path.join(pmRoot, VECTORIZATION_STATUS_LEDGER_PATH);
     const serialized = `${JSON.stringify({
         version: 1,
         generated_at: nowIso(),
+        ...(embedding ? { embedding } : {}),
         items: Object.entries(normalizedEntries).map(([id, updated_at]) => ({
             id,
             updated_at,
@@ -111,6 +130,13 @@ function buildVectorPayload(item) {
         updated_at: item.updated_at,
     };
 }
+function buildVectorizationIdentityForProvider(provider) {
+    const identity = buildVectorizationEmbeddingIdentity(provider.name, provider.model);
+    if (!identity) {
+        throw new Error("Embedding provider must include a provider name and model");
+    }
+    return identity;
+}
 function buildSkippedSemanticRefreshResult(itemIds, warning) {
     return {
         refreshed: [],
@@ -177,31 +203,39 @@ async function collectSemanticRefreshWorkload(pmRoot, idPrefix, preferredFormat,
         warnings,
     };
 }
-async function refreshLocatedSemanticVectors(settings, provider, vectorStore, documents) {
-    if (documents.length === 0) {
-        return { refreshed: [], skipped: [], warnings: [] };
-    }
+async function embedLocatedSemanticVectors(settings, provider, documents) {
+    const corpusInputs = documents.map((entry) => buildSemanticCorpusInput(entry.document, {
+        providerName: provider.name,
+    }));
+    const embeddingResult = await executeEmbeddingBatchesWithRetry(provider, settings, corpusInputs);
+    return {
+        vectors: embeddingResult.vectors,
+        vector_dimension: inferConsistentVectorDimension(embeddingResult.vectors, "Semantic refresh embedding"),
+        warnings: embeddingResult.warnings,
+    };
+}
+async function upsertLocatedSemanticVectors(vectorStore, documents, vectors) {
+    await executeVectorUpsert(vectorStore, documents.map((entry, index) => ({
+        id: entry.id,
+        vector: vectors[index],
+        payload: buildVectorPayload(entry.document.metadata),
+    })));
+    return {
+        refreshed: documents.map((entry) => entry.id),
+        skipped: [],
+        warnings: [],
+    };
+}
+async function resetSemanticVectorStore(vectorStore, ledgerEntries) {
     try {
-        const corpusInputs = documents.map((entry) => buildSemanticCorpusInput(entry.document, {
-            providerName: provider.name,
-        }));
-        const embeddingResult = await executeEmbeddingBatchesWithRetry(provider, settings, corpusInputs);
-        await executeVectorUpsert(vectorStore, documents.map((entry, index) => ({
-            id: entry.id,
-            vector: embeddingResult.vectors[index],
-            payload: buildVectorPayload(entry.document.metadata),
-        })));
-        return {
-            refreshed: documents.map((entry) => entry.id),
-            skipped: [],
-            warnings: embeddingResult.warnings,
-        };
+        await executeVectorReset(vectorStore, Object.keys(ledgerEntries));
+        return { refreshed: [], skipped: [], warnings: [] };
     }
     catch (error) {
         return {
             refreshed: [],
-            skipped: documents.map((entry) => entry.id),
-            warnings: [`search_semantic_refresh_failed:${toErrorMessage(error)}`],
+            skipped: [],
+            warnings: [`search_semantic_refresh_reset_failed:${toErrorMessage(error)}`],
         };
     }
 }
@@ -261,7 +295,50 @@ export async function refreshSemanticEmbeddingsForMutatedItems(pmRoot, itemIds,
     }
     const typeRegistry = resolveItemTypeRegistry(runtimeContext.settings, getActiveExtensionRegistrations());
     const workload = await collectSemanticRefreshWorkload(pmRoot, runtimeContext.settings.id_prefix, runtimeContext.settings.item_format, normalizedItemIds, typeRegistry.type_to_folder, runtimeContext.settings.schema);
-    const refreshedResult = await refreshLocatedSemanticVectors(runtimeContext.settings, runtimeContext.provider, runtimeContext.vectorStore, workload.documents);
+    const ledgerRead = workload.documents.length > 0 || workload.missingIds.length > 0
+        ? await readVectorizationStatusLedger(pmRoot)
+        : { entries: {}, embedding: null, warnings: [] };
+    const embeddingIdentity = buildVectorizationIdentityForProvider(runtimeContext.provider);
+    const nextLedgerBaseEntries = ledgerRead.entries;
+    let refreshedResult = { refreshed: [], skipped: [], warnings: [] };
+    let nextEmbeddingMetadata = ledgerRead.embedding;
+    if (workload.documents.length > 0) {
+        if (ledgerRead.embedding && hasVectorizationEmbeddingIdentityChanged(ledgerRead.embedding, embeddingIdentity)) {
+            refreshedResult = {
+                refreshed: [],
+                skipped: workload.documents.map((entry) => entry.id),
+                warnings: ["search_semantic_refresh_requires_reindex:embedding_identity_changed"],
+            };
+        }
+        else {
+            try {
+                const embedded = await embedLocatedSemanticVectors(runtimeContext.settings, runtimeContext.provider, workload.documents);
+                if (hasVectorizationVectorDimensionChanged(ledgerRead.embedding, embedded.vector_dimension)) {
+                    refreshedResult = {
+                        refreshed: [],
+                        skipped: workload.documents.map((entry) => entry.id),
+                        warnings: [...embedded.warnings, "search_semantic_refresh_requires_reindex:vector_dimension_changed"],
+                    };
+                }
+                else {
+                    nextEmbeddingMetadata = buildVectorizationEmbeddingMetadata(embeddingIdentity, embedded.vector_dimension);
+                    const upserted = await upsertLocatedSemanticVectors(runtimeContext.vectorStore, workload.documents, embedded.vectors);
+                    refreshedResult = {
+                        refreshed: upserted.refreshed,
+                        skipped: upserted.skipped,
+                        warnings: [...embedded.warnings, ...upserted.warnings],
+                    };
+                }
+            }
+            catch (error) {
+                refreshedResult = {
+                    refreshed: [],
+                    skipped: workload.documents.map((entry) => entry.id),
+                    warnings: [`search_semantic_refresh_failed:${toErrorMessage(error)}`],
+                };
+            }
+        }
+    }
     const pruneResult = await pruneMissingSemanticVectors(runtimeContext.vectorStore, workload.missingIds);
     const refreshedIdSet = new Set(refreshedResult.refreshed);
     const refreshedEntries = Object.fromEntries(workload.documents
@@ -269,16 +346,15 @@ export async function refreshSemanticEmbeddingsForMutatedItems(pmRoot, itemIds,
         .map((entry) => [entry.id, entry.document.metadata.updated_at]));
     const ledgerWarnings = [];
     if (Object.keys(refreshedEntries).length > 0 || workload.missingIds.length > 0) {
-        const ledgerRead = await readVectorizationStatusLedger(pmRoot);
         const nextEntries = {
-            ...ledgerRead.entries,
+            ...nextLedgerBaseEntries,
             ...normalizeVectorizationLedgerEntries(refreshedEntries),
         };
         for (const missingId of workload.missingIds) {
             delete nextEntries[missingId];
         }
         try {
-            await writeVectorizationStatusLedger(pmRoot, nextEntries);
+            await writeVectorizationStatusLedger(pmRoot, nextEntries, nextEmbeddingMetadata);
         }
         catch (error) {
             ledgerWarnings.push(`search_vectorization_status_ledger_write_failed:${toErrorMessage(error)}`);
@@ -374,4 +450,4 @@ export async function refreshSearchArtifactsForMutation(pmRoot, itemIds, options
     };
 }
 //# sourceMappingURL=cache.js.map
-//# debugId=d04073fd-fa5a-5454-8e71-11bc477005b0
+//# debugId=5d698c95-b557-5c29-bc3f-caf70b5d6d0f