feat(genome): working-set-manager PR-1 — typed data layer for cache hierarchy + paging

src/clippy-baseline.txt

@@ -1 +1 @@
-146
+148

src/shared/generated/genome/AccessDenied.ts

@@ -0,0 +1,36 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { PageRef } from "./PageRef";
+import type { PersonaId } from "./PersonaId";
+
+/**
+ * Typed refusal from the MMU-style permission check. Per
+ * GENOME-FOUNDRY-SENTINEL Part 4: "AccessDenied is loud. Audit log
+ * captures it. This is how the substrate makes per-persona privacy
+ * structural rather than policy."
+ *
+ * PR-1 ships the wire shape. PR-2 / PR-3 add the
+ * `WorkingSetManager::audit_access` enforcement that produces it,
+ * and audit-recorder (#1344, codex's PR) subscribes to it as one of
+ * its `AccessDenied` audit-log inputs.
+ */
+export type AccessDenied = { 
+/**
+ * Which persona attempted the access.
+ */
+actor: PersonaId, 
+/**
+ * Which page was attempted.
+ */
+page: PageRef, 
+/**
+ * Which persona OWNS that page (whose private region was it
+ * reaching into). `None` means "no owner — the region is
+ * substrate-controlled (e.g. foundry-imported)" and the denial
+ * is for a different reason (license, policy, etc.).
+ */
+owner?: PersonaId, 
+/**
+ * Human-readable reason. Per Joel's "never swallow errors" rule:
+ * loud, specific, debuggable.
+ */
+reason: string, };

src/shared/generated/genome/ArtifactId.ts

@@ -0,0 +1,9 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+/**
+ * Stable per-artifact identifier. Content-addressed (the value IS
+ * the SHA-256-derived UUID of the artifact bytes), so two callers
+ * computing the ID independently arrive at the same value. Typed
+ * wrapper distinct from `PersonaId`.
+ */
+export type ArtifactId = string;

src/shared/generated/genome/EvictionPolicy.ts

@@ -0,0 +1,15 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+/**
+ * Per-tier eviction policy. The variants are dimensioned by the
+ * per-role table in GENOME-FOUNDRY-SENTINEL Part 2:
+ *
+ * | Role | Policy | When eviction fires |
+ * |------|--------|---------------------|
+ * | Fast | `LruWithinTurn` | sub-step needs a page not resident |
+ * | Warm | `LruAcrossTurns { window }` (discrete-GPU only) | Fast spill |
+ * | Bench | `LfuPlusRecency` | Warm spill (discrete) / Fast spill (UMA) |
+ * | Cold | `DemandAlignedWithRefinedPreference` | Bench spill |
+ * | Frozen | `AppendOnlyGcOnSleep` | never in hot path |
+ */
+export type EvictionPolicy = { "kind": "lruWithinTurn" } | { "kind": "lruAcrossTurns", windowTurns: number, } | { "kind": "lfuPlusRecency" } | { "kind": "demandAlignedWithRefinedPreference" } | { "kind": "appendOnlyGcOnSleep" };

src/shared/generated/genome/EvictionRecord.ts

@@ -0,0 +1,41 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { EvictionPolicy } from "./EvictionPolicy";
+import type { PageRef } from "./PageRef";
+import type { TierRole } from "./TierRole";
+
+/**
+ * Typed record emitted to the trace bus every time a page is evicted
+ * from some tier. The reason carries the policy that fired (LRU,
+ * LFU, etc.). Recurring evictions of the same page across turns are
+ * the signal sentinel uses to upgrade the page's tier policy.
+ *
+ * Per GENOME-FOUNDRY-SENTINEL Part 2: "every evicted page emits an
+ * EvictionRecord to the trace bus." PR-3 wires this through my just-
+ * shipped artifact dispatch (#1339 + #1343); PR-1 ships the shape.
+ */
+export type EvictionRecord = { 
+/**
+ * The page that was evicted.
+ */
+page: PageRef, 
+/**
+ * Which tier evicted it.
+ */
+fromRole: TierRole, 
+/**
+ * Where the page went (Some) or whether it was dropped entirely
+ * (None — only valid for Cold/Frozen during GC).
+ */
+toRole?: TierRole, 
+/**
+ * The policy that fired this eviction. Lets the trace bus
+ * reconstruct *why* without re-running the policy.
+ */
+policyFired: EvictionPolicy, 
+/**
+ * Time spent on the eviction itself (selection + tier-write +
+ * metadata update). Doesn't include the time the calling
+ * page_in/page_out spent blocked on it — that's a separate
+ * signal on the caller side.
+ */
+elapsedUs: number, };

src/shared/generated/genome/PageFault.ts

@@ -0,0 +1,40 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { EvictionRecord } from "./EvictionRecord";
+import type { PageRef } from "./PageRef";
+import type { PersonaId } from "./PersonaId";
+import type { TierRole } from "./TierRole";
+
+/**
+ * Typed event emitted when a persona's composition needs a page that
+ * isn't already in its working set. Sentinel observes these to detect
+ * patterns: a persona that page-faults on the same page across many
+ * turns is a signal to either pre-fetch it or pin it higher.
+ *
+ * `from_role: None` means "true cold miss" — the page does not exist
+ * in any tier yet (typically a fresh KV-cache entry or a never-loaded
+ * MoE expert). `from_role: Some(role)` means "tier promotion" — the
+ * page existed in `role` and got moved up.
+ */
+export type PageFault = { page: PageRef, 
+/**
+ * Where the page was before the fault. `None` for true cold
+ * miss (page didn't exist yet).
+ */
+fromRole?: TierRole, 
+/**
+ * Where the page lives after the fault is serviced.
+ */
+toRole: TierRole, persona: PersonaId, 
+/**
+ * Time spent servicing the fault (tier lookup + transfer +
+ * eviction-if-any). Drives sentinel's "is this page worth
+ * pre-fetching" calculus.
+ */
+elapsedUs: number, 
+/**
+ * If servicing the fault required evicting another page, the
+ * record of that eviction. Lets sentinel correlate cause +
+ * effect across the trace bus in one record instead of joining
+ * two separate event streams.
+ */
+evictionCost?: EvictionRecord, };

src/shared/generated/genome/PageHandle.ts

@@ -0,0 +1,18 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { PageRef } from "./PageRef";
+import type { TierRole } from "./TierRole";
+
+/**
+ * Opaque handle returned by `page_in`. Carries enough context for the
+ * caller to use the page without exposing the tier-internal storage.
+ * PR-1 ships the wire shape; PR-2 (trait + impl) gives the type
+ * behaviors. The `tier_role` field lets the caller decide whether to
+ * pin the handle (Fast / Warm) or stream-read it (Cold / Frozen).
+ */
+export type PageHandle = { page: PageRef, tierRole: TierRole, 
+/**
+ * Byte size of the page as resident in `tier_role`. For Cold /
+ * Frozen this is the size at-rest; for Fast / Warm it's the
+ * size in accelerator-addressable memory.
+ */
+sizeBytes: number, };

src/shared/generated/genome/PageKind.ts

@@ -0,0 +1,8 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+/**
+ * What kind of page this is. Used by the working-set manager to pick
+ * the right tier eviction policy (e.g. a `KVCache` page evicts
+ * differently from a `LoRALayer` page even within the same tier).
+ */
+export type PageKind = "loRALayer" | "moEExpert" | "kVCache" | "engram";

src/shared/generated/genome/PageOffset.ts

@@ -0,0 +1,10 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+/**
+ * Sub-artifact offset for paging artifacts that don't fit in a
+ * single page (MoE experts, KV chunks, large engrams). For
+ * single-page artifacts the offset is `Whole`. Newtype around
+ * the variants so it serializes cleanly and gives the type system
+ * a hook to enforce "this PageRef points inside ArtifactId X".
+ */
+export type PageOffset = { "kind": "whole" } | { "kind": "expert", expertIndex: number, } | { "kind": "range", startByte: number, endByte: number, };

src/shared/generated/genome/PageRef.ts

@@ -0,0 +1,15 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { ArtifactId } from "./ArtifactId";
+import type { PageKind } from "./PageKind";
+import type { PageOffset } from "./PageOffset";
+
+/**
+ * A fully-qualified reference to one page in the substrate. Three
+ * components: the kind (for tier-policy dispatch), the artifact
+ * (which content-addressed blob the page lives in), and the offset
+ * (where in the artifact the page is).
+ *
+ * Hash + Eq let `PageRef` serve as a `HashMap` key in
+ * `WorkingSet.pages`.
+ */
+export type PageRef = { kind: PageKind, artifact: ArtifactId, offset: PageOffset, };

src/shared/generated/genome/PersonaId.ts

@@ -0,0 +1,9 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+/**
+ * Stable per-persona identifier. UUID-shaped so it can't be confused
+ * with `ArtifactId` (same primitive, different type — the type system
+ * catches swapped arguments). See module docstring for the rehoming
+ * plan.
+ */
+export type PersonaId = string;

src/shared/generated/genome/ResidentPage.ts

@@ -0,0 +1,23 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { PageRef } from "./PageRef";
+import type { TierRole } from "./TierRole";
+
+/**
+ * A page currently in some persona's working set. Tracks the
+ * per-turn metadata the eviction policy needs (last_access,
+ * access_count_window) and the pinning flag the composition layer
+ * sets to prevent mid-turn evictions of in-use pages.
+ *
+ * `last_access_ms` is `u64` (unix-ms) instead of `std::time::Instant`
+ * because (a) ts-rs needs a wire-stable representation and (b) the
+ * trace bus can replay records across processes where `Instant` is
+ * meaningless. Sub-millisecond timing for hot-path decisions stays
+ * in caller-side `Instant`s.
+ */
+export type ResidentPage = { page: PageRef, role: TierRole, lastAccessMs: number, accessCountWindow: number, 
+/**
+ * When true the eviction policy must skip this page until the
+ * composition layer unpins it. Composition-pinned pages cannot
+ * evict mid-turn.
+ */
+pinned: boolean, };

src/shared/generated/genome/TierCapacity.ts

@@ -0,0 +1,19 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+/**
+ * Current vs configured byte capacity of a tier. The governor sets
+ * `configured_limit` from the policy file (Part 11). The tier itself
+ * reports `current_used` from its backing store. The delta is the
+ * available headroom; when `current_used` approaches `configured_limit`,
+ * the tier triggers eviction.
+ */
+export type TierCapacity = { 
+/**
+ * Bytes currently in use by this tier's backing store.
+ */
+currentUsed: number, 
+/**
+ * Bytes the tier is configured to hold (policy limit, NOT a
+ * hardware ceiling). The governor enforces; the tier respects.
+ */
+configuredLimit: number, };

src/shared/generated/genome/TierError.ts

@@ -0,0 +1,9 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { PageRef } from "./PageRef";
+import type { TierRole } from "./TierRole";
+
+/**
+ * Errors a tier's read/write operations can surface. PR-1 ships
+ * the shape; PR-2's `TierStore` trait returns it.
+ */
+export type TierError = { "kind": "pageNotFound", page: PageRef, } | { "kind": "noEvictionCandidate", from_role: TierRole, bytes_needed: number, } | { "kind": "backingStoreIo", reason: string, } | { "kind": "roleNotConfigured", role: TierRole, };

src/shared/generated/genome/TierRole.ts

@@ -0,0 +1,27 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+/**
+ * The five named tier roles. Discrete-GPU configurations populate
+ * all five; UMA configurations omit `Warm` (Fast and Warm would
+ * share the same physical bytes there — an `Fast`→`Warm` eviction
+ * would be a no-op, so the type system removes the option). Vision
+ * Pro / iOS / M-series MacBooks are UMA-class and have four roles
+ * in their governor's `Vec<TierConfig>`. Embedded targets may drop
+ * to three tiers (Fast, Cold, Frozen) if Bench would compete with
+ * foreground responsiveness.
+ *
+ * Tier semantics:
+ * - `Fast` — bytes the accelerator can read at peak bandwidth.
+ *   Discrete GPU: VRAM. UMA: the hot portion of unified memory.
+ * - `Warm` — bytes the accelerator can reach with a copy or a
+ *   tier-promotion. Discrete GPU: host RAM (PCIe-attached). UMA:
+ *   omitted (same pool as Fast).
+ * - `Bench` — bytes the host can read at memory speed; cold to the
+ *   accelerator. A designated portion of system RAM holding the
+ *   genome catalog + recently-used artifacts. Always present.
+ * - `Cold` — bytes on local SSD. The full genome pool lives here on
+ *   every hardware class. Read latency is milliseconds.
+ * - `Frozen` — bytes on archive storage. Append-only with provenance
+ *   preserved. Never on the hot path; GC during sleep.
+ */
+export type TierRole = "fast" | "warm" | "bench" | "cold" | "frozen";

src/shared/generated/genome/WorkingSet.ts

@@ -0,0 +1,22 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { PersonaId } from "./PersonaId";
+import type { ResidentPage } from "./ResidentPage";
+import type { WorkingSetCapacity } from "./WorkingSetCapacity";
+
+/**
+ * A persona's currently-resident pages plus its policy budget.
+ * PR-1 ships the data shape with no traits / no impl — PR-2 adds
+ * the `WorkingSetManager` trait that produces and consumes these.
+ *
+ * `pages` is keyed by `PageRef` because that's the lookup the hot
+ * path needs (composition asks "is this page resident?"). HashMap
+ * instead of BTreeMap because access is by exact match, not range.
+ */
+export type WorkingSet = { persona: PersonaId, 
+/**
+ * All resident pages for this persona, keyed by a stringified
+ * `PageRef`. On the wire this serializes as a JSON object with
+ * string keys (serde's HashMap → object behavior). The TS side
+ * sees a record keyed by string with `ResidentPage` values.
+ */
+pages: { [key in string]: ResidentPage }, capacity: WorkingSetCapacity, };

src/shared/generated/genome/WorkingSetCapacity.ts

@@ -0,0 +1,25 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+/**
+ * Per-persona working-set budget the governor publishes. Bytes
+ * (not page counts) because pages vary in size by kind. The governor
+ * re-publishes when policy changes (hardware probe shifts class,
+ * pressure event drops the cap, etc.).
+ */
+export type WorkingSetCapacity = { 
+/**
+ * Maximum bytes the persona's Fast tier is allowed to hold.
+ */
+fastBytes: number, 
+/**
+ * Maximum bytes in Warm. Set to 0 on UMA hardware (where Warm
+ * is structurally absent) — code that addresses Warm on UMA
+ * hits `TierError::RoleNotConfigured`.
+ */
+warmBytes: number, 
+/**
+ * Maximum bytes pinned per-turn (composition lock). Smaller
+ * than fast_bytes because pinning starves the eviction policy;
+ * the governor caps to prevent runaway pinning.
+ */
+maxPinnedBytes: number, };

src/shared/generated/genome/index.ts

@@ -0,0 +1,20 @@
+// Auto-generated barrel export — do not edit manually
+// Source: generator/generate-rust-bindings.ts
+// Re-generate: npx tsx generator/generate-rust-bindings.ts
+
+export type { AccessDenied } from './AccessDenied';
+export type { ArtifactId } from './ArtifactId';
+export type { EvictionPolicy } from './EvictionPolicy';
+export type { EvictionRecord } from './EvictionRecord';
+export type { PageFault } from './PageFault';
+export type { PageHandle } from './PageHandle';
+export type { PageKind } from './PageKind';
+export type { PageOffset } from './PageOffset';
+export type { PageRef } from './PageRef';
+export type { PersonaId } from './PersonaId';
+export type { ResidentPage } from './ResidentPage';
+export type { TierCapacity } from './TierCapacity';
+export type { TierError } from './TierError';
+export type { TierRole } from './TierRole';
+export type { WorkingSet } from './WorkingSet';
+export type { WorkingSetCapacity } from './WorkingSetCapacity';

src/shared/generated/index.ts

@@ -38,6 +38,7 @@ export * from './cognition';
 export * from './comms';
 export * from './dataset';
 export * from './forge';
+export * from './genome';
 export * from './gpu';
 export * from './grid';
 export * from './inference';