@labacacia/nps-sdk 1.0.0-alpha.6 → 1.0.0-alpha.7

package/dist/nop/models.js

@@ -0,0 +1,50 @@
+// Copyright 2026 INNO LOTUS PTY LTD
+// SPDX-License-Identifier: Apache-2.0
+export var TaskState;
+(function (TaskState) {
+    TaskState["PENDING"] = "pending";
+    TaskState["PREFLIGHT"] = "preflight";
+    TaskState["RUNNING"] = "running";
+    TaskState["WAITING_SYNC"] = "waiting_sync";
+    TaskState["COMPLETED"] = "completed";
+    TaskState["FAILED"] = "failed";
+    TaskState["CANCELLED"] = "cancelled";
+    TaskState["SKIPPED"] = "skipped";
+})(TaskState || (TaskState = {}));
+export var TaskPriority;
+(function (TaskPriority) {
+    TaskPriority["LOW"] = "low";
+    TaskPriority["NORMAL"] = "normal";
+    TaskPriority["HIGH"] = "high";
+})(TaskPriority || (TaskPriority = {}));
+export var BackoffStrategy;
+(function (BackoffStrategy) {
+    BackoffStrategy["FIXED"] = "fixed";
+    BackoffStrategy["LINEAR"] = "linear";
+    BackoffStrategy["EXPONENTIAL"] = "exponential";
+})(BackoffStrategy || (BackoffStrategy = {}));
+export var AggregateStrategy;
+(function (AggregateStrategy) {
+    AggregateStrategy["MERGE"] = "merge";
+    AggregateStrategy["FIRST"] = "first";
+    AggregateStrategy["FASTEST_K"] = "fastest_k";
+    AggregateStrategy["ALL"] = "all";
+})(AggregateStrategy || (AggregateStrategy = {}));
+export function computeDelayMs(policy, attempt) {
+    const base = policy.baseDelayMs ?? 1000;
+    const cap = policy.maxDelayMs ?? 30_000;
+    let delay;
+    switch (policy.backoff) {
+        case BackoffStrategy.FIXED:
+            delay = base;
+            break;
+        case BackoffStrategy.LINEAR:
+            delay = base * (attempt + 1);
+            break;
+        case BackoffStrategy.EXPONENTIAL:
+            delay = base * Math.pow(2, attempt);
+            break;
+    }
+    return Math.min(delay, cap);
+}
+//# sourceMappingURL=models.js.map

package/dist/nop/models.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"models.js","sourceRoot":"","sources":["../../src/nop/models.ts"],"names":[],"mappings":"AAAA,oCAAoC;AACpC,sCAAsC;AAEtC,MAAM,CAAN,IAAY,SASX;AATD,WAAY,SAAS;IACnB,gCAAyB,CAAA;IACzB,oCAA2B,CAAA;IAC3B,gCAAyB,CAAA;IACzB,0CAA8B,CAAA;IAC9B,oCAA2B,CAAA;IAC3B,8BAAwB,CAAA;IACxB,oCAA2B,CAAA;IAC3B,gCAAyB,CAAA;AAC3B,CAAC,EATW,SAAS,KAAT,SAAS,QASpB;AAED,MAAM,CAAN,IAAY,YAIX;AAJD,WAAY,YAAY;IACtB,2BAAc,CAAA;IACd,iCAAiB,CAAA;IACjB,6BAAe,CAAA;AACjB,CAAC,EAJW,YAAY,KAAZ,YAAY,QAIvB;AAED,MAAM,CAAN,IAAY,eAIX;AAJD,WAAY,eAAe;IACzB,kCAAqB,CAAA;IACrB,oCAAsB,CAAA;IACtB,8CAA2B,CAAA;AAC7B,CAAC,EAJW,eAAe,KAAf,eAAe,QAI1B;AAED,MAAM,CAAN,IAAY,iBAKX;AALD,WAAY,iBAAiB;IAC3B,oCAAoB,CAAA;IACpB,oCAAoB,CAAA;IACpB,4CAAwB,CAAA;IACxB,gCAAkB,CAAA;AACpB,CAAC,EALW,iBAAiB,KAAjB,iBAAiB,QAK5B;AASD,MAAM,UAAU,cAAc,CAAC,MAAmB,EAAE,OAAe;IACjE,MAAM,IAAI,GAAG,MAAM,CAAC,WAAW,IAAI,IAAI,CAAC;IACxC,MAAM,GAAG,GAAI,MAAM,CAAC,UAAU,IAAK,MAAM,CAAC;IAC1C,IAAI,KAAa,CAAC;IAClB,QAAQ,MAAM,CAAC,OAAO,EAAE,CAAC;QACvB,KAAK,eAAe,CAAC,KAAK;YAAQ,KAAK,GAAG,IAAI,CAAC;YAAC,MAAM;QACtD,KAAK,eAAe,CAAC,MAAM;YAAO,KAAK,GAAG,IAAI,GAAG,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC;YAAC,MAAM;QACtE,KAAK,eAAe,CAAC,WAAW;YAAE,KAAK,GAAG,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;YAAC,MAAM;IAC/E,CAAC;IACD,OAAO,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;AAC9B,CAAC"}

package/dist/nop/nop-types.d.ts

@@ -0,0 +1,136 @@
+/** NCP protocol version marker */
+type NcpVersion = 1;
+/** Alternative approach considered but not taken */
+export interface Alternative {
+    value: string;
+    probability: number;
+}
+/** NOP protocol version marker */
+type NopVersion = 1;
+/** Task priority levels */
+export type Priority = "urgent" | "normal" | "low";
+/** Task category — what kind of work this is */
+export type TaskCategory = "code" | "research" | "docs" | "test" | "refactor" | "ops";
+/** Task mailbox paths — where files live during lifecycle */
+export interface Mailbox {
+    /** Base path for the task mailbox */
+    base: string;
+    /** Active directory name. Default: "active" */
+    active?: string;
+    /** Done directory name. Default: "done" */
+    done?: string;
+}
+/** Context the worker needs to do its job */
+export interface TaskContext {
+    /** File paths relevant to the task */
+    files?: string[];
+    /** Key facts the worker needs to know */
+    knowledge?: string[];
+    /** Git branch to work on */
+    branch?: string;
+}
+/** Boundaries the worker must operate within */
+export interface TaskConstraints {
+    /** Model to use: "sonnet", "haiku", "opus" */
+    model?: string;
+    /** Max seconds for task execution */
+    time_limit?: number;
+    /** Directories/files the worker may touch */
+    scope?: string[];
+    /** Whether changes need operator approval gate */
+    proceed_gate?: boolean;
+}
+/** NOP payload for task dispatch (MVP subset of TaskFrame 0x40) */
+export interface NopIntentPayload {
+    _nop: NopVersion;
+    /** Unique task ID: task-{source}-{YYYYMMDD}-{HHMMSS} */
+    id: string;
+    /** Who dispatched — NPS NID format: urn:nps:agent:{domain}:{name} */
+    from: string;
+    /** Target worker NID. Omit = any available worker picks up */
+    to?: string;
+    /** ISO 8601 timestamp when task was dispatched */
+    created_at: string;
+    /** Task priority. Default: "normal" */
+    priority?: Priority;
+    /** What kind of work this task involves */
+    category?: TaskCategory;
+    /** Where task files live during lifecycle */
+    mailbox: Mailbox;
+    /** Context for the worker */
+    context?: TaskContext;
+    /** Execution boundaries (NPS-5 §3.2 scope carving) */
+    constraints?: TaskConstraints;
+}
+/** Terminal task states (NPS-5 §4 state machine) */
+export type TaskStatus = "completed" | "failed" | "timeout" | "blocked";
+/** NOP payload for task result (AlignStream equivalent — NPS-5 §3.4) */
+export interface NopResultPayload {
+    _nop: NopVersion;
+    /** Same task ID from the intent */
+    id: string;
+    /** Terminal state */
+    status: TaskStatus;
+    /** Which worker executed — NPS NID format */
+    from: string;
+    /** ISO 8601 timestamp when worker claimed the task */
+    picked_up_at: string;
+    /** ISO 8601 timestamp when worker finished */
+    completed_at: string;
+    /** Files that were modified */
+    files_changed?: string[];
+    /** Git commit hashes + messages */
+    commits?: string[];
+    /** New tasks discovered during execution */
+    follow_up?: string[];
+    /** Seconds the task took */
+    duration?: number;
+    /** Error message if failed/timeout */
+    error?: string | null;
+}
+/** Complete intent message: NCP envelope + NOP payload */
+export interface IntentMessage {
+    _ncp: NcpVersion;
+    type: "intent";
+    /** Short verb phrase: "fix-bug", "write-test", "research", "refactor" */
+    intent: string;
+    /** Orchestrator's confidence this is the right task/worker. 0-1 */
+    confidence: number;
+    /** NOP task payload */
+    payload: NopIntentPayload;
+}
+/** Complete result message: NCP envelope + NOP payload */
+export interface ResultMessage {
+    _ncp: NcpVersion;
+    type: "result";
+    /** Human-readable summary of what was done */
+    value: string;
+    /** Worker's confidence in the result quality. 0-1 */
+    probability: number;
+    /** Other approaches considered but not taken */
+    alternatives: Alternative[];
+    /** NOP result payload */
+    payload: NopResultPayload;
+}
+/** Any NOP message */
+export type NopMessage = IntentMessage | ResultMessage;
+/** All possible task states */
+export type TaskState = "pending" | "active" | "completed" | "failed" | "timeout" | "blocked" | "cancelled";
+/** Valid state transitions */
+export declare const VALID_TRANSITIONS: Record<string, TaskState[]>;
+/** Directory where a task file lives based on its state */
+export declare const STATE_DIRECTORY: Record<TaskState, string>;
+/** File extensions by message type */
+export declare const FILE_EXTENSIONS: {
+    readonly intent: ".intent.json";
+    readonly result: ".result.json";
+};
+/** Default mailbox directory names */
+export declare const MAILBOX_DEFAULTS: {
+    readonly active: "active";
+    readonly done: "done";
+    readonly inbox: "inbox";
+    readonly blocked: "blocked";
+};
+export {};
+//# sourceMappingURL=nop-types.d.ts.map

package/dist/nop/nop-types.d.ts.map

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

package/dist/nop/nop-types.js

@@ -0,0 +1,44 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) 2026 LabAcacia / INNO LOTUS PTY LTD
+//
+// NOP Task Protocol — TypeScript Type Definitions
+// NPS-5 Neural Orchestration Protocol, MVP subset
+//
+// NCP carries the envelope. NOP fills the payload.
+// IntentFrame dispatches. ResultFrame reports back.
+/** Valid state transitions */
+export const VALID_TRANSITIONS = {
+    pending: ["active", "cancelled"],
+    active: ["completed", "failed", "timeout", "blocked"],
+    blocked: ["active", "cancelled"],
+    completed: [],
+    failed: [],
+    timeout: [],
+    cancelled: [],
+};
+// -----------------------------------------------------------------------------
+// File Naming Conventions
+// -----------------------------------------------------------------------------
+/** Directory where a task file lives based on its state */
+export const STATE_DIRECTORY = {
+    pending: "inbox",
+    active: "active",
+    completed: "done",
+    failed: "done",
+    timeout: "done",
+    blocked: "blocked",
+    cancelled: "done",
+};
+/** File extensions by message type */
+export const FILE_EXTENSIONS = {
+    intent: ".intent.json",
+    result: ".result.json",
+};
+/** Default mailbox directory names */
+export const MAILBOX_DEFAULTS = {
+    active: "active",
+    done: "done",
+    inbox: "inbox",
+    blocked: "blocked",
+};
+//# sourceMappingURL=nop-types.js.map

package/dist/nop/nop-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nop-types.js","sourceRoot":"","sources":["../../src/nop/nop-types.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,oDAAoD;AACpD,EAAE;AACF,kDAAkD;AAClD,kDAAkD;AAClD,EAAE;AACF,mDAAmD;AACnD,oDAAoD;AAkKpD,8BAA8B;AAC9B,MAAM,CAAC,MAAM,iBAAiB,GAAgC;IAC5D,OAAO,EAAI,CAAC,QAAQ,EAAE,WAAW,CAAC;IAClC,MAAM,EAAK,CAAC,WAAW,EAAE,QAAQ,EAAE,SAAS,EAAE,SAAS,CAAC;IACxD,OAAO,EAAI,CAAC,QAAQ,EAAE,WAAW,CAAC;IAClC,SAAS,EAAE,EAAE;IACb,MAAM,EAAK,EAAE;IACb,OAAO,EAAI,EAAE;IACb,SAAS,EAAE,EAAE;CACd,CAAC;AAEF,gFAAgF;AAChF,0BAA0B;AAC1B,gFAAgF;AAEhF,2DAA2D;AAC3D,MAAM,CAAC,MAAM,eAAe,GAA8B;IACxD,OAAO,EAAI,OAAO;IAClB,MAAM,EAAK,QAAQ;IACnB,SAAS,EAAE,MAAM;IACjB,MAAM,EAAK,MAAM;IACjB,OAAO,EAAI,MAAM;IACjB,OAAO,EAAI,SAAS;IACpB,SAAS,EAAE,MAAM;CAClB,CAAC;AAEF,sCAAsC;AACtC,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,MAAM,EAAE,cAAc;IACtB,MAAM,EAAE,cAAc;CACd,CAAC;AAEX,sCAAsC;AACtC,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,MAAM,EAAE,QAAQ;IAChB,IAAI,EAAE,MAAM;IACZ,KAAK,EAAE,OAAO;IACd,OAAO,EAAE,SAAS;CACV,CAAC"}

package/dist/nop/registry.d.ts

@@ -0,0 +1,3 @@
+import { FrameRegistry } from "../core/registry.js";
+export declare function registerNopFrames(registry: FrameRegistry): void;
+//# sourceMappingURL=registry.d.ts.map

package/dist/nop/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/nop/registry.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAIpD,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,aAAa,GAAG,IAAI,CAK/D"}

package/dist/nop/registry.js

@@ -0,0 +1,11 @@
+// Copyright 2026 INNO LOTUS PTY LTD
+// SPDX-License-Identifier: Apache-2.0
+import { FrameType } from "../core/frames.js";
+import { AlignStreamFrame, DelegateFrame, SyncFrame, TaskFrame } from "./frames.js";
+export function registerNopFrames(registry) {
+    registry.register(FrameType.TASK, TaskFrame);
+    registry.register(FrameType.DELEGATE, DelegateFrame);
+    registry.register(FrameType.SYNC, SyncFrame);
+    registry.register(FrameType.ALIGN_STREAM, AlignStreamFrame);
+}
+//# sourceMappingURL=registry.js.map

package/dist/nop/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/nop/registry.ts"],"names":[],"mappings":"AAAA,oCAAoC;AACpC,sCAAsC;AAGtC,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAC9C,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAEpF,MAAM,UAAU,iBAAiB,CAAC,QAAuB;IACvD,QAAQ,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,EAAU,SAAS,CAAC,CAAC;IACrD,QAAQ,CAAC,QAAQ,CAAC,SAAS,CAAC,QAAQ,EAAM,aAAa,CAAC,CAAC;IACzD,QAAQ,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,EAAU,SAAS,CAAC,CAAC;IACrD,QAAQ,CAAC,QAAQ,CAAC,SAAS,CAAC,YAAY,EAAE,gBAAgB,CAAC,CAAC;AAC9D,CAAC"}

package/dist/nwp/anchor-client.d.ts

@@ -0,0 +1,109 @@
+export interface MemberInfo {
+    nid: string;
+    node_roles: string[];
+    activation_mode: string;
+    child_anchor?: boolean;
+    member_count?: number;
+    tags?: string[];
+    joined_at?: string;
+    last_seen?: string;
+    capabilities?: unknown;
+    metrics?: unknown;
+}
+export interface TopologySnapshot {
+    version: number;
+    anchor_nid: string;
+    cluster_size: number;
+    members: MemberInfo[];
+    truncated?: boolean;
+}
+export interface TopologyFilter {
+    tags_any?: string[];
+    tags_all?: string[];
+    node_roles?: string[];
+}
+export interface MemberChanges {
+    node_roles?: string[];
+    activation_mode?: string;
+    tags?: string[];
+    member_count?: number;
+    last_seen?: string;
+    capabilities?: unknown;
+    metrics?: unknown;
+}
+/** Discriminated union for topology stream events (NPS-2 §12.2). */
+export type TopologyEvent = {
+    kind: "member_joined";
+    version: number;
+    member: MemberInfo;
+} | {
+    kind: "member_left";
+    version: number;
+    nid: string;
+} | {
+    kind: "member_updated";
+    version: number;
+    nid: string;
+    changes: MemberChanges;
+} | {
+    kind: "anchor_state";
+    version: number;
+    field: string;
+    details?: unknown;
+} | {
+    kind: "resync_required";
+    version: 0;
+    reason: string;
+};
+/**
+ * Surfaces an Anchor-side topology error to the caller. `nwpErrorCode` matches
+ * one of the NWP-TOPOLOGY-* codes; `npsStatus` is the NPS status code.
+ */
+export declare class AnchorTopologyError extends Error {
+    readonly nwpErrorCode: string;
+    readonly npsStatus: string;
+    constructor(nwpErrorCode: string, npsStatus: string, message?: string);
+}
+/**
+ * Typed client for an Anchor Node's reserved query endpoints.
+ *
+ * ```ts
+ * const client = new AnchorNodeClient("http://anchor.local:8080", "/anchor");
+ *
+ * const snap = await client.getSnapshot({ scope: "cluster" });
+ * for await (const ev of client.subscribe({ sinceVersion: snap.version })) {
+ *   console.log(ev);
+ * }
+ * ```
+ */
+export declare class AnchorNodeClient {
+    private readonly baseUrl;
+    private readonly pathPrefix;
+    constructor(baseUrl: string, pathPrefix?: string);
+    /**
+     * Fetch the current cluster topology (NPS-2 §12.1).
+     *
+     * POSTs a `topology.snapshot` query and returns the first `data` element of
+     * the response CapsFrame.
+     */
+    getSnapshot(options?: {
+        scope?: "cluster" | "member";
+        include?: string[];
+        depth?: number;
+        targetNid?: string;
+    }): Promise<TopologySnapshot>;
+    /**
+     * Subscribe to live topology changes (NPS-2 §12.2).
+     *
+     * The first NDJSON line (subscription ack) is automatically skipped. Each
+     * subsequent line is parsed into a `TopologyEvent`. The generator stops after
+     * a `resync_required` event — callers MUST issue a fresh `getSnapshot` before
+     * resubscribing.
+     */
+    subscribe(options?: {
+        filter?: TopologyFilter;
+        sinceVersion?: number;
+        scope?: "cluster" | "member";
+    }): AsyncGenerator<TopologyEvent>;
+}
+//# sourceMappingURL=anchor-client.d.ts.map

package/dist/nwp/anchor-client.d.ts.map

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

package/dist/nwp/anchor-client.js

@@ -0,0 +1,279 @@
+// Copyright 2026 INNO LOTUS PTY LTD
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * AnchorNodeClient — typed HTTP client for an Anchor Node's reserved query
+ * types (NPS-2 §12 — `topology.snapshot` and `topology.stream`).
+ *
+ * Uses `fetch` only; no extra dependencies.
+ */
+// ── Wire constants ────────────────────────────────────────────────────────────
+const SCOPE_CLUSTER = "cluster";
+const SCOPE_MEMBER = "member";
+const TYPE_SNAPSHOT = "topology.snapshot";
+const TYPE_STREAM = "topology.stream";
+const EVENT_MEMBER_JOINED = "member_joined";
+const EVENT_MEMBER_LEFT = "member_left";
+const EVENT_MEMBER_UPDATED = "member_updated";
+const EVENT_ANCHOR_STATE = "anchor_state";
+const EVENT_RESYNC_REQUIRED = "resync_required";
+/**
+ * Surfaces an Anchor-side topology error to the caller. `nwpErrorCode` matches
+ * one of the NWP-TOPOLOGY-* codes; `npsStatus` is the NPS status code.
+ */
+export class AnchorTopologyError extends Error {
+    nwpErrorCode;
+    npsStatus;
+    constructor(nwpErrorCode, npsStatus, message) {
+        super(message);
+        this.nwpErrorCode = nwpErrorCode;
+        this.npsStatus = npsStatus;
+        this.name = "AnchorTopologyError";
+    }
+}
+// ── AnchorNodeClient ──────────────────────────────────────────────────────────
+/**
+ * Typed client for an Anchor Node's reserved query endpoints.
+ *
+ * ```ts
+ * const client = new AnchorNodeClient("http://anchor.local:8080", "/anchor");
+ *
+ * const snap = await client.getSnapshot({ scope: "cluster" });
+ * for await (const ev of client.subscribe({ sinceVersion: snap.version })) {
+ *   console.log(ev);
+ * }
+ * ```
+ */
+export class AnchorNodeClient {
+    baseUrl;
+    pathPrefix;
+    constructor(baseUrl, pathPrefix = "") {
+        // Normalise trailing slashes once.
+        this.baseUrl = baseUrl.replace(/\/$/, "");
+        this.pathPrefix = pathPrefix.replace(/\/$/, "");
+    }
+    // ── topology.snapshot ──────────────────────────────────────────────────────
+    /**
+     * Fetch the current cluster topology (NPS-2 §12.1).
+     *
+     * POSTs a `topology.snapshot` query and returns the first `data` element of
+     * the response CapsFrame.
+     */
+    async getSnapshot(options) {
+        const scope = options?.scope ?? "cluster";
+        const include = options?.include ?? ["members"];
+        const depth = options?.depth;
+        const targetNid = options?.targetNid;
+        const topology = {
+            scope: scope === "cluster" ? SCOPE_CLUSTER : SCOPE_MEMBER,
+            include,
+        };
+        if (depth !== undefined)
+            topology["depth"] = depth;
+        if (targetNid !== undefined)
+            topology["target_nid"] = targetNid;
+        const body = { type: TYPE_SNAPSHOT, topology };
+        const url = `${this.baseUrl}${this.pathPrefix}/query`;
+        const res = await fetch(url, {
+            method: "POST",
+            headers: { "Content-Type": "application/json", "Accept": "application/json" },
+            body: JSON.stringify(body),
+        });
+        if (!res.ok) {
+            throw await buildFetchError("topology.snapshot", res);
+        }
+        const caps = await res.json();
+        const rows = caps.data;
+        if (!Array.isArray(rows) || rows.length !== 1) {
+            throw new Error(`topology.snapshot expected exactly 1 data row; got ${Array.isArray(rows) ? rows.length : "non-array"}.`);
+        }
+        return rows[0];
+    }
+    // ── topology.stream ────────────────────────────────────────────────────────
+    /**
+     * Subscribe to live topology changes (NPS-2 §12.2).
+     *
+     * The first NDJSON line (subscription ack) is automatically skipped. Each
+     * subsequent line is parsed into a `TopologyEvent`. The generator stops after
+     * a `resync_required` event — callers MUST issue a fresh `getSnapshot` before
+     * resubscribing.
+     */
+    async *subscribe(options) {
+        const scope = options?.scope ?? "cluster";
+        const filter = options?.filter;
+        const sinceVersion = options?.sinceVersion;
+        const topology = {
+            scope: scope === "cluster" ? SCOPE_CLUSTER : SCOPE_MEMBER,
+        };
+        if (filter !== undefined)
+            topology["filter"] = filter;
+        if (sinceVersion !== undefined)
+            topology["since_version"] = sinceVersion;
+        const body = {
+            type: TYPE_STREAM,
+            action: "subscribe",
+            stream_id: crypto.randomUUID(),
+            topology,
+        };
+        const url = `${this.baseUrl}${this.pathPrefix}/subscribe`;
+        const res = await fetch(url, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "Accept": "application/x-ndjson",
+            },
+            body: JSON.stringify(body),
+        });
+        if (!res.ok) {
+            throw await buildFetchError("topology.stream", res);
+        }
+        if (res.body === null)
+            return;
+        let ackSkipped = false;
+        for await (const line of readNdjsonLines(res.body)) {
+            // Skip the first non-empty line (subscription ack).
+            if (!ackSkipped) {
+                ackSkipped = true;
+                continue;
+            }
+            // Mid-stream protocol error: { status, error } with no event_type.
+            const maybeErr = tryParseStreamError(line);
+            if (maybeErr !== null)
+                throw maybeErr;
+            const ev = parseTopologyEvent(line);
+            if (ev === null)
+                continue;
+            yield ev;
+            if (ev.kind === EVENT_RESYNC_REQUIRED)
+                return;
+        }
+    }
+}
+// ── NDJSON line reader ────────────────────────────────────────────────────────
+/**
+ * Reads a `ReadableStream<Uint8Array>` and yields complete, non-empty lines.
+ * Lines are split on `\n`; trailing `\r` is stripped.
+ */
+async function* readNdjsonLines(body) {
+    const decoder = new TextDecoder();
+    let buffer = "";
+    const reader = body.getReader();
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            buffer += decoder.decode(value, { stream: true });
+            let newlineIdx;
+            while ((newlineIdx = buffer.indexOf("\n")) !== -1) {
+                const raw = buffer.slice(0, newlineIdx);
+                buffer = buffer.slice(newlineIdx + 1);
+                const line = raw.endsWith("\r") ? raw.slice(0, -1) : raw;
+                if (line.length > 0)
+                    yield line;
+            }
+        }
+        // Flush decoder.
+        buffer += decoder.decode();
+        const remaining = buffer.endsWith("\r") ? buffer.slice(0, -1) : buffer;
+        if (remaining.length > 0)
+            yield remaining;
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
+// ── Parsing helpers ───────────────────────────────────────────────────────────
+/** Returns an `AnchorTopologyError` if the line is an error frame, else null. */
+function tryParseStreamError(line) {
+    try {
+        const obj = JSON.parse(line);
+        if (typeof obj !== "object" || obj === null)
+            return null;
+        if ("event_type" in obj)
+            return null; // It's a regular event line.
+        if (typeof obj["error"] !== "string")
+            return null;
+        if (typeof obj["status"] !== "string")
+            return null;
+        const msg = typeof obj["message"] === "string" ? obj["message"] : undefined;
+        return new AnchorTopologyError(obj["error"], obj["status"], msg);
+    }
+    catch {
+        return null;
+    }
+}
+/** Parses one NDJSON event line into a `TopologyEvent`, or null if unrecognised. */
+function parseTopologyEvent(line) {
+    let obj;
+    try {
+        obj = JSON.parse(line);
+    }
+    catch {
+        return null;
+    }
+    if (typeof obj !== "object" || obj === null)
+        return null;
+    const eventType = obj["event_type"];
+    if (typeof eventType !== "string")
+        return null;
+    const version = typeof obj["seq"] === "number" ? obj["seq"] : 0;
+    const payload = (obj["payload"] ?? {});
+    switch (eventType) {
+        case EVENT_MEMBER_JOINED:
+            return {
+                kind: "member_joined",
+                version,
+                member: payload,
+            };
+        case EVENT_MEMBER_LEFT:
+            return {
+                kind: "member_left",
+                version,
+                nid: typeof payload["nid"] === "string" ? payload["nid"] : "",
+            };
+        case EVENT_MEMBER_UPDATED:
+            return {
+                kind: "member_updated",
+                version,
+                nid: typeof payload["nid"] === "string" ? payload["nid"] : "",
+                changes: (payload["changes"] ?? {}),
+            };
+        case EVENT_ANCHOR_STATE:
+            return {
+                kind: "anchor_state",
+                version,
+                field: typeof payload["field"] === "string" ? payload["field"] : "",
+                details: payload["details"],
+            };
+        case EVENT_RESYNC_REQUIRED:
+            return {
+                kind: "resync_required",
+                version: 0,
+                reason: typeof payload["reason"] === "string" ? payload["reason"] : "unknown",
+            };
+        default:
+            return null;
+    }
+}
+/** Builds an `AnchorTopologyError` from a non-ok HTTP response. */
+async function buildFetchError(operation, res) {
+    let body;
+    try {
+        body = await res.text();
+    }
+    catch {
+        body = "";
+    }
+    try {
+        const obj = JSON.parse(body);
+        if (typeof obj === "object" && obj !== null &&
+            typeof obj["error"] === "string" &&
+            typeof obj["status"] === "string") {
+            const msg = typeof obj["message"] === "string" ? obj["message"] : body;
+            return new AnchorTopologyError(obj["error"], obj["status"], msg);
+        }
+    }
+    catch { /* fall through */ }
+    return new AnchorTopologyError("UNKNOWN", `HTTP-${res.status}`, `${operation} returned ${res.status}: ${body}`);
+}
+//# sourceMappingURL=anchor-client.js.map