@namzu/sdk 0.1.8 → 0.3.0

package/dist/session/handoff/__tests__/capacity.test.js

@@ -0,0 +1,103 @@
+import { describe, expect, it } from 'vitest';
+import { InMemorySessionStore } from '../../../store/session/memory.js';
+import { InMemoryThreadStore } from '../../../store/thread/memory.js';
+import { DefaultCapacityValidator, DelegationCapacityExceeded } from '../capacity.js';
+const tenant = 'tnt_alpha';
+function user() {
+    return { kind: 'user', userId: 'usr_a', tenantId: tenant };
+}
+function agent() {
+    return { kind: 'agent', agentId: 'agt_a', tenantId: tenant };
+}
+async function seedProject(store) {
+    const project = await store.createProject({ tenantId: tenant, name: 'p' }, tenant);
+    const threadStore = new InMemoryThreadStore();
+    const thread = await threadStore.createThread({ projectId: project.id, title: 'default' }, tenant);
+    const root = await store.createSession({ threadId: thread.id, projectId: project.id, currentActor: user() }, tenant);
+    return { project, thread, root };
+}
+async function spawnChild(store, parentId, projectId, threadId) {
+    const child = await store.createSession({ threadId, projectId, currentActor: user() }, tenant);
+    await store.createSubSession({
+        parentSessionId: parentId,
+        childSessionId: child.id,
+        kind: 'agent_spawn',
+        spawnedBy: agent(),
+    }, tenant);
+    return { childId: child.id };
+}
+describe('DefaultCapacityValidator', () => {
+    it('depth: root session validates against limit 4 (new child would be depth 1) — passes', async () => {
+        const store = new InMemorySessionStore();
+        const { root } = await seedProject(store);
+        const validator = new DefaultCapacityValidator(store);
+        await expect(validator.validateDepth(root.id, 4, tenant)).resolves.toBeUndefined();
+    });
+    it('depth: chain of 4 (root→c1→c2→c3→c4) allows a 5th (depth 5) to pass when limit = 5', async () => {
+        const store = new InMemorySessionStore();
+        const { project, thread, root } = await seedProject(store);
+        const c1 = await spawnChild(store, root.id, project.id, thread.id);
+        const c2 = await spawnChild(store, c1.childId, project.id, thread.id);
+        const c3 = await spawnChild(store, c2.childId, project.id, thread.id);
+        const c4 = await spawnChild(store, c3.childId, project.id, thread.id);
+        const validator = new DefaultCapacityValidator(store);
+        // Ancestry of c4: root→c1→c2→c3→c4 = length 5. Spawning under c4 = depth 5.
+        await expect(validator.validateDepth(c4.childId, 5, tenant)).resolves.toBeUndefined();
+    });
+    it('depth: over-limit throws DelegationCapacityExceeded with dimension=depth', async () => {
+        const store = new InMemorySessionStore();
+        const { project, thread, root } = await seedProject(store);
+        const c1 = await spawnChild(store, root.id, project.id, thread.id);
+        const c2 = await spawnChild(store, c1.childId, project.id, thread.id);
+        const c3 = await spawnChild(store, c2.childId, project.id, thread.id);
+        const c4 = await spawnChild(store, c3.childId, project.id, thread.id);
+        const validator = new DefaultCapacityValidator(store);
+        try {
+            // Ancestry of c4 has length 5; limit=4 means depth 5 > 4 → reject.
+            await validator.validateDepth(c4.childId, 4, tenant);
+            expect.fail('expected DelegationCapacityExceeded');
+        }
+        catch (err) {
+            expect(err).toBeInstanceOf(DelegationCapacityExceeded);
+            const e = err;
+            expect(e.details.dimension).toBe('depth');
+            expect(e.details.limit).toBe(4);
+            expect(e.details.current).toBe(5);
+        }
+    });
+    it('width: empty parent with 4 pending children passes limit=8', async () => {
+        const store = new InMemorySessionStore();
+        const { root } = await seedProject(store);
+        const validator = new DefaultCapacityValidator(store);
+        await expect(validator.validateWidth(root.id, 4, 8, tenant)).resolves.toBeUndefined();
+    });
+    it('width: existing 5 + pending 3 = 8 passes exactly at the limit', async () => {
+        const store = new InMemorySessionStore();
+        const { project, thread, root } = await seedProject(store);
+        for (let i = 0; i < 5; i++) {
+            await spawnChild(store, root.id, project.id, thread.id);
+        }
+        const validator = new DefaultCapacityValidator(store);
+        await expect(validator.validateWidth(root.id, 3, 8, tenant)).resolves.toBeUndefined();
+    });
+    it('width: existing 6 + pending 3 = 9 exceeds 8, throws dimension=width', async () => {
+        const store = new InMemorySessionStore();
+        const { project, thread, root } = await seedProject(store);
+        for (let i = 0; i < 6; i++) {
+            await spawnChild(store, root.id, project.id, thread.id);
+        }
+        const validator = new DefaultCapacityValidator(store);
+        try {
+            await validator.validateWidth(root.id, 3, 8, tenant);
+            expect.fail('expected DelegationCapacityExceeded');
+        }
+        catch (err) {
+            expect(err).toBeInstanceOf(DelegationCapacityExceeded);
+            const e = err;
+            expect(e.details.dimension).toBe('width');
+            expect(e.details.current).toBe(9);
+            expect(e.details.limit).toBe(8);
+        }
+    });
+});
+//# sourceMappingURL=capacity.test.js.map

package/dist/session/handoff/__tests__/capacity.test.js.map

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

package/dist/session/handoff/__tests__/single.test.d.ts

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

package/dist/session/handoff/__tests__/single.test.d.ts.map

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

package/dist/session/handoff/__tests__/single.test.js

@@ -0,0 +1,239 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { ThreadManager } from '../../../manager/thread/lifecycle.js';
+import { TenantIsolationError } from '../../../session/errors.js';
+import { GitWorktreeDriver, } from '../../../session/workspace/git-worktree.js';
+import { WorkspaceBackendRegistry } from '../../../session/workspace/registry.js';
+import { InMemorySessionStore } from '../../../store/session/memory.js';
+import { InMemoryThreadStore } from '../../../store/thread/memory.js';
+import { generateHandoffId } from '../../../utils/id.js';
+import { DefaultCapacityValidator } from '../capacity.js';
+import { DelegationCapacityExceeded } from '../capacity.js';
+import { executeSingleHandoff } from '../single.js';
+import { HandoffLockRejected, HandoffVersionConflict } from '../version.js';
+const tenant = 'tnt_alpha';
+const otherTenant = 'tnt_beta';
+function stubLogger() {
+    return {
+        debug: vi.fn(),
+        info: vi.fn(),
+        warn: vi.fn(),
+        error: vi.fn(),
+        child() {
+            return stubLogger();
+        },
+    };
+}
+function okExec(stdout = '', stderr = '') {
+    return { stdout, stderr };
+}
+function user(kind = 'usr_a') {
+    return { kind: 'user', userId: kind, tenantId: tenant };
+}
+function agent() {
+    return { kind: 'agent', agentId: 'agt_a', tenantId: tenant };
+}
+function buildDeps(store, threadStore, execOverride, runResolver) {
+    const execCalls = [];
+    const exec = execOverride
+        ? execOverride
+        : async (_file, args) => {
+            execCalls.push(args.join(' '));
+            return okExec();
+        };
+    const driver = new GitWorktreeDriver({
+        repoRoot: '/repo',
+        logger: stubLogger(),
+        execFile: exec,
+    });
+    const registry = new WorkspaceBackendRegistry();
+    registry.register(driver);
+    const events = {
+        onLocked: vi.fn(),
+        onUnlocked: vi.fn(),
+        onCommitted: vi.fn(),
+        onBroadcastRollback: vi.fn(),
+    };
+    const threadManager = new ThreadManager({ threadStore, sessionStore: store });
+    const deps = {
+        store,
+        workspaceRegistry: registry,
+        capacity: new DefaultCapacityValidator(store),
+        events,
+        threadManager,
+        ...(runResolver !== undefined && { runStatus: runResolver }),
+    };
+    return { deps, events, execCalls };
+}
+async function seedIdle(store, threadStore) {
+    const project = await store.createProject({ tenantId: tenant, name: 'p' }, tenant);
+    const thread = await threadStore.createThread({ projectId: project.id, title: 'handoff-single-test' }, tenant);
+    const session = await store.createSession({ threadId: thread.id, projectId: project.id, currentActor: user('usr_source') }, tenant);
+    return { project, thread, session };
+}
+function buildAssignment(sourceSessionId, projectId, threadId, expectedOwnerVersion, recipient = user('usr_target')) {
+    return {
+        id: generateHandoffId(),
+        mode: 'single',
+        sourceSessionId,
+        tenantId: tenant,
+        threadId,
+        projectId,
+        sourceActor: user('usr_source'),
+        recipientActor: recipient,
+        expectedOwnerVersion,
+        createdAt: new Date('2026-02-01'),
+    };
+}
+describe('executeSingleHandoff', () => {
+    let store;
+    let threadStore;
+    beforeEach(() => {
+        store = new InMemorySessionStore();
+        threadStore = new InMemoryThreadStore();
+    });
+    it('happy path: idle source → lock → commit → outcome populated + source mutated', async () => {
+        const { project, thread, session } = await seedIdle(store, threadStore);
+        const { deps, events } = buildDeps(store, threadStore);
+        const assignment = buildAssignment(session.id, project.id, thread.id, 0);
+        const outcome = await executeSingleHandoff(deps, assignment, tenant);
+        expect(outcome.assignmentId).toBe(assignment.id);
+        expect(outcome.workspaceId.startsWith('wsp_')).toBe(true);
+        expect(outcome.newSessionId.startsWith('ses_')).toBe(true);
+        expect(outcome.committedOwnerVersion).toBe(1);
+        const reloaded = await store.getSession(session.id, tenant);
+        expect(reloaded?.status).toBe('idle');
+        expect(reloaded?.ownerVersion).toBe(1);
+        expect(reloaded?.previousActors).toHaveLength(1);
+        expect(reloaded?.currentActor).toEqual(assignment.recipientActor);
+        // Events fire in order: locked then committed.
+        expect(events.onLocked).toHaveBeenCalledTimes(1);
+        expect(events.onCommitted).toHaveBeenCalledTimes(1);
+        expect(events.onUnlocked).not.toHaveBeenCalled();
+    });
+    it('rejects when source session is non-idle (active → HandoffLockRejected with active_run)', async () => {
+        const { project, thread, session } = await seedIdle(store, threadStore);
+        await store.updateSession({ ...session, status: 'active' }, tenant);
+        const { deps } = buildDeps(store, threadStore);
+        const assignment = buildAssignment(session.id, project.id, thread.id, 0);
+        try {
+            await executeSingleHandoff(deps, assignment, tenant);
+            expect.fail('expected HandoffLockRejected');
+        }
+        catch (err) {
+            expect(err).toBeInstanceOf(HandoffLockRejected);
+            expect(err.details.reason).toBe('active_run');
+        }
+    });
+    it('rejects when Run resolver reports pending_hitl', async () => {
+        const { project, thread, session } = await seedIdle(store, threadStore);
+        const resolver = {
+            async blockingRun() {
+                return { reason: 'pending_hitl' };
+            },
+        };
+        const { deps } = buildDeps(store, threadStore, undefined, resolver);
+        const assignment = buildAssignment(session.id, project.id, thread.id, 0);
+        try {
+            await executeSingleHandoff(deps, assignment, tenant);
+            expect.fail('expected HandoffLockRejected');
+        }
+        catch (err) {
+            expect(err).toBeInstanceOf(HandoffLockRejected);
+            expect(err.details.reason).toBe('pending_hitl');
+        }
+    });
+    it('rejects on tenant mismatch (TenantIsolationError)', async () => {
+        const { project, thread, session } = await seedIdle(store, threadStore);
+        const { deps } = buildDeps(store, threadStore);
+        // Assignment tenant differs from the call-site tenant.
+        const assignment = {
+            ...buildAssignment(session.id, project.id, thread.id, 0),
+            tenantId: otherTenant,
+        };
+        await expect(executeSingleHandoff(deps, assignment, otherTenant)).rejects.toBeInstanceOf(TenantIsolationError);
+    });
+    it('rejects on CAS mismatch (HandoffVersionConflict)', async () => {
+        const { project, thread, session } = await seedIdle(store, threadStore);
+        const { deps } = buildDeps(store, threadStore);
+        // Simulate a concurrent bump: move ownerVersion to 1 before the assignment
+        // with expectedOwnerVersion=0 is executed.
+        await store.updateSession({ ...session, ownerVersion: 1 }, tenant);
+        const assignment = buildAssignment(session.id, project.id, thread.id, 0);
+        try {
+            await executeSingleHandoff(deps, assignment, tenant);
+            expect.fail('expected HandoffVersionConflict');
+        }
+        catch (err) {
+            expect(err).toBeInstanceOf(HandoffVersionConflict);
+            expect(err.details.expected).toBe(0);
+            expect(err.details.actual).toBe(1);
+        }
+    });
+    it('depth cap enforcement rejects with DelegationCapacityExceeded (dimension=depth)', async () => {
+        // Build a chain so the handoff source already sits at max depth.
+        const project = await store.createProject({ tenantId: tenant, name: 'p' }, tenant);
+        const thread = await threadStore.createThread({ projectId: project.id, title: 'depth-cap' }, tenant);
+        // Set a tight limit on the project via a second createProject? — no, the
+        // store hardcodes defaults {4,8,10}. Build a depth-4 chain then attempt
+        // handoff on depth-4 node (ancestry length 5 > 4).
+        const root = await store.createSession({ threadId: thread.id, projectId: project.id, currentActor: user('usr_source') }, tenant);
+        let parent = root.id;
+        let tail = root.id;
+        for (let i = 0; i < 4; i++) {
+            const child = await store.createSession({ threadId: thread.id, projectId: project.id, currentActor: user(`usr_${i}`) }, tenant);
+            await store.createSubSession({
+                parentSessionId: parent,
+                childSessionId: child.id,
+                kind: 'agent_spawn',
+                spawnedBy: agent(),
+            }, tenant);
+            parent = child.id;
+            tail = child.id;
+        }
+        // Source is `tail` at ancestry length 5 → depth-capacity with limit 4 rejects.
+        const { deps } = buildDeps(store, threadStore);
+        const assignment = buildAssignment(tail, project.id, thread.id, 0);
+        await expect(executeSingleHandoff(deps, assignment, tenant)).rejects.toBeInstanceOf(DelegationCapacityExceeded);
+    });
+    it('compensating revert: workspace provisioning failure reverts source to idle, version unchanged, onUnlocked fires', async () => {
+        const { project, thread, session } = await seedIdle(store, threadStore);
+        // Fail only on `worktree add` but pass for everything else. Here we fail
+        // the single worktree add.
+        const exec = async (_file, args) => {
+            if (args.includes('add')) {
+                throw new Error('simulated git worktree add failure');
+            }
+            return okExec();
+        };
+        const { deps, events } = buildDeps(store, threadStore, exec);
+        const assignment = buildAssignment(session.id, project.id, thread.id, 0);
+        await expect(executeSingleHandoff(deps, assignment, tenant)).rejects.toThrow(/Workspace backend git-worktree failed on create/);
+        // Source is back to idle, ownerVersion unchanged.
+        const reloaded = await store.getSession(session.id, tenant);
+        expect(reloaded?.status).toBe('idle');
+        expect(reloaded?.ownerVersion).toBe(0);
+        expect(reloaded?.previousActors).toHaveLength(0);
+        // onLocked fired, then onUnlocked, no onCommitted.
+        expect(events.onLocked).toHaveBeenCalledTimes(1);
+        expect(events.onUnlocked).toHaveBeenCalledTimes(1);
+        expect(events.onCommitted).not.toHaveBeenCalled();
+    });
+    it('compensating revert: store.createSubSession failure still reverts + archives partial recipient', async () => {
+        const { project, thread, session } = await seedIdle(store, threadStore);
+        // Monkey-patch createSubSession on the store to throw.
+        const original = store.createSubSession.bind(store);
+        store.createSubSession = async () => {
+            throw new Error('simulated createSubSession failure');
+        };
+        const { deps, events } = buildDeps(store, threadStore);
+        const assignment = buildAssignment(session.id, project.id, thread.id, 0);
+        await expect(executeSingleHandoff(deps, assignment, tenant)).rejects.toThrow(/createSubSession failure/);
+        // Restore for subsequent tests (though beforeEach makes this moot).
+        store.createSubSession = original;
+        const reloaded = await store.getSession(session.id, tenant);
+        expect(reloaded?.status).toBe('idle');
+        expect(reloaded?.ownerVersion).toBe(0);
+        expect(events.onUnlocked).toHaveBeenCalledTimes(1);
+    });
+});
+//# sourceMappingURL=single.test.js.map

package/dist/session/handoff/__tests__/single.test.js.map

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

package/dist/session/handoff/assignment.d.ts

@@ -0,0 +1,71 @@
+/**
+ * HandoffAssignment — the data envelope driving
+ * {@link executeSingleHandoff} and {@link executeBroadcastHandoff}.
+ *
+ * See session-hierarchy.md §4.8 (HandoffAssignment), §6.1 (single-recipient
+ * flow), §6.2 (multi-recipient broadcast flow). The shape exposed here is
+ * intentionally minimal — a single row per (source, recipient) pair so the
+ * broadcast flow can work with a homogeneous `readonly HandoffAssignment[]`.
+ */
+import type { SessionId, TenantId } from '../../types/ids/index.js';
+import type { HandoffId, ProjectId, ThreadId, WorkspaceId } from '../../types/session/ids.js';
+import type { ActorRef } from '../hierarchy/actor.js';
+/**
+ * Handoff mode discriminator. `single` transfers ownership of the source
+ * session; `broadcast` fans out into N isolated sub-sessions while the source
+ * session parks at `awaiting_merge` (session-hierarchy.md §5.4 / §6.2).
+ */
+export type HandoffMode = 'single' | 'broadcast';
+/**
+ * Input row for a handoff execution. One record per source/recipient pair.
+ *
+ * For a `single` handoff, exactly one record is submitted. For a `broadcast`
+ * handoff, N records share the same `sourceSessionId`, `broadcastId`, and
+ * `expectedOwnerVersion`; recipients differ per row. See session-hierarchy.md
+ * §4.8.
+ */
+export interface HandoffAssignment {
+    id: HandoffId;
+    mode: HandoffMode;
+    sourceSessionId: SessionId;
+    tenantId: TenantId;
+    /**
+     * Topic-layer scope the source session belongs to. Handoff recipients
+     * always land on the same Thread (cross-thread handoff is forbidden —
+     * a new actor taking over a conversation stays on the same topic).
+     * Validated against `source.threadId` at execute time.
+     */
+    threadId: ThreadId;
+    /**
+     * Denormalized from the owning Thread. Kept alongside `threadId` as the
+     * Session record itself carries both (see `Session` JSDoc). Consistency
+     * validated against `source.projectId` at execute time.
+     */
+    projectId: ProjectId;
+    /** The actor initiating the handoff (must be the source's current owner). */
+    sourceActor: ActorRef;
+    /** Single recipient or one of many (for broadcast). */
+    recipientActor: ActorRef;
+    /** CAS value for the source {@link Session.ownerVersion} at submission time. */
+    expectedOwnerVersion: number;
+    createdAt: Date;
+    /** Correlates the N rows of a broadcast fan-out; required for `broadcast`. */
+    broadcastId?: string;
+}
+/**
+ * Outcome of a committed handoff (single) or one row of a committed broadcast.
+ *
+ * `committedOwnerVersion` is the source session's version *after* commit. For
+ * a broadcast, every row in the returned array reports the same committed
+ * version (the source is CAS-locked once per broadcast, not per recipient).
+ */
+export interface HandoffOutcome {
+    assignmentId: HandoffId;
+    /** The recipient's newly-spawned session id. */
+    newSessionId: SessionId;
+    /** Isolated workspace provisioned for the recipient. */
+    workspaceId: WorkspaceId;
+    /** Source session's new {@link Session.ownerVersion} after commit. */
+    committedOwnerVersion: number;
+}
+//# sourceMappingURL=assignment.d.ts.map

package/dist/session/handoff/assignment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assignment.d.ts","sourceRoot":"","sources":["../../../src/session/handoff/assignment.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAA;AACnE,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAA;AAC7F,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAA;AAErD;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,WAAW,CAAA;AAEhD;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IACjC,EAAE,EAAE,SAAS,CAAA;IACb,IAAI,EAAE,WAAW,CAAA;IACjB,eAAe,EAAE,SAAS,CAAA;IAC1B,QAAQ,EAAE,QAAQ,CAAA;IAClB;;;;;OAKG;IACH,QAAQ,EAAE,QAAQ,CAAA;IAClB;;;;OAIG;IACH,SAAS,EAAE,SAAS,CAAA;IACpB,6EAA6E;IAC7E,WAAW,EAAE,QAAQ,CAAA;IACrB,uDAAuD;IACvD,cAAc,EAAE,QAAQ,CAAA;IACxB,gFAAgF;IAChF,oBAAoB,EAAE,MAAM,CAAA;IAC5B,SAAS,EAAE,IAAI,CAAA;IACf,8EAA8E;IAC9E,WAAW,CAAC,EAAE,MAAM,CAAA;CACpB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC9B,YAAY,EAAE,SAAS,CAAA;IACvB,gDAAgD;IAChD,YAAY,EAAE,SAAS,CAAA;IACvB,wDAAwD;IACxD,WAAW,EAAE,WAAW,CAAA;IACxB,sEAAsE;IACtE,qBAAqB,EAAE,MAAM,CAAA;CAC7B"}

package/dist/session/handoff/assignment.js

@@ -0,0 +1,11 @@
+/**
+ * HandoffAssignment — the data envelope driving
+ * {@link executeSingleHandoff} and {@link executeBroadcastHandoff}.
+ *
+ * See session-hierarchy.md §4.8 (HandoffAssignment), §6.1 (single-recipient
+ * flow), §6.2 (multi-recipient broadcast flow). The shape exposed here is
+ * intentionally minimal — a single row per (source, recipient) pair so the
+ * broadcast flow can work with a homogeneous `readonly HandoffAssignment[]`.
+ */
+export {};
+//# sourceMappingURL=assignment.js.map

package/dist/session/handoff/assignment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assignment.js","sourceRoot":"","sources":["../../../src/session/handoff/assignment.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/session/handoff/broadcast.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Multi-recipient (broadcast) handoff — atomic fan-out with compensating
+ * rollback.
+ *
+ * See session-hierarchy.md §6.2 (Multi-recipient broadcast flow — atomic),
+ * §5.4 (broadcast source-session post-fan-out), §6.5 (capacity enforcement).
+ *
+ * **Atomicity contract** — one transaction boundary: either the full fan-out
+ * commits (source CAS-lock + N assignments + N sub-sessions + N worktrees),
+ * or none of it is externally observable. On any step failure the kernel
+ * executes a compensating rollback and emits `onBroadcastRollback` with
+ * accurate `partialState` counts. The rollback itself is idempotent per
+ * roadmap Risk #3.
+ *
+ * Commit / rollback sequence (pattern doc §6.2):
+ * ```
+ * COMMIT:   idle → locked(CAS) → N assignments → N sub-sessions → N worktrees → awaiting_merge
+ * ROLLBACK: ( ← tear down partial worktrees ← delete partial sub-sessions ←
+ *             delete partial assignments ← release CAS ) emit broadcast.rollback;
+ *             source → idle
+ * ```
+ */
+import type { ThreadManager } from '../../manager/thread/lifecycle.js';
+import type { TenantId } from '../../types/ids/index.js';
+import type { SessionStore } from '../../types/session/store.js';
+import type { WorkspaceBackendRegistry } from '../workspace/registry.js';
+import type { HandoffAssignment, HandoffOutcome } from './assignment.js';
+import type { CapacityValidator } from './capacity.js';
+import type { HandoffEventSink } from './events.js';
+import { type RunStatusResolver } from './single.js';
+export interface BroadcastHandoffDeps {
+    store: SessionStore;
+    workspaceRegistry: WorkspaceBackendRegistry;
+    capacity: CapacityValidator;
+    events: HandoffEventSink;
+    runStatus?: RunStatusResolver;
+    /**
+     * Gate every recipient-session creation on the Thread being `'open'`.
+     * Added in Phase 2.6; checked once per broadcast (all recipients share
+     * a threadId by the fan-out invariant validated above).
+     */
+    threadManager: ThreadManager;
+}
+/**
+ * Executes a broadcast fan-out. All assignments MUST share the same
+ * `sourceSessionId`, `expectedOwnerVersion`, `broadcastId`, and `projectId`.
+ * Duplicate recipients (same actor kind + id) are rejected before any write.
+ *
+ * Returns one {@link HandoffOutcome} per recipient on success. On failure the
+ * source session is restored, every provisioned resource is torn down, and
+ * the underlying error propagates after `onBroadcastRollback` is emitted.
+ */
+export declare function executeBroadcastHandoff(deps: BroadcastHandoffDeps, assignments: readonly HandoffAssignment[], tenantId: TenantId): Promise<readonly HandoffOutcome[]>;
+//# sourceMappingURL=broadcast.d.ts.map

package/dist/session/handoff/broadcast.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"broadcast.d.ts","sourceRoot":"","sources":["../../../src/session/handoff/broadcast.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mCAAmC,CAAA;AACtE,OAAO,KAAK,EAAa,QAAQ,EAAE,MAAM,0BAA0B,CAAA;AAEnE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAA;AAKhE,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAA;AACxE,OAAO,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AACxE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA;AACtD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AACnD,OAAO,EAA4B,KAAK,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAG9E,MAAM,WAAW,oBAAoB;IACpC,KAAK,EAAE,YAAY,CAAA;IACnB,iBAAiB,EAAE,wBAAwB,CAAA;IAC3C,QAAQ,EAAE,iBAAiB,CAAA;IAC3B,MAAM,EAAE,gBAAgB,CAAA;IACxB,SAAS,CAAC,EAAE,iBAAiB,CAAA;IAC7B;;;;OAIG;IACH,aAAa,EAAE,aAAa,CAAA;CAC5B;AAgBD;;;;;;;;GAQG;AACH,wBAAsB,uBAAuB,CAC5C,IAAI,EAAE,oBAAoB,EAC1B,WAAW,EAAE,SAAS,iBAAiB,EAAE,EACzC,QAAQ,EAAE,QAAQ,GAChB,OAAO,CAAC,SAAS,cAAc,EAAE,CAAC,CAoOpC"}