@namzu/sdk 27.0.0 → 28.0.0

package/dist/store/topic/objective.d.ts

@@ -0,0 +1,104 @@
+import type { TenantId, TopicId } from '../../types/ids/index.js';
+import { type ObjectivePhase, type ObjectiveRoundVerdict, type TopicObjective } from '../../types/topic/objective.js';
+export interface CreateObjectiveParams {
+    readonly id: string;
+    readonly topicId: TopicId;
+    readonly objective: string;
+    /** Rounds this objective may BEGIN before it blocks itself. */
+    readonly maxRounds: number;
+}
+export interface TopicObjectiveStore {
+    /** `null` when this id has never been written, or belongs to another tenant. */
+    getObjective(id: string, tenantId: TenantId): Promise<TopicObjective | null>;
+    /**
+     * Refuses an id that already exists, rather than overwriting.
+     *
+     * A create that silently replaced would reset `roundsStarted` — the one
+     * field whose whole job is to be un-resettable by the thing it caps.
+     */
+    createObjective(params: CreateObjectiveParams, tenantId: TenantId): Promise<TopicObjective>;
+    /**
+     * Debit one round, under compare-and-set on `revision`.
+     *
+     * Returns the record with `roundsStarted` already incremented, so the
+     * caller cannot run the round and then fail to record that it did.
+     * Throws `ObjectiveExhaustedError` when the cap is reached, having first
+     * written the `blocked` phase — so a reader that never sees the throw
+     * still finds the objective stopped for a stated reason.
+     */
+    beginRound(id: string, tenantId: TenantId, opts: {
+        revision: number;
+    }): Promise<TopicObjective>;
+    /** Record what a round decided, under the same compare-and-set. */
+    settleRound(id: string, tenantId: TenantId, verdict: ObjectiveRoundVerdict, opts: {
+        revision: number;
+    }): Promise<TopicObjective>;
+    /** Move between `active` and `paused`, under the same compare-and-set. */
+    setPhase(id: string, tenantId: TenantId, phase: ObjectivePhase, opts: {
+        revision: number;
+    }): Promise<TopicObjective>;
+}
+/** A round asked for beyond the cap. */
+export declare class ObjectiveExhaustedError extends Error {
+    readonly details: {
+        id: string;
+        maxRounds: number;
+    };
+    constructor(details: {
+        id: string;
+        maxRounds: number;
+    });
+}
+/** An id that already exists. */
+export declare class ObjectiveExistsError extends Error {
+    readonly details: {
+        id: string;
+    };
+    constructor(details: {
+        id: string;
+    });
+}
+/**
+ * The shared write logic.
+ *
+ * Both implementations differ only in where the record lands, so the rules
+ * — what a round costs, when the cap bites, which phases accept a write —
+ * are written once. Two copies of a compare-and-set is two chances to have
+ * one of them drift, and the drift would be invisible until a host used the
+ * other implementation.
+ */
+declare abstract class ObjectiveStoreBase implements TopicObjectiveStore {
+    protected readonly now: () => number;
+    protected constructor(now: () => number);
+    abstract getObjective(id: string, tenantId: TenantId): Promise<TopicObjective | null>;
+    protected abstract put(record: TopicObjective): Promise<void>;
+    createObjective(params: CreateObjectiveParams, tenantId: TenantId): Promise<TopicObjective>;
+    beginRound(id: string, tenantId: TenantId, opts: {
+        revision: number;
+    }): Promise<TopicObjective>;
+    settleRound(id: string, tenantId: TenantId, verdict: ObjectiveRoundVerdict, opts: {
+        revision: number;
+    }): Promise<TopicObjective>;
+    setPhase(id: string, tenantId: TenantId, phase: ObjectivePhase, opts: {
+        revision: number;
+    }): Promise<TopicObjective>;
+}
+export declare class InMemoryTopicObjectiveStore extends ObjectiveStoreBase {
+    private readonly objectives;
+    constructor(now?: () => number);
+    getObjective(id: string, tenantId: TenantId): Promise<TopicObjective | null>;
+    protected put(record: TopicObjective): Promise<void>;
+}
+export interface DiskTopicObjectiveStoreConfig {
+    /** The session root. Objectives live under `<rootDir>/objectives/`. */
+    readonly rootDir: string;
+}
+export declare class DiskTopicObjectiveStore extends ObjectiveStoreBase {
+    private readonly config;
+    constructor(config: DiskTopicObjectiveStoreConfig, now?: () => number);
+    private path;
+    getObjective(id: string, tenantId: TenantId): Promise<TopicObjective | null>;
+    protected put(record: TopicObjective): Promise<void>;
+}
+export {};
+//# sourceMappingURL=objective.d.ts.map

package/dist/store/topic/objective.d.ts.map

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

package/dist/store/topic/objective.js

@@ -0,0 +1,195 @@
+import { mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { StaleObjectiveError, } from '../../types/topic/objective.js';
+import { DiskRecordStore } from '../kv/record-store.js';
+import { defineSchema } from '../schema.js';
+/**
+ * Where an objective lives between runs.
+ *
+ * Beside `TopicStateStore` rather than inside it, for the reason that store
+ * gives for living beside the Topic: permission mode and the next-run queue
+ * change several times inside one conversation, and an objective's phase
+ * changes once per round. Sharing a `revision` would make a round
+ * completing conflict with a mode toggle — two facts about one topic that
+ * have nothing to say to each other.
+ */
+const SCHEMA = defineSchema({ kind: 'topic-objective', current: 1, migrations: {} });
+const records = new DiskRecordStore(SCHEMA);
+/** A round asked for beyond the cap. */
+export class ObjectiveExhaustedError extends Error {
+    details;
+    constructor(details) {
+        super(`Objective ${details.id} has used all ${details.maxRounds} of its rounds.`);
+        this.name = 'ObjectiveExhaustedError';
+        this.details = details;
+    }
+}
+/** An id that already exists. */
+export class ObjectiveExistsError extends Error {
+    details;
+    constructor(details) {
+        super(`Objective ${details.id} already exists.`);
+        this.name = 'ObjectiveExistsError';
+        this.details = details;
+    }
+}
+function assertFresh(id, existing, revision) {
+    if (revision !== existing.revision) {
+        throw new StaleObjectiveError({
+            id,
+            expectedRevision: revision,
+            actualRevision: existing.revision,
+        });
+    }
+}
+function missing(id) {
+    return new Error(`No objective ${id}.`);
+}
+/**
+ * The shared write logic.
+ *
+ * Both implementations differ only in where the record lands, so the rules
+ * — what a round costs, when the cap bites, which phases accept a write —
+ * are written once. Two copies of a compare-and-set is two chances to have
+ * one of them drift, and the drift would be invisible until a host used the
+ * other implementation.
+ */
+class ObjectiveStoreBase {
+    now;
+    constructor(now) {
+        this.now = now;
+    }
+    async createObjective(params, tenantId) {
+        if (await this.getObjective(params.id, tenantId)) {
+            throw new ObjectiveExistsError({ id: params.id });
+        }
+        if (params.maxRounds < 1) {
+            // A cap of zero is an objective that can never run. Accepting it
+            // would produce a record that blocks on its own first round, which
+            // reads as a runaway that was stopped rather than a caller mistake.
+            throw new Error(`maxRounds must be at least 1, got ${params.maxRounds}.`);
+        }
+        const record = {
+            id: params.id,
+            topicId: params.topicId,
+            tenantId,
+            revision: 1,
+            objective: params.objective,
+            phase: 'active',
+            maxRounds: params.maxRounds,
+            roundsStarted: 0,
+            updatedAt: this.now(),
+        };
+        await this.put(record);
+        return record;
+    }
+    async beginRound(id, tenantId, opts) {
+        const existing = await this.getObjective(id, tenantId);
+        if (!existing)
+            throw missing(id);
+        assertFresh(id, existing, opts.revision);
+        if (existing.phase !== 'active') {
+            throw new Error(`Objective ${id} is ${existing.phase}, not active.`);
+        }
+        if (existing.roundsStarted >= existing.maxRounds) {
+            // Blocked BEFORE the throw. A caller that swallows this error, or a
+            // process that dies on it, must not leave a record that still says
+            // `active` — the next reader would start the round this refused.
+            await this.put({
+                ...existing,
+                revision: existing.revision + 1,
+                phase: 'blocked',
+                blockedReason: {
+                    code: 'round_cap',
+                    message: `Reached the ${existing.maxRounds}-round cap.`,
+                },
+                updatedAt: this.now(),
+            });
+            throw new ObjectiveExhaustedError({ id, maxRounds: existing.maxRounds });
+        }
+        const record = {
+            ...existing,
+            revision: existing.revision + 1,
+            roundsStarted: existing.roundsStarted + 1,
+            updatedAt: this.now(),
+        };
+        await this.put(record);
+        return record;
+    }
+    async settleRound(id, tenantId, verdict, opts) {
+        const existing = await this.getObjective(id, tenantId);
+        if (!existing)
+            throw missing(id);
+        assertFresh(id, existing, opts.revision);
+        const record = {
+            ...existing,
+            revision: existing.revision + 1,
+            phase: verdict.phase ?? existing.phase,
+            ...(verdict.blockedReason ? { blockedReason: verdict.blockedReason } : {}),
+            ...(verdict.runId ? { lastRunId: verdict.runId } : {}),
+            updatedAt: this.now(),
+        };
+        await this.put(record);
+        return record;
+    }
+    async setPhase(id, tenantId, phase, opts) {
+        const existing = await this.getObjective(id, tenantId);
+        if (!existing)
+            throw missing(id);
+        assertFresh(id, existing, opts.revision);
+        if (existing.phase === 'complete' && phase !== 'complete') {
+            // One-way. Reopening a finished objective by writing a phase would
+            // let a stale caller restart work somebody already signed off, and
+            // the round counter it would run against is the one already spent.
+            throw new Error(`Objective ${id} is complete; it cannot be moved to ${phase}.`);
+        }
+        // A move off `blocked` drops the reason. Carrying it would describe a
+        // running objective as blocked by something it no longer is, and that
+        // stale sentence is what an operator reads to decide whether to
+        // intervene.
+        const { blockedReason, ...rest } = existing;
+        const record = {
+            ...rest,
+            revision: existing.revision + 1,
+            phase,
+            ...(phase === 'blocked' && blockedReason ? { blockedReason } : {}),
+            updatedAt: this.now(),
+        };
+        await this.put(record);
+        return record;
+    }
+}
+export class InMemoryTopicObjectiveStore extends ObjectiveStoreBase {
+    objectives = new Map();
+    constructor(now = Date.now) {
+        super(now);
+    }
+    async getObjective(id, tenantId) {
+        const found = this.objectives.get(id);
+        // Another tenant's record reads as absent rather than as an error, for
+        // the reason the project listing gives: refusing confirms it is there.
+        return found && found.tenantId === tenantId ? found : null;
+    }
+    async put(record) {
+        this.objectives.set(record.id, record);
+    }
+}
+export class DiskTopicObjectiveStore extends ObjectiveStoreBase {
+    config;
+    constructor(config, now = Date.now) {
+        super(now);
+        this.config = config;
+    }
+    path(id) {
+        return join(this.config.rootDir, 'objectives', `${id}.json`);
+    }
+    async getObjective(id, tenantId) {
+        const found = await records.read(this.path(id));
+        return found && found.tenantId === tenantId ? found : null;
+    }
+    async put(record) {
+        await mkdir(join(this.config.rootDir, 'objectives'), { recursive: true });
+        await records.write(this.path(record.id), record);
+    }
+}
+//# sourceMappingURL=objective.js.map

package/dist/store/topic/objective.js.map

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

package/dist/store/topic/state.d.ts

@@ -0,0 +1,60 @@
+import type { TenantId, TopicId } from '../../types/ids/index.js';
+import type { Message } from '../../types/message/index.js';
+import type { PermissionMode } from '../../types/permission/index.js';
+import { type TopicState } from '../../types/topic/state.js';
+export interface TopicStateStore {
+    /** `null` when this topic has never had state written. */
+    getState(topicId: TopicId, tenantId: TenantId): Promise<TopicState | null>;
+    /**
+     * Compare-and-set on `revision`, `0` for a first write.
+     *
+     * Rejects a stale revision the way `updateTopic` rejects a stale
+     * `ownerVersion`. Two hosts toggling one conversation's mode is not
+     * hypothetical — a TUI and a webhook on the same topic — and
+     * last-write-wins there silently reopens a mode somebody just closed.
+     */
+    setPermissionMode(topicId: TopicId, tenantId: TenantId, mode: PermissionMode, opts: {
+        readonly revision: number;
+    }): Promise<TopicState>;
+    /**
+     * Replace the next-run queue, under the same compare-and-set.
+     *
+     * Replace rather than append, so the caller that read the list is the
+     * one that decides what the new one is — an append primitive would let
+     * a caller add to a list it had never seen.
+     */
+    setQueuedMessages(topicId: TopicId, tenantId: TenantId, messages: readonly Message[], opts: {
+        readonly revision: number;
+    }): Promise<TopicState>;
+}
+export declare class InMemoryTopicStateStore implements TopicStateStore {
+    private readonly now;
+    private readonly states;
+    constructor(now?: () => number);
+    getState(topicId: TopicId, tenantId: TenantId): Promise<TopicState | null>;
+    setPermissionMode(topicId: TopicId, tenantId: TenantId, mode: PermissionMode, opts: {
+        revision: number;
+    }): Promise<TopicState>;
+    setQueuedMessages(topicId: TopicId, tenantId: TenantId, messages: readonly Message[], opts: {
+        revision: number;
+    }): Promise<TopicState>;
+}
+export interface DiskTopicStateStoreConfig {
+    /** The session root. State lives under `<rootDir>/topic-state/`. */
+    readonly rootDir: string;
+}
+export declare class DiskTopicStateStore implements TopicStateStore {
+    private readonly config;
+    private readonly now;
+    constructor(config: DiskTopicStateStoreConfig, now?: () => number);
+    private path;
+    getState(topicId: TopicId, tenantId: TenantId): Promise<TopicState | null>;
+    setPermissionMode(topicId: TopicId, tenantId: TenantId, mode: PermissionMode, opts: {
+        revision: number;
+    }): Promise<TopicState>;
+    setQueuedMessages(topicId: TopicId, tenantId: TenantId, messages: readonly Message[], opts: {
+        revision: number;
+    }): Promise<TopicState>;
+    private persist;
+}
+//# sourceMappingURL=state.d.ts.map

package/dist/store/topic/state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../../src/store/topic/state.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAA;AACjE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,8BAA8B,CAAA;AAC3D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAA;AACrE,OAAO,EAAwB,KAAK,UAAU,EAAE,MAAM,4BAA4B,CAAA;AAwBlF,MAAM,WAAW,eAAe;IAC/B,0DAA0D;IAC1D,QAAQ,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAA;IAC1E;;;;;;;OAOG;IACH,iBAAiB,CAChB,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,cAAc,EACpB,IAAI,EAAE;QAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,GACjC,OAAO,CAAC,UAAU,CAAC,CAAA;IAEtB;;;;;;OAMG;IACH,iBAAiB,CAChB,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,QAAQ,EAClB,QAAQ,EAAE,SAAS,OAAO,EAAE,EAC5B,IAAI,EAAE;QAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,GACjC,OAAO,CAAC,UAAU,CAAC,CAAA;CACtB;AAwBD,qBAAa,uBAAwB,YAAW,eAAe;IAGlD,OAAO,CAAC,QAAQ,CAAC,GAAG;IAFhC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiC;gBAE3B,GAAG,GAAE,MAAM,MAAiB;IAEnD,QAAQ,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAQ1E,iBAAiB,CACtB,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,cAAc,EACpB,IAAI,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,GACxB,OAAO,CAAC,UAAU,CAAC;IAehB,iBAAiB,CACtB,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,QAAQ,EAClB,QAAQ,EAAE,SAAS,OAAO,EAAE,EAC5B,IAAI,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,GACxB,OAAO,CAAC,UAAU,CAAC;CActB;AAED,MAAM,WAAW,yBAAyB;IACzC,oEAAoE;IACpE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACxB;AAED,qBAAa,mBAAoB,YAAW,eAAe;IAEzD,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,GAAG;gBADH,MAAM,EAAE,yBAAyB,EACjC,GAAG,GAAE,MAAM,MAAiB;IAG9C,OAAO,CAAC,IAAI;IAIN,QAAQ,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAK1E,iBAAiB,CACtB,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,cAAc,EACpB,IAAI,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,GACxB,OAAO,CAAC,UAAU,CAAC;IAehB,iBAAiB,CACtB,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,QAAQ,EAClB,QAAQ,EAAE,SAAS,OAAO,EAAE,EAC5B,IAAI,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,GACxB,OAAO,CAAC,UAAU,CAAC;YAeR,OAAO;CAIrB"}

package/dist/store/topic/state.js

@@ -0,0 +1,128 @@
+import { mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { StaleTopicStateError } from '../../types/topic/state.js';
+import { DiskRecordStore } from '../kv/record-store.js';
+import { defineSchema } from '../schema.js';
+/**
+ * Where a conversation's mutable state lives between runs.
+ *
+ * Its own store rather than a field on the Topic record, and its own file
+ * rather than a column: the Topic is identity and ownership, this is
+ * session state that changes several times inside one conversation. Merging
+ * them would make every mode toggle a compare-and-set conflict against a
+ * title rename.
+ *
+ * A separate store rather than an extension of `TopicStore` because there
+ * is no disk `TopicStore` to extend — topics are in-memory everywhere in
+ * this tree today. Persisting the state on its own is what the durability
+ * this exists for actually needs; building a whole topic disk store to
+ * carry one field would be a much larger change nobody asked for, and this
+ * record is designed to be folded into one if that arrives.
+ */
+const SCHEMA = defineSchema({ kind: 'topic-state', current: 1, migrations: {} });
+const records = new DiskRecordStore(SCHEMA);
+/** The record after one accepted write. */
+function next(topicId, tenantId, previous, patch, now) {
+    return {
+        topicId,
+        tenantId,
+        revision: (previous?.revision ?? 0) + 1,
+        permissionMode: patch.permissionMode ?? previous?.permissionMode ?? 'auto',
+        ...(patch.queuedMessages !== undefined
+            ? { queuedMessages: patch.queuedMessages }
+            : previous?.queuedMessages
+                ? { queuedMessages: previous.queuedMessages }
+                : {}),
+        updatedAt: now,
+    };
+}
+export class InMemoryTopicStateStore {
+    now;
+    states = new Map();
+    constructor(now = Date.now) {
+        this.now = now;
+    }
+    async getState(topicId, tenantId) {
+        const found = this.states.get(topicId);
+        // A record from another tenant reads as absent rather than as an
+        // error, for the reason the project listing gives: refusing would
+        // confirm that somebody else's topic is there.
+        return found && found.tenantId === tenantId ? found : null;
+    }
+    async setPermissionMode(topicId, tenantId, mode, opts) {
+        const existing = await this.getState(topicId, tenantId);
+        const actual = existing?.revision ?? 0;
+        if (opts.revision !== actual) {
+            throw new StaleTopicStateError({
+                topicId,
+                expectedRevision: opts.revision,
+                actualRevision: actual,
+            });
+        }
+        const record = next(topicId, tenantId, existing, { permissionMode: mode }, this.now());
+        this.states.set(topicId, record);
+        return record;
+    }
+    async setQueuedMessages(topicId, tenantId, messages, opts) {
+        const existing = await this.getState(topicId, tenantId);
+        const actual = existing?.revision ?? 0;
+        if (opts.revision !== actual) {
+            throw new StaleTopicStateError({
+                topicId,
+                expectedRevision: opts.revision,
+                actualRevision: actual,
+            });
+        }
+        const record = next(topicId, tenantId, existing, { queuedMessages: messages }, this.now());
+        this.states.set(topicId, record);
+        return record;
+    }
+}
+export class DiskTopicStateStore {
+    config;
+    now;
+    constructor(config, now = Date.now) {
+        this.config = config;
+        this.now = now;
+    }
+    path(topicId) {
+        return join(this.config.rootDir, 'topic-state', `${topicId}.json`);
+    }
+    async getState(topicId, tenantId) {
+        const found = await records.read(this.path(topicId));
+        return found && found.tenantId === tenantId ? found : null;
+    }
+    async setPermissionMode(topicId, tenantId, mode, opts) {
+        const existing = await this.getState(topicId, tenantId);
+        const actual = existing?.revision ?? 0;
+        if (opts.revision !== actual) {
+            throw new StaleTopicStateError({
+                topicId,
+                expectedRevision: opts.revision,
+                actualRevision: actual,
+            });
+        }
+        const record = next(topicId, tenantId, existing, { permissionMode: mode }, this.now());
+        await this.persist(record);
+        return record;
+    }
+    async setQueuedMessages(topicId, tenantId, messages, opts) {
+        const existing = await this.getState(topicId, tenantId);
+        const actual = existing?.revision ?? 0;
+        if (opts.revision !== actual) {
+            throw new StaleTopicStateError({
+                topicId,
+                expectedRevision: opts.revision,
+                actualRevision: actual,
+            });
+        }
+        const record = next(topicId, tenantId, existing, { queuedMessages: messages }, this.now());
+        await this.persist(record);
+        return record;
+    }
+    async persist(record) {
+        await mkdir(join(this.config.rootDir, 'topic-state'), { recursive: true });
+        await records.write(this.path(record.topicId), record);
+    }
+}
+//# sourceMappingURL=state.js.map

package/dist/store/topic/state.js.map

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

package/dist/streaming/coalesce.d.ts

@@ -1,5 +1,10 @@
 import type { RunEvent } from '../types/run/events.js';
-interface CoalesceOptions {
+export interface CoalesceOptions {
+    /**
+     * Sliding merge window. 16ms is roughly one animation frame at 60fps,
+     * which is the point past which a human cannot see the difference and
+     * below which the consumer pays for deltas nobody perceives.
+     */
     windowMs: number;
 }
 /**
@@ -13,10 +18,19 @@ interface CoalesceOptions {
  * All other event types pass through immediately and flush any buffered
  * deltas first to preserve ordering.
  *
- * The orchestrator does NOT use this — it emits raw deltas. SSE adapters
- * and other slow consumers opt in. A 16ms window roughly aligns with one
- * UI animation frame at 60fps, which is the empirically derived default
- * for a live stream route.
+ * The orchestrator does NOT use this — it emits raw deltas, and nothing
+ * inside the kernel calls this function. That is deliberate and is why it
+ * is exported: the consumer this exists for is a host's HTTP route, and a
+ * kernel with no UI and no hosted service has no in-process caller to
+ * offer. `bridge/sse/` maps an event to the wire; deciding how OFTEN to
+ * write to a slow client is the host's policy, because only the host
+ * knows what is on the other end of its socket.
+ *
+ * `streaming/` owns coalescing and nothing else. SSE mapping lives in
+ * `bridge/sse/`, provider chunk assembly in the provider drivers, and the
+ * run event stream in `runtime/query/` — none of them belong here, and a
+ * second occupant of this directory should be another rate policy or
+ * nothing.
  *
  * Backpressure semantics: this helper does not drop events. If the
  * upstream produces faster than the consumer drains, the helper still
@@ -24,5 +38,4 @@ interface CoalesceOptions {
  * accept queue growth.
  */
 export declare function coalesce(stream: AsyncIterable<RunEvent>, options?: CoalesceOptions): AsyncGenerator<RunEvent, void, unknown>;
-export {};
 //# sourceMappingURL=coalesce.d.ts.map

package/dist/streaming/coalesce.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"coalesce.d.ts","sourceRoot":"","sources":["../../src/streaming/coalesce.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAA;AAEtD,UAAU,eAAe;IACxB,QAAQ,EAAE,MAAM,CAAA;CAChB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAuB,QAAQ,CAC9B,MAAM,EAAE,aAAa,CAAC,QAAQ,CAAC,EAC/B,OAAO,GAAE,eAAkC,GACzC,cAAc,CAAC,QAAQ,EAAE,IAAI,EAAE,OAAO,CAAC,CAyDzC"}
+{"version":3,"file":"coalesce.d.ts","sourceRoot":"","sources":["../../src/streaming/coalesce.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAA;AAEtD,MAAM,WAAW,eAAe;IAC/B;;;;OAIG;IACH,QAAQ,EAAE,MAAM,CAAA;CAChB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAuB,QAAQ,CAC9B,MAAM,EAAE,aAAa,CAAC,QAAQ,CAAC,EAC/B,OAAO,GAAE,eAAkC,GACzC,cAAc,CAAC,QAAQ,EAAE,IAAI,EAAE,OAAO,CAAC,CAyDzC"}

package/dist/streaming/coalesce.js

@@ -9,10 +9,19 @@
  * All other event types pass through immediately and flush any buffered
  * deltas first to preserve ordering.
  *
- * The orchestrator does NOT use this — it emits raw deltas. SSE adapters
- * and other slow consumers opt in. A 16ms window roughly aligns with one
- * UI animation frame at 60fps, which is the empirically derived default
- * for a live stream route.
+ * The orchestrator does NOT use this — it emits raw deltas, and nothing
+ * inside the kernel calls this function. That is deliberate and is why it
+ * is exported: the consumer this exists for is a host's HTTP route, and a
+ * kernel with no UI and no hosted service has no in-process caller to
+ * offer. `bridge/sse/` maps an event to the wire; deciding how OFTEN to
+ * write to a slow client is the host's policy, because only the host
+ * knows what is on the other end of its socket.
+ *
+ * `streaming/` owns coalescing and nothing else. SSE mapping lives in
+ * `bridge/sse/`, provider chunk assembly in the provider drivers, and the
+ * run event stream in `runtime/query/` — none of them belong here, and a
+ * second occupant of this directory should be another rate policy or
+ * nothing.
  *
  * Backpressure semantics: this helper does not drop events. If the
  * upstream produces faster than the consumer drains, the helper still

package/dist/streaming/coalesce.js.map

@@ -1 +1 @@
-{"version":3,"file":"coalesce.js","sourceRoot":"","sources":["../../src/streaming/coalesce.ts"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,KAAK,SAAS,CAAC,CAAC,QAAQ,CAC9B,MAA+B,EAC/B,UAA2B,EAAE,QAAQ,EAAE,EAAE,EAAE;IAE3C,MAAM,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAA;IAC5B,IAAI,OAAO,GAAkF,IAAI,CAAA;IACjG,MAAM,QAAQ,GAAG,IAAI,GAAG,EAGrB,CAAA;IAEH,QAAQ,CAAC,CAAC,QAAQ;QACjB,IAAI,OAAO,EAAE,CAAC;YACb,MAAM,OAAO,CAAC,KAAK,CAAA;YACnB,OAAO,GAAG,IAAI,CAAA;QACf,CAAC;QACD,KAAK,MAAM,GAAG,IAAI,QAAQ,CAAC,MAAM,EAAE,EAAE,CAAC;YACrC,MAAM,GAAG,CAAC,KAAK,CAAA;QAChB,CAAC;QACD,QAAQ,CAAC,KAAK,EAAE,CAAA;IACjB,CAAC;IAED,MAAM,GAAG,GAAG,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,CAAA;IAE5B,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAClC,IAAI,KAAK,CAAC,IAAI,KAAK,YAAY,EAAE,CAAC;YACjC,IAAI,OAAO,IAAI,OAAO,CAAC,KAAK,CAAC,SAAS,KAAK,KAAK,CAAC,SAAS,IAAI,OAAO,CAAC,QAAQ,GAAG,GAAG,EAAE,EAAE,CAAC;gBACxF,OAAO,CAAC,KAAK,GAAG;oBACf,GAAG,OAAO,CAAC,KAAK;oBAChB,IAAI,EAAE,OAAO,CAAC,KAAK,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI;iBACrC,CAAA;YACF,CAAC;iBAAM,CAAC;gBACP,IAAI,OAAO;oBAAE,MAAM,OAAO,CAAC,KAAK,CAAA;gBAChC,OAAO,GAAG,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,EAAE,GAAG,QAAQ,EAAE,CAAA;YAChD,CAAC;YACD,SAAQ;QACT,CAAC;QAED,IAAI,KAAK,CAAC,IAAI,KAAK,kBAAkB,EAAE,CAAC;YACvC,MAAM,QAAQ,GAAG,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC,CAAA;YAC9C,IAAI,QAAQ,IAAI,QAAQ,CAAC,QAAQ,GAAG,GAAG,EAAE,EAAE,CAAC;gBAC3C,QAAQ,CAAC,KAAK,GAAG;oBAChB,GAAG,QAAQ,CAAC,KAAK;oBACjB,WAAW,EAAE,QAAQ,CAAC,KAAK,CAAC,WAAW,GAAG,KAAK,CAAC,WAAW;iBAC3D,CAAA;YACF,CAAC;iBAAM,CAAC;gBACP,IAAI,QAAQ;oBAAE,MAAM,QAAQ,CAAC,KAAK,CAAA;gBAClC,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,SAAS,EAAE;oBAC7B,KAAK;oBACL,QAAQ,EAAE,GAAG,EAAE,GAAG,QAAQ;iBAC1B,CAAC,CAAA;YACH,CAAC;YACD,SAAQ;QACT,CAAC;QAED,KAAK,CAAC,CAAC,QAAQ,EAAE,CAAA;QACjB,MAAM,KAAK,CAAA;IACZ,CAAC;IAED,KAAK,CAAC,CAAC,QAAQ,EAAE,CAAA;AAClB,CAAC"}
+{"version":3,"file":"coalesce.js","sourceRoot":"","sources":["../../src/streaming/coalesce.ts"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,CAAC,KAAK,SAAS,CAAC,CAAC,QAAQ,CAC9B,MAA+B,EAC/B,UAA2B,EAAE,QAAQ,EAAE,EAAE,EAAE;IAE3C,MAAM,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAA;IAC5B,IAAI,OAAO,GAAkF,IAAI,CAAA;IACjG,MAAM,QAAQ,GAAG,IAAI,GAAG,EAGrB,CAAA;IAEH,QAAQ,CAAC,CAAC,QAAQ;QACjB,IAAI,OAAO,EAAE,CAAC;YACb,MAAM,OAAO,CAAC,KAAK,CAAA;YACnB,OAAO,GAAG,IAAI,CAAA;QACf,CAAC;QACD,KAAK,MAAM,GAAG,IAAI,QAAQ,CAAC,MAAM,EAAE,EAAE,CAAC;YACrC,MAAM,GAAG,CAAC,KAAK,CAAA;QAChB,CAAC;QACD,QAAQ,CAAC,KAAK,EAAE,CAAA;IACjB,CAAC;IAED,MAAM,GAAG,GAAG,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,CAAA;IAE5B,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAClC,IAAI,KAAK,CAAC,IAAI,KAAK,YAAY,EAAE,CAAC;YACjC,IAAI,OAAO,IAAI,OAAO,CAAC,KAAK,CAAC,SAAS,KAAK,KAAK,CAAC,SAAS,IAAI,OAAO,CAAC,QAAQ,GAAG,GAAG,EAAE,EAAE,CAAC;gBACxF,OAAO,CAAC,KAAK,GAAG;oBACf,GAAG,OAAO,CAAC,KAAK;oBAChB,IAAI,EAAE,OAAO,CAAC,KAAK,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI;iBACrC,CAAA;YACF,CAAC;iBAAM,CAAC;gBACP,IAAI,OAAO;oBAAE,MAAM,OAAO,CAAC,KAAK,CAAA;gBAChC,OAAO,GAAG,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,EAAE,GAAG,QAAQ,EAAE,CAAA;YAChD,CAAC;YACD,SAAQ;QACT,CAAC;QAED,IAAI,KAAK,CAAC,IAAI,KAAK,kBAAkB,EAAE,CAAC;YACvC,MAAM,QAAQ,GAAG,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC,CAAA;YAC9C,IAAI,QAAQ,IAAI,QAAQ,CAAC,QAAQ,GAAG,GAAG,EAAE,EAAE,CAAC;gBAC3C,QAAQ,CAAC,KAAK,GAAG;oBAChB,GAAG,QAAQ,CAAC,KAAK;oBACjB,WAAW,EAAE,QAAQ,CAAC,KAAK,CAAC,WAAW,GAAG,KAAK,CAAC,WAAW;iBAC3D,CAAA;YACF,CAAC;iBAAM,CAAC;gBACP,IAAI,QAAQ;oBAAE,MAAM,QAAQ,CAAC,KAAK,CAAA;gBAClC,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,SAAS,EAAE;oBAC7B,KAAK;oBACL,QAAQ,EAAE,GAAG,EAAE,GAAG,QAAQ;iBAC1B,CAAC,CAAA;YACH,CAAC;YACD,SAAQ;QACT,CAAC;QAED,KAAK,CAAC,CAAC,QAAQ,EAAE,CAAA;QACjB,MAAM,KAAK,CAAA;IACZ,CAAC;IAED,KAAK,CAAC,CAAC,QAAQ,EAAE,CAAA;AAClB,CAAC"}

package/dist/telemetry/runtime-accessors.d.ts

@@ -1,3 +1,29 @@
-import { type Tracer } from '@opentelemetry/api';
+import { type SpanContext, type Tracer } from '@opentelemetry/api';
 export declare function getTracer(): Tracer;
+/**
+ * The active span's context, read fresh on every call — nothing here is
+ * ever cached. `utils/log/create-logger.ts`'s `emit` calls this once per
+ * ACCEPTED record (after the level check, never before) so a logger built
+ * before any tracer provider registers still picks up spans started after
+ * registration. Caching this at logger construction would repeat the exact
+ * mistake `telemetry/metrics.ts` documents for a meter: a bag that
+ * captured the no-op instance once stayed no-op for the rest of the
+ * process even after a real provider registered later.
+ *
+ * `undefined` whenever nothing is active — the DEFAULT, not an edge case
+ * this function has to detect. `@opentelemetry/api` ships a
+ * `NoopContextManager` until something registers a real one
+ * (`@namzu/telemetry`'s `registerTelemetry` does, via
+ * `NodeTracerProvider.register()`), and that default's `active()`
+ * unconditionally returns `ROOT_CONTEXT` — it does not even remember what a
+ * caller set with `context.with()`. So a host that never configures
+ * telemetry gets `undefined` here on every call, for free, with nothing in
+ * this function special-casing "telemetry not configured": that behaviour
+ * is the api's own default, not a check performed here. Which is also why
+ * this can only ever ADD information to a record — reading the active
+ * context can never make an unconfigured host fail a check that would
+ * otherwise pass (`an-optional-dependency-may-not-degrade-a-check`, in
+ * reverse).
+ */
+export declare function getActiveSpanContext(): SpanContext | undefined;
 //# sourceMappingURL=runtime-accessors.d.ts.map

package/dist/telemetry/runtime-accessors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime-accessors.d.ts","sourceRoot":"","sources":["../../src/telemetry/runtime-accessors.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,KAAK,MAAM,EAAS,MAAM,oBAAoB,CAAA;AAEvD,wBAAgB,SAAS,IAAI,MAAM,CAElC"}
+{"version":3,"file":"runtime-accessors.d.ts","sourceRoot":"","sources":["../../src/telemetry/runtime-accessors.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,MAAM,EAAkB,MAAM,oBAAoB,CAAA;AAElF,wBAAgB,SAAS,IAAI,MAAM,CAElC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,oBAAoB,IAAI,WAAW,GAAG,SAAS,CAiB9D"}