@rayfold/server 0.1.0

package/context.js

@@ -0,0 +1,109 @@
+/** In-process event bus used for `emits` and for streams that subscribe to events. */
+export class EventBus {
+    subs = new Map();
+    seq = 0;
+    publish(name, payload) {
+        this.seq++;
+        const enriched = { ...payload, seq: this.seq };
+        for (const fn of this.subs.get(name) ?? [])
+            fn(enriched);
+        for (const fn of this.subs.get("*") ?? [])
+            fn({ event: name, ...enriched });
+    }
+    on(name, fn) {
+        let set = this.subs.get(name);
+        if (!set)
+            this.subs.set(name, (set = new Set()));
+        set.add(fn);
+        return () => set.delete(fn);
+    }
+    /** Async iterator over an event; ends when `signal` aborts. Buffers between pulls. */
+    subscribe(name, signal) {
+        const bus = this;
+        return {
+            [Symbol.asyncIterator]() {
+                const queue = [];
+                let waiting = null;
+                let done = false;
+                const off = bus.on(name, (p) => {
+                    if (done)
+                        return;
+                    if (waiting) {
+                        const w = waiting;
+                        waiting = null;
+                        w({ value: p, done: false });
+                    }
+                    else
+                        queue.push(p);
+                });
+                const finish = () => {
+                    if (done)
+                        return;
+                    done = true;
+                    off();
+                    if (waiting) {
+                        const w = waiting;
+                        waiting = null;
+                        w({ value: undefined, done: true });
+                    }
+                };
+                signal?.addEventListener("abort", finish, { once: true });
+                if (signal?.aborted)
+                    finish();
+                return {
+                    next() {
+                        if (queue.length)
+                            return Promise.resolve({ value: queue.shift(), done: false });
+                        if (done)
+                            return Promise.resolve({ value: undefined, done: true });
+                        return new Promise((res) => (waiting = res));
+                    },
+                    return() {
+                        finish();
+                        return Promise.resolve({ value: undefined, done: true });
+                    },
+                };
+            },
+        };
+    }
+}
+/**
+ * In-memory idempotency records. Records expire after `ttlMs`; expired ones are dropped on read and swept on every
+ * write, and past `maxEntries` the oldest go first, so memory stays bounded however many commands arrive.
+ */
+export class MemoryIdempotencyStore {
+    ttlMs;
+    now;
+    maxEntries;
+    map = new Map();
+    constructor(ttlMs = 24 * 3_600_000, now = Date.now, maxEntries = 100_000) {
+        this.ttlMs = ttlMs;
+        this.now = now;
+        this.maxEntries = maxEntries;
+    }
+    async get(scope, key) {
+        const k = `${scope}\u0000${key}`;
+        const r = this.map.get(k);
+        if (r && this.now() - r.at > this.ttlMs) {
+            this.map.delete(k);
+            return undefined;
+        }
+        return r;
+    }
+    async put(scope, key, record) {
+        const k = `${scope}\u0000${key}`;
+        this.map.delete(k); // re-inserted at the end, so the map stays ordered oldest first
+        this.map.set(k, record);
+        const t = this.now();
+        for (const [old, r] of this.map) {
+            if (this.map.size > this.maxEntries || t - r.at > this.ttlMs)
+                this.map.delete(old);
+            else
+                break;
+        }
+    }
+    get size() {
+        return this.map.size;
+    }
+}
+//# sourceMappingURL=context.js.map

package/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Expr, Shape } from \"@rayfold/schema\";\nimport type { RequestMeta } from \"./protocol.ts\";\n\n/** In-process event bus used for `emits` and for streams that subscribe to events. */\nexport class EventBus {\n  private readonly subs = new Map<string, Set<(payload: unknown) => void>>();\n  private seq = 0;\n\n  publish(name: string, payload: Record<string, unknown>): void {\n    this.seq++;\n    const enriched = { ...payload, seq: this.seq };\n    for (const fn of this.subs.get(name) ?? []) fn(enriched);\n    for (const fn of this.subs.get(\"*\") ?? []) fn({ event: name, ...enriched });\n  }\n\n  on(name: string, fn: (payload: unknown) => void): () => void {\n    let set = this.subs.get(name);\n    if (!set) this.subs.set(name, (set = new Set()));\n    set.add(fn);\n    return () => set!.delete(fn);\n  }\n\n  /** Async iterator over an event; ends when `signal` aborts. Buffers between pulls. */\n  subscribe<T = unknown>(name: string, signal?: AbortSignal): AsyncIterable<T> {\n    const bus = this;\n    return {\n      [Symbol.asyncIterator]() {\n        const queue: T[] = [];\n        let waiting: ((r: IteratorResult<T>) => void) | null = null;\n        let done = false;\n        const off = bus.on(name, (p) => {\n          if (done) return;\n          if (waiting) {\n            const w = waiting;\n            waiting = null;\n            w({ value: p as T, done: false });\n          } else queue.push(p as T);\n        });\n        const finish = () => {\n          if (done) return;\n          done = true;\n          off();\n          if (waiting) {\n            const w = waiting;\n            waiting = null;\n            w({ value: undefined as never, done: true });\n          }\n        };\n        signal?.addEventListener(\"abort\", finish, { once: true });\n        if (signal?.aborted) finish();\n        return {\n          next(): Promise<IteratorResult<T>> {\n            if (queue.length) return Promise.resolve({ value: queue.shift()!, done: false });\n            if (done) return Promise.resolve({ value: undefined as never, done: true });\n            return new Promise((res) => (waiting = res));\n          },\n          return(): Promise<IteratorResult<T>> {\n            finish();\n            return Promise.resolve({ value: undefined as never, done: true });\n          },\n        };\n      },\n    };\n  }\n}\n\nexport interface PolicyHint {\n  /** Pushable read policy for the type being loaded, if any (spec 06 §4). */\n  filter?: Expr;\n}\n\n/** What every resolver receives. `V` is the server's viewer type. */\nexport interface RayfoldContext<V = unknown> {\n  viewer: V;\n  signal: AbortSignal;\n  simulate: boolean;\n  /** Compact wire mode requested by the client (spec 04 section 1). */\n  compact?: boolean;\n  /** Expected version for a conditional command (spec 03 section 4a). */\n  ifVersion?: string | number;\n  /**\n   * Conditional-write check: throws VersionConflict when the request carried `ifVersion` and it differs\n   * from `actual`. `current` is the entity as stored; it is returned to the client in the op's shape.\n   */\n  checkVersion(key: string, actual: unknown, current: unknown): void;\n  events: EventBus;\n  meta: RequestMeta;\n  opId: number;\n  opName: string;\n  policy: PolicyHint;\n  /** The shape this op asked for, so an adapter can plan a whole screen at once (spec 02). */\n  shape?: Shape;\n  /** Values for `$name` references in the op's shape. */\n  vars?: Record<string, unknown>;\n  /** Per-request scratch space (e.g. per-request loader caches). */\n  state: Map<string, unknown>;\n  /**\n   * Scratch space shared by every op of the batch. The executor keeps loaded field values here, so an entity one op\n   * already loaded is not loaded again by another op of the same request (spec 03 section 2).\n   */\n  batch: Map<string, unknown>;\n  /** Wall clock, injectable for tests. */\n  now: () => number;\n}\n\nexport interface IdempotencyRecord {\n  argsHash: string;\n  /** the full ok frame */\n  frame: unknown;\n  /** the same result in compact form, for retries that ask for compact frames */\n  compactFrame?: unknown;\n  at: number;\n}\n\nexport interface IdempotencyStore {\n  get(scope: string, key: string): Promise<IdempotencyRecord | undefined>;\n  put(scope: string, key: string, record: IdempotencyRecord): Promise<void>;\n}\n\n/**\n * In-memory idempotency records. Records expire after `ttlMs`; expired ones are dropped on read and swept on every\n * write, and past `maxEntries` the oldest go first, so memory stays bounded however many commands arrive.\n */\nexport class MemoryIdempotencyStore implements IdempotencyStore {\n  private readonly map = new Map<string, IdempotencyRecord>();\n  constructor(\n    private readonly ttlMs = 24 * 3_600_000,\n    private readonly now: () => number = Date.now,\n    private readonly maxEntries = 100_000,\n  ) {}\n  async get(scope: string, key: string): Promise<IdempotencyRecord | undefined> {\n    const k = `${scope}\\u0000${key}`;\n    const r = this.map.get(k);\n    if (r && this.now() - r.at > this.ttlMs) {\n      this.map.delete(k);\n      return undefined;\n    }\n    return r;\n  }\n  async put(scope: string, key: string, record: IdempotencyRecord): Promise<void> {\n    const k = `${scope}\\u0000${key}`;\n    this.map.delete(k); // re-inserted at the end, so the map stays ordered oldest first\n    this.map.set(k, record);\n    const t = this.now();\n    for (const [old, r] of this.map) {\n      if (this.map.size > this.maxEntries || t - r.at > this.ttlMs) this.map.delete(old);\n      else break;\n    }\n  }\n  get size(): number {\n    return this.map.size;\n  }\n}\n"]}

package/core.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The runtime without a transport: schema, batches, policies, cost, live queries. Nothing here needs Node, so it runs
+ * in a browser, a worker or any JavaScript runtime; the HTTP, WebSocket and MCP transports are in the main entry.
+ */
+export * from "./protocol.js";
+export { EventBus, MemoryIdempotencyStore, type IdempotencyStore, type IdempotencyRecord, type RayfoldContext, type PolicyHint } from "./context.js";
+export { Executor, ok, derivePatches, stripTypes, type Resolvers, type FieldResolver, type SingleFieldResolver, type RootResolver, type StreamResolver, type CommandResult } from "./executor.js";
+export { executeBatch, FrameSink, type BatchOptions, type BatchRuntime, type ExecuteOptions } from "./batch.js";
+export { RayfoldServer, createRayfoldServer, type RayfoldServerOptions } from "./server.js";
+export { MemoryShapeRegistry, defaultShape, resolveRequestShape, type ShapeRegistry } from "./views.js";
+export { coerceArgs, coerceValue, coerceScalar, resolveRefs, collectRefs, getPath } from "./args.js";
+export { estimateCost, type CostEstimate } from "./cost.js";
+export { decide, decisionError, pushableFilter, hasPolicy, type Decision } from "./policy.js";
+export { checkWiring } from "./wiring.js";
+export { ChangeBus, changeFromPatch, diffResults, normalizeResult, readSetOf, type Change } from "./live.js";
+export type { Instrumentation, BatchInfo, OpInfo, LoaderInfo, Outcome } from "./instrumentation.js";
+export { MemoryUsage, type UsageSink, type UsageEvent, type UsageEntry } from "./usage.js";
+export { capabilityAllows } from "./capability-scope.js";

package/core.js

@@ -0,0 +1,18 @@
+/**
+ * The runtime without a transport: schema, batches, policies, cost, live queries. Nothing here needs Node, so it runs
+ * in a browser, a worker or any JavaScript runtime; the HTTP, WebSocket and MCP transports are in the main entry.
+ */
+export * from "./protocol.js";
+export { EventBus, MemoryIdempotencyStore } from "./context.js";
+export { Executor, ok, derivePatches, stripTypes } from "./executor.js";
+export { executeBatch, FrameSink } from "./batch.js";
+export { RayfoldServer, createRayfoldServer } from "./server.js";
+export { MemoryShapeRegistry, defaultShape, resolveRequestShape } from "./views.js";
+export { coerceArgs, coerceValue, coerceScalar, resolveRefs, collectRefs, getPath } from "./args.js";
+export { estimateCost } from "./cost.js";
+export { decide, decisionError, pushableFilter, hasPolicy } from "./policy.js";
+export { checkWiring } from "./wiring.js";
+export { ChangeBus, changeFromPatch, diffResults, normalizeResult, readSetOf } from "./live.js";
+export { MemoryUsage } from "./usage.js";
+export { capabilityAllows } from "./capability-scope.js";
+//# sourceMappingURL=core.js.map

package/core.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.js","sourceRoot":"","sources":["../src/core.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,cAAc,eAAe,CAAC;AAC9B,OAAO,EAAE,QAAQ,EAAE,sBAAsB,EAAuF,MAAM,cAAc,CAAC;AACrJ,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,aAAa,EAAE,UAAU,EAA4H,MAAM,eAAe,CAAC;AAClM,OAAO,EAAE,YAAY,EAAE,SAAS,EAA6D,MAAM,YAAY,CAAC;AAChH,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAA6B,MAAM,aAAa,CAAC;AAC5F,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,mBAAmB,EAAsB,MAAM,YAAY,CAAC;AACxG,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACrG,OAAO,EAAE,YAAY,EAAqB,MAAM,WAAW,CAAC;AAC5D,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,cAAc,EAAE,SAAS,EAAiB,MAAM,aAAa,CAAC;AAC9F,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,WAAW,EAAE,eAAe,EAAE,SAAS,EAAe,MAAM,WAAW,CAAC;AAE7G,OAAO,EAAE,WAAW,EAAoD,MAAM,YAAY,CAAC;AAC3F,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC","sourcesContent":["/**\n * The runtime without a transport: schema, batches, policies, cost, live queries. Nothing here needs Node, so it runs\n * in a browser, a worker or any JavaScript runtime; the HTTP, WebSocket and MCP transports are in the main entry.\n */\nexport * from \"./protocol.ts\";\nexport { EventBus, MemoryIdempotencyStore, type IdempotencyStore, type IdempotencyRecord, type RayfoldContext, type PolicyHint } from \"./context.ts\";\nexport { Executor, ok, derivePatches, stripTypes, type Resolvers, type FieldResolver, type SingleFieldResolver, type RootResolver, type StreamResolver, type CommandResult } from \"./executor.ts\";\nexport { executeBatch, FrameSink, type BatchOptions, type BatchRuntime, type ExecuteOptions } from \"./batch.ts\";\nexport { RayfoldServer, createRayfoldServer, type RayfoldServerOptions } from \"./server.ts\";\nexport { MemoryShapeRegistry, defaultShape, resolveRequestShape, type ShapeRegistry } from \"./views.ts\";\nexport { coerceArgs, coerceValue, coerceScalar, resolveRefs, collectRefs, getPath } from \"./args.ts\";\nexport { estimateCost, type CostEstimate } from \"./cost.ts\";\nexport { decide, decisionError, pushableFilter, hasPolicy, type Decision } from \"./policy.ts\";\nexport { checkWiring } from \"./wiring.ts\";\nexport { ChangeBus, changeFromPatch, diffResults, normalizeResult, readSetOf, type Change } from \"./live.ts\";\nexport type { Instrumentation, BatchInfo, OpInfo, LoaderInfo, Outcome } from \"./instrumentation.ts\";\nexport { MemoryUsage, type UsageSink, type UsageEvent, type UsageEntry } from \"./usage.ts\";\nexport { capabilityAllows } from \"./capability-scope.ts\";\n"]}

package/cost.d.ts

@@ -0,0 +1,15 @@
+/** Static cost, depth and field-count estimation. Spec: spec/06 §5, spec/02 §5. */
+import { type OpDef, type RayfoldSchemaIR, type Shape } from "@rayfold/schema";
+export interface CostEstimate {
+    cost: number;
+    depth: number;
+    fields: number;
+}
+/**
+ * cost = op.base + op.perItem × first + Σ over selected fields of (field.base + field.perItem × childFirst) × mult
+ * where mult is the product of page sizes enclosing the field (fields inside `items` of a Page<T> count `first` times).
+ * A field's base defaults to 1 when it returns objects (an entity, an object, a page, a list of them) and to 0 when
+ * it returns scalars or enums: those come with the row that is already loaded. The perItem of a page, op or field,
+ * defaults to 1, so every row a page can return is charged. `@cost` overrides each default.
+ */
+export declare function estimateCost(ir: RayfoldSchemaIR, op: OpDef, args: Record<string, unknown>, shape: Shape, vars?: Record<string, unknown>): CostEstimate;

package/cost.js

@@ -0,0 +1,110 @@
+/** Static cost, depth and field-count estimation. Spec: spec/06 §5, spec/02 §5. */
+import { annotation, fieldsOf, isPageRef } from "@rayfold/schema";
+import { defaultShape, isScalarLike } from "./views.js";
+const DEFAULT_FIRST = 20;
+/** Largest page the runtime serves; any page size the cost model cannot trust counts as this. */
+const MAX_FIRST = 200;
+/**
+ * cost = op.base + op.perItem × first + Σ over selected fields of (field.base + field.perItem × childFirst) × mult
+ * where mult is the product of page sizes enclosing the field (fields inside `items` of a Page<T> count `first` times).
+ * A field's base defaults to 1 when it returns objects (an entity, an object, a page, a list of them) and to 0 when
+ * it returns scalars or enums: those come with the row that is already loaded. The perItem of a page, op or field,
+ * defaults to 1, so every row a page can return is charged. `@cost` overrides each default.
+ */
+export function estimateCost(ir, op, args, shape, vars = {}) {
+    const c = annotation(op, "cost");
+    const base = num(c?.args["base"]) ?? 1;
+    const perItem = num(c?.args["perItem"]) ?? (isPageRef(op.returns) ? 1 : 0);
+    const first = isPageRef(op.returns) ? pageFirst(args, op.args) : 1;
+    const acc = { fields: 0, depth: 0 };
+    const shapeCost = walk(ir, op.returns, shape, 1, first, 1, acc, vars);
+    return { cost: Math.max(1, base + perItem * first + shapeCost), depth: acc.depth, fields: acc.fields };
+}
+/** Fields without a sub-shape that resolve to objects get that type's default view, exactly as the executor does. */
+function walk(ir, t, shape, mult, itemsFirst, depth, acc, vars) {
+    acc.depth = Math.max(acc.depth, depth);
+    const isPage = isPageRef(t) || (t.kind === "list" && isPageRef(t.of));
+    let total = 0;
+    const visit = (items, ref) => {
+        const fields = fieldsOf(ir, ref) ?? [];
+        for (const it of items) {
+            switch (it.kind) {
+                case "field": {
+                    acc.fields++;
+                    const f = fields.find((x) => x.name === it.name);
+                    const fc = f ? annotation(f, "cost") : undefined;
+                    const childFirst = f && isPageRef(f.type) ? pageFirst(substituteVars(it.args ?? {}, vars), f.args) : 1;
+                    const defaultBase = f && isScalarLike(ir, f.type) ? 0 : 1;
+                    const defaultPerItem = f && isPageRef(f.type) ? 1 : 0;
+                    total += mult * ((num(fc?.args["base"]) ?? defaultBase) + (num(fc?.args["perItem"]) ?? defaultPerItem) * childFirst);
+                    if (f && !isScalarLike(ir, f.type)) {
+                        const sub = it.shape ?? defaultShape(ir, f.type);
+                        const childMult = isPage && it.name === "items" ? mult * itemsFirst : mult;
+                        total += walk(ir, f.type, sub, childMult, childFirst, depth + 1, acc, vars);
+                    }
+                    break;
+                }
+                case "spread": {
+                    const v = ir.views[`${it.type}.${it.view}`];
+                    if (v)
+                        visit(v.shape.items, ref);
+                    break;
+                }
+                case "on":
+                    visit(it.shape.items, { kind: "named", name: it.type, nullable: false });
+                    break;
+                case "defer":
+                    visit(it.shape.items, ref);
+                    break;
+            }
+        }
+    };
+    visit(shape.items, t);
+    return total;
+}
+/**
+ * Page size for costing. The estimate runs on the request as sent, before coercion, so anything that is not a whole
+ * number from 0 to MAX_FIRST (negative, fractional, huge, a $ref, a missing variable) counts as MAX_FIRST:
+ * bad input can raise the estimate but never lower it.
+ */
+function pageFirst(args, defs) {
+    const page = args["page"];
+    if (page !== undefined) {
+        if (!page || typeof page !== "object" || Array.isArray(page))
+            return MAX_FIRST;
+        if ("first" in page)
+            return pageSize(page["first"]);
+    }
+    if ("first" in args)
+        return pageSize(args["first"]);
+    const def = defs.find((a) => a.name === "page")?.default;
+    if (def && typeof def === "object" && !Array.isArray(def) && "first" in def)
+        return pageSize(def["first"]);
+    const firstDef = defs.find((a) => a.name === "first")?.default;
+    if (firstDef !== undefined)
+        return pageSize(firstDef);
+    return DEFAULT_FIRST;
+}
+function pageSize(v) {
+    return typeof v === "number" && Number.isInteger(v) && v >= 0 ? Math.min(v, MAX_FIRST) : MAX_FIRST;
+}
+function num(v) {
+    return typeof v === "number" ? v : undefined;
+}
+function substituteVars(v, vars) {
+    const walkV = (x) => {
+        if (x === null || typeof x !== "object")
+            return x;
+        if (Array.isArray(x))
+            return x.map(walkV);
+        const o = x;
+        if (typeof o["$var"] === "string")
+            return vars[o["$var"]];
+        const out = {};
+        for (const [k, y] of Object.entries(o))
+            out[k] = walkV(y);
+        return out;
+    };
+    return walkV(v);
+}
+//# sourceMappingURL=cost.js.map

package/cost.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost.js","sourceRoot":"","sources":["../src/cost.ts"],"names":[],"mappings":"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","sourcesContent":["/** Static cost, depth and field-count estimation. Spec: spec/06 §5, spec/02 §5. */\nimport { annotation, fieldsOf, isPageRef, type ArgDef, type OpDef, type RayfoldSchemaIR, type Shape, type ShapeItem, type TypeRef } from \"@rayfold/schema\";\nimport { defaultShape, isScalarLike } from \"./views.ts\";\n\nexport interface CostEstimate {\n  cost: number;\n  depth: number;\n  fields: number;\n}\n\nconst DEFAULT_FIRST = 20;\n/** Largest page the runtime serves; any page size the cost model cannot trust counts as this. */\nconst MAX_FIRST = 200;\n\n/**\n * cost = op.base + op.perItem × first + Σ over selected fields of (field.base + field.perItem × childFirst) × mult\n * where mult is the product of page sizes enclosing the field (fields inside `items` of a Page<T> count `first` times).\n * A field's base defaults to 1 when it returns objects (an entity, an object, a page, a list of them) and to 0 when\n * it returns scalars or enums: those come with the row that is already loaded. The perItem of a page, op or field,\n * defaults to 1, so every row a page can return is charged. `@cost` overrides each default.\n */\nexport function estimateCost(ir: RayfoldSchemaIR, op: OpDef, args: Record<string, unknown>, shape: Shape, vars: Record<string, unknown> = {}): CostEstimate {\n  const c = annotation(op, \"cost\");\n  const base = num(c?.args[\"base\"]) ?? 1;\n  const perItem = num(c?.args[\"perItem\"]) ?? (isPageRef(op.returns) ? 1 : 0);\n  const first = isPageRef(op.returns) ? pageFirst(args, op.args) : 1;\n  const acc = { fields: 0, depth: 0 };\n  const shapeCost = walk(ir, op.returns, shape, 1, first, 1, acc, vars);\n  return { cost: Math.max(1, base + perItem * first + shapeCost), depth: acc.depth, fields: acc.fields };\n}\n\n/** Fields without a sub-shape that resolve to objects get that type's default view, exactly as the executor does. */\nfunction walk(ir: RayfoldSchemaIR, t: TypeRef, shape: Shape, mult: number, itemsFirst: number, depth: number, acc: { fields: number; depth: number }, vars: Record<string, unknown>): number {\n  acc.depth = Math.max(acc.depth, depth);\n  const isPage = isPageRef(t) || (t.kind === \"list\" && isPageRef(t.of));\n  let total = 0;\n  const visit = (items: ShapeItem[], ref: TypeRef): void => {\n    const fields = fieldsOf(ir, ref) ?? [];\n    for (const it of items) {\n      switch (it.kind) {\n        case \"field\": {\n          acc.fields++;\n          const f = fields.find((x) => x.name === it.name);\n          const fc = f ? annotation(f, \"cost\") : undefined;\n          const childFirst = f && isPageRef(f.type) ? pageFirst(substituteVars(it.args ?? {}, vars), f.args) : 1;\n          const defaultBase = f && isScalarLike(ir, f.type) ? 0 : 1;\n          const defaultPerItem = f && isPageRef(f.type) ? 1 : 0;\n          total += mult * ((num(fc?.args[\"base\"]) ?? defaultBase) + (num(fc?.args[\"perItem\"]) ?? defaultPerItem) * childFirst);\n          if (f && !isScalarLike(ir, f.type)) {\n            const sub = it.shape ?? defaultShape(ir, f.type);\n            const childMult = isPage && it.name === \"items\" ? mult * itemsFirst : mult;\n            total += walk(ir, f.type, sub, childMult, childFirst, depth + 1, acc, vars);\n          }\n          break;\n        }\n        case \"spread\": {\n          const v = ir.views[`${it.type}.${it.view}`];\n          if (v) visit(v.shape.items, ref);\n          break;\n        }\n        case \"on\":\n          visit(it.shape.items, { kind: \"named\", name: it.type, nullable: false });\n          break;\n        case \"defer\":\n          visit(it.shape.items, ref);\n          break;\n      }\n    }\n  };\n  visit(shape.items, t);\n  return total;\n}\n\n/**\n * Page size for costing. The estimate runs on the request as sent, before coercion, so anything that is not a whole\n * number from 0 to MAX_FIRST (negative, fractional, huge, a $ref, a missing variable) counts as MAX_FIRST:\n * bad input can raise the estimate but never lower it.\n */\nfunction pageFirst(args: Record<string, unknown>, defs: ArgDef[]): number {\n  const page = args[\"page\"];\n  if (page !== undefined) {\n    if (!page || typeof page !== \"object\" || Array.isArray(page)) return MAX_FIRST;\n    if (\"first\" in page) return pageSize((page as Record<string, unknown>)[\"first\"]);\n  }\n  if (\"first\" in args) return pageSize(args[\"first\"]);\n  const def = defs.find((a) => a.name === \"page\")?.default;\n  if (def && typeof def === \"object\" && !Array.isArray(def) && \"first\" in def) return pageSize((def as Record<string, unknown>)[\"first\"]);\n  const firstDef = defs.find((a) => a.name === \"first\")?.default;\n  if (firstDef !== undefined) return pageSize(firstDef);\n  return DEFAULT_FIRST;\n}\n\nfunction pageSize(v: unknown): number {\n  return typeof v === \"number\" && Number.isInteger(v) && v >= 0 ? Math.min(v, MAX_FIRST) : MAX_FIRST;\n}\n\nfunction num(v: unknown): number | undefined {\n  return typeof v === \"number\" ? v : undefined;\n}\n\nfunction substituteVars(v: unknown, vars: Record<string, unknown>): Record<string, unknown> {\n  const walkV = (x: unknown): unknown => {\n    if (x === null || typeof x !== \"object\") return x;\n    if (Array.isArray(x)) return x.map(walkV);\n    const o = x as Record<string, unknown>;\n    if (typeof o[\"$var\"] === \"string\") return vars[o[\"$var\"]];\n    const out: Record<string, unknown> = {};\n    for (const [k, y] of Object.entries(o)) out[k] = walkV(y);\n    return out;\n  };\n  return walkV(v) as Record<string, unknown>;\n}\n"]}

package/executor.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Operation execution and shape projection.
+ * Level-wise batching: every field of every object at one nesting level is resolved with one loader
+ * call, across lists and pages, so N+1 cannot occur (spec 01 §4 @load, spec 02).
+ */
+import type { Instrumentation } from "./instrumentation.js";
+import { type Annotation, type OpDef, type RayfoldSchemaIR, type Shape } from "@rayfold/schema";
+import type { RayfoldContext } from "./context.js";
+import { type Frame, type PatchOp } from "./protocol.js";
+import type { UsageSink } from "./usage.js";
+export type FieldResolver<P = unknown, A = Record<string, unknown>, R = unknown> = (parents: P[], args: A, ctx: RayfoldContext<never>) => R[] | Promise<R[]>;
+export type SingleFieldResolver<P = unknown, A = Record<string, unknown>, R = unknown> = (parent: P, args: A, ctx: RayfoldContext<never>) => R | Promise<R>;
+export type RootResolver<A = Record<string, unknown>, R = unknown> = (args: A, ctx: RayfoldContext<never>) => R | Promise<R>;
+export type StreamResolver<A = Record<string, unknown>, R = unknown> = (args: A, ctx: RayfoldContext<never>) => AsyncIterable<R>;
+export interface Resolvers {
+    Query?: Record<string, RootResolver<never, unknown>>;
+    Command?: Record<string, RootResolver<never, unknown>>;
+    Stream?: Record<string, StreamResolver<never, unknown>>;
+    /** Entity/object field loaders, batch by default: (parents[], args, ctx) => results[] */
+    [typeName: string]: Record<string, FieldResolver<never, never, unknown> | SingleFieldResolver<never, never, unknown> | RootResolver<never, unknown> | StreamResolver<never, unknown>> | undefined;
+}
+declare const COMMAND_RESULT: unique symbol;
+export interface CommandResult<R = unknown> {
+    [COMMAND_RESULT]: true;
+    result: R;
+    patch?: PatchOp[];
+    emit?: Array<{
+        event: string;
+        payload: Record<string, unknown>;
+    }>;
+}
+/** Wrap a command's return value to attach extra patches or events. */
+export declare function ok<R>(result: R, extra?: {
+    patch?: PatchOp[];
+    emit?: Array<{
+        event: string;
+        payload: Record<string, unknown>;
+    }>;
+}): CommandResult<R>;
+export interface ExecutorOptions {
+    maxDepth: number;
+    maxFields: number;
+    instrumentation?: Instrumentation;
+    /** Records which members each client asked for (spec 11). Nothing is recorded without one. */
+    usage?: UsageSink;
+}
+type Emit = (frame: Frame) => void;
+/** Compact mode: drop `$type` except on union members; keep everything else identical. */
+/** Compact form of a query frame (`data` or `at`): `$type` stripped where the schema fixes it, `meta` dropped. */
+export declare function compactQueryFrame(f: Frame): Frame;
+export declare function stripTypes(v: unknown): unknown;
+export declare class Executor {
+    private readonly ir;
+    private readonly resolvers;
+    private readonly opts;
+    constructor(ir: RayfoldSchemaIR, resolvers: Resolvers, opts: ExecutorOptions);
+    runQuery(op: OpDef, args: Record<string, unknown>, shape: Shape, explicit: boolean, cost: number, ctx: RayfoldContext, emit: Emit): Promise<unknown>;
+    runCommand(op: OpDef, args: Record<string, unknown>, shape: Shape, explicit: boolean, cost: number, ctx: RayfoldContext, emit: Emit): Promise<{
+        result: unknown;
+        frame: Frame;
+        full: Frame;
+        compact: Frame;
+        patch: PatchOp[];
+    }>;
+    /** VersionConflict -> failed_precondition carrying the current entity in the op's shape. */
+    private conflictWithCurrent;
+    private checkDeclaredError;
+    runStream(op: OpDef, args: Record<string, unknown>, shape: Shape, explicit: boolean, ctx: RayfoldContext, emit: Emit): Promise<void>;
+    /** The command's write policy, checked before an idempotent replay is served. */
+    authorize(op: OpDef, args: Record<string, unknown>, ctx: RayfoldContext): void;
+    private checkOpPolicy;
+    private flushDeferred;
+    /** Project one value (object, list, or null) of static type `t`. */
+    private projectValue;
+    /** Project all `slots` (objects of static type `t`) through `shape`, batching each field once. */
+    private projectMany;
+    /** Resolve field values for all targets with one loader call (or property access). */
+    private loadField;
+    /** The pushable read policy of the entity a resolver loads, handed to it as ctx.policy.filter (spec 06 section 4). */
+    private policyHint;
+    /** Expand spreads/type conditions and group field selections by (name, args). */
+    private flatten;
+}
+/** Every entity object in a projected result becomes a `set` patch (spec 04 §2). */
+export declare function derivePatches(data: unknown): PatchOp[];
+export declare function annotationsOf(x: {
+    annotations: Annotation[];
+}): Annotation[];
+export {};