@lumencast/protocol 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,159 @@
+/** LSDP major version. Bumped only on breaking envelope/semantic changes. */
+export declare const PROTOCOL_VERSION: 1;
+/** LSDP/1.0 WebSocket subprotocol — see LSDP/1 §1. Kept for 1.0 client compat. */
+export declare const WS_SUBPROTOCOL: "lsdp.v1";
+/** LSDP/1.1 WebSocket subprotocol — opts into the additive 1.1 frame surface
+ * (since_sequence resume, unsubscribe, transition, cause, nonce, client_msg_id,
+ * from_scene_id + show transition). See LSDP/1.1 envelope/header section. */
+export declare const WS_SUBPROTOCOL_V1_1: "lsdp.v1.1";
+/** Canonical advertise/accept list, ordered by preference (1.1 first, 1.0 fallback). */
+export declare const WS_SUBPROTOCOLS: readonly ["lsdp.v1.1", "lsdp.v1"];
+/** A leaf path expressed as a dot-separated string. See LSDP/1 §10 for reserved namespaces. */
+export type LeafPath = string;
+/** A scene identifier — operator-chosen, not derived. */
+export type SceneId = string;
+/** A scene version — sha256 hash prefixed with `sha256:`. */
+export type SceneVersion = string;
+/** A test session identifier. */
+export type SessionId = string;
+/** Permitted JSON values inside a `delta.patches[].value`. Objects are forbidden — push leaf-grain. */
+export type LeafValue = string | number | boolean | null | LeafValue[];
+/** Closed taxonomy of LSDP/1 error codes. Match by exact string equality. */
+export type ErrorCode = "AUTH_DENIED" | "WRITE_FORBIDDEN" | "SCENE_NOT_FOUND" | "BUNDLE_FETCH_FAILED" | "BUNDLE_INCOMPATIBLE" | "VERSION_GAP" | "VERSION_MISMATCH" | "UNKNOWN_PATH" | "INVALID_VALUE" | "RATE_LIMIT" | "TEST_SESSION_EXPIRED" | "INTERNAL";
+/** Per-leaf animation directive on a delta patch (LSDP/1.1 §3.2.2).
+ * Servers MAY emit ; runtimes interpret when applying the new value.
+ * 1.0 receivers ignore. */
+export interface TransitionSpec {
+    kind: "tween" | "spring" | "snap";
+    /** tween only */
+    duration_ms?: number;
+    /** tween only */
+    easing?: "linear" | "ease-in" | "ease-out" | "ease-in-out";
+    /** spring only */
+    stiffness?: number;
+    /** spring only */
+    damping?: number;
+}
+/** Optional provenance metadata on a delta (LSDP/1.1 §3.2.3). Receivers
+ * MUST NOT use it for semantic decisions — debug/audit only. */
+export interface Cause {
+    /** e.g. "operator:user-abc", "adapter:http_poll", "service:ranker" */
+    source: string;
+    /** Echoes InputFrame.client_msg_id verbatim when the delta was caused
+     * by an operator input. */
+    input_id?: string;
+}
+/** Show-level scene-swap transition on a scene_changed frame
+ * (LSDP/1.1 §3.3.1). Runtimes that don't recognise `kind` fall back
+ * to crossfade. */
+export interface SceneTransition {
+    kind: "crossfade" | (string & {});
+    duration_ms?: number;
+}
+/** A leaf-grain patch. */
+export interface Patch {
+    path: LeafPath;
+    value: LeafValue;
+    /** Optional 1.1 per-leaf transition directive. */
+    transition?: TransitionSpec;
+}
+interface BaseFrame {
+    v: typeof PROTOCOL_VERSION;
+    /** Monotonically increasing per subscription. Required on server frames except `pong`. */
+    seq?: number;
+    /** ISO 8601 timestamp. SHOULD be sent on snapshots and errors; MAY be omitted on deltas. */
+    ts?: string;
+}
+export interface SnapshotFrame extends BaseFrame {
+    type: "snapshot";
+    seq: number;
+    scene_id: SceneId;
+    scene_version: SceneVersion;
+    /** Flat dictionary of leaf paths to JSON values. */
+    state: Record<LeafPath, LeafValue>;
+}
+export interface DeltaFrame extends BaseFrame {
+    type: "delta";
+    seq: number;
+    /** Non-empty array of patches; applied left-to-right, atomic per frame. */
+    patches: Patch[];
+    /** Optional provenance (LSDP/1.1 §3.2.3). Debug/audit only. */
+    cause?: Cause;
+}
+export interface SceneChangedFrame extends BaseFrame {
+    type: "scene_changed";
+    seq: number;
+    scene_id: SceneId;
+    scene_version: SceneVersion;
+    /** Previously active scene id (LSDP/1.1 §3.3.1). 1.0 receivers ignore. */
+    from_scene_id?: SceneId;
+    /** Show-level transition between old and new scene (LSDP/1.1 §3.3.1). */
+    transition?: SceneTransition;
+}
+export interface ErrorFrame extends BaseFrame {
+    type: "error";
+    seq: number;
+    code: ErrorCode;
+    message: string;
+    recoverable: boolean;
+    /**
+     * REQUIRED for path-scoped codes (`WRITE_FORBIDDEN`, `UNKNOWN_PATH`,
+     * `INVALID_VALUE`) per LSDP/1.0.1 §3.4.1. Forbidden for codes that
+     * are not path-scoped.
+     */
+    path?: LeafPath;
+    /** Optional, for `RATE_LIMIT`. */
+    retry_after_ms?: number;
+    /** Optional, for `BUNDLE_INCOMPATIBLE`. */
+    requested_version?: string;
+    supported_version?: string;
+    /** Optional, for `TEST_SESSION_EXPIRED`. */
+    session?: string;
+}
+export interface PongFrame {
+    v: typeof PROTOCOL_VERSION;
+    type: "pong";
+    /** Echoes PingFrame.nonce verbatim (LSDP/1.1 §3.5). 1.0 servers omit. */
+    nonce?: string;
+}
+export type ServerFrame = SnapshotFrame | DeltaFrame | SceneChangedFrame | ErrorFrame | PongFrame;
+export interface SubscribeFrame {
+    v: typeof PROTOCOL_VERSION;
+    type: "subscribe";
+    /** Opaque authentication token. */
+    token: string;
+    /** Required for test mode (preview a specific scene); forbidden for live. */
+    scene?: SceneId;
+    /** Required for test mode with isolated session; forbidden otherwise. */
+    session?: SessionId;
+    /** Last seq the client successfully observed before disconnect
+     * (LSDP/1.1 §4.1, §18). Server resumes with deltas from
+     * since_sequence+1 if the replay buffer covers, else fresh snapshot.
+     * 1.0 servers MUST ignore this field. Omit (or 0) means no resume. */
+    since_sequence?: number;
+}
+export interface InputFrame {
+    v: typeof PROTOCOL_VERSION;
+    type: "input";
+    /** Non-empty. Server validates each path against active scene's `operator_inputs`. */
+    patches: Patch[];
+    /** Free-form correlation tag (LSDP/1.1 §4.2). Server MUST echo
+     * verbatim in the resulting Delta.cause.input_id. 1.0 servers ignore. */
+    client_msg_id?: string;
+}
+export interface PingFrame {
+    v: typeof PROTOCOL_VERSION;
+    type: "ping";
+    /** Free-form correlation identifier (LSDP/1.1 §4.3). Receiver MUST
+     * echo verbatim in the Pong reply. */
+    nonce?: string;
+}
+/** Clean teardown signal (LSDP/1.1 §4.4). Server MUST close the
+ * WebSocket within 1 second of receipt. No data flows after. */
+export interface UnsubscribeFrame {
+    v: typeof PROTOCOL_VERSION;
+    type: "unsubscribe";
+}
+export type ClientFrame = SubscribeFrame | InputFrame | PingFrame | UnsubscribeFrame;
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,13 @@
+// LSDP/1 wire types and shared shapes.
+// Canonical reference: lumencast-protocol/spec/LSDP-1.md (and ERROR-CODES.md, RUNTIME-API.md).
+/** LSDP major version. Bumped only on breaking envelope/semantic changes. */
+export const PROTOCOL_VERSION = 1;
+/** LSDP/1.0 WebSocket subprotocol — see LSDP/1 §1. Kept for 1.0 client compat. */
+export const WS_SUBPROTOCOL = "lsdp.v1";
+/** LSDP/1.1 WebSocket subprotocol — opts into the additive 1.1 frame surface
+ * (since_sequence resume, unsubscribe, transition, cause, nonce, client_msg_id,
+ * from_scene_id + show transition). See LSDP/1.1 envelope/header section. */
+export const WS_SUBPROTOCOL_V1_1 = "lsdp.v1.1";
+/** Canonical advertise/accept list, ordered by preference (1.1 first, 1.0 fallback). */
+export const WS_SUBPROTOCOLS = [WS_SUBPROTOCOL_V1_1, WS_SUBPROTOCOL];
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,uCAAuC;AACvC,+FAA+F;AAE/F,6EAA6E;AAC7E,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAU,CAAC;AAE3C,kFAAkF;AAClF,MAAM,CAAC,MAAM,cAAc,GAAG,SAAkB,CAAC;AAEjD;;6EAE6E;AAC7E,MAAM,CAAC,MAAM,mBAAmB,GAAG,WAAoB,CAAC;AAExD,wFAAwF;AACxF,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,mBAAmB,EAAE,cAAc,CAAU,CAAC"}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@lumencast/protocol",
+  "version": "0.1.0",
+  "description": "LSDP/1 wire protocol — envelope, codec, sequence, leaf-path utilities, error taxonomy, types. Pure code, no IO.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./conformance": {
+      "types": "./dist/conformance/index.d.ts",
+      "import": "./dist/conformance/index.js"
+    },
+    "./cli": "./dist/cli.js"
+  },
+  "bin": {
+    "lumencast-js-conformance": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "homepage": "https://github.com/Lumencast/lumencast-js/tree/main/packages/protocol",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Lumencast/lumencast-js.git",
+    "directory": "packages/protocol"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "ws": "^8.18.0",
+    "yaml": "^2.6.1"
+  },
+  "devDependencies": {
+    "@types/ws": "^8.5.13",
+    "vitest": "^4.1.5"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "typecheck": "tsc -b --pretty",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "conformance": "vitest run --config vitest.conformance.config.ts"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+// lumencast-js conformance CLI.
+//
+// Subcommands:
+//   conformance --server <ws-url> --control-url <http-url>
+//                [--scenarios-dir <path>] [--tag required]
+//                [--scenario <name>] [--timeout 60s]
+//
+// Walks every scenario whose tag matches `--tag` (default required) under
+// `<scenarios-dir>` (defaults to <env LUMENCAST_PROTOCOL_REPO>/conformance/v1/scenarios)
+// and runs the harness against the supplied server + control plane.
+//
+// Exit code: 0 if all PASS, 1 if any FAIL.
+
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { Harness, loadScenarios, type Report, type Tag } from "./conformance/index.js";
+
+async function main(argv: string[]): Promise<number> {
+  const sub = argv[0];
+  if (!sub || sub === "--help" || sub === "-h") {
+    printUsage();
+    return sub ? 0 : 2;
+  }
+  if (sub === "conformance") return cmdConformance(argv.slice(1));
+  process.stderr.write(`lumencast-js: unknown subcommand "${sub}"\n`);
+  printUsage();
+  return 2;
+}
+
+function printUsage(): void {
+  process.stderr.write(
+    [
+      "usage: lumencast-js-conformance conformance <flags>",
+      "",
+      "  --server <ws-url>           WS endpoint (used if /test/setup doesn't return one)",
+      "  --control-url <http-url>    HTTP test control plane root (required)",
+      "  --scenarios-dir <path>      directory containing scenario YAMLs",
+      "                              default: $LUMENCAST_PROTOCOL_REPO/conformance/v1/scenarios",
+      "  --tag <required|recommended|extended>   default: required",
+      "  --scenario <name>           run a single scenario (basename without .yaml)",
+      "  --timeout <ms>              total run timeout, default 60000",
+      "",
+    ].join("\n"),
+  );
+}
+
+async function cmdConformance(args: string[]): Promise<number> {
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args,
+      options: {
+        server: { type: "string" },
+        "control-url": { type: "string" },
+        "scenarios-dir": { type: "string" },
+        tag: { type: "string", default: "required" },
+        scenario: { type: "string" },
+        timeout: { type: "string", default: "60000" },
+        help: { type: "boolean", short: "h" },
+      },
+      strict: true,
+      allowPositionals: false,
+    });
+  } catch (err) {
+    process.stderr.write(`conformance: ${(err as Error).message}\n`);
+    return 2;
+  }
+
+  if (parsed.values["help"]) {
+    printUsage();
+    return 0;
+  }
+
+  const controlUrl = parsed.values["control-url"] as string | undefined;
+  if (!controlUrl) {
+    process.stderr.write("--control-url required\n");
+    return 2;
+  }
+  const serverUrl = parsed.values["server"] as string | undefined;
+  const tagRaw = parsed.values["tag"] as string;
+  if (tagRaw !== "required" && tagRaw !== "recommended" && tagRaw !== "extended") {
+    process.stderr.write(`--tag must be required|recommended|extended, got ${tagRaw}\n`);
+    return 2;
+  }
+  const tag: Tag = tagRaw;
+
+  const scenariosDir = resolveScenariosDir(parsed.values["scenarios-dir"] as string | undefined);
+  if (!scenariosDir) return 2;
+
+  const timeoutMs = Number.parseInt(parsed.values["timeout"] as string, 10);
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+    process.stderr.write(`--timeout invalid\n`);
+    return 2;
+  }
+
+  let scenarios;
+  try {
+    scenarios = loadScenarios({
+      scenariosDir,
+      ...(parsed.values["scenario"] ? { scenarioName: parsed.values["scenario"] as string } : {}),
+    });
+  } catch (err) {
+    process.stderr.write(`load: ${(err as Error).message}\n`);
+    return 2;
+  }
+
+  const harness = new Harness({
+    ...(serverUrl ? { serverUrl } : {}),
+    controlUrl,
+  });
+
+  const deadline = setTimeout(() => {
+    process.stderr.write(`conformance: timeout ${timeoutMs}ms exceeded\n`);
+    process.exit(1);
+  }, timeoutMs);
+  deadline.unref();
+
+  const report = await harness.runAll(scenarios, tag);
+
+  printReport(report);
+
+  return report.failed > 0 ? 1 : 0;
+}
+
+function resolveScenariosDir(flag: string | undefined): string | null {
+  if (flag) return resolve(flag);
+  const repo = process.env["LUMENCAST_PROTOCOL_REPO"];
+  if (repo) return resolve(repo, "conformance/v1/scenarios");
+  // Fallback: try several candidates so the CLI works whether it is
+  // invoked from the lumencast-js root, from inside the lumencast-protocol
+  // checkout (e.g. interop/run-matrix.sh), or from a parallel directory
+  // structure. Returns the first candidate that resolves to an existing
+  // directory ; falls back to the canonical sibling layout so the error
+  // message still points at the expected path.
+  const cwd = process.cwd();
+  const candidates = [
+    // Already inside a lumencast-protocol checkout (cwd is interop/, scripts/, …).
+    resolve(cwd, "../conformance/v1/scenarios"),
+    resolve(cwd, "conformance/v1/scenarios"),
+    // Sibling of the monorepo (the original heuristic).
+    resolve(cwd, "../lumencast-protocol/conformance/v1/scenarios"),
+    // Parent-of-parent sibling (helps when invoked from a deeper dist/ shim).
+    resolve(cwd, "../../lumencast-protocol/conformance/v1/scenarios"),
+  ];
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) return candidate;
+  }
+  return candidates[2] ?? candidates[0] ?? null;
+}
+
+function printReport(rep: Report): void {
+  process.stdout.write(
+    `Conformance report — ${rep.total} total, ${rep.passed} passed, ${rep.failed} failed, ${rep.skipped} skipped\n`,
+  );
+  for (const r of rep.results) {
+    if (r.outcome === "PASS") {
+      process.stdout.write(`  PASS  ${r.name} [${r.tag}/${r.target}]\n`);
+    } else if (r.outcome === "SKIP") {
+      process.stdout.write(`  SKIP  ${r.name} — ${r.reason ?? "filtered"}\n`);
+    } else {
+      process.stdout.write(`  FAIL  ${r.name} [${r.tag}/${r.target}] — ${r.reason ?? "unknown"}\n`);
+    }
+  }
+}
+
+main(process.argv.slice(2)).then(
+  (code) => {
+    process.exitCode = code;
+  },
+  (err) => {
+    process.stderr.write(`lumencast-js: ${(err as Error).stack ?? String(err)}\n`);
+    process.exitCode = 1;
+  },
+);