dna-sdk 0.1.0

package/dist/kernel/instance.d.ts

@@ -0,0 +1,211 @@
+/**
+ * ManifestInstance v3 — public API for querying manifest documents.
+ *
+ * Provides query (all/one/root), navigation (get/describe/listKinds/summary),
+ * prompt building (buildPrompt with template cascade), and layer resolution.
+ *
+ * Method bodies delegate to namespace classes (PromptBuilder, CompositionEngine,
+ * Navigator, LockManager) and viz/ functions. The old API surface is preserved
+ * as one-line delegates for backwards compatibility.
+ *
+ * 1:1 parity with Python dna.v3.kernel.instance.
+ */
+import { Document } from "./document.js";
+import type { Lockfile } from "./lock.js";
+import type { CompositionResult, KindPort, SourcePort } from "./protocols.js";
+import type { CompositionProfile } from "./composition-resolver.js";
+import type { PreviewBlock } from "./preview.js";
+import { PromptBuilder } from "./prompt-builder.js";
+import { CompositionEngine } from "./composition-resolver.js";
+import { Navigator } from "./navigator.js";
+import { LockManager } from "./lock-manager.js";
+import { ReportBuilder } from "./reports.js";
+export type { PreviewBlock };
+/** @internal Test hook — reset the once-per-process deprecation state. */
+export declare function _resetDeprecationWarnings(): void;
+export interface ManifestInstanceOpts {
+    scope: string;
+    documents: Document[];
+    kinds: Map<string, KindPort>;
+    source?: SourcePort | null;
+    resolveErrors?: string[];
+    kernel?: unknown;
+    profiles?: CompositionProfile[];
+}
+export interface BuildPromptOpts {
+    agent?: string;
+    context?: Record<string, unknown>;
+    /** Generic slot filtering: keys are slot names from the CompositionProfile,
+     *  values are arrays of doc names to keep. */
+    enabledSlots?: Record<string, string[]>;
+    /** @deprecated Use enabledSlots.skills instead. Kept for backwards compat. */
+    enabledSkills?: string[];
+    /** @deprecated Use enabledSlots.guardrails instead. */
+    enabledGuardrails?: string[];
+}
+export declare class ManifestInstance {
+    readonly scope: string;
+    readonly documents: Document[];
+    readonly resolveErrors: string[];
+    private _kinds;
+    private _source;
+    private _kernel;
+    private _root;
+    private _compositionResult;
+    /** Composition profiles registered by extensions. */
+    readonly _profiles: readonly CompositionProfile[];
+    private _promptBuilder;
+    private _compositionEngine;
+    private _navigator;
+    private _lockManager;
+    private _reportBuilder;
+    constructor(opts: ManifestInstanceOpts);
+    get prompt(): PromptBuilder;
+    get composition(): CompositionEngine;
+    get nav(): Navigator;
+    get lock(): LockManager;
+    get reports(): ReportBuilder;
+    /**
+     * Find the CompositionProfile for a document's kind (via its alias).
+     * Returns null if no profile covers this kind.
+     */
+    profileFor(doc: Document): CompositionProfile | null;
+    /**
+     * Return all docs of `kind`.
+     *
+     * @deprecated Will be removed in 1.0 — filter `mi.documents`
+     * (e.g. `mi.documents.filter((d) => d.kind === kind)`) or use
+     * `kernel.query(scope, kind)` for indexed/record-plane reads.
+     * (s-blessed-query-surface)
+     */
+    all(kind: string): Document[];
+    /** @internal Non-warning twin of `all()` — used by the SDK's own
+     *  collaborators (`applyHooks`, `ReportBuilder`, viz). External
+     *  callers use the blessed surface (`mi.documents` / `kernel.query`). */
+    _all(kind: string): Document[];
+    /**
+     * Lookup a single doc by (kind, name).
+     *
+     * @deprecated Will be removed in 1.0 — search `mi.documents`
+     * (e.g. `mi.documents.find((d) => d.kind === kind && d.name === name) ??
+     * null`) or use `kernel.query(scope, kind)` with a filter for
+     * indexed/record-plane reads. (s-blessed-query-surface)
+     */
+    one(kind: string, name: string): Document | null;
+    /** @internal Non-warning twin of `one()` — used by the SDK's own
+     *  collaborators (`readSpec*`, `readMetadata`). External callers use
+     *  the blessed surface (`mi.documents` / `kernel.query`). */
+    _one(kind: string, name: string): Document | null;
+    /**
+     * Return the KindPort registered for `kind` (by kind name), or null.
+     */
+    kindFor(kind: string): KindPort | null;
+    /**
+     * True when the document's KindPort is marked as the manifest root.
+     */
+    isRootDoc(doc: Document): boolean;
+    /**
+     * Return all documents whose registered KindPort satisfies a predicate.
+     */
+    allWhere(predicate: (kp: KindPort) => boolean): Document[];
+    /**
+     * Return the KindPort whose `alias` matches, or null.
+     */
+    kindForAlias(alias: string): KindPort | null;
+    /**
+     * Iterate a document's declared dep_filters dynamically.
+     * Delegates to CompositionEngine.
+     */
+    iterDocDeps(doc: Document): {
+        label: string;
+        targetKind: string;
+        names: string[];
+    }[];
+    get root(): Document | null;
+    readSpec(kind: string, name: string, field: string): unknown;
+    readSpecString(kind: string, name: string, field: string): string | undefined;
+    readSpecStringArray(kind: string, name: string, field: string): string[];
+    readMetadata(kind: string, name: string, field: string): unknown;
+    defaultAgent(): Document | null;
+    get compositionResult(): CompositionResult;
+    listKinds(): string[];
+    /**
+     * Return every kind REGISTERED in this manifest (not just those that have
+     * documents on disk).
+     */
+    allKinds(): Array<{
+        kind: string;
+        alias: string;
+        apiVersion: string;
+        origin: string | null;
+    }>;
+    renderDoc(kind: string, name: string): PreviewBlock[];
+    consumersOf(kind: string, name: string): Array<{
+        kind: string;
+        name: string;
+    }>;
+    get(kind?: string): Array<{
+        kind: string;
+        name: string;
+        apiVersion: string;
+    }>;
+    describe(kind: string, name: string): string;
+    summary(): string;
+    inventory(): Record<string, unknown>;
+    dependencyTree(): Record<string, unknown>;
+    erModel(): {
+        entities: {
+            id: string;
+            kind: string;
+            name: string;
+            attrs: {
+                key: string;
+                type: string;
+                value: string;
+            }[];
+        }[];
+        relationships: {
+            sourceId: string;
+            targetId: string;
+            label: string;
+            isMany: boolean;
+        }[];
+    };
+    dependencyTreeMermaid(): string;
+    compositionFlowchartMermaid(): string;
+    c4ComponentMermaid(): string;
+    erDiagramMermaid(): string;
+    mindmapMermaid(): string;
+    pieChartMermaid(): string;
+    quadrantMermaid(): string;
+    timelineMermaid(): string;
+    sankeyMermaid(): string;
+    kindCatalogMermaid(): string;
+    exportDiagramsMd(path?: string): Record<string, string>;
+    matrix(): Record<string, unknown>;
+    matrixMarkdown(): string;
+    health(): Record<string, unknown>;
+    impact(kind: string, name: string): Record<string, unknown>;
+    asciiTree(): string;
+    /**
+     * Resolve a ref-like value (path or markdown/yaml/txt filename).
+     *
+     * v1.0 async refactor: SourcePort.resolveRef is async, so this is
+     * async too. Cascades to PromptBuilder.build() and
+     * ManifestInstance.buildPrompt() — every prompt build is async.
+     * That's the honest contract — the alternative (cache-based sync
+     * ref) requires knowing every ref at scope load time, which doesn't
+     * hold for dynamic context fields.
+     */
+    ref(value: string): Promise<string>;
+    buildPrompt(opts?: BuildPromptOpts): Promise<string>;
+    resolve(layers?: Record<string, string>): ManifestInstance;
+    generateLock(): Lockfile;
+    /** Auto-register Hook documents on the kernel's HookRegistry. */
+    applyHooks(): void;
+    /** Find the best prompt-target document matching `name`.
+     *  Considers promptTargetPriority when multiple kinds match. */
+    findAgent(name: string): Document | null;
+    /** @internal */
+    _findAgent(name: string): Document | null;
+}

package/dist/kernel/instance.js

@@ -0,0 +1,487 @@
+/**
+ * ManifestInstance v3 — public API for querying manifest documents.
+ *
+ * Provides query (all/one/root), navigation (get/describe/listKinds/summary),
+ * prompt building (buildPrompt with template cascade), and layer resolution.
+ *
+ * Method bodies delegate to namespace classes (PromptBuilder, CompositionEngine,
+ * Navigator, LockManager) and viz/ functions. The old API surface is preserved
+ * as one-line delegates for backwards compatibility.
+ *
+ * 1:1 parity with Python dna.v3.kernel.instance.
+ */
+import { readSpecString, readSpecStringArray } from "./spec-access.js";
+import { ScannerPipeline } from "./safety-scanner.js";
+import { profileForOrchestrator } from "./composition-resolver.js";
+import { PromptBuilder } from "./prompt-builder.js";
+import { CompositionEngine } from "./composition-resolver.js";
+import { Navigator } from "./navigator.js";
+import { LockManager } from "./lock-manager.js";
+import { ReportBuilder } from "./reports.js";
+// Viz imports — all use `import type { ManifestInstance }` so no circular issue at runtime.
+import { dependencyTreeMermaid as vizDependencyTreeMermaid, compositionFlowchartMermaid as vizCompositionFlowchartMermaid, c4ComponentMermaid as vizC4ComponentMermaid, erDiagramMermaid as vizErDiagramMermaid, erModel as vizErModel, mindmapMermaid as vizMindmapMermaid, pieChartMermaid as vizPieChartMermaid, quadrantMermaid as vizQuadrantMermaid, timelineMermaid as vizTimelineMermaid, sankeyMermaid as vizSankeyMermaid, kindCatalogMermaid as vizKindCatalogMermaid, exportDiagramsMd as vizExportDiagramsMd, } from "../viz/mermaid.js";
+import { healthReport as vizHealthReport, impact as vizImpact } from "../viz/health.js";
+import { matrix as vizMatrix, matrixMarkdown as vizMatrixMarkdown } from "../viz/matrix.js";
+import { asciiTree as vizAsciiTree } from "../viz/ascii.js";
+/**
+ * s-kernel-sandbox-hook-exec — whether a Hook's `action: "script"` may run
+ * arbitrary code from `spec.body` via `new Function(...)`. OFF by default: a
+ * Hook doc is reachable via the normal doc-write path, so executing its body is
+ * an unauthenticated RCE in the host process. Opt in with
+ * `DNA_ALLOW_HOOK_SCRIPT_EXEC=1` only in trusted single-tenant deployments.
+ * 1:1 with the Python twin (dna.operations._hook_script_exec_allowed).
+ */
+function hookScriptExecAllowed() {
+    return (typeof process !== "undefined" &&
+        process.env?.DNA_ALLOW_HOOK_SCRIPT_EXEC === "1");
+}
+// ---------------------------------------------------------------------------
+// Deprecation plumbing (s-blessed-query-surface)
+// ---------------------------------------------------------------------------
+/** Methods that already fired their once-per-process deprecation warning. */
+const _deprecationWarned = new Set();
+/** `console.warn` a deprecation message once per method per process —
+ *  mirror of the Python `DeprecationWarning` on the same members. */
+function warnDeprecatedOnce(method, message) {
+    if (_deprecationWarned.has(method))
+        return;
+    _deprecationWarned.add(method);
+    console.warn(message);
+}
+/** @internal Test hook — reset the once-per-process deprecation state. */
+export function _resetDeprecationWarnings() {
+    _deprecationWarned.clear();
+}
+// ---------------------------------------------------------------------------
+// ManifestInstance
+// ---------------------------------------------------------------------------
+export class ManifestInstance {
+    scope;
+    documents;
+    resolveErrors;
+    _kinds;
+    _source;
+    _kernel;
+    _root = undefined; // undefined = not computed
+    _compositionResult = undefined;
+    /** Composition profiles registered by extensions. */
+    _profiles;
+    // -- Namespace instances (lazy) --------------------------------------------
+    _promptBuilder = null;
+    _compositionEngine = null;
+    _navigator = null;
+    _lockManager = null;
+    _reportBuilder = null;
+    constructor(opts) {
+        this.scope = opts.scope;
+        this.documents = opts.documents;
+        this._kinds = opts.kinds;
+        this._source = opts.source ?? null;
+        this._kernel = opts.kernel ?? null;
+        this.resolveErrors = opts.resolveErrors ?? [];
+        this._profiles = opts.profiles ?? [];
+    }
+    // -- Namespace getters (lazy, memoized) ------------------------------------
+    get prompt() {
+        return this._promptBuilder ??= new PromptBuilder(this);
+    }
+    get composition() {
+        return this._compositionEngine ??= new CompositionEngine(this);
+    }
+    get nav() {
+        return this._navigator ??= new Navigator(this);
+    }
+    get lock() {
+        return this._lockManager ??= new LockManager(this);
+    }
+    get reports() {
+        return this._reportBuilder ??= new ReportBuilder(this);
+    }
+    /**
+     * Find the CompositionProfile for a document's kind (via its alias).
+     * Returns null if no profile covers this kind.
+     */
+    profileFor(doc) {
+        const kp = this._kinds.get(`${doc.apiVersion}\0${doc.kind}`);
+        if (!kp)
+            return null;
+        return profileForOrchestrator(this._profiles, kp.alias);
+    }
+    // -- Query ----------------------------------------------------------------
+    /**
+     * Return all docs of `kind`.
+     *
+     * @deprecated Will be removed in 1.0 — filter `mi.documents`
+     * (e.g. `mi.documents.filter((d) => d.kind === kind)`) or use
+     * `kernel.query(scope, kind)` for indexed/record-plane reads.
+     * (s-blessed-query-surface)
+     */
+    all(kind) {
+        warnDeprecatedOnce("all", "ManifestInstance.all() is deprecated and will be removed in 1.0 — " +
+            "filter mi.documents (e.g. `mi.documents.filter((d) => d.kind === " +
+            "kind)`) or use `kernel.query(scope, kind)` for " +
+            "indexed/record-plane reads.");
+        return this._all(kind);
+    }
+    /** @internal Non-warning twin of `all()` — used by the SDK's own
+     *  collaborators (`applyHooks`, `ReportBuilder`, viz). External
+     *  callers use the blessed surface (`mi.documents` / `kernel.query`). */
+    _all(kind) {
+        return this.documents.filter((d) => d.kind === kind);
+    }
+    /**
+     * Lookup a single doc by (kind, name).
+     *
+     * @deprecated Will be removed in 1.0 — search `mi.documents`
+     * (e.g. `mi.documents.find((d) => d.kind === kind && d.name === name) ??
+     * null`) or use `kernel.query(scope, kind)` with a filter for
+     * indexed/record-plane reads. (s-blessed-query-surface)
+     */
+    one(kind, name) {
+        warnDeprecatedOnce("one", "ManifestInstance.one() is deprecated and will be removed in 1.0 — " +
+            "search mi.documents (e.g. `mi.documents.find((d) => d.kind === " +
+            "kind && d.name === name) ?? null`) or use `kernel.query(scope, " +
+            "kind)` with a filter for indexed/record-plane reads.");
+        return this._one(kind, name);
+    }
+    /** @internal Non-warning twin of `one()` — used by the SDK's own
+     *  collaborators (`readSpec*`, `readMetadata`). External callers use
+     *  the blessed surface (`mi.documents` / `kernel.query`). */
+    _one(kind, name) {
+        return (this.documents.find((d) => d.kind === kind && d.name === name) ?? null);
+    }
+    /**
+     * Return the KindPort registered for `kind` (by kind name), or null.
+     */
+    kindFor(kind) {
+        for (const [key, kp] of this._kinds) {
+            const kn = key.split("\0")[1] ?? "";
+            if (kn === kind)
+                return kp;
+        }
+        return null;
+    }
+    /**
+     * True when the document's KindPort is marked as the manifest root.
+     */
+    isRootDoc(doc) {
+        const kp = this._kinds.get(`${doc.apiVersion}\0${doc.kind}`);
+        return kp?.isRoot === true;
+    }
+    /**
+     * Return all documents whose registered KindPort satisfies a predicate.
+     */
+    allWhere(predicate) {
+        return this.documents.filter((d) => {
+            const kp = this._kinds.get(`${d.apiVersion}\0${d.kind}`);
+            return kp ? predicate(kp) : false;
+        });
+    }
+    /**
+     * Return the KindPort whose `alias` matches, or null.
+     */
+    kindForAlias(alias) {
+        for (const kp of this._kinds.values()) {
+            if (kp.alias === alias)
+                return kp;
+        }
+        return null;
+    }
+    /**
+     * Iterate a document's declared dep_filters dynamically.
+     * Delegates to CompositionEngine.
+     */
+    iterDocDeps(doc) {
+        return this.composition.iterDocDeps(doc);
+    }
+    get root() {
+        if (this._root !== undefined)
+            return this._root;
+        // Phase 16 — Genome is the canonical root Kind. ModuleKind class
+        // is gone; legacy ``kind: Module`` docs no longer parse.
+        for (const d of this.documents) {
+            const kp = this._kinds.get(`${d.apiVersion}\0${d.kind}`);
+            if (kp?.isRoot) {
+                this._root = d;
+                return d;
+            }
+        }
+        this._root = null;
+        return null;
+    }
+    // -- Spec-access sugar (mirrors Python mi.read_spec) ---------------------
+    readSpec(kind, name, field) {
+        const doc = this._one(kind, name);
+        if (!doc) {
+            throw new Error(`${kind}/${name}: document not found in manifest`);
+        }
+        return doc.spec[field];
+    }
+    readSpecString(kind, name, field) {
+        const doc = this._one(kind, name);
+        if (!doc)
+            throw new Error(`${kind}/${name}: document not found in manifest`);
+        return readSpecString(doc, field);
+    }
+    readSpecStringArray(kind, name, field) {
+        const doc = this._one(kind, name);
+        if (!doc)
+            throw new Error(`${kind}/${name}: document not found in manifest`);
+        return readSpecStringArray(doc, field);
+    }
+    readMetadata(kind, name, field) {
+        const doc = this._one(kind, name);
+        if (!doc)
+            throw new Error(`${kind}/${name}: document not found in manifest`);
+        return doc.metadata[field];
+    }
+    defaultAgent() {
+        const root = this.root;
+        if (!root)
+            return null;
+        const kp = this._kinds.get(`${root.apiVersion}\0${root.kind}`);
+        if (!kp)
+            return null;
+        const agentName = kp.getDefaultAgentName(root);
+        if (!agentName)
+            return null;
+        return this._findAgent(agentName);
+    }
+    // -- Composition validation → CompositionEngine ---------------------------
+    get compositionResult() {
+        if (this._compositionResult !== undefined)
+            return this._compositionResult;
+        this._compositionResult = this.composition.validate();
+        return this._compositionResult;
+    }
+    // -- Navigation → Navigator -----------------------------------------------
+    listKinds() {
+        return [...new Set(this.documents.map((d) => d.kind))].sort();
+    }
+    /**
+     * Return every kind REGISTERED in this manifest (not just those that have
+     * documents on disk).
+     */
+    allKinds() {
+        const out = [];
+        for (const kp of this._kinds.values()) {
+            out.push({
+                kind: kp.kind,
+                alias: kp.alias,
+                apiVersion: kp.apiVersion,
+                origin: kp.origin ?? null,
+            });
+        }
+        out.sort((a, b) => a.kind.localeCompare(b.kind));
+        return out;
+    }
+    renderDoc(kind, name) {
+        return this.nav.renderDoc(kind, name);
+    }
+    consumersOf(kind, name) {
+        return this.composition.consumersOf(kind, name);
+    }
+    get(kind) {
+        const docs = kind != null ? this._all(kind) : this.documents;
+        return docs.map((d) => ({
+            kind: d.kind,
+            name: d.name,
+            apiVersion: d.apiVersion,
+        }));
+    }
+    describe(kind, name) {
+        return this.nav.describe(kind, name);
+    }
+    summary() {
+        return this.nav.summary();
+    }
+    inventory() {
+        return this.nav.inventory();
+    }
+    dependencyTree() {
+        return this.composition.dependencyTree();
+    }
+    // -- ER Model → viz -------------------------------------------------------
+    erModel() {
+        return vizErModel(this);
+    }
+    // -- Mermaid diagrams → viz ------------------------------------------------
+    dependencyTreeMermaid() { return vizDependencyTreeMermaid(this); }
+    compositionFlowchartMermaid() { return vizCompositionFlowchartMermaid(this); }
+    c4ComponentMermaid() { return vizC4ComponentMermaid(this); }
+    erDiagramMermaid() { return vizErDiagramMermaid(this); }
+    mindmapMermaid() { return vizMindmapMermaid(this); }
+    pieChartMermaid() { return vizPieChartMermaid(this); }
+    quadrantMermaid() { return vizQuadrantMermaid(this); }
+    timelineMermaid() { return vizTimelineMermaid(this); }
+    sankeyMermaid() { return vizSankeyMermaid(this); }
+    kindCatalogMermaid() { return vizKindCatalogMermaid(this); }
+    exportDiagramsMd(path) { return vizExportDiagramsMd(this, path); }
+    // -- Matrix → viz ----------------------------------------------------------
+    matrix() { return vizMatrix(this); }
+    matrixMarkdown() { return vizMatrixMarkdown(this); }
+    // -- Health / Impact → viz -------------------------------------------------
+    health() { return vizHealthReport(this); }
+    impact(kind, name) { return vizImpact(this, kind, name); }
+    // -- ASCII tree → viz ------------------------------------------------------
+    asciiTree() { return vizAsciiTree(this); }
+    // -- Ref resolution -------------------------------------------------------
+    /**
+     * Resolve a ref-like value (path or markdown/yaml/txt filename).
+     *
+     * v1.0 async refactor: SourcePort.resolveRef is async, so this is
+     * async too. Cascades to PromptBuilder.build() and
+     * ManifestInstance.buildPrompt() — every prompt build is async.
+     * That's the honest contract — the alternative (cache-based sync
+     * ref) requires knowing every ref at scope load time, which doesn't
+     * hold for dynamic context fields.
+     */
+    async ref(value) {
+        if (!value)
+            return "";
+        if (this._source &&
+            (value.includes("/") || /\.(md|txt|yaml)$/.test(value))) {
+            const resolved = await this._source.resolveRef(this.scope, value);
+            if (resolved)
+                return resolved;
+        }
+        return value;
+    }
+    // -- Prompt → PromptBuilder ------------------------------------------------
+    async buildPrompt(opts) {
+        return this.prompt.build(opts);
+    }
+    // -- Layers ---------------------------------------------------------------
+    resolve(layers) {
+        if (!layers)
+            return this;
+        const kernel = this._kernel;
+        if (kernel?.resolveLayers) {
+            return kernel.resolveLayers(this, layers);
+        }
+        // Fallback if no kernel ref (e.g., constructed directly in tests)
+        return this;
+    }
+    // -- Lock → LockManager ---------------------------------------------------
+    generateLock() {
+        return this.lock.generate();
+    }
+    // -- Hook auto-registration ------------------------------------------------
+    /** Auto-register Hook documents on the kernel's HookRegistry. */
+    applyHooks() {
+        const kernel = this._kernel;
+        if (!kernel?.hooks)
+            return;
+        const hooks = this._all("Hook");
+        for (const doc of hooks) {
+            const spec = doc.spec;
+            const target = spec.target;
+            const type = spec.type;
+            const action = spec.action;
+            if (type === "middleware" && target) {
+                if (action === "inject_fields") {
+                    const fields = (spec.fields ?? {});
+                    kernel.hooks.use(target, (ctx) => {
+                        const context = (ctx.data?.context ?? {});
+                        for (const [k, v] of Object.entries(fields)) {
+                            context[k] = v;
+                        }
+                        return { ...ctx, data: { ...ctx.data, context } };
+                    });
+                }
+                else if (action === "script") {
+                    const body = spec.body ?? "";
+                    if (body.trim() && !hookScriptExecAllowed()) {
+                        console.warn(`Hook ${doc.name}: action='script' skipped — exec of Hook spec.body ` +
+                            `is disabled (RCE surface). Use a declarative action, or set ` +
+                            `DNA_ALLOW_HOOK_SCRIPT_EXEC=1 in a trusted deployment. (s-kernel-sandbox-hook-exec)`);
+                    }
+                    else if (body.trim()) {
+                        try {
+                            const fn = new Function("ctx", `return (${body.trim()})(ctx);`);
+                            kernel.hooks.use(target, (ctx) => fn(ctx));
+                        }
+                        catch (e) {
+                            console.warn(`Hook ${doc.name}: script compilation failed: ${e}`);
+                        }
+                    }
+                }
+            }
+            else if (type === "event" && target) {
+                if (action === "log") {
+                    kernel.hooks.on(target, (ctx) => {
+                        console.log(`[Hook:${doc.name}] ${target}`, {
+                            agent: ctx.agent,
+                            scope: ctx.scope,
+                            promptLength: ctx.prompt?.length,
+                        });
+                    });
+                }
+                else if (action === "script") {
+                    const body = spec.body ?? "";
+                    if (body.trim() && !hookScriptExecAllowed()) {
+                        console.warn(`Hook ${doc.name}: event action='script' skipped — exec of Hook ` +
+                            `spec.body is disabled (RCE surface). Use action='log', or set ` +
+                            `DNA_ALLOW_HOOK_SCRIPT_EXEC=1 in a trusted deployment. (s-kernel-sandbox-hook-exec)`);
+                    }
+                    else if (body.trim()) {
+                        try {
+                            const fn = new Function("ctx", `(${body.trim()})(ctx);`);
+                            kernel.hooks.on(target, (ctx) => fn(ctx));
+                        }
+                        catch (e) {
+                            console.warn(`Hook ${doc.name}: script compilation failed: ${e}`);
+                        }
+                    }
+                }
+            }
+        }
+        // -- SafetyPolicy input enforcement ----------------------------------------
+        const policies = this._all("SafetyPolicy");
+        for (const doc of policies) {
+            const spec = doc.spec;
+            const scope = spec.scope;
+            const action = spec.action;
+            const rules = (spec.rules ?? []);
+            if ((scope === "input" || scope === "both") && rules.length > 0) {
+                kernel.hooks.use("pre_build_prompt", (ctx) => {
+                    const pipeline = new ScannerPipeline(rules);
+                    const context = (ctx.data?.context ?? {});
+                    for (const [key, val] of Object.entries(context)) {
+                        if (typeof val === "string") {
+                            try {
+                                context[key] = pipeline.apply(val, action);
+                            }
+                            catch {
+                                /* block action throws — skip field */
+                            }
+                        }
+                    }
+                    return { ...ctx, data: { ...ctx.data, context } };
+                });
+            }
+        }
+    }
+    // -- Agent lookup -----------------------------------------------------------
+    /** Find the best prompt-target document matching `name`.
+     *  Considers promptTargetPriority when multiple kinds match. */
+    findAgent(name) {
+        return this._findAgent(name);
+    }
+    /** @internal */
+    _findAgent(name) {
+        let best = null;
+        let bestPriority = -1;
+        for (const d of this.documents) {
+            const kp = this._kinds.get(`${d.apiVersion}\0${d.kind}`);
+            if (kp?.isPromptTarget && d.name === name) {
+                const priority = kp.promptTargetPriority ?? 0;
+                if (priority > bestPriority) {
+                    best = d;
+                    bestPriority = priority;
+                }
+            }
+        }
+        return best;
+    }
+}