kibi-cli 2.3.0 → 2.5.0

package/dist/operations/mutation/plan-apply-journal.d.ts

@@ -0,0 +1,182 @@
+import type { FilesystemPort, OperationContext, PrologPort } from "../../public/operations/runtime-types.js";
+import type { RelationshipInput } from "./types.js";
+/**
+ * Write-ahead journal for atomic kb_apply_plan application.
+ *
+ * A compile plan changes two resources: workspace files (the plan's
+ * sourceWrites and the relationship shards its steps append) and the compiled
+ * branch store. Before the first write, the journal records every intended
+ * file change with exact before/after bytes and hashes, every store upsert,
+ * and a fingerprint of the store entities the plan touches. Files are then
+ * published with temp-file + rename (fsync where the port supports it), and
+ * the store mutations commit in one Prolog transaction. The store commit is
+ * the only commit point: any failure before it restores every file from the
+ * journal, and an interrupted application is completed or rolled back from
+ * the journal by the next mutating call.
+ */
+export declare const PLAN_APPLY_JOURNAL_VERSION: "kibi.plan-apply-journal.v1";
+export type PlanApplyFileWrite = Readonly<{
+    /** Workspace-relative path with forward slashes. */
+    path: string;
+    /**
+     * plan: one of the plan's sourceWrites; entity-document: the authored
+     * document a step's entity is rendered into; relationship-shard: a shard
+     * the steps' relationships append to.
+     */
+    origin: "plan" | "entity-document" | "relationship-shard";
+    mode: "write" | "delete";
+    beforeHash: string | null;
+    afterHash: string | null;
+    /** Exact bytes before the plan; null when the file did not exist. */
+    before: string | null;
+    /** Exact bytes after the plan; null for a delete. */
+    after: string | null;
+}>;
+export type PlanApplyStoreEntry = Readonly<{
+    entity: Readonly<Record<string, unknown>>;
+    relationships: readonly RelationshipInput[];
+    skipContradictionCheck: boolean;
+}>;
+export type PlanApplyJournalState = 
+/** Journal durable; files may be partly published; store untouched. */
+"prepared"
+/** Files published; the store batch was (or is about to be) submitted. */
+ | "store_committing"
+/** The store accepted the batch; postcommit receipts may be pending. */
+ | "store_committed" | "committed" | "rolled_back";
+export type PlanApplyJournal = Readonly<{
+    version: typeof PLAN_APPLY_JOURNAL_VERSION;
+    journalId: string;
+    planHash: string;
+    branch: string;
+    state: PlanApplyJournalState;
+    createdAt: string;
+    updatedAt: string;
+    /** Emptied once the journal reaches a terminal state. */
+    files: readonly PlanApplyFileWrite[];
+    store: Readonly<{
+        entityIds: readonly string[];
+        /** Fingerprint of the touched store entities before the commit. */
+        preCommitFingerprint: string;
+        /** Emptied once the journal reaches a terminal state. */
+        entries: readonly PlanApplyStoreEntry[];
+    }>;
+    summary: Readonly<{
+        planPaths: readonly string[];
+        filePaths: readonly string[];
+        changedEntities: number;
+        changedRelationships: number;
+    }>;
+    resolution?: Readonly<{
+        action: "completed" | "rolled_back";
+        by: "apply" | "recovery";
+        detail: string;
+    }>;
+}>;
+export type PlanApplyRecovery = Readonly<{
+    journalId: string;
+    planHash: string;
+    /** What this recovery did; "none" when the journal was already terminal. */
+    action: "completed" | "rolled_back" | "none";
+    state: "committed" | "rolled_back";
+    /** Workspace files this recovery changed. */
+    restoredPaths: readonly string[];
+    detail: string;
+    /** Postcommit receipt failure left for the next recovery, if any. */
+    receiptFailure?: string;
+}>;
+export declare function planApplyJournalId(planHash: string): string;
+export declare function isPlanApplyJournalId(value: string): boolean;
+export declare function contentHash(value: string): string;
+/** A journal handle bound to its file. */
+export type PlanApplyJournalHandle = {
+    readonly journalPath: string;
+    journal: PlanApplyJournal;
+};
+/**
+ * The terminal-or-absent journal slot for a plan. Returns the existing
+ * journal (if any) so the caller can refuse a plan that already committed.
+ */
+export declare function openPlanApplyJournal(context: OperationContext, planHash: string): Readonly<{
+    journalId: string;
+    journalPath: string;
+    branch: string;
+    existing: PlanApplyJournal | null;
+}>;
+/** Durably record a journal state; the handle tracks the latest record. */
+export declare function recordPlanApplyJournal(handle: PlanApplyJournalHandle, update: Partial<Pick<PlanApplyJournal, "state" | "resolution">>, now?: Date): void;
+export declare function createPlanApplyJournal(journalPath: string, journal: PlanApplyJournal): PlanApplyJournalHandle;
+/** Bind pending-source receipts to the bytes a committed plan published. */
+export declare function reconcilePendingSourceReceipts(workspaceRoot: string, writes: readonly {
+    readonly path: string;
+    readonly mode?: "write" | "delete";
+    readonly afterHash: string | null;
+}[]): void;
+/**
+ * Replace one workspace file atomically: write a unique staged file in the
+ * target directory, fsync it, rename it over the target, then fsync the
+ * directory. Ports without rename (test and constrained hosts) write the
+ * target directly.
+ */
+export declare function publishWorkspaceFile(fsPort: FilesystemPort, absolute: string, content: string): Promise<void>;
+/**
+ * Publish every journaled file's after-bytes in journal order. Throws on the
+ * first failure; the caller restores the before-bytes from the journal.
+ */
+export declare function publishJournaledFiles(fsPort: FilesystemPort, workspaceRoot: string, files: readonly PlanApplyFileWrite[]): Promise<void>;
+/** Restore every journaled file's before-bytes (in-process rollback). */
+export declare function restoreJournaledFiles(fsPort: FilesystemPort, workspaceRoot: string, journalPath: string, files: readonly PlanApplyFileWrite[]): Promise<string[]>;
+/**
+ * Fingerprint the store state of the entities a plan touches: their sorted
+ * properties and outgoing relationships. Comparing the fingerprint taken
+ * before the commit with a later one decides whether an interrupted batch
+ * commit took effect; the batch is one transaction, so it either changed the
+ * plan's entities or changed nothing.
+ */
+export declare function storeFingerprint(prolog: PrologPort, entityIds: readonly string[]): Promise<string>;
+type RecoveryOptions = Readonly<{
+    /** Lazily acquire Prolog; needed only to resolve a store_committing journal. */
+    prolog: () => Promise<PrologPort | undefined>;
+    now?: () => Date;
+}>;
+/**
+ * Deterministically finish one journal:
+ * - prepared: the store was never asked to commit, so every file is restored
+ *   to its before-bytes and the journal ends rolled_back;
+ * - store_committing: the store fingerprint decides. Unchanged since the
+ *   journal was written means the batch never took effect (roll back);
+ *   changed means it committed (complete: publish every after-byte);
+ * - store_committed: complete;
+ * - committed / rolled_back: nothing to do (replay is idempotent).
+ * Recovery refuses, changing nothing, when a journaled file holds neither
+ * its before nor its after bytes.
+ */
+export declare function recoverPlanApplyJournal(context: OperationContext, handle: PlanApplyJournalHandle, options: RecoveryOptions): Promise<PlanApplyRecovery>;
+/** Open an explicit journal by id for kb_apply_plan recoveryJournalId. */
+export declare function openPlanApplyJournalById(context: OperationContext, journalId: string): PlanApplyJournalHandle;
+/**
+ * Detect and finish every incomplete plan journal of the active branch. Runs
+ * at the start of each mutating call that holds the workspace mutation lock,
+ * before that call reads or writes anything. Journals are finished in path
+ * order so the outcome does not depend on directory enumeration order.
+ */
+export declare function recoverPendingPlanApplyJournals(context: OperationContext, options: RecoveryOptions): Promise<PlanApplyRecovery[]>;
+/** One line per journal a recovery actually changed, for result warnings. */
+export declare function planRecoveryNotes(recoveries: readonly PlanApplyRecovery[]): string[];
+/**
+ * A mutating call that settled an interrupted plan and then failed on its own
+ * work still reports the settlement in its failure text. Typed errors keep
+ * their class, code and retryability.
+ */
+export declare function withPlanRecoveryNotes(error: unknown, notes: readonly string[]): unknown;
+/**
+ * Recover every pending plan journal before another mutation, then refuse
+ * that mutation while a recovered plan still has unfinished postcommit work
+ * (pending-source receipts): a later write could change the files the
+ * journal guards and leave it unrecoverable. `explicitJournalId` is the
+ * journal the caller is recovering on purpose, which reports its own
+ * unfinished work instead.
+ */
+export declare function settlePendingPlanApplyJournals(context: OperationContext, options: RecoveryOptions, explicitJournalId?: string): Promise<PlanApplyRecovery[]>;
+export {};
+//# sourceMappingURL=plan-apply-journal.d.ts.map

package/dist/operations/mutation/plan-apply-journal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan-apply-journal.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/plan-apply-journal.ts"],"names":[],"mappings":"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"}