@unbrained/pm-cli 2026.9.2 → 2026.9.3

package/dist/core/history/event-classification.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @module core/history/event-classification
+ *
+ * Declares the stable semantic boundary between history events that advance
+ * project work and maintenance events that only preserve tracker governance.
+ */
+import type { HistoryEntry } from "../../types/index.js";
+/** Current version of the public history-event classification policy. */
+export declare const HISTORY_EVENT_CLASSIFICATION_VERSION: 1;
+/** Semantic effect of an immutable history event on project recency. */
+export type HistoryEventClass = "substantive" | "maintenance";
+/** Operations whose meaning is always governance or storage maintenance. */
+export declare const MAINTENANCE_HISTORY_OPERATIONS: readonly ["docs_add", "files_add", "history:author-acknowledge", "history_author_acknowledge", "history_compact", "history_compact_baseline", "history_redact", "history_repair", "normalize", "release", "test_run_track", "tests_add", "tests_remove", "update_audit", "update_ownership_bypass"];
+/** Operations whose meaning always advances lifecycle or working context. */
+export declare const SUBSTANTIVE_HISTORY_OPERATIONS: readonly ["append", "cancel", "claim", "close", "comment_add", "create", "learning_add", "note_add", "reopen"];
+/**
+ * Classify an immutable event using its declared class when present, then the
+ * versioned operation/path contract. Unknown events fail closed as substantive
+ * so new work cannot silently disappear from temporal relevance.
+ */
+export declare function classifyHistoryEvent(entry: Pick<HistoryEntry, "op" | "patch" | "event_class">): HistoryEventClass;

package/dist/core/history/event-classification.js

@@ -0,0 +1,109 @@
+/** Current version of the public history-event classification policy. */
+
+!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]="6398c65d-fb5c-5479-93c2-0be963352a92")}catch(e){}}();
+export const HISTORY_EVENT_CLASSIFICATION_VERSION = 1;
+/** Operations whose meaning is always governance or storage maintenance. */
+export const MAINTENANCE_HISTORY_OPERATIONS = [
+    "docs_add",
+    "files_add",
+    "history:author-acknowledge",
+    "history_author_acknowledge",
+    "history_compact",
+    "history_compact_baseline",
+    "history_redact",
+    "history_repair",
+    "normalize",
+    "release",
+    "test_run_track",
+    "tests_add",
+    "tests_remove",
+    "update_audit",
+    "update_ownership_bypass",
+];
+/** Operations whose meaning always advances lifecycle or working context. */
+export const SUBSTANTIVE_HISTORY_OPERATIONS = [
+    "append",
+    "cancel",
+    "claim",
+    "close",
+    "comment_add",
+    "create",
+    "learning_add",
+    "note_add",
+    "reopen",
+];
+const MAINTENANCE_OPERATIONS = new Set(MAINTENANCE_HISTORY_OPERATIONS);
+const SUBSTANTIVE_OPERATIONS = new Set(SUBSTANTIVE_HISTORY_OPERATIONS);
+const MAINTENANCE_UPDATE_FIELDS = new Set([
+    "actual_result",
+    "affected_version",
+    "assignee",
+    "blocked_by",
+    "blocked_reason",
+    "close_reason",
+    "confidence",
+    "customer_impact",
+    "definition_of_ready",
+    "dependencies",
+    "docs",
+    "environment",
+    "expected_result",
+    "files",
+    "fixed_version",
+    "goal",
+    "impact",
+    "learnings",
+    "notes",
+    "objective",
+    "order",
+    "outcome",
+    "parent",
+    "release",
+    "reminders",
+    "reporter",
+    "repro_steps",
+    "resolution",
+    "reviewer",
+    "severity",
+    "sprint",
+    "tests",
+    "test_runs",
+    "unblock_note",
+    "updated_at",
+    "value",
+    "why_now",
+]);
+function topLevelPatchField(operation) {
+    const segments = operation.path.split("/").filter(Boolean);
+    if (segments[0] === "metadata" || segments[0] === "front_matter") {
+        return segments[1];
+    }
+    return segments[0] === "body" ? "body" : undefined;
+}
+/**
+ * Classify an immutable event using its declared class when present, then the
+ * versioned operation/path contract. Unknown events fail closed as substantive
+ * so new work cannot silently disappear from temporal relevance.
+ */
+export function classifyHistoryEvent(entry) {
+    if (entry.event_class === "substantive" ||
+        entry.event_class === "maintenance") {
+        return entry.event_class;
+    }
+    if (MAINTENANCE_OPERATIONS.has(entry.op))
+        return "maintenance";
+    if (SUBSTANTIVE_OPERATIONS.has(entry.op))
+        return "substantive";
+    if (entry.op !== "update")
+        return "substantive";
+    return Array.isArray(entry.patch) &&
+        entry.patch.length > 0 &&
+        entry.patch.every((operation) => {
+            const field = topLevelPatchField(operation);
+            return field !== undefined && MAINTENANCE_UPDATE_FIELDS.has(field);
+        })
+        ? "maintenance"
+        : "substantive";
+}
+//# sourceMappingURL=event-classification.js.map
+//# debugId=6398c65d-fb5c-5479-93c2-0be963352a92

package/dist/core/history/event-index.d.ts

@@ -47,6 +47,8 @@ export interface HistoryEventIndexQueryResult {
     /** Whether another matching event exists. */
     has_more: boolean;
 }
+/** Latest substantive immutable event for each requested history stream. */
+export type LatestSubstantiveHistoryEvents = Readonly<Record<string, IndexedHistoryEvent>>;
 declare function loadDatabaseSync(loadModule: (specifier: string) => unknown): DatabaseSyncConstructor | null;
 declare function loadStableDatabaseSync(nodeVersion: string, loadModule: (specifier: string) => unknown): DatabaseSyncConstructor | null;
 /** Rebuild the complete optional event projection from authoritative streams. */
@@ -57,16 +59,25 @@ export declare function rebuildHistoryEventIndex(pmRoot: string): Promise<boolea
  */
 export declare function queryHistoryEventStreams(pmRoot: string, query: HistoryEventIndexQuery): Promise<HistoryEventIndexQueryResult>;
 /**
- * Update an already-built event projection after one authoritative append.
- * Absence is a cheap no-op; corrupt projections are removed for lazy rebuild.
+ * Serialize an authoritative append with its optional SQLite projection.
+ * The database write lock spans the file append and size capture, so compliant
+ * cross-process writers cannot certify a newer stream size with older rows.
  */
-export declare function updateHistoryEventIndexAfterAppend(historyPath: string, entry: HistoryEntry): Promise<void>;
+export declare function appendHistoryEntryWithEventIndex(historyPath: string, entry: HistoryEntry, append: () => Promise<void>): Promise<void>;
 /** Invalidate the optional event projection after a non-append rewrite. */
 export declare function removeHistoryEventIndexForHistoryPath(historyPath: string): Promise<void>;
 /** Query the optional event projection without scanning history streams. */
 export declare function queryHistoryEventIndex(pmRoot: string, query: HistoryEventIndexQuery): Promise<HistoryEventIndexQueryResult | null>;
+declare function collectLatestSubstantiveEvents(events: readonly IndexedHistoryEvent[], requested: ReadonlySet<string>): Record<string, IndexedHistoryEvent>;
+/**
+ * Read one latest substantive coordinate per requested stream. The optional
+ * SQLite projection is preferred; individual authoritative streams are the
+ * fail-closed fallback and remain the source of truth.
+ */
+export declare function readLatestSubstantiveHistoryEvents(pmRoot: string, streamIds: readonly string[]): Promise<LatestSubstantiveHistoryEvents>;
 /** Test-only dependency seam for runtimes without `node:sqlite`. */
 export declare const _testOnly: {
+    collectLatestSubstantiveEvents: typeof collectLatestSubstantiveEvents;
     loadDatabaseSync: typeof loadDatabaseSync;
     loadStableDatabaseSync: typeof loadStableDatabaseSync;
     setDatabaseSync(databaseSync: DatabaseSyncConstructor | null): () => void;