@lmzhen/dsh-evolution-core 0.30.16 → 0.30.18

package/lib/types/unit-storage.d.ts

@@ -0,0 +1,83 @@
+import type { EvolutionIoLike } from './io.ts';
+export declare const UNIT_STORAGE_SCHEMA_VERSION = 1;
+export interface UnitSnapshot {
+    readonly schemaVersion: typeof UNIT_STORAGE_SCHEMA_VERSION;
+    readonly unitId: string;
+    readonly planDigest: string;
+    readonly runId: string;
+    readonly target: string;
+    readonly targetExists: boolean;
+    readonly targetBefore: string | null;
+    readonly targetAfter?: string;
+    readonly supportBefore: readonly {
+        path: string;
+        content: string | null;
+    }[];
+    readonly supportAfter: readonly {
+        path: string;
+        content: string;
+    }[];
+    readonly sourceBefore: readonly {
+        name: string;
+        body: string;
+    }[];
+    readonly origin: string;
+    readonly summary: string;
+    readonly createdAt: number;
+}
+export interface UnitEvidenceRecord {
+    readonly schemaVersion: typeof UNIT_STORAGE_SCHEMA_VERSION;
+    readonly unitId: string;
+    readonly runId: string;
+    readonly planDigest: string;
+    readonly state: 'target-only' | 'sources-partial' | 'complete';
+    readonly target: {
+        before: string | null;
+        after: string;
+        supportDigest: string;
+        created: boolean;
+    };
+    readonly sources: readonly {
+        name: string;
+        before: string;
+        after: string | null;
+        archived: boolean;
+        absorbedInto: string;
+    }[];
+    readonly mutations: number;
+    readonly at: number;
+}
+export interface UnitIndexEntry {
+    readonly unitId: string;
+    readonly storageKey: string;
+    readonly runId: string;
+    readonly planDigest: string;
+    readonly state: UnitEvidenceRecord['state'];
+    readonly receiptPath?: string;
+    readonly updatedAt: number;
+}
+/** Stable, filesystem-safe key; unitId stays opaque (may contain ':' or '/'). */
+export declare function unitStorageKey(unitId: string): string;
+export declare function unitSnapshotsDir(home: string): string;
+export declare function unitSnapshotPath(home: string, unitId: string): string;
+export declare function unitEvidencePath(home: string, unitId: string): string;
+export declare function unitIndexPath(home: string): string;
+export declare function writeUnitSnapshot(io: EvolutionIoLike, home: string, snapshot: UnitSnapshot): Promise<string>;
+export declare function readUnitSnapshot(io: EvolutionIoLike, home: string, unitId: string): Promise<UnitSnapshot | null>;
+export declare function writeUnitEvidence(io: EvolutionIoLike, home: string, evidence: UnitEvidenceRecord): Promise<string>;
+export declare function readUnitEvidence(io: EvolutionIoLike, home: string, unitId: string): Promise<UnitEvidenceRecord | null>;
+export declare function readUnitIndex(io: EvolutionIoLike, home: string): Promise<UnitIndexEntry[]>;
+export declare function upsertUnitIndex(io: EvolutionIoLike, home: string, entry: UnitIndexEntry): Promise<void>;
+export interface UnitReceiptRecord {
+    readonly schemaVersion: typeof UNIT_STORAGE_SCHEMA_VERSION;
+    readonly unitId: string;
+    readonly runId: string;
+    readonly planDigest: string;
+    readonly target: string;
+    readonly archived: readonly string[];
+    readonly at: number;
+}
+export declare function unitReceiptPath(home: string, unitId: string): string;
+export declare function writeUnitReceipt(io: EvolutionIoLike, home: string, receipt: UnitReceiptRecord): Promise<string>;
+export declare function readUnitReceipt(io: EvolutionIoLike, home: string, unitId: string): Promise<UnitReceiptRecord | null>;
+//# sourceMappingURL=unit-storage.d.ts.map

package/lib/types/unit-storage.js

@@ -0,0 +1,124 @@
+/** G2 unit storage: opaque unitId -> Windows-safe storage key. */
+import { createHash } from 'node:crypto';
+import { join } from 'node:path';
+export const UNIT_STORAGE_SCHEMA_VERSION = 1;
+/** Stable, filesystem-safe key; unitId stays opaque (may contain ':' or '/'). */
+export function unitStorageKey(unitId) {
+    return createHash('sha256').update(unitId).digest('hex');
+}
+export function unitSnapshotsDir(home) {
+    return join(home, 'merge', 'unit-snapshots');
+}
+export function unitSnapshotPath(home, unitId) {
+    return join(unitSnapshotsDir(home), unitStorageKey(unitId) + '.json');
+}
+export function unitEvidencePath(home, unitId) {
+    return join(home, 'merge', 'units', unitStorageKey(unitId), 'evidence.json');
+}
+export function unitIndexPath(home) {
+    return join(home, 'merge', 'unit-index.json');
+}
+export async function writeUnitSnapshot(io, home, snapshot) {
+    const path = unitSnapshotPath(home, snapshot.unitId);
+    const content = JSON.stringify(snapshot, null, 2) + '\n';
+    if (io.transact !== undefined)
+        await io.transact(path, () => content);
+    else
+        await io.writeText(path, content);
+    return path;
+}
+export async function readUnitSnapshot(io, home, unitId) {
+    const raw = await io.readText(unitSnapshotPath(home, unitId));
+    if (raw === null)
+        return null;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export async function writeUnitEvidence(io, home, evidence) {
+    const path = unitEvidencePath(home, evidence.unitId);
+    const content = JSON.stringify(evidence, null, 2) + '\n';
+    if (io.transact !== undefined)
+        await io.transact(path, () => content);
+    else
+        await io.writeText(path, content);
+    await upsertUnitIndex(io, home, {
+        unitId: evidence.unitId,
+        storageKey: unitStorageKey(evidence.unitId),
+        runId: evidence.runId,
+        planDigest: evidence.planDigest,
+        state: evidence.state,
+        updatedAt: evidence.at,
+    });
+    return path;
+}
+export async function readUnitEvidence(io, home, unitId) {
+    const raw = await io.readText(unitEvidencePath(home, unitId));
+    if (raw === null)
+        return null;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export async function readUnitIndex(io, home) {
+    const raw = await io.readText(unitIndexPath(home));
+    if (raw === null)
+        return [];
+    try {
+        const parsed = JSON.parse(raw);
+        return Array.isArray(parsed.entries) ? parsed.entries : [];
+    }
+    catch {
+        return [];
+    }
+}
+export async function upsertUnitIndex(io, home, entry) {
+    const path = unitIndexPath(home);
+    const content = (current) => {
+        let entries = [];
+        if (current !== null) {
+            try {
+                entries = JSON.parse(current).entries ?? [];
+            }
+            catch {
+                entries = [];
+            }
+        }
+        const next = entries.filter(item => item.unitId !== entry.unitId).concat(entry);
+        return JSON.stringify({ schemaVersion: UNIT_STORAGE_SCHEMA_VERSION, entries: next }, null, 2) + '\n';
+    };
+    if (io.transact !== undefined)
+        await io.transact(path, content);
+    else
+        await io.writeText(path, content(await io.readText(path)));
+}
+export function unitReceiptPath(home, unitId) {
+    return join(home, 'merge', 'unit-receipts', unitStorageKey(unitId) + '.json');
+}
+export async function writeUnitReceipt(io, home, receipt) {
+    const path = unitReceiptPath(home, receipt.unitId);
+    const text = JSON.stringify(receipt, null, 2) + '\n';
+    if (io.transact !== undefined)
+        await io.transact(path, () => text);
+    else
+        await io.writeText(path, text);
+    return path;
+}
+export async function readUnitReceipt(io, home, unitId) {
+    const raw = await io.readText(unitReceiptPath(home, unitId));
+    if (raw === null)
+        return null;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=unit-storage.js.map

package/lib/types/unit-transaction.d.ts

@@ -0,0 +1,195 @@
+import type { EvolutionIoLike } from "./io.ts";
+import { type UnitEvidenceRecord } from "./unit-storage.ts";
+import { type UnitJournalPhase } from "./unit-journal.ts";
+export interface UnitSupportFile {
+    readonly path: string;
+    readonly content: string;
+}
+export interface UnitPlan {
+    readonly runId: string;
+    readonly pairKey: string;
+    readonly target: string;
+    readonly targetExists: boolean;
+    readonly sources: readonly string[];
+    readonly body: string;
+    readonly supportFiles: readonly UnitSupportFile[];
+    readonly expectedTargetBody: string | null;
+    readonly expectedSourceBodies: readonly {
+        name: string;
+        body: string;
+    }[];
+    readonly origin: "foreground" | "subagent" | "background_review";
+    readonly summary: string;
+}
+export interface UnitCommitResult {
+    readonly ok: boolean;
+    readonly message: string;
+    readonly archived?: readonly string[];
+    readonly mutations?: number;
+}
+export interface UnitBackend {
+    readSkill(name: string): Promise<string | null>;
+    readSupportFile(name: string, path: string): Promise<string | null>;
+    commit(plan: UnitPlan, onPhase?: (phase: "target-pending" | "target-applied" | "target-written" | "source-archiving" | "sources-archived" | "support-pending" | "unit-written", detail?: {
+        source?: string;
+    }) => void | Promise<void>, signal?: AbortSignal, assertFence?: () => Promise<boolean>): Promise<UnitCommitResult>;
+    restoreTarget(name: string, body: string | null): Promise<void>;
+    restoreSource(name: string, body: string): Promise<void>;
+    restoreSupportFile?(name: string, path: string, content: string | null): Promise<void>;
+}
+export interface UnitClaim {
+    release(): Promise<void>;
+}
+export interface UnitClaimPort {
+    acquire(target: string, runId: string): Promise<UnitClaim>;
+}
+export interface UnitTransactionOptions {
+    readonly io: EvolutionIoLike;
+    readonly home: string;
+    readonly backend: UnitBackend;
+    readonly claim: UnitClaimPort;
+    readonly now?: () => number;
+    readonly waitMs?: number;
+    /** Gate/fault-injection seam: called after each journal phase is durable. */
+    readonly onPhase?: (phase: UnitJournalPhase) => void | Promise<void>;
+    /** Gate instrumentation: tree fence then target claim. */
+    readonly onLock?: (lock: "tree" | "claim") => void;
+}
+export type UnitErrorCode = "unit-plan-missing" | "unit-conflict" | "unit-committed" | "unit-prepare-failed" | "unit-commit-failed" | "unit-claim-failed" | "unit-fence-failed" | "unit-rollback-blocked";
+export interface UnitFailure {
+    readonly ok: false;
+    readonly code: UnitErrorCode;
+    readonly message: string;
+}
+export interface UnitPrepared {
+    readonly unitId: string;
+    readonly planDigest: string;
+}
+export interface UnitTransaction {
+    prepare(plan: UnitPlan): Promise<{
+        ok: true;
+        prepared: UnitPrepared;
+    } | UnitFailure>;
+    commit(prepared: UnitPrepared, options?: {
+        signal?: AbortSignal;
+    }): Promise<{
+        ok: true;
+        evidence: UnitEvidenceRecord;
+    } | UnitFailure>;
+    verify(ref: {
+        unitId: string;
+    } | {
+        runId: string;
+    }): Promise<UnitEvidenceRecord | UnitEvidenceRecord[] | null>;
+    rollback(ref: {
+        unitId: string;
+        reason: string;
+    }): Promise<{
+        ok: true;
+        evidence: UnitEvidenceRecord;
+    } | UnitFailure>;
+    finalize(unitId: string): Promise<{
+        ok: true;
+        evidence: UnitEvidenceRecord;
+    } | UnitFailure>;
+    rollForward(unitId: string): Promise<{
+        ok: true;
+        evidence: UnitEvidenceRecord;
+    } | UnitFailure>;
+    cancel(unitId: string, reason: string): Promise<{
+        ok: boolean;
+        phase: UnitJournalPhase | "none";
+    }>;
+}
+export declare class UnitTransactions implements UnitTransaction {
+    private readonly options;
+    private readonly prepared;
+    private readonly commits;
+    private readonly now;
+    constructor(options: UnitTransactionOptions);
+    private unitId;
+    private snapshot;
+    prepare(plan: UnitPlan): Promise<{
+        ok: true;
+        prepared: {
+            unitId: string;
+            planDigest: string;
+        };
+        code?: never;
+        message?: never;
+    } | {
+        ok: false;
+        code: "unit-conflict";
+        message: string;
+        prepared?: never;
+    }>;
+    commit(prepared: UnitPrepared, options?: {
+        signal?: AbortSignal;
+    }): Promise<{
+        ok: true;
+        evidence: UnitEvidenceRecord;
+    } | UnitFailure>;
+    private commitOnce;
+    verify(ref: {
+        unitId: string;
+    } | {
+        runId: string;
+    }): Promise<UnitEvidenceRecord | UnitEvidenceRecord[] | null>;
+    finalize(unitId: string): Promise<{
+        ok: true;
+        evidence: UnitEvidenceRecord;
+        code?: never;
+        message?: never;
+    } | {
+        ok: false;
+        code: "unit-rollback-blocked";
+        message: string;
+        evidence?: never;
+    }>;
+    rollForward(unitId: string): Promise<{
+        ok: true;
+        evidence: UnitEvidenceRecord;
+        code?: never;
+        message?: never;
+    } | {
+        ok: false;
+        code: "unit-rollback-blocked";
+        message: string;
+        evidence?: never;
+    }>;
+    rollback(ref: {
+        unitId: string;
+        reason: string;
+    }): Promise<{
+        ok: false;
+        code: "unit-committed";
+        message: string;
+        evidence?: never;
+    } | {
+        ok: false;
+        code: "unit-rollback-blocked";
+        message: string;
+        evidence?: never;
+    } | {
+        ok: false;
+        code: "unit-fence-failed";
+        message: string;
+        evidence?: never;
+    } | {
+        ok: true;
+        evidence: UnitEvidenceRecord;
+        code?: never;
+        message?: never;
+    }>;
+    cancel(unitId: string, reason: string): Promise<{
+        ok: boolean;
+        phase: "none";
+    } | {
+        ok: boolean;
+        phase: "target-pending" | "target-written" | "source-archiving" | "sources-archived";
+    } | {
+        ok: boolean;
+        phase: "prepared" | "support-pending" | "committed" | "failed" | "rolled-back";
+    }>;
+}
+//# sourceMappingURL=unit-transaction.d.ts.map