@haibun/core 4.0.0-alpha.2 → 4.0.0-alpha.3

package/build/lib/resources.js

@@ -0,0 +1,249 @@
+/**
+ * Resources — the vocabulary and topology of things stored in a graph.
+ *
+ * Answers "what is a graph resource, how is it typed, how does it link, and how is it governed?"
+ * Pure declarative data: zod schemas, type aliases, vocabulary consts, and tiny pure derivations.
+ * No runtime behavior, no node built-ins — browser-safe.
+ *
+ * Contents:
+ *   - Resource identity (id/type), Access levels, Comment vocabulary
+ *   - LinkRelations + EdgePredicates: semantic labels for properties and edges (ActivityStreams / JSON-LD)
+ *   - TRel / TPropertyDef / TEdgeDef / TDomainTopology: the shape of a vertex-type declaration
+ *   - TDomainDefinition / TRegisteredDomain: how steppers register a domain
+ *   - Helpers: getRel, getMediaType, edgeRel, isReplyEdge
+ *
+ * Grounded in JSON-LD / ActivityStreams / RDF — vertex label is a local handle, `type` is the
+ * RDF class URI that JSON-LD emits, `id` is the IRI.
+ */
+import { z } from "zod";
+// ============================================================================
+// Resource identity
+// ============================================================================
+/**
+ * The universal shape of anything identifiable and typed.
+ * `id` is the identifier (IRI in JSON-LD emission), `type` is the RDF class
+ * (typically a compact IRI like "vc:VerifiableCredential"; mapped to `@type` via JSON-LD context).
+ *
+ * Field naming follows the W3C VC 2.0 data model (unquoted `id`/`type`); the `@id`/`@type`
+ * JSON-LD keywords are produced by the context at serialization time.
+ */
+export const ResourceSchema = z.object({
+    id: z.string(),
+    type: z.string(),
+});
+/** Root vertex label — any resource. Use as edge range when the target is polymorphic. */
+export const RESOURCE_LABEL = "Resource";
+// ============================================================================
+// Access levels
+// ============================================================================
+/**
+ * Visibility policy for stored resources:
+ *   - private: visible only to the resource's owner.
+ *   - public: visible to everyone.
+ *   - opened: previously private, deliberately widened for audit; history preserves the prior state.
+ *
+ * Query contexts also accept `all` to mean "do not filter by access level"; this is not
+ * a storage value, only a query-time relaxation.
+ */
+const ACCESS_LEVELS = ["private", "public", "opened"];
+const ACCESS_QUERY_LEVELS = [...ACCESS_LEVELS, "all"];
+export const AccessLevelSchema = z.enum(ACCESS_LEVELS, {
+    message: `accessLevel must be one of ${ACCESS_LEVELS.map((v) => `"${v}"`).join(", ")}`,
+});
+export const Access = AccessLevelSchema.enum;
+export const AccessQueryLevelSchema = z.enum(ACCESS_QUERY_LEVELS, {
+    message: `accessLevel (query) must be one of ${ACCESS_QUERY_LEVELS.map((v) => `"${v}"`).join(", ")}`,
+});
+export const AccessQuery = AccessQueryLevelSchema.enum;
+// ============================================================================
+// Comment vocabulary
+// ============================================================================
+/**
+ * Free-text annotation attached to any Resource. Threads via IN_REPLY_TO.
+ * The commentsOn edge carries rel IN_REPLY_TO and range Resource.
+ *
+ * Full Zod schema and domain definition live at the bottom of this file,
+ * after TDomainDefinition is declared — see `CommentSchema` and
+ * `commentDomainDefinition`.
+ */
+export const COMMENT_LABEL = "Comment";
+export const COMMENT_DOMAIN = "comment";
+export const COMMENT_EDGE = "commentsOn";
+/**
+ * Discourse — closed set of speech acts a Comment can perform.
+ *
+ * Every Comment carries a required discourse tag. The set is deliberately
+ * small and closed; adding a value is a PR and requires a linked-data
+ * mapping note.
+ *
+ *   suggest  — schema:SuggestAction; proposing a change
+ *   measure  — narration of a sosa:Observation
+ *   report   — schema:Report / as:Announce
+ *   narrate  — prose narration (no standard mapping)
+ *   question — schema:Question; asking for clarification
+ *   apply    — narration of a schema:UpdateAction (the Development is the act)
+ *   revert   — narration of a schema:UpdateAction undoing a prior apply
+ *   play     — rehearsal or try-out; prov:Activity with no side effects
+ */
+export const DISCOURSE = {
+    suggest: "suggest",
+    measure: "measure",
+    report: "report",
+    narrate: "narrate",
+    question: "question",
+    apply: "apply",
+    revert: "revert",
+    play: "play",
+};
+const DISCOURSE_VALUES = Object.values(DISCOURSE);
+export const DiscourseSchema = z.enum(DISCOURSE_VALUES, {
+    message: `discourse must be one of ${DISCOURSE_VALUES.map((v) => `"${v}"`).join(", ")}`,
+});
+export const LinkRelations = {
+    NAME: { rel: "name", uri: "as:name", range: "literal", relation: false },
+    PUBLISHED: { rel: "published", uri: "as:published", range: "literal", relation: false },
+    ATTRIBUTED_TO: { rel: "attributedTo", uri: "as:attributedTo", range: "iri", relation: false },
+    AUDIENCE: { rel: "audience", uri: "as:to", range: "iri", relation: false },
+    CONTEXT: { rel: "context", uri: "as:context", range: "container", relation: false },
+    UPDATED: { rel: "updated", uri: "as:updated", range: "literal", relation: false },
+    CONTENT: { rel: "content", uri: "as:content", range: "literal", relation: false },
+    IN_REPLY_TO: { rel: "inReplyTo", uri: "as:inReplyTo", range: "iri", relation: true },
+    ATTACHMENT: { rel: "attachment", uri: "as:attachment", range: "iri", relation: false },
+    TAG: { rel: "tag", uri: "as:tag", range: "literal", relation: false },
+    IDENTIFIER: { rel: "identifier", uri: "dcterms:identifier", range: "iri", relation: false },
+    URL: { rel: "url", uri: "as:url", range: "literal", relation: false },
+    // PROV-O — provenance and lineage
+    WAS_INFORMED_BY: { rel: "wasInformedBy", uri: "prov:wasInformedBy", range: "iri", relation: true },
+    INVALIDATED: { rel: "invalidated", uri: "prov:invalidated", range: "iri", relation: true },
+    WAS_ASSOCIATED_WITH: { rel: "wasAssociatedWith", uri: "prov:wasAssociatedWith", range: "iri", relation: false },
+    WAS_STARTED_BY: { rel: "wasStartedBy", uri: "prov:wasStartedBy", range: "iri", relation: true },
+    STARTED_AT_TIME: { rel: "startedAtTime", uri: "prov:startedAtTime", range: "literal", relation: false },
+    // SOSA / W3C SSN — observation and sensing
+    PHENOMENON_TIME: { rel: "phenomenonTime", uri: "sosa:phenomenonTime", range: "literal", relation: false },
+    RESULT_TIME: { rel: "resultTime", uri: "sosa:resultTime", range: "literal", relation: false },
+    HAS_RESULT: { rel: "hasResult", uri: "sosa:hasResult", range: "container", relation: false },
+    MADE_BY_SENSOR: { rel: "madeBySensor", uri: "sosa:madeBySensor", range: "iri", relation: true },
+    OBSERVED_PROPERTY: { rel: "observedProperty", uri: "sosa:observedProperty", range: "literal", relation: false },
+    // schema.org — action outcomes
+    SCHEMA_OBJECT: { rel: "schemaObject", uri: "schema:object", range: "literal", relation: false },
+    SCHEMA_RESULT: { rel: "schemaResult", uri: "schema:result", range: "literal", relation: false },
+    REPLACEE: { rel: "replacee", uri: "schema:replacee", range: "literal", relation: false },
+    REPLACEMENT: { rel: "replacement", uri: "schema:replacement", range: "literal", relation: false },
+    // Haibun native — no existing vocabulary mapping
+    DISCOURSE: { rel: "discourse", uri: "hbn:discourse", range: "literal", relation: false },
+    SEQ_PATH: { rel: "seqPath", uri: "hbn:seqPath", range: "literal", relation: false },
+    HOST_ID: { rel: "hostId", uri: "hbn:hostId", range: "literal", relation: false },
+    ACCESS_LEVEL: { rel: "accessLevel", uri: "hbn:accessLevel", range: "literal", relation: false },
+    MEASUREMENT_KIND: { rel: "measurementKind", uri: "hbn:measurementKind", range: "literal", relation: false },
+    SHAPE_DIGEST: { rel: "shapeDigest", uri: "hbn:shapeDigest", range: "container", relation: false },
+    OUTCOME_REASON: { rel: "outcomeReason", uri: "hbn:outcomeReason", range: "literal", relation: false },
+};
+/** Lookup a rel's RDF range. Returns undefined for unknown rels. */
+export function getRelRange(rel) {
+    for (const entry of Object.values(LinkRelations)) {
+        if (entry.rel === rel)
+            return entry.range;
+    }
+    return undefined;
+}
+/** JSON-LD context mapping: rel → standard URI. Derived from LinkRelations. */
+export const REL_CONTEXT = Object.fromEntries(Object.values(LinkRelations).map(({ rel, uri }) => [rel, uri]));
+/**
+ * Standard edge predicates for graph vertices.
+ * Each carries its LinkRelation rel — the single source of truth for predicate→rel resolution.
+ * Steppers use these as edge keys in getConcerns().edges and in createEdge() calls.
+ */
+export const EdgePredicates = {
+    from: { rel: LinkRelations.ATTRIBUTED_TO.rel },
+    to: { rel: LinkRelations.AUDIENCE.rel },
+    cc: { rel: LinkRelations.AUDIENCE.rel },
+    author: { rel: LinkRelations.ATTRIBUTED_TO.rel },
+    attachment: { rel: LinkRelations.ATTACHMENT.rel },
+    inReplyTo: { rel: LinkRelations.IN_REPLY_TO.rel },
+    references: { rel: LinkRelations.CONTEXT.rel },
+    commentsOn: { rel: LinkRelations.IN_REPLY_TO.rel },
+    endpoint: { rel: LinkRelations.URL.rel },
+    wasInformedBy: { rel: LinkRelations.WAS_INFORMED_BY.rel },
+    invalidated: { rel: LinkRelations.INVALIDATED.rel },
+    madeBySensor: { rel: LinkRelations.MADE_BY_SENSOR.rel },
+};
+/** Edge predicate name strings — use `EDGE.from` instead of `"from"`. */
+export const EDGE = Object.fromEntries(Object.keys(EdgePredicates).map((k) => [k, k]));
+/** Resolve a predicate name to its rel. */
+export function edgeRel(predicate) {
+    return EdgePredicates[predicate]?.rel;
+}
+/** Rel values that are reply-type (derived from LinkRelations entries with relation: true). */
+const relationRels = new Set(Object.values(LinkRelations)
+    .filter((lr) => lr.relation)
+    .map((lr) => lr.rel));
+/** Check if a rel value is a reply-type (conversational/threading link). */
+function isRelationRel(rel) {
+    return relationRels.has(rel);
+}
+/**
+ * Check if an edge type (predicate name or rel) is a reply-type link.
+ * Resolves predicate names via EdgePredicates, then checks the rel.
+ */
+export function isReplyEdge(edgeType) {
+    if (isRelationRel(edgeType))
+        return true;
+    const rel = edgeRel(edgeType);
+    return rel ? isRelationRel(rel) : false;
+}
+/** Get the rel for a property definition. */
+export function getRel(def) {
+    return typeof def === "string" ? def : def.rel;
+}
+/** Get the mediaType for a content property, if any. */
+export function getMediaType(def) {
+    return typeof def === "string" ? undefined : def.mediaType;
+}
+/** Domain name for type labels — auto-populated from registered domains with topology. */
+export const DOMAIN_VERTEX_LABEL = "vertex-label";
+// ============================================================================
+// Comment schema + domain definition
+// ============================================================================
+/**
+ * Comment — free-text annotation attached to any Resource. See COMMENT_LABEL /
+ * COMMENT_DOMAIN / COMMENT_EDGE near the top of this file for the vocabulary
+ * consts.
+ *
+ * `discourse` tags the speech act (suggest, measure, report, narrate,
+ * question, apply, revert, play). Closed enum in ./discourse.ts.
+ *
+ * `author` stays an optional URI string at the storage layer (e.g.
+ * "user:alice", "stepper:llm", "llm:gpt-x"). Legacy data may lack it.
+ * Structured-Actor hydration is a query-time projection, not storage.
+ */
+export const CommentSchema = z.object({
+    id: z.string(),
+    text: z.string(),
+    author: z.string().optional(),
+    discourse: DiscourseSchema,
+    timestamp: z.string(),
+});
+/**
+ * Comment domain definition — register this in a stepper's
+ * `getConcerns().domains` to expose Comment as a first-class graph vertex.
+ * Topology uses existing LinkRelations for every property; no new rels
+ * introduced here.
+ */
+export const commentDomainDefinition = {
+    selectors: [COMMENT_DOMAIN],
+    schema: CommentSchema,
+    description: "Comment",
+    topology: {
+        vertexLabel: COMMENT_LABEL,
+        id: "id",
+        properties: {
+            id: LinkRelations.IDENTIFIER.rel,
+            text: { rel: LinkRelations.CONTENT.rel, mediaType: "text/markdown" },
+            author: LinkRelations.ATTRIBUTED_TO.rel,
+            discourse: LinkRelations.DISCOURSE.rel,
+            timestamp: LinkRelations.PUBLISHED.rel,
+        },
+        edges: { [COMMENT_EDGE]: { rel: LinkRelations.IN_REPLY_TO.rel, range: RESOURCE_LABEL } },
+    },
+};
+//# sourceMappingURL=resources.js.map

package/build/lib/resources.js.map

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

package/build/lib/rpc-client.d.ts

@@ -0,0 +1,68 @@
+/**
+ * rpc-client — capability-scoped client for a haibun host's RPC
+ * transport (modules/web-server-hono/sse-transport.ts).
+ *
+ * Centralises Bearer-token auth, seqPath threading, timeout, retry
+ * with backoff, and streaming-NDJSON parsing. Callers that already
+ * have a seqPath (feature-step context) pass it; external callers
+ * may pass `[]` and the server synthesises a seqPath rooted on its
+ * own hostId, matching the MCP dispatch path.
+ */
+export type RpcClientConfig = {
+    /** Base URL of the main host (e.g. "http://localhost:8223"). */
+    baseUrl: string;
+    /** Bearer token granting the caller's scoped capabilities on the target host. */
+    capabilityToken?: string;
+    /** Per-call timeout in ms before abort. Default 30_000. */
+    timeoutMs?: number;
+    /** Retry policy. */
+    retry?: {
+        maxAttempts?: number;
+        baseDelayMs?: number;
+    };
+    /** Injected for tests. Defaults to global fetch. */
+    fetchImpl?: typeof fetch;
+};
+export type RpcCallOptions = {
+    /** Abort signal from the caller. Fires in addition to the per-call timeout. */
+    signal?: AbortSignal;
+};
+export type RpcError = {
+    error: string;
+    [k: string]: unknown;
+};
+/**
+ * Every RPC call must thread the caller's seqPath so observations on
+ * the target host link back to the invoking context (no synthetic
+ * `[0, N]` roots). Callers supply either their current feature-step's
+ * seqPath or the seqPath of the observation they are acting on.
+ */
+export declare class RpcClient {
+    private readonly baseUrl;
+    private readonly capabilityToken?;
+    private readonly timeoutMs;
+    private readonly maxAttempts;
+    private readonly baseDelayMs;
+    private readonly fetchImpl;
+    constructor(config: RpcClientConfig);
+    /**
+     * Blocking JSON-RPC call. Returns parsed JSON on success; an RpcError
+     * object (with string `error` field) on HTTP or application error.
+     */
+    call<T = unknown>(method: string, params: Record<string, unknown>, seqPath: number[], opts?: RpcCallOptions): Promise<T | RpcError>;
+    /**
+     * Streaming JSON-RPC call. Yields chunks as they arrive over NDJSON
+     * (one JSON object per line). Completes when the stream closes.
+     * Consumers may `break` early; the underlying connection is aborted.
+     */
+    stream<TChunk = unknown>(method: string, params: Record<string, unknown>, seqPath: number[], opts?: RpcCallOptions): AsyncGenerator<TChunk, void, unknown>;
+    private buildHeaders;
+    /**
+     * Retry `operation` with exponential backoff + jitter. Returns the
+     * last error as an RpcError when `maxAttempts` is exhausted. Retries
+     * on fetch network errors; does NOT retry on application errors
+     * (RpcError with `error` string) — those are the server's answer.
+     */
+    private withRetry;
+}
+//# sourceMappingURL=rpc-client.d.ts.map

package/build/lib/rpc-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rpc-client.d.ts","sourceRoot":"","sources":["../../src/lib/rpc-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,MAAM,eAAe,GAAG;IAC7B,gEAAgE;IAChE,OAAO,EAAE,MAAM,CAAC;IAChB,iFAAiF;IACjF,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,2DAA2D;IAC3D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oBAAoB;IACpB,KAAK,CAAC,EAAE;QACP,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,WAAW,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC;IACF,oDAAoD;IACpD,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC5B,+EAA+E;IAC/E,MAAM,CAAC,EAAE,WAAW,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,QAAQ,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,CAAC;AAE/D;;;;;GAKG;AACH,qBAAa,SAAS;IACrB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;gBAE7B,MAAM,EAAE,eAAe;IASnC;;;OAGG;IACH,IAAI,CAAC,CAAC,GAAG,OAAO,EACf,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,OAAO,EAAE,MAAM,EAAE,EACjB,IAAI,GAAE,cAAmB,GACvB,OAAO,CAAC,CAAC,GAAG,QAAQ,CAAC;IAmBxB;;;;OAIG;IACI,MAAM,CAAC,MAAM,GAAG,OAAO,EAC7B,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,OAAO,EAAE,MAAM,EAAE,EACjB,IAAI,GAAE,cAAmB,GACvB,cAAc,CAAC,MAAM,EAAE,IAAI,EAAE,OAAO,CAAC;IA4BxC,OAAO,CAAC,YAAY;IAMpB;;;;;OAKG;YACW,SAAS;CAiCvB"}

package/build/lib/rpc-client.js

@@ -0,0 +1,186 @@
+/**
+ * rpc-client — capability-scoped client for a haibun host's RPC
+ * transport (modules/web-server-hono/sse-transport.ts).
+ *
+ * Centralises Bearer-token auth, seqPath threading, timeout, retry
+ * with backoff, and streaming-NDJSON parsing. Callers that already
+ * have a seqPath (feature-step context) pass it; external callers
+ * may pass `[]` and the server synthesises a seqPath rooted on its
+ * own hostId, matching the MCP dispatch path.
+ */
+/**
+ * Every RPC call must thread the caller's seqPath so observations on
+ * the target host link back to the invoking context (no synthetic
+ * `[0, N]` roots). Callers supply either their current feature-step's
+ * seqPath or the seqPath of the observation they are acting on.
+ */
+export class RpcClient {
+    baseUrl;
+    capabilityToken;
+    timeoutMs;
+    maxAttempts;
+    baseDelayMs;
+    fetchImpl;
+    constructor(config) {
+        this.baseUrl = config.baseUrl.replace(/\/+$/, "");
+        this.capabilityToken = config.capabilityToken;
+        this.timeoutMs = config.timeoutMs ?? 30_000;
+        this.maxAttempts = config.retry?.maxAttempts ?? 3;
+        this.baseDelayMs = config.retry?.baseDelayMs ?? 250;
+        this.fetchImpl = config.fetchImpl ?? ((...args) => fetch(...args));
+    }
+    /**
+     * Blocking JSON-RPC call. Returns parsed JSON on success; an RpcError
+     * object (with string `error` field) on HTTP or application error.
+     */
+    call(method, params, seqPath, opts = {}) {
+        return this.withRetry(async (signal) => {
+            const url = `${this.baseUrl}/rpc/${encodeURIComponent(method)}`;
+            const res = await this.fetchImpl(url, {
+                method: "POST",
+                headers: this.buildHeaders(),
+                body: JSON.stringify({ jsonrpc: "2.0", id: `rpc-${Date.now()}`, method, params, seqPath }),
+                signal,
+            });
+            const body = (await res.json());
+            if (!res.ok) {
+                // 422 = application error with a body we want to surface intact.
+                if (typeof body.error === "string")
+                    return body;
+                return { error: `HTTP ${res.status}` };
+            }
+            return body;
+        }, opts.signal);
+    }
+    /**
+     * Streaming JSON-RPC call. Yields chunks as they arrive over NDJSON
+     * (one JSON object per line). Completes when the stream closes.
+     * Consumers may `break` early; the underlying connection is aborted.
+     */
+    async *stream(method, params, seqPath, opts = {}) {
+        const controller = new AbortController();
+        if (opts.signal) {
+            if (opts.signal.aborted)
+                controller.abort();
+            else
+                opts.signal.addEventListener("abort", () => controller.abort(), { once: true });
+        }
+        const timeoutHandle = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+            const url = `${this.baseUrl}/rpc/${encodeURIComponent(method)}`;
+            const res = await this.fetchImpl(url, {
+                method: "POST",
+                headers: this.buildHeaders(),
+                body: JSON.stringify({ jsonrpc: "2.0", id: `rpc-stream-${Date.now()}`, method, params, seqPath, stream: true }),
+                signal: controller.signal,
+            });
+            if (!res.ok || !res.body) {
+                const text = res.body ? await res.text().catch(() => "") : "";
+                throw new Error(`stream ${method}: HTTP ${res.status}${text ? ` — ${text}` : ""}`);
+            }
+            yield* readNdjson(res.body);
+        }
+        finally {
+            clearTimeout(timeoutHandle);
+            // If the consumer didn't already abort, do so now to ensure
+            // no dangling connection — this is a no-op if already closed.
+            controller.abort();
+        }
+    }
+    buildHeaders() {
+        const h = { "Content-Type": "application/json" };
+        if (this.capabilityToken)
+            h.Authorization = `Bearer ${this.capabilityToken}`;
+        return h;
+    }
+    /**
+     * Retry `operation` with exponential backoff + jitter. Returns the
+     * last error as an RpcError when `maxAttempts` is exhausted. Retries
+     * on fetch network errors; does NOT retry on application errors
+     * (RpcError with `error` string) — those are the server's answer.
+     */
+    async withRetry(operation, outerSignal) {
+        let lastErr;
+        for (let attempt = 0; attempt < this.maxAttempts; attempt++) {
+            const controller = new AbortController();
+            const abortFromOuter = () => controller.abort();
+            if (outerSignal) {
+                if (outerSignal.aborted) {
+                    controller.abort();
+                }
+                else {
+                    outerSignal.addEventListener("abort", abortFromOuter, { once: true });
+                }
+            }
+            const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
+            try {
+                return await operation(controller.signal);
+            }
+            catch (err) {
+                lastErr = err;
+                if (outerSignal?.aborted)
+                    throw err;
+            }
+            finally {
+                clearTimeout(timeout);
+                outerSignal?.removeEventListener("abort", abortFromOuter);
+            }
+            if (attempt + 1 < this.maxAttempts) {
+                const backoff = this.baseDelayMs * 2 ** attempt;
+                const jitter = Math.floor(Math.random() * this.baseDelayMs);
+                await new Promise((r) => setTimeout(r, backoff + jitter));
+            }
+        }
+        return { error: `rpc failed after ${this.maxAttempts} attempts: ${lastErr instanceof Error ? lastErr.message : String(lastErr)}` };
+    }
+}
+/**
+ * Parse an NDJSON response body — one JSON object per line. Tolerates
+ * partial lines across chunks. Stops on stream end.
+ */
+async function* readNdjson(body) {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            buffer += decoder.decode(value, { stream: true });
+            let idx = buffer.indexOf("\n");
+            while (idx !== -1) {
+                const line = buffer.slice(0, idx).trim();
+                buffer = buffer.slice(idx + 1);
+                if (line.length > 0) {
+                    try {
+                        yield JSON.parse(line);
+                    }
+                    catch {
+                        // Malformed chunk — skip rather than crash the stream.
+                    }
+                }
+                idx = buffer.indexOf("\n");
+            }
+        }
+        // Flush any remaining buffered content (final line without trailing newline).
+        const tail = buffer.trim();
+        if (tail.length > 0) {
+            try {
+                yield JSON.parse(tail);
+            }
+            catch {
+                /* ignore trailing malformed content */
+            }
+        }
+    }
+    finally {
+        try {
+            await reader.cancel();
+        }
+        catch {
+            /* reader already closed */
+        }
+    }
+}
+//# sourceMappingURL=rpc-client.js.map

package/build/lib/rpc-client.js.map

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

package/build/lib/sse-subscriber.d.ts

@@ -0,0 +1,57 @@
+/**
+ * sse-subscriber — EventSource client shared by every consumer of a
+ * haibun host's /sse event stream.
+ *
+ * Browser SPAs connect to their own origin's /sse; Node-side peers
+ * connect to another host's /sse. Both need the same primitives: open,
+ * dispatch parsed events to listeners, reconnect on error with backoff,
+ * filter subscriptions, close cleanly. This class centralises that.
+ *
+ * Transport-agnostic within the EventSource contract: the caller
+ * supplies the URL; whether it resolves to the same origin or a
+ * remote host is the caller's concern.
+ *
+ * The SSE message format this subscriber decodes is the one
+ * web-server-hono's SSETransport emits: each `message` event's
+ * `data` field is a JSON envelope with `{ type, event, ... }` or a
+ * plain event payload. Payloads that don't parse as JSON are passed
+ * through verbatim so callers can handle wire-format variants.
+ */
+type EventHandler = (event: Record<string, unknown>) => void;
+type EventFilter = (event: Record<string, unknown>) => boolean;
+type EventSourceCtor = new (url: string) => any;
+export type SseSubscriberConfig = {
+    /** Full URL of the SSE endpoint — absolute for remote hosts, relative for same-origin. */
+    url: string;
+    /** Reconnect delay on error, in ms. Default 2000. */
+    reconnectDelayMs?: number;
+    /**
+     * Override the EventSource constructor. Defaults to globalThis.EventSource.
+     * Tests inject a mock; Node consumers can pass undici's or a polyfill.
+     */
+    EventSourceCtor?: EventSourceCtor;
+    /** Short tag included in log lines to distinguish multiple subscribers. */
+    clientId?: string;
+};
+export declare class SseSubscriber {
+    private readonly url;
+    private readonly reconnectDelayMs;
+    private readonly EventSourceCtor;
+    private readonly clientId;
+    private source;
+    private reconnectTimer;
+    private readonly listeners;
+    private closed;
+    constructor(config: SseSubscriberConfig);
+    /** Open the stream. Subsequent subscribe/close calls operate on this connection. Idempotent. */
+    connect(): void;
+    /** Register a listener. Returns an unsubscribe function. */
+    subscribe(handler: EventHandler, filter?: EventFilter): () => void;
+    /** Tag for log correlation. */
+    get id(): string;
+    /** Close the connection and stop reconnecting. */
+    close(): void;
+    private dispatch;
+}
+export {};
+//# sourceMappingURL=sse-subscriber.d.ts.map

package/build/lib/sse-subscriber.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse-subscriber.d.ts","sourceRoot":"","sources":["../../src/lib/sse-subscriber.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,KAAK,YAAY,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;AAC7D,KAAK,WAAW,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC;AAG/D,KAAK,eAAe,GAAG,KAAK,GAAG,EAAE,MAAM,KAAK,GAAG,CAAC;AAEhD,MAAM,MAAM,mBAAmB,GAAG;IACjC,0FAA0F;IAC1F,GAAG,EAAE,MAAM,CAAC;IACZ,qDAAqD;IACrD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,qBAAa,aAAa;IACzB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAkB;IAClD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAElC,OAAO,CAAC,MAAM,CAAoB;IAClC,OAAO,CAAC,cAAc,CAA8C;IACpE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAyD;IACnF,OAAO,CAAC,MAAM,CAAS;gBAEX,MAAM,EAAE,mBAAmB;IAWvC,gGAAgG;IAChG,OAAO,IAAI,IAAI;IA4Bf,4DAA4D;IAC5D,SAAS,CAAC,OAAO,EAAE,YAAY,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,MAAM,IAAI;IASlE,+BAA+B;IAC/B,IAAI,EAAE,IAAI,MAAM,CAEf;IAED,kDAAkD;IAClD,KAAK,IAAI,IAAI;IAUb,OAAO,CAAC,QAAQ;CAShB"}