@once-agent/sdk 0.1.5 → 0.1.7

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Jamie Oswald
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+MIT License
+
+Copyright (c) 2026 Jamie Oswald
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.

package/README.md

@@ -1,5 +1,10 @@
 # @once-agent/sdk
 
+> **Local protection:** `protectLocal` wraps an existing async function using a
+> durable same-machine SQLite file. This feature requires Node.js 24.15 or
+> later. See the local function guide:
+> https://github.com/stringsofthemind-oss/once/blob/main/examples/local-function/README.md
+
 
 <!-- ONCE_STRIPE_SANDBOX_NOTICE -->
 

package/dist/benchmark.d.ts

@@ -0,0 +1,40 @@
+export type OnceBenchmarkDecision = "BASELINE_CREATED" | "UNCHANGED" | "CHANGED" | "UNKNOWN";
+export interface BenchmarkObservation {
+    timestamp: string;
+    resource: string;
+    fingerprint: string;
+    latency_ms?: number;
+    response_bytes?: number;
+    upstream_cost?: number;
+    once_cost?: number;
+    once_decision?: OnceBenchmarkDecision;
+    metadata?: Record<string, unknown>;
+}
+export interface BenchmarkMetrics {
+    observations: number;
+    unique_resources: number;
+    baseline_observations: number;
+    eligible_repeated_observations: number;
+    unchanged_repeats: number;
+    changed_repeats: number;
+    hindsight_repeat_opportunities: number;
+    hindsight_avoidance_upper_bound: number;
+    evaluated_once_decisions: number;
+    safely_avoidable_observations: number;
+    avoidance_rate: number | null;
+    real_changes_with_once_decision: number;
+    real_changes_correctly_detected: number;
+    change_recall: number | null;
+    stale_state_errors: number;
+    stale_state_error_rate: number | null;
+    latency_avoidable_ms: number;
+    response_bytes_avoidable: number;
+    upstream_cost_avoidable: number;
+    once_check_cost: number;
+    economic_avoidance_ratio: number | null;
+}
+export declare function appendBenchmarkObservation(tracePath: string, observation: BenchmarkObservation): Promise<void>;
+export declare function readBenchmarkTrace(tracePath: string): Promise<BenchmarkObservation[]>;
+export declare function calculateBenchmarkMetrics(observations: BenchmarkObservation[]): BenchmarkMetrics;
+export declare function runBenchmark(tracePath: string): Promise<BenchmarkMetrics>;
+//# sourceMappingURL=benchmark.d.ts.map

package/dist/benchmark.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"benchmark.d.ts","sourceRoot":"","sources":["../src/benchmark.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,qBAAqB,GAC7B,kBAAkB,GAClB,WAAW,GACX,SAAS,GACT,SAAS,CAAC;AAEd,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,qBAAqB,CAAC;IACtC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,gBAAgB;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;IACzB,qBAAqB,EAAE,MAAM,CAAC;IAC9B,8BAA8B,EAAE,MAAM,CAAC;IACvC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,eAAe,EAAE,MAAM,CAAC;IACxB,8BAA8B,EAAE,MAAM,CAAC;IACvC,+BAA+B,EAAE,MAAM,CAAC;IACxC,wBAAwB,EAAE,MAAM,CAAC;IACjC,6BAA6B,EAAE,MAAM,CAAC;IACtC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,+BAA+B,EAAE,MAAM,CAAC;IACxC,+BAA+B,EAAE,MAAM,CAAC;IACxC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,sBAAsB,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,oBAAoB,EAAE,MAAM,CAAC;IAC7B,wBAAwB,EAAE,MAAM,CAAC;IACjC,uBAAuB,EAAE,MAAM,CAAC;IAChC,eAAe,EAAE,MAAM,CAAC;IACxB,wBAAwB,EAAE,MAAM,GAAG,IAAI,CAAC;CACzC;AA8BD,wBAAsB,0BAA0B,CAC9C,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,oBAAoB,GAChC,OAAO,CAAC,IAAI,CAAC,CAQf;AAED,wBAAsB,kBAAkB,CACtC,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,oBAAoB,EAAE,CAAC,CAgBjC;AAED,wBAAgB,yBAAyB,CACvC,YAAY,EAAE,oBAAoB,EAAE,GACnC,gBAAgB,CA2GlB;AAMD,wBAAsB,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CA+B/E"}

package/dist/benchmark.js

@@ -0,0 +1,169 @@
+import { appendFile, readFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { mkdir } from "node:fs/promises";
+function finiteNumber(value) {
+    return typeof value === "number" && Number.isFinite(value)
+        ? value
+        : 0;
+}
+function validateObservation(value, lineNumber) {
+    if (!value || typeof value !== "object") {
+        throw new Error(`Invalid benchmark observation on line ${lineNumber}.`);
+    }
+    const candidate = value;
+    if (typeof candidate.timestamp !== "string" || candidate.timestamp.length === 0) {
+        throw new Error(`Missing timestamp on line ${lineNumber}.`);
+    }
+    if (typeof candidate.resource !== "string" || candidate.resource.length === 0) {
+        throw new Error(`Missing resource on line ${lineNumber}.`);
+    }
+    if (typeof candidate.fingerprint !== "string" || candidate.fingerprint.length === 0) {
+        throw new Error(`Missing fingerprint on line ${lineNumber}.`);
+    }
+    return candidate;
+}
+export async function appendBenchmarkObservation(tracePath, observation) {
+    const absolutePath = resolve(tracePath);
+    await mkdir(dirname(absolutePath), { recursive: true });
+    await appendFile(absolutePath, `${JSON.stringify(observation)}\n`, "utf8");
+}
+export async function readBenchmarkTrace(tracePath) {
+    const text = await readFile(resolve(tracePath), "utf8");
+    const lines = text
+        .split(/\r?\n/u)
+        .map(line => line.trim())
+        .filter(Boolean);
+    return lines.map((line, index) => {
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            throw new Error(`Invalid JSON on benchmark trace line ${index + 1}.`);
+        }
+        return validateObservation(parsed, index + 1);
+    });
+}
+export function calculateBenchmarkMetrics(observations) {
+    const previousByResource = new Map();
+    const resources = new Set();
+    let baselineObservations = 0;
+    let eligibleRepeatedObservations = 0;
+    let unchangedRepeats = 0;
+    let changedRepeats = 0;
+    let evaluatedOnceDecisions = 0;
+    let safelyAvoidableObservations = 0;
+    let realChangesWithOnceDecision = 0;
+    let realChangesCorrectlyDetected = 0;
+    let staleStateErrors = 0;
+    let latencyAvoidableMs = 0;
+    let responseBytesAvoidable = 0;
+    let upstreamCostAvoidable = 0;
+    let onceCheckCost = 0;
+    for (const observation of observations) {
+        resources.add(observation.resource);
+        const previous = previousByResource.get(observation.resource);
+        if (!previous) {
+            baselineObservations += 1;
+            previousByResource.set(observation.resource, observation);
+            continue;
+        }
+        eligibleRepeatedObservations += 1;
+        const actuallyChanged = previous.fingerprint !== observation.fingerprint;
+        if (actuallyChanged) {
+            changedRepeats += 1;
+        }
+        else {
+            unchangedRepeats += 1;
+        }
+        if (observation.once_decision) {
+            evaluatedOnceDecisions += 1;
+            onceCheckCost += finiteNumber(observation.once_cost);
+            if (actuallyChanged) {
+                realChangesWithOnceDecision += 1;
+                if (observation.once_decision === "CHANGED") {
+                    realChangesCorrectlyDetected += 1;
+                }
+                if (observation.once_decision === "UNCHANGED") {
+                    staleStateErrors += 1;
+                }
+            }
+            else if (observation.once_decision === "UNCHANGED") {
+                safelyAvoidableObservations += 1;
+                latencyAvoidableMs += finiteNumber(observation.latency_ms);
+                responseBytesAvoidable += finiteNumber(observation.response_bytes);
+                upstreamCostAvoidable += finiteNumber(observation.upstream_cost);
+            }
+        }
+        previousByResource.set(observation.resource, observation);
+    }
+    const hindsightRepeatOpportunities = unchangedRepeats;
+    const hindsightAvoidanceUpperBound = eligibleRepeatedObservations === 0
+        ? 0
+        : hindsightRepeatOpportunities / eligibleRepeatedObservations;
+    const avoidanceRate = evaluatedOnceDecisions === 0
+        ? null
+        : safelyAvoidableObservations / evaluatedOnceDecisions;
+    const changeRecall = realChangesWithOnceDecision === 0
+        ? null
+        : realChangesCorrectlyDetected / realChangesWithOnceDecision;
+    const staleStateErrorRate = evaluatedOnceDecisions === 0
+        ? null
+        : staleStateErrors / evaluatedOnceDecisions;
+    const economicAvoidanceRatio = onceCheckCost > 0
+        ? upstreamCostAvoidable / onceCheckCost
+        : null;
+    return {
+        observations: observations.length,
+        unique_resources: resources.size,
+        baseline_observations: baselineObservations,
+        eligible_repeated_observations: eligibleRepeatedObservations,
+        unchanged_repeats: unchangedRepeats,
+        changed_repeats: changedRepeats,
+        hindsight_repeat_opportunities: hindsightRepeatOpportunities,
+        hindsight_avoidance_upper_bound: hindsightAvoidanceUpperBound,
+        evaluated_once_decisions: evaluatedOnceDecisions,
+        safely_avoidable_observations: safelyAvoidableObservations,
+        avoidance_rate: avoidanceRate,
+        real_changes_with_once_decision: realChangesWithOnceDecision,
+        real_changes_correctly_detected: realChangesCorrectlyDetected,
+        change_recall: changeRecall,
+        stale_state_errors: staleStateErrors,
+        stale_state_error_rate: staleStateErrorRate,
+        latency_avoidable_ms: latencyAvoidableMs,
+        response_bytes_avoidable: responseBytesAvoidable,
+        upstream_cost_avoidable: upstreamCostAvoidable,
+        once_check_cost: onceCheckCost,
+        economic_avoidance_ratio: economicAvoidanceRatio
+    };
+}
+function percent(value) {
+    return value === null ? "n/a" : `${(value * 100).toFixed(2)}%`;
+}
+export async function runBenchmark(tracePath) {
+    const observations = await readBenchmarkTrace(tracePath);
+    const metrics = calculateBenchmarkMetrics(observations);
+    console.log("");
+    console.log("Once Benchmark");
+    console.log("--------------");
+    console.log(`Trace: ${resolve(tracePath)}`);
+    console.log(`Observations: ${metrics.observations}`);
+    console.log(`Unique resources: ${metrics.unique_resources}`);
+    console.log(`Eligible repeated observations: ${metrics.eligible_repeated_observations}`);
+    console.log(`Hindsight repeat opportunities: ${metrics.hindsight_repeat_opportunities}`);
+    console.log(`Hindsight avoidance upper bound: ${percent(metrics.hindsight_avoidance_upper_bound)}`);
+    console.log(`Shadow Once decisions evaluated: ${metrics.evaluated_once_decisions}`);
+    console.log(`Safely avoided by Once: ${metrics.safely_avoidable_observations}`);
+    console.log(`Measured avoidance rate: ${percent(metrics.avoidance_rate)}`);
+    console.log(`Change recall: ${percent(metrics.change_recall)}`);
+    console.log(`Stale-state errors: ${metrics.stale_state_errors}`);
+    console.log(`Avoidable upstream latency: ${metrics.latency_avoidable_ms.toFixed(0)} ms`);
+    console.log(`Avoidable response bytes: ${metrics.response_bytes_avoidable.toFixed(0)}`);
+    console.log(`Avoidable upstream cost: ${metrics.upstream_cost_avoidable.toFixed(6)}`);
+    console.log(`Once check cost: ${metrics.once_check_cost.toFixed(6)}`);
+    console.log(`Economic Avoidance Ratio: ${metrics.economic_avoidance_ratio === null
+        ? "n/a"
+        : `${metrics.economic_avoidance_ratio.toFixed(2)}x`}`);
+    return metrics;
+}
+//# sourceMappingURL=benchmark.js.map

package/dist/benchmark.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"benchmark.js","sourceRoot":"","sources":["../src/benchmark.ts"],"names":[],"mappings":"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"}

package/dist/cli.js

@@ -5,6 +5,8 @@ import { runScan } from "./scan.js";
 import { runSetup } from "./setup.js";
 import { runProtect } from "./protect.js";
 import { applyProtectionPlan } from "./apply.js";
+import { runBenchmark } from "./benchmark.js";
+import { runTraceFetch } from "./trace.js";
 async function runDoctor() {
     console.log("");
     console.log("Once Doctor");
@@ -73,6 +75,12 @@ function printHelp() {
     console.log("  once scan [directory]");
     console.log("      Find likely consequential operations locally.");
     console.log("");
+    console.log("  once trace fetch <url> [--resource=<id>] [--trace=<path>]");
+    console.log("      Record a raw HTTP observation for Dataset #1 without inventing an Once decision.");
+    console.log("");
+    console.log("  once benchmark <trace.jsonl>");
+    console.log("      Measure hindsight opportunity separately from measured Once avoidance.");
+    console.log("");
     console.log("  once doctor");
     console.log("      Verify your Once connection.");
     console.log("");
@@ -83,6 +91,8 @@ function printHelp() {
     console.log("  once protect . --apply");
     console.log("  once setup .");
     console.log("  once scan .");
+    console.log("  once trace fetch https://api.github.com/repos/stringsofthemind-oss/once");
+    console.log("  once benchmark .once/agent-trace.jsonl");
     console.log("  once doctor");
 }
 async function main() {
@@ -93,6 +103,35 @@ async function main() {
         case "doctor":
             await runDoctor();
             return;
+        case "trace": {
+            const subcommand = (args.shift() ?? "").toLowerCase();
+            if (subcommand !== "fetch") {
+                throw new Error("trace currently supports only read-only HTTP collection: once trace fetch <url>");
+            }
+            const urlValue = args.find(value => !value.startsWith("--"));
+            if (!urlValue) {
+                throw new Error("trace fetch requires a URL. Example: once trace fetch https://api.github.com/repos/stringsofthemind-oss/once");
+            }
+            const resourceArgument = args.find(value => value.startsWith("--resource="));
+            const traceArgument = args.find(value => value.startsWith("--trace="));
+            await runTraceFetch(urlValue, {
+                resource: resourceArgument
+                    ? resourceArgument.substring("--resource=".length)
+                    : undefined,
+                tracePath: traceArgument
+                    ? traceArgument.substring("--trace=".length)
+                    : undefined
+            });
+            return;
+        }
+        case "benchmark": {
+            const tracePath = args.find(value => !value.startsWith("--"));
+            if (!tracePath) {
+                throw new Error("benchmark requires a JSONL trace path. Example: once benchmark .once/agent-trace.jsonl");
+            }
+            await runBenchmark(tracePath);
+            return;
+        }
         case "scan": {
             const noEstimate = args.includes("--no-estimate");
             const requestedPath = args.find(value => !value.startsWith("--")) ?? ".";
@@ -129,15 +168,6 @@ async function main() {
                     const message = String(error instanceof Error
                         ? error.message
                         : error);
-                    /*
-                     * runProtect currently does not persist a plan
-                     * when zero candidates are selected.
-                     *
-                     * Because this apply path has just run Protect
-                     * successfully with writePlan=true, a missing
-                     * protect-plan here means there were zero
-                     * selected candidates.
-                     */
                     if (message.includes("protect-plan.json") &&
                         message.includes("ENOENT")) {
                         throw new Error("--apply requires exactly one PATCHABLE candidate; found 0.");

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/connect/binding.d.ts

@@ -0,0 +1,17 @@
+export type ConnectPayload = Record<string, unknown>;
+export interface ConnectBinding {
+    operationId: string;
+    payloadFingerprint: string;
+}
+export declare class ConnectBindingError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+export declare function canonicalizeConnectPayload(payload: ConnectPayload): string;
+export declare function fingerprintConnectPayload(payload: ConnectPayload): string;
+export declare function bindConnectOperation({ operationId, payload, }: {
+    operationId: string;
+    payload: ConnectPayload;
+}): Readonly<ConnectBinding>;
+export declare function assertConnectBindingMatch(previousBinding: ConnectBinding, nextBinding: ConnectBinding): true;
+//# sourceMappingURL=binding.d.ts.map

package/dist/connect/binding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"binding.d.ts","sourceRoot":"","sources":["../../src/connect/binding.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,cAAc,GACxB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE1B,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAED,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAGpB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM;CAMf;AA0FD,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,cAAc,GACtB,MAAM,CAaR;AAED,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,cAAc,GACtB,MAAM,CAcR;AAED,wBAAgB,oBAAoB,CAAC,EACnC,WAAW,EACX,OAAO,GACR,EAAE;IACD,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,cAAc,CAAC;CACzB,GAAG,QAAQ,CAAC,cAAc,CAAC,CAgB3B;AAED,wBAAgB,yBAAyB,CACvC,eAAe,EAAE,cAAc,EAC/B,WAAW,EAAE,cAAc,GAC1B,IAAI,CAsBN"}

package/dist/connect/binding.js

@@ -0,0 +1,91 @@
+import { createHash } from "node:crypto";
+export class ConnectBindingError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.name = "ConnectBindingError";
+        this.code = code;
+    }
+}
+function canonicalize(value, path = "$") {
+    if (value === null) {
+        return "null";
+    }
+    const type = typeof value;
+    if (type === "string") {
+        return JSON.stringify(value);
+    }
+    if (type === "boolean") {
+        return value ? "true" : "false";
+    }
+    if (type === "number") {
+        const numberValue = value;
+        if (!Number.isFinite(numberValue)) {
+            throw new ConnectBindingError(`Unsupported non-finite number at ${path}.`, "UNSUPPORTED_PAYLOAD_VALUE");
+        }
+        if (Object.is(numberValue, -0)) {
+            return "0";
+        }
+        return JSON.stringify(numberValue);
+    }
+    if (Array.isArray(value)) {
+        return "[" +
+            value
+                .map((item, index) => canonicalize(item, `${path}[${index}]`))
+                .join(",") +
+            "]";
+    }
+    if (type === "object") {
+        const objectValue = value;
+        const prototype = Object.getPrototypeOf(objectValue);
+        if (prototype !== Object.prototype &&
+            prototype !== null) {
+            throw new ConnectBindingError(`Unsupported object type at ${path}.`, "UNSUPPORTED_PAYLOAD_VALUE");
+        }
+        const keys = Object.keys(objectValue).sort();
+        return "{" +
+            keys
+                .map((key) => `${JSON.stringify(key)}:${canonicalize(objectValue[key], `${path}.${key}`)}`)
+                .join(",") +
+            "}";
+    }
+    throw new ConnectBindingError(`Unsupported payload value at ${path}.`, "UNSUPPORTED_PAYLOAD_VALUE");
+}
+export function canonicalizeConnectPayload(payload) {
+    if (payload === null ||
+        typeof payload !== "object" ||
+        Array.isArray(payload)) {
+        throw new ConnectBindingError("Once Connect payload must be a plain object.", "INVALID_PAYLOAD");
+    }
+    return canonicalize(payload);
+}
+export function fingerprintConnectPayload(payload) {
+    const canonical = canonicalizeConnectPayload(payload);
+    const digest = createHash("sha256")
+        .update("once-connect-payload-v1\0", "utf8")
+        .update(canonical, "utf8")
+        .digest("hex");
+    return `once-connect-payload-v1:${digest}`;
+}
+export function bindConnectOperation({ operationId, payload, }) {
+    if (typeof operationId !== "string" ||
+        operationId.trim() === "") {
+        throw new ConnectBindingError("Once Connect requires a stable operationId.", "INVALID_OPERATION_ID");
+    }
+    return Object.freeze({
+        operationId,
+        payloadFingerprint: fingerprintConnectPayload(payload),
+    });
+}
+export function assertConnectBindingMatch(previousBinding, nextBinding) {
+    if (previousBinding.operationId !==
+        nextBinding.operationId) {
+        throw new ConnectBindingError("Operation identities do not match.", "OPERATION_ID_MISMATCH");
+    }
+    if (previousBinding.payloadFingerprint !==
+        nextBinding.payloadFingerprint) {
+        throw new ConnectBindingError("The same operationId was reused with a different consequential payload.", "PAYLOAD_DRIFT");
+    }
+    return true;
+}
+//# sourceMappingURL=binding.js.map

package/dist/connect/binding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"binding.js","sourceRoot":"","sources":["../../src/connect/binding.ts"],"names":[],"mappings":"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"}

package/dist/connect/classifier.d.ts

@@ -0,0 +1,18 @@
+export declare const CONNECT_DECISION: Readonly<{
+    readonly PROTECT: "PROTECT";
+    readonly BYPASS: "BYPASS";
+    readonly REJECT: "REJECT";
+}>;
+export type ConnectDecision = (typeof CONNECT_DECISION)[keyof typeof CONNECT_DECISION];
+export interface ConnectSafetyDeclaration {
+    changesExternalState: boolean;
+    retryPossible: boolean;
+    ambiguousOutcomePossible: boolean;
+    duplicateUndesirable: boolean;
+}
+export interface ConnectClassification {
+    decision: ConnectDecision;
+    reason: "INVALID_OPERATION" | "INCOMPLETE_SAFETY_DECLARATION" | "CONSEQUENTIAL_RETRY_RISK" | "PROTECTION_CONDITIONS_NOT_ALL_PRESENT";
+}
+export declare function classifyConnectOperation(operation: unknown): Readonly<ConnectClassification>;
+//# sourceMappingURL=classifier.d.ts.map

package/dist/connect/classifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"classifier.d.ts","sourceRoot":"","sources":["../../src/connect/classifier.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,gBAAgB;;;;EAIlB,CAAC;AAEZ,MAAM,MAAM,eAAe,GACzB,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,OAAO,gBAAgB,CAAC,CAAC;AAE3D,MAAM,WAAW,wBAAwB;IACvC,oBAAoB,EAAE,OAAO,CAAC;IAC9B,aAAa,EAAE,OAAO,CAAC;IACvB,wBAAwB,EAAE,OAAO,CAAC;IAClC,oBAAoB,EAAE,OAAO,CAAC;CAC/B;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,eAAe,CAAC;IAC1B,MAAM,EACF,mBAAmB,GACnB,+BAA+B,GAC/B,0BAA0B,GAC1B,uCAAuC,CAAC;CAC7C;AAaD,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,OAAO,GACjB,QAAQ,CAAC,qBAAqB,CAAC,CAmEjC"}

package/dist/connect/classifier.js

@@ -0,0 +1,49 @@
+export const CONNECT_DECISION = Object.freeze({
+    PROTECT: "PROTECT",
+    BYPASS: "BYPASS",
+    REJECT: "REJECT",
+});
+function requireBoolean(value, name) {
+    if (typeof value !== "boolean") {
+        throw new TypeError(`Once Connect requires boolean "${name}".`);
+    }
+}
+export function classifyConnectOperation(operation) {
+    if (!operation ||
+        typeof operation !== "object" ||
+        Array.isArray(operation)) {
+        return Object.freeze({
+            decision: CONNECT_DECISION.REJECT,
+            reason: "INVALID_OPERATION",
+        });
+    }
+    const candidate = operation;
+    const { changesExternalState, retryPossible, ambiguousOutcomePossible, duplicateUndesirable, } = candidate;
+    try {
+        requireBoolean(changesExternalState, "changesExternalState");
+        requireBoolean(retryPossible, "retryPossible");
+        requireBoolean(ambiguousOutcomePossible, "ambiguousOutcomePossible");
+        requireBoolean(duplicateUndesirable, "duplicateUndesirable");
+    }
+    catch {
+        return Object.freeze({
+            decision: CONNECT_DECISION.REJECT,
+            reason: "INCOMPLETE_SAFETY_DECLARATION",
+        });
+    }
+    const requiresProtection = changesExternalState &&
+        retryPossible &&
+        ambiguousOutcomePossible &&
+        duplicateUndesirable;
+    if (requiresProtection) {
+        return Object.freeze({
+            decision: CONNECT_DECISION.PROTECT,
+            reason: "CONSEQUENTIAL_RETRY_RISK",
+        });
+    }
+    return Object.freeze({
+        decision: CONNECT_DECISION.BYPASS,
+        reason: "PROTECTION_CONDITIONS_NOT_ALL_PRESENT",
+    });
+}
+//# sourceMappingURL=classifier.js.map

package/dist/connect/classifier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"classifier.js","sourceRoot":"","sources":["../../src/connect/classifier.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,CAAC;IAC5C,OAAO,EAAE,SAAS;IAClB,MAAM,EAAE,QAAQ;IAChB,MAAM,EAAE,QAAQ;CACR,CAAC,CAAC;AAqBZ,SAAS,cAAc,CACrB,KAAc,EACd,IAAY;IAEZ,IAAI,OAAO,KAAK,KAAK,SAAS,EAAE,CAAC;QAC/B,MAAM,IAAI,SAAS,CACjB,kCAAkC,IAAI,IAAI,CAC3C,CAAC;IACJ,CAAC;AACH,CAAC;AAED,MAAM,UAAU,wBAAwB,CACtC,SAAkB;IAElB,IACE,CAAC,SAAS;QACV,OAAO,SAAS,KAAK,QAAQ;QAC7B,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,EACxB,CAAC;QACD,OAAO,MAAM,CAAC,MAAM,CAAC;YACnB,QAAQ,EAAE,gBAAgB,CAAC,MAAM;YACjC,MAAM,EAAE,mBAAmB;SAC5B,CAAC,CAAC;IACL,CAAC;IAED,MAAM,SAAS,GACb,SAAoC,CAAC;IAEvC,MAAM,EACJ,oBAAoB,EACpB,aAAa,EACb,wBAAwB,EACxB,oBAAoB,GACrB,GAAG,SAAS,CAAC;IAEd,IAAI,CAAC;QACH,cAAc,CACZ,oBAAoB,EACpB,sBAAsB,CACvB,CAAC;QAEF,cAAc,CACZ,aAAa,EACb,eAAe,CAChB,CAAC;QAEF,cAAc,CACZ,wBAAwB,EACxB,0BAA0B,CAC3B,CAAC;QAEF,cAAc,CACZ,oBAAoB,EACpB,sBAAsB,CACvB,CAAC;IACJ,CAAC;IACD,MAAM,CAAC;QACL,OAAO,MAAM,CAAC,MAAM,CAAC;YACnB,QAAQ,EAAE,gBAAgB,CAAC,MAAM;YACjC,MAAM,EAAE,+BAA+B;SACxC,CAAC,CAAC;IACL,CAAC;IAED,MAAM,kBAAkB,GACtB,oBAAoB;QACpB,aAAa;QACb,wBAAwB;QACxB,oBAAoB,CAAC;IAEvB,IAAI,kBAAkB,EAAE,CAAC;QACvB,OAAO,MAAM,CAAC,MAAM,CAAC;YACnB,QAAQ,EAAE,gBAAgB,CAAC,OAAO;YAClC,MAAM,EAAE,0BAA0B;SACnC,CAAC,CAAC;IACL,CAAC;IAED,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,QAAQ,EAAE,gBAAgB,CAAC,MAAM;QACjC,MAAM,EAAE,uCAAuC;KAChD,CAAC,CAAC;AACL,CAAC"}

package/dist/connect/execute.d.ts

@@ -0,0 +1,30 @@
+import type { ConnectClassification, ConnectSafetyDeclaration } from "./classifier.js";
+import type { ConnectPayload } from "./binding.js";
+export interface ConnectProtectedContext {
+    operationId: string;
+    payload: ConnectPayload;
+    payloadFingerprint: string;
+    classification: Readonly<ConnectClassification>;
+}
+export interface ConnectExecutionInput<T = unknown> {
+    safety: ConnectSafetyDeclaration;
+    operationId: string;
+    payload: ConnectPayload;
+    bypass?: () => Promise<T> | T;
+    protect?: (context: ConnectProtectedContext) => Promise<T> | T;
+}
+export declare class ConnectExecutionError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+/**
+ * Framework-neutral Connect orchestration boundary.
+ *
+ * Connect decides whether the proposed tool call requires
+ * Once protection. It does not implement execution safety.
+ *
+ * Protected execution is delegated to the existing Once
+ * runtime/kernel supplied by the caller.
+ */
+export declare function executeConnectOperation<T = unknown>({ safety, operationId, payload, bypass, protect, }: ConnectExecutionInput<T>): Promise<T>;
+//# sourceMappingURL=execute.d.ts.map

package/dist/connect/execute.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execute.d.ts","sourceRoot":"","sources":["../../src/connect/execute.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,qBAAqB,EACrB,wBAAwB,EACzB,MAAM,iBAAiB,CAAC;AAMzB,OAAO,KAAK,EACV,cAAc,EACf,MAAM,cAAc,CAAC;AAEtB,MAAM,WAAW,uBAAuB;IACtC,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,cAAc,CAAC;IACxB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,cAAc,EAAE,QAAQ,CAAC,qBAAqB,CAAC,CAAC;CACjD;AAED,MAAM,WAAW,qBAAqB,CAAC,CAAC,GAAG,OAAO;IAChD,MAAM,EAAE,wBAAwB,CAAC;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,cAAc,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IAC9B,OAAO,CAAC,EAAE,CACR,OAAO,EAAE,uBAAuB,KAC7B,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;CACrB;AAED,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAGpB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM;CAMf;AAED;;;;;;;;GAQG;AACH,wBAAsB,uBAAuB,CAAC,CAAC,GAAG,OAAO,EAAE,EACzD,MAAM,EACN,WAAW,EACX,OAAO,EACP,MAAM,EACN,OAAO,GACR,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAoDvC"}