dsh-hashline-edit 0.1.1 → 0.2.0

package/lib/types/src/apply-patch/resolve.d.ts

@@ -0,0 +1,129 @@
+/**
+ * apply_patch v4 — resolution layer.
+ *
+ * Two addressing families meet here:
+ *
+ * - **fragment mode** is content matching against the pre-call baseline. The
+ *   `oldLines` sequence (' ' and '-' lines) must match exactly one place in the
+ *   hunk's window; `@@ <context>` must itself match exactly one line and moves
+ *   the window start after it. Zero or multiple hits reject with candidate rows.
+ * - **identity mode** is served-lease addressing. Both anchors must belong to
+ *   the `(session, file, anchor)` served set; a missing, retired or foreign
+ *   anchor rejects with the file's current rows served back.
+ *
+ * The layer is pure over `FileBaseline` + served anchors: no I/O, no store
+ * access. `plan.ts` supplies the baselines and the lease source.
+ *
+ * @module dsh-hashline-edit/apply-patch/resolve
+ */
+import { type LeaseSpanSource } from "../hashline/resolve.js";
+import type { Anchor, FileBaseline, FragmentHunk, IdentityHunk, LineRange, PatchCandidate, PatchPath, PatchProblem, PlannedMutation, PlannedReferenceUse, ReferenceHunk } from "./types.js";
+/** A file's served anchors, parallel to its baseline lines; `null` = never served. */
+export type ServedAnchors = readonly (string | null)[];
+/** The inputs one hunk resolution reads. */
+export interface ResolveContext {
+    readonly baseline: FileBaseline;
+    readonly served: ServedAnchors;
+    /**
+     * Read-only lease identity source for identity mode. When present it is
+     * authoritative (MVCC lease identity, including rebasing); the `served`
+     * mirror is only the fallback for tests/callers with no store lease view.
+     */
+    readonly identity?: LeaseSpanSource;
+    /**
+     * Session-wide anchor homes — other files that served this anchor. Used only
+     * to diagnose a foreign anchor; a cross-file anchor is refused either way.
+     */
+    readonly homesOf?: (anchor: Anchor) => readonly PatchPath[];
+}
+/** A successful fragment match in baseline coordinates. */
+export interface FragmentMatch {
+    /** Inclusive range covering the hunk's oldLines (' ' + '-'); zero-width when oldLines is empty. */
+    readonly range: LineRange;
+    /** 1-based line where the search window began (after `@@ <context>`, else 1). */
+    readonly windowStart: number;
+}
+/** Fragment match failure: no occurrence or more than one, with candidate rows. */
+export type FragmentMatchResult = {
+    readonly ok: true;
+    readonly match: FragmentMatch;
+} | {
+    readonly ok: false;
+    readonly reason: "no-match" | "ambiguous";
+    readonly candidates: readonly PatchCandidate[];
+};
+/** Identity resolution outcome. */
+export type IdentityResolveResult = {
+    readonly ok: true;
+    readonly range: LineRange;
+} | {
+    readonly ok: false;
+    readonly problems: readonly PatchProblem[];
+};
+/** Reference resolution outcome. */
+export type ReferenceResolveResult = {
+    readonly ok: true;
+    readonly reference: PlannedReferenceUse;
+    /** The destination replacement this reference materializes. */
+    readonly mutation: PlannedMutation;
+} | {
+    readonly ok: false;
+    readonly problems: readonly PatchProblem[];
+};
+/** The baseline's lines; an empty file is zero lines, never one empty line. */
+export declare function baselineLinesOf(baseline: FileBaseline): string[];
+/**
+ * Match one fragment hunk against its baseline.
+ *
+ * Byte-exact: no whitespace, Unicode or newline normalization. The window is
+ * `[windowStart, end]` and every subsequent hunk's window begins after the
+ * previous hunk's end (the planner enforces the monotonic cursor).
+ *
+ * @param hunk - the parsed fragment hunk.
+ * @param context - baseline plus served anchors (served is unused here; kept for one call shape).
+ * @param windowStart - 1-based line the search starts at; defaults to 1.
+ * @returns the unique match or the rejection with candidates.
+ */
+export declare function matchFragmentHunk(hunk: FragmentHunk, context: ResolveContext, windowStart?: number): FragmentMatchResult;
+/**
+ * Resolve one identity hunk (`@@<a>` / `@@<a>-<b>`) against the served set.
+ *
+ * The anchors must be present in `context.served` at exactly one position each
+ * (or hold a live lease when `context.identity` is present), `from` not after
+ * `to`. Every failure uses `E_STALE_ANCHOR` with the anchor named, so the
+ * planner can serve the file's current rows for a retry.
+ *
+ * @param hunk - the parsed identity hunk.
+ * @param context - baseline plus served anchors / lease source.
+ * @returns the resolved inclusive range, or all problems for this hunk.
+ */
+export declare function resolveIdentityHunk(hunk: IdentityHunk, context: ResolveContext): IdentityResolveResult;
+/**
+ * Resolve one `*** Copy From:` / `*** Cut From:` hunk.
+ *
+ * The target addressing must be identity mode (`@@<a>` / `@@<a>-<b>`): a
+ * fragment-mode reference hunk is refused with `E_PATCH_SYNTAX` at the
+ * reference line. The source span must be served for the declared source file;
+ * the destination is replaced by the source bytes. A `cut` also plans the
+ * source retirement, in the same transaction, as a deletion over the same
+ * anchors.
+ *
+ * @param hunk - the parsed reference hunk.
+ * @param destination - the target file's baseline + served anchors / lease source.
+ * @param source - the source file's baseline + served anchors / lease source.
+ * @returns the materialized reference and destination mutation, or the problems.
+ */
+export declare function resolveReferenceHunk(hunk: ReferenceHunk, destination: ResolveContext, source: ResolveContext | FileBaseline, sourceServed?: ServedAnchors): ReferenceResolveResult;
+/**
+ * Check one file's resolved mutations for overlap.
+ *
+ * Two mutations whose target ranges intersect reject the whole call with
+ * `E_BATCH_ABORT`-shaped evidence (both patch lines named). Zero-width
+ * insertions at the same point are ordered by submission, not treated as
+ * overlap; every other intersection is a rejection.
+ *
+ * @param mutations - one file's mutations, in submission order.
+ * @param path - the target file for the problem's path field.
+ * @returns every overlap problem found (empty when disjoint).
+ */
+export declare function checkMutationOverlaps(mutations: readonly PlannedMutation[], path?: PatchPath): readonly PatchProblem[];

package/lib/types/src/apply-patch/tool.d.ts

@@ -0,0 +1,54 @@
+/**
+ * apply_patch v4 — tool use case.
+ *
+ * The deep module the dsh host adapter calls. One `execute` owns the whole pipeline for one call:
+ *
+ *   grammar.parseApplyPatch → plan.planApplyPatch → commit.commitPlan → render
+ *
+ * and returns the model-facing `{ content, details }` envelope. A rejection carries the rendered
+ * `[E_*]` envelope and is marked `isError`; nothing was written because plan/grammar own every
+ * pre-commit check and commit rolls back or reports its recovery report.
+ *
+ * The orchestration deps are injectable so the transaction lane can test the complete
+ * parse→plan→commit→render path before the grammar/resolve lanes merge into this branch.
+ *
+ * @module dsh-hashline-edit/apply-patch/tool
+ */
+import { parseApplyPatch, type ParsePatchOptions } from "./grammar.js";
+import { planApplyPatch, type PlanApplyPatchOptions } from "./plan.js";
+import { type CommitPlanOptions, type CommitPlanResult } from "./commit.js";
+import { renderFailure, renderSuccess } from "./render.js";
+import type { ApplyPatchContext, ApplyPatchToolResult, PatchPlan, PlanPatchResult } from "./types.js";
+/** The registered tool name; `apply_patch` is the only mutation entry point. */
+export declare const APPLY_PATCH_TOOL_NAME = "apply_patch";
+/** The use-case seam: one narrow interface over the pipeline. */
+export interface ApplyPatchTool {
+    /**
+     * Execute one apply_patch call.
+     * @param input - the raw patch text.
+     * @param ctx - live cwd, session identity and cancellation.
+     * @returns the model-facing envelope; `isError` marks a rejection (nothing written).
+     */
+    execute(input: string, ctx: ApplyPatchContext): Promise<ApplyPatchToolResult>;
+    /**
+     * Parse + plan without writing, for previews and tests.
+     * @param input - the raw patch text.
+     * @param ctx - live cwd, session identity and cancellation.
+     * @returns the plan or every collected problem.
+     */
+    plan(input: string, ctx: ApplyPatchContext): Promise<PlanPatchResult>;
+}
+/** The injectable seams of the pipeline; production uses the real modules. */
+export interface ApplyPatchToolDeps {
+    readonly parse?: (input: string, options?: ParsePatchOptions) => ReturnType<typeof parseApplyPatch>;
+    readonly plan?: (document: Parameters<typeof planApplyPatch>[0], options: PlanApplyPatchOptions) => ReturnType<typeof planApplyPatch>;
+    readonly commit?: (plan: PatchPlan, options: CommitPlanOptions) => Promise<CommitPlanResult>;
+    readonly renderSuccess?: typeof renderSuccess;
+    readonly renderFailure?: typeof renderFailure;
+}
+/**
+ * Build the apply_patch use case.
+ * @param deps - optional seam overrides; production binds the real modules.
+ * @returns the tool seam bound to the real hashline engine and store.
+ */
+export declare function createApplyPatchTool(deps?: ApplyPatchToolDeps): ApplyPatchTool;

package/lib/types/src/apply-patch/types.d.ts

@@ -0,0 +1,362 @@
+/**
+ * apply_patch v4 — shared contract types.
+ *
+ * This module is the frozen vocabulary every apply-patch lane compiles against:
+ *
+ * - the **patch AST** the grammar layer produces (`PatchDocument`),
+ * - the **plan IR** the planner produces and the transaction layer commits
+ *   (`PatchPlan`, `PlannedFile`, `PlannedMutation`),
+ * - the **result / error** types the renderer and the host adapter consume.
+ *
+ * The engine underneath is the existing hashline kernel: content-addressed 4-char
+ * anchors, served leases, MVCC snapshots, correlated multi-file transactions and
+ * the undo store. Nothing here re-declares those primitives; the plan IR only
+ * adds the addressing and lifecycle vocabulary apply_patch needs.
+ *
+ * Vocabulary (see GLOSSARY.md): anchor, served row, lease, fragment hunk,
+ * identity hunk, reference hunk, patch line, plan.
+ *
+ * @module dsh-hashline-edit/apply-patch/types
+ */
+import type { DomainErrorCode, ServedRow } from "../domain-errors.js";
+import type { LineEnding } from "../edit-diff.js";
+import type { HashStore } from "../hash-store.js";
+import type { TransactionRecoveryReport } from "../mutation-engine/types.js";
+/** Patch AST (grammar layer output). */
+/** A 4-character anchor: `[A-Za-z0-9]{4}` (the hashline alphabet). */
+export type Anchor = string;
+/** A 1-based line number in the submitted patch text, used by every diagnostic. */
+export type PatchLineNumber = number;
+/** A path exactly as written in the patch: workspace-relative or workspace-absolute. */
+export type PatchPath = string;
+/** A closed anchor span; both anchors must have been served for the same file. */
+export interface AnchorSpan {
+    readonly from: Anchor;
+    readonly to: Anchor;
+}
+/** One parsed `*** Begin Patch` … `*** End Patch` document. */
+export interface PatchDocument {
+    /** File operations in submission order. */
+    readonly files: readonly PatchFileOp[];
+    /** Total number of lines in the input (1-based diagnostics may point at EOF). */
+    readonly lineCount: number;
+}
+export type PatchFileOp = AddFileOp | DeleteFileOp | UpdateFileOp;
+/** `*** Add File: <path>` — every following line is a '+' content line. */
+export interface AddFileOp {
+    readonly kind: "add";
+    readonly path: PatchPath;
+    readonly headerLine: PatchLineNumber;
+    /** Content lines WITHOUT the leading '+', in file order. Empty means an empty file. */
+    readonly contentLines: readonly string[];
+}
+/** `*** Delete File: <path>` */
+export interface DeleteFileOp {
+    readonly kind: "delete";
+    readonly path: PatchPath;
+    readonly headerLine: PatchLineNumber;
+}
+/** `*** Update File: <path>` with its optional `*** Move to:` and zero or more hunks. */
+export interface UpdateFileOp {
+    readonly kind: "update";
+    readonly path: PatchPath;
+    readonly headerLine: PatchLineNumber;
+    /** `*** Move to: <path>`; the parser only accepts it directly after the update header. */
+    readonly moveTo?: MoveDirective;
+    /** Hunks in submission order; each hunk's window starts after the previous hunk's end. */
+    readonly hunks: readonly PatchHunk[];
+}
+/** `*** Move to: <path>` */
+export interface MoveDirective {
+    readonly path: PatchPath;
+    readonly line: PatchLineNumber;
+}
+export type PatchHunk = FragmentHunk | IdentityHunk | ReferenceHunk;
+/**
+ * The addressing a hunk opens with.
+ *
+ * `start` is the bare `@@` (fragment mode, search from the file start);
+ * `context` is `@@ <line>` (fragment mode, search window starts after that
+ * line's unique hit); `anchors` is `@@<a>` / `@@<a>-<b>` (identity mode).
+ */
+export type HunkAddress = {
+    readonly kind: "start";
+} | {
+    readonly kind: "context";
+    readonly text: string;
+} | {
+    readonly kind: "anchors";
+    readonly span: AnchorSpan;
+};
+/** A context/line matcher hunk: `@@` or `@@ <context>` followed by ' '/'+'/'-' lines. */
+export interface FragmentHunk {
+    readonly kind: "fragment";
+    /** Grammar guarantees this is `start` or `context`; `anchors` never appears here. */
+    readonly address: HunkAddress;
+    readonly headerLine: PatchLineNumber;
+    /** Body lines, in submission order; at least one is required. */
+    readonly lines: readonly FragmentLine[];
+    /** `*** End of File` line number when the hunk is tail-pinned, absent otherwise. */
+    readonly endOfFile?: PatchLineNumber;
+}
+/** One body line of a fragment hunk. */
+export interface FragmentLine {
+    readonly op: "context" | "remove" | "add";
+    /** Line content without the leading marker (' ', '-', '+'). */
+    readonly text: string;
+    readonly line: PatchLineNumber;
+}
+/** An identity hunk: `@@<a>` / `@@<a>-<b>` followed by '+' lines only (empty body = delete). */
+export interface IdentityHunk {
+    readonly kind: "identity";
+    readonly span: AnchorSpan;
+    readonly headerLine: PatchLineNumber;
+    /** '+' lines without the marker; empty means the span is deleted. */
+    readonly addedLines: readonly string[];
+}
+/** A copy/cut hunk: the content comes from another file's served span; no body lines allowed. */
+export interface ReferenceHunk {
+    readonly kind: "reference";
+    /**
+     * The hunk's own addressing (`@@`, `@@ <context>`, `@@<a>` or `@@<a>-<b>`),
+     * which determines the destination position (see docs/apply-patch-v4-internals.md §4).
+     */
+    readonly address: HunkAddress;
+    readonly source: ReferenceSource;
+    readonly headerLine: PatchLineNumber;
+}
+/** `*** Copy From:` / `*** Cut From:` source span. */
+export interface ReferenceSource {
+    readonly mode: "copy" | "cut";
+    readonly path: PatchPath;
+    readonly span: AnchorSpan;
+    readonly line: PatchLineNumber;
+}
+/** Plan IR (planner output / transaction input). */
+/**
+ * An inclusive 1-based line range in a file's pre-call baseline.
+ *
+ * A zero-width insertion uses the engine's inverted convention:
+ * `startLine = point + 1` and `endLine = point` (insert after line `point`;
+ * point 0 inserts at the start of the file).
+ */
+export interface LineRange {
+    readonly startLine: number;
+    readonly endLine: number;
+}
+/** The file-lifecycle action planned for one target. */
+export type LifecyclePlan = {
+    readonly kind: "keep";
+} | {
+    readonly kind: "add";
+} | {
+    readonly kind: "delete";
+} | {
+    readonly kind: "move";
+    readonly to: PatchPath;
+    readonly toAbsolutePath: string;
+};
+/** One file's state at call time — the single baseline every mutation resolves against. */
+export interface FileBaseline {
+    /** The path as written in the patch. */
+    readonly path: PatchPath;
+    /** The resolved absolute path the engine reads/writes. */
+    readonly absolutePath: string;
+    /** LF-normalized text; `""` for an Add File target. */
+    readonly text: string;
+    /** 4-char anchors parallel to the file's lines; empty for an Add File target. */
+    readonly hashes: readonly string[];
+    /** Byte-order mark the file carried ("" when none). */
+    readonly bom: string;
+    /** The file's original line ending. */
+    readonly ending: LineEnding;
+    /** False for `*** Add File:` targets, true for every other existing target. */
+    readonly exists: boolean;
+}
+/** One resolved content mutation against `FileBaseline.text`, in baseline coordinates. */
+export interface PlannedMutation {
+    readonly kind: "replace" | "insert" | "delete";
+    readonly range: LineRange;
+    /** Replacement lines (LF-joined at commit); empty for `delete` and for an empty insertion. */
+    readonly lines: readonly string[];
+    /** The patch line that produced this mutation (diagnostics and ordering evidence). */
+    readonly patchLine: PatchLineNumber;
+}
+/** One Copy/Cut source span materialized from a baseline. */
+export interface PlannedReferenceUse {
+    readonly mode: "copy" | "cut";
+    readonly path: PatchPath;
+    readonly absolutePath: string;
+    readonly range: LineRange;
+    /** The source bytes, line-split and LF-normalized. */
+    readonly lines: readonly string[];
+    readonly patchLine: PatchLineNumber;
+}
+/** One file in the plan, with every mutation expressed against its own pre-call baseline. */
+export interface PlannedFile {
+    readonly path: PatchPath;
+    readonly absolutePath: string;
+    readonly lifecycle: LifecyclePlan;
+    readonly baseline: FileBaseline;
+    /** Non-overlapping mutations in baseline coordinates, ordered by `range.startLine`. */
+    readonly mutations: readonly PlannedMutation[];
+    /** Copy/Cut sources this target consumes. */
+    readonly references: readonly PlannedReferenceUse[];
+    /** True when committing this member changes bytes or the namespace. */
+    readonly writes: boolean;
+}
+/** The full plan one apply_patch call commits as one correlated transaction. */
+export interface PatchPlan {
+    /** Written members in commit order: the primary file leads, the rest follow deterministically. */
+    readonly files: readonly PlannedFile[];
+    /** Files read only as Copy/Cut sources (never written). */
+    readonly referenceFiles: readonly FileBaseline[];
+    readonly stats: PatchStats;
+}
+/** Aggregate line/file counts the success summary reports. */
+export interface PatchStats {
+    readonly filesChanged: number;
+    readonly addedLines: number;
+    readonly removedLines: number;
+}
+/** Result and error types. */
+/**
+ * The two error codes apply_patch adds to the shared registry.
+ *
+ * `E_STALE_ANCHOR` is NOT new: `src/domain-errors.ts` already registers it with
+ * the served-rows payload this feature reuses. The registry lane must add these
+ * two codes (payload + producer) before the surface lane registers the tool.
+ */
+export type ApplyPatchNewErrorCode = "E_PATCH_SYNTAX" | "E_UNIQUE_MATCH";
+/** Every code a patch problem may carry. */
+export type ApplyPatchErrorCode = DomainErrorCode | ApplyPatchNewErrorCode;
+/** One candidate row for an ambiguous fragment match, served back to the model. */
+export interface PatchCandidate {
+    /** 1-based line number in the baseline. */
+    readonly line: number;
+    readonly hash: Anchor;
+    readonly text: string;
+}
+/** One collectable problem in a rejection; every problem carries its patch line and code. */
+export interface PatchProblem {
+    readonly code: ApplyPatchErrorCode;
+    readonly patchLine: PatchLineNumber;
+    readonly path?: PatchPath;
+    readonly message: string;
+    /** Candidate rows when the failure is an ambiguous fragment match. */
+    readonly candidates?: readonly PatchCandidate[];
+    /** 1-based target line used to center the rejection serve window when known. */
+    readonly line?: number;
+}
+/** One file's current rows rendered `HASH│content` for reject-and-serve. */
+export interface ServedFileBlock {
+    readonly path: PatchPath;
+    readonly rows: readonly ServedRow[];
+    /** Rendered block, one `HASH│content` row per line. */
+    readonly text: string;
+}
+/** One file's lifecycle status and line counts in the success summary. */
+export interface AppliedFileSummary {
+    /** A = added, M = modified, R = renamed, D = deleted. */
+    readonly status: "A" | "M" | "R" | "D";
+    readonly path: PatchPath;
+    /** Original path for a rename (`R` only). */
+    readonly fromPath?: PatchPath;
+    readonly addedLines: number;
+    readonly removedLines: number;
+}
+/** Metrics one committed call reports (mirrors the existing RMetrics intent). */
+export interface PatchMetrics {
+    readonly files: number;
+    readonly hunks: number;
+    readonly addedLines: number;
+    readonly removedLines: number;
+    readonly durationMs?: number;
+}
+/** Successful apply_patch outcome. */
+export interface ApplyPatchSuccess {
+    readonly ok: true;
+    /** File-level summary, e.g. `Updated 2 files:\nA src/new.ts\nM src/a.ts`. */
+    readonly summary: string;
+    /** Annotated diff for the UI/details (never the model's primary text). */
+    readonly diff: string;
+    readonly files: readonly AppliedFileSummary[];
+    /** New anchors for every changed line, per file — the second call needs no read. */
+    readonly served: readonly ServedFileBlock[];
+    readonly warnings: readonly string[];
+    readonly metrics: PatchMetrics;
+}
+/** Rejected apply_patch outcome: one transaction, zero disk writes. */
+export interface ApplyPatchFailure {
+    readonly ok: false;
+    /** Primary code for the envelope; every problem still carries its own code. */
+    readonly code: ApplyPatchErrorCode;
+    readonly message: string;
+    /** Every independently diagnosable problem, in patch order. */
+    readonly problems: readonly PatchProblem[];
+    /** Current rows for every file named by a problem (reject-and-serve). */
+    readonly served: readonly ServedFileBlock[];
+    /** A rejection is pre-commit: the disk is unchanged by construction. */
+    /**
+     * True when the commit left the disk byte-identical (every written member rolled back). A
+     * mid-commit failure that could not be rolled back sets this false and reports exactly which
+     * members were restored, remain, or are uncertain.
+     */
+    readonly changedNothing: boolean;
+    /** The rollback's three-way outcome, when the failure happened after a member was written. */
+    readonly recovery?: TransactionRecoveryReport;
+}
+export type ApplyPatchResult = ApplyPatchSuccess | ApplyPatchFailure;
+/** The grammar seam's total result: a document or every syntax problem found. */
+export type ParsePatchResult = {
+    readonly ok: true;
+    readonly document: PatchDocument;
+} | {
+    readonly ok: false;
+    readonly problems: readonly PatchProblem[];
+};
+/** The planner seam's total result. */
+export type PlanPatchResult = {
+    readonly ok: true;
+    readonly plan: PatchPlan;
+} | {
+    readonly ok: false;
+    readonly problems: readonly PatchProblem[];
+    /** Current rows for every problem file, so the rejection needs no read to retry. */
+    readonly served: readonly ServedFileBlock[];
+};
+/** The model-facing tool envelope returned by the renderer / tool use case. */
+export interface ApplyPatchToolResult {
+    readonly content: ReadonlyArray<{
+        readonly type: "text";
+        readonly text: string;
+    }>;
+    readonly details: ApplyPatchDetails;
+    /** True when this envelope renders a rejection (nothing was written). */
+    readonly isError?: boolean;
+}
+/** The structured details half of {@link ApplyPatchToolResult}. */
+export interface ApplyPatchDetails {
+    readonly summary: string;
+    readonly diff: string;
+    readonly files: readonly AppliedFileSummary[];
+    readonly servedByPath: readonly ServedFileBlock[];
+    readonly warnings: readonly string[];
+    readonly metrics: PatchMetrics;
+}
+/** Execution facts every apply_patch seam shares. */
+export interface ApplyPatchContext {
+    /** Absolute directory relative request paths resolve against (the live session directory). */
+    readonly cwd: string;
+    /** Session identity that keys served anchors and leases; never empty. */
+    readonly sessionKey: string;
+    /** Caller cancellation forwarded into every async file operation. */
+    readonly signal?: AbortSignal;
+}
+/** Options for the planner/commit seams over the existing hash store. */
+export interface ApplyPatchEngineOptions extends ApplyPatchContext {
+    /** Hash store override for tests; the default opens the configured store. */
+    readonly store?: HashStore;
+    /** POSIX access-mode bitmask; commit defaults to read+write, plan to read-only. */
+    readonly accessMode?: number;
+}

package/lib/types/src/domain-errors.d.ts

@@ -28,13 +28,13 @@
  * See ADR-0047.
  */
 export type Audience = "MODEL" | "USER";
-export type DomainErrorCode = "E_BAD_PAYLOAD" | "E_EMPTY_RANGE" | "E_STALE_ANCHOR" | "E_UNKNOWN_ANCHOR" | "E_FOREIGN_ANCHOR" | "E_STALE_RANGE" | "E_TARGET_LOST" | "E_UNVERIFIED_RANGE" | "E_MALFORMED_ANCHOR" | "E_SUSPICIOUS_TEXT" | "E_BATCH_ABORT" | "E_NOOP_LOOP" | "E_UNSUPPORTED_FILE" | "E_ACCESS" | "E_NOT_FOUND" | "E_UNDO_STALE" | "E_UNDO_UNAVAILABLE" | "E_LOSSY_TEXT" | "E_UNDO_REVERT_FAILED" | "E_UNKNOWN" | "E_LARGE_FILE" | "E_INTERNAL_INVARIANT";
+export type DomainErrorCode = "E_BAD_PAYLOAD" | "E_EMPTY_RANGE" | "E_STALE_ANCHOR" | "E_UNKNOWN_ANCHOR" | "E_FOREIGN_ANCHOR" | "E_STALE_RANGE" | "E_TARGET_LOST" | "E_UNVERIFIED_RANGE" | "E_MALFORMED_ANCHOR" | "E_SUSPICIOUS_TEXT" | "E_BATCH_ABORT" | "E_NOOP_LOOP" | "E_UNSUPPORTED_FILE" | "E_ACCESS" | "E_NOT_FOUND" | "E_UNDO_STALE" | "E_UNDO_UNAVAILABLE" | "E_LOSSY_TEXT" | "E_UNDO_REVERT_FAILED" | "E_UNKNOWN" | "E_LARGE_FILE" | "E_INTERNAL_INVARIANT" | "E_PATCH_SYNTAX" | "E_UNIQUE_MATCH";
 /**
  * The registered tool whose call produced an `E_BAD_PAYLOAD`. WHY the registered name: the model
  * reads the tool list, so `undo_last_edit` names the call it must repair and a short form would
  * name nothing. A tool belongs here only after a live path is measured, never by assumption.
  */
-export type PayloadSubject = "read" | "edit" | "undo_last_edit";
+export type PayloadSubject = "read" | "edit" | "apply_patch" | "undo_last_edit";
 export declare function isPayloadSubject(value: unknown): value is PayloadSubject;
 /**
  * Applied-tier warning codes — the `W_*` namespace (spec
@@ -180,6 +180,20 @@ export interface ErrorPayloadMap {
          */
         subject?: PayloadSubject;
     };
+    E_PATCH_SYNTAX: {
+        message: string;
+        path?: string;
+        patchLine?: number;
+        servedRows?: ServedRow[];
+        servedBlock?: string;
+    };
+    E_UNIQUE_MATCH: {
+        message: string;
+        path?: string;
+        patchLine?: number;
+        servedRows?: ServedRow[];
+        servedBlock?: string;
+    };
 }
 export interface CodeSpec<P> {
     audience: Audience;

package/lib/types/src/edit-undo.d.ts

@@ -1,5 +1,5 @@
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { type LineEnding } from "./edit-diff.js";
+import type { UndoLifecycle } from "./undo-store.js";
 export interface UndoEntry {
     content: string;
     bom: string;
@@ -26,6 +26,16 @@ export interface UndoEntry {
     rawPre?: string | null;
     /** The anchor generation the stored hashes were derived under (0 = pre-generation). */
     anchorGeneration?: number | null;
+    /** The lifecycle action this entry reverses; absent/null is an ordinary edit. */
+    lifecycle?: UndoLifecycle | null;
+    /** Move: the absolute pre-transaction path. */
+    fromPath?: string | null;
+    /** Move: the absolute committed path. */
+    toPath?: string | null;
+    /** The raw post-transaction text when the commit wrote non-canonical bytes (pure move). */
+    rawPost?: string | null;
+    /** Add: directories the add created, outermost first. */
+    createdDirs?: readonly string[] | null;
 }
 export declare function saveUndo(path: string, entry: UndoEntry): Promise<{
     persisted: boolean;
@@ -67,4 +77,3 @@ export declare function executeUndoLastEdit(params: {
 }, ctx: UndoLastEditContext, options?: {
     withFileMutationQueue?: UndoMutationQueue;
 }): Promise<UndoLastEditResult>;
-export declare function regEditUndo(pi: ExtensionAPI): void;

package/lib/types/src/file-content/detection.d.ts

@@ -30,6 +30,23 @@ export interface LoadFileOptions {
     signal?: AbortSignal;
 }
 export declare function loadFileKindAndText(filePath: string, options?: LoadFileOptions): Promise<LFile>;
+/**
+ * Decode a whole file image as strict UTF-8, stripping a UTF-8 BOM.
+ *
+ * WHY this helper exists after the multi-encoding governance was removed: the host
+ * layer reads files as UTF-8 only, but it still has to name a non-UTF-8 target as
+ * such instead of handing the model replacement characters. A fatal decode is the
+ * admission test — the bytes are either UTF-8 or they are refused here, and the
+ * UTF-8 BOM is the one BOM the text keeps meaning for, stripped so it never
+ * reaches a line anchor.
+ *
+ * The refusal is a model-facing fact plus the next action (the user decides how to
+ * convert the file): the message names the path and tells the model to ask.
+ * @param path - the model-supplied path, used verbatim in the refusal.
+ * @returns the decoded text without a BOM character.
+ * @throws DomainError `E_UNSUPPORTED_FILE` when the bytes are not valid UTF-8.
+ */
+export declare function decodeUtf8Strict(bytes: Uint8Array, path: string): string;
 export interface ControlCharReport {
     /** Total occurrences, not distinct code points. */
     count: number;

package/lib/types/src/file-content/index.d.ts

@@ -12,9 +12,9 @@ import { visLines } from "../utils.js";
 import { type FileStats, type LFile } from "./detection.js";
 import { type ReadWindow, type ShownRange } from "./preview.js";
 import type { ServedRow } from "../served-session/serve-render.js";
-import type { TruncationResult } from "@earendil-works/pi-coding-agent";
+import type { TruncationResult } from "../host-utils.js";
 export type { FileStats, LFile, LoadFileOptions } from "./detection.js";
-export { loadFileKindAndText } from "./detection.js";
+export { decodeUtf8Strict, loadFileKindAndText } from "./detection.js";
 export { readNormFile, decodeNormText, fileSnap, snapshotIdFor, statKeyOf, type NormText, type NormFile, type SnapInfo, type StatIdentity, type ReadNormOptions, } from "./loader.js";
 export { fmtReadPreview, StatIdentityMismatchError } from "./preview.js";
 export type { ReadWindow } from "./preview.js";

package/lib/types/src/file-content/preview.d.ts

@@ -1,4 +1,4 @@
-import { type TruncationResult } from "@earendil-works/pi-coding-agent";
+import { type TruncationResult } from "../host-utils.js";
 import { type AnchorWalk } from "../hashline/hash-identity.js";
 import type { ServedRow } from "../served-session/serve-render.js";
 /** The lines one page actually rendered, 1-based and inclusive. */