@rayfold/server 0.1.0

package/protocol.js

@@ -0,0 +1,98 @@
+export const PROTOCOL_CODES = [
+    "canceled",
+    "unknown",
+    "invalid_argument",
+    "deadline_exceeded",
+    "not_found",
+    "already_exists",
+    "permission_denied",
+    "resource_exhausted",
+    "failed_precondition",
+    "aborted",
+    "out_of_range",
+    "unimplemented",
+    "internal",
+    "unavailable",
+    "data_loss",
+    "unauthenticated",
+];
+export const HTTP_STATUS = {
+    invalid_argument: 400,
+    failed_precondition: 400,
+    out_of_range: 400,
+    unauthenticated: 401,
+    permission_denied: 403,
+    not_found: 404,
+    already_exists: 409,
+    aborted: 409,
+    resource_exhausted: 429,
+    canceled: 499,
+    unimplemented: 501,
+    unavailable: 503,
+    deadline_exceeded: 504,
+    domain: 422,
+    unknown: 500,
+    internal: 500,
+    data_loss: 500,
+};
+const RETRYABLE = new Set(["unavailable", "deadline_exceeded", "aborted"]);
+/** Thrown by resolvers / runtime; converted to a WireError at the frame boundary. */
+export class RayfoldError extends Error {
+    code;
+    type;
+    data;
+    path;
+    retryable;
+    constructor(code, message, opts = {}) {
+        super(message);
+        this.name = "RayfoldError";
+        this.code = code;
+        this.type = opts.type;
+        this.data = opts.data;
+        this.path = opts.path;
+        this.retryable = opts.retryable ?? RETRYABLE.has(code);
+    }
+    toWire() {
+        const w = { code: this.code, message: this.message };
+        if (this.type !== undefined)
+            w.type = this.type;
+        if (this.data !== undefined)
+            w.data = this.data;
+        if (this.path !== undefined)
+            w.path = this.path;
+        if (this.retryable !== RETRYABLE.has(this.code))
+            w.retryable = this.retryable;
+        return w;
+    }
+    withPath(path) {
+        return new RayfoldError(this.code, this.message, { type: this.type, data: this.data, path, retryable: this.retryable });
+    }
+    static domain(type, data, message) {
+        return new RayfoldError("domain", message ?? type, { type, data });
+    }
+}
+/**
+ * Raised through `ctx.checkVersion` when a conditional command's `ifVersion` does not match.
+ * The executor projects `current` through the op's shape so the client can repair its cache without a GET.
+ */
+export class VersionConflict extends RayfoldError {
+    key;
+    expected;
+    actual;
+    current;
+    constructor(key, expected, actual, current) {
+        super("failed_precondition", `${key} is at version ${String(actual)}, not ${String(expected)}`, { type: "VersionConflict", data: { key, expected, actual } });
+        this.key = key;
+        this.expected = expected;
+        this.actual = actual;
+        this.current = current;
+    }
+}
+export function toWireError(e) {
+    if (e instanceof RayfoldError)
+        return e.toWire();
+    if (e instanceof Error && e.name === "AbortError")
+        return { code: "canceled", message: "Canceled" };
+    return { code: "internal", message: "Internal error" };
+}
+//# sourceMappingURL=protocol.js.map

package/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"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","sourcesContent":["/** Wire-level request/frame types. Spec: spec/03, spec/04, spec/05. */\nimport type { JsonValue } from \"@rayfold/schema\";\n\nexport interface RequestOp {\n  id: number;\n  op: string;\n  args?: Record<string, unknown>;\n  shape?: string;\n  vars?: Record<string, JsonValue>;\n  key?: string;\n  live?: boolean;\n  deadline?: number;\n  simulate?: boolean;\n  /** Omit `$type` where the schema makes it redundant and omit `meta` unless it carries `replay`. Requires a schema-aware client. */\n  compact?: boolean;\n  /** Conditional write: the version the client last saw of the entity this command targets (spec 03 section 4a). */\n  ifVersion?: string | number;\n}\n\nexport interface RequestMeta {\n  client?: string;\n  deadline?: number;\n  /** W3C trace context (spec 04 section 4); the HTTP transport copies it from the headers of the same names. */\n  traceparent?: string;\n  tracestate?: string;\n}\n\nexport interface RequestEnvelope {\n  rayfold?: string;\n  ops: RequestOp[];\n  meta?: RequestMeta;\n}\n\nexport const PROTOCOL_CODES = [\n  \"canceled\",\n  \"unknown\",\n  \"invalid_argument\",\n  \"deadline_exceeded\",\n  \"not_found\",\n  \"already_exists\",\n  \"permission_denied\",\n  \"resource_exhausted\",\n  \"failed_precondition\",\n  \"aborted\",\n  \"out_of_range\",\n  \"unimplemented\",\n  \"internal\",\n  \"unavailable\",\n  \"data_loss\",\n  \"unauthenticated\",\n] as const;\nexport type ProtocolCode = (typeof PROTOCOL_CODES)[number];\nexport type ErrorCode = ProtocolCode | \"domain\";\n\nexport interface WireError {\n  code: ErrorCode;\n  type?: string;\n  message: string;\n  data?: unknown;\n  path?: string;\n  retryable?: boolean;\n}\n\nexport type PatchOp =\n  | { set: string; value: Record<string, unknown> }\n  | { del: string }\n  | { inv: string[] }\n  | { invOp: string[] }\n  /** Result-scoped (spec 04 section 2b): merge these fields into the plain object at this result path. */\n  | { at: string; value: Record<string, unknown> }\n  /** Result-scoped: remove these old positions, then insert these elements at these new positions. */\n  | { list: string; del?: number[]; ins?: Array<{ at: number; value: unknown }> };\n\nexport interface FrameMeta {\n  cost?: number;\n  cache?: \"hit\" | \"miss\" | \"stale\";\n  ms?: number;\n  replay?: boolean;\n  cursor?: string;\n  [k: string]: unknown;\n}\n\nexport type Frame =\n  | { id: number; data: unknown; meta?: FrameMeta; errors?: WireError[]; fin?: boolean }\n  | { id: number; ok: unknown; patch?: PatchOp[]; meta?: FrameMeta; errors?: WireError[]; fin: true }\n  | { id: number; item: unknown; meta?: FrameMeta }\n  | { id: number; patch: PatchOp[]; meta?: FrameMeta }\n  | { id: number; at: string; data: unknown; errors?: WireError[] }\n  | { id: number; error: WireError; fin: true }\n  | { id: number; fin: true }\n  | { error: WireError; fin: true };\n\nexport const HTTP_STATUS: Record<ErrorCode, number> = {\n  invalid_argument: 400,\n  failed_precondition: 400,\n  out_of_range: 400,\n  unauthenticated: 401,\n  permission_denied: 403,\n  not_found: 404,\n  already_exists: 409,\n  aborted: 409,\n  resource_exhausted: 429,\n  canceled: 499,\n  unimplemented: 501,\n  unavailable: 503,\n  deadline_exceeded: 504,\n  domain: 422,\n  unknown: 500,\n  internal: 500,\n  data_loss: 500,\n};\n\nconst RETRYABLE = new Set<ErrorCode>([\"unavailable\", \"deadline_exceeded\", \"aborted\"]);\n\n/** Thrown by resolvers / runtime; converted to a WireError at the frame boundary. */\nexport class RayfoldError extends Error {\n  readonly code: ErrorCode;\n  readonly type: string | undefined;\n  readonly data: unknown;\n  readonly path: string | undefined;\n  readonly retryable: boolean;\n\n  constructor(code: ErrorCode, message: string, opts: { type?: string | undefined; data?: unknown; path?: string | undefined; retryable?: boolean | undefined } = {}) {\n    super(message);\n    this.name = \"RayfoldError\";\n    this.code = code;\n    this.type = opts.type;\n    this.data = opts.data;\n    this.path = opts.path;\n    this.retryable = opts.retryable ?? RETRYABLE.has(code);\n  }\n\n  toWire(): WireError {\n    const w: WireError = { code: this.code, message: this.message };\n    if (this.type !== undefined) w.type = this.type;\n    if (this.data !== undefined) w.data = this.data;\n    if (this.path !== undefined) w.path = this.path;\n    if (this.retryable !== RETRYABLE.has(this.code)) w.retryable = this.retryable;\n    return w;\n  }\n\n  withPath(path: string): RayfoldError {\n    return new RayfoldError(this.code, this.message, { type: this.type, data: this.data, path, retryable: this.retryable });\n  }\n\n  static domain(type: string, data: unknown, message?: string): RayfoldError {\n    return new RayfoldError(\"domain\", message ?? type, { type, data });\n  }\n}\n\n/**\n * Raised through `ctx.checkVersion` when a conditional command's `ifVersion` does not match.\n * The executor projects `current` through the op's shape so the client can repair its cache without a GET.\n */\nexport class VersionConflict extends RayfoldError {\n  constructor(\n    readonly key: string,\n    readonly expected: string | number,\n    readonly actual: unknown,\n    readonly current: unknown,\n  ) {\n    super(\"failed_precondition\", `${key} is at version ${String(actual)}, not ${String(expected)}`, { type: \"VersionConflict\", data: { key, expected, actual } });\n  }\n}\n\nexport function toWireError(e: unknown): WireError {\n  if (e instanceof RayfoldError) return e.toWire();\n  if (e instanceof Error && e.name === \"AbortError\") return { code: \"canceled\", message: \"Canceled\" };\n  return { code: \"internal\", message: \"Internal error\" };\n}\n"]}

package/server.d.ts

@@ -0,0 +1,58 @@
+import type { Instrumentation } from "./instrumentation.js";
+import { type LoadedSchema, type RayfoldSchemaIR, type Shape } from "@rayfold/schema";
+import { type BatchOptions, type ExecuteOptions } from "./batch.js";
+import { EventBus, type IdempotencyStore } from "./context.js";
+import { type Resolvers } from "./executor.js";
+import type { Frame, RequestEnvelope } from "./protocol.js";
+import { type ShapeRegistry } from "./views.js";
+import { ChangeBus } from "./live.js";
+import type { UsageSink } from "./usage.js";
+export interface RayfoldServerOptions {
+    /** `.rayfold` text, a loaded schema, or a raw IR. */
+    schema: string | LoadedSchema | RayfoldSchemaIR;
+    resolvers: Resolvers;
+    /** Production mode: only registered shape ids are accepted (spec 02 §3). Default false. */
+    trustedShapes?: boolean;
+    /** Cost budget per batch (spec 06 §5). Default 1000. */
+    budget?: number;
+    maxOps?: number;
+    maxDepth?: number;
+    maxFields?: number;
+    /** Add `meta.ms` to frames. Default false (keeps frames deterministic). */
+    timing?: boolean;
+    idempotency?: IdempotencyStore;
+    shapes?: ShapeRegistry;
+    events?: EventBus;
+    now?: () => number;
+    /** Hooks around batches, ops and loaders, for tracing and metrics (`@rayfold/otel` makes them OpenTelemetry spans). */
+    instrumentation?: Instrumentation;
+    /** Where to record which members each client asks for (spec 11). Without one, nothing is recorded. */
+    usage?: UsageSink;
+}
+export declare class RayfoldServer {
+    readonly ir: RayfoldSchemaIR;
+    readonly hash: string;
+    readonly events: EventBus;
+    /** Entity/op change notifications driving live queries (extension `live`). */
+    readonly changes: ChangeBus;
+    /** Field-usage telemetry, when the server was given a sink (spec 11). */
+    readonly usage: UsageSink | undefined;
+    readonly shapes: ShapeRegistry;
+    readonly options: BatchOptions;
+    private readonly rt;
+    constructor(opts: RayfoldServerOptions);
+    /** Execute a batch; frames arrive as they are produced. */
+    execute(envelope: RequestEnvelope, opts?: ExecuteOptions): AsyncIterable<Frame>;
+    /** Convenience: run a batch and collect every frame. */
+    collect(envelope: RequestEnvelope, opts?: ExecuteOptions): Promise<Frame[]>;
+    /** Register a shape (text or AST) so it can be referenced by id in trusted mode. */
+    registerShape(shape: string | Shape): string;
+    /** Discovery document (spec 10 outline). */
+    manifest(): {
+        rayfold: string;
+        schemaHash: string;
+        extensions: string[];
+        limits: Omit<BatchOptions, "now">;
+    };
+}
+export declare function createRayfoldServer(opts: RayfoldServerOptions): RayfoldServer;

package/server.js

@@ -0,0 +1,79 @@
+import { loadSchema, schemaHash } from "@rayfold/schema";
+import { executeBatch } from "./batch.js";
+import { EventBus, MemoryIdempotencyStore } from "./context.js";
+import { Executor } from "./executor.js";
+import { MemoryShapeRegistry } from "./views.js";
+import { ChangeBus } from "./live.js";
+import { parseShapeText } from "@rayfold/schema";
+export class RayfoldServer {
+    ir;
+    hash;
+    events;
+    /** Entity/op change notifications driving live queries (extension `live`). */
+    changes = new ChangeBus();
+    /** Field-usage telemetry, when the server was given a sink (spec 11). */
+    usage;
+    shapes;
+    options;
+    rt;
+    constructor(opts) {
+        this.ir = typeof opts.schema === "string" ? loadSchema(opts.schema).ir : "ir" in opts.schema ? opts.schema.ir : opts.schema;
+        this.hash = schemaHash(this.ir);
+        this.events = opts.events ?? new EventBus();
+        this.usage = opts.usage;
+        this.shapes = opts.shapes ?? new MemoryShapeRegistry(this.ir);
+        this.options = {
+            trustedShapes: opts.trustedShapes ?? false,
+            budget: opts.budget ?? 1000,
+            maxOps: opts.maxOps ?? 50,
+            maxDepth: opts.maxDepth ?? 8,
+            maxFields: opts.maxFields ?? 500,
+            timing: opts.timing ?? false,
+            now: opts.now ?? Date.now,
+        };
+        this.rt = {
+            ir: this.ir,
+            executor: new Executor(this.ir, opts.resolvers, {
+                maxDepth: this.options.maxDepth,
+                maxFields: this.options.maxFields,
+                ...(opts.instrumentation ? { instrumentation: opts.instrumentation } : {}),
+                ...(opts.usage ? { usage: opts.usage } : {}),
+            }),
+            registry: this.shapes,
+            idempotency: opts.idempotency ?? new MemoryIdempotencyStore(undefined, this.options.now),
+            events: this.events,
+            changes: this.changes,
+            options: this.options,
+            inflight: new Map(),
+            ...(opts.usage ? { usage: opts.usage } : {}),
+            ...(opts.instrumentation ? { instrumentation: opts.instrumentation } : {}),
+        };
+    }
+    /** Execute a batch; frames arrive as they are produced. */
+    execute(envelope, opts = {}) {
+        return executeBatch(this.rt, envelope, opts);
+    }
+    /** Convenience: run a batch and collect every frame. */
+    async collect(envelope, opts = {}) {
+        const out = [];
+        for await (const f of this.execute(envelope, opts))
+            out.push(f);
+        return out;
+    }
+    /** Register a shape (text or AST) so it can be referenced by id in trusted mode. */
+    registerShape(shape) {
+        return this.shapes.register(typeof shape === "string" ? parseShapeText(shape) : shape, true);
+    }
+    /** Discovery document (spec 10 outline). */
+    manifest() {
+        const { now: _now, ...limits } = this.options;
+        const extensions = ["live", "rb"];
+        if (Object.values(this.ir.ops).some((o) => o.annotations.some((a) => a.name === "http")))
+            extensions.push("http");
+        return { rayfold: "0.1", schemaHash: this.hash, extensions, limits };
+    }
+}
+export function createRayfoldServer(opts) {
+    return new RayfoldServer(opts);
+}
+//# sourceMappingURL=server.js.map

package/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Instrumentation } from \"./instrumentation.ts\";\nimport { loadSchema, schemaHash, type LoadedSchema, type RayfoldSchemaIR, type Shape } from \"@rayfold/schema\";\nimport { executeBatch, type BatchOptions, type BatchRuntime, type ExecuteOptions } from \"./batch.ts\";\nimport { EventBus, MemoryIdempotencyStore, type IdempotencyStore } from \"./context.ts\";\nimport { Executor, type Resolvers } from \"./executor.ts\";\nimport type { Frame, RequestEnvelope } from \"./protocol.ts\";\nimport { MemoryShapeRegistry, type ShapeRegistry } from \"./views.ts\";\nimport { ChangeBus } from \"./live.ts\";\nimport type { UsageSink } from \"./usage.ts\";\nimport { parseShapeText } from \"@rayfold/schema\";\n\nexport interface RayfoldServerOptions {\n  /** `.rayfold` text, a loaded schema, or a raw IR. */\n  schema: string | LoadedSchema | RayfoldSchemaIR;\n  resolvers: Resolvers;\n  /** Production mode: only registered shape ids are accepted (spec 02 §3). Default false. */\n  trustedShapes?: boolean;\n  /** Cost budget per batch (spec 06 §5). Default 1000. */\n  budget?: number;\n  maxOps?: number;\n  maxDepth?: number;\n  maxFields?: number;\n  /** Add `meta.ms` to frames. Default false (keeps frames deterministic). */\n  timing?: boolean;\n  idempotency?: IdempotencyStore;\n  shapes?: ShapeRegistry;\n  events?: EventBus;\n  now?: () => number;\n  /** Hooks around batches, ops and loaders, for tracing and metrics (`@rayfold/otel` makes them OpenTelemetry spans). */\n  instrumentation?: Instrumentation;\n  /** Where to record which members each client asks for (spec 11). Without one, nothing is recorded. */\n  usage?: UsageSink;\n}\n\nexport class RayfoldServer {\n  readonly ir: RayfoldSchemaIR;\n  readonly hash: string;\n  readonly events: EventBus;\n  /** Entity/op change notifications driving live queries (extension `live`). */\n  readonly changes = new ChangeBus();\n  /** Field-usage telemetry, when the server was given a sink (spec 11). */\n  readonly usage: UsageSink | undefined;\n  readonly shapes: ShapeRegistry;\n  readonly options: BatchOptions;\n  private readonly rt: BatchRuntime;\n\n  constructor(opts: RayfoldServerOptions) {\n    this.ir = typeof opts.schema === \"string\" ? loadSchema(opts.schema).ir : \"ir\" in opts.schema ? opts.schema.ir : opts.schema;\n    this.hash = schemaHash(this.ir);\n    this.events = opts.events ?? new EventBus();\n    this.usage = opts.usage;\n    this.shapes = opts.shapes ?? new MemoryShapeRegistry(this.ir);\n    this.options = {\n      trustedShapes: opts.trustedShapes ?? false,\n      budget: opts.budget ?? 1000,\n      maxOps: opts.maxOps ?? 50,\n      maxDepth: opts.maxDepth ?? 8,\n      maxFields: opts.maxFields ?? 500,\n      timing: opts.timing ?? false,\n      now: opts.now ?? Date.now,\n    };\n    this.rt = {\n      ir: this.ir,\n      executor: new Executor(this.ir, opts.resolvers, {\n        maxDepth: this.options.maxDepth,\n        maxFields: this.options.maxFields,\n        ...(opts.instrumentation ? { instrumentation: opts.instrumentation } : {}),\n        ...(opts.usage ? { usage: opts.usage } : {}),\n      }),\n      registry: this.shapes,\n      idempotency: opts.idempotency ?? new MemoryIdempotencyStore(undefined, this.options.now),\n      events: this.events,\n      changes: this.changes,\n      options: this.options,\n      inflight: new Map(),\n      ...(opts.usage ? { usage: opts.usage } : {}),\n      ...(opts.instrumentation ? { instrumentation: opts.instrumentation } : {}),\n    };\n  }\n\n  /** Execute a batch; frames arrive as they are produced. */\n  execute(envelope: RequestEnvelope, opts: ExecuteOptions = {}): AsyncIterable<Frame> {\n    return executeBatch(this.rt, envelope, opts);\n  }\n\n  /** Convenience: run a batch and collect every frame. */\n  async collect(envelope: RequestEnvelope, opts: ExecuteOptions = {}): Promise<Frame[]> {\n    const out: Frame[] = [];\n    for await (const f of this.execute(envelope, opts)) out.push(f);\n    return out;\n  }\n\n  /** Register a shape (text or AST) so it can be referenced by id in trusted mode. */\n  registerShape(shape: string | Shape): string {\n    return this.shapes.register(typeof shape === \"string\" ? parseShapeText(shape) : shape, true);\n  }\n\n  /** Discovery document (spec 10 outline). */\n  manifest(): { rayfold: string; schemaHash: string; extensions: string[]; limits: Omit<BatchOptions, \"now\"> } {\n    const { now: _now, ...limits } = this.options;\n    const extensions = [\"live\", \"rb\"];\n    if (Object.values(this.ir.ops).some((o) => o.annotations.some((a) => a.name === \"http\"))) extensions.push(\"http\");\n    return { rayfold: \"0.1\", schemaHash: this.hash, extensions, limits };\n  }\n}\n\nexport function createRayfoldServer(opts: RayfoldServerOptions): RayfoldServer {\n  return new RayfoldServer(opts);\n}\n"]}

package/usage.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Field-usage telemetry (spec 11 "Field usage telemetry"): which members each client still asks for, so removing one
+ * is a fact rather than a guess. `rayfold check --unused` reads a snapshot of this and lists what no client has
+ * touched.
+ *
+ * A server records nothing unless it is given a sink. A sink keeps only what the question needs: the operation, the
+ * path of the member (`Book.author`, or empty for the operation itself), the client name from `Rayfold-Client`, when
+ * it was last seen and how often. No arguments, no values, no viewer.
+ */
+export interface UsageEvent {
+    /** the operation the request named */
+    op: string;
+    /** `Type.field`, or "" for the operation itself */
+    path: string;
+    /** the `Rayfold-Client` header, or "" when the caller did not name itself */
+    client: string;
+}
+export interface UsageSink {
+    record(event: UsageEvent, at: number): void;
+}
+export interface UsageEntry extends UsageEvent {
+    /** RFC 3339, UTC */
+    lastSeen: string;
+    count: number;
+}
+/**
+ * Usage in memory, for a single process. Real deployments hand the same events to whatever they already run for
+ * metrics; this is what `rayfold dev`, the tests and a small server use.
+ */
+export declare class MemoryUsage implements UsageSink {
+    private readonly max;
+    private readonly seen;
+    /** A full sink stops recording rather than growing without bound: telemetry must not be a way to exhaust memory. */
+    constructor(max?: number);
+    record(event: UsageEvent, at: number): void;
+    /** Everything recorded, oldest member first within an operation: the file `rayfold check --unused` reads. */
+    snapshot(): UsageEntry[];
+    get size(): number;
+}

package/usage.js

@@ -0,0 +1,44 @@
+/**
+ * Field-usage telemetry (spec 11 "Field usage telemetry"): which members each client still asks for, so removing one
+ * is a fact rather than a guess. `rayfold check --unused` reads a snapshot of this and lists what no client has
+ * touched.
+ *
+ * A server records nothing unless it is given a sink. A sink keeps only what the question needs: the operation, the
+ * path of the member (`Book.author`, or empty for the operation itself), the client name from `Rayfold-Client`, when
+ * it was last seen and how often. No arguments, no values, no viewer.
+ */
+/**
+ * Usage in memory, for a single process. Real deployments hand the same events to whatever they already run for
+ * metrics; this is what `rayfold dev`, the tests and a small server use.
+ */
+export class MemoryUsage {
+    max;
+    seen = new Map();
+    /** A full sink stops recording rather than growing without bound: telemetry must not be a way to exhaust memory. */
+    constructor(max = 100_000) {
+        this.max = max;
+    }
+    record(event, at) {
+        const key = `${event.client}|${event.op}|${event.path}`;
+        const seen = this.seen.get(key);
+        if (seen) {
+            if (at > seen.at)
+                seen.at = at;
+            seen.count++;
+            return;
+        }
+        if (this.seen.size >= this.max)
+            return;
+        this.seen.set(key, { event, at, count: 1 });
+    }
+    /** Everything recorded, oldest member first within an operation: the file `rayfold check --unused` reads. */
+    snapshot() {
+        return [...this.seen.values()]
+            .map(({ event, at, count }) => ({ ...event, lastSeen: new Date(at).toISOString(), count }))
+            .sort((a, b) => (a.op === b.op ? (a.path === b.path ? a.client.localeCompare(b.client) : a.path.localeCompare(b.path)) : a.op.localeCompare(b.op)));
+    }
+    get size() {
+        return this.seen.size;
+    }
+}
+//# sourceMappingURL=usage.js.map

package/usage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage.js","sourceRoot":"","sources":["../src/usage.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAqBH;;;GAGG;AACH,MAAM,OAAO,WAAW;IAIO,GAAG;IAHf,IAAI,GAAG,IAAI,GAAG,EAA4D,CAAC;IAE5F,oHAAoH;IACpH,YAA6B,GAAG,GAAG,OAAO;mBAAb,GAAG;IAAa,CAAC;IAE9C,MAAM,CAAC,KAAiB,EAAE,EAAU;QAClC,MAAM,GAAG,GAAG,GAAG,KAAK,CAAC,MAAM,IAAI,KAAK,CAAC,EAAE,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC;QACxD,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAChC,IAAI,IAAI,EAAE,CAAC;YACT,IAAI,EAAE,GAAG,IAAI,CAAC,EAAE;gBAAE,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC;YAC/B,IAAI,CAAC,KAAK,EAAE,CAAC;YACb,OAAO;QACT,CAAC;QACD,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,GAAG;YAAE,OAAO;QACvC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC;IAC9C,CAAC;IAED,6GAA6G;IAC7G,QAAQ;QACN,OAAO,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;aAC3B,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,KAAK,EAAE,QAAQ,EAAE,IAAI,IAAI,CAAC,EAAE,CAAC,CAAC,WAAW,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;aAC1F,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IACxJ,CAAC;IAED,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;IACxB,CAAC;CACF","sourcesContent":["/**\n * Field-usage telemetry (spec 11 \"Field usage telemetry\"): which members each client still asks for, so removing one\n * is a fact rather than a guess. `rayfold check --unused` reads a snapshot of this and lists what no client has\n * touched.\n *\n * A server records nothing unless it is given a sink. A sink keeps only what the question needs: the operation, the\n * path of the member (`Book.author`, or empty for the operation itself), the client name from `Rayfold-Client`, when\n * it was last seen and how often. No arguments, no values, no viewer.\n */\n\nexport interface UsageEvent {\n  /** the operation the request named */\n  op: string;\n  /** `Type.field`, or \"\" for the operation itself */\n  path: string;\n  /** the `Rayfold-Client` header, or \"\" when the caller did not name itself */\n  client: string;\n}\n\nexport interface UsageSink {\n  record(event: UsageEvent, at: number): void;\n}\n\nexport interface UsageEntry extends UsageEvent {\n  /** RFC 3339, UTC */\n  lastSeen: string;\n  count: number;\n}\n\n/**\n * Usage in memory, for a single process. Real deployments hand the same events to whatever they already run for\n * metrics; this is what `rayfold dev`, the tests and a small server use.\n */\nexport class MemoryUsage implements UsageSink {\n  private readonly seen = new Map<string, { event: UsageEvent; at: number; count: number }>();\n\n  /** A full sink stops recording rather than growing without bound: telemetry must not be a way to exhaust memory. */\n  constructor(private readonly max = 100_000) {}\n\n  record(event: UsageEvent, at: number): void {\n    const key = `${event.client}|${event.op}|${event.path}`;\n    const seen = this.seen.get(key);\n    if (seen) {\n      if (at > seen.at) seen.at = at;\n      seen.count++;\n      return;\n    }\n    if (this.seen.size >= this.max) return;\n    this.seen.set(key, { event, at, count: 1 });\n  }\n\n  /** Everything recorded, oldest member first within an operation: the file `rayfold check --unused` reads. */\n  snapshot(): UsageEntry[] {\n    return [...this.seen.values()]\n      .map(({ event, at, count }) => ({ ...event, lastSeen: new Date(at).toISOString(), count }))\n      .sort((a, b) => (a.op === b.op ? (a.path === b.path ? a.client.localeCompare(b.client) : a.path.localeCompare(b.path)) : a.op.localeCompare(b.op)));\n  }\n\n  get size(): number {\n    return this.seen.size;\n  }\n}\n"]}

package/views.d.ts

@@ -0,0 +1,33 @@
+/** Default views and shape helpers. Spec: spec/01 §2.7, spec/02 §2. */
+import { type FieldDef, type RayfoldSchemaIR, type Shape, type TypeRef } from "@rayfold/schema";
+export declare function isScalarLike(ir: RayfoldSchemaIR, t: TypeRef): boolean;
+export declare function isEntity(ir: RayfoldSchemaIR, t: TypeRef): boolean;
+/**
+ * Default view of a type: the `Type.default` view if declared, else every scalar/enum field
+ * (nested entities and objects are omitted). Memoised per IR.
+ */
+export declare function defaultShape(ir: RayfoldSchemaIR, t: TypeRef): Shape;
+export interface ShapeRegistry {
+    /** Resolve a `sha256:` id to a parsed shape; undefined if unknown. */
+    get(id: string): Shape | undefined;
+    /** Register an inline shape (dev mode) and return its id. */
+    /** Pinned shapes (registered by the server) are never evicted; shapes learned from requests may be. */
+    register(shape: Shape, pin?: boolean): string;
+}
+/**
+ * Shapes by id. Shapes the server registers are pinned. Shapes learned from requests are kept up to `max`, least
+ * recently used out first, so clients cannot grow the server's memory without bound.
+ */
+export declare class MemoryShapeRegistry implements ShapeRegistry {
+    private readonly ir;
+    private readonly max;
+    private readonly pinned;
+    private readonly learned;
+    constructor(ir: RayfoldSchemaIR, max?: number);
+    get(id: string): Shape | undefined;
+    register(shape: Shape, pin?: boolean): string;
+    get size(): number;
+}
+/** Turn the request's `shape` string into a Shape, honouring trusted-shapes mode. */
+export declare function resolveRequestShape(ir: RayfoldSchemaIR, shapeText: string | undefined, returns: TypeRef, registry: ShapeRegistry, trustedOnly: boolean): Shape;
+export declare function findField(fields: FieldDef[], name: string): FieldDef | undefined;

package/views.js

@@ -0,0 +1,108 @@
+/** Default views and shape helpers. Spec: spec/01 §2.7, spec/02 §2. */
+import { baseName, canonicalShape, fieldsOf, isShapeId, parseShapeText, shapeIdOf, } from "@rayfold/schema";
+import { RayfoldError } from "./protocol.js";
+const SCALAR_LIKE = new Set(["scalar", "enum"]);
+export function isScalarLike(ir, t) {
+    const d = ir.types[baseName(t)];
+    return !!d && SCALAR_LIKE.has(d.kind);
+}
+export function isEntity(ir, t) {
+    return ir.types[baseName(t)]?.kind === "entity";
+}
+/**
+ * Default view of a type: the `Type.default` view if declared, else every scalar/enum field
+ * (nested entities and objects are omitted). Memoised per IR.
+ */
+export function defaultShape(ir, t) {
+    const name = t.kind === "list" ? baseNameThroughLists(t) : t.name;
+    const key = `${name}.default`;
+    const declared = ir.views[key];
+    if (declared)
+        return declared.shape;
+    let memo = defaultMemo.get(ir);
+    if (!memo)
+        defaultMemo.set(ir, (memo = new Map()));
+    const cached = memo.get(name);
+    if (cached)
+        return cached;
+    const fields = fieldsOf(ir, t) ?? [];
+    const shape = {
+        items: fields
+            .filter((f) => f.args.length === 0 && (isScalarLike(ir, f.type) || (name === "Page" && f.name === "items")))
+            .map((f) => ({ kind: "field", name: f.name })),
+    };
+    memo.set(name, shape);
+    return shape;
+}
+const defaultMemo = new WeakMap();
+function baseNameThroughLists(t) {
+    return t.kind === "list" ? baseNameThroughLists(t.of) : t.name;
+}
+/**
+ * Shapes by id. Shapes the server registers are pinned. Shapes learned from requests are kept up to `max`, least
+ * recently used out first, so clients cannot grow the server's memory without bound.
+ */
+export class MemoryShapeRegistry {
+    ir;
+    max;
+    pinned = new Map();
+    learned = new Map();
+    constructor(ir, max = 10_000) {
+        this.ir = ir;
+        this.max = max;
+    }
+    get(id) {
+        const p = this.pinned.get(id);
+        if (p)
+            return p;
+        const s = this.learned.get(id);
+        if (s) {
+            this.learned.delete(id);
+            this.learned.set(id, s);
+        }
+        return s;
+    }
+    register(shape, pin = false) {
+        const id = shapeIdOf(canonicalShape(shape, (t, v) => this.ir.views[`${t}.${v}`]));
+        if (pin) {
+            this.pinned.set(id, shape);
+            this.learned.delete(id);
+            return id;
+        }
+        if (this.pinned.has(id))
+            return id;
+        this.learned.delete(id);
+        this.learned.set(id, shape);
+        if (this.learned.size > this.max)
+            this.learned.delete(this.learned.keys().next().value);
+        return id;
+    }
+    get size() {
+        return this.pinned.size + this.learned.size;
+    }
+}
+/** Turn the request's `shape` string into a Shape, honouring trusted-shapes mode. */
+export function resolveRequestShape(ir, shapeText, returns, registry, trustedOnly) {
+    if (shapeText === undefined)
+        return defaultShape(ir, returns);
+    if (isShapeId(shapeText)) {
+        const s = registry.get(shapeText);
+        if (!s)
+            throw new RayfoldError("not_found", `Unknown shape ${shapeText}`);
+        return s;
+    }
+    if (trustedOnly)
+        throw new RayfoldError("permission_denied", "Only registered shapes are accepted");
+    let parsed;
+    try {
+        parsed = parseShapeText(shapeText);
+    }
+    catch (e) {
+        throw new RayfoldError("invalid_argument", `Bad shape: ${e.message}`);
+    }
+    return parsed; // registered by the batch planner once depth, field and cost checks pass
+}
+export function findField(fields, name) {
+    return fields.find((f) => f.name === name);
+}
+//# sourceMappingURL=views.js.map

package/views.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"views.js","sourceRoot":"","sources":["../src/views.ts"],"names":[],"mappings":"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","sourcesContent":["/** Default views and shape helpers. Spec: spec/01 §2.7, spec/02 §2. */\nimport {\n  baseName,\n  canonicalShape,\n  fieldsOf,\n  isShapeId,\n  parseShapeText,\n  shapeIdOf,\n  type FieldDef,\n  type RayfoldSchemaIR,\n  type Shape,\n  type TypeRef,\n} from \"@rayfold/schema\";\nimport { RayfoldError } from \"./protocol.ts\";\n\nconst SCALAR_LIKE = new Set([\"scalar\", \"enum\"]);\n\nexport function isScalarLike(ir: RayfoldSchemaIR, t: TypeRef): boolean {\n  const d = ir.types[baseName(t)];\n  return !!d && SCALAR_LIKE.has(d.kind);\n}\n\nexport function isEntity(ir: RayfoldSchemaIR, t: TypeRef): boolean {\n  return ir.types[baseName(t)]?.kind === \"entity\";\n}\n\n/**\n * Default view of a type: the `Type.default` view if declared, else every scalar/enum field\n * (nested entities and objects are omitted). Memoised per IR.\n */\nexport function defaultShape(ir: RayfoldSchemaIR, t: TypeRef): Shape {\n  const name = t.kind === \"list\" ? baseNameThroughLists(t) : t.name;\n  const key = `${name}.default`;\n  const declared = ir.views[key];\n  if (declared) return declared.shape;\n  let memo = defaultMemo.get(ir);\n  if (!memo) defaultMemo.set(ir, (memo = new Map()));\n  const cached = memo.get(name);\n  if (cached) return cached;\n  const fields = fieldsOf(ir, t) ?? [];\n  const shape: Shape = {\n    items: fields\n      .filter((f) => f.args.length === 0 && (isScalarLike(ir, f.type) || (name === \"Page\" && f.name === \"items\")))\n      .map((f) => ({ kind: \"field\", name: f.name })),\n  };\n  memo.set(name, shape);\n  return shape;\n}\nconst defaultMemo = new WeakMap<RayfoldSchemaIR, Map<string, Shape>>();\n\nfunction baseNameThroughLists(t: TypeRef): string {\n  return t.kind === \"list\" ? baseNameThroughLists(t.of) : t.name;\n}\n\nexport interface ShapeRegistry {\n  /** Resolve a `sha256:` id to a parsed shape; undefined if unknown. */\n  get(id: string): Shape | undefined;\n  /** Register an inline shape (dev mode) and return its id. */\n  /** Pinned shapes (registered by the server) are never evicted; shapes learned from requests may be. */\n  register(shape: Shape, pin?: boolean): string;\n}\n\n/**\n * Shapes by id. Shapes the server registers are pinned. Shapes learned from requests are kept up to `max`, least\n * recently used out first, so clients cannot grow the server's memory without bound.\n */\nexport class MemoryShapeRegistry implements ShapeRegistry {\n  private readonly pinned = new Map<string, Shape>();\n  private readonly learned = new Map<string, Shape>();\n  constructor(\n    private readonly ir: RayfoldSchemaIR,\n    private readonly max = 10_000,\n  ) {}\n  get(id: string): Shape | undefined {\n    const p = this.pinned.get(id);\n    if (p) return p;\n    const s = this.learned.get(id);\n    if (s) {\n      this.learned.delete(id);\n      this.learned.set(id, s);\n    }\n    return s;\n  }\n  register(shape: Shape, pin = false): string {\n    const id = shapeIdOf(canonicalShape(shape, (t, v) => this.ir.views[`${t}.${v}`]));\n    if (pin) {\n      this.pinned.set(id, shape);\n      this.learned.delete(id);\n      return id;\n    }\n    if (this.pinned.has(id)) return id;\n    this.learned.delete(id);\n    this.learned.set(id, shape);\n    if (this.learned.size > this.max) this.learned.delete(this.learned.keys().next().value!);\n    return id;\n  }\n  get size(): number {\n    return this.pinned.size + this.learned.size;\n  }\n}\n\n/** Turn the request's `shape` string into a Shape, honouring trusted-shapes mode. */\nexport function resolveRequestShape(\n  ir: RayfoldSchemaIR,\n  shapeText: string | undefined,\n  returns: TypeRef,\n  registry: ShapeRegistry,\n  trustedOnly: boolean,\n): Shape {\n  if (shapeText === undefined) return defaultShape(ir, returns);\n  if (isShapeId(shapeText)) {\n    const s = registry.get(shapeText);\n    if (!s) throw new RayfoldError(\"not_found\", `Unknown shape ${shapeText}`);\n    return s;\n  }\n  if (trustedOnly) throw new RayfoldError(\"permission_denied\", \"Only registered shapes are accepted\");\n  let parsed: Shape;\n  try {\n    parsed = parseShapeText(shapeText);\n  } catch (e) {\n    throw new RayfoldError(\"invalid_argument\", `Bad shape: ${(e as Error).message}`);\n  }\n  return parsed; // registered by the batch planner once depth, field and cost checks pass\n}\n\nexport function findField(fields: FieldDef[], name: string): FieldDef | undefined {\n  return fields.find((f) => f.name === name);\n}\n"]}

package/wiring.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Do the resolvers cover the schema?
+ *
+ * The runtime answers that one call at a time: an operation with no resolver fails with `unimplemented` when someone
+ * calls it, and a field that takes arguments fails the same way when a shape asks for it. Both are found in
+ * production, by a user. This finds them at build time instead, and also finds the opposite - a resolver the schema
+ * has no place for, which is what a rename leaves behind and what nothing reports at all.
+ *
+ *     const findings = checkWiring(schema.ir, resolvers);
+ *     expect(findings).toEqual([]);          // in your own test suite
+ *
+ * `rayfold check schema.rayfold --resolvers ./src/resolvers.ts` runs the same check from the command line.
+ */
+import type { Diagnostic, RayfoldSchemaIR } from "@rayfold/schema";
+import type { Resolvers } from "./executor.js";
+export declare function checkWiring(ir: RayfoldSchemaIR, resolvers: Resolvers): Diagnostic[];

package/wiring.js

@@ -0,0 +1,57 @@
+const ROOT = { query: "Query", command: "Command", stream: "Stream" };
+const ROOTS = new Set(["Query", "Command", "Stream"]);
+export function checkWiring(ir, resolvers) {
+    const out = [];
+    const err = (code, at, message) => void out.push({ severity: "error", code, at, message });
+    const warn = (code, at, message) => void out.push({ severity: "warning", code, at, message });
+    const entries = resolvers;
+    // what the schema declares, and the runtime would refuse
+    for (const op of Object.values(ir.ops)) {
+        if (!entries[ROOT[op.kind]]?.[op.name]) {
+            err("missing-resolver", `${op.name}()`, `No ${op.kind} resolver: every call fails with unimplemented. Add ${ROOT[op.kind]}.${op.name}`);
+        }
+    }
+    for (const type of Object.values(ir.types)) {
+        if (type.builtin || !("fields" in type))
+            continue;
+        for (const field of type.fields) {
+            // a field with no arguments is read off the parent when there is no loader, which is a resolver shape of its own
+            if (!field.args.length)
+                continue;
+            if (!entries[type.name]?.[field.name]) {
+                err("missing-loader", `${type.name}.${field.name}`, `The field takes arguments, so it needs a loader: any shape asking for it fails with unimplemented`);
+            }
+        }
+    }
+    // what the resolvers wire that the schema no longer has: a rename leaves this behind and nothing says so
+    for (const [key, members] of Object.entries(entries)) {
+        if (!members)
+            continue;
+        if (ROOTS.has(key)) {
+            const kind = key === "Query" ? "query" : key === "Command" ? "command" : "stream";
+            for (const name of Object.keys(members)) {
+                const op = ir.ops[name];
+                if (!op)
+                    warn("unknown-resolver", `${name}()`, `${key}.${name} is wired, but the schema has no such operation`);
+                else if (op.kind !== kind)
+                    warn("unknown-resolver", `${name}()`, `${name} is a ${op.kind} in the schema, but it is wired under ${key}`);
+            }
+            continue;
+        }
+        const type = ir.types[key];
+        if (!type || type.builtin) {
+            warn("unknown-resolver", key, `Loaders are wired for ${key}, but the schema has no such type`);
+            continue;
+        }
+        if (!("fields" in type)) {
+            warn("unknown-resolver", key, `Loaders are wired for ${key}, but a ${type.kind} has no fields to load`);
+            continue;
+        }
+        for (const name of Object.keys(members)) {
+            if (!type.fields.some((f) => f.name === name))
+                warn("unknown-resolver", `${key}.${name}`, `${key}.${name} is wired, but the schema has no such field`);
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=wiring.js.map

package/wiring.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wiring.js","sourceRoot":"","sources":["../src/wiring.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Do the resolvers cover the schema?\n *\n * The runtime answers that one call at a time: an operation with no resolver fails with `unimplemented` when someone\n * calls it, and a field that takes arguments fails the same way when a shape asks for it. Both are found in\n * production, by a user. This finds them at build time instead, and also finds the opposite - a resolver the schema\n * has no place for, which is what a rename leaves behind and what nothing reports at all.\n *\n *     const findings = checkWiring(schema.ir, resolvers);\n *     expect(findings).toEqual([]);          // in your own test suite\n *\n * `rayfold check schema.rayfold --resolvers ./src/resolvers.ts` runs the same check from the command line.\n */\nimport type { Diagnostic, OpKind, RayfoldSchemaIR } from \"@rayfold/schema\";\nimport type { Resolvers } from \"./executor.ts\";\n\nconst ROOT: Record<OpKind, \"Query\" | \"Command\" | \"Stream\"> = { query: \"Query\", command: \"Command\", stream: \"Stream\" };\nconst ROOTS = new Set([\"Query\", \"Command\", \"Stream\"]);\n\nexport function checkWiring(ir: RayfoldSchemaIR, resolvers: Resolvers): Diagnostic[] {\n  const out: Diagnostic[] = [];\n  const err = (code: string, at: string, message: string): void => void out.push({ severity: \"error\", code, at, message });\n  const warn = (code: string, at: string, message: string): void => void out.push({ severity: \"warning\", code, at, message });\n  const entries = resolvers as Record<string, Record<string, unknown> | undefined>;\n\n  // what the schema declares, and the runtime would refuse\n  for (const op of Object.values(ir.ops)) {\n    if (!entries[ROOT[op.kind]]?.[op.name]) {\n      err(\"missing-resolver\", `${op.name}()`, `No ${op.kind} resolver: every call fails with unimplemented. Add ${ROOT[op.kind]}.${op.name}`);\n    }\n  }\n  for (const type of Object.values(ir.types)) {\n    if (type.builtin || !(\"fields\" in type)) continue;\n    for (const field of type.fields) {\n      // a field with no arguments is read off the parent when there is no loader, which is a resolver shape of its own\n      if (!field.args.length) continue;\n      if (!entries[type.name]?.[field.name]) {\n        err(\"missing-loader\", `${type.name}.${field.name}`, `The field takes arguments, so it needs a loader: any shape asking for it fails with unimplemented`);\n      }\n    }\n  }\n\n  // what the resolvers wire that the schema no longer has: a rename leaves this behind and nothing says so\n  for (const [key, members] of Object.entries(entries)) {\n    if (!members) continue;\n    if (ROOTS.has(key)) {\n      const kind = key === \"Query\" ? \"query\" : key === \"Command\" ? \"command\" : \"stream\";\n      for (const name of Object.keys(members)) {\n        const op = ir.ops[name];\n        if (!op) warn(\"unknown-resolver\", `${name}()`, `${key}.${name} is wired, but the schema has no such operation`);\n        else if (op.kind !== kind) warn(\"unknown-resolver\", `${name}()`, `${name} is a ${op.kind} in the schema, but it is wired under ${key}`);\n      }\n      continue;\n    }\n    const type = ir.types[key];\n    if (!type || type.builtin) {\n      warn(\"unknown-resolver\", key, `Loaders are wired for ${key}, but the schema has no such type`);\n      continue;\n    }\n    if (!(\"fields\" in type)) {\n      warn(\"unknown-resolver\", key, `Loaders are wired for ${key}, but a ${type.kind} has no fields to load`);\n      continue;\n    }\n    for (const name of Object.keys(members)) {\n      if (!type.fields.some((f) => f.name === name)) warn(\"unknown-resolver\", `${key}.${name}`, `${key}.${name} is wired, but the schema has no such field`);\n    }\n  }\n\n  return out;\n}\n"]}

package/ws.d.ts

@@ -0,0 +1,21 @@
+import type { IncomingMessage, Server } from "node:http";
+import type { RayfoldServer } from "./server.js";
+import { type Frame } from "./protocol.js";
+import { type OriginOptions } from "./guard.js";
+export declare const SUBPROTOCOL = "rayfold.0.1";
+export interface WsOptions extends OriginOptions {
+    /** Largest frame or assembled message accepted, in bytes. Default 1 MiB. */
+    maxMessage?: number;
+    path?: string;
+    viewer?: (req: IncomingMessage) => unknown | Promise<unknown>;
+}
+/** Attach the Rayfold WebSocket endpoint to a Node HTTP server. */
+export declare function attachWebSocket(http: Server, server: RayfoldServer, opts?: WsOptions): void;
+export declare function encodeFrame(payload: Buffer, opcode: number): Buffer;
+export declare function decodeFrame(buf: Buffer): {
+    opcode: number;
+    fin: boolean;
+    payload: Buffer;
+    length: number;
+} | null;
+export type { Frame };