dna-sdk 0.1.0

package/dist/kernel/index.d.ts

@@ -0,0 +1,624 @@
+/**
+ * Kernel v3 — Mediator connecting 5 ports.
+ *
+ * 1:1 parity with Python dna.v3.kernel.__init__.
+ */
+import { Document } from "./document.js";
+import type { CompositionProfile } from "./composition-resolver.js";
+import { HookRegistry, type HookContext, type HookNameArg } from "./hooks.js";
+import { ManifestInstance } from "./instance.js";
+import { type CachePort, type Extension, type KindPort, type ReaderPort, type ResolverPort, type SourcePort, type WriterPort, type StorageDescriptor, type SerializedDocument, type WritableSourcePort, type ToolDefinition } from "./protocols.js";
+import { type Template, type MaterializeOptions } from "./templates.js";
+import { type ResolvedDocument } from "./resolver.js";
+import type { FSLike } from "./fs.js";
+export { kebabKindName, generateAlias, EXPLICIT_ALIAS_ALLOWLIST, KIND_NAME_COLLISION_ALLOWLIST, } from "./kind-registry.js";
+/** Raised when writeDocument/deleteDocument is called but no
+ *  WritableSourcePort is registered on the Kernel. */
+export declare class NotWritableError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Return value of Kernel.previewDocument().
+ *
+ * - `target` — absolute path for filesystem sources, synthetic URL
+ *   (e.g. "sqlite://<scope>/<kind>/<name>") for others.
+ * - `files` — the exact bytes that would be written. Readonly.
+ * - `existsAlready` — true iff the target is already present; UIs use
+ *   this to render "create" vs "overwrite" affordances. Optimistic
+ *   concurrency (ifMatch) is deferred per
+ *   docs/superpowers/specs/2026-04-04-kernel-write-path-design.md
+ *   Out-of-Scope.
+ */
+export interface PreviewResult {
+    readonly target: string;
+    /** L3 (2026-05-25): files may have `content` (str) or `contentBytes`
+     * (Uint8Array). Preview UIs that only render text should fallback
+     * to an empty-string display when contentBytes is set. */
+    readonly files: readonly import("./protocols.js").SerializedFile[];
+    readonly existsAlready: boolean;
+}
+/** i-112 Phase 1 — single source of truth para os special-scope names.
+ *  Dois papéis distintos (paridade 1:1 com Python protocols.py):
+ *  DEFAULT_BASE_SCOPE = fallback de herança; SYSTEM_SCOPE = casa dos lookups globais.
+ *  Ambos "_lib" hoje; nomeados separados pra Fases 2-3 divergirem. */
+export declare const DEFAULT_BASE_SCOPE = "_lib";
+export declare const SYSTEM_SCOPE = "_lib";
+/**
+ * The scope that owns the canonical ModelProfile registry.
+ * Queried directly by `modelProfile()` — regardless of the caller's scope.
+ * 1:1 parity with Python `Kernel._MODEL_REGISTRY_SCOPE`.
+ */
+export declare const MODEL_REGISTRY_SCOPE = "_lib";
+/**
+ * The scope that owns the canonical VoicePolicy registry. GLOBAL like
+ * ModelProfile — queried directly regardless of the caller's scope.
+ * 1:1 parity with Python `Kernel._VOICE_POLICY_SCOPE`.
+ */
+export declare const VOICE_POLICY_SCOPE = "_lib";
+export declare class Kernel {
+    private static readonly _BOOTSTRAP_KINDS;
+    private static readonly _LEGACY_NON_INHERITABLE;
+    static readonly INHERIT_PARENT_SCOPE = "_lib";
+    private _classifyKinds;
+    /** Kinds structurally never overlayable. Derived from KindPort.isOverlayable
+     *  (s-kernel-kindport-classification-attrs). 1:1 with Python
+     *  Kernel._NON_OVERLAYABLE_KINDS. */
+    get NON_OVERLAYABLE_KINDS(): ReadonlySet<string>;
+    /** Per-scope ledger + structural Kinds that do NOT inherit across scopes.
+     *  Derived from KindPort.scopeInheritable. 1:1 with Python
+     *  Kernel._NON_INHERITABLE_KINDS. */
+    get NON_INHERITABLE_KINDS(): ReadonlySet<string>;
+    /** `k.INHERITABLE_KINDS.has(kind)` — denylist-backed membership (everything
+     *  inherits EXCEPT NON_INHERITABLE_KINDS). 1:1 with Python _INHERITABLE_KINDS. */
+    get INHERITABLE_KINDS(): {
+        has(kind: string): boolean;
+    };
+    private _source;
+    private _cache;
+    private _resolvers;
+    /** @internal — public so the KindRegistry `RegistryHost` slice reaches the
+     *  rescan gate. Convention `_`-private; not a supported API surface. */
+    _readers: ReaderPort[];
+    private _writers;
+    private _writableSource;
+    private _profiles;
+    /** Registered-Kind identity map + the registration funnel (Fase 3,
+     *  s-kernel-decomp-ts-parity). OWNS the `_kinds` Map; the kernel's `_kinds`
+     *  getter proxies to it, and `kind()`/`kindFromDescriptor()`/
+     *  `_registerKindDefinitions()`/`_registerCustomKinds()`/`validateDepFilters()`
+     *  are thin facades. Shared across withTenant copies (Object.assign copies the
+     *  ref) — Kinds are global, registered once at boot. Py twin:
+     *  `Kernel._kindreg`. */
+    private _kindreg;
+    /** The registered-Kind dict — proxied to `this._kindreg` so the ~20 inline
+     *  `this._kinds` read sites across the kernel keep working after the Fase 3
+     *  extraction. Key: "apiVersion\0kind". Py twin: `Kernel._kinds` property. */
+    get _kinds(): Map<string, KindPort>;
+    /** Extensions that successfully registered, in load() order. Used by
+     *  listTemplates() to aggregate scaffolds from every loaded extension. */
+    private _extensions;
+    /** Tool-definition registry (s-dna-port-surface-parity — TS twin of the
+     *  Py `Kernel._toolreg`). Tools are global (not tenant-scoped), so one
+     *  registry is safely shared across withTenant shallow copies. */
+    private _toolreg;
+    /** Composition-V2 engine (Phase 17 — s-ts-composition-v2-port). Holds a
+     *  back-ref to this kernel; the kernel keeps the public methods
+     *  (resolveDocument / computeResolutionChain / personalizeDocument /
+     *  compositionSummary) as thin delegators, 1:1 with the Python layout. */
+    private readonly _composition;
+    /** Document write/delete execution (tenant resolve, layer-policy check,
+     *  pre_save veto, persist, post_save/post_delete) — extracted collaborator
+     *  (Fase 2, s-kernel-decomp-f2-writepipeline). The kernel keeps
+     *  writeDocument/deleteDocument as thin facades. Non-readonly: withTenant
+     *  re-instantiates it against the copy so a tenant-bound kernel resolves its
+     *  own tenant. Py twin: `Kernel._write_pipeline`. */
+    private _writePipeline;
+    readonly hooks: HookRegistry;
+    /** @internal — public for the KindRegistry `RegistryHost` slice. */
+    _genericsResolved: boolean;
+    private _fs;
+    /** s-alias-generated-not-typed — owner context for alias generation of
+     *  the Kinds registered by the Extension currently inside load().
+     *  @internal — public for the KindRegistry `RegistryHost` slice.
+     *  Py twin: Kernel._loading_ext_owner. */
+    _loadingExtOwner: string | null;
+    /** Two-planes F2 — pluggable semantic-search provider (see search()). */
+    private _searchProvider;
+    /** Damper: warn once per provider-failure episode, then debug. */
+    private _searchProviderWarned;
+    /**
+     * rec-embedding-port — pluggable embedding provider (see embed()). null = no
+     * real provider → the deterministic zero-dep FakeEmbeddingProvider (offline/CI
+     * floor) is constructed lazily on first use.
+     */
+    private _embeddingProvider;
+    /**
+     * Tenant binding (Phase 1 — tenant-as-first-class).
+     *
+     * `null` means unbound — only GLOBAL kinds may be written; TENANTED
+     * kinds raise `TenantRequired`. Set via the constructor (Sanity
+     * `withConfig` pattern) or per-call via `withTenant(other)` (Stripe
+     * Connect pattern).
+     */
+    tenant: string | null;
+    constructor(opts?: {
+        tenant?: string | null;
+    });
+    /**
+     * Return a shallow-copy Kernel bound to `tenant`. Original Kernel is
+     * unchanged — call sites can hand off the copy to per-request
+     * handlers without mutating shared state (Sanity `client.withConfig`
+     * pattern).
+     *
+     * Pass `tenant=null` to obtain an unbound kernel (writes only allowed
+     * for GLOBAL kinds).
+     */
+    withTenant(tenant: string | null): Kernel;
+    /** Return the registered KindPort for a kind name (case-sensitive).
+     *  With apiVersion the lookup is EXACT on (apiVersion, kind) — bare
+     *  lookups on a name shared by multiple apiVersions resolve
+     *  extension-first then registration order (i-195, Py twin:
+     *  KindRegistry.port_for). */
+    private _kindPortFor;
+    /** Public lookup for a registered KindPort by kind name. Use from
+     *  tooling that needs to consult Kind metadata (isRuntimeArtifact,
+     *  scope, storage, ...) without reaching into Kernel internals. Pass
+     *  apiVersion for exact resolution on ambiguous names (i-195). */
+    kindPortFor(kind: string, apiVersion?: string): KindPort | null;
+    /** Validate a Kind-Writer Agent's slot↔schema contract
+     *  (feat/kind-writer-pilot, Task 2). Called from writeDocument only when
+     *  spec.writes_kind is set — fail early so a malformed Kind-Writer is
+     *  rejected before runtime emission. Twin of Python _validate_kind_writer.
+     *
+     *  Contract:
+     *  - writes_kind must resolve to a registered KindPort whose schema() is an
+     *    object (schema-bearing); unknown / schema-less → Error (mentions schema).
+     *  - every creative_slots name must be a property in the schema.
+     *  - every required schema field must be covered by
+     *    creative_slots ∪ Object.keys(system_slots); uncovered → "unmapped". */
+    /** @internal — called by the Helix extension's Kind-Writer pre_save
+     *  guard (s-write-path-despecialize). Thin delegator to
+     *  `WritePipeline.validateKindWriter` (Fase 2,
+     *  s-kernel-decomp-f2-writepipeline). */
+    _validateKindWriter(spec: Record<string, unknown>): void;
+    /** All registered KindPorts. Order matches registration. Facade over
+     *  `this._kindreg.allPorts()` (Fase 3). */
+    kindPorts(): KindPort[];
+    /** F3 D4 (spec 2026-06-10-kinds-descriptor-f3): kind names whose port
+     *  declares `embedFields` — via descriptor `embed:` or a class-level
+     *  `embedFields` (the KindBase parity hook for not-yet-migrated
+     *  classes). Py twin: `Kernel.embeddable_kinds()` (frozenset). */
+    embeddableKinds(): Set<string>;
+    /** Return the TenantScope for a registered kind, or null if unset.
+     *  Phase 1 keeps undeclared kinds permissive (back-compat). @internal —
+     *  read by WritePipeline.resolveTenantArg via the back-ref. */
+    _kindScope(kind: string): string | null;
+    use(hook: HookNameArg, fn: (ctx: HookContext) => HookContext): void;
+    on(hook: HookNameArg, fn: (ctx: HookContext) => void): void;
+    /** Register a veto listener (e.g. 'pre_save') — throwing vetoes the
+     *  operation. See HookRegistry.onVeto for priority/key semantics. */
+    onVeto(hook: HookNameArg, fn: import("./hooks.js").VetoHandler, opts?: {
+        priority?: number;
+        key?: string;
+    }): void;
+    source(s: SourcePort): void;
+    /** The SourcePort registered via source(), or null. Read-only getter.
+     *  The setter method is `source(src)`. Named `activeSource` to avoid
+     *  collision between a method and a property of the same name.
+     *  Parity: python Kernel.active_source. */
+    get activeSource(): SourcePort | null;
+    /**
+     * Kernel-level record query — push-down delegated to `source.query`
+     * (two-planes F2; TS twin of the Py `kernel.query`).
+     *
+     * Adds on top of the source:
+     * - Tenant binding auto-stamp: `opts.tenant` > `Kernel.tenant` > unset
+     *   (Stripe Connect pattern, same as writeDocument).
+     * - Cross-scope `scopes` (F2.4): iterates the scopes with per-scope
+     *   queries and CONCATENATES without dedup — records from distinct
+     *   scopes are distinct docs. Mutually exclusive with a diverging
+     *   positional `scope`: `scopes` wins (the positional is ignored).
+     *   `limit`/`offset` apply PER scope.
+     *
+     * Divergence from Py (documented): the TS kernel has NO
+     * origin/inheritance machinery (no `origin=` param, no scope-inheritance
+     * chain, no catalog pass) — those live in the Py QueryEngine only.
+     * Records are per-scope, so the record plane loses nothing.
+     *
+     * Sources without the optional `query` capability (e.g. PostgresSource
+     * TS, no push-down this phase) raise a clear capability error.
+     */
+    query(scope: string, kind: string, opts?: {
+        filter?: import("./protocols.js").QueryFilter;
+        limit?: number;
+        offset?: number;
+        orderBy?: string[];
+        tenant?: string;
+        scopes?: string[];
+    }): AsyncIterable<Record<string, unknown>>;
+    /**
+     * F2 D2 — public aggregation count alongside `query` (TS twin of the
+     * Py `kernel.count`). Push-down to `source.count` (FS: in-memory core).
+     *
+     * Returns `CountResult`: `{ total, groups }` — groups by count DESC,
+     * key ASC with `null` last; `groups` is `null` without `groupBy`.
+     *
+     * NO origin/inheritance on purpose — records are per-scope (spec D5:
+     * derived views build on top of `kernel.query` in code). Cross-scope
+     * via `scopes` (totals SUMMED, groups MERGED by key and re-sorted;
+     * `scopes` wins over a diverging positional `scope`).
+     *
+     * Example (Studio velocity):
+     *   const res = await kernel.count("dna-development", "Story", {
+     *     groupBy: "spec.status",
+     *   });
+     *   // { total: 950, groups: [{ key: "done", count: 700 }, …] }
+     */
+    count(scope: string, kind: string, opts?: {
+        filter?: import("./protocols.js").QueryFilter;
+        groupBy?: string;
+        tenant?: string;
+        scopes?: string[];
+    }): Promise<import("./protocols.js").CountResult>;
+    /**
+     * Register the embedding provider (rec-embedding-port). One per kernel; later
+     * registration replaces (boot-time wiring). Sibling to
+     * `recordSearchProvider` — a real provider (ONNX all-MiniLM-L6-v2) registers
+     * itself at app boot; without one, `embed` uses the deterministic
+     * `FakeEmbeddingProvider` floor.
+     */
+    embeddingProvider(provider: import("./protocols.js").EmbeddingPort): void;
+    /** The registered embedding provider, or a lazily-constructed fake (cached).
+     *  The fake is zero-dep core (js-sha256, already a dependency) so it is a
+     *  static import — no ML deps enter the graph. */
+    private _resolveEmbeddingProvider;
+    /**
+     * Embed texts into dense vectors (rec-embedding-port; TS twin of the Py
+     * `kernel.embed`). Uses the registered `EmbeddingPort` when present, else the
+     * deterministic zero-dep fake floor. Returns one `dims`-length vector per
+     * input, in order; empty input → empty array. Read the space via
+     * `embeddingDims` / `embeddingModelId`.
+     */
+    embed(texts: string[]): Promise<number[][]>;
+    /** Output dimensionality of the active embedding provider. */
+    get embeddingDims(): number;
+    /** Identity of the active embedding space (vectors from different `modelId`s
+     *  are NOT comparable). */
+    get embeddingModelId(): string;
+    /**
+     * Register the semantic-search provider (two-planes F2). One per
+     * kernel; later registration replaces (boot-time wiring) and resets
+     * the failure-warning damper (new provider → fresh episode).
+     */
+    recordSearchProvider(provider: import("./protocols.js").RecordSearchProvider): void;
+    /**
+     * Public record search (F2 D2; TS twin of the Py `kernel.search`).
+     * Provider registered → semantic (degraded=false). No provider OR
+     * provider error → lexical token-match fallback over `query()`
+     * (degraded=true; requires `kind` — without it returns empty
+     * degraded). Tenant binding same as `query()`.
+     */
+    search(scope: string, queryText: string, opts?: {
+        kind?: string | null;
+        k?: number;
+        tenant?: string;
+    }): Promise<{
+        hits: Array<Record<string, unknown>>;
+        degraded: boolean;
+    }>;
+    /**
+     * Degraded fallback for `search()` — honest DEV lexical scan, NOT
+     * similarity (two-planes F2; 1:1 with the Py `_lexical_search`).
+     *
+     * Matches by token-set over the STRING VALUES of each doc's spec
+     * (recursive walk; never substring over serialized JSON —
+     * `json.dumps` Py and `JSON.stringify` TS diverge in separators and
+     * would break parity). Requires `kind` (records are scanned per-kind);
+     * without it there is nothing safe to scan → empty.
+     * Score = query tokens present ÷ total query tokens.
+     */
+    private _lexicalSearch;
+    /**
+     * Internal — one raw doc for a `(scope, kind, name, tenant)` layer key
+     * (tenant is "" for the base layer). TS twin of the Py
+     * `_granular_doc_cached` MINUS the cache: the TS kernel has no
+     * kernel-level doc cache, so this is a direct source read on every
+     * call. PERF divergence only — same inputs, same outputs (see
+     * composition-resolver.ts module docstring, divergence #1).
+     */
+    _granularDoc(key: [string, string, string, string]): Promise<Record<string, unknown> | null>;
+    /**
+     * Internal — the ordered Catalog scope set for `tenant` (Phase 3b ch1,
+     * i-112 on the Py side). The TS kernel has NO catalog machinery yet
+     * (Genome scan + tenant lockfile — TS parity tracked as `i-185`), so
+     * this hook returns `[]`: the resolver's Catalog splice is fully
+     * implemented but contributes no layers on TS today (see
+     * composition-resolver.ts module docstring, divergence #3).
+     */
+    _catalogScopes(tenant: string | null, opts?: {
+        exclude?: Set<string>;
+    }): Promise<Array<[string, string | null]>>;
+    /**
+     * Walk `Genome.spec.parent_scope` transitively → ordered resolution
+     * chain of `[scope, tenant]` pairs, HIGHEST priority first:
+     *   [[scope, tenant], [scope, null], [parent, tenant], [parent, null], …]
+     * When `tenant` is null, only base layers are emitted per scope.
+     * Cycle detection via visited set; depth capped at MAX_RESOLUTION_DEPTH;
+     * missing Genome / missing parent_scope terminates the walk (with the
+     * V1 back-compat escalation to `_lib`).
+     * Py twin: `Kernel._compute_resolution_chain`.
+     */
+    computeResolutionChain(scope: string, tenant?: string | null): Promise<Array<[string, string | null]>>;
+    /**
+     * Resolve the composition rule `[scope_inheritance, merge_strategy,
+     * tenant_overlay]` for (scope, kind) — the scope's
+     * `LayerPolicy.composition_rules[kind]`, else the inherit-by-default
+     * denylist. Py twin: `Kernel._get_composition_rule`.
+     */
+    getCompositionRule(scope: string, kind: string): Promise<[string, string, string]>;
+    /**
+     * Resolve a doc through the composition chain — Phase 17 primitive.
+     * Returns `ResolvedDocument` with merged doc + full provenance.
+     * Bootstrap Kinds (Genome, LayerPolicy, KindDefinition) bypass
+     * inheritance entirely (local-only, single-layer provenance).
+     * Py twin: `Kernel.resolve_document`.
+     */
+    resolveDocument(scope: string, kind: string, name: string, opts?: {
+        tenant?: string | null;
+    }): Promise<ResolvedDocument>;
+    /**
+     * Clone an inherited doc into `targetScope` as a local override.
+     * Throws when the doc isn't inherited or the target already exists
+     * (without `overwrite`). Py twin: `Kernel.personalize_document`
+     * (bundle-entry payload cloning is Py-only — divergence #4 in
+     * composition-resolver.ts).
+     */
+    personalizeDocument(targetScope: string, kind: string, name: string, opts?: {
+        tenant?: string | null;
+        overwrite?: boolean;
+    }): Promise<ResolvedDocument>;
+    /**
+     * Cheap aggregate of the scope's parent chain + per-Kind local /
+     * inherited / installed counts (Py twin: `Kernel.composition_summary`;
+     * same snake_case wire shape:
+     * `{scope, parent_chain, resources: {Kind: {local, inherited, installed,
+     * total}}}`). The Py twin rides its QueryEngine origin filters; the TS
+     * kernel has no origin machinery, so the three passes are computed here
+     * directly with the SAME dedup semantics (local names shadow catalog +
+     * parent names; catalog names do NOT shadow inherited — mirroring the
+     * three independent origin-filtered queries Python makes). `installed`
+     * is always 0 until the TS catalog surface lands (i-185).
+     */
+    compositionSummary(scope: string, opts?: {
+        tenant?: string | null;
+    }): Promise<Record<string, unknown>>;
+    /** WriterPorts registered via writer(w). Returns a FROZEN snapshot of
+     *  the internal writer list — mutating the returned array throws in
+     *  strict mode and never affects the Kernel's internal state.
+     *  Parity: python Kernel.active_writers (which returns a tuple). */
+    get activeWriters(): readonly WriterPort[];
+    /** ReaderPorts registered via reader(r). Frozen snapshot — mirror of
+     *  activeWriters (s-dna-rw-roundtrip-suite: the round-trip conformance
+     *  suite enumerates registered pairs through this surface).
+     *  Parity: python Kernel.active_readers. */
+    get activeReaders(): readonly ReaderPort[];
+    cache(c: CachePort): void;
+    resolver(scheme: string, r: ResolverPort): void;
+    reader(r: ReaderPort): void;
+    writer(w: WriterPort): void;
+    writableSource(ws: WritableSourcePort): void;
+    fs(f: FSLike): void;
+    /** Register a Kind (H1 validation funnel). Thin facade over
+     *  `this._kindreg.registerKind()` (Fase 3, s-kernel-decomp-ts-parity —
+     *  the funnel moved into the KindRegistry; Py twin: `Kernel.kind()`
+     *  delegating to `self._kindreg.register_kind`). */
+    kind(k: KindPort): void;
+    /** F3 (spec D3): register a BUILTIN Kind from a KindDefinition
+     *  descriptor (`kinds/*.kind.yaml` package data). Thin facade over the
+     *  KindRegistry funnel (Fase 3). Py twin: `Kernel.kind_from_descriptor`. */
+    kindFromDescriptor(raw: Record<string, unknown>): KindPort;
+    /** Summary dict for a registered kind, including resolved docs. Facade
+     *  over `this._kindreg.describe()` (Fase 3). */
+    describeKind(kindName: string): Record<string, unknown> | null;
+    /** Register a composition profile that declares how an orchestrator
+     *  kind connects to other kinds. Called by extensions (e.g.
+     *  HelixExtension) during register(). */
+    compositionProfile(profile: CompositionProfile): void;
+    /** Register a tool definition (delegates to the ToolRegistry;
+     *  last-write-wins on same name). Py twin: `Kernel.tool`. */
+    tool(td: ToolDefinition): void;
+    /** Return a tool definition by name, or `null` if unknown.
+     *  Py twin: `Kernel.get_tool`. */
+    getTool(name: string): ToolDefinition | null;
+    /** Return registered tool definitions, optionally filtered by group(s)
+     *  (`groups: ["read"]` expands the umbrella alias).
+     *  Py twin: `Kernel.get_tools`. */
+    getTools(opts?: {
+        group?: string | null;
+        groups?: Iterable<string> | null;
+    }): ToolDefinition[];
+    /** Reverse-build `{group: [toolNames…]}` from the registry.
+     *  Py twin: `Kernel.list_tool_groups`. */
+    listToolGroups(): Record<string, string[]>;
+    /** Canonical dep_filter target resolution (s-alias-generated-not-typed).
+     *
+     *  The CONTRACT is alias-valued dep_filters (`"soulspec-soul"`). The
+     *  legacy `"kind=<Name>"` format resolves through a DEPRECATED shim so
+     *  per-scope KindDefinition docs keep working. Builtin extensions must
+     *  be alias-pure (validateDepFilters rejects `kind=` there). Delegates
+     *  to the shared `resolveDepFilterTargetOver` — since
+     *  s-unify-composition-subsystems the ONE resolver every dep_filter
+     *  reader (`validateRefs` / `mi.composition` / the Kernel) consumes.
+     *  Facade over `this._kindreg.resolveDepFilterTarget()` (Fase 3).
+     *  Py twin: KindRegistry.resolve_dep_filter_target. */
+    resolveDepFilterTarget(value: string): KindPort | null;
+    /** s-alias-generated-not-typed — every dep_filter target of an
+     *  EXTENSION-registered Kind must resolve to a registered alias.
+     *
+     *  Aliases are the wire key of dep_filters / Mustache sections /
+     *  LayerPolicy — a typo used to degrade the prompt SILENTLY (the dep
+     *  just vanished from the context, warning buried in logs). Called at
+     *  the end of `loadBuiltins()` (the TS twin of `Kernel.auto()`).
+     *
+     *  - Extension/builtin port with an unknown alias OR the legacy
+     *    `kind=` format → `KindRegistrationError` (boot fails loud).
+     *  - Per-scope declarative ports (user KindDefinition docs) only WARN
+     *    — user docs never take the boot down (same posture as the
+     *    parse_error / plane-lint funnels).
+     *  Facade over `this._kindreg.validateDepFilters()` (Fase 3).
+     *  Py twin: Kernel.validate_dep_filters. */
+    validateDepFilters(): void;
+    load(ext: Extension): void;
+    /**
+     * Aggregate `templates()` from every loaded extension.
+     *
+     * The `templates()` method is feature-tested via
+     * `typeof ext.templates === "function"` so extensions that predate
+     * Phase 0 (and don't declare the method) still work. A misbehaving
+     * extension that throws inside its `templates()` is logged to
+     * `console.warn` but never breaks discovery for the other
+     * extensions.
+     */
+    listTemplates(): Template[];
+    /**
+     * Materialize a template by id into `opts.targetRoot`.
+     *
+     * Throws `Error("template not found: <id>")` if no loaded extension
+     * advertises a template with the given id (the TS equivalent of
+     * Python's `KeyError`). `opts.onConflict` is passed through to
+     * {@link materialize}.
+     */
+    scaffold(templateId: string, opts: MaterializeOptions): string[];
+    /** @internal — public for the KindRegistry `RegistryHost` slice (the
+     *  2-phase-load rescan re-resolves generic BUNDLE readers/writers here). */
+    _ensureGenericReadersWriters(): void;
+    containerForKind(kindName: string): string | null;
+    storageForKind(kindName: string): StorageDescriptor | null;
+    kindByContainer(container: string): string | null;
+    /**
+     * Stable human-readable locator for a document.
+     *
+     * - Filesystem sources (detected by the presence of a `baseDir`
+     *   property) → "<baseDir>/<scope>/<kindSubdir>/<name>"
+     * - Other sources → "<scheme>://<scope>/<kind>/<name>" where scheme
+     *   comes from source.urlScheme, falling back to the class name with
+     *   the trailing "source" suffix stripped.
+     *
+     * Parity: python Kernel._target_locator.
+     */
+    _targetLocator(scope: string, kind: string, name: string): string;
+    serializeDocument(_scope: string, kind: string, name: string, raw: Record<string, unknown>): SerializedDocument;
+    /**
+     * Pure preview — returns target, serialized files, existsAlready.
+     *
+     * Does NOT touch disk. ``existsAlready`` is a UI hint so callers can
+     * render "create" vs "overwrite" affordances. Parity: Python
+     * Kernel.preview_document.
+     */
+    previewDocument(scope: string, kind: string, name: string, raw: Record<string, unknown>): Promise<PreviewResult>;
+    /**
+     * Best-effort probe: is the target document already present?
+     *
+     * Uses the writable source's `listVersions` when available (non-empty
+     * = exists). Returns false on any adapter failure — this is a UI hint,
+     * not a correctness gate. Parity: Python Kernel._target_exists.
+     */
+    private _targetExists;
+    writeDocument(scope: string, kind: string, name: string, raw: Record<string, unknown>, options?: {
+        skipHooks?: boolean;
+        author?: string;
+        tenant?: string | null;
+        layer?: [string, string];
+    }): Promise<string>;
+    deleteDocument(scope: string, kind: string, name: string, options?: {
+        skipHooks?: boolean;
+        author?: string;
+        tenant?: string | null;
+        layer?: [string, string];
+    }): Promise<void>;
+    /** @internal — resolve the registered writable source or throw
+     *  NotWritableError. Used by WritePipeline (Py twin:
+     *  `Kernel._require_writable_source`). */
+    _requireWritableSource(): WritableSourcePort;
+    /**
+     * Per-scope cache of the base (no-layer) ManifestInstance. Used by the
+     * layer-policy check so it does not re-resolve layers per call. Mirrors
+     * Python KernelCache._base (the kernel's extracted cache collaborator).
+     */
+    private _baseInstanceCache;
+    /** LRU bound on _baseInstanceCache (scopes). Mirrors Py _BASE_INSTANCE_MAX (i-036). */
+    private static readonly BASE_INSTANCE_MAX;
+    private _ensureBaseInstance;
+    /**
+     * Resolve a kind name to its globally-unique alias (`<owner>-<kind>`).
+     * Falls back to `kind.toLowerCase()` when no registered port provides one.
+     * Facade over `this._kindreg.aliasFor()` (Fase 3). Parity: Python
+     * Kernel._alias_for delegating to `self._kindreg.alias_for`.
+     */
+    private _aliasFor;
+    /**
+     * Validate that writing/deleting `kind/name` in `scope` against the given
+     * layer overlay satisfies the Module's LayerPolicy (OPEN / RESTRICTED /
+     * LOCKED). Parity: Python Kernel._check_layer_policy.
+     *
+     * Policy modes (resolved via alias `<owner>-<kind>`):
+     * - LOCKED — any write throws.
+     * - RESTRICTED — adding a new doc (not present in base) throws; adding a
+     *   *new top-level spec key* on an existing doc throws; overriding
+     *   existing top-level spec keys is allowed.
+     * - OPEN (default) — never throws.
+     *
+     * When the scope has no Module doc, policy defaults to OPEN (no-op).
+     */
+    /** @internal — read by WritePipeline (write/delete policy gate). */
+    _checkLayerPolicyAsync(scope: string, kind: string, name: string, raw: unknown, layer: [string, string]): Promise<void>;
+    instance(scope: string, layers?: Record<string, string>): Promise<ManifestInstance>;
+    resolveLayers(mi: ManifestInstance, layers: Record<string, string>): Promise<ManifestInstance>;
+    private _applyLayers;
+    /**
+     * If a kind declares `descriptionFallbackField` and metadata.description
+     * is missing/empty, derive it from the named spec field. Mutates `raw`.
+     */
+    static _fillDerivedDescription(raw: Record<string, unknown>, kindPort: unknown): void;
+    _parseDoc(raw: Record<string, unknown>, origin?: string): Document;
+    /**
+     * Phase 1 of 2-phase loading: parse KindDefinition docs + register
+     * synthetic DeclarativeKindPorts. Thin facade over the KindRegistry
+     * funnel (Fase 3, s-kernel-decomp-ts-parity). Returns true iff new
+     * BUNDLE readers were added (the rescan gate). Py twin:
+     * `Kernel._register_kind_definitions`.
+     */
+    private _registerKindDefinitions;
+    /** Register dynamic `Module.spec.custom_kinds`. Thin facade over the
+     *  KindRegistry funnel (Fase 3). Py twin: `Kernel._register_custom_kinds`. */
+    private _registerCustomKinds;
+    /** s-realtime-model-single-default — 1:1 parity with the Python kernel:
+     *  the realtime fallback the prompt-budget guard caps against resolves
+     *  through ONE env (DNA_VOICE_REALTIME_MODEL), read at ACCESS time so a
+     *  pin set after construction still applies. */
+    readonly _DEFAULT_REALTIME_MODEL_FALLBACK = "gpt-realtime-2";
+    get _DEFAULT_REALTIME_MODEL(): string;
+    /**
+     * Resolve a ModelProfile from the `_lib` scope by `model_id` (pass 1)
+     * or `aliases[]` (pass 2). Returns the matching Document or null on miss.
+     *
+     * Always queries `MODEL_REGISTRY_SCOPE` ("_lib") directly — ModelProfile
+     * is GLOBAL and NOT in `INHERITABLE_KINDS`; any caller scope is irrelevant.
+     *
+     * 1:1 parity with Python `Kernel.model_profile(model_id_or_alias)`.
+     *
+     * @param modelIdOrAlias - The model_id string or an alias declared in the profile.
+     * @returns The matching Document, or null on miss or error.
+     */
+    modelProfile(modelIdOrAlias: string): Promise<import("./document.js").Document | null>;
+    /**
+     * Resolve a VoicePolicy from the `_lib` scope by metadata name.
+     * Returns the matching Document, the first policy as a fallback, or null
+     * on miss/error. Always queries `VOICE_POLICY_SCOPE` ("_lib")
+     * directly — VoicePolicy is GLOBAL and NOT in `INHERITABLE_KINDS`.
+     *
+     * 1:1 parity with Python `Kernel.voice_policy(name)`.
+     */
+    voicePolicy(name?: string): Promise<import("./document.js").Document | null>;
+}
+export { ManifestInstance } from "./instance.js";