@responsibleai/agent-hooks 0.1.0-alpha.2

package/dist/index.d.ts

@@ -0,0 +1,328 @@
+/**
+ * agent-hooks: framework-neutral agent lifecycle hook contract.
+ * Implements AGENT-HOOKS-0.1. Lifted and adapted from
+ * `policy-engine/sdk/node/src/index.ts`.
+ */
+import { AgentHooksCoreError } from "./native";
+export { AgentHooksCoreError };
+/** Spec version this SDK implements (§4.1 `spec` field). */
+export declare const SPEC_VERSION = "agent-hooks/0.1";
+/** Name of the default identity provider (§10.1, §10.2). */
+export declare const JCS_SHA256 = "jcs-sha256";
+export type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/** The closed set of agent lifecycle interception points (§3). */
+export declare const InterceptionPoint: Readonly<{
+    readonly AgentStartup: "agent_startup";
+    readonly Input: "input";
+    readonly PreModelCall: "pre_model_call";
+    readonly PostModelCall: "post_model_call";
+    readonly PreToolCall: "pre_tool_call";
+    readonly PostToolCall: "post_tool_call";
+    readonly Output: "output";
+    readonly AgentShutdown: "agent_shutdown";
+}>;
+export type InterceptionPoint = (typeof InterceptionPoint)[keyof typeof InterceptionPoint];
+/** Whether a `transform` verdict is permitted at `hp` (§3, §4.3). */
+export declare function transformPermitted(hp: InterceptionPoint): boolean;
+/** Verdict decision values (§5.1). Three, closed: `warn` is `allow` +
+ * `warnings[]`; `escalate` is `deny` + an `approval` block. */
+export declare const Decision: Readonly<{
+    readonly Allow: "allow";
+    readonly Deny: "deny";
+    readonly Transform: "transform";
+}>;
+export type Decision = (typeof Decision)[keyof typeof Decision];
+/** Whether the action proceeds under `d` (§2 permit class). */
+export declare function permits(d: Decision): boolean;
+/** Whether the host acts on verdicts (§8). */
+export declare const EnforcementMode: Readonly<{
+    readonly Enforce: "enforce";
+    readonly EvaluateOnly: "evaluate_only";
+}>;
+export type EnforcementMode = (typeof EnforcementMode)[keyof typeof EnforcementMode];
+/** Reserved `host_error:*` reasons a host synthesizes (§11). */
+export declare const HostError: Readonly<{
+    readonly ContextInvalid: "host_error:context_invalid";
+    readonly InterceptorFailed: "host_error:interceptor_failed";
+    readonly InterceptorTimeout: "host_error:interceptor_timeout";
+    readonly VerdictInvalid: "host_error:verdict_invalid";
+    readonly TransformInvalid: "host_error:transform_invalid";
+    readonly TransformTargetForbidden: "host_error:transform_target_forbidden";
+    readonly TransformConflict: "host_error:transform_conflict";
+    readonly CompositionDisagreement: "host_error:composition_disagreement";
+    readonly ApprovalResolverFailed: "host_error:approval_resolver_failed";
+    readonly ApprovalUnresolved: "host_error:approval_unresolved";
+    readonly ApprovalIdentityMismatch: "host_error:approval_identity_mismatch";
+    readonly AdapterUnsupported: "host_error:adapter_unsupported";
+    readonly StreamingUnsupported: "host_error:streaming_unsupported";
+    readonly NoInterceptor: "host_error:no_interceptor";
+}>;
+export type HostError = (typeof HostError)[keyof typeof HostError];
+/** A single `$target`-rooted replacement (§5.2). */
+export interface Transform {
+    /** Path rooted at `$target` (or the deprecated `$policy_target` alias). */
+    path: string;
+    value: JsonValue;
+}
+/** Opaque pointer to an offline-verifiable artefact (§5.3). */
+export interface Evidence {
+    artefact?: string | null;
+    verification_pointers?: Record<string, string>;
+}
+/** A recorded concern that does not affect control flow (§5.1). */
+export interface Warning {
+    reason?: string | null;
+    message?: string | null;
+}
+/** Interceptor return value (§5). */
+export interface Verdict {
+    decision: Decision;
+    reason?: string | null;
+    message?: string | null;
+    /** Recorded concerns; permitted on any decision (§5.1). */
+    warnings?: Warning[];
+    /** Present only on `deny`: marks the deny as liftable by the approval
+     * seam (§9). MAY be empty; reserved for approver-facing parameters. */
+    approval?: Record<string, JsonValue>;
+    transform?: Transform;
+    evidence?: Evidence;
+    result_labels?: string[];
+}
+/** Constructor sugar for the three-verdict vocabulary (§5.1). Merges
+ * with the `Verdict` interface: `Verdict.warn(...)`, `Verdict.escalate(...)`. */
+export declare const Verdict: Readonly<{
+    /** The trivial permit verdict. */
+    allow(): Verdict;
+    /** What earlier drafts called `warn`: an `allow` carrying one
+     * warning (§5.1). */
+    warn(reason?: string, message?: string): Verdict;
+    /** What earlier drafts called `escalate`: a liftable deny — denied
+     * as-is unless the approval seam lifts it (§5.1, §9). */
+    escalate(reason?: string, message?: string): Verdict;
+}>;
+/** The trivial permit verdict. */
+export declare const ALLOW: Readonly<Verdict>;
+/** Host-synthesized deny verdict for a §11 failure. */
+export declare function hostErrorVerdict(err: HostError, message?: string): Verdict;
+/** Host-synthesized **liftable** deny (§7.5 `"approval"` knob value):
+ * the failure is consultable rather than final. */
+export declare function hostErrorLiftable(err: HostError, message?: string): Verdict;
+/** A deny carrying an `approval` block (§5.1). */
+export declare function isLiftable(v: Verdict): boolean;
+/** The closed profile set (§7.2). */
+export declare const CompositionProfile: Readonly<{
+    readonly SequentialFirstDeny: "sequential/first_deny";
+    readonly SequentialRunAll: "sequential/run_all";
+    readonly ParallelStrictest: "parallel/strictest";
+    readonly ParallelUnanimous: "parallel/unanimous";
+}>;
+export type CompositionProfile = (typeof CompositionProfile)[keyof typeof CompositionProfile];
+/** `sequential/first_deny` knob (§7.4): what a permit resolution does
+ * to the rest of the fold. */
+export type OnApproval = "stop" | "resume";
+/** `"deny" | "approval"` knob value (§7.5): synthesize a plain deny, or
+ * a liftable one and consult the seam. */
+export type SynthesisPolicy = "deny" | "approval";
+/** The composition profile and knobs in effect for one emission
+ * (§7.1, §10.3). Serialized verbatim into the record's `composition`
+ * block. */
+export interface CompositionConfig {
+    profile: CompositionProfile;
+    /** `sequential/first_deny` only. */
+    on_approval?: OnApproval;
+    /** `parallel/unanimous` only. */
+    on_disagreement?: SynthesisPolicy;
+    /** Parallel profiles only. */
+    on_transform_conflict?: SynthesisPolicy;
+}
+/** Constructors for the closed profile set (§7.2). */
+export declare const Composition: Readonly<{
+    /** The default: `sequential/first_deny` with `on_approval: stop`. A
+     * default, not a conformance baseline — no profile is mandatory. */
+    default(): CompositionConfig;
+    firstDeny(onApproval?: OnApproval): CompositionConfig;
+    runAll(): CompositionConfig;
+    strictest(onTransformConflict?: SynthesisPolicy): CompositionConfig;
+    unanimous(onDisagreement?: SynthesisPolicy, onTransformConflict?: SynthesisPolicy): CompositionConfig;
+}>;
+/** The host-declared identity provider (§10.1):
+ *
+ * - `"jcs-sha256"` — the shipped default (§10.2); fail-closed I-JSON
+ *   domain; in effect unless the host configures otherwise.
+ * - `{name, fn}` — a host-supplied pure function. The echo and record
+ *   rules (§10.1) still apply; the golden vectors do not.
+ * - `null` — identity-unbound: approvals bind by correlation only;
+ *   records carry `null` identities and self-describe as unbound. */
+export type IdentityProvider = typeof JCS_SHA256 | {
+    name: string;
+    fn: (ctx: AgentContext) => string;
+} | null;
+/** Wire-shaped agent context (§4). Required core typed; conditional and
+ * optional fields indexed. */
+export interface AgentContext {
+    spec: string;
+    interception_point: InterceptionPoint;
+    timestamp: string;
+    sequence: number;
+    agent: {
+        id: string;
+        framework: string;
+        name?: string;
+        version?: string;
+    };
+    session: {
+        id: string;
+        started_at?: string;
+        turn?: number;
+    };
+    target: JsonValue;
+    extensions?: Record<string, JsonValue>;
+    [conditional: string]: JsonValue | undefined;
+}
+/** Payload-free per-interceptor summary on the record (§10.3). */
+export interface VerdictSummary {
+    index: number;
+    decision: Decision;
+    reason?: string | null;
+}
+/** Host-side record of one emission (§10.3).
+ *
+ * Payload-free by design: the identities (when a provider is declared)
+ * bind the record to the exact pre/post-composition context without
+ * duplicating the (possibly sensitive) payload into audit storage.
+ * `composition` makes the record interpretable without out-of-band
+ * knowledge of host configuration. */
+export interface InterceptionRecord {
+    interception_point: InterceptionPoint;
+    mode: EnforcementMode;
+    /** The combined verdict (§7.3), possibly host-synthesized or
+     * approval-substituted. */
+    verdict: Verdict;
+    /** Provider output before dispatch; `null` iff `identity_provider` is
+     * `null` (or the provider itself rejected the context). */
+    input_identity: string | null;
+    /** Provider output after composition completes. */
+    enforced_identity: string | null;
+    /** The declared identity provider (§10.1). */
+    identity_provider: string | null;
+    /** `ctx.session.id` — correlates records across a session. */
+    session_id: string;
+    /** `ctx.sequence` — total order within the session (§12.2.3). */
+    sequence: number;
+    /** Registration index of the interceptor whose verdict won the
+     * aggregation or whose liftable deny was consulted (§7.6); `null`
+     * for a pure-allow combination or a host-synthesized verdict. */
+    decided_by: number | null;
+    /** The composition profile and knobs in effect (§7.1). */
+    composition: CompositionConfig;
+    /** Per-interceptor summary; populated in multi-verdict profiles
+     * (`sequential/run_all`, `parallel/*`). */
+    verdicts?: VerdictSummary[];
+    /** `true` iff one or more registered interceptors were never invoked
+     * in this emission. Defined only for `sequential/first_deny` (§7.4). */
+    fold_truncated?: boolean;
+    /** `"approval"` iff an approval resolution substituted for a verdict
+     * in this emission (§7.6). */
+    resolved_by?: "approval" | null;
+}
+/** Whether the guarded action executes (§6, §8). */
+export declare function proceeds(r: InterceptionRecord): boolean;
+/** Interceptor protocol (§7). */
+export interface Interceptor {
+    intercept(context: AgentContext): Verdict | Promise<Verdict>;
+}
+/** Approval seam (§9). */
+export declare const ApprovalOutcome: Readonly<{
+    readonly Approve: "approve";
+    readonly Reject: "reject";
+    readonly Unresolved: "unresolved";
+}>;
+export type ApprovalOutcome = (typeof ApprovalOutcome)[keyof typeof ApprovalOutcome];
+/** `context_identity` is `null` when the identity provider is `null`
+ * (§10.1) — the approval is then identity-unbound. */
+export interface ApprovalRequest {
+    context_identity: string | null;
+    interception_point: InterceptionPoint;
+    verdict: Verdict;
+    context: AgentContext;
+}
+/** The resolution's `context_identity` MUST echo the request's byte for
+ * byte (`null` echoes as `null`, §9 echo rule). */
+export interface ApprovalResolution {
+    outcome: ApprovalOutcome;
+    context_identity: string | null;
+    verdict?: Verdict;
+}
+export interface ApprovalResolver {
+    resolve(request: ApprovalRequest): ApprovalResolution | Promise<ApprovalResolution>;
+}
+/** Depth-first scan for non-finite numbers. Returns the dotted path of
+ * the first offender, or `null` when the value is clean. */
+export declare function findNonFinite(v: unknown, path?: string): string | null;
+/** §4.4 remediation detail for a non-finite number at `path`. */
+export declare function nonFiniteDetail(path: string): string;
+/** Serialize per §10.2 (RFC 8785). Implemented by the Rust core. */
+export declare function canonicalJson(v: JsonValue): string;
+/** `"sha256:" + hex(SHA-256(canonicalJson(ctx_rc)))` (§10.2). Fails
+ * closed (`host_error:context_invalid` with remediation detail) on a
+ * non-I-JSON projection — integrals beyond ±(2^53−1), non-finite
+ * numbers. Rust core. */
+export declare function contextIdentity(ctx: AgentContext): string;
+/** §5: validate an interceptor's wire return value. Rust core. */
+export declare function validateVerdict(v: Verdict): void;
+/** §5.2: apply a `$target`-rooted transform. Returns a new object. Rust core. */
+export declare function applyTransform(target: JsonValue, path: string, value: JsonValue): JsonValue;
+/** §7.4 fold-through: apply one transform to the context's `target` (and
+ * its conditional alias) so the next interceptor sees the effect. Returns
+ * the updated context. Rust core. */
+export declare function applyTransformCtx(ctx: AgentContext, path: string, value: JsonValue): AgentContext;
+/** §8 `evaluate_only`: validate a transform against the context's current
+ * target without applying it. Rust core. */
+export declare function validateTransformCtx(ctx: AgentContext, path: string, value: JsonValue): void;
+/** Everything {@link finalize} needs beyond the context and combined
+ * verdict (§10.3). */
+export interface FinalizeMeta {
+    /** Provider output computed **before** dispatch; `null` when the
+     * identity provider is `null` or rejected the context. */
+    input_identity?: string | null;
+    /** The declared provider name (§10.1). When `"jcs-sha256"`, the core
+     * computes `enforced_identity` from the post-fold context itself; a
+     * custom provider's host passes `enforced_identity` explicitly. */
+    identity_provider?: string | null;
+    /** Pre-computed post-composition identity for custom providers.
+     * Ignored when `identity_provider == "jcs-sha256"`. */
+    enforced_identity?: string | null;
+    decided_by?: number | null;
+    /** REQUIRED: the profile and knobs in effect (§7.1). */
+    composition: CompositionConfig;
+    /** Per-interceptor summaries (multi-verdict profiles, §10.3). */
+    verdicts?: VerdictSummary[] | null;
+    /** `sequential/first_deny` only (§7.4). */
+    fold_truncated?: boolean | null;
+    /** `"approval"` iff a resolution substituted for a verdict (§7.6). */
+    resolved_by?: "approval" | null;
+}
+/** §10.3: build the `InterceptionRecord` for one completed emission.
+ * `meta.input_identity` MUST have been computed before interceptor
+ * dispatch; transforms were already applied during the §7.4 fold. Rust
+ * core. */
+export declare function finalize(ctx: AgentContext, verdict: Verdict, mode: EnforcementMode, meta: FinalizeMeta): InterceptionRecord;
+/** §7.3/§7.5 aggregation for the multi-verdict profiles: severity-max
+ * winner (or synthesized conflict/disagreement verdict) with the §7.3
+ * metadata unions. Rust core. */
+export declare function composeAggregate(composition: CompositionConfig, verdicts: Verdict[]): {
+    combined: Verdict;
+    decided_by: number | null;
+    consult: boolean;
+    apply_transform: boolean;
+    verdicts: VerdictSummary[];
+};
+export { AgentContextBuilder } from "./builder";
+export { InterceptionEmitter } from "./emitter";
+/** Raised by a host when a verdict blocks the guarded action (§6). */
+export declare class InterceptionBlocked extends Error {
+    readonly result: InterceptionRecord;
+    constructor(result: InterceptionRecord);
+}

package/dist/index.js

@@ -0,0 +1,273 @@
+"use strict";
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+/**
+ * agent-hooks: framework-neutral agent lifecycle hook contract.
+ * Implements AGENT-HOOKS-0.1. Lifted and adapted from
+ * `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.transformPermitted = transformPermitted;
+exports.permits = permits;
+exports.hostErrorVerdict = hostErrorVerdict;
+exports.hostErrorLiftable = hostErrorLiftable;
+exports.isLiftable = isLiftable;
+exports.proceeds = proceeds;
+exports.findNonFinite = findNonFinite;
+exports.nonFiniteDetail = nonFiniteDetail;
+exports.canonicalJson = canonicalJson;
+exports.contextIdentity = contextIdentity;
+exports.validateVerdict = validateVerdict;
+exports.applyTransform = applyTransform;
+exports.applyTransformCtx = applyTransformCtx;
+exports.validateTransformCtx = validateTransformCtx;
+exports.finalize = finalize;
+exports.composeAggregate = composeAggregate;
+const native_1 = require("./native");
+Object.defineProperty(exports, "AgentHooksCoreError", { enumerable: true, get: function () { return native_1.AgentHooksCoreError; } });
+/** Spec version this SDK implements (§4.1 `spec` field). */
+exports.SPEC_VERSION = "agent-hooks/0.1";
+/** Name of the default identity provider (§10.1, §10.2). */
+exports.JCS_SHA256 = "jcs-sha256";
+/** The closed set of agent lifecycle interception points (§3). */
+exports.InterceptionPoint = Object.freeze({
+    AgentStartup: "agent_startup",
+    Input: "input",
+    PreModelCall: "pre_model_call",
+    PostModelCall: "post_model_call",
+    PreToolCall: "pre_tool_call",
+    PostToolCall: "post_tool_call",
+    Output: "output",
+    AgentShutdown: "agent_shutdown",
+});
+/** Whether a `transform` verdict is permitted at `hp` (§3, §4.3). */
+function transformPermitted(hp) {
+    return hp !== exports.InterceptionPoint.AgentStartup && hp !== exports.InterceptionPoint.AgentShutdown;
+}
+/** Verdict decision values (§5.1). Three, closed: `warn` is `allow` +
+ * `warnings[]`; `escalate` is `deny` + an `approval` block. */
+exports.Decision = Object.freeze({
+    Allow: "allow",
+    Deny: "deny",
+    Transform: "transform",
+});
+/** Whether the action proceeds under `d` (§2 permit class). */
+function permits(d) {
+    return d === exports.Decision.Allow || d === exports.Decision.Transform;
+}
+/** Whether the host acts on verdicts (§8). */
+exports.EnforcementMode = Object.freeze({
+    Enforce: "enforce",
+    EvaluateOnly: "evaluate_only",
+});
+/** Reserved `host_error:*` reasons a host synthesizes (§11). */
+exports.HostError = Object.freeze({
+    ContextInvalid: "host_error:context_invalid",
+    InterceptorFailed: "host_error:interceptor_failed",
+    InterceptorTimeout: "host_error:interceptor_timeout",
+    VerdictInvalid: "host_error:verdict_invalid",
+    TransformInvalid: "host_error:transform_invalid",
+    TransformTargetForbidden: "host_error:transform_target_forbidden",
+    TransformConflict: "host_error:transform_conflict",
+    CompositionDisagreement: "host_error:composition_disagreement",
+    ApprovalResolverFailed: "host_error:approval_resolver_failed",
+    ApprovalUnresolved: "host_error:approval_unresolved",
+    ApprovalIdentityMismatch: "host_error:approval_identity_mismatch",
+    AdapterUnsupported: "host_error:adapter_unsupported",
+    StreamingUnsupported: "host_error:streaming_unsupported",
+    NoInterceptor: "host_error:no_interceptor",
+});
+/** Constructor sugar for the three-verdict vocabulary (§5.1). Merges
+ * with the `Verdict` interface: `Verdict.warn(...)`, `Verdict.escalate(...)`. */
+exports.Verdict = Object.freeze({
+    /** The trivial permit verdict. */
+    allow() {
+        return { decision: exports.Decision.Allow };
+    },
+    /** What earlier drafts called `warn`: an `allow` carrying one
+     * warning (§5.1). */
+    warn(reason, message) {
+        return { decision: exports.Decision.Allow, warnings: [{ reason, message }] };
+    },
+    /** What earlier drafts called `escalate`: a liftable deny — denied
+     * as-is unless the approval seam lifts it (§5.1, §9). */
+    escalate(reason, message) {
+        return { decision: exports.Decision.Deny, reason, message, approval: {} };
+    },
+});
+/** The trivial permit verdict. */
+exports.ALLOW = Object.freeze({ decision: exports.Decision.Allow });
+/** Host-synthesized deny verdict for a §11 failure. */
+function hostErrorVerdict(err, message) {
+    return { decision: exports.Decision.Deny, reason: err, message };
+}
+/** Host-synthesized **liftable** deny (§7.5 `"approval"` knob value):
+ * the failure is consultable rather than final. */
+function hostErrorLiftable(err, message) {
+    return { ...hostErrorVerdict(err, message), approval: {} };
+}
+/** A deny carrying an `approval` block (§5.1). */
+function isLiftable(v) {
+    return v.decision === exports.Decision.Deny && v.approval != null;
+}
+// ---- Composition (§7) -------------------------------------------------------
+/** The closed profile set (§7.2). */
+exports.CompositionProfile = Object.freeze({
+    SequentialFirstDeny: "sequential/first_deny",
+    SequentialRunAll: "sequential/run_all",
+    ParallelStrictest: "parallel/strictest",
+    ParallelUnanimous: "parallel/unanimous",
+});
+/** Constructors for the closed profile set (§7.2). */
+exports.Composition = Object.freeze({
+    /** The default: `sequential/first_deny` with `on_approval: stop`. A
+     * default, not a conformance baseline — no profile is mandatory. */
+    default() {
+        return { profile: exports.CompositionProfile.SequentialFirstDeny, on_approval: "stop" };
+    },
+    firstDeny(onApproval = "stop") {
+        return { profile: exports.CompositionProfile.SequentialFirstDeny, on_approval: onApproval };
+    },
+    runAll() {
+        return { profile: exports.CompositionProfile.SequentialRunAll };
+    },
+    strictest(onTransformConflict = "deny") {
+        return {
+            profile: exports.CompositionProfile.ParallelStrictest,
+            on_transform_conflict: onTransformConflict,
+        };
+    },
+    unanimous(onDisagreement = "deny", onTransformConflict = "deny") {
+        return {
+            profile: exports.CompositionProfile.ParallelUnanimous,
+            on_disagreement: onDisagreement,
+            on_transform_conflict: onTransformConflict,
+        };
+    },
+});
+/** Whether the guarded action executes (§6, §8). */
+function proceeds(r) {
+    return r.mode === exports.EnforcementMode.EvaluateOnly || permits(r.verdict.decision);
+}
+/** Approval seam (§9). */
+exports.ApprovalOutcome = Object.freeze({
+    Approve: "approve",
+    Reject: "reject",
+    Unresolved: "unresolved",
+});
+// ---- Non-finite guard (§4.4, §10.2) -----------------------------------------
+//
+// `JSON.stringify` silently corrupts NaN/±Infinity to `null`, so every
+// marshalling point below pre-scans and fails closed
+// (`host_error:context_invalid`) instead of letting the corrupted value
+// cross the boundary. The core never sees a non-finite number (it is
+// unrepresentable in JSON), which is exactly why the guard must live on
+// the JS side of the funnel.
+/** Depth-first scan for non-finite numbers. Returns the dotted path of
+ * the first offender, or `null` when the value is clean. */
+function findNonFinite(v, path = "$") {
+    if (typeof v === "number")
+        return Number.isFinite(v) ? null : path;
+    if (Array.isArray(v)) {
+        for (let i = 0; i < v.length; i++) {
+            const hit = findNonFinite(v[i], `${path}[${i}]`);
+            if (hit !== null)
+                return hit;
+        }
+        return null;
+    }
+    if (v !== null && typeof v === "object") {
+        for (const [k, item] of Object.entries(v)) {
+            const hit = findNonFinite(item, `${path}.${k}`);
+            if (hit !== null)
+                return hit;
+        }
+        return null;
+    }
+    return null;
+}
+/** §4.4 remediation detail for a non-finite number at `path`. */
+function nonFiniteDetail(path) {
+    return `${path}: non-finite number (NaN/Infinity) is not representable in JSON; remove or string-encode it, see spec §4.4`;
+}
+/** Marshalling guard: `JSON.stringify` that fails closed
+ * (`host_error:context_invalid`) on non-finite numbers instead of
+ * silently corrupting them to `null` (§4.4). */
+function marshal(v) {
+    const hit = findNonFinite(v);
+    if (hit !== null)
+        throw new native_1.AgentHooksCoreError(exports.HostError.ContextInvalid, nonFiniteDetail(hit));
+    return JSON.stringify(v);
+}
+// ---- Canonical JSON & context identity (§10) -------------------------------
+//
+// Delegates to the Rust core via napi-rs so every SDK produces
+// byte-identical output. The pure-TS implementation was removed once the
+// core became canonical (see sdk/rust/core/src/canonical.rs).
+/** Serialize per §10.2 (RFC 8785). Implemented by the Rust core. */
+function canonicalJson(v) {
+    return native_1.native.canonicalJson(marshal(v));
+}
+/** `"sha256:" + hex(SHA-256(canonicalJson(ctx_rc)))` (§10.2). Fails
+ * closed (`host_error:context_invalid` with remediation detail) on a
+ * non-I-JSON projection — integrals beyond ±(2^53−1), non-finite
+ * numbers. Rust core. */
+function contextIdentity(ctx) {
+    return native_1.native.contextIdentity(marshal(ctx));
+}
+/** §5: validate an interceptor's wire return value. Rust core. */
+function validateVerdict(v) {
+    native_1.native.validateVerdict(marshal(v));
+}
+/** §5.2: apply a `$target`-rooted transform. Returns a new object. Rust core. */
+function applyTransform(target, path, value) {
+    return JSON.parse(native_1.native.applyTransform(marshal(target), path, marshal(value)));
+}
+/** §7.4 fold-through: apply one transform to the context's `target` (and
+ * its conditional alias) so the next interceptor sees the effect. Returns
+ * the updated context. Rust core. */
+function applyTransformCtx(ctx, path, value) {
+    return JSON.parse(native_1.native.applyTransformCtx(marshal(ctx), path, marshal(value)));
+}
+/** §8 `evaluate_only`: validate a transform against the context's current
+ * target without applying it. Rust core. */
+function validateTransformCtx(ctx, path, value) {
+    native_1.native.validateTransformCtx(marshal(ctx), path, marshal(value));
+}
+/** §10.3: build the `InterceptionRecord` for one completed emission.
+ * `meta.input_identity` MUST have been computed before interceptor
+ * dispatch; transforms were already applied during the §7.4 fold. Rust
+ * core. */
+function finalize(ctx, verdict, mode, meta) {
+    return JSON.parse(native_1.native.finalize(marshal(ctx), marshal(verdict), mode, JSON.stringify({
+        input_identity: meta.input_identity ?? null,
+        identity_provider: meta.identity_provider ?? null,
+        enforced_identity: meta.enforced_identity ?? null,
+        decided_by: meta.decided_by ?? null,
+        composition: meta.composition,
+        verdicts: meta.verdicts ?? null,
+        fold_truncated: meta.fold_truncated ?? null,
+        resolved_by: meta.resolved_by ?? null,
+    })));
+}
+/** §7.3/§7.5 aggregation for the multi-verdict profiles: severity-max
+ * winner (or synthesized conflict/disagreement verdict) with the §7.3
+ * metadata unions. Rust core. */
+function composeAggregate(composition, verdicts) {
+    return JSON.parse(native_1.native.composeAggregate(JSON.stringify(composition), marshal(verdicts)));
+}
+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; } });
+/** Raised by a host when a verdict blocks the guarded action (§6). */
+class InterceptionBlocked extends Error {
+    result;
+    constructor(result) {
+        super(`${result.interception_point} blocked: ${result.verdict.decision} (${result.verdict.reason ?? "no reason"})`);
+        this.result = result;
+        this.name = "InterceptionBlocked";
+    }
+}
+exports.InterceptionBlocked = InterceptionBlocked;

package/dist/native.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Loader for the napi-rs native module + typed re-export.
+ *
+ * `@napi-rs/cli build` emits `agent-hooks.<platform>.node` alongside a
+ * generated `index.js` loader; this module re-exports it with types and
+ * the `AgentHooksCoreError` unwrapping so callers get `.code`.
+ */
+/** Thrown by every native function on failure. `.code` is the §11
+ *  `host_error:*` wire string. */
+export declare class AgentHooksCoreError extends Error {
+    readonly code: string;
+    constructor(code: string, detail: string);
+}
+export declare const native: {
+    specVersion: () => string;
+    canonicalJson: (valueJson: string) => string;
+    contextIdentity: (ctxJson: string) => string;
+    validateVerdict: (verdictJson: string) => string;
+    applyTransform: (targetJson: string, path: string, valueJson: string) => string;
+    applyTransformCtx: (ctxJson: string, path: string, valueJson: string) => string;
+    validateTransformCtx: (ctxJson: string, path: string, valueJson: string) => string;
+    finalize: (ctxJson: string, verdictJson: string, mode: string, optionsJson: string) => string;
+    composeAggregate: (compositionJson: string, verdictsJson: string) => string;
+    ctkScriptedIntercept: (rulesJson: string, ctxJson: string) => string;
+    ctkScriptedResolve: (rulesJson: string, ctxJson: string, identity: string) => string;
+    ctkShouldSkip: (vectorJson: string, capsJson: string) => string;
+    ctkAssert: (vectorJson: string, recordedJson: string, runRecordJson: string) => string;
+};