@hydraharness/harness-session-projection 0.1.1-rc.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,50 @@
+# @hydraharness/harness-session-projection
+
+Session-projection Service Definition and drive registry. It owns `ctx.sessionProjections`, the registry that drives every registered projection unit over committed session events and serves finished whole values to carriers, currently the api-proxy history tail page and `session/projection` push frame. A domain registers pure mathematics; the framework owns the drive. The [session-projection RFC](../../../.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md) records the design rationale.
+
+Definitions with `history: active-version` fold only the selected transcript and refold on version creation or selection. Durable checkpoint watermarks still use the complete log sequence. A suffix containing a path change cannot reconstruct a shared prefix; restoration requests the complete log. Definitions sharing a key must agree on history mode and state version.
+
+## Service: `SessionProjectionRegistry` (ctx key: `sessionProjections`)
+
+### Public API
+
+- `ctx.sessionProjections.register(definition): () => void` Register one domain's unit. Duplicate keys and invalid `stateVersion` throw; the registration is an effect on the calling fiber, so an unloaded domain plugin's key (with its cached cells) disappears from subsequent drives and snapshots — clients read that as capability absence.
+- `ctx.sessionProjections.onChanged(listener): () => void` Subscribe to the change feed: one call per client-visible unit whose state reference changed, per committed event, carrying the schema-validated view and the causing seq. Effect-tied like `register`.
+- `ctx.sessionProjections.stateOf(session, key)` Read one registered unit's current host state without computing unrelated views. The returned value is a live read-only reference; callers must not mutate it.
+- `ctx.sessionProjections.snapshot(session): ProjectionSnapshot` One consistent synchronous cut over every registered client-visible unit — `{ asOfSeq, values }` with `asOfSeq` = the seq of the last event every value reflects (`-1` for an empty log). Host-only state is available only through `stateOf`.
+
+### Key Types
+
+- `SessionProjectionMap` — the merge-extensible client-view table shared by wire blocks and client hooks. Values are wire-JSON whole values; rendering belongs to the slot system, never this layer.
+- `SessionProjectionStateMap` — the merge-extensible host fold-state table. Every client-visible key appears in both tables; host-only keys appear only here.
+- `ProjectionDefinition<K, S>` — `{ key, stateSchema, init(), apply(state, event), wire?, stateVersion }`: a synchronous state-driven computation unit. `wire` supplies `viewSchema` and `view`; omitting it makes the unit host-only.
+
+## Contract
+
+- **The framework drives, the domain computes.** The registry subscribes to `session/event` once; every committed event passes every unit's `apply` eagerly. Domains hold no subscriptions. Cells (`{state, observedSeq}` per unit per session, WeakMap-keyed) build lazily — a unit registered after events flowed, or a read of a session predating the registration, folds `init` over the in-memory log on first touch.
+- **Same-reference means no work.** `apply` MUST return the same state reference for events that do not concern the unit; the drive gates the change feed on `Object.is`, so non-matching events cost one call and nothing downstream.
+- **Whole-value event rule (load-bearing).** A state-carrying log event MUST carry the complete post-change state, never a bare delta — it keeps every transition trivially cheap and every served value self-describing (last-wins for consumers).
+- **Synchronous unit discipline.** `init`/`apply`/`wire.view` MUST be synchronous; carriers read `snapshot()` in the same tick as their page slice, which is what makes `asOfSeq` one consistent cut. An accidentally async view returns a Promise, which fails `wire.viewSchema.parse`.
+- **State is validated plain JSON, `stateVersion` is its invalidation anchor.** The persisted projection cache stores `(sessionId, key, ver, seq, val)` rows and validates `val` with `stateSchema` before use; bump `stateVersion` whenever the state fields or fold semantics change. Every unit's state is checkpointed — client-visible and host-only alike.
+- **No wire vocabulary here.** The registry exposes only the change feed and the snapshot read face; carriers (api-proxy) mint their own frames (`session/projection`) and blocks from them.
+- **Optional capability.** Domain plugins register under `ctx.inject(['sessionProjections'], …)` so headless assemblies without the registry stay unaffected; carriers use `ctx.get('sessionProjections')` and omit their block/frames entirely when the registry is absent.
+
+## Role
+
+This package owns the Service Definition and drive roles of the capability seam: domain host plugins (e.g. `@hydraharness/harness-tool-todo`) contribute units, carriers (`@hydraharness/harness-host-apiproxy`) consume the snapshot and change feed, and neither knows the other.
+
+## Model Experience
+
+None, as the registry only computes client-facing read models of already-logged session state and touches no prompt, message, schema, stream, or tool result.
+
+#### KV Cache effect
+
+None; projections never assemble or send provider requests.
+
+## Known Limitations and Deferred Work
+
+- **Every tail page carries every client-visible key** — there is no per-key opt-out or lazy-key request shape yet; acceptable while values are UI-scale whole states (a todo list, a goal snapshot), revisit if a domain's value grows large.
+- **The unit table is process-wide, so key presence is not a per-session capability signal** — a key registered by ANY agent preset appears in every session's snapshot, including sessions whose own composition mounts nothing that produces it. A client must read the VALUE (`plan.active`, an empty todo list) rather than treat an absent key as absence of the feature; a unit whose empty value is indistinguishable from a real one belongs on the host plane instead, which is why `@hydraharness/harness-token-meter` sits there.
+- **Eager drive touches every unit per event** — cheap by construction (whole-value rule, same-reference gate), but a hot path would justify per-unit event-type prefilters, addable without contract change.
+- **Registry cells live in memory only** — a restart rebuilds by folding the log on first touch; compositions that mount `@hydraharness/harness-session-projection-cache` seed that fold from persisted rows instead.
+- **Synchronous unit discipline is only partially mechanical** — `wire.viewSchema.parse` rejects a Promise-returning view, but an `apply` that blocks or reads torn non-session state is a review concern; the invariant companion documents why no runtime check exists.

package/lib/index.js

@@ -0,0 +1,327 @@
+import { Service } from "@hydraharness/cordis";
+import { sessionVersions } from "@hydraharness/harness-session";
+//#region lib/types/index.js
+/**
+* Service Definition and drive registry for the session-projection capability seam: the merge-extensible state and client-view type
+* tables, the `ProjectionDefinition` state-driven computation unit contract,
+* and the `ctx.sessionProjections` registry that DRIVES every registered unit
+* forward eagerly over committed session events. Domain host plugins
+* contribute pure folds and optional client views; the framework owns the
+* subscription, the per-session watermark cache, and change notification;
+* carriers consume the snapshot read face and the change feed. Neither side
+* knows the other
+* (capability-seam three-way split). Design authority: the session-projection
+* RFC (.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md).
+*
+* Whole-value event rule (load-bearing): a state-carrying log event MUST
+* carry the complete post-change state, never a bare delta — it keeps every
+* unit's transition trivially cheap and every served value self-describing.
+*
+* @module @hydraharness/harness-session-projection
+*/
+/**
+* `ctx.sessionProjections`: the projection unit table and its drive. The
+* service subscribes to `session/event` once; every committed event passes
+* every registered unit's `apply` (eager drive), and a changed state
+* reference in a client-visible unit notifies the change feed with the
+* schema-validated view.
+* Cells build lazily — a unit registered after events flowed, or a session
+* older than the registry, folds `init` over the in-memory log on first
+* touch (event or read). Registration is an effect (disposer rides the
+* calling fiber): an unloaded domain plugin's key disappears from snapshots
+* and clients read it as capability absence. Domain
+* plugins register under `ctx.inject(['sessionProjections'], …)` so headless
+* assemblies without the registry stay unaffected. Registrants sharing a key
+* share one unit and are counted: the same tool package mounted in N agent
+* presets registers N times, and the key survives until the last one
+* unloads.
+*/
+var SessionProjectionRegistry = class extends Service {
+	registrations = /* @__PURE__ */ new Map();
+	listeners = /* @__PURE__ */ new Set();
+	/**
+	* Create and install the registry as `ctx.sessionProjections`.
+	* @param ctx - Cordis context that owns the service.
+	*/
+	constructor(ctx) {
+		super(ctx, "sessionProjections");
+		ctx.on("session/event", (session, event) => {
+			this.drive(session, event);
+		});
+	}
+	register(definition) {
+		const wire = definition.wire;
+		const erased = {
+			history: definition.history,
+			key: definition.key,
+			stateSchema: definition.stateSchema,
+			init: () => definition.init(),
+			apply: (state, event) => definition.apply(state, event),
+			wire: wire === void 0 ? void 0 : {
+				viewSchema: wire.viewSchema,
+				view: (state) => wire.view(state)
+			},
+			stateVersion: definition.stateVersion
+		};
+		if (!Number.isSafeInteger(definition.stateVersion) || definition.stateVersion < 0) throw new Error(`session projection ${JSON.stringify(definition.key)} stateVersion must be a non-negative integer, got ${String(definition.stateVersion)}`);
+		const dispose = this.ctx.effect(function* () {
+			const key = erased.key;
+			const existing = this.registrations.get(key);
+			if (existing === void 0) this.registrations.set(key, {
+				def: erased,
+				cells: /* @__PURE__ */ new WeakMap(),
+				refs: 1
+			});
+			else {
+				if (existing.def.stateVersion !== erased.stateVersion || existing.def.history !== erased.history) throw new Error(`session projection key ${JSON.stringify(key)} is already registered at stateVersion ${String(existing.def.stateVersion)}; refusing to share it with stateVersion ${String(erased.stateVersion)}`);
+				existing.refs += 1;
+			}
+			yield () => {
+				const live = this.registrations.get(key);
+				/* v8 ignore next -- the disposer runs once per successful registration, so the entry it counted is still here */
+				if (live === void 0) return;
+				live.refs -= 1;
+				if (live.refs === 0) this.registrations.delete(key);
+			};
+		}.bind(this), "sessionProjections.register()");
+		return () => void dispose();
+	}
+	/**
+	* Subscribe to the change feed. The registration is an effect on the
+	* calling context's fiber.
+	* @param listener - called once per client-visible unit whose state reference changed, per committed event.
+	* @returns the exact disposer that unsubscribes.
+	*/
+	onChanged(listener) {
+		const dispose = this.ctx.effect(() => {
+			this.listeners.add(listener);
+			return () => {
+				this.listeners.delete(listener);
+			};
+		}, "sessionProjections.onChanged()");
+		return () => void dispose();
+	}
+	/**
+	* Read one unit's current host state without computing unrelated views.
+	* The returned value is live; callers must not mutate it.
+	* @param session - the session whose state is read.
+	* @param key - the registered unit key.
+	* @returns current state, or `undefined` when the key is not registered.
+	*/
+	stateOf(session, key) {
+		const registration = this.registrations.get(key);
+		if (registration === void 0) return void 0;
+		return this.cellFor(registration, session).state;
+	}
+	/**
+	* One consistent cut over every registered client-visible unit for one session, read from
+	* the watermark cache (missing cells fold lazily over the in-memory log).
+	* Fully synchronous — every value and `asOfSeq` reflect the same log
+	* position. Each value passes its unit's `viewSchema` before leaving.
+	* @param session - the session whose projection values are read.
+	* @returns the snapshot; `values` is empty when no client-visible unit is registered.
+	*/
+	snapshot(session) {
+		const values = {};
+		for (const registration of this.registrations.values()) {
+			if (registration.def.wire === void 0) continue;
+			const cell = this.cellFor(registration, session);
+			values[registration.def.key] = registration.def.wire.viewSchema.parse(registration.def.wire.view(cell.state));
+		}
+		return {
+			asOfSeq: session.seq - 1,
+			values
+		};
+	}
+	/**
+	* State-level checkpoint of every persisted unit for one session, read
+	* from the watermark cache (missing cells fold lazily over the in-memory
+	* log). This is the write side of the persisted projection cache: the
+	* returned rows are the `(key → {ver, seq, val})` part of the durable
+	* `(sessionId, key, ver, seq, val)`
+	* rows. Every `val` is a DETACHED structured clone — never the live
+	* cell reference: the watermark cache is this registry's authoritative
+	* mutable state, and a caller reaching the live reference could corrupt
+	* every subsequent snapshot and frame through it (plain JSON by the unit
+	* contract, so the clone is total).
+	* @param session - the session whose unit states are checkpointed.
+	* @returns one row per registered key.
+	*/
+	checkpoint(session) {
+		const rows = {};
+		for (const registration of this.registrations.values()) {
+			const cell = this.cellFor(registration, session);
+			rows[registration.def.key] = {
+				ver: registration.def.stateVersion,
+				seq: cell.observedSeq,
+				val: structuredClone(cell.state)
+			};
+		}
+		return rows;
+	}
+	/**
+	* The stored seq a {@link restore} tail read over `checkpoint` must start
+	* at: one event BELOW the lowest usable watermark (a row is usable when
+	* its `ver` matches the live unit's `stateVersion`; an absent or mismatched row
+	* pulls the floor to `0` — that key must refold the full log). The
+	* one-below anchor is load-bearing: the tail then proves how far the
+	* stored log still extends, so {@link restore} can detect a log that
+	* shrank below a row's watermark (crash-repair truncation) instead of
+	* serving the stale row as current — an empty tail read from the anchor
+	* yields an end below every watermark and the restore rejects for a full
+	* re-read.
+	* @param checkpoint - persisted rows for one session (possibly stale or empty).
+	* @returns the seq to hand the persistence `readFrom`, or `undefined`
+	*   when no unit is registered (no read needed — {@link restore} would
+	*   serve empty values regardless).
+	*/
+	restoreFloor(checkpoint) {
+		let floor;
+		for (const registration of this.registrations.values()) {
+			const row = checkpoint[registration.def.key];
+			const need = row !== void 0 && row.ver === registration.def.stateVersion ? Math.max(row.seq + 1, 0) : 0;
+			floor = floor === void 0 ? need : Math.min(floor, need);
+		}
+		return floor === void 0 ? void 0 : Math.max(floor - 1, 0);
+	}
+	/**
+	* View a checkpoint's rows without any log read: for every registered
+	* client-visible unit whose row's `ver` matches, serve the schema-validated
+	* `view` of the schema-validated stored state; mismatched, malformed, or absent rows leave their key
+	* absent (a cold or listing consumer treats it as not-yet-available and a
+	* fuller read path refolds it). The zero-I/O rung of the read ladder —
+	* values are as stale as their rows, never wrong.
+	* @param checkpoint - persisted rows for one session (possibly stale or empty).
+	* @returns whole values per key with a usable row; empty when none.
+	*/
+	viewCheckpoint(checkpoint) {
+		const values = {};
+		for (const registration of this.registrations.values()) {
+			const def = registration.def;
+			if (def.wire === void 0) continue;
+			const row = checkpoint[def.key];
+			if (row === void 0 || row.ver !== def.stateVersion) continue;
+			let state;
+			try {
+				state = def.stateSchema.parse(row.val);
+			} catch {
+				continue;
+			}
+			values[def.key] = def.wire.viewSchema.parse(def.wire.view(state));
+		}
+		return values;
+	}
+	/**
+	* Whether every registered client-visible unit has a usable checkpoint row.
+	* Host-only units do not affect client listing reads. A row is usable only
+	* when its version, persisted state, and rendered client value pass the
+	* current unit definitions.
+	* @param checkpoint - persisted rows for one session (possibly stale or incomplete).
+	* @returns `true` when {@link viewCheckpoint} can serve every current client value.
+	*/
+	checkpointHasCurrentViews(checkpoint) {
+		for (const registration of this.registrations.values()) {
+			const def = registration.def;
+			if (def.wire === void 0) continue;
+			const row = checkpoint[def.key];
+			if (row === void 0 || row.ver !== def.stateVersion) return false;
+			try {
+				const state = def.stateSchema.parse(row.val);
+				def.wire.viewSchema.parse(def.wire.view(state));
+			} catch {
+				return false;
+			}
+		}
+		return true;
+	}
+	/**
+	* Cold read: fold every persisted unit over a stored log suffix, seeding
+	* each from its checkpoint row when usable — the one read recipe (cached
+	* state + forward tail replay + `view`) applied without a live `Session`.
+	* Call with the events returned by a persistence
+	* `readFrom(id, restoreFloor(checkpoint))` and that same floor as
+	* `baseSeq`; the floor's one-below anchor makes the supplied end honest,
+	* so a shrunk log is detected here. A row is usable iff its
+	* `ver` matches the live unit's `stateVersion`, it does not predate `baseSeq`
+	* (`seq >= baseSeq - 1`), and it does not claim events past the
+	* supplied end (`seq <= endSeq`); an unusable row is discarded
+	* and its key refolds from `init` — which is only sound over the full
+	* log, so a discarded row with `baseSeq > 0` throws (the caller re-reads
+	* from seq 0, e.g. after a crash-repair truncation shrank the log below
+	* a row's watermark).
+	* @param checkpoint - persisted rows for one session (possibly stale or empty).
+	* @param events - the stored events with `seq >= baseSeq`, in seq order.
+	* @param baseSeq - the seq `events` starts at (its first event's seq when non-empty).
+	* @returns the snapshot cut at the supplied log end (`asOfSeq` is the last
+	*   supplied event's seq, `baseSeq - 1` for an empty tail) plus the
+	*   refreshed checkpoint rows at that cut, ready for a durable write-back.
+	*/
+	restore(checkpoint, events, baseSeq) {
+		const endSeq = events.at(-1)?.seq ?? baseSeq - 1;
+		const values = {};
+		const refreshed = {};
+		for (const registration of this.registrations.values()) {
+			const def = registration.def;
+			const row = checkpoint[def.key];
+			const usable = row !== void 0 && row.ver === def.stateVersion && row.seq >= baseSeq - 1 && row.seq <= endSeq;
+			if (!usable && baseSeq > 0) throw new Error(`session projection ${JSON.stringify(def.key)} cannot restore from seq ${baseSeq}: its checkpoint row is missing, version-mismatched, or beyond the supplied log end; re-read from seq 0`);
+			if (def.history === "active-version" && baseSeq > 0 && events.some((event) => event.type === "session/version" || event.type === "session/version-selected")) throw new Error("active-version projection requires a complete log after a path change; re-read from seq 0");
+			const active = def.history === "active-version" && baseSeq === 0 ? sessionVersions(events).events() : void 0;
+			let state = active === void 0 && usable ? def.stateSchema.parse(row.val) : def.init();
+			const from = usable ? row.seq : baseSeq - 1;
+			for (const event of active ?? events) if (active !== void 0 || event.seq > from) state = def.apply(state, event);
+			if (def.wire !== void 0) values[def.key] = def.wire.viewSchema.parse(def.wire.view(state));
+			refreshed[def.key] = {
+				ver: def.stateVersion,
+				seq: endSeq,
+				val: state
+			};
+		}
+		return {
+			snapshot: {
+				asOfSeq: endSeq,
+				values
+			},
+			checkpoint: refreshed
+		};
+	}
+	/** Fold one unit from init over `events`, producing a cell watermarked at the last folded event. */
+	buildCell(def, events) {
+		let state = def.init();
+		const source = def.history === "active-version" ? sessionVersions(events).events() : events;
+		for (const event of source) state = def.apply(state, event);
+		return {
+			state,
+			observedSeq: events.at(-1)?.seq ?? -1
+		};
+	}
+	/** Read (or lazily build, folding the full in-memory log) one unit's cell. */
+	cellFor(registration, session) {
+		let cell = registration.cells.get(session);
+		if (cell === void 0) {
+			cell = this.buildCell(registration.def, session.events);
+			registration.cells.set(session, cell);
+		}
+		return cell;
+	}
+	/** Eager drive: pass one committed event through every registered unit; notify on changed references. */
+	drive(session, event) {
+		for (const registration of this.registrations.values()) {
+			let cell = registration.cells.get(session);
+			if (cell === void 0) {
+				cell = this.buildCell(registration.def, session.events.slice(0, event.seq));
+				registration.cells.set(session, cell);
+			}
+			const next = registration.def.history === "active-version" && (event.type === "session/version" || event.type === "session/version-selected") ? this.buildCell(registration.def, session.events).state : registration.def.apply(cell.state, event);
+			const changed = !Object.is(next, cell.state);
+			cell.state = next;
+			cell.observedSeq = event.seq;
+			if (changed && registration.def.wire !== void 0 && this.listeners.size > 0) {
+				const value = registration.def.wire.viewSchema.parse(registration.def.wire.view(next));
+				for (const listener of this.listeners) listener(session, registration.def.key, value, event.seq);
+			}
+		}
+	}
+};
+//#endregion
+export { SessionProjectionRegistry, SessionProjectionRegistry as default };

package/lib/invariant.js

@@ -0,0 +1,31 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@hydraharness/harness-session-projection`.
+* @module @hydraharness/harness-session-projection/invariant
+*/
+const PACKAGE_NAME = "@hydraharness/harness-session-projection";
+/** Cordis companion plugin name. */
+const name = "session-projection-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: the registry's own contracts (duplicate-key and
+* stateVersion rejection, effect-tied removal, the Object.is change gate) are
+* enforced synchronously inside the service and proven by its spec, the
+* drive relation (every committed `session/event` passes every unit) would
+* require re-running the drive to check — duplicating the implementation
+* rather than detecting drift — and the served-value relation (every served
+* key has a live registration) lives on each carrier's wire path, which
+* emits no cordis event this companion could observe; carrier specs assert
+* it. Synchronous-unit discipline is enforced as far as practical by the
+* boundary `schema.parse` (a Promise-returning view fails loudly).
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,265 @@
+/**
+ * Service Definition and drive registry for the session-projection capability seam: the merge-extensible state and client-view type
+ * tables, the `ProjectionDefinition` state-driven computation unit contract,
+ * and the `ctx.sessionProjections` registry that DRIVES every registered unit
+ * forward eagerly over committed session events. Domain host plugins
+ * contribute pure folds and optional client views; the framework owns the
+ * subscription, the per-session watermark cache, and change notification;
+ * carriers consume the snapshot read face and the change feed. Neither side
+ * knows the other
+ * (capability-seam three-way split). Design authority: the session-projection
+ * RFC (.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md).
+ *
+ * Whole-value event rule (load-bearing): a state-carrying log event MUST
+ * carry the complete post-change state, never a bare delta — it keeps every
+ * unit's transition trivially cheap and every served value self-describing.
+ *
+ * @module @hydraharness/harness-session-projection
+ */
+import { Context, Service } from '@hydraharness/cordis';
+import type { ZodType } from 'zod';
+import type { Session, SessionEvent } from '@hydraharness/harness-session';
+declare module '@hydraharness/cordis' {
+    interface Context {
+        sessionProjections: SessionProjectionRegistry;
+    }
+}
+import type { SessionProjectionMap, SessionProjectionStateMap } from './types.ts';
+export type { SessionProjectionMap, SessionProjectionStateMap } from './types.ts';
+/**
+ * One domain's state-driven computation unit: a pure synchronous fold plus
+ * declarations and an optional client view — never an opaque getter. The framework drives
+ * `apply` on every committed session event; the domain holds no
+ * subscriptions and owns only the computation. All functions MUST be
+ * synchronous (an async unit would tear the carriers' consistency cut), and
+ * `state` MUST be plain JSON (the persisted-cache precondition).
+ */
+export interface ProjectionDefinition<K extends keyof SessionProjectionStateMap, S extends SessionProjectionStateMap[K] = SessionProjectionStateMap[K]> {
+    /** Active-version units refold selected event references when a transcript path changes. */
+    history?: 'active-version';
+    /** The projection key this unit owns (its `SessionProjectionStateMap` entry). */
+    key: K;
+    /** Validates persisted state before it seeds a fold. */
+    stateSchema: ZodType<S>;
+    /**
+     * State for the empty log.
+     * @returns the initial state.
+     */
+    init(): NoInfer<S>;
+    /**
+     * Pure transition: previous state + one committed event → next state. A
+     * unit uninterested in an event MUST return the same state reference — an
+     * unchanged reference (`Object.is`) produces zero downstream work.
+     * @param state - the state covering all prior events.
+     * @param event - the next committed session event.
+     * @returns the next state (same reference when the event is not the unit's).
+     */
+    apply(state: NoInfer<S>, event: SessionEvent): NoInfer<S>;
+    /** Client view. Omit for host-only units. */
+    wire?: K extends keyof SessionProjectionMap ? {
+        /** Validates the wire payload before it leaves the host. */
+        viewSchema: ZodType<SessionProjectionMap[K]>;
+        /**
+         * State → wire payload (the read-side projection).
+         * @param state - the current state.
+         * @returns the whole current value for this unit's key.
+         */
+        view(state: NoInfer<S>): SessionProjectionMap[K];
+    } : never;
+    /**
+     * Persisted-cache invalidation version: bump whenever the serialized state fields or the
+     * fold semantics change, so persisted `(sessionId, key, ver, seq, val)`
+     * rows from an older unit are discarded instead of being forward-applied
+     * into garbage. Non-negative integer.
+     */
+    stateVersion: number;
+}
+/**
+ * Change-feed listener: one unit's value changed for one session. `value` is
+ * the schema-validated `view` output; `seq` is the unit's watermark at
+ * emission (the seq of the event that caused the change).
+ */
+export type ProjectionChangeListener = (session: Session, key: Extract<keyof SessionProjectionMap, string>, value: unknown, seq: number) => void;
+/**
+ * One consistent read cut over every registered client-visible unit for one session.
+ * `asOfSeq` is the shared watermark — the seq of the last event every value
+ * reflects (`-1` for an empty log, mirroring `session/subscribed.lastSeq`).
+ */
+export interface ProjectionSnapshot {
+    /** Seq of the last event the values reflect; -1 for an empty log. */
+    asOfSeq: number;
+    /** Whole current client value per registered key. */
+    values: Partial<SessionProjectionMap>;
+}
+/**
+ * One unit's checkpoint: its internal state (plain JSON by the unit
+ * contract), the seq of the last event folded into it, and the unit
+ * `stateVersion` that produced it — the persisted projection-cache row
+ * `(sessionId, key, ver, seq, val)` minus the two outer keys. A row is
+ * never authoritative, only a fold shortcut: `restore` discards it on a
+ * version mismatch or when it claims events past the stored log end.
+ */
+export interface ProjectionCheckpointRow {
+    /** The registering unit's `stateVersion` at fold time. */
+    ver: number;
+    /** Seq of the last event folded into `val`; -1 for the empty log. */
+    seq: number;
+    /** The unit's internal state — plain JSON per the unit contract. */
+    val: unknown;
+}
+/** Checkpoint rows keyed by projection key (one session's persisted cache value). */
+export type ProjectionCheckpoint = Record<string, ProjectionCheckpointRow>;
+/**
+ * `ctx.sessionProjections`: the projection unit table and its drive. The
+ * service subscribes to `session/event` once; every committed event passes
+ * every registered unit's `apply` (eager drive), and a changed state
+ * reference in a client-visible unit notifies the change feed with the
+ * schema-validated view.
+ * Cells build lazily — a unit registered after events flowed, or a session
+ * older than the registry, folds `init` over the in-memory log on first
+ * touch (event or read). Registration is an effect (disposer rides the
+ * calling fiber): an unloaded domain plugin's key disappears from snapshots
+ * and clients read it as capability absence. Domain
+ * plugins register under `ctx.inject(['sessionProjections'], …)` so headless
+ * assemblies without the registry stay unaffected. Registrants sharing a key
+ * share one unit and are counted: the same tool package mounted in N agent
+ * presets registers N times, and the key survives until the last one
+ * unloads.
+ */
+export declare class SessionProjectionRegistry extends Service {
+    private readonly registrations;
+    private readonly listeners;
+    /**
+     * Create and install the registry as `ctx.sessionProjections`.
+     * @param ctx - Cordis context that owns the service.
+     */
+    constructor(ctx: Context);
+    /**
+     * Register one domain's unit. The registration is an effect on the calling
+     * context's fiber: disposing the fiber (or calling the returned disposer)
+     * removes the key — and the unit's cached cells — from subsequent drives
+     * and snapshots.
+     * @param definition - key, state schema, pure unit functions, and stateVersion.
+     * @returns the exact disposer that unregisters this unit.
+     */
+    register<K extends keyof SessionProjectionMap, S extends SessionProjectionStateMap[K]>(definition: Omit<ProjectionDefinition<K, S>, 'wire'> & {
+        wire: NonNullable<ProjectionDefinition<K, S>['wire']>;
+    }): () => void;
+    /**
+     * Register one host-only unit. Its state is omitted from client snapshots
+     * and always checkpointed like every other unit.
+     * @param definition - key, state schema, pure unit functions, and stateVersion.
+     * @returns the exact disposer that unregisters this unit.
+     */
+    register<K extends Exclude<keyof SessionProjectionStateMap, keyof SessionProjectionMap>, S extends SessionProjectionStateMap[K]>(definition: Omit<ProjectionDefinition<K, S>, 'wire'>): () => void;
+    /**
+     * Subscribe to the change feed. The registration is an effect on the
+     * calling context's fiber.
+     * @param listener - called once per client-visible unit whose state reference changed, per committed event.
+     * @returns the exact disposer that unsubscribes.
+     */
+    onChanged(listener: ProjectionChangeListener): () => void;
+    /**
+     * Read one unit's current host state without computing unrelated views.
+     * The returned value is live; callers must not mutate it.
+     * @param session - the session whose state is read.
+     * @param key - the registered unit key.
+     * @returns current state, or `undefined` when the key is not registered.
+     */
+    stateOf<K extends keyof SessionProjectionStateMap>(session: Session, key: K): SessionProjectionStateMap[K] | undefined;
+    /**
+     * One consistent cut over every registered client-visible unit for one session, read from
+     * the watermark cache (missing cells fold lazily over the in-memory log).
+     * Fully synchronous — every value and `asOfSeq` reflect the same log
+     * position. Each value passes its unit's `viewSchema` before leaving.
+     * @param session - the session whose projection values are read.
+     * @returns the snapshot; `values` is empty when no client-visible unit is registered.
+     */
+    snapshot(session: Session): ProjectionSnapshot;
+    /**
+     * State-level checkpoint of every persisted unit for one session, read
+     * from the watermark cache (missing cells fold lazily over the in-memory
+     * log). This is the write side of the persisted projection cache: the
+     * returned rows are the `(key → {ver, seq, val})` part of the durable
+     * `(sessionId, key, ver, seq, val)`
+     * rows. Every `val` is a DETACHED structured clone — never the live
+     * cell reference: the watermark cache is this registry's authoritative
+     * mutable state, and a caller reaching the live reference could corrupt
+     * every subsequent snapshot and frame through it (plain JSON by the unit
+     * contract, so the clone is total).
+     * @param session - the session whose unit states are checkpointed.
+     * @returns one row per registered key.
+     */
+    checkpoint(session: Session): ProjectionCheckpoint;
+    /**
+     * The stored seq a {@link restore} tail read over `checkpoint` must start
+     * at: one event BELOW the lowest usable watermark (a row is usable when
+     * its `ver` matches the live unit's `stateVersion`; an absent or mismatched row
+     * pulls the floor to `0` — that key must refold the full log). The
+     * one-below anchor is load-bearing: the tail then proves how far the
+     * stored log still extends, so {@link restore} can detect a log that
+     * shrank below a row's watermark (crash-repair truncation) instead of
+     * serving the stale row as current — an empty tail read from the anchor
+     * yields an end below every watermark and the restore rejects for a full
+     * re-read.
+     * @param checkpoint - persisted rows for one session (possibly stale or empty).
+     * @returns the seq to hand the persistence `readFrom`, or `undefined`
+     *   when no unit is registered (no read needed — {@link restore} would
+     *   serve empty values regardless).
+     */
+    restoreFloor(checkpoint: ProjectionCheckpoint): number | undefined;
+    /**
+     * View a checkpoint's rows without any log read: for every registered
+     * client-visible unit whose row's `ver` matches, serve the schema-validated
+     * `view` of the schema-validated stored state; mismatched, malformed, or absent rows leave their key
+     * absent (a cold or listing consumer treats it as not-yet-available and a
+     * fuller read path refolds it). The zero-I/O rung of the read ladder —
+     * values are as stale as their rows, never wrong.
+     * @param checkpoint - persisted rows for one session (possibly stale or empty).
+     * @returns whole values per key with a usable row; empty when none.
+     */
+    viewCheckpoint(checkpoint: ProjectionCheckpoint): Partial<SessionProjectionMap>;
+    /**
+     * Whether every registered client-visible unit has a usable checkpoint row.
+     * Host-only units do not affect client listing reads. A row is usable only
+     * when its version, persisted state, and rendered client value pass the
+     * current unit definitions.
+     * @param checkpoint - persisted rows for one session (possibly stale or incomplete).
+     * @returns `true` when {@link viewCheckpoint} can serve every current client value.
+     */
+    checkpointHasCurrentViews(checkpoint: ProjectionCheckpoint): boolean;
+    /**
+     * Cold read: fold every persisted unit over a stored log suffix, seeding
+     * each from its checkpoint row when usable — the one read recipe (cached
+     * state + forward tail replay + `view`) applied without a live `Session`.
+     * Call with the events returned by a persistence
+     * `readFrom(id, restoreFloor(checkpoint))` and that same floor as
+     * `baseSeq`; the floor's one-below anchor makes the supplied end honest,
+     * so a shrunk log is detected here. A row is usable iff its
+     * `ver` matches the live unit's `stateVersion`, it does not predate `baseSeq`
+     * (`seq >= baseSeq - 1`), and it does not claim events past the
+     * supplied end (`seq <= endSeq`); an unusable row is discarded
+     * and its key refolds from `init` — which is only sound over the full
+     * log, so a discarded row with `baseSeq > 0` throws (the caller re-reads
+     * from seq 0, e.g. after a crash-repair truncation shrank the log below
+     * a row's watermark).
+     * @param checkpoint - persisted rows for one session (possibly stale or empty).
+     * @param events - the stored events with `seq >= baseSeq`, in seq order.
+     * @param baseSeq - the seq `events` starts at (its first event's seq when non-empty).
+     * @returns the snapshot cut at the supplied log end (`asOfSeq` is the last
+     *   supplied event's seq, `baseSeq - 1` for an empty tail) plus the
+     *   refreshed checkpoint rows at that cut, ready for a durable write-back.
+     */
+    restore(checkpoint: ProjectionCheckpoint, events: readonly SessionEvent[], baseSeq: number): {
+        snapshot: ProjectionSnapshot;
+        checkpoint: ProjectionCheckpoint;
+    };
+    /** Fold one unit from init over `events`, producing a cell watermarked at the last folded event. */
+    private buildCell;
+    /** Read (or lazily build, folding the full in-memory log) one unit's cell. */
+    private cellFor;
+    /** Eager drive: pass one committed event through every registered unit; notify on changed references. */
+    private drive;
+}
+export default SessionProjectionRegistry;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/index.js

@@ -0,0 +1,344 @@
+/**
+ * Service Definition and drive registry for the session-projection capability seam: the merge-extensible state and client-view type
+ * tables, the `ProjectionDefinition` state-driven computation unit contract,
+ * and the `ctx.sessionProjections` registry that DRIVES every registered unit
+ * forward eagerly over committed session events. Domain host plugins
+ * contribute pure folds and optional client views; the framework owns the
+ * subscription, the per-session watermark cache, and change notification;
+ * carriers consume the snapshot read face and the change feed. Neither side
+ * knows the other
+ * (capability-seam three-way split). Design authority: the session-projection
+ * RFC (.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md).
+ *
+ * Whole-value event rule (load-bearing): a state-carrying log event MUST
+ * carry the complete post-change state, never a bare delta — it keeps every
+ * unit's transition trivially cheap and every served value self-describing.
+ *
+ * @module @hydraharness/harness-session-projection
+ */
+import { Service } from '@hydraharness/cordis';
+import { sessionVersions } from '@hydraharness/harness-session';
+/**
+ * `ctx.sessionProjections`: the projection unit table and its drive. The
+ * service subscribes to `session/event` once; every committed event passes
+ * every registered unit's `apply` (eager drive), and a changed state
+ * reference in a client-visible unit notifies the change feed with the
+ * schema-validated view.
+ * Cells build lazily — a unit registered after events flowed, or a session
+ * older than the registry, folds `init` over the in-memory log on first
+ * touch (event or read). Registration is an effect (disposer rides the
+ * calling fiber): an unloaded domain plugin's key disappears from snapshots
+ * and clients read it as capability absence. Domain
+ * plugins register under `ctx.inject(['sessionProjections'], …)` so headless
+ * assemblies without the registry stay unaffected. Registrants sharing a key
+ * share one unit and are counted: the same tool package mounted in N agent
+ * presets registers N times, and the key survives until the last one
+ * unloads.
+ */
+export class SessionProjectionRegistry extends Service {
+    registrations = new Map();
+    listeners = new Set();
+    /**
+     * Create and install the registry as `ctx.sessionProjections`.
+     * @param ctx - Cordis context that owns the service.
+     */
+    constructor(ctx) {
+        super(ctx, 'sessionProjections');
+        ctx.on('session/event', (session, event) => {
+            this.drive(session, event);
+        });
+    }
+    register(definition) {
+        const wire = definition.wire;
+        const erased = {
+            history: definition.history,
+            key: definition.key,
+            stateSchema: definition.stateSchema,
+            init: () => definition.init(),
+            apply: (state, event) => definition.apply(state, event),
+            wire: wire === undefined
+                ? undefined
+                : { viewSchema: wire.viewSchema, view: state => wire.view(state) },
+            stateVersion: definition.stateVersion,
+        };
+        if (!Number.isSafeInteger(definition.stateVersion) || definition.stateVersion < 0) {
+            throw new Error(`session projection ${JSON.stringify(definition.key)} stateVersion must be a non-negative integer, got ${String(definition.stateVersion)}`);
+        }
+        const dispose = this.ctx.effect(function* () {
+            const key = erased.key;
+            const existing = this.registrations.get(key);
+            if (existing === undefined) {
+                this.registrations.set(key, { def: erased, cells: new WeakMap(), refs: 1 });
+            }
+            else {
+                if (existing.def.stateVersion !== erased.stateVersion || existing.def.history !== erased.history) {
+                    throw new Error(`session projection key ${JSON.stringify(key)} is already registered at stateVersion ${String(existing.def.stateVersion)}; refusing to share it with stateVersion ${String(erased.stateVersion)}`);
+                }
+                existing.refs += 1;
+            }
+            yield () => {
+                const live = this.registrations.get(key);
+                /* v8 ignore next -- the disposer runs once per successful registration, so the entry it counted is still here */
+                if (live === undefined)
+                    return;
+                live.refs -= 1;
+                if (live.refs === 0)
+                    this.registrations.delete(key);
+            };
+        }.bind(this), 'sessionProjections.register()');
+        return () => void dispose();
+    }
+    /**
+     * Subscribe to the change feed. The registration is an effect on the
+     * calling context's fiber.
+     * @param listener - called once per client-visible unit whose state reference changed, per committed event.
+     * @returns the exact disposer that unsubscribes.
+     */
+    onChanged(listener) {
+        const dispose = this.ctx.effect(() => {
+            this.listeners.add(listener);
+            return () => {
+                this.listeners.delete(listener);
+            };
+        }, 'sessionProjections.onChanged()');
+        return () => void dispose();
+    }
+    /**
+     * Read one unit's current host state without computing unrelated views.
+     * The returned value is live; callers must not mutate it.
+     * @param session - the session whose state is read.
+     * @param key - the registered unit key.
+     * @returns current state, or `undefined` when the key is not registered.
+     */
+    stateOf(session, key) {
+        const registration = this.registrations.get(key);
+        if (registration === undefined)
+            return undefined;
+        return this.cellFor(registration, session).state;
+    }
+    /**
+     * One consistent cut over every registered client-visible unit for one session, read from
+     * the watermark cache (missing cells fold lazily over the in-memory log).
+     * Fully synchronous — every value and `asOfSeq` reflect the same log
+     * position. Each value passes its unit's `viewSchema` before leaving.
+     * @param session - the session whose projection values are read.
+     * @returns the snapshot; `values` is empty when no client-visible unit is registered.
+     */
+    snapshot(session) {
+        const values = {};
+        for (const registration of this.registrations.values()) {
+            if (registration.def.wire === undefined)
+                continue;
+            const cell = this.cellFor(registration, session);
+            values[registration.def.key] = registration.def.wire.viewSchema.parse(registration.def.wire.view(cell.state));
+        }
+        return { asOfSeq: session.seq - 1, values };
+    }
+    /**
+     * State-level checkpoint of every persisted unit for one session, read
+     * from the watermark cache (missing cells fold lazily over the in-memory
+     * log). This is the write side of the persisted projection cache: the
+     * returned rows are the `(key → {ver, seq, val})` part of the durable
+     * `(sessionId, key, ver, seq, val)`
+     * rows. Every `val` is a DETACHED structured clone — never the live
+     * cell reference: the watermark cache is this registry's authoritative
+     * mutable state, and a caller reaching the live reference could corrupt
+     * every subsequent snapshot and frame through it (plain JSON by the unit
+     * contract, so the clone is total).
+     * @param session - the session whose unit states are checkpointed.
+     * @returns one row per registered key.
+     */
+    checkpoint(session) {
+        const rows = {};
+        for (const registration of this.registrations.values()) {
+            const cell = this.cellFor(registration, session);
+            rows[registration.def.key] = {
+                ver: registration.def.stateVersion,
+                seq: cell.observedSeq,
+                val: structuredClone(cell.state),
+            };
+        }
+        return rows;
+    }
+    /**
+     * The stored seq a {@link restore} tail read over `checkpoint` must start
+     * at: one event BELOW the lowest usable watermark (a row is usable when
+     * its `ver` matches the live unit's `stateVersion`; an absent or mismatched row
+     * pulls the floor to `0` — that key must refold the full log). The
+     * one-below anchor is load-bearing: the tail then proves how far the
+     * stored log still extends, so {@link restore} can detect a log that
+     * shrank below a row's watermark (crash-repair truncation) instead of
+     * serving the stale row as current — an empty tail read from the anchor
+     * yields an end below every watermark and the restore rejects for a full
+     * re-read.
+     * @param checkpoint - persisted rows for one session (possibly stale or empty).
+     * @returns the seq to hand the persistence `readFrom`, or `undefined`
+     *   when no unit is registered (no read needed — {@link restore} would
+     *   serve empty values regardless).
+     */
+    restoreFloor(checkpoint) {
+        let floor;
+        for (const registration of this.registrations.values()) {
+            const row = checkpoint[registration.def.key];
+            const need = row !== undefined && row.ver === registration.def.stateVersion
+                ? Math.max(row.seq + 1, 0)
+                : 0;
+            floor = floor === undefined ? need : Math.min(floor, need);
+        }
+        return floor === undefined ? undefined : Math.max(floor - 1, 0);
+    }
+    /**
+     * View a checkpoint's rows without any log read: for every registered
+     * client-visible unit whose row's `ver` matches, serve the schema-validated
+     * `view` of the schema-validated stored state; mismatched, malformed, or absent rows leave their key
+     * absent (a cold or listing consumer treats it as not-yet-available and a
+     * fuller read path refolds it). The zero-I/O rung of the read ladder —
+     * values are as stale as their rows, never wrong.
+     * @param checkpoint - persisted rows for one session (possibly stale or empty).
+     * @returns whole values per key with a usable row; empty when none.
+     */
+    viewCheckpoint(checkpoint) {
+        const values = {};
+        for (const registration of this.registrations.values()) {
+            const def = registration.def;
+            if (def.wire === undefined)
+                continue;
+            const row = checkpoint[def.key];
+            if (row === undefined || row.ver !== def.stateVersion)
+                continue;
+            let state;
+            try {
+                state = def.stateSchema.parse(row.val);
+            }
+            catch {
+                continue;
+            }
+            values[def.key] = def.wire.viewSchema.parse(def.wire.view(state));
+        }
+        return values;
+    }
+    /**
+     * Whether every registered client-visible unit has a usable checkpoint row.
+     * Host-only units do not affect client listing reads. A row is usable only
+     * when its version, persisted state, and rendered client value pass the
+     * current unit definitions.
+     * @param checkpoint - persisted rows for one session (possibly stale or incomplete).
+     * @returns `true` when {@link viewCheckpoint} can serve every current client value.
+     */
+    checkpointHasCurrentViews(checkpoint) {
+        for (const registration of this.registrations.values()) {
+            const def = registration.def;
+            if (def.wire === undefined)
+                continue;
+            const row = checkpoint[def.key];
+            if (row === undefined || row.ver !== def.stateVersion)
+                return false;
+            try {
+                const state = def.stateSchema.parse(row.val);
+                def.wire.viewSchema.parse(def.wire.view(state));
+            }
+            catch {
+                return false;
+            }
+        }
+        return true;
+    }
+    /**
+     * Cold read: fold every persisted unit over a stored log suffix, seeding
+     * each from its checkpoint row when usable — the one read recipe (cached
+     * state + forward tail replay + `view`) applied without a live `Session`.
+     * Call with the events returned by a persistence
+     * `readFrom(id, restoreFloor(checkpoint))` and that same floor as
+     * `baseSeq`; the floor's one-below anchor makes the supplied end honest,
+     * so a shrunk log is detected here. A row is usable iff its
+     * `ver` matches the live unit's `stateVersion`, it does not predate `baseSeq`
+     * (`seq >= baseSeq - 1`), and it does not claim events past the
+     * supplied end (`seq <= endSeq`); an unusable row is discarded
+     * and its key refolds from `init` — which is only sound over the full
+     * log, so a discarded row with `baseSeq > 0` throws (the caller re-reads
+     * from seq 0, e.g. after a crash-repair truncation shrank the log below
+     * a row's watermark).
+     * @param checkpoint - persisted rows for one session (possibly stale or empty).
+     * @param events - the stored events with `seq >= baseSeq`, in seq order.
+     * @param baseSeq - the seq `events` starts at (its first event's seq when non-empty).
+     * @returns the snapshot cut at the supplied log end (`asOfSeq` is the last
+     *   supplied event's seq, `baseSeq - 1` for an empty tail) plus the
+     *   refreshed checkpoint rows at that cut, ready for a durable write-back.
+     */
+    restore(checkpoint, events, baseSeq) {
+        const endSeq = events.at(-1)?.seq ?? baseSeq - 1;
+        const values = {};
+        const refreshed = {};
+        for (const registration of this.registrations.values()) {
+            const def = registration.def;
+            const row = checkpoint[def.key];
+            const usable = row !== undefined
+                && row.ver === def.stateVersion
+                && row.seq >= baseSeq - 1
+                && row.seq <= endSeq;
+            if (!usable && baseSeq > 0) {
+                throw new Error(`session projection ${JSON.stringify(def.key)} cannot restore from seq ${baseSeq}: `
+                    + 'its checkpoint row is missing, version-mismatched, or beyond the supplied log end; re-read from seq 0');
+            }
+            if (def.history === 'active-version' && baseSeq > 0 && events.some(event => event.type === 'session/version' || event.type === 'session/version-selected')) {
+                throw new Error('active-version projection requires a complete log after a path change; re-read from seq 0');
+            }
+            const active = def.history === 'active-version' && baseSeq === 0 ? sessionVersions(events).events() : undefined;
+            let state = active === undefined && usable ? def.stateSchema.parse(row.val) : def.init();
+            const from = usable ? row.seq : baseSeq - 1;
+            for (const event of active ?? events) {
+                if (active !== undefined || event.seq > from)
+                    state = def.apply(state, event);
+            }
+            if (def.wire !== undefined)
+                values[def.key] = def.wire.viewSchema.parse(def.wire.view(state));
+            refreshed[def.key] = { ver: def.stateVersion, seq: endSeq, val: state };
+        }
+        return {
+            snapshot: { asOfSeq: endSeq, values: values },
+            checkpoint: refreshed,
+        };
+    }
+    /** Fold one unit from init over `events`, producing a cell watermarked at the last folded event. */
+    buildCell(def, events) {
+        let state = def.init();
+        const source = def.history === 'active-version' ? sessionVersions(events).events() : events;
+        for (const event of source)
+            state = def.apply(state, event);
+        return { state, observedSeq: (events.at(-1)?.seq ?? -1) };
+    }
+    /** Read (or lazily build, folding the full in-memory log) one unit's cell. */
+    cellFor(registration, session) {
+        let cell = registration.cells.get(session);
+        if (cell === undefined) {
+            cell = this.buildCell(registration.def, session.events);
+            registration.cells.set(session, cell);
+        }
+        return cell;
+    }
+    /** Eager drive: pass one committed event through every registered unit; notify on changed references. */
+    drive(session, event) {
+        for (const registration of this.registrations.values()) {
+            let cell = registration.cells.get(session);
+            if (cell === undefined) {
+                // Late build mid-stream: fold history before this event (seq = log
+                // index, so the prefix slice is exact), then take the normal gate.
+                cell = this.buildCell(registration.def, session.events.slice(0, event.seq));
+                registration.cells.set(session, cell);
+            }
+            const next = registration.def.history === 'active-version' && (event.type === 'session/version' || event.type === 'session/version-selected')
+                ? this.buildCell(registration.def, session.events).state : registration.def.apply(cell.state, event);
+            const changed = !Object.is(next, cell.state);
+            cell.state = next;
+            cell.observedSeq = event.seq;
+            if (changed && registration.def.wire !== undefined && this.listeners.size > 0) {
+                const value = registration.def.wire.viewSchema.parse(registration.def.wire.view(next));
+                for (const listener of this.listeners) {
+                    listener(session, registration.def.key, value, event.seq);
+                }
+            }
+        }
+    }
+}
+export default SessionProjectionRegistry;
+//# sourceMappingURL=index.js.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@hydraharness/harness-session-projection`.
+ * @module @hydraharness/harness-session-projection/invariant
+ */
+import type { Context } from '@hydraharness/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "session-projection-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/invariant.js

@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@hydraharness/harness-session-projection`.
+ * @module @hydraharness/harness-session-projection/invariant
+ */
+const PACKAGE_NAME = '@hydraharness/harness-session-projection';
+/** Cordis companion plugin name. */
+export const name = 'session-projection-invariant';
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants'];
+/**
+ * No runtime invariant: the registry's own contracts (duplicate-key and
+ * stateVersion rejection, effect-tied removal, the Object.is change gate) are
+ * enforced synchronously inside the service and proven by its spec, the
+ * drive relation (every committed `session/event` passes every unit) would
+ * require re-running the drive to check — duplicating the implementation
+ * rather than detecting drift — and the served-value relation (every served
+ * key has a live registration) lives on each carrier's wire path, which
+ * emits no cordis event this companion could observe; carrier specs assert
+ * it. Synchronous-unit discipline is enforced as far as practical by the
+ * boundary `schema.parse` (a Promise-returning view fails loudly).
+ */
+const install = () => { };
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+/* jscpd:ignore-end */
+//# sourceMappingURL=invariant.js.map

package/lib/types/types.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Pure-type outlet of the session-projection Service Definition: the one projection type
+ * table, importable from client aggregates without dragging the host-side
+ * cordis Context merges of the package root (@hydraharness/harness-agent → @hydraharness/harness-session). Domain
+ * packages may declare-merge through either the package root or this outlet —
+ * re-export preserves symbol identity, so both land on the same table.
+ *
+ * @module @hydraharness/harness-session-projection/types
+ */
+/**
+ * The merge-extensible client projection table shared by wire blocks, client
+ * cells, and React hooks. Domain packages merge their client-visible key here;
+ * values are wire-JSON whole values. How a value is rendered is the slot
+ * system's business, never this layer's.
+ */
+export interface SessionProjectionMap {
+}
+/**
+ * The merge-extensible host fold-state table. Each client-visible key also
+ * appears in {@link SessionProjectionMap}; host-only keys appear only here.
+ * Values must be plain JSON so the projection cache can persist them.
+ */
+export interface SessionProjectionStateMap {
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/types/types.js

@@ -0,0 +1,11 @@
+/**
+ * Pure-type outlet of the session-projection Service Definition: the one projection type
+ * table, importable from client aggregates without dragging the host-side
+ * cordis Context merges of the package root (@hydraharness/harness-agent → @hydraharness/harness-session). Domain
+ * packages may declare-merge through either the package root or this outlet —
+ * re-export preserves symbol identity, so both land on the same table.
+ *
+ * @module @hydraharness/harness-session-projection/types
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@hydraharness/harness-session-projection",
+  "description": "Session-projection seam: the merge-extensible projection type table, the provider contract, and the ctx.sessionProjections registry serving whole current values of log-derived per-session state",
+  "hydra": {
+    "plugin": {
+      "application": "Build current session views, such as goals and statistics, from recorded conversation events."
+    }
+  },
+  "version": "0.1.1-rc.5",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MaiHongPhong1902/Hydra-Harness.git",
+    "directory": "packages/session/session-projection"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./types": {
+      "types": "./lib/types/types.d.ts",
+      "default": "./lib/types/types.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "zod": "^4.4.3"
+  },
+  "peerDependencies": {
+    "@hydraharness/harness-invariants": "^0.1.1-rc.5",
+    "@hydraharness/harness-session": "^0.1.1-rc.5",
+    "@hydraharness/cordis": "^4.0.2"
+  },
+  "devDependencies": {
+    "@hydraharness/harness-invariants": "^0.1.1-rc.5",
+    "@hydraharness/cordis": "^4.0.2",
+    "@hydraharness/harness-session": "^0.1.1-rc.5"
+  }
+}