@synadia-ai/agent-fabric 0.0.0-stage → 0.1.0

package/dist/index.cjs

@@ -0,0 +1,4821 @@
+'use strict';
+
+var agentService = require('@synadia-ai/agent-service');
+var node_async_hooks = require('node:async_hooks');
+var agents = require('@synadia-ai/agents');
+var node_child_process = require('node:child_process');
+var node_crypto = require('node:crypto');
+var promises = require('node:fs/promises');
+var node_os = require('node:os');
+var node_path = require('node:path');
+var natsCore = require('@nats-io/nats-core');
+var node_fs = require('node:fs');
+
+// src/tracing.ts
+var EDGE_RECORD_VERSION = 1;
+var DEFAULT_EDGE_SUBJECT = "TRACE.edges";
+var THREAD_ID_FIELD = "thread_id";
+var ROOT_ID_FIELD = "root_id";
+var THREAD_ID_HEADER = "X-Synadia-Thread-ID";
+var ROOT_ID_HEADER = "X-Synadia-Root-ID";
+var SUBJECT_FORBIDDEN = /[\u0000-\u0020\u007f\u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000\ufeff]/;
+function assertValidTraceOptions(options) {
+  if (options === void 0) return;
+  const subject = options.edgeSubject;
+  if (subject === void 0 || subject === null) return;
+  const reject2 = (reason) => {
+    throw new agents.NatsAgentError(`trace.edgeSubject ${JSON.stringify(subject)}: ${reason}`);
+  };
+  if (typeof subject !== "string") reject2("must be a string or null");
+  if (subject.length === 0) reject2("must not be empty");
+  for (const token of subject.split(".")) {
+    if (token.length === 0) reject2("must not contain an empty token");
+    if (SUBJECT_FORBIDDEN.test(token)) reject2("must not contain whitespace or control characters");
+    if (token.includes("*") || token.includes(">")) reject2("must not contain wildcards");
+  }
+}
+var COUNTERS_KEY = /* @__PURE__ */ Symbol.for("@synadia-ai/agent-fabric:trace-record-counts");
+var counters = (() => {
+  const g = globalThis;
+  return g[COUNTERS_KEY] ??= { published: 0, dropped: 0 };
+})();
+function countTraceRecordPublished() {
+  counters.published += 1;
+}
+function countTraceRecordDropped() {
+  counters.dropped += 1;
+}
+function traceRecordCounts() {
+  return Object.freeze({ published: counters.published, dropped: counters.dropped });
+}
+var STORAGE_KEY = /* @__PURE__ */ Symbol.for("@synadia-ai/agent-fabric:trace-scope");
+var storage = (() => {
+  const g = globalThis;
+  return g[STORAGE_KEY] ??= new node_async_hooks.AsyncLocalStorage();
+})();
+function bindActiveTrace(scope, fn) {
+  return storage.run(scope, fn);
+}
+function activeTrace() {
+  return storage.getStore();
+}
+function traceHeaders() {
+  const scope = activeTrace();
+  if (scope === void 0) return {};
+  scope.turnCountHint += 1;
+  return {
+    [THREAD_ID_HEADER]: scope.threadId,
+    [ROOT_ID_HEADER]: scope.rootId
+  };
+}
+var THREAD_ID_HEX_LEN = 32;
+var THREAD_ID_RE = new RegExp(`^[0-9a-f]{${THREAD_ID_HEX_LEN}}$`);
+function isThreadId(value) {
+  return THREAD_ID_RE.test(value);
+}
+function randomThreadId() {
+  const bytes = new Uint8Array(THREAD_ID_HEX_LEN / 2);
+  crypto.getRandomValues(bytes);
+  let out = "";
+  for (const b of bytes) out += b.toString(16).padStart(2, "0");
+  return out;
+}
+var TOOL_CALL_ID_MAX = 256;
+var LONE_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/;
+function validToolCallId(toolCallId) {
+  if (LONE_SURROGATE.test(toolCallId)) return false;
+  const codePoints = Array.from(toolCallId).length;
+  return codePoints > 0 && codePoints <= TOOL_CALL_ID_MAX;
+}
+function buildEdgeRecord(agent, threadId, parentId, rootId, toolCallId, turnCountHint) {
+  const recordId = randomThreadId();
+  const record2 = {
+    version: EDGE_RECORD_VERSION,
+    kind: "edge",
+    record_id: recordId,
+    ts: Math.floor(Date.now() / 1e3),
+    agent,
+    thread_id: threadId,
+    parent_id: parentId,
+    root_id: rootId,
+    tool_call_id: toolCallId,
+    turn_count_hint: turnCountHint
+  };
+  return { recordId, payload: new TextEncoder().encode(JSON.stringify(record2)) };
+}
+
+// src/tracing.ts
+var TOOL_CALL_ID_CONTEXT_KEY = "toolCallId";
+function fabricTracing(options = {}) {
+  assertValidTraceOptions(options);
+  const edgeSubject = options.edgeSubject === void 0 ? DEFAULT_EDGE_SUBJECT : options.edgeSubject;
+  return {
+    promptInterceptor: promptInterceptor(edgeSubject),
+    requestInterceptor,
+    heartbeatExtras: edgeSubject === null ? () => ({}) : () => {
+      const counts = traceRecordCounts();
+      return { records_published: counts.published, records_dropped: counts.dropped };
+    }
+  };
+}
+function promptInterceptor(edgeSubject) {
+  return {
+    beforePrompt(ctx) {
+      const raw = ctx.context[TOOL_CALL_ID_CONTEXT_KEY];
+      const toolCallId = typeof raw === "string" && validToolCallId(raw) ? raw : null;
+      const plan = { ...mintLineage(), toolCallId };
+      return {
+        fields: { [THREAD_ID_FIELD]: plan.threadId, [ROOT_ID_FIELD]: plan.rootId },
+        state: plan
+      };
+    },
+    async beforePublish(ctx, extras) {
+      const plan = extras?.state;
+      if (edgeSubject === null || plan === void 0) return;
+      await publishEdge(ctx, edgeSubject, plan);
+    }
+  };
+}
+function mintLineage() {
+  const threadId = randomThreadId();
+  const ambient = activeTrace();
+  if (ambient === void 0) {
+    return { threadId, parentId: null, rootId: threadId, turnCountHint: 0 };
+  }
+  return {
+    threadId,
+    parentId: ambient.threadId,
+    rootId: ambient.rootId,
+    turnCountHint: ambient.turnCountHint
+  };
+}
+async function publishEdge(ctx, subject, plan) {
+  if (!ctx.identity.canSign) {
+    warnEdgesUnsigned(ctx.connection);
+    countTraceRecordDropped();
+    return;
+  }
+  try {
+    const agent = await ctx.identity.selfId();
+    const record2 = buildEdgeRecord(
+      agent,
+      plan.threadId,
+      plan.parentId,
+      plan.rootId,
+      plan.toolCallId,
+      plan.turnCountHint
+    );
+    await ctx.identity.publishSigned(subject, record2.payload, { nonce: record2.recordId });
+    countTraceRecordPublished();
+  } catch (err) {
+    countTraceRecordDropped();
+    console.warn(`@synadia-ai/agent-fabric: failed to publish edge record on ${subject}`, err);
+  }
+}
+var warnedUnsigned = /* @__PURE__ */ new WeakSet();
+function warnEdgesUnsigned(nc) {
+  if (warnedUnsigned.has(nc)) return;
+  warnedUnsigned.add(nc);
+  console.warn(
+    "@synadia-ai/agent-fabric: tracing is enabled but no identity signer is configured; edge records are not published (consumers ignore unsigned records). Pass identity: { signer } to sign them."
+  );
+}
+var requestInterceptor = {
+  async aroundRequest(ctx, next) {
+    await bindActiveTrace(scopeFor(ctx.envelope.extras ?? {}), next);
+  }
+};
+var HALF_LINEAGE_PAIR = "envelope `thread_id` and `root_id` must be given together";
+function scopeFor(extras) {
+  const threadId = lineageField(extras, THREAD_ID_FIELD);
+  const rootId = lineageField(extras, ROOT_ID_FIELD);
+  if (threadId === void 0 !== (rootId === void 0)) {
+    throw new agentService.RequestRejectedError(400, HALF_LINEAGE_PAIR);
+  }
+  if (threadId !== void 0 && rootId !== void 0) {
+    return { threadId, rootId, turnCountHint: 0 };
+  }
+  const minted = randomThreadId();
+  return { threadId: minted, rootId: minted, turnCountHint: 0 };
+}
+function lineageField(extras, wireName) {
+  const value = Object.hasOwn(extras, wireName) ? extras[wireName] : void 0;
+  if (value === void 0 || value === null) return void 0;
+  if (typeof value !== "string") {
+    throw new agentService.RequestRejectedError(400, `envelope \`${wireName}\` must be a string`);
+  }
+  if (value === "") return void 0;
+  if (!isThreadId(value)) {
+    throw new agentService.RequestRejectedError(
+      400,
+      `envelope \`${wireName}\` must be ${THREAD_ID_HEX_LEN} lowercase hex characters`
+    );
+  }
+  return value;
+}
+var OUTSIDE_RUN_ID = /[^A-Za-z0-9_-]/gu;
+function durableRunId(toolCallId) {
+  if (!validToolCallId(toolCallId)) {
+    throw new agents.NatsAgentError(
+      `durableRunId: tool call id ${JSON.stringify(toolCallId)} is empty, too long or not valid Unicode`
+    );
+  }
+  const scope = activeTrace();
+  if (scope === void 0) return void 0;
+  return `${scope.threadId}-${toolCallId.replace(OUTSIDE_RUN_ID, "_")}`;
+}
+function durableTrace() {
+  const scope = activeTrace();
+  if (scope === void 0) return void 0;
+  return { thread_id: scope.threadId, root_id: scope.rootId };
+}
+function durableHeaders(trace) {
+  const ids = checked(trace);
+  if (ids === void 0) return {};
+  return { [THREAD_ID_HEADER]: ids.thread_id, [ROOT_ID_HEADER]: ids.root_id };
+}
+function withDurableTrace(trace, turnCount, fn) {
+  if (!Number.isSafeInteger(turnCount) || turnCount < 0) {
+    throw new agents.NatsAgentError(
+      `withDurableTrace: turn count ${String(turnCount)} is not a whole number, 0 or more`
+    );
+  }
+  const ids = checked(trace);
+  if (ids === void 0) return fn();
+  return bindActiveTrace(
+    { threadId: ids.thread_id, rootId: ids.root_id, turnCountHint: turnCount },
+    fn
+  );
+}
+function checked(trace) {
+  if (typeof trace !== "object" || trace === null) return void 0;
+  const { thread_id: threadId, root_id: rootId } = trace;
+  if (typeof threadId !== "string" || typeof rootId !== "string") return void 0;
+  if (!isThreadId(threadId) || !isThreadId(rootId)) return void 0;
+  return { thread_id: threadId, root_id: rootId };
+}
+var SERVED_RECORD_VERSION = 1;
+var SERVED_RECORD_REASON_VERSION = 2;
+var HARNESSES = /* @__PURE__ */ new Set(["claude", "openclaw"]);
+var PHASES = /* @__PURE__ */ new Set(["start", "end"]);
+var STATUSES = /* @__PURE__ */ new Set(["ok", "error", "timeout"]);
+var REASONS = /* @__PURE__ */ new Set([
+  "final_text",
+  "no_reply",
+  "shutdown",
+  "delivery",
+  "expired"
+]);
+var HARNESS_THREAD_ID_MAX = 256;
+function validHarnessThreadId(value) {
+  if (typeof value !== "string" || value.length === 0) return false;
+  if (SUBJECT_FORBIDDEN.test(value)) return false;
+  if (LONE_SURROGATE.test(value)) return false;
+  return Array.from(value).length <= HARNESS_THREAD_ID_MAX;
+}
+function unixSeconds() {
+  return Math.floor(Date.now() / 1e3);
+}
+function buildServedRecord(agent, threadId, rootId, harness, harnessThreadId, phase, status, ts = unixSeconds(), reason) {
+  if (!HARNESSES.has(harness)) {
+    throw new Error(`buildServedRecord: harness must be "claude" or "openclaw", got ${harness}`);
+  }
+  if (!PHASES.has(phase)) {
+    throw new Error(`buildServedRecord: phase must be "start" or "end", got ${phase}`);
+  }
+  if (phase === "end" && status === void 0) {
+    throw new Error("buildServedRecord: an end record needs a status");
+  }
+  if (phase === "start" && status !== void 0) {
+    throw new Error("buildServedRecord: a start record carries no status");
+  }
+  if (status !== void 0 && !STATUSES.has(status)) {
+    throw new Error(`buildServedRecord: status must be "ok", "error" or "timeout", got ${status}`);
+  }
+  if (phase === "start" && reason !== void 0) {
+    throw new Error("buildServedRecord: a start record carries no reason");
+  }
+  if (reason !== void 0 && !REASONS.has(reason)) {
+    throw new Error(
+      `buildServedRecord: reason must be "final_text", "no_reply", "shutdown", "delivery" or "expired", got ${reason}`
+    );
+  }
+  if (!validHarnessThreadId(harnessThreadId)) {
+    throw new Error("buildServedRecord: harnessThreadId is not a usable harness thread id");
+  }
+  if (!Number.isInteger(ts) || ts < 0) {
+    throw new Error("buildServedRecord: ts must be a non-negative integer of unix seconds");
+  }
+  const recordId = randomThreadId();
+  const record2 = {
+    version: reason !== void 0 ? SERVED_RECORD_REASON_VERSION : SERVED_RECORD_VERSION,
+    kind: "served",
+    record_id: recordId,
+    ts,
+    agent,
+    thread_id: threadId,
+    root_id: rootId,
+    harness,
+    harness_thread_id: harnessThreadId,
+    phase,
+    ...status !== void 0 ? { status } : {},
+    ...reason !== void 0 ? { reason } : {}
+  };
+  return { recordId, payload: new TextEncoder().encode(JSON.stringify(record2)) };
+}
+var defaultLogger = () => ({
+  debug: () => void 0,
+  info: () => void 0,
+  warn: (msg, ctx) => console.warn(`@synadia-ai/agent-fabric: ${msg}`, ctx ?? ""),
+  error: (msg, ctx) => console.error(`@synadia-ai/agent-fabric: ${msg}`, ctx ?? "")
+});
+var ServedPublisher = class {
+  #agents;
+  #subject;
+  #logger;
+  #unsignedWarned = false;
+  // Records are built, signed and handed to the connection one after
+  // another, in the order they were due. A failed record never rejects the
+  // chain: `#send` catches everything.
+  #chain = Promise.resolve();
+  constructor(options) {
+    this.#agents = options.agents;
+    this.#subject = options.subject ?? DEFAULT_EDGE_SUBJECT;
+    this.#logger = options.logger ?? defaultLogger();
+  }
+  /** Where the records go. */
+  get subject() {
+    return this.#subject;
+  }
+  /**
+   * Start a prompt's pair: `scope` is the served prompt's trace scope —
+   * the one the fabric's request interceptor bound around the handler,
+   * `activeTrace()` inside it — and `harness` the one whose id `bind` will
+   * name. The arrival, `start`'s `ts`, is now.
+   */
+  beginTurn(scope, harness) {
+    const arrivedAt = unixSeconds();
+    let harnessThreadId;
+    let settled = false;
+    return {
+      bind: (id) => {
+        if (settled) {
+          this.#logger.warn(
+            "served: harness thread id bound after the turn ended; no served record"
+          );
+          return;
+        }
+        if (harnessThreadId !== void 0) {
+          if (id !== harnessThreadId) {
+            this.#logger.warn("served: harness thread id already bound for this prompt; ignored");
+          }
+          return;
+        }
+        if (!validHarnessThreadId(id)) {
+          this.#logger.warn("served: unusable harness thread id bound; no served record");
+          return;
+        }
+        harnessThreadId = id;
+        void this.publish(scope, harness, id, "start", void 0, arrivedAt);
+      },
+      settle: (status, atMs, reason) => {
+        if (settled) return;
+        settled = true;
+        if (harnessThreadId === void 0) return;
+        const ts = atMs === void 0 ? unixSeconds() : Math.floor(atMs / 1e3);
+        void this.publish(scope, harness, harnessThreadId, "end", status, ts, reason);
+      }
+    };
+  }
+  /**
+   * Publish one signed record, after every record handed over before it.
+   * Fail-open and asynchronous: the returned promise never rejects and
+   * nothing awaits it on the prompt path. A record that cannot go out — no
+   * signer, a client already closed, a publish that threw — is logged and
+   * counts as dropped; one that went out counts as published. Every record
+   * moves the process-wide {@link traceRecordCounts}.
+   */
+  publish(scope, harness, harnessThreadId, phase, status, ts, reason) {
+    const next = this.#chain.then(
+      () => this.#send(scope, harness, harnessThreadId, phase, status, ts, reason)
+    );
+    this.#chain = next;
+    return next;
+  }
+  /**
+   * Resolves once every record handed to `publish` so far has been signed
+   * and handed to the connection, or dropped. For shutdown and tests.
+   */
+  flush() {
+    return this.#chain;
+  }
+  async #send(scope, harness, harnessThreadId, phase, status, ts, reason) {
+    try {
+      const agent = await this.#agents.selfId();
+      const record2 = buildServedRecord(
+        agent,
+        scope.threadId,
+        scope.rootId,
+        harness,
+        harnessThreadId,
+        phase,
+        status,
+        ts,
+        reason
+      );
+      await this.#agents.publishSigned(this.#subject, record2.payload, { nonce: record2.recordId });
+      countTraceRecordPublished();
+    } catch (err) {
+      countTraceRecordDropped();
+      if (isSignatureRequired(err)) {
+        if (this.#unsignedWarned) return;
+        this.#unsignedWarned = true;
+        this.#logger.warn(
+          "served: no identity signer is configured; served records are not published (consumers ignore unsigned records). Pass identity: { signer } to sign them."
+        );
+        return;
+      }
+      this.#logger.warn("served: failed to publish served record", {
+        subject: this.#subject,
+        phase,
+        reason: err instanceof Error ? err.message : String(err)
+      });
+    }
+  }
+};
+function isSignatureRequired(err) {
+  return err instanceof agents.SenderSignatureRequiredError || err instanceof Error && err.name === "SenderSignatureRequiredError";
+}
+function servedPublisher(options) {
+  return new ServedPublisher(options);
+}
+
+// src/scratchpad.ts
+var REFERENCE_PREFIX = "sp-ref:";
+var SHORT_REFERENCE_PREFIX = "sp-r1:";
+var REFERENCE_RE = /sp-(?:ref|r1):[A-Za-z0-9_-]+/g;
+var READS_REFERENCES_KEY = "scratchpad_refs_ok";
+function findReferences(text2) {
+  return text2.match(REFERENCE_RE) ?? [];
+}
+function removeReferences(text2, only) {
+  return text2.replace(REFERENCE_RE, (token) => only === void 0 || only.includes(token) ? "" : token).replace(/[ \t]+$/gm, "").replace(/\n{3,}/g, "\n\n").trim();
+}
+function referenceCreator(reference) {
+  if (!reference.startsWith(REFERENCE_PREFIX)) return void 0;
+  let made;
+  try {
+    made = JSON.parse(
+      Buffer.from(reference.slice(REFERENCE_PREFIX.length), "base64url").toString("utf8")
+    );
+  } catch {
+    return void 0;
+  }
+  if (typeof made !== "object" || made === null) return void 0;
+  const creator = made["creator"];
+  return typeof creator === "string" && creator !== "" ? creator : void 0;
+}
+function readsReferences(metadata) {
+  return metadata[READS_REFERENCES_KEY] === "true";
+}
+function granteeFromIdentity(identity) {
+  const dot = identity.indexOf(".");
+  if (dot <= 0 || dot === identity.length - 1) {
+    throw new Error(`not an agent identity: ${identity}`);
+  }
+  return { account: identity.slice(0, dot), user: identity.slice(dot + 1) };
+}
+var GRANT_REQUEST_ENDPOINT = "sp-grant";
+var DEFAULT_GRANT_REQUEST_TIMEOUT_MS = 1e4;
+var PROMPT_PREFIX = "agents.prompt.";
+var GRANT_PREFIX = `agents.${GRANT_REQUEST_ENDPOINT}.`;
+function grantSubject(promptAddress) {
+  if (!promptAddress.startsWith(PROMPT_PREFIX) || promptAddress === PROMPT_PREFIX) {
+    throw new Error(`not a prompt address: ${promptAddress}`);
+  }
+  return GRANT_PREFIX + promptAddress.slice(PROMPT_PREFIX.length);
+}
+function encodeGrantRequest(request) {
+  const { trace } = request;
+  return JSON.stringify({
+    reference: request.reference,
+    grantee: request.grantee,
+    ...trace !== void 0 ? {
+      trace: {
+        thread_id: trace.thread_id,
+        root_id: trace.root_id,
+        ...trace.tool_call_id !== void 0 ? { tool_call_id: trace.tool_call_id } : {}
+      }
+    } : {}
+  });
+}
+function encodeGrantReply(reply) {
+  return JSON.stringify(
+    reply.granted ? { granted: true } : { granted: false, reason: reply.reason }
+  );
+}
+async function requestGrant(agents, creatorAddress, request, options = {}) {
+  let answer;
+  try {
+    const msg = await agents.requestSigned(
+      grantSubject(creatorAddress),
+      encodeGrantRequest(request),
+      { timeoutMs: options.timeoutMs ?? DEFAULT_GRANT_REQUEST_TIMEOUT_MS }
+    );
+    answer = JSON.parse(msg.string());
+  } catch (err) {
+    return refusal(`no answer from ${creatorAddress}: ${describe(err)}`);
+  }
+  if (typeof answer !== "object" || answer === null) {
+    return refusal("refused without a reason");
+  }
+  const { granted, reason } = answer;
+  if (granted === true) return { granted: true };
+  return refusal(typeof reason === "string" ? reason : "refused without a reason");
+}
+async function answerGrantRequest(requester, payload, scratchPad, logger = agents.SILENT_LOGGER) {
+  const request = parseGrantRequest(payload);
+  if (request === void 0) return refusal("not a grant request");
+  let from;
+  let to;
+  try {
+    from = granteeFromIdentity(requester);
+    to = granteeFromIdentity(request.grantee);
+  } catch {
+    return refusal("grantee is not an agent identity");
+  }
+  const labels = request.trace;
+  const trace = labels !== void 0 ? { threadId: labels.thread_id, rootId: labels.root_id } : void 0;
+  let own = false;
+  try {
+    own = await scratchPad.owns(request.reference);
+  } catch {
+  }
+  if (!own) return refusal("the reference does not point into this agent's volume");
+  let held;
+  try {
+    held = await scratchPad.granted(request.reference, from);
+  } catch (err) {
+    logger.error("grant request: the ledger could not be read", { error: describe(err) });
+    return refusal("the grant could not be made");
+  }
+  if (held === void 0) {
+    return refusal(
+      "this agent holds no live read grant it made to the requester on that reference"
+    );
+  }
+  if (held !== "first-hand") {
+    return refusal(
+      "the requester's own grant was made at another agent's request; only an agent this agent handed the reference itself may ask for another"
+    );
+  }
+  if (to.account === from.account && to.user === from.user) {
+    return refusal("a grant request is for another agent, not for the requester");
+  }
+  try {
+    await scratchPad.grantRead(request.reference, to, trace, labels?.tool_call_id, "on-request");
+  } catch (err) {
+    logger.error("grant request: the grant failed", { error: describe(err) });
+    return refusal("the grant could not be made");
+  }
+  logger.info("grant request: granted", { grantee: request.grantee, requester });
+  return { granted: true };
+}
+function grantRequestEndpoint(options) {
+  const { scratchPad } = options;
+  const logger = options.logger ?? agents.SILENT_LOGGER;
+  const gate = new agentService.SenderGate({ minSenderTrust: "signed", logger });
+  async function decide(msg) {
+    const admission = await gate.admitPrompt(msg);
+    if (!admission.ok) return refusal(admission.description);
+    const sender = admission.sender;
+    if (sender?.trust !== "verified") return refusal("a grant request must be signed");
+    return answerGrantRequest(sender.id, msg.string(), scratchPad, logger);
+  }
+  return {
+    name: GRANT_REQUEST_ENDPOINT,
+    subject: grantSubject(options.promptAddress),
+    queue: "agents",
+    handler: (err, msg) => {
+      if (err) return;
+      void decide(msg).catch((e) => {
+        logger.error("grant request failed", { error: describe(e) });
+        return refusal("the grant could not be made");
+      }).then((reply) => {
+        if (!reply.granted) logger.info("grant request refused", { reason: reply.reason });
+        msg.respond(encodeGrantReply(reply));
+      });
+    }
+  };
+}
+function parseGrantRequest(text2) {
+  let value;
+  try {
+    value = JSON.parse(text2);
+  } catch {
+    return void 0;
+  }
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return void 0;
+  const { reference, grantee, trace } = value;
+  if (typeof reference !== "string" || typeof grantee !== "string") return void 0;
+  if (typeof trace !== "object" || trace === null) return { reference, grantee };
+  const { thread_id, root_id, tool_call_id } = trace;
+  if (typeof thread_id !== "string" || typeof root_id !== "string" || !isThreadId(thread_id) || !isThreadId(root_id)) {
+    return { reference, grantee };
+  }
+  return {
+    reference,
+    grantee,
+    trace: {
+      thread_id,
+      root_id,
+      ...typeof tool_call_id === "string" && validToolCallId(tool_call_id) ? { tool_call_id } : {}
+    }
+  };
+}
+function refusal(reason) {
+  return { granted: false, reason };
+}
+function describe(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+
+// src/scratchpad-extension.ts
+var READS_SCRATCHPAD_REFERENCES_FIELD = "reads_scratchpad_references";
+var ScratchPadExtension = class {
+  /**
+   * For the agent's `AgentService` (`interceptors: [...]`): remembers the
+   * references in every prompt it serves.
+   */
+  requestInterceptor;
+  #scratchPad;
+  #agents;
+  #discoverTimeoutMs;
+  #grantRequestTimeoutMs;
+  // Every reference this agent was given, exactly as it came.
+  #given = /* @__PURE__ */ new Set();
+  // Live handles by address, from discovery: a creator is asked only when
+  // it is on the fabric with a verified identity.
+  #known = /* @__PURE__ */ new Map();
+  constructor(options) {
+    this.#scratchPad = options.scratchPad;
+    this.#agents = options.agents;
+    this.#discoverTimeoutMs = options.discoverTimeoutMs;
+    this.#grantRequestTimeoutMs = options.grantRequestTimeoutMs;
+    this.requestInterceptor = {
+      aroundRequest: (ctx, next) => {
+        this.remember(ctx.envelope.prompt);
+        return next();
+      }
+    };
+  }
+  /**
+   * Note the references in `text` as given to this agent: what it
+   * committed, or received some way the hooks do not see.
+   */
+  remember(text2) {
+    for (const reference of findReferences(text2)) this.#given.add(reference);
+  }
+  /**
+   * The reply side: before a reply carrying `reference`, this agent's own,
+   * goes out, remember it and grant the served prompt's sender read on it,
+   * first-hand — only a sender whose signature verified, since a grant
+   * names a principal and an unsigned claim proves none. `true` when
+   * granted, so the reference may go into the reply; `false` for a sender
+   * that did not verify. Throws when the reference is not this agent's own
+   * or the grant fails. The commit itself stays the agent's.
+   */
+  async grantCaller(reference, sender) {
+    this.remember(reference);
+    if (sender?.trust !== "verified") return false;
+    if (!await this.#scratchPad.owns(reference)) {
+      throw new Error("the reference points into another agent's volume; only its creator grants");
+    }
+    await this.#scratchPad.grantRead(
+      reference,
+      granteeFromIdentity(sender.id),
+      servedTrace(),
+      void 0,
+      "first-hand"
+    );
+    return true;
+  }
+  /** The discovery fields hook. */
+  discoveryFields(agent) {
+    this.#note(agent);
+    return { [READS_SCRATCHPAD_REFERENCES_FIELD]: readsReferences(agent.metadata) };
+  }
+  /** The prompt rewrite hook. */
+  async beforePrompt(ctx) {
+    const { address, target } = ctx;
+    const found = findReferences(ctx.prompt);
+    if (found.length === 0) return;
+    if (!readsReferences(target.metadata)) {
+      const prompt2 = removeReferences(ctx.prompt);
+      if (prompt2 === "") {
+        return {
+          error: `the prompt was not sent: "${address}" does not read ScratchPad references (discover_agents: reads_scratchpad_references is false), and the prompt held nothing but references; put the content they point at into the prompt itself`
+        };
+      }
+      return {
+        prompt: prompt2,
+        fields: {
+          references_removed: found.length,
+          note: `"${address}" does not read ScratchPad references: ${found.length} reference(s) were removed from your prompt, it got only the text, and nothing was granted`
+        }
+      };
+    }
+    const references = [...new Set(found)];
+    const unknown2 = references.filter((reference) => !this.#given.has(reference));
+    if (unknown2.length > 0) {
+      return {
+        error: `the prompt was not sent: ${unknown2.length} of its ScratchPad references (${unknown2[0].slice(0, 24)}\u2026) is not one you were given. Copy each reference exactly as you received it, the whole token, or leave it out.`
+      };
+    }
+    if (target.identity === void 0 || !target.idSigVerified) {
+      return {
+        error: `cannot hand a ScratchPad reference to "${address}": its identity is not verified, so no read grant can be issued; put the content in the prompt instead`
+      };
+    }
+    const grantee = granteeFromIdentity(target.identity);
+    const trace = servedTrace();
+    const toolCallId = ctx.toolCallId !== void 0 && validToolCallId(ctx.toolCallId) ? ctx.toolCallId : void 0;
+    const refused = [];
+    let reason = "";
+    for (const reference of references) {
+      try {
+        if (await this.#scratchPad.owns(reference)) {
+          await this.#scratchPad.grantRead(reference, grantee, trace, toolCallId, "first-hand");
+          continue;
+        }
+      } catch (err) {
+        return {
+          error: `could not grant "${address}" read on ${reference.slice(0, 32)}\u2026: ${describe2(err)}; the prompt was not sent`
+        };
+      }
+      const answer = await this.#askCreator(reference, address, target.identity, trace, toolCallId);
+      if (!answer.granted) {
+        refused.push(reference);
+        reason = answer.reason;
+      }
+    }
+    if (refused.length === 0) return;
+    const removed = found.filter((reference) => refused.includes(reference)).length;
+    const prompt = removeReferences(ctx.prompt, refused);
+    if (prompt === "") {
+      return {
+        error: `the prompt was not sent: it held nothing but references, and their creator did not grant "${address}" read (${reason}); put the content they point at into the prompt itself`
+      };
+    }
+    return {
+      prompt,
+      fields: {
+        references_removed: removed,
+        note: `${removed} reference(s) were removed from your prompt, and "${address}" got only the text: you did not create that content, and its creator did not grant "${address}" read (${reason}). If it needs the content, put the content itself in a prompt`
+      }
+    };
+  }
+  /** The reply look hook. */
+  afterReply(ctx) {
+    this.remember(ctx.text);
+  }
+  // Ask the creator of a reference this agent was handed to grant the
+  // target read on it. The creator is the address the token names, and it
+  // must be on the fabric with a verified identity: a request to anyone
+  // else could not be answered with a grant anyway. A target that is the
+  // creator reads its own volume and needs no grant.
+  async #askCreator(reference, targetAddress, targetIdentity, trace, toolCallId) {
+    let address = referenceCreator(reference);
+    if (address === void 0 && this.#scratchPad.resolveReference) {
+      try {
+        address = (await this.#scratchPad.resolveReference(reference, trace)).creator;
+      } catch {
+        return { granted: false, reason: "the reference could not be resolved" };
+      }
+    }
+    if (address === void 0) {
+      return { granted: false, reason: "the reference does not name its creator" };
+    }
+    if (address === targetAddress) return { granted: true };
+    const creator = await this.#lookup(address);
+    if (creator === void 0 || !creator.idSigVerified) {
+      return {
+        granted: false,
+        reason: `its creator, ${address}, is not on the fabric with a verified identity`
+      };
+    }
+    const request = {
+      reference,
+      grantee: targetIdentity,
+      ...trace !== void 0 ? {
+        trace: {
+          thread_id: trace.threadId,
+          root_id: trace.rootId,
+          ...toolCallId !== void 0 ? { tool_call_id: toolCallId } : {}
+        }
+      } : {}
+    };
+    return requestGrant(
+      this.#agents,
+      address,
+      request,
+      this.#grantRequestTimeoutMs !== void 0 ? { timeoutMs: this.#grantRequestTimeoutMs } : {}
+    );
+  }
+  // The handle for an address: from discovery so far, else from a fresh one.
+  async #lookup(address) {
+    const known = this.#known.get(address);
+    if (known !== void 0) return known;
+    try {
+      const found = await this.#agents.discover(
+        this.#discoverTimeoutMs !== void 0 ? { timeoutMs: this.#discoverTimeoutMs } : {}
+      );
+      for (const handle of found) this.#note(handle);
+    } catch {
+    }
+    return this.#known.get(address);
+  }
+  // Remember a handle, preferring one whose identity verifies.
+  #note(handle) {
+    const known = this.#known.get(handle.promptSubject);
+    if (known === void 0 || handle.idSigVerified || !known.idSigVerified) {
+      this.#known.set(handle.promptSubject, handle);
+    }
+  }
+};
+function scratchPadExtension(options) {
+  return new ScratchPadExtension(options);
+}
+function servedTrace() {
+  const scope = activeTrace();
+  return scope !== void 0 ? { threadId: scope.threadId, rootId: scope.rootId } : void 0;
+}
+function describe2(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+
+// src/scratchpad-native/errors.ts
+var NativeScratchPadError = class extends Error {
+  code;
+  unknown;
+  local;
+  constructor(code, message, options = {}) {
+    super(message, options.cause === void 0 ? void 0 : { cause: options.cause });
+    this.name = "NativeScratchPadError";
+    this.code = code;
+    this.unknown = options.unknown ?? false;
+    this.local = options.local ?? false;
+  }
+};
+function invalid(message, cause) {
+  return new NativeScratchPadError("invalid", message, { local: true, cause });
+}
+function failed(mutation, message, cause) {
+  return new NativeScratchPadError(mutation ? "unknown" : "corrupt", message, {
+    unknown: mutation,
+    cause
+  });
+}
+
+// node_modules/@unicode/unicode-15.0.0/General_Category/Unassigned/regex.mjs
+var regex_default = /[\u0378\u0379\u0380-\u0383\u038B\u038D\u03A2\u0530\u0557\u0558\u058B\u058C\u0590\u05C8-\u05CF\u05EB-\u05EE\u05F5-\u05FF\u070E\u074B\u074C\u07B2-\u07BF\u07FB\u07FC\u082E\u082F\u083F\u085C\u085D\u085F\u086B-\u086F\u088F\u0892-\u0897\u0984\u098D\u098E\u0991\u0992\u09A9\u09B1\u09B3-\u09B5\u09BA\u09BB\u09C5\u09C6\u09C9\u09CA\u09CF-\u09D6\u09D8-\u09DB\u09DE\u09E4\u09E5\u09FF\u0A00\u0A04\u0A0B-\u0A0E\u0A11\u0A12\u0A29\u0A31\u0A34\u0A37\u0A3A\u0A3B\u0A3D\u0A43-\u0A46\u0A49\u0A4A\u0A4E-\u0A50\u0A52-\u0A58\u0A5D\u0A5F-\u0A65\u0A77-\u0A80\u0A84\u0A8E\u0A92\u0AA9\u0AB1\u0AB4\u0ABA\u0ABB\u0AC6\u0ACA\u0ACE\u0ACF\u0AD1-\u0ADF\u0AE4\u0AE5\u0AF2-\u0AF8\u0B00\u0B04\u0B0D\u0B0E\u0B11\u0B12\u0B29\u0B31\u0B34\u0B3A\u0B3B\u0B45\u0B46\u0B49\u0B4A\u0B4E-\u0B54\u0B58-\u0B5B\u0B5E\u0B64\u0B65\u0B78-\u0B81\u0B84\u0B8B-\u0B8D\u0B91\u0B96-\u0B98\u0B9B\u0B9D\u0BA0-\u0BA2\u0BA5-\u0BA7\u0BAB-\u0BAD\u0BBA-\u0BBD\u0BC3-\u0BC5\u0BC9\u0BCE\u0BCF\u0BD1-\u0BD6\u0BD8-\u0BE5\u0BFB-\u0BFF\u0C0D\u0C11\u0C29\u0C3A\u0C3B\u0C45\u0C49\u0C4E-\u0C54\u0C57\u0C5B\u0C5C\u0C5E\u0C5F\u0C64\u0C65\u0C70-\u0C76\u0C8D\u0C91\u0CA9\u0CB4\u0CBA\u0CBB\u0CC5\u0CC9\u0CCE-\u0CD4\u0CD7-\u0CDC\u0CDF\u0CE4\u0CE5\u0CF0\u0CF4-\u0CFF\u0D0D\u0D11\u0D45\u0D49\u0D50-\u0D53\u0D64\u0D65\u0D80\u0D84\u0D97-\u0D99\u0DB2\u0DBC\u0DBE\u0DBF\u0DC7-\u0DC9\u0DCB-\u0DCE\u0DD5\u0DD7\u0DE0-\u0DE5\u0DF0\u0DF1\u0DF5-\u0E00\u0E3B-\u0E3E\u0E5C-\u0E80\u0E83\u0E85\u0E8B\u0EA4\u0EA6\u0EBE\u0EBF\u0EC5\u0EC7\u0ECF\u0EDA\u0EDB\u0EE0-\u0EFF\u0F48\u0F6D-\u0F70\u0F98\u0FBD\u0FCD\u0FDB-\u0FFF\u10C6\u10C8-\u10CC\u10CE\u10CF\u1249\u124E\u124F\u1257\u1259\u125E\u125F\u1289\u128E\u128F\u12B1\u12B6\u12B7\u12BF\u12C1\u12C6\u12C7\u12D7\u1311\u1316\u1317\u135B\u135C\u137D-\u137F\u139A-\u139F\u13F6\u13F7\u13FE\u13FF\u169D-\u169F\u16F9-\u16FF\u1716-\u171E\u1737-\u173F\u1754-\u175F\u176D\u1771\u1774-\u177F\u17DE\u17DF\u17EA-\u17EF\u17FA-\u17FF\u181A-\u181F\u1879-\u187F\u18AB-\u18AF\u18F6-\u18FF\u191F\u192C-\u192F\u193C-\u193F\u1941-\u1943\u196E\u196F\u1975-\u197F\u19AC-\u19AF\u19CA-\u19CF\u19DB-\u19DD\u1A1C\u1A1D\u1A5F\u1A7D\u1A7E\u1A8A-\u1A8F\u1A9A-\u1A9F\u1AAE\u1AAF\u1ACF-\u1AFF\u1B4D-\u1B4F\u1B7F\u1BF4-\u1BFB\u1C38-\u1C3A\u1C4A-\u1C4C\u1C89-\u1C8F\u1CBB\u1CBC\u1CC8-\u1CCF\u1CFB-\u1CFF\u1F16\u1F17\u1F1E\u1F1F\u1F46\u1F47\u1F4E\u1F4F\u1F58\u1F5A\u1F5C\u1F5E\u1F7E\u1F7F\u1FB5\u1FC5\u1FD4\u1FD5\u1FDC\u1FF0\u1FF1\u1FF5\u1FFF\u2065\u2072\u2073\u208F\u209D-\u209F\u20C1-\u20CF\u20F1-\u20FF\u218C-\u218F\u2427-\u243F\u244B-\u245F\u2B74\u2B75\u2B96\u2CF4-\u2CF8\u2D26\u2D28-\u2D2C\u2D2E\u2D2F\u2D68-\u2D6E\u2D71-\u2D7E\u2D97-\u2D9F\u2DA7\u2DAF\u2DB7\u2DBF\u2DC7\u2DCF\u2DD7\u2DDF\u2E5E-\u2E7F\u2E9A\u2EF4-\u2EFF\u2FD6-\u2FEF\u2FFC-\u2FFF\u3040\u3097\u3098\u3100-\u3104\u3130\u318F\u31E4-\u31EF\u321F\uA48D-\uA48F\uA4C7-\uA4CF\uA62C-\uA63F\uA6F8-\uA6FF\uA7CB-\uA7CF\uA7D2\uA7D4\uA7DA-\uA7F1\uA82D-\uA82F\uA83A-\uA83F\uA878-\uA87F\uA8C6-\uA8CD\uA8DA-\uA8DF\uA954-\uA95E\uA97D-\uA97F\uA9CE\uA9DA-\uA9DD\uA9FF\uAA37-\uAA3F\uAA4E\uAA4F\uAA5A\uAA5B\uAAC3-\uAADA\uAAF7-\uAB00\uAB07\uAB08\uAB0F\uAB10\uAB17-\uAB1F\uAB27\uAB2F\uAB6C-\uAB6F\uABEE\uABEF\uABFA-\uABFF\uD7A4-\uD7AF\uD7C7-\uD7CA\uD7FC-\uD7FF\uFA6E\uFA6F\uFADA-\uFAFF\uFB07-\uFB12\uFB18-\uFB1C\uFB37\uFB3D\uFB3F\uFB42\uFB45\uFBC3-\uFBD2\uFD90\uFD91\uFDC8-\uFDCE\uFDD0-\uFDEF\uFE1A-\uFE1F\uFE53\uFE67\uFE6C-\uFE6F\uFE75\uFEFD\uFEFE\uFF00\uFFBF-\uFFC1\uFFC8\uFFC9\uFFD0\uFFD1\uFFD8\uFFD9\uFFDD-\uFFDF\uFFE7\uFFEF-\uFFF8\uFFFE\uFFFF]|\uD800[\uDC0C\uDC27\uDC3B\uDC3E\uDC4E\uDC4F\uDC5E-\uDC7F\uDCFB-\uDCFF\uDD03-\uDD06\uDD34-\uDD36\uDD8F\uDD9D-\uDD9F\uDDA1-\uDDCF\uDDFE-\uDE7F\uDE9D-\uDE9F\uDED1-\uDEDF\uDEFC-\uDEFF\uDF24-\uDF2C\uDF4B-\uDF4F\uDF7B-\uDF7F\uDF9E\uDFC4-\uDFC7\uDFD6-\uDFFF]|\uD801[\uDC9E\uDC9F\uDCAA-\uDCAF\uDCD4-\uDCD7\uDCFC-\uDCFF\uDD28-\uDD2F\uDD64-\uDD6E\uDD7B\uDD8B\uDD93\uDD96\uDDA2\uDDB2\uDDBA\uDDBD-\uDDFF\uDF37-\uDF3F\uDF56-\uDF5F\uDF68-\uDF7F\uDF86\uDFB1\uDFBB-\uDFFF]|\uD802[\uDC06\uDC07\uDC09\uDC36\uDC39-\uDC3B\uDC3D\uDC3E\uDC56\uDC9F-\uDCA6\uDCB0-\uDCDF\uDCF3\uDCF6-\uDCFA\uDD1C-\uDD1E\uDD3A-\uDD3E\uDD40-\uDD7F\uDDB8-\uDDBB\uDDD0\uDDD1\uDE04\uDE07-\uDE0B\uDE14\uDE18\uDE36\uDE37\uDE3B-\uDE3E\uDE49-\uDE4F\uDE59-\uDE5F\uDEA0-\uDEBF\uDEE7-\uDEEA\uDEF7-\uDEFF\uDF36-\uDF38\uDF56\uDF57\uDF73-\uDF77\uDF92-\uDF98\uDF9D-\uDFA8\uDFB0-\uDFFF]|\uD803[\uDC49-\uDC7F\uDCB3-\uDCBF\uDCF3-\uDCF9\uDD28-\uDD2F\uDD3A-\uDE5F\uDE7F\uDEAA\uDEAE\uDEAF\uDEB2-\uDEFC\uDF28-\uDF2F\uDF5A-\uDF6F\uDF8A-\uDFAF\uDFCC-\uDFDF\uDFF7-\uDFFF]|\uD804[\uDC4E-\uDC51\uDC76-\uDC7E\uDCC3-\uDCCC\uDCCE\uDCCF\uDCE9-\uDCEF\uDCFA-\uDCFF\uDD35\uDD48-\uDD4F\uDD77-\uDD7F\uDDE0\uDDF5-\uDDFF\uDE12\uDE42-\uDE7F\uDE87\uDE89\uDE8E\uDE9E\uDEAA-\uDEAF\uDEEB-\uDEEF\uDEFA-\uDEFF\uDF04\uDF0D\uDF0E\uDF11\uDF12\uDF29\uDF31\uDF34\uDF3A\uDF45\uDF46\uDF49\uDF4A\uDF4E\uDF4F\uDF51-\uDF56\uDF58-\uDF5C\uDF64\uDF65\uDF6D-\uDF6F\uDF75-\uDFFF]|\uD805[\uDC5C\uDC62-\uDC7F\uDCC8-\uDCCF\uDCDA-\uDD7F\uDDB6\uDDB7\uDDDE-\uDDFF\uDE45-\uDE4F\uDE5A-\uDE5F\uDE6D-\uDE7F\uDEBA-\uDEBF\uDECA-\uDEFF\uDF1B\uDF1C\uDF2C-\uDF2F\uDF47-\uDFFF]|\uD806[\uDC3C-\uDC9F\uDCF3-\uDCFE\uDD07\uDD08\uDD0A\uDD0B\uDD14\uDD17\uDD36\uDD39\uDD3A\uDD47-\uDD4F\uDD5A-\uDD9F\uDDA8\uDDA9\uDDD8\uDDD9\uDDE5-\uDDFF\uDE48-\uDE4F\uDEA3-\uDEAF\uDEF9-\uDEFF\uDF0A-\uDFFF]|\uD807[\uDC09\uDC37\uDC46-\uDC4F\uDC6D-\uDC6F\uDC90\uDC91\uDCA8\uDCB7-\uDCFF\uDD07\uDD0A\uDD37-\uDD39\uDD3B\uDD3E\uDD48-\uDD4F\uDD5A-\uDD5F\uDD66\uDD69\uDD8F\uDD92\uDD99-\uDD9F\uDDAA-\uDEDF\uDEF9-\uDEFF\uDF11\uDF3B-\uDF3D\uDF5A-\uDFAF\uDFB1-\uDFBF\uDFF2-\uDFFE]|\uD808[\uDF9A-\uDFFF]|\uD809[\uDC6F\uDC75-\uDC7F\uDD44-\uDFFF]|[\uD80A\uD80E-\uD810\uD812-\uD819\uD824-\uD82A\uD82D\uD82E\uD830-\uD832\uD83F\uD87B-\uD87D\uD87F\uD889-\uDB3F\uDB41-\uDB7F][\uDC00-\uDFFF]|\uD80B[\uDC00-\uDF8F\uDFF3-\uDFFF]|\uD80D[\uDC56-\uDFFF]|\uD811[\uDE47-\uDFFF]|\uD81A[\uDE39-\uDE3F\uDE5F\uDE6A-\uDE6D\uDEBF\uDECA-\uDECF\uDEEE\uDEEF\uDEF6-\uDEFF\uDF46-\uDF4F\uDF5A\uDF62\uDF78-\uDF7C\uDF90-\uDFFF]|\uD81B[\uDC00-\uDE3F\uDE9B-\uDEFF\uDF4B-\uDF4E\uDF88-\uDF8E\uDFA0-\uDFDF\uDFE5-\uDFEF\uDFF2-\uDFFF]|\uD821[\uDFF8-\uDFFF]|\uD823[\uDCD6-\uDCFF\uDD09-\uDFFF]|\uD82B[\uDC00-\uDFEF\uDFF4\uDFFC\uDFFF]|\uD82C[\uDD23-\uDD31\uDD33-\uDD4F\uDD53\uDD54\uDD56-\uDD63\uDD68-\uDD6F\uDEFC-\uDFFF]|\uD82F[\uDC6B-\uDC6F\uDC7D-\uDC7F\uDC89-\uDC8F\uDC9A\uDC9B\uDCA4-\uDFFF]|\uD833[\uDC00-\uDEFF\uDF2E\uDF2F\uDF47-\uDF4F\uDFC4-\uDFFF]|\uD834[\uDCF6-\uDCFF\uDD27\uDD28\uDDEB-\uDDFF\uDE46-\uDEBF\uDED4-\uDEDF\uDEF4-\uDEFF\uDF57-\uDF5F\uDF79-\uDFFF]|\uD835[\uDC55\uDC9D\uDCA0\uDCA1\uDCA3\uDCA4\uDCA7\uDCA8\uDCAD\uDCBA\uDCBC\uDCC4\uDD06\uDD0B\uDD0C\uDD15\uDD1D\uDD3A\uDD3F\uDD45\uDD47-\uDD49\uDD51\uDEA6\uDEA7\uDFCC\uDFCD]|\uD836[\uDE8C-\uDE9A\uDEA0\uDEB0-\uDFFF]|\uD837[\uDC00-\uDEFF\uDF1F-\uDF24\uDF2B-\uDFFF]|\uD838[\uDC07\uDC19\uDC1A\uDC22\uDC25\uDC2B-\uDC2F\uDC6E-\uDC8E\uDC90-\uDCFF\uDD2D-\uDD2F\uDD3E\uDD3F\uDD4A-\uDD4D\uDD50-\uDE8F\uDEAF-\uDEBF\uDEFA-\uDEFE\uDF00-\uDFFF]|\uD839[\uDC00-\uDCCF\uDCFA-\uDFDF\uDFE7\uDFEC\uDFEF\uDFFF]|\uD83A[\uDCC5\uDCC6\uDCD7-\uDCFF\uDD4C-\uDD4F\uDD5A-\uDD5D\uDD60-\uDFFF]|\uD83B[\uDC00-\uDC70\uDCB5-\uDD00\uDD3E-\uDDFF\uDE04\uDE20\uDE23\uDE25\uDE26\uDE28\uDE33\uDE38\uDE3A\uDE3C-\uDE41\uDE43-\uDE46\uDE48\uDE4A\uDE4C\uDE50\uDE53\uDE55\uDE56\uDE58\uDE5A\uDE5C\uDE5E\uDE60\uDE63\uDE65\uDE66\uDE6B\uDE73\uDE78\uDE7D\uDE7F\uDE8A\uDE9C-\uDEA0\uDEA4\uDEAA\uDEBC-\uDEEF\uDEF2-\uDFFF]|\uD83C[\uDC2C-\uDC2F\uDC94-\uDC9F\uDCAF\uDCB0\uDCC0\uDCD0\uDCF6-\uDCFF\uDDAE-\uDDE5\uDE03-\uDE0F\uDE3C-\uDE3F\uDE49-\uDE4F\uDE52-\uDE5F\uDE66-\uDEFF]|\uD83D[\uDED8-\uDEDB\uDEED-\uDEEF\uDEFD-\uDEFF\uDF77-\uDF7A\uDFDA-\uDFDF\uDFEC-\uDFEF\uDFF1-\uDFFF]|\uD83E[\uDC0C-\uDC0F\uDC48-\uDC4F\uDC5A-\uDC5F\uDC88-\uDC8F\uDCAE\uDCAF\uDCB2-\uDCFF\uDE54-\uDE5F\uDE6E\uDE6F\uDE7D-\uDE7F\uDE89-\uDE8F\uDEBE\uDEC6-\uDECD\uDEDC-\uDEDF\uDEE9-\uDEEF\uDEF9-\uDEFF\uDF93\uDFCB-\uDFEF\uDFFA-\uDFFF]|\uD869[\uDEE0-\uDEFF]|\uD86D[\uDF3A-\uDF3F]|\uD86E[\uDC1E\uDC1F]|\uD873[\uDEA2-\uDEAF]|\uD87A[\uDFE1-\uDFFF]|\uD87E[\uDE1E-\uDFFF]|\uD884[\uDF4B-\uDF4F]|\uD888[\uDFB0-\uDFFF]|\uDB40[\uDC00\uDC02-\uDC1F\uDC80-\uDCFF\uDDF0-\uDFFF]|[\uDBBF\uDBFF][\uDFFE\uDFFF]/;
+
+// src/scratchpad-native/protocol.ts
+var SUBJECT_PREFIX = "sp.v1.api.v2.";
+var METADATA_HEADER = "ScratchPad-Metadata";
+var REPLY_HEADER = "ScratchPad-Reply";
+var CHUNK_SIZE = 512 * 1024;
+var MAX_NODE_BYTES = 900 * 1024;
+var MAX_CHUNKS = 20480;
+var MAX_TREE_ENTRIES = 8192;
+var MAX_DEPTH = 128;
+var MAX_CONTROL_BYTES = 16 * 1024;
+var MAX_REPLY_BYTES = 128 * 1024;
+var MAX_HEADER_BYTES = 8 * 1024;
+var MAX_READ_BYTES = CHUNK_SIZE;
+var MAX_PREPARE_OBJECTS = 64;
+var MAX_VOLUME_OBJECTS = 65536;
+var MAX_VOLUME_BYTES = 8 * 2 ** 30;
+var WRITER_SLOTS = 8;
+var RETENTION_SLOTS = 8;
+var GRANT_SLOTS = 16;
+var MAX_GRANT_SECONDS = 3600;
+var ZERO_CONTENT_ID = "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA";
+var CODES = [
+  "ok",
+  "invalid",
+  "unauthenticated",
+  "denied",
+  "not_found",
+  "exists",
+  "conflict",
+  "fenced",
+  "intent_changed",
+  "capacity",
+  "summary_limit",
+  "closed",
+  "epoch_changed",
+  "expired",
+  "corrupt",
+  "incomplete",
+  "busy",
+  "unknown",
+  "unavailable",
+  "internal"
+];
+var PUBLIC_LIMITS = Object.freeze({
+  object_bytes: MAX_NODE_BYTES,
+  read_bytes: MAX_READ_BYTES,
+  control_bytes: MAX_CONTROL_BYTES,
+  reply_bytes: MAX_REPLY_BYTES,
+  writers: WRITER_SLOTS,
+  retentions: RETENTION_SLOTS,
+  grants: GRANT_SLOTS,
+  grant_seconds: MAX_GRANT_SECONDS
+});
+function check(condition, message) {
+  if (!condition) throw invalid(message);
+}
+function record(value, required, optional = []) {
+  check(
+    typeof value === "object" && value !== null && !Array.isArray(value),
+    "expected JSON object"
+  );
+  const result = value;
+  check(
+    required.every((key) => Object.hasOwn(result, key)),
+    "required field is absent"
+  );
+  check(
+    Object.keys(result).every((key) => required.includes(key) || optional.includes(key)),
+    "unknown field"
+  );
+  return result;
+}
+function uint(value, max = Number.MAX_SAFE_INTEGER, min = 0) {
+  check(
+    typeof value === "number" && Number.isSafeInteger(value) && value >= min && value <= max,
+    "integer outside its bound"
+  );
+}
+function bool(value) {
+  check(typeof value === "boolean", "expected boolean");
+}
+function text(value, max, min = 0) {
+  check(
+    typeof value === "string" && Buffer.from(value).toString("utf8") === value,
+    "invalid Unicode text"
+  );
+  check(
+    Buffer.byteLength(value) <= max && Buffer.byteLength(value) >= min,
+    "text outside its byte bound"
+  );
+}
+function validateContentID(value) {
+  check(typeof value === "string" && /^[A-Za-z0-9_-]{43}$/.test(value), "invalid content identity");
+  const bytes = Buffer.from(value, "base64url");
+  check(
+    bytes.length === 32 && bytes.toString("base64url") === value,
+    "noncanonical content identity"
+  );
+}
+function validatePublicKey(value, kind) {
+  check(typeof value === "string" && /^[A-Z2-7]{56}$/.test(value), "invalid public NKEY");
+  const alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
+  let bits = 0, pending = 0;
+  const data = [];
+  for (const character of value) {
+    pending = pending << 5 | alphabet.indexOf(character);
+    bits += 5;
+    if (bits >= 8) {
+      bits -= 8;
+      data.push(pending >>> bits & 255);
+    }
+  }
+  check(data.length === 35 && data[0] === (kind === "account" ? 0 : 160), "wrong NKEY kind");
+  let crc = 0;
+  for (const byte of data.slice(0, 33)) {
+    crc ^= byte << 8;
+    for (let i = 0; i < 8; i++) crc = (crc << 1 ^ (crc & 32768 ? 4129 : 0)) & 65535;
+  }
+  check(data[33] === (crc & 255) && data[34] === crc >>> 8, "NKEY checksum differs");
+}
+function validatePrincipal(value) {
+  const v = record(value, ["account", "user"]);
+  validatePublicKey(v.account, "account");
+  validatePublicKey(v.user, "user");
+}
+function validateName(value) {
+  text(value, 255, 1);
+  check(value !== "." && value !== ".." && !/[\x00-\x1f\x7f/]/.test(value), "forbidden entry name");
+  check(normalizeUnicode15(value) === value, "entry name is not NFC");
+}
+function normalizeUnicode15(value) {
+  let result = "", assigned = "";
+  for (const point of value) {
+    if (regex_default.test(point)) {
+      result += assigned.normalize("NFC") + point;
+      assigned = "";
+    } else assigned += point;
+  }
+  return result + assigned.normalize("NFC");
+}
+function validatePath(value, maxBytes = 4096) {
+  text(value, maxBytes, 1);
+  check(value.startsWith("/"), "path must be absolute");
+  if (value === "/") return;
+  const names = value.slice(1).split("/");
+  check(names.length <= MAX_DEPTH, "path exceeds its depth bound");
+  for (const name of names) validateName(name);
+}
+function validateVolume(value) {
+  check(typeof value === "string" && /^[0-9A-Za-z]{1,64}$/.test(value), "invalid volume name");
+}
+function validateTarget(value) {
+  const v = record(value, ["volume", "creation_id"]);
+  validateVolume(v.volume);
+  check(
+    typeof v.creation_id === "string" && /^[0-9a-f]{32}$/.test(v.creation_id),
+    "invalid volume creation identity"
+  );
+}
+function validateTrace(value) {
+  const v = record(value, [], ["thread_id", "root_id", "tool_call_id"]);
+  for (const field of ["thread_id", "root_id"]) {
+    if (v[field] !== void 0) text(v[field], 32);
+  }
+  if (v.tool_call_id !== void 0) {
+    text(v.tool_call_id, 1024);
+    check([...v.tool_call_id].length <= 256, "tool-call label is too long");
+  }
+  if (!v.thread_id && !v.root_id && !v.tool_call_id) return;
+  check(
+    typeof v.thread_id === "string" && /^[0-9a-f]{32}$/.test(v.thread_id),
+    "invalid trace thread"
+  );
+  check(typeof v.root_id === "string" && /^[0-9a-f]{32}$/.test(v.root_id), "invalid trace root");
+}
+function validateAction(value) {
+  const v = record(value, ["operation_id", "trace"]);
+  text(v.operation_id, 256, 1);
+  check([...v.operation_id].length <= 64, "operation identity is too long");
+  validateTrace(v.trace);
+}
+function validateHead(value) {
+  const v = record(value, ["generation", "root"]);
+  uint(v.generation, void 0, 1);
+  validateContentID(v.root);
+}
+function validateWriter(value) {
+  const v = record(value, ["slot", "generation"]);
+  uint(v.slot, WRITER_SLOTS - 1);
+  uint(v.generation, void 0, 1);
+}
+function validateRetentionHandle(value) {
+  const v = record(value, ["slot", "generation"]);
+  uint(v.slot, RETENTION_SLOTS - 1);
+  uint(v.generation, void 0, 1);
+}
+function validateGrantHandle(value) {
+  const v = record(value, ["slot", "generation"]);
+  uint(v.slot, GRANT_SLOTS - 1);
+  uint(v.generation, void 0, 1);
+}
+function validateCommand(value) {
+  const v = record(value, [
+    "creation_id",
+    "writer",
+    "number",
+    "operation_id",
+    "base",
+    "root",
+    "trace",
+    "retention"
+  ]);
+  validateTarget({ volume: "v", creation_id: v.creation_id });
+  validateWriter(v.writer);
+  uint(v.number, void 0, 1);
+  validateAction({ operation_id: v.operation_id, trace: v.trace });
+  validateHead(v.base);
+  validateContentID(v.root);
+  const r = record(v.retention, ["enabled", "slot", "generation", "until"]);
+  bool(r.enabled);
+  uint(r.slot, RETENTION_SLOTS - 1);
+  uint(r.generation);
+  uint(r.until);
+  check(
+    r.enabled || r.slot === 0 && r.generation === 0 && r.until === 0,
+    "disabled retention must be zero"
+  );
+}
+function validateReceipt(value) {
+  const v = record(value, ["volume", "principal", "command", "head", "retention"]);
+  validateVolume(v.volume);
+  validatePrincipal(v.principal);
+  validateCommand(v.command);
+  validateHead(v.head);
+  check(
+    v.head.root === v.command.root && v.head.generation - v.command.base.generation === 1,
+    "receipt head differs from command"
+  );
+  if (v.command.retention.enabled) {
+    validateRetentionHandle(v.retention);
+    check(
+      v.retention.slot === v.command.retention.slot && v.retention.generation > v.command.retention.generation,
+      "receipt retention differs from command"
+    );
+  } else {
+    const retention = record(v.retention, ["slot", "generation"]);
+    check(retention.slot === 0 && retention.generation === 0, "unexpected receipt retention");
+  }
+}
+function sameValue(a, b) {
+  if (a === b) return true;
+  if (!a || !b || typeof a !== "object" || typeof b !== "object") return false;
+  const left = a, right = b;
+  return Object.keys(left).length === Object.keys(right).length && Object.keys(left).every((key) => Object.hasOwn(right, key) && sameValue(left[key], right[key]));
+}
+function validateVolumeView(value) {
+  const v = record(value, [
+    "target",
+    "owner",
+    "head",
+    "revision",
+    "closed",
+    "epoch",
+    "objects",
+    "bytes",
+    "writers",
+    "retentions",
+    "grants"
+  ]);
+  validateTarget(v.target);
+  validatePrincipal(v.owner);
+  validateHead(v.head);
+  uint(v.revision, void 0, 1);
+  bool(v.closed);
+  uint(v.epoch, v.revision);
+  uint(v.objects, MAX_VOLUME_OBJECTS);
+  uint(v.bytes, MAX_VOLUME_BYTES);
+  check(
+    v.head.generation <= v.revision && (!v.closed || v.epoch === v.revision),
+    "inconsistent volume revision"
+  );
+  check(Array.isArray(v.writers) && v.writers.length === WRITER_SLOTS, "wrong writer slot count");
+  for (const [index, raw] of v.writers.entries()) {
+    const slot = record(raw, ["generation", "number", "write"], ["principal", "receipt"]);
+    uint(slot.generation, v.revision, 1);
+    uint(slot.number);
+    bool(slot.write);
+    if (slot.principal !== void 0) {
+      validatePrincipal(slot.principal);
+      check(slot.principal.account === v.owner.account, "writer belongs to another account");
+    } else check(!slot.write && slot.number === 0, "writer identity absent");
+    if (slot.number === 0) check(slot.receipt === void 0, "unused writer has a receipt");
+    else {
+      validateReceipt(slot.receipt);
+      check(
+        slot.write && sameValue(slot.receipt.principal, slot.principal) && slot.receipt.volume === v.target.volume && slot.receipt.command.creation_id === v.target.creation_id && slot.receipt.command.writer.slot === index && slot.receipt.command.writer.generation === slot.generation && slot.receipt.command.number === slot.number && slot.receipt.head.generation <= v.head.generation,
+        "writer receipt differs from slot"
+      );
+    }
+  }
+  check(
+    Array.isArray(v.retentions) && v.retentions.length === RETENTION_SLOTS,
+    "wrong retention slot count"
+  );
+  for (const raw of v.retentions) {
+    const slot = record(raw, ["generation"], ["pin"]);
+    uint(slot.generation, v.revision);
+    if (slot.pin !== void 0) {
+      check(slot.generation > 0, "retention pin has zero generation");
+      const pin = record(slot.pin, ["root", "until", "origin"]);
+      validateContentID(pin.root);
+      uint(pin.until);
+      const origin = record(pin.origin, ["writer", "number"]);
+      uint(origin.number);
+      if (origin.number === 0) {
+        const writer = record(origin.writer, ["slot", "generation"]);
+        check(writer.slot === 0 && writer.generation === 0, "empty retention origin is not zero");
+      } else {
+        validateWriter(origin.writer);
+        check(origin.writer.generation < slot.generation, "retention origin generation is invalid");
+      }
+    }
+  }
+  check(Array.isArray(v.grants) && v.grants.length === GRANT_SLOTS, "wrong grant slot count");
+  for (const raw of v.grants) {
+    const slot = record(raw, ["generation"], ["grant"]);
+    uint(slot.generation, v.revision);
+    if (slot.grant !== void 0) {
+      check(slot.generation > 0, "grant has zero generation");
+      const grant = record(slot.grant, [
+        "principal",
+        "root",
+        "path",
+        "directory",
+        "retention",
+        "until"
+      ]);
+      validatePrincipal(grant.principal);
+      validateContentID(grant.root);
+      validatePath(grant.path, 256);
+      bool(grant.directory);
+      validateRetentionHandle(grant.retention);
+      uint(grant.until, void 0, 1);
+      check(
+        grant.principal.account === v.owner.account && grant.retention.generation < slot.generation,
+        "invalid grant principal or retention generation"
+      );
+    }
+  }
+}
+function validateInfo(value) {
+  const v = record(value, ["principal", "scopes", "limits"]);
+  validatePrincipal(v.principal);
+  check(sameValue(v.limits, PUBLIC_LIMITS), "service limits differ from this client contract");
+  check(Array.isArray(v.scopes) && v.scopes.length <= 16, "scope count exceeds bound");
+  const seen = /* @__PURE__ */ new Set();
+  for (const raw of v.scopes) {
+    const scope = record(raw, ["volume", "objects", "bytes"]);
+    validateVolume(scope.volume);
+    uint(scope.objects, MAX_VOLUME_OBJECTS, 1);
+    uint(scope.bytes, MAX_VOLUME_BYTES, 4);
+    check(!seen.has(scope.volume), "duplicate scope");
+    seen.add(scope.volume);
+  }
+}
+function validateContentObject(value) {
+  const v = record(value, ["kind", "id"]);
+  validateContentID(v.id);
+  check(v.kind === "chnk" || v.kind === "fobj" || v.kind === "tree", "unsupported object kind");
+}
+function validateObjectSpec(value) {
+  const v = record(value, ["object", "length"]);
+  validateContentObject(v.object);
+  uint(v.length, v.object.kind === "chnk" ? CHUNK_SIZE : MAX_NODE_BYTES, 1);
+}
+function validateProgress(value, preparation) {
+  const v = record(value, ["object", "length", "state", "next", "code"]);
+  validateObjectSpec({ object: v.object, length: v.length });
+  validateContentObject(v.object);
+  uint(v.next);
+  if (v.state === "refused") {
+    check(preparation && v.next === 0 && v.code === "capacity", "invalid refusal state");
+    return;
+  }
+  check(v.code === "ok", "invalid progress code");
+  if (v.state === "reserved" || v.state === "verified")
+    check(v.next === 0, "unexpected progress cursor");
+  else {
+    check(v.state === "verifying" && v.object.kind !== "chnk", "invalid progress state");
+    uint(v.next, (v.object.kind === "tree" ? MAX_TREE_ENTRIES : MAX_CHUNKS) - 1, 1);
+  }
+}
+function validateProgressResult(value, preparation) {
+  const v = record(value, ["epoch", "objects"]);
+  uint(v.epoch);
+  check(
+    Array.isArray(v.objects) && v.objects.length > 0 && v.objects.length <= MAX_PREPARE_OBJECTS,
+    "invalid progress count"
+  );
+  const seen = /* @__PURE__ */ new Set();
+  for (const raw of v.objects) {
+    validateProgress(raw, preparation);
+    const key = raw.object.kind + ":" + raw.object.id;
+    check(!seen.has(key), "duplicate object progress");
+    seen.add(key);
+  }
+}
+function validatePrepareResult(value) {
+  validateProgressResult(value, true);
+}
+function validateVerifyResult(value) {
+  validateProgressResult(value, false);
+}
+function validateEntryBody(v) {
+  validateContentID(v.object);
+  bool(v.executable);
+  if (v.type === "symlink") {
+    text(v.link_target, 4096, 1);
+    check(
+      !v.link_target.includes("\0") && !v.executable && v.object === ZERO_CONTENT_ID,
+      "invalid symlink metadata"
+    );
+  } else {
+    check(v.type === "file" || v.type === "directory", "invalid entry type");
+    check(v.link_target === void 0 || v.link_target === "", "unexpected symlink target");
+    check(v.type === "file" || !v.executable, "directory is executable");
+  }
+}
+function validateStat(value) {
+  const v = record(value, ["type", "object", "size", "sha256", "executable"], ["link_target"]);
+  validateEntryBody(v);
+  uint(v.size, MAX_VOLUME_BYTES);
+  if (v.type === "file")
+    check(typeof v.sha256 === "string" && /^[0-9a-f]{64}$/.test(v.sha256), "invalid file digest");
+  else check(v.size === 0 && v.sha256 === "", "non-file metadata contains file bytes");
+}
+function validateListResult(value) {
+  const v = record(value, ["entries", "next", "done"]);
+  uint(v.next, MAX_TREE_ENTRIES);
+  bool(v.done);
+  check(
+    Array.isArray(v.entries) && v.entries.length <= 64 && v.entries.length <= v.next && (v.done || v.entries.length > 0),
+    "invalid list window"
+  );
+  let last = Buffer.alloc(0), bytes = 0;
+  for (const raw of v.entries) {
+    const entry = record(raw, ["name", "type", "object", "executable"], ["link_target"]);
+    validateName(entry.name);
+    validateEntryBody(entry);
+    const name = Buffer.from(entry.name);
+    check(Buffer.compare(last, name) < 0, "list names are not strictly ordered");
+    last = name;
+    bytes += Buffer.byteLength(goJSON(entry)) + 1;
+  }
+  check(bytes <= 64 * 1024, "list bytes exceed bound");
+}
+function validateReplyMetadata(value) {
+  const v = record(value, ["code", "message"], ["range"]);
+  check(
+    typeof v.code === "string" && CODES.includes(v.code),
+    "unknown reply code"
+  );
+  text(v.message, 256);
+  if (v.code !== "ok") {
+    check(v.message !== "" && v.range === void 0, "invalid error reply");
+    return;
+  }
+  check(v.message === "", "success reply has an error message");
+  if (v.range !== void 0) {
+    const range = record(v.range, ["stat", "offset", "length"]);
+    validateStat(range.stat);
+    check(range.stat.type === "file", "range is not a file");
+    uint(range.offset, range.stat.size);
+    uint(range.length, MAX_READ_BYTES);
+    check(range.length <= range.stat.size - range.offset, "range exceeds file");
+  }
+}
+function validateCollectionReport(value) {
+  const v = record(value, [
+    "inventory_objects",
+    "inventory_bytes",
+    "live_objects",
+    "live_bytes",
+    "candidate_objects",
+    "candidate_bytes",
+    "delete_objects"
+  ]);
+  uint(v.inventory_objects, MAX_VOLUME_OBJECTS);
+  uint(v.inventory_bytes, MAX_VOLUME_BYTES);
+  uint(v.live_objects, v.inventory_objects);
+  uint(v.live_bytes, v.inventory_bytes);
+  uint(v.candidate_objects);
+  uint(v.candidate_bytes);
+  uint(v.delete_objects);
+  check(
+    v.candidate_objects === v.inventory_objects - v.live_objects && v.candidate_bytes === v.inventory_bytes - v.live_bytes && v.delete_objects <= v.candidate_objects,
+    "collection counters differ"
+  );
+}
+function validateCollectionResult(value) {
+  const v = record(value, ["volume", "collection"]);
+  validateVolumeView(v.volume);
+  validateCollectionReport(v.collection);
+  check(
+    !v.volume.closed && v.volume.objects === v.collection.live_objects && v.volume.bytes === v.collection.live_bytes,
+    "collection does not match reopened volume"
+  );
+}
+function validateEmpty(value) {
+  record(value, []);
+}
+function goJSON(value, escapeHTML = true) {
+  let encoded = JSON.stringify(value);
+  check(encoded !== void 0, "value cannot be encoded as JSON");
+  encoded = encoded.replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029");
+  return escapeHTML ? encoded.replace(/</g, "\\u003c").replace(/>/g, "\\u003e").replace(/&/g, "\\u0026") : encoded;
+}
+function parseStrictJSON(data, limit) {
+  const bytes = typeof data === "string" ? Buffer.from(data) : Buffer.from(data);
+  check(bytes.length <= limit, "JSON exceeds its byte bound");
+  const source = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+  let cursor = 0;
+  const whitespace = () => {
+    while (/[\t\n\r ]/.test(source[cursor] ?? "!")) cursor++;
+  };
+  const string = () => {
+    const start = cursor++;
+    for (; ; ) {
+      check(cursor < source.length, "unterminated JSON string");
+      const char = source[cursor++];
+      if (char === "\\") {
+        cursor++;
+        continue;
+      }
+      if (char === '"') break;
+    }
+    const value2 = JSON.parse(source.slice(start, cursor));
+    text(value2, limit);
+    return value2;
+  };
+  const value = (depth) => {
+    check(depth <= 64, "JSON nesting exceeds bound");
+    whitespace();
+    const first = source[cursor];
+    if (first === '"') return string();
+    if (first === "{") {
+      cursor++;
+      whitespace();
+      const result2 = /* @__PURE__ */ Object.create(null);
+      if (source[cursor] === "}") {
+        cursor++;
+        return result2;
+      }
+      for (; ; ) {
+        check(source[cursor] === '"', "JSON key must be a string");
+        const key = string();
+        whitespace();
+        check(!Object.hasOwn(result2, key), "duplicate JSON key");
+        check(source[cursor++] === ":", "missing JSON colon");
+        result2[key] = value(depth + 1);
+        whitespace();
+        const delimiter = source[cursor++];
+        if (delimiter === "}") return result2;
+        check(delimiter === ",", "invalid JSON object separator");
+        whitespace();
+      }
+    }
+    if (first === "[") {
+      cursor++;
+      whitespace();
+      const result2 = [];
+      if (source[cursor] === "]") {
+        cursor++;
+        return result2;
+      }
+      for (; ; ) {
+        result2.push(value(depth + 1));
+        whitespace();
+        const delimiter = source[cursor++];
+        if (delimiter === "]") return result2;
+        check(delimiter === ",", "invalid JSON array separator");
+        whitespace();
+      }
+    }
+    for (const [token, decoded] of [
+      ["true", true],
+      ["false", false],
+      ["null", null]
+    ]) {
+      if (source.startsWith(token, cursor)) {
+        cursor += token.length;
+        return decoded;
+      }
+    }
+    const match = /^-?(?:0|[1-9][0-9]*)/.exec(source.slice(cursor));
+    check(match, "invalid JSON value");
+    cursor += match[0].length;
+    const number = Number(match[0]);
+    check(
+      Number.isSafeInteger(number) && !Object.is(number, -0),
+      "unsafe or noncanonical JSON integer"
+    );
+    return number;
+  };
+  const result = value(0);
+  whitespace();
+  check(cursor === source.length, "trailing JSON data");
+  return result;
+}
+
+// src/scratchpad-native/codec.ts
+var CodecError = class extends Error {
+  constructor(reason, message) {
+    super(message);
+    this.reason = reason;
+    this.name = "CodecError";
+  }
+  reason;
+};
+function reject(reason, message) {
+  throw new CodecError(reason, message);
+}
+function hash(tag, data) {
+  return node_crypto.createHash("sha256").update(tag).update("\0").update(data).digest("base64url");
+}
+function chunkID(data) {
+  return hash("scratchpad:v1:chunk", data);
+}
+function fileObjectID(data) {
+  return hash("scratchpad:v1:file", data);
+}
+function treeNodeID(data) {
+  return hash("scratchpad:v1:tree", data);
+}
+async function chunkStream(source, emit) {
+  const file = { size: 0, digest: "", chunks: [] };
+  const digest = node_crypto.createHash("sha256"), buffer = Buffer.alloc(CHUNK_SIZE);
+  let used = 0;
+  const flush = async () => {
+    if (file.chunks.length >= MAX_CHUNKS) reject("chunk-shape", "file exceeds chunk count bound");
+    const bytes = buffer.subarray(0, used), id = chunkID(bytes);
+    digest.update(bytes);
+    file.size += used;
+    file.chunks.push({ id, length: used });
+    await emit(file.chunks.length - 1, { kind: "chnk", id }, bytes);
+    used = 0;
+  };
+  for await (const part of source) {
+    check(part instanceof Uint8Array, "stream must yield bytes");
+    let offset = 0;
+    while (offset < part.length) {
+      const length = Math.min(CHUNK_SIZE - used, part.length - offset);
+      buffer.set(part.subarray(offset, offset + length), used);
+      used += length;
+      offset += length;
+      if (used === CHUNK_SIZE) await flush();
+    }
+  }
+  if (used !== 0) await flush();
+  file.digest = digest.digest("hex");
+  return file;
+}
+function head(major, value) {
+  uint(value);
+  if (value < 24) return Buffer.from([major << 5 | value]);
+  if (value <= 255) return Buffer.from([major << 5 | 24, value]);
+  if (value <= 65535) {
+    const bytes2 = Buffer.alloc(3);
+    bytes2[0] = major << 5 | 25;
+    bytes2.writeUInt16BE(value, 1);
+    return bytes2;
+  }
+  if (value <= 4294967295) {
+    const bytes2 = Buffer.alloc(5);
+    bytes2[0] = major << 5 | 26;
+    bytes2.writeUInt32BE(value, 1);
+    return bytes2;
+  }
+  const bytes = Buffer.alloc(9);
+  bytes[0] = major << 5 | 27;
+  bytes.writeBigUInt64BE(BigInt(value), 1);
+  return bytes;
+}
+function byteString(bytes) {
+  return Buffer.concat([head(2, bytes.length), bytes]);
+}
+function textString(value) {
+  const bytes = Buffer.from(value);
+  return Buffer.concat([head(3, bytes.length), bytes]);
+}
+function validateFile(file) {
+  uint(file.size);
+  check(
+    typeof file.digest === "string" && /^[0-9a-f]{64}$/.test(file.digest),
+    "invalid logical file digest"
+  );
+  if (!Array.isArray(file.chunks) || file.chunks.length > MAX_CHUNKS)
+    reject("chunk-shape", "chunk count exceeds bound");
+  let total = 0;
+  for (const [index, chunk] of file.chunks.entries()) {
+    validateContentID(chunk.id);
+    uint(chunk.length);
+    if (chunk.length === 0 || chunk.length > CHUNK_SIZE || index !== file.chunks.length - 1 && chunk.length !== CHUNK_SIZE)
+      reject("chunk-shape", "invalid fixed chunk length");
+    total += chunk.length;
+  }
+  if (total !== file.size) reject("chunk-shape", "chunk lengths differ from file size");
+}
+function encodeFileObject(file) {
+  validateFile(file);
+  const parts = [head(5, 3), textString("c"), head(4, file.chunks.length)];
+  for (const chunk of file.chunks)
+    parts.push(head(4, 2), byteString(Buffer.from(chunk.id, "base64url")), head(0, chunk.length));
+  parts.push(
+    textString("d"),
+    byteString(Buffer.from(file.digest, "hex")),
+    textString("s"),
+    head(0, file.size)
+  );
+  return Buffer.concat(parts);
+}
+function entryName(name) {
+  if (typeof name !== "string" || Buffer.from(name).toString("utf8") !== name)
+    reject("utf8", "invalid entry name UTF-8");
+  if (Buffer.byteLength(name) === 0 || Buffer.byteLength(name) > 255)
+    reject("name-length", "entry name length exceeds bound");
+  if (name === "." || name === ".." || /[\x00-\x1f\x7f/]/.test(name))
+    reject("name-forbidden", "forbidden entry name");
+  try {
+    validateName(name);
+  } catch {
+    reject("not-nfc", "entry name is not NFC");
+  }
+}
+function validateEntry(entry) {
+  entryName(entry.name);
+  if (entry.type === "symlink") {
+    if (entry.executable || entry.object !== void 0 && entry.object !== ZERO_CONTENT_ID)
+      reject("type-invalid", "symlink has file fields");
+    const target = entry.linkTarget ?? "";
+    if (typeof target !== "string" || Buffer.from(target).toString("utf8") !== target)
+      reject("utf8", "invalid symlink UTF-8");
+    if (Buffer.byteLength(target) === 0 || Buffer.byteLength(target) > 4096 || target.includes("\0"))
+      reject("target-invalid", "invalid symlink target");
+  } else {
+    if (entry.type !== "file" && entry.type !== "directory")
+      reject("type-invalid", "unknown entry type");
+    validateContentID(entry.object);
+    if (entry.linkTarget || entry.type === "directory" && entry.executable)
+      reject("type-invalid", "entry has fields of another type");
+  }
+}
+function encodeTreeNode(entries) {
+  for (const entry of entries) validateEntry(entry);
+  const sorted = [...entries].sort(
+    (a, b) => Buffer.compare(Buffer.from(a.name), Buffer.from(b.name))
+  );
+  for (let index = 1; index < sorted.length; index++)
+    if (sorted[index].name === sorted[index - 1].name)
+      reject("duplicate-name", "duplicate tree entry");
+  if (entries.length > MAX_TREE_ENTRIES) reject("entry-count", "tree entry count exceeds bound");
+  const parts = [head(5, 1), textString("e"), head(4, entries.length)];
+  let length = parts.reduce((sum, part) => sum + part.length, 0);
+  for (const entry of sorted) {
+    const fields = [head(5, entry.executable ? 4 : 3)];
+    if (entry.type === "symlink") fields.push(textString("l"), textString(entry.linkTarget));
+    else fields.push(textString("i"), byteString(Buffer.from(entry.object, "base64url")));
+    fields.push(
+      textString("n"),
+      textString(entry.name),
+      textString("t"),
+      head(0, entry.type === "file" ? 0 : entry.type === "directory" ? 1 : 2)
+    );
+    if (entry.executable) fields.push(textString("x"), head(0, 1));
+    length += fields.reduce((sum, part) => sum + part.length, 0);
+    if (length > MAX_NODE_BYTES) reject("node-size", "tree node byte count exceeds bound");
+    parts.push(...fields);
+  }
+  return Buffer.concat(parts);
+}
+treeNodeID(encodeTreeNode([]));
+function decodeCBOR(data) {
+  let cursor = 0;
+  const take = (length) => {
+    if (!Number.isSafeInteger(length) || length > data.length - cursor)
+      reject("type-mismatch", "truncated CBOR");
+    const bytes = Buffer.from(data.buffer, data.byteOffset + cursor, length);
+    cursor += length;
+    return bytes;
+  };
+  const item = (depth) => {
+    if (depth > 8) reject("type-mismatch", "CBOR nesting exceeds object shape");
+    const first = take(1)[0], major = first >>> 5, additional = first & 31;
+    if (additional === 31) reject("indefinite-length", "indefinite CBOR length");
+    if (![0, 2, 3, 4, 5].includes(major)) reject("forbidden-item", "forbidden CBOR item");
+    let value = additional;
+    if (additional >= 24) {
+      if (additional > 27) reject("forbidden-item", "reserved CBOR length");
+      const bytes = take(2 ** (additional - 24));
+      const large = additional === 27 ? bytes.readBigUInt64BE() : BigInt(bytes.readUIntBE(0, bytes.length));
+      const minimum = [24n, 256n, 65536n, 4294967296n][additional - 24];
+      if (large < minimum) reject("non-shortest", "CBOR integer is not shortest");
+      if (large > BigInt(Number.MAX_SAFE_INTEGER))
+        reject("type-mismatch", "CBOR integer exceeds exact range");
+      value = Number(large);
+    }
+    if (major === 0) return value;
+    if (major === 2) return take(value);
+    if (major === 3) {
+      try {
+        return new TextDecoder("utf-8", { fatal: true }).decode(take(value));
+      } catch {
+        return reject("utf8", "CBOR text is not UTF-8");
+      }
+    }
+    if (value > data.length - cursor) reject("type-mismatch", "CBOR item count exceeds input");
+    if (major === 4) {
+      const values = [];
+      for (let index = 0; index < value; index++) values.push(item(depth + 1));
+      return values;
+    }
+    const result2 = /* @__PURE__ */ new Map();
+    let last;
+    for (let index = 0; index < value; index++) {
+      const start = cursor;
+      let key;
+      try {
+        key = item(depth + 1);
+      } catch (error) {
+        if (error instanceof CodecError && error.reason === "utf8")
+          reject("key-unknown", "invalid UTF-8 map key cannot be a schema key");
+        throw error;
+      }
+      const encoded = Buffer.from(data.subarray(start, cursor));
+      if (typeof key !== "string") reject("type-mismatch", "CBOR map key must be text");
+      if (last && Buffer.compare(last, encoded) >= 0)
+        reject("key-order", "CBOR keys are not strictly ordered");
+      last = encoded;
+      result2.set(key, item(depth + 1));
+    }
+    return result2;
+  };
+  const result = item(0);
+  if (cursor !== data.length) reject("trailing-bytes", "trailing CBOR bytes");
+  return result;
+}
+function map(value, keys) {
+  if (!(value instanceof Map)) reject("type-mismatch", "expected CBOR map");
+  for (const key of value.keys())
+    if (!keys.includes(key)) reject("key-unknown", "unknown object key");
+  for (const key of keys) if (!value.has(key)) reject("key-missing", "missing object key");
+  return value;
+}
+function bytes32(value) {
+  if (!(value instanceof Uint8Array) || value.length !== 32)
+    reject("type-mismatch", "expected 32-byte digest");
+  return Buffer.from(value);
+}
+function integer(value) {
+  if (typeof value !== "number") reject("type-mismatch", "expected unsigned integer");
+  return value;
+}
+function decodeFileObject(data) {
+  const fields = map(decodeCBOR(data), ["c", "d", "s"]), refs = fields.get("c");
+  if (!Array.isArray(refs)) reject("type-mismatch", "chunks must be array");
+  const file = {
+    size: integer(fields.get("s")),
+    digest: bytes32(fields.get("d")).toString("hex"),
+    chunks: []
+  };
+  for (const ref of refs) {
+    if (!Array.isArray(ref) || ref.length !== 2)
+      reject("type-mismatch", "chunk reference must have two fields");
+    file.chunks.push({ id: bytes32(ref[0]).toString("base64url"), length: integer(ref[1]) });
+  }
+  validateFile(file);
+  return file;
+}
+function decodeTreeNode(data) {
+  if (data.length > MAX_NODE_BYTES) reject("node-size", "tree node exceeds byte bound");
+  const fields = map(decodeCBOR(data), ["e"]), raw = fields.get("e");
+  if (!Array.isArray(raw)) reject("type-mismatch", "entries must be an array");
+  if (raw.length > MAX_TREE_ENTRIES) reject("entry-count", "tree entry count exceeds bound");
+  const entries = [];
+  let previous;
+  for (const item of raw) {
+    if (!(item instanceof Map)) reject("type-mismatch", "entry must be a map");
+    for (const key of item.keys())
+      if (!["i", "l", "n", "t", "x"].includes(key)) reject("key-unknown", "unknown entry key");
+    if (!item.has("n") || !item.has("t")) reject("key-missing", "missing entry name or type");
+    const name = item.get("n"), type = integer(item.get("t"));
+    if (typeof name !== "string") reject("type-mismatch", "entry name must be text");
+    if (type > 2) reject("type-invalid", "unknown entry type");
+    if (!item.has(type === 2 ? "l" : "i")) reject("key-missing", "missing entry target");
+    if (item.has(type === 2 ? "i" : "l")) reject("type-invalid", "entry has other target type");
+    if (item.has("x") && integer(item.get("x")) !== 1)
+      reject("type-invalid", "executable flag must be one");
+    const entry = {
+      name,
+      type: type === 0 ? "file" : type === 1 ? "directory" : "symlink"
+    };
+    if (item.has("x")) entry.executable = true;
+    if (type === 2) {
+      const target = item.get("l");
+      if (typeof target !== "string") reject("type-mismatch", "symlink target must be text");
+      entry.linkTarget = target;
+    } else entry.object = bytes32(item.get("i")).toString("base64url");
+    validateEntry(entry);
+    if (previous !== void 0) {
+      const order = Buffer.compare(Buffer.from(previous), Buffer.from(name));
+      if (order === 0) reject("duplicate-name", "duplicate tree entry");
+      if (order > 0) reject("entry-order", "entries are not sorted");
+    }
+    previous = name;
+    entries.push(entry);
+  }
+  return entries;
+}
+function verifyObject(object, data) {
+  validateContentID(object.id);
+  if (object.kind === "chnk") {
+    if (data.length === 0 || data.length > CHUNK_SIZE)
+      reject("chunk-shape", "chunk length outside bound");
+    if (chunkID(data) !== object.id) reject("id-mismatch", "chunk identity differs");
+  } else if (object.kind === "fobj") {
+    const file = decodeFileObject(data);
+    if (!Buffer.from(encodeFileObject(file)).equals(data))
+      reject("type-invalid", "file bytes are not canonical");
+    if (fileObjectID(data) !== object.id) reject("id-mismatch", "file identity differs");
+  } else if (object.kind === "tree") {
+    const entries = decodeTreeNode(data);
+    if (!Buffer.from(encodeTreeNode(entries)).equals(data))
+      reject("type-invalid", "tree bytes are not canonical");
+    if (treeNodeID(data) !== object.id) reject("id-mismatch", "tree identity differs");
+  } else reject("type-invalid", "unsupported object kind");
+}
+function validateReference(value) {
+  const v = record(value, [
+    "version",
+    "creator",
+    "account",
+    "target",
+    "root",
+    "generation",
+    "path",
+    "retention",
+    "expires_at"
+  ]);
+  check(v.version === 2, "reference version must be two");
+  text(v.creator, 512, 1);
+  validatePublicKey(v.account, "account");
+  validateTarget(v.target);
+  validateContentID(v.root);
+  uint(v.generation, void 0, 1);
+  validatePath(v.path, 256);
+  validateRetentionHandle(v.retention);
+  uint(v.expires_at, void 0, 1);
+}
+function encodeReference(reference) {
+  validateReference(reference);
+  const ordered = {
+    version: 2,
+    creator: reference.creator,
+    account: reference.account,
+    target: { volume: reference.target.volume, creation_id: reference.target.creation_id },
+    root: reference.root,
+    generation: reference.generation,
+    path: reference.path,
+    retention: { slot: reference.retention.slot, generation: reference.retention.generation },
+    expires_at: reference.expires_at
+  };
+  const token = "sp-ref:" + Buffer.from(goJSON(ordered, false)).toString("base64url");
+  check(Buffer.byteLength(token) <= 16 * 1024, "reference exceeds byte bound");
+  return token;
+}
+function decodeReference(token) {
+  text(token, 16 * 1024);
+  check(token.startsWith("sp-ref:"), "reference prefix is absent");
+  const encoded = token.slice(7);
+  check(/^[A-Za-z0-9_-]+$/.test(encoded), "reference is not unpadded base64url");
+  const data = Buffer.from(encoded, "base64url");
+  check(data.toString("base64url") === encoded, "reference base64url has stray bits");
+  const reference = parseStrictJSON(data, 16 * 1024);
+  validateReference(reference);
+  check(encodeReference(reference) === token, "reference JSON is not canonical");
+  return reference;
+}
+
+// src/scratchpad-native/references.ts
+var SHORT_REFERENCE_PREFIX2 = "sp-r1:";
+var SHORT_REFERENCE_BYTES = 66;
+var REFERENCE_PATHS = 8;
+var MAX_REFERENCE_INTENT_BYTES = 3072;
+var MAX_REFERENCE_METADATA_BYTES = 32768;
+function decodeShortReference(token) {
+  text(token, SHORT_REFERENCE_BYTES, SHORT_REFERENCE_BYTES);
+  check(/^sp-r1:[A-Za-z0-9_-]{60}$/.test(token), "malformed short reference");
+  const data = Buffer.from(token.slice(SHORT_REFERENCE_PREFIX2.length), "base64url");
+  check(data.length === 45 && data[32] < 64, "invalid short reference slots");
+  const generation = Number(data.readBigUInt64BE(24));
+  uint(generation, void 0, 1);
+  const result = {
+    route: data.subarray(0, 8).toString("hex"),
+    creation_id: data.subarray(8, 24).toString("hex"),
+    retention: { slot: data[32] >> 3, generation },
+    path_index: data[32] & 7
+  };
+  validateTarget({ volume: "Reference", creation_id: result.creation_id });
+  return result;
+}
+function referenceRoute(account, volume) {
+  return node_crypto.createHash("sha256").update(`scratchpad-reference-volume-v1\0${account}\0${volume}`).digest().subarray(0, 8).toString("hex");
+}
+function validateReferenceSpec(value) {
+  const v = record(value, ["creator", "paths"]);
+  text(v.creator, 512, 1);
+  check(
+    Array.isArray(v.paths) && v.paths.length > 0 && v.paths.length <= REFERENCE_PATHS,
+    "reference paths exceed bound"
+  );
+  let previous = "";
+  for (const path of v.paths) {
+    validatePath(path, 256);
+    check(
+      Buffer.compare(Buffer.from(previous), Buffer.from(path)) < 0,
+      "reference paths must be distinct and sorted"
+    );
+    previous = path;
+  }
+  check(
+    Buffer.byteLength(goJSON({ creator: v.creator, paths: v.paths })) <= MAX_REFERENCE_INTENT_BYTES,
+    "reference intent exceeds byte bound"
+  );
+}
+function validateResolvedReference(value) {
+  const v = record(value, ["short", "expanded"]);
+  text(v.short, SHORT_REFERENCE_BYTES, SHORT_REFERENCE_BYTES);
+  const locator = decodeShortReference(v.short);
+  validateReference(v.expanded);
+  check(
+    locator.route === referenceRoute(v.expanded.account, v.expanded.target.volume) && locator.creation_id === v.expanded.target.creation_id && sameValue(locator.retention, v.expanded.retention),
+    "short reference binding differs"
+  );
+}
+function validateReferenceCapabilities(value) {
+  const v = record(value, [
+    "enabled",
+    "version",
+    "prefix",
+    "token_bytes",
+    "paths_per_retention",
+    "max_intent_bytes",
+    "max_metadata_bytes"
+  ]);
+  check(
+    typeof v.enabled === "boolean" && v.version === 1 && v.prefix === SHORT_REFERENCE_PREFIX2 && v.token_bytes === SHORT_REFERENCE_BYTES && v.paths_per_retention === REFERENCE_PATHS && v.max_intent_bytes === MAX_REFERENCE_INTENT_BYTES && v.max_metadata_bytes === MAX_REFERENCE_METADATA_BYTES,
+    "unsupported reference capability"
+  );
+}
+function validateReferencePublishRequest(value) {
+  const v = record(value, ["target", "command", "reference"]);
+  validateTarget(v.target);
+  validateCommand(v.command);
+  check(
+    v.target.creation_id === v.command.creation_id && v.command.retention.enabled && v.command.retention.until > 0,
+    "referenced publication requires finite retention and matching target"
+  );
+  validateReferenceSpec(v.reference);
+}
+function validateReferencePublishResult(value) {
+  const v = record(value, ["receipt", "references"]);
+  validateReceipt(v.receipt);
+  check(
+    v.receipt.command.retention.enabled && Array.isArray(v.references) && v.references.length > 0 && v.references.length <= REFERENCE_PATHS,
+    "invalid referenced receipt"
+  );
+  let previous = "", creator;
+  for (const [index, pair] of v.references.entries()) {
+    validateResolvedReference(pair);
+    const ref = pair.expanded;
+    creator ??= ref.creator;
+    check(
+      decodeShortReference(pair.short).path_index === index && ref.creator === creator && Buffer.compare(Buffer.from(previous), Buffer.from(ref.path)) < 0 && ref.account === v.receipt.principal.account && ref.target.volume === v.receipt.volume && ref.target.creation_id === v.receipt.command.creation_id && ref.root === v.receipt.head.root && ref.generation === v.receipt.head.generation && sameValue(ref.retention, v.receipt.retention) && ref.expires_at === v.receipt.command.retention.until,
+      "reference differs from receipt"
+    );
+    previous = ref.path;
+  }
+}
+function validateReferenceStatResult(value) {
+  const v = record(value, ["reference", "stat"]);
+  validateResolvedReference(v.reference);
+  validateStat(v.stat);
+}
+function validateReferenceRetainRequest(value) {
+  const v = record(value, ["retain", "reference"]);
+  const retain = record(v.retain, ["target", "slot", "generation", "root", "until", "action"]);
+  validateTarget(retain.target);
+  uint(retain.slot, RETENTION_SLOTS - 1);
+  uint(retain.generation);
+  validateContentID(retain.root);
+  uint(retain.until, void 0, 1);
+  validateAction(retain.action);
+  validateReferenceSpec(v.reference);
+}
+function validateReferenceRetainResult(value) {
+  const v = record(value, ["volume", "references"]);
+  validateVolumeView(v.volume);
+  check(
+    Array.isArray(v.references) && v.references.length > 0 && v.references.length <= REFERENCE_PATHS,
+    "invalid retained references"
+  );
+  let first, previous = "";
+  for (const [index, pair] of v.references.entries()) {
+    validateResolvedReference(pair);
+    const ref = pair.expanded;
+    first ??= ref;
+    const retained = v.volume.retentions[ref.retention.slot];
+    check(
+      decodeShortReference(pair.short).path_index === index && Buffer.compare(Buffer.from(previous), Buffer.from(ref.path)) < 0 && ref.creator === first.creator && ref.root === first.root && ref.generation === first.generation && sameValue(ref.retention, first.retention) && ref.expires_at === first.expires_at && sameValue(ref.target, v.volume.target) && ref.account === v.volume.owner.account && retained.generation === ref.retention.generation && retained.pin?.root === ref.root && retained.pin.until === ref.expires_at,
+      "reference differs from retained root"
+    );
+    previous = ref.path;
+  }
+}
+
+// src/scratchpad-cli.ts
+var DEFAULT_SP_BIN = "sp";
+var HANDOFF_TTL_S = 600;
+var DEFAULT_GRANT_TTL_S = 600;
+var EXPIRY_MARGIN_S = 5;
+var MAX_LEDGER = 16;
+var MAX_REFERENCE_BYTES = 16 * 1024;
+var MAX_READ_BYTES2 = 16 * 1024 * 1024;
+var MAX_READ_STDOUT = Math.ceil(MAX_READ_BYTES2 / 3) * 4 + 64 * 1024;
+var MAX_STDOUT = 256 * 1024;
+var MAX_STDERR = 64 * 1024;
+var ACCOUNT_RE = /^A[A-Z2-7]{55}$/;
+var VOLUME_RE = /^[0-9A-Za-z]{1,64}$/;
+var CREATION_RE = /^[0-9a-f]{32}$/;
+var ROOT_RE = /^[A-Za-z0-9_-]{43}$/;
+var BASE64URL_RE = /^[A-Za-z0-9_-]+$/;
+var BASE64_RE = /^[A-Za-z0-9+/]*={0,2}$/;
+var ScratchPadError = class extends Error {
+  constructor(message, code, unknown2) {
+    super(message);
+    this.code = code;
+    this.unknown = unknown2;
+    this.name = "ScratchPadError";
+  }
+  code;
+  unknown;
+};
+var isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+var hasKeys = (v, keys) => Object.keys(v).length === keys.length && keys.every((k) => k in v);
+var positive = (v) => Number.isSafeInteger(v) && v > 0;
+var utf8Bytes = (s) => Buffer.byteLength(s, "utf8");
+function validTarget(v) {
+  return isObject(v) && hasKeys(v, ["volume", "creation_id"]) && typeof v["volume"] === "string" && VOLUME_RE.test(v["volume"]) && typeof v["creation_id"] === "string" && CREATION_RE.test(v["creation_id"]);
+}
+function validPath(p) {
+  if (typeof p !== "string" || !p.startsWith("/") || utf8Bytes(p) > 256) return false;
+  if (p === "/") return true;
+  return p.slice(1).split("/").every((name) => name !== "" && name !== "." && name !== "..");
+}
+function decodeReference2(reference) {
+  const refuse2 = (why) => {
+    throw new Error(`malformed ScratchPad reference: ${why}`);
+  };
+  if (typeof reference !== "string" || !reference.startsWith(REFERENCE_PREFIX)) {
+    refuse2("no sp-ref: prefix");
+  }
+  if (reference.length > MAX_REFERENCE_BYTES) refuse2("longer than 16 KiB");
+  const body = reference.slice(REFERENCE_PREFIX.length);
+  if (!BASE64URL_RE.test(body) || body.length % 4 === 1) refuse2("not unpadded base64url");
+  let v;
+  try {
+    v = JSON.parse(Buffer.from(body, "base64url").toString("utf8"));
+  } catch {
+    refuse2("not JSON");
+  }
+  const keys = [
+    "version",
+    "creator",
+    "account",
+    "target",
+    "root",
+    "generation",
+    "path",
+    "retention",
+    "expires_at"
+  ];
+  if (!isObject(v) || !hasKeys(v, keys)) return refuse2("not the version 2 fields");
+  const r = v.retention;
+  if (v["version"] !== 2 || typeof v["creator"] !== "string" || v["creator"].length === 0 || utf8Bytes(v["creator"]) > 512 || typeof v["account"] !== "string" || !ACCOUNT_RE.test(v["account"]) || !validTarget(v["target"]) || typeof v["root"] !== "string" || !ROOT_RE.test(v["root"]) || !positive(v["generation"]) || !validPath(v["path"]) || !isObject(r) || !hasKeys(r, ["slot", "generation"]) || !Number.isSafeInteger(r["slot"]) || r["slot"] < 0 || r["slot"] > 7 || !positive(r["generation"]) || !positive(v["expires_at"])) {
+    refuse2("a field is out of shape");
+  }
+  return v;
+}
+var now = () => Math.floor(Date.now() / 1e3);
+var RETENTION_SLOTS2 = 8;
+var GRANT_SLOTS2 = 16;
+var CONTROL_KINDS = ["close", "apply", "release", "grant"];
+var NO_VOLUME_CODES = ["workspace", "not_found"];
+var count = (v) => Number.isSafeInteger(v) && v >= 0;
+function decodeDescribe(reply) {
+  const refuse2 = (why) => {
+    throw new ScratchPadError(`sp describe: ${why}`, "malformed_reply", false);
+  };
+  if (!isObject(reply) || !isObject(reply["volume"])) return refuse2("the reply names no volume");
+  const volume = reply["volume"];
+  const control = reply["control"];
+  let kind;
+  if (control !== null && control !== void 0) {
+    if (!isObject(control) || typeof control["kind"] !== "string" || !CONTROL_KINDS.includes(control["kind"])) {
+      return refuse2("the saved control request is out of shape");
+    }
+    kind = control["kind"];
+  }
+  if (typeof volume["closed"] !== "boolean") return refuse2("the volume names no closed state");
+  const retentions = volume["retentions"];
+  const grants = volume["grants"];
+  if (!Array.isArray(retentions) || retentions.length !== RETENTION_SLOTS2)
+    return refuse2("not eight retention slots");
+  if (!Array.isArray(grants) || grants.length !== GRANT_SLOTS2)
+    return refuse2("not sixteen grant slots");
+  const pins = retentions.map((slot) => {
+    if (!isObject(slot) || !count(slot["generation"]))
+      return refuse2("a retention slot is out of shape");
+    const pin = slot["pin"];
+    if (pin === void 0 || pin === null)
+      return { generation: slot["generation"], until: void 0 };
+    if (!isObject(pin) || !count(pin["until"]) || typeof pin["root"] !== "string")
+      return refuse2("a retention pin is out of shape");
+    return { generation: slot["generation"], until: pin["until"] };
+  });
+  const live = [];
+  for (const slot of grants) {
+    if (!isObject(slot) || !count(slot["generation"]))
+      return refuse2("a grant slot is out of shape");
+    const grant = slot["grant"];
+    if (grant === void 0 || grant === null) continue;
+    const handle = isObject(grant) ? grant["retention"] : void 0;
+    if (!isObject(grant) || !count(grant["until"]) || !isObject(handle) || !count(handle["slot"]) || handle["slot"] >= RETENTION_SLOTS2 || !positive(handle["generation"])) {
+      return refuse2("a grant is out of shape");
+    }
+    live.push({
+      slot: handle["slot"],
+      generation: handle["generation"],
+      until: grant["until"]
+    });
+  }
+  return { closed: volume["closed"], control: kind, retentions: pins, grants: live };
+}
+function decodeSpool(reply) {
+  const refuse2 = (why) => {
+    throw new ScratchPadError(`sp spool-remove: ${why}`, "malformed_reply", false);
+  };
+  if (!isObject(reply) || typeof reply["present"] !== "boolean")
+    return refuse2("the reply says no spool state");
+  const present = reply["present"];
+  const keys = ["present", "files", "bytes", "removable", "applied"];
+  if (present) keys.push("phase");
+  if (!hasKeys(reply, keys) || present && (typeof reply["phase"] !== "string" || reply["phase"] === "") || !count(reply["files"]) || !count(reply["bytes"]) || typeof reply["removable"] !== "boolean" || typeof reply["applied"] !== "boolean") {
+    return refuse2("the spool state is out of shape");
+  }
+  return { present, removable: reply["removable"], applied: reply["applied"] };
+}
+function cleanupCannotHelp(view, at = now()) {
+  const maintenance = view.control === "close" || view.control === "apply";
+  if (view.closed && !maintenance)
+    return "the volume is closed, and no cleanup of this agent's is saved";
+  if (maintenance) return void 0;
+  const room = view.retentions.some(
+    (pin, slot) => pin.until === void 0 || // free
+    pin.until !== 0 && // expired, and no live grant names this exact handle
+    pin.until <= at && !view.grants.some(
+      (g) => g.slot === slot && g.generation === pin.generation && g.until > at
+    )
+  );
+  return room ? void 0 : "every retention slot holds a live pin";
+}
+function spCliScratchPad(options) {
+  if (!("creds" in options.nats) || options.nats.creds === void 0) {
+    throw new Error(
+      "ScratchPad: the sp CLI needs NATS_URL and NATS_CREDS; a NATS context or an nkey seed alone is not supported"
+    );
+  }
+  const connection = ["--url", options.nats.url, "--creds", options.nats.creds];
+  const bin = options.bin ?? DEFAULT_SP_BIN;
+  const configuredDir = options.dir ?? node_path.join(node_os.tmpdir(), `scratchpad-${options.volume}`);
+  const grantTtlS = Math.min(options.grantTtlS ?? DEFAULT_GRANT_TTL_S, DEFAULT_GRANT_TTL_S);
+  let dir;
+  let binding;
+  let mutations = Promise.resolve();
+  let mayHavePending = true;
+  let pendingGrant;
+  const ledger = /* @__PURE__ */ new Map();
+  function serialize(work) {
+    const next = mutations.then(work);
+    mutations = next.catch(() => void 0);
+    return next;
+  }
+  const expansions = /* @__PURE__ */ new Map();
+  async function resolveReference(token, trace) {
+    if (!token.startsWith(SHORT_REFERENCE_PREFIX2)) return decodeReference2(token);
+    decodeShortReference(token);
+    const cached = expansions.get(token);
+    if (cached && cached.expires_at > now()) return structuredClone(cached);
+    const reply = await sp(
+      "resolve",
+      ["--ref", token],
+      { trace }
+    );
+    const pair = { short: token, expanded: reply?.reference };
+    validateResolvedReference(pair);
+    if (reply.full_reference !== encodeReference(pair.expanded))
+      throw new ScratchPadError(
+        "sp resolve: expanded token differs from descriptor",
+        "malformed_reply",
+        false
+      );
+    const ref = decodeReference2(reply.full_reference);
+    if (ref.expires_at <= now()) throw new Error("the reference has expired");
+    expansions.delete(token);
+    expansions.set(token, ref);
+    if (expansions.size > 64) expansions.delete(expansions.keys().next().value);
+    return structuredClone(ref);
+  }
+  async function workspace() {
+    dir ??= (async () => {
+      await promises.mkdir(configuredDir, { recursive: true, mode: 448 });
+      return promises.realpath(configuredDir);
+    })();
+    return dir;
+  }
+  async function sp(command, args, opts = {}) {
+    const trace = opts.trace ? ["--thread-id", opts.trace.threadId, "--root-id", opts.trace.rootId] : [];
+    if (opts.trace && opts.toolCallId !== void 0) trace.push("--tool-call-id", opts.toolCallId);
+    const volume = ["read", "resolve"].includes(command) ? [] : ["--volume", options.volume];
+    const argv = [command, ...connection, "--dir", await workspace(), ...volume, ...args, ...trace];
+    const maxStdout = opts.maxStdout ?? MAX_STDOUT;
+    const { code, stdout, stderr } = await new Promise((resolve3) => {
+      const child = node_child_process.execFile(
+        bin,
+        argv,
+        { maxBuffer: Math.max(maxStdout, MAX_STDERR), encoding: "utf8" },
+        (err, stdout2, stderr2) => {
+          const e = err;
+          resolve3({
+            code: e === null ? 0 : typeof e.code === "number" ? e.code : null,
+            stdout: stdout2 ?? "",
+            stderr: stderr2 || (e !== null && typeof e.code === "string" ? e.message : "")
+          });
+        }
+      );
+      child.stdin?.end(opts.stdin ?? "");
+    });
+    if (code === null && /^spawn .*(ENOENT|EACCES)/m.test(stderr)) {
+      throw new ScratchPadError(`sp ${command}: ${stderr.trim()}`, "spawn_failed", false);
+    }
+    if (code === 0 && stdout.length <= maxStdout) {
+      try {
+        return JSON.parse(stdout);
+      } catch {
+      }
+    }
+    let failure = {
+      code: code === 0 ? "malformed_reply" : "failed",
+      message: stderr.trim().slice(0, 512) || `exit ${code ?? "by signal"}`,
+      unknown: opts.mutation === true
+    };
+    if (code !== 0) {
+      try {
+        const e = JSON.parse(stderr).error;
+        if (isObject(e) && typeof e["code"] === "string") {
+          failure = {
+            code: e["code"],
+            message: typeof e["message"] === "string" ? e["message"] : "",
+            unknown: e["unknown"] === true || opts.mutation === true && typeof e["unknown"] !== "boolean"
+          };
+        }
+      } catch {
+      }
+    }
+    throw new ScratchPadError(
+      `sp ${command}: ${failure.code}${failure.unknown ? " (outcome unknown)" : ""}: ${failure.message}`,
+      failure.code,
+      failure.unknown
+    );
+  }
+  function bind(reply, command) {
+    const r = reply;
+    const account = r?.principal?.account;
+    if (typeof account !== "string" || !ACCOUNT_RE.test(account) || !validTarget(r.target)) {
+      throw new ScratchPadError(
+        `sp ${command}: the reply names no principal and target`,
+        "malformed_reply",
+        false
+      );
+    }
+    if (r.target.volume !== options.volume) {
+      throw new ScratchPadError(
+        `sp ${command}: the workspace is bound to another volume`,
+        "invalid",
+        false
+      );
+    }
+    return { account, target: { volume: r.target.volume, creation_id: r.target.creation_id } };
+  }
+  async function init(trace) {
+    binding ??= bind(await sp("init", [], { trace, mutation: true }), "init");
+    return binding;
+  }
+  async function describe3(trace) {
+    if (binding !== void 0) return binding;
+    try {
+      binding = bind(await sp("describe", [], { trace }), "describe");
+    } catch (err) {
+      if (err instanceof ScratchPadError && NO_VOLUME_CODES.includes(err.code)) return void 0;
+      throw err;
+    }
+    return binding;
+  }
+  const ownedBy = (ref, b) => b !== void 0 && ref.account === b.account && ref.target.volume === b.target.volume && ref.target.creation_id === b.target.creation_id;
+  const ledgerKey = (ref, grantee) => JSON.stringify([
+    ref.account,
+    ref.target.volume,
+    ref.target.creation_id,
+    ref.root,
+    ref.path,
+    grantee.account,
+    grantee.user
+  ]);
+  function prune() {
+    const t = now();
+    for (const [key, until] of ledger) {
+      if (Math.max(until["first-hand"] ?? 0, until["on-request"] ?? 0) <= t) ledger.delete(key);
+    }
+  }
+  function record2(key, kind, expiresAt) {
+    ledger.set(key, { ...ledger.get(key), [kind]: expiresAt });
+  }
+  function grantExpiry(reply, ref) {
+    const r = reply;
+    if (!isObject(r) || !isObject(r.handle) || !positive(r.expires_at)) {
+      throw new ScratchPadError(
+        "sp grant: the reply names no handle and expiry",
+        "malformed_reply",
+        true
+      );
+    }
+    return Math.min(r.expires_at, ref.expires_at);
+  }
+  async function publish(bytes, path, operationId, trace) {
+    return sp(
+      "publish-file",
+      [
+        "--source",
+        "-",
+        "--path",
+        path,
+        "--operation-id",
+        operationId,
+        "--creator",
+        options.creator,
+        "--ttl-seconds",
+        String(HANDOFF_TTL_S)
+      ],
+      { trace, stdin: bytes, mutation: true }
+    );
+  }
+  async function recover(trace) {
+    if (!mayHavePending) return;
+    try {
+      await sp("recover", [], { trace, mutation: true });
+    } catch (err) {
+      if (!(err instanceof ScratchPadError) || err.unknown) throw err;
+    }
+    mayHavePending = false;
+  }
+  async function removeRefusedSpool(refusal2, trace) {
+    let why;
+    try {
+      const spool = decodeSpool(await sp("spool-remove", ["--apply"], { trace, mutation: true }));
+      if (!spool.present || spool.applied) return;
+      why = "the refused publication's spool is protected";
+    } catch (err) {
+      if (err instanceof ScratchPadError && err.unknown) throw err;
+      why = `its spool was not removed: ${err.message}`;
+    }
+    mayHavePending = true;
+    throw new ScratchPadError(
+      `${refusal2.message}; cleanup not started: ${why}`,
+      refusal2.code,
+      false
+    );
+  }
+  async function volumeView(trace) {
+    return decodeDescribe(await sp("describe", [], { trace }));
+  }
+  async function commit(text2, path, trace) {
+    if (options.creator === void 0) {
+      throw new Error(
+        "ScratchPad: a reference names its creator; this ScratchPad was made without one"
+      );
+    }
+    const own = await init(trace);
+    await recover(trace);
+    const operationId = node_crypto.randomUUID();
+    let reply;
+    try {
+      reply = await publish(text2, path, operationId, trace);
+    } catch (err) {
+      if (err instanceof ScratchPadError && err.unknown) mayHavePending = true;
+      if (!(err instanceof ScratchPadError) || err.code !== "capacity" || err.unknown) throw err;
+      await removeRefusedSpool(err, trace);
+      let reason;
+      try {
+        reason = cleanupCannotHelp(await volumeView(trace));
+      } catch (inspect) {
+        throw new ScratchPadError(
+          `${err.message}; cleanup not started: ${inspect.message}`,
+          err.code,
+          false
+        );
+      }
+      if (reason !== void 0)
+        throw new ScratchPadError(
+          `${err.message}; cleanup not started: ${reason}`,
+          err.code,
+          false
+        );
+      try {
+        await sp("maintain", ["--apply"], { trace, mutation: true });
+      } catch (cleanup) {
+        mayHavePending = true;
+        const unknown2 = !(cleanup instanceof ScratchPadError) || cleanup.unknown;
+        throw new ScratchPadError(
+          `${err.message}; cleanup: ${cleanup.message}`,
+          unknown2 && cleanup instanceof ScratchPadError ? cleanup.code : unknown2 ? "failed" : err.code,
+          unknown2
+        );
+      }
+      try {
+        reply = await publish(text2, path, operationId, trace);
+      } catch (again) {
+        if (again instanceof ScratchPadError && again.unknown) mayHavePending = true;
+        throw again;
+      }
+    }
+    const token = reply?.reference;
+    if (typeof token !== "string" || !isObject(reply.receipt)) {
+      mayHavePending = true;
+      throw new ScratchPadError(
+        "sp publish-file: the reply names no receipt and reference",
+        "malformed_reply",
+        true
+      );
+    }
+    const ref = await resolveReference(token, trace);
+    if (!ownedBy(ref, own) || ref.path !== path || ref.creator !== options.creator) {
+      throw new ScratchPadError(
+        "sp publish-file: the reference names another volume, path or creator",
+        "malformed_reply",
+        false
+      );
+    }
+    return token;
+  }
+  async function runGrant(args, trace, toolCallId, ref) {
+    return grantExpiry(await sp("grant", args, { trace, toolCallId, mutation: true }), ref);
+  }
+  async function grantRead(reference, grantee, trace, toolCallId, kind) {
+    const ref = await resolveReference(reference, trace);
+    if (!ownedBy(ref, await describe3(trace))) {
+      throw new Error(
+        "the reference points into another agent's volume; only its creator can grant read on it"
+      );
+    }
+    await recover(trace);
+    if (pendingGrant !== void 0) {
+      const earlier = pendingGrant;
+      try {
+        record2(
+          earlier.key,
+          earlier.kind,
+          await runGrant(earlier.args, void 0, void 0, earlier.ref)
+        );
+        pendingGrant = void 0;
+      } catch (err) {
+        if (!(err instanceof ScratchPadError) || err.unknown) throw err;
+        pendingGrant = void 0;
+      }
+    }
+    const remaining = ref.expires_at - now() - EXPIRY_MARGIN_S;
+    const ttl = Math.floor(Math.min(grantTtlS, remaining));
+    if (ttl < 1)
+      throw new Error(
+        "the reference has expired, or is about to; there is nothing left to grant on"
+      );
+    const key = ledgerKey(ref, grantee);
+    prune();
+    if (!ledger.has(key) && ledger.size >= MAX_LEDGER) {
+      throw new Error(
+        `this agent already holds ${MAX_LEDGER} live grants; try again when one expires`
+      );
+    }
+    const trail = trace ? ["--thread-id", trace.threadId, "--root-id", trace.rootId] : [];
+    if (trace && toolCallId !== void 0) trail.push("--tool-call-id", toolCallId);
+    const args = [
+      "--ref",
+      reference,
+      "--grantee-account",
+      grantee.account,
+      "--grantee-user",
+      grantee.user,
+      "--operation-id",
+      node_crypto.randomUUID(),
+      "--ttl-seconds",
+      String(ttl)
+    ];
+    try {
+      record2(key, kind, await runGrant(args, trace, toolCallId, ref));
+    } catch (err) {
+      if (err instanceof ScratchPadError && err.unknown)
+        pendingGrant = { args: [...args, ...trail], key, kind, ref };
+      throw err;
+    }
+  }
+  const pad = {
+    commit(text2, path, trace) {
+      return serialize(() => commit(text2, path, trace));
+    },
+    async read(reference, trace) {
+      const ref = await resolveReference(reference, trace);
+      if (ref.expires_at <= now()) throw new Error("the reference has expired");
+      const got = await sp(
+        "read",
+        ["--ref", reference],
+        {
+          trace,
+          maxStdout: MAX_READ_STDOUT
+        }
+      );
+      const { data_base64: data, bytes } = got ?? {};
+      if (typeof data !== "string" || !BASE64_RE.test(data) || !Number.isSafeInteger(bytes) || bytes > MAX_READ_BYTES2) {
+        throw new ScratchPadError("sp read: the reply carries no data", "malformed_reply", false);
+      }
+      const raw = Buffer.from(data, "base64");
+      if (raw.length !== bytes || raw.toString("base64") !== data) {
+        throw new ScratchPadError(
+          "sp read: the data does not match its length",
+          "malformed_reply",
+          false
+        );
+      }
+      try {
+        return new TextDecoder("utf-8", { fatal: true }).decode(raw);
+      } catch {
+        throw new Error("the referenced file is not UTF-8 text");
+      }
+    },
+    resolveReference,
+    async owns(reference) {
+      let ref;
+      try {
+        ref = await resolveReference(reference);
+      } catch {
+        return false;
+      }
+      return ownedBy(ref, await describe3(activeTrace()));
+    },
+    grantRead(reference, grantee, trace, toolCallId, kind = "first-hand") {
+      return serialize(() => grantRead(reference, grantee, trace, toolCallId, kind));
+    },
+    granted(reference, grantee) {
+      const find = (ref) => {
+        if (!ownedBy(ref, binding)) return void 0;
+        const until = ledger.get(ledgerKey(ref, grantee)), t = now();
+        if ((until?.["first-hand"] ?? 0) > t) return "first-hand";
+        if ((until?.["on-request"] ?? 0) > t) return "on-request";
+        return void 0;
+      };
+      if (reference.startsWith(SHORT_REFERENCE_PREFIX2))
+        return resolveReference(reference).then(find, () => void 0);
+      try {
+        return find(decodeReference2(reference));
+      } catch {
+        return void 0;
+      }
+    }
+  };
+  return pad;
+}
+var SCRATCHPAD_VOLUME_VAR = "SCRATCHPAD_VOLUME";
+var SCRATCHPAD_BIN_VAR = "SCRATCHPAD_BIN";
+var SCRATCHPAD_DIR_VAR = "SCRATCHPAD_DIR";
+var SCRATCHPAD_GRANT_TTL_S_VAR = "SCRATCHPAD_GRANT_TTL_S";
+function scratchPadFromEnv(env = process.env, options = {}) {
+  const optional = (name) => {
+    const value = env[name];
+    return value === void 0 || value === "" ? void 0 : value;
+  };
+  const volume = optional(SCRATCHPAD_VOLUME_VAR);
+  if (volume === void 0) return void 0;
+  const ttl = optional(SCRATCHPAD_GRANT_TTL_S_VAR);
+  let grantTtlS;
+  if (ttl !== void 0) {
+    grantTtlS = Number(ttl);
+    if (!Number.isFinite(grantTtlS) || grantTtlS <= 0) {
+      throw new Error(`${SCRATCHPAD_GRANT_TTL_S_VAR} must be a positive number, got "${ttl}"`);
+    }
+  }
+  const context = optional("NATS_CONTEXT");
+  const creds = optional("NATS_CREDS");
+  const url = optional("NATS_URL") ?? "nats://127.0.0.1:4222";
+  const nats = options.nats ?? (creds !== void 0 ? { url, creds } : context !== void 0 ? { context } : { url });
+  const bin = optional(SCRATCHPAD_BIN_VAR);
+  const dir = optional(SCRATCHPAD_DIR_VAR);
+  return spCliScratchPad({
+    volume,
+    nats,
+    ...bin !== void 0 ? { bin } : {},
+    ...dir !== void 0 ? { dir } : {},
+    ...grantTtlS !== void 0 ? { grantTtlS } : {},
+    ...options.creator !== void 0 ? { creator: options.creator } : {}
+  });
+}
+var LOOP_GUARD_CODE = 409;
+function loopGuardDescription(rootId) {
+  return `the agent's model is waiting inside a prompt of this tree (root ${rootId}); a prompt of the same tree cannot be served until that call returns`;
+}
+function openCalls(result) {
+  if (typeof result !== "object" || result === null || Array.isArray(result)) return void 0;
+  const open = result.open_calls;
+  if (open === void 0) return 0;
+  return typeof open === "number" && Number.isInteger(open) && open >= 0 ? open : void 0;
+}
+function isThenable(value) {
+  return (typeof value === "object" || typeof value === "function") && value !== null && typeof value.then === "function";
+}
+function loopGuard() {
+  const byScope = /* @__PURE__ */ new Map();
+  const byRoot = /* @__PURE__ */ new Map();
+  const waiting = (rootId) => {
+    const entries = byRoot.get(rootId);
+    if (entries === void 0) return false;
+    for (const entry of entries) if (entry.waiting) return true;
+    return false;
+  };
+  const toolCallEnded = (entry, returned, result) => {
+    entry.running -= 1;
+    const open = returned ? openCalls(result) : void 0;
+    if (open === void 0) return;
+    entry.open = open;
+    if (entry.running === 0 && entry.open === 0) entry.waiting = false;
+  };
+  return {
+    requestInterceptor: {
+      async aroundRequest(_ctx, next) {
+        const scope = activeTrace();
+        if (scope === void 0) {
+          await next();
+          return;
+        }
+        const { rootId } = scope;
+        if (waiting(rootId)) {
+          throw new agentService.RequestRejectedError(LOOP_GUARD_CODE, loopGuardDescription(rootId));
+        }
+        const entry = { rootId, waiting: false, running: 0, open: 0 };
+        byScope.set(scope, entry);
+        let ofRoot = byRoot.get(rootId);
+        if (ofRoot === void 0) byRoot.set(rootId, ofRoot = /* @__PURE__ */ new Set());
+        ofRoot.add(entry);
+        try {
+          await next();
+        } finally {
+          byScope.delete(scope);
+          ofRoot.delete(entry);
+          if (ofRoot.size === 0) byRoot.delete(rootId);
+        }
+      }
+    },
+    promptInterceptor: {
+      beforePrompt() {
+        const scope = activeTrace();
+        const entry = scope === void 0 ? void 0 : byScope.get(scope);
+        if (entry !== void 0) entry.waiting = true;
+      }
+    },
+    aroundToolCall(scope, run) {
+      const entry = scope === void 0 ? void 0 : byScope.get(scope);
+      if (entry === void 0) return run();
+      entry.running += 1;
+      let value;
+      try {
+        value = run();
+      } catch (err) {
+        toolCallEnded(entry, false);
+        throw err;
+      }
+      if (isThenable(value)) {
+        void value.then(
+          (result) => toolCallEnded(entry, true, result),
+          () => toolCallEnded(entry, false)
+        );
+      } else {
+        toolCallEnded(entry, true, value);
+      }
+      return value;
+    },
+    serving: (rootId) => byRoot.has(rootId),
+    waiting
+  };
+}
+function pathRequest(v) {
+  validateTarget(v.target);
+  validateContentID(v.root);
+  validatePath(v.path);
+  validateTrace(v.trace);
+}
+function validateRequest(verb, value) {
+  switch (verb) {
+    case "reference.info":
+    case "info":
+      validateEmpty(value);
+      return;
+    case "volume.create": {
+      const v = record(value, ["volume", "action"]);
+      validateVolume(v.volume);
+      validateAction(v.action);
+      return;
+    }
+    case "volume.get": {
+      const v = record(value, ["target"]);
+      validateTarget(v.target);
+      return;
+    }
+    case "object.prepare": {
+      const v = record(value, ["target", "objects"]);
+      validateTarget(v.target);
+      check(
+        Array.isArray(v.objects) && v.objects.length > 0 && v.objects.length <= MAX_PREPARE_OBJECTS,
+        "invalid preparation count"
+      );
+      const seen = /* @__PURE__ */ new Set();
+      for (const raw of v.objects) {
+        validateObjectSpec(raw);
+        const key = raw.object.kind + ":" + raw.object.id;
+        check(!seen.has(key), "duplicate preparation object");
+        seen.add(key);
+      }
+      return;
+    }
+    case "object.verify": {
+      const v = record(value, ["target", "epoch", "objects"]);
+      validateTarget(v.target);
+      uint(v.epoch);
+      check(
+        Array.isArray(v.objects) && v.objects.length > 0 && v.objects.length <= MAX_PREPARE_OBJECTS,
+        "invalid verification count"
+      );
+      const seen = /* @__PURE__ */ new Set();
+      for (const raw of v.objects) {
+        validateContentObject(raw);
+        const key = raw.kind + ":" + raw.id;
+        check(!seen.has(key), "duplicate verification object");
+        seen.add(key);
+      }
+      return;
+    }
+    case "object.put": {
+      const v = record(value, ["target", "object", "epoch"]);
+      validateTarget(v.target);
+      validateContentObject(v.object);
+      uint(v.epoch);
+      return;
+    }
+    case "reference.retain":
+      validateReferenceRetainRequest(value);
+      return;
+    case "reference.publish":
+    case "reference.receipt":
+      validateReferencePublishRequest(value);
+      return;
+    case "reference.resolve":
+    case "reference.stat": {
+      const v = record(value, ["reference", "trace"]);
+      text(v.reference, SHORT_REFERENCE_BYTES, SHORT_REFERENCE_BYTES);
+      decodeShortReference(v.reference);
+      validateTrace(v.trace);
+      return;
+    }
+    case "checkpoint.publish": {
+      const v = record(value, ["target", "command"]);
+      validateTarget(v.target);
+      validateCommand(v.command);
+      check(
+        v.target.creation_id === v.command.creation_id,
+        "command names another creation identity"
+      );
+      return;
+    }
+    case "writer.reset": {
+      const v = record(value, ["target", "writer"]);
+      validateTarget(v.target);
+      validateWriter(v.writer);
+      return;
+    }
+    case "root.retain": {
+      const v = record(value, ["target", "slot", "generation", "root", "until", "action"]);
+      validateTarget(v.target);
+      uint(v.slot, RETENTION_SLOTS - 1);
+      uint(v.generation);
+      validateContentID(v.root);
+      uint(v.until);
+      validateAction(v.action);
+      return;
+    }
+    case "root.release": {
+      const v = record(value, ["target", "handle"]);
+      validateTarget(v.target);
+      validateRetentionHandle(v.handle);
+      return;
+    }
+    case "grant.issue": {
+      const v = record(value, [
+        "target",
+        "slot",
+        "generation",
+        "principal",
+        "root",
+        "path",
+        "retention",
+        "until",
+        "action"
+      ]);
+      validateTarget(v.target);
+      uint(v.slot, GRANT_SLOTS - 1);
+      uint(v.generation);
+      validatePrincipal(v.principal);
+      validateContentID(v.root);
+      validatePath(v.path, 256);
+      validateRetentionHandle(v.retention);
+      uint(v.until, void 0, 1);
+      validateAction(v.action);
+      return;
+    }
+    case "grant.revoke": {
+      const v = record(value, ["target", "handle", "action"]);
+      validateTarget(v.target);
+      validateGrantHandle(v.handle);
+      validateAction(v.action);
+      return;
+    }
+    case "content.stat": {
+      const v = record(value, ["target", "root", "path", "trace"]);
+      pathRequest(v);
+      return;
+    }
+    case "content.read": {
+      const v = record(value, ["target", "root", "path", "trace", "offset", "length"]);
+      pathRequest(v);
+      uint(v.offset);
+      uint(v.length, MAX_READ_BYTES, 1);
+      return;
+    }
+    case "content.list": {
+      const v = record(value, ["target", "root", "path", "trace", "offset", "limit"]);
+      pathRequest(v);
+      uint(v.offset, 4294967295);
+      uint(v.limit, 64, 1);
+      return;
+    }
+    case "maintenance.close":
+    case "maintenance.plan":
+    case "maintenance.apply": {
+      const v = record(value, ["target", "revision"]);
+      validateTarget(v.target);
+      uint(v.revision, void 0, 1);
+      return;
+    }
+    default:
+      throw invalid("unknown ScratchPad verb");
+  }
+}
+var ScratchPadTransport = class {
+  constructor(nc, options = {}) {
+    this.nc = nc;
+    check(nc && !nc.isClosed() && !nc.isDraining(), "an open NATS connection is required");
+    check(nc.info?.headers === true, "NATS header support is required");
+    check(
+      (nc.info?.max_payload ?? 0) >= MAX_NODE_BYTES + MAX_HEADER_BYTES,
+      "NATS max_payload cannot carry the largest canonical object"
+    );
+    this.timeoutMs = options.timeoutMs ?? 1e4;
+    uint(this.timeoutMs, 5 * 60 * 1e3, 1);
+  }
+  nc;
+  timeoutMs;
+  async within(work, deadline, signal) {
+    void work.catch(() => {
+    });
+    if (signal?.aborted) throw signal.reason ?? new Error("operation cancelled");
+    const remaining = deadline - performance.now();
+    if (remaining <= 0) throw new Error("request deadline exceeded");
+    return new Promise((resolve3, reject2) => {
+      const timer = setTimeout(() => {
+        cleanup();
+        reject2(new Error("request deadline exceeded"));
+      }, remaining);
+      const cancel = () => {
+        cleanup();
+        const cause = signal?.reason;
+        reject2(cause instanceof Error ? cause : new Error("operation cancelled", { cause }));
+      };
+      const cleanup = () => {
+        clearTimeout(timer);
+        signal?.removeEventListener("abort", cancel);
+      };
+      signal?.addEventListener("abort", cancel, { once: true });
+      void work.then(
+        (value) => {
+          cleanup();
+          resolve3(value);
+        },
+        (error) => {
+          cleanup();
+          reject2(error instanceof Error ? error : new Error("request failed", { cause: error }));
+        }
+      );
+    });
+  }
+  async exchange(verb, body, mutation, ranged, options, metadata) {
+    let headerBytes = 0;
+    const requestHeaders = metadata === void 0 ? void 0 : natsCore.headers();
+    if (metadata !== void 0) {
+      headerBytes = 12 + Buffer.byteLength(METADATA_HEADER) + 4 + Buffer.byteLength(metadata);
+      check(
+        headerBytes <= MAX_HEADER_BYTES && !/[\r\n\0]/.test(metadata),
+        "invalid request header"
+      );
+      requestHeaders.set(METADATA_HEADER, metadata);
+    }
+    check(
+      body.length + headerBytes <= (this.nc.info?.max_payload ?? 0),
+      "request exceeds NATS payload bound"
+    );
+    const deadline = performance.now() + this.timeoutMs;
+    try {
+      if (options.signal?.aborted || this.nc.isClosed() || this.nc.isDraining())
+        throw new Error("connection or signal closed before transmission");
+      await this.within(this.nc.flush(), deadline, options.signal);
+      if (options.signal?.aborted || this.nc.isClosed() || this.nc.isDraining())
+        throw new Error("connection or signal closed before transmission");
+      if (deadline <= performance.now()) throw new Error("deadline ended before transmission");
+      check(this.nc.info?.headers === true, "NATS header support is required");
+      check(
+        body.length + headerBytes <= (this.nc.info?.max_payload ?? 0),
+        "request exceeds current NATS payload bound"
+      );
+    } catch (cause) {
+      throw new NativeScratchPadError("unavailable", "request not transmitted", {
+        local: true,
+        cause
+      });
+    }
+    let reply;
+    try {
+      const request = this.nc.request(SUBJECT_PREFIX + verb, body, {
+        timeout: Math.max(1, Math.ceil(deadline - performance.now())),
+        ...requestHeaders === void 0 ? {} : { headers: requestHeaders }
+      });
+      reply = await this.within(request, deadline, options.signal);
+    } catch (cause) {
+      throw new NativeScratchPadError(
+        mutation ? "unknown" : "unavailable",
+        "request returned no trustworthy reply",
+        { unknown: mutation, cause }
+      );
+    }
+    try {
+      let count2 = 0, size = 12, value = "";
+      for (const [key, values] of reply.headers ?? []) {
+        for (const item of values) size += Buffer.byteLength(key) + 4 + Buffer.byteLength(item);
+        if (key.toLowerCase() === REPLY_HEADER.toLowerCase()) {
+          count2 += values.length;
+          value = values[0] ?? "";
+        }
+      }
+      check(
+        size <= MAX_HEADER_BYTES && count2 === 1,
+        "reply must have one bounded ScratchPad-Reply header"
+      );
+      const meta = parseStrictJSON(value, MAX_HEADER_BYTES);
+      validateReplyMetadata(meta);
+      if (meta.code !== "ok") {
+        check(reply.data.length === 0, "error reply has a body");
+        throw new NativeScratchPadError(meta.code, meta.message, {
+          unknown: mutation && ["unknown", "unavailable", "internal"].includes(meta.code)
+        });
+      }
+      check(ranged === (meta.range !== void 0), "reply range does not match verb");
+      check(
+        reply.data.length <= (ranged ? MAX_READ_BYTES : MAX_REPLY_BYTES),
+        "reply body exceeds bound"
+      );
+      return { metadata: meta, body: reply.data };
+    } catch (cause) {
+      if (cause instanceof NativeScratchPadError && !cause.local) throw cause;
+      throw failed(mutation, "reply metadata is malformed", cause);
+    }
+  }
+  async control(verb, request, validate, mutation, options) {
+    validateRequest(verb, request);
+    const body = Buffer.from(goJSON(request));
+    check(body.length <= MAX_CONTROL_BYTES, "control request exceeds bound");
+    const reply = await this.exchange(verb, body, mutation, false, options);
+    try {
+      const result = parseStrictJSON(reply.body, MAX_REPLY_BYTES);
+      validate(result);
+      return result;
+    } catch (cause) {
+      throw failed(mutation, "reply body is malformed", cause);
+    }
+  }
+  matching(condition, mutation, detail) {
+    if (!condition) throw failed(mutation, detail);
+  }
+  async view(verb, target, request, mutation, options) {
+    const result = await this.control(verb, request, validateVolumeView, mutation, options);
+    this.matching(
+      sameValue(result.target, target),
+      mutation,
+      "reply names another volume incarnation"
+    );
+    return result;
+  }
+  info(options = {}) {
+    return this.control("info", {}, validateInfo, false, options);
+  }
+  async createVolume(request, options = {}) {
+    const expected = structuredClone(request);
+    const result = await this.control(
+      "volume.create",
+      expected,
+      validateVolumeView,
+      true,
+      options
+    );
+    this.matching(result.target.volume === expected.volume, true, "reply names another volume");
+    return result;
+  }
+  getVolume(target, options = {}) {
+    const expected = structuredClone(target);
+    return this.view("volume.get", expected, { target: expected }, false, options);
+  }
+  async prepare(request, options = {}) {
+    const expected = structuredClone(request);
+    const result = await this.control(
+      "object.prepare",
+      expected,
+      validatePrepareResult,
+      true,
+      options
+    );
+    this.matching(
+      result.objects.length === expected.objects.length && result.objects.every(
+        (progress, index) => sameValue(progress.object, expected.objects[index].object) && progress.length === expected.objects[index].length
+      ),
+      true,
+      "preparation reply names other objects"
+    );
+    return result;
+  }
+  async putPrepared(request, data, options = {}) {
+    const expected = structuredClone(request), bytes = Uint8Array.from(data);
+    validateRequest("object.put", expected);
+    check(bytes.length > 0 && bytes.length <= MAX_NODE_BYTES, "object bytes exceed bound");
+    try {
+      verifyObject(expected.object, bytes);
+    } catch (cause) {
+      throw invalid("object bytes differ from canonical identity", cause);
+    }
+    const reply = await this.exchange(
+      "object.put",
+      bytes,
+      true,
+      false,
+      options,
+      goJSON(expected)
+    );
+    try {
+      validateEmpty(parseStrictJSON(reply.body, MAX_REPLY_BYTES));
+    } catch (cause) {
+      throw failed(true, "put reply body is malformed", cause);
+    }
+  }
+  async verify(request, options = {}) {
+    const expected = structuredClone(request);
+    const result = await this.control(
+      "object.verify",
+      expected,
+      validateVerifyResult,
+      true,
+      options
+    );
+    this.matching(
+      result.epoch === expected.epoch && result.objects.length === expected.objects.length && result.objects.every(
+        (progress, index) => sameValue(progress.object, expected.objects[index])
+      ),
+      true,
+      "verification reply names other objects or epoch"
+    );
+    return result;
+  }
+  async publish(request, options = {}) {
+    const expected = structuredClone(request);
+    const result = await this.control(
+      "checkpoint.publish",
+      expected,
+      validateReceipt,
+      true,
+      options
+    );
+    const normalize = (command) => ({
+      ...command,
+      trace: Object.fromEntries(Object.entries(command.trace).filter(([, value]) => value !== ""))
+    });
+    this.matching(
+      result.volume === expected.target.volume && sameValue(normalize(result.command), normalize(expected.command)),
+      true,
+      "receipt names another command"
+    );
+    return result;
+  }
+  /** Unknown reference verbs on older services return invalid. Other failures propagate. */
+  async referenceInfo(options = {}) {
+    try {
+      return await this.control(
+        "reference.info",
+        {},
+        validateReferenceCapabilities,
+        false,
+        options
+      );
+    } catch (error) {
+      if (error instanceof NativeScratchPadError && error.code === "invalid" && !error.local && !error.unknown)
+        return void 0;
+      throw error;
+    }
+  }
+  async referencePublication(verb, request, options) {
+    const expected = structuredClone(request), mutation = verb === "reference.publish";
+    const result = await this.control(
+      verb,
+      expected,
+      validateReferencePublishResult,
+      mutation,
+      options
+    );
+    this.matching(
+      result.receipt.volume === expected.target.volume && sameValue(
+        {
+          ...result.receipt.command,
+          trace: Object.fromEntries(
+            Object.entries(result.receipt.command.trace).filter(([, value]) => value !== "")
+          )
+        },
+        {
+          ...expected.command,
+          trace: Object.fromEntries(
+            Object.entries(expected.command.trace).filter(([, value]) => value !== "")
+          )
+        }
+      ) && result.references.length === expected.reference.paths.length && result.references.every(
+        (pair, index) => pair.expanded.creator === expected.reference.creator && pair.expanded.path === expected.reference.paths[index]
+      ),
+      mutation,
+      "referenced receipt names another intent"
+    );
+    return result;
+  }
+  referencePublish(request, options = {}) {
+    return this.referencePublication("reference.publish", request, options);
+  }
+  referenceReceipt(request, options = {}) {
+    return this.referencePublication("reference.receipt", request, options);
+  }
+  async referenceResolve(request, options = {}) {
+    const expected = structuredClone(request);
+    const result = await this.control(
+      "reference.resolve",
+      expected,
+      validateResolvedReference,
+      false,
+      options
+    );
+    this.matching(result.short === expected.reference, false, "resolution names another reference");
+    return result;
+  }
+  async referenceStat(request, options = {}) {
+    const expected = structuredClone(request);
+    const result = await this.control(
+      "reference.stat",
+      expected,
+      validateReferenceStatResult,
+      false,
+      options
+    );
+    this.matching(
+      result.reference.short === expected.reference,
+      false,
+      "stat names another reference"
+    );
+    return result;
+  }
+  async referenceRetain(request, options = {}) {
+    const expected = structuredClone(request), retain = expected.retain;
+    const result = await this.control(
+      "reference.retain",
+      expected,
+      validateReferenceRetainResult,
+      true,
+      options
+    );
+    this.matching(
+      sameValue(result.volume.target, retain.target) && result.references.length === expected.reference.paths.length && result.references.every(
+        (pair, index) => pair.expanded.creator === expected.reference.creator && pair.expanded.path === expected.reference.paths[index] && pair.expanded.root === retain.root && pair.expanded.expires_at === retain.until && pair.expanded.retention.slot === retain.slot && pair.expanded.retention.generation === retain.generation + 1
+      ),
+      true,
+      "retained references name another intent"
+    );
+    return result;
+  }
+  async resetWriter(target, writer, options = {}) {
+    const expected = structuredClone({ target, writer });
+    const result = await this.control("writer.reset", expected, validateWriter, true, options);
+    this.matching(
+      result.slot === expected.writer.slot && result.generation > expected.writer.generation,
+      true,
+      "reset reply names another writer generation"
+    );
+    return result;
+  }
+  retain(request, options = {}) {
+    const expected = structuredClone(request);
+    return this.view("root.retain", expected.target, expected, true, options);
+  }
+  release(request, options = {}) {
+    const expected = structuredClone(request);
+    return this.view("root.release", expected.target, expected, true, options);
+  }
+  async issueGrant(request, options = {}) {
+    const expected = structuredClone(request);
+    const result = await this.control(
+      "grant.issue",
+      expected,
+      validateGrantHandle,
+      true,
+      options
+    );
+    this.matching(
+      result.slot === expected.slot && result.generation > expected.generation,
+      true,
+      "grant reply names another slot generation"
+    );
+    return result;
+  }
+  revokeGrant(request, options = {}) {
+    const expected = structuredClone(request);
+    return this.view("grant.revoke", expected.target, expected, true, options);
+  }
+  stat(request, options = {}) {
+    return this.control("content.stat", structuredClone(request), validateStat, false, options);
+  }
+  async list(request, options = {}) {
+    const expected = structuredClone(request);
+    const result = await this.control(
+      "content.list",
+      expected,
+      validateListResult,
+      false,
+      options
+    );
+    this.matching(
+      result.entries.length <= expected.limit && result.next === expected.offset + result.entries.length,
+      false,
+      "list result differs from requested window"
+    );
+    return result;
+  }
+  async read(request, options = {}) {
+    const expected = structuredClone(request);
+    validateRequest("content.read", expected);
+    const data = Buffer.from(goJSON(expected));
+    check(data.length <= MAX_CONTROL_BYTES, "read request exceeds bound");
+    const reply = await this.exchange("content.read", data, false, true, options), range = reply.metadata.range;
+    this.matching(
+      range.offset === expected.offset && range.length === Math.min(expected.length, range.stat.size - range.offset) && reply.body.length === range.length,
+      false,
+      "range result differs from request"
+    );
+    return { stat: range.stat, offset: range.offset, data: reply.body };
+  }
+  closeVolume(request, options = {}) {
+    const expected = structuredClone(request);
+    return this.view("maintenance.close", expected.target, expected, true, options);
+  }
+  planCollection(request, options = {}) {
+    return this.control(
+      "maintenance.plan",
+      structuredClone(request),
+      validateCollectionReport,
+      false,
+      options
+    );
+  }
+  async applyCollection(request, options = {}) {
+    const expected = structuredClone(request);
+    const result = await this.control(
+      "maintenance.apply",
+      expected,
+      validateCollectionResult,
+      true,
+      options
+    );
+    this.matching(
+      sameValue(result.volume.target, expected.target),
+      true,
+      "collection names another volume incarnation"
+    );
+    return result;
+  }
+};
+
+// src/scratchpad-native/reader.ts
+var DEFAULT_READ_LIMIT_BYTES = 16 * 1024 * 1024;
+function wireTrace(trace, toolCallId) {
+  const result = trace ? { thread_id: trace.threadId, root_id: trace.rootId } : {};
+  if (toolCallId) result.tool_call_id = toolCallId;
+  validateTrace(result);
+  return Object.fromEntries(Object.entries(result).filter(([, value]) => value !== ""));
+}
+var ScratchPadReader = class {
+  constructor(transport, principal) {
+    this.transport = transport;
+    this.principal = principal;
+  }
+  transport;
+  principal;
+  expansions = /* @__PURE__ */ new Map();
+  reference(token) {
+    return this.checkedReference(decodeReference(token));
+  }
+  checkedReference(reference) {
+    if (reference.account !== this.principal.account)
+      throw new NativeScratchPadError("denied", "reference belongs to another account", {
+        local: true
+      });
+    this.checkDeadline(reference.expires_at);
+    return reference;
+  }
+  checkDeadline(expiresAt) {
+    if (Date.now() >= expiresAt * 1e3)
+      throw new NativeScratchPadError("expired", "reference has expired", { local: true });
+  }
+  cacheReference(pair) {
+    this.expansions.delete(pair.short);
+    this.expansions.set(pair.short, structuredClone(pair.expanded));
+    if (this.expansions.size > 64) this.expansions.delete(this.expansions.keys().next().value);
+  }
+  /** Expand either form for programmatic use. Metadata supplies no read authority. */
+  async resolveReference(token, trace) {
+    if (!token.startsWith(SHORT_REFERENCE_PREFIX2)) return this.reference(token);
+    decodeShortReference(token);
+    const cached = this.expansions.get(token);
+    if (cached) return this.checkedReference(structuredClone(cached));
+    const pair = await this.transport.referenceResolve({
+      reference: token,
+      trace: wireTrace(trace)
+    });
+    this.checkedReference(pair.expanded);
+    this.cacheReference(pair);
+    return structuredClone(pair.expanded);
+  }
+  async openFile(token, options) {
+    const limit = options.limitBytes ?? DEFAULT_READ_LIMIT_BYTES;
+    uint(limit, MAX_VOLUME_BYTES);
+    const resolved = token.startsWith(SHORT_REFERENCE_PREFIX2) ? await this.transport.referenceStat({ reference: token, trace: wireTrace(options.trace) }) : void 0;
+    const reference = resolved ? this.checkedReference(resolved.reference.expanded) : this.reference(token);
+    if (resolved) this.cacheReference(resolved.reference);
+    const request = {
+      target: reference.target,
+      root: reference.root,
+      path: reference.path,
+      trace: wireTrace(options.trace)
+    };
+    const stat = resolved?.stat ?? await this.transport.stat(request);
+    this.checkDeadline(reference.expires_at);
+    check(stat.type === "file", "reference does not name a file");
+    if (stat.size > limit)
+      throw new NativeScratchPadError(
+        "capacity",
+        `file has ${stat.size} bytes; read limit is ${limit}`,
+        { local: true }
+      );
+    return { request, stat, expiresAt: reference.expires_at };
+  }
+  async *chunks(request, stat, expiresAt) {
+    this.checkDeadline(expiresAt);
+    const chunks = [], digest = node_crypto.createHash("sha256");
+    for (let offset = 0; offset < stat.size; offset += CHUNK_SIZE) {
+      const length = Math.min(CHUNK_SIZE, stat.size - offset);
+      this.checkDeadline(expiresAt);
+      const result = await this.transport.read({ ...request, offset, length });
+      this.checkDeadline(expiresAt);
+      if (!sameValue(stat, result.stat) || result.offset !== offset || result.data.length !== length) {
+        throw new NativeScratchPadError("corrupt", "read range differs from the immutable file");
+      }
+      digest.update(result.data);
+      chunks.push({ id: chunkID(result.data), length });
+      yield result.data;
+      this.checkDeadline(expiresAt);
+    }
+    const sha256 = digest.digest("hex");
+    const object = fileObjectID(encodeFileObject({ size: stat.size, digest: sha256, chunks }));
+    this.checkDeadline(expiresAt);
+    if (sha256 !== stat.sha256 || object !== stat.object)
+      throw new NativeScratchPadError("corrupt", "file bytes differ from their digest or identity");
+  }
+  /** Returns bytes only after size, logical digest and canonical file identity agree. */
+  async readBytes(token, options = {}) {
+    const { request, stat, expiresAt } = await this.openFile(token, options);
+    const output = new Uint8Array(stat.size);
+    let offset = 0;
+    for await (const bytes of this.chunks(request, stat, expiresAt)) {
+      output.set(bytes, offset);
+      offset += bytes.length;
+    }
+    this.checkDeadline(expiresAt);
+    return output;
+  }
+  /** Bytes are provisional until iteration completes without error. Consume to EOF
+   * and publish a downloaded file only after success; early cancellation is unverified.
+   * The caller must set an explicit whole-file size allowance.
+   */
+  async *readStream(token, options) {
+    uint(options?.limitBytes, MAX_VOLUME_BYTES);
+    const { request, stat, expiresAt } = await this.openFile(token, options);
+    yield* this.chunks(request, stat, expiresAt);
+    this.checkDeadline(expiresAt);
+  }
+  async read(reference, trace) {
+    return new TextDecoder("utf-8", { fatal: true }).decode(
+      await this.readBytes(reference, trace ? { trace } : {})
+    );
+  }
+};
+async function scratchPadReader(options) {
+  const transport = new ScratchPadTransport(options.nc, options);
+  const info = await transport.info();
+  return new ScratchPadReader(transport, info.principal);
+}
+var STATE_LIMIT = 128 * 1024;
+var OWNERS = /* @__PURE__ */ Symbol.for("synadia.fabric.scratchpad.workspace-owners.v1");
+var globals = globalThis;
+var owners = globals[OWNERS] ??= /* @__PURE__ */ new Set();
+var WorkspaceStore = class _WorkspaceStore {
+  constructor(db, directory) {
+    this.db = db;
+    this.directory = directory;
+  }
+  db;
+  directory;
+  poisoned = false;
+  closed = false;
+  static async open(directory) {
+    check(
+      typeof directory === "string" && directory.length > 0,
+      "a persistent workspace directory is required"
+    );
+    const [major, minor] = process.versions.node.split(".").map(Number);
+    check(
+      major > 22 || major === 22 && minor >= 13,
+      "native ScratchPad requires Node 22.13 or later"
+    );
+    const { DatabaseSync } = await import('node:sqlite');
+    const requested = node_path.resolve(directory);
+    node_fs.mkdirSync(requested, { recursive: true, mode: 448 });
+    const directoryStat = node_fs.lstatSync(requested);
+    check(
+      directoryStat.isDirectory() && !directoryStat.isSymbolicLink(),
+      "workspace must be a real directory"
+    );
+    check(
+      process.platform === "win32" || (directoryStat.mode & 63) === 0,
+      "workspace directory must have mode 0700"
+    );
+    const canonical = node_fs.realpathSync(requested);
+    if (owners.has(canonical))
+      throw new NativeScratchPadError("busy", "workspace is already open in this process", {
+        local: true
+      });
+    owners.add(canonical);
+    let db;
+    try {
+      const file = node_path.join(canonical, "scratchpad.sqlite");
+      try {
+        const fd = node_fs.openSync(
+          file,
+          node_fs.constants.O_CREAT | node_fs.constants.O_EXCL | node_fs.constants.O_WRONLY | (node_fs.constants.O_NOFOLLOW ?? 0),
+          384
+        );
+        try {
+          node_fs.fsyncSync(fd);
+        } finally {
+          node_fs.closeSync(fd);
+        }
+        if (process.platform !== "win32") {
+          const parent = node_fs.openSync(canonical, node_fs.constants.O_RDONLY);
+          try {
+            node_fs.fsyncSync(parent);
+          } finally {
+            node_fs.closeSync(parent);
+          }
+        }
+      } catch (error) {
+        if (error.code !== "EEXIST") throw error;
+      }
+      const stat = node_fs.lstatSync(file);
+      check(
+        stat.isFile() && !stat.isSymbolicLink() && stat.nlink === 1,
+        "workspace database must be a private regular file"
+      );
+      check(
+        process.platform === "win32" || (stat.mode & 63) === 0,
+        "workspace database must have mode 0600"
+      );
+      db = new DatabaseSync(file);
+      db.exec(
+        "PRAGMA busy_timeout=0; PRAGMA locking_mode=EXCLUSIVE; PRAGMA journal_mode=DELETE; PRAGMA synchronous=EXTRA; PRAGMA fullfsync=ON; BEGIN EXCLUSIVE; COMMIT;"
+      );
+      db.exec(
+        "CREATE TABLE IF NOT EXISTS state (id INTEGER PRIMARY KEY CHECK(id=1), value TEXT NOT NULL); CREATE TABLE IF NOT EXISTS objects (kind TEXT NOT NULL, id TEXT NOT NULL, ordinal INTEGER NOT NULL, body BLOB NOT NULL, PRIMARY KEY(kind,id)); CREATE INDEX IF NOT EXISTS object_order ON objects(ordinal);"
+      );
+      return new _WorkspaceStore(db, canonical);
+    } catch (cause) {
+      db?.close();
+      owners.delete(canonical);
+      if (cause instanceof NativeScratchPadError) throw cause;
+      throw new NativeScratchPadError("busy", "cannot exclusively open the workspace database", {
+        local: true,
+        cause
+      });
+    }
+  }
+  usable() {
+    check(
+      !this.closed && !this.poisoned,
+      "workspace is closed or had a write failure; close and reopen it"
+    );
+  }
+  load() {
+    this.usable();
+    const row = this.db.prepare("SELECT value FROM state WHERE id=1").get();
+    return row ? parseStrictJSON(String(row.value), STATE_LIMIT) : void 0;
+  }
+  save(state, afterRemote = false, clearObjects = false) {
+    this.usable();
+    try {
+      const json = JSON.stringify(state);
+      check(Buffer.byteLength(json) <= STATE_LIMIT, "workspace metadata exceeds its byte bound");
+      this.db.exec("BEGIN IMMEDIATE");
+      this.db.prepare(
+        "INSERT INTO state(id,value) VALUES(1,?) ON CONFLICT(id) DO UPDATE SET value=excluded.value"
+      ).run(json);
+      if (clearObjects) this.db.exec("DELETE FROM objects");
+      this.db.exec("COMMIT");
+    } catch (cause) {
+      this.poisoned = true;
+      if (this.db.isTransaction) this.db.exec("ROLLBACK");
+      throw new NativeScratchPadError(
+        "unavailable",
+        "workspace write failed; close and reopen before recovery",
+        { local: true, unknown: afterRemote, cause }
+      );
+    }
+  }
+  clearObjects() {
+    this.usable();
+    this.db.exec("DELETE FROM objects");
+  }
+  putObject(ordinal, object, data) {
+    this.usable();
+    uint(ordinal);
+    check(data.length > 0 && data.length <= MAX_NODE_BYTES, "spool object exceeds bound");
+    verifyObject(object, data);
+    this.db.prepare(
+      "INSERT INTO objects(kind,id,ordinal,body) VALUES(?,?,?,?) ON CONFLICT(kind,id) DO NOTHING"
+    ).run(object.kind, object.id, ordinal, data);
+  }
+  objects() {
+    this.usable();
+    return this.db.prepare("SELECT kind,id,length(body) AS length FROM objects ORDER BY ordinal").all().map((row) => ({
+      object: { kind: row.kind, id: String(row.id) },
+      length: Number(row.length)
+    }));
+  }
+  bytes(object) {
+    this.usable();
+    const row = this.db.prepare("SELECT body FROM objects WHERE kind=? AND id=?").get(object.kind, object.id);
+    check(row?.body instanceof Uint8Array, "saved publication payload is missing");
+    verifyObject(object, row.body);
+    return row.body;
+  }
+  close() {
+    if (this.closed) return;
+    this.db.close();
+    this.closed = true;
+    owners.delete(this.directory);
+  }
+};
+
+// src/scratchpad-native/client.ts
+function now2() {
+  return Math.floor(Date.now() / 1e3);
+}
+function refuse(code, message) {
+  throw new NativeScratchPadError(code, message, { local: true });
+}
+function unknown(error, message) {
+  return new NativeScratchPadError(
+    error instanceof NativeScratchPadError ? error.code : "unknown",
+    message,
+    { unknown: true, cause: error }
+  );
+}
+function validateState(value) {
+  const s = record(
+    value,
+    ["version", "principal", "volume", "creator", "creation", "next", "grants"],
+    ["target", "writer", "pending", "last"]
+  );
+  check(s.version === 1, "unsupported workspace version");
+  validatePrincipal(s.principal);
+  validateVolume(s.volume);
+  text(s.creator, 512, 1);
+  validateAction(s.creation);
+  uint(s.next, void 0, 1);
+  if (s.target !== void 0) {
+    validateTarget(s.target);
+    check(s.target.volume === s.volume, "workspace target differs from volume");
+  }
+  if (s.writer !== void 0) {
+    validateWriter(s.writer);
+    check(s.writer.slot === 0 && s.target, "workspace writer binding is invalid");
+  }
+  check(Array.isArray(s.grants) && s.grants.length <= 16, "workspace grant ledger exceeds bound");
+  for (const raw of s.grants) {
+    const g = record(raw, ["request", "handle", "kind"]);
+    check(g.kind === "first-hand" || g.kind === "on-request", "invalid grant provenance");
+    validateGrant(g.request);
+    const h = record(g.handle, ["slot", "generation"]);
+    uint(h.slot, 15);
+    uint(h.generation, void 0, 1);
+  }
+  if (s.last !== void 0) {
+    const last = record(s.last, ["reference", "receipt", "path", "ttl"], ["resolved"]);
+    validateReceipt(last.receipt);
+    text(last.reference, 8192, 1);
+    let reference;
+    if (last.reference.startsWith(SHORT_REFERENCE_PREFIX2)) {
+      validateResolvedReference(last.resolved);
+      validateReferencePublishResult({ receipt: last.receipt, references: [last.resolved] });
+      check(last.resolved.short === last.reference, "saved short reference differs");
+      reference = last.resolved.expanded;
+    } else {
+      check(last.resolved === void 0, "full reference has unexpected expansion");
+      reference = decodeReference(last.reference);
+    }
+    validatePath(last.path, 256);
+    uint(last.ttl, MAX_GRANT_SECONDS, 1);
+    check(
+      sameValue(last.receipt.principal, s.principal) && sameValue(reference.target, s.target) && reference.root === last.receipt.head.root && reference.path === last.path && sameValue(reference.retention, last.receipt.retention),
+      "saved receipt differs from workspace"
+    );
+  }
+  if (s.pending !== void 0) {
+    check(s.target, "pending operation has no target");
+    const p = s.pending;
+    switch (p.kind) {
+      case "publish":
+        record(p, ["kind", "command", "path", "ttl"], ["expiry_revision", "reference"]);
+        if (p.reference !== void 0) {
+          validateReferenceSpec(p.reference);
+          check(
+            p.reference.creator === s.creator && sameValue(p.reference.paths, [p.path]),
+            "saved reference intent differs from publication"
+          );
+        }
+        validateCommand(p.command);
+        validatePath(p.path, 256);
+        uint(p.ttl, MAX_GRANT_SECONDS, 1);
+        if (p.expiry_revision !== void 0) uint(p.expiry_revision, void 0, 1);
+        check(
+          p.command.creation_id === s.target.creation_id && sameValue(p.command.writer, s.writer) && p.command.number === s.next,
+          "pending writer position differs"
+        );
+        break;
+      case "reset":
+        record(p, ["kind", "writer"]);
+        validateWriter(p.writer);
+        break;
+      case "grant":
+        record(p, ["kind", "request", "provenance"]);
+        validateGrant(p.request);
+        check(
+          p.provenance === "first-hand" || p.provenance === "on-request",
+          "invalid pending grant provenance"
+        );
+        break;
+      case "release":
+        record(p, ["kind", "request"]);
+        record(p.request, ["target", "handle"]);
+        validateTarget(p.request.target);
+        validateRetentionHandle(p.request.handle);
+        break;
+      case "close":
+      case "apply":
+        record(p, ["kind", "request"]);
+        record(p.request, ["target", "revision"]);
+        validateTarget(p.request.target);
+        uint(p.request.revision, void 0, 1);
+        break;
+      default:
+        check(false, "unknown workspace pending operation");
+    }
+    if ("request" in p)
+      check(sameValue(p.request.target, s.target), "pending operation names another target");
+  }
+}
+function validateGrant(value) {
+  const g = record(value, [
+    "target",
+    "slot",
+    "generation",
+    "principal",
+    "root",
+    "path",
+    "retention",
+    "until",
+    "action"
+  ]);
+  validateTarget(g.target);
+  uint(g.slot, 15);
+  uint(g.generation);
+  validatePrincipal(g.principal);
+  validatePath(g.path, 256);
+  validateRetentionHandle(g.retention);
+  uint(g.until, void 0, 1);
+  validateAction(g.action);
+  text(g.root, 43, 43);
+}
+var NativeScratchPad = class extends ScratchPadReader {
+  constructor(transport, store, state, scope, ttl) {
+    super(transport, state.principal);
+    this.store = store;
+    this.state = state;
+    this.scope = scope;
+    this.ttl = ttl;
+  }
+  store;
+  state;
+  scope;
+  ttl;
+  tail = Promise.resolve();
+  closing = false;
+  closePromise;
+  run(work) {
+    if (this.closing)
+      return Promise.reject(
+        new NativeScratchPadError("closed", "native client is closed", { local: true })
+      );
+    const result = this.tail.then(work);
+    this.tail = result.then(
+      () => {
+      },
+      () => {
+      }
+    );
+    return result;
+  }
+  save(state, remote = false, clearObjects = false) {
+    try {
+      validateState(state);
+      this.store.save(state, remote, clearObjects);
+      this.state = state;
+    } catch (error) {
+      if (remote)
+        throw unknown(
+          error,
+          "remote effect may be accepted; close and reopen the workspace before recovery"
+        );
+      throw error;
+    }
+  }
+  change(pending) {
+    this.save({ ...this.state, pending });
+  }
+  target() {
+    check(this.state.target, "workspace has no volume");
+    return this.state.target;
+  }
+  async ensureTarget() {
+    if (!this.state.target) {
+      const view2 = await this.transport.createVolume({
+        volume: this.state.volume,
+        action: this.state.creation
+      });
+      if (!sameValue(view2.owner, this.principal))
+        throw unknown(void 0, "volume creation names another owner");
+      this.save({ ...this.state, target: view2.target }, true);
+      return view2;
+    }
+    const view = await this.transport.getVolume(this.state.target);
+    check(
+      sameValue(view.owner, this.principal),
+      "workspace principal is no longer the volume owner"
+    );
+    return view;
+  }
+  async initialize() {
+    if (this.state.writer) return;
+    const view = await this.ensureTarget();
+    if (this.state.pending)
+      refuse("fenced", "writer reset needs an explicit resetWriter with the observed generation");
+    const slot = view.writers[0];
+    if (slot.number !== 0)
+      refuse(
+        "fenced",
+        "writer slot 0 has accepted commands but this workspace has no journal; inspect describe and reset explicitly"
+      );
+    await this.reset({ slot: 0, generation: slot.generation });
+  }
+  async reset(writer) {
+    const previous = this.state;
+    this.change({ kind: "reset", writer });
+    let result;
+    try {
+      result = await this.transport.resetWriter(this.target(), writer);
+    } catch (error) {
+      if (error instanceof NativeScratchPadError && !error.unknown) this.save(previous, true);
+      throw error;
+    }
+    const state = { ...this.state, writer: result, next: 1 };
+    delete state.pending;
+    delete state.last;
+    this.save(state, true, true);
+    return result;
+  }
+  /** Explicitly abandon writer recovery, fencing the exact generation observed by describe(). */
+  resetWriter(options) {
+    return this.run(async () => {
+      uint(options.expectedGeneration, void 0, 1);
+      if (options.target) {
+        validateTarget(options.target);
+        check(
+          options.target.volume === this.state.volume,
+          "explicit reset target names another volume"
+        );
+        if (this.state.target)
+          check(
+            sameValue(options.target, this.state.target),
+            "explicit reset target differs from workspace"
+          );
+        else {
+          const view = await this.transport.getVolume(options.target);
+          check(sameValue(view.owner, this.principal), "explicit reset target has another owner");
+          this.save({ ...this.state, target: view.target });
+        }
+      }
+      await this.ensureTarget();
+      if (this.state.pending && !["reset", "publish"].includes(this.state.pending.kind))
+        refuse("busy", "recover the pending control request before resetting the writer");
+      return this.reset({ slot: 0, generation: options.expectedGeneration });
+    });
+  }
+  describe() {
+    return this.run(async () => {
+      const volume = await this.ensureTarget();
+      return this.state.pending ? { volume, pending: this.state.pending.kind } : { volume };
+    });
+  }
+  recover() {
+    return this.run(() => this.recoverPending());
+  }
+  async recoverPending() {
+    if (this.state.pending?.kind === "reset")
+      refuse("fenced", "reset outcome needs an explicit resetWriter with the observed generation");
+    await this.initialize();
+    const pending = this.state.pending;
+    if (pending?.kind === "publish") {
+      try {
+        return { kind: "publish", ...await this.resumePublish(pending) };
+      } catch (error) {
+        if (error instanceof NativeScratchPadError && error.code === "expired" && !error.unknown && !this.state.pending)
+          return { kind: "expired" };
+        throw error;
+      }
+    }
+    if (pending) {
+      await this.control(pending, false);
+      return { kind: pending.kind };
+    }
+    return this.state.last ? { kind: "ready", reference: this.state.last.reference, receipt: this.state.last.receipt } : { kind: "ready" };
+  }
+  publishBytes(bytes, path, options) {
+    const stable = Uint8Array.from(bytes);
+    return this.publishStream([stable], path, options);
+  }
+  /** A publication replaces the head with one file at path. Older references keep their retained roots. */
+  publishStream(source, path, options) {
+    return this.publish(source, path, options, false);
+  }
+  publish(source, path, options, recover) {
+    options = structuredClone(options);
+    return this.run(async () => {
+      validatePath(path, 256);
+      check(path !== "/", "a file path is required");
+      const trace = wireTrace(options.trace), ttl = options.ttlSeconds ?? this.ttl;
+      uint(ttl, MAX_GRANT_SECONDS, 1);
+      validateAction({ operation_id: options.operationId, trace });
+      if (recover) await this.recoverPending();
+      await this.initialize();
+      const pending = this.state.pending;
+      if (pending) {
+        if (pending.kind !== "publish" || pending.command.operation_id !== options.operationId)
+          refuse("busy", "recover the pending operation before publishing another one");
+        this.samePublication(pending, path, ttl, trace);
+        return this.resumePublish(pending);
+      }
+      if (this.state.last?.receipt.command.operation_id === options.operationId) {
+        const last = this.state.last;
+        this.samePublication(
+          { kind: "publish", command: last.receipt.command, path: last.path, ttl: last.ttl },
+          path,
+          ttl,
+          trace
+        );
+        return { reference: last.reference, receipt: last.receipt };
+      }
+      const capabilities = await this.transport.referenceInfo();
+      const reference = capabilities?.enabled ? { creator: this.state.creator, paths: [path] } : void 0;
+      if (reference) validateReferenceSpec(reference);
+      this.store.clearObjects();
+      let ordinal = 0, totalBytes = 0;
+      const put = (object, data) => {
+        totalBytes += data.length;
+        if (totalBytes > this.scope.bytes || ordinal + 1 > this.scope.objects)
+          refuse("capacity", "artifact exceeds this volume's configured capacity");
+        this.store.putObject(ordinal++, object, data);
+      };
+      try {
+        const file = await chunkStream(source, (_index, object, data) => put(object, data));
+        const fileBytes = encodeFileObject(file);
+        let root = fileObjectID(fileBytes);
+        put({ kind: "fobj", id: root }, fileBytes);
+        let type = "file";
+        for (const name of path.slice(1).split("/").reverse()) {
+          const data = encodeTreeNode([{ name, type, object: root }]);
+          root = treeNodeID(data);
+          put({ kind: "tree", id: root }, data);
+          type = "directory";
+        }
+        const objects = this.store.objects();
+        let view = await this.transport.getVolume(this.target());
+        const clock = now2();
+        const fullRetention = view.retentions.every((slot2) => slot2.pin);
+        const canRelease = view.retentions.some(
+          (slot2, index) => slot2.pin && slot2.pin.until !== 0 && slot2.pin.until <= clock && !view.grants.some(
+            (grant) => grant.grant && grant.grant.until > clock && sameValue(grant.grant.retention, { slot: index, generation: slot2.generation })
+          )
+        );
+        if (fullRetention && !canRelease)
+          refuse(
+            "capacity",
+            "all retention slots hold live or protected handoffs; cleanup cannot free a slot"
+          );
+        const needsCleanup = fullRetention || view.objects + objects.length > this.scope.objects || view.bytes + objects.reduce((n, object) => n + object.length, 0) > this.scope.bytes;
+        if (needsCleanup) view = await this.maintainInternal();
+        const slot = view.retentions.findIndex((entry) => !entry.pin);
+        if (slot < 0)
+          refuse(
+            "capacity",
+            "all retention slots are occupied; release finished handoffs or wait for their expiry"
+          );
+        if (view.objects + objects.length > this.scope.objects || view.bytes + objects.reduce((n, object) => n + object.length, 0) > this.scope.bytes)
+          refuse("capacity", "live roots and this artifact exceed the volume's capacity");
+        const writer = this.state.writer;
+        const actual = view.writers[writer.slot];
+        if (actual.generation !== writer.generation || actual.number + 1 !== this.state.next)
+          refuse("fenced", "remote writer position differs from the durable workspace");
+        if (view.closed) refuse("closed", "volume is closed by another maintenance interval");
+        const command = {
+          creation_id: this.target().creation_id,
+          writer,
+          number: this.state.next,
+          operation_id: options.operationId,
+          base: view.head,
+          root,
+          trace,
+          retention: {
+            enabled: true,
+            slot,
+            generation: view.retentions[slot].generation,
+            until: now2() + ttl
+          }
+        };
+        const publication = {
+          kind: "publish",
+          command,
+          path,
+          ttl,
+          ...reference ? { reference } : {}
+        };
+        this.change(publication);
+        return await this.resumePublish(publication);
+      } catch (error) {
+        if (!this.state.pending) this.store.clearObjects();
+        throw error;
+      }
+    });
+  }
+  samePublication(publication, path, ttl, trace) {
+    if (publication.path !== path || publication.ttl !== ttl || !sameValue(publication.command.trace, trace))
+      refuse(
+        "intent_changed",
+        "operation id is already bound to another publication; recover uses its saved payload"
+      );
+  }
+  async resumePublish(publication) {
+    if (publication.reference) {
+      try {
+        const result = await this.transport.referenceReceipt({
+          target: this.target(),
+          command: publication.command,
+          reference: publication.reference
+        });
+        if (!sameValue(result.receipt.principal, this.principal))
+          throw unknown(void 0, "referenced receipt names another principal");
+        return this.accept(publication, result.receipt, result.references[0]);
+      } catch (error) {
+        if (!(error instanceof NativeScratchPadError && error.code === "not_found" && !error.unknown))
+          throw error;
+      }
+    }
+    const view = await this.transport.getVolume(this.target());
+    const slot = view.writers[publication.command.writer.slot];
+    if (!publication.reference && slot.receipt && sameValue(slot.receipt.command, publication.command) && sameValue(slot.receipt.principal, this.principal))
+      return this.accept(publication, slot.receipt);
+    if (slot.generation !== publication.command.writer.generation || slot.number >= publication.command.number)
+      refuse("fenced", "saved writer position has been fenced; inspect and reset explicitly");
+    if (publication.expiry_revision !== void 0) {
+      await this.fenceExpired(publication, view);
+      throw new NativeScratchPadError("expired", "saved publication expired without acceptance");
+    }
+    if (publication.command.retention.until > now2()) await this.upload();
+    let receipt, resolved;
+    try {
+      if (publication.reference) {
+        const result = await this.transport.referencePublish({
+          target: this.target(),
+          command: publication.command,
+          reference: publication.reference
+        });
+        receipt = result.receipt;
+        resolved = result.references[0];
+      } else {
+        receipt = await this.transport.publish({
+          target: this.target(),
+          command: publication.command
+        });
+      }
+    } catch (error) {
+      if (error instanceof NativeScratchPadError && error.code === "expired" && !error.unknown) {
+        await this.fenceExpired(publication, view);
+      }
+      throw error;
+    }
+    if (!sameValue(receipt.command, publication.command) || !sameValue(receipt.principal, this.principal))
+      throw unknown(void 0, "publish receipt differs from the saved command");
+    return this.accept(publication, receipt, resolved);
+  }
+  async fenceExpired(publication, view) {
+    let revision = publication.expiry_revision;
+    if (revision === void 0) {
+      if (view.closed) refuse("closed", "another maintenance interval owns this closed volume");
+      revision = view.revision;
+      publication = { ...publication, expiry_revision: revision };
+      this.change(publication);
+    }
+    if (!(view.closed && view.revision === revision + 1)) {
+      if (view.revision !== revision) {
+        const pending = { ...publication };
+        delete pending.expiry_revision;
+        this.change(pending);
+        throw new NativeScratchPadError(
+          "conflict",
+          "expiry fence changed; recover the saved publication again"
+        );
+      }
+      view = await this.transport.closeVolume({ target: this.target(), revision });
+    }
+    const slot = view.writers[publication.command.writer.slot];
+    if (!view.closed || view.revision !== revision + 1 || slot.generation !== publication.command.writer.generation || slot.number !== publication.command.number - 1)
+      throw unknown(void 0, "expiry fence has not established publication absence");
+    const continuation = {
+      kind: "apply",
+      request: { target: this.target(), revision: view.revision }
+    };
+    this.save({ ...this.state, pending: continuation }, true, true);
+    await this.control(continuation, true);
+  }
+  accept(publication, receipt, resolved) {
+    check(
+      Boolean(publication.reference) === Boolean(resolved),
+      "referenced publication lost its descriptor"
+    );
+    const reference = resolved?.short ?? encodeReference({
+      version: 2,
+      creator: this.state.creator,
+      account: this.principal.account,
+      target: this.target(),
+      root: receipt.head.root,
+      generation: receipt.head.generation,
+      path: publication.path,
+      retention: receipt.retention,
+      expires_at: publication.command.retention.until
+    });
+    const state = {
+      ...this.state,
+      next: receipt.command.number + 1,
+      last: {
+        reference,
+        receipt,
+        path: publication.path,
+        ttl: publication.ttl,
+        ...resolved ? { resolved } : {}
+      }
+    };
+    delete state.pending;
+    this.save(state, true, true);
+    if (resolved) this.cacheReference(resolved);
+    return { reference, receipt };
+  }
+  async upload() {
+    const objects = this.store.objects();
+    check(objects.length > 0, "saved publication payload is missing");
+    const sorted = [...objects].sort(
+      (a, b) => Buffer.compare(
+        Buffer.from(`${a.object.kind}:${a.object.id}`),
+        Buffer.from(`${b.object.kind}:${b.object.id}`)
+      )
+    );
+    const verified = /* @__PURE__ */ new Set();
+    let epoch;
+    const key = (o) => o.kind + ":" + o.id;
+    for (let start = 0; start < sorted.length; start += MAX_PREPARE_OBJECTS) {
+      const result = await this.transport.prepare({
+        target: this.target(),
+        objects: sorted.slice(start, start + MAX_PREPARE_OBJECTS)
+      });
+      if (epoch !== void 0 && epoch !== result.epoch)
+        throw unknown(void 0, "upload preparation changed epoch; recover the saved publication");
+      epoch = result.epoch;
+      for (const object of result.objects) {
+        if (object.state === "refused")
+          refuse(
+            "capacity",
+            "object reservation refused; saved publication stays pending for recovery or explicit reset"
+          );
+        if (object.state === "verified") verified.add(key(object.object));
+      }
+    }
+    check(epoch !== void 0, "publication contains no objects");
+    for (const spec of objects) {
+      if (verified.has(key(spec.object))) continue;
+      await this.transport.putPrepared(
+        { target: this.target(), object: spec.object, epoch },
+        this.store.bytes(spec.object)
+      );
+      let next = -1;
+      for (; ; ) {
+        const result = await this.transport.verify({
+          target: this.target(),
+          epoch,
+          objects: [spec.object]
+        });
+        const progress = result.objects[0];
+        if (progress.state === "verified") break;
+        if (progress.state !== "verifying" || progress.next <= next)
+          throw unknown(void 0, "object verification did not advance");
+        next = progress.next;
+      }
+    }
+  }
+  async commit(value, path, trace) {
+    const result = await this.publish(
+      [Buffer.from(value)],
+      path.startsWith("/") ? path : "/" + path,
+      { operationId: node_crypto.randomUUID(), ...trace ? { trace } : {} },
+      true
+    );
+    return result.reference;
+  }
+  owns(token) {
+    const matches = (ref) => ref.creator === this.state.creator && sameValue(ref.target, this.state.target);
+    if (token.startsWith(SHORT_REFERENCE_PREFIX2))
+      return this.resolveReference(token).then(matches, () => false);
+    try {
+      return matches(this.reference(token));
+    } catch {
+      return false;
+    }
+  }
+  granted(token, grantee) {
+    const find = (ref) => {
+      if (ref.creator !== this.state.creator || !sameValue(ref.target, this.state.target))
+        return void 0;
+      let kind;
+      for (const grant of this.state.grants) {
+        const q = grant.request;
+        if (q.until > now2() && sameValue(q.principal, grantee) && q.root === ref.root && q.path === ref.path && sameValue(q.retention, ref.retention)) {
+          if (grant.kind === "first-hand") return grant.kind;
+          kind = grant.kind;
+        }
+      }
+      return kind;
+    };
+    if (token.startsWith(SHORT_REFERENCE_PREFIX2))
+      return this.resolveReference(token).then(find, () => void 0);
+    try {
+      return find(this.reference(token));
+    } catch {
+      return void 0;
+    }
+  }
+  grantRead(token, grantee, trace, toolCallId, kind = "first-hand") {
+    return this.run(async () => {
+      validatePrincipal(grantee);
+      const labels = wireTrace(trace, toolCallId);
+      if (!await this.owns(token) || grantee.account !== this.principal.account)
+        refuse("denied", "only the owner can grant this same-account reference");
+      const ref = await this.resolveReference(token, trace);
+      if (this.state.pending) await this.recoverPending();
+      const view = await this.transport.getVolume(this.target()), clock = now2();
+      const pin = view.retentions[ref.retention.slot];
+      if (pin.generation !== ref.retention.generation || pin.pin?.root !== ref.root)
+        refuse("expired", "reference retention is no longer held");
+      const until = Math.min(
+        clock + this.ttl,
+        ref.expires_at,
+        pin.pin.until || Number.MAX_SAFE_INTEGER
+      );
+      if (until <= clock) refuse("expired", "reference retention has expired");
+      const old = this.state.grants.find(
+        (g) => g.request.until >= until && sameValue(g.request.principal, grantee) && g.request.root === ref.root && g.request.path === ref.path && sameValue(g.request.retention, ref.retention) && view.grants[g.handle.slot]?.generation === g.handle.generation
+      );
+      if (old) {
+        if (kind === "first-hand" && old.kind !== kind) {
+          const grants = this.state.grants.map((g) => g === old ? { ...g, kind } : g);
+          this.save({ ...this.state, grants });
+        }
+        return;
+      }
+      const slot = view.grants.findIndex((g) => !g.grant || g.grant.until <= clock);
+      if (slot < 0) refuse("capacity", "all read-grant slots hold live grants");
+      const control = {
+        kind: "grant",
+        provenance: kind,
+        request: {
+          target: this.target(),
+          slot,
+          generation: view.grants[slot].generation,
+          principal: { ...grantee },
+          root: ref.root,
+          path: ref.path,
+          retention: ref.retention,
+          until,
+          action: { operation_id: node_crypto.randomUUID(), trace: labels }
+        }
+      };
+      this.change(control);
+      await this.control(control, true);
+    });
+  }
+  /** Release a completed handoff. Refuses while any live grant names its retention. */
+  release(token) {
+    return this.run(async () => {
+      if (this.state.pending) refuse("busy", "recover the pending operation before release");
+      const ref = token.startsWith(SHORT_REFERENCE_PREFIX2) ? await this.resolveReference(token) : decodeReference(token);
+      if (ref.account !== this.principal.account || !sameValue(ref.target, this.state.target))
+        refuse("denied", "reference belongs to another workspace");
+      const view = await this.transport.getVolume(this.target());
+      if (view.grants.some(
+        (g) => g.grant && g.grant.until > now2() && sameValue(g.grant.retention, ref.retention)
+      ))
+        refuse("busy", "a live read grant still uses this retention");
+      const control = {
+        kind: "release",
+        request: { target: this.target(), handle: ref.retention }
+      };
+      this.change(control);
+      await this.control(control, true);
+    });
+  }
+  /** Collect unreferenced content in this client's own maintenance interval. */
+  maintain() {
+    return this.run(() => this.maintainInternal());
+  }
+  async maintainInternal() {
+    if (this.state.pending) refuse("busy", "recover the pending operation before collection");
+    let view = await this.ensureTarget();
+    if (view.closed) refuse("closed", "another maintenance interval owns this closed volume");
+    const clock = now2();
+    for (const [slot, held] of view.retentions.entries()) {
+      if (!held.pin || held.pin.until === 0 || held.pin.until > clock) continue;
+      const handle = { slot, generation: held.generation };
+      if (view.grants.some(
+        (g) => g.grant && g.grant.until > clock && sameValue(g.grant.retention, handle)
+      ))
+        continue;
+      const control2 = { kind: "release", request: { target: this.target(), handle } };
+      this.change(control2);
+      await this.control(control2, true);
+    }
+    view = await this.transport.getVolume(this.target());
+    const control = {
+      kind: "close",
+      request: { target: this.target(), revision: view.revision }
+    };
+    this.change(control);
+    await this.control(control, true);
+    return this.transport.getVolume(this.target());
+  }
+  async control(control, fresh) {
+    let failure, view, handle;
+    let settled = false;
+    try {
+      switch (control.kind) {
+        case "grant":
+          handle = await this.transport.issueGrant(control.request);
+          break;
+        case "release":
+          view = await this.transport.release(control.request);
+          break;
+        case "close":
+          view = await this.transport.closeVolume(control.request);
+          break;
+        case "apply":
+          view = (await this.transport.applyCollection(control.request)).volume;
+          break;
+      }
+      settled = true;
+    } catch (error) {
+      failure = error;
+      if (control.kind !== "release") {
+        try {
+          view = await this.transport.getVolume(this.target());
+          if (control.kind === "grant") {
+            const q = control.request, observed = view.grants[q.slot], g = observed.grant;
+            if (observed.generation > q.generation && g && sameValue(g.principal, q.principal) && g.root === q.root && g.path === q.path && sameValue(g.retention, q.retention) && g.until === q.until) {
+              handle = { slot: q.slot, generation: observed.generation };
+              failure = void 0;
+              settled = true;
+            }
+          } else if (control.kind === "close") {
+            if (view.closed && view.revision === control.request.revision + 1) {
+              failure = void 0;
+              settled = true;
+            } else if (view.revision !== control.request.revision) {
+              settled = true;
+              failure = new NativeScratchPadError(
+                "conflict",
+                "saved close is fenced by another revision"
+              );
+            }
+          } else if (!view.closed) {
+            failure = void 0;
+            settled = true;
+          }
+        } catch {
+        }
+      }
+      if (error instanceof NativeScratchPadError && !error.unknown && (fresh || control.kind === "release" || control.kind === "grant" && error.code === "expired"))
+        settled = true;
+    }
+    if (!settled)
+      throw unknown(failure, `the saved ${control.kind} request stays pending; call recover()`);
+    if (!failure && control.kind === "close" && (!view?.closed || view.revision !== control.request.revision + 1))
+      throw unknown(void 0, "close returned another maintenance interval");
+    const state = { ...this.state };
+    delete state.pending;
+    if (!failure && control.kind === "grant") {
+      check(handle, "grant acceptance has no handle");
+      state.grants = state.grants.filter(
+        (g) => g.request.until > now2() && g.handle.slot !== handle.slot
+      );
+      state.grants.push({ request: control.request, handle, kind: control.provenance });
+    }
+    if (!failure && control.kind === "close")
+      state.pending = {
+        kind: "apply",
+        request: { target: this.target(), revision: view.revision }
+      };
+    this.save(state, true);
+    if (failure)
+      throw failure instanceof Error ? failure : new Error("control request failed", { cause: failure });
+    if (state.pending?.kind === "apply") await this.control(state.pending, true);
+  }
+  close() {
+    if (this.closePromise) return this.closePromise;
+    this.closing = true;
+    return this.closePromise = this.tail.then(() => this.store.close());
+  }
+};
+async function nativeScratchPad(options) {
+  validateVolume(options.volume);
+  text(options.creator, 512, 1);
+  const ttl = options.ttlSeconds ?? 600;
+  uint(ttl, MAX_GRANT_SECONDS, 1);
+  const transport = new ScratchPadTransport(options.nc, options);
+  const info = await transport.info();
+  const scope = info.scopes.find((scope2) => scope2.volume === options.volume);
+  if (!scope) refuse("denied", "authenticated principal owns no provisioned scope for this volume");
+  const store = await WorkspaceStore.open(options.dir);
+  try {
+    let state = store.load();
+    if (state === void 0) {
+      state = {
+        version: 1,
+        principal: info.principal,
+        volume: options.volume,
+        creator: options.creator,
+        creation: { operation_id: node_crypto.randomUUID(), trace: {} },
+        next: 1,
+        grants: []
+      };
+      store.save(state);
+    }
+    validateState(state);
+    check(
+      sameValue(state.principal, info.principal) && state.volume === options.volume && state.creator === options.creator,
+      "workspace is bound to another principal, volume, or creator"
+    );
+    return new NativeScratchPad(transport, store, state, scope, ttl);
+  } catch (error) {
+    store.close();
+    throw error;
+  }
+}
+async function nativeScratchPadFromEnv(env, options) {
+  const volume = env["SCRATCHPAD_VOLUME"];
+  if (!volume) return void 0;
+  const dir = env["SCRATCHPAD_DIR"];
+  check(dir, "SCRATCHPAD_DIR must name a persistent private directory for the native client");
+  const value = env["SCRATCHPAD_GRANT_TTL_S"];
+  check(value === void 0 || /^[0-9]+$/.test(value), "SCRATCHPAD_GRANT_TTL_S must be an integer");
+  return nativeScratchPad({
+    ...options,
+    volume,
+    dir,
+    ...value === void 0 ? {} : { ttlSeconds: Number(value) }
+  });
+}
+
+// src/plugin-settings.ts
+var EDGE_SUBJECT_OPTION = "edgeSubject";
+var EDGE_SUBJECT_VAR = "SYNADIA_FABRIC_EDGE_SUBJECT";
+function resolveEdgeSubject(options, env = process.env) {
+  if (Object.hasOwn(options, EDGE_SUBJECT_OPTION)) {
+    return options[EDGE_SUBJECT_OPTION];
+  }
+  const fromEnv = env[EDGE_SUBJECT_VAR];
+  if (fromEnv !== void 0) return fromEnv;
+  return DEFAULT_EDGE_SUBJECT;
+}
+var SCRATCHPAD_OPTION = "scratchpad";
+var SP_VARS = {
+  url: "SP_NATS_URL",
+  creds: "SP_NATS_CREDS",
+  dir: SCRATCHPAD_DIR_VAR,
+  volume: SCRATCHPAD_VOLUME_VAR,
+  creator: "SP_CREATOR",
+  threadId: "SP_THREAD_ID",
+  rootId: "SP_ROOT_ID",
+  callerAccount: "SP_CALLER_ACCOUNT",
+  callerUser: "SP_CALLER_USER",
+  grants: "SP_GRANTS_FILE"
+};
+async function resolveScratchPad(ctx, env) {
+  const log = ctx.logger;
+  const raw = ctx.options[SCRATCHPAD_OPTION];
+  const options = raw !== null && typeof raw === "object" ? raw : {};
+  const pick = (option, variable) => {
+    const fromOptions = options[option];
+    if (typeof fromOptions === "string" && fromOptions !== "") return fromOptions;
+    const fromEnv = env[variable];
+    return fromEnv === void 0 || fromEnv === "" ? void 0 : fromEnv;
+  };
+  const volume = pick("volume", SP_VARS.volume);
+  if (volume === void 0) return void 0;
+  let url = pick("url", "NATS_URL");
+  let creds = pick("creds", "NATS_CREDS");
+  if (url === void 0 || creds === void 0) {
+    const context = env["NATS_CONTEXT"] || stringOf(ctx.settings.config["context"]);
+    if (context !== void 0) {
+      try {
+        const { fields } = await agents.readContextFile(context);
+        url ??= stringOf(fields["url"]);
+        creds ??= stringOf(fields["creds"]);
+      } catch (err) {
+        log.warn(
+          `agent-fabric: ScratchPad is off: the NATS context "${context}" could not be read (${String(err)})`
+        );
+        return void 0;
+      }
+    }
+  }
+  url ??= stringOf(ctx.settings.config["url"]);
+  creds ??= stringOf(ctx.settings.config["credentials"]);
+  if (url === void 0 || creds === void 0) {
+    log.warn(
+      "agent-fabric: ScratchPad is off: sp needs a NATS URL and a credentials file (options.scratchpad, NATS_URL and NATS_CREDS, a NATS context with both, or url and credentials in the plugin's configuration)"
+    );
+    return void 0;
+  }
+  let dir = pick("dir", SP_VARS.dir);
+  if (dir === void 0 && ctx.settings.stateDir !== void 0) {
+    dir = node_path.join(ctx.settings.stateDir, "scratchpad");
+  }
+  if (dir !== void 0) {
+    dir = node_path.resolve(expandHome(dir));
+    try {
+      node_fs.mkdirSync(dir, { recursive: true, mode: 448 });
+    } catch (err) {
+      log.warn(`agent-fabric: ScratchPad workspace ${dir} could not be created (${String(err)})`);
+    }
+  }
+  const grants = dir !== void 0 ? `${dir}.grants` : void 0;
+  if (grants !== void 0) pruneRecordedGrants(grants, log);
+  return {
+    url,
+    creds: expandHome(creds),
+    volume,
+    ...dir !== void 0 ? { dir } : {},
+    ...grants !== void 0 ? { grants } : {}
+  };
+}
+function exportScratchPad(settings, env) {
+  env[SP_VARS.url] = settings.url;
+  env[SP_VARS.creds] = settings.creds;
+  env[SP_VARS.volume] = settings.volume;
+  if (settings.dir !== void 0) env[SP_VARS.dir] = settings.dir;
+  if (settings.grants !== void 0) env[SP_VARS.grants] = settings.grants;
+}
+var ServedPromptEnv = class {
+  constructor(env) {
+    this.env = env;
+  }
+  env;
+  #holder;
+  enter(request, scope) {
+    this.#clear();
+    this.#holder = request.id;
+    if (scope !== void 0) {
+      this.env[SP_VARS.threadId] = scope.threadId;
+      this.env[SP_VARS.rootId] = scope.rootId;
+    }
+    if (request.caller !== void 0) {
+      try {
+        const grantee = granteeFromIdentity(request.caller);
+        this.env[SP_VARS.callerAccount] = grantee.account;
+        this.env[SP_VARS.callerUser] = grantee.user;
+      } catch {
+      }
+    }
+  }
+  leave(request) {
+    if (this.#holder === request.id) {
+      this.#clear();
+      this.#holder = void 0;
+    }
+  }
+  #clear() {
+    delete this.env[SP_VARS.threadId];
+    delete this.env[SP_VARS.rootId];
+    delete this.env[SP_VARS.callerAccount];
+    delete this.env[SP_VARS.callerUser];
+  }
+};
+function spBinary(env, skillDir) {
+  const own = env[SCRATCHPAD_BIN_VAR];
+  if (own !== void 0 && own !== "") return own;
+  const os = node_os.platform() === "darwin" ? "darwin" : node_os.platform() === "linux" ? "linux" : void 0;
+  const cpu = node_os.arch() === "arm64" ? "arm64" : node_os.arch() === "x64" ? "amd64" : void 0;
+  if (os === void 0 || cpu === void 0) return void 0;
+  return node_path.join(skillDir, "bin", `sp-${os}-${cpu}`);
+}
+var ScratchPadHandOn = class {
+  #inner;
+  #scratchPad;
+  #early = [];
+  requestInterceptor = {
+    aroundRequest: (ctx, next) => {
+      if (this.#inner === void 0) this.#early.push(ctx.envelope.prompt);
+      else this.#inner.remember(ctx.envelope.prompt);
+      return next();
+    }
+  };
+  /**
+   * Builds the extension, once the plugin's client is on the bus. Given the
+   * plugin's service, also answers grant requests for what this agent
+   * published, on the endpoint an SDK-built agent serves them on
+   * (`grantRequestEndpoint`), added through the service's own
+   * `addEndpoint`, since the plugin builds its service before the add-on
+   * could name an extra endpoint. Several instances of one agent share the
+   * work, as an SDK-built agent's do.
+   */
+  start(options) {
+    const { scratchPad, agents: agents$1, service } = options;
+    this.#scratchPad = scratchPad;
+    this.#inner = scratchPadExtension({ scratchPad, agents: agents$1 });
+    for (const text2 of this.#early.splice(0)) this.#inner.remember(text2);
+    if (service === void 0) return;
+    const logger = options.logger ?? agents.SILENT_LOGGER;
+    const ep = grantRequestEndpoint({
+      promptAddress: service.subject.prompt,
+      scratchPad,
+      logger
+    });
+    try {
+      service.service.addEndpoint(ep.name, {
+        subject: ep.subject,
+        ...ep.queue !== void 0 ? { queue: ep.queue } : {},
+        handler: ep.handler
+      });
+    } catch (err) {
+      logger.warn(`agent-fabric: grant requests are not answered: ${String(err)}`);
+    }
+  }
+  discoveryFields(agent) {
+    return this.#inner?.discoveryFields(agent) ?? {
+      [READS_SCRATCHPAD_REFERENCES_FIELD]: readsReferences(agent.metadata)
+    };
+  }
+  async beforePrompt(ctx) {
+    const inner = this.#inner;
+    const scratchPad = this.#scratchPad;
+    if (inner === void 0 || scratchPad === void 0) {
+      if (findReferences(ctx.prompt).length === 0) return;
+      return {
+        error: "the prompt was not sent: ScratchPad is not ready yet; try again in a moment"
+      };
+    }
+    for (const reference of new Set(findReferences(ctx.prompt))) {
+      if (await scratchPad.owns(reference)) inner.remember(reference);
+    }
+    return inner.beforePrompt(ctx);
+  }
+  afterReply(ctx) {
+    this.#inner?.afterReply(ctx);
+  }
+};
+function spPort(settings, creator, env, skillDir) {
+  const bin = spBinary(env, skillDir);
+  if (bin === void 0) return void 0;
+  const port = spCliScratchPad({
+    volume: settings.volume,
+    nats: { url: settings.url, creds: settings.creds },
+    bin,
+    creator,
+    ...settings.dir !== void 0 ? { dir: settings.dir } : {}
+  });
+  return settings.grants !== void 0 ? withRecordedGrants(port, settings.grants) : port;
+}
+var RECORDED_LINE = /^(\d+) (\S+) (\S+) (sp-(?:ref|r1):[A-Za-z0-9_-]+)$/;
+function readRecordedGrants(file) {
+  let text2;
+  try {
+    text2 = node_fs.readFileSync(file, "utf8");
+  } catch {
+    return [];
+  }
+  const grants = [];
+  for (const line of text2.split("\n")) {
+    const m = RECORDED_LINE.exec(line);
+    if (m === null) continue;
+    grants.push({
+      expiresAt: Number(m[1]),
+      grantee: { account: m[2], user: m[3] },
+      reference: m[4]
+    });
+  }
+  return grants;
+}
+function pruneRecordedGrants(file, log) {
+  const t = Math.floor(Date.now() / 1e3);
+  const live = readRecordedGrants(file).filter((g) => g.expiresAt > t);
+  try {
+    const staging = `${file}.${process.pid}.tmp`;
+    node_fs.writeFileSync(
+      staging,
+      live.map((g) => `${g.expiresAt} ${g.grantee.account} ${g.grantee.user} ${g.reference}
+`).join(""),
+      { mode: 384 }
+    );
+    node_fs.renameSync(staging, file);
+  } catch (err) {
+    log.warn(`agent-fabric: ScratchPad grants file ${file} could not be written (${String(err)})`);
+  }
+}
+function withRecordedGrants(port, file, now3 = () => Date.now() / 1e3) {
+  return {
+    ...port.resolveReference ? {
+      resolveReference: (reference, trace) => port.resolveReference(reference, trace)
+    } : {},
+    owns: (reference) => port.owns(reference),
+    grantRead: (reference, grantee, trace, toolCallId, kind) => port.grantRead(reference, grantee, trace, toolCallId, kind),
+    async granted(reference, grantee) {
+      const own = await port.granted(reference, grantee);
+      if (own === "first-hand") return own;
+      const t = now3();
+      const recorded = readRecordedGrants(file).some(
+        (g) => g.reference === reference && g.grantee.account === grantee.account && g.grantee.user === grantee.user && g.expiresAt > t
+      );
+      return recorded ? "first-hand" : own;
+    }
+  };
+}
+function stringOf(value) {
+  return typeof value === "string" && value !== "" ? value : void 0;
+}
+function expandHome(path) {
+  if (path === "~") return node_os.homedir();
+  if (path.startsWith("~/")) return node_path.join(node_os.homedir(), path.slice(2));
+  return path;
+}
+
+exports.DEFAULT_EDGE_SUBJECT = DEFAULT_EDGE_SUBJECT;
+exports.DEFAULT_GRANT_REQUEST_TIMEOUT_MS = DEFAULT_GRANT_REQUEST_TIMEOUT_MS;
+exports.DEFAULT_GRANT_TTL_S = DEFAULT_GRANT_TTL_S;
+exports.DEFAULT_READ_LIMIT_BYTES = DEFAULT_READ_LIMIT_BYTES;
+exports.DEFAULT_SP_BIN = DEFAULT_SP_BIN;
+exports.EDGE_RECORD_VERSION = EDGE_RECORD_VERSION;
+exports.EDGE_SUBJECT_OPTION = EDGE_SUBJECT_OPTION;
+exports.EDGE_SUBJECT_VAR = EDGE_SUBJECT_VAR;
+exports.GRANT_REQUEST_ENDPOINT = GRANT_REQUEST_ENDPOINT;
+exports.HARNESS_THREAD_ID_MAX = HARNESS_THREAD_ID_MAX;
+exports.LOOP_GUARD_CODE = LOOP_GUARD_CODE;
+exports.NativeScratchPad = NativeScratchPad;
+exports.NativeScratchPadError = NativeScratchPadError;
+exports.READS_REFERENCES_KEY = READS_REFERENCES_KEY;
+exports.READS_SCRATCHPAD_REFERENCES_FIELD = READS_SCRATCHPAD_REFERENCES_FIELD;
+exports.REFERENCE_PREFIX = REFERENCE_PREFIX;
+exports.ROOT_ID_FIELD = ROOT_ID_FIELD;
+exports.ROOT_ID_HEADER = ROOT_ID_HEADER;
+exports.SCRATCHPAD_BIN_VAR = SCRATCHPAD_BIN_VAR;
+exports.SCRATCHPAD_DIR_VAR = SCRATCHPAD_DIR_VAR;
+exports.SCRATCHPAD_GRANT_TTL_S_VAR = SCRATCHPAD_GRANT_TTL_S_VAR;
+exports.SCRATCHPAD_OPTION = SCRATCHPAD_OPTION;
+exports.SCRATCHPAD_VOLUME_VAR = SCRATCHPAD_VOLUME_VAR;
+exports.SERVED_RECORD_REASON_VERSION = SERVED_RECORD_REASON_VERSION;
+exports.SERVED_RECORD_VERSION = SERVED_RECORD_VERSION;
+exports.SHORT_REFERENCE_PREFIX = SHORT_REFERENCE_PREFIX;
+exports.SP_VARS = SP_VARS;
+exports.ScratchPadError = ScratchPadError;
+exports.ScratchPadExtension = ScratchPadExtension;
+exports.ScratchPadHandOn = ScratchPadHandOn;
+exports.ScratchPadReader = ScratchPadReader;
+exports.ServedPromptEnv = ServedPromptEnv;
+exports.ServedPublisher = ServedPublisher;
+exports.THREAD_ID_FIELD = THREAD_ID_FIELD;
+exports.THREAD_ID_HEADER = THREAD_ID_HEADER;
+exports.THREAD_ID_HEX_LEN = THREAD_ID_HEX_LEN;
+exports.TOOL_CALL_ID_CONTEXT_KEY = TOOL_CALL_ID_CONTEXT_KEY;
+exports.TOOL_CALL_ID_MAX = TOOL_CALL_ID_MAX;
+exports.activeTrace = activeTrace;
+exports.answerGrantRequest = answerGrantRequest;
+exports.assertValidTraceOptions = assertValidTraceOptions;
+exports.bindActiveTrace = bindActiveTrace;
+exports.buildEdgeRecord = buildEdgeRecord;
+exports.buildServedRecord = buildServedRecord;
+exports.countTraceRecordDropped = countTraceRecordDropped;
+exports.countTraceRecordPublished = countTraceRecordPublished;
+exports.decodeReference = decodeReference;
+exports.decodeShortReference = decodeShortReference;
+exports.durableHeaders = durableHeaders;
+exports.durableRunId = durableRunId;
+exports.durableTrace = durableTrace;
+exports.encodeGrantReply = encodeGrantReply;
+exports.encodeGrantRequest = encodeGrantRequest;
+exports.encodeReference = encodeReference;
+exports.exportScratchPad = exportScratchPad;
+exports.fabricTracing = fabricTracing;
+exports.findReferences = findReferences;
+exports.grantRequestEndpoint = grantRequestEndpoint;
+exports.grantSubject = grantSubject;
+exports.granteeFromIdentity = granteeFromIdentity;
+exports.isThreadId = isThreadId;
+exports.loopGuard = loopGuard;
+exports.loopGuardDescription = loopGuardDescription;
+exports.nativeScratchPad = nativeScratchPad;
+exports.nativeScratchPadFromEnv = nativeScratchPadFromEnv;
+exports.randomThreadId = randomThreadId;
+exports.readRecordedGrants = readRecordedGrants;
+exports.readsReferences = readsReferences;
+exports.referenceCreator = referenceCreator;
+exports.removeReferences = removeReferences;
+exports.requestGrant = requestGrant;
+exports.resolveEdgeSubject = resolveEdgeSubject;
+exports.resolveScratchPad = resolveScratchPad;
+exports.scratchPadExtension = scratchPadExtension;
+exports.scratchPadFromEnv = scratchPadFromEnv;
+exports.scratchPadReader = scratchPadReader;
+exports.servedPublisher = servedPublisher;
+exports.spBinary = spBinary;
+exports.spCliScratchPad = spCliScratchPad;
+exports.spPort = spPort;
+exports.traceHeaders = traceHeaders;
+exports.traceRecordCounts = traceRecordCounts;
+exports.unixSeconds = unixSeconds;
+exports.validHarnessThreadId = validHarnessThreadId;
+exports.validToolCallId = validToolCallId;
+exports.withDurableTrace = withDurableTrace;
+exports.withRecordedGrants = withRecordedGrants;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map