@namzu/sdk 0.1.7 → 0.2.0

package/dist/session/handoff/single.js

@@ -0,0 +1,217 @@
+/**
+ * Single-recipient handoff flow — `idle → locked → CAS → commit | revert`.
+ *
+ * See session-hierarchy.md §6.1 (single-recipient flow) and §6.4 (concurrent
+ * CAS). Function-based per Convention #9 — dependencies arrive as an
+ * explicit `deps` envelope so tests can inject mocks and production code
+ * composes flows without a class hierarchy.
+ *
+ * Flow (pattern doc §5.1 + §6.1):
+ *   1. Load source session; verify tenant.
+ *   2. Check status (must be `idle`); no non-terminal Runs.
+ *   3. Validate capacity (depth + width).
+ *   4. Transition source `idle → locked` with CAS on `ownerVersion`.
+ *   5. Emit `onLocked`.
+ *   6. Spawn recipient sub-session + provision isolated workspace.
+ *   7. On any step 6 failure: compensating revert (`locked → idle`, version
+ *      unchanged, dispose any partial worktree), emit `onUnlocked`, rethrow.
+ *   8. On success: commit `locked → idle` with updated `currentActor` +
+ *      appended `previousActors` + bumped `ownerVersion`.
+ *   9. Emit `onCommitted` with the new version.
+ */
+import { TenantIsolationError } from '../errors.js';
+import { HandoffLockRejected, HandoffVersionConflict } from './version.js';
+/** Null resolver — treats every session as unblocked. Used by tests that do not exercise Run fan-in. */
+export const NOOP_RUN_STATUS_RESOLVER = {
+    async blockingRun() {
+        return null;
+    },
+};
+/**
+ * Executes a single-recipient handoff against `deps.store`. Throws
+ * {@link HandoffLockRejected}, {@link HandoffVersionConflict},
+ * {@link TenantIsolationError}, or {@link DelegationCapacityExceeded} on
+ * invariant violations. Workspace provisioning failures surface as
+ * {@link WorkspaceBackendError} after the compensating revert.
+ */
+export async function executeSingleHandoff(deps, assignment, tenantId) {
+    if (assignment.tenantId !== tenantId) {
+        throw new TenantIsolationError({
+            requested: tenantId,
+            resource: `handoff-assignment(${assignment.id})`,
+        });
+    }
+    // 1. Load source session + tenant check.
+    const source = await deps.store.getSession(assignment.sourceSessionId, tenantId);
+    if (!source) {
+        throw new Error(`Source session ${assignment.sourceSessionId} not found`);
+    }
+    if (source.tenantId !== tenantId) {
+        throw new TenantIsolationError({
+            requested: tenantId,
+            resource: `session(${source.id})`,
+        });
+    }
+    if (source.projectId !== assignment.projectId) {
+        throw new Error(`Assignment projectId ${assignment.projectId} does not match source session projectId ${source.projectId}`);
+    }
+    // 2. Status check — only `idle` sessions may lock. `active`, `awaiting_hitl`,
+    //    `awaiting_merge`, `locked`, `failed`, `archived` all reject.
+    if (source.status !== 'idle') {
+        throw new HandoffLockRejected({
+            sessionId: source.id,
+            reason: statusToLockReason(source.status),
+        });
+    }
+    // 3. Non-terminal Run fan-in (§5.1).
+    const runResolver = deps.runStatus ?? NOOP_RUN_STATUS_RESOLVER;
+    const blocking = await runResolver.blockingRun(source.id, tenantId);
+    if (blocking) {
+        throw new HandoffLockRejected({
+            sessionId: source.id,
+            reason: blocking.reason,
+        });
+    }
+    // 4. Capacity — depth (new child depth = parent ancestry length + 1) and
+    //    width (one new child under the source's *parent* would change — but
+    //    single handoff does NOT create a child under the source; it transfers
+    //    ownership of the same session. Width only applies to broadcast).
+    //    For `single` we still validate depth to future-proof should the flow
+    //    evolve into a branch variant.
+    const project = await deps.store.getProject(source.projectId, tenantId);
+    if (!project) {
+        throw new Error(`Project ${source.projectId} not found`);
+    }
+    await deps.capacity.validateDepth(source.id, project.config.maxDelegationDepth, tenantId);
+    // 5. CAS → `idle → locked`.
+    if (source.ownerVersion !== assignment.expectedOwnerVersion) {
+        throw new HandoffVersionConflict({
+            sessionId: source.id,
+            expected: assignment.expectedOwnerVersion,
+            actual: source.ownerVersion,
+        });
+    }
+    const locked = {
+        ...source,
+        status: 'locked',
+    };
+    await deps.store.updateSession(locked, tenantId);
+    emit(deps.events.onLocked, { sessionId: source.id, at: new Date() });
+    // 6. Provision recipient resources. Track partial state for rollback.
+    let provisionedWorkspace = null;
+    let createdSessionId = null;
+    try {
+        const driver = deps.workspaceRegistry.get('git-worktree');
+        provisionedWorkspace = await driver.create({ label: `handoff-${assignment.id}` });
+        const recipientSession = await deps.store.createSession({ projectId: source.projectId, currentActor: assignment.recipientActor }, tenantId);
+        createdSessionId = recipientSession.id;
+        await deps.store.createSubSession({
+            parentSessionId: source.id,
+            childSessionId: recipientSession.id,
+            kind: 'user_handoff',
+            spawnedBy: assignment.sourceActor,
+        }, tenantId);
+        // 7. Commit source: `locked → idle` with appended actor + bumped version.
+        //    The source transitions ownership to the recipient — the previous
+        //    owner is permanently read-only (§6.1).
+        const committed = {
+            ...source,
+            status: 'idle',
+            currentActor: assignment.recipientActor,
+            previousActors: source.currentActor
+                ? [...source.previousActors, source.currentActor]
+                : [...source.previousActors],
+            ownerVersion: source.ownerVersion + 1,
+        };
+        await deps.store.updateSession(committed, tenantId);
+        emit(deps.events.onCommitted, {
+            sessionId: source.id,
+            newVersion: committed.ownerVersion,
+            handoffIds: [assignment.id],
+            at: new Date(),
+        });
+        return {
+            assignmentId: assignment.id,
+            newSessionId: recipientSession.id,
+            workspaceId: provisionedWorkspace.id,
+            committedOwnerVersion: committed.ownerVersion,
+        };
+    }
+    catch (failure) {
+        // Compensating revert — idempotent. Every step tolerates prior success.
+        await revertLock(deps, source, provisionedWorkspace, createdSessionId, tenantId);
+        throw failure;
+    }
+}
+/**
+ * Reverts a source session from `locked` back to `idle` preserving
+ * `ownerVersion`, disposes any provisioned worktree, and emits `onUnlocked`.
+ *
+ * **Idempotent.** Every sub-op tolerates being called against already-released
+ * state:
+ *   - `updateSession` replays the same payload — last-write-wins (Phase 3
+ *     store uses write-tmp-rename).
+ *   - `dispose` on a missing worktree is a no-op by contract
+ *     (`driver.ts#dispose` + `git-worktree.ts` regex for "not a working tree").
+ */
+async function revertLock(deps, source, workspace, createdSessionId, tenantId) {
+    const reverted = { ...source, status: 'idle' };
+    try {
+        await deps.store.updateSession(reverted, tenantId);
+    }
+    catch {
+        // Swallow — the flow is already unwinding a primary failure; surfacing
+        // secondary errors would mask root cause. Idempotent per Risk #3.
+    }
+    if (workspace) {
+        try {
+            const driver = deps.workspaceRegistry.get('git-worktree');
+            await driver.dispose(workspace);
+        }
+        catch {
+            // Idempotent rollback per Risk #3 — dispose is already tolerant of
+            // missing worktrees, but we still guard the registry lookup path.
+        }
+    }
+    if (createdSessionId) {
+        // No `deleteSession` in the Phase 3 store surface — mark the partially
+        // created recipient session as `archived` so it is inert. A later phase
+        // introduces explicit deletion; until then this is the cleanest
+        // compensator that does not add surface area.
+        try {
+            const recipient = await deps.store.getSession(createdSessionId, tenantId);
+            if (recipient) {
+                await deps.store.updateSession({ ...recipient, status: 'archived' }, tenantId);
+            }
+        }
+        catch {
+            // Same rationale as above.
+        }
+    }
+    emit(deps.events.onUnlocked, { sessionId: source.id, at: new Date() });
+}
+function statusToLockReason(status) {
+    switch (status) {
+        case 'active':
+            return 'active_run';
+        case 'awaiting_hitl':
+            return 'pending_hitl';
+        case 'awaiting_merge':
+            return 'pending_subsession';
+        case 'locked':
+            return 'active_run';
+        case 'failed':
+            return 'active_run';
+        case 'archived':
+            return 'active_run';
+        case 'idle':
+            // Unreachable — caller guards. Keep a sentinel value so exhaustiveness
+            // does not force an `assert never` export from this module.
+            return 'active_run';
+    }
+}
+function emit(handler, event) {
+    if (handler)
+        handler(event);
+}
+//# sourceMappingURL=single.js.map

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

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

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

@@ -0,0 +1,52 @@
+/**
+ * Typed errors for the handoff state machine.
+ *
+ * See session-hierarchy.md §5.1 (illegal `active → locked` transition) and
+ * §6.4 (concurrent CAS). Both classes carry structured `details` so consumers
+ * can route without string parsing (Convention #5: deny-by-default, fail
+ * fast).
+ */
+import type { RunId, SessionId } from '../../types/ids/index.js';
+/**
+ * Raised when a handoff's CAS write finds {@link Session.ownerVersion} has
+ * advanced since the assignment was constructed — another actor committed
+ * first (session-hierarchy.md §6.4 concurrent CAS). The caller re-reads and
+ * decides whether to retry.
+ */
+export declare class HandoffVersionConflict extends Error {
+    readonly details: {
+        sessionId: SessionId;
+        expected: number;
+        actual: number;
+    };
+    constructor(details: {
+        sessionId: SessionId;
+        expected: number;
+        actual: number;
+    });
+}
+/**
+ * Reasons a session cannot transition `* → locked` for handoff. See
+ * session-hierarchy.md §5.1 — lock entry requires an `idle` session with all
+ * runs terminal. The three reasons are the non-terminal Run statuses that
+ * fan in to a non-idle Session.
+ */
+export type HandoffLockRejectedReason = 'active_run' | 'pending_hitl' | 'pending_subsession';
+/**
+ * Raised when a handoff targets a session whose current Run is non-terminal.
+ * Callers must wait for the active Run to terminalize (or cancel it) before
+ * re-attempting the handoff (session-hierarchy.md §5.1).
+ */
+export declare class HandoffLockRejected extends Error {
+    readonly details: {
+        sessionId: SessionId;
+        reason: HandoffLockRejectedReason;
+        runId?: RunId;
+    };
+    constructor(details: {
+        sessionId: SessionId;
+        reason: HandoffLockRejectedReason;
+        runId?: RunId;
+    });
+}
+//# sourceMappingURL=version.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../../../src/session/handoff/version.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAA;AAEhE;;;;;GAKG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;IAChD,QAAQ,CAAC,OAAO,EAAE;QACjB,SAAS,EAAE,SAAS,CAAA;QACpB,QAAQ,EAAE,MAAM,CAAA;QAChB,MAAM,EAAE,MAAM,CAAA;KACd,CAAA;gBAEW,OAAO,EAAE;QAAE,SAAS,EAAE,SAAS,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE;CAO/E;AAED;;;;;GAKG;AACH,MAAM,MAAM,yBAAyB,GAAG,YAAY,GAAG,cAAc,GAAG,oBAAoB,CAAA;AAE5F;;;;GAIG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;IAC7C,QAAQ,CAAC,OAAO,EAAE;QACjB,SAAS,EAAE,SAAS,CAAA;QACpB,MAAM,EAAE,yBAAyB,CAAA;QACjC,KAAK,CAAC,EAAE,KAAK,CAAA;KACb,CAAA;gBAEW,OAAO,EAAE;QAAE,SAAS,EAAE,SAAS,CAAC;QAAC,MAAM,EAAE,yBAAyB,CAAC;QAAC,KAAK,CAAC,EAAE,KAAK,CAAA;KAAE;CAK/F"}

package/dist/session/handoff/version.js

@@ -0,0 +1,36 @@
+/**
+ * Typed errors for the handoff state machine.
+ *
+ * See session-hierarchy.md §5.1 (illegal `active → locked` transition) and
+ * §6.4 (concurrent CAS). Both classes carry structured `details` so consumers
+ * can route without string parsing (Convention #5: deny-by-default, fail
+ * fast).
+ */
+/**
+ * Raised when a handoff's CAS write finds {@link Session.ownerVersion} has
+ * advanced since the assignment was constructed — another actor committed
+ * first (session-hierarchy.md §6.4 concurrent CAS). The caller re-reads and
+ * decides whether to retry.
+ */
+export class HandoffVersionConflict extends Error {
+    details;
+    constructor(details) {
+        super(`Handoff version conflict on ${details.sessionId}: expected ${details.expected}, actual ${details.actual}`);
+        this.name = 'HandoffVersionConflict';
+        this.details = details;
+    }
+}
+/**
+ * Raised when a handoff targets a session whose current Run is non-terminal.
+ * Callers must wait for the active Run to terminalize (or cancel it) before
+ * re-attempting the handoff (session-hierarchy.md §5.1).
+ */
+export class HandoffLockRejected extends Error {
+    details;
+    constructor(details) {
+        super(`Handoff lock rejected on ${details.sessionId}: ${details.reason}`);
+        this.name = 'HandoffLockRejected';
+        this.details = details;
+    }
+}
+//# sourceMappingURL=version.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../../../src/session/handoff/version.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH;;;;;GAKG;AACH,MAAM,OAAO,sBAAuB,SAAQ,KAAK;IACvC,OAAO,CAIf;IAED,YAAY,OAAmE;QAC9E,KAAK,CACJ,+BAA+B,OAAO,CAAC,SAAS,cAAc,OAAO,CAAC,QAAQ,YAAY,OAAO,CAAC,MAAM,EAAE,CAC1G,CAAA;QACD,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAA;QACpC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAA;IACvB,CAAC;CACD;AAUD;;;;GAIG;AACH,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IACpC,OAAO,CAIf;IAED,YAAY,OAAmF;QAC9F,KAAK,CAAC,4BAA4B,OAAO,CAAC,SAAS,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAA;QACzE,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAA;QACjC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAA;IACvB,CAAC;CACD"}

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

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

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

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

package/dist/session/hierarchy/__tests__/session.test.js

@@ -0,0 +1,67 @@
+import { describe, expect, it } from 'vitest';
+import { deriveStatus } from '../session.js';
+const tenant = 'tnt_a';
+const project = 'prj_a';
+function user() {
+    return { kind: 'user', userId: 'usr_a', tenantId: tenant };
+}
+function makeSession(status) {
+    return {
+        id: 'ses_a',
+        projectId: project,
+        tenantId: tenant,
+        status,
+        currentActor: user(),
+        previousActors: [],
+        workspaceId: null,
+        ownerVersion: 0,
+        createdAt: new Date('2026-01-01'),
+        updatedAt: new Date('2026-01-01'),
+    };
+}
+function runs(...statuses) {
+    return statuses.map((status) => ({ status }));
+}
+describe('deriveStatus', () => {
+    it('empty run set → idle', () => {
+        expect(deriveStatus(makeSession('idle'), [])).toBe('idle');
+    });
+    it('all succeeded → idle', () => {
+        expect(deriveStatus(makeSession('idle'), runs('succeeded', 'succeeded'))).toBe('idle');
+    });
+    it('any running → active (overrides idle session status)', () => {
+        expect(deriveStatus(makeSession('idle'), runs('succeeded', 'running'))).toBe('active');
+    });
+    it('any awaiting_subsession → active (delegation-in-flight parent is active)', () => {
+        expect(deriveStatus(makeSession('idle'), runs('succeeded', 'awaiting_subsession'))).toBe('active');
+    });
+    it('awaiting_subsession alone → active', () => {
+        expect(deriveStatus(makeSession('idle'), runs('awaiting_subsession'))).toBe('active');
+    });
+    it('any awaiting_hitl → awaiting_hitl', () => {
+        expect(deriveStatus(makeSession('idle'), runs('succeeded', 'awaiting_hitl'))).toBe('awaiting_hitl');
+    });
+    it('any awaiting_hitl_resolution → awaiting_hitl (persisted HITL wait)', () => {
+        expect(deriveStatus(makeSession('idle'), runs('awaiting_hitl_resolution'))).toBe('awaiting_hitl');
+    });
+    it('all failed → failed', () => {
+        expect(deriveStatus(makeSession('idle'), runs('failed', 'failed'))).toBe('failed');
+    });
+    it('cancelled + failed + succeeded mix → idle (cancellation is not terminal Session state)', () => {
+        expect(deriveStatus(makeSession('idle'), runs('succeeded', 'cancelled', 'failed'))).toBe('idle');
+    });
+    it('locked session-level state wins over derived (even with succeeded runs)', () => {
+        expect(deriveStatus(makeSession('locked'), runs('succeeded'))).toBe('locked');
+    });
+    it('awaiting_merge session-level state wins over derived', () => {
+        expect(deriveStatus(makeSession('awaiting_merge'), runs('succeeded'))).toBe('awaiting_merge');
+    });
+    it('archived session-level state wins over derived (retention tombstone)', () => {
+        expect(deriveStatus(makeSession('archived'), runs('succeeded'))).toBe('archived');
+    });
+    it('running takes precedence over HITL', () => {
+        // Two runs — one running, one HITL. Active is higher priority (§5.1).
+        expect(deriveStatus(makeSession('idle'), runs('running', 'awaiting_hitl'))).toBe('active');
+    });
+});
+//# sourceMappingURL=session.test.js.map

package/dist/session/hierarchy/__tests__/session.test.js.map

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

package/dist/session/hierarchy/actor.d.ts

@@ -0,0 +1,26 @@
+import type { AgentId, TenantId, UserId } from '../../types/ids/index.js';
+/**
+ * Discriminated union of actors that can own a {@link Session}.
+ *
+ * See session-hierarchy.md §4.3. The `parentActor` field on the agent variant
+ * pairs with {@link Lineage} (§10.4) — permission audit events walk this
+ * chain to attribute subagent actions back to the originating user. Renamed
+ * from `spawnedBy` during the 0.2.0 design phase (no shim kept).
+ */
+export type ActorRef = {
+    kind: 'user';
+    userId: UserId;
+    tenantId: TenantId;
+} | {
+    kind: 'agent';
+    agentId: AgentId;
+    tenantId: TenantId;
+    parentActor?: ActorRef;
+} | {
+    kind: 'system';
+    role: SystemRoleId;
+    tenantId: TenantId;
+};
+/** Branded id for the {@link ActorRef} `system` variant. */
+export type SystemRoleId = `sys_${string}`;
+//# sourceMappingURL=actor.d.ts.map

package/dist/session/hierarchy/actor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"actor.d.ts","sourceRoot":"","sources":["../../../src/session/hierarchy/actor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAA;AAEzE;;;;;;;GAOG;AACH,MAAM,MAAM,QAAQ,GACjB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,QAAQ,CAAA;CAAE,GACpD;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,QAAQ,CAAC;IAAC,WAAW,CAAC,EAAE,QAAQ,CAAA;CAAE,GAC/E;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,YAAY,CAAC;IAAC,QAAQ,EAAE,QAAQ,CAAA;CAAE,CAAA;AAE7D,4DAA4D;AAC5D,MAAM,MAAM,YAAY,GAAG,OAAO,MAAM,EAAE,CAAA"}

package/dist/session/hierarchy/actor.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=actor.js.map

package/dist/session/hierarchy/actor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"actor.js","sourceRoot":"","sources":["../../../src/session/hierarchy/actor.ts"],"names":[],"mappings":""}

package/dist/session/hierarchy/index.d.ts

@@ -0,0 +1,8 @@
+export type { ActorRef, SystemRoleId } from './actor.js';
+export type { Lineage } from './lineage.js';
+export type { Tenant } from './tenant.js';
+export type { Project, ProjectConfig } from './project.js';
+export type { Session, SessionStatus } from './session.js';
+export { deriveStatus } from './session.js';
+export type { SubSession, SubSessionStatus, SubSessionKind, FailureMode, CompletionMode, DeliverableRef, } from './sub-session.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/session/hierarchy/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/session/hierarchy/index.ts"],"names":[],"mappings":"AAGA,YAAY,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AACxD,YAAY,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAC3C,YAAY,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACzC,YAAY,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAC1D,YAAY,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAC1D,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAC3C,YAAY,EACX,UAAU,EACV,gBAAgB,EAChB,cAAc,EACd,WAAW,EACX,cAAc,EACd,cAAc,GACd,MAAM,kBAAkB,CAAA"}

package/dist/session/hierarchy/index.js

@@ -0,0 +1,4 @@
+// Sub-barrel for the session-hierarchy entity model.
+// Convention #4: concrete types live in sibling files; re-export them here.
+export { deriveStatus } from './session.js';
+//# sourceMappingURL=index.js.map

package/dist/session/hierarchy/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/session/hierarchy/index.ts"],"names":[],"mappings":"AAAA,qDAAqD;AACrD,4EAA4E;AAO5E,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA"}

package/dist/session/hierarchy/lineage.d.ts

@@ -0,0 +1,15 @@
+import type { SessionId } from '../../types/ids/index.js';
+/**
+ * Parent/root linkage carried on every sub-session event.
+ *
+ * Per session-hierarchy.md §10.4 every `RunEvent` emitted from a sub-session
+ * carries a {@link Lineage} so consumers can reconstruct the delegation tree
+ * without walking the store. `depth` is 0 at the root session and grows by 1
+ * per delegation level.
+ */
+export interface Lineage {
+    parentSessionId: SessionId;
+    rootSessionId: SessionId;
+    depth: number;
+}
+//# sourceMappingURL=lineage.d.ts.map

package/dist/session/hierarchy/lineage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lineage.d.ts","sourceRoot":"","sources":["../../../src/session/hierarchy/lineage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAA;AAEzD;;;;;;;GAOG;AACH,MAAM,WAAW,OAAO;IACvB,eAAe,EAAE,SAAS,CAAA;IAC1B,aAAa,EAAE,SAAS,CAAA;IACxB,KAAK,EAAE,MAAM,CAAA;CACb"}

package/dist/session/hierarchy/lineage.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=lineage.js.map

package/dist/session/hierarchy/lineage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lineage.js","sourceRoot":"","sources":["../../../src/session/hierarchy/lineage.ts"],"names":[],"mappings":""}

package/dist/session/hierarchy/project.d.ts

@@ -0,0 +1,40 @@
+import type { KnowledgeBaseRef, MemoryStoreRef, TenantId, VaultRef } from '../../types/ids/index.js';
+import type { ProjectId } from '../../types/session/ids.js';
+import type { RetentionPolicy } from '../retention/policy.js';
+/**
+ * Per-project configuration. Defaults per session-hierarchy.md §3 / §4.2 /
+ * §8.2 are applied at instantiation time (not encoded here) so the type
+ * stays declarative:
+ *   - maxDelegationDepth: 4
+ *   - maxDelegationWidth: 8
+ *   - maxInterventionDepth: 10
+ *   - sharedDeliverables: false
+ *
+ * `retentionPolicy` replaces the Phase 1 `RetentionPolicyRef = unknown`
+ * placeholder with the real {@link RetentionPolicy} shape (§12.3). Absent
+ * (deny-by-default per Convention #5) means archival is fully disabled for
+ * the project; explicit configuration is required.
+ */
+export interface ProjectConfig {
+    maxDelegationDepth: number;
+    maxDelegationWidth: number;
+    maxInterventionDepth: number;
+    sharedMemoryStores?: readonly MemoryStoreRef[];
+    sharedVaults?: readonly VaultRef[];
+    sharedKnowledgeBases?: readonly KnowledgeBaseRef[];
+    sharedDeliverables?: boolean;
+    retentionPolicy?: RetentionPolicy;
+}
+/**
+ * Long-lived goal scope that owns shared memory, vaults, knowledge bases,
+ * and deliverables across sessions. See session-hierarchy.md §4.2.
+ */
+export interface Project {
+    id: ProjectId;
+    tenantId: TenantId;
+    name: string;
+    config: ProjectConfig;
+    createdAt: Date;
+    updatedAt: Date;
+}
+//# sourceMappingURL=project.d.ts.map

package/dist/session/hierarchy/project.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project.d.ts","sourceRoot":"","sources":["../../../src/session/hierarchy/project.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAA;AACpG,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAA;AAC3D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AAE7D;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,aAAa;IAC7B,kBAAkB,EAAE,MAAM,CAAA;IAC1B,kBAAkB,EAAE,MAAM,CAAA;IAC1B,oBAAoB,EAAE,MAAM,CAAA;IAC5B,kBAAkB,CAAC,EAAE,SAAS,cAAc,EAAE,CAAA;IAC9C,YAAY,CAAC,EAAE,SAAS,QAAQ,EAAE,CAAA;IAClC,oBAAoB,CAAC,EAAE,SAAS,gBAAgB,EAAE,CAAA;IAClD,kBAAkB,CAAC,EAAE,OAAO,CAAA;IAC5B,eAAe,CAAC,EAAE,eAAe,CAAA;CACjC;AAED;;;GAGG;AACH,MAAM,WAAW,OAAO;IACvB,EAAE,EAAE,SAAS,CAAA;IACb,QAAQ,EAAE,QAAQ,CAAA;IAClB,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,aAAa,CAAA;IACrB,SAAS,EAAE,IAAI,CAAA;IACf,SAAS,EAAE,IAAI,CAAA;CACf"}

package/dist/session/hierarchy/project.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=project.js.map

package/dist/session/hierarchy/project.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"project.js","sourceRoot":"","sources":["../../../src/session/hierarchy/project.ts"],"names":[],"mappings":""}

package/dist/session/hierarchy/session.d.ts

@@ -0,0 +1,59 @@
+import type { SessionId, TenantId } from '../../types/ids/index.js';
+import type { RunStatus } from '../../types/run/status.js';
+import type { ProjectId, WorkspaceId } from '../../types/session/ids.js';
+import type { ActorRef } from './actor.js';
+/**
+ * Session lifecycle states. See session-hierarchy.md §4.3 and the state
+ * machine in §5.1. `awaiting_merge` is a sub-state of idle used on the
+ * broadcast source session (§5.4) between fan-out and all recipients
+ * terminalizing.
+ */
+export type SessionStatus = 'active' | 'idle' | 'locked' | 'awaiting_hitl' | 'awaiting_merge' | 'failed' | 'archived';
+/**
+ * Multi-turn work unit owned by exactly one {@link ActorRef} at a time.
+ *
+ * Fields derived from session-hierarchy.md §4.3:
+ *   - `previousActors` is append-only and publicly read-only; previous
+ *     owners cannot write to the session again (Decision #3).
+ *   - `ownerVersion` is the CAS counter for handoff (§6.1 / §6.2 / §6.4).
+ *   - `workspaceId` is nullable for sessions whose workspace has not yet
+ *     been provisioned (or has been torn down during archival).
+ */
+export interface Session {
+    id: SessionId;
+    projectId: ProjectId;
+    tenantId: TenantId;
+    status: SessionStatus;
+    currentActor: ActorRef | null;
+    previousActors: readonly ActorRef[];
+    workspaceId: WorkspaceId | null;
+    ownerVersion: number;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/**
+ * Pure Run→Session fan-in helper per session-hierarchy.md §5.1.
+ *
+ * The precedence (highest first) matches the pattern-doc table:
+ *   1. Session-level states that do not fan in from Run status:
+ *      - `locked` (handoff CAS window) — preserved verbatim
+ *      - `awaiting_merge` (broadcast source post-fan-out, §5.4) — preserved
+ *      - `archived` (retention tombstone, §12.3) — preserved
+ *   2. Any Run `running` or `awaiting_subsession` → Session `active`.
+ *      Delegation-in-flight is an active state of the parent — the parent
+ *      Run is suspended waiting on the child's SessionSummaryMaterializer,
+ *      and the session is NOT idle while that is pending.
+ *   3. Any Run `awaiting_hitl` or `awaiting_hitl_resolution` → Session
+ *      `awaiting_hitl`.
+ *   4. All Runs `failed` and at least one Run present → Session `failed`.
+ *   5. Otherwise (all runs terminal — succeeded/cancelled/failed mix, or no
+ *      runs at all) → Session `idle`.
+ *
+ * `cancelled` does NOT surface a `failed` Session (§5.1 — "Cancellation is
+ * not a terminal Session state"). Only `failed` runs drive the Session to
+ * `failed` when every Run ended that way.
+ */
+export declare function deriveStatus(session: Session, runs: readonly {
+    status: RunStatus;
+}[]): SessionStatus;
+//# sourceMappingURL=session.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../../src/session/hierarchy/session.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAA;AACnE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAA;AAC1D,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAA;AACxE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAE1C;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GACtB,QAAQ,GACR,MAAM,GACN,QAAQ,GACR,eAAe,GACf,gBAAgB,GAChB,QAAQ,GACR,UAAU,CAAA;AAEb;;;;;;;;;GASG;AACH,MAAM,WAAW,OAAO;IACvB,EAAE,EAAE,SAAS,CAAA;IACb,SAAS,EAAE,SAAS,CAAA;IACpB,QAAQ,EAAE,QAAQ,CAAA;IAClB,MAAM,EAAE,aAAa,CAAA;IACrB,YAAY,EAAE,QAAQ,GAAG,IAAI,CAAA;IAC7B,cAAc,EAAE,SAAS,QAAQ,EAAE,CAAA;IACnC,WAAW,EAAE,WAAW,GAAG,IAAI,CAAA;IAC/B,YAAY,EAAE,MAAM,CAAA;IACpB,SAAS,EAAE,IAAI,CAAA;IACf,SAAS,EAAE,IAAI,CAAA;CACf;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,YAAY,CAC3B,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,SAAS;IAAE,MAAM,EAAE,SAAS,CAAA;CAAE,EAAE,GACpC,aAAa,CA4Bf"}