@almadar/shell-runtime 0.1.0 → 1.0.0

package/dist/{chunk-QQRDUMB2.js → chunk-QCJWPXLH.js}

@@ -1,16 +1,16 @@
 // src/client/local-fold.ts
-function mirrorResponse(store, frameKeyOf, response) {
+function paintStates(store, response) {
   for (const [trait, state] of Object.entries(response.states)) {
     if (store.states.getState(trait)?.currentState !== state) store.states.seedState(trait, state);
   }
-  for (const [trait, row] of Object.entries(response.entityByTrait ?? {})) {
-    const frameKey = frameKeyOf(trait);
-    if (frameKey === void 0) continue;
-    store.frames.set(frameKey, { ...store.frames.get(frameKey) ?? {}, ...row });
-  }
-  for (const effect of response.clientEffectsByTrait ?? []) {
-    if (effect.callsitePayload !== void 0) store.callsitePayloads.set(effect.traitName, effect.callsitePayload);
-  }
+}
+function paintFrames(store, delta, framesSince) {
+  if (delta === void 0) return;
+  if (store.applyFrames(delta) === "gap") store.applyFrames(framesSince(store.frameVersion));
+}
+function paintResponse(store, framesSince, response) {
+  paintStates(store, response);
+  paintFrames(store, response.frames, framesSince);
 }
 function traceResponse(observer, response) {
   if (observer === void 0) return;
@@ -31,10 +31,10 @@ function createLocalFold(opts) {
   return {
     foldLocalResponse: async (response, traceHops, notify) => {
       if (traceHops) traceResponse(opts.observer, response);
-      mirrorResponse(opts.store, opts.frameKeyOf, response);
+      paintResponse(opts.store, opts.framesSince, response);
       if (notify) opts.store.notify();
     }
   };
 }
 
-export { createLocalFold, mirrorResponse, traceResponse };
+export { createLocalFold, paintFrames, paintResponse, paintStates, traceResponse };

package/dist/{chunk-QELZ6TEJ.js → chunk-UD2CXYSJ.js}

@@ -88,6 +88,34 @@ function acquirePushChannel(key, resolveUrl, resumeKey, subscriber) {
     }
   };
 }
+var SessionEndedError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "SessionEndedError";
+  }
+};
+var TransportStatusError = class extends Error {
+  constructor(status, bodyText) {
+    super(`the server answered ${status}${bodyText.length > 0 ? `: ${bodyText}` : " with no body"}`);
+    this.status = status;
+    this.bodyText = bodyText;
+    this.refusal = parseRefusal(bodyText);
+    this.name = "TransportStatusError";
+  }
+  status;
+  bodyText;
+  /** The `{ error, code }` body when the answer carried one. */
+  refusal;
+};
+function parseRefusal(text) {
+  if (text.length === 0) return void 0;
+  try {
+    const parsed = JSON.parse(text);
+    return typeof parsed === "object" && parsed !== null ? parsed : void 0;
+  } catch {
+    return void 0;
+  }
+}
 var COMPRESSED_BODY_MIN_BYTES = 32 * 1024;
 async function encodeJsonBody(value, compress) {
   const text = JSON.stringify(value);
@@ -122,8 +150,9 @@ function createHttpTransport(options) {
       return `${eventsUrl}?${search.toString()}`;
     };
     const key = `${eventsUrl}?${new URLSearchParams(params).toString()}`;
+    const mintUrl = params["clientId"] !== void 0 ? `${eventsUrl}/ticket?${new URLSearchParams({ clientId: params["clientId"] }).toString()}` : `${eventsUrl}/ticket`;
     const resolveUrl = async () => {
-      const reply = await fetchFn(`${eventsUrl}/ticket`, { method: "POST", headers: await authHeaders(getAccessToken) });
+      const reply = await fetchFn(mintUrl, { method: "POST", headers: await authHeaders(getAccessToken) });
       if (!reply.ok) throw new Error(`the server refused a stream ticket: ${reply.status}`);
       const body = await reply.json();
       if (typeof body.ticket !== "string" || body.ticket.length === 0) throw new Error("the server sent no stream ticket");
@@ -169,7 +198,14 @@ function createHttpTransport(options) {
         getAccessToken,
         compress
       );
-      return await res.json();
+      const text = await res.text();
+      if (res.status === 409) {
+        const refusal = parseRefusal(text);
+        if (refusal?.code === "SESSION_ENDED") throw new SessionEndedError(refusal.error ?? "the session ended");
+      }
+      if (!res.ok && res.status !== 403) throw new TransportStatusError(res.status, text);
+      const body = JSON.parse(text);
+      return body;
     },
     async resolveRows(reference) {
       const res = await jsonPost(fetchFn, `${serverUrl}/resolve-rows`, { ref: reference }, getAccessToken, compress);
@@ -205,4 +241,4 @@ function createInProcessTransport(evaluate, options = {}) {
   };
 }
 
-export { COMPRESSED_BODY_MIN_BYTES, createHttpTransport, createInProcessTransport, deriveCarriesCircuitState, encodeJsonBody };
+export { COMPRESSED_BODY_MIN_BYTES, SessionEndedError, TransportStatusError, createHttpTransport, createInProcessTransport, deriveCarriesCircuitState, encodeJsonBody };

package/dist/{chunk-UJHOUZAL.js → chunk-V4EMDPCO.js}

@@ -1,9 +1,6 @@
-import { storesRowsInBrowser } from '@almadar/core';
-
 // src/runtime/evaluation/residence-transport.ts
 function createResidenceTransport(options) {
-  const { local, remote, traitIndex } = options;
-  const browserStored = new Set(traitIndex.allEntities.filter(storesRowsInBrowser).map((e) => e.name));
+  const { local, remote, browserEntities } = options;
   const route = (orbitalName, request) => {
     if (request.residence === "browser") return local;
     if (request.residence === "server") {
@@ -25,7 +22,7 @@ function createResidenceTransport(options) {
       return route(orbitalName, request).send(orbitalName, request);
     },
     async resolveRows(reference) {
-      const owner = browserStored.has(reference.entityType) ? local : remote;
+      const owner = browserEntities.has(reference.entityType) ? local : remote;
       if (owner?.resolveRows === void 0) throw new Error(`residence: no transport resolves ${reference.entityType} row sets`);
       return owner.resolveRows(reference);
     },

package/dist/chunk-VNGXRYFF.js

@@ -0,0 +1,9 @@
+// src/credentials/env-vars.ts
+var CREDENTIAL_MASTER_KEY_ENV = "ALMADAR_CREDENTIAL_MASTER_KEY";
+var CREDENTIAL_PREVIOUS_MASTER_KEY_ENV = "ALMADAR_CREDENTIAL_MASTER_KEY_PREVIOUS";
+var STORE_BOOTSTRAP_ENV_VARS = /* @__PURE__ */ new Set([CREDENTIAL_MASTER_KEY_ENV, CREDENTIAL_PREVIOUS_MASTER_KEY_ENV]);
+function allCredentialEnvVars() {
+  return new Set(STORE_BOOTSTRAP_ENV_VARS);
+}
+
+export { CREDENTIAL_MASTER_KEY_ENV, CREDENTIAL_PREVIOUS_MASTER_KEY_ENV, STORE_BOOTSTRAP_ENV_VARS, allCredentialEnvVars };

package/dist/{chunk-HNOAZWFH.js → chunk-WGCWJOT2.js}

@@ -9,6 +9,8 @@ var PROGRAM_EFFECTS = [
   "program/print",
   "program/eval",
   "program/validate",
+  "program/prove",
+  "program/os-grants",
   "program/compose",
   "program/step"
 ];

package/dist/chunk-X6W44WHO.js

@@ -0,0 +1,26 @@
+import { decodeServerProgressWire, decodeNextWire, decodeResolveProgressWire, decodeFiredTick } from '@almadar/core/kernel-wire';
+export { decodeIoRequestWire } from '@almadar/core/kernel-wire';
+
+// src/kernel/decode.ts
+function decodeProgress(json) {
+  return decodeServerProgressWire(JSON.parse(json));
+}
+function decodeNext(json) {
+  const value = JSON.parse(json);
+  return value === null ? null : decodeNextWire(value);
+}
+function decodeResolveProgress(json) {
+  return decodeResolveProgressWire(JSON.parse(json));
+}
+function decodeDueTicks(json) {
+  const value = JSON.parse(json);
+  if (value === null || typeof value !== "object" || Array.isArray(value)) throw new Error("tickPass: the kernel answered a non-object");
+  const byOrbital = {};
+  for (const [orbital, ticks] of Object.entries(value)) {
+    if (!Array.isArray(ticks)) throw new Error(`tickPass: the kernel answered a non-list for orbital ${orbital}`);
+    byOrbital[orbital] = ticks.map(decodeFiredTick);
+  }
+  return byOrbital;
+}
+
+export { decodeDueTicks, decodeNext, decodeProgress, decodeResolveProgress };

package/dist/chunk-ZUSM4VW4.js

@@ -0,0 +1,197 @@
+import { resolveCredentialRef, getEffectiveCredentialStore, getModeControl } from './chunk-HLOUDLPI.js';
+import { credentialStorageKey, resolveCredentialStatusIdentity, credentialStatusConnected } from '@almadar/core';
+
+function userCredentialKey(principal, name) {
+  return credentialStorageKey({ name, principal });
+}
+function envTailsOf(env) {
+  return (names) => {
+    const tails = [];
+    for (const name of names) {
+      const value = env[name];
+      if (value === void 0 || value === "") continue;
+      const chars = Array.from(value);
+      tails.push(chars.length >= 8 ? { name, last4: chars.slice(-4).join("") } : { name });
+    }
+    return tails;
+  };
+}
+var installedSecretsHost = {
+  async store() {
+    return getEffectiveCredentialStore();
+  },
+  async resolve(name, principal) {
+    return resolveCredentialRef(name, void 0, principal);
+  }
+};
+function createSecretStore(now = Date.now, host = installedSecretsHost, tokenPost) {
+  const environmentMinted = /* @__PURE__ */ new Map();
+  const storeMinted = /* @__PURE__ */ new WeakMap();
+  const cacheFor = (store) => {
+    if (store === null) return environmentMinted;
+    const held = storeMinted.get(store);
+    if (held !== void 0) return held;
+    const cache = /* @__PURE__ */ new Map();
+    storeMinted.set(store, cache);
+    return cache;
+  };
+  const slot = (name, principal) => credentialStorageKey({ name, ...principal !== void 0 ? { principal } : {} });
+  return {
+    async get(name, principal) {
+      const store = await host.store();
+      const minted = cacheFor(store);
+      const key = slot(name, principal);
+      const held = minted.get(key);
+      if (held !== void 0) {
+        if (held.expiresAt > now()) return held.value;
+        minted.delete(key);
+      }
+      if (store !== null && store.enabled && tokenPost !== void 0) {
+        const fresh = await store.resolveFresh(name, principal, tokenPost);
+        if (fresh !== void 0) return fresh;
+      }
+      return host.resolve(name, principal);
+    },
+    async set(name, value, ttlMs, principal) {
+      const minted = cacheFor(await host.store());
+      const key = slot(name, principal);
+      if (ttlMs <= 0) minted.delete(key);
+      else minted.set(key, { value, expiresAt: now() + ttlMs });
+    },
+    async rotate(name, value, principal) {
+      const store = await host.store();
+      if (store === null) throw new Error("this host keeps no credential store to rotate into");
+      cacheFor(store).delete(slot(name, principal));
+      await store.replace(name, value, principal);
+    },
+    async persist(name, value, principal, label) {
+      const store = await host.store();
+      if (store === null || !store.enabled) throw new Error("this host keeps no credential store to persist into");
+      cacheFor(store).delete(slot(name, principal));
+      await store.persist(name, value, principal, label);
+    },
+    async label(name, principal) {
+      return (await host.store())?.label(name, principal);
+    },
+    async durable() {
+      const store = await host.store();
+      return store !== null && store.enabled;
+    },
+    async forget(name, principal) {
+      const store = await host.store();
+      const minted = cacheFor(store);
+      const key = slot(name, principal);
+      minted.delete(key);
+      await store?.remove(name, principal);
+    }
+  };
+}
+function createCredentialConnectPort(post) {
+  return async (grant) => {
+    const store = getEffectiveCredentialStore();
+    if (store === null || !store.enabled) return { error: { kind: "unavailable", message: "this host holds no credential store that can connect" } };
+    return store.connect(grant, post);
+  };
+}
+function createCredentialAdminPort() {
+  const installed = () => {
+    const store = getEffectiveCredentialStore();
+    if (store === null) throw new Error("this host keeps no credential store");
+    return store;
+  };
+  return {
+    async list() {
+      return getEffectiveCredentialStore()?.listing() ?? null;
+    },
+    async read(name) {
+      return getEffectiveCredentialStore()?.resolve(name) ?? null;
+    },
+    async write(service, name, value) {
+      await installed().set(service, name, value);
+    },
+    async remove(name) {
+      return installed().remove(name);
+    },
+    async rotate() {
+      return installed().rotate();
+    },
+    async mode() {
+      return getModeControl()?.mode ?? null;
+    },
+    async setMode(mode) {
+      const control = getModeControl();
+      if (control === null) throw new Error("No integration manager is installed on this host");
+      if (mode !== "mock" && mode !== "real") throw new Error(`mode must be "mock" or "real", got "${mode}"`);
+      control.setMode(mode);
+      return control.mode;
+    }
+  };
+}
+var systemRandom = (bytes) => crypto.getRandomValues(new Uint8Array(bytes));
+var RANDOM_BYTES_MAX = 1024;
+function binary(bytes) {
+  let text = "";
+  for (const byte of bytes) text += String.fromCharCode(byte);
+  return text;
+}
+function base64Standard(bytes) {
+  return btoa(binary(bytes));
+}
+function base64Url(bytes) {
+  return base64Standard(bytes).replaceAll("+", "-").replaceAll("/", "_").replaceAll("=", "");
+}
+function randomBytesPayload(ports, bytes, key) {
+  if (key !== void 0 && (typeof key !== "string" || key === "")) {
+    throw new Error(`call key must evaluate to a non-empty string, got ${String(key)}`);
+  }
+  if (typeof bytes !== "number" || !Number.isInteger(bytes) || bytes < 1 || bytes > RANDOM_BYTES_MAX) {
+    throw new Error(`random-bytes: the byte count must be an integer from 1 to ${RANDOM_BYTES_MAX}, got ${String(bytes)}`);
+  }
+  const value = base64Url(ports.random(bytes));
+  return key === void 0 ? { value } : { value, key };
+}
+function signedIn(head, principal) {
+  if (principal === void 0) throw new Error(`${head}: nobody is signed in`);
+  return principal;
+}
+function credentialName(head, credential) {
+  if (typeof credential !== "string") throw new Error(`${head}: the credential must be a secret knob's name`);
+  return credential;
+}
+async function credentialStatusPayload(ports, credential, principal) {
+  const identity = resolveCredentialStatusIdentity(credential, principal);
+  const connected = credentialStatusConnected(await ports.secrets.get(identity.name, identity.principal), identity.principal);
+  const label = connected ? await ports.secrets.label?.(identity.name, identity.principal) ?? "" : "";
+  return { connected, label };
+}
+async function credentialForgetPayload(ports, credential, principal) {
+  const who = signedIn("credential-forget", principal);
+  const name = credentialName("credential-forget", credential);
+  await ports.secrets.forget(name, who);
+  return { connected: false, label: "" };
+}
+function createSecretPorts(options = {}) {
+  return {
+    random: options.random ?? systemRandom,
+    secrets: options.secrets ?? createSecretStore(Date.now, installedSecretsHost, options.tokenPost),
+    credentials: options.credentials ?? createCredentialAdminPort(),
+    env: options.env ?? ((names) => envTailsOf(process.env)(names)),
+    ...options.tokenPost !== void 0 ? { connect: createCredentialConnectPort(options.tokenPost) } : {}
+  };
+}
+var browserSecrets = {
+  async get(name) {
+    throw new Error(`credential ${name} is not available in a browser`);
+  },
+  async set(name) {
+    throw new Error(`credential ${name} cannot be stored in a browser`);
+  },
+  async forget(name) {
+    throw new Error(`credential ${name} cannot be forgotten in a browser`);
+  }
+};
+function createBrowserSecretPorts() {
+  return { random: systemRandom, secrets: browserSecrets };
+}
+
+export { RANDOM_BYTES_MAX, base64Standard, base64Url, createBrowserSecretPorts, createCredentialAdminPort, createCredentialConnectPort, createSecretPorts, createSecretStore, credentialForgetPayload, credentialStatusPayload, envTailsOf, randomBytesPayload, systemRandom, userCredentialKey };

package/dist/client/EventTransport.d.ts

@@ -1,4 +1,4 @@
-import { OrbitalSchema, OrbitalEventRequest, OrbitalEventResponse, RowSetRef, RowQueryPage, EmittedEvent, ServerTopology } from '@almadar/core';
+import { OrbitalSchema, EventRequest, EventResponse, RowSetRef, RowQueryPage, EmittedEvent, ServerTopology } from '@almadar/core';
 
 /**
  * EventTransport — the client → orbital event transport port (plan P5,
@@ -11,8 +11,8 @@ import { OrbitalSchema, OrbitalEventRequest, OrbitalEventResponse, RowSetRef, Ro
  * be switched onto this port at the W5b build checkpoint (see the plan);
  * until then this file has no consumers outside this package.
  *
- * The wire shapes are `@almadar/core`'s existing `OrbitalEventRequest` /
- * `OrbitalEventResponse` — no shadow types.
+ * The wire shapes are `@almadar/core`'s existing `EventRequest` /
+ * `EventResponse` — no shadow types.
  *
  * @packageDocumentation
  */
@@ -48,7 +48,7 @@ interface EventTransport {
     register(schema: OrbitalSchema): Promise<EventTransportRegisterResult>;
     unregister(): Promise<void>;
     /** Play one event through the orbital named `orbitalName`. */
-    send(orbitalName: string, request: OrbitalEventRequest): Promise<OrbitalEventResponse>;
+    send(orbitalName: string, request: EventRequest): Promise<EventResponse>;
     /**
      * A row-set reference resolved by the host that holds the rows, for the viewer the transport is signed in as (the
      * host applies `@read`): the rows that still match, in the reference's order. Absent when the transport has no
@@ -78,7 +78,7 @@ interface EventTransport {
     subscribeHostDispatches?(onDispatch: HostDispatchListener, params?: Record<string, string>): () => void;
 }
 /** A dispatch the host ran on its own, with its result. */
-type HostDispatchListener = (orbitalName: string, request: OrbitalEventRequest, response: OrbitalEventResponse) => void;
+type HostDispatchListener = (orbitalName: string, request: EventRequest, response: EventResponse) => void;
 /**
  * Supplies the bearer token the hosting server authenticates with. Resolved
  * per request (tokens expire); `undefined` sends the request unauthenticated
@@ -86,6 +86,22 @@ type HostDispatchListener = (orbitalName: string, request: OrbitalEventRequest,
  * from `@almadar/ui`'s `providers/ServerBridge.tsx`.
  */
 type AccessTokenProvider = () => Promise<string | undefined>;
+/** The host freed this client's session after its live stream dropped: mount again with the frames the client holds (EXEC-DIST-9). */
+declare class SessionEndedError extends Error {
+    constructor(message: string);
+}
+/** The host answered a dispatch with a non-2xx status: a transport or auth failure, never an event response. */
+declare class TransportStatusError extends Error {
+    readonly status: number;
+    readonly bodyText: string;
+    /** The `{ error, code }` body when the answer carried one. */
+    readonly refusal: RefusalBody | undefined;
+    constructor(status: number, bodyText: string);
+}
+interface RefusalBody {
+    code?: string;
+    error?: string;
+}
 interface HttpTransportOptions {
     serverUrl: string;
     getAccessToken?: AccessTokenProvider;
@@ -108,7 +124,7 @@ declare function encodeJsonBody(value: object, compress: boolean): Promise<{
 /** HTTP transport — POSTs to a server speaking the canonical playground-runtime contract. */
 declare function createHttpTransport(options: HttpTransportOptions): EventTransport;
 /** Evaluates one event against an orbital with no wire in between — the unified `evaluateOrbitalEvent` (a separate, in-progress unit) is a valid `OrbitalEvaluator`. */
-type OrbitalEvaluator = (orbitalName: string, request: OrbitalEventRequest) => Promise<OrbitalEventResponse>;
+type OrbitalEvaluator = (orbitalName: string, request: EventRequest) => Promise<EventResponse>;
 interface InProcessTransportOptions {
     onRegister?: (schema: OrbitalSchema) => Promise<void> | void;
     onUnregister?: () => Promise<void> | void;
@@ -127,5 +143,5 @@ interface InProcessTransportOptions {
 /** In-process transport — the evaluator is INJECTED (e.g. the unified `evaluateOrbitalEvent`, owned elsewhere). */
 declare function createInProcessTransport(evaluate: OrbitalEvaluator, options?: InProcessTransportOptions): EventTransport;
 
-export { COMPRESSED_BODY_MIN_BYTES, createHttpTransport, createInProcessTransport, deriveCarriesCircuitState, encodeJsonBody };
+export { COMPRESSED_BODY_MIN_BYTES, SessionEndedError, TransportStatusError, createHttpTransport, createInProcessTransport, deriveCarriesCircuitState, encodeJsonBody };
 export type { AccessTokenProvider, EventTransport, EventTransportRegisterResult, HostDispatchListener, HttpTransportOptions, InProcessTransportOptions, OrbitalEvaluator, PushTarget };

package/dist/client/EventTransport.js

@@ -1,2 +1 @@
-export { COMPRESSED_BODY_MIN_BYTES, createHttpTransport, createInProcessTransport, deriveCarriesCircuitState, encodeJsonBody } from '../chunk-QELZ6TEJ.js';
-import '../chunk-MLKGABMK.js';
+export { COMPRESSED_BODY_MIN_BYTES, SessionEndedError, TransportStatusError, createHttpTransport, createInProcessTransport, deriveCarriesCircuitState, encodeJsonBody } from '../chunk-UD2CXYSJ.js';

package/dist/client/awaiting.js

@@ -1,2 +1 @@
 export { AwaitingRegistry } from '../chunk-HC6ERSAH.js';
-import '../chunk-MLKGABMK.js';

package/dist/client/channel-transport.d.ts

@@ -1,4 +1,4 @@
-import { OrbitalEventRequest, OrbitalEventResponse, EmittedEvent } from '@almadar/core';
+import { EventRequest, EventResponse, EmittedEvent } from '@almadar/core';
 import { PushTarget, EventTransport } from './EventTransport.js';
 
 /**
@@ -20,11 +20,11 @@ type ChannelMessage = {
     almadarChannel: 'send';
     id: number;
     orbitalName: string;
-    request: OrbitalEventRequest;
+    request: EventRequest;
 } | {
     almadarChannel: 'reply';
     id: number;
-    response: OrbitalEventResponse;
+    response: EventResponse;
 } | {
     almadarChannel: 'push';
     emitted: EmittedEvent;
@@ -32,8 +32,8 @@ type ChannelMessage = {
 } | {
     almadarChannel: 'dispatched';
     orbitalName: string;
-    request: OrbitalEventRequest;
-    response: OrbitalEventResponse;
+    request: EventRequest;
+    response: EventResponse;
 };
 interface TransportChannel {
     post(message: ChannelMessage): void;
@@ -51,7 +51,7 @@ interface ServedChannel {
     /** Push a host-side event to the view (e.g. one a declared input caused while no view was asking). */
     push(emitted: EmittedEvent, target: PushTarget): void;
     /** Send the view the result of a dispatch the host ran on its own. */
-    pushDispatch(orbitalName: string, request: OrbitalEventRequest, response: OrbitalEventResponse): void;
+    pushDispatch(orbitalName: string, request: EventRequest, response: EventResponse): void;
     stop(): void;
 }
 /** The host half: serve `transport` on `channel` for the program named `schemaName`. */

package/dist/client/channel-transport.js

@@ -1,2 +1 @@
 export { createChannelTransport, holdUntilServed, serveChannel } from '../chunk-SKLMWHQD.js';
-import '../chunk-MLKGABMK.js';

package/dist/client/circuit-store.d.ts

@@ -1,8 +1,8 @@
 import { AwaitingRegistry } from './awaiting.js';
 import { StateBook } from './state-book.js';
-import { EntityRow, EventPayload, TraitDefinition } from '@almadar/core';
+import { EntityRow, TraitDefinition } from '@almadar/core';
+import { FrameDelta } from '@almadar/core/kernel-wire';
 import { RollbackCause, TransitionObserver } from './trait-types.js';
-import '@almadar/core/kernel-wire';
 
 /**
  * CircuitStore — P2, `docs/Almadar_Runtime_Stateless_Stateful_PLAN.md` §4.2.
@@ -28,14 +28,25 @@ interface TraitSnapshot {
     state: string;
     frame: EntityRow | undefined;
 }
+/**
+ * What a frame delta did to the store: `applied`; `stale` (its version is behind the one painted: dropped, so an
+ * old repaint never overwrites a newer value); `gap` (it starts past the painted version: nothing applied, the
+ * caller asks the kernel for `framesSince(frameVersion)` and applies the snapshot).
+ */
+type FrameOutcome = 'applied' | 'stale' | 'gap';
 interface CircuitStore {
     /** Each trait's state as the kernel last reported it. */
     readonly states: StateBook;
     /** The entity-frame map (`(set @entity.X)` writes), keyed by
      *  `IndexedTrait.frameKey`. */
     readonly frames: Map<string, EntityRow>;
-    /** Embedded child → the payload its composer last composed it with (sticky `@callsitePayload`). */
-    readonly callsitePayloads: Map<string, EventPayload>;
+    /** The version of the kernel's frame record this store has painted. */
+    readonly frameVersion: number;
+    /**
+     * Paint the kernel's frame delta (EXEC-DIST-7): ops land only at the version they start from, and a snapshot
+     * (`from` 0 with a leading `clear`) always lands. The store merges nothing by its own rules.
+     */
+    applyFrames(delta: FrameDelta): FrameOutcome;
     /** Traits awaiting a server round trip (per-trait subscriptions; see `AwaitingRegistry`). */
     readonly awaiting: AwaitingRegistry;
     /**
@@ -73,4 +84,4 @@ interface CircuitStore {
 declare function createMemoryCircuitStore(traits?: readonly TraitDefinition[], observer?: TransitionObserver): CircuitStore;
 
 export { createMemoryCircuitStore };
-export type { CircuitStore, TraitSnapshot };
+export type { CircuitStore, FrameOutcome, TraitSnapshot };

package/dist/client/circuit-store.js

@@ -1,4 +1,3 @@
-export { createMemoryCircuitStore } from '../chunk-ODJCZ27I.js';
-import '../chunk-Q2H75UYT.js';
+export { createMemoryCircuitStore } from '../chunk-N7HYNKK6.js';
+import '../chunk-A2JJT4GA.js';
 import '../chunk-HC6ERSAH.js';
-import '../chunk-MLKGABMK.js';