@namzu/sdk 0.1.7 → 0.2.0

package/dist/session/summary/deliverable.d.ts

@@ -0,0 +1,74 @@
+/**
+ * DeliverableRef — discriminated union of artifact types a completed
+ * sub-session may emit.
+ *
+ * Consumed by two surfaces:
+ *   1. `SessionSummaryRef.deliverables` — authoritative list of artifacts a
+ *      completed sub-session produced. See session-hierarchy.md §4.7.
+ *   2. `SubSession.prevArtifactRef` — intervention chains reference a prior
+ *      immutable artifact. See session-hierarchy.md §4.5, §8.1.
+ *
+ * The `session_summary` variant is what intervention sub-sessions use — a
+ * follow-up intervention points at the previous completed session's summary,
+ * forming a strict acyclic DAG validated by
+ * `session/intervention/prev-artifact.ts`.
+ *
+ * Convention #6: this is a discriminated union on `kind`; any consumer must
+ * handle all variants exhaustively.
+ */
+import type { RunId, SessionId } from '../../types/ids/index.js';
+import type { DeliverableId, SummaryId } from '../../types/session/ids.js';
+/** Discriminator for {@link DeliverableRef}. */
+export type DeliverableKind = 'file' | 'session_summary' | 'message' | 'artifact_blob';
+/**
+ * A file deliverable — a path relative to the workspace root, plus a content
+ * hash pinning the file to its state at materialize time. Subsequent edits to
+ * the file on disk do not mutate the deliverable; the ref is a snapshot.
+ */
+export interface FileDeliverable {
+    readonly id: DeliverableId;
+    readonly kind: 'file';
+    /** Path relative to the owning session's workspace root. */
+    readonly path: string;
+    /** sha256 of the file's content at materialize time. */
+    readonly contentHash: string;
+    readonly sizeBytes: number;
+}
+/**
+ * A pointer to a previously-materialized {@link SessionSummaryRef}. The
+ * intervention DAG uses this variant to reference the immutable output of a
+ * prior completed session.
+ */
+export interface SessionSummaryDeliverable {
+    readonly id: DeliverableId;
+    readonly kind: 'session_summary';
+    readonly sessionId: SessionId;
+    readonly summaryRef: SummaryId;
+    readonly at: Date;
+}
+/**
+ * A specific persisted message within a session run — useful for referencing
+ * a single LLM turn as an artifact (e.g. a decision record).
+ */
+export interface MessageDeliverable {
+    readonly id: DeliverableId;
+    readonly kind: 'message';
+    readonly sessionId: SessionId;
+    readonly runId: RunId;
+    /** Opaque identifier bound to the run's persisted message log. */
+    readonly messageId: string;
+}
+/**
+ * An opaque blob deliverable — content lives in an out-of-band storage
+ * backend (object store, artifact registry). The SDK does not fetch or
+ * validate blob contents; callers resolve via the `storageRef`.
+ */
+export interface ArtifactBlobDeliverable {
+    readonly id: DeliverableId;
+    readonly kind: 'artifact_blob';
+    /** Opaque — bound to a storage backend the consumer owns. */
+    readonly storageRef: string;
+    readonly mediaType?: string;
+}
+export type DeliverableRef = FileDeliverable | SessionSummaryDeliverable | MessageDeliverable | ArtifactBlobDeliverable;
+//# sourceMappingURL=deliverable.d.ts.map

package/dist/session/summary/deliverable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deliverable.d.ts","sourceRoot":"","sources":["../../../src/session/summary/deliverable.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAA;AAChE,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAA;AAE1E,gDAAgD;AAChD,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,iBAAiB,GAAG,SAAS,GAAG,eAAe,CAAA;AAEtF;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC/B,QAAQ,CAAC,EAAE,EAAE,aAAa,CAAA;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,4DAA4D;IAC5D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,wDAAwD;IACxD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAC1B;AAED;;;;GAIG;AACH,MAAM,WAAW,yBAAyB;IACzC,QAAQ,CAAC,EAAE,EAAE,aAAa,CAAA;IAC1B,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAA;IAChC,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAA;IAC7B,QAAQ,CAAC,UAAU,EAAE,SAAS,CAAA;IAC9B,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAA;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IAClC,QAAQ,CAAC,EAAE,EAAE,aAAa,CAAA;IAC1B,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;IACxB,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAA;IAC7B,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;IACrB,kEAAkE;IAClE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAC1B;AAED;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACvC,QAAQ,CAAC,EAAE,EAAE,aAAa,CAAA;IAC1B,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAA;IAC9B,6DAA6D;IAC7D,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAC3B;AAED,MAAM,MAAM,cAAc,GACvB,eAAe,GACf,yBAAyB,GACzB,kBAAkB,GAClB,uBAAuB,CAAA"}

package/dist/session/summary/deliverable.js

@@ -0,0 +1,20 @@
+/**
+ * DeliverableRef — discriminated union of artifact types a completed
+ * sub-session may emit.
+ *
+ * Consumed by two surfaces:
+ *   1. `SessionSummaryRef.deliverables` — authoritative list of artifacts a
+ *      completed sub-session produced. See session-hierarchy.md §4.7.
+ *   2. `SubSession.prevArtifactRef` — intervention chains reference a prior
+ *      immutable artifact. See session-hierarchy.md §4.5, §8.1.
+ *
+ * The `session_summary` variant is what intervention sub-sessions use — a
+ * follow-up intervention points at the previous completed session's summary,
+ * forming a strict acyclic DAG validated by
+ * `session/intervention/prev-artifact.ts`.
+ *
+ * Convention #6: this is a discriminated union on `kind`; any consumer must
+ * handle all variants exhaustively.
+ */
+export {};
+//# sourceMappingURL=deliverable.js.map

package/dist/session/summary/deliverable.js.map

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

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

@@ -0,0 +1,6 @@
+export type { ArtifactBlobDeliverable, DeliverableKind, DeliverableRef, FileDeliverable, MessageDeliverable, SessionSummaryDeliverable, } from './deliverable.js';
+export { AGENT_SUMMARY_MAX_CHARS, AgentSummaryTooLongError, SessionAlreadySummarizedError, } from './ref.js';
+export type { SessionSummaryKeyDecision, SessionSummaryOutcome, SessionSummaryOutcomeStatus, SessionSummaryRef, } from './ref.js';
+export { SessionSummaryMaterializer } from './materialize.js';
+export type { MaterializeInput, SessionSummaryMaterializerDeps, } from './materialize.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/session/summary/index.ts"],"names":[],"mappings":"AAOA,YAAY,EACX,uBAAuB,EACvB,eAAe,EACf,cAAc,EACd,eAAe,EACf,kBAAkB,EAClB,yBAAyB,GACzB,MAAM,kBAAkB,CAAA;AACzB,OAAO,EACN,uBAAuB,EACvB,wBAAwB,EACxB,6BAA6B,GAC7B,MAAM,UAAU,CAAA;AACjB,YAAY,EACX,yBAAyB,EACzB,qBAAqB,EACrB,2BAA2B,EAC3B,iBAAiB,GACjB,MAAM,UAAU,CAAA;AACjB,OAAO,EAAE,0BAA0B,EAAE,MAAM,kBAAkB,CAAA;AAC7D,YAAY,EACX,gBAAgB,EAChB,8BAA8B,GAC9B,MAAM,kBAAkB,CAAA"}

package/dist/session/summary/index.js

@@ -0,0 +1,9 @@
+// Sub-barrel for the session summary module (Convention #4).
+//
+// See session-hierarchy.md §4.7 (SessionSummaryRef shape) and §8.1
+// (kernel-only emission invariant). Concrete types and the materializer live
+// in sibling files; re-export them here so consumers import via
+// `../session/summary/index.js`.
+export { AGENT_SUMMARY_MAX_CHARS, AgentSummaryTooLongError, SessionAlreadySummarizedError, } from './ref.js';
+export { SessionSummaryMaterializer } from './materialize.js';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/session/summary/index.ts"],"names":[],"mappings":"AAAA,6DAA6D;AAC7D,EAAE;AACF,mEAAmE;AACnE,6EAA6E;AAC7E,gEAAgE;AAChE,iCAAiC;AAUjC,OAAO,EACN,uBAAuB,EACvB,wBAAwB,EACxB,6BAA6B,GAC7B,MAAM,UAAU,CAAA;AAOjB,OAAO,EAAE,0BAA0B,EAAE,MAAM,kBAAkB,CAAA"}

package/dist/session/summary/materialize.d.ts

@@ -0,0 +1,82 @@
+/**
+ * SessionSummaryMaterializer — kernel terminalization primitive.
+ *
+ * The sole producer of {@link SessionSummaryRef}. No agent-callable surface
+ * exists to bypass this (Convention #0 load-bearing — see
+ * session-hierarchy.md §8.1).
+ *
+ * Atomicity contract (§8.1): the summary write and the owning session's
+ * `non-terminal → idle` status flip commit as one logical unit. In the
+ * InMemory store the two happen within the same method call under the store's
+ * Map guard; in the Disk store they are two sequential write-tmp-renames
+ * (summary.json first, then session.json). A mid-step crash leaves the
+ * summary persisted but the session still active — `recover()` replays the
+ * session-status flip idempotently on next boot.
+ *
+ * The class is function-call-style (no internal state beyond deps). Tests
+ * inject a fake generator for deterministic IDs; production uses
+ * `generateSummaryId` from `utils/id.ts`.
+ */
+import type { SessionId, TenantId } from '../../types/ids/index.js';
+import type { SummaryId } from '../../types/session/ids.js';
+import type { SessionStore } from '../../types/session/store.js';
+import type { DeliverableRef } from './deliverable.js';
+import { type SessionSummaryKeyDecision, type SessionSummaryOutcome, type SessionSummaryRef } from './ref.js';
+/**
+ * Dependencies for {@link SessionSummaryMaterializer}. The generator is
+ * injected so tests can produce deterministic IDs; production code wires
+ * `generateSummaryId` from `utils/id.ts`.
+ */
+export interface SessionSummaryMaterializerDeps {
+    readonly store: SessionStore;
+    readonly generateSummaryId: () => SummaryId;
+    /** Clock hook — defaults to `new Date()` when omitted. */
+    readonly now?: () => Date;
+}
+/**
+ * Caller-supplied payload for {@link SessionSummaryMaterializer.materialize}.
+ * The materializer validates `agentSummary` length, constructs the
+ * `SessionSummaryRef`, and delegates the atomic write to the store.
+ */
+export interface MaterializeInput {
+    readonly sessionId: SessionId;
+    readonly tenantId: TenantId;
+    readonly finalOutcome: SessionSummaryOutcome;
+    readonly agentSummary: string;
+    readonly declaredDeliverables: readonly DeliverableRef[];
+    readonly keyDecisions: readonly SessionSummaryKeyDecision[];
+}
+export declare class SessionSummaryMaterializer {
+    private readonly deps;
+    constructor(deps: SessionSummaryMaterializerDeps);
+    /**
+     * Kernel emission path. Validates, builds the immutable
+     * {@link SessionSummaryRef}, and hands it to the store for atomic write +
+     * status-flip. Rejects with:
+     *
+     * - {@link AgentSummaryTooLongError} — `agentSummary` exceeds the max char
+     *   cap ({@link AGENT_SUMMARY_MAX_CHARS}).
+     * - `TenantIsolationError` — session is owned by a different tenant.
+     * - {@link SessionAlreadySummarizedError} — the session already has a
+     *   persisted summary. Re-materialization would duplicate history; the
+     *   caller should instead open an intervention sub-session (§4.5).
+     */
+    materialize(input: MaterializeInput): Promise<SessionSummaryRef>;
+    /**
+     * Recovery path. Called at boot (or explicitly by the lifecycle manager)
+     * for sessions whose `summary.json` is persisted but whose `session.json`
+     * still reports a non-terminal status — the crash window between the two
+     * atomic writes on disk.
+     *
+     * Idempotent: if the session is already `'idle'` (or another terminal
+     * state), no write occurs; the existing summary is returned. If no summary
+     * is persisted, returns `null` and no side effect occurs. This is the only
+     * non-materialize path that may touch the stored summary — it does not
+     * mint a new ID, only re-triggers the store's status flip via
+     * `recordSummary` when it detects the dangling session.
+     */
+    recover(sessionId: SessionId, tenantId: TenantId): Promise<SessionSummaryRef | null>;
+    private assertSummaryLength;
+    private clock;
+}
+//# sourceMappingURL=materialize.d.ts.map

package/dist/session/summary/materialize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"materialize.d.ts","sourceRoot":"","sources":["../../../src/session/summary/materialize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAA;AACnE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAA;AAC3D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAA;AAEhE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AACtD,OAAO,EAIN,KAAK,yBAAyB,EAC9B,KAAK,qBAAqB,EAC1B,KAAK,iBAAiB,EACtB,MAAM,UAAU,CAAA;AAEjB;;;;GAIG;AACH,MAAM,WAAW,8BAA8B;IAC9C,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAA;IAC5B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,SAAS,CAAA;IAC3C,0DAA0D;IAC1D,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,IAAI,CAAA;CACzB;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAA;IAC7B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAA;IAC3B,QAAQ,CAAC,YAAY,EAAE,qBAAqB,CAAA;IAC5C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,oBAAoB,EAAE,SAAS,cAAc,EAAE,CAAA;IACxD,QAAQ,CAAC,YAAY,EAAE,SAAS,yBAAyB,EAAE,CAAA;CAC3D;AAcD,qBAAa,0BAA0B;IACtC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAgC;gBAEzC,IAAI,EAAE,8BAA8B;IAIhD;;;;;;;;;;;OAWG;IACG,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAgCtE;;;;;;;;;;;;OAYG;IACG,OAAO,CAAC,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;IAoB1F,OAAO,CAAC,mBAAmB;IAS3B,OAAO,CAAC,KAAK;CAGb"}

package/dist/session/summary/materialize.js

@@ -0,0 +1,117 @@
+/**
+ * SessionSummaryMaterializer — kernel terminalization primitive.
+ *
+ * The sole producer of {@link SessionSummaryRef}. No agent-callable surface
+ * exists to bypass this (Convention #0 load-bearing — see
+ * session-hierarchy.md §8.1).
+ *
+ * Atomicity contract (§8.1): the summary write and the owning session's
+ * `non-terminal → idle` status flip commit as one logical unit. In the
+ * InMemory store the two happen within the same method call under the store's
+ * Map guard; in the Disk store they are two sequential write-tmp-renames
+ * (summary.json first, then session.json). A mid-step crash leaves the
+ * summary persisted but the session still active — `recover()` replays the
+ * session-status flip idempotently on next boot.
+ *
+ * The class is function-call-style (no internal state beyond deps). Tests
+ * inject a fake generator for deterministic IDs; production uses
+ * `generateSummaryId` from `utils/id.ts`.
+ */
+import { AGENT_SUMMARY_MAX_CHARS, AgentSummaryTooLongError, SessionAlreadySummarizedError, } from './ref.js';
+/**
+ * Session statuses from which a materialize call may legally transition to
+ * `'idle'` as part of the terminalization. Other states (already `'idle'`,
+ * `'failed'`, `'archived'`, `'awaiting_hitl'`) are left untouched; the
+ * materializer never moves a session *out of* `'failed'` or `'archived'`.
+ */
+const TERMINALIZABLE_STATUSES = new Set([
+    'active',
+    'locked',
+    'awaiting_merge',
+]);
+export class SessionSummaryMaterializer {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /**
+     * Kernel emission path. Validates, builds the immutable
+     * {@link SessionSummaryRef}, and hands it to the store for atomic write +
+     * status-flip. Rejects with:
+     *
+     * - {@link AgentSummaryTooLongError} — `agentSummary` exceeds the max char
+     *   cap ({@link AGENT_SUMMARY_MAX_CHARS}).
+     * - `TenantIsolationError` — session is owned by a different tenant.
+     * - {@link SessionAlreadySummarizedError} — the session already has a
+     *   persisted summary. Re-materialization would duplicate history; the
+     *   caller should instead open an intervention sub-session (§4.5).
+     */
+    async materialize(input) {
+        this.assertSummaryLength(input.agentSummary);
+        const session = await this.deps.store.getSession(input.sessionId, input.tenantId);
+        if (!session) {
+            throw new Error(`Session ${input.sessionId} not found`);
+        }
+        const existing = await this.deps.store.getSummary(input.sessionId, input.tenantId);
+        if (existing) {
+            throw new SessionAlreadySummarizedError({
+                sessionId: input.sessionId,
+                existingSummaryId: existing.id,
+            });
+        }
+        const summary = {
+            id: this.deps.generateSummaryId(),
+            sessionRef: input.sessionId,
+            tenantId: input.tenantId,
+            outcome: input.finalOutcome,
+            deliverables: input.declaredDeliverables,
+            agentSummary: input.agentSummary,
+            keyDecisions: input.keyDecisions,
+            at: this.clock(),
+            materializedBy: 'kernel',
+        };
+        await this.deps.store.recordSummary(summary, input.tenantId);
+        return summary;
+    }
+    /**
+     * Recovery path. Called at boot (or explicitly by the lifecycle manager)
+     * for sessions whose `summary.json` is persisted but whose `session.json`
+     * still reports a non-terminal status — the crash window between the two
+     * atomic writes on disk.
+     *
+     * Idempotent: if the session is already `'idle'` (or another terminal
+     * state), no write occurs; the existing summary is returned. If no summary
+     * is persisted, returns `null` and no side effect occurs. This is the only
+     * non-materialize path that may touch the stored summary — it does not
+     * mint a new ID, only re-triggers the store's status flip via
+     * `recordSummary` when it detects the dangling session.
+     */
+    async recover(sessionId, tenantId) {
+        const summary = await this.deps.store.getSummary(sessionId, tenantId);
+        if (!summary)
+            return null;
+        const session = await this.deps.store.getSession(sessionId, tenantId);
+        if (!session)
+            return summary;
+        if (TERMINALIZABLE_STATUSES.has(session.status)) {
+            // Dangling: summary persisted but session never flipped. Replay the
+            // status transition by re-invoking `recordSummary` — store impls
+            // treat an existing-summary path as "flip-only, no duplicate write".
+            // Cast preserves the kernel brand on the recovered record.
+            await this.deps.store.recordSummary(summary, tenantId);
+        }
+        return summary;
+    }
+    assertSummaryLength(agentSummary) {
+        if (agentSummary.length > AGENT_SUMMARY_MAX_CHARS) {
+            throw new AgentSummaryTooLongError({
+                actual: agentSummary.length,
+                max: AGENT_SUMMARY_MAX_CHARS,
+            });
+        }
+    }
+    clock() {
+        return this.deps.now ? this.deps.now() : new Date();
+    }
+}
+//# sourceMappingURL=materialize.js.map

package/dist/session/summary/materialize.js.map

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

package/dist/session/summary/ref.d.ts

@@ -0,0 +1,91 @@
+/**
+ * SessionSummaryRef — the structured pointer a parent session sees when a
+ * sub-session completes. Kernel-owned terminalization primitive: the only
+ * producer is {@link SessionSummaryMaterializer.materialize} (see
+ * `./materialize.ts`). See session-hierarchy.md §4.7 (shape) and §8.1
+ * (emission invariant).
+ *
+ * The `materializedBy: 'kernel'` literal field is load-bearing — combined
+ * with the opaque {@link SummaryId} brand (mintable only by
+ * `generateSummaryId`), it enforces at the type level that no agent or tool
+ * can construct a valid `SessionSummaryRef`. `SessionStore.recordSummary`
+ * only accepts `SessionSummaryRef & { materializedBy: 'kernel' }`, so even a
+ * payload shaped correctly would fail the structural check.
+ *
+ * This is Convention #0 load-bearing: there is no "tool" path to emit a
+ * summary; the parent agent sees only what the kernel seals.
+ */
+import type { SessionId, TenantId } from '../../types/ids/index.js';
+import type { SummaryId } from '../../types/session/ids.js';
+import type { DeliverableRef } from './deliverable.js';
+/**
+ * Max characters allowed for {@link SessionSummaryRef.agentSummary}. See
+ * session-hierarchy.md §4.7 — the agent's narration is bounded to keep
+ * parent prompts token-finite regardless of the child's transcript length.
+ */
+export declare const AGENT_SUMMARY_MAX_CHARS = 4000;
+export type SessionSummaryOutcomeStatus = 'succeeded' | 'partial' | 'failed';
+export interface SessionSummaryOutcome {
+    readonly status: SessionSummaryOutcomeStatus;
+    /** Short human-readable one-liner. Optional per pattern doc §4.7. */
+    readonly verdict?: string;
+}
+export interface SessionSummaryKeyDecision {
+    readonly at: Date;
+    readonly summary: string;
+}
+/**
+ * Structured completion pointer emitted by the kernel when a sub-session
+ * terminalizes. See session-hierarchy.md §4.7 and §8.1.
+ *
+ * Readonly across the board — the record is immutable once sealed.
+ */
+export interface SessionSummaryRef {
+    readonly id: SummaryId;
+    readonly sessionRef: SessionId;
+    readonly tenantId: TenantId;
+    readonly outcome: SessionSummaryOutcome;
+    readonly deliverables: readonly DeliverableRef[];
+    /** Agent's own narration; bounded to {@link AGENT_SUMMARY_MAX_CHARS}. */
+    readonly agentSummary: string;
+    readonly keyDecisions: readonly SessionSummaryKeyDecision[];
+    /** When the summary was materialized. */
+    readonly at: Date;
+    /**
+     * Literal `'kernel'` — enforces kernel-only emission at the type level.
+     * See the module header for the invariant rationale.
+     */
+    readonly materializedBy: 'kernel';
+}
+/**
+ * Raised by {@link SessionSummaryMaterializer.materialize} when the provided
+ * `agentSummary` exceeds {@link AGENT_SUMMARY_MAX_CHARS}. Convention #5
+ * deny-by-default — the kernel does not truncate silently.
+ */
+export declare class AgentSummaryTooLongError extends Error {
+    readonly details: {
+        readonly actual: number;
+        readonly max: number;
+    };
+    constructor(details: {
+        actual: number;
+        max: number;
+    });
+}
+/**
+ * Raised when {@link SessionSummaryMaterializer.materialize} is invoked
+ * against a session that already has a persisted summary. Re-materialization
+ * would duplicate history — callers wanting to append must open a new
+ * intervention sub-session (see session-hierarchy.md §4.5).
+ */
+export declare class SessionAlreadySummarizedError extends Error {
+    readonly details: {
+        readonly sessionId: SessionId;
+        readonly existingSummaryId: SummaryId;
+    };
+    constructor(details: {
+        sessionId: SessionId;
+        existingSummaryId: SummaryId;
+    });
+}
+//# sourceMappingURL=ref.d.ts.map

package/dist/session/summary/ref.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ref.d.ts","sourceRoot":"","sources":["../../../src/session/summary/ref.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAA;AACnE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAA;AAC3D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AAEtD;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,OAAO,CAAA;AAE3C,MAAM,MAAM,2BAA2B,GAAG,WAAW,GAAG,SAAS,GAAG,QAAQ,CAAA;AAE5E,MAAM,WAAW,qBAAqB;IACrC,QAAQ,CAAC,MAAM,EAAE,2BAA2B,CAAA;IAC5C,qEAAqE;IACrE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CACzB;AAED,MAAM,WAAW,yBAAyB;IACzC,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAA;IACjB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACxB;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IACjC,QAAQ,CAAC,EAAE,EAAE,SAAS,CAAA;IACtB,QAAQ,CAAC,UAAU,EAAE,SAAS,CAAA;IAC9B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAA;IAC3B,QAAQ,CAAC,OAAO,EAAE,qBAAqB,CAAA;IACvC,QAAQ,CAAC,YAAY,EAAE,SAAS,cAAc,EAAE,CAAA;IAChD,yEAAyE;IACzE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,YAAY,EAAE,SAAS,yBAAyB,EAAE,CAAA;IAC3D,yCAAyC;IACzC,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAA;IACjB;;;OAGG;IACH,QAAQ,CAAC,cAAc,EAAE,QAAQ,CAAA;CACjC;AAED;;;;GAIG;AACH,qBAAa,wBAAyB,SAAQ,KAAK;IAClD,QAAQ,CAAC,OAAO,EAAE;QACjB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;QACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;KACpB,CAAA;gBAEW,OAAO,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE;CAKpD;AAED;;;;;GAKG;AACH,qBAAa,6BAA8B,SAAQ,KAAK;IACvD,QAAQ,CAAC,OAAO,EAAE;QACjB,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAA;QAC7B,QAAQ,CAAC,iBAAiB,EAAE,SAAS,CAAA;KACrC,CAAA;gBAEW,OAAO,EAAE;QAAE,SAAS,EAAE,SAAS,CAAC;QAAC,iBAAiB,EAAE,SAAS,CAAA;KAAE;CAO3E"}

package/dist/session/summary/ref.js

@@ -0,0 +1,51 @@
+/**
+ * SessionSummaryRef — the structured pointer a parent session sees when a
+ * sub-session completes. Kernel-owned terminalization primitive: the only
+ * producer is {@link SessionSummaryMaterializer.materialize} (see
+ * `./materialize.ts`). See session-hierarchy.md §4.7 (shape) and §8.1
+ * (emission invariant).
+ *
+ * The `materializedBy: 'kernel'` literal field is load-bearing — combined
+ * with the opaque {@link SummaryId} brand (mintable only by
+ * `generateSummaryId`), it enforces at the type level that no agent or tool
+ * can construct a valid `SessionSummaryRef`. `SessionStore.recordSummary`
+ * only accepts `SessionSummaryRef & { materializedBy: 'kernel' }`, so even a
+ * payload shaped correctly would fail the structural check.
+ *
+ * This is Convention #0 load-bearing: there is no "tool" path to emit a
+ * summary; the parent agent sees only what the kernel seals.
+ */
+/**
+ * Max characters allowed for {@link SessionSummaryRef.agentSummary}. See
+ * session-hierarchy.md §4.7 — the agent's narration is bounded to keep
+ * parent prompts token-finite regardless of the child's transcript length.
+ */
+export const AGENT_SUMMARY_MAX_CHARS = 4000;
+/**
+ * Raised by {@link SessionSummaryMaterializer.materialize} when the provided
+ * `agentSummary` exceeds {@link AGENT_SUMMARY_MAX_CHARS}. Convention #5
+ * deny-by-default — the kernel does not truncate silently.
+ */
+export class AgentSummaryTooLongError extends Error {
+    details;
+    constructor(details) {
+        super(`agentSummary ${details.actual} chars exceeds max ${details.max}`);
+        this.name = 'AgentSummaryTooLongError';
+        this.details = details;
+    }
+}
+/**
+ * Raised when {@link SessionSummaryMaterializer.materialize} is invoked
+ * against a session that already has a persisted summary. Re-materialization
+ * would duplicate history — callers wanting to append must open a new
+ * intervention sub-session (see session-hierarchy.md §4.5).
+ */
+export class SessionAlreadySummarizedError extends Error {
+    details;
+    constructor(details) {
+        super(`Session ${details.sessionId} already has summary ${details.existingSummaryId}; re-materialization rejected`);
+        this.name = 'SessionAlreadySummarizedError';
+        this.details = details;
+    }
+}
+//# sourceMappingURL=ref.js.map

package/dist/session/summary/ref.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ref.js","sourceRoot":"","sources":["../../../src/session/summary/ref.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAMH;;;;GAIG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,IAAI,CAAA;AAuC3C;;;;GAIG;AACH,MAAM,OAAO,wBAAyB,SAAQ,KAAK;IACzC,OAAO,CAGf;IAED,YAAY,OAAwC;QACnD,KAAK,CAAC,gBAAgB,OAAO,CAAC,MAAM,sBAAsB,OAAO,CAAC,GAAG,EAAE,CAAC,CAAA;QACxE,IAAI,CAAC,IAAI,GAAG,0BAA0B,CAAA;QACtC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAA;IACvB,CAAC;CACD;AAED;;;;;GAKG;AACH,MAAM,OAAO,6BAA8B,SAAQ,KAAK;IAC9C,OAAO,CAGf;IAED,YAAY,OAA+D;QAC1E,KAAK,CACJ,WAAW,OAAO,CAAC,SAAS,wBAAwB,OAAO,CAAC,iBAAiB,+BAA+B,CAC5G,CAAA;QACD,IAAI,CAAC,IAAI,GAAG,+BAA+B,CAAA;QAC3C,IAAI,CAAC,OAAO,GAAG,OAAO,CAAA;IACvB,CAAC;CACD"}

package/dist/session/workspace/__tests__/git-worktree.test.d.ts

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

package/dist/session/workspace/__tests__/git-worktree.test.d.ts.map

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