@almadar/shell-runtime 0.0.0-stage → 1.0.0

package/dist/chunk-I3TKINSO.js

@@ -0,0 +1,398 @@
+import { LaneHeldByParkedDispatch } from './chunk-NU6LVKGS.js';
+import { decodeDueTicks, decodeResolveProgress, decodeProgress, decodeNext } from './chunk-X6W44WHO.js';
+import { declareCapabilities, answerRequest } from './chunk-7WB6VWRK.js';
+import { installKernelEvaluator, LiveBroadcastItemSchema, MountSeedSchema, ExternalInputSchema, NameListSchema, PayloadJsonSchemaSchema, PayloadIssueSchema, InboundOnlySchema, OptionalNameSchema, EntityRowSchema, isEntityReferenceAny, InboundAnswerSchema, EventPayloadSchema, InboundFoundSchema } from '@almadar/core';
+
+var PROGRAM_SURFACE = {
+  parse(input) {
+    return input;
+  }
+};
+function declaredEntityTypes(schema) {
+  return schema.orbitals.flatMap((orbital) => [orbital.entity, ...orbital.auxiliaryEntities ?? []].flatMap((entity) => isEntityReferenceAny(entity) ? [] : [entity.name]));
+}
+function contractAnswers(ask) {
+  return {
+    findExternalInput(orbital, trait, event) {
+      return ask(ExternalInputSchema.nullable(), { kind: "findExternalInput", orbital, trait, event }) ?? void 0;
+    },
+    findInbound(name) {
+      return ask(InboundFoundSchema, { kind: "findInbound", name });
+    },
+    inboundPayload(route, delivery, credential) {
+      const headers = Object.fromEntries(Object.entries(delivery.headers).flatMap(([name, value]) => value === void 0 ? [] : [[name, value]]));
+      return ask(EventPayloadSchema, { kind: "inboundPayload", route, headers, rawBody: delivery.rawBody, ...typeof credential === "string" ? { credential } : {} });
+    },
+    inboundAnswer(route, emitted, error) {
+      return ask(InboundAnswerSchema, { kind: "inboundAnswer", route, emitted, ...error !== void 0 ? { error } : {} });
+    },
+    credentialUnset(credential) {
+      return ask(InboundAnswerSchema, { kind: "credentialUnset", credential });
+    },
+    dispatchFailed(message) {
+      return ask(InboundAnswerSchema, { kind: "dispatchFailed", message });
+    }
+  };
+}
+var KernelEngine = class _KernelEngine {
+  constructor(kernel, schemaJson, ports, entityTypes = [], forkedFrom, providedHandle, preserveProgramContext = false, lazyDir) {
+    this.kernel = kernel;
+    this.schemaJson = schemaJson;
+    this.ports = ports;
+    this.entityTypes = entityTypes;
+    this.preserveProgramContext = preserveProgramContext;
+    this.lazyDir = lazyDir;
+    installKernelEvaluator(kernel);
+    this.ports = {
+      ...ports,
+      substrateMessage: (site, key, value) => JSON.parse(kernel.osCompletionEvent(JSON.stringify({ ...site, emit: { success: site.emit.onMessage } }), key, JSON.stringify({ ok: value }))),
+      substrateCompletion: (site, key, op, args, outcome) => JSON.parse(kernel.substrateCompletionEvent(JSON.stringify(site), key, op, JSON.stringify(args), JSON.stringify(outcome)))
+    };
+    this.handle = providedHandle ?? forkedFrom?.fork() ?? this.openServer();
+    this.declare();
+  }
+  kernel;
+  schemaJson;
+  ports;
+  entityTypes;
+  preserveProgramContext;
+  lazyDir;
+  handle;
+  turns = /* @__PURE__ */ new Map();
+  tickRelayIntervalMs;
+  stateful = false;
+  /**
+   * A kernel on the same program, registered once, holding none of this one's session: every trait at its initial
+   * state, no rows the kernel held, its mounted ticks kept. A stateless host serves each request a
+   * fork (EXEC-DIST-5), `ports` answering it.
+   */
+  fork(ports = this.ports) {
+    return new _KernelEngine(this.kernel, this.schemaJson, ports, this.entityTypes, this.handle, void 0, this.preserveProgramContext, this.lazyDir);
+  }
+  forkProgram(program, ports = this.ports) {
+    const schemaJson = JSON.stringify(program);
+    const entityTypes = [.../* @__PURE__ */ new Set([
+      ...this.entityTypes,
+      ...declaredEntityTypes(program)
+    ])];
+    return new _KernelEngine(this.kernel, schemaJson, ports, entityTypes, void 0, this.handle.forkProgram(schemaJson), true);
+  }
+  /** A server over the host's ports. */
+  openServer() {
+    return new this.kernel.Server(this.schemaJson, this.lazyDir);
+  }
+  declare() {
+    const handle = this.handle;
+    declareCapabilities(this.ports.persistence, (entityType, queryJson, writeJson) => handle.setCapabilities(entityType, queryJson, writeJson), this.entityTypes);
+  }
+  /** The contract answers for a host with no program registered yet: the kernel's, asked with no program. */
+  static withoutProgram(kernel) {
+    return contractAnswers((schema, query) => schema.parse(JSON.parse(kernel.contractQueryWithoutProgram(JSON.stringify(query)))));
+  }
+  static open(kernel, schema, ports, lazyDir) {
+    return new _KernelEngine(kernel, JSON.stringify(schema), ports, declaredEntityTypes(schema), void 0, void 0, false, lazyDir);
+  }
+  /** A fresh kernel on the same program: every trait back at its initial state. */
+  reset() {
+    const contextualHandle = this.preserveProgramContext ? this.handle.fork() : void 0;
+    this.handle.free();
+    this.handle = contextualHandle ?? this.openServer();
+    this.declare();
+    if (this.tickRelayIntervalMs !== void 0) this.handle.setTickRelayInterval(this.tickRelayIntervalMs);
+    if (this.stateful) this.handle.setStateful(true);
+    if (this.managedProgram !== void 0) this.handle.setManagedProgram(this.managedProgram);
+  }
+  managedProgram;
+  /** The program whose declared credentials this kernel's credential effects manage beside its own (a console's app). */
+  setManagedProgram(program) {
+    this.managedProgram = JSON.stringify(program);
+    this.handle.setManagedProgram(this.managedProgram);
+  }
+  /** `client` mounted `traits` of `orbital`: their mount-scoped ticks fire while any client holds them. A request derives this itself; this is for a mount made outside a request. */
+  mountClient(client, orbital, traits) {
+    this.handle.mountClient(client, orbital, JSON.stringify(traits));
+  }
+  unmountClient(client, orbital, traits) {
+    this.handle.unmountClient(client, orbital, JSON.stringify(traits));
+  }
+  /** `client` is gone: everything it mounted is released. */
+  releaseClient(client) {
+    this.handle.releaseClient(client);
+  }
+  /** This host holds the circuit state: the kernel takes a client's copy of it only on a delegated leg and refuses any other request carrying one. */
+  setStateful() {
+    this.stateful = true;
+    this.handle.setStateful(true);
+  }
+  /** Whether the program declares any tick: the host runs its timer only then. */
+  declaresTicks() {
+    return this.handle.declaresTicks();
+  }
+  /** Queue a tick-stamped dispatch for the coalesced peer relay; the ms after which to flush when it opened a window. */
+  relayTick(orbital, request) {
+    const window = JSON.parse(this.handle.relayTick(orbital, JSON.stringify(request)));
+    return window ?? void 0;
+  }
+  /** The relay window's length in ms; the kernel's default is 50. */
+  setTickRelayInterval(intervalMs) {
+    this.tickRelayIntervalMs = intervalMs;
+    this.handle.setTickRelayInterval(intervalMs);
+  }
+  /** Every item queued since the window opened, in first-arrival order; the window closes. */
+  flushTickRelay() {
+    return LiveBroadcastItemSchema.array().parse(JSON.parse(this.handle.flushTickRelay()));
+  }
+  /** One pass of the kernel's tick clock: the ticks due at monotonic `nowMs` that this server runs (`[background]` ticks, and those of a mounted trait), keyed by the orbital each `runTick` request is addressed to. */
+  tickPass(nowMs) {
+    return decodeDueTicks(this.handle.tickPass(nowMs));
+  }
+  /** Stop the kernel's tick clock; its phase is kept. */
+  tickPause() {
+    this.handle.tickPause();
+  }
+  /** Restart the kernel's tick clock; the paused span is never counted. */
+  tickResume() {
+    this.handle.tickResume();
+  }
+  tickPaused() {
+    return this.handle.tickPaused();
+  }
+  /** What this host mounts when it starts: the kernel's boot mounts for the side it serves (EXEC-ENDPOINT-3). */
+  bootMounts(side) {
+    return MountSeedSchema.array().parse(JSON.parse(this.handle.bootMounts(side)));
+  }
+  /** What mounts when a client opens `routePath` (EXEC-ENDPOINT-3). */
+  routeMounts(routePath) {
+    return MountSeedSchema.array().parse(JSON.parse(this.handle.routeMounts(routePath)));
+  }
+  dispose() {
+    this.handle.free();
+  }
+  answers = contractAnswers((schema, query) => this.contract(schema, query));
+  contract(schema, query) {
+    return schema.parse(JSON.parse(this.handle.contractQuery(JSON.stringify(query))));
+  }
+  /** Every external input the program declares: what an outside client may send which trait. */
+  externalInputs() {
+    return this.contract(ExternalInputSchema.array(), { kind: "externalInputs" });
+  }
+  /** What the kernel holds of every trait of the program, in name order, and the browser-stored entities. */
+  programSurface() {
+    return this.contract(PROGRAM_SURFACE, { kind: "programSurface" });
+  }
+  /** The entities a provider acting as the caller may read. */
+  readableEntities() {
+    return this.contract(NameListSchema, { kind: "readableEntities" });
+  }
+  /** The declared input of `trait.event` in `orbital`, when there is one. */
+  findExternalInput(orbital, trait, event) {
+    return this.answers.findExternalInput(orbital, trait, event);
+  }
+  /** The declared input a `listens`-addressed event names from `caller`'s position (`EVENT`, `Trait.EVENT`, `Orbital.Trait.EVENT`), when there is one. */
+  findInputByAddress(address, caller) {
+    return this.contract(ExternalInputSchema.nullable(), { kind: "findInputByAddress", address, caller }) ?? void 0;
+  }
+  /** A declared payload as the JSON Schema of one object: what a tool-calling model fills. */
+  payloadJsonSchema(fields) {
+    return this.contract(PayloadJsonSchemaSchema, { kind: "payloadSchemaToJsonSchema", fields });
+  }
+  /** The ways `value` misses the declared payload `fields`. */
+  payloadIssues(fields, value) {
+    return this.contract(PayloadIssueSchema.array(), { kind: "payloadIssues", fields, value });
+  }
+  /** The route a hook name is delivered to, or the answer to write for a hook the program does not serve. */
+  findInbound(name) {
+    return this.answers.findInbound(name);
+  }
+  /** The trait that handles `event` as an inbound hook in `orbital`, with the refusal message, when a client-facing request names it. */
+  inboundOnly(orbital, trait, event) {
+    return this.contract(InboundOnlySchema, { kind: "inboundOnly", orbital, ...trait !== void 0 ? { trait } : {}, event }) ?? void 0;
+  }
+  /** The payload an inbound event is delivered with. */
+  inboundPayload(route, delivery, credential) {
+    return this.answers.inboundPayload(route, delivery, credential);
+  }
+  /** The HTTP answer a finished dispatch produced for `route`. */
+  inboundAnswer(route, emitted, error) {
+    return this.answers.inboundAnswer(route, emitted, error);
+  }
+  /** The answer for a route whose credential the host holds no value for. */
+  credentialUnset(credential) {
+    return this.answers.credentialUnset(credential);
+  }
+  /** The answer for a delivery whose dispatch failed. */
+  dispatchFailed(message) {
+    return this.answers.dispatchFailed(message);
+  }
+  /** The name of the program's `[identity]` entity, when it declares one. */
+  identityEntity() {
+    return this.contract(OptionalNameSchema, { kind: "identityEntity" }) ?? void 0;
+  }
+  /** The orbital that declares `entity` inline. */
+  entityOwnerOrbital(entity) {
+    return this.contract(OptionalNameSchema, { kind: "entityOwner", entity }) ?? void 0;
+  }
+  /** `rows` of `entity` as `user` reads them: narrowed by the entity's declared `@read`, which the kernel evaluates with `@user` bound to the viewer. */
+  readRows(entity, rows, user) {
+    return this.contract(EntityRowSchema.array(), { kind: "readRows", entity, rows, viewer: user ?? null });
+  }
+  liveItemDelivered(item, clientId) {
+    return this.handle.liveItemDelivered(JSON.stringify(item), clientId);
+  }
+  /** `OsGrants::allows` over the grants of `orbital` in the program this kernel runs (the app level alone with no orbital). */
+  osAllows(requirementJson, orbital) {
+    return this.handle.osAllows(requirementJson, orbital);
+  }
+  /** Whether `url`'s origin is declared in the program's `egress` (the kernel's rule). */
+  egressAllows(url) {
+    return this.handle.egressAllows(url);
+  }
+  /** Place the program's anchored grants and arguments under the host's anchors. */
+  setOsAnchors(anchorsJson) {
+    return this.handle.setOsAnchors(anchorsJson);
+  }
+  /** An `os/` call's arguments with its anchored parts resolved under the host's anchors. */
+  osResolveArgs(op, argsJson) {
+    return this.handle.osResolveArgs(op, argsJson);
+  }
+  tlsComplete(key, outcomeJson) {
+    return this.handle.tlsComplete(key, outcomeJson);
+  }
+  /** A live stream of `client`'s session opened (EXEC-DIST-9); the id closes it. */
+  openSessionStream(client) {
+    return this.handle.openSessionStream(client);
+  }
+  /** The live stream `id` dropped: the kernel frees the session once its streams have all dropped and it is quiet. */
+  closeSessionStream(id) {
+    return this.handle.closeSessionStream(id);
+  }
+  /** The current state of a trait instance, `''` when it has none. */
+  stateOf(traitName, entityId) {
+    return this.handle.getState(traitName, entityId);
+  }
+  /**
+   * `reference` resolved for the identity `scope.originClientId`'s session bound (the anonymous viewer with none) against the host-answered store (EXEC-RENDER-3): the rows that still
+   * match its query and that identity's `@read` in the reference's order, a missing or hidden row omitted, and `total`
+   * re-counted (a `total: none` reference is not re-counted: the total is the resolved window). Each read the
+   * kernel makes is answered here, as in `evaluate`.
+   */
+  async resolveRows(reference, scope) {
+    const handle = this.handle;
+    let progress = decodeResolveProgress(handle.resolveRows(JSON.stringify(reference), scope.originClientId));
+    while (progress.status === "await") {
+      const { flight, requests } = progress;
+      let replies;
+      try {
+        replies = await Promise.all(
+          requests.map(async (pending) => ({ id: pending.id, answer: await answerRequest(this.ports, pending.request, scope) }))
+        );
+      } catch (error) {
+        handle.abandon(flight);
+        throw error;
+      }
+      progress = decodeResolveProgress(handle.resumeResolve(flight, JSON.stringify(replies)));
+    }
+    return { rows: progress.rows, total: progress.total };
+  }
+  /**
+   * Run `request` against `orbital`. The kernel orders every start and every resumption (EXEC-CONC-2): while another
+   * dispatch holds the lane it answers `queued` and runs the work itself once the lane frees; this host only answers
+   * what each dispatch asks.
+   */
+  async evaluate(orbital, request, scope) {
+    const handle = this.handle;
+    const streams = scope.onStream !== void 0;
+    let running = await this.ran(handle.start(orbital, JSON.stringify(request)), streams);
+    try {
+      while (running.progress.status === "await") {
+        const { flight, requests } = running.progress;
+        const assertReentry = () => {
+          if (handle.holdsLane(flight)) throw new LaneHeldByParkedDispatch(flight, request.event);
+        };
+        let replies;
+        try {
+          replies = await Promise.all(
+            requests.map(async (pending) => ({ id: pending.id, answer: await answerRequest(this.ports, pending.request, { ...scope, assertReentry }) }))
+          );
+        } catch (error) {
+          handle.abandon(flight);
+          throw error;
+        }
+        running = await this.ran(handle.resume(flight, JSON.stringify(replies)), streams);
+      }
+    } finally {
+      this.runQueued();
+    }
+    if (scope.onStream !== void 0 && running.stream !== void 0) {
+      const items = JSON.parse(running.stream);
+      for (const item of items) scope.onStream(item);
+      scope.onStream({ type: "complete", data: running.progress.response, timestamp: Date.now() });
+    }
+    return running.progress.response;
+  }
+  /** The kernel's answer to a start or resume, once it has run: at once, or when the kernel takes it from its queue. */
+  ran(json, streams) {
+    const progress = decodeProgress(json);
+    if (progress.status !== "queued") return this.running(progress, streams);
+    const turn = new Promise((ran, failed) => {
+      this.turns.set(progress.ticket, { streams, ran, failed });
+    });
+    queueMicrotask(() => this.runQueued());
+    return turn;
+  }
+  running(progress, streams) {
+    return { progress, stream: streams && progress.status === "done" ? this.handle.dispatchStream() : void 0 };
+  }
+  /** Run each piece of queued work that can run now, in the kernel's order, handing each to the dispatch it continues. */
+  runQueued() {
+    for (; ; ) {
+      const next = decodeNext(this.handle.next());
+      if (next === null) return;
+      const turn = this.turns.get(next.ticket);
+      if (turn === void 0) throw new Error(`kernel wire: the kernel ran ticket ${next.ticket}, which nothing waits on`);
+      this.turns.delete(next.ticket);
+      if (next.outcome === "failed") {
+        turn.failed(new Error(next.error));
+        continue;
+      }
+      if (next.progress.status === "queued") throw new Error("kernel wire: the kernel queued work it was running");
+      turn.ran(this.running(next.progress, turn.streams));
+    }
+  }
+};
+function kernelRequest(request, locale) {
+  const { _activeTraits: _dropped, _targetTrait: sidecarTarget, ...rest } = request.payload ?? {};
+  const payload = rest;
+  const target = request.targetTrait ?? (typeof sidecarTarget === "string" ? sidecarTarget : void 0);
+  const { payload: _payload, user: _hostViewer, ...others } = request;
+  return {
+    ...others,
+    ...request.payload !== void 0 ? { payload } : {},
+    ...target !== void 0 ? { targetTrait: target } : {},
+    ...locale !== void 0 ? { locale } : {}
+  };
+}
+function withOriginClient(response, clientId) {
+  if (clientId === void 0) return response;
+  return {
+    ...response,
+    emittedEvents: response.emittedEvents.map((emitted) => emitted.source === void 0 ? emitted : { ...emitted, source: { ...emitted.source, originClientId: emitted.source.originClientId ?? clientId } })
+  };
+}
+async function evaluateOnKernel(kernel, request, locale) {
+  return withOriginClient(await kernel.engine.evaluate(kernel.orbital, kernelRequest(request, locale), {
+    orbital: kernel.orbital,
+    ...request.clientId !== void 0 ? { originClientId: request.clientId } : {},
+    ...locale !== void 0 ? { locale } : {},
+    ...request.entityId !== void 0 ? { entityId: request.entityId } : {},
+    ...kernel.onStream !== void 0 ? { onStream: (item) => {
+      if (item.type === "event" && item.data.source !== void 0 && request.clientId !== void 0) {
+        kernel.onStream?.({ ...item, data: { ...item.data, source: { ...item.data.source, originClientId: item.data.source.originClientId ?? request.clientId } } });
+      } else if (item.type === "complete") {
+        kernel.onStream?.({ ...item, data: withOriginClient(item.data, request.clientId) });
+      } else kernel.onStream?.(item);
+    } } : {}
+  }), request.clientId);
+}
+
+export { KernelEngine, evaluateOnKernel, kernelRequest };

package/dist/chunk-IOPUS6Q5.js

@@ -0,0 +1,15 @@
+// src/client/trait-mount-error.ts
+var TraitMountError = class extends Error {
+  trait;
+  event;
+  original;
+  constructor(trait, event, original) {
+    super(original.message);
+    this.name = "TraitMountError";
+    this.trait = trait;
+    this.event = event;
+    this.original = original;
+  }
+};
+
+export { TraitMountError };

package/dist/chunk-LKWYCYX5.js

@@ -0,0 +1,22 @@
+// src/client/declared-input-dispatch.ts
+async function dispatchDeclaredInput(contract, orbitalName, request, send) {
+  const declared = contract.findExternalInput(orbitalName, request.targetTrait, request.event);
+  if (!declared) {
+    return {
+      success: false,
+      transitioned: false,
+      states: {},
+      emittedEvents: [],
+      error: `'${request.event}' is not an external input of ${orbitalName}.${request.targetTrait}`,
+      rejections: [{ code: "not-an-external-input", trait: request.targetTrait, event: request.event }]
+    };
+  }
+  return send(orbitalName, {
+    event: request.event,
+    payload: request.payload ?? {},
+    targetTrait: request.targetTrait,
+    ...request.entityId !== void 0 ? { entityId: request.entityId } : {}
+  });
+}
+
+export { dispatchDeclaredInput };

package/dist/chunk-LYFIQPXX.js

@@ -0,0 +1 @@
+

package/dist/chunk-LZIOTBFX.js

@@ -0,0 +1 @@
+

package/dist/chunk-MU335ZA4.js

@@ -0,0 +1,63 @@
+import { defaultCallService } from './chunk-4SEK5ER2.js';
+import { routeByEntity } from './chunk-O57GKTYU.js';
+import { KernelEngine, evaluateOnKernel } from './chunk-I3TKINSO.js';
+import { InFlightCalls } from './chunk-MZKIL5IN.js';
+import { createInProcessTransport } from './chunk-UD2CXYSJ.js';
+import { orbitalInlineEntities, storesRowsInBrowser, inlineTraitRefs } from '@almadar/core';
+
+var LOCAL_CLIENT = "local";
+function localStorePersistence(schema, store, memory) {
+  const browserStored = new Set(schema.orbitals.flatMap(orbitalInlineEntities).filter(storesRowsInBrowser).map((entity) => entity.name));
+  return routeByEntity(browserStored, store, memory);
+}
+function openLocalKernel(options) {
+  const { schema, persistence } = options;
+  const callService = options.callService ?? defaultCallService;
+  const engine = KernelEngine.open(options.kernel, { ...schema, orbitals: inlineTraitRefs(schema.orbitals) }, {
+    persistence,
+    callService: (service, action, params, context) => callService(service, action, params, context),
+    programEffect: () => void 0,
+    inFlightCalls: new InFlightCalls(),
+    servicePorts: options.servicePorts ?? ((caller, user, message) => ({
+      caller,
+      message,
+      inputs: () => engine.externalInputs(),
+      readableEntities: () => engine.readableEntities(),
+      dispatchInput: () => Promise.reject(new Error("a local store host takes no input dispatch")),
+      read: async (entity) => engine.readRows(entity, await persistence.list(entity), user)
+    })),
+    deliverLive: () => void 0,
+    deferCallOutcome: options.deferCallOutcome ?? (() => void 0),
+    ...options.pageFacts !== void 0 ? { pageFacts: options.pageFacts } : {},
+    ...options.hostActions !== void 0 ? { hostActions: options.hostActions } : {},
+    ...options.secretPorts !== void 0 ? { secretPorts: options.secretPorts } : {},
+    ...options.onDevice !== void 0 ? { onDevice: options.onDevice } : {},
+    ...options.tabs !== void 0 ? { tabs: options.tabs } : {},
+    ...options.os !== void 0 ? { os: options.os } : {}
+  });
+  for (const trait of engine.programSurface().traits) engine.mountClient(LOCAL_CLIENT, trait.orbital, [trait.name]);
+  return engine;
+}
+function createLocalStoreTransport(options) {
+  return createInProcessTransport(
+    async (orbital, request) => evaluateOnKernel(
+      { engine: await options.kernelEngine, orbital },
+      request,
+      request.locale ?? options.locale?.()
+    ),
+    {
+      carriesCircuitState: false,
+      ...options.schema !== void 0 ? { resolveRows: resolveOn(options) } : {}
+    }
+  );
+}
+function resolveOn(options) {
+  return async (reference) => resolveLocalRows(await options.kernelEngine, reference);
+}
+function resolveLocalRows(engine, reference) {
+  const owner = engine.entityOwnerOrbital(reference.entityType);
+  if (owner === void 0) return Promise.reject(new Error(`${reference.entityType}: no orbital of the local program declares this entity`));
+  return engine.resolveRows(reference, { orbital: owner });
+}
+
+export { createLocalStoreTransport, localStorePersistence, openLocalKernel, resolveLocalRows };

package/dist/chunk-MZKIL5IN.js

@@ -0,0 +1,74 @@
+// src/effects/in-flight-calls.ts
+var InFlightCalls = class {
+  calls = /* @__PURE__ */ new Map();
+  /** Whether a call started with `key` is still running. */
+  inFlight(key) {
+    return (this.calls.get(key)?.size ?? 0) > 0;
+  }
+  /**
+   * Run `work` registered under `key`, handing it the abort signal; `work` must settle promptly once the
+   * signal aborts (see `untilAborted`). The call is cancelled when the signal was aborted by the time
+   * `work` settles, whatever it settled with.
+   */
+  async run(key, work) {
+    const lease = this.track(key);
+    try {
+      const value = await work(lease.signal);
+      return lease.signal.aborted ? { cancelled: true } : { cancelled: false, value };
+    } catch (err) {
+      if (lease.signal.aborted) return { cancelled: true };
+      throw err;
+    } finally {
+      lease.release();
+    }
+  }
+  reserve(key) {
+    return this.inFlight(key) ? void 0 : this.track(key);
+  }
+  track(key) {
+    const controller = new AbortController();
+    const running = this.calls.get(key) ?? /* @__PURE__ */ new Set();
+    running.add(controller);
+    this.calls.set(key, running);
+    return {
+      signal: controller.signal,
+      release: () => {
+        running.delete(controller);
+        if (running.size === 0 && this.calls.get(key) === running) this.calls.delete(key);
+      }
+    };
+  }
+  cancelAll() {
+    for (const key of this.calls.keys()) this.cancel(key);
+  }
+  /** Abort every call running under `key`; false (a no-op) when none is. */
+  cancel(key) {
+    const running = this.calls.get(key);
+    if (running === void 0 || running.size === 0) return false;
+    this.calls.delete(key);
+    for (const controller of running) controller.abort();
+    return true;
+  }
+};
+function untilAborted(signal, promise) {
+  if (signal.aborted) {
+    promise.catch(() => void 0);
+    return Promise.reject(new Error("The call was cancelled"));
+  }
+  return new Promise((resolve, reject) => {
+    const onAbort = () => reject(new Error("The call was cancelled"));
+    signal.addEventListener("abort", onAbort, { once: true });
+    promise.then(
+      (value) => {
+        signal.removeEventListener("abort", onAbort);
+        resolve(value);
+      },
+      (err) => {
+        signal.removeEventListener("abort", onAbort);
+        reject(err);
+      }
+    );
+  });
+}
+
+export { InFlightCalls, untilAborted };

package/dist/chunk-N7HYNKK6.js

@@ -0,0 +1,83 @@
+import { StateBook } from './chunk-A2JJT4GA.js';
+import { AwaitingRegistry } from './chunk-HC6ERSAH.js';
+
+// src/client/circuit-store.ts
+function createMemoryCircuitStore(traits = [], observer) {
+  const states = new StateBook(traits, observer);
+  const frames = /* @__PURE__ */ new Map();
+  const listeners = /* @__PURE__ */ new Set();
+  let version = 0;
+  let frameVersion = 0;
+  let frameSession;
+  return {
+    states,
+    frames,
+    get frameVersion() {
+      return frameVersion;
+    },
+    applyFrames(delta) {
+      if (delta.session !== void 0) {
+        const snapshot = delta.from === 0 && delta.ops[0]?.[0] === "clear";
+        if (!snapshot) {
+          const current = (frameSession === void 0 || delta.session === frameSession) && delta.from === frameVersion;
+          if (delta.session === frameSession && delta.to <= frameVersion && !current) return "stale";
+          if (!current) return "gap";
+        }
+        frameSession = delta.session;
+        frameVersion = delta.to;
+      }
+      for (const op of delta.ops) {
+        switch (op[0]) {
+          case "clear":
+            frames.clear();
+            break;
+          case "del":
+            frames.delete(op[1]);
+            break;
+          case "put":
+            frames.set(op[1], { ...op[2] });
+            break;
+          case "set":
+            for (const [frame, fields] of Object.entries(op[1])) frames.set(frame, { ...frames.get(frame) ?? {}, ...fields });
+            break;
+        }
+      }
+      return "applied";
+    },
+    awaiting: new AwaitingRegistry(),
+    snapshot(trait, entityId, frameKey) {
+      const key = frameKey ?? trait;
+      const frame = frames.get(key);
+      return {
+        state: states.getState(trait, entityId)?.currentState ?? "",
+        frame: frame !== void 0 ? { ...frame } : void 0
+      };
+    },
+    restore(trait, entityId, snap, frameKey, cause) {
+      const key = frameKey ?? trait;
+      if (snap.state !== "") {
+        states.rollbackState(trait, snap.state, entityId, cause);
+      }
+      if (snap.frame === void 0) {
+        frames.delete(key);
+      } else {
+        frames.set(key, { ...snap.frame });
+      }
+    },
+    notify() {
+      version += 1;
+      for (const listener of listeners) listener();
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    getVersion() {
+      return version;
+    }
+  };
+}
+
+export { createMemoryCircuitStore };