@nifrajs/webmcp 3.5.0

package/dist/index.js

@@ -0,0 +1,692 @@
+/**
+ * Nifra's typed Agent Surface contract and WebMCP adapter.
+ *
+ * WebMCP is the page-local transport: a compatible host discovers the standard
+ * `document.modelContext.registerTool` surface. Nifra adds typed core-tool
+ * execution, deterministic prediction/reconciliation, bounded receipts, and a
+ * host-independent conformance runner around that transport.
+ */
+import { validateStandard } from "@nifrajs/core/schema";
+import { toCatalogEntry } from "@nifrajs/core/tool-catalog";
+import { defineTool, executeTool, } from "@nifrajs/core/tool-contract";
+const MAX_ID_LENGTH = 128;
+const MAX_PATH_LENGTH = 256;
+const MAX_PATCH_OPERATIONS = 256;
+const MAX_ACTIVE_PREDICTIONS = 256;
+const MAX_PATCH_VALUE_BYTES = 64 * 1024;
+const DEFAULT_MAX_RECEIPT_BYTES = 16 * 1024;
+const MAX_RECEIPT_BYTES = 64 * 1024;
+const MAX_REGISTRATION_ERROR_LENGTH = 256;
+const VERSION_RE = /^[-A-Za-z0-9._:/]{1,128}$/;
+const STATE_PATH_RE = /^[a-z][A-Za-z0-9._:/-]{0,127}$/;
+const FORBIDDEN_PATH_SEGMENTS = new Set(["__proto__", "constructor", "prototype"]);
+/** Create a capability from the same core tool contract used by Nifra's other adapters. */
+export function defineAgentCapability(options) {
+    const tool = defineTool(options);
+    const scope = options.scope ?? "page";
+    if (scope !== "page" && scope !== "session" && scope !== "server")
+        throw new TypeError("agent surface: scope is invalid");
+    const reads = validateStatePaths(options.reads ?? [], "reads");
+    const writes = validateStatePaths(options.writes ?? [], "writes");
+    const reconciliation = options.reconciliation ?? "manual";
+    if (reconciliation !== "accept-server-state" &&
+        reconciliation !== "reload" &&
+        reconciliation !== "manual")
+        throw new TypeError("agent surface: reconciliation is invalid");
+    if (options.predict !== undefined && options.reconcile === undefined)
+        throw new TypeError("agent surface: predict requires reconcile");
+    return Object.freeze({
+        tool,
+        surface: Object.freeze({
+            scope,
+            reads: Object.freeze(reads),
+            writes: Object.freeze(writes),
+            reconciliation,
+        }),
+        ...(options.predict === undefined ? {} : { predict: options.predict }),
+        ...(options.reconcile === undefined ? {} : { reconcile: options.reconcile }),
+    });
+}
+function validateStatePaths(paths, label) {
+    if (!Array.isArray(paths))
+        throw new TypeError(`agent surface: ${label} must be an array`);
+    const unique = new Set();
+    for (const path of paths) {
+        if (typeof path !== "string" || !STATE_PATH_RE.test(path))
+            throw new TypeError(`agent surface: ${label} contains an invalid path`);
+        unique.add(path);
+    }
+    return [...unique];
+}
+/** Adapt one canonical capability to the proposed WebMCP tool shape. */
+export function toWebMcpTool(capability, options = {}) {
+    const maxReceiptBytes = validateReceiptLimit(options.maxReceiptBytes);
+    const entry = toCatalogEntry(capability.tool);
+    const fixedCapabilities = [capability.tool.capability, ...(options.capabilities ?? [])];
+    return {
+        name: entry.name,
+        description: entry.description,
+        inputSchema: entry.inputSchema,
+        annotations: entry.annotations,
+        execute: async (input) => {
+            if (options.authorize !== undefined) {
+                let authorized = false;
+                try {
+                    authorized = await options.authorize(input);
+                }
+                catch {
+                    // A page-local guard is untrusted adapter code. Treat a thrown guard as a denial rather
+                    // than leaking its exception through the WebMCP host.
+                    authorized = false;
+                }
+                if (!authorized)
+                    return deniedReceipt(options.dryRun === true);
+            }
+            const result = await executeAgentCapability(capability, input, {
+                ...options,
+                capabilities: fixedCapabilities,
+            });
+            const receipt = toReceipt(result, maxReceiptBytes);
+            // Raw output mode is explicitly opt-in and exists for hosts that already impose their own
+            // response limits. The default receipt path stays bounded.
+            if (options.resultMode === "output" && result.ok)
+                return result.output;
+            return receipt;
+        },
+    };
+}
+function deniedReceipt(dryRun) {
+    return Object.freeze({
+        ok: false,
+        outcome: "denied",
+        dryRun,
+        error: { code: "capability_denied", stage: "capability" },
+        evidence: Object.freeze([]),
+    });
+}
+/** Execute through Nifra's existing validation, policy, approval, idempotency, and evidence path. */
+export function executeAgentCapability(capability, input, options = {}) {
+    return executeTool(capability.tool, input, {
+        ...options,
+        capabilities: [capability.tool.capability, ...(options.capabilities ?? [])],
+    });
+}
+function toReceipt(result, maxReceiptBytes) {
+    if (result.ok) {
+        const bounded = boundReceiptOutput(result.output, maxReceiptBytes);
+        return Object.freeze({
+            ok: true,
+            outcome: result.dryRun ? "dry-run" : "committed",
+            dryRun: result.dryRun,
+            ...(bounded.output === undefined ? {} : { output: bounded.output }),
+            ...(bounded.truncated ? { outputTruncated: true } : {}),
+            evidence: result.evidence,
+        });
+    }
+    return Object.freeze({
+        ok: false,
+        outcome: "failed",
+        dryRun: result.dryRun,
+        error: { code: result.error.code, stage: result.error.stage },
+        evidence: result.evidence,
+    });
+}
+function validateReceiptLimit(value) {
+    if (value === undefined)
+        return DEFAULT_MAX_RECEIPT_BYTES;
+    if (!Number.isSafeInteger(value) || value < 256 || value > MAX_RECEIPT_BYTES)
+        throw new RangeError(`agent surface: maxReceiptBytes must be a safe integer between 256 and ${MAX_RECEIPT_BYTES}`);
+    return value;
+}
+function boundReceiptOutput(output, maxBytes) {
+    if (output === undefined)
+        return {};
+    try {
+        const encoded = new TextEncoder().encode(JSON.stringify(output));
+        return encoded.byteLength <= maxBytes ? { output } : { truncated: true };
+    }
+    catch {
+        // A non-JSON output is not safe to put in a portable receipt. The typed output mode remains
+        // available to an embedding host that has its own serialization contract.
+        return { truncated: true };
+    }
+}
+const targetRegistrations = new WeakMap();
+function defaultTarget() {
+    const page = globalThis.document;
+    return page;
+}
+/** Register an explicit allowlist of capabilities, safely degrading on ordinary browsers. */
+export async function registerWebMcpTools(capabilities, target = defaultTarget(), options = {}) {
+    const context = target?.modelContext;
+    if (context === undefined || typeof context.registerTool !== "function")
+        return Object.freeze({
+            supported: false,
+            registered: Object.freeze([]),
+            failed: Object.freeze([]),
+            cleanup: async () => { },
+        });
+    const key = context;
+    const existing = targetRegistrations.get(key) ?? new Set();
+    targetRegistrations.set(key, existing);
+    const registered = [];
+    const failed = [];
+    for (const capability of capabilities) {
+        const name = capability.tool.name;
+        if (existing.has(name)) {
+            failed.push({ name, error: "duplicate tool name is already registered" });
+            continue;
+        }
+        // Reserve before awaiting the host. `registerTool` may be asynchronous, and another caller can
+        // enter this function while it is pending. Keeping the reservation in the same set as committed
+        // names makes duplicate detection atomic from JavaScript's point of view; failures release only
+        // their own reservation so a later registration can retry safely.
+        existing.add(name);
+        try {
+            await context.registerTool(toWebMcpTool(capability, options));
+            registered.push(name);
+        }
+        catch (error) {
+            existing.delete(name);
+            if (existing.size === 0 && targetRegistrations.get(key) === existing)
+                targetRegistrations.delete(key);
+            failed.push({ name, error: describeError(error) });
+        }
+    }
+    let cleaned = false;
+    const cleanup = async () => {
+        if (cleaned)
+            return;
+        cleaned = true;
+        if (context.unregisterTool === undefined)
+            return;
+        for (const name of [...registered].reverse()) {
+            try {
+                await context.unregisterTool(name);
+                existing.delete(name);
+            }
+            catch {
+                // Cleanup is best effort; a host failure must not break the application.
+            }
+        }
+        if (existing.size === 0 && targetRegistrations.get(key) === existing)
+            targetRegistrations.delete(key);
+    };
+    return Object.freeze({
+        supported: true,
+        registered: Object.freeze([...registered]),
+        failed: Object.freeze([...failed]),
+        cleanup,
+    });
+}
+function describeError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return message.length <= MAX_REGISTRATION_ERROR_LENGTH
+        ? message
+        : `${message.slice(0, MAX_REGISTRATION_ERROR_LENGTH - 3)}...`;
+}
+/**
+ * An atomic, defensive prediction store. Predictions are overlays over authoritative state; a server
+ * commit replaces the base and remaining overlays are replayed or conflict-dropped.
+ */
+export function createPredictionStore(initial) {
+    let authoritative = cloneValue(initial, "initial state");
+    validateVersion(initial.version);
+    const active = new Map();
+    const conflicted = new Map();
+    const order = [];
+    const listeners = new Set();
+    const removeActive = (id) => {
+        active.delete(id);
+        const index = order.indexOf(id);
+        if (index !== -1)
+            order.splice(index, 1);
+    };
+    const rememberConflict = (id) => {
+        conflicted.delete(id);
+        if (conflicted.size >= MAX_ACTIVE_PREDICTIONS) {
+            const oldest = conflicted.keys().next().value;
+            if (oldest !== undefined)
+                conflicted.delete(oldest);
+        }
+        conflicted.set(id, true);
+    };
+    const snapshot = () => {
+        let state = cloneValue(authoritative.state, "authoritative state");
+        const invalid = [];
+        for (const id of [...order]) {
+            const stored = active.get(id);
+            if (stored === undefined)
+                continue;
+            try {
+                state = applyPredictionPatch(state, stored.prediction.patch);
+            }
+            catch {
+                invalid.push(id);
+            }
+        }
+        for (const id of invalid) {
+            removeActive(id);
+            rememberConflict(id);
+        }
+        return Object.freeze({
+            state,
+            version: authoritative.version,
+            authoritativeVersion: authoritative.version,
+            activePredictionIds: Object.freeze(order.filter((id) => active.has(id))),
+        });
+    };
+    const emit = (event) => {
+        for (const listener of listeners) {
+            try {
+                listener(event);
+            }
+            catch {
+                // Observer failures cannot change the state machine.
+            }
+        }
+    };
+    const predict = (predictionId, prediction, now = Date.now()) => {
+        validateIdentifier(predictionId, "prediction id");
+        validatePrediction(prediction);
+        const current = snapshot();
+        if (active.has(predictionId) || conflicted.has(predictionId))
+            return { outcome: "invalid", predictionId, snapshot: current };
+        if (active.size >= MAX_ACTIVE_PREDICTIONS)
+            return { outcome: "invalid", predictionId, snapshot: current };
+        if (prediction.baseVersion !== authoritative.version)
+            return { outcome: "stale", predictionId, snapshot: current };
+        if (prediction.expiresAt !== undefined && prediction.expiresAt <= now)
+            return { outcome: "expired", predictionId, snapshot: current };
+        const candidate = applyPredictionPatch(current.state, prediction.patch);
+        // Clone before storing so caller mutation after predict cannot change the overlay.
+        const stored = {
+            id: predictionId,
+            prediction: Object.freeze({
+                baseVersion: prediction.baseVersion,
+                patch: Object.freeze(prediction.patch.map((op) => clonePatchOperation(op))),
+                ...(prediction.expiresAt === undefined ? {} : { expiresAt: prediction.expiresAt }),
+            }),
+        };
+        active.set(predictionId, stored);
+        order.push(predictionId);
+        const next = snapshot();
+        // This should be impossible after candidate was applied; retain the guard as an atomicity check.
+        if (!deepEqual(candidate, next.state)) {
+            removeActive(predictionId);
+            return { outcome: "invalid", predictionId, snapshot: snapshot() };
+        }
+        const result = { outcome: "predicted", predictionId, snapshot: next };
+        emit({ type: "predicted", predictionId, snapshot: next });
+        return result;
+    };
+    const discardUnreplayablePredictions = () => {
+        const discarded = [];
+        let projected = cloneValue(authoritative.state, "authoritative state");
+        for (const id of [...order]) {
+            const stored = active.get(id);
+            if (stored === undefined)
+                continue;
+            if (stored.prediction.baseVersion !== authoritative.version) {
+                removeActive(id);
+                rememberConflict(id);
+                discarded.push(id);
+                continue;
+            }
+            try {
+                projected = applyPredictionPatch(projected, stored.prediction.patch);
+            }
+            catch {
+                removeActive(id);
+                rememberConflict(id);
+                discarded.push(id);
+            }
+        }
+        return Object.freeze(discarded);
+    };
+    const commit = (predictionId, nextAuthoritative, now = Date.now()) => {
+        validateIdentifier(predictionId, "prediction id");
+        const stored = active.get(predictionId);
+        const current = snapshot();
+        if (stored === undefined) {
+            if (conflicted.delete(predictionId))
+                return { outcome: "conflicted", predictionId, snapshot: current };
+            return { outcome: "missing", predictionId, snapshot: current };
+        }
+        if (stored.prediction.expiresAt !== undefined && stored.prediction.expiresAt <= now) {
+            removeActive(predictionId);
+            const expired = snapshot();
+            emit({ type: "expired", predictionId, snapshot: expired });
+            return { outcome: "expired", predictionId, snapshot: expired };
+        }
+        if (stored.prediction.baseVersion !== authoritative.version) {
+            removeActive(predictionId);
+            rememberConflict(predictionId);
+            const conflicted = snapshot();
+            emit({ type: "conflicted", predictionId, snapshot: conflicted });
+            return { outcome: "conflicted", predictionId, snapshot: conflicted };
+        }
+        validateVersion(nextAuthoritative.version);
+        const nextState = cloneValue(nextAuthoritative.state, "authoritative state");
+        removeActive(predictionId);
+        authoritative = { state: nextState, version: nextAuthoritative.version };
+        const discarded = discardUnreplayablePredictions();
+        const committed = snapshot();
+        emit({ type: "committed", predictionId, snapshot: committed });
+        for (const id of discarded)
+            emit({ type: "conflicted", predictionId: id, snapshot: committed });
+        return { outcome: "committed", predictionId, snapshot: committed };
+    };
+    const rollback = (predictionId) => {
+        validateIdentifier(predictionId, "prediction id");
+        if (!active.has(predictionId))
+            return { outcome: "missing", predictionId, snapshot: snapshot() };
+        removeActive(predictionId);
+        const rolledBack = snapshot();
+        emit({ type: "rolled-back", predictionId, snapshot: rolledBack });
+        return { outcome: "rolled-back", predictionId, snapshot: rolledBack };
+    };
+    const expire = (now = Date.now()) => {
+        const expired = [];
+        for (const id of [...order]) {
+            const stored = active.get(id);
+            if (stored?.prediction.expiresAt !== undefined && stored.prediction.expiresAt <= now) {
+                removeActive(id);
+                expired.push(id);
+                emit({ type: "expired", predictionId: id, snapshot: snapshot() });
+            }
+        }
+        return Object.freeze(expired);
+    };
+    return {
+        snapshot,
+        predict,
+        commit,
+        rollback,
+        expire,
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+    };
+}
+/** Apply a pure prediction, execute the core tool, then commit or roll it back atomically. */
+export async function executePredicted(capability, input, store, options = {}) {
+    const now = options.now ?? Date.now;
+    const validated = await validateStandard(capability.tool.input, input);
+    if (options.signal?.aborted)
+        return { outcome: "rolled-back", snapshot: store.snapshot() };
+    if (!validated.ok) {
+        const tool = await executeAgentCapability(capability, input, options);
+        return {
+            outcome: "executed",
+            tool,
+            snapshot: store.snapshot(),
+        };
+    }
+    if (capability.predict === undefined) {
+        const tool = await executeAgentCapability(capability, input, options);
+        return {
+            outcome: tool.ok ? "executed" : "rolled-back",
+            tool,
+            snapshot: store.snapshot(),
+        };
+    }
+    if (capability.reconcile === undefined)
+        throw new TypeError("agent surface: prediction capability has no reconciler");
+    const before = store.snapshot();
+    const predictionInput = cloneValue(validated.value, "prediction input");
+    const prediction = await capability.predict({
+        input: predictionInput,
+        snapshot: before.state,
+        version: before.version,
+        now: now(),
+    });
+    if (options.signal?.aborted)
+        return { outcome: "rolled-back", snapshot: store.snapshot() };
+    const predictionId = options.predictionId ?? crypto.randomUUID();
+    const proposed = store.predict(predictionId, prediction, now());
+    if (proposed.outcome !== "predicted")
+        return {
+            outcome: proposed.outcome === "missing" ? "invalid" : proposed.outcome,
+            predictionId,
+            prediction,
+            snapshot: proposed.snapshot,
+        };
+    const tool = await executeAgentCapability(capability, input, options);
+    if (!tool.ok || options.signal?.aborted) {
+        const rolledBack = store.rollback(predictionId);
+        return { outcome: "rolled-back", predictionId, prediction, tool, snapshot: rolledBack.snapshot };
+    }
+    let authoritative;
+    try {
+        authoritative = await capability.reconcile({
+            input: cloneValue(predictionInput, "reconciliation input"),
+            output: cloneValue(tool.output, "reconciliation output"),
+            previous: before,
+            prediction,
+            now: now(),
+        });
+    }
+    catch {
+        const rolledBack = store.rollback(predictionId);
+        return { outcome: "rolled-back", predictionId, prediction, tool, snapshot: rolledBack.snapshot };
+    }
+    if (options.signal?.aborted) {
+        const rolledBack = store.rollback(predictionId);
+        return { outcome: "rolled-back", predictionId, prediction, tool, snapshot: rolledBack.snapshot };
+    }
+    const committed = store.commit(predictionId, authoritative, now());
+    return {
+        outcome: committed.outcome === "committed"
+            ? "committed"
+            : committed.outcome === "expired"
+                ? "expired"
+                : "conflicted",
+        predictionId,
+        prediction,
+        tool,
+        snapshot: committed.snapshot,
+    };
+}
+/** Run deterministic host-independent checks over the WebMCP projection and optional calls. */
+export async function runAgentSurfaceConformance(capabilities, options = {}) {
+    const checks = [];
+    const names = new Set();
+    for (const capability of capabilities) {
+        if (names.has(capability.tool.name))
+            throw new Error(`agent surface conformance: duplicate ${capability.tool.name}`);
+        names.add(capability.tool.name);
+        const tool = toWebMcpTool(capability);
+        if (tool.name !== capability.tool.name || typeof tool.execute !== "function")
+            throw new Error(`agent surface conformance: invalid descriptor ${capability.tool.name}`);
+    }
+    checks.push("unique standard descriptors");
+    const report = await registerWebMcpTools(capabilities, options.target, options.registration);
+    if (!report.supported) {
+        checks.push("unsupported host degrades safely");
+        return Object.freeze({
+            supported: false,
+            registered: report.registered,
+            failed: report.failed,
+            checks: Object.freeze(checks),
+        });
+    }
+    try {
+        checks.push("host registration");
+        const byName = new Map(capabilities.map((capability) => [capability.tool.name, capability]));
+        for (const testCase of options.cases ?? []) {
+            const capability = byName.get(testCase.capability.tool.name);
+            if (capability === undefined)
+                throw new Error(`agent surface conformance: unknown case ${testCase.capability.tool.name}`);
+            const result = await toWebMcpTool(capability, options.registration).execute(testCase.input);
+            await testCase.assert?.(result);
+            checks.push(`call ${capability.tool.name}`);
+        }
+    }
+    finally {
+        await report.cleanup();
+    }
+    return Object.freeze({
+        supported: true,
+        registered: report.registered,
+        failed: report.failed,
+        checks: Object.freeze(checks),
+    });
+}
+function validateIdentifier(value, label) {
+    if (typeof value !== "string" || value.length === 0 || value.length > MAX_ID_LENGTH)
+        throw new TypeError(`agent surface: ${label} is invalid`);
+}
+function validateVersion(version) {
+    if (typeof version !== "string" || !VERSION_RE.test(version))
+        throw new TypeError("agent surface: version is invalid");
+}
+function validatePrediction(prediction) {
+    validateVersion(prediction.baseVersion);
+    if (!Array.isArray(prediction.patch) || prediction.patch.length > MAX_PATCH_OPERATIONS)
+        throw new TypeError("agent surface: prediction patch is invalid");
+    if (prediction.expiresAt !== undefined && !Number.isSafeInteger(prediction.expiresAt))
+        throw new TypeError("agent surface: prediction expiry is invalid");
+    for (const operation of prediction.patch) {
+        if (operation === null || typeof operation !== "object")
+            throw new TypeError("agent surface: prediction operation is invalid");
+        if (operation.op !== "add" && operation.op !== "replace" && operation.op !== "remove")
+            throw new TypeError("agent surface: prediction operation is unsupported");
+        if (typeof operation.path !== "string" || operation.path.length > MAX_PATH_LENGTH)
+            throw new TypeError("agent surface: prediction path is invalid");
+        decodePointer(operation.path);
+    }
+}
+function cloneValue(value, label) {
+    try {
+        return structuredClone(value);
+    }
+    catch {
+        throw new TypeError(`agent surface: ${label} must be structured-cloneable`);
+    }
+}
+function clonePatchOperation(operation) {
+    if (operation.op === "remove")
+        return { op: "remove", path: operation.path };
+    return {
+        op: operation.op,
+        path: operation.path,
+        value: clonePatchValue(operation.value),
+    };
+}
+function clonePatchValue(value) {
+    try {
+        const cloned = structuredClone(value);
+        const encoded = JSON.stringify(cloned);
+        if (encoded === undefined)
+            throw new TypeError("agent surface: patch value must be JSON-serializable");
+        if (new TextEncoder().encode(encoded).byteLength > MAX_PATCH_VALUE_BYTES)
+            throw new RangeError("agent surface: patch value exceeds its size limit");
+        return cloned;
+    }
+    catch (error) {
+        if (error instanceof RangeError || error instanceof TypeError)
+            throw error;
+        throw new TypeError("agent surface: patch value must be structured-cloneable JSON");
+    }
+}
+function deepEqual(a, b) {
+    try {
+        return JSON.stringify(a) === JSON.stringify(b);
+    }
+    catch {
+        return false;
+    }
+}
+function decodePointer(path) {
+    if (path === "")
+        return Object.freeze([]);
+    if (!path.startsWith("/"))
+        throw new TypeError("agent surface: patch path must be a JSON Pointer");
+    const segments = path
+        .slice(1)
+        .split("/")
+        .map((segment) => {
+        for (let index = 0; index < segment.length; index += 1) {
+            if (segment[index] === "~" && segment[index + 1] !== "0" && segment[index + 1] !== "1")
+                throw new TypeError("agent surface: patch pointer escape is invalid");
+        }
+        return segment.replace(/~1/g, "/").replace(/~0/g, "~");
+    });
+    if (segments.some((segment) => FORBIDDEN_PATH_SEGMENTS.has(segment)))
+        throw new TypeError("agent surface: prototype path is forbidden");
+    return Object.freeze(segments);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function applyPredictionPatch(state, operations) {
+    let current = cloneValue(state, "prediction state");
+    for (const operation of operations)
+        current = applyPredictionOperation(current, operation);
+    return current;
+}
+function applyPredictionOperation(document, operation) {
+    const segments = decodePointer(operation.path);
+    if (segments.length === 0) {
+        if (operation.op === "remove")
+            throw new TypeError("agent surface: root removal is forbidden");
+        return clonePatchValue(operation.value);
+    }
+    const parentSegments = segments.slice(0, -1);
+    const leaf = segments[segments.length - 1];
+    const parent = readPointer(document, parentSegments);
+    if (Array.isArray(parent)) {
+        if (operation.op === "add") {
+            if (leaf === "-")
+                parent.push(clonePatchValue(operation.value));
+            else {
+                const index = arrayIndex(leaf, parent.length, true);
+                parent.splice(index, 0, clonePatchValue(operation.value));
+            }
+            return document;
+        }
+        const index = arrayIndex(leaf, parent.length, false);
+        if (operation.op === "replace")
+            parent[index] = clonePatchValue(operation.value);
+        else
+            parent.splice(index, 1);
+        return document;
+    }
+    if (!isRecord(parent))
+        throw new TypeError("agent surface: patch parent is not an object");
+    if (operation.op === "replace" && !Object.hasOwn(parent, leaf))
+        throw new TypeError("agent surface: replace target is missing");
+    if (operation.op === "remove" && !Object.hasOwn(parent, leaf))
+        throw new TypeError("agent surface: remove target is missing");
+    if (operation.op === "remove")
+        delete parent[leaf];
+    else
+        parent[leaf] = clonePatchValue(operation.value);
+    return document;
+}
+function readPointer(document, segments) {
+    let current = document;
+    for (const segment of segments) {
+        if (Array.isArray(current))
+            current = current[arrayIndex(segment, current.length, false)];
+        else if (isRecord(current) && Object.hasOwn(current, segment))
+            current = current[segment];
+        else
+            throw new TypeError("agent surface: patch parent is missing");
+    }
+    return current;
+}
+function arrayIndex(segment, length, allowEnd) {
+    if (!/^(?:0|[1-9]\d*)$/.test(segment))
+        throw new TypeError("agent surface: array index is invalid");
+    const index = Number(segment);
+    if (!Number.isSafeInteger(index) ||
+        index < 0 ||
+        index > length ||
+        (!allowEnd && index === length))
+        throw new TypeError("agent surface: array index is out of bounds");
+    return index;
+}
+//# sourceMappingURL=index.js.map