@xtrable-ltd/nanoesis 0.1.9 → 0.1.11

package/dist/index.d.ts

@@ -152,7 +152,12 @@ interface DirEntry {
     readonly kind: EntryKind;
 }
 interface ContentSource {
-    /** Immediate children of a directory. */
+    /**
+     * Immediate children of a directory, sorted by `name` ascending. The sort is part
+     * of the port contract (CLAUDE §2: determinism) — every implementation must return
+     * a stable order so downstream Map/Set/loop iteration over the result produces
+     * byte-identical output across runs.
+     */
     list(dir: string): Promise<readonly DirEntry[]>;
     /** Read a UTF-8 text file; rejects if it does not exist. */
     readText(path: string): Promise<string>;
@@ -175,164 +180,6 @@ declare class InMemoryContentSource implements ContentSource {
     list(dir: string): Promise<readonly DirEntry[]>;
 }
 
-/**
- * The outcome of a {@link WorkingStore.rename}. Clobbering an existing destination, or
- * renaming a path that does not exist, are *expected* outcomes (a user renames to a name
- * already in use), so they are returned as data, not thrown (CLAUDE §2): the host maps
- * them to 409/404.
- */
-type RenameResult = {
-    readonly ok: true;
-} | {
-    readonly ok: false;
-    readonly reason: 'exists' | 'missing';
-};
-/**
- * The editor's working store (DESIGN §11c): a read {@link ContentSource} for
- * compile/validate, plus the write/delete/rename the editor content API needs. The
- * editor API depends on this port, never a concrete store, so the index-backed
- * {@link IndexedStore} (over an adopter's get/put/delete) and the blob adapter are
- * interchangeable behind it.
- */
-interface WorkingStore extends ContentSource {
-    /** Create or overwrite `path` with raw bytes (binary-correct). */
-    write(path: string, contents: Uint8Array): Promise<void>;
-    /** Delete a file, or a whole directory subtree; a missing path is a no-op. */
-    delete(path: string): Promise<void>;
-    /** Move a file or subtree; refuses to clobber, or to rename a missing path. */
-    rename(from: string, to: string): Promise<RenameResult>;
-}
-
-/**
- * The content index (DESIGN §11d): the sorted set of every key in the working store,
- * the directory listing a flat blob store cannot give cheaply, lifted into one object
- * we own. Enumeration (the editor tree, compile) reads this, so the adopter's store
- * stays get/put/delete with no `list`. Persisted under a reserved key with a fixed-size
- * backup ring for integrity.
- */
-interface ContentIndex {
-    /** Monotonic, bumped on every save; orders the backup ring during recovery. */
-    readonly version: number;
-    /** Every key that exists, sorted and de-duplicated (deterministic, CLAUDE §2). */
-    readonly keys: readonly string[];
-    /** Checksum over version + keys, so a corrupt stored index is caught on read. */
-    readonly checksum: string;
-}
-/** Reserved key prefix for the index and its backups; excluded from enumeration. */
-declare const RESERVED_PREFIX = ".nanoesis/";
-/** The empty index of a fresh store: version 0, no keys. */
-declare function emptyIndex(): ContentIndex;
-/**
- * Load the index, recovering through the backup ring if the live copy is missing or
- * corrupt (DESIGN §11d): the highest valid version among the ring slots wins. Returns
- * the empty index when nothing valid is found, a fresh store, or the accepted residual
- * case where the live index and every backup are lost (the files still exist by key,
- * but cannot be enumerated until something rewrites the index).
- */
-declare function loadIndex(store: BlobStore): Promise<ContentIndex>;
-/**
- * Write a new index whose keys are `nextKeys`, backing up the one it replaces first
- * (DESIGN §11d). The previous index goes into its ring slot (`version % ring`, oldest
- * overwritten), then the new index is written to the live key, a constant two writes
- * per save regardless of ring size. Returns the new index (the caller's next `prev`).
- */
-declare function saveIndex(store: BlobStore, prev: ContentIndex, nextKeys: readonly string[]): Promise<ContentIndex>;
-/** What a {@link reconcileIndex} did, for a maintenance UI/CLI and the startup signal. */
-interface ReconcileResult {
-    /** The index after reconciling (the prior one unchanged when nothing differed). */
-    readonly index: ContentIndex;
-    /** Keys now in the index that the prior index lacked (orphaned blobs, recovered). */
-    readonly added: readonly string[];
-    /** Keys the prior index held that no longer exist in the store (stale entries dropped). */
-    readonly removed: readonly string[];
-}
-/**
- * Rebuild the index from the store's *actual* keys (DESIGN §11d): the safety net for a
- * store that got files by a path that bypassed the index, where the files are present
- * by key but unenumerable. The engine cannot list a {@link BlobStore} (none is required
- * to, §11c), so the caller supplies the real key set, an adapter that *can* enumerate
- * (e.g. `BlobContainer.list`) provides it; the rebuild stays pure index logic here.
- *
- * The reserved namespace is never indexed (the index is not its own content). When the
- * resulting key set matches the existing index this is a no-op, no write, no version
- * bump, so reconciling a healthy store is cheap and idempotent.
- */
-declare function reconcileIndex(store: BlobStore, actualKeys: readonly string[]): Promise<ReconcileResult>;
-
-/**
- * A {@link ContentSource} backed by the content index (DESIGN §11d) over a
- * {@link BlobStore}: enumeration (`list`/`exists`) is synthesised from the index's key
- * set, reads go straight to `get`. This is the working store the editor and compile run
- * against once an adopter provides only get/put/delete, every existing `list` caller is
- * unchanged because it still sees a `ContentSource`.
- *
- * Mutations (`write`/`delete`/`rename`) write the file(s) first, then the index
- * (content-first, §11d), keeping the in-memory copy in step so reads on this instance
- * reflect the change at once. The index is only rewritten when the key *set* changes, an
- * overwrite of an existing key is a single `put`.
- *
- * Construction does no I/O: the index loads (and recovers through the backup ring, §11d)
- * lazily on the first enumeration or mutation, so a host can wire the store synchronously.
- *
- * The prefix-synthesis below mirrors {@link InMemoryContentSource} exactly (a cross-check
- * test pins them together); the two are interchangeable implementations of the port.
- */
-declare class IndexedStore implements WorkingStore {
-    private readonly store;
-    private index;
-    private loading;
-    /**
-     * Per-instance mutex (DESIGN §11d): every mutation (`write`/`delete`/`rename`/`reconcile`)
-     * runs through {@link serializeMutation}, which chains onto the previous mutation's
-     * completion. Without it, two concurrent mutations both read the cached `this.index`,
-     * each compute their "next" key set from that stale snapshot, and the second
-     * `saveIndex` clobbers the first — the file writes land in blob, but the index keeps
-     * stale references or loses fresh ones (the "I deleted it and it's still there" or
-     * "I added it and it didn't appear" bugs surfaced dogfooding the marketing site,
-     * 2026-05-28). Reads (`list`/`exists`/`readBytes`) are *not* serialised; an
-     * in-flight mutation simply means a reader sees the pre-mutation index, eventually
-     * consistent and safe. Crashes inside `work()` release the lock so a single failure
-     * does not deadlock subsequent operations.
-     */
-    private mutationLock;
-    constructor(store: BlobStore);
-    /** The index, loaded once on first need and cached (mutations replace the cached copy). */
-    private loaded;
-    private serializeMutation;
-    list(dir: string): Promise<readonly DirEntry[]>;
-    readText(path: string): Promise<string>;
-    readBytes(path: string): Promise<Uint8Array>;
-    exists(path: string): Promise<boolean>;
-    /**
-     * Create or overwrite `key`. The index is rewritten only when `key` is new (an
-     * overwrite leaves the key set unchanged, so editing an item is a single `put`).
-     */
-    write(key: string, bytes: Uint8Array): Promise<void>;
-    /**
-     * Delete a file, or a whole directory subtree (every key under `key/`). Idempotent: a
-     * path the index does not know is still deleted from the store (clearing an orphan),
-     * and deleting nothing is a no-op.
-     */
-    delete(key: string): Promise<void>;
-    /**
-     * Move/rename a file, or a whole directory subtree (every key under `from/` is remapped
-     * under `to/`). Clobbering an existing destination, or renaming a missing path, are
-     * returned as data (`ok: false`), not thrown (CLAUDE §2), the same contract the host's
-     * `/api/rename` enforces. (Mutating the reserved namespace is a programmer error and
-     * still throws.)
-     */
-    rename(from: string, to: string): Promise<RenameResult>;
-    /**
-     * Rebuild this store's index from the *actual* keys the underlying store holds (DESIGN
-     * §11d), recovering files that arrived by a path that bypassed the index. A
-     * {@link BlobStore} cannot enumerate itself, so the caller supplies the real key set
-     * from an adapter that can (e.g. `BlobContainer.list`). Unlike calling
-     * {@link reconcileIndex} on a fresh store, this also refreshes the cached in-memory
-     * index, so this live instance sees the recovered files immediately.
-     */
-    reconcile(actualKeys: readonly string[]): Promise<ReconcileResult>;
-}
-
 /**
  * The authors byline (DESIGN §6.11). An `authors` field stores an ordered list of
  * author refs; the compiler renders them as one grammatical line. Everything here
@@ -610,6 +457,384 @@ interface CompileInput {
  */
 declare function compileTemplate(input: CompileInput): string;
 
+/**
+ * The field-type registry (DESIGN §6.7). Field types and their rules are defined
+ * *once* here and shared by the compiler, the editor's form generator, and (later)
+ * Monaco's IntelliSense. This is the OCP extension point (CLAUDE.md §3): adding a
+ * field type means adding an entry here, never editing a switch in the compiler or
+ * the inference cascade.
+ */
+type FieldType = 'image' | 'file' | 'url' | 'email' | 'phone' | 'date' | 'time' | 'code' | 'richtext' | 'authors' | 'text' | 'shorttext';
+/** How a resolved value is placed into output, the compiler reads this, never the type name. */
+type ValueKind = 'text' | 'html' | 'url' | 'asset' | 'authors';
+interface FieldTypeDef {
+    readonly type: FieldType;
+    readonly valueKind: ValueKind;
+    /** Default editor control hint, consumed by the form generator (DESIGN §7). */
+    readonly control: string;
+    readonly multiline: boolean;
+}
+declare const FIELD_TYPES: Readonly<Record<FieldType, FieldTypeDef>>;
+declare function isFieldType(value: string): value is FieldType;
+declare function valueKindOf(type: FieldType): ValueKind;
+
+/**
+ * Derive the editor's form from a template, "the template is the schema"
+ * (DESIGN §5.5/§6). Walking the same parse the compiler uses, each page-scope
+ * token becomes one field whose control is inferred from where it sits, deduped by
+ * name and labelled. This is the single source of truth the editor's form
+ * generator and the compiler share (DESIGN §6.7).
+ *
+ * Inference is **component-aware**: when a component is used (`<doc file="{x}">`),
+ * the bound field's type comes from how that prop is used *inside* the component,
+ * not from the attribute's position on the usage. A component's prop types are
+ * simply the field types of its own body, so the same derivation resolves them,
+ * recursively, through nested components, with a cycle guard.
+ */
+interface DerivedField {
+    readonly name: string;
+    readonly type: FieldType;
+    readonly label: string;
+    readonly required: boolean;
+    readonly multiline: boolean;
+    readonly help?: string;
+    /** Minimum character length (`data-minlength`); the gate warns when shorter. */
+    readonly minLength?: number;
+    /** Maximum character length (`data-maxlength`); the gate warns when longer. */
+    readonly maxLength?: number;
+    /** A curated multi-reference (a `data-each` loop field). */
+    readonly multiple?: boolean;
+    /** Collection the reference picker is scoped to (`data-pick-from`). */
+    readonly pickFrom?: string;
+}
+/** Author-declared length bounds on a field value (`data-minlength`/`data-maxlength`). */
+interface LengthConstraints {
+    readonly minLength?: number;
+    readonly maxLength?: number;
+}
+declare function deriveFields(template: string, components?: ComponentMap): DerivedField[];
+
+/**
+ * Stamping decisions (PROPOSAL-template-versioning §4.1, PROPOSAL-llm-guardrails §4).
+ * `detectStamp` is pure — given the old and new template sources, it decides whether a
+ * destructive change is taking place and reports the schema delta (added / removed
+ * fields, plus per-token type changes).
+ *
+ * Two destructive shapes (PROPOSAL-llm-guardrails §1, both share the same recovery
+ * story — auto-stamp a snapshot, flag for migration):
+ *
+ * 1. **Token-set asymmetric.** A token removed or renamed. The token *doesn't exist*
+ *    in the new schema, so content authored against it has nowhere to render.
+ * 2. **Token retained, type changed destructively.** The token *still exists*, but
+ *    its inferred type can't losslessly render data authored under the old type
+ *    (`richtext → shorttext` silently escapes HTML; `shorttext → image` reinterprets
+ *    free text as a path). The §4 rule in {@link isDestructiveTypeChange} encodes
+ *    which transitions are destructive vs widening.
+ *
+ * Both flow through `IndexedStore.write`'s auto-stamp path identically — the editor
+ * UI and MCP both see the same recovery affordance, regardless of which destructive
+ * shape triggered it.
+ */
+type TemplateKind = 'template' | 'component';
+/** A field reference (name + inferred type) in the schema delta returned by `computeSchemaDelta`. */
+interface SchemaFieldRef {
+    readonly name: string;
+    readonly type: FieldType;
+}
+/** A type change on a token retained across the edit (PROPOSAL-llm-guardrails §4-§5). */
+interface TypeChange {
+    readonly name: string;
+    readonly from: FieldType;
+    readonly to: FieldType;
+    /** True when the change can't losslessly render data authored under `from`. */
+    readonly destructive: boolean;
+}
+/**
+ * Structured "what changed" report (PROPOSAL-llm-guardrails §5). Returned by
+ * `IndexedStore.write` for template/component writes so callers (MCP, editor UI)
+ * can react without re-deriving themselves. Empty arrays everywhere when an edit
+ * changes only whitespace, comments, or non-token markup.
+ */
+interface SchemaDelta {
+    readonly added: readonly SchemaFieldRef[];
+    readonly removed: readonly SchemaFieldRef[];
+    readonly typeChanged: readonly TypeChange[];
+}
+/** What `detectStamp` learned from comparing two template sources. */
+interface StampDecision {
+    readonly destructive: boolean;
+    /** Tokens present in `oldSource` but absent in `newSource`, sorted for stability. */
+    readonly removedTokens: readonly string[];
+    /** Tokens present in `newSource` but absent in `oldSource`, sorted for stability. */
+    readonly addedTokens: readonly string[];
+    /** Tokens retained but whose inferred type changed (PROPOSAL-llm-guardrails §1). */
+    readonly typeChanged: readonly TypeChange[];
+}
+/** The record `stampSnapshot` returns (and that the write path surfaces as `stamped`). */
+interface StampRecord {
+    /** The base template/component name (no `@v<N>` suffix). */
+    readonly name: string;
+    /** The integer version slot the snapshot occupies. */
+    readonly version: number;
+    /** The full path the snapshot was written to. */
+    readonly snapshotPath: string;
+}
+/**
+ * Whether a field's type change from `from` to `to` can't losslessly render content
+ * authored against `from`. Drives both auto-stamp (destructive triggers a snapshot)
+ * and the validation gate's `content.type-drift` warning per-item.
+ *
+ * The rule (PROPOSAL-llm-guardrails §4) reduces to:
+ * - `anything → richtext` is safe (HTML escapes text fine).
+ * - `richtext → anything else` is destructive (HTML becomes escaped text).
+ * - Free-text → strict date/time is destructive (ISO required, free text won't parse).
+ * - `date ↔ time` is destructive (both ISO but different shapes; values don't transfer).
+ * - Same `valueKind` otherwise is non-destructive (text ↔ text, asset ↔ asset).
+ * - Cross-`valueKind` into text is non-destructive (text representation works).
+ * - Everything else cross-kind is destructive (text → asset/url/authors; asset ↔ url; …).
+ */
+declare function isDestructiveTypeChange(from: FieldType, to: FieldType): boolean;
+/**
+ * Compute the schema delta between two field lists. The richer counterpart to the
+ * token-name diff in {@link detectStamp} — used by `IndexedStore.write` to surface
+ * `schemaDelta` (PROPOSAL-llm-guardrails §5) without re-deriving on the caller side.
+ * Pure; component-aware via `deriveFields`.
+ */
+declare function computeSchemaDelta(oldFields: readonly DerivedField[], newFields: readonly DerivedField[]): SchemaDelta;
+/**
+ * Decide whether the change from `oldSource` to `newSource` is destructive, and report
+ * the schema diff (added / removed / typeChanged). Pure — no I/O. The field-name +
+ * type set is derived via the same `deriveFields` the editor's form generator uses
+ * (so the "schema" the decision is taken against is identical to what the form shows).
+ * Component-aware: fields bound to component props are categorised by how that
+ * component uses them internally, matching the compiler's resolution.
+ */
+declare function detectStamp(oldSource: string, newSource: string, components?: ComponentMap): StampDecision;
+
+/**
+ * The outcome of a {@link WorkingStore.rename}. Clobbering an existing destination, or
+ * renaming a path that does not exist, are *expected* outcomes (a user renames to a name
+ * already in use), so they are returned as data, not thrown (CLAUDE §2): the host maps
+ * them to 409/404. The third case — refusing to rename into or out of the reserved
+ * template-version namespace (`@v<N>` suffix, PROPOSAL §3) — is also returned as data,
+ * not thrown, so the editor and MCP surface a tidy error to the user rather than a 500.
+ */
+type RenameResult = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly reason: 'exists' | 'missing' | 'reserved-version';
+};
+/**
+ * Outcome of a {@link WorkingStore.write}. Returned as data so a caller that cares can
+ * surface the stamp info to the user (the `/api/write` route attaches `stamped` to its
+ * response; MCP's `write_file` passes it through), while a caller that does not care
+ * can ignore the return value entirely (per JavaScript's discard semantics). For
+ * non-template writes and for non-destructive template writes, `stamped` is absent.
+ */
+interface WriteResult {
+    /** Snapshot record when a destructive template/component write triggered auto-stamp. */
+    readonly stamped?: StampRecord;
+    /**
+     * True when the destructive write succeeded but the snapshot copy that should have
+     * preserved the old bytes failed. The new current is in place (site stays
+     * consistent); the snapshot's old bytes are not preserved. Surfaced as a Health
+     * warning (`templates.stamp-incomplete`) so the migration-UX left-pane render
+     * is known to be unavailable for items affected by this particular stamp.
+     */
+    readonly stampIncomplete?: boolean;
+    /**
+     * The schema diff between the old and new bytes for template/component writes
+     * (PROPOSAL-llm-guardrails §5). Present whenever the target is a template or
+     * component and there was a prior version; undefined for content writes, public
+     * files, and brand-new templates. Carries `added`/`removed` (with types) and
+     * `typeChanged` (with per-change `destructive` flag). MCP callers consume this to
+     * react to schema impact without re-deriving; the editor surfaces a summary in the
+     * stamp banner.
+     */
+    readonly schemaDelta?: SchemaDelta;
+}
+/**
+ * The editor's working store (DESIGN §11c): a read {@link ContentSource} for
+ * compile/validate, plus the write/delete/rename the editor content API needs. The
+ * editor API depends on this port, never a concrete store, so the index-backed
+ * {@link IndexedStore} (over an adopter's get/put/delete) and the blob adapter are
+ * interchangeable behind it.
+ */
+interface WorkingStore extends ContentSource {
+    /**
+     * Create or overwrite `path` with raw bytes (binary-correct). Returns a
+     * {@link WriteResult}; callers that do not care about stamp info can ignore it.
+     * Destructive writes to `templates/*.html` / `components/*.html` auto-stamp a
+     * snapshot of the prior bytes before the new bytes land (PROPOSAL §4.1).
+     */
+    write(path: string, contents: Uint8Array): Promise<WriteResult>;
+    /** Delete a file, or a whole directory subtree; a missing path is a no-op. */
+    delete(path: string): Promise<void>;
+    /** Move a file or subtree; refuses to clobber, to rename a missing path, or to
+     *  rename into or out of the reserved template-version namespace (`@v<N>`). */
+    rename(from: string, to: string): Promise<RenameResult>;
+    /**
+     * Manually stamp a snapshot of the current `<kind>/<name>.html` to the next
+     * `<name>@v<N+1>.html` slot (PROPOSAL §4.1 + §6, the manual "Stamp version" action).
+     * Used for the additive-but-want-a-clean-break case the auto-stamp path does not
+     * trigger. Throws if the current file does not exist or `name` is already
+     * versioned. Distinguished from `write` so the store can bypass its own
+     * reserved-path refusal — snapshots are immutable to user-initiated `write`s but
+     * the engine's stamp pathway needs to create them.
+     */
+    stamp(name: string, kind: TemplateKind): Promise<StampRecord>;
+}
+
+/**
+ * The content index (DESIGN §11d): the sorted set of every key in the working store,
+ * the directory listing a flat blob store cannot give cheaply, lifted into one object
+ * we own. Enumeration (the editor tree, compile) reads this, so the adopter's store
+ * stays get/put/delete with no `list`. Persisted under a reserved key with a fixed-size
+ * backup ring for integrity.
+ */
+interface ContentIndex {
+    /** Monotonic, bumped on every save; orders the backup ring during recovery. */
+    readonly version: number;
+    /** Every key that exists, sorted and de-duplicated (deterministic, CLAUDE §2). */
+    readonly keys: readonly string[];
+    /** Checksum over version + keys, so a corrupt stored index is caught on read. */
+    readonly checksum: string;
+}
+/** Reserved key prefix for the index and its backups; excluded from enumeration. */
+declare const RESERVED_PREFIX = ".nanoesis/";
+/** The empty index of a fresh store: version 0, no keys. */
+declare function emptyIndex(): ContentIndex;
+/**
+ * Load the index, recovering through the backup ring if the live copy is missing or
+ * corrupt (DESIGN §11d): the highest valid version among the ring slots wins. Returns
+ * the empty index when nothing valid is found, a fresh store, or the accepted residual
+ * case where the live index and every backup are lost (the files still exist by key,
+ * but cannot be enumerated until something rewrites the index).
+ */
+declare function loadIndex(store: BlobStore): Promise<ContentIndex>;
+/**
+ * Write a new index whose keys are `nextKeys`, backing up the one it replaces first
+ * (DESIGN §11d). The previous index goes into its ring slot (`version % ring`, oldest
+ * overwritten), then the new index is written to the live key, a constant two writes
+ * per save regardless of ring size. Returns the new index (the caller's next `prev`).
+ */
+declare function saveIndex(store: BlobStore, prev: ContentIndex, nextKeys: readonly string[]): Promise<ContentIndex>;
+/** What a {@link reconcileIndex} did, for a maintenance UI/CLI and the startup signal. */
+interface ReconcileResult {
+    /** The index after reconciling (the prior one unchanged when nothing differed). */
+    readonly index: ContentIndex;
+    /** Keys now in the index that the prior index lacked (orphaned blobs, recovered). */
+    readonly added: readonly string[];
+    /** Keys the prior index held that no longer exist in the store (stale entries dropped). */
+    readonly removed: readonly string[];
+}
+/**
+ * Rebuild the index from the store's *actual* keys (DESIGN §11d): the safety net for a
+ * store that got files by a path that bypassed the index, where the files are present
+ * by key but unenumerable. The engine cannot list a {@link BlobStore} (none is required
+ * to, §11c), so the caller supplies the real key set, an adapter that *can* enumerate
+ * (e.g. `BlobContainer.list`) provides it; the rebuild stays pure index logic here.
+ *
+ * The reserved namespace is never indexed (the index is not its own content). When the
+ * resulting key set matches the existing index this is a no-op, no write, no version
+ * bump, so reconciling a healthy store is cheap and idempotent.
+ */
+declare function reconcileIndex(store: BlobStore, actualKeys: readonly string[]): Promise<ReconcileResult>;
+
+/**
+ * A {@link ContentSource} backed by the content index (DESIGN §11d) over a
+ * {@link BlobStore}: enumeration (`list`/`exists`) is synthesised from the index's key
+ * set, reads go straight to `get`. This is the working store the editor and compile run
+ * against once an adopter provides only get/put/delete, every existing `list` caller is
+ * unchanged because it still sees a `ContentSource`.
+ *
+ * Mutations (`write`/`delete`/`rename`) write the file(s) first, then the index
+ * (content-first, §11d), keeping the in-memory copy in step so reads on this instance
+ * reflect the change at once. The index is only rewritten when the key *set* changes, an
+ * overwrite of an existing key is a single `put`.
+ *
+ * Construction does no I/O: the index loads (and recovers through the backup ring, §11d)
+ * lazily on the first enumeration or mutation, so a host can wire the store synchronously.
+ *
+ * The prefix-synthesis below mirrors {@link InMemoryContentSource} exactly (a cross-check
+ * test pins them together); the two are interchangeable implementations of the port.
+ */
+declare class IndexedStore implements WorkingStore {
+    private readonly store;
+    private index;
+    private loading;
+    /**
+     * Per-instance mutex (DESIGN §11d): every mutation (`write`/`delete`/`rename`/`reconcile`)
+     * runs through {@link serializeMutation}, which chains onto the previous mutation's
+     * completion. Without it, two concurrent mutations both read the cached `this.index`,
+     * each compute their "next" key set from that stale snapshot, and the second
+     * `saveIndex` clobbers the first — the file writes land in blob, but the index keeps
+     * stale references or loses fresh ones (the "I deleted it and it's still there" or
+     * "I added it and it didn't appear" bugs surfaced dogfooding the marketing site,
+     * 2026-05-28). Reads (`list`/`exists`/`readBytes`) are *not* serialised; an
+     * in-flight mutation simply means a reader sees the pre-mutation index, eventually
+     * consistent and safe. Crashes inside `work()` release the lock so a single failure
+     * does not deadlock subsequent operations.
+     */
+    private mutationLock;
+    constructor(store: BlobStore);
+    /** The index, loaded once on first need and cached (mutations replace the cached copy). */
+    private loaded;
+    private serializeMutation;
+    list(dir: string): Promise<readonly DirEntry[]>;
+    readText(path: string): Promise<string>;
+    readBytes(path: string): Promise<Uint8Array>;
+    exists(path: string): Promise<boolean>;
+    /**
+     * Create or overwrite `key`. The index is rewritten only when `key` is new (an
+     * overwrite leaves the key set unchanged, so editing an item is a single `put`).
+     *
+     * **Auto-stamp** (PROPOSAL §4.1): a destructive write to a template or component
+     * path (one that removes a token from the existing source) snapshots the prior
+     * bytes to `<base>@v<N+1>.html` before the new bytes land. Order is
+     * **current first, snapshot second** (§16.3): if the snapshot copy fails after
+     * the current write succeeded, the site stays consistent — only the migration
+     * UX's left-pane comparison is unavailable for items affected by this stamp,
+     * surfaced as `templates.stamp-incomplete`.
+     *
+     * Direct writes to a reserved-version path are refused (snapshots are
+     * immutable; the user retires them via `delete`, not by overwriting them).
+     */
+    write(key: string, bytes: Uint8Array): Promise<WriteResult>;
+    /**
+     * Manually stamp a snapshot of the current `<kind>/<name>.html` to the next available
+     * `<name>@v<N+1>.html` slot. Uses the same internal `this.store.put` pathway the
+     * auto-stamp uses (so the public `write`'s reserved-version refusal doesn't apply),
+     * and runs under the mutation mutex so a concurrent destructive auto-stamp can't
+     * race with a manual stamp.
+     */
+    stamp(name: string, kind: TemplateKind): Promise<StampRecord>;
+    /**
+     * Delete a file, or a whole directory subtree (every key under `key/`). Idempotent: a
+     * path the index does not know is still deleted from the store (clearing an orphan),
+     * and deleting nothing is a no-op.
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Move/rename a file, or a whole directory subtree (every key under `from/` is remapped
+     * under `to/`). Clobbering an existing destination, or renaming a missing path, are
+     * returned as data (`ok: false`), not thrown (CLAUDE §2), the same contract the host's
+     * `/api/rename` enforces. (Mutating the reserved namespace is a programmer error and
+     * still throws.)
+     */
+    rename(from: string, to: string): Promise<RenameResult>;
+    /**
+     * Rebuild this store's index from the *actual* keys the underlying store holds (DESIGN
+     * §11d), recovering files that arrived by a path that bypassed the index. A
+     * {@link BlobStore} cannot enumerate itself, so the caller supplies the real key set
+     * from an adapter that can (e.g. `BlobContainer.list`). Unlike calling
+     * {@link reconcileIndex} on a fresh store, this also refreshes the cached in-memory
+     * index, so this live instance sees the recovered files immediately.
+     */
+    reconcile(actualKeys: readonly string[]): Promise<ReconcileResult>;
+}
+
 /**
  * Redirect generation (DESIGN §9). A move or slug rename changes a page's URL;
  * internal `ref:` links auto-update, but external/bookmarked/indexed URLs would
@@ -697,27 +922,6 @@ declare const DOCUMENT_SHELL = "document";
  */
 declare function loadDocumentShell(source: ContentSource, templatesDir?: string): Promise<string | undefined>;
 
-/**
- * The field-type registry (DESIGN §6.7). Field types and their rules are defined
- * *once* here and shared by the compiler, the editor's form generator, and (later)
- * Monaco's IntelliSense. This is the OCP extension point (CLAUDE.md §3): adding a
- * field type means adding an entry here, never editing a switch in the compiler or
- * the inference cascade.
- */
-type FieldType = 'image' | 'file' | 'url' | 'email' | 'phone' | 'date' | 'time' | 'code' | 'richtext' | 'authors' | 'text' | 'shorttext';
-/** How a resolved value is placed into output, the compiler reads this, never the type name. */
-type ValueKind = 'text' | 'html' | 'url' | 'asset' | 'authors';
-interface FieldTypeDef {
-    readonly type: FieldType;
-    readonly valueKind: ValueKind;
-    /** Default editor control hint, consumed by the form generator (DESIGN §7). */
-    readonly control: string;
-    readonly multiline: boolean;
-}
-declare const FIELD_TYPES: Readonly<Record<FieldType, FieldTypeDef>>;
-declare function isFieldType(value: string): value is FieldType;
-declare function valueKindOf(type: FieldType): ValueKind;
-
 /**
  * Contextual token inference (DESIGN §6.2). A token's control type is inferred from
  * *where it sits*, via a precedence cascade:
@@ -768,6 +972,95 @@ declare function findTokens(input: string): TokenRef[];
 /** If the trimmed input is exactly one token, return it; otherwise null. */
 declare function wholeValueToken(input: string): TokenRef | null;
 
+/**
+ * Versioned-name conventions for templates + components (PROPOSAL §3, §2.9). A snapshot
+ * lives at the same path as its current sibling with an `@v<N>` suffix appended to the
+ * base name, e.g. `templates/article.html` (current) and `templates/article@v1.html`
+ * (snapshot). The suffix is reserved: the engine refuses to mutate paths into or out of
+ * the form, so users can't accidentally collide with it.
+ *
+ * Canonical form is strict: `@v` followed by a positive base-10 integer with no leading
+ * zeros, exactly one suffix per name. `@v01`, `@v`, `@v1@v2` are not versions, just
+ * unusually-named bare templates — the helper returns false rather than try to repair.
+ */
+/** True when `name` parses as `<base>@v<N>` in canonical form (no nesting). */
+declare function isVersionedTemplateName(name: string): boolean;
+/** The base name without any `@v<N>` suffix (returns the input unchanged if unversioned). */
+declare function baseTemplateName(name: string): string;
+/** The numeric version, or `null` if `name` is not in canonical versioned form. */
+declare function versionNumber(name: string): number | null;
+/** Build the canonical snapshot name for `base` at `version`. Throws on invalid input. */
+declare function snapshotName(base: string, version: number): string;
+/**
+ * The next version slot to allocate, given the names of every snapshot already in play
+ * (typically the result of enumerating siblings of the current template). One higher than
+ * the maximum existing version; 1 if no snapshots exist. Gaps are preserved (deleting a
+ * snapshot does not reuse its number) — the user can see gaps in their tree but the
+ * sequence remains monotonic, matching the proposal §16.5 decision.
+ */
+declare function nextVersionNumber(existingNames: readonly string[]): number;
+/**
+ * True when `path` matches the canonical snapshot form for a template or component (under
+ * `templates/` or `components/`, ending in `.html`, base name has an `@v<N>` suffix).
+ * Used by {@link IndexedStore} to refuse renames into or out of the reserved namespace.
+ *
+ * Matching paths in other partitions (content, public) are *not* reserved — users can
+ * name content files however they like; the engine only owns the convention inside the
+ * partitions whose tokens it interprets.
+ */
+declare function isReservedVersionedPath(path: string): boolean;
+
+/**
+ * Template-version migration helpers (PROPOSAL-template-versioning §4.3, §6).
+ *
+ * `pendingMigrations` enumerates content items whose JSON has fields that don't match
+ * the schema of their bound template — orphan fields (data the template no longer
+ * renders) or missing required fields (template wants but JSON is empty). Drift is
+ * computed per-item against the item's *bound* template (current name or snapshot pin),
+ * so pinned items are still flagged if the pin itself has drift.
+ *
+ * `bestFitSnapshot` picks the most recent snapshot of a base whose tokens are a
+ * superset of an item's fields — used by the migration UX's left-pane render to show
+ * "this is how the item rendered before."
+ *
+ * `applyMigration` rewrites an item JSON per a user-supplied resolution (drop / rename
+ * / keep / fill). Idempotent in the sense that a no-op resolution leaves the JSON
+ * byte-identical; non-resolved keys are preserved.
+ */
+interface PendingMigrationItem {
+    /** Full content path (e.g. "content/blog/post.json"). */
+    readonly path: string;
+    /** The item's `template` field — e.g. "article" or "article@v1". */
+    readonly boundTemplate: string;
+    /** The base name (no `@v<N>` suffix). For pinned items this is the family. */
+    readonly currentTemplate: string;
+    /** Fields in JSON that the bound template doesn't render. */
+    readonly orphanFields: readonly string[];
+    /** Required fields the bound template wants but the JSON's `fields` is empty for. */
+    readonly missingRequiredFields: readonly string[];
+    /** Best-fit snapshot name (e.g. "article@v2") for the migration UX's left pane,
+     *  or `null` when no snapshot's tokens cover the item's fields. */
+    readonly bestFitSnapshot: string | null;
+}
+interface PendingMigrations {
+    readonly items: readonly PendingMigrationItem[];
+    /** Items grouped by `currentTemplate` for the workspace's list view. */
+    readonly byTemplate: ReadonlyMap<string, readonly PendingMigrationItem[]>;
+}
+interface MigrationResolution {
+    /** Orphan field names to remove from the item JSON. */
+    readonly drop: readonly string[];
+    /** Map of orphan field → current-template field to copy the value into. */
+    readonly rename: Readonly<Record<string, string>>;
+    /** Orphan field names to leave in the item JSON (advisory; gate stops warning). */
+    readonly keep: readonly string[];
+    /** Map of current-template field → value to fill (for missing required fields). */
+    readonly fill: Readonly<Record<string, string>>;
+}
+declare function pendingMigrations(store: WorkingStore): Promise<PendingMigrations>;
+declare function bestFitSnapshot(store: WorkingStore, base: string, itemFieldNames: readonly string[]): Promise<string | null>;
+declare function applyMigration(store: WorkingStore, itemPath: string, resolution: MigrationResolution): Promise<void>;
+
 /**
  * The authoring reference (DESIGN §14). A single, generated description of the whole
  * template surface, every field type, annotation, loop, and token, that powers three
@@ -853,42 +1146,6 @@ declare function buildRss(entries: readonly PageEntry[], options: RssOptions): A
  */
 declare function buildContentIndex(entries: readonly PageEntry[]): Artifact;
 
-/**
- * Derive the editor's form from a template, "the template is the schema"
- * (DESIGN §5.5/§6). Walking the same parse the compiler uses, each page-scope
- * token becomes one field whose control is inferred from where it sits, deduped by
- * name and labelled. This is the single source of truth the editor's form
- * generator and the compiler share (DESIGN §6.7).
- *
- * Inference is **component-aware**: when a component is used (`<doc file="{x}">`),
- * the bound field's type comes from how that prop is used *inside* the component,
- * not from the attribute's position on the usage. A component's prop types are
- * simply the field types of its own body, so the same derivation resolves them,
- * recursively, through nested components, with a cycle guard.
- */
-interface DerivedField {
-    readonly name: string;
-    readonly type: FieldType;
-    readonly label: string;
-    readonly required: boolean;
-    readonly multiline: boolean;
-    readonly help?: string;
-    /** Minimum character length (`data-minlength`); the gate warns when shorter. */
-    readonly minLength?: number;
-    /** Maximum character length (`data-maxlength`); the gate warns when longer. */
-    readonly maxLength?: number;
-    /** A curated multi-reference (a `data-each` loop field). */
-    readonly multiple?: boolean;
-    /** Collection the reference picker is scoped to (`data-pick-from`). */
-    readonly pickFrom?: string;
-}
-/** Author-declared length bounds on a field value (`data-minlength`/`data-maxlength`). */
-interface LengthConstraints {
-    readonly minLength?: number;
-    readonly maxLength?: number;
-}
-declare function deriveFields(template: string, components?: ComponentMap): DerivedField[];
-
 /**
  * Static analysis of a template's structure, used by the validation gate, the
  * media phase, and (later) the editor. Extracts the signals downstream needs:
@@ -1318,7 +1575,15 @@ type Severity = 'error' | 'warning' | 'info';
  * coarse and stable — adding adapter-specific categories ("kv", "cloudflare", …) would
  * couple the engine to specific cloud concepts, which is what we are avoiding.
  */
-type Source = 'content' | 'index' | 'auth' | 'connectivity';
+type Source = 'content' | 'index' | 'auth' | 'connectivity' | 'templates';
+/**
+ * Arguments a repair handle carries through to its `Repair.run`. Plain string map so the
+ * shape serialises cleanly across the API boundary; repairs that need richer types parse
+ * them inside `run`. Per-item context (an item path, a snapshot name) lives here when one
+ * generic repair handles many findings (e.g. `templates.rebind-item-to-current` rebinds
+ * whichever path it's given).
+ */
+type RepairArgs = Readonly<Record<string, string>>;
 /**
  * One thing the diagnostics gate found wrong (or noteworthy). Shape mirrors the
  * validation gate's {@link Diagnostic} type so a future merger is one step.
@@ -1336,6 +1601,8 @@ interface Finding {
     readonly repair?: {
         readonly id: string;
         readonly label: string;
+        /** Per-finding context (e.g. an item path) the registered repair needs to run. */
+        readonly args?: RepairArgs;
     };
 }
 /**
@@ -1359,11 +1626,12 @@ interface Diagnostic {
 /**
  * One in-place fix. Idempotent: calling `run` twice does not double-write. The host
  * re-runs the diagnostic set after a repair to refresh the UI, so repairs don't have to
- * return findings themselves.
+ * return findings themselves. `args` carries per-finding context from the {@link Finding}
+ * that surfaced the repair handle (e.g. the item path a "rebind to current" repair acts on).
  */
 interface Repair {
     readonly id: string;
-    run(deps: DiagnoseDeps): Promise<void>;
+    run(deps: DiagnoseDeps, args: RepairArgs): Promise<void>;
 }
 
 /**
@@ -1384,11 +1652,12 @@ interface DiagnosticRegistry {
     addRepair(repair: Repair): void;
     /** Run every registered diagnostic in order; concatenate their findings. */
     runAll(deps: DiagnoseDeps): Promise<readonly Finding[]>;
-    /** Run the named repair, then return a fresh `runAll` so the UI re-renders. */
-    runRepair(id: string, deps: DiagnoseDeps): Promise<readonly Finding[]>;
+    /** Run the named repair with optional per-finding args, then return a fresh `runAll`
+     *  so the UI re-renders. Args default to `{}` when the repair needs none. */
+    runRepair(id: string, deps: DiagnoseDeps, args?: RepairArgs): Promise<readonly Finding[]>;
 }
 declare function createDiagnosticRegistry(): DiagnosticRegistry;
 
 declare const workingStoreRoundTripDiagnostic: Diagnostic;
 
-export { type Artifact, type ArtifactSink, type AuthEndpoints, type AuthResult, type AuthorDirectory, type AuthorEntry, type AuthorOption, type AuthorRef, type AuthoringReference, type BlobStore, type BoundItem, type ChangePasswordRequest, type ChangePasswordSuccess, type CollectionConfig, type CollectionQuery, type CompileInput, type CompilePageOptions, type CompileSiteOptions, type CompiledPage, type ComponentMap, type ContentIndex, type ContentItem, ContentParseError, type ContentSource, type CreateTokenSuccess, type CreateUserRequest, DEFAULT_DIRS, DOCUMENT_SHELL, type DerivedField, type DiagnoseDeps, type Severity as DiagnoseSeverity, type Source as DiagnoseSource, type Diagnostic$1 as Diagnostic, type Diagnostic as DiagnosticCheck, type DiagnosticRegistry, type DirEntry, type DirNode, type EncodeRequest, type EncodedImage, type EncodedVariant, type EntryKind, FIELD_TYPES, type FieldPrimitive, type FieldRecord, type FieldType, type FieldTypeDef, type FieldValue, type Finding, type IdentityProvider, type ImageEncoder, type ImageFormat, type ImageInfo, InMemoryArtifactSink, InMemoryBlobStore, InMemoryContentSource, IndexedStore, type ItemNode, type LengthConstraints, type LoginRequest, type LoginSuccess, type MediaResolver, type PageEntry, type PreBuildHook, type Principal, type PublishOptions, type PublishResult, type PublishSummary, type PurgeService, RESERVED_PREFIX, type ReconcileResult, type RedirectRule, type ReferenceContext, type ReferenceEntry, type ReferenceSection, type RefreshSuccess, type RenameResult, type Repair, type ResetPasswordRequest, type ResolveContext, type Role, type RssOptions, type Scope, type Severity$1 as Severity, type SiteConfig, type SortFile, type TemplateAnalysis, type TokenContext, type TokenRef, type TreeNode, type UpdateUserRequest, type UserAdminEndpoints, type UserSummary, type ValidationResult, type ValueKind, type WorkingStore, analyzeTemplate, buildAuthoringReference, buildContentIndex, buildPictureMarkup, buildRedirects, buildResolveContext, buildRss, buildSitemap, canEdit, compilePage, compileSite, compileTemplate, contentHash, contentTypeFor, createDiagnosticRegistry, deriveFields, emptyIndex, escapeHtmlAttribute, escapeHtmlText, escapeJsonStringContent, findTokens, hasRole, humanize, inferControl, isFieldType, joinAuthors, loadComponentScripts, loadComponentStyles, loadComponents, loadContentTree, loadDocumentShell, loadIndex, loadRedirects, loadSiteConfig, loadTemplate, noopPurgeService, outputPathForItem, parseContentItem, parseRedirects, parseSortFile, processImage, publishSite, reconcileIndex, renderAuthors, renderReferenceMarkdown, sanitizeUrl, saveIndex, slugify, textContent, toAuthorRefs, urlForItem, validateSite, valueKindOf, wholeValueToken, workingStoreRoundTripDiagnostic };
+export { type Artifact, type ArtifactSink, type AuthEndpoints, type AuthResult, type AuthorDirectory, type AuthorEntry, type AuthorOption, type AuthorRef, type AuthoringReference, type BlobStore, type BoundItem, type ChangePasswordRequest, type ChangePasswordSuccess, type CollectionConfig, type CollectionQuery, type CompileInput, type CompilePageOptions, type CompileSiteOptions, type CompiledPage, type ComponentMap, type ContentIndex, type ContentItem, ContentParseError, type ContentSource, type CreateTokenSuccess, type CreateUserRequest, DEFAULT_DIRS, DOCUMENT_SHELL, type DerivedField, type DiagnoseDeps, type Severity as DiagnoseSeverity, type Source as DiagnoseSource, type Diagnostic$1 as Diagnostic, type Diagnostic as DiagnosticCheck, type DiagnosticRegistry, type DirEntry, type DirNode, type EncodeRequest, type EncodedImage, type EncodedVariant, type EntryKind, FIELD_TYPES, type FieldPrimitive, type FieldRecord, type FieldType, type FieldTypeDef, type FieldValue, type Finding, type IdentityProvider, type ImageEncoder, type ImageFormat, type ImageInfo, InMemoryArtifactSink, InMemoryBlobStore, InMemoryContentSource, IndexedStore, type ItemNode, type LengthConstraints, type LoginRequest, type LoginSuccess, type MediaResolver, type MigrationResolution, type PageEntry, type PendingMigrationItem, type PendingMigrations, type PreBuildHook, type Principal, type PublishOptions, type PublishResult, type PublishSummary, type PurgeService, RESERVED_PREFIX, type ReconcileResult, type RedirectRule, type ReferenceContext, type ReferenceEntry, type ReferenceSection, type RefreshSuccess, type RenameResult, type Repair, type RepairArgs, type ResetPasswordRequest, type ResolveContext, type Role, type RssOptions, type SchemaDelta, type SchemaFieldRef, type Scope, type Severity$1 as Severity, type SiteConfig, type SortFile, type StampDecision, type StampRecord, type TemplateAnalysis, type TemplateKind, type TokenContext, type TokenRef, type TreeNode, type TypeChange, type UpdateUserRequest, type UserAdminEndpoints, type UserSummary, type ValidationResult, type ValueKind, type WorkingStore, analyzeTemplate, applyMigration, baseTemplateName, bestFitSnapshot, buildAuthoringReference, buildContentIndex, buildPictureMarkup, buildRedirects, buildResolveContext, buildRss, buildSitemap, canEdit, compilePage, compileSite, compileTemplate, computeSchemaDelta, contentHash, contentTypeFor, createDiagnosticRegistry, deriveFields, detectStamp, emptyIndex, escapeHtmlAttribute, escapeHtmlText, escapeJsonStringContent, findTokens, hasRole, humanize, inferControl, isDestructiveTypeChange, isFieldType, isReservedVersionedPath, isVersionedTemplateName, joinAuthors, loadComponentScripts, loadComponentStyles, loadComponents, loadContentTree, loadDocumentShell, loadIndex, loadRedirects, loadSiteConfig, loadTemplate, nextVersionNumber, noopPurgeService, outputPathForItem, parseContentItem, parseRedirects, parseSortFile, pendingMigrations, processImage, publishSite, reconcileIndex, renderAuthors, renderReferenceMarkdown, sanitizeUrl, saveIndex, slugify, snapshotName, textContent, toAuthorRefs, urlForItem, validateSite, valueKindOf, versionNumber, wholeValueToken, workingStoreRoundTripDiagnostic };