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

package/dist/emitter.d.ts

@@ -17,8 +17,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}.
@@ -28,8 +35,12 @@
  * a single JS thread. Sharing one emitter across workers is unsupported.
  */
 import { AgentContext, ApprovalResolver, CompositionConfig, EnforcementMode, IdentityProvider, EmitOutcome, InterceptionPoint, InterceptionRecord, Interceptor } from "./index";
+import { HostDeclaration, HostRegistry, ResolvedDeclaration } from "./declaration";
 /** §7 RECOMMENDED interceptor/resolver timeout (milliseconds). */
 export declare const DEFAULT_TIMEOUT_MS = 5000;
+export declare class EmitterSealed extends Error {
+    constructor(what: string);
+}
 /** Envelope facts for {@link InterceptionEmitter.recordHostFailure}:
  * what the host still knows about an emission whose context it could
  * not construct (§10.3 "Host projection failure"). Everything is
@@ -51,18 +62,24 @@ export interface HostFailure {
     timestamp?: string;
 }
 export declare class InterceptionEmitter {
-    private readonly mode;
-    private readonly resolver;
-    private readonly timeoutMs;
     private readonly interceptors;
     private _records;
     private composition;
     private identity;
-    private readonly names;
     private approvalRedactor;
     private recordSink;
     private maxRecords;
     private _recordsDropped;
+    private readonly mode;
+    private resolver;
+    /** §7 emitter-wide interceptor bound; `null` disables enforcement. */
+    private timeoutMs;
+    /** §9 resolver bound (`approval_resolver_ms`, §7.7.3); `null` disables. */
+    private resolverTimeoutMs;
+    /** §7.7.7: a declaration-built emitter refuses reconfiguration. */
+    private sealed;
+    /** The resolved declaration this emitter was built from, if any. */
+    private _declaration;
     /**
      * `timeoutMs` bounds each interceptor `intercept()` and resolver
      * `resolve()` call (§7, RECOMMENDED default 5000 ms); breach fails
@@ -72,12 +89,43 @@ export declare class InterceptionEmitter {
      * loop cannot be interrupted. `timeoutMs: null` disables enforcement.
      */
     constructor(mode?: EnforcementMode, resolver?: ApprovalResolver | null, timeoutMs?: number | null);
-    /** Race `fn`'s result against the §7 timeout. */
+    /** 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: HostDeclaration, registry: HostRegistry): InterceptionEmitter;
+    /** {@link HostDeclaration.fromPath} then {@link fromDeclaration}. */
+    static fromDeclarationPath(path: string, registry: HostRegistry): Promise<InterceptionEmitter>;
+    /** {@link HostDeclaration.fromJson} then {@link fromDeclaration}. */
+    static fromDeclarationJson(text: string, registry: HostRegistry): InterceptionEmitter;
+    /** {@link HostDeclaration.fromValue} then {@link fromDeclaration}. */
+    static fromDeclarationValue(value: unknown, registry: HostRegistry): InterceptionEmitter;
+    /** 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(): ResolvedDeclaration | null;
+    /** 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. */
+    private static fromResolved;
+    /** §7.7.7: a declaration-built emitter refuses reconfiguration;
+     * otherwise the declaration would not be what ran. */
+    private unsealed;
+    /** Race `fn`'s result against a timeout (§7). `limitMs: null` runs
+     * unbounded. */
     private withTimeout;
     get records(): readonly InterceptionRecord[];
     /** Register an interceptor, optionally with a host-chosen
-     * payload-free `name` recorded on `verdicts[].name` (§10.3). */
-    register(interceptor: Interceptor, name?: string): this;
+     * 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: Interceptor, name?: string, at?: Iterable<InterceptionPoint>): this;
     /**
      * Declare the composition profile for subsequent emissions (§7.1).
      * The profile and knob values are validated against the closed §7.2
@@ -108,7 +156,8 @@ export declare class InterceptionEmitter {
     /** 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: (record: InterceptionRecord) => void): this;
     /** Bound the in-memory record buffer: when full, the OLDEST record
      * is dropped and {@link recordsDropped} increments. Unbounded by
@@ -152,6 +201,11 @@ export declare class InterceptionEmitter {
     recordHostFailure(point: InterceptionPoint, failure?: HostFailure): InterceptionRecord;
     /** Deliver a record to the sink and the bounded buffer (§10.3). */
     private deliver;
+    /** The interceptors bound at the context's point, in dispatch order
+     * (§7.7.8). */
+    private active;
+    /** The bound a registration runs under: its own, else the emitter's. */
+    private limit;
     /** Profile dispatch (§7.4–§7.5). Returns the combined verdict and
      * its record metadata. */
     private dispatch;
@@ -167,7 +221,7 @@ export declare 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. */
     private dispatchFirstDeny;
@@ -189,12 +243,12 @@ export declare class InterceptionEmitter {
     private aggregateAndConsult;
     /** Apply (enforce) or validate (evaluate_only) one transform (§7.4, §8). */
     private foldTransform;
-    /** 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). */
     private tryCustomIdentity;
+    /** 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). */
     private identityOf;
     /** Consult the approval seam for a liftable deny (§9), when the
      * profile conditions allow it: `enforce` mode, not `agent_shutdown`,