@namzu/sdk 0.1.8 → 0.3.0

package/dist/session/retention/archive-backend-ref.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Branded lookup identifier for an archived sub-session in a pluggable
+ * {@link ArchiveBackend}. Produced by
+ * {@link ArchiveBackend.store} on a successful archival write and consumed by
+ * {@link ArchiveBackend.restore} to re-hydrate the bundle.
+ *
+ * Follows Convention #2 (`<prefix>_<opaque>` template literal brand). Prefix
+ * chosen as `arc_` to match the `archive` domain — short, unambiguous, and
+ * distinct from every existing prefix (`prj_`, `ses_`, `sub_`, `sum_`, …).
+ *
+ * The string after the prefix is opaque — backend-specific. A disk backend
+ * embeds it in a directory path; an object-store backend may encode a key;
+ * callers MUST NOT parse or pattern-match beyond the brand check.
+ *
+ * See session-hierarchy.md §12.3 Retention and Archival.
+ */
+export type ArchiveBackendRef = `arc_${string}`;
+//# sourceMappingURL=archive-backend-ref.d.ts.map

package/dist/session/retention/archive-backend-ref.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"archive-backend-ref.d.ts","sourceRoot":"","sources":["../../../src/session/retention/archive-backend-ref.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,iBAAiB,GAAG,OAAO,MAAM,EAAE,CAAA"}

package/dist/session/retention/archive-backend-ref.js

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

package/dist/session/retention/archive-backend-ref.js.map

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

package/dist/session/retention/archive.d.ts

@@ -0,0 +1,130 @@
+/**
+ * ArchivalManager — on-demand archival primitive for sub-sessions. Pattern
+ * doc §12.3 (Retention and Archival).
+ *
+ * Convention #9 (Registry + Manager + Store): Manager-shape with explicit
+ * deps for the {@link SessionStore}, {@link WorkspaceBackendRegistry}, and a
+ * pluggable {@link ArchiveBackend}. Convention #5 deny-by-default: absent
+ * backend → {@link ArchiveNotConfiguredError} on every `archive()` call.
+ *
+ * Atomic invariant (pattern doc §12.3):
+ *
+ *   1. Read sub-session + owning session + messages + optional summary
+ *   2. backend.store(bundle) — archive durability confirmed
+ *   3. Flip sub-session to `status: 'archived'` + attach archiveRef/archivedAt
+ *   4. Workspace driver dispose (idempotent)
+ *
+ * Step 2 is the durability boundary: if the process crashes between step 2
+ * and step 3, the archive exists but the live record is still non-archived
+ * — recovery is to re-invoke `archive()`, which sees a non-terminal status
+ * and replays. Step 3 is the single point of no return.
+ *
+ * A completed archive leaves the sub-session in-place with `status:
+ * 'archived'` + an attached `archiveRef`. Pattern doc §12.3 calls this the
+ * tombstone: `SessionStore.drill` still finds it through the normal linkage
+ * path, so the archive is navigable without a parallel index.
+ */
+import type { SubSessionId, TenantId } from '../../types/ids/index.js';
+import type { WorkspaceId } from '../../types/session/ids.js';
+import type { SessionStore } from '../../types/session/store.js';
+import type { WorkspaceRef } from '../workspace/ref.js';
+import type { WorkspaceBackendRegistry } from '../workspace/registry.js';
+import type { ArchiveBackend, SubSessionTombstone } from './backend.js';
+/**
+ * Raised when {@link ArchivalManager.archive} or {@link ArchivalManager.restore}
+ * is invoked against a project whose retention policy does not supply an
+ * {@link ArchiveBackend}. Convention #5 — explicit error rather than silent
+ * no-op.
+ */
+export declare class ArchiveNotConfiguredError extends Error {
+    constructor();
+}
+/**
+ * Raised when {@link ArchivalManager.archive} targets a sub-session that is
+ * not eligible for archival. The three reasons map to pattern doc §12.3
+ * (archival only applies to idle / merged / rejected / failed sub-sessions).
+ */
+export declare class SubSessionNotArchivableError extends Error {
+    readonly details: {
+        readonly subSessionId: SubSessionId;
+        readonly reason: 'not_idle' | 'already_archived' | 'missing';
+    };
+    constructor(details: {
+        subSessionId: SubSessionId;
+        reason: 'not_idle' | 'already_archived' | 'missing';
+    });
+}
+/**
+ * Raised when {@link ArchivalManager.restore} is called against a
+ * sub-session that is not currently archived. Distinct from
+ * {@link SubSessionNotArchivableError} because the semantics are inverted:
+ * restore requires an archived record, archive rejects one.
+ */
+export declare class SubSessionNotArchivedError extends Error {
+    readonly details: {
+        readonly subSessionId: SubSessionId;
+        readonly reason: 'not_archived' | 'missing' | 'missing_archive_ref';
+    };
+    constructor(details: {
+        subSessionId: SubSessionId;
+        reason: 'not_archived' | 'missing' | 'missing_archive_ref';
+    });
+}
+/**
+ * Lookup callback resolving a live {@link WorkspaceRef} from the id stored
+ * on a {@link SubSession}. Injected by the caller because Phase 8 does not
+ * ship a dedicated workspace store — the ref typically lives in a handoff
+ * assignment or is held by the agent lifecycle manager. Return `null` when
+ * the ref is unknown or already disposed; the manager archives without
+ * workspace data in that case (the disk backend allows it).
+ */
+export type WorkspaceResolver = (workspaceId: WorkspaceId, tenantId: TenantId) => Promise<WorkspaceRef | null>;
+export interface ArchivalManagerDeps {
+    readonly sessionStore: SessionStore;
+    readonly workspaceRegistry: WorkspaceBackendRegistry;
+    /**
+     * Archive backend. Absent = archival disabled for this manager
+     * (`archive()`/`restore()` throw {@link ArchiveNotConfiguredError}).
+     */
+    readonly archiveBackend?: ArchiveBackend;
+    /**
+     * Optional workspace resolver. When absent, `archive()` skips workspace
+     * snapshotting (only the ref would be captured) and workspace disposal
+     * (nothing to dispose). This is the conservative default and matches
+     * pattern doc §7.1 (lazy workspace provisioning).
+     */
+    readonly workspaceResolver?: WorkspaceResolver;
+    /**
+     * Optional logger hook for `sub_session.archived` emission. Pattern doc
+     * §12.3 requires the event; full event-bus wiring is a platform concern
+     * (a later phase of the roadmap). Phase 8 ships the log seam so tests
+     * can observe without the bus.
+     */
+    readonly onArchived?: (tombstone: SubSessionTombstone) => void;
+    readonly onRestored?: (subSessionId: SubSessionId, tenantId: TenantId) => void;
+}
+export declare class ArchivalManager {
+    private readonly deps;
+    constructor(deps: ArchivalManagerDeps);
+    /**
+     * Archive an eligible sub-session. See module header for the atomic
+     * invariant and recovery semantics.
+     *
+     * Returns the {@link SubSessionTombstone} shape — the same identity +
+     * archive fields the store now carries on the live record.
+     */
+    archive(subSessionId: SubSessionId, tenantId: TenantId): Promise<SubSessionTombstone>;
+    /**
+     * Reverse of {@link archive}. Reads the tombstone, invokes
+     * `backend.restore`, then flips the sub-session back to `idle`. Does NOT
+     * re-materialize the workspace — the caller decides whether to
+     * re-provision via a {@link WorkspaceBackendDriver}.
+     *
+     * The restored `ArchiveInput` bundle is NOT returned here because the
+     * concrete pattern in Phase 8 is "flip status and make navigable again";
+     * consumers that need the bundle itself can call the backend directly.
+     */
+    restore(subSessionId: SubSessionId, tenantId: TenantId): Promise<void>;
+    private requireBackend;
+}
+//# sourceMappingURL=archive.d.ts.map

package/dist/session/retention/archive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"archive.d.ts","sourceRoot":"","sources":["../../../src/session/retention/archive.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAa,YAAY,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAA;AACjF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAA;AAC7D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAA;AAEhE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AACvD,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAA;AACxE,OAAO,KAAK,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAA;AAEvE;;;;;GAKG;AACH,qBAAa,yBAA0B,SAAQ,KAAK;;CAKnD;AAED;;;;GAIG;AACH,qBAAa,4BAA6B,SAAQ,KAAK;IACtD,QAAQ,CAAC,OAAO,EAAE;QACjB,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAA;QACnC,QAAQ,CAAC,MAAM,EAAE,UAAU,GAAG,kBAAkB,GAAG,SAAS,CAAA;KAC5D,CAAA;gBAEW,OAAO,EAAE;QACpB,YAAY,EAAE,YAAY,CAAA;QAC1B,MAAM,EAAE,UAAU,GAAG,kBAAkB,GAAG,SAAS,CAAA;KACnD;CAKD;AAED;;;;;GAKG;AACH,qBAAa,0BAA2B,SAAQ,KAAK;IACpD,QAAQ,CAAC,OAAO,EAAE;QACjB,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAA;QACnC,QAAQ,CAAC,MAAM,EAAE,cAAc,GAAG,SAAS,GAAG,qBAAqB,CAAA;KACnE,CAAA;gBAEW,OAAO,EAAE;QACpB,YAAY,EAAE,YAAY,CAAA;QAC1B,MAAM,EAAE,cAAc,GAAG,SAAS,GAAG,qBAAqB,CAAA;KAC1D;CAKD;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAC/B,WAAW,EAAE,WAAW,EACxB,QAAQ,EAAE,QAAQ,KACd,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAAA;AAejC,MAAM,WAAW,mBAAmB;IACnC,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAA;IACnC,QAAQ,CAAC,iBAAiB,EAAE,wBAAwB,CAAA;IACpD;;;OAGG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,cAAc,CAAA;IACxC;;;;;OAKG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,iBAAiB,CAAA;IAC9C;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,SAAS,EAAE,mBAAmB,KAAK,IAAI,CAAA;IAC9D,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,YAAY,EAAE,YAAY,EAAE,QAAQ,EAAE,QAAQ,KAAK,IAAI,CAAA;CAC9E;AAED,qBAAa,eAAe;IAC3B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAqB;gBAE9B,IAAI,EAAE,mBAAmB;IAIrC;;;;;;OAMG;IACG,OAAO,CAAC,YAAY,EAAE,YAAY,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,mBAAmB,CAAC;IA+E3F;;;;;;;;;OASG;IACG,OAAO,CAAC,YAAY,EAAE,YAAY,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IA8B5E,OAAO,CAAC,cAAc;CAKtB"}

package/dist/session/retention/archive.js

@@ -0,0 +1,203 @@
+/**
+ * ArchivalManager — on-demand archival primitive for sub-sessions. Pattern
+ * doc §12.3 (Retention and Archival).
+ *
+ * Convention #9 (Registry + Manager + Store): Manager-shape with explicit
+ * deps for the {@link SessionStore}, {@link WorkspaceBackendRegistry}, and a
+ * pluggable {@link ArchiveBackend}. Convention #5 deny-by-default: absent
+ * backend → {@link ArchiveNotConfiguredError} on every `archive()` call.
+ *
+ * Atomic invariant (pattern doc §12.3):
+ *
+ *   1. Read sub-session + owning session + messages + optional summary
+ *   2. backend.store(bundle) — archive durability confirmed
+ *   3. Flip sub-session to `status: 'archived'` + attach archiveRef/archivedAt
+ *   4. Workspace driver dispose (idempotent)
+ *
+ * Step 2 is the durability boundary: if the process crashes between step 2
+ * and step 3, the archive exists but the live record is still non-archived
+ * — recovery is to re-invoke `archive()`, which sees a non-terminal status
+ * and replays. Step 3 is the single point of no return.
+ *
+ * A completed archive leaves the sub-session in-place with `status:
+ * 'archived'` + an attached `archiveRef`. Pattern doc §12.3 calls this the
+ * tombstone: `SessionStore.drill` still finds it through the normal linkage
+ * path, so the archive is navigable without a parallel index.
+ */
+/**
+ * Raised when {@link ArchivalManager.archive} or {@link ArchivalManager.restore}
+ * is invoked against a project whose retention policy does not supply an
+ * {@link ArchiveBackend}. Convention #5 — explicit error rather than silent
+ * no-op.
+ */
+export class ArchiveNotConfiguredError extends Error {
+    constructor() {
+        super('Retention archival not configured for this project (Convention #5: deny-by-default)');
+        this.name = 'ArchiveNotConfiguredError';
+    }
+}
+/**
+ * Raised when {@link ArchivalManager.archive} targets a sub-session that is
+ * not eligible for archival. The three reasons map to pattern doc §12.3
+ * (archival only applies to idle / merged / rejected / failed sub-sessions).
+ */
+export class SubSessionNotArchivableError extends Error {
+    details;
+    constructor(details) {
+        super(`Sub-session ${details.subSessionId} not archivable: ${details.reason}`);
+        this.name = 'SubSessionNotArchivableError';
+        this.details = details;
+    }
+}
+/**
+ * Raised when {@link ArchivalManager.restore} is called against a
+ * sub-session that is not currently archived. Distinct from
+ * {@link SubSessionNotArchivableError} because the semantics are inverted:
+ * restore requires an archived record, archive rejects one.
+ */
+export class SubSessionNotArchivedError extends Error {
+    details;
+    constructor(details) {
+        super(`Sub-session ${details.subSessionId} cannot be restored: ${details.reason}`);
+        this.name = 'SubSessionNotArchivedError';
+        this.details = details;
+    }
+}
+/**
+ * Sub-session statuses eligible for archival. Pattern doc §12.3 speaks of
+ * "idle" broadly; we honor the enumerated terminal-like states. Anything
+ * else (active / pending / in-flight merge) rejects with
+ * `'not_idle'`.
+ */
+const ARCHIVABLE_STATUSES = new Set([
+    'idle',
+    'merged',
+    'merge_rejected',
+    'failed',
+]);
+export class ArchivalManager {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /**
+     * Archive an eligible sub-session. See module header for the atomic
+     * invariant and recovery semantics.
+     *
+     * Returns the {@link SubSessionTombstone} shape — the same identity +
+     * archive fields the store now carries on the live record.
+     */
+    async archive(subSessionId, tenantId) {
+        const backend = this.requireBackend();
+        // 1. Resolve + validate sub-session.
+        const sub = await this.deps.sessionStore.getSubSession(subSessionId, tenantId);
+        if (!sub) {
+            throw new SubSessionNotArchivableError({ subSessionId, reason: 'missing' });
+        }
+        if (sub.status === 'archived') {
+            throw new SubSessionNotArchivableError({ subSessionId, reason: 'already_archived' });
+        }
+        if (!ARCHIVABLE_STATUSES.has(sub.status)) {
+            throw new SubSessionNotArchivableError({ subSessionId, reason: 'not_idle' });
+        }
+        // 2. Load owning child session bundle (messages + optional summary).
+        // Phase 9 Known Delta #7: uses `loadSessionMessages` for full-fidelity
+        // round-trip (original MessageId + timestamp preserved). Previously
+        // the Phase 8 archivalmanager synthesized `msg_restored_N` IDs from the
+        // payload-only `loadMessages` return — that lossy reshape is gone.
+        const childSessionId = sub.childSessionId;
+        const messages = await this.deps.sessionStore.loadSessionMessages(childSessionId, tenantId);
+        const summaryRefOrNull = await this.deps.sessionStore.getSummary(childSessionId, tenantId);
+        const summaryRef = summaryRefOrNull ?? undefined;
+        // 3. Resolve optional live workspace ref.
+        let workspace;
+        if (sub.workspaceId && this.deps.workspaceResolver) {
+            const resolved = await this.deps.workspaceResolver(sub.workspaceId, tenantId);
+            if (resolved)
+                workspace = resolved;
+        }
+        // 4. Durability boundary: persist the archive bundle.
+        const bundleOut = await backend.store({
+            subSessionId: sub.id,
+            sessionId: childSessionId,
+            tenantId,
+            ...(workspace !== undefined && { workspace }),
+            ...(summaryRef !== undefined && { summaryRef }),
+            messages,
+        });
+        // 5. Point-of-no-return: flip sub-session to archived + attach ref.
+        const archived = {
+            ...sub,
+            status: 'archived',
+            archiveRef: bundleOut.archiveRef,
+            archivedAt: bundleOut.archivedAt,
+        };
+        await this.deps.sessionStore.updateSubSession(archived, tenantId);
+        // 6. Dispose the workspace (idempotent — driver contract tolerates
+        //    already-disposed refs; a missing ref is a no-op).
+        if (workspace) {
+            try {
+                const driver = this.deps.workspaceRegistry.get(workspace.meta.backend);
+                await driver.dispose(workspace);
+            }
+            catch {
+                // Idempotent — a secondary failure here must not unwind the
+                // already-committed archive. Pattern doc §12.3: workspace
+                // disposal is a cleanup operation, not part of the atomic
+                // archive envelope.
+            }
+        }
+        const tombstone = {
+            subSessionId: sub.id,
+            sessionId: childSessionId,
+            tenantId,
+            ...(sub.summaryRef !== undefined && { summaryRef: sub.summaryRef }),
+            archiveRef: bundleOut.archiveRef,
+            archivedAt: bundleOut.archivedAt,
+        };
+        this.deps.onArchived?.(tombstone);
+        return tombstone;
+    }
+    /**
+     * Reverse of {@link archive}. Reads the tombstone, invokes
+     * `backend.restore`, then flips the sub-session back to `idle`. Does NOT
+     * re-materialize the workspace — the caller decides whether to
+     * re-provision via a {@link WorkspaceBackendDriver}.
+     *
+     * The restored `ArchiveInput` bundle is NOT returned here because the
+     * concrete pattern in Phase 8 is "flip status and make navigable again";
+     * consumers that need the bundle itself can call the backend directly.
+     */
+    async restore(subSessionId, tenantId) {
+        const backend = this.requireBackend();
+        const sub = await this.deps.sessionStore.getSubSession(subSessionId, tenantId);
+        if (!sub) {
+            throw new SubSessionNotArchivedError({ subSessionId, reason: 'missing' });
+        }
+        if (sub.status !== 'archived') {
+            throw new SubSessionNotArchivedError({ subSessionId, reason: 'not_archived' });
+        }
+        if (!sub.archiveRef) {
+            throw new SubSessionNotArchivedError({ subSessionId, reason: 'missing_archive_ref' });
+        }
+        // Validate the archive ref by invoking the backend — this surfaces
+        // ArchiveNotFoundError up the stack if the bundle is missing or
+        // corrupt, rather than silently un-archiving an orphaned record.
+        await backend.restore(sub.archiveRef);
+        const restored = {
+            ...sub,
+            status: 'idle',
+            archiveRef: undefined,
+            archivedAt: undefined,
+        };
+        await this.deps.sessionStore.updateSubSession(restored, tenantId);
+        this.deps.onRestored?.(subSessionId, tenantId);
+    }
+    requireBackend() {
+        const backend = this.deps.archiveBackend;
+        if (!backend)
+            throw new ArchiveNotConfiguredError();
+        return backend;
+    }
+}
+//# sourceMappingURL=archive.js.map

package/dist/session/retention/archive.js.map

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

package/dist/session/retention/backend.d.ts

@@ -0,0 +1,101 @@
+/**
+ * ArchiveBackend — pluggable archival contract. See session-hierarchy.md
+ * §12.3 Retention and Archival.
+ *
+ * Convention #10 (Provider abstraction): interface lives here; concrete
+ * implementations (disk, s3, glacier, …) live in sibling files. Phase 8 ships
+ * the reference disk impl (`disk-backend.ts`); production deployments plug
+ * their own over the same surface.
+ *
+ * Convention #9 (Registry + Manager + Store): {@link ArchivalManager} is the
+ * Manager; this `ArchiveBackend` is the Provider slot it drives; the live
+ * `SessionStore` is the Store it mutates.
+ */
+import type { SessionMessage } from '../../store/session/messages.js';
+import type { SessionId, SubSessionId, TenantId } from '../../types/ids/index.js';
+import type { SummaryId } from '../../types/session/ids.js';
+import type { SessionSummaryRef } from '../summary/ref.js';
+import type { WorkspaceRef } from '../workspace/ref.js';
+import type { ArchiveBackendRef } from './archive-backend-ref.js';
+/**
+ * Output of a successful {@link ArchiveBackend.store} call. `archiveRef` is
+ * the opaque lookup key used by {@link ArchiveBackend.restore} to rehydrate
+ * the bundle.
+ */
+export interface ArchiveOutput {
+    readonly archiveRef: ArchiveBackendRef;
+    readonly archivedAt: Date;
+}
+/**
+ * Bundle handed to {@link ArchiveBackend.store} (and returned by
+ * {@link ArchiveBackend.restore}). Captures the minimum surface needed to
+ * re-hydrate a sub-session in the future — sub-session metadata plus the
+ * owning session's messages and optional summary.
+ */
+export interface ArchiveInput {
+    readonly subSessionId: SubSessionId;
+    /**
+     * The session the sub-session owns. Each sub-session wraps exactly one
+     * child {@link Session} (pattern doc §4.4); the archived bundle captures
+     * that session's messages and summary.
+     */
+    readonly sessionId: SessionId;
+    readonly tenantId: TenantId;
+    /**
+     * Present when the sub-session had a provisioned workspace at archive
+     * time. Absent for sub-sessions that never materialized one (pattern doc
+     * §7.1 allows lazy workspace provisioning).
+     */
+    readonly workspace?: WorkspaceRef;
+    readonly summaryRef?: SessionSummaryRef;
+    /**
+     * Full message log for the owning session. Captured at archive time;
+     * append-only discipline (pattern doc §13.4) means this is a complete
+     * snapshot, not a partial view.
+     */
+    readonly messages: readonly SessionMessage[];
+}
+/**
+ * Pluggable archival backend. Implementations MUST write atomically
+ * (Convention #8 — write-tmp-rename per file) and MUST produce a unique
+ * {@link ArchiveBackendRef} per call. Concurrent `store` calls with
+ * overlapping input are a caller error — the Manager serializes per
+ * sub-session.
+ */
+export interface ArchiveBackend {
+    /** Discriminator. Free-form; reference impl uses `'disk'`. */
+    readonly kind: string;
+    /**
+     * Persist the bundle. Returns the lookup ref consumers embed in the
+     * sub-session tombstone (§12.3). Must be atomic at the bundle level —
+     * post-success, a restore sees the full bundle or throws.
+     */
+    store(input: ArchiveInput): Promise<ArchiveOutput>;
+    /**
+     * Reverse of {@link store}. Throws when the ref does not resolve or when
+     * the bundle is corrupt. Does NOT re-materialize the workspace on disk —
+     * callers decide whether to re-provision via a
+     * {@link WorkspaceBackendDriver}.
+     */
+    restore(archiveRef: ArchiveBackendRef): Promise<ArchiveInput>;
+}
+/**
+ * The in-store marker a sub-session becomes after archival. Replaces the
+ * live record in-slot (see pattern doc §12.3): the sub-session's status
+ * flips to `'archived'` and `archiveRef` + `archivedAt` are attached. This
+ * way `SessionStore.drill` still finds it via the normal linkage path — the
+ * tombstone is navigable without a parallel index.
+ *
+ * Fields are a subset of {@link SubSession} — the identity columns plus the
+ * archive pointer — extracted here so consumers can destructure a tombstone
+ * view without carrying the full live-record shape.
+ */
+export interface SubSessionTombstone {
+    readonly subSessionId: SubSessionId;
+    readonly sessionId: SessionId;
+    readonly tenantId: TenantId;
+    readonly summaryRef?: SummaryId;
+    readonly archiveRef: ArchiveBackendRef;
+    readonly archivedAt: Date;
+}
+//# sourceMappingURL=backend.d.ts.map

package/dist/session/retention/backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../../../src/session/retention/backend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAA;AACrE,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAA;AACjF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAA;AAC3D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AAC1D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AACvD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAA;AAEjE;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC7B,QAAQ,CAAC,UAAU,EAAE,iBAAiB,CAAA;IACtC,QAAQ,CAAC,UAAU,EAAE,IAAI,CAAA;CACzB;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC5B,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAA;IACnC;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAA;IAC7B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAA;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,YAAY,CAAA;IACjC,QAAQ,CAAC,UAAU,CAAC,EAAE,iBAAiB,CAAA;IACvC;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,SAAS,cAAc,EAAE,CAAA;CAC5C;AAED;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC9B,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IAErB;;;;OAIG;IACH,KAAK,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,aAAa,CAAC,CAAA;IAElD;;;;;OAKG;IACH,OAAO,CAAC,UAAU,EAAE,iBAAiB,GAAG,OAAO,CAAC,YAAY,CAAC,CAAA;CAC7D;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,mBAAmB;IACnC,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAA;IACnC,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAA;IAC7B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAA;IAC3B,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,CAAA;IAC/B,QAAQ,CAAC,UAAU,EAAE,iBAAiB,CAAA;IACtC,QAAQ,CAAC,UAAU,EAAE,IAAI,CAAA;CACzB"}

package/dist/session/retention/backend.js

@@ -0,0 +1,15 @@
+/**
+ * ArchiveBackend — pluggable archival contract. See session-hierarchy.md
+ * §12.3 Retention and Archival.
+ *
+ * Convention #10 (Provider abstraction): interface lives here; concrete
+ * implementations (disk, s3, glacier, …) live in sibling files. Phase 8 ships
+ * the reference disk impl (`disk-backend.ts`); production deployments plug
+ * their own over the same surface.
+ *
+ * Convention #9 (Registry + Manager + Store): {@link ArchivalManager} is the
+ * Manager; this `ArchiveBackend` is the Provider slot it drives; the live
+ * `SessionStore` is the Store it mutates.
+ */
+export {};
+//# sourceMappingURL=backend.js.map

package/dist/session/retention/backend.js.map

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

package/dist/session/retention/disk-backend.d.ts

@@ -0,0 +1,59 @@
+/**
+ * DiskArchiveBackend — reference filesystem-backed {@link ArchiveBackend}.
+ *
+ * Convention #8 (atomic writes): every file lands via write-tmp-rename; the
+ * final `archive.json` marker is written LAST so a crash mid-bundle leaves
+ * the directory visible but UN-marked, and `restore` treats such a bundle
+ * as missing. This mirrors the Phase 5 materializer's "marker-last"
+ * invariant.
+ *
+ * Layout:
+ *
+ *   {rootDir}/archive/{arc_<opaque>}/
+ *     subsession.json        # Identity + metadata
+ *     summary.json            # SessionSummaryRef (optional — present iff input.summaryRef)
+ *     messages.jsonl          # One SessionMessage per line (append-style, serialized once)
+ *     workspace.json          # WorkspaceRef (optional — present iff input.workspace)
+ *     archive.json            # Marker — final write; presence = bundle committed
+ *
+ * Workspace directory contents are NOT archived — we persist the
+ * {@link WorkspaceRef} only. The pattern doc §12.3 explicitly allows this:
+ * the ref is the re-hydration handle; the worktree itself is disposed at
+ * archive time via the caller's {@link WorkspaceBackendDriver}, not copied
+ * into the archive bundle. This is a Phase 8 interpretation — see the
+ * roadmap deliverable report for rationale (tar bundling deferred).
+ *
+ * See session-hierarchy.md §12.3.
+ */
+import type { ArchiveBackendRef } from './archive-backend-ref.js';
+import type { ArchiveBackend, ArchiveInput, ArchiveOutput } from './backend.js';
+/**
+ * Raised when {@link DiskArchiveBackend.restore} cannot resolve the supplied
+ * ref — either the directory is missing, or the `archive.json` marker is
+ * absent (crash-mid-write signal).
+ */
+export declare class ArchiveNotFoundError extends Error {
+    readonly details: {
+        archiveRef: ArchiveBackendRef;
+        reason: 'missing' | 'incomplete';
+    };
+    constructor(details: {
+        archiveRef: ArchiveBackendRef;
+        reason: 'missing' | 'incomplete';
+    });
+}
+/**
+ * Config for {@link DiskArchiveBackend}. `rootDir` is absolute — bundles land
+ * under `{rootDir}/archive/`.
+ */
+export interface DiskArchiveBackendConfig {
+    readonly rootDir: string;
+}
+export declare class DiskArchiveBackend implements ArchiveBackend {
+    readonly kind = "disk";
+    private readonly rootDir;
+    constructor(config: DiskArchiveBackendConfig);
+    store(input: ArchiveInput): Promise<ArchiveOutput>;
+    restore(archiveRef: ArchiveBackendRef): Promise<ArchiveInput>;
+}
+//# sourceMappingURL=disk-backend.d.ts.map

package/dist/session/retention/disk-backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"disk-backend.d.ts","sourceRoot":"","sources":["../../../src/session/retention/disk-backend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AASH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAA;AACjE,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAE/E;;;;GAIG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;IAC9C,QAAQ,CAAC,OAAO,EAAE;QAAE,UAAU,EAAE,iBAAiB,CAAC;QAAC,MAAM,EAAE,SAAS,GAAG,YAAY,CAAA;KAAE,CAAA;gBAEzE,OAAO,EAAE;QAAE,UAAU,EAAE,iBAAiB,CAAC;QAAC,MAAM,EAAE,SAAS,GAAG,YAAY,CAAA;KAAE;CAKxF;AAED;;;GAGG;AACH,MAAM,WAAW,wBAAwB;IACxC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACxB;AA6BD,qBAAa,kBAAmB,YAAW,cAAc;IACxD,QAAQ,CAAC,IAAI,UAAS;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAQ;gBAEpB,MAAM,EAAE,wBAAwB;IAItC,KAAK,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,aAAa,CAAC;IAsDlD,OAAO,CAAC,UAAU,EAAE,iBAAiB,GAAG,OAAO,CAAC,YAAY,CAAC;CA4DnE"}