treelay 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1399 @@
+import { Liquid } from 'liquidjs';
+
+/**
+ * Layer reference syntax — SPEC §2 ("Referencing layers") and §3.
+ *
+ * A ref names where a layer's content comes from. Three origins, distinguished
+ * purely by shape so nothing has to be declared twice:
+ *
+ * ```
+ *   ../base                                local path (relative or absolute)
+ *   file:./base                            local path, explicit
+ *   git+https://host/o/r.git#v1.2.0        git at a commit-ish
+ *   git+ssh://git@host/o/r.git#main        git over ssh
+ *   git+file:///srv/repos/pkgs.git#v1      git with a local remote (offline/tests)
+ *   github:acme/base#v2                    shorthand for git+https://github.com/acme/base.git
+ *   @acme/base@^2                          npm package, resolved through node_modules
+ *   npm:@acme/base@^2                      npm, explicit
+ * ```
+ *
+ * Any non-local form may carry `?path=<subdir>` to use a subdirectory of the
+ * fetched tree as the layer root — the monorepo-of-layers case (`?path=core/_layer`).
+ *
+ * Parsing is pure and total: it never touches the network or the filesystem.
+ * {@link canonicalRef} is the single normalized string used as a lockfile key,
+ * so two spellings of the same thing cannot occupy two lock entries.
+ */
+/** Where a layer's bytes come from. */
+type RefKind = "local" | "git" | "npm";
+/** A ref that is fetched and pinned — everything except a local path. */
+type RemoteRefKind = Exclude<RefKind, "local">;
+interface BaseRef {
+    /** The ref exactly as written in the manifest. */
+    raw: string;
+}
+/** A path on this machine; never locked, never cached. */
+interface LocalRef extends BaseRef {
+    kind: "local";
+    /** The path portion, with any `file:` scheme stripped. */
+    path: string;
+}
+/** A git repository at a commit-ish (branch, tag, or full SHA). */
+interface GitRef extends BaseRef {
+    kind: "git";
+    /** Clone URL, scheme included, `git+` prefix stripped. */
+    url: string;
+    /** Branch / tag / SHA as written. Defaults to `HEAD`. */
+    committish: string;
+    /** Subdirectory of the repo that forms the layer root. */
+    subdir?: string;
+}
+/** An npm package, resolved through the installed `node_modules` tree. */
+interface NpmRef extends BaseRef {
+    kind: "npm";
+    /** Package name, scope included. */
+    name: string;
+    /** Semver range as written. Defaults to `*`. */
+    range: string;
+    /** Subdirectory of the package that forms the layer root. */
+    subdir?: string;
+}
+type ParsedRef = LocalRef | GitRef | NpmRef;
+/** Refs that are fetched, cached and pinned in `treelay.lock`. */
+type RemoteRef = GitRef | NpmRef;
+/** Raised when a ref cannot be parsed at all. */
+declare class InvalidRefError extends Error {
+    readonly ref: string;
+    constructor(ref: string, reason: string);
+}
+/** Is this ref a local path (the only kind that is never fetched)? */
+declare function isLocalRef(ref: string): boolean;
+/** Parse a layer reference. Pure: no network, no filesystem. */
+declare function parseRef(ref: string): ParsedRef;
+/**
+ * The normalized spelling of a ref — the lockfile key.
+ *
+ * Two manifests writing `github:acme/base#v2` and
+ * `git+https://github.com/acme/base.git#v2` mean the same layer and must share
+ * one lock entry, so the key is derived from the parsed shape rather than the
+ * text. Local refs canonicalize to themselves; they are never locked.
+ */
+declare function canonicalRef(ref: ParsedRef | string): string;
+/**
+ * The immutable spelling of a ref once resolved — what the lock pins to.
+ *
+ * `git+…#main` resolves to `git+…#<sha>`; `npm:pkg@^2` to `npm:pkg@2.3.1`.
+ * Recording this (alongside the requested form) is what lets drift detection
+ * say precisely *what moved*.
+ */
+declare function pinnedRef(ref: RemoteRef, revision: string): string;
+/** A 40-hex git object name — already immutable, so nothing to re-resolve. */
+declare function isCommitSha(committish: string): boolean;
+
+/**
+ * `treelay.lock` — resolved lineage and pinned revisions (SPEC §3, §9).
+ *
+ * The lockfile sits beside the **leaf layer's manifest** and is committed to
+ * version control. It answers one question: *what exactly was materialized?* A
+ * manifest says `#main`; the lock says which commit `main` was when the tree was
+ * last resolved, plus an integrity hash of the content that produced.
+ *
+ * Note the division of labour with `<dest>/.treelay/lock.json` (§7): that file
+ * records what a *destination* was built from, and is regenerated on every
+ * compile. `treelay.lock` records what the *source composition* pins to, and
+ * changes only when a ref is added or deliberately advanced.
+ *
+ * Serialization is deterministic — sorted keys throughout, fixed field order,
+ * two-space indent, trailing newline — so re-running `treelay lock` on an
+ * unchanged tree produces a byte-identical file and never shows up in a diff.
+ */
+
+/** Filename of the source-side lockfile, beside the leaf manifest. */
+declare const LOCKFILE_NAME = "treelay.lock";
+/** Bumped when the on-disk shape changes incompatibly. */
+declare const LOCKFILE_VERSION = 1;
+/** One pinned layer reference. */
+interface LockEntry {
+    kind: RemoteRefKind;
+    /** Clone URL (git) or package name (npm). */
+    source: string;
+    /** The mutable thing that was asked for: branch, tag, or semver range. */
+    requested: string;
+    /** The immutable revision it resolved to: commit SHA, or exact version. */
+    resolved: string;
+    /** `sha256:…` over the materialized tree — detects a tampered cache. */
+    integrity: string;
+    /** Subdirectory of the fetched tree used as the layer root, if any. */
+    path?: string;
+    /**
+     * Which layers asked for this ref, as paths relative to the lockfile (local
+     * layers) or canonical refs (remote ones). Sorted. Purely informational, but
+     * it is what makes a held-back pin explainable months later.
+     */
+    requestedBy?: string[];
+}
+/** The parsed lockfile. */
+interface TreelayLock {
+    lockfileVersion: number;
+    /** Canonical ref → what it pinned to. */
+    refs: Record<string, LockEntry>;
+}
+/** An empty, valid lock — what a tree with no remote refs serializes to. */
+declare function emptyLock(): TreelayLock;
+/** Absolute path of the lockfile for a leaf layer directory. */
+declare function lockfilePath(leafDir: string): string;
+/** Raised when a lockfile exists but cannot be used. */
+declare class LockfileError extends Error {
+    constructor(file: string, reason: string);
+}
+/** Read the lockfile beside a leaf layer, or an empty lock when there is none. */
+declare function readLock(leafDir: string): TreelayLock;
+/**
+ * Render a lock to its canonical text.
+ *
+ * Field order is fixed rather than alphabetical because these files are read by
+ * humans during incident review: what was asked for, then what it became.
+ */
+declare function serializeLock(lock: TreelayLock): string;
+/** Write the lock beside a leaf layer. Returns true when the bytes changed. */
+declare function writeLock(leafDir: string, lock: TreelayLock): boolean;
+/** Do two locks pin the same things to the same revisions? */
+declare function locksEqual(a: TreelayLock, b: TreelayLock): boolean;
+
+/**
+ * Core type definitions for treelay.
+ *
+ * See SPEC.md — these mirror the manifest (§2), merge semantics (§4), the
+ * `.treelay` sidecar (§4), variables (§6), and the programmatic API (§10).
+ */
+
+/** A reference to another layer: local path, npm spec, or git spec. */
+type LayerRef = string;
+/**
+ * Where a layer's content came from, once resolved (§3).
+ *
+ * Local layers are edited in place; fetched ones live in the content-addressed
+ * cache at an exact revision and are read-only by construction — which is also
+ * what disqualifies them as promotion targets (§8).
+ */
+interface LayerOrigin {
+    kind: "local" | "git" | "npm";
+    /** Canonical ref (lockfile key). Absent for the leaf and plain local layers. */
+    ref?: string;
+    /** Exact revision materialized: commit SHA or package version. */
+    revision?: string;
+    /** `sha256:…` over the materialized tree, as recorded in the lock. */
+    integrity?: string;
+}
+/** Per-file merge strategy (§4). */
+type MergeStrategy = "replace" | "deep-merge" | "patch" | "append" | "prepend" | "delete";
+/**
+ * A `.treelay` sidecar's `op:` (§4). Distinct from `MergeStrategy`: `merge` here
+ * is a *structured patch* (RFC 7386/6902) onto the inherited file, whereas the
+ * strategy `deep-merge` merges two whole files when the same path exists in
+ * multiple layers.
+ */
+type SidecarOpKind = "replace" | "patch" | "merge" | "append" | "prepend" | "delete";
+/** How `deep-merge` treats arrays (§4). */
+type ArrayPolicy = "replace" | "concat" | "by-key";
+/** Whether non-suffixed text files are rendered (§6). */
+type RenderMode = "suffix" | "all-text";
+/** The declared type of a template variable (§6). */
+type VariableType = "string" | "number" | "boolean" | "json" | "yaml" | "path";
+/** A single variable declaration in a manifest (§6). */
+interface VariableDecl {
+    type: VariableType;
+    /** Prompt text; omit to never prompt (pure default/computed). */
+    prompt?: string;
+    /** Default value; may itself be a Liquid template string. */
+    default?: unknown;
+    /** Optional enum of allowed values. */
+    choices?: unknown[];
+    /** Liquid expression — when falsy, the question and value are skipped. */
+    when?: string;
+    /** Liquid template that renders to "" when valid, else the error message. */
+    validate?: string;
+    /** Masked input; excluded from the persisted answers file. */
+    secret?: boolean;
+    /** Derived from other variables; never prompted. */
+    computed?: boolean;
+}
+/** The `treelay.json` manifest (or `"treelay"` key in package.json) — §2. */
+interface Manifest {
+    name?: string;
+    /** Inherit-only; not compilable as a leaf. */
+    abstract?: boolean;
+    parents?: LayerRef[];
+    mixins?: LayerRef[];
+    /**
+     * Trees vendored into the composed output at a fixed subpath (§3).
+     *
+     * `{ "packages": "git+file:///srv/packages.git#v1.2.0" }` materializes that
+     * repo at `packages/` in every compiled tree. Mount *paths* merge across the
+     * graph by ordinary layer precedence, so a leaf can hold one back at an older
+     * ref while its parents float — a ref override, not a separate mechanism.
+     */
+    mounts?: Record<string, LayerRef>;
+    ignore?: string[];
+    /** glob → strategy defaults. */
+    merge?: Record<string, MergeStrategy>;
+    arrays?: ArrayPolicy;
+    /** Suffix that marks a file for rendering (default ".tmpl"). */
+    templateSuffix?: string;
+    render?: RenderMode;
+    variables?: Record<string, VariableDecl>;
+}
+/** A loaded layer: its resolved location plus parsed manifest. */
+interface Layer {
+    /**
+     * Stable identity. A local layer is identified by its absolute directory; a
+     * fetched one by its canonical ref, so provenance stays meaningful across
+     * machines whose caches sit in different places.
+     */
+    id: string;
+    /** Absolute path to the layer's root directory (a cache path when fetched). */
+    dir: string;
+    manifest: Manifest;
+    /** Whether the layer dir is writable (false for node_modules/git installs) — §8. */
+    writable: boolean;
+    /** Where the content came from; local with no ref when omitted. */
+    origin?: LayerOrigin;
+    /**
+     * Subpath this layer's files are re-rooted under in the output (§3 mounts).
+     * Absent for ordinary layers, which compose at the tree root.
+     */
+    mountPath?: string;
+}
+/**
+ * The fully resolved composition: layers ordered lowest → highest precedence,
+ * plus the merged variable schema across all of them (§3, §6).
+ */
+interface ResolvedGraph {
+    /** Lowest precedence first; the leaf/self is last. */
+    layers: Layer[];
+    /** Merged variable declarations across the whole graph (§6). */
+    variables: Record<string, VariableDecl>;
+    /**
+     * Pinned revisions for every remote ref this graph touched, in memory.
+     *
+     * Resolution deliberately does not write it: `resolve` is called by read-only
+     * commands too, and a lockfile appearing as a side effect of `explain` would
+     * be a surprise. Callers that own the source tree (`compile`, `treelay lock`)
+     * persist it when {@link ResolvedGraph.lockDirty} is set.
+     *
+     * Optional because a graph can also be *synthesized* — reflux builds partial
+     * stacks to test shadowing (§8) — and a synthetic stack pins nothing.
+     */
+    lock?: TreelayLock;
+    /** True when `lock` differs from what is on disk (entries added or advanced). */
+    lockDirty?: boolean;
+    /** Leaf directory the lockfile belongs beside. */
+    lockDir?: string;
+}
+/** A `.treelay` sidecar operation on an inherited file (§4). */
+interface SidecarOp {
+    op: SidecarOpKind;
+    /**
+     * Hash of the parent content the patch was authored against (§5). Detects
+     * drift: when it still matches the inherited file, the patch is known to
+     * apply exactly; when it doesn't, compile takes the reconciling path.
+     */
+    base?: string;
+    /**
+     * The parent content itself. A hash can detect drift but cannot reconstruct
+     * the base, so this is what actually enables a *true* diff3 once the
+     * inherited file has moved on. Reflux (§8) records it automatically.
+     */
+    baseContent?: string;
+    /** Liquid expression; skip the op when falsy. */
+    when?: string;
+    /** Render the payload/result with variables (§6). */
+    render?: boolean;
+    /** Unified-diff payload for `op: patch`. */
+    patch?: string;
+    /** RFC 7386 JSON Merge Patch for `op: merge`. */
+    merge?: unknown;
+    /** RFC 6902 JSON Patch for `op: merge`. */
+    jsonPatch?: unknown[];
+    /** Literal payload for `op: append` / `prepend` / `replace`. */
+    content?: string;
+}
+/** Where a compiled file came from, for `explain` (§10). */
+interface FileProvenance {
+    /** Layer id that last produced/owned the content. */
+    fromLayer: string;
+    strategy: MergeStrategy;
+    /** Layer ids whose patches/merges were applied, in order. */
+    patchedFrom?: string[];
+    /** True if user-created in the destination, not template-generated (§7). */
+    owned: boolean;
+}
+/** Result of a compile (§10). */
+interface CompileResult {
+    files: Record<string, FileProvenance>;
+}
+/** A resolved set of variable values keyed by name. */
+type Values = Record<string, unknown>;
+/** The kind of change a destination file represents vs baseline (§8). */
+type ChangeKind = "modified" | "added" | "deleted";
+/** A single change detected by `status` (§8). */
+interface Change {
+    path: string;
+    kind: ChangeKind;
+    /** Layer id currently producing this file (undefined for user-added). */
+    producingLayer?: string;
+    /**
+     * Writable layers this change could be promoted into, already filtered to
+     * those a higher layer would not immediately shadow (§8 guard 1).
+     */
+    targets?: string[];
+    /** Layers that patched/merged on top of the producer, in order. */
+    patchedBy?: string[];
+    /** True when the destination owns the file and no layer produces it (§7). */
+    owned?: boolean;
+}
+
+/** Error types used across treelay. */
+/** A cycle was found in the parents/mixins graph (§3). */
+declare class CycleError extends Error {
+    readonly path: string[];
+    constructor(path: string[]);
+}
+/** C3 could not produce a consistent linearization (§3). */
+declare class InconsistentHierarchyError extends Error {
+    constructor(message: string);
+}
+/** A patch/merge could not be applied cleanly (§5). */
+declare class MergeConflictError extends Error {
+    readonly file: string;
+    constructor(file: string, message: string);
+}
+/** Placeholder for not-yet-built functionality during scaffolding. */
+declare class NotImplementedError extends Error {
+    constructor(what: string);
+}
+
+/**
+ * C3 linearization (Python's MRO) over the `parents` graph — SPEC §3.
+ *
+ * This is the principled answer to multiple inheritance: it resolves diamonds
+ * (a shared ancestor appears once, before its descendants), respects the local
+ * order parents were declared in, and is monotonic. The naive alternative
+ * (depth-first + last-wins dedupe) produces surprising orders in diamonds.
+ *
+ * Output is MRO order: most-derived first (root, then ancestors high → low
+ * precedence). Callers that apply layers lowest-precedence-first should reverse
+ * the ancestor portion. See `resolve.ts`.
+ */
+/**
+ * Linearize `root` over a parent graph.
+ *
+ * @param root      the starting node
+ * @param parentsOf returns the direct parents of a node, in declaration order
+ * @param key       stable identity for a node (defaults to String)
+ * @returns         MRO: `[root, ...ancestors]`, highest precedence first
+ */
+declare function c3Linearize<T>(root: T, parentsOf: (node: T) => T[], key?: (node: T) => string): T[];
+
+/**
+ * Resolve a leaf overlay directory into an ordered, linearized layer stack
+ * plus the merged variable schema — SPEC §3, §6.
+ *
+ * Precedence, lowest → highest: mounts < parents (C3-linearized) < mixins < self.
+ *
+ * Resolution is synchronous even though it may clone repositories. Every caller
+ * in the library and CLI treats `resolve` as a plain function, and a build
+ * cannot proceed without its layers anyway, so there is nothing to overlap with
+ * — the cost of going async would be paid by every consumer for no gain.
+ */
+
+interface ResolveOptions {
+    /**
+     * Refuse to resolve any ref the lockfile does not already pin. The CI
+     * posture: a build either reproduces from what was committed, or it fails.
+     */
+    frozen?: boolean;
+    /** Re-resolve moving refs to their current upstream revision. */
+    updateRefs?: boolean;
+    /** Ignore the lockfile entirely — resolve everything live, pin nothing. */
+    noLock?: boolean;
+    /** Override the fetch cache root (tests). */
+    cacheDir?: string;
+}
+/** Raised when a `mounts` declaration cannot be materialized coherently. */
+declare class MountError extends Error {
+    constructor(mountPath: string, reason: string);
+}
+/** Resolve a leaf directory into its full composition. */
+declare function resolve(srcDir: string, options?: ResolveOptions): ResolvedGraph;
+/**
+ * Resolve a layer reference to an absolute directory on disk.
+ *
+ * Retained as the low-level entry point: local paths resolve directly, and
+ * fetched refs are materialized into the cache and their root returned.
+ */
+declare function resolveRef(ref: LayerRef, fromDir: string, options?: ResolveOptions & {
+    lock?: TreelayLock;
+}): string;
+
+/** Manifest loading — SPEC §2. */
+
+/**
+ * Load the manifest for a layer directory. Looks for a standalone
+ * `treelay.{json,yaml,yml}`, then falls back to a `"treelay"` key in
+ * `package.json`. Returns an empty manifest if none is found (a plain
+ * directory is a valid, parent-less layer).
+ */
+declare function loadManifest(dir: string): Manifest;
+
+/**
+ * Variable declaration merge + value resolution — SPEC §6.
+ *
+ * Declarations merge across the linearized stack (parents < mixins < self),
+ * producing one merged questionnaire for the whole composition. Values are then
+ * resolved lowest → highest: declared default → answers file → prompts → CLI/env.
+ */
+
+/**
+ * Merge variable declarations across layers (lowest → highest precedence).
+ * Same-named declarations merge per-key, so a child can override just the
+ * `default` while inheriting the parent's `prompt`/`type`.
+ */
+declare function mergeVariableDecls(layers: Layer[]): Record<string, VariableDecl>;
+/** Options controlling how values are sourced. */
+interface ResolveValuesOptions {
+    /** Pre-supplied answers (e.g. loaded from `.treelay/answers.json`). */
+    answers?: Values;
+    /** CLI `--set k=v` overrides (highest precedence before computed). */
+    set?: Values;
+    /** Whether to prompt interactively for missing, prompt-able variables. */
+    prompt?: boolean;
+}
+/**
+ * Resolve final variable values for a graph (§6 steps 3–4): collect from
+ * defaults/answers/overrides, prompt for the rest, then evaluate computed and
+ * templated defaults in dependency order via a fixpoint over the declarations.
+ */
+declare function resolveValues(graph: ResolvedGraph, options?: ResolveValuesOptions): Promise<Values>;
+
+/**
+ * Template rendering via LiquidJS — SPEC §6.
+ *
+ * LiquidJS is chosen for safety: layers arrive as third-party npm packages, so
+ * the engine must not allow arbitrary code execution or filesystem/network
+ * access. We construct the engine with file-system access disabled; a template
+ * can only read the resolved variable values.
+ */
+
+/** A sandboxed Liquid engine — no includes/layouts from disk. */
+declare function createEngine(): Liquid;
+/** Render a single template string with the given values. */
+declare function renderString(template: string, values: Values): Promise<string>;
+/**
+ * Decide whether a file path should be rendered, and return its output name.
+ * Suffix opt-in (default): only `*.tmpl` files render, with the suffix stripped.
+ */
+declare function templateTarget(path: string, suffix?: string): {
+    render: boolean;
+    outPath: string;
+};
+
+/**
+ * `.treelay` sidecar parsing & detection — SPEC §4.
+ *
+ * A `<targetPath>.treelay` file describes an operation on the inherited file:
+ * the strategy, an optional base hash (enabling true 3-way merge, §5), an
+ * optional `when:` guard, and the payload. This is the canonical, full-power
+ * form; the filename suffixes (`.patch`/`.append`/`.delete`) are sugar that
+ * desugar to one of these ops.
+ */
+
+/** Is this path a sidecar? (Distinct from the `.treelay/` state dir, §7.) */
+declare function isSidecar(path: string): boolean;
+/** Map a sidecar path to the inherited file it operates on. */
+declare function sidecarTarget(path: string): string;
+/** Parse sidecar YAML into a validated op. */
+declare function parseSidecar(yaml: string): SidecarOp;
+/**
+ * If `path` ends in a known merge suffix, return the desugared op and the
+ * target path it applies to. A bare `.patch` has no recorded `base`, so it is
+ * best-effort apply rather than true 3-way (§5).
+ */
+declare function desugarSuffix(path: string): {
+    op: SidecarOpKind;
+    target: string;
+} | undefined;
+
+/** Recursive deep merge for structured files — SPEC §4. */
+
+type Json = unknown;
+/**
+ * Deep-merge `over` onto `base`. Objects merge recursively; arrays follow the
+ * `arrays` policy. Default `replace` because concat surprises people (§4).
+ */
+declare function deepMerge(base: Json, over: Json, arrays?: ArrayPolicy): Json;
+
+/**
+ * Unified-diff 3-way merge — SPEC §5.
+ *
+ * Two paths, chosen by whether the caller can supply the base *content* the
+ * patch was authored against:
+ *
+ * - **base known** → reconstruct the author's intent (`base` → `patched`), then
+ *   reconcile it against the drift the inherited file actually took
+ *   (`base` → `current`) with a real diff3. This resolves cleanly far more
+ *   often than a flat apply and produces honest conflicts when it can't.
+ * - **base unknown** → best-effort apply onto `current`. jsdiff searches for
+ *   each hunk's location, so hunks that merely *moved* still land; changed
+ *   context is rejected rather than guessed at.
+ *
+ * Either way the function is all-or-nothing: it returns fully merged text or
+ * throws `MergeConflictError`. It never returns partially-patched content.
+ */
+/** Default conflict-marker labels, phrased for the `update` direction (§7). */
+declare const MERGE_LABELS: {
+    readonly ours: "ours (your edits)";
+    readonly base: "base (last template output)";
+    readonly theirs: "theirs (new template)";
+};
+interface TextMerge3Args {
+    /** Common ancestor both sides diverged from. */
+    base: string;
+    /** The local side — kept first in conflict markers, as git does. */
+    ours: string;
+    /** The incoming side. */
+    theirs: string;
+    labels?: {
+        ours: string;
+        base: string;
+        theirs: string;
+    };
+}
+interface TextMerge3Result {
+    /** False when the two sides edited the same region. */
+    clean: boolean;
+    /** Merged text; carries diff3-style conflict markers when `clean` is false. */
+    text: string;
+}
+/**
+ * Three-way merge of raw text — the same diff3 engine `applyPatch3Way` uses,
+ * exposed directly for `update`, which already holds all three versions and has
+ * no patch to apply.
+ *
+ * Conflicts are *returned*, not thrown: unlike compile, `update` has to write
+ * something (markers or a `.rej`) so the user can resolve it in place.
+ * Markers include the base section, so you can see what the template previously
+ * produced rather than guessing why the two sides disagree.
+ */
+declare function mergeText3(args: TextMerge3Args): TextMerge3Result;
+interface Patch3WayArgs {
+    /** Relative path, for error messages. */
+    file: string;
+    /** The inherited content the patch should land on. */
+    current: string;
+    /** Unified diff. Bare `@@` hunks are accepted (no `---`/`+++` headers). */
+    patch: string;
+    /**
+     * The exact content the patch was authored against. When supplied, enables a
+     * true 3-way merge; omit it for best-effort apply.
+     */
+    base?: string;
+}
+/**
+ * Apply a unified diff onto `current`, reconciling against `base` when known.
+ *
+ * Returns the merged text, or throws MergeConflictError — never half-applies.
+ */
+declare function applyPatch3Way(args: Patch3WayArgs): string;
+
+/** Structured patches for config files — SPEC §5. */
+/**
+ * Apply an RFC 7386 JSON Merge Patch. `null` values in the patch delete keys;
+ * everything else recurses. The target is deep-cloned first so the caller's
+ * value is never mutated (the underlying library mutates in place).
+ */
+declare function applyMergePatch(target: unknown, patch: unknown): unknown;
+/**
+ * Apply an RFC 6902 JSON Patch (precise array/path ops). Non-mutating: returns
+ * the new document and leaves the input untouched.
+ */
+declare function applyJsonPatch(target: unknown, ops: unknown[]): unknown;
+interface StructuredMerge3Result {
+    clean: boolean;
+    /** The merged document; only meaningful when `clean`. */
+    value: unknown;
+}
+/**
+ * Three-way merge two structured documents by reconciling their *changes*
+ * rather than their lines (§7).
+ *
+ * Line-based merging conflicts on edits that happen to sit near each other;
+ * comparing `base → ours` and `base → theirs` as merge patches instead means
+ * two sides adding different keys — the common case for `package.json` — merges
+ * cleanly no matter where those keys landed in the file.
+ */
+declare function mergeStructured3(base: unknown, ours: unknown, theirs: unknown): StructuredMerge3Result;
+
+/** Per-file merge strategy dispatch — SPEC §4. */
+
+/**
+ * Default strategy for a path when no manifest glob or sidecar specifies one:
+ * structured files deep-merge, binaries replace, everything else replaces (text
+ * gets patch/append only via explicit sidecar/suffix).
+ */
+declare function defaultStrategy(path: string): MergeStrategy;
+/** Resolve the strategy for a path given the manifest `merge` globs (§4). */
+declare function strategyFor(path: string, globs?: Record<string, MergeStrategy>): MergeStrategy;
+
+/**
+ * Content hashing — the single source of truth for the `sha256:…` format used
+ * by `.treelay` sidecar `base:` fields (§5) and the destination baseline (§7).
+ */
+/** Hash content into the canonical `sha256:<hex>` form. */
+declare function hashContent(data: Buffer | string): string;
+/** Whether `data` matches a recorded `sha256:…` hash. */
+declare function matchesHash(data: Buffer | string, recorded: string): boolean;
+/**
+ * Hash a whole directory tree into one `sha256:…` — the lockfile's `integrity`.
+ *
+ * Deliberately independent of any VCS: it digests the *materialized content*,
+ * which is the thing a build actually consumes. A git commit SHA already says
+ * which revision was asked for; this says the bytes on disk still are that
+ * revision, so a corrupted or hand-edited cache entry is caught rather than
+ * silently compiled in.
+ *
+ * Paths are sorted and mixed into the digest alongside their content, so
+ * renaming a file changes the hash even when the bytes are identical.
+ */
+declare function hashTree(dir: string): string;
+
+/**
+ * Destination `.treelay/` state — SPEC §7.
+ *
+ * Written into the compiled destination so the template link survives: the
+ * lockfile (resolved lineage), persisted answers (deterministic re-render),
+ * the baseline (merge base for update & reflux), and the generated/owned map.
+ */
+
+declare const STATE_DIR = ".treelay";
+interface TreelayState {
+    lock: LockFile;
+    answers: Values;
+    /** relative path → content hash of what the template last produced. */
+    baseline: Record<string, string>;
+    /** relative path → whether the template owns it (vs user-created). */
+    manifest: Record<string, {
+        owned: boolean;
+        fromLayer: string;
+    }>;
+}
+interface LockFile {
+    /**
+     * Layer ids/refs lowest → highest precedence at last compile. The last entry
+     * is the leaf — this is how `update <dest>` rediscovers its source template
+     * without being told where it came from.
+     */
+    lineage: string[];
+    /** Resolved version refs per layer (npm/git), for drift detection. */
+    versions: Record<string, string>;
+}
+declare const statePaths: (destDir: string) => {
+    dir: string;
+    lock: string;
+    answers: string;
+    baseline: string;
+    /** Content snapshot of the last template output — the diff3 merge base (§7). */
+    baselineDir: string;
+    manifest: string;
+};
+/**
+ * The leaf template a destination was compiled from, recovered from the lock.
+ * Returns undefined for a lockfile with no lineage (nothing to update against).
+ */
+declare function sourceOf(state: TreelayState): string | undefined;
+/** Whether a destination already carries treelay state (⇒ `update`, not compile). */
+declare function hasState(destDir: string): boolean;
+/**
+ * Persist the state artifacts into `<destDir>/.treelay/`.
+ *
+ * `snapshot` is the exact content the template just produced. It is stored
+ * alongside the hash index because the two answer different questions: the hash
+ * cheaply decides *whether* a file changed, but only the content can serve as
+ * the merge base when both the template and the user changed it (§7). Passing
+ * it replaces any previous snapshot wholesale, so files the template no longer
+ * produces don't linger as stale merge bases.
+ */
+declare function writeState(destDir: string, state: TreelayState, decls: Record<string, VariableDecl>, snapshot?: ReadonlyMap<string, Buffer>): void;
+/**
+ * Read one file's baseline content — the merge base for `update` (§7).
+ *
+ * Undefined when the destination predates snapshotting, never had the file, or
+ * the snapshot has gone stale. `expectedHash` is what makes the last case safe:
+ * any writer that advances `baseline.json` without passing a fresh `snapshot` to
+ * {@link writeState} leaves content that no longer matches, and merging against
+ * a wrong base corrupts silently. Verifying here turns that into a plain
+ * "no base available", which callers surface as a conflict instead.
+ */
+declare function readBaselineFile(destDir: string, rel: string, expectedHash?: string): Buffer | undefined;
+/** Read back persisted state (used by update/status/reflux). */
+declare function readState(destDir: string): TreelayState;
+
+/**
+ * Compile pipeline — SPEC §6 (the eight steps) and §7 (state).
+ *
+ *   resolve graph → merge var decls → resolve values → eval computed →
+ *   render each layer → merge rendered layers per-file → drop empty-named
+ *   files → materialize + persist state.
+ *
+ * Render-then-merge: a child's op is authored against the parent's *rendered*
+ * output, so each layer is rendered before the merge step.
+ */
+
+interface CompileOptions {
+    destDir: string;
+    /** Final variable values (from `resolveValues`). */
+    values?: Values;
+    /**
+     * Persist newly-resolved pins back into the source `treelay.lock` (§3).
+     *
+     * Defaults to true, following every package manager: the first build after a
+     * ref is added records what it resolved to, so the *next* build reproduces it.
+     * A frozen resolve never gets here — it fails on the unpinned ref instead.
+     */
+    writeLockfile?: boolean;
+}
+/**
+ * One accumulated output file as it builds up across the layer stack. Also the
+ * public shape of an in-memory composition (see {@link composeFiles}).
+ */
+interface FileEntry {
+    data: Buffer;
+    strategy: MergeStrategy;
+    fromLayer: string;
+    patchedFrom: string[];
+}
+/**
+ * Compose a graph into an in-memory file map, writing nothing.
+ *
+ * This is the whole pipeline minus materialization, split out because `update`
+ * (§7) needs the *would-be* output to merge against a project that already
+ * exists — recompiling straight onto disk would destroy the very edits it is
+ * trying to preserve.
+ *
+ * `destDir` is only used to prune a destination nested inside the source tree,
+ * so a compose is safe to run with the real destination path.
+ */
+declare function composeFiles(graph: ResolvedGraph, values?: Values, destDir?: string): Promise<Map<string, FileEntry>>;
+/** Provenance + baseline bookkeeping derived from a composition. */
+declare function summarize(acc: ReadonlyMap<string, FileEntry>): {
+    result: CompileResult;
+    baseline: Record<string, string>;
+    manifest: TreelayState["manifest"];
+};
+/** Materialize a resolved graph into a destination directory. */
+declare function compile(graph: ResolvedGraph, options: CompileOptions): Promise<CompileResult>;
+
+/**
+ * Layer file enumeration & classification — the shared walk beneath both
+ * `compile` (§6/§7) and `explain` (§9).
+ *
+ * Everything that decides *which* files in a layer participate in composition,
+ * and *what kind* of contribution each one makes, lives here. Compile turns
+ * those entries into bytes; explain turns them into provenance. Keeping the
+ * walk in one place is what stops the two from disagreeing about what a layer
+ * contains.
+ */
+
+/**
+ * Globs never materialized into the output.
+ *
+ * `.git` is excluded in **both** forms deliberately (§4, "built-in tombstone"):
+ * `**\/.git/**` covers a normal repository directory's contents, while
+ * `**\/.git` covers the *gitlink file* that a git **submodule** checkout carries
+ * in place of a directory. A layer vendored as a submodule would otherwise
+ * publish its gitlink into every compiled tree, producing output that git reads
+ * as a broken submodule. `.gitignore`/`.gitmodules` are ordinary files and are
+ * intentionally **not** matched by the exact-name `.git` glob.
+ */
+declare const ALWAYS_IGNORE: string[];
+/** What sort of contribution a source file in a layer makes. */
+type EntryKind = "file" | "sidecar" | "suffix";
+/** One classified source file within a layer. */
+interface LayerEntry {
+    /** Path of the source file relative to the layer dir. */
+    source: string;
+    /** The path after stripping the template suffix (may still carry an op suffix). */
+    inner: string;
+    /** True when the source carried the template suffix (content renders, §6). */
+    isTemplate: boolean;
+    kind: EntryKind;
+    /** For sidecar/suffix entries, the operation being performed. */
+    op?: SidecarOpKind;
+    /**
+     * The output path this entry targets, *before* Liquid path rendering.
+     * For ops this is the inherited file the op applies to.
+     */
+    rawTarget: string;
+}
+/**
+ * Raised when a destination directory is a layer root itself — compiling a
+ * layer on top of itself is degenerate, not merely awkward, so it fails loud
+ * rather than half-consuming its own output.
+ */
+declare class SelfCompileError extends Error {
+    constructor(dir: string);
+}
+/**
+ * Extra ignore globs so a destination nested *inside* a layer never feeds its
+ * own prior output back into the composition (§7).
+ *
+ * The autom-lake shape — compiling into a gitignored `build/` inside the source
+ * repo — is explicitly supported: a destination that is a strict descendant of
+ * a layer is pruned from that layer's walk. A destination that *is* the layer
+ * root is rejected via {@link SelfCompileError}.
+ */
+declare function destExclusions(layerDir: string, destDir?: string): string[];
+/**
+ * Re-root an output path under a layer's mount point (§3).
+ *
+ * A mounted layer composes exactly like any other — same strategies, same
+ * sidecars — except that every path it produces or operates on is prefixed.
+ * Keeping that in one function is what stops `compile` and `explain` from
+ * disagreeing about where a mounted file lands.
+ */
+declare function mountTarget(layer: Layer, target: string): string;
+/** List the composable source files of a layer, lowest-level primitive. */
+declare function listLayerFiles(layer: Layer, destDir?: string): string[];
+/**
+ * Classify one source path into the contribution it makes.
+ *
+ * The template suffix is outermost (§6): strip and render first, then the inner
+ * name decides whether this is a sidecar, suffix sugar, or a plain file.
+ */
+declare function classifyEntry(source: string, templateSuffix: string): LayerEntry;
+/** Enumerate a layer's classified entries, in stable (sorted) order. */
+declare function enumerateLayer(layer: Layer, destDir?: string): LayerEntry[];
+
+/**
+ * `explain` — per-file provenance across the layer stack (SPEC §9, §12 step 7).
+ *
+ * The debugging story for a system whose whole job is "this file came from
+ * somewhere non-obvious": for every output path, which layers contributed, via
+ * which strategy, in what precedence order, and which one won.
+ *
+ * Read-only. It walks the same enumeration as `compile` (see `layer-files.ts`)
+ * and mirrors its accumulation bookkeeping — `winner`/`strategy`/`patchedFrom`
+ * are defined to match `CompileResult.files[path]` exactly, and a test asserts
+ * that equivalence so the two cannot drift apart silently.
+ *
+ * Unlike compile, explain never throws on a not-yet-implemented strategy: a
+ * unified-diff patch is *described* rather than applied, so `explain` stays
+ * useful precisely where a build is failing.
+ */
+
+/** Why a layer is in the stack (§1, §3). */
+type LayerRole = "parent" | "mixin" | "self" | "mount";
+/** What a contribution did to the accumulating file. */
+type ContributionAction = "create" | "replace" | "deep-merge" | "append" | "prepend" | "delete" | "merge" | "patch";
+/** A layer's position and identity within the resolved stack. */
+interface LayerSummary {
+    id: string;
+    name: string;
+    role: LayerRole;
+    /** 1-based position, lowest precedence first. */
+    position: number;
+    writable: boolean;
+    /** Canonical ref this layer was fetched from (§3); absent for local layers. */
+    ref?: string;
+    /** Exact revision materialized — commit SHA or package version. */
+    revision?: string;
+    /** Subpath a mounted layer's files are re-rooted under (§3). */
+    mountPath?: string;
+}
+/** One layer's contribution to one output path. */
+interface Contribution {
+    layer: string;
+    name: string;
+    role: LayerRole;
+    position: number;
+    /** Source file within the layer that produced this contribution. */
+    source: string;
+    action: ContributionAction;
+    /** How the file would be combined at this step (§4). */
+    strategy: MergeStrategy;
+    kind: LayerEntry["kind"];
+    /** Recorded base hash from a sidecar, enabling true 3-way merge (§5). */
+    base?: string;
+    /** True when a `when:` guard evaluated falsy and the op was skipped (§4). */
+    skipped?: boolean;
+    /** Human note (unsupported strategy, unrendered path, …). */
+    note?: string;
+}
+/** The full provenance of one output path. */
+interface FileExplanation {
+    path: string;
+    /** In precedence order, lowest → highest. */
+    contributions: Contribution[];
+    /** Whether the file survives to the output (false ⇒ tombstoned). */
+    present: boolean;
+    /** Layer id whose content won — mirrors `CompileResult.files[path].fromLayer`. */
+    winner?: string;
+    /** Winning strategy — mirrors `CompileResult.files[path].strategy`. */
+    strategy?: MergeStrategy;
+    /** Layers whose patches/merges were folded in — mirrors `patchedFrom`. */
+    patchedFrom: string[];
+    /** True for a destination file with no template origin (user-owned, §7). */
+    owned?: boolean;
+}
+/** The whole composition, explained. */
+interface ExplainResult {
+    layers: LayerSummary[];
+    /** Keyed by output path, insertion-ordered by path. */
+    files: Record<string, FileExplanation>;
+}
+interface ExplainOptions {
+    /** Variable values used to render templated paths and `when:` guards (§6). */
+    values?: Values;
+    /** A destination nested inside a layer, pruned from the walk (§7). */
+    destDir?: string;
+}
+/** Classify each layer by why it is in the stack. */
+declare function summarizeLayers(graph: ResolvedGraph): LayerSummary[];
+/** Explain every output path produced by a resolved graph. */
+declare function explain(graph: ResolvedGraph, options?: ExplainOptions): Promise<ExplainResult>;
+/** Explain a single output path; undefined when no layer touches it. */
+declare function explainFile(graph: ResolvedGraph, path: string, options?: ExplainOptions): Promise<FileExplanation | undefined>;
+/**
+ * Explain a compiled destination (§7).
+ *
+ * The lockfile's lineage records absolute layer dirs lowest → highest, so its
+ * last entry *is* the source root: a destination can reconstruct its own graph
+ * and re-explain itself with the answers it was built from. Files the template
+ * does not own are reported as user-owned rather than omitted.
+ */
+declare function explainDest(destDir: string): Promise<ExplainResult>;
+/** Render an explanation as aligned, human-readable text. */
+declare function formatExplanation(result: ExplainResult, only?: string): string;
+
+/**
+ * Upstream drift — has a ref moved since the lock pinned it? (SPEC §3, §9)
+ *
+ * Drift is *reported*, never acted on. A build whose lock says `abc123` keeps
+ * producing `abc123` even after `main` advances; that is the entire point of
+ * pinning. What treelay owes the user is that the divergence is visible —
+ * `explain` annotates the layer, `update` says so before merging, and
+ * `treelay lock --update` is the one command that advances a pin.
+ *
+ * The probe is best-effort by construction. Being offline, lacking credentials,
+ * or having deleted the package makes the current revision *unknown*, which is
+ * a distinct answer from "unchanged" and is presented as one.
+ */
+
+/** Whether a pinned ref still matches its upstream. */
+type DriftStatus = "in-sync" | "moved" | "unknown" | "immutable";
+/** One ref's drift verdict. */
+interface DriftReport {
+    /** Canonical ref (the lockfile key). */
+    ref: string;
+    /** What was asked for — branch, tag, or semver range. */
+    requested: string;
+    /** The revision the lock pins, and what any build here materializes. */
+    locked: string;
+    /** What the ref points at now; undefined when it could not be determined. */
+    current?: string;
+    status: DriftStatus;
+    /** Layers composed from this ref, for a message that names names. */
+    layers: string[];
+}
+/** Has anything actually moved? (unknown is not drift — it is ignorance). */
+declare function hasDrift(reports: readonly DriftReport[]): boolean;
+/**
+ * Check every pinned ref in a resolved graph against its upstream.
+ *
+ * Contacts the network once per distinct ref, so callers should treat it as an
+ * explicit action rather than something to fold into a hot path.
+ */
+declare function checkDrift(graph: ResolvedGraph, fromDir?: string): DriftReport[];
+/** Human-readable drift summary. Empty string when nothing has moved. */
+declare function formatDrift(reports: readonly DriftReport[]): string;
+
+/**
+ * Living-template update — SPEC §7.
+ *
+ * Reloads saved answers (prompting only for newly-introduced variables),
+ * recompiles `theirs`, and three-way merges against the baseline (`base`) and
+ * the working copy (`ours`), then rewrites the baseline.
+ *
+ * The whole resolution is computed before anything is written. `update` touches
+ * a project the user has been working in, so a failure partway through must
+ * leave that project exactly as it was rather than half-updated.
+ */
+
+/** How each file was resolved. */
+type Resolution = "take-theirs" | "keep-ours" | "merged" | "conflict" | "delete"
+/** All three sides agree — nothing to do. Lets a no-op update say so. */
+ | "unchanged";
+interface UpdateOptions {
+    /**
+     * How conflicts are surfaced:
+     * - `markers` (default) — write the merged file with diff3 conflict markers.
+     * - `rej` — leave the working file untouched and drop the incoming version
+     *   beside it as `<file>.rej`, for projects where a file must stay parseable.
+     */
+    onConflict?: "markers" | "rej";
+    /** CLI `--set k=v` overrides applied over saved answers. */
+    set?: Record<string, unknown>;
+    /** Prompt for variables the new template version introduced (default true). */
+    prompt?: boolean;
+    /** Refuse to resolve refs `treelay.lock` does not pin (§3). */
+    frozen?: boolean;
+}
+interface UpdatePlan {
+    /** Per file: the resolution that update would apply. */
+    files: Record<string, Resolution>;
+    /** Paths that could not be merged cleanly. */
+    conflicts: string[];
+    /** Variables the new template version introduced and now has answers for. */
+    newVariables: string[];
+    /**
+     * Pinned refs whose upstream has moved since `treelay.lock` was written (§3).
+     *
+     * Reported, never followed. An update that silently recomposed at a newer
+     * revision because a branch advanced would make "pull my template's changes
+     * down" mean two different things depending on the day.
+     */
+    drift: DriftReport[];
+}
+/** Dry-run: compute the per-file 3-way resolution without writing (§10). */
+declare function planUpdate(destDir: string, options?: UpdateOptions): Promise<UpdatePlan>;
+/** Apply a template update into an existing destination. */
+declare function update(destDir: string, options?: UpdateOptions): Promise<UpdatePlan>;
+
+/**
+ * Blast radius — SPEC §8 guard 3.
+ *
+ * "Promoting up reaches *every sibling* inheriting that layer — the intent, but
+ * a footgun." Before a promote lands, report who else is downstream of the
+ * target so the reach is a stated fact rather than a surprise on someone else's
+ * next `update`.
+ *
+ * Two populations, found two different ways:
+ *
+ * - **dependents** — other *layers* declaring the target as a parent or mixin.
+ *   Found by reading manifests. These inherit the change by composition.
+ * - **destinations** — already-compiled *projects* whose lockfile lineage
+ *   includes the target. Found by reading `.treelay/lock.json`. These are live
+ *   deployments that will absorb the change when they next update.
+ *
+ * The search is bounded: reflux passes a root (normally the common ancestor of
+ * the composition) rather than letting this wander the filesystem.
+ */
+interface BlastRadius {
+    /** The layer being promoted into. */
+    layer: string;
+    searchRoot: string;
+    /** Other layer dirs that declare the target as a parent or mixin. */
+    dependents: string[];
+    /** Compiled destination dirs whose lineage includes the target. */
+    destinations: string[];
+    /**
+     * True when the scan may be incomplete — consumers can live outside the
+     * search root, so "none found" is never proof of "none exist".
+     */
+    bounded: boolean;
+}
+interface BlastRadiusOptions {
+    /** Directory to scan. Consumers outside it are invisible to this scan. */
+    searchRoot: string;
+    /** Destination doing the promoting; excluded from `destinations`. */
+    excludeDest?: string;
+    /** Layer doing the promoting; excluded from `dependents`. */
+    excludeLayer?: string;
+    /** Directory depth to scan. Deep enough for a monorepo, bounded for sanity. */
+    depth?: number;
+}
+/** Find every layer and compiled destination downstream of `layerDir`. */
+declare function blastRadius(layerDir: string, options: BlastRadiusOptions): BlastRadius;
+/** A one-line warning in the shape SPEC §8 guard 3 asks for. */
+declare function describeBlastRadius(radius: BlastRadius, layerName: string): string;
+/** The deepest directory containing every given path — a natural search root. */
+declare function commonAncestor(paths: string[]): string;
+
+/**
+ * Reflux — pushing instance edits back up the graph — SPEC §8.
+ *
+ * `compile` is instantiation; reflux is "pull member up". `status` lists what
+ * diverged from the baseline and blames the layer that produced it, `promote`
+ * pushes a change into an existing ancestor, and `extract` factors it into a
+ * brand-new overlay.
+ *
+ * Every write-back runs the three guards of §8:
+ *
+ *   1. **Precedence shadowing** — refuse a target a higher layer would override,
+ *      because the change would silently vanish on the next recompile.
+ *   2. **Round-trip verification** — recompile and assert the destination
+ *      reproduces byte-for-byte, rolling back the layer writes if it doesn't.
+ *   3. **Blast radius** — report which other layers and compiled destinations
+ *      the target feeds before the change reaches them.
+ *
+ * Guards 1 and 2 divide the work: guard 1 catches the cases that provably
+ * cannot work (a wholesale override sits above the target) with a precise,
+ * actionable message; guard 2 catches everything subtler — partial merges,
+ * append ordering, re-render losses — by simply checking whether the graph
+ * reproduces reality.
+ */
+
+/** List changes in a destination vs its baseline, with provenance (§8). */
+declare function status(destDir: string): Promise<Change[]>;
+/** Render `status` output in the annotated form of SPEC §8. */
+declare function formatStatus(changes: Change[], graph: ResolvedGraph): string;
+/** How a promoted change was written into its target layer. */
+type LandingMode = "rewrite" | "patch" | "create" | "tombstone";
+interface LandedChange {
+    path: string;
+    mode: LandingMode;
+    /** File written inside the target layer, relative to the layer root. */
+    wrote: string;
+}
+interface PromoteResult {
+    /** Layer id promoted into. */
+    target: string;
+    targetName: string;
+    landed: LandedChange[];
+    verified: boolean;
+    blastRadius: BlastRadius;
+    /** Human-readable §8 guard 3 warning. */
+    blastRadiusWarning: string;
+}
+interface PromoteOptions {
+    /** Target layer to promote into; if omitted, auto-suggest from provenance. */
+    to?: LayerRef;
+    /** Recompile and assert byte-identity after promoting (default true). */
+    verify?: boolean;
+    /** Root for the blast-radius scan (default: common ancestor of the graph). */
+    searchRoot?: string;
+}
+/**
+ * Promote changes up into a target layer. Throws on precedence-shadowing,
+ * read-only targets, or a failed round-trip verification (§8 guards). Generates
+ * a `.treelay` sidecar recording both `base` and `baseContent` when the change
+ * lands as a patch rather than a rewrite (§5).
+ */
+declare function promote(destDir: string, changes: Change[], options?: PromoteOptions): Promise<PromoteResult>;
+interface ExtractOptions {
+    /** Path for the new overlay layer. */
+    as: string;
+    /** Wire it into the leaf's `mixins` (vs leaving it free-standing). */
+    asMixin?: boolean;
+    /** Name for the new layer's manifest (default: its directory name). */
+    name?: string;
+    /** Recompile and assert byte-identity afterwards (default true when wired). */
+    verify?: boolean;
+}
+interface ExtractResult {
+    /** Absolute path of the new layer. */
+    layer: string;
+    name: string;
+    files: string[];
+    /** Whether the leaf was rewired to consume the new layer. */
+    wired: boolean;
+    verified: boolean;
+}
+/**
+ * Capture changes as a new overlay layer (§8).
+ *
+ * A free-standing extraction (`asMixin: false`) deliberately skips round-trip
+ * verification and leaves the baseline alone: the new layer is not in the graph
+ * yet, so the destination provably *cannot* reproduce from it. Verifying would
+ * fail by construction, and rewriting the baseline would falsely mark the edits
+ * as inherited.
+ */
+declare function extract(destDir: string, changes: Change[], options: ExtractOptions): Promise<ExtractResult>;
+
+/**
+ * Round-trip verification — SPEC §8 guard 2.
+ *
+ * "After any promote/extract, recompile and assert the working copy is
+ * byte-identical." This is the guard that makes reflux trustworthy: a promoted
+ * edit is only accepted once the graph provably reproduces it, so merge-order
+ * interactions surface as a loud failure instead of silent drift.
+ *
+ * The comparison is deliberately one-directional. Every path the template
+ * produces must match the destination exactly; files the destination has but
+ * the template does not are *user-owned* (§7) and are none of verification's
+ * business. Without that asymmetry every unpromoted local file would read as a
+ * failure.
+ */
+
+/**
+ * Compose a graph and return its output in memory, without touching any real
+ * destination — verification must not be able to disturb what it is checking.
+ */
+declare function composeToMemory(graph: ResolvedGraph, values: Values, destDir?: string): Promise<Map<string, Buffer>>;
+type MismatchKind = "content-differs" | "missing-in-dest" | "should-have-been-removed";
+interface VerifyMismatch {
+    path: string;
+    kind: MismatchKind;
+    detail: string;
+}
+interface VerifyResult {
+    ok: boolean;
+    mismatches: VerifyMismatch[];
+    /** The recomposed output, reusable as the new baseline on success. */
+    composed: Map<string, Buffer>;
+}
+interface VerifyOptions {
+    /**
+     * Paths a promotion intended to remove. Verification asserts the recompiled
+     * template no longer produces them — otherwise a promoted tombstone that
+     * failed to take would pass unnoticed, since the file is already gone from
+     * the destination either way.
+     */
+    expectAbsent?: string[];
+}
+/** Recompile `graph` and assert `destDir` reproduces it byte-for-byte. */
+declare function roundTripVerify(destDir: string, graph: ResolvedGraph, values: Values, options?: VerifyOptions): Promise<VerifyResult>;
+/** Render mismatches into a message suitable for a thrown error. */
+declare function describeMismatches(mismatches: VerifyMismatch[]): string;
+
+/**
+ * Git-backed layers (SPEC §3).
+ *
+ * Two operations, deliberately separated because they have very different
+ * costs and failure modes:
+ *
+ * - **resolve** — what commit does `#main` mean *right now*? Needs the remote.
+ * - **materialize** — give me the tree at commit `abc123`. Needs only the cache
+ *   once that commit has been fetched, and is what a locked build does.
+ *
+ * That split is the whole of "compile honours the lock": a locked build never
+ * asks the first question, so a moved branch cannot change what it produces.
+ *
+ * Everything shells out to the user's `git`. Reimplementing the wire protocol
+ * to save a process spawn would trade a well-tested dependency every developer
+ * already has for a novel one that has to learn about proxies, credential
+ * helpers, SSH agents and partial clones.
+ */
+
+/** Raised when a git operation fails, carrying git's own message. */
+declare class GitFetchError extends Error {
+    readonly url: string;
+    constructor(url: string, message: string);
+}
+
+/**
+ * npm-backed layers (SPEC §3).
+ *
+ * An overlay *is* a normal npm package (§2), so treelay resolves npm refs the
+ * way any Node program resolves a dependency: through the installed
+ * `node_modules` tree, starting at the layer that declared the ref.
+ *
+ * **treelay deliberately does not install anything.** Package installation is
+ * already owned by a tool with a lockfile, an integrity model, a registry
+ * configuration and an offline cache; shipping a second, worse copy of that
+ * inside a composition engine would mean two lockfiles disagreeing about the
+ * same tree. treelay's job is to record *which* version composition consumed,
+ * and to fail clearly when the package is not installed at all.
+ *
+ * The consequence worth naming: an npm layer's exact version is whatever the
+ * package manager put on disk. `treelay.lock` pins what was used and
+ * {@link liveNpmVersion} reports when the installed tree has since moved, but
+ * reproducing an old pin is `npm ci`'s job, not treelay's.
+ */
+
+/** Raised when an npm layer cannot be resolved from the installed tree. */
+declare class NpmResolveError extends Error {
+    readonly packageName: string;
+    constructor(packageName: string, message: string);
+}
+
+/**
+ * Content-addressed cache for fetched layers (SPEC §3).
+ *
+ * Every fetched tree lands at a path derived from *what it is*, never from who
+ * asked for it: `<root>/git/<repo-key>/rev/<commit>/`. Two layers pinning the
+ * same commit share one checkout, a held-back pin coexists with a floating one
+ * instead of fighting over a working directory, and the cache is safe to delete
+ * at any time — worst case the next resolve re-fetches.
+ *
+ * `TREELAY_CACHE_DIR` overrides the location, which is how tests stay hermetic.
+ */
+/** Root of the cache: `$TREELAY_CACHE_DIR`, else `~/.cache/treelay`. */
+declare function cacheRoot(override?: string): string;
+/**
+ * A filesystem-safe, collision-resistant key for a remote location.
+ *
+ * The readable slug is there for humans poking at the cache; the hash suffix is
+ * what actually guarantees uniqueness, since sanitizing a URL is lossy.
+ */
+declare function locationKey(location: string): string;
+
+/**
+ * Fetching a remote layer, lock-aware (SPEC §3).
+ *
+ * One entry point sits between resolution and the per-transport fetchers, and
+ * it is where the lockfile earns its keep:
+ *
+ * - **locked** — the lock already pins this ref → materialize *that* revision.
+ *   No remote query, so a branch that has since moved cannot change the build.
+ * - **unlocked** — resolve the ref live, materialize, and hand back an entry for
+ *   the caller to record.
+ * - **frozen** — an unlocked ref is an error, not a silent lock update. This is
+ *   the CI posture: builds reproduce or they fail.
+ *
+ * Everything here is synchronous by design. Layer resolution is called from
+ * `resolve()`, which the entire library and CLI treat as a plain function; making
+ * it async to accommodate a subprocess would ripple through every caller for no
+ * behavioural gain, since a build cannot proceed without its layers anyway.
+ */
+
+/** Raised when a frozen resolve meets a ref the lockfile does not pin. */
+declare class LockMissingError extends Error {
+    readonly ref: string;
+    constructor(ref: string);
+}
+/** Raised when cached content no longer matches the integrity the lock records. */
+declare class IntegrityError extends Error {
+    constructor(ref: string, expected: string, actual: string);
+}
+interface FetchOptions {
+    /** Directory the ref was declared in — the anchor for npm resolution. */
+    fromDir: string;
+    /** Existing pins; consulted before any remote is contacted. */
+    lock: TreelayLock;
+    /** Refuse to resolve refs the lock does not already pin (CI). */
+    frozen?: boolean;
+    /** Re-resolve moving refs to their current revision, advancing the lock. */
+    updateRefs?: boolean;
+    /** Override the cache root (tests). */
+    cacheDir?: string;
+}
+/** A materialized remote layer plus the lock entry describing it. */
+interface FetchedLayer {
+    /** Canonical ref — the lockfile key. */
+    ref: string;
+    /** Absolute path of the layer root on disk. */
+    dir: string;
+    revision: string;
+    integrity: string;
+    entry: LockEntry;
+    /** True when the lock gained or changed an entry because of this fetch. */
+    changed: boolean;
+}
+/** Fetch (or reuse) a remote layer, honouring the lock. */
+declare function fetchLayer(ref: RemoteRef, options: FetchOptions): FetchedLayer;
+/**
+ * Re-hash a materialized layer. Used by `treelay lock --check` to notice a
+ * cache that has been edited in place without re-fetching anything.
+ */
+declare function verifyIntegrity(dir: string, expected: string): boolean;
+/**
+ * What a ref points at on the remote right now — the drift probe.
+ *
+ * Undefined means "could not tell" (offline, no credentials, package not
+ * installed), never "unchanged": an advisory check that silently reports
+ * in-sync when it could not look would be worse than saying nothing.
+ */
+declare function liveRevision(ref: RemoteRef, fromDir: string): string | undefined;
+
+export { ALWAYS_IGNORE, type ArrayPolicy, type BlastRadius, type BlastRadiusOptions, type Change, type ChangeKind, type CompileResult, CycleError, type DriftReport, type DriftStatus, type ExtractOptions, type ExtractResult, type FetchOptions, type FetchedLayer, type FileEntry, type FileProvenance, GitFetchError, type GitRef, InconsistentHierarchyError, IntegrityError, InvalidRefError, LOCKFILE_NAME, LOCKFILE_VERSION, type LandedChange, type LandingMode, type Layer, type LayerOrigin, type LayerRef, type LocalRef, type LockEntry, type LockFile, LockMissingError, LockfileError, MERGE_LABELS, type Manifest, MergeConflictError, type MergeStrategy, type MismatchKind, MountError, NotImplementedError, type NpmRef, NpmResolveError, type ParsedRef, type Patch3WayArgs, type PromoteOptions, type PromoteResult, type RefKind, type RemoteRef, type RemoteRefKind, type RenderMode, type Resolution, type ResolveOptions, type ResolvedGraph, STATE_DIR, SelfCompileError, type SidecarOp, type SidecarOpKind, type TextMerge3Args, type TextMerge3Result, type TreelayLock, type TreelayState, type UpdateOptions, type UpdatePlan, type Values, type VariableDecl, type VariableType, type VerifyMismatch, type VerifyResult, applyJsonPatch, applyMergePatch, applyPatch3Way, blastRadius, c3Linearize, cacheRoot, canonicalRef, checkDrift, classifyEntry, commonAncestor, compile, composeFiles, composeToMemory, createEngine, deepMerge, defaultStrategy, describeBlastRadius, describeMismatches, destExclusions, desugarSuffix, emptyLock, enumerateLayer, explain, explainDest, explainFile, extract, fetchLayer, formatDrift, formatExplanation, formatStatus, hasDrift, hasState, hashContent, hashTree, isCommitSha, isLocalRef, isSidecar, listLayerFiles, liveRevision, loadManifest, locationKey, lockfilePath, locksEqual, matchesHash, mergeStructured3, mergeText3, mergeVariableDecls, mountTarget, parseRef, parseSidecar, pinnedRef, planUpdate, promote, readBaselineFile, readLock, readState, renderString, resolve, resolveRef, resolveValues, roundTripVerify, serializeLock, sidecarTarget, sourceOf, statePaths, status, strategyFor, summarize, summarizeLayers, templateTarget, update, verifyIntegrity, writeLock, writeState };