dna-sdk 0.1.0

package/dist/kernel/protocols.d.ts

@@ -0,0 +1,751 @@
+/**
+ * v3 Kernel Protocols — the 5 ports + shared types.
+ *
+ * Parity with Python dna.kernel.protocols is SURFACE-TRACKED, not
+ * assumed (s-dna-port-surface-parity): every port's member list — and every
+ * INTENTIONAL asymmetry, with its justification — lives in the shared
+ * fixture `tests/parity-fixtures/port-surface-parity.json`, enforced by
+ * `tests/port-surface-parity.test.ts` (via the keyof-bound PORT_SURFACE
+ * manifest in `./port-surface.ts`) and by the Python twin
+ * `packages/sdk-py/tests/test_port_surface_parity.py` (real Protocol
+ * introspection). Adding/removing a member on either side without updating
+ * the fixture turns the suites red.
+ */
+import type { BundleHandle } from "./bundle-handle.js";
+import type { Document } from "./document.js";
+import type { PreviewBlock } from "./preview.js";
+import type { HookContext, HookNameArg, HookRegistry, VetoHandler } from "./hooks.js";
+import type { CompositionProfile } from "./composition-resolver.js";
+export type { BundleHandle };
+export declare const LayerPolicy: {
+    readonly OPEN: "open";
+    readonly RESTRICTED: "restricted";
+    readonly LOCKED: "locked";
+};
+export type LayerPolicy = (typeof LayerPolicy)[keyof typeof LayerPolicy];
+/**
+ * Whether a Kind's documents belong to a tenant or are globally shared.
+ *
+ * Mirrors the Kubernetes CRD `scope: Namespaced | Cluster` model. Each
+ * KindPort declares its scope; the kernel enforces it on every write.
+ *
+ * - `TENANTED` (default): documents belong to one tenant. Writing
+ *   requires a tenant arg; reading is filtered by tenant.
+ *   Agent, EvalCase, EvalRun, AssessmentRun, Finding, etc.
+ * - `GLOBAL`: documents are shared across all tenants. Writes must
+ *   not pass a tenant; reads ignore the bound tenant.
+ *   Doc, KindDefinition, Module-level configs, etc.
+ */
+export declare const TenantScope: {
+    readonly TENANTED: "tenanted";
+    readonly GLOBAL: "global";
+};
+export type TenantScope = (typeof TenantScope)[keyof typeof TenantScope];
+/** Reserved tenant slugs — never accepted as user input. */
+export declare const RESERVED_TENANT_SLUGS: Set<string>;
+/**
+ * Raised when a TENANTED kind is written without a tenant arg.
+ *
+ * Bind a tenant on construction (`new Kernel({ tenant: X })`) or
+ * per-call (`kernel.withTenant(X).writeDocument(...)`).
+ */
+export declare class TenantRequired extends Error {
+    constructor(message?: string);
+}
+/**
+ * Raised when a GLOBAL kind is written with a tenant arg.
+ *
+ * Global kinds (Doc, KindDefinition, ...) are shared across
+ * tenants. Writes must explicitly omit `tenant`.
+ */
+export declare class TenantNotAllowed extends Error {
+    constructor(message?: string);
+}
+/**
+ * Raised when `writeDocument` vetoes a doc whose `spec` violates the Kind's
+ * declared JSON Schema (`KindPort.schema()`).
+ *
+ * s-write-path-validation (i-008): the kernel used to validate schemas only
+ * at SCAN/read (the fail-soft `parse_error` channel) — a shape-broken doc
+ * would persist and explode later, far from the author. Now every
+ * `writeDocument` validates the spec at write time when the Kind declares a
+ * schema; Kinds without a schema stay permissive.
+ * Mode knob: `DNA_WRITE_VALIDATION=enforce|warn|off`.
+ */
+export declare class SpecValidationError extends Error {
+    constructor(message?: string);
+}
+/** Raised when a tenant slug is reserved or empty. */
+export declare class InvalidTenantSlug extends Error {
+    constructor(message?: string);
+}
+/**
+ * Validate a tenant slug.
+ *
+ * Phase 1 only checks the reserved set + non-empty/length. Character
+ * rules (DNS-label, lowercase) are NOT enforced at the kernel boundary
+ * so existing tests/data using uppercase ("T1", "Acme") keep working.
+ * Path-traversal safety lives in the adapter.
+ *
+ * Phase 2 may tighten to k8s namespace rules (`[a-z0-9-]{1,63}`) once
+ * the migration is complete.
+ */
+export declare function validateTenantSlug(tenant: string | null | undefined): void;
+/**
+ * Raised when a write to a layer violates the declared LayerPolicy in
+ * `Module.spec.layers`. Thrown by `Kernel.writeDocument` before the adapter
+ * is touched. Harness endpoints translate to HTTP 403.
+ */
+export declare class LayerPolicyViolationError extends Error {
+    constructor(message: string);
+}
+export interface CompositionResult {
+    resolved: string[];
+    missing: string[];
+    warnings: string[];
+    /**
+     * Refs whose target Kind is plane="record" (two-planes F2.5, spec D6).
+     * Records are excluded from the MI materialization on the Py side, so
+     * the engine can't check them against the doc index — they resolve
+     * lazily via the kernel record plane at read time. Deferred refs are
+     * NOT missing: `isCompositionValid` ignores them.
+     */
+    deferred: string[];
+}
+export declare function isCompositionValid(result: CompositionResult): boolean;
+export interface CacheItem {
+    name: string;
+    kind: string;
+    contentPath: string;
+    raw?: Record<string, unknown>;
+}
+export interface ResolvedItem {
+    name: string;
+    kind: string;
+    sourcePath: string;
+}
+/**
+ * Filter shape — dict of dotted `field_path` → expected value.
+ *
+ *   { "status": "in-progress" }                  // shorthand equality
+ *   { "status": { "in": ["todo", "done"] } }     // operator form
+ *   { "spec.priority": { "gte": 2 } }
+ *
+ * Unprefixed paths resolve under `spec.`; `name` is a reserved short for
+ * `metadata.name`. Implicit AND across keys; no OR (issue two queries).
+ */
+export type QueryFilter = Record<string, unknown>;
+/**
+ * Ordering — list of field paths optionally prefixed with `-` for
+ * descending. Applied in declaration order. `null`/missing values sort
+ * LAST regardless of direction (parity with PG `DESC NULLS LAST`; the Py
+ * side was fixed in i-121 — TS is born correct).
+ */
+export type QueryOrder = string[];
+/** Shape returned by `count()` — groups ordered by count DESC, then key
+ *  ASC with `null` last. `groups` is `null` when no `groupBy` was asked. */
+export interface CountResult {
+    total: number;
+    groups: Array<{
+        key: unknown;
+        count: number;
+    }> | null;
+}
+/**
+ * Raised when a query filter / order_by is malformed in a way the
+ * adapter can detect statically (unknown operator, …). 1:1 with the Py
+ * `QueryError`.
+ */
+export declare class QueryError extends Error {
+    constructor(message?: string);
+}
+/** Operators recognized by `matchFilter` — the Py `_PG_OP_MAP` set + `in`. */
+export declare const QUERY_OPS: ReadonlySet<string>;
+/**
+ * Walk a dotted `fieldPath` through `doc`. Unprefixed paths resolve under
+ * `spec.`; `name` is a reserved short for `metadata.name`. Returns `null`
+ * when any segment is missing (never `undefined` — parity with Py `None`).
+ */
+export declare function resolveFieldPath(doc: Record<string, unknown>, path: string): unknown;
+/**
+ * Evaluate a `QueryFilter` against a single doc. Unknown operators throw
+ * `QueryError` so callers can debug instead of silently matching. 1:1
+ * port of the Py `_match_filter` (only single-key dicts enter the
+ * operator branch; anything else is shorthand equality).
+ */
+export declare function matchFilter(doc: Record<string, unknown>, filter: QueryFilter): boolean;
+/**
+ * Stable sort `rows` by each `orderBy` field, last-first to achieve the
+ * desired primary/secondary precedence. Prefixed `-` means descending.
+ * `null` values sort LAST regardless of direction: the None-flag is
+ * `(v === null) !== descending` — immune to the reversed comparator
+ * (i-121: parity with PG `DESC NULLS LAST`; a plain `v === null` flag
+ * would flip under reversal and shove nulls to the FRONT in DESC).
+ *
+ * Mixed-type values (number + string across rows on the same field) fall
+ * back to stringified compare to mirror the Py TypeError fallback. Does
+ * not mutate the input. Best-effort like the Py protocol-default —
+ * adapters with native push-down use the backend's type semantics.
+ */
+export declare function applyOrderBy(rows: Record<string, unknown>[], orderBy: QueryOrder): Record<string, unknown>[];
+/** Options accepted by the query half of the record-plane port (TS).
+ *  NOTE: no `projection` on the TS surface — Py-only for now. */
+export interface SourceQueryOpts {
+    filter?: QueryFilter;
+    limit?: number;
+    offset?: number;
+    orderBy?: QueryOrder;
+    tenant?: string;
+}
+/** Options accepted by the count half of the record-plane port (TS). */
+export interface SourceCountOpts {
+    filter?: QueryFilter;
+    groupBy?: string;
+    tenant?: string;
+}
+/**
+ * In-memory query core — mirror of the Py `SourcePort.query`
+ * protocol-default minus the IO: kind filter first (cheap), then
+ * `matchFilter`, then `applyOrderBy`, then limit/offset paging.
+ * `FilesystemSource.query` is `loadAll` + this; the shared parity
+ * fixture drives it directly.
+ */
+export declare function queryDocs(docs: Record<string, unknown>[], kind: string, opts?: Omit<SourceQueryOpts, "tenant">): Record<string, unknown>[];
+/**
+ * In-memory count core — mirror of the Py `SourcePort.count`
+ * protocol-default: total of docs matching the filter, optionally
+ * grouped by a field path. Groups ordered by count DESC, then key ASC
+ * with `null` LAST (matches PG `ORDER BY count DESC, key ASC NULLS
+ * LAST` and the spirit of i-121).
+ */
+export declare function countDocs(docs: Record<string, unknown>[], kind: string, opts?: Omit<SourceCountOpts, "tenant">): CountResult;
+/**
+ * Two-planes F2 (spec D2): semantic search over record docs. The PG
+ * adapter (pgvector+RRF) lives in harness-shared (Py) and registers
+ * itself on the kernel at app boot — the kernel core gains NO
+ * LLM/embedding deps. Without a provider, `kernel.search()` degrades to
+ * an in-memory lexical scan (explicit `degraded: true` — never fake
+ * similarity). 1:1 with the Py `RecordSearchProvider` Protocol.
+ *
+ * Hit shape: the guaranteed intersection across providers and the
+ * lexical fallback is `{scope, kind, name, score}` — richer providers
+ * may carry extra fields that callers must treat as optional.
+ */
+export interface RecordSearchProvider {
+    search(opts: {
+        scope: string;
+        queryText: string;
+        kind?: string | null;
+        k?: number;
+        tenant?: string;
+    }): Promise<Array<Record<string, unknown>>>;
+}
+/**
+ * Sibling port to `RecordSearchProvider` (rsh-memory-similarity-evolution →
+ * rec-embedding-port): turn text into dense vectors so the search plane can do
+ * real similarity instead of the lexical fallback. The kernel core gains NO ML
+ * deps — a real provider (ONNX all-MiniLM-L6-v2 via `@huggingface/transformers`,
+ * an optional peer dep) registers itself on the kernel at app boot; when none
+ * is registered, `kernel.embed()` uses the deterministic hash-based
+ * `FakeEmbeddingProvider` (the zero-dep offline floor that runs in CI).
+ *
+ * Parity: the FAKE is bit-exact Py↔TS by construction (integer feature-hashing
+ * + IEEE-754 ops — see `src/kernel/embedding.ts`); a real ONNX provider is
+ * parity-by-artifact (same model id, cosine ≈ 1). 1:1 with the Py
+ * `EmbeddingPort` Protocol.
+ *
+ * Contract:
+ *  - `embed(texts)` returns one vector per input text, each of length `dims`,
+ *    in input order. Empty input → empty array.
+ *  - `dims` is the fixed output dimensionality (same for every vector).
+ *  - `modelId` identifies the embedding space; vectors from providers with
+ *    different `modelId` are NOT comparable.
+ */
+export interface EmbeddingPort {
+    readonly modelId: string;
+    readonly dims: number;
+    embed(texts: string[]): Promise<number[][]>;
+}
+/**
+ * @deprecated s-sourceport-contract-cleanup — the record-plane contract was
+ * UNIFIED into `WritableSourcePort` (+ the `query`/`count` read half declared
+ * on `SourcePort`). This alias preserves the old name for existing importers;
+ * its shape is exactly the four ops the F2 D2 port formalized:
+ * `saveDocument`/`deleteDocument` (write half) + non-optional `query`/`count`
+ * (read half). The fifth record-plane operation, `search`, still lives on
+ * `RecordSearchProvider` registered on the kernel. New code should reference
+ * `WritableSourcePort` / `SourcePort` directly.
+ */
+export type RecordStorePort = Pick<WritableSourcePort, "saveDocument" | "deleteDocument"> & Required<Pick<SourcePort, "query" | "count">>;
+export declare class ResolveError extends Error {
+    constructor(message?: string);
+}
+export declare class ResolveNotFoundError extends ResolveError {
+    constructor(message?: string);
+}
+export declare class ResolveAuthError extends ResolveError {
+    constructor(message?: string);
+}
+export declare class ResolveNetworkError extends ResolveError {
+    constructor(message?: string);
+}
+export type StoragePattern = "bundle" | "yaml" | "root" | "standalone";
+export type BodyMode = "text" | "list" | "sections";
+export interface StorageDescriptor {
+    container: string;
+    pattern: StoragePattern;
+    marker?: string;
+    bodyAs?: BodyMode;
+    bodyField?: string;
+    bodyParser?: (body: string) => Record<string, unknown>;
+}
+export declare const SD: {
+    bundle(container: string, marker: string, bodyAs?: BodyMode, bodyField?: string): StorageDescriptor;
+    yaml(container: string): StorageDescriptor;
+    root(filename?: string): StorageDescriptor;
+    standalone(filename: string, bodyAs?: BodyMode, bodyField?: string): StorageDescriptor;
+};
+export declare function defaultVisibleInBackend(storage: StorageDescriptor | null | undefined): boolean;
+export declare function resolveVisibleInBackend(kp: KindPort): boolean;
+/** WHERE — load documents from storage.
+ *
+ * v1.0 async refactor: read methods return `Promise<...>` so adapters
+ * with non-local backends (Postgres, HTTP, S3) can implement them
+ * naturally. Filesystem adapter wraps sync impls in `Promise.resolve`
+ * for back-compat.
+ */
+export interface SourcePort {
+    readonly supportsReaders: boolean;
+    /**
+     * Phase 16 — return the docs the kernel needs registered/parsed
+     * BEFORE ``loadAll`` fires (Genome + KindDefinition + LayerPolicy).
+     * Adapters that can filter cheaply (SQL ``WHERE kind IN (...)``)
+     * SHOULD do so. Filesystem adapters MAY return a superset.
+     *
+     * Tenant semantics: when ``opts.tenant`` is set, the tenant-published
+     * Genome shadows the platform Genome (Phase 9 multi-tenant
+     * publishing). KindDefinition + LayerPolicy stay platform-only
+     * (non-overlayable per Phase 16).
+     *
+     * 1:1 parity with Python ``SourcePort.load_bootstrap_docs``.
+     */
+    loadBootstrapDocs(scope: string, opts?: {
+        tenant?: string;
+    }): Promise<Record<string, unknown>[]>;
+    loadAll(scope: string, readers?: ReaderPort[]): Promise<Record<string, unknown>[]>;
+    resolveRef(scope: string, ref: string): Promise<string>;
+    loadLayer(scope: string, layerId: string, layerValue: string, readers?: ReaderPort[]): Promise<Record<string, unknown>[]>;
+    /**
+     * Release adapter-held resources (connection pools, file handles, …).
+     * Mirror of the Py `SourcePort.close` (a SOURCE_PORT_CORE_MEMBERS entry
+     * behind the Py boot gate). OPTIONAL on the TS interface — the kernel
+     * treats a missing `close` as a no-op: `FilesystemSource` implements a
+     * documented no-op (nothing to release), `PostgresSource` ends its
+     * owned pool.
+     */
+    close?(): Promise<void>;
+    /**
+     * OPTIONAL L1 granular access — `[kind, name]` refs of every doc in
+     * the scope, metadata only (no bundle entries, no parse). Mirror of
+     * the Py `SourcePort.list_doc_refs`. `opts.kind` filters; tenant is
+     * the union of base + overlay with the overlay shadowing base.
+     * Declared via `SourceCapabilities.granularList`
+     * (s-dna-port-surface-parity closed this TS gap).
+     */
+    listDocRefs?(scope: string, opts?: {
+        kind?: string | null;
+        tenant?: string | null;
+    }): Promise<Array<[string, string]>>;
+    /**
+     * Two-planes F2 — OPTIONAL record-plane reads. The Kernel consults the
+     * declared capabilities (`sourceCapabilities(src).queryPushdown`,
+     * s-sourceport-contract-cleanup) and raises a clear capability error
+     * otherwise. `FilesystemSource` implements both over `loadAll` + the
+     * pure helpers (`queryDocs`/`countDocs`); PG TS gets no push-down this
+     * phase (Py-only).
+     */
+    query?(scope: string, kind: string, opts?: SourceQueryOpts): AsyncIterable<Record<string, unknown>>;
+    count?(scope: string, kind: string, opts?: SourceCountOpts): Promise<CountResult>;
+    /**
+     * OPTIONAL L1 granular access — one raw doc for (scope, kind, name),
+     * tenant overlay shadowing base (mirror of the Py `SourcePort.load_one`).
+     * The Kernel consults `sourceCapabilities(src).granularOne`
+     * (s-sourceport-contract-cleanup) and falls back to `loadAll` + find
+     * (base layer only) when absent — same as the Python
+     * `_granular_doc_cached` legacy-adapter fallback.
+     */
+    loadOne?(scope: string, kind: string, name: string, opts?: {
+        readers?: ReaderPort[];
+        tenant?: string | null;
+    }): Promise<Record<string, unknown> | null>;
+    /**
+     * OPTIONAL explicit capability declaration (s-sourceport-contract-cleanup)
+     * — a literal `SourceCapabilities` from `kernel/capabilities.ts`. When
+     * absent, `sourceCapabilities()` derives structurally (deprecated path).
+     * Optional so existing third-party implementers stay source-compatible.
+     */
+    capabilities?(): import("./capabilities.js").SourceCapabilities;
+}
+/**
+ * Phase 16 — Kinds the kernel needs registered/parsed BEFORE
+ * ``loadAll`` fires. Order is meaningful: KindDefinition first
+ * (custom Kinds need to be registered before parsing other docs),
+ * LayerPolicy next (kernel reads at write-time), Genome last
+ * (root identity).
+ */
+export declare const BOOTSTRAP_KIND_NAMES: readonly ["KindDefinition", "LayerPolicy", "Genome"];
+/**
+ * Phase 16 helper — return the Genome doc for ``scope`` (or ``null``
+ * if missing). Pulls bootstrap docs and filters for the Genome Kind.
+ * Tenant-aware: when ``opts.tenant`` is set, the underlying adapter
+ * applies tenant-overlay routing (tenant-published Genome shadows
+ * platform).
+ *
+ * 1:1 parity with Python ``package_doc_for_scope``.
+ */
+export declare function packageDocForScope(source: SourcePort, scope: string, opts?: {
+    tenant?: string;
+}): Promise<Record<string, unknown> | null>;
+/** WHERE — store/retrieve installed deps.
+ *
+ * v1.0: fully async. All four methods may do filesystem / network IO
+ * (FilesystemCache uses fs/promises; Redis/HTTP caches are inherently
+ * async). Hot path concerns about prompt-building are addressed by
+ * caching results in-memory at higher layers, not by sync IO. */
+export interface CachePort {
+    has(scope: string, key: string): Promise<boolean>;
+    store(scope: string, key: string, items: CacheItem[]): Promise<void>;
+    loadKey(scope: string, key: string, readers?: ReaderPort[]): Promise<Record<string, unknown>[]>;
+    loadAll(scope: string, readers?: ReaderPort[]): Promise<Record<string, unknown>[]>;
+}
+/** FROM — fetch external deps. v1.0: async (network IO is inherently
+ * async; sync HTTP would block the event loop). */
+export interface ResolverPort {
+    resolve(uri: string, dep: Record<string, unknown>): Promise<ResolvedItem[]>;
+    cacheKey(uri: string): string;
+}
+/** Reads a bundle directory and produces a raw dict.
+ *
+ * v1.0 BundleHandle migration: signatures take a `BundleHandle`
+ * instead of a filesystem path string, so adapters with non-FS
+ * backends (Postgres, in-memory) can rehydrate bundles uniformly.
+ *
+ * Methods are async because backends may need to fetch entries
+ * from a network/database. Filesystem readers can return
+ * `Promise.resolve(...)` if their existing impl is sync.
+ */
+export interface ReaderPort {
+    detect(bundle: BundleHandle): boolean | Promise<boolean>;
+    read(bundle: BundleHandle): Record<string, unknown> | Promise<Record<string, unknown>>;
+    /** Container this Reader's Kind is rooted at (e.g. `"skills"`), or
+     *  undefined for unscoped readers (tried as fallback in every
+     *  container). Lets the scanner route bundles to the right Reader
+     *  without trying every reader's `detect()` on every subdir — H3
+     *  container-aware routing. Formal port member since
+     *  s-dna-rw-roundtrip-suite (the scanner previously duck-typed it);
+     *  Python twin: `ReaderPort._owner_container` (default None). */
+    readonly _ownerContainer?: string;
+}
+export interface SerializedFile {
+    relativePath: string;
+    /** Text content (UTF-8). Mutually exclusive with `contentBytes`. */
+    content?: string;
+    /** Binary content. Set when the entry is a non-text payload (PNG,
+     * audio, etc). Mutually exclusive with `content`. Introduced in L3
+     * (s-writer-binary-entries 2026-05-25) for parity with Python. */
+    contentBytes?: Uint8Array;
+}
+export interface SerializedDocument {
+    files: SerializedFile[];
+}
+export interface WritableSourcePort extends SourcePort {
+    /**
+     * Persist a raw document. Adapters decide their own serialization
+     * strategy (filesystem writes bundles, HTTP adapters POST raw JSON,
+     * DB adapters insert rows). Returns an opaque version id; adapters
+     * without real versioning return "1".
+     */
+    saveDocument(scope: string, kind: string, name: string, raw: Record<string, unknown>, options?: {
+        author?: string;
+        tenant?: string | null;
+        layer?: [string, string];
+    }): Promise<string>;
+    /**
+     * Delete a document. Adapters handle the mechanics (rm -rf for
+     * bundle filesystems, DELETE for HTTP, DELETE FROM for SQL, etc.).
+     */
+    deleteDocument(scope: string, kind: string, name: string, options?: {
+        author?: string;
+        tenant?: string | null;
+        layer?: [string, string];
+    }): Promise<void>;
+    /**
+     * Optional version history. Stub adapters return []; real adapters
+     * (Postgres, etc.) return { id: string }[] newest first.
+     */
+    listVersions?(scope: string, kind: string, name: string): Promise<Array<{
+        id: string;
+    }>>;
+    /**
+     * Optional single-version fetch (the `Versionable` capability;
+     * `PostgresSource` implements it). Mirror of the Py
+     * `WritableSourcePort.get_version`.
+     */
+    getVersion?(scope: string, kind: string, name: string, versionId: string): Promise<Record<string, unknown>>;
+    /**
+     * Optional draft→published promotion. Mirror of the Py
+     * `WritableSourcePort.publish`. The TS PG adapter is a documented
+     * single-step no-op (writes go live immediately; no draft state) —
+     * adapters with a real draft store return the published version id.
+     * The Py-only `save_manifest` / `load_drafts` / `list_scopes` half is
+     * a JUSTIFIED asymmetry — see
+     * tests/parity-fixtures/port-surface-parity.json.
+     */
+    publish?(scope: string, kind: string, name: string): Promise<string>;
+}
+/** Writes a raw dict back to a bundle directory. Inverse of ReaderPort.
+ *
+ * v1.0 BundleHandle migration: write signature takes BundleHandle
+ * (was: filesystem path string). Adapters provide the right handle
+ * for their backend; the writer's job is purely to format files into
+ * `bundle.writeText/writeBytes` calls.
+ *
+ * s-dna-rw-roundtrip-suite: `serialize` is REQUIRED — part of the
+ * contract (it was load-bearing but optional: `kernel.serializeDocument`
+ * consumed it behind a presence check, so a conforming writer could
+ * silently miss it and only fail at emission time). `write` and
+ * `serialize` must stay COHERENT: `write(bundle, raw)` must produce
+ * exactly the entries `serialize(raw)` returns. The round-trip
+ * conformance suite enforces this for every registered pair.
+ * Python twin: `WriterPort.serialize` returning
+ * `[{relativePath, content | content_bytes}]`.
+ */
+export interface WriterPort {
+    canWrite(raw: Record<string, unknown>): boolean;
+    write(bundle: BundleHandle, raw: Record<string, unknown>): void | Promise<void>;
+    serialize(raw: Record<string, unknown>): SerializedFile[];
+}
+/**
+ * Optional presentation/UX capability of a Kind.
+ *
+ * Py twin: the `KindPresentation` capability Protocol in protocols.py —
+ * kept OFF Python's runtime_checkable `KindPort` so the H1 isinstance
+ * registration gate never requires these members on a minimal Kind
+ * (s-dna-kindport-descriptor-schema). TS interfaces express the same
+ * contract natively as optional members; `KindPort` extends this slice.
+ * The Py↔TS pairing is tracked in
+ * `tests/parity-fixtures/port-surface-parity.json` (KindPresentation port).
+ */
+export interface KindPresentation {
+    /** Canonical prose documentation. May be overridden at load time by a DOCS.md file
+     *  alongside the extension's source. Resolved prose is cached on `_resolvedDocs`. */
+    readonly docs?: string;
+    /** Spec field to derive metadata.description from when none was declared. */
+    readonly descriptionFallbackField?: string | null;
+    /** Per-field UI hints for Studio form rendering, keyed by spec field
+     *  name (widget/label/help/language/height/order — see
+     *  `docs/KIND-UI-HINTS.md`). When absent, consumers infer the widget
+     *  from the value type. */
+    readonly uiSchema?: Record<string, Record<string, unknown>>;
+    /** Colors for mermaid diagrams, graph nodes, and other visualizations. */
+    readonly graphStyle?: {
+        fill: string;
+        stroke: string;
+        textColor: string;
+    };
+    /** Single emoji or character for ASCII tree / compact views. */
+    readonly asciiIcon?: string;
+    /** Human-friendly plural label (e.g. "Agents" for Agent). */
+    readonly displayLabel?: string;
+    /** Explicit backend-visibility override; unset/null falls back to
+     *  `defaultVisibleInBackend(storage)` — see `resolveVisibleInBackend`. */
+    readonly visibleInBackend?: boolean | null;
+    /**
+     * Optional: returns renderable blocks for the Studio's preview pane.
+     * Each extension implements this for its own kinds. When undefined,
+     * the kernel falls back to `genericSpecDump` from preview.ts.
+     */
+    preview?(doc: Document): PreviewBlock[];
+    /** Per-doc annotations for graph rendering and health checks.
+     *  e.g. Guardrail returns {severity, scope, rules}.
+     *  Agent returns {model, soul, skills_count}. */
+    graphMeta?(doc: Document): Record<string, unknown> | null;
+}
+/** WHO — identity + composition role.
+ *
+ * Core contract + the optional `KindPresentation` slice. Python's twin
+ * keeps the two apart at runtime (`KindPort` runtime_checkable Protocol
+ * + `KindPresentation` typing-only capability); TS folds the optional
+ * slice in via `extends` — structural typing has no isinstance gate to
+ * protect. */
+export interface KindPort extends KindPresentation {
+    readonly apiVersion: string;
+    readonly kind: string;
+    readonly alias: string;
+    readonly origin?: string;
+    /**
+     * Optional tenant scope declaration. When unset (Phase 1 default),
+     * the kernel treats the kind permissively (back-compat). Phase 2
+     * iterates through every Extension to set TENANTED or GLOBAL
+     * explicitly, flipping enforcement on per-Kind. See TenantScope.
+     */
+    readonly scope?: TenantScope;
+    readonly isRoot: boolean;
+    readonly isPromptTarget: boolean;
+    readonly promptTargetPriority: number;
+    readonly flattenInContext: boolean;
+    readonly storage: StorageDescriptor;
+    /**
+     * `true` for Kinds whose documents are produced by runtime workflows
+     * (eval engine, GAIA pipeline, autolab loop, evidence-capture hooks)
+     * rather than authored as source-of-truth. Tools that replicate "the
+     * inputs to the system" — filesystem→Postgres seed, catalog publish,
+     * manifest export — MUST skip Kinds where this is true so they don't
+     * re-inject historical execution data as canonical configuration.
+     * Default `false` (provided by KindBase) keeps existing extensions
+     * unchanged.
+     */
+    readonly isRuntimeArtifact: boolean;
+    readonly isSchemaAffecting?: boolean;
+    readonly isOverlayable?: boolean;
+    readonly scopeInheritable?: boolean;
+    readonly plane?: "record" | "composition";
+    depFilters(): Record<string, string> | null;
+    getDefaultAgentName(doc: Document): string | null;
+    getLayerPolicies(doc: Document): Record<string, LayerPolicy | string> | null;
+    parse(raw: Record<string, unknown>): unknown;
+    describe(doc: Document): string | null;
+    summary(doc: Document): Record<string, unknown> | null;
+    promptTemplate(): string | null;
+    /** JSON Schema for this kind's spec. Zod-based kinds convert their schema;
+     *  declarative kinds return native JSON Schema. */
+    schema?(): Record<string, unknown> | null;
+    /** Which spec fields reference other kinds by alias.
+     *  Clearer name for depFilters(). */
+    dependencies?(): Record<string, string> | null;
+}
+/**
+ * An invocable tool exposed to agents. This port carries the DNA discovery
+ * metadata (group, hitl, scope); the underlying callable stays framework-
+ * native and is never wrapped or serialized.
+ */
+export interface ToolPort {
+    readonly name: string;
+    /** Tool group (cognitive | manifest | code | docs | web | write | eval |
+     *  eval_lab | …). `null` = registered but not group-filterable (rare). */
+    readonly group: string | null;
+    /** Full docstring / long description. */
+    readonly description: string;
+    /** First paragraph of the description. */
+    readonly summary: string;
+    /** JSON Schema of the tool's arguments (best-effort; may be `{}`). */
+    readonly argsSchema: Record<string, unknown>;
+    /** Write tool that needs a HumanInTheLoop interrupt at the root graph. */
+    readonly hitl: boolean;
+    /** Layer-policy hint — "tenant" respects tenant overlay, "global"
+     *  doesn't. Reserved for future use. */
+    readonly scope: string | null;
+    /** Module file name that defined the tool (best-effort). */
+    readonly source: string;
+    /** Return the underlying invocable (framework-native tool or function). */
+    getCallable(): unknown;
+}
+/**
+ * Concrete ToolPort implementation, stored in the kernel's ToolRegistry.
+ * Twin of the Py `ToolDefinition` dataclass — the `callable` init field
+ * holds the framework-native invocable; `getCallable()` is the canonical
+ * accessor (never serialize or wrap-replace it).
+ */
+export declare class ToolDefinition implements ToolPort {
+    readonly name: string;
+    readonly group: string | null;
+    readonly description: string;
+    readonly summary: string;
+    readonly argsSchema: Record<string, unknown>;
+    readonly hitl: boolean;
+    readonly scope: string | null;
+    readonly source: string;
+    private readonly _callable;
+    constructor(init: {
+        name: string;
+        group?: string | null;
+        description?: string;
+        summary?: string;
+        argsSchema?: Record<string, unknown>;
+        hitl?: boolean;
+        scope?: string | null;
+        source?: string;
+        callable?: unknown;
+    });
+    getCallable(): unknown;
+}
+/**
+ * The registration-time surface the Kernel offers to `Extension.register()`.
+ *
+ * This is the *explicit contract* of what an extension may call while it is
+ * being loaded (s-dna-extension-host-contract). It is a narrow slice of the
+ * Kernel — the registration vocabulary — NOT the whole Kernel API. Derived
+ * from actual usage across every builtin extension:
+ *
+ * - `kind(kp)`              — register a KindPort (identity + composition)
+ * - `kindFromDescriptor()`  — register a record Kind from a
+ *                             `kinds/*.kind.yaml` descriptor (F3 — Kinds as
+ *                             data). Pair with `loadDescriptors()` from
+ *                             `./descriptor-loader.js`.
+ * - `reader(r)`             — register a ReaderPort (detect/scan a format)
+ * - `writer(w)`             — register a WriterPort (write a format)
+ * - `on(hook, fn)`          — subscribe to an event (e.g. `post_save`)
+ * - `onVeto(hook, fn)`      — register a veto listener (e.g. `pre_save`
+ *                             write guards — throwing vetoes the operation)
+ * - `tool(td)`              — register a ToolDefinition (DNA tool discovery
+ *                             metadata; queried via `kernel.getTools()`)
+ * - `compositionProfile()`  — register orchestrator kind wiring
+ * - `hooks`                 — the HookRegistry itself, for advanced listener
+ *                             management (`kernel.hooks.onVeto(..., {key})`)
+ *
+ * The real `Kernel` satisfies this interface structurally (statically
+ * asserted in `tests/extension-host-contract.test.ts`). Py twin:
+ * `ExtensionHost` in `dna/kernel/protocols.py`.
+ */
+export interface ExtensionHost {
+    /** The HookRegistry the `on`/`onVeto` conveniences delegate to. */
+    readonly hooks: HookRegistry;
+    kind(kp: KindPort): void;
+    kindFromDescriptor(raw: Record<string, unknown>): KindPort;
+    reader(r: ReaderPort): void;
+    writer(w: WriterPort): void;
+    on(hook: HookNameArg, fn: (ctx: HookContext) => void): void;
+    onVeto(hook: HookNameArg, fn: VetoHandler, opts?: {
+        priority?: number;
+        key?: string;
+    }): void;
+    tool(td: ToolDefinition): void;
+    compositionProfile(profile: CompositionProfile): void;
+}
+/**
+ * Registers kinds, readers, and writers on the Kernel.
+ *
+ * The `templates?()` method is INTENTIONALLY OPTIONAL so extensions that
+ * predate Phase 0 (i.e. shipped before the Template contract existed)
+ * keep satisfying the `Extension` contract without modification. When
+ * present, `Kernel.listTemplates()` aggregates entries from every loaded
+ * extension so UIs (Tauri Studio, CLI) can offer `scaffold()` for any
+ * extension-shipped file tree. See `./templates.ts` for the payload
+ * shape.
+ */
+export interface Extension {
+    readonly name: string;
+    readonly version: string;
+    /**
+     * Wire the extension into the kernel. `kernel.load(ext)` fail-loud
+     * validates the whole contract first (`name` non-empty string,
+     * `version` string, `register` callable → `ExtensionLoadError`
+     * otherwise), then calls `register()` with the registration-time
+     * host slice — see {@link ExtensionHost} for the exact vocabulary.
+     */
+    register(kernel: ExtensionHost): void;
+    /** Optional — return the file-tree scaffolds this extension ships. */
+    templates?(): Template[];
+}
+export type { Template, OnConflict, MaterializeOptions, } from "./templates.js";
+import type { Template } from "./templates.js";