@flaxia/node 0.3.7 → 0.5.0

package/dist/swarm/__tests__/adapter.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=adapter.test.d.ts.map

package/dist/swarm/__tests__/adapter.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.test.d.ts","sourceRoot":"","sources":["../../../src/swarm/__tests__/adapter.test.ts"],"names":[],"mappings":""}

package/dist/swarm/__tests__/controller.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=controller.test.d.ts.map

package/dist/swarm/__tests__/controller.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"controller.test.d.ts","sourceRoot":"","sources":["../../../src/swarm/__tests__/controller.test.ts"],"names":[],"mappings":""}

package/dist/swarm/__tests__/defects.test.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Regression tests for the swarm node runtime, written from the
+ * feature/swarm-inference quality review and kept after the fixes landed.
+ *
+ * Every test here encodes the behaviour we WANT. Do not weaken a test in this
+ * file to make the suite green — if one of these starts failing, the defect it
+ * documents has come back.
+ *
+ *   H2  the engine / GPU device must be disposed when a session ends
+ *   M1  `maxNewTokens` and the prompt are validated against the model
+ *   M2  a coordinator `swarm-error` settles the local session
+ *   M4  the host result conforms to `SwarmInferenceResult`
+ *   M6  malformed or stray hidden-state frames are never trusted
+ */
+export {};
+//# sourceMappingURL=defects.test.d.ts.map

package/dist/swarm/__tests__/defects.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"defects.test.d.ts","sourceRoot":"","sources":["../../../src/swarm/__tests__/defects.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG"}

package/dist/swarm/__tests__/hardening.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=hardening.test.d.ts.map

package/dist/swarm/__tests__/hardening.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hardening.test.d.ts","sourceRoot":"","sources":["../../../src/swarm/__tests__/hardening.test.ts"],"names":[],"mappings":""}

package/dist/swarm/__tests__/runtime.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=runtime.test.d.ts.map

package/dist/swarm/__tests__/runtime.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.test.d.ts","sourceRoot":"","sources":["../../../src/swarm/__tests__/runtime.test.ts"],"names":[],"mappings":""}

package/dist/swarm/__tests__/session.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=session.test.d.ts.map

package/dist/swarm/__tests__/session.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.test.d.ts","sourceRoot":"","sources":["../../../src/swarm/__tests__/session.test.ts"],"names":[],"mappings":""}

package/dist/swarm/adapter.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Minimal surface of one Pooled (SwarmLLM) engine slice that a swarm session
+ * drives. It mirrors the methods `Qwen35Engine` exposes in the vendored engine
+ * (`vendor/pooled/engine/qwen35.js`) so the same adapter works for a host slice
+ * (`hasEmbed`/`hasHead`) and a middle slice.
+ */
+export interface SwarmEngineAdapter {
+    readonly dim: number;
+    readonly nc: number;
+    /** KV cache length of this slice; the session may not exceed it. */
+    readonly maxSeq?: number;
+    reset(): void;
+    /** Embed a single token into a hidden state (host slices only). */
+    embedRun(token: number, pos: number): Promise<Float32Array>;
+    /** Run a hidden state through this slice's layers. */
+    runHidden(hidden: Float32Array, pos: number): Promise<Float32Array>;
+    /** Final norm + LM head + logits (host slices only). */
+    headFromHidden(hidden: Float32Array): Promise<Float32Array>;
+    setHidden(hidden: Float32Array): void;
+    dispose(): void;
+}
+/** Config passed straight through to `Qwen35Engine.create`. */
+export interface PooledEngineSliceConfig {
+    device: unknown;
+    meta: Record<string, unknown>;
+    layerRange: [number, number];
+    hasEmbed: boolean;
+    hasHead: boolean;
+    vocab: number;
+    maxSeq?: number;
+    batchCols?: number;
+    weights: unknown;
+}
+export interface RawPooledEngine {
+    dims: {
+        dim: number;
+    };
+    NC: number;
+    maxSeq?: number;
+    reset(): void;
+    embedRun(token: number, pos: number): Promise<Float32Array>;
+    runHidden(hidden: Float32Array, pos: number): Promise<Float32Array>;
+    headFromHidden(hidden: Float32Array): Promise<Float32Array>;
+    setHidden(hidden: Float32Array): void;
+    dispose?(): void;
+}
+export interface PooledTensorInfo {
+    shape: number[];
+    byteOffset: number;
+    byteLength: number;
+    ggmlType: number;
+}
+export interface PooledGguf {
+    meta: Record<string, unknown>;
+    tensors: Record<string, PooledTensorInfo>;
+    /** Set to stream Q4_0/Q8_0 matrices straight into GPU buffers. */
+    streamEntry?: (info: PooledTensorInfo) => Promise<unknown>;
+}
+export interface PooledTokenizer {
+    vocab: Record<string, number>;
+    encode(text: string): number[];
+    decode(ids: number[]): string;
+}
+export interface PooledEngineModule {
+    Qwen35Engine: {
+        create(config: PooledEngineSliceConfig): Promise<RawPooledEngine>;
+    };
+    parseGGUFHeader(buffer: ArrayBuffer, options?: {
+        skipTokenizer?: boolean;
+    }): PooledGguf;
+    qwen35Weights(gguf: PooledGguf, bytesOf: (info: PooledTensorInfo) => Promise<Uint8Array>, options: {
+        lo: number;
+        hi: number;
+        hasEmbed: boolean;
+        hasHead: boolean;
+        mtp?: boolean;
+    }, onProgress?: (bytes: number) => void, onEntry?: (entry: unknown, name: string) => void): Promise<unknown>;
+    tokenizerFromGGUF(meta: Record<string, unknown>): unknown;
+    makeTokenizer(vocab: unknown): PooledTokenizer;
+    argmax(logits: Float32Array): number;
+    f32ToF16(value: number): number;
+    f16ToF32(value: number): number;
+    /** Upload one converted entry with writeBuffer (large matrices cannot use mappedAtCreation). */
+    gpuUploadEntry(device: unknown, entry: unknown, keepCpu?: boolean): unknown;
+    /** Stream a Q4_0/Q8_0 tensor from a fetch Response straight into GPU buffers. */
+    streamEntryToGPU(device: unknown, info: PooledTensorInfo, openRange: (info: PooledTensorInfo) => Promise<Response>, options?: {
+        staging?: number;
+    }): Promise<unknown>;
+    GGML_EMBED: string;
+}
+export type EngineModuleImporter = (url: string) => Promise<unknown>;
+export declare class SwarmEngineUnavailableError extends Error {
+    constructor(message: string);
+}
+/**
+ * Load the vendored engine module for a node's swarm slice. Fails fast with
+ * {@link SwarmEngineUnavailableError} when the context has no WebGPU adapter or
+ * the module does not look like the Pooled engine, so a node can report a clean
+ * capability failure instead of throwing deep inside an inference loop.
+ *
+ * The module URL is a runtime string (the engine ships as its own chunk), so the
+ * bundler must not try to resolve it statically; the injected importer keeps it
+ * testable without a browser.
+ */
+export declare function loadPooledEngineModule(moduleUrl: string, importer?: EngineModuleImporter): Promise<PooledEngineModule>;
+/**
+ * Wrap a raw Pooled engine slice in the stable adapter surface.
+ *
+ * `dispose()` releases the slice's own buffers *and* the GPU device it was
+ * created on: the runtime requests a fresh device per session, so leaving it
+ * alive would keep the whole model resident in the GPU on a worker that is
+ * reused for the next task. Calling it twice is a no-op.
+ */
+export declare function wrapPooledEngine(engine: RawPooledEngine, device?: unknown): SwarmEngineAdapter;
+//# sourceMappingURL=adapter.d.ts.map

package/dist/swarm/adapter.d.ts.map

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

package/dist/swarm/controller.d.ts

@@ -0,0 +1,87 @@
+import { type SwarmChainNode, type SwarmInitMessage, type SwarmMember, type SwarmSlice, type SwarmSliceMessage } from '@flaxia/sdk';
+import type { SwarmEngineAdapter } from './adapter';
+import { type SwarmSemantics } from './session';
+import type { SwarmControlMessage } from './messages';
+/**
+ * Model and tokenizer access the controller needs. `plan` runs on the host
+ * (it owns the metadata); `load` builds this node's engine slice. Both are
+ * injected so the controller is testable without a GPU or a model server.
+ */
+export interface SwarmRuntime {
+    plan(members: SwarmMember[], model: string): Promise<SwarmChainNode[]>;
+    load(slice: SwarmSlice, model: string): Promise<{
+        engine: SwarmEngineAdapter;
+        semantics: SwarmSemantics;
+        warm?: boolean;
+    }>;
+}
+export interface SwarmControllerOptions {
+    /** First control message: `swarm-init` on the host, `swarm-slice` on a worker. */
+    initial: SwarmInitMessage | SwarmSliceMessage;
+    runtime: SwarmRuntime;
+    /** Worker -> main: a JSON control message for the coordinator. */
+    sendControl: (message: unknown) => void;
+    /** Worker -> main: a binary hidden-state frame for the coordinator. */
+    sendFrame: (frame: ArrayBuffer) => void;
+    /** Worker -> main: a streamed token. */
+    emitToken: (token: string) => unknown;
+    onDone: (result: unknown) => void;
+    onError: (error: string) => void;
+}
+/**
+ * Drives one node's part of a swarm session inside the Web Worker: the host
+ * plans the split then generates; a worker loads its slice and forwards frames.
+ * All I/O is through injected callbacks, so `self` never leaks in here.
+ *
+ * The controller owns one engine for the life of the session and disposes it
+ * when the session ends either way: a worker is reused for the next task, so an
+ * undisposed slice would keep its GPU buffers (and device) resident.
+ */
+export declare class SwarmController {
+    private readonly options;
+    private frameHandler;
+    private engine;
+    private semantics;
+    private sessionId;
+    private model;
+    private chainLength;
+    private chain;
+    private slice;
+    private hostWarm;
+    private prompt;
+    private maxNewTokens;
+    private sliceLoaded;
+    private generationStarted;
+    private settled;
+    constructor(options: SwarmControllerOptions);
+    start(): Promise<void>;
+    handleControl(message: SwarmControlMessage): Promise<void>;
+    handleFrame(frame: ArrayBuffer): void;
+    /**
+     * Stop the session because the coordinator settled the task elsewhere. Exactly
+     * like a failure this disposes the engine, so the GPU buffers and device do
+     * not stay resident on a device the scheduler has already moved on from.
+     */
+    abort(reason: string): void;
+    private link;
+    /**
+     * A slice message decides how much of the model this device materialises, so
+     * validate it even when it arrived through a path that already validated it:
+     * a hostile host must not be able to ask for a slice like `end = 1e9` (whole
+     * model in GPU memory) or claim a role/position that is not its own.
+     */
+    private validateSlice;
+    private loadSlice;
+    private startHost;
+    /**
+     * The chain this node planned (or, for a node that never saw the plan, its own
+     * slice) as `SwarmInferenceNodeInfo`s. Only this node can report its own
+     * warmth, so `warm` is filled in for the host entry alone.
+     */
+    private nodeInfos;
+    /** Release the engine (and its GPU device) exactly once, at session end. */
+    private teardown;
+    private finish;
+    private fail;
+}
+//# sourceMappingURL=controller.d.ts.map

package/dist/swarm/controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"controller.d.ts","sourceRoot":"","sources":["../../src/swarm/controller.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,cAAc,EAEnB,KAAK,gBAAgB,EACrB,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,iBAAiB,EACvB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,EAAsE,KAAK,cAAc,EAAE,MAAM,WAAW,CAAC;AACpH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEtD;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,OAAO,EAAE,WAAW,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC;IACvE,IAAI,CACF,KAAK,EAAE,UAAU,EACjB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC;QAAE,MAAM,EAAE,kBAAkB,CAAC;QAAC,SAAS,EAAE,cAAc,CAAC;QAAC,IAAI,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CACvF;AAED,MAAM,WAAW,sBAAsB;IACrC,kFAAkF;IAClF,OAAO,EAAE,gBAAgB,GAAG,iBAAiB,CAAC;IAC9C,OAAO,EAAE,YAAY,CAAC;IACtB,kEAAkE;IAClE,WAAW,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;IACxC,uEAAuE;IACvE,SAAS,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAC;IACxC,wCAAwC;IACxC,SAAS,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC;IACtC,MAAM,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IAClC,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CAClC;AAED;;;;;;;;GAQG;AACH,qBAAa,eAAe;IAgBd,OAAO,CAAC,QAAQ,CAAC,OAAO;IAfpC,OAAO,CAAC,YAAY,CAA+C;IACnE,OAAO,CAAC,MAAM,CAAmC;IACjD,OAAO,CAAC,SAAS,CAA+B;IAChD,OAAO,CAAC,SAAS,CAAM;IACvB,OAAO,CAAC,KAAK,CAAM;IACnB,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,KAAK,CAAwB;IACrC,OAAO,CAAC,KAAK,CAA2B;IACxC,OAAO,CAAC,QAAQ,CAAkC;IAClD,OAAO,CAAC,MAAM,CAAyB;IACvC,OAAO,CAAC,YAAY,CAAO;IAC3B,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,iBAAiB,CAAS;IAClC,OAAO,CAAC,OAAO,CAAS;gBAEK,OAAO,EAAE,sBAAsB;IAEtD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA4BtB,aAAa,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBhE,WAAW,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI;IAKrC;;;;OAIG;IACH,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAI3B,OAAO,CAAC,IAAI;IASZ;;;;;OAKG;IACH,OAAO,CAAC,aAAa;YAuBP,SAAS;YA6BT,SAAS;IAkDvB;;;;OAIG;IACH,OAAO,CAAC,SAAS;IAcjB,4EAA4E;IAC5E,OAAO,CAAC,QAAQ;IAWhB,OAAO,CAAC,MAAM;IAOd,OAAO,CAAC,IAAI;CAMb"}

package/dist/swarm/messages.d.ts

@@ -0,0 +1,41 @@
+import { type SwarmErrorMessage, type SwarmInitMessage, type SwarmSliceMessage, type SwarmStartMessage } from '@flaxia/sdk';
+/** Swarm control messages the coordinator sends to a node. */
+export type SwarmControlMessage = SwarmInitMessage | SwarmSliceMessage | SwarmStartMessage | SwarmErrorMessage;
+/** Messages from the main thread into the swarm worker. */
+export type SwarmWorkerInbound = {
+    id: string;
+    type: 'swarm-control';
+    message: SwarmControlMessage;
+} | {
+    id: string;
+    type: 'swarm-frame';
+    frame: ArrayBuffer;
+};
+/** Messages the swarm worker sends back to the main thread. */
+export type SwarmWorkerOutbound = {
+    id: string;
+    type: 'swarm-message';
+    message: unknown;
+} | {
+    id: string;
+    type: 'swarm-frame';
+    frame: ArrayBuffer;
+};
+/**
+ * Structural validation for every control message a node accepts. The SDK
+ * validators check the fields the node relies on (slice bounds, chain position,
+ * hop keys, ids), so a malformed or hostile message is dropped before it can
+ * reach the engine or the layer loader.
+ */
+export declare function isSwarmControlMessage(value: unknown): value is SwarmControlMessage;
+export declare function isSwarmFrameMessage(value: unknown): value is {
+    id: string;
+    type: 'swarm-frame';
+    frame: ArrayBuffer;
+};
+export declare function isSwarmControlEnvelope(value: unknown): value is {
+    id: string;
+    type: 'swarm-control';
+    message: SwarmControlMessage;
+};
+//# sourceMappingURL=messages.d.ts.map

package/dist/swarm/messages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"messages.d.ts","sourceRoot":"","sources":["../../src/swarm/messages.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACvB,MAAM,aAAa,CAAC;AAErB,8DAA8D;AAC9D,MAAM,MAAM,mBAAmB,GAAG,gBAAgB,GAAG,iBAAiB,GAAG,iBAAiB,GAAG,iBAAiB,CAAC;AAE/G,2DAA2D;AAC3D,MAAM,MAAM,kBAAkB,GAC1B;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,eAAe,CAAC;IAAC,OAAO,EAAE,mBAAmB,CAAA;CAAE,GACnE;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,aAAa,CAAC;IAAC,KAAK,EAAE,WAAW,CAAA;CAAE,CAAC;AAE5D,+DAA+D;AAC/D,MAAM,MAAM,mBAAmB,GAC3B;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,eAAe,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,GACvD;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,aAAa,CAAC;IAAC,KAAK,EAAE,WAAW,CAAA;CAAE,CAAC;AAE5D;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,mBAAmB,CAOlF;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,aAAa,CAAC;IAAC,KAAK,EAAE,WAAW,CAAA;CAAE,CAIpH;AAED,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,OAAO,GACb,KAAK,IAAI;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,eAAe,CAAC;IAAC,OAAO,EAAE,mBAAmB,CAAA;CAAE,CAI9E"}

package/dist/swarm/runtime.d.ts

@@ -0,0 +1,16 @@
+import { type PooledEngineModule, type PooledTokenizer } from './adapter';
+import type { SwarmRuntime } from './controller';
+import { type SwarmSemantics } from './session';
+/**
+ * Resolve a task payload's `model` to the GGUF it loads.
+ *
+ * The payload is unvalidated API input: it must only ever match the registry
+ * above, never a caller-supplied URL, or every opted-in node could be made to
+ * range-fetch an arbitrary host of the submitter's choosing.
+ */
+export declare function resolveModelUrl(model: string): string;
+/** Range-fetch bytes, caching complete entries so a second start skips the network. */
+export declare function rangeFetch(url: string, lo: number, hi: number): Promise<Uint8Array>;
+export declare function buildSemantics(mod: PooledEngineModule, tok: PooledTokenizer): SwarmSemantics;
+export declare function createSwarmRuntime(): SwarmRuntime;
+//# sourceMappingURL=runtime.d.ts.map

package/dist/swarm/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../src/swarm/runtime.ts"],"names":[],"mappings":"AAMA,OAAO,EAIL,KAAK,kBAAkB,EAGvB,KAAK,eAAe,EACrB,MAAM,WAAW,CAAC;AACnB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAmB,KAAK,cAAc,EAAE,MAAM,WAAW,CAAC;AA4BjE;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAIrD;AAuBD,uFAAuF;AACvF,wBAAsB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAMzF;AAoFD,wBAAgB,cAAc,CAAC,GAAG,EAAE,kBAAkB,EAAE,GAAG,EAAE,eAAe,GAAG,cAAc,CA0C5F;AAED,wBAAgB,kBAAkB,IAAI,YAAY,CA2FjD"}

package/dist/swarm/session.d.ts

@@ -0,0 +1,73 @@
+import type { SwarmEngineAdapter } from './adapter';
+/**
+ * One swarm node's hidden-state link to the coordinator. Frames are opaque
+ * ArrayBuffers (see `encodeSwarmFrame`); the coordinator relays them around the
+ * chain without touching the payload.
+ */
+export interface SwarmFrameLink {
+    send(frame: ArrayBuffer): void;
+    onFrame(handler: (frame: ArrayBuffer) => void): void;
+}
+/**
+ * The bits that depend on the model/tokenizer, injected so the session logic
+ * stays testable without a GPU: how to pack a hidden state to bytes, how to
+ * unpack it, and how to pick the next token from logits.
+ */
+export interface SwarmSemantics {
+    /** Pack a hidden state to the f16 payload bytes carried by a frame. */
+    packHidden(hidden: Float32Array): Uint8Array;
+    /** Unpack a frame payload back to a hidden state. */
+    unpackHidden(payload: Uint8Array): Float32Array;
+    argmax(logits: Float32Array): number;
+    /** Tokenize the prompt (host only). */
+    encodePrompt?(text: string | string[]): number[];
+    /** Detokenize generated ids (host only). */
+    decodeTokens?(ids: number[]): string;
+    /** Stop as soon as this id is sampled (host only). */
+    eosIds?: Set<number>;
+}
+/**
+ * Ceiling on prompt + generated tokens a session may use. Enough context for
+ * chat prompts; KV memory grows with this on the attention layers the node
+ * holds, so keep it modest for crowd devices. A model with a smaller native
+ * context lowers it further when the slice is created.
+ */
+export declare const SESSION_MAX_SEQ = 4096;
+export interface SwarmHostOptions {
+    /** Number of nodes in the chain, including this host. */
+    chainLength: number;
+    /** Prompt token ids; the host tokenizes before starting. */
+    promptTokens: number[];
+    /** Maximum tokens to generate. */
+    maxNewTokens: number;
+    engine: SwarmEngineAdapter;
+    link: SwarmFrameLink;
+    semantics: SwarmSemantics;
+    /** Stop as soon as this id is sampled (it is not emitted). */
+    eosIds?: Set<number>;
+    /** Called with each generated token id as it is produced. */
+    onToken?: (id: number) => unknown;
+}
+export interface SwarmHostResult {
+    tokens: number[];
+}
+/**
+ * Drive a generation across the chain. The host embeds each token, ships the
+ * hidden state around the ring (each worker runs its slice and forwards), then
+ * runs the LM head and samples locally. With `chainLength === 1` the host is the
+ * whole model and no frames are sent.
+ */
+export declare function runSwarmHost(options: SwarmHostOptions): Promise<SwarmHostResult>;
+export interface SwarmWorkerOptions {
+    engine: SwarmEngineAdapter;
+    link: SwarmFrameLink;
+    semantics: SwarmSemantics;
+}
+/**
+ * Run one middle slice until the host's stop frame arrives. Each hidden frame
+ * is unpacked, run through this node's layers and forwarded around the ring.
+ * Resolves once the stop frame has been forwarded; rejects if a frame cannot be
+ * decoded, so a corrupt stream fails the session instead of hanging it.
+ */
+export declare function runSwarmWorker(options: SwarmWorkerOptions): Promise<void>;
+//# sourceMappingURL=session.d.ts.map

package/dist/swarm/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/swarm/session.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAEpD;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,CAAC;IAC/B,OAAO,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,GAAG,IAAI,CAAC;CACtD;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,uEAAuE;IACvE,UAAU,CAAC,MAAM,EAAE,YAAY,GAAG,UAAU,CAAC;IAC7C,qDAAqD;IACrD,YAAY,CAAC,OAAO,EAAE,UAAU,GAAG,YAAY,CAAC;IAChD,MAAM,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAAC;IACrC,uCAAuC;IACvC,YAAY,CAAC,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC;IACjD,4CAA4C;IAC5C,YAAY,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC;IACrC,sDAAsD;IACtD,MAAM,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CACtB;AAED;;;;;GAKG;AACH,eAAO,MAAM,eAAe,OAAO,CAAC;AA2EpC,MAAM,WAAW,gBAAgB;IAC/B,yDAAyD;IACzD,WAAW,EAAE,MAAM,CAAC;IACpB,4DAA4D;IAC5D,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,kCAAkC;IAClC,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,kBAAkB,CAAC;IAC3B,IAAI,EAAE,cAAc,CAAC;IACrB,SAAS,EAAE,cAAc,CAAC;IAC1B,8DAA8D;IAC9D,MAAM,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACrB,6DAA6D;IAC7D,OAAO,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC;CACnC;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CAyDtF;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,kBAAkB,CAAC;IAC3B,IAAI,EAAE,cAAc,CAAC;IACrB,SAAS,EAAE,cAAc,CAAC;CAC3B;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAsCzE"}