dna-sdk 0.1.0

package/dist/kernel/kind_base.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Kind base class with sensible defaults.
+ *
+ * 1:1 parity with python/dna/kernel/kind_base.py.
+ *
+ * Cuts the boilerplate that every Kind implementation duplicated.
+ * Subclassing pattern:
+ *
+ *     class AssetKind extends KindBase {
+ *       readonly apiVersion = "github.com/ruinosus/dna/asset/v1";
+ *       readonly kind = "Asset";
+ *       readonly alias = "asset-asset";
+ *       readonly storage = StorageDescriptorImpl.bundle(
+ *         "assets", "ASSET.md",
+ *       );
+ *       readonly asciiIcon = "🖼️";
+ *       readonly displayLabel = "Assets";
+ *     }
+ *
+ * That's the minimum-viable Kind. Everything else inherits sensible
+ * defaults from this base.
+ *
+ * The base is **purely additive**: existing Kind impls keep working
+ * as plain objects (they declare every field explicitly). Migrating
+ * a Kind to `KindBase` is a strict simplification — no API changes.
+ *
+ * Mandatory overrides (no default available):
+ *   - `apiVersion`  — globally unique namespace string
+ *   - `kind`        — CamelCase Kind name
+ *   - `alias`       — globally unique alias
+ *   - `storage`     — StorageDescriptor (call StorageDescriptorImpl.bundle/yaml/root)
+ *
+ * Everything else has defaults that match the most common case.
+ */
+import Ajv from "ajv";
+import type { Document } from "./document.js";
+import type { KindPort, LayerPolicy, StorageDescriptor } from "./protocols.js";
+/** Default volatile spec fields shared by every Kind (s-sync-s1). Exported
+ *  so DeclarativeKindPort (meta.ts) unions the SAME set instead of
+ *  re-hardcoding it — twin of Python's KindBase.VOLATILE_SPEC_FIELDS
+ *  class attribute (C1 review carry-over). */
+export declare const DEFAULT_VOLATILE_SPEC_FIELDS: ReadonlySet<string>;
+/** JSON Schema `format` values that appear in real Kind schemas across the
+ *  repo (builtin kind descriptors, KindDefinition YAMLs, tests). ajv v8 ships
+ *  ZERO built-in formats, and the Python twin (`jsonschema`) treats `format`
+ *  as annotation-only by default — so parity is "formats never validate".
+ *  Registering each as `true` keeps exactly that semantics (always-valid
+ *  annotation) while silencing ajv's per-compile
+ *  `unknown format "X" ignored in schema` warning (s-public-ci).
+ *  NOTE: deliberately NOT ajv-formats — that would start rejecting values and
+ *  break Py↔TS validation parity. */
+export declare const SCHEMA_ANNOTATION_FORMATS: readonly string[];
+/** Canonical Ajv factory for the SDK — every `new Ajv(...)` in the kernel
+ *  goes through here so options stay in one place. strict:false accepts the
+ *  lenient JSON Schema shapes users author in YAML. */
+export declare function createAjv(): Ajv;
+export declare abstract class KindBase implements Omit<KindPort, "apiVersion" | "kind" | "alias" | "storage"> {
+    readonly origin?: string;
+    readonly isPromptTarget: boolean;
+    readonly promptTargetPriority: number;
+    readonly flattenInContext: boolean;
+    get isRoot(): boolean;
+    readonly isRuntimeArtifact: boolean;
+    readonly plane: "record" | "composition";
+    readonly isSchemaAffecting: boolean;
+    readonly isOverlayable: boolean;
+    readonly scopeInheritable: boolean;
+    readonly isCatalogIdentity: boolean;
+    readonly embedFields: string[] | null;
+    readonly validateOnParse: boolean;
+    private _parseValidator?;
+    private _parseAjv?;
+    readonly docs?: string;
+    readonly descriptionFallbackField?: string;
+    readonly graphStyle?: {
+        fill: string;
+        stroke: string;
+        textColor: string;
+    };
+    readonly asciiIcon?: string;
+    readonly displayLabel?: string;
+    readonly uiSchema?: Record<string, Record<string, unknown>>;
+    readonly markerSharedAllowed: boolean;
+    readonly volatileSpecFields: ReadonlySet<string>;
+    depFilters(): Record<string, string> | null;
+    dependencies(): Record<string, string> | null;
+    schema(): Record<string, unknown> | null;
+    getDefaultAgentName(_doc: Document): string | null;
+    getLayerPolicies(_doc: Document): Record<string, LayerPolicy | string> | null;
+    parse(raw: Record<string, unknown>): unknown;
+    /** Validate `raw.spec` against `schema()` (ajv). No-op when no schema.
+     *  Throws a clear error for a malformed spec (s-typed-models-for-dict-kinds). */
+    private _validateSpec;
+    describe(_doc: Document): string | null;
+    summary(doc: Document): Record<string, unknown> | null;
+    promptTemplate(): string | null;
+    protected canonicalSpec(spec: Record<string, unknown>): Record<string, unknown>;
+    /** Stable SHA-256 of the doc's authored identity — basis for source
+     *  diff/sync. Invariant to key order, formatting, volatile stamps, and
+     *  instruction_file-vs-inline; sensitive to real content. */
+    canonicalDigest(doc: Document): string;
+    abstract readonly apiVersion: string;
+    abstract readonly kind: string;
+    abstract readonly alias: string;
+    abstract readonly storage: StorageDescriptor;
+}

package/dist/kernel/kind_base.js

@@ -0,0 +1,244 @@
+/**
+ * Kind base class with sensible defaults.
+ *
+ * 1:1 parity with python/dna/kernel/kind_base.py.
+ *
+ * Cuts the boilerplate that every Kind implementation duplicated.
+ * Subclassing pattern:
+ *
+ *     class AssetKind extends KindBase {
+ *       readonly apiVersion = "github.com/ruinosus/dna/asset/v1";
+ *       readonly kind = "Asset";
+ *       readonly alias = "asset-asset";
+ *       readonly storage = StorageDescriptorImpl.bundle(
+ *         "assets", "ASSET.md",
+ *       );
+ *       readonly asciiIcon = "🖼️";
+ *       readonly displayLabel = "Assets";
+ *     }
+ *
+ * That's the minimum-viable Kind. Everything else inherits sensible
+ * defaults from this base.
+ *
+ * The base is **purely additive**: existing Kind impls keep working
+ * as plain objects (they declare every field explicitly). Migrating
+ * a Kind to `KindBase` is a strict simplification — no API changes.
+ *
+ * Mandatory overrides (no default available):
+ *   - `apiVersion`  — globally unique namespace string
+ *   - `kind`        — CamelCase Kind name
+ *   - `alias`       — globally unique alias
+ *   - `storage`     — StorageDescriptor (call StorageDescriptorImpl.bundle/yaml/root)
+ *
+ * Everything else has defaults that match the most common case.
+ */
+import { createHash } from "node:crypto";
+import Ajv from "ajv";
+/** Default volatile spec fields shared by every Kind (s-sync-s1). Exported
+ *  so DeclarativeKindPort (meta.ts) unions the SAME set instead of
+ *  re-hardcoding it — twin of Python's KindBase.VOLATILE_SPEC_FIELDS
+ *  class attribute (C1 review carry-over). */
+export const DEFAULT_VOLATILE_SPEC_FIELDS = new Set([
+    "updated_at",
+    "version",
+    "created_at",
+]);
+/** JSON Schema `format` values that appear in real Kind schemas across the
+ *  repo (builtin kind descriptors, KindDefinition YAMLs, tests). ajv v8 ships
+ *  ZERO built-in formats, and the Python twin (`jsonschema`) treats `format`
+ *  as annotation-only by default — so parity is "formats never validate".
+ *  Registering each as `true` keeps exactly that semantics (always-valid
+ *  annotation) while silencing ajv's per-compile
+ *  `unknown format "X" ignored in schema` warning (s-public-ci).
+ *  NOTE: deliberately NOT ajv-formats — that would start rejecting values and
+ *  break Py↔TS validation parity. */
+export const SCHEMA_ANNOTATION_FORMATS = [
+    "date-time",
+    "date",
+    "email",
+    "markdown",
+];
+/** Canonical Ajv factory for the SDK — every `new Ajv(...)` in the kernel
+ *  goes through here so options stay in one place. strict:false accepts the
+ *  lenient JSON Schema shapes users author in YAML. */
+export function createAjv() {
+    const formats = {};
+    for (const f of SCHEMA_ANNOTATION_FORMATS)
+        formats[f] = true;
+    return new Ajv({ strict: false, allErrors: true, formats });
+}
+/** Stable, sorted-key, compact JSON — twin of Python's
+ *  `json.dumps(sort_keys=True, separators=(",",":"))`. Logically-equal objects
+ *  serialize identically regardless of insertion order (s-sync-s1). */
+function _stableStringify(value) {
+    if (value === null || typeof value !== "object") {
+        return JSON.stringify(value) ?? "null";
+    }
+    if (Array.isArray(value)) {
+        return "[" + value.map(_stableStringify).join(",") + "]";
+    }
+    const obj = value;
+    const keys = Object.keys(obj).sort();
+    return ("{" +
+        keys.map((k) => JSON.stringify(k) + ":" + _stableStringify(obj[k])).join(",") +
+        "}");
+}
+export class KindBase {
+    // ---- Identity (subclasses MUST set these) -----------------------
+    // abstract apiVersion: string;
+    // abstract kind: string;
+    // abstract alias: string;
+    // abstract storage: StorageDescriptor;
+    // ---- Optional identity ------------------------------------------
+    origin;
+    // ---- Behavior flags (sensible defaults) -------------------------
+    // ``isRoot`` was an explicit boolean Phase 0–15. Phase 16 derives
+    // it from the storage descriptor: a Kind is the scope root iff its
+    // storage pattern is ROOT (single file at scope root). GenomeKind
+    // is the only one today; the getter keeps the existing read API
+    // (``kp.isRoot``) working for all consumers.
+    isPromptTarget = false;
+    promptTargetPriority = 0;
+    flattenInContext = false;
+    get isRoot() {
+        const storage = this.storage;
+        return storage?.pattern === "root";
+    }
+    // See KindPort.isRuntimeArtifact in protocols.ts. Override to `true`
+    // only on Kinds whose documents are generated by runtime workflows
+    // (EvalRun, Finding, Evidence, AssessmentRun, ...).
+    isRuntimeArtifact = false;
+    // ---- Two-planes (spec 2026-06-09-kinds-two-planes-design) --------
+    // "composition" (default) — participates in agent composition.
+    // "record" — pure typed document; writes never invalidate scope
+    // caches (Python kernel branches on this; TS has no cache machinery,
+    // the attr exists for 1:1 parity + the registration lint below).
+    plane = "composition";
+    // ---- Kernel classification (s-kernel-kindport-classification-attrs) ----
+    // The kernel DERIVES its classification sets from these per-Kind attributes
+    // instead of matching hardcoded Kind names. 1:1 parity with the Python
+    // KindBase. Defaults match the common case; the few Kinds that differ override.
+    // `isSchemaAffecting`: writing this Kind invalidates the schema cache.
+    isSchemaAffecting = false;
+    // `isOverlayable`: a tenant overlay may fork this Kind. False only for the
+    // structural bootstrap Kinds (scope identity / schema / policy).
+    isOverlayable = true;
+    // `scopeInheritable`: documents inherit across scopes by default. False for the
+    // per-scope SDLC ledger + structural Kinds.
+    scopeInheritable = true;
+    // `isCatalogIdentity`: writing a doc of this Kind changes the Catalog
+    // tier's scope/mandatory set (s-write-path-despecialize — replaces the
+    // hardcoded `kind == "Genome"` check in the Python write path; the TS
+    // kernel keeps no catalog cache, the attribute exists for 1:1 Kind
+    // metadata parity). True only on the scope-root identity Kind.
+    isCatalogIdentity = false;
+    // ---- Embedding source fields (F3 spec D4) ------------------------
+    // Fields of `spec` that compose the doc's embedding text. null =
+    // not embeddable (or still covered by the legacy EMBEDDABLE_KINDS
+    // frozenset in harness-shared). Declared here so the D4 derivation
+    // covers still-class Kinds as well as descriptor-synthesized ports.
+    embedFields = null;
+    // ---- Validation (s-typed-models-for-dict-kinds) -----------------
+    // When true, parse() validates the doc's `spec` against schema() (ajv) before
+    // returning — a malformed doc throws a clear error. 1:1 parity with the
+    // Python KindBase.validate_on_parse. Opt-in (default false).
+    validateOnParse = false;
+    _parseValidator;
+    _parseAjv;
+    // ---- Optional rendering hints (duck-typed by Studio) -----------
+    docs;
+    descriptionFallbackField;
+    graphStyle;
+    asciiIcon;
+    displayLabel;
+    uiSchema;
+    // ---- H1 opt-in for shared bundle markers -----------------------
+    markerSharedAllowed = false;
+    // ---- Source-sync identity (s-sync-s1) --------------------------
+    // Write-/runtime-stamped spec fields, NOT part of authored identity —
+    // excluded from canonicalDigest so the same doc in two sources hashes
+    // identically. Kinds override to extend (e.g. a Forecast adds generated_at).
+    volatileSpecFields = DEFAULT_VOLATILE_SPEC_FIELDS;
+    // ---- Behavior methods (default implementations) ----------------
+    depFilters() {
+        return null;
+    }
+    dependencies() {
+        return this.depFilters();
+    }
+    schema() {
+        return null;
+    }
+    getDefaultAgentName(_doc) {
+        return null;
+    }
+    getLayerPolicies(_doc) {
+        return null;
+    }
+    parse(raw) {
+        if (this.validateOnParse)
+            this._validateSpec(raw);
+        return raw;
+    }
+    /** Validate `raw.spec` against `schema()` (ajv). No-op when no schema.
+     *  Throws a clear error for a malformed spec (s-typed-models-for-dict-kinds). */
+    _validateSpec(raw) {
+        const schema = this.schema();
+        if (!schema)
+            return;
+        if (this._parseValidator === undefined) {
+            this._parseAjv = createAjv();
+            this._parseValidator = this._parseAjv.compile(schema);
+        }
+        if (!this._parseValidator)
+            return;
+        // Accept a full envelope ({apiVersion, kind, spec}) OR a flat spec dict
+        // (mirrors the gaia Kinds' defensive parse + the Python twin).
+        const spec = "apiVersion" in raw && raw.spec && typeof raw.spec === "object"
+            ? raw.spec
+            : raw;
+        if (!this._parseValidator(spec)) {
+            const errs = this._parseAjv?.errorsText(this._parseValidator.errors);
+            throw new Error(`Kind '${this.kind}' spec validation failed: ${errs}`);
+        }
+    }
+    describe(_doc) {
+        return null;
+    }
+    summary(doc) {
+        const spec = doc.spec;
+        if (spec && typeof spec === "object" && !Array.isArray(spec)) {
+            return { ...spec };
+        }
+        return null;
+    }
+    promptTemplate() {
+        return null;
+    }
+    // ---- Source-sync digest (s-sync-s1; twin of Python canonical_digest) ----
+    canonicalSpec(spec) {
+        const out = {};
+        for (const [k, v] of Object.entries(spec ?? {})) {
+            if (this.volatileSpecFields.has(k))
+                continue;
+            out[k] = v;
+        }
+        delete out["source_files"]; // pure transport, never identity
+        if (out["instruction_file"] && out["instruction"]) {
+            delete out["instruction_file"]; // file-backed == inline once resolved
+        }
+        return out;
+    }
+    /** Stable SHA-256 of the doc's authored identity — basis for source
+     *  diff/sync. Invariant to key order, formatting, volatile stamps, and
+     *  instruction_file-vs-inline; sensitive to real content. */
+    canonicalDigest(doc) {
+        const spec = (doc.spec ?? {});
+        const payload = {
+            kind: doc.kind ?? this.kind,
+            name: doc.name ?? null,
+            spec: this.canonicalSpec({ ...spec }),
+        };
+        return createHash("sha256").update(_stableStringify(payload), "utf8").digest("hex");
+    }
+}

package/dist/kernel/layer-resolver.d.ts

@@ -0,0 +1,48 @@
+/**
+ * DefaultLayerResolver — overlay resolution with per-kind policies.
+ *
+ * 1:1 parity with Python dna.kernel.layer_resolver.
+ *
+ * Kernel-owned since s-invert-layer-resolver-dep (2026-07-07): layer
+ * resolution is a core kernel responsibility, so the default resolver
+ * lives in the kernel package — the kernel must work with ZERO
+ * extensions loaded. Previously at src/extensions/helix/layers.ts
+ * (which remains as a deprecated reexport shim).
+ *
+ * Iterates layer dimensions, loads overlays from the source,
+ * and merges with per-kind policies (open/restricted/locked).
+ * The resolver is fully generic: it depends only on
+ * kernel/protocols.LayerPolicy — no extension models or constants.
+ */
+/**
+ * Deep merge two plain objects. Overlay wins.
+ * Lists are replaced (not concatenated), dicts are merged recursively.
+ */
+export declare function deepMerge(base: Record<string, unknown>, overlay: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Concat + dedup + sort base.spec.timeline and overlay.spec.timeline
+ * (per ADR 2026-05-10). Returns the merged list when EITHER side has a
+ * timeline array; ``null`` when neither does.
+ *
+ * Dedup key: `at + actor + type + (from + to | summary)`.
+ * Sort: descending by ``at`` (newest first).
+ */
+export declare function mergeTimelineArrays(baseSpec: Record<string, unknown>, overlaySpec: Record<string, unknown>): Record<string, unknown>[] | null;
+export interface LayerSource {
+    loadLayer(scope: string, layerId: string, layerValue: string): Record<string, unknown>[];
+}
+/**
+ * Merges layer overlay documents into base documents, applying policies by kind alias.
+ *
+ * Policies map: `{ kind_alias_or_kind_name: LayerPolicy }`
+ * - open: deep merge spec (or add new documents)
+ * - restricted: only override existing keys in spec
+ * - locked: block changes (warn only)
+ */
+export declare class DefaultLayerResolver {
+    resolve(baseDocuments: Record<string, unknown>[], layers: Record<string, string>, source: LayerSource, scope: string, policies: Record<string, string>): Record<string, unknown>[];
+    private _mergeAll;
+    private _policyForKind;
+    private _applyMerge;
+    private _applyRestrictedMerge;
+}

package/dist/kernel/layer-resolver.js

@@ -0,0 +1,284 @@
+/**
+ * DefaultLayerResolver — overlay resolution with per-kind policies.
+ *
+ * 1:1 parity with Python dna.kernel.layer_resolver.
+ *
+ * Kernel-owned since s-invert-layer-resolver-dep (2026-07-07): layer
+ * resolution is a core kernel responsibility, so the default resolver
+ * lives in the kernel package — the kernel must work with ZERO
+ * extensions loaded. Previously at src/extensions/helix/layers.ts
+ * (which remains as a deprecated reexport shim).
+ *
+ * Iterates layer dimensions, loads overlays from the source,
+ * and merges with per-kind policies (open/restricted/locked).
+ * The resolver is fully generic: it depends only on
+ * kernel/protocols.LayerPolicy — no extension models or constants.
+ */
+import { LayerPolicy } from "./protocols.js";
+// ---------------------------------------------------------------------------
+// Deep merge
+// ---------------------------------------------------------------------------
+/**
+ * Deep merge two plain objects. Overlay wins.
+ * Lists are replaced (not concatenated), dicts are merged recursively.
+ */
+export function deepMerge(base, overlay) {
+    const result = structuredClone(base);
+    for (const [key, value] of Object.entries(overlay)) {
+        if (key in result &&
+            typeof result[key] === "object" &&
+            result[key] !== null &&
+            !Array.isArray(result[key]) &&
+            typeof value === "object" &&
+            value !== null &&
+            !Array.isArray(value)) {
+            result[key] = deepMerge(result[key], value);
+        }
+        else {
+            result[key] = structuredClone(value);
+        }
+    }
+    return result;
+}
+// ---------------------------------------------------------------------------
+// Timeline merger (cross-overlay append-only)
+// ---------------------------------------------------------------------------
+/**
+ * Concat + dedup + sort base.spec.timeline and overlay.spec.timeline
+ * (per ADR 2026-05-10). Returns the merged list when EITHER side has a
+ * timeline array; ``null`` when neither does.
+ *
+ * Dedup key: `at + actor + type + (from + to | summary)`.
+ * Sort: descending by ``at`` (newest first).
+ */
+export function mergeTimelineArrays(baseSpec, overlaySpec) {
+    const baseTl = Array.isArray(baseSpec.timeline)
+        ? baseSpec.timeline
+        : [];
+    const overlayTl = Array.isArray(overlaySpec.timeline)
+        ? overlaySpec.timeline
+        : [];
+    if (baseTl.length === 0 && overlayTl.length === 0)
+        return null;
+    const seen = new Set();
+    const merged = [];
+    for (const ev of [...baseTl, ...overlayTl]) {
+        if (typeof ev !== "object" || ev === null || Array.isArray(ev))
+            continue;
+        const key = JSON.stringify([
+            ev.at ?? null,
+            ev.actor ?? null,
+            ev.type ?? null,
+            ev.from ?? null,
+            ev.to ?? null,
+            ev.summary ?? null,
+        ]);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        merged.push(structuredClone(ev));
+    }
+    // Stable sort: newest first.
+    merged.sort((a, b) => {
+        const ax = String(a.at ?? "");
+        const bx = String(b.at ?? "");
+        if (ax < bx)
+            return 1;
+        if (ax > bx)
+            return -1;
+        return 0;
+    });
+    return merged;
+}
+// ---------------------------------------------------------------------------
+// Overlay metadata stamper (Phase 2 overlay UX)
+// ---------------------------------------------------------------------------
+/**
+ * In-place: write ``has_overlay`` + ``overlay_fields`` into ``doc.metadata``.
+ * Studio's editor banners + per-field markers read these.
+ *
+ * ``overlayFields=null`` is the sentinel for "the entire doc came from
+ * the overlay" (overlay-only add, no base to diff against). Frontend
+ * treats this distinctly from an empty list.
+ *
+ * Idempotent across multiple layer dimensions: subsequent calls UNION
+ * the field list so the user sees every field touched across all
+ * applied layers.
+ */
+function stampOverlayMetadata(doc, overlayFields) {
+    const md = doc.metadata ?? {};
+    doc.metadata = md;
+    md.has_overlay = true;
+    if (overlayFields === null) {
+        md.overlay_fields = null;
+        return;
+    }
+    const existing = md.overlay_fields;
+    if (existing === undefined || existing === null) {
+        md.overlay_fields = [...overlayFields];
+        return;
+    }
+    if (Array.isArray(existing)) {
+        const merged = [...existing];
+        for (const f of overlayFields) {
+            if (!merged.includes(f))
+                merged.push(f);
+        }
+        md.overlay_fields = merged;
+    }
+}
+// ---------------------------------------------------------------------------
+// DefaultLayerResolver
+// ---------------------------------------------------------------------------
+/**
+ * Merges layer overlay documents into base documents, applying policies by kind alias.
+ *
+ * Policies map: `{ kind_alias_or_kind_name: LayerPolicy }`
+ * - open: deep merge spec (or add new documents)
+ * - restricted: only override existing keys in spec
+ * - locked: block changes (warn only)
+ */
+export class DefaultLayerResolver {
+    resolve(baseDocuments, layers, source, scope, policies) {
+        let result = baseDocuments.map((d) => structuredClone(d));
+        for (const [layerId, value] of Object.entries(layers)) {
+            const overlayDocs = source.loadLayer(scope, layerId, value);
+            if (overlayDocs.length === 0)
+                continue;
+            result = this._mergeAll(result, overlayDocs, policies, layerId, value);
+        }
+        return result;
+    }
+    // -------------------------------------------------------------------------
+    _mergeAll(baseDocs, overlayDocs, policies, layerId, value) {
+        const result = baseDocs.map((d) => structuredClone(d));
+        // Build index: "kind\0name" -> position in result
+        const baseIndex = new Map();
+        for (let i = 0; i < result.length; i++) {
+            const kind = result[i].kind ?? "";
+            const name = result[i].metadata?.name ?? "";
+            if (kind && name)
+                baseIndex.set(`${kind}\0${name}`, i);
+        }
+        for (const overlay of overlayDocs) {
+            const oKind = overlay.kind ?? "";
+            const oName = overlay.metadata?.name ?? "";
+            const policy = this._policyForKind(oKind, policies);
+            const key = `${oKind}\0${oName}`;
+            if (baseIndex.has(key)) {
+                const idx = baseIndex.get(key);
+                result[idx] = this._applyMerge(result[idx], overlay, policy, layerId, value);
+            }
+            else {
+                // New document — only allowed under OPEN policy
+                if (policy === LayerPolicy.LOCKED ||
+                    policy === LayerPolicy.RESTRICTED) {
+                    console.warn(`Layer '${layerId}=${value}' tried to add '${oKind}/${oName}' but policy is ${policy}. Ignored.`);
+                }
+                else {
+                    // Overlay-only add — stamp metadata so the frontend knows
+                    // "the whole doc is your overlay" (Phase 2 UX).
+                    const newDoc = structuredClone(overlay);
+                    stampOverlayMetadata(newDoc, null);
+                    result.push(newDoc);
+                }
+            }
+        }
+        return result;
+    }
+    _policyForKind(kind, policies) {
+        if (kind in policies)
+            return policies[kind];
+        const kindLower = kind.toLowerCase();
+        for (const [alias, policy] of Object.entries(policies)) {
+            if (alias.endsWith(`-${kindLower}`) || alias === kindLower)
+                return policy;
+        }
+        return LayerPolicy.OPEN;
+    }
+    _applyMerge(base, overlay, policy, layerId, value) {
+        const specOverlay = overlay.spec ?? {};
+        const specBase = base.spec ?? {};
+        // Timeline is append-only across overlays — concat+sort regardless
+        // of policy (even LOCKED). ADR 2026-05-10.
+        const mergedTimeline = mergeTimelineArrays(specBase, specOverlay);
+        if (Object.keys(specOverlay).length === 0 && mergedTimeline === null) {
+            return base;
+        }
+        if (policy === LayerPolicy.LOCKED) {
+            if (mergedTimeline === null) {
+                const name = base.metadata?.name ?? "";
+                console.warn(`Layer '${layerId}=${value}' tried to modify locked document '${name}'. Ignored.`);
+                return base;
+            }
+            // Timeline-only overlay on a LOCKED doc still appends events.
+            const result = structuredClone(base);
+            const sp = result.spec ?? {};
+            sp.timeline = mergedTimeline;
+            result.spec = sp;
+            return result;
+        }
+        if (policy === LayerPolicy.RESTRICTED) {
+            // Strip `timeline` from the restricted-merge call so the
+            // "unknown key" warning doesn't fire for timeline-only changes.
+            const specOverlayNoTl = {};
+            for (const [k, v] of Object.entries(specOverlay)) {
+                if (k !== "timeline")
+                    specOverlayNoTl[k] = v;
+            }
+            const result = this._applyRestrictedMerge(base, specOverlayNoTl, layerId, value);
+            if (mergedTimeline !== null) {
+                const sp = result.spec ?? {};
+                sp.timeline = mergedTimeline;
+                result.spec = sp;
+            }
+            return result;
+        }
+        // OPEN — deep merge spec
+        const result = structuredClone(base);
+        result.spec = deepMerge(specBase, specOverlay);
+        if (mergedTimeline !== null) {
+            result.spec.timeline = mergedTimeline;
+        }
+        if (Object.keys(specOverlay).length > 0) {
+            // Phase 2 overlay UX: top-level spec keys the overlay provided
+            // are "overridden" under OPEN policy. Exclude `timeline` since
+            // it's append-only, not an override.
+            const overridden = Object.keys(specOverlay).filter((k) => k !== "timeline");
+            if (overridden.length > 0) {
+                stampOverlayMetadata(result, overridden);
+            }
+        }
+        return result;
+    }
+    _applyRestrictedMerge(base, specOverlay, layerId, value) {
+        const result = structuredClone(base);
+        const specBase = result.spec ?? {};
+        const applied = [];
+        for (const [key, val] of Object.entries(specOverlay)) {
+            if (!(key in specBase)) {
+                console.warn(`Layer '${layerId}=${value}' tried to add key '${key}' to restricted document. Ignored.`);
+                continue;
+            }
+            if (typeof specBase[key] === "object" &&
+                specBase[key] !== null &&
+                !Array.isArray(specBase[key]) &&
+                typeof val === "object" &&
+                val !== null &&
+                !Array.isArray(val)) {
+                specBase[key] = deepMerge(specBase[key], val);
+            }
+            else {
+                specBase[key] = structuredClone(val);
+            }
+            applied.push(key);
+        }
+        result.spec = specBase;
+        // Restricted policy drops unknown keys — stamp only the ones
+        // that actually merged.
+        if (applied.length > 0) {
+            stampOverlayMetadata(result, applied);
+        }
+        return result;
+    }
+}