ushman-ledger 0.3.0

package/dist/list.js

@@ -0,0 +1,139 @@
+import { mapWithConcurrencyLimit } from "./async.js";
+import { matchesReadIndexFilter, } from "./read-index.js";
+import { loadLedgerState } from "./recovery.js";
+import { parseLedgerEntry } from "./schema/entry.js";
+import { readPhaseEntryText } from "./storage/filesystem.js";
+const matchesFilter = (entry, filter) => {
+    if (filter.kind && entry.kind !== filter.kind) {
+        return false;
+    }
+    if (filter.phase && entry.phase !== filter.phase) {
+        return false;
+    }
+    if (filter.since && entry.ts < filter.since) {
+        return false;
+    }
+    return true;
+};
+const ENTRY_READ_BATCH_SIZE = 32;
+const ENTRY_READ_CONCURRENCY = 16;
+const getFilteredReadIndexEntries = ({ direction, filter, manifest, readIndex, }) => {
+    const sourceEntries = direction === 'asc' ? readIndex.entries : [...readIndex.entries].reverse();
+    const filteredEntries = [];
+    for (const readIndexEntry of sourceEntries) {
+        if (!matchesReadIndexFilter({
+            filter,
+            manifest,
+            readIndexEntry,
+        })) {
+            continue;
+        }
+        filteredEntries.push(readIndexEntry);
+        if (direction === 'desc' && filter.limit && filteredEntries.length === filter.limit) {
+            break;
+        }
+    }
+    return filteredEntries;
+};
+export const getOrderedEntryLocations = (manifest, readIndex, filter, direction = 'asc') => {
+    return getFilteredReadIndexEntries({
+        direction,
+        filter,
+        manifest,
+        readIndex,
+    })
+        .map((readIndexEntry) => {
+        const location = manifest.entryLocations[readIndexEntry.id];
+        if (!location) {
+            return null;
+        }
+        return [readIndexEntry.id, location];
+    })
+        .filter((entryLocation) => entryLocation !== null);
+};
+const readManifestEntry = async ({ allowMissing, entryId, location, workspaceRoot, }) => {
+    try {
+        const text = await readPhaseEntryText(workspaceRoot, location.phase, `${entryId}.json`);
+        return {
+            entry: parseLedgerEntry(JSON.parse(text)),
+            entryId,
+            location,
+        };
+    }
+    catch (error) {
+        if (allowMissing && error.code === 'ENOENT') {
+            return {
+                entry: null,
+                entryId,
+                location,
+            };
+        }
+        throw error;
+    }
+};
+export const readManifestEntryBatch = async ({ allowMissing = false, entryLocations, workspaceRoot, }) => mapWithConcurrencyLimit(entryLocations, ENTRY_READ_CONCURRENCY, async ([entryId, location]) => readManifestEntry({
+    allowMissing,
+    entryId,
+    location,
+    workspaceRoot,
+}));
+const collectLimitedEntries = async ({ filter, manifest, readIndex, workspaceRoot, }) => {
+    const collectedEntries = [];
+    const orderedEntries = getOrderedEntryLocations(manifest, readIndex, filter, 'desc');
+    const limit = filter.limit ?? 0;
+    for (let index = 0; index < orderedEntries.length && collectedEntries.length < limit; index += ENTRY_READ_BATCH_SIZE) {
+        const batch = orderedEntries.slice(index, index + ENTRY_READ_BATCH_SIZE);
+        const resolvedEntries = await readManifestEntryBatch({
+            entryLocations: batch,
+            workspaceRoot,
+        });
+        for (const resolvedEntry of resolvedEntries) {
+            if (!resolvedEntry.entry) {
+                continue;
+            }
+            if (matchesFilter(resolvedEntry.entry, filter)) {
+                collectedEntries.push(resolvedEntry.entry);
+            }
+            if (collectedEntries.length === limit) {
+                break;
+            }
+        }
+    }
+    collectedEntries.reverse();
+    return collectedEntries;
+};
+export const iterateEntriesFromManifest = async function* (workspaceRoot, manifest, readIndex, filter = {}) {
+    if (filter.limit) {
+        for (const entry of await collectLimitedEntries({ filter, manifest, readIndex, workspaceRoot })) {
+            yield entry;
+        }
+        return;
+    }
+    const orderedEntries = getOrderedEntryLocations(manifest, readIndex, filter);
+    for (let index = 0; index < orderedEntries.length; index += ENTRY_READ_BATCH_SIZE) {
+        const batch = orderedEntries.slice(index, index + ENTRY_READ_BATCH_SIZE);
+        const resolvedEntries = await readManifestEntryBatch({
+            entryLocations: batch,
+            workspaceRoot,
+        });
+        for (const resolvedEntry of resolvedEntries) {
+            if (!resolvedEntry.entry) {
+                continue;
+            }
+            if (matchesFilter(resolvedEntry.entry, filter)) {
+                yield resolvedEntry.entry;
+            }
+        }
+    }
+};
+export const listEntries = async function* (workspaceRoot, filter = {}) {
+    const { manifest, readIndex } = await loadLedgerState(workspaceRoot);
+    yield* iterateEntriesFromManifest(workspaceRoot, manifest, readIndex, filter);
+};
+export const readAllEntries = async (workspaceRoot, filter = {}) => {
+    const entries = [];
+    for await (const entry of listEntries(workspaceRoot, filter)) {
+        entries.push(entry);
+    }
+    return entries;
+};

package/dist/manifest-update.d.ts

@@ -0,0 +1,13 @@
+import type { LedgerEntry } from './schema/entry.ts';
+import type { LedgerArchiveMetadata, LedgerManifest } from './schema/manifest.ts';
+export declare const getNextManifestSequence: (lastSequence: number) => number;
+export declare const updateManifestForEntry: ({ entry, logicalHash, manifest, }: {
+    readonly entry: LedgerEntry;
+    readonly logicalHash: string;
+    readonly manifest: LedgerManifest;
+}) => LedgerManifest;
+export declare const updateManifestForArchive: ({ archive, manifest, }: {
+    readonly archive: LedgerArchiveMetadata;
+    readonly manifest: LedgerManifest;
+}) => LedgerManifest;
+//# sourceMappingURL=manifest-update.d.ts.map

package/dist/manifest-update.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest-update.d.ts","sourceRoot":"","sources":["../src/manifest-update.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,qBAAqB,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAElF,eAAO,MAAM,uBAAuB,GAAI,cAAc,MAAM,WAQ3D,CAAC;AAEF,eAAO,MAAM,sBAAsB,GAAI,mCAIpC;IACC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;CACrC,KAAG,cA6BH,CAAC;AAEF,eAAO,MAAM,wBAAwB,GAAI,wBAGtC;IACC,QAAQ,CAAC,OAAO,EAAE,qBAAqB,CAAC;IACxC,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;CACrC,KAAG,cAGF,CAAC"}

package/dist/manifest-update.js

@@ -0,0 +1,43 @@
+export const getNextManifestSequence = (lastSequence) => {
+    if (!Number.isSafeInteger(lastSequence) || lastSequence < 0) {
+        throw new Error(`Invalid ledger sequence counter: ${lastSequence}.`);
+    }
+    if (lastSequence >= Number.MAX_SAFE_INTEGER) {
+        throw new Error('Ledger sequence counter exceeded Number.MAX_SAFE_INTEGER.');
+    }
+    return lastSequence + 1;
+};
+export const updateManifestForEntry = ({ entry, logicalHash, manifest, }) => {
+    const nextSequence = getNextManifestSequence(manifest.lastSequence);
+    return {
+        ...manifest,
+        entryCount: manifest.entryCount + 1,
+        entryLocations: {
+            ...manifest.entryLocations,
+            [entry.id]: {
+                phase: entry.phase,
+                sequence: nextSequence,
+            },
+        },
+        idempotencyIndex: {
+            ...manifest.idempotencyIndex,
+            [entry.phase]: {
+                ...(manifest.idempotencyIndex[entry.phase] ?? {}),
+                [logicalHash]: entry.id,
+            },
+        },
+        lastSequence: nextSequence,
+        perPhaseCounts: {
+            ...manifest.perPhaseCounts,
+            [entry.phase]: (manifest.perPhaseCounts[entry.phase] ?? 0) + 1,
+        },
+        perPhaseLatest: {
+            ...manifest.perPhaseLatest,
+            [entry.phase]: entry.id,
+        },
+    };
+};
+export const updateManifestForArchive = ({ archive, manifest, }) => ({
+    ...manifest,
+    archives: [...manifest.archives, archive],
+});

package/dist/note.d.ts

@@ -0,0 +1,13 @@
+import { appendRecord } from './record.ts';
+import type { LedgerPhase } from './schema/entry.ts';
+import type { NoteSubkind } from './schema/note.ts';
+export type NoteBody = {
+    readonly body: string;
+    readonly phase: LedgerPhase;
+    readonly summary: string;
+};
+export declare const appendNote: (workspaceRoot: string, subkind: NoteSubkind, noteBody: NoteBody) => Promise<{
+    entry: Awaited<ReturnType<typeof appendRecord>>["entry"];
+    id: string;
+}>;
+//# sourceMappingURL=note.d.ts.map

package/dist/note.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"note.d.ts","sourceRoot":"","sources":["../src/note.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAGpD,MAAM,MAAM,QAAQ,GAAG;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC5B,CAAC;AAEF,eAAO,MAAM,UAAU,GACnB,eAAe,MAAM,EACrB,SAAS,WAAW,EACpB,UAAU,QAAQ,KACnB,OAAO,CAAC;IAAE,KAAK,EAAE,OAAO,CAAC,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAYlF,CAAC"}

package/dist/note.js

@@ -0,0 +1,15 @@
+import { appendRecord } from "./record.js";
+import { LEDGER_LIBRARY_VERSION } from "./version.js";
+export const appendNote = async (workspaceRoot, subkind, noteBody) => {
+    return appendRecord(workspaceRoot, {
+        body: noteBody.body,
+        emitter: {
+            tool: 'ushman-ledger',
+            version: LEDGER_LIBRARY_VERSION,
+        },
+        kind: 'note',
+        phase: noteBody.phase,
+        subkind,
+        summary: noteBody.summary,
+    });
+};

package/dist/patch-metadata.d.ts

@@ -0,0 +1,37 @@
+type ParsedPatchLine = {
+    readonly kind: 'add' | 'context' | 'remove';
+    readonly value: string;
+};
+type ParsedPatchHunk = {
+    readonly endLine: number;
+    readonly lines: readonly ParsedPatchLine[];
+    readonly newCount: number;
+    readonly newStart: number;
+    readonly oldCount: number;
+    readonly oldStart: number;
+    readonly startLine: number;
+};
+type ParsedPatchFile = {
+    readonly hunks: readonly ParsedPatchHunk[];
+    readonly newPath: string | null;
+    readonly oldPath: string | null;
+    readonly path: string;
+};
+export declare const parseStructuredPatch: (patchText: string) => ParsedPatchFile[];
+export declare const derivePatchPayloadFromDiffText: ({ patchText, workspaceRoot, }: {
+    readonly patchText: string;
+    readonly workspaceRoot: string;
+}) => Promise<{
+    diff: string;
+    diffSha256: string;
+    fileSha256After: Record<string, string>;
+    fileSha256Before: Record<string, string>;
+    hunks: {
+        endLine: number;
+        path: string;
+        startLine: number;
+    }[];
+    touchedPaths: string[];
+}>;
+export {};
+//# sourceMappingURL=patch-metadata.d.ts.map

package/dist/patch-metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"patch-metadata.d.ts","sourceRoot":"","sources":["../src/patch-metadata.ts"],"names":[],"mappings":"AAMA,KAAK,eAAe,GAAG;IACnB,QAAQ,CAAC,IAAI,EAAE,KAAK,GAAG,SAAS,GAAG,QAAQ,CAAC;IAC5C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEF,KAAK,eAAe,GAAG;IACnB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,SAAS,eAAe,EAAE,CAAC;IAC3C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC9B,CAAC;AAEF,KAAK,eAAe,GAAG;IACnB,QAAQ,CAAC,KAAK,EAAE,SAAS,eAAe,EAAE,CAAC;IAC3C,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACzB,CAAC;AA0IF,eAAO,MAAM,oBAAoB,GAAI,WAAW,MAAM,sBA6DrD,CAAC;AAwLF,eAAO,MAAM,8BAA8B,GAAU,+BAGlD;IACC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAClC;;;;;;;;;;;EA2BA,CAAC"}

package/dist/patch-metadata.js

@@ -0,0 +1,300 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { sha256Hex } from "./json.js";
+const EMPTY_FILE_SHA256 = sha256Hex('');
+const toWorkspaceRelativePath = (value) => value.replaceAll('\\', '/').replace(/^[ab]\//u, '');
+const resolvePatchPath = (value) => {
+    if (!value || value === '/dev/null') {
+        return null;
+    }
+    return toWorkspaceRelativePath(value);
+};
+const parseHunkHeader = (line) => {
+    const match = /^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/u.exec(line);
+    if (!match) {
+        return null;
+    }
+    const oldStart = Number.parseInt(match[1], 10);
+    const oldCount = Number.parseInt(match[2] ?? '1', 10);
+    const newStart = Number.parseInt(match[3], 10);
+    const newCount = Number.parseInt(match[4] ?? '1', 10);
+    const startLine = Math.max(1, newCount > 0 ? newStart : oldStart);
+    const endLine = Math.max(startLine, startLine + Math.max(newCount, 1) - 1);
+    return {
+        endLine,
+        newCount,
+        newStart,
+        oldCount,
+        oldStart,
+        startLine,
+    };
+};
+const splitPatchLines = (patchText) => patchText.replace(/\r\n/gu, '\n').split('\n');
+const finalizeParsedPatchFile = (value) => {
+    if (value.sawMalformedPatchLines) {
+        throw new Error('Patch payload derivation requires valid unified diff hunks for every changed text block.');
+    }
+    const resolvedPath = value.newPath ?? value.oldPath;
+    if (!resolvedPath) {
+        return null;
+    }
+    return {
+        hunks: value.hunks,
+        newPath: value.newPath,
+        oldPath: value.oldPath,
+        path: resolvedPath,
+    };
+};
+const createMutablePatchFile = (diffMatch) => ({
+    hunks: [],
+    newPath: toWorkspaceRelativePath(diffMatch[2]),
+    oldPath: toWorkspaceRelativePath(diffMatch[1]),
+    sawMalformedPatchLines: false,
+});
+const applyPatchMetadataLine = ({ currentFile, line, }) => {
+    if (line.startsWith('--- ')) {
+        currentFile.oldPath = resolvePatchPath(line.slice(4).trim());
+        return true;
+    }
+    if (line.startsWith('+++ ')) {
+        currentFile.newPath = resolvePatchPath(line.slice(4).trim());
+        return true;
+    }
+    return false;
+};
+const createMutablePatchHunk = (line) => {
+    const parsedHeader = parseHunkHeader(line);
+    if (!parsedHeader) {
+        return null;
+    }
+    return {
+        ...parsedHeader,
+        lines: [],
+    };
+};
+const appendHunkLine = ({ currentHunk, line, }) => {
+    if (!currentHunk || line.startsWith('\')) {
+        return;
+    }
+    if (line.startsWith('+')) {
+        currentHunk.lines.push({ kind: 'add', value: line.slice(1) });
+        return;
+    }
+    if (line.startsWith('-')) {
+        currentHunk.lines.push({ kind: 'remove', value: line.slice(1) });
+        return;
+    }
+    if (line.startsWith(' ')) {
+        currentHunk.lines.push({ kind: 'context', value: line.slice(1) });
+    }
+};
+export const parseStructuredPatch = (patchText) => {
+    const lines = splitPatchLines(patchText);
+    const files = [];
+    let currentFile = null;
+    let currentHunk = null;
+    const flushHunk = () => {
+        if (!currentFile || !currentHunk) {
+            return;
+        }
+        currentFile.hunks.push({
+            ...currentHunk,
+            lines: [...currentHunk.lines],
+        });
+        currentHunk = null;
+    };
+    const flushFile = () => {
+        flushHunk();
+        if (!currentFile) {
+            return;
+        }
+        const parsedFile = finalizeParsedPatchFile(currentFile);
+        if (parsedFile) {
+            files.push(parsedFile);
+        }
+        currentFile = null;
+    };
+    for (const line of lines) {
+        const diffMatch = /^diff --git a\/(.+?) b\/(.+)$/u.exec(line);
+        if (diffMatch) {
+            flushFile();
+            currentFile = createMutablePatchFile(diffMatch);
+            continue;
+        }
+        if (!currentFile) {
+            continue;
+        }
+        if (applyPatchMetadataLine({ currentFile, line })) {
+            continue;
+        }
+        const nextHunk = createMutablePatchHunk(line);
+        if (nextHunk) {
+            flushHunk();
+            currentHunk = nextHunk;
+            continue;
+        }
+        if (line.startsWith('@@')) {
+            currentFile.sawMalformedPatchLines = true;
+            continue;
+        }
+        appendHunkLine({ currentHunk, line });
+    }
+    flushFile();
+    return files;
+};
+const splitTextSnapshot = (text) => {
+    if (text.length === 0) {
+        return {
+            hasTrailingNewline: false,
+            lines: [],
+        };
+    }
+    const hasTrailingNewline = text.endsWith('\n');
+    const lines = text.replace(/\r\n/gu, '\n').split('\n');
+    if (hasTrailingNewline) {
+        lines.pop();
+    }
+    return {
+        hasTrailingNewline,
+        lines,
+    };
+};
+const joinTextSnapshot = (snapshot) => {
+    if (snapshot.lines.length === 0) {
+        return '';
+    }
+    return `${snapshot.lines.join('\n')}${snapshot.hasTrailingNewline ? '\n' : ''}`;
+};
+const buildExpectedAfterSegment = (lines) => lines.filter((line) => line.kind !== 'remove').map((line) => line.value);
+const buildExpectedBeforeSegment = (lines) => lines.filter((line) => line.kind !== 'add').map((line) => line.value);
+const segmentsEqual = (left, right) => left.length === right.length && left.every((value, index) => value === right[index]);
+const reconstructBeforeText = ({ afterText, file }) => {
+    const snapshot = splitTextSnapshot(afterText);
+    const lines = [...snapshot.lines];
+    for (const hunk of [...file.hunks].reverse()) {
+        const afterSegment = buildExpectedAfterSegment(hunk.lines);
+        const beforeSegment = buildExpectedBeforeSegment(hunk.lines);
+        const startIndex = Math.max(0, hunk.newStart - 1);
+        const actualAfterSegment = lines.slice(startIndex, startIndex + afterSegment.length);
+        if (!segmentsEqual(actualAfterSegment, afterSegment)) {
+            throw new Error(`Patch hunk did not match the current workspace content for ${file.path} at line ${hunk.startLine}.`);
+        }
+        lines.splice(startIndex, afterSegment.length, ...beforeSegment);
+    }
+    return joinTextSnapshot({
+        hasTrailingNewline: snapshot.hasTrailingNewline,
+        lines,
+    });
+};
+const reconstructAfterText = ({ beforeText, file, }) => {
+    const snapshot = splitTextSnapshot(beforeText);
+    const lines = [...snapshot.lines];
+    for (const hunk of file.hunks) {
+        const beforeSegment = buildExpectedBeforeSegment(hunk.lines);
+        const afterSegment = buildExpectedAfterSegment(hunk.lines);
+        const startIndex = Math.max(0, hunk.oldStart - 1);
+        const actualBeforeSegment = lines.slice(startIndex, startIndex + beforeSegment.length);
+        if (!segmentsEqual(actualBeforeSegment, beforeSegment)) {
+            throw new Error(`Patch hunk did not match the expected preimage content for ${file.path} at line ${hunk.startLine}.`);
+        }
+        lines.splice(startIndex, beforeSegment.length, ...afterSegment);
+    }
+    return joinTextSnapshot({
+        hasTrailingNewline: snapshot.hasTrailingNewline,
+        lines,
+    });
+};
+const isMissingPathError = (error) => error.code === 'ENOENT';
+const readWorkspacePatchTarget = async ({ workspaceFilePath }) => {
+    try {
+        return {
+            exists: true,
+            text: await readFile(workspaceFilePath, 'utf8'),
+        };
+    }
+    catch (error) {
+        if (!isMissingPathError(error)) {
+            throw error;
+        }
+        return {
+            exists: false,
+            text: '',
+        };
+    }
+};
+const resolvePatchTextPair = ({ file, workspaceAfterText, workspaceFileExists, }) => {
+    if (file.hunks.length === 0) {
+        return {
+            afterText: workspaceAfterText,
+            beforeText: workspaceAfterText,
+        };
+    }
+    try {
+        return {
+            afterText: workspaceAfterText,
+            beforeText: reconstructBeforeText({
+                afterText: workspaceAfterText,
+                file,
+            }),
+        };
+    }
+    catch (error) {
+        const synthesizedAfterText = reconstructAfterText({
+            beforeText: '',
+            file,
+        });
+        const isNewFilePatch = !workspaceFileExists || workspaceAfterText === synthesizedAfterText;
+        if (!isNewFilePatch) {
+            throw new Error(`Patch payload derivation expected ${file.path} to match the diff postimage or be absent: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        return {
+            afterText: synthesizedAfterText,
+            beforeText: '',
+        };
+    }
+};
+const buildHashMaps = async ({ files, workspaceRoot, }) => {
+    const fileSha256After = {};
+    const fileSha256Before = {};
+    for (const file of files) {
+        const workspaceFilePath = path.join(workspaceRoot, file.path);
+        const workspacePatchTarget = await readWorkspacePatchTarget({
+            workspaceFilePath,
+        });
+        const { afterText, beforeText } = resolvePatchTextPair({
+            file,
+            workspaceAfterText: workspacePatchTarget.text,
+            workspaceFileExists: workspacePatchTarget.exists,
+        });
+        fileSha256After[file.path] = afterText.length > 0 ? sha256Hex(afterText) : EMPTY_FILE_SHA256;
+        fileSha256Before[file.path] = beforeText.length > 0 ? sha256Hex(beforeText) : EMPTY_FILE_SHA256;
+    }
+    return {
+        fileSha256After,
+        fileSha256Before,
+    };
+};
+export const derivePatchPayloadFromDiffText = async ({ patchText, workspaceRoot, }) => {
+    const files = parseStructuredPatch(patchText);
+    if (files.length === 0) {
+        throw new Error('Patch payload derivation requires at least one unified diff file block.');
+    }
+    const hunks = files.flatMap((file) => file.hunks.map((hunk) => ({
+        endLine: hunk.endLine,
+        path: file.path,
+        startLine: hunk.startLine,
+    })));
+    const touchedPaths = [...new Set(files.map((file) => file.path))];
+    const { fileSha256After, fileSha256Before } = await buildHashMaps({
+        files,
+        workspaceRoot,
+    });
+    return {
+        diff: patchText,
+        diffSha256: sha256Hex(patchText),
+        fileSha256After,
+        fileSha256Before,
+        hunks,
+        touchedPaths,
+    };
+};