botmux 2.111.0 → 2.112.0

package/dist/workflows/migration/v2-ledger.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Durable v2-definition -> v3 Saved Workflow migration ledger.
+ *
+ * The legacy definition file is user-authored source material and is never
+ * rewritten. One source identity (canonical real path + workflow id) owns one
+ * stable Saved Workflow. Every semantic legacy revision then maps to an exact
+ * immutable v3 revision. The v2 execution engine is gone; a pending migration
+ * is repaired by re-running the migration command without mutating the legacy
+ * source bytes.
+ */
+import { type WorkflowDefinition } from '../definition.js';
+import { type SavedWorkflowOwner, type SavedWorkflowScope } from '../v3/library-schema.js';
+export declare const LEGACY_MIGRATION_LEDGER_SCHEMA_VERSION: 1;
+export declare const LEGACY_SOURCE_KEY_RE: RegExp;
+export declare const LEGACY_MIGRATION_KEY_RE: RegExp;
+export declare const LEGACY_CONTENT_HASH_RE: RegExp;
+export declare const LEGACY_CONVERSION_HASH_RE: RegExp;
+export type LegacyMigrationState = 'pending' | 'committed';
+export interface LegacySourceIdentity {
+    path: string;
+    workflowId: string;
+}
+export interface LegacyDefinitionIdentity extends LegacySourceIdentity {
+    contentHash: string;
+}
+export interface LegacyMigrationTarget {
+    workflowId: string;
+    owner: SavedWorkflowOwner;
+    scope: SavedWorkflowScope;
+}
+export type LegacyMigrationSupersedeReason = 'target_latest_changed_before_materialization';
+/** Immutable audit row for an explicitly abandoned pending allocation. */
+export interface LegacyMigrationSupersededAllocation {
+    conversionHash: string;
+    targetRevisionId: string;
+    targetHumanVersion: number;
+    targetCreatedAt: string;
+    expectedLatestRevision?: string;
+    preparedAt: string;
+    supersededAt: string;
+    reason: LegacyMigrationSupersedeReason;
+}
+/**
+ * Allocation frozen before touching the v3 library. It contains enough data
+ * to reconstruct and byte-check the exact immutable revision after any crash.
+ */
+export interface LegacyMigrationRevisionRecord {
+    migrationKey: string;
+    state: LegacyMigrationState;
+    contentHash: string;
+    conversionHash: string;
+    targetRevisionId: string;
+    targetHumanVersion: number;
+    targetCreatedAt: string;
+    expectedLatestRevision?: string;
+    preparedAt: string;
+    updatedAt: string;
+    supersededAllocations?: LegacyMigrationSupersededAllocation[];
+}
+export interface LegacyMigrationSourceRecord {
+    sourceKey: string;
+    legacy: LegacySourceIdentity;
+    target: LegacyMigrationTarget;
+    revisions: Record<string, LegacyMigrationRevisionRecord>;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface LegacyMigrationLedger {
+    schemaVersion: typeof LEGACY_MIGRATION_LEDGER_SCHEMA_VERSION;
+    sources: Record<string, LegacyMigrationSourceRecord>;
+}
+export type LegacyMigrationLookup = {
+    kind: 'none';
+} | {
+    kind: 'exact';
+    source: LegacyMigrationSourceRecord;
+    revision: LegacyMigrationRevisionRecord;
+} | {
+    kind: 'changed_after_migration';
+    source: LegacyMigrationSourceRecord;
+    currentContentHash: string;
+};
+export declare class LegacyMigrationLedgerError extends Error {
+    constructor(message: string);
+}
+export declare function legacyMigrationLedgerPath(dataDir: string): string;
+export declare function legacyDefinitionIdentity(path: string, definition: WorkflowDefinition): LegacyDefinitionIdentity;
+export declare function legacySourceKey(identity: LegacySourceIdentity): string;
+export declare function legacyMigrationKey(identity: LegacyDefinitionIdentity): string;
+/** Stable across legacy revisions so semantic edits append v3 revisions. */
+export declare function migratedSavedWorkflowId(identity: LegacySourceIdentity): string;
+export declare function computeLegacyConversionHash(value: unknown): string;
+export declare function validateLegacyMigrationSourceRecord(raw: unknown, expectedSourceKey?: string): LegacyMigrationSourceRecord;
+export declare function validateLegacyMigrationLedger(raw: unknown): LegacyMigrationLedger;
+export declare function readLegacyMigrationLedger(dataDir: string): LegacyMigrationLedger;
+export interface PrepareLegacyMigrationInput {
+    identity: LegacyDefinitionIdentity;
+    target: LegacyMigrationTarget;
+    conversionHash: string;
+    targetRevisionId: string;
+    targetHumanVersion: number;
+    targetCreatedAt: string;
+    expectedLatestRevision?: string;
+    now?: Date;
+}
+/**
+ * First durable phase. The exact target allocation is immutable once written.
+ * A repeated call must reproduce it byte-for-byte or fail closed.
+ */
+export declare function prepareLegacyMigration(dataDir: string, input: PrepareLegacyMigrationInput): {
+    source: LegacyMigrationSourceRecord;
+    revision: LegacyMigrationRevisionRecord;
+    created: boolean;
+};
+export interface SupersedePendingLegacyMigrationInput extends PrepareLegacyMigrationInput {
+    /** CAS guard: the exact pending allocation the operator inspected. */
+    previousTargetRevisionId: string;
+    reason: LegacyMigrationSupersedeReason;
+}
+/**
+ * Explicit recovery for a pending allocation that was never materialized but
+ * whose optimistic library base moved. The abandoned allocation is retained
+ * as immutable audit evidence; committed rows can never be superseded.
+ *
+ * The service must prove the previous target revision is absent before calling
+ * this ledger seam. A concurrent drift after reallocation is harmless: the
+ * library CAS fails and the operator may explicitly supersede again.
+ */
+export declare function supersedePendingLegacyMigration(dataDir: string, input: SupersedePendingLegacyMigrationInput): {
+    source: LegacyMigrationSourceRecord;
+    revision: LegacyMigrationRevisionRecord;
+};
+export declare function commitLegacyMigration(dataDir: string, identity: LegacyDefinitionIdentity, now?: Date): {
+    source: LegacyMigrationSourceRecord;
+    revision: LegacyMigrationRevisionRecord;
+};
+export declare function findLegacyMigration(dataDir: string, identity: LegacyDefinitionIdentity): LegacyMigrationLookup;
+//# sourceMappingURL=v2-ledger.d.ts.map

package/dist/workflows/migration/v2-ledger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"v2-ledger.d.ts","sourceRoot":"","sources":["../../../src/workflows/migration/v2-ledger.ts"],"names":[],"mappings":"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"}