@namzu/sdk 0.1.7 → 0.2.0

package/dist/session/hierarchy/session.js

@@ -0,0 +1,51 @@
+/**
+ * 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 function deriveStatus(session, runs) {
+    // Session-level overrides — these states do not fan in from Run status.
+    if (session.status === 'locked')
+        return 'locked';
+    if (session.status === 'awaiting_merge')
+        return 'awaiting_merge';
+    if (session.status === 'archived')
+        return 'archived';
+    // Any active Run (in-flight iteration or awaiting a child sub-session) →
+    // `active`. Delegation is an active state: the parent Run is suspended
+    // waiting on the child's Materializer, not idle.
+    const hasActive = runs.some((r) => r.status === 'running' || r.status === 'awaiting_subsession');
+    if (hasActive)
+        return 'active';
+    // Any HITL block (synchronous or persisted) → `awaiting_hitl`.
+    const hasHitl = runs.some((r) => r.status === 'awaiting_hitl' || r.status === 'awaiting_hitl_resolution');
+    if (hasHitl)
+        return 'awaiting_hitl';
+    // All failed (with at least one Run) → `failed`. Note that a `cancelled`
+    // Run does NOT drive the Session to `failed`; §5.1 is explicit that
+    // cancellation leaves the Session `idle`.
+    if (runs.length > 0 && runs.every((r) => r.status === 'failed')) {
+        return 'failed';
+    }
+    // Otherwise — empty run set, or all runs terminated (succeeded / cancelled
+    // / mixed with failed) — the Session is `idle`.
+    return 'idle';
+}
+//# sourceMappingURL=session.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../../../src/session/hierarchy/session.ts"],"names":[],"mappings":"AA2CA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,YAAY,CAC3B,OAAgB,EAChB,IAAsC;IAEtC,wEAAwE;IACxE,IAAI,OAAO,CAAC,MAAM,KAAK,QAAQ;QAAE,OAAO,QAAQ,CAAA;IAChD,IAAI,OAAO,CAAC,MAAM,KAAK,gBAAgB;QAAE,OAAO,gBAAgB,CAAA;IAChE,IAAI,OAAO,CAAC,MAAM,KAAK,UAAU;QAAE,OAAO,UAAU,CAAA;IAEpD,yEAAyE;IACzE,uEAAuE;IACvE,iDAAiD;IACjD,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,SAAS,IAAI,CAAC,CAAC,MAAM,KAAK,qBAAqB,CAAC,CAAA;IAChG,IAAI,SAAS;QAAE,OAAO,QAAQ,CAAA;IAE9B,+DAA+D;IAC/D,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CACxB,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,eAAe,IAAI,CAAC,CAAC,MAAM,KAAK,0BAA0B,CAC9E,CAAA;IACD,IAAI,OAAO;QAAE,OAAO,eAAe,CAAA;IAEnC,yEAAyE;IACzE,oEAAoE;IACpE,0CAA0C;IAC1C,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,QAAQ,CAAC,EAAE,CAAC;QACjE,OAAO,QAAQ,CAAA;IAChB,CAAC;IAED,2EAA2E;IAC3E,gDAAgD;IAChD,OAAO,MAAM,CAAA;AACd,CAAC"}

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

@@ -0,0 +1,76 @@
+import type { SessionId } from '../../types/ids/index.js';
+import type { SubSessionId, SummaryId, WorkspaceId } from '../../types/session/ids.js';
+import type { ArchiveBackendRef } from '../retention/archive-backend-ref.js';
+import type { DeliverableRef } from '../summary/deliverable.js';
+import type { ActorRef } from './actor.js';
+/**
+ * Full 11-variant status union. See session-hierarchy.md §4.4 and the merge
+ * state machine in §4.4.1. Absence of a `closed` state is load-bearing —
+ * completed sub-sessions land on `idle` and stay there for drill-down
+ * (Decision #5).
+ */
+export type SubSessionStatus = 'pending' | 'active' | 'idle' | 'failed' | 'awaiting_merge' | 'pending_merge' | 'merging' | 'merged' | 'merge_conflict' | 'merge_rejected' | 'archived';
+/**
+ * Discriminator for how a sub-session was created. Pattern doc §4.4
+ * enumerates four variants; the three kept here collapse `user_handoff`
+ * and `user_broadcast` into the single `user_handoff` kind (multi-recipient
+ * flows are encoded via `broadcastGroupId` in later phases).
+ */
+export type SubSessionKind = 'agent_spawn' | 'user_handoff' | 'intervention';
+/**
+ * Per-spawn failure policy for parallel fan-out. See session-hierarchy.md
+ * §4.4. Default is `delegate` — siblings continue and the parent agent
+ * decides what to do with partial results.
+ */
+export type FailureMode = 'fail_fast' | 'delegate';
+/**
+ * Completion contract the parent expects. See session-hierarchy.md §9.
+ *
+ * `summary_ref` is the default for agent delegation and interventions.
+ * `merge_back` is used by multi-user handoff; full spec lives in
+ * `collaboration-primitives.md`.
+ */
+export type CompletionMode = 'summary_ref' | 'merge_back';
+/**
+ * Re-export of the real {@link DeliverableRef} discriminated union. The
+ * concrete shape lives in `../summary/deliverable.ts` — see
+ * session-hierarchy.md §4.7 / §8.1. Phase 5 (this phase) replaced the Phase 1
+ * `unknown` placeholder with the real type.
+ */
+export type { DeliverableRef };
+/**
+ * Edge between a parent {@link Session} and a child session, carrying the
+ * delegation metadata. The child session itself lives in `SessionStore`
+ * like any other session — see session-hierarchy.md §4.4.
+ */
+export interface SubSession {
+    id: SubSessionId;
+    parentSessionId: SessionId;
+    childSessionId: SessionId;
+    kind: SubSessionKind;
+    status: SubSessionStatus;
+    spawnedBy: ActorRef;
+    spawnedAt: Date;
+    failureMode: FailureMode;
+    completionMode: CompletionMode;
+    workspaceId: WorkspaceId | null;
+    /**
+     * For interventions, the immutable artifact being addressed. Chains form
+     * a strict acyclic DAG — see session-hierarchy.md §4.5.
+     */
+    prevArtifactRef?: DeliverableRef;
+    /** Fan-out bookkeeping for broadcasts (§4.4). */
+    broadcastGroupId?: string;
+    /** Populated by {@link SessionSummaryMaterializer} on terminalization (§8). */
+    summaryRef?: SummaryId;
+    /**
+     * Pointer to the archive bundle for this sub-session. Present iff
+     * `status === 'archived'` (pattern doc §12.3). The paired
+     * {@link archivedAt} timestamp captures when the bundle was sealed.
+     * Cleared by {@link ArchivalManager.restore}.
+     */
+    archiveRef?: ArchiveBackendRef;
+    archivedAt?: Date;
+    updatedAt: Date;
+}
+//# sourceMappingURL=sub-session.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sub-session.d.ts","sourceRoot":"","sources":["../../../src/session/hierarchy/sub-session.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAA;AACzD,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAA;AACtF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qCAAqC,CAAA;AAC5E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAA;AAC/D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAE1C;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GACzB,SAAS,GACT,QAAQ,GACR,MAAM,GACN,QAAQ,GACR,gBAAgB,GAChB,eAAe,GACf,SAAS,GACT,QAAQ,GACR,gBAAgB,GAChB,gBAAgB,GAChB,UAAU,CAAA;AAEb;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,aAAa,GAAG,cAAc,GAAG,cAAc,CAAA;AAE5E;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG,WAAW,GAAG,UAAU,CAAA;AAElD;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG,aAAa,GAAG,YAAY,CAAA;AAEzD;;;;;GAKG;AACH,YAAY,EAAE,cAAc,EAAE,CAAA;AAE9B;;;;GAIG;AACH,MAAM,WAAW,UAAU;IAC1B,EAAE,EAAE,YAAY,CAAA;IAChB,eAAe,EAAE,SAAS,CAAA;IAC1B,cAAc,EAAE,SAAS,CAAA;IACzB,IAAI,EAAE,cAAc,CAAA;IACpB,MAAM,EAAE,gBAAgB,CAAA;IACxB,SAAS,EAAE,QAAQ,CAAA;IACnB,SAAS,EAAE,IAAI,CAAA;IACf,WAAW,EAAE,WAAW,CAAA;IACxB,cAAc,EAAE,cAAc,CAAA;IAC9B,WAAW,EAAE,WAAW,GAAG,IAAI,CAAA;IAC/B;;;OAGG;IACH,eAAe,CAAC,EAAE,cAAc,CAAA;IAChC,iDAAiD;IACjD,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,+EAA+E;IAC/E,UAAU,CAAC,EAAE,SAAS,CAAA;IACtB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,iBAAiB,CAAA;IAC9B,UAAU,CAAC,EAAE,IAAI,CAAA;IACjB,SAAS,EAAE,IAAI,CAAA;CACf"}

package/dist/session/hierarchy/sub-session.js

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

package/dist/session/hierarchy/sub-session.js.map

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

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

@@ -0,0 +1,13 @@
+import type { TenantId } from '../../types/ids/index.js';
+/**
+ * Tenancy boundary for everything in the hierarchy.
+ *
+ * Intentionally thin — naming, billing, SSO, and quotas live outside the SDK
+ * (session-hierarchy.md §4.1 Convention #17). No API surface crosses
+ * {@link TenantId}.
+ */
+export interface Tenant {
+    id: TenantId;
+    createdAt: Date;
+}
+//# sourceMappingURL=tenant.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tenant.d.ts","sourceRoot":"","sources":["../../../src/session/hierarchy/tenant.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAA;AAExD;;;;;;GAMG;AACH,MAAM,WAAW,MAAM;IACtB,EAAE,EAAE,QAAQ,CAAA;IACZ,SAAS,EAAE,IAAI,CAAA;CACf"}

package/dist/session/hierarchy/tenant.js

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

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

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

package/dist/session/index.d.ts

@@ -0,0 +1,10 @@
+export * from './hierarchy/index.js';
+export * from './events/index.js';
+export * from './workspace/index.js';
+export * from './handoff/index.js';
+export * from './summary/index.js';
+export * from './intervention/index.js';
+export * from './migration/index.js';
+export * from './retention/index.js';
+export { TenantIsolationError, WorkspaceBackendError, AncestryCycleError } from './errors.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/session/index.ts"],"names":[],"mappings":"AAMA,cAAc,sBAAsB,CAAA;AACpC,cAAc,mBAAmB,CAAA;AACjC,cAAc,sBAAsB,CAAA;AACpC,cAAc,oBAAoB,CAAA;AAClC,cAAc,oBAAoB,CAAA;AAClC,cAAc,yBAAyB,CAAA;AACvC,cAAc,sBAAsB,CAAA;AACpC,cAAc,sBAAsB,CAAA;AACpC,OAAO,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA"}

package/dist/session/index.js

@@ -0,0 +1,15 @@
+// Top-level barrel for the session hierarchy module.
+// Phase 1 populates `hierarchy/`; Phase 2 adds `events/`; Phase 3 adds
+// `workspace/` + `errors.ts`; Phase 4 adds `handoff/`; Phase 5 adds
+// `summary/` + `intervention/`; Phase 7 adds `migration/`; Phase 8 adds
+// `retention/`.
+export * from './hierarchy/index.js';
+export * from './events/index.js';
+export * from './workspace/index.js';
+export * from './handoff/index.js';
+export * from './summary/index.js';
+export * from './intervention/index.js';
+export * from './migration/index.js';
+export * from './retention/index.js';
+export { TenantIsolationError, WorkspaceBackendError, AncestryCycleError } from './errors.js';
+//# sourceMappingURL=index.js.map

package/dist/session/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/session/index.ts"],"names":[],"mappings":"AAAA,qDAAqD;AACrD,uEAAuE;AACvE,oEAAoE;AACpE,wEAAwE;AACxE,gBAAgB;AAEhB,cAAc,sBAAsB,CAAA;AACpC,cAAc,mBAAmB,CAAA;AACjC,cAAc,sBAAsB,CAAA;AACpC,cAAc,oBAAoB,CAAA;AAClC,cAAc,oBAAoB,CAAA;AAClC,cAAc,yBAAyB,CAAA;AACvC,cAAc,sBAAsB,CAAA;AACpC,cAAc,sBAAsB,CAAA;AACpC,OAAO,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA"}

package/dist/session/intervention/__tests__/prev-artifact.test.d.ts

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

package/dist/session/intervention/__tests__/prev-artifact.test.d.ts.map

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

package/dist/session/intervention/__tests__/prev-artifact.test.js

@@ -0,0 +1,179 @@
+import { describe, expect, it } from 'vitest';
+import { ArtifactRefCycleError, InterventionDepthExceeded, validatePrevArtifactChain, } from '../prev-artifact.js';
+// Helpers -------------------------------------------------------------------
+function sessionId(n) {
+    return `ses_${n}`;
+}
+function subId(n) {
+    return `sub_${n}`;
+}
+function summaryDeliverable(targetSession) {
+    return {
+        id: 'del_test',
+        kind: 'session_summary',
+        sessionId: targetSession,
+        summaryRef: 'sum_test',
+        at: new Date('2026-04-17T00:00:00Z'),
+    };
+}
+/**
+ * Build a loader that walks a pre-configured chain. `chain[i]` is the node
+ * returned for the i'th step (keyed by the session id the previous step
+ * targeted). `nodesBySession` keys the loader by `sessionId`.
+ */
+function buildLoader(nodes) {
+    const map = new Map();
+    for (const n of nodes) {
+        map.set(n.bySession, {
+            subSessionId: n.subSessionId,
+            sessionId: n.sessionId,
+            ...(n.prevArtifactRef !== undefined && { prevArtifactRef: n.prevArtifactRef }),
+        });
+    }
+    return {
+        loadAncestor: async (sid) => map.get(sid) ?? null,
+    };
+}
+describe('validatePrevArtifactChain', () => {
+    it('accepts a depth-1 chain (direct parent only)', async () => {
+        const loader = buildLoader([
+            {
+                bySession: sessionId(1),
+                subSessionId: subId(1),
+                sessionId: sessionId(1),
+                // No prevArtifactRef — chain terminates here.
+            },
+        ]);
+        const chain = await validatePrevArtifactChain(loader, subId(100), summaryDeliverable(sessionId(1)), 10);
+        expect(chain).toEqual([subId(1)]);
+    });
+    it('accepts a depth-2 chain', async () => {
+        const loader = buildLoader([
+            {
+                bySession: sessionId(1),
+                subSessionId: subId(1),
+                sessionId: sessionId(1),
+                prevArtifactRef: summaryDeliverable(sessionId(2)),
+            },
+            {
+                bySession: sessionId(2),
+                subSessionId: subId(2),
+                sessionId: sessionId(2),
+            },
+        ]);
+        const chain = await validatePrevArtifactChain(loader, subId(100), summaryDeliverable(sessionId(1)), 10);
+        expect(chain).toEqual([subId(1), subId(2)]);
+    });
+    it('accepts a chain exactly at the depth limit', async () => {
+        // 10-deep chain with maxDepth = 10.
+        const nodes = [];
+        for (let i = 1; i <= 10; i++) {
+            nodes.push({
+                bySession: sessionId(i),
+                subSessionId: subId(i),
+                sessionId: sessionId(i),
+                ...(i < 10 && { prevArtifactRef: summaryDeliverable(sessionId(i + 1)) }),
+            });
+        }
+        const loader = buildLoader(nodes);
+        const chain = await validatePrevArtifactChain(loader, subId(100), summaryDeliverable(sessionId(1)), 10);
+        expect(chain).toHaveLength(10);
+    });
+    it('rejects a chain that would exceed the depth limit', async () => {
+        // 11-deep chain with maxDepth = 10.
+        const nodes = [];
+        for (let i = 1; i <= 11; i++) {
+            nodes.push({
+                bySession: sessionId(i),
+                subSessionId: subId(i),
+                sessionId: sessionId(i),
+                ...(i < 11 && { prevArtifactRef: summaryDeliverable(sessionId(i + 1)) }),
+            });
+        }
+        const loader = buildLoader(nodes);
+        await expect(validatePrevArtifactChain(loader, subId(100), summaryDeliverable(sessionId(1)), 10)).rejects.toBeInstanceOf(InterventionDepthExceeded);
+    });
+    it('rejects self-reference as a cycle', async () => {
+        // proposedChild's prev points at a node whose subSessionId == proposedChild.
+        const loader = buildLoader([
+            {
+                bySession: sessionId(1),
+                subSessionId: subId(100), // SAME id as proposedChild
+                sessionId: sessionId(1),
+            },
+        ]);
+        await expect(validatePrevArtifactChain(loader, subId(100), summaryDeliverable(sessionId(1)), 10)).rejects.toBeInstanceOf(ArtifactRefCycleError);
+    });
+    it('rejects a 2-cycle (A -> B -> A)', async () => {
+        const loader = buildLoader([
+            {
+                bySession: sessionId(1),
+                subSessionId: subId(1),
+                sessionId: sessionId(1),
+                prevArtifactRef: summaryDeliverable(sessionId(2)),
+            },
+            {
+                bySession: sessionId(2),
+                subSessionId: subId(2),
+                sessionId: sessionId(2),
+                prevArtifactRef: summaryDeliverable(sessionId(1)),
+            },
+        ]);
+        await expect(validatePrevArtifactChain(loader, subId(100), summaryDeliverable(sessionId(1)), 10)).rejects.toBeInstanceOf(ArtifactRefCycleError);
+    });
+    it('rejects a 3-cycle (A -> B -> C -> A)', async () => {
+        const loader = buildLoader([
+            {
+                bySession: sessionId(1),
+                subSessionId: subId(1),
+                sessionId: sessionId(1),
+                prevArtifactRef: summaryDeliverable(sessionId(2)),
+            },
+            {
+                bySession: sessionId(2),
+                subSessionId: subId(2),
+                sessionId: sessionId(2),
+                prevArtifactRef: summaryDeliverable(sessionId(3)),
+            },
+            {
+                bySession: sessionId(3),
+                subSessionId: subId(3),
+                sessionId: sessionId(3),
+                prevArtifactRef: summaryDeliverable(sessionId(1)),
+            },
+        ]);
+        await expect(validatePrevArtifactChain(loader, subId(100), summaryDeliverable(sessionId(1)), 10)).rejects.toBeInstanceOf(ArtifactRefCycleError);
+    });
+    it('returns an empty chain for a non-session_summary deliverable', async () => {
+        const fileRef = {
+            id: 'del_file',
+            kind: 'file',
+            path: 'a.txt',
+            contentHash: 'abc',
+            sizeBytes: 0,
+        };
+        const loader = {
+            loadAncestor: async () => null,
+        };
+        const chain = await validatePrevArtifactChain(loader, subId(100), fileRef, 10);
+        expect(chain).toEqual([]);
+    });
+    it('terminates cleanly on unknown ancestor (archived/tombstoned)', async () => {
+        const loader = buildLoader([
+        // no matching node — loadAncestor returns null for any id
+        ]);
+        const chain = await validatePrevArtifactChain(loader, subId(100), summaryDeliverable(sessionId(42)), 10);
+        expect(chain).toEqual([]);
+    });
+    it('rejects zero/negative maxDepth as depth-exceeded up front', async () => {
+        const loader = buildLoader([
+            {
+                bySession: sessionId(1),
+                subSessionId: subId(1),
+                sessionId: sessionId(1),
+            },
+        ]);
+        await expect(validatePrevArtifactChain(loader, subId(100), summaryDeliverable(sessionId(1)), 0)).rejects.toBeInstanceOf(InterventionDepthExceeded);
+    });
+});
+//# sourceMappingURL=prev-artifact.test.js.map

package/dist/session/intervention/__tests__/prev-artifact.test.js.map

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

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

@@ -0,0 +1,3 @@
+export { ArtifactRefCycleError, InterventionDepthExceeded, validatePrevArtifactChain, } from './prev-artifact.js';
+export type { InterventionChainLoader, PrevArtifactNode, } from './prev-artifact.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/session/intervention/index.ts"],"names":[],"mappings":"AAOA,OAAO,EACN,qBAAqB,EACrB,yBAAyB,EACzB,yBAAyB,GACzB,MAAM,oBAAoB,CAAA;AAC3B,YAAY,EACX,uBAAuB,EACvB,gBAAgB,GAChB,MAAM,oBAAoB,CAAA"}

package/dist/session/intervention/index.js

@@ -0,0 +1,8 @@
+// Sub-barrel for the intervention DAG module (Convention #4).
+//
+// See session-hierarchy.md §4.5 — intervention chains via `prevArtifactRef`
+// form a strict acyclic DAG capped by
+// `Project.config.maxInterventionDepth`. This module owns the pre-commit
+// validator + typed errors; sub-session wiring is Phase 6.
+export { ArtifactRefCycleError, InterventionDepthExceeded, validatePrevArtifactChain, } from './prev-artifact.js';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/session/intervention/index.ts"],"names":[],"mappings":"AAAA,8DAA8D;AAC9D,EAAE;AACF,4EAA4E;AAC5E,sCAAsC;AACtC,yEAAyE;AACzE,2DAA2D;AAE3D,OAAO,EACN,qBAAqB,EACrB,yBAAyB,EACzB,yBAAyB,GACzB,MAAM,oBAAoB,CAAA"}

package/dist/session/intervention/prev-artifact.d.ts

@@ -0,0 +1,103 @@
+/**
+ * prevArtifactRef DAG primitives — acyclic walker, cycle detection, depth
+ * enforcement. See session-hierarchy.md §4.5.
+ *
+ * Intervention chains link successive follow-up sub-sessions via
+ * `SubSession.prevArtifactRef`, forming a strict acyclic DAG over prior
+ * completed sessions. This module supplies the pre-commit validator that
+ * rejects any insertion that would close a cycle or overflow
+ * {@link Project.config.maxInterventionDepth} (default 10).
+ *
+ * Convention #5: deny-by-default. Cycle or depth violation rejects with a
+ * typed error; callers never get a silently-truncated chain.
+ *
+ * Convention #0: no silent fallbacks. The walker surfaces corruption as
+ * `ArtifactRefCycleError` rather than infinite-looping.
+ */
+import type { SessionId } from '../../types/ids/index.js';
+import type { SubSessionId } from '../../types/session/ids.js';
+import type { DeliverableRef } from '../summary/deliverable.js';
+/**
+ * Minimal record the validator needs to step ancestrally from one
+ * sub-session to its predecessor. Concrete stores provide this projection.
+ *
+ * `sessionId` is the completed session this node represents (the one the
+ * incoming {@link DeliverableRef} pointed at). `subSessionId` is its own
+ * sub-session edge id — used for the visited-set so intervention chains form
+ * an acyclic DAG over sub-session identities.
+ */
+export interface PrevArtifactNode {
+    readonly subSessionId: SubSessionId;
+    readonly sessionId: SessionId;
+    readonly prevArtifactRef?: DeliverableRef;
+}
+/**
+ * Raised when {@link validatePrevArtifactChain} detects a cycle — revisiting
+ * a sub-session id already in the ancestry set. Indicates a bug in the caller
+ * (or pre-existing store corruption); the write must be rejected.
+ */
+export declare class ArtifactRefCycleError extends Error {
+    readonly details: {
+        readonly startSubSessionId: SubSessionId;
+        readonly cyclePath: readonly SubSessionId[];
+    };
+    constructor(details: {
+        startSubSessionId: SubSessionId;
+        cyclePath: readonly SubSessionId[];
+    });
+}
+/**
+ * Raised when the resolved chain length exceeds the configured intervention
+ * depth limit (`Project.config.maxInterventionDepth`). Convention #5
+ * deny-by-default — the kernel does not auto-truncate.
+ */
+export declare class InterventionDepthExceeded extends Error {
+    readonly details: {
+        readonly subSessionId: SubSessionId;
+        readonly depth: number;
+        readonly limit: number;
+    };
+    constructor(details: {
+        subSessionId: SubSessionId;
+        depth: number;
+        limit: number;
+    });
+}
+/**
+ * Loader surface the validator queries to walk ancestry. Returning `null`
+ * means "no further ancestor" — the chain terminates cleanly. The loader is
+ * injected so tests can fake a chain without standing up a full
+ * {@link SessionStore}.
+ */
+export interface InterventionChainLoader {
+    /**
+     * Resolves the ancestor node for the supplied {@link SessionId} — the
+     * session that the last step's `SessionSummaryDeliverable.sessionId` named.
+     * Returns `null` when no sub-session edge exists for that session (root
+     * session, or an archived/tombstoned ancestor — see §12.3).
+     */
+    loadAncestor(sessionId: SessionId): Promise<PrevArtifactNode | null>;
+}
+/**
+ * Pre-commit validator for adding a `prevArtifactRef` on a proposed child
+ * sub-session. Walks from `candidateAncestor` backwards through
+ * `loader.loadAncestor`, seeding the visited-set with `proposedChild` so a
+ * cycle (the candidate chain loops back to the child) is rejected
+ * immediately.
+ *
+ * Returns the resolved ancestry chain (oldest last, length ≤ `maxDepth`),
+ * excluding `proposedChild` itself. The chain is ordered from
+ * immediate-ancestor to furthest-ancestor (reverse-chronological per §4.5).
+ *
+ * Throws:
+ * - {@link ArtifactRefCycleError} if the walk revisits `proposedChild` or
+ *   any already-visited ancestor.
+ * - {@link InterventionDepthExceeded} if the chain would exceed `maxDepth`.
+ *
+ * Non-session_summary deliverables (file / message / artifact_blob) do not
+ * form chain links — the walker terminates cleanly when it encounters one,
+ * since only `kind: 'session_summary'` references another sub-session's
+ * ancestry.
+ */
+export declare function validatePrevArtifactChain(loader: InterventionChainLoader, proposedChild: SubSessionId, candidateAncestor: DeliverableRef, maxDepth: number): Promise<readonly SubSessionId[]>;
+//# sourceMappingURL=prev-artifact.d.ts.map

package/dist/session/intervention/prev-artifact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prev-artifact.d.ts","sourceRoot":"","sources":["../../../src/session/intervention/prev-artifact.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAA;AACzD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAA;AAC9D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAA;AAE/D;;;;;;;;GAQG;AACH,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAA;IACnC,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAA;IAC7B,QAAQ,CAAC,eAAe,CAAC,EAAE,cAAc,CAAA;CACzC;AAED;;;;GAIG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAC/C,QAAQ,CAAC,OAAO,EAAE;QACjB,QAAQ,CAAC,iBAAiB,EAAE,YAAY,CAAA;QACxC,QAAQ,CAAC,SAAS,EAAE,SAAS,YAAY,EAAE,CAAA;KAC3C,CAAA;gBAEW,OAAO,EAAE;QACpB,iBAAiB,EAAE,YAAY,CAAA;QAC/B,SAAS,EAAE,SAAS,YAAY,EAAE,CAAA;KAClC;CAOD;AAED;;;;GAIG;AACH,qBAAa,yBAA0B,SAAQ,KAAK;IACnD,QAAQ,CAAC,OAAO,EAAE;QACjB,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAA;QACnC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;QACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KACtB,CAAA;gBAEW,OAAO,EAAE;QAAE,YAAY,EAAE,YAAY,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE;CAOjF;AAED;;;;;GAKG;AACH,MAAM,WAAW,uBAAuB;IACvC;;;;;OAKG;IACH,YAAY,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAA;CACpE;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,yBAAyB,CAC9C,MAAM,EAAE,uBAAuB,EAC/B,aAAa,EAAE,YAAY,EAC3B,iBAAiB,EAAE,cAAc,EACjC,QAAQ,EAAE,MAAM,GACd,OAAO,CAAC,SAAS,YAAY,EAAE,CAAC,CAyDlC"}

package/dist/session/intervention/prev-artifact.js

@@ -0,0 +1,112 @@
+/**
+ * prevArtifactRef DAG primitives — acyclic walker, cycle detection, depth
+ * enforcement. See session-hierarchy.md §4.5.
+ *
+ * Intervention chains link successive follow-up sub-sessions via
+ * `SubSession.prevArtifactRef`, forming a strict acyclic DAG over prior
+ * completed sessions. This module supplies the pre-commit validator that
+ * rejects any insertion that would close a cycle or overflow
+ * {@link Project.config.maxInterventionDepth} (default 10).
+ *
+ * Convention #5: deny-by-default. Cycle or depth violation rejects with a
+ * typed error; callers never get a silently-truncated chain.
+ *
+ * Convention #0: no silent fallbacks. The walker surfaces corruption as
+ * `ArtifactRefCycleError` rather than infinite-looping.
+ */
+/**
+ * Raised when {@link validatePrevArtifactChain} detects a cycle — revisiting
+ * a sub-session id already in the ancestry set. Indicates a bug in the caller
+ * (or pre-existing store corruption); the write must be rejected.
+ */
+export class ArtifactRefCycleError extends Error {
+    details;
+    constructor(details) {
+        super(`prevArtifactRef cycle starting at ${details.startSubSessionId}: ${details.cyclePath.join(' -> ')}`);
+        this.name = 'ArtifactRefCycleError';
+        this.details = details;
+    }
+}
+/**
+ * Raised when the resolved chain length exceeds the configured intervention
+ * depth limit (`Project.config.maxInterventionDepth`). Convention #5
+ * deny-by-default — the kernel does not auto-truncate.
+ */
+export class InterventionDepthExceeded extends Error {
+    details;
+    constructor(details) {
+        super(`Intervention chain depth ${details.depth} exceeds limit ${details.limit} at ${details.subSessionId}`);
+        this.name = 'InterventionDepthExceeded';
+        this.details = details;
+    }
+}
+/**
+ * Pre-commit validator for adding a `prevArtifactRef` on a proposed child
+ * sub-session. Walks from `candidateAncestor` backwards through
+ * `loader.loadAncestor`, seeding the visited-set with `proposedChild` so a
+ * cycle (the candidate chain loops back to the child) is rejected
+ * immediately.
+ *
+ * Returns the resolved ancestry chain (oldest last, length ≤ `maxDepth`),
+ * excluding `proposedChild` itself. The chain is ordered from
+ * immediate-ancestor to furthest-ancestor (reverse-chronological per §4.5).
+ *
+ * Throws:
+ * - {@link ArtifactRefCycleError} if the walk revisits `proposedChild` or
+ *   any already-visited ancestor.
+ * - {@link InterventionDepthExceeded} if the chain would exceed `maxDepth`.
+ *
+ * Non-session_summary deliverables (file / message / artifact_blob) do not
+ * form chain links — the walker terminates cleanly when it encounters one,
+ * since only `kind: 'session_summary'` references another sub-session's
+ * ancestry.
+ */
+export async function validatePrevArtifactChain(loader, proposedChild, candidateAncestor, maxDepth) {
+    if (maxDepth <= 0) {
+        throw new InterventionDepthExceeded({
+            subSessionId: proposedChild,
+            depth: 1,
+            limit: maxDepth,
+        });
+    }
+    // Non-session_summary refs are leaves — no chain links.
+    if (candidateAncestor.kind !== 'session_summary') {
+        return [];
+    }
+    const visited = new Set([proposedChild]);
+    const chain = [];
+    let currentRef = candidateAncestor;
+    while (currentRef !== undefined) {
+        if (currentRef.kind !== 'session_summary') {
+            // Chain terminates on non-session deliverable.
+            return chain;
+        }
+        // `SessionSummaryDeliverable.sessionId` names the completed session the
+        // ref points at. The loader resolves that to the sub-session edge
+        // carrying its own `prevArtifactRef` (if any), giving us the next step.
+        const ancestorNode = await loader.loadAncestor(currentRef.sessionId);
+        if (!ancestorNode) {
+            // Unknown ancestor (root session, or archived / tombstoned). Chain
+            // ends cleanly — absence is not a cycle.
+            return chain;
+        }
+        if (visited.has(ancestorNode.subSessionId)) {
+            throw new ArtifactRefCycleError({
+                startSubSessionId: proposedChild,
+                cyclePath: [...chain, ancestorNode.subSessionId],
+            });
+        }
+        visited.add(ancestorNode.subSessionId);
+        chain.push(ancestorNode.subSessionId);
+        if (chain.length > maxDepth) {
+            throw new InterventionDepthExceeded({
+                subSessionId: proposedChild,
+                depth: chain.length,
+                limit: maxDepth,
+            });
+        }
+        currentRef = ancestorNode.prevArtifactRef;
+    }
+    return chain;
+}
+//# sourceMappingURL=prev-artifact.js.map