@responsibleai/agent-hooks 0.1.0-beta.1 → 0.1.0-beta.2

package/dist/emitter.js

@@ -20,8 +20,15 @@
  * serial dispatch over isolated snapshots — §7.2: parallel names
  * isolation semantics, not scheduling.
  *
- * Fail-closed defaults: an `enforce`-mode emission with zero registered
- * interceptors yields `deny host_error:no_interceptor` (§7), and
+ * An emitter can also be built from a host declaration document (§7.7)
+ * through {@link InterceptionEmitter.fromDeclaration} and the path, JSON
+ * and value forms. The document is validated and resolved by the Rust
+ * core; this module runs the host's kind resolvers (step 11 of §7.7.6),
+ * seals the emitter (§7.7.7) and stamps the contract version on every
+ * record (§7.7.8).
+ *
+ * Fail-closed defaults: an `enforce`-mode emission with zero interceptors
+ * bound at the point yields `deny host_error:no_interceptor` (§7), and
  * {@link InterceptionEmitter.emit} **throws** {@link InterceptionBlocked}
  * on any block — the ignorable-result variant is the explicitly named
  * {@link InterceptionEmitter.emitUnchecked}.
@@ -31,8 +38,9 @@
  * a single JS thread. Sharing one emitter across workers is unsupported.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.InterceptionEmitter = exports.DEFAULT_TIMEOUT_MS = void 0;
+exports.InterceptionEmitter = exports.EmitterSealed = exports.DEFAULT_TIMEOUT_MS = void 0;
 const index_1 = require("./index");
+const declaration_1 = require("./declaration");
 const native_1 = require("./native");
 /** §7 RECOMMENDED interceptor/resolver timeout (milliseconds). */
 exports.DEFAULT_TIMEOUT_MS = 5000;
@@ -43,6 +51,24 @@ class InterceptTimeout extends Error {
         this.name = "InterceptTimeout";
     }
 }
+/** Thrown when a setter or `register` is called on an emitter built
+ * from a host declaration (§7.7.7): the declaration must stay what ran. */
+/** Recursively freeze a JSON-shaped value in place and return it. */
+function deepFreeze(value) {
+    if (value !== null && typeof value === "object" && !Object.isFrozen(value)) {
+        Object.freeze(value);
+        for (const v of Object.values(value))
+            deepFreeze(v);
+    }
+    return value;
+}
+class EmitterSealed extends Error {
+    constructor(what) {
+        super(`${what}: this emitter was built from a host declaration and is sealed (see spec §7.7.7)`);
+        this.name = "EmitterSealed";
+    }
+}
+exports.EmitterSealed = EmitterSealed;
 /** Whether a verdict was synthesized by the host (§11) rather than
  * returned by an interceptor or resolver. */
 function isHostSynthesized(v) {
@@ -109,19 +135,32 @@ function synthesized(err, detail) {
     };
 }
 const NOT_CONSULTED = { consulted: false };
+/** Whether `v` looks like an interceptor (§7): an object with an
+ * `intercept` method. */
+function isInterceptor(v) {
+    return (v !== null &&
+        (typeof v === "object" || typeof v === "function") &&
+        typeof v.intercept === "function");
+}
 class InterceptionEmitter {
-    mode;
-    resolver;
-    timeoutMs;
     interceptors = [];
     _records = [];
     composition = index_1.Composition.default();
     identity = index_1.JCS_SHA256;
-    names = [];
     approvalRedactor = null;
     recordSink = null;
     maxRecords = null;
     _recordsDropped = 0;
+    mode;
+    resolver;
+    /** §7 emitter-wide interceptor bound; `null` disables enforcement. */
+    timeoutMs;
+    /** §9 resolver bound (`approval_resolver_ms`, §7.7.3); `null` disables. */
+    resolverTimeoutMs;
+    /** §7.7.7: a declaration-built emitter refuses reconfiguration. */
+    sealed = false;
+    /** The resolved declaration this emitter was built from, if any. */
+    _declaration = null;
     /**
      * `timeoutMs` bounds each interceptor `intercept()` and resolver
      * `resolve()` call (§7, RECOMMENDED default 5000 ms); breach fails
@@ -134,17 +173,151 @@ class InterceptionEmitter {
         this.mode = mode;
         this.resolver = resolver;
         this.timeoutMs = timeoutMs;
+        this.resolverTimeoutMs = timeoutMs;
+    }
+    // ---- host declaration (§7.7) ----------------------------------------------
+    /** Build an emitter from a validated declaration: steps 8 to 11 of
+     * §7.7.6 (resolve against the registry's surface and names in the
+     * core, then run every binding's kind resolver). The result is
+     * sealed (§7.7.7) and stamps `declaration` on every record (§7.7.8).
+     * Throws {@link DeclarationError} on refusal; no emitter exists then. */
+    static fromDeclaration(declaration, registry) {
+        const resolved = (0, declaration_1.resolveDeclaration)(declaration, registry);
+        return InterceptionEmitter.fromResolved(resolved, registry);
     }
-    /** Race `fn`'s result against the §7 timeout. */
-    async withTimeout(fn) {
-        if (this.timeoutMs === null)
+    /** {@link HostDeclaration.fromPath} then {@link fromDeclaration}. */
+    static async fromDeclarationPath(path, registry) {
+        return InterceptionEmitter.fromDeclaration(await declaration_1.HostDeclaration.fromPath(path), registry);
+    }
+    /** {@link HostDeclaration.fromJson} then {@link fromDeclaration}. */
+    static fromDeclarationJson(text, registry) {
+        return InterceptionEmitter.fromDeclaration(declaration_1.HostDeclaration.fromJson(text), registry);
+    }
+    /** {@link HostDeclaration.fromValue} then {@link fromDeclaration}. */
+    static fromDeclarationValue(value, registry) {
+        return InterceptionEmitter.fromDeclaration(declaration_1.HostDeclaration.fromValue(value), registry);
+    }
+    /** The resolved declaration this emitter runs under, when it was
+     * built from one (§7.7.7). Its canonical JSON is the equivalence
+     * oracle for the construction paths. The value is frozen all the
+     * way down: writing through it has no effect on dispatch or records.
+     * `null` for an emitter configured in code. */
+    get declaration() {
+        return this._declaration;
+    }
+    /** Step 11 and construction. Every reference is looked up again in
+     * the registry's own maps, so bookkeeping drift between the names the
+     * core checked and what the registry holds fails closed. */
+    static fromResolved(resolved, registry) {
+        const cfg = resolved.configuration;
+        let resolver = null;
+        if (cfg.approval.resolver !== null) {
+            const name = cfg.approval.resolver;
+            const r = registry.approvalResolverRef(name);
+            if (r === undefined) {
+                throw declaration_1.DeclarationError.single(declaration_1.DeclarationErrorClass.ReferenceUnresolved, "/configuration/approval/resolver", `approval resolver ${JSON.stringify(name)} vanished from the registry`);
+            }
+            resolver = r;
+        }
+        let identity;
+        if (cfg.identity_provider === null) {
+            identity = null;
+        }
+        else if (cfg.identity_provider === index_1.JCS_SHA256) {
+            identity = index_1.JCS_SHA256;
+        }
+        else {
+            const name = cfg.identity_provider;
+            const fn = registry.identityFn(name);
+            if (fn === undefined) {
+                throw declaration_1.DeclarationError.single(declaration_1.DeclarationErrorClass.ReferenceUnresolved, "/configuration/identity_provider", `identity provider ${JSON.stringify(name)} vanished from the registry`);
+            }
+            identity = { name, fn };
+        }
+        let approvalRedactor = null;
+        if (cfg.approval.redactor !== null) {
+            const name = cfg.approval.redactor;
+            const fn = registry.redactorFn(name);
+            if (fn === undefined) {
+                throw declaration_1.DeclarationError.single(declaration_1.DeclarationErrorClass.ReferenceUnresolved, "/configuration/approval/redactor", `approval redactor ${JSON.stringify(name)} vanished from the registry`);
+            }
+            approvalRedactor = fn;
+        }
+        const bound = [];
+        resolved.bindings.forEach((b, i) => {
+            const pointer = `/bindings/${i}`;
+            const resolverFn = registry.kindResolver(b.kind);
+            if (resolverFn === undefined) {
+                throw declaration_1.DeclarationError.single(declaration_1.DeclarationErrorClass.KindUnknown, `${pointer}/kind`, `kind ${JSON.stringify(b.kind)} vanished from the registry`);
+            }
+            // The dispatch set is fixed before the resolver runs and the
+            // context carries a frozen copy, so a resolver cannot widen its
+            // own binding (the Rust core hands out `&BTreeSet` for the same
+            // reason).
+            const at = new Set(b.at);
+            const context = {
+                id: b.id,
+                kind: b.kind,
+                at: Object.freeze([...b.at]),
+                timeoutMs: b.timeout_ms,
+                host: resolved.host ?? null,
+                declarationVersion: resolved.declaration,
+            };
+            // §7.7.5: a resolver that throws or returns a non-interceptor
+            // refuses the document; the message is bounded and the config is
+            // never echoed by the loader.
+            let interceptor;
+            try {
+                interceptor = resolverFn(b.config, context);
+            }
+            catch (e) {
+                const msg = e instanceof Error ? e.message : "resolver threw a non-Error value";
+                throw declaration_1.DeclarationError.single(declaration_1.DeclarationErrorClass.BindingRejected, pointer, `binding ${JSON.stringify(b.id)} (kind ${JSON.stringify(b.kind)}) rejected: ${msg}`);
+            }
+            if (!isInterceptor(interceptor)) {
+                const why = interceptor instanceof Promise
+                    ? "resolver returned a Promise; kind resolvers are synchronous"
+                    : "resolver did not return an interceptor";
+                throw declaration_1.DeclarationError.single(declaration_1.DeclarationErrorClass.BindingRejected, pointer, `binding ${JSON.stringify(b.id)} (kind ${JSON.stringify(b.kind)}) rejected: ${why}`);
+            }
+            bound.push({
+                interceptor,
+                name: b.id,
+                at,
+                timeoutMs: b.timeout_ms,
+            });
+        });
+        const em = new InterceptionEmitter(cfg.mode, resolver, cfg.timeouts.interceptor_ms);
+        em.resolverTimeoutMs = cfg.timeouts.approval_resolver_ms;
+        // The emitter owns its own copy of the composition and the
+        // declaration it exposes is frozen all the way down, so the seal
+        // cannot be bypassed by writing through `emitter.declaration`.
+        em.composition = { ...cfg.composition };
+        em.identity = identity;
+        em.approvalRedactor = approvalRedactor;
+        em.maxRecords = cfg.records.max_buffered;
+        em.interceptors.push(...bound);
+        em._declaration = deepFreeze(resolved);
+        em.sealed = true;
+        return em;
+    }
+    /** §7.7.7: a declaration-built emitter refuses reconfiguration;
+     * otherwise the declaration would not be what ran. */
+    unsealed(what) {
+        if (this.sealed)
+            throw new EmitterSealed(what);
+    }
+    /** Race `fn`'s result against a timeout (§7). `limitMs: null` runs
+     * unbounded. */
+    async withTimeout(fn, limitMs) {
+        if (limitMs === null)
             return fn();
         let timer;
         try {
             return await Promise.race([
                 (async () => fn())(),
                 new Promise((_, reject) => {
-                    timer = setTimeout(() => reject(new InterceptTimeout()), this.timeoutMs);
+                    timer = setTimeout(() => reject(new InterceptTimeout()), limitMs);
                 }),
             ]);
         }
@@ -157,10 +330,36 @@ class InterceptionEmitter {
         return this._records;
     }
     /** Register an interceptor, optionally with a host-chosen
-     * payload-free `name` recorded on `verdicts[].name` (§10.3). */
-    register(interceptor, name) {
-        this.interceptors.push(interceptor);
-        this.names.push(name ?? null);
+     * payload-free `name` recorded on `verdicts[].name` (§10.3) and the
+     * points it runs at (`at`; omitted = every point). At point P the
+     * interceptors that run are those bound there, in registration
+     * order; `interceptors_registered`, `verdicts[].index` and
+     * `decided_by` count and index that list (§7.7.8). Throws
+     * {@link EmitterSealed} on a declaration-built emitter. */
+    register(interceptor, name, at) {
+        this.unsealed("register");
+        let points = null;
+        if (at !== undefined) {
+            // The compile-time type does not protect plain-JS callers: a
+            // misspelled point must not bind nowhere without a word.
+            points = new Set();
+            const known = Object.values(index_1.InterceptionPoint);
+            for (const p of at) {
+                if (!known.includes(p)) {
+                    throw new RangeError(`unknown interception point ${JSON.stringify(p)}: the point set is closed (§3)`);
+                }
+                points.add(p);
+            }
+            if (points.size === 0) {
+                throw new RangeError("at must name at least one interception point; omit it to bind every point (§7.7.5)");
+            }
+        }
+        this.interceptors.push({
+            interceptor,
+            name: name ?? null,
+            at: points,
+            timeoutMs: undefined,
+        });
         return this;
     }
     /**
@@ -178,6 +377,7 @@ class InterceptionEmitter {
      * profile. See docs/PRODUCTION.md.
      */
     setComposition(composition) {
+        this.unsealed("setComposition");
         const profiles = Object.values(index_1.CompositionProfile);
         if (!profiles.includes(composition.profile)) {
             throw new RangeError(`unknown composition profile ${JSON.stringify(composition.profile)}: the profile set is closed (§7.2)`);
@@ -200,6 +400,7 @@ class InterceptionEmitter {
      * `^[a-z][a-z0-9_-]*$` and must not begin with `jcs` (reserved so a
      * custom function can never claim golden-vector semantics). */
     setIdentityProvider(provider) {
+        this.unsealed("setIdentityProvider");
         if (provider !== null && provider !== index_1.JCS_SHA256) {
             if (!/^[a-z][a-z0-9_-]*$/.test(provider.name) || provider.name.startsWith("jcs")) {
                 throw new RangeError("identity provider name must match ^[a-z][a-z0-9_-]*$ and must not begin with 'jcs' (§10.1)");
@@ -215,13 +416,15 @@ class InterceptionEmitter {
      * redactor that throws fails the consultation closed as
      * `host_error:approval_resolver_failed`. */
     setApprovalRedactor(redactor) {
+        this.unsealed("setApprovalRedactor");
         this.approvalRedactor = redactor;
         return this;
     }
     /** Register a per-emission record callback (§10.3), invoked
      * synchronously after every emission before buffering; a sink
      * exception is swallowed (audit delivery is the host's liveness
-     * concern, not the control plane's). */
+     * concern, not the control plane's). Allowed on a sealed emitter: it
+     * changes where records go, not what they say (§7.7.7). */
     setRecordSink(sink) {
         this.recordSink = sink;
         return this;
@@ -230,6 +433,7 @@ class InterceptionEmitter {
      * is dropped and {@link recordsDropped} increments. Unbounded by
      * default. */
     setMaxRecords(max) {
+        this.unsealed("setMaxRecords");
         this.maxRecords = max;
         return this;
     }
@@ -285,8 +489,9 @@ class InterceptionEmitter {
             }
         }
         const identityFailed = outcome !== null;
+        const active = this.active(ctx);
         if (outcome === null)
-            outcome = await this.dispatch(ctx);
+            outcome = await this.dispatch(ctx, active);
         const providerName = this.identity === null ? null : this.identity === index_1.JCS_SHA256 ? index_1.JCS_SHA256 : this.identity.name;
         const meta = {
             input_identity: inputIdentity,
@@ -300,13 +505,15 @@ class InterceptionEmitter {
                 : null,
             decided_by: outcome.decidedBy,
             composition: this.composition,
+            declaration: this._declaration?.declaration ?? null,
+            // §10.3 summaries with the bound names attached positionally.
             verdicts: outcome.verdicts.map((v) => ({
                 ...v,
-                ...(this.names[v.index] != null ? { name: this.names[v.index] } : {}),
+                ...(active[v.index]?.name != null ? { name: active[v.index].name } : {}),
             })),
             fold_truncated: outcome.foldTruncated,
             resolved_by: outcome.resolvedBy,
-            interceptors_registered: this.interceptors.length,
+            interceptors_registered: active.length,
         };
         let record;
         if (identityFailed) {
@@ -362,10 +569,11 @@ class InterceptionEmitter {
             enforced_identity: null,
             decided_by: null,
             composition: this.composition,
+            declaration: this._declaration?.declaration ?? null,
             verdicts: null,
             fold_truncated: null,
             resolved_by: null,
-            interceptors_registered: this.interceptors.length,
+            interceptors_registered: this.interceptors.filter((b) => runsAt(b, point)).length,
         });
         return this.deliver(record);
     }
@@ -390,23 +598,34 @@ class InterceptionEmitter {
         return record;
     }
     // ---------------------------------------------------------------------------
+    /** The interceptors bound at the context's point, in dispatch order
+     * (§7.7.8). */
+    active(ctx) {
+        const point = pointOf(ctx);
+        return this.interceptors.filter((b) => runsAt(b, point));
+    }
+    /** The bound a registration runs under: its own, else the emitter's. */
+    limit(b) {
+        return b.timeoutMs === undefined ? this.timeoutMs : b.timeoutMs;
+    }
     /** Profile dispatch (§7.4–§7.5). Returns the combined verdict and
      * its record metadata. */
-    async dispatch(ctx) {
-        if (this.interceptors.length === 0) {
+    async dispatch(ctx, active) {
+        if (active.length === 0) {
             // §7: zero interceptors fails closed, profile-independent.
             // Register an explicit allow-all interceptor for a deliberate
-            // passthrough.
+            // passthrough. With per-point bindings (§7.7.5) this is per
+            // point: a surface point with no binding denies.
             return synthesized(index_1.HostError.NoInterceptor);
         }
         switch (this.composition.profile) {
             case index_1.CompositionProfile.SequentialFirstDeny:
-                return this.dispatchFirstDeny(ctx);
+                return this.dispatchFirstDeny(ctx, active);
             case index_1.CompositionProfile.SequentialRunAll:
-                return this.dispatchRunAll(ctx);
+                return this.dispatchRunAll(ctx, active);
             case index_1.CompositionProfile.ParallelStrictest:
             case index_1.CompositionProfile.ParallelUnanimous:
-                return this.dispatchParallel(ctx);
+                return this.dispatchParallel(ctx, active);
             default:
                 // Unreachable through the public API: setComposition validates
                 // against the closed §7.2 set. Fail closed rather than silently
@@ -417,12 +636,12 @@ class InterceptionEmitter {
     /** Invoke one interceptor on its own copy of `ctx` (§7) and pass the
      * result through the §5 gate. Never throws: every failure becomes the
      * §6.3 synthesized deny. */
-    async invoke(interceptor, ctx) {
+    async invoke(bound, ctx) {
         let v;
         try {
             // §7: each interceptor gets its own copy — in-place mutation of
             // the copy cannot alter enforcement.
-            v = await this.withTimeout(() => interceptor.intercept(structuredClone(ctx)));
+            v = await this.withTimeout(() => bound.interceptor.intercept(structuredClone(ctx)), this.limit(bound));
         }
         catch (e) {
             if (e instanceof InterceptTimeout) {
@@ -451,11 +670,11 @@ class InterceptionEmitter {
      * short-circuits; a liftable deny consults the seam, then `stop` or
      * `resume` per the knob.
      *
-     * `perInterceptor` stays index-aligned with registration order (one
+     * `perInterceptor` stays index-aligned with dispatch order (one
      * entry per invoked interceptor, §10.3 summaries); `pool`
      * additionally holds substituted resolutions for the §7.3 unions. */
-    async dispatchFirstDeny(ctx) {
-        const n = this.interceptors.length;
+    async dispatchFirstDeny(ctx, active) {
+        const n = active.length;
         const onApproval = this.composition.on_approval ?? "stop";
         const perInterceptor = [];
         const pool = [];
@@ -463,7 +682,7 @@ class InterceptionEmitter {
         let resolvedBy = null;
         const truncated = (i) => i + 1 < n;
         for (let i = 0; i < n; i++) {
-            let v = await this.invoke(this.interceptors[i], ctx);
+            let v = await this.invoke(active[i], ctx);
             perInterceptor.push(v);
             pool.push(v);
             if (isHostSynthesized(v)) {
@@ -560,12 +779,12 @@ class InterceptionEmitter {
      * consulted at most once, only when the winner is liftable (which
      * implies every deny in the emission is liftable — a single plain
      * deny already won the severity order). */
-    async dispatchRunAll(ctx) {
+    async dispatchRunAll(ctx, active) {
         const all = [];
-        for (const interceptor of this.interceptors) {
+        for (const bound of active) {
             // §6.3 per-interceptor: a malformed verdict becomes that
             // interceptor's synthesized deny; the rest still run.
-            const v = await this.invoke(interceptor, ctx);
+            const v = await this.invoke(bound, ctx);
             if (v.decision === index_1.Decision.Transform) {
                 const folded = this.foldTransform(ctx, v);
                 if (!(0, index_1.permits)(folded.decision)) {
@@ -590,13 +809,13 @@ class InterceptionEmitter {
     }
     /** Parallel profiles (§7.5): isolated snapshots, no fold; serial
      * dispatch (isolation semantics, not scheduling). */
-    async dispatchParallel(ctx) {
+    async dispatchParallel(ctx, active) {
         // Every interceptor receives its own copy of the same untransformed
         // snapshot ({@link invoke} clones per call).
         const snapshot = structuredClone(ctx);
         const all = [];
-        for (const interceptor of this.interceptors) {
-            all.push(await this.invoke(interceptor, snapshot));
+        for (const bound of active) {
+            all.push(await this.invoke(bound, snapshot));
         }
         return this.aggregateAndConsult(ctx, all);
     }
@@ -685,9 +904,6 @@ class InterceptionEmitter {
         }
         return v;
     }
-    /** The declared provider's output for `ctx` (§10.1); `null` iff the
-     * provider is `null`. Throws {@link AgentHooksCoreError} iff the
-     * provider rejected the context (§10.2 fail-closed value domain). */
     /** Custom-provider identity, or null when the provider fails (the
      * emission has already been decided at this point). */
     tryCustomIdentity(ctx) {
@@ -698,6 +914,9 @@ class InterceptionEmitter {
             return null;
         }
     }
+    /** The declared provider's output for `ctx` (§10.1); `null` iff the
+     * provider is `null`. Throws {@link AgentHooksCoreError} iff the
+     * provider rejected the context (§10.2 fail-closed value domain). */
     identityOf(ctx) {
         if (this.identity === null)
             return null;
@@ -759,7 +978,7 @@ class InterceptionEmitter {
                 interception_point: ctx.interception_point,
                 verdict,
                 context: presented,
-            }));
+            }), this.resolverTimeoutMs);
         }
         catch (e) {
             if (e instanceof InterceptTimeout) {
@@ -796,6 +1015,24 @@ class InterceptionEmitter {
     }
 }
 exports.InterceptionEmitter = InterceptionEmitter;
+/** The context's interception point when it names one. */
+function pointOf(ctx) {
+    const p = ctx["interception_point"];
+    return typeof p === "string" && Object.values(index_1.InterceptionPoint).includes(p)
+        ? p
+        : null;
+}
+/** Whether a registration runs at `point` (§7.7.5). A registration
+ * without an `at` filter runs everywhere. An unparseable point never
+ * reaches dispatch (§4 validation denies first); every binding counts
+ * then so the record is conservative. */
+function runsAt(b, point) {
+    if (b.at === null)
+        return true;
+    if (point === null)
+        return true;
+    return b.at.has(point);
+}
 /** `(code, detail)` of a native failure; anything else maps to
  * `fallback` with the stringified error as detail. */
 function codeAndDetail(e, fallback = index_1.HostError.ContextInvalid) {

package/dist/index.d.ts

@@ -137,7 +137,7 @@ export interface CompositionConfig {
     on_approval?: OnApproval;
     /** `parallel/unanimous` only. */
     on_disagreement?: SynthesisPolicy;
-    /** Parallel profiles only. */
+    /** `parallel/strictest` only. */
     on_transform_conflict?: SynthesisPolicy;
 }
 /** Constructors for the closed profile set (§7.2). */
@@ -231,6 +231,11 @@ export interface InterceptionRecord {
     decided_by: number | null;
     /** The composition profile and knobs in effect (§7.1). */
     composition: CompositionConfig;
+    /** The host declaration contract version the emitter was built from
+     * (§7.7.8), e.g. `agent-hooks-declaration/1.0`. Present iff the
+     * emitter was constructed from a declaration document; absent for
+     * an emitter configured in code. */
+    declaration?: string;
     /** Per-interceptor summary; populated in multi-verdict profiles
      * (`sequential/run_all`, `parallel/*`). */
     verdicts?: VerdictSummary[];
@@ -242,7 +247,7 @@ export interface InterceptionRecord {
      * resolution substituted; `"rejection"` iff consulted without a
      * lift; absent iff never consulted. */
     resolved_by?: "approval" | "rejection" | null;
-    /** Interceptors registered at emission time (§10.3). */
+    /** Interceptors bound at the emitted point (§10.3, §7.7.8). */
     interceptors_registered: number;
 }
 /** Whether the guarded action executes (§6, §8). */
@@ -315,6 +320,10 @@ export interface FinalizeMeta {
     decided_by?: number | null;
     /** REQUIRED: the profile and knobs in effect (§7.1). */
     composition: CompositionConfig;
+    /** The declaration contract version the emitter was built from
+     * (§7.7.8); absent or `null` for an emitter configured in code. The
+     * core never defaults it. */
+    declaration?: string | null;
     /** Per-interceptor summaries (multi-verdict profiles, §10.3). */
     verdicts?: VerdictSummary[] | null;
     /** Sequential profiles (§7.4). */
@@ -340,8 +349,10 @@ export declare function composeAggregate(composition: CompositionConfig, verdict
     verdicts: VerdictSummary[];
 };
 export { AgentContextBuilder } from "./builder";
-export { InterceptionEmitter } from "./emitter";
+export { InterceptionEmitter, EmitterSealed } from "./emitter";
 export type { HostFailure } from "./emitter";
+export { CAPABILITIES, DECLARATION_VERSION, DeclarationBuilder, DeclarationError, DeclarationErrorClass, HostDeclaration, HostRegistry, HostRegistryError, HostSurface, MAX_BINDINGS, MAX_DEPTH, MAX_DETAIL_LEN, MAX_DOCUMENT_BYTES, MAX_ID_LEN, MAX_KIND_LEN, MAX_TIMEOUT_MS, SUPPORTED_DECLARATION_VERSIONS, canonicalDeclaration, declarationVersions, fullKnobSupport, validKind, validReference, } from "./declaration";
+export type { BindingContext, Finding, HostInfo, KindResolver, KnobSupport, RegistryNames, ResolvedBinding, ResolvedConfiguration, ResolvedDeclaration, ResolvedSurface, TimeoutSupport, ToolSeamPosture, } from "./declaration";
 /** Raised by a host when a verdict blocks the guarded action (§6). */
 /** Returned by `InterceptionEmitter.emit` on a proceeding emission:
  * the record plus the **effective** (post-composition) target the

package/dist/index.js

@@ -7,7 +7,7 @@
  * `policy-engine/sdk/node/src/index.ts`.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.InterceptionBlocked = exports.InterceptionEmitter = exports.AgentContextBuilder = exports.ApprovalOutcome = exports.Composition = exports.CompositionProfile = exports.ALLOW = exports.Verdict = exports.HostError = exports.EnforcementMode = exports.Decision = exports.InterceptionPoint = exports.JCS_SHA256 = exports.SPEC_VERSION = exports.AgentHooksCoreError = void 0;
+exports.InterceptionBlocked = exports.validReference = exports.validKind = exports.fullKnobSupport = exports.declarationVersions = exports.canonicalDeclaration = exports.SUPPORTED_DECLARATION_VERSIONS = exports.MAX_TIMEOUT_MS = exports.MAX_KIND_LEN = exports.MAX_ID_LEN = exports.MAX_DOCUMENT_BYTES = exports.MAX_DETAIL_LEN = exports.MAX_DEPTH = exports.MAX_BINDINGS = exports.HostSurface = exports.HostRegistryError = exports.HostRegistry = exports.HostDeclaration = exports.DeclarationErrorClass = exports.DeclarationError = exports.DeclarationBuilder = exports.DECLARATION_VERSION = exports.CAPABILITIES = exports.EmitterSealed = exports.InterceptionEmitter = exports.AgentContextBuilder = exports.ApprovalOutcome = exports.Composition = exports.CompositionProfile = exports.ALLOW = exports.Verdict = exports.HostError = exports.EnforcementMode = exports.Decision = exports.InterceptionPoint = exports.JCS_SHA256 = exports.SPEC_VERSION = exports.AgentHooksCoreError = void 0;
 exports.transformPermitted = transformPermitted;
 exports.permits = permits;
 exports.hostErrorVerdict = hostErrorVerdict;
@@ -251,6 +251,7 @@ function finalize(ctx, verdict, mode, meta) {
         enforced_identity: meta.enforced_identity ?? null,
         decided_by: meta.decided_by ?? null,
         composition: meta.composition,
+        declaration: meta.declaration ?? null,
         verdicts: meta.verdicts ?? null,
         fold_truncated: meta.fold_truncated ?? null,
         resolved_by: meta.resolved_by ?? null,
@@ -267,6 +268,30 @@ var builder_1 = require("./builder");
 Object.defineProperty(exports, "AgentContextBuilder", { enumerable: true, get: function () { return builder_1.AgentContextBuilder; } });
 var emitter_1 = require("./emitter");
 Object.defineProperty(exports, "InterceptionEmitter", { enumerable: true, get: function () { return emitter_1.InterceptionEmitter; } });
+Object.defineProperty(exports, "EmitterSealed", { enumerable: true, get: function () { return emitter_1.EmitterSealed; } });
+var declaration_1 = require("./declaration");
+Object.defineProperty(exports, "CAPABILITIES", { enumerable: true, get: function () { return declaration_1.CAPABILITIES; } });
+Object.defineProperty(exports, "DECLARATION_VERSION", { enumerable: true, get: function () { return declaration_1.DECLARATION_VERSION; } });
+Object.defineProperty(exports, "DeclarationBuilder", { enumerable: true, get: function () { return declaration_1.DeclarationBuilder; } });
+Object.defineProperty(exports, "DeclarationError", { enumerable: true, get: function () { return declaration_1.DeclarationError; } });
+Object.defineProperty(exports, "DeclarationErrorClass", { enumerable: true, get: function () { return declaration_1.DeclarationErrorClass; } });
+Object.defineProperty(exports, "HostDeclaration", { enumerable: true, get: function () { return declaration_1.HostDeclaration; } });
+Object.defineProperty(exports, "HostRegistry", { enumerable: true, get: function () { return declaration_1.HostRegistry; } });
+Object.defineProperty(exports, "HostRegistryError", { enumerable: true, get: function () { return declaration_1.HostRegistryError; } });
+Object.defineProperty(exports, "HostSurface", { enumerable: true, get: function () { return declaration_1.HostSurface; } });
+Object.defineProperty(exports, "MAX_BINDINGS", { enumerable: true, get: function () { return declaration_1.MAX_BINDINGS; } });
+Object.defineProperty(exports, "MAX_DEPTH", { enumerable: true, get: function () { return declaration_1.MAX_DEPTH; } });
+Object.defineProperty(exports, "MAX_DETAIL_LEN", { enumerable: true, get: function () { return declaration_1.MAX_DETAIL_LEN; } });
+Object.defineProperty(exports, "MAX_DOCUMENT_BYTES", { enumerable: true, get: function () { return declaration_1.MAX_DOCUMENT_BYTES; } });
+Object.defineProperty(exports, "MAX_ID_LEN", { enumerable: true, get: function () { return declaration_1.MAX_ID_LEN; } });
+Object.defineProperty(exports, "MAX_KIND_LEN", { enumerable: true, get: function () { return declaration_1.MAX_KIND_LEN; } });
+Object.defineProperty(exports, "MAX_TIMEOUT_MS", { enumerable: true, get: function () { return declaration_1.MAX_TIMEOUT_MS; } });
+Object.defineProperty(exports, "SUPPORTED_DECLARATION_VERSIONS", { enumerable: true, get: function () { return declaration_1.SUPPORTED_DECLARATION_VERSIONS; } });
+Object.defineProperty(exports, "canonicalDeclaration", { enumerable: true, get: function () { return declaration_1.canonicalDeclaration; } });
+Object.defineProperty(exports, "declarationVersions", { enumerable: true, get: function () { return declaration_1.declarationVersions; } });
+Object.defineProperty(exports, "fullKnobSupport", { enumerable: true, get: function () { return declaration_1.fullKnobSupport; } });
+Object.defineProperty(exports, "validKind", { enumerable: true, get: function () { return declaration_1.validKind; } });
+Object.defineProperty(exports, "validReference", { enumerable: true, get: function () { return declaration_1.validReference; } });
 class InterceptionBlocked extends Error {
     result;
     constructor(result) {

package/dist/native.d.ts

@@ -6,9 +6,12 @@
  * the `AgentHooksCoreError` unwrapping so callers get `.code`.
  */
 /** Thrown by every native function on failure. `.code` is the §11
- *  `host_error:*` wire string. */
+ *  `host_error:*` wire string, or a §7.7.6 `declaration_error:*`
+ *  string from the declaration functions (the detail is then JSON
+ *  findings, which `declaration.ts` retypes as `DeclarationError`). */
 export declare class AgentHooksCoreError extends Error {
     readonly code: string;
+    readonly detail: string;
     constructor(code: string, detail: string);
 }
 export declare const native: {
@@ -26,4 +29,8 @@ export declare const native: {
     ctkScriptedResolve: (rulesJson: string, ctxJson: string, identity: string) => string;
     ctkShouldSkip: (vectorJson: string, capsJson: string) => string;
     ctkAssert: (vectorJson: string, recordedJson: string, runRecordJson: string) => string;
+    declarationVersions: () => string;
+    declarationValidate: (documentJson: string) => string;
+    declarationResolve: (documentJson: string, hostJson: string) => string;
+    declarationResolveSurface: (documentJson: string, surfaceJson: string) => string;
 };