@kraken-e2e/signaling 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Core types of the Kraken signal log (ADR-0003).
+ *
+ * The transport SPI is a "dumb log": append with acknowledged ordering, blocking
+ * reads after a sequence number, scope lifecycle. All intelligence (subscriber
+ * cursors, predicates, diagnostics) lives in the SignalBus facade.
+ */
+/** JSON-serializable values only; every transport round-trips payloads through JSON. */
+export type SignalPayload = null | boolean | number | string | SignalPayload[] | {
+    [key: string]: SignalPayload;
+};
+/**
+ * Isolation unit for signals. `scenarioId` must be unique per scenario INSTANCE
+ * (each Examples row gets its own scope). Cross-scenario signals are unsupported.
+ */
+export interface SignalScope {
+    readonly runId: string;
+    readonly scenarioId: string;
+}
+/** Opaque key transports use for storage isolation (Map key / Redis stream name). */
+export declare function scopeKey(scope: SignalScope): string;
+export interface SignalRecord<P extends SignalPayload = SignalPayload> {
+    /** Strictly increasing per scope; assigned by the transport's single sequencer. */
+    readonly seq: number;
+    readonly name: string;
+    /** Subscriber id (actor id) of the publisher. */
+    readonly from: string;
+    readonly payload: P;
+    /** Epoch ms at the sequencer. Diagnostic only — never used for ordering. */
+    readonly publishedAt: number;
+}
+export interface SignalQuery {
+    readonly name: string;
+    /** Only records with seq strictly greater than this match. */
+    readonly afterSeq: number;
+    /** If set, only records published by this subscriber match. */
+    readonly from?: string | undefined;
+}
+export interface TransportWaitOptions {
+    /** Waiter-local wall-clock budget. Transport latency counts against it. */
+    readonly timeoutMs: number;
+    readonly signal?: AbortSignal | undefined;
+}
+/**
+ * The transport SPI. Implementations must pass the conformance suite exported
+ * at `@kraken-e2e/signaling/conformance` before use (ADR-0003 D7).
+ */
+export interface SignalTransport {
+    createScope(scope: SignalScope): Promise<void>;
+    /**
+     * Acknowledged append: resolves once the record is durably ordered.
+     * MUST NOT resolve synchronously. Never blocks on receivers; never fails
+     * because nobody is listening.
+     */
+    publish(scope: SignalScope, signal: {
+        name: string;
+        from: string;
+        payload: SignalPayload;
+    }): Promise<SignalRecord>;
+    /**
+     * Resolves with the earliest record matching the query (name, optional from,
+     * seq > afterSeq), replaying history first, then waiting live. Rejects with
+     * SignalTimeoutError, ScopeClosedError, SignalWaitAbortedError, or
+     * TransportUnavailableError. Never hangs past timeoutMs.
+     */
+    waitFor(scope: SignalScope, query: SignalQuery, opts: TransportWaitOptions): Promise<SignalRecord>;
+    /** Full in-scope history snapshot (timeout diagnostics, reporters). */
+    history(scope: SignalScope): Promise<readonly SignalRecord[]>;
+    /** Idempotent. Rejects all pending waiters with ScopeClosedError; frees retention. */
+    destroyScope(scope: SignalScope): Promise<void>;
+    /** Health probe for `kraken doctor`. */
+    ping(): Promise<void>;
+}
+//# 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":"AAAA;;;;;;GAMG;AAEH,wFAAwF;AACxF,MAAM,MAAM,aAAa,GACrB,IAAI,GACJ,OAAO,GACP,MAAM,GACN,MAAM,GACN,aAAa,EAAE,GACf;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,CAAA;CAAE,CAAC;AAErC;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,qFAAqF;AACrF,wBAAgB,QAAQ,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAEnD;AAED,MAAM,WAAW,YAAY,CAAC,CAAC,SAAS,aAAa,GAAG,aAAa;IACnE,mFAAmF;IACnF,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,iDAAiD;IACjD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;IACpB,4EAA4E;IAC5E,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,8DAA8D;IAC9D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,+DAA+D;IAC/D,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACpC;AAED,MAAM,WAAW,oBAAoB;IACnC,2EAA2E;IAC3E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;CAC3C;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,WAAW,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C;;;;OAIG;IACH,OAAO,CACL,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,aAAa,CAAA;KAAE,GAC7D,OAAO,CAAC,YAAY,CAAC,CAAC;IACzB;;;;;OAKG;IACH,OAAO,CACL,KAAK,EAAE,WAAW,EAClB,KAAK,EAAE,WAAW,EAClB,IAAI,EAAE,oBAAoB,GACzB,OAAO,CAAC,YAAY,CAAC,CAAC;IACzB,uEAAuE;IACvE,OAAO,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,SAAS,YAAY,EAAE,CAAC,CAAC;IAC9D,sFAAsF;IACtF,YAAY,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChD,wCAAwC;IACxC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB"}

package/dist/types.js

@@ -0,0 +1,12 @@
+/**
+ * Core types of the Kraken signal log (ADR-0003).
+ *
+ * The transport SPI is a "dumb log": append with acknowledged ordering, blocking
+ * reads after a sequence number, scope lifecycle. All intelligence (subscriber
+ * cursors, predicates, diagnostics) lives in the SignalBus facade.
+ */
+/** Opaque key transports use for storage isolation (Map key / Redis stream name). */
+export function scopeKey(scope) {
+    return `${scope.runId}/${scope.scenarioId}`;
+}
+//# 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;;;;;;GAMG;AAoBH,qFAAqF;AACrF,MAAM,UAAU,QAAQ,CAAC,KAAkB;IACzC,OAAO,GAAG,KAAK,CAAC,KAAK,IAAI,KAAK,CAAC,UAAU,EAAE,CAAC;AAC9C,CAAC"}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@kraken-e2e/signaling",
+  "version": "0.1.0",
+  "description": "Standalone multi-actor signal log (scoped append-only log with per-subscriber cursors), transports, and the transport-conformance suite",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./conformance": {
+      "types": "./dist/conformance.d.ts",
+      "default": "./dist/conformance.js"
+    },
+    "./package.json": "./package.json",
+    "./redis": {
+      "types": "./dist/redis-transport.d.ts",
+      "default": "./dist/redis-transport.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "peerDependencies": {
+    "vitest": "^4.0.0",
+    "redis": "^6.1.0"
+  },
+  "peerDependenciesMeta": {
+    "vitest": {
+      "optional": true
+    },
+    "redis": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.0",
+    "typescript": "~6.0.3",
+    "vitest": "^4.1.9",
+    "redis": "~6.1.0"
+  },
+  "license": "GPL-3.0-only",
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}