kioku-core 0.3.0.0 → 0.4.0.0

raw patch · 43 files changed

+8098/−1543 lines, 43 filesdep ~filepathdep ~keirodep ~keiro-corePVP ok

version bump matches the API change (PVP)

Dependency ranges changed: filepath, keiro, keiro-core, kioku-api, kioku-core, kioku-migrations, kiroku-store, shibuya-core, shibuya-kiroku-adapter, unordered-containers

API changes (from Hackage documentation)

Files

• CHANGELOG.md +179/−0
• kioku-core.cabal +52/−16
• src/Kioku/Database/Schema.hs +89/−0
• src/Kioku/Distill/L1.hs +212/−104
• src/Kioku/Distill/L2.hs +208/−99
• src/Kioku/Distill/L3.hs +196/−83
• src/Kioku/Distill/Timer.hs +52/−23
• src/Kioku/Distill/Timer/Worker.hs +138/−27
• src/Kioku/Memory.hs +308/−32
• src/Kioku/Memory/Domain.hs +168/−8
• src/Kioku/Memory/Embedding/Worker.hs +240/−52
• src/Kioku/Memory/EventStream.hs +22/−5
• src/Kioku/Memory/ReadModel.hs +322/−192
• src/Kioku/Partition.hs +92/−0
• src/Kioku/Recall.hs +546/−163
• src/Kioku/Recall/Capability.hs +13/−7
• src/Kioku/Session.hs +336/−53
• src/Kioku/Session/Domain.hs +183/−8
• src/Kioku/Session/EventStream.hs +24/−6
• src/Kioku/Session/ReadModel.hs +439/−258
• src/Kioku/Worker/Failure.hs +12/−0
• src/Kioku/Workspace.hs +222/−0
• test/Kioku/AwaitingSpec.hs +33/−13
• test/Kioku/CodecCompatSpec.hs +181/−4
• test/Kioku/DistillSpec.hs +332/−86
• test/Kioku/EmbeddingWorkerSpec.hs +124/−15
• test/Kioku/IdempotencySpec.hs +55/−40
• test/Kioku/MemorySpaceSpec.hs +461/−0
• test/Kioku/PortfolioAccessSpec.hs +523/−0
• test/Kioku/ReadModelReconcileSpec.hs +114/−44
• test/Kioku/RecallCompatSpec.hs +234/−0
• test/Kioku/RecallHarness.hs +157/−108
• test/Kioku/RecallSqlSpec.hs +108/−24
• test/Kioku/RecallTargetSpec.hs +458/−0
• test/Kioku/SchemaSpec.hs +91/−16
• test/Kioku/ScopeIdentitySpec.hs +28/−3
• test/Kioku/SessionInvariantsSpec.hs +94/−35
• test/Kioku/SessionLineageSpec.hs +23/−8
• test/Kioku/SpaceFixtures.hs +89/−0
• test/Kioku/SpaceIsolationSpec.hs +537/−0
• test/Kioku/TimerWorkerSpec.hs +204/−11
• test/Kioku/WorkspaceSpec.hs +187/−0
• test/Main.hs +12/−0

@@ -1,5 +1,184 @@ # Changelog +## 0.4.0.0 — 2026-08-17++### Breaking Changes++- Moved onto the Keiro 0.13 / Kiroku 0.8 / Shibuya 0.9 cohort: `keiro ^>=0.13.0.0`,+  `keiro-core ^>=0.13.0.0`, `kiroku-store ^>=0.8.0.0`, `shibuya-core ^>=0.9.0.0`, and+  `shibuya-kiroku-adapter ^>=0.5.1.1`. A consumer that writes its own `Store` interpreter must+  handle Kiroku's new retention, checkpoint-initialization and visible-head constructors; one that+  matches exhaustively on `Kiroku.Store.Error.StoreError` must add arms for+  `TransientTransactionFailure` and `HistoryRetentionActive`; and one that matches on+  `Shibuya.Core.Ack.DeadLetterReason` must handle the new `ApplicationFailure` arm.+- The library now builds with `-Werror=incomplete-patterns`. This is breaking only for a fork+  carrying its own partial matches; `kioku-core` itself was already clean.++- Kioku's projections now live in the `kioku` PostgreSQL schema instead of `kiroku`, and every+  statement names them explicitly through the new internal `Kioku.Database.Schema` rather than+  resolving them through `search_path`. The event store is unchanged; Kioku still appends to the+  host's Kiroku streams. The runtime role needs `USAGE ON SCHEMA kioku` in addition to its+  existing table privileges.+- Read-model identities advance with the relations they name: memory v2 -> v3+  (`kioku-memory-v3`), session v4 -> v5 (`kioku-session-v5`), turn v2 -> v3 (`kioku-turn-v3`).+  Keiro's registry stores no physical relation name, so the version bump is what makes a binary+  from the wrong side of `kioku/0012-relocate-projections-to-kioku-schema` fail closed with+  `ReadModelStaleSchema` instead of querying tables that have moved. `kioku-migrate up` reconciles+  the registry; a library embedder must call `Kioku.ReadModel.reconcileReadModelRegistry` itself+  before serving traffic.+- pgvector capability detection now probes schema `kioku`, table `memories`. The `to_regtype`+  check for the `vector` type still resolves against the connection's search path, because the+  extension was deliberately not moved.++### Fixed++- `Kioku.Worker.Failure.isTransientStoreError` now classifies `TransientTransactionFailure` as+  transient and `HistoryRetentionActive` as permanent. Both arms were absent: the first because+  the constructor is new in `kiroku-store` 0.8.0.0, the second since 0.7.0.0. Before 0.8.0.0+  PostgreSQL's `40001`/`40P01` reached this function as `UnexpectedServerError` and were called+  permanent, so a serialization failure or deadlock halted the embedding worker instead of+  retrying it.+++### Breaking Changes++- `recall` takes a `MemoryAccessContext` and a `RecallQuery` instead of a `RecallRequest`, and+  returns `Either RecallError [RecallHit]`. The target says what to search; the memory space comes+  from the context and nothing in the request can change it, so widening a target can never widen+  the tenancy. It is the one read that takes a whole context rather than a `MemorySpaceId`,+  because it is the only one that can be asked to widen.+- `RecallRequest` and the new `legacyRecall` are **deprecated** wrappers for one release.+  `legacyRecall` maps the request's scope through `legacyRecallTarget` — so `ScopeGlobal` stays+  namespace-wide — refuses a request naming a space other than the one its context authorizes,+  and preserves the old `maxResults` edges (zero returns nothing; anything above 100 is clamped,+  which is unobservable because a fused result set holds at most 100 memories). See+  `docs/adr/an-explicit-recall-target-replaces-the-overloaded-scope.md` for the removal+  conditions.+- `ExactScope (ScopeGlobal ns)` — ranked recall of the exact global bucket — **executes**, and+  returns the rows recorded with no entity scope rather than the whole namespace. Each of the+  three targets now compiles to its own SQL: the exact global bucket asks for+  `scope_kind IS NULL AND scope_ref IS NULL`, an exact entity compares both columns, and a+  namespace-wide target carries no scope clause at all. The single parameterised predicate they+  replace read NULL scope columns as "no scope filter", which is why the exact global bucket+  previously had to be refused. See+  `docs/adr/each-recall-target-gets-its-own-statement.md`.+- `RecallError` lost `RecallExactGlobalUnsupported`. Its only remaining constructor is+  `RecallSpaceMismatch`, which only the deprecated `legacyRecall` can produce; `recall` keeps+  returning `Either` so that adding a refusal later is not a breaking change at every call site.+- `RecallStrategy` moved to `kioku-api`'s `Kioku.Api.Recall`. `Kioku.Recall` re-exports it, so an+  existing import keeps working.+- The recall test seams (`selectFtsCandidates`, `selectVectorCandidates`,+  `selectVectorCandidatesDiagnosed`) take a `ResolvedRecall` — a query bound to one authorized+  space with its target already compiled to a scope predicate. `resolveRecall` is the only way to+  build one, and it is total. `selectVectorCandidatesStmt`, `selectVectorCandidatesExactStmt`,+  `vectorCandidateQuery` and `memoryRecordColumns` are replaced by `vectorCandidateSql` /+  `ftsCandidateSql` and the `runVectorAnnCandidates` / `explainVectorAnnCandidates` /+  `explainVectorExactCandidates` / `explainFtsCandidates` transaction seams, which is how the+  recall harness stopped keeping its own copy of the vector SQL to `EXPLAIN`.+- `Kioku.Distill.L1.FindMergeCandidates` receives the pass's `MemoryAccessContext` rather than its+  `MemorySpaceId`, and its error channel is `L1Error` rather than `ReadModelError`. `L1Error`+  gained `L1RecallRefused`, so a recall refusal cannot arrive at the consolidator as an empty+  candidate list.+- **Behavior change:** `Kioku.Distill.L1.recallCandidates` draws merge candidates from the+  session's exact scope rather than from its whole namespace, so it agrees with+  `scopedScanCandidates` about which memories a session's atoms may merge into. A globally-scoped+  session used to draw candidates from every entity scope beside it — and could merge an atom into+  one, rewriting a memory that feeds a scene the session has nothing to do with. Entity-scoped+  sessions are unaffected; globally-scoped ones will report more `stored` and fewer `merged`.+- Every memory and session command payload gained required fields: `memorySpaceId` and+  `actorPrincipal` on all of them, plus `ownerPrincipal` on `RecordMemoryData`,+  `StartSessionData`, and `RecordInteractiveSessionData`. Every construction site is a compile+  error until updated. The corresponding event payloads gained the same fields.+- Every write function takes a `MemoryAccessContext` first and is named `*WithContext`:+  `recordWithContext`, `supersedeWithContext`, `archiveWithContext`, `updateTagsWithContext`,+  `updateConfidenceWithContext`, `mergeWithContext`, `startWithContext`, `awaitInputWithContext`,+  `resumeWithContext`, `forceResumeWithContext`, `completeWithContext`, `failSessionWithContext`,+  `recordInteractiveWithContext`, and `recordTurnWithContext`. The unsuffixed names remain as+  **deprecated** wrappers for one release; they take no context and refuse any payload naming a+  space other than `legacyMemorySpaceId`.+- `distillSessionL1` takes a `MemoryAccessContext` first and demands the `MemoryDistill`+  permission before any LLM call.+- `fireL1Timer`, `fireKiokuTimer`, `runKiokuTimerWorkerOnce`, and `drainKiokuTimers` take a+  `MemoryContextProvider`, because a worker discovers its own work and cannot arrive holding a+  context.+- `MemoryWriteError` gained `MemoryNotPermitted`, `MemorySpaceMismatch`, and+  `MemoryActorMismatch`; `SessionWriteError` gained the three equivalents; `L1Error` gained+  `L1NotPermitted`.+- An L1 timer payload that cannot be parsed now dead-letters instead of being ignored. Payloads+  written before this release parse fine and fire in the legacy space.+- Every read function takes a `MemorySpaceId` first and returns nothing outside it:+  `Kioku.Memory.getMemoryRowById`, `getActiveRowsInNamespace`, `getActiveRowsByScope`,+  `getRowsBySession`, `getActiveRowsByType`, `getSupersessionChain`; `Kioku.Session.getById`,+  `getRecentInNamespace`, `getByScope`, `getByFocus`, `getByStartedRange`, `getChain`,+  `getDelegationChildren`, `getAwaitingByCorrelationKey`, `getTurns`; `Kioku.Recall.getById`,+  `getActiveByScope`, `getActiveInNamespace`, `getGlobal`, `getBySession`, `getByType`;+  `Kioku.Distill.L2.getScenesByScope` and `regenerateScene`; `Kioku.Distill.L3.getPersonaByScope`+  and `regeneratePersona`. Pass `memoryContextSpace` of the context that authorized the read.+- `RecallRequest` gained a required `memorySpaceId` field.+- Every read-model query record is now a record with named fields rather than a positional+  constructor, with `memorySpaceId` first: `MemoryByIdQuery`, `MemoriesByNamespaceQuery`,+  `MemoriesByScopeQuery`, `MemoriesBySessionQuery`, `MemoriesByTypeQuery`,+  `MemorySupersessionChainQuery`, and the nine session equivalents.+- `MemoryRow`, `SessionRow`, `TurnRow`, `SceneRow`, and `PersonaRow` gained a leading+  `memorySpaceId` field.+- `fireL2SceneTimer` and `fireL3PersonaTimer` take a `MemoryContextProvider`, like `fireL1Timer`.+- Scene and persona timer ids and correlation ids now include the memory space, so two spaces+  sharing a namespace and scope no longer share one timer. Timers already scheduled keep their+  old ids and fire in the legacy space.+- `runEmbeddingWorkerHost`, `embeddingWorkerProcessor`, and `embeddingHandler` take a+  `MemoryContextProvider`, like the timer handlers, because the embedding worker also discovers+  its own work.+- `backfillMissingEmbeddings` takes an `EmbeddingWorkerEnv` and an `EmbeddingBackfillScope` in+  place of an `EmbeddingModel` and a dimension count.+- `EmbedOutcome` gained `EmbedSpaceMismatch`.+- `runKiokuTimerWorkerOnce` and `drainKiokuTimers` require `Tracing :> es`.+- Scene and persona mirrors moved from `.kioku/{scenes,persona}/<slug>.md` to+  `.kioku/spaces/<space-dir>/{scenes,persona}/<slug>.md`. `sceneMirrorPath` and+  `personaMirrorPath` keep their signatures — the space comes from the row — but return different+  paths. Run `kioku migrate-artifacts` to relocate existing files.+- A cross-space id on a write path now returns `MemoryNotFound` / `SessionNotFound` rather than+  reaching the aggregate and returning `MemoryCommandRejected`. That closes the existence oracle+  the previous release documented: an id in another space is now indistinguishable from one that+  was never written.+- Read-model registry identities advanced: memory models to v2 / `kioku-memory-v2`, session models+  to v4 / `kioku-session-v4`, turns to v2 / `kioku-turn-v2`. `kioku-migrate` reconciles them; a+  host applying migrations as a library must call `reconcileReadModelRegistry` itself.++### Added++- `Kioku.Partition` — the single place that decides what a payload written before memory spaces+  means: the legacy space, and a legacy-marked agent label. No codec invents its own default.+- `Kioku.Distill.Timer.L1TimerPayload`, which carries the memory space a scheduled distillation+  pass belongs to.+- `Kioku.Workspace` — the per-space artifact layout and the migration of the pre-partition tree.+  A memory space id is validated for a database column rather than for a path, so the directory+  component is a sanitised prefix plus a digest of the exact id: `..` cannot escape+  `.kioku/spaces`, and two ids that differ only in case cannot share a directory.+- `kioku migrate-artifacts` — a dry run by default; `--apply` copies, never moves, and refuses a+  destination whose content differs.+- `kioku worker --backfill --space ID` — an embedding backfill bounded to one memory space. The+  default stays every space.+- A `kioku.timer.fire` span per fire attempt, carrying `kioku.memory_space_id`, the timer id, the+  attempt count, a bounded `kioku.timer.outcome`, and the failure reason. Metrics gained no space+  or principal label and must not: a space is caller-supplied text.+- Aggregate state carries the memory space, and every non-creation edge guards on it, so a command+  naming a different space is refused by the state machine rather than by a read-model precheck.++### Compatibility++- Events already on disk keep decoding. They land in `legacyMemorySpaceId`; an old free-text+  `agentId` is recorded as a legacy-marked label and never rewritten into a directory principal;+  an event that recorded no agent is `UnattributedPrincipal`. Encoders emit only the new form.+- Reads are partitioned by the schema. Every read-model table carries a non-null+  `memory_space_id`, backfilled to `kioku_legacy`, and every statement names it. An upgraded+  single-space deployment sees exactly what it saw before. See+  `docs/user/upgrading-to-memory-spaces.md`.+- Workspace mirrors are partitioned. Files written before this release stay at `.kioku/scenes`+  and `.kioku/persona`, which nothing writes to any more; `kioku migrate-artifacts` reports and+  relocates them. The one exception is deletion: emptying a scope in the legacy space unlinks its+  historical mirror too, because forgotten content surviving on disk is a retention failure+  rather than a stale cache.+ ## 0.3.0.0 — 2026-08-05  ### Breaking Changes

@@ -1,6 +1,6 @@ cabal-version:   3.0 name:            kioku-core-version:         0.3.0.0+version:         0.4.0.0 synopsis:        Reusable agent memory runtime description:   Core runtime for kioku. M1 establishes the application effect stack; later@@ -27,6 +27,7 @@   ghc-options:     -Wall -Wcompat -Widentities -Wincomplete-record-updates     -Wincomplete-uni-patterns -Wpartial-fields -Wredundant-constraints+    -Werror=incomplete-patterns  common shared   default-language:   GHC2024@@ -42,8 +43,8 @@     TemplateHaskell  library-  import:          warnings, shared-  hs-source-dirs:  src+  import:           warnings, shared+  hs-source-dirs:   src   exposed-modules:     Kioku.App     Kioku.Distill.Consolidate@@ -64,6 +65,7 @@     Kioku.Memory.Embedding.Worker     Kioku.Memory.EventStream     Kioku.Memory.ReadModel+    Kioku.Partition     Kioku.ReadModel     Kioku.Recall     Kioku.Recall.Capability@@ -72,7 +74,32 @@     Kioku.Session.EventStream     Kioku.Session.ReadModel     Kioku.Worker.Failure+    Kioku.Workspace +  -- Where Kioku's projections physically live is Kioku's business, so the+  -- qualified relation names stay internal rather than becoming a public API a+  -- consumer could pin its own SQL to.+  other-modules:    Kioku.Database.Schema++  -- Works around a GHC 9.12.4 coercion-optimiser bug that makes the *profiled*+  -- build of Kioku.Distill.L1 panic:+  --+  --     panic! (the 'impossible' happened) / coercionKind / ConsSymbolDef+  --     pprPanic, called at compiler/GHC/Core/Coercion.hs:2550:17+  --+  -- `ConsSymbolDef` is the built-in rewrite axiom behind the type-level Symbol+  -- machinery that mmzk-typeid's `Data.KindID.V7` prefix validation produces.+  -- With -prof, optCoercion builds an AxiomRuleCo whose argument coercions no+  -- longer let the built-in rule re-prove itself, and coercionKind crashes.+  --+  -- This lives in ghc-prof-options, not ghc-options, so ordinary builds keep the+  -- coercion optimiser; only the profiled way pays for the workaround. Profiling+  -- detail is NOT the trigger -- `profiling-detail: none` and `late-toplevel`+  -- both still panic -- so do not "simplify" this to a -fprof-auto tweak.+  -- Retest and drop once the toolchain moves off GHC 9.12.4. Full write-up:+  -- mori://MMZK1526/mmzk-typeid/upstream-issues/mmzk-typeid-kindid-ghc-9-12-4-profiling-coercionkind-panic+  ghc-prof-options: -fno-opt-coercion+   -- Two bounds below look wrong but are not. baikai-effectful has no 0.4   -- release; 0.3.0.2 is its newest and is itself built against baikai ^>=0.4.0,   -- so its version lags the rest of the Baikai cohort by design. And shikumi is@@ -100,18 +127,19 @@     , hasql-transaction       >=1.0       && <1.3     , hs-opentelemetry-api    >=1.0       && <1.1     , keiki                   ^>=0.9.0.0-    , keiro                   ^>=0.11.0.0-    , keiro-core              ^>=0.11.0.0-    , kioku-api               ^>=0.3.0.0-    , kiroku-store            ^>=0.3.0.1+    , keiro                   ^>=0.13.0.0+    , keiro-core              ^>=0.13.0.0+    , kioku-api               ^>=0.4.0.0+    , kiroku-store            ^>=0.8.0.0     , lens                    >=5.2       && <5.4     , mmzk-typeid             >=0.7       && <0.8-    , shibuya-core            >=0.8.0.1   && <0.9-    , shibuya-kiroku-adapter  ^>=0.4.0.0+    , shibuya-core            ^>=0.9.0.0+    , shibuya-kiroku-adapter  ^>=0.5.1.1     , shikumi                 ^>=0.3.0.1     , shikumi-trace           ^>=0.2.0.1     , text                    >=2.1       && <2.2     , time                    >=1.12      && <1.15+    , unordered-containers    >=0.2       && <0.3     , uuid                    >=1.3       && <1.4     , vector                  ^>=0.13.2.0 @@ -125,16 +153,23 @@     Kioku.DistillSpec     Kioku.EmbeddingWorkerSpec     Kioku.IdempotencySpec+    Kioku.MemorySpaceSpec+    Kioku.PortfolioAccessSpec     Kioku.ReadModelReconcileSpec+    Kioku.RecallCompatSpec     Kioku.RecallHarness     Kioku.RecallSpec     Kioku.RecallSqlSpec+    Kioku.RecallTargetSpec     Kioku.ReiCompatSpec     Kioku.SchemaSpec     Kioku.ScopeIdentitySpec     Kioku.SessionInvariantsSpec     Kioku.SessionLineageSpec+    Kioku.SpaceFixtures+    Kioku.SpaceIsolationSpec     Kioku.TimerWorkerSpec+    Kioku.WorkspaceSpec    hs-source-dirs: test   ghc-options:    -threaded -rtsopts -with-rtsopts=-N@@ -148,16 +183,17 @@     , directory                      >=1.3     , effectful                      >=2.5     , effectful-core                 >=2.5+    , filepath                       >=1.4     , hasql                          >=1.6     , hasql-transaction              >=1.0-    , keiro                          ^>=0.11.0.0-    , keiro-core                     ^>=0.11.0.0-    , kioku-api                      ^>=0.3.0.0-    , kioku-core                     ^>=0.3.0.0-    , kioku-migrations:test-support  ^>=0.3.0.0-    , kiroku-store                   ^>=0.3.0.1+    , keiro                          ^>=0.13.0.0+    , keiro-core                     ^>=0.13.0.0+    , kioku-api                      ^>=0.4.0.0+    , kioku-core                     ^>=0.4.0.0+    , kioku-migrations:test-support  ^>=0.4.0.0+    , kiroku-store                   ^>=0.8.0.0     , lens                           >=5.2-    , shibuya-core                   >=0.8.0.1   && <0.9+    , shibuya-core                   ^>=0.9.0.0     , shikumi                        ^>=0.3.0.1     , shikumi-trace                  ^>=0.2.0.1     , tasty                          >=1.5

@@ -0,0 +1,89 @@+-- | Where Kioku's own relations live, spelled once.+--+-- Kioku shares the host application's Kiroku event store but owns its projections, and since+-- migration @0012-relocate-projections-to-kioku-schema.sql@ those projections live in a+-- dedicated @kioku@ PostgreSQL schema rather than beside the event tables in @kiroku@. See+-- @docs\/adr\/projections-live-in-the-kioku-schema.md@.+--+-- Every statement Kioku issues names its relation through one of the constants below instead+-- of relying on @search_path@. That is deliberate. The Kiroku connection puts its own primary+-- schema first and then whatever @extraSearchPath@ entries the host configured, on a pool the+-- host shares — so an unqualified @memories@ would resolve to whichever relation the host's+-- settings happened to reach first. Naming the schema in the SQL makes ownership a property of+-- the query rather than of the connection.+--+-- 'Keiro.Connection.qualifyTable' produces the double-quoted @\"kioku\".\"memories\"@ form, so+-- these values are safe to concatenate into static SQL. They are trusted constants and nothing+-- user-supplied reaches them; every value a caller provides still travels as a parameter.+--+-- This module stays in @other-modules@: the physical layout is Kioku's business, not a public+-- API its consumers should be able to depend on.+module Kioku.Database.Schema+  ( kiokuSchema,+    memoriesTable,+    sessionsTable,+    turnsTable,+    l1WatermarksTable,+    consolidationDecisionsTable,+    scenesTable,+    personasTable,+    memoriesRelation,+    sessionsRelation,+    turnsRelation,+  )+where++import Data.Text (Text)+import Keiro.Connection (qualifyTable)++-- | The PostgreSQL schema every Kioku-owned relation lives in.+--+-- Not to be confused with a Keiro read-model schema identity (a logical name, version, and+-- shape hash) or with a Kioku memory space (a @memory_space_id@ column value). Moving the+-- tables into one schema changes neither; see+-- @docs\/adr\/the-partition-is-a-column-not-a-schema.md@.+kiokuSchema :: Text+kiokuSchema = "kioku"++-- | The unqualified names Keiro's 'Keiro.ReadModel.ReadModel' metadata records, which it keeps+-- separate from the schema. Exported so a read-model declaration and the SQL it runs cannot+-- drift apart: both are built from these.+memoriesRelation, sessionsRelation, turnsRelation :: Text+memoriesRelation = "memories"+sessionsRelation = "sessions"+turnsRelation = "turns"++l1WatermarksRelation, consolidationDecisionsRelation, scenesRelation, personasRelation :: Text+l1WatermarksRelation = "l1_watermarks"+consolidationDecisionsRelation = "consolidation_decisions"+scenesRelation = "scenes"+personasRelation = "personas"++-- | The memory projection: one row per memory, with its full-text vector and its optional+-- embedding.+memoriesTable :: Text+memoriesTable = qualifyTable kiokuSchema memoriesRelation++-- | The session projection, including continuation and awaiting state.+sessionsTable :: Text+sessionsTable = qualifyTable kiokuSchema sessionsRelation++-- | The ordered turns of a session.+turnsTable :: Text+turnsTable = qualifyTable kiokuSchema turnsRelation++-- | L1 distillation's idempotency watermarks.+l1WatermarksTable :: Text+l1WatermarksTable = qualifyTable kiokuSchema l1WatermarksRelation++-- | L2 consolidation's decision audit trail.+consolidationDecisionsTable :: Text+consolidationDecisionsTable = qualifyTable kiokuSchema consolidationDecisionsRelation++-- | L3 scene projections.+scenesTable :: Text+scenesTable = qualifyTable kiokuSchema scenesRelation++-- | L3 persona projections.+personasTable :: Text+personasTable = qualifyTable kiokuSchema personasRelation

@@ -36,8 +36,17 @@ import Hasql.Statement (Statement, preparable) import Hasql.Transaction qualified as Tx import Keiro.ReadModel (ReadModelError)+import Kioku.Api.Access+  ( MemoryAccessContext,+    MemoryPermission (..),+    MemorySpaceId,+    memoryContextAllows,+    memoryContextRecordedActor,+    memoryContextSpace,+  ) import Kioku.Api.Scope (MemoryScope, scopeFromColumns, scopeKindText, scopeNamespaceText, scopeRefText) import Kioku.Api.Types (Confidence (..), MemoryRecord (..), MemoryType (..), confidenceFromText, memoryTypeFromText)+import Kioku.Database.Schema (consolidationDecisionsTable, l1WatermarksTable) import Kioku.Distill.Consolidate   ( ConsolidateInput (..),     ConsolidationAction (..),@@ -50,6 +59,7 @@ import Kioku.Memory qualified as Memory import Kioku.Memory.Domain (RecordMemoryData (..)) import Kioku.Memory.ReadModel (MemoryRow (..))+import Kioku.Partition (memorySpaceParam) import Kioku.Prelude import Kioku.Recall qualified as Recall import Kioku.Recall.Capability (VectorCapability)@@ -61,8 +71,21 @@ import Kiroku.Store.Transaction (runTransaction) import Shikumi.Schema.Types (field, unField) +-- | How a pass finds memories that a newly extracted atom might merge into.+--+-- The authorizing context is an argument rather than something the finder closes over, so a+-- finder value can be built once at startup and still be used by passes running in different+-- memory spaces. It is the whole context rather than a bare 'MemorySpaceId' because+-- 'Kioku.Recall.recall' takes one: a finder that searches must be handed the decision that+-- authorized the pass, so that widening what it searches can never widen whose memories it+-- reaches.+-- The error channel is 'L1Error' rather than 'ReadModelError' because a finder that runs recall+-- can fail in a way a read model cannot — see 'L1RecallRefused'. Flattening such a refusal into+-- an empty candidate list would tell the consolidator there is nothing to merge into, which is+-- the "a denial became an empty result" mistake 'Kioku.Api.Access' exists to prevent. newtype FindMergeCandidates es = FindMergeCandidates-  { runFindMergeCandidates :: MemoryScope -> Text -> Eff es (Either ReadModelError [MemoryRecord])+  { runFindMergeCandidates ::+      MemoryAccessContext -> MemoryScope -> Text -> Eff es (Either L1Error [MemoryRecord])   }  data L1Error@@ -73,6 +96,10 @@   | L1ExtractionFailed !Text   | L1ConsolidationFailed !Text   | L1MemoryWriteFailed !Memory.MemoryWriteError+  | -- | the context does not authorize distillation in this space+    L1NotPermitted !MemoryPermission+  | -- | the merge-candidate finder asked recall for something it would not run+    L1RecallRefused !Recall.RecallError   deriving stock (Generic, Show)  data L1Summary = L1Summary@@ -116,14 +143,16 @@   }  data WatermarkRow = WatermarkRow-  { sessionId :: !Text,+  { memorySpaceId :: !MemorySpaceId,+    sessionId :: !Text,     lastTurnIndex :: !Int32,     distilledAt :: !UTCTime   }   deriving stock (Generic, Eq, Show)  data AuditRow = AuditRow-  { decisionId :: !Text,+  { memorySpaceId :: !MemorySpaceId,+    decisionId :: !Text,     sessionId :: !Text,     namespace :: !Text,     scopeKind :: !(Maybe Text),@@ -142,94 +171,125 @@ -- skipped before any LLM call, which is what makes keiro's at-least-once timer -- re-fires cheap. The watermark advances only when the whole fold succeeds, so -- a failed pass is retried in full.+--+-- The pass writes memories, so it needs a 'MemoryAccessContext' — the one for the memory space+-- the session belongs to. It demands 'MemoryDistill' before anything else, so an unauthorized+-- pass fails before it spends a single LLM token rather than after, at the first write. distillSessionL1 ::   (IOE :> es, KirokuStoreResource :> es, Store :> es, Error StoreError :> es) =>+  MemoryAccessContext ->   L1RunMode ->   DistillRuntime ->   FindMergeCandidates es ->   SessionId ->   Eff es (Either L1Error L1Outcome)-distillSessionL1 mode rt finder sid = do-  sessionResult <- Session.getById sid-  case sessionResult of-    Left err -> pure (Left (L1SessionReadFailed err))-    Right Nothing -> pure (Left (L1SessionNotFound sid))-    Right (Just session) -> do-      turnsResult <- Session.getTurns sid-      case turnsResult of-        Left err -> pure (Left (L1TurnReadFailed err))-        Right turns -> do-          let maxTurnIndex = maximum (0 : fmap (.turnIndex) turns)-          upToDate <- watermarkCovers mode sid maxTurnIndex-          if upToDate-            then pure (Right L1SkippedUpToDate)-            else do-              inputResult <- buildExtractInput sid session turns-              case inputResult of-                Left err -> pure (Left err)-                Right input -> do-                  extractedResult <- liftIO (runExtraction rt input)-                  case extractedResult of-                    Left err -> pure (Left (L1ExtractionFailed (Text.pack (show err))))-                    Right output -> do-                      foldResult <--                        foldM-                          (stepAtom maxTurnIndex session)-                          (Right emptySummary {extracted = length output.atoms})-                          output.atoms-                      case foldResult of-                        Left err -> pure (Left err)-                        Right summary -> do-                          writeWatermark sid maxTurnIndex-                          pure (Right (L1Distilled summary))+distillSessionL1 context mode rt finder sid+  | not (memoryContextAllows MemoryDistill context) =+      pure (Left (L1NotPermitted MemoryDistill))+  | otherwise = do+      sessionResult <- Session.getById space sid+      case sessionResult of+        Left err -> pure (Left (L1SessionReadFailed err))+        Right Nothing -> pure (Left (L1SessionNotFound sid))+        Right (Just session) -> do+          turnsResult <- Session.getTurns space sid+          case turnsResult of+            Left err -> pure (Left (L1TurnReadFailed err))+            Right turns -> do+              let maxTurnIndex = maximum (0 : fmap (.turnIndex) turns)+              upToDate <- watermarkCovers mode space sid maxTurnIndex+              if upToDate+                then pure (Right L1SkippedUpToDate)+                else do+                  inputResult <- buildExtractInput space sid session turns+                  case inputResult of+                    Left err -> pure (Left err)+                    Right input -> do+                      extractedResult <- liftIO (runExtraction rt input)+                      case extractedResult of+                        Left err -> pure (Left (L1ExtractionFailed (Text.pack (show err))))+                        Right output -> do+                          foldResult <-+                            foldM+                              (stepAtom maxTurnIndex session)+                              (Right emptySummary {extracted = length output.atoms})+                              output.atoms+                          case foldResult of+                            Left err -> pure (Left err)+                            Right summary -> do+                              writeWatermark space sid maxTurnIndex+                              pure (Right (L1Distilled summary))   where+    space = memoryContextSpace context+     stepAtom _ _ (Left err) _ = pure (Left err)     stepAtom maxTurnIndex session (Right summary) atom =-      applyAtom rt finder sid session maxTurnIndex summary atom+      applyAtom context rt finder sid session maxTurnIndex summary atom  watermarkCovers ::   (Store :> es) =>   L1RunMode ->+  MemorySpaceId ->   SessionId ->   Int ->   Eff es Bool-watermarkCovers IgnoreWatermark _ _ = pure False-watermarkCovers RespectWatermark sid maxTurnIndex = do-  stored <- readWatermark sid+watermarkCovers IgnoreWatermark _ _ _ = pure False+watermarkCovers RespectWatermark space sid maxTurnIndex = do+  stored <- readWatermark space sid   pure (maybe False (>= maxTurnIndex) stored)  readWatermark ::   (Store :> es) =>+  MemorySpaceId ->   SessionId ->   Eff es (Maybe Int)-readWatermark sid =+readWatermark space sid =   runTransaction $-    fmap fromIntegral <$> Tx.statement (idText sid) selectWatermarkStmt+    fmap fromIntegral <$> Tx.statement (WatermarkKey space (idText sid)) selectWatermarkStmt  writeWatermark ::   (IOE :> es, Store :> es) =>+  MemorySpaceId ->   SessionId ->   Int ->   Eff es ()-writeWatermark sid maxTurnIndex = do+writeWatermark space sid maxTurnIndex = do   now <- liftIO getCurrentTime   runTransaction $     Tx.statement       WatermarkRow-        { sessionId = idText sid,+        { memorySpaceId = space,+          sessionId = idText sid,           lastTurnIndex = fromIntegral maxTurnIndex,           distilledAt = now         }       upsertWatermarkStmt +data WatermarkKey = WatermarkKey !MemorySpaceId !Text+ scopedScanCandidates ::   (IOE :> es, Store :> es) =>   Int ->   FindMergeCandidates es scopedScanCandidates limit =-  FindMergeCandidates \scope _query ->-    fmap (take (max 0 limit)) <$> Recall.getActiveByScope scope+  FindMergeCandidates \context scope _query ->+    bimap L1MemoryReadFailed (take (max 0 limit))+      <$> Recall.getActiveByScope (memoryContextSpace context) scope +-- | Merge candidates from ranked hybrid recall over the atom's own text.+--+-- The target is @'Recall.ExactScope' scope@, the same population 'scopedScanCandidates' draws+-- from. The two finders differ in how they /rank/ and bound that population — one by hybrid+-- relevance to the atom, the other by a priority-ordered scan — and a finder that also changed+-- which memories exist would not be a substitutable alternative to the other.+--+-- It was not always so. Until recall targets were explicit this line read+-- @'Recall.legacyRecallTarget' scope@, which maps a global scope to /namespace-wide/, so a+-- session scoped @mori@ drew candidates from @mori:repo:web@ as well — and could merge an atom+-- into that memory, rewriting content that feeds a scene the session has nothing to do with.+-- Nobody chose that; it is what @ScopeGlobal@ meaning two things looked like from inside one+-- module. See @docs\/plans\/30-migrate-recall-consumers-to-explicit-targets.md@ for the decision+-- and what it costs: a globally-scoped session now stores where it used to merge across scopes. recallCandidates ::   (IOE :> es, Store :> es) =>   EmbeddingModel ->@@ -237,29 +297,37 @@   Int ->   FindMergeCandidates es recallCandidates model capability limit =-  FindMergeCandidates \scope query -> do-    hits <--      Recall.recall-        model-        capability-        Recall.RecallRequest-          { scope,-            query,-            strategy = Recall.Hybrid,-            maxResults = max 0 limit-          }-    pure (Right (fmap (.memory) hits))+  FindMergeCandidates \context scope query ->+    -- A limit of zero or less asks for no candidates, which is what the pre-'RecallLimit'+    -- @take (max 0 limit)@ produced. Anything above the bound is clamped rather than refused:+    -- a fused result set holds at most 100 memories, so it was never reachable anyway.+    case Recall.mkRecallLimit (min Recall.maxRecallLimit limit) of+      Left _ -> pure (Right [])+      Right maxResults -> do+        hits <-+          Recall.recall+            model+            capability+            context+            Recall.RecallQuery+              { target = Recall.ExactScope scope,+                query,+                strategy = Recall.Hybrid,+                maxResults+              }+        pure (bimap L1RecallRefused (fmap (.memory)) hits)  buildExtractInput ::   (IOE :> es, Store :> es) =>+  MemorySpaceId ->   SessionId ->   SessionRow ->   [TurnRow] ->   Eff es (Either L1Error ExtractInput)-buildExtractInput sid session turns = do+buildExtractInput space sid session turns = do   memoryTextResult <-     if null turns-      then fallbackMemoryText sid (sessionScope session)+      then fallbackMemoryText space sid (sessionScope session)       else pure (Right (renderTurns turns))   pure do     memoryText <- memoryTextResult@@ -272,17 +340,18 @@  fallbackMemoryText ::   (IOE :> es, Store :> es) =>+  MemorySpaceId ->   SessionId ->   MemoryScope ->   Eff es (Either L1Error Text)-fallbackMemoryText sid scope = do-  bySession <- Recall.getBySession sid+fallbackMemoryText space sid scope = do+  bySession <- Recall.getBySession space sid   case bySession of     Left err -> pure (Left (L1MemoryReadFailed err))     Right rows       | not (null rows) -> pure (Right (renderMemories rows))       | otherwise -> do-          byScope <- Recall.getActiveByScope scope+          byScope <- Recall.getActiveByScope space scope           pure $             case byScope of               Left err -> Left (L1MemoryReadFailed err)@@ -290,6 +359,7 @@  applyAtom ::   (IOE :> es, KirokuStoreResource :> es, Store :> es, Error StoreError :> es) =>+  MemoryAccessContext ->   DistillRuntime ->   FindMergeCandidates es ->   SessionId ->@@ -298,10 +368,14 @@   L1Summary ->   ExtractedAtom ->   Eff es (Either L1Error L1Summary)-applyAtom rt finder sid session maxTurnIndex summary atom = do-  candidatesResult <- finder.runFindMergeCandidates (sessionScope session) (unField atom.content)+applyAtom context rt finder sid session maxTurnIndex summary atom = do+  candidatesResult <-+    finder.runFindMergeCandidates+      context+      (sessionScope session)+      (unField atom.content)   case candidatesResult of-    Left err -> pure (Left (L1MemoryReadFailed err))+    Left err -> pure (Left err)     Right candidates -> do       decisionResult <-         liftIO $@@ -315,11 +389,11 @@       case decisionResult of         Left err -> pure (Left (L1ConsolidationFailed (Text.pack (show err))))         Right decision -> do-          appliedResult <- applyDecision sid session atom decision+          appliedResult <- applyDecision context sid session atom decision           case appliedResult of             Left err -> pure (Left err)             Right applied -> do-              writeAudit sid session atom maxTurnIndex decision applied+              writeAudit (memoryContextSpace context) sid session atom maxTurnIndex decision applied               pure (Right (addAppliedDecision summary applied))  -- | Apply a consolidation decision, writing nothing until the whole plan for@@ -328,12 +402,13 @@ -- keiro's at-least-once timer contract. applyDecision ::   (IOE :> es, KirokuStoreResource :> es, Store :> es, Error StoreError :> es) =>+  MemoryAccessContext ->   SessionId ->   SessionRow ->   ExtractedAtom ->   ConsolidationDecision ->   Eff es (Either L1Error AppliedDecision)-applyDecision sid session atom decision =+applyDecision context sid session atom decision =   case decision.action of     SkipAtom -> pure (Right (appliedSkip Nothing))     StoreAtom -> storeWinner Nothing Nothing@@ -360,7 +435,7 @@                 appliedNote = note               }         )-        <$> recordAtom sid session atom decision winner supersedes+        <$> recordAtom context sid session atom decision winner supersedes      mergeInto action = do       let requested = nub (parsedTargetIds decision)@@ -371,23 +446,26 @@       if not (null requested) && null nonSelf         then pure (Right (appliedSkip (Just selfTargetNote)))         else do-          winnerRow <- Memory.getMemoryRowById winner+          winnerRow <- Memory.getMemoryRowById (memoryContextSpace context) winner           case winnerRow of             Left err -> pure (Left (L1MemoryReadFailed err))             Right (Just row)               | row.status /= "active" ->                   pure (Right (appliedSkip (Just (retiredWinnerNote row.status))))             _ -> do-              resolved <- resolveExistingTargets nonSelf+              resolved <- resolveExistingTargets (memoryContextSpace context) nonSelf               case resolved of                 Left err -> pure (Left err)                 Right [] -> storeWinner (Just degradeNote) Nothing                 Right targets@(firstTarget : _) -> do-                  winnerResult <- recordAtom sid session atom decision winner (Just firstTarget)+                  winnerResult <- recordAtom context sid session atom decision winner (Just firstTarget)                   case winnerResult of                     Left err -> pure (Left err)                     Right stored -> do-                      mergeResults <- traverse (\target -> requireMemoryWrite =<< Memory.merge target stored) targets+                      mergeResults <-+                        traverse+                          (\target -> requireMemoryWrite =<< Memory.mergeWithContext context target stored)+                          targets                       pure $                         case lefts mergeResults of                           err : _ -> Left err@@ -406,14 +484,15 @@ -- wedging the timer and leaking one memory per retry. resolveExistingTargets ::   (IOE :> es, Store :> es) =>+  MemorySpaceId ->   [MemoryId] ->   Eff es (Either L1Error [MemoryId])-resolveExistingTargets =+resolveExistingTargets space =   foldM step (Right [])   where     step (Left err) _ = pure (Left err)     step (Right acc) mid = do-      row <- Memory.getMemoryRowById mid+      row <- Memory.getMemoryRowById space mid       pure $         case row of           Left err -> Left (L1MemoryReadFailed err)@@ -428,8 +507,13 @@ retiredWinnerNote status =   "this atom was already distilled and is now " <> status <> "; already represented" +-- | The distilled memory belongs to the space the pass was authorized for, and is attributed to+-- that context's principal — the thing that ran the distillation, not the agent whose session+-- produced the evidence. @agentId@ still carries that agent, unchanged, as the organizing label+-- it always was. recordAtom ::   (IOE :> es, KirokuStoreResource :> es, Store :> es, Error StoreError :> es) =>+  MemoryAccessContext ->   SessionId ->   SessionRow ->   ExtractedAtom ->@@ -437,12 +521,16 @@   MemoryId ->   Maybe MemoryId ->   Eff es (Either L1Error MemoryId)-recordAtom sid session atom decision memoryId supersedes = do+recordAtom context sid session atom decision memoryId supersedes = do   now <- liftIO getCurrentTime   requireMemoryWrite-    =<< Memory.record+    =<< Memory.recordWithContext+      context       RecordMemoryData         { memoryId,+          memorySpaceId = memoryContextSpace context,+          actorPrincipal = memoryContextRecordedActor context,+          ownerPrincipal = Nothing,           agentId = session.agentId,           sessionId = Just sid,           scope = sessionScope session,@@ -466,6 +554,7 @@ -- over new turns still writes its own. writeAudit ::   (IOE :> es, Store :> es) =>+  MemorySpaceId ->   SessionId ->   SessionRow ->   ExtractedAtom ->@@ -473,12 +562,13 @@   ConsolidationDecision ->   AppliedDecision ->   Eff es ()-writeAudit sid session atom maxTurnIndex decision applied = do+writeAudit space sid session atom maxTurnIndex decision applied = do   now <- liftIO getCurrentTime   runTransaction $     Tx.statement       AuditRow-        { decisionId = l1AuditKey sid maxTurnIndex (unField atom.content),+        { memorySpaceId = space,+          decisionId = l1AuditKey sid maxTurnIndex (unField atom.content),           sessionId = idText sid,           namespace = scopeNamespaceText (sessionScope session),           scopeKind = scopeKindText (sessionScope session),@@ -604,15 +694,24 @@ encodeTargetIds =   TE.decodeUtf8 . BL.toStrict . Aeson.encode -selectWatermarkStmt :: Statement Text (Maybe Int32)+selectWatermarkStmt :: Statement WatermarkKey (Maybe Int32) selectWatermarkStmt =   preparable-    """-    SELECT last_turn_index-    FROM kioku_l1_watermarks-    WHERE session_id = $1-    """-    (E.param (E.nonNullable E.text))+    ( """+      SELECT last_turn_index+      FROM+      """+        <> " "+        <> l1WatermarksTable+        <> " "+        <> """+           WHERE memory_space_id = $1+             AND session_id = $2+           """+    )+    ( ((\(WatermarkKey space _) -> space) >$< memorySpaceParam)+        <> ((\(WatermarkKey _ sessionId) -> sessionId) >$< E.param (E.nonNullable E.text))+    )     (D.rowMaybe (D.column (D.nonNullable D.int4)))  -- | @GREATEST@ keeps the watermark monotonic: a slow pass over turns 1-3 that@@ -620,39 +719,48 @@ upsertWatermarkStmt :: Statement WatermarkRow () upsertWatermarkStmt =   preparable-    """-    INSERT INTO kioku_l1_watermarks (session_id, last_turn_index, distilled_at)-    VALUES ($1, $2, $3)-    ON CONFLICT (session_id) DO UPDATE-      SET last_turn_index =-            GREATEST(kioku_l1_watermarks.last_turn_index, EXCLUDED.last_turn_index),-          distilled_at = EXCLUDED.distilled_at-    """+    ( "INSERT INTO "+        <> l1WatermarksTable+        <> " AS watermark\n"+        <> """+             (memory_space_id, session_id, last_turn_index, distilled_at)+           VALUES ($1, $2, $3, $4)+           ON CONFLICT (session_id) DO UPDATE+             SET last_turn_index =+                   GREATEST(watermark.last_turn_index, EXCLUDED.last_turn_index),+                 distilled_at = EXCLUDED.distilled_at+           """+    )     watermarkRowEncoder     D.noResult  watermarkRowEncoder :: E.Params WatermarkRow watermarkRowEncoder =-  ((\row -> row.sessionId) >$< E.param (E.nonNullable E.text))+  ((\row -> row.memorySpaceId) >$< memorySpaceParam)+    <> ((\row -> row.sessionId) >$< E.param (E.nonNullable E.text))     <> ((\row -> row.lastTurnIndex) >$< E.param (E.nonNullable E.int4))     <> ((\row -> row.distilledAt) >$< E.param (E.nonNullable E.timestamptz))  insertAuditStmt :: Statement AuditRow () insertAuditStmt =   preparable-    """-    INSERT INTO kioku_consolidation_decisions-      (decision_id, session_id, namespace, scope_kind, scope_ref, candidate_content,-       decision, target_ids, result_memory_id, rationale, decided_at)-    VALUES ($1, $2, $3, $4, $5, $6, $7, $8::jsonb, $9, $10, $11)-    ON CONFLICT (decision_id) DO NOTHING-    """+    ( "INSERT INTO "+        <> consolidationDecisionsTable+        <> "\n"+        <> """+             (memory_space_id, decision_id, session_id, namespace, scope_kind, scope_ref,+              candidate_content, decision, target_ids, result_memory_id, rationale, decided_at)+           VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9::jsonb, $10, $11, $12)+           ON CONFLICT (decision_id) DO NOTHING+           """+    )     auditRowEncoder     D.noResult  auditRowEncoder :: E.Params AuditRow auditRowEncoder =-  ((\row -> row.decisionId) >$< E.param (E.nonNullable E.text))+  ((\row -> row.memorySpaceId) >$< memorySpaceParam)+    <> ((\row -> row.decisionId) >$< E.param (E.nonNullable E.text))     <> ((\row -> row.sessionId) >$< E.param (E.nonNullable E.text))     <> ((\row -> row.namespace) >$< E.param (E.nonNullable E.text))     <> ((\row -> row.scopeKind) >$< E.param (E.nullable E.text))

@@ -8,6 +8,7 @@     l2SceneProcessManagerName,     l2SceneTimerId,     l2SceneTimerScheduleProjection,+    SceneTimerPayload (..),     mirrorSceneToCurrentWorkspace,     mirrorSceneToWorkspace,     regenerateScene,@@ -16,16 +17,16 @@   ) where -import Contravariant.Extras (contrazip3, contrazip4) import Control.Exception (IOException, try) import Crypto.Hash (Digest, SHA256) import Crypto.Hash qualified as Hash import Data.Aeson qualified as Aeson+import Data.Aeson.Types (withObject, (.:)) import Data.ByteString qualified as BS import Data.ByteString.Lazy qualified as BL-import Data.Foldable (for_)+import Data.Foldable (for_, traverse_) import Data.Functor.Contravariant ((>$<))-import Data.Maybe (catMaybes)+import Data.Maybe (catMaybes, maybeToList) import Data.Text qualified as Text import Data.Text.Encoding qualified as TE import Data.Text.IO qualified as TextIO@@ -41,9 +42,11 @@ import Keiro.Projection (InlineProjection (..)) import Keiro.ReadModel (ReadModelError) import Keiro.Timer (TimerId (..), TimerRequest (..), TimerRow (..), scheduleTimerTx)+import Kioku.Api.Access (MemoryContextProvider (..), MemorySpaceId, legacyMemorySpaceId, memoryContextSpace) import Kioku.Api.Scope (MemoryScope, scopeFromColumns, scopeKindText, scopeNamespaceText, scopeRefText) import Kioku.Api.Types (MemoryRecord (..))-import Kioku.Distill.L3 (scheduleL3PersonaTimerTx)+import Kioku.Database.Schema (memoriesTable, scenesTable)+import Kioku.Distill.L3 (partitionedCorrelationId, scheduleL3PersonaTimerTx) import Kioku.Distill.Runtime (DistillRuntime, distillWorkspaceRoot, runSceneDistillation) import Kioku.Distill.Scene (SceneInput (..), SceneOutput (..)) import Kioku.Distill.ScopeIdentity (escapeScopeComponent, scopeIdentity, scopeSlugFromColumns)@@ -57,8 +60,10 @@     MemoryRecordedData (..),     MemorySupersededData (..),   )+import Kioku.Partition (memorySpaceColumn, memorySpaceParam, parsePartitionSpace) import Kioku.Prelude import Kioku.Recall qualified as Recall+import Kioku.Workspace (legacySceneArtifactDir, sceneArtifactDir) import Kiroku.Store.Effect (Store) import Kiroku.Store.Transaction (runTransaction) import Kiroku.Store.Types (EventId (..), RecordedEvent (..))@@ -73,7 +78,8 @@   deriving stock (Generic, Show)  data SceneRow = SceneRow-  { sceneId :: !Text,+  { memorySpaceId :: !MemorySpaceId,+    sceneId :: !Text,     namespace :: !Text,     scopeKind :: !(Maybe Text),     scopeRef :: !(Maybe Text),@@ -87,12 +93,23 @@   }   deriving stock (Generic, Eq, Show) -newtype SceneTimerPayload = SceneTimerPayload-  { scope :: MemoryScope+-- | What a scheduled scene regeneration needs to know.+--+-- @memorySpaceId@ is what keeps two spaces that happen to share a namespace and scope from+-- regenerating each other's scene. Timers scheduled before the field existed decode into+-- 'Kioku.Api.Access.legacyMemorySpaceId', the same rule stored events follow.+data SceneTimerPayload = SceneTimerPayload+  { memorySpaceId :: !MemorySpaceId,+    scope :: !MemoryScope   }   deriving stock (Generic, Eq, Show)-  deriving anyclass (FromJSON, ToJSON)+  deriving anyclass (ToJSON) +instance FromJSON SceneTimerPayload where+  parseJSON =+    withObject "SceneTimerPayload" \o ->+      SceneTimerPayload <$> parsePartitionSpace o <*> o .: "scope"+ l2SceneProcessManagerName :: Text l2SceneProcessManagerName = "kioku-l2-scene" @@ -119,15 +136,16 @@   MemoryRecorded d ->     scheduleTimerTx $       l2SceneTimerRequest+        d.memorySpaceId         d.scope         (idText (d.memoryId :: MemoryId))         (addUTCTime sceneDebounceSeconds d.recordedAt)   MemoryArchived d ->-    scheduleScopedSceneTimerTx d.memoryId (kindSourceId d.memoryId "archived") d.archivedAt+    scheduleScopedSceneTimerTx d.memorySpaceId d.memoryId (kindSourceId d.memoryId "archived") d.archivedAt   MemorySuperseded d ->-    scheduleScopedSceneTimerTx d.memoryId (kindSourceId d.memoryId "superseded") d.supersededAt+    scheduleScopedSceneTimerTx d.memorySpaceId d.memoryId (kindSourceId d.memoryId "superseded") d.supersededAt   MemoryMerged d ->-    scheduleScopedSceneTimerTx d.memoryId (kindSourceId d.memoryId "merged") d.mergedAt+    scheduleScopedSceneTimerTx d.memorySpaceId d.memoryId (kindSourceId d.memoryId "merged") d.mergedAt   -- Confidence is in the scene's source hash ('atomSource') and in the LLM prompt   -- ('renderAtom'), so changing it makes the scene stale exactly as forgetting does.   --@@ -139,6 +157,7 @@   -- event id is stable across replay, so it cannot double-schedule either.   MemoryConfidenceUpdated d ->     scheduleScopedSceneTimerTx+      d.memorySpaceId       d.memoryId       (idText d.memoryId <> ":confidence:" <> eventIdText recorded.eventId)       d.updatedAt@@ -157,12 +176,13 @@ -- memory id, because keiro's 'scheduleTimerTx' re-arms a conflicting timer only -- while it is still @scheduled@ — reusing the record-time id would be silently -- dropped once that timer has fired, which by then it almost always has.-scheduleScopedSceneTimerTx :: MemoryId -> Text -> UTCTime -> Tx.Transaction ()-scheduleScopedSceneTimerTx memoryId sourceId occurredAt = do-  scopeCols <- Tx.statement (idText memoryId) selectMemoryScopeColumnsStmt+scheduleScopedSceneTimerTx :: MemorySpaceId -> MemoryId -> Text -> UTCTime -> Tx.Transaction ()+scheduleScopedSceneTimerTx memorySpaceId memoryId sourceId occurredAt = do+  scopeCols <- Tx.statement (MemoryScopeLookup memorySpaceId (idText memoryId)) selectMemoryScopeColumnsStmt   for_ scopeCols \(ns, sk, sr) ->     scheduleTimerTx $       l2SceneTimerRequest+        memorySpaceId         (scopeFromColumns ns sk sr)         sourceId         (addUTCTime sceneDebounceSeconds occurredAt)@@ -175,18 +195,21 @@ eventIdText :: EventId -> Text eventIdText (EventId uuid) = UUID.toText uuid -l2SceneTimerRequest :: MemoryScope -> Text -> UTCTime -> TimerRequest-l2SceneTimerRequest scope sourceId fireAt =+l2SceneTimerRequest :: MemorySpaceId -> MemoryScope -> Text -> UTCTime -> TimerRequest+l2SceneTimerRequest memorySpaceId scope sourceId fireAt =   TimerRequest-    { timerId = l2SceneTimerId scope sourceId,+    { timerId = l2SceneTimerId memorySpaceId scope sourceId,       processManagerName = l2SceneProcessManagerName,-      correlationId = scopeIdentity scope,+      correlationId = partitionedCorrelationId memorySpaceId scope,       fireAt,-      payload = Aeson.toJSON (SceneTimerPayload scope)+      payload = Aeson.toJSON SceneTimerPayload {memorySpaceId, scope}     } -l2SceneTimerId :: MemoryScope -> Text -> TimerId-l2SceneTimerId scope sourceId =+-- | The timer id and correlation id both carry the memory space, for the reason given at+-- 'Kioku.Distill.L3.l3PersonaTimerId': these timers are keyed by a scope, and two spaces are+-- allowed to use the same one.+l2SceneTimerId :: MemorySpaceId -> MemoryScope -> Text -> TimerId+l2SceneTimerId memorySpaceId scope sourceId =   TimerId $     UUIDv5.generateNamed       l2SceneTimerNamespace@@ -195,17 +218,18 @@     raw =       l2SceneProcessManagerName         <> ":"-        <> scopeIdentity scope+        <> partitionedCorrelationId memorySpaceId scope         <> ":"         <> sourceId  regenerateScene ::   (IOE :> es, Store :> es) =>   DistillRuntime ->+  MemorySpaceId ->   MemoryScope ->   Eff es (Either L2Error (Maybe SceneRow))-regenerateScene rt scope = do-  memoryResult <- Recall.getActiveByScope scope+regenerateScene rt memorySpaceId scope = do+  memoryResult <- Recall.getActiveByScope memorySpaceId scope   case memoryResult of     Left err -> pure (Left (L2MemoryReadFailed err))     -- Every memory in this scope has been forgotten. Delete the scene outright@@ -214,21 +238,21 @@     -- memories, and a blank mirror file is just a confusing way to still be     -- there. No LLM runs on this path -- there is nothing left to summarize.     Right [] -> do-      existing <- lookupScene scope defaultSceneKey+      existing <- lookupScene memorySpaceId scope defaultSceneKey       case existing of         Left err -> pure (Left err)         Right Nothing -> pure (Right Nothing)         Right (Just row) -> do           now <- liftIO getCurrentTime           runTransaction do-            Tx.statement row.sceneId deleteSceneStmt-            scheduleL3PersonaTimerTx scope now+            Tx.statement (SceneKey memorySpaceId row.sceneId) deleteSceneStmt+            scheduleL3PersonaTimerTx memorySpaceId scope now           liftIO (bestEffortRemoveSceneMirror rt row)           pure (Right Nothing)     Right atoms -> do       let sourceHash = sceneSourceHash atoms           sceneId = sceneRowId scope-      existing <- lookupScene scope defaultSceneKey+      existing <- lookupScene memorySpaceId scope defaultSceneKey       case existing of         Left err -> pure (Left err)         Right (Just row)@@ -250,7 +274,8 @@               now <- liftIO getCurrentTime               let row =                     SceneRow-                      { sceneId,+                      { memorySpaceId,+                        sceneId,                         namespace = scopeNamespaceText scope,                         scopeKind = scopeKindText scope,                         scopeRef = scopeRefText scope,@@ -264,16 +289,22 @@                       }               runTransaction do                 Tx.statement row upsertSceneStmt-                scheduleL3PersonaTimerTx scope now+                scheduleL3PersonaTimerTx memorySpaceId scope now               liftIO (bestEffortMirrorScene rt row)               pure (Right (Just row)) +-- | Fire one L2 scene timer.+--+-- Like the L1 handler, a background pass cannot arrive holding an authorization context: it+-- reads the memory space out of the payload and asks the provider for a decision about /that/+-- space. A refusal is a configuration fact, so it dead-letters rather than retrying forever. fireL2SceneTimer ::   (IOE :> es, Store :> es) =>+  MemoryContextProvider (Eff es) ->   DistillRuntime ->   TimerRow ->   Eff es FireOutcome-fireL2SceneTimer rt row+fireL2SceneTimer contexts rt row   | row.processManagerName /= l2SceneProcessManagerName =       pure FireNotMine   | otherwise =@@ -283,35 +314,72 @@         Aeson.Error err ->           pure (FireFailedPermanently ("L2 scene timer payload is malformed: " <> Text.pack err))         Aeson.Success payload -> do-          result <- regenerateScene rt payload.scope-          pure $-            case result of-              Right _ -> FireCompleted (timerMarkerEventId row.timerId)-              Left err -> FireRetryLater (fireRetryDelay row.attempts) (Text.pack (show err))+          decision <- contexts.contextForSpace payload.memorySpaceId+          case decision of+            Left denial ->+              pure+                ( FireFailedPermanently+                    ("L2 scene timer is not authorized for its memory space: " <> Text.pack (show denial))+                )+            Right context -> do+              result <- regenerateScene rt (memoryContextSpace context) payload.scope+              pure $+                case result of+                  Right _ -> FireCompleted (timerMarkerEventId row.timerId)+                  Left err -> FireRetryLater (fireRetryDelay row.attempts) (Text.pack (show err))  lookupScene ::   (Store :> es) =>+  MemorySpaceId ->   MemoryScope ->   Text ->   Eff es (Either L2Error (Maybe SceneRow))-lookupScene scope sceneKey = do+lookupScene memorySpaceId scope sceneKey = do   result <-     runTransaction $-      Tx.statement-        (scopeNamespaceText scope, scopeKindText scope, scopeRefText scope, sceneKey)-        selectSceneByScopeKeyStmt+      Tx.statement (SceneScopeKey (scopeKey memorySpaceId scope) sceneKey) selectSceneByScopeKeyStmt   pure (Right result)  getScenesByScope ::   (Store :> es) =>+  MemorySpaceId ->   MemoryScope ->   Eff es [SceneRow]-getScenesByScope scope =+getScenesByScope memorySpaceId scope =   runTransaction $-    Tx.statement-      (scopeNamespaceText scope, scopeKindText scope, scopeRefText scope)-      selectScenesByScopeStmt+    Tx.statement (scopeKey memorySpaceId scope) selectScenesByScopeStmt +-- | A scope lookup inside one memory space, as a record rather than a tuple so that the+-- partition cannot be transposed with the namespace it sits beside.+data PartitionedScope = PartitionedScope+  { memorySpaceId :: !MemorySpaceId,+    namespace :: !Text,+    scopeKind :: !(Maybe Text),+    scopeRef :: !(Maybe Text)+  }++data SceneScopeKey = SceneScopeKey !PartitionedScope !Text++data SceneKey = SceneKey !MemorySpaceId !Text++data MemoryScopeLookup = MemoryScopeLookup !MemorySpaceId !Text++scopeKey :: MemorySpaceId -> MemoryScope -> PartitionedScope+scopeKey memorySpaceId scope =+  PartitionedScope+    { memorySpaceId,+      namespace = scopeNamespaceText scope,+      scopeKind = scopeKindText scope,+      scopeRef = scopeRefText scope+    }++partitionedScopeEncoder :: E.Params PartitionedScope+partitionedScopeEncoder =+  ((\q -> q.memorySpaceId) >$< memorySpaceParam)+    <> ((\q -> q.namespace) >$< E.param (E.nonNullable E.text))+    <> ((\q -> q.scopeKind) >$< E.param (E.nullable E.text))+    <> ((\q -> q.scopeRef) >$< E.param (E.nullable E.text))+ mirrorSceneToCurrentWorkspace :: SceneRow -> IO FilePath mirrorSceneToCurrentWorkspace row = do   workspace <- getCurrentDirectory@@ -320,14 +388,30 @@ mirrorSceneToWorkspace :: FilePath -> SceneRow -> IO FilePath mirrorSceneToWorkspace workspace row = do   let path = sceneMirrorPath workspace row-  createDirectoryIfMissing True (workspace </> ".kioku" </> "scenes")+  createDirectoryIfMissing True (sceneArtifactDir workspace row.memorySpaceId)   TextIO.writeFile path (renderSceneFile row)   pure path +-- | The mirror path is derived from the row's own memory space as well as its scope.+--+-- The filename alone cannot separate two spaces: the slug comes from the namespace, kind, and+-- ref, and two spaces are allowed to hold all three. The space is the directory. See+-- "Kioku.Workspace" for why that directory is not simply the space id. sceneMirrorPath :: FilePath -> SceneRow -> FilePath sceneMirrorPath workspace row =-  workspace </> ".kioku" </> "scenes" </> Text.unpack (sceneScopeSlug row <> ".md")+  sceneArtifactDir workspace row.memorySpaceId </> Text.unpack (sceneScopeSlug row <> ".md") +-- | Where this scene's mirror lived before memory spaces existed.+--+-- Only meaningful for the legacy space, which is the only space that can have one: the+-- historical tree predates the partition, so every file in it was written by the deployment that+-- became @kioku_legacy@.+legacySceneMirrorPath :: FilePath -> SceneRow -> Maybe FilePath+legacySceneMirrorPath workspace row+  | row.memorySpaceId == legacyMemorySpaceId =+      Just (legacySceneArtifactDir workspace </> Text.unpack (sceneScopeSlug row <> ".md"))+  | otherwise = Nothing+ bestEffortMirrorScene :: DistillRuntime -> SceneRow -> IO () bestEffortMirrorScene rt row = do   let write = do@@ -340,16 +424,24 @@ -- The durable artifact is the database row, and it is already gone by the time -- this runs; a failure to unlink the file must not fail the timer, and the next -- regeneration in this workspace rewrites or removes it anyway.+--+-- The legacy space's pre-partition mirror goes too, and it is the one place anything still+-- touches the historical tree. Every memory in this scope has been forgotten, so a surviving+-- @.kioku\/scenes\/…@ file is not merely stale — it is forgotten content that a host agent would+-- keep reading until somebody ran the artifact migration. bestEffortRemoveSceneMirror :: DistillRuntime -> SceneRow -> IO () bestEffortRemoveSceneMirror rt row = do   let remove = do         workspace <- distillWorkspaceRoot rt-        let path = sceneMirrorPath workspace row-        exists <- doesFileExist path-        when exists (removeFile path)+        traverse_ removeIfPresent (sceneMirrorPath workspace row : maybeToList (legacySceneMirrorPath workspace row))   _ <- try remove :: IO (Either IOException ())   pure () +removeIfPresent :: FilePath -> IO ()+removeIfPresent path = do+  exists <- doesFileExist path+  when exists (removeFile path)+ renderSceneFile :: SceneRow -> Text renderSceneFile row =   "# " <> row.title <> "\n\n" <> row.bodyMd <> "\n"@@ -412,8 +504,9 @@ sceneRowDecoder :: D.Row SceneRow sceneRowDecoder =   SceneRow-    <$> D.column (D.nonNullable D.text)+    <$> memorySpaceColumn     <*> D.column (D.nonNullable D.text)+    <*> D.column (D.nonNullable D.text)     <*> D.column (D.nullable D.text)     <*> D.column (D.nullable D.text)     <*> D.column (D.nonNullable D.text)@@ -426,7 +519,8 @@  sceneRowEncoder :: E.Params SceneRow sceneRowEncoder =-  ((\row -> row.sceneId) >$< E.param (E.nonNullable E.text))+  ((\row -> row.memorySpaceId) >$< memorySpaceParam)+    <> ((\row -> row.sceneId) >$< E.param (E.nonNullable E.text))     <> ((\row -> row.namespace) >$< E.param (E.nonNullable E.text))     <> ((\row -> row.scopeKind) >$< E.param (E.nullable E.text))     <> ((\row -> row.scopeRef) >$< E.param (E.nullable E.text))@@ -438,11 +532,13 @@     <> ((\row -> row.createdAt) >$< E.param (E.nonNullable E.timestamptz))     <> ((\row -> row.updatedAt) >$< E.param (E.nonNullable E.timestamptz)) -selectMemoryScopeColumnsStmt :: Statement Text (Maybe (Text, Maybe Text, Maybe Text))+selectMemoryScopeColumnsStmt :: Statement MemoryScopeLookup (Maybe (Text, Maybe Text, Maybe Text)) selectMemoryScopeColumnsStmt =   preparable-    "SELECT namespace, scope_kind, scope_ref FROM kioku_memories WHERE memory_id = $1"-    (E.param (E.nonNullable E.text))+    ("SELECT namespace, scope_kind, scope_ref FROM " <> memoriesTable <> " WHERE memory_space_id = $1 AND memory_id = $2")+    ( ((\(MemoryScopeLookup space _) -> space) >$< memorySpaceParam)+        <> ((\(MemoryScopeLookup _ memoryId) -> memoryId) >$< E.param (E.nonNullable E.text))+    )     ( D.rowMaybe         ( (,,)             <$> D.column (D.nonNullable D.text)@@ -451,69 +547,82 @@         )     ) -selectSceneByScopeKeyStmt :: Statement (Text, Maybe Text, Maybe Text, Text) (Maybe SceneRow)+selectSceneByScopeKeyStmt :: Statement SceneScopeKey (Maybe SceneRow) selectSceneByScopeKeyStmt =   preparable-    """-    SELECT scene_id, namespace, scope_kind, scope_ref, scene_key, title, body_md,-           atom_ids::text, source_hash, created_at, updated_at-    FROM kioku_scenes-    WHERE namespace = $1-      AND ((scope_kind = $2 AND scope_ref = $3)-           OR ($2 IS NULL AND scope_kind IS NULL AND $3 IS NULL AND scope_ref IS NULL))-      AND scene_key = $4-    """-    ( contrazip4-        (E.param (E.nonNullable E.text))-        (E.param (E.nullable E.text))-        (E.param (E.nullable E.text))-        (E.param (E.nonNullable E.text))+    ( """+      SELECT memory_space_id, scene_id, namespace, scope_kind, scope_ref, scene_key, title, body_md,+             atom_ids::text, source_hash, created_at, updated_at+      FROM+      """+        <> " "+        <> scenesTable+        <> " "+        <> """+           WHERE memory_space_id = $1+             AND namespace = $2+             AND ((scope_kind = $3 AND scope_ref = $4)+                  OR ($3 IS NULL AND scope_kind IS NULL AND $4 IS NULL AND scope_ref IS NULL))+             AND scene_key = $5+           """     )+    ( ((\(SceneScopeKey scope _) -> scope) >$< partitionedScopeEncoder)+        <> ((\(SceneScopeKey _ sceneKey) -> sceneKey) >$< E.param (E.nonNullable E.text))+    )     (D.rowMaybe sceneRowDecoder) -selectScenesByScopeStmt :: Statement (Text, Maybe Text, Maybe Text) [SceneRow]+selectScenesByScopeStmt :: Statement PartitionedScope [SceneRow] selectScenesByScopeStmt =   preparable-    """-    SELECT scene_id, namespace, scope_kind, scope_ref, scene_key, title, body_md,-           atom_ids::text, source_hash, created_at, updated_at-    FROM kioku_scenes-    WHERE namespace = $1-      AND ((scope_kind = $2 AND scope_ref = $3)-           OR ($2 IS NULL AND scope_kind IS NULL AND $3 IS NULL AND scope_ref IS NULL))-    ORDER BY scene_key ASC, updated_at DESC-    """-    ( contrazip3-        (E.param (E.nonNullable E.text))-        (E.param (E.nullable E.text))-        (E.param (E.nullable E.text))+    ( """+      SELECT memory_space_id, scene_id, namespace, scope_kind, scope_ref, scene_key, title, body_md,+             atom_ids::text, source_hash, created_at, updated_at+      FROM+      """+        <> " "+        <> scenesTable+        <> " "+        <> """+           WHERE memory_space_id = $1+             AND namespace = $2+             AND ((scope_kind = $3 AND scope_ref = $4)+                  OR ($3 IS NULL AND scope_kind IS NULL AND $4 IS NULL AND scope_ref IS NULL))+           ORDER BY scene_key ASC, updated_at DESC+           """     )+    partitionedScopeEncoder     (D.rowList sceneRowDecoder)  -- | Delete by the row's own primary key, which was written from @sceneRowId@. -- Deriving the key here instead would re-implement the scope-identity format--- that docs/plans/13-... owns changing.-deleteSceneStmt :: Statement Text ()+-- that docs/plans/13-... owns changing. That key is now composite: @sceneRowId@ is derived+-- from the scope alone, and two memory spaces may hold the same scope.+deleteSceneStmt :: Statement SceneKey () deleteSceneStmt =   preparable-    "DELETE FROM kioku_scenes WHERE scene_id = $1"-    (E.param (E.nonNullable E.text))+    ("DELETE FROM " <> scenesTable <> " WHERE memory_space_id = $1 AND scene_id = $2")+    ( ((\(SceneKey space _) -> space) >$< memorySpaceParam)+        <> ((\(SceneKey _ sceneId) -> sceneId) >$< E.param (E.nonNullable E.text))+    )     D.noResult  upsertSceneStmt :: Statement SceneRow () upsertSceneStmt =   preparable-    """-    INSERT INTO kioku_scenes-      (scene_id, namespace, scope_kind, scope_ref, scene_key, title, body_md,-       atom_ids, source_hash, created_at, updated_at)-    VALUES ($1, $2, $3, $4, $5, $6, $7, $8::jsonb, $9, $10, $11)-    ON CONFLICT (scene_id) DO UPDATE SET-      title = EXCLUDED.title,-      body_md = EXCLUDED.body_md,-      atom_ids = EXCLUDED.atom_ids,-      source_hash = EXCLUDED.source_hash,-      updated_at = EXCLUDED.updated_at-    """+    ( "INSERT INTO "+        <> scenesTable+        <> "\n"+        <> """+             (memory_space_id, scene_id, namespace, scope_kind, scope_ref, scene_key, title, body_md,+              atom_ids, source_hash, created_at, updated_at)+           VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9::jsonb, $10, $11, $12)+           ON CONFLICT (memory_space_id, scene_id) DO UPDATE SET+             title = EXCLUDED.title,+             body_md = EXCLUDED.body_md,+             atom_ids = EXCLUDED.atom_ids,+             source_hash = EXCLUDED.source_hash,+             updated_at = EXCLUDED.updated_at+           """+    )     sceneRowEncoder     D.noResult

@@ -5,8 +5,10 @@     PersonaRow (..),     fireL3PersonaTimer,     getPersonaByScope,+    PersonaTimerPayload (..),     l3PersonaProcessManagerName,     l3PersonaTimerId,+    partitionedCorrelationId,     mirrorPersonaToCurrentWorkspace,     mirrorPersonaToWorkspace,     personaMirrorPath,@@ -16,16 +18,17 @@   ) where -import Contravariant.Extras (contrazip3) import Control.Exception (IOException, try) import Crypto.Hash (Digest, SHA256) import Crypto.Hash qualified as Hash import Data.Aeson qualified as Aeson+import Data.Aeson.Types (withObject, (.:)) import Data.ByteString qualified as BS import Data.ByteString.Lazy qualified as BL+import Data.Foldable (traverse_) import Data.Functor.Contravariant ((>$<)) import Data.Int (Int32)-import Data.Maybe (catMaybes)+import Data.Maybe (catMaybes, maybeToList) import Data.Text qualified as Text import Data.Text.Encoding qualified as TE import Data.Text.IO qualified as TextIO@@ -39,12 +42,22 @@ import Hasql.Statement (Statement, preparable) import Hasql.Transaction qualified as Tx import Keiro.Timer (TimerId (..), TimerRequest (..), TimerRow (..), scheduleTimerTx)+import Kioku.Api.Access+  ( MemoryContextProvider (..),+    MemorySpaceId,+    legacyMemorySpaceId,+    memoryContextSpace,+    memorySpaceIdText,+  ) import Kioku.Api.Scope (MemoryScope, scopeKindText, scopeNamespaceText, scopeRefText)+import Kioku.Database.Schema (personasTable, scenesTable) import Kioku.Distill.Persona (PersonaInput (..), PersonaOutput (..)) import Kioku.Distill.Runtime (DistillRuntime, distillWorkspaceRoot, runPersonaDistillation) import Kioku.Distill.ScopeIdentity (scopeIdentity, scopeSlugFromColumns) import Kioku.Distill.Timer.Outcome (FireOutcome (..), fireRetryDelay, timerMarkerEventId)+import Kioku.Partition (memorySpaceColumn, memorySpaceParam, parsePartitionSpace) import Kioku.Prelude+import Kioku.Workspace (legacyPersonaArtifactDir, personaArtifactDir) import Kiroku.Store.Effect (Store) import Kiroku.Store.Transaction (runTransaction) import Shikumi.Schema.Types (field, unField)@@ -57,7 +70,8 @@   deriving stock (Generic, Show)  data PersonaRow = PersonaRow-  { personaId :: !Text,+  { memorySpaceId :: !MemorySpaceId,+    personaId :: !Text,     namespace :: !Text,     scopeKind :: !(Maybe Text),     scopeRef :: !(Maybe Text),@@ -77,33 +91,50 @@   }   deriving stock (Generic, Eq, Show) -newtype PersonaTimerPayload = PersonaTimerPayload-  { scope :: MemoryScope+-- | What a scheduled persona regeneration needs to know.+--+-- @memorySpaceId@ is what keeps two spaces that happen to share a namespace and scope from+-- regenerating each other's persona. Timers scheduled before the field existed decode into+-- 'Kioku.Api.Access.legacyMemorySpaceId', the same rule stored events follow.+data PersonaTimerPayload = PersonaTimerPayload+  { memorySpaceId :: !MemorySpaceId,+    scope :: !MemoryScope   }   deriving stock (Generic, Eq, Show)-  deriving anyclass (FromJSON, ToJSON)+  deriving anyclass (ToJSON) +instance FromJSON PersonaTimerPayload where+  parseJSON =+    withObject "PersonaTimerPayload" \o ->+      PersonaTimerPayload <$> parsePartitionSpace o <*> o .: "scope"+ l3PersonaProcessManagerName :: Text l3PersonaProcessManagerName = "kioku-l3-persona"  personaDebounceSeconds :: NominalDiffTime personaDebounceSeconds = 5 -scheduleL3PersonaTimerTx :: MemoryScope -> UTCTime -> Tx.Transaction ()-scheduleL3PersonaTimerTx scope now =+scheduleL3PersonaTimerTx :: MemorySpaceId -> MemoryScope -> UTCTime -> Tx.Transaction ()+scheduleL3PersonaTimerTx memorySpaceId scope now =   scheduleTimerTx $     TimerRequest-      { timerId = l3PersonaTimerId scope fireAt,+      { timerId = l3PersonaTimerId memorySpaceId scope fireAt,         processManagerName = l3PersonaProcessManagerName,-        correlationId = scopeIdentity scope,+        correlationId = partitionedCorrelationId memorySpaceId scope,         fireAt,-        payload = Aeson.toJSON (PersonaTimerPayload scope)+        payload = Aeson.toJSON PersonaTimerPayload {memorySpaceId, scope}       }   where     fireAt = addUTCTime personaDebounceSeconds now -l3PersonaTimerId :: MemoryScope -> UTCTime -> TimerId-l3PersonaTimerId scope fireAt =+-- | The timer id and correlation id both carry the memory space.+--+-- Unlike the L1 timers, which are keyed by a globally unique session id, these are keyed by a+-- scope — and two spaces are allowed to use the same one. Without the space in the id,+-- keiro's @scheduleTimerTx@ upsert would treat one space's regeneration as a re-arming of the+-- other's and only one payload would survive.+l3PersonaTimerId :: MemorySpaceId -> MemoryScope -> UTCTime -> TimerId+l3PersonaTimerId memorySpaceId scope fireAt =   TimerId $     UUIDv5.generateNamed       l3PersonaTimerNamespace@@ -112,34 +143,42 @@     raw =       l3PersonaProcessManagerName         <> ":"-        <> scopeIdentity scope+        <> partitionedCorrelationId memorySpaceId scope         <> ":"         <> Text.pack (show fireAt) +-- | A scope identity qualified by its memory space. 'memorySpaceIdText' cannot contain @:@,+-- @\/@ or @%@ (see 'Kioku.Api.Access.mkMemorySpaceId') and 'scopeIdentity' escapes those same+-- characters, so joining the two with @:@ is injective.+partitionedCorrelationId :: MemorySpaceId -> MemoryScope -> Text+partitionedCorrelationId memorySpaceId scope =+  memorySpaceIdText memorySpaceId <> ":" <> scopeIdentity scope+ regeneratePersona ::   (IOE :> es, Store :> es) =>   DistillRuntime ->+  MemorySpaceId ->   MemoryScope ->   Eff es (Either L3Error (Maybe PersonaRow))-regeneratePersona rt scope = do-  scenes <- getPersonaScenesByScope scope+regeneratePersona rt memorySpaceId scope = do+  scenes <- getPersonaScenesByScope memorySpaceId scope   case scenes of     -- Every scene in this scope is gone, so the persona distilled from them has     -- no source left. Delete it and its mirror, symmetrically with the scene     -- delete in "Kioku.Distill.L2", and without an LLM call: there is nothing     -- to summarize. The persona is the top of the pyramid, so nothing chains on.     [] -> do-      existing <- getPersonaByScope scope+      existing <- getPersonaByScope memorySpaceId scope       case existing of         Nothing -> pure (Right Nothing)         Just row -> do-          runTransaction (Tx.statement row.personaId deletePersonaStmt)+          runTransaction (Tx.statement (PersonaKey memorySpaceId row.personaId) deletePersonaStmt)           liftIO (bestEffortRemovePersonaMirror rt row)           pure (Right Nothing)     _ -> do       let sourceHash = personaSourceHash scenes           personaId = personaRowId scope-      existing <- getPersonaByScope scope+      existing <- getPersonaByScope memorySpaceId scope       case existing of         Just row           | row.sourceHash == sourceHash -> do@@ -160,7 +199,8 @@               now <- liftIO getCurrentTime               let row =                     PersonaRow-                      { personaId,+                      { memorySpaceId,+                        personaId,                         namespace = scopeNamespaceText scope,                         scopeKind = scopeKindText scope,                         scopeRef = scopeRefText scope,@@ -174,12 +214,18 @@               liftIO (bestEffortMirrorPersona rt row)               pure (Right (Just row)) +-- | Fire one L3 persona timer.+--+-- Like the L1 handler, a background pass cannot arrive holding an authorization context: it+-- reads the memory space out of the payload and asks the provider for a decision about /that/+-- space. A refusal is a configuration fact, so it dead-letters rather than retrying forever. fireL3PersonaTimer ::   (IOE :> es, Store :> es) =>+  MemoryContextProvider (Eff es) ->   DistillRuntime ->   TimerRow ->   Eff es FireOutcome-fireL3PersonaTimer rt row+fireL3PersonaTimer contexts rt row   | row.processManagerName /= l3PersonaProcessManagerName =       pure FireNotMine   | otherwise =@@ -189,32 +235,65 @@         Aeson.Error err ->           pure (FireFailedPermanently ("L3 persona timer payload is malformed: " <> Text.pack err))         Aeson.Success payload -> do-          result <- regeneratePersona rt payload.scope-          pure $-            case result of-              Right _ -> FireCompleted (timerMarkerEventId row.timerId)-              Left err -> FireRetryLater (fireRetryDelay row.attempts) (Text.pack (show err))+          decision <- contexts.contextForSpace payload.memorySpaceId+          case decision of+            Left denial ->+              pure+                ( FireFailedPermanently+                    ("L3 persona timer is not authorized for its memory space: " <> Text.pack (show denial))+                )+            Right context -> do+              result <- regeneratePersona rt (memoryContextSpace context) payload.scope+              pure $+                case result of+                  Right _ -> FireCompleted (timerMarkerEventId row.timerId)+                  Left err -> FireRetryLater (fireRetryDelay row.attempts) (Text.pack (show err))  getPersonaByScope ::   (Store :> es) =>+  MemorySpaceId ->   MemoryScope ->   Eff es (Maybe PersonaRow)-getPersonaByScope scope =+getPersonaByScope memorySpaceId scope =   runTransaction $-    Tx.statement-      (scopeNamespaceText scope, scopeKindText scope, scopeRefText scope)-      selectPersonaByScopeStmt+    Tx.statement (scopeKey memorySpaceId scope) selectPersonaByScopeStmt  getPersonaScenesByScope ::   (Store :> es) =>+  MemorySpaceId ->   MemoryScope ->   Eff es [PersonaSceneRow]-getPersonaScenesByScope scope =+getPersonaScenesByScope memorySpaceId scope =   runTransaction $-    Tx.statement-      (scopeNamespaceText scope, scopeKindText scope, scopeRefText scope)-      selectScenesForPersonaStmt+    Tx.statement (scopeKey memorySpaceId scope) selectScenesForPersonaStmt +-- | A scope lookup inside one memory space, as a record rather than a four-tuple so that the+-- partition cannot be transposed with the namespace it sits beside.+data PartitionedScope = PartitionedScope+  { memorySpaceId :: !MemorySpaceId,+    namespace :: !Text,+    scopeKind :: !(Maybe Text),+    scopeRef :: !(Maybe Text)+  }++data PersonaKey = PersonaKey !MemorySpaceId !Text++scopeKey :: MemorySpaceId -> MemoryScope -> PartitionedScope+scopeKey memorySpaceId scope =+  PartitionedScope+    { memorySpaceId,+      namespace = scopeNamespaceText scope,+      scopeKind = scopeKindText scope,+      scopeRef = scopeRefText scope+    }++partitionedScopeEncoder :: E.Params PartitionedScope+partitionedScopeEncoder =+  ((\q -> q.memorySpaceId) >$< memorySpaceParam)+    <> ((\q -> q.namespace) >$< E.param (E.nonNullable E.text))+    <> ((\q -> q.scopeKind) >$< E.param (E.nullable E.text))+    <> ((\q -> q.scopeRef) >$< E.param (E.nullable E.text))+ mirrorPersonaToCurrentWorkspace :: PersonaRow -> IO FilePath mirrorPersonaToCurrentWorkspace row = do   workspace <- getCurrentDirectory@@ -223,14 +302,25 @@ mirrorPersonaToWorkspace :: FilePath -> PersonaRow -> IO FilePath mirrorPersonaToWorkspace workspace row = do   let path = personaMirrorPath workspace row-  createDirectoryIfMissing True (workspace </> ".kioku" </> "persona")+  createDirectoryIfMissing True (personaArtifactDir workspace row.memorySpaceId)   TextIO.writeFile path (row.bodyMd <> "\n")   pure path +-- | The mirror path is derived from the row's own memory space as well as its scope, for the+-- reason given at 'Kioku.Distill.L2.sceneMirrorPath': the slug cannot separate two spaces+-- because both are allowed to hold the same scope. personaMirrorPath :: FilePath -> PersonaRow -> FilePath personaMirrorPath workspace row =-  workspace </> ".kioku" </> "persona" </> Text.unpack (personaScopeSlug row <> ".md")+  personaArtifactDir workspace row.memorySpaceId </> Text.unpack (personaScopeSlug row <> ".md") +-- | Where this persona's mirror lived before memory spaces existed. Only the legacy space can+-- have one; see 'Kioku.Distill.L2.sceneMirrorPath'.+legacyPersonaMirrorPath :: FilePath -> PersonaRow -> Maybe FilePath+legacyPersonaMirrorPath workspace row+  | row.memorySpaceId == legacyMemorySpaceId =+      Just (legacyPersonaArtifactDir workspace </> Text.unpack (personaScopeSlug row <> ".md"))+  | otherwise = Nothing+ bestEffortMirrorPersona :: DistillRuntime -> PersonaRow -> IO () bestEffortMirrorPersona rt row = do   let write = do@@ -241,16 +331,25 @@  -- | Remove a persona's mirror file. Best-effort for the same reason writing it -- is: the database row is the durable artifact and is already deleted.+--+-- The legacy space's pre-partition mirror goes too, symmetrically with the scene delete in+-- "Kioku.Distill.L2": every scene this persona was distilled from is gone, so a surviving+-- @.kioku\/persona\/…@ file describes memories nobody may read any more. bestEffortRemovePersonaMirror :: DistillRuntime -> PersonaRow -> IO () bestEffortRemovePersonaMirror rt row = do   let remove = do         workspace <- distillWorkspaceRoot rt-        let path = personaMirrorPath workspace row-        exists <- doesFileExist path-        when exists (removeFile path)+        traverse_+          removeIfPresent+          (personaMirrorPath workspace row : maybeToList (legacyPersonaMirrorPath workspace row))   _ <- try remove :: IO (Either IOException ())   pure () +removeIfPresent :: FilePath -> IO ()+removeIfPresent path = do+  exists <- doesFileExist path+  when exists (removeFile path)+ personaScopeSlug :: PersonaRow -> Text personaScopeSlug row =   scopeSlugFromColumns row.namespace row.scopeKind row.scopeRef@@ -293,8 +392,9 @@ personaRowDecoder :: D.Row PersonaRow personaRowDecoder =   PersonaRow-    <$> D.column (D.nonNullable D.text)+    <$> memorySpaceColumn     <*> D.column (D.nonNullable D.text)+    <*> D.column (D.nonNullable D.text)     <*> D.column (D.nullable D.text)     <*> D.column (D.nullable D.text)     <*> D.column (D.nonNullable D.text)@@ -313,7 +413,8 @@  personaRowEncoder :: E.Params PersonaRow personaRowEncoder =-  ((\row -> row.personaId) >$< E.param (E.nonNullable E.text))+  ((\row -> row.memorySpaceId) >$< memorySpaceParam)+    <> ((\row -> row.personaId) >$< E.param (E.nonNullable E.text))     <> ((\row -> row.namespace) >$< E.param (E.nonNullable E.text))     <> ((\row -> row.scopeKind) >$< E.param (E.nullable E.text))     <> ((\row -> row.scopeRef) >$< E.param (E.nullable E.text))@@ -323,64 +424,76 @@     <> ((\row -> row.createdAt) >$< E.param (E.nonNullable E.timestamptz))     <> ((\row -> row.updatedAt) >$< E.param (E.nonNullable E.timestamptz)) -selectPersonaByScopeStmt :: Statement (Text, Maybe Text, Maybe Text) (Maybe PersonaRow)+selectPersonaByScopeStmt :: Statement PartitionedScope (Maybe PersonaRow) selectPersonaByScopeStmt =   preparable-    """-    SELECT persona_id, namespace, scope_kind, scope_ref, body_md, scene_count,-           source_hash, created_at, updated_at-    FROM kioku_personas-    WHERE namespace = $1-      AND ((scope_kind = $2 AND scope_ref = $3)-           OR ($2 IS NULL AND scope_kind IS NULL AND $3 IS NULL AND scope_ref IS NULL))-    """-    ( contrazip3-        (E.param (E.nonNullable E.text))-        (E.param (E.nullable E.text))-        (E.param (E.nullable E.text))+    ( """+      SELECT memory_space_id, persona_id, namespace, scope_kind, scope_ref, body_md, scene_count,+             source_hash, created_at, updated_at+      FROM+      """+        <> " "+        <> personasTable+        <> " "+        <> """+           WHERE memory_space_id = $1+             AND namespace = $2+             AND ((scope_kind = $3 AND scope_ref = $4)+                  OR ($3 IS NULL AND scope_kind IS NULL AND $4 IS NULL AND scope_ref IS NULL))+           """     )+    partitionedScopeEncoder     (D.rowMaybe personaRowDecoder) -selectScenesForPersonaStmt :: Statement (Text, Maybe Text, Maybe Text) [PersonaSceneRow]+selectScenesForPersonaStmt :: Statement PartitionedScope [PersonaSceneRow] selectScenesForPersonaStmt =   preparable-    """-    SELECT scene_id, title, body_md, updated_at-    FROM kioku_scenes-    WHERE namespace = $1-      AND ((scope_kind = $2 AND scope_ref = $3)-           OR ($2 IS NULL AND scope_kind IS NULL AND $3 IS NULL AND scope_ref IS NULL))-    ORDER BY scene_key ASC, updated_at DESC-    """-    ( contrazip3-        (E.param (E.nonNullable E.text))-        (E.param (E.nullable E.text))-        (E.param (E.nullable E.text))+    ( """+      SELECT scene_id, title, body_md, updated_at+      FROM+      """+        <> " "+        <> scenesTable+        <> " "+        <> """+           WHERE memory_space_id = $1+             AND namespace = $2+             AND ((scope_kind = $3 AND scope_ref = $4)+                  OR ($3 IS NULL AND scope_kind IS NULL AND $4 IS NULL AND scope_ref IS NULL))+           ORDER BY scene_key ASC, updated_at DESC+           """     )+    partitionedScopeEncoder     (D.rowList personaSceneRowDecoder) --- | Delete by the row's own primary key, for the same reason 'deleteSceneStmt'--- does: the scope-identity string format is not re-implemented here.-deletePersonaStmt :: Statement Text ()+-- | Delete by the row's own primary key, for the same reason 'deleteSceneStmt' does: the+-- scope-identity string format is not re-implemented here. That key is now composite, because+-- the persona id alone is derived from the scope and two spaces may share one.+deletePersonaStmt :: Statement PersonaKey () deletePersonaStmt =   preparable-    "DELETE FROM kioku_personas WHERE persona_id = $1"-    (E.param (E.nonNullable E.text))+    ("DELETE FROM " <> personasTable <> " WHERE memory_space_id = $1 AND persona_id = $2")+    ( ((\(PersonaKey space _) -> space) >$< memorySpaceParam)+        <> ((\(PersonaKey _ personaId) -> personaId) >$< E.param (E.nonNullable E.text))+    )     D.noResult  upsertPersonaStmt :: Statement PersonaRow () upsertPersonaStmt =   preparable-    """-    INSERT INTO kioku_personas-      (persona_id, namespace, scope_kind, scope_ref, body_md, scene_count,-       source_hash, created_at, updated_at)-    VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9)-    ON CONFLICT (persona_id) DO UPDATE SET-      body_md = EXCLUDED.body_md,-      scene_count = EXCLUDED.scene_count,-      source_hash = EXCLUDED.source_hash,-      updated_at = EXCLUDED.updated_at-    """+    ( "INSERT INTO "+        <> personasTable+        <> "\n"+        <> """+             (memory_space_id, persona_id, namespace, scope_kind, scope_ref, body_md, scene_count,+              source_hash, created_at, updated_at)+           VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10)+           ON CONFLICT (memory_space_id, persona_id) DO UPDATE SET+             body_md = EXCLUDED.body_md,+             scene_count = EXCLUDED.scene_count,+             source_hash = EXCLUDED.source_hash,+             updated_at = EXCLUDED.updated_at+           """+    )     personaRowEncoder     D.noResult

@@ -7,10 +7,12 @@     l1IdleTimerId,     l1RampTimerId,     l1TimerScheduleProjection,+    L1TimerPayload (..),   ) where  import Data.Aeson qualified as Aeson+import Data.Aeson.Types (withObject, (.:), (.:?)) import Data.ByteString qualified as BS import Data.Foldable (traverse_) import Data.Text qualified as Text@@ -21,7 +23,9 @@ import Data.UUID.V5 qualified as UUIDv5 import Keiro.Projection (InlineProjection (..)) import Keiro.Timer (TimerId (..), TimerRequest (..), scheduleTimerTx)+import Kioku.Api.Access (MemorySpaceId) import Kioku.Id (SessionId, idText)+import Kioku.Partition (parsePartitionSpace) import Kioku.Prelude import Kioku.Session.Domain   ( InteractiveSessionRecordedData (..),@@ -70,48 +74,73 @@ l1FinalTimerId :: SessionId -> TimerId l1FinalTimerId sid = l1TimerIdFor (idText sid <> ":final") +-- | What a scheduled L1 pass needs to know before it can write anything.+--+-- @memorySpaceId@ is the load-bearing field: distillation records and merges memories, and a+-- worker that could not tell which space a session belongs to would have to guess. Timers+-- scheduled before this field existed decode into 'Kioku.Api.Access.legacyMemorySpaceId', the+-- same rule stored events follow.+--+-- @turnCount@ is diagnostic only; the real freshness check is the @kioku_l1_watermarks@ read+-- inside the pass.+data L1TimerPayload = L1TimerPayload+  { kind :: !Text,+    turnCount :: !(Maybe Int),+    memorySpaceId :: !MemorySpaceId+  }+  deriving stock (Generic, Eq, Show)+  deriving anyclass (ToJSON)++instance FromJSON L1TimerPayload where+  parseJSON =+    withObject "L1TimerPayload" \o ->+      L1TimerPayload+        <$> o .: "kind"+        <*> o .:? "turnCount"+        <*> parsePartitionSpace o+ timerRequestsForEvent :: SessionEvent -> [TimerRequest] timerRequestsForEvent = \case   SessionStarted d ->-    [idleRequest d.sessionId (addUTCTime idleFlushSeconds d.startedAt) (Just 0)]+    [idleRequest d.sessionId d.memorySpaceId (addUTCTime idleFlushSeconds d.startedAt) (Just 0)]   InteractiveSessionRecorded d ->-    [idleRequest d.sessionId (addUTCTime idleFlushSeconds d.startedAt) (Just 0)]+    [idleRequest d.sessionId d.memorySpaceId (addUTCTime idleFlushSeconds d.startedAt) (Just 0)]   SessionCompleted d ->-    [finalRequest d.sessionId d.completedAt]+    [finalRequest d.sessionId d.memorySpaceId d.completedAt]   SessionFailed d ->-    [finalRequest d.sessionId (failedAt d)]+    [finalRequest d.sessionId d.memorySpaceId (failedAt d)]   SessionAwaiting _ -> []   SessionResumed _ -> []   TurnRecorded d ->-    let idle = idleRequest d.sessionId (addUTCTime idleFlushSeconds d.recordedAt) (Just d.turnIndex)-        ramp = rampRequest d.sessionId d.turnIndex d.recordedAt+    let idle = idleRequest d.sessionId d.memorySpaceId (addUTCTime idleFlushSeconds d.recordedAt) (Just d.turnIndex)+        ramp = rampRequest d.sessionId d.memorySpaceId d.turnIndex d.recordedAt      in if isRampTurn d.turnIndex then [ramp, idle] else [idle] -idleRequest :: SessionId -> UTCTime -> Maybe Int -> TimerRequest-idleRequest sid = l1TimerRequest (l1IdleTimerId sid) sid "idle"+idleRequest :: SessionId -> MemorySpaceId -> UTCTime -> Maybe Int -> TimerRequest+idleRequest sid space = l1TimerRequest (l1IdleTimerId sid) sid space "idle" -rampRequest :: SessionId -> Int -> UTCTime -> TimerRequest-rampRequest sid turnIndex fireAt =-  l1TimerRequest (l1RampTimerId sid turnIndex) sid "ramp" fireAt (Just turnIndex)+rampRequest :: SessionId -> MemorySpaceId -> Int -> UTCTime -> TimerRequest+rampRequest sid space turnIndex fireAt =+  l1TimerRequest (l1RampTimerId sid turnIndex) sid space "ramp" fireAt (Just turnIndex) -finalRequest :: SessionId -> UTCTime -> TimerRequest-finalRequest sid fireAt =-  l1TimerRequest (l1FinalTimerId sid) sid "final" fireAt Nothing+finalRequest :: SessionId -> MemorySpaceId -> UTCTime -> TimerRequest+finalRequest sid space fireAt =+  l1TimerRequest (l1FinalTimerId sid) sid space "final" fireAt Nothing --- | @turnCount@ in the payload is diagnostic only; the real freshness check is--- the @kioku_l1_watermarks@ read inside the pass.-l1TimerRequest :: TimerId -> SessionId -> Text -> UTCTime -> Maybe Int -> TimerRequest-l1TimerRequest timerId sid kind fireAt turnCount =+-- | The timer /id/ deliberately does not include the memory space.+--+-- It does not need to: a session id is globally unique and the aggregate pins each session to+-- exactly one space, so two spaces cannot produce the same @(session, kind)@ pair. Folding the+-- space in would also change every id, which would leave a second idle timer armed for every+-- session already in flight at upgrade time.+l1TimerRequest :: TimerId -> SessionId -> MemorySpaceId -> Text -> UTCTime -> Maybe Int -> TimerRequest+l1TimerRequest timerId sid memorySpaceId kind fireAt turnCount =   TimerRequest     { timerId,       processManagerName = l1ExtractProcessManagerName,       correlationId = idText sid,       fireAt,-      payload =-        Aeson.object-          [ "kind" Aeson..= kind,-            "turnCount" Aeson..= turnCount-          ]+      payload = Aeson.toJSON L1TimerPayload {kind, turnCount, memorySpaceId}     }  isRampTurn :: Int -> Bool

@@ -10,13 +10,20 @@   ) where +import Data.Aeson qualified as Aeson+import Data.Aeson.Types qualified as Aeson+import Data.HashMap.Strict (HashMap)+import Data.HashMap.Strict qualified as HashMap+import Data.Int (Int64) import Data.Text qualified as Text import Data.Time (NominalDiffTime, addUTCTime)+import Data.UUID qualified as UUID import Effectful (Eff, IOE, (:>)) import Effectful.Error.Static (Error) import Keiro.Telemetry (KeiroMetrics) import Keiro.Timer-  ( TimerRequest (..),+  ( TimerId (..),+    TimerRequest (..),     TimerRow (..),     TimerWorkerOptions (..),     deadLetterTimer,@@ -24,11 +31,12 @@     runTimerWorkerWith,     scheduleTimerTx,   )+import Kioku.Api.Access (MemoryContextProvider (..), MemorySpaceId, memorySpaceIdText) import Kioku.Distill.L1 (FindMergeCandidates, L1Error (..), L1RunMode (..), distillSessionL1) import Kioku.Distill.L2 (fireL2SceneTimer) import Kioku.Distill.L3 (fireL3PersonaTimer) import Kioku.Distill.Runtime (DistillRuntime)-import Kioku.Distill.Timer (l1ExtractProcessManagerName)+import Kioku.Distill.Timer (L1TimerPayload (..), l1ExtractProcessManagerName) import Kioku.Distill.Timer.Outcome   ( FireOutcome (..),     fireRetryDelay,@@ -36,12 +44,15 @@     unknownTimerRetryDelay,   ) import Kioku.Id (parseIdLenient)+import Kioku.Partition (parsePartitionSpace) import Kioku.Prelude import Kiroku.Store.Effect (Store) import Kiroku.Store.Effect.Resource (KirokuStoreResource) import Kiroku.Store.Error (StoreError) import Kiroku.Store.Transaction (runTransaction) import Kiroku.Store.Types (EventId (..))+import OpenTelemetry.Attributes qualified as Attr+import Shibuya.Telemetry.Effect (Tracing, addAttributes, defaultSpanArguments, withSpan') import System.IO qualified as IO  -- | kioku's timer policy.@@ -55,13 +66,22 @@ kiokuTimerWorkerOptions =   TimerWorkerOptions {maxAttempts = Just 8, requeueStuckAfter = Just 300} +-- | Fire one L1 distillation timer.+--+-- A background pass discovers its own work, so it cannot arrive holding an authorization+-- context the way an interactive caller does. It reads the memory space out of the timer+-- payload — put there by the projection from the session event, and defaulted to the legacy+-- space for timers scheduled before that field existed — and asks the provider for a decision+-- about /that/ space. An embedded host wires the provider to+-- 'Kioku.Api.Access.assumeAuthorizedContextProvider'. fireL1Timer ::   (IOE :> es, KirokuStoreResource :> es, Store :> es, Error StoreError :> es) =>+  MemoryContextProvider (Eff es) ->   DistillRuntime ->   FindMergeCandidates es ->   TimerRow ->   Eff es FireOutcome-fireL1Timer rt finder row+fireL1Timer contexts rt finder row   | row.processManagerName /= l1ExtractProcessManagerName =       pure FireNotMine   | otherwise =@@ -73,18 +93,34 @@             ( FireFailedPermanently                 ("L1 timer correlation id is not a session id: " <> row.correlationId)             )-        Right sid -> do-          result <- distillSessionL1 RespectWatermark rt finder sid-          pure $-            case result of-              -- Both a real pass and a watermark skip mean this timer is done.-              Right _outcome -> FireCompleted (timerMarkerEventId row.timerId)-              -- A session may legitimately be gone (deleted data); nothing to do.-              Left (L1SessionNotFound _) -> FireCompleted (timerMarkerEventId row.timerId)-              -- Everything else — a failed LLM extraction or consolidation, a-              -- read-model error, a failed write — is worth another attempt, and-              -- the attempt ceiling bounds how many.-              Left err -> FireRetryLater (fireRetryDelay row.attempts) (Text.pack (show err))+        Right sid ->+          -- A payload this handler cannot parse will not parse on the next attempt either.+          case Aeson.fromJSON @L1TimerPayload row.payload of+            Aeson.Error err ->+              pure (FireFailedPermanently ("L1 timer payload is malformed: " <> Text.pack err))+            Aeson.Success payload -> do+              decision <- contexts.contextForSpace payload.memorySpaceId+              case decision of+                -- Dead-letter rather than retry: a refusal to distill this space is a+                -- configuration fact, and quietly retrying it every 30 seconds forever would+                -- hide it. The dead-letter row is where an operator can see and requeue it.+                Left denial ->+                  pure+                    ( FireFailedPermanently+                        ("L1 timer is not authorized for its memory space: " <> Text.pack (show denial))+                    )+                Right context -> do+                  result <- distillSessionL1 context RespectWatermark rt finder sid+                  pure $+                    case result of+                      -- Both a real pass and a watermark skip mean this timer is done.+                      Right _outcome -> FireCompleted (timerMarkerEventId row.timerId)+                      -- A session may legitimately be gone (deleted data); nothing to do.+                      Left (L1SessionNotFound _) -> FireCompleted (timerMarkerEventId row.timerId)+                      -- Everything else — a failed LLM extraction or consolidation, a+                      -- read-model error, a failed write — is worth another attempt, and+                      -- the attempt ceiling bounds how many.+                      Left err -> FireRetryLater (fireRetryDelay row.attempts) (Text.pack (show err))  -- | Offer the timer to each handler in turn. The handlers identify their own -- work by process-manager name, so a 'FireNotMine' simply falls through to the@@ -92,17 +128,18 @@ -- the runner decides what to do about that. fireKiokuTimer ::   (IOE :> es, KirokuStoreResource :> es, Store :> es, Error StoreError :> es) =>+  MemoryContextProvider (Eff es) ->   DistillRuntime ->   FindMergeCandidates es ->   TimerRow ->   Eff es FireOutcome-fireKiokuTimer rt finder row = do-  l1Result <- fireL1Timer rt finder row+fireKiokuTimer contexts rt finder row = do+  l1Result <- fireL1Timer contexts rt finder row   case l1Result of     FireNotMine -> do-      l2Result <- fireL2SceneTimer rt row+      l2Result <- fireL2SceneTimer contexts rt row       case l2Result of-        FireNotMine -> fireL3PersonaTimer rt row+        FireNotMine -> fireL3PersonaTimer contexts rt row         outcome -> pure outcome     outcome -> pure outcome @@ -111,6 +148,11 @@ -- Returning 'Nothing' to keiro means "do not mark this row fired"; every such -- branch has already moved the row itself, so the timer never sits in @firing@ -- waiting on the 300-second stale requeue.+--+-- Every diagnostic this writes names the memory space, including the @last_error@ that lands in+-- the dead-letter row. That column is what an operator actually reads at three in the morning,+-- and a dead-lettered distillation that does not say which tenant it belongs to is a page+-- somebody has to answer with a query. applyFireOutcome ::   (IOE :> es, Store :> es) =>   TimerRow ->@@ -123,14 +165,73 @@     rescheduleClaimedTimer row delay     pure Nothing   FireFailedPermanently reason -> do-    logTimer row ("dead-lettering: " <> reason)-    void (deadLetterTimer row.timerId reason)+    let annotated = spaceQualified row reason+    logTimer row ("dead-lettering: " <> annotated)+    void (deadLetterTimer row.timerId annotated)     pure Nothing   FireNotMine -> do     logTimer row "no handler owns this process manager; requeueing"     rescheduleClaimedTimer row unknownTimerRetryDelay     pure Nothing +-- | Prefix a diagnostic with the memory space the timer's payload names.+--+-- @unknown@ covers the payloads that have no space to name: a malformed payload, or one from a+-- process manager that is not Kioku's. Those are exactly the cases where the timer is about to+-- be dead-lettered, so saying "unknown" is more useful than silently claiming the legacy space.+spaceQualified :: TimerRow -> Text -> Text+spaceQualified row reason =+  "[memory space "+    <> maybe "unknown" memorySpaceIdText (timerPayloadSpace row.payload)+    <> "] "+    <> reason++-- | The memory space a timer payload names, for diagnostics only.+--+-- Every one of the three payload types carries the space, and each decodes it through+-- 'parsePartitionSpace' — the same function this uses — so this cannot disagree with the handler+-- that actually acts on the payload. It is read here rather than returned by the handlers so+-- that a span and a dead-letter row can name the space even when no handler claimed the timer.+timerPayloadSpace :: Aeson.Value -> Maybe MemorySpaceId+timerPayloadSpace = \case+  Aeson.Object o -> Aeson.parseMaybe parsePartitionSpace o+  _ -> Nothing++-- | Span attributes for one fire attempt.+--+-- The space is here, on the trace, and deliberately not on a metric: a memory space is+-- caller-supplied text with no bound on how many distinct values exist, and a counter labelled+-- by it is an unbounded time series per tenant. Traces are sampled and per-incident; that is the+-- right place for an identifier a caller chose.+timerSpanAttributes :: TimerRow -> HashMap Text Attr.Attribute+timerSpanAttributes row =+  HashMap.fromList+    ( [ ("kioku.timer.process_manager", Attr.toAttribute row.processManagerName),+        ("kioku.timer.id", Attr.toAttribute (timerIdText row.timerId)),+        ("kioku.timer.attempts", Attr.toAttribute (fromIntegral @Int @Int64 row.attempts))+      ]+        <> foldMap+          (\space -> [("kioku.memory_space_id", Attr.toAttribute (memorySpaceIdText space))])+          (timerPayloadSpace row.payload)+    )++-- | What the fire decided, as a bounded outcome plus an unbounded reason.+--+-- The outcome is one of four constants, so it is safe anywhere including a metric label. The+-- reason is free text — an LLM provider message, a codec error — and stays on the span.+fireOutcomeAttributes :: FireOutcome -> HashMap Text Attr.Attribute+fireOutcomeAttributes = \case+  FireCompleted _ -> HashMap.fromList [outcomeAttr "completed"]+  FireRetryLater _ note -> HashMap.fromList [outcomeAttr "retry", reasonAttr note]+  FireFailedPermanently reason -> HashMap.fromList [outcomeAttr "dead_letter", reasonAttr reason]+  FireNotMine -> HashMap.fromList [outcomeAttr "not_mine"]+  where+    outcomeAttr value = ("kioku.timer.outcome", Attr.toAttribute (value :: Text))+    reasonAttr value = ("kioku.timer.reason", Attr.toAttribute value)++timerIdText :: TimerId -> Text+timerIdText (TimerId uuid) = UUID.toText uuid+ -- | Push a claimed timer back out into the future. -- -- keiro has no single-call "reschedule a firing timer" at this pin, so this is@@ -158,16 +259,25 @@             payload = row.payload           } +-- | Claim and fire at most one due timer, inside a span that names the memory space.+--+-- keiro's own timer metrics stay exactly as they are: they carry no space and no principal, and+-- this deliberately adds neither. See 'timerSpanAttributes'. runKiokuTimerWorkerOnce ::-  (IOE :> es, KirokuStoreResource :> es, Store :> es, Error StoreError :> es) =>+  (IOE :> es, KirokuStoreResource :> es, Store :> es, Error StoreError :> es, Tracing :> es) =>   Maybe KeiroMetrics ->+  MemoryContextProvider (Eff es) ->   DistillRuntime ->   FindMergeCandidates es ->   UTCTime ->   Eff es (Maybe TimerRow)-runKiokuTimerWorkerOnce metrics rt finder now =+runKiokuTimerWorkerOnce metrics contexts rt finder now =   runTimerWorkerWith metrics kiokuTimerWorkerOptions now \row ->-    fireKiokuTimer rt finder row >>= applyFireOutcome row+    withSpan' "kioku.timer.fire" defaultSpanArguments \fireSpan -> do+      addAttributes fireSpan (timerSpanAttributes row)+      outcome <- fireKiokuTimer contexts rt finder row+      addAttributes fireSpan (fireOutcomeAttributes outcome)+      applyFireOutcome row outcome  -- | Claim and fire due timers until none remain, returning how many were -- processed.@@ -178,16 +288,17 @@ -- terminal state, so a timer processed in this pass is not claimable again -- within it. drainKiokuTimers ::-  (IOE :> es, KirokuStoreResource :> es, Store :> es, Error StoreError :> es) =>+  (IOE :> es, KirokuStoreResource :> es, Store :> es, Error StoreError :> es, Tracing :> es) =>   Maybe KeiroMetrics ->+  MemoryContextProvider (Eff es) ->   DistillRuntime ->   FindMergeCandidates es ->   Eff es Int-drainKiokuTimers metrics rt finder = go 0+drainKiokuTimers metrics contexts rt finder = go 0   where     go processed = do       now <- liftIO getCurrentTime-      claimed <- runKiokuTimerWorkerOnce metrics rt finder now+      claimed <- runKiokuTimerWorkerOnce metrics contexts rt finder now       case claimed of         Nothing -> pure processed         Just _ -> go (processed + 1)

@@ -1,11 +1,53 @@+-- | Writing and reading memories.+--+-- Every write takes a 'MemoryAccessContext' first. That record is the statement "somebody has+-- already decided this caller may do this here" — obtained from+-- 'Kioku.Api.Access.authorizeMemoryAccess' behind a service boundary, or from+-- 'Kioku.Api.Access.assumeAuthorizedMemoryContext' in a trusted in-process host. Kioku's core+-- never derives one.+--+-- Each write asks the context for one permission:+--+-- * 'MemoryRecord' — 'recordWithContext', 'updateTagsWithContext',+--   'updateConfidenceWithContext'. These create or amend a memory.+-- * 'MemoryForget' — 'supersedeWithContext', 'archiveWithContext', 'mergeWithContext'. These+--   retire one.+--+-- The context is checked against the command, not merged into it: the payload names its own+-- memory space and actor, and a payload that disagrees with the context that authorized it is+-- rejected rather than quietly rewritten. That keeps the stored event and the decision that+-- allowed it the same fact.+--+-- The unsuffixed functions ('record', 'archive', …) remain for one release as deprecated+-- compatibility wrappers. They take no context and refuse any payload naming a space other than+-- 'legacyMemorySpaceId', so they cannot reach data belonging to anybody else.+--+-- Every read takes a 'MemorySpaceId' first and returns nothing outside it. Pass+-- 'Kioku.Api.Access.memoryContextSpace' of the context that authorized the read: the context is+-- what decides which space may be named, and the space is what the schema enforces. A read+-- takes the space rather than the whole context because these functions return+-- @Either ReadModelError@, and a permission denial has already been decided — a context exists+-- only for permissions 'Kioku.Api.Access.authorizeMemoryAccess' actually checked. module Kioku.Memory   ( MemoryWriteError (..),++    -- * Writing memory+    recordWithContext,+    supersedeWithContext,+    archiveWithContext,+    updateTagsWithContext,+    updateConfidenceWithContext,+    mergeWithContext,++    -- * Deprecated compatibility wrappers, confined to the legacy memory space     record,     supersede,     archive,     updateTags,     updateConfidence,     merge,++    -- * Reading memory     getMemoryRowById,     getActiveRowsInNamespace,     getActiveRowsByScope,@@ -21,6 +63,16 @@ import Keiro.Command (CommandError (..), defaultRunCommandOptions) import Keiro.Projection (runCommandWithProjections) import Keiro.ReadModel (ConsistencyMode (..), ReadModelError, runQueryWith)+import Kioku.Api.Access+  ( MemoryAccessContext,+    MemoryPermission (..),+    MemorySpaceId,+    RecordedPrincipal (..),+    legacyMemorySpaceId,+    memoryContextAllows,+    memoryContextRecordedActor,+    memoryContextSpace,+  ) import Kioku.Api.Scope (MemoryScope (..), Namespace (..), scopeKindText, scopeNamespaceText, scopeRefText) import Kioku.Api.Types (MemoryType, confidenceToText, memoryTypeToText) import Kioku.Distill.L2 (l2SceneTimerScheduleProjection)@@ -54,29 +106,112 @@   | MemoryNotFound   | MemoryNotActive   | MemoryConflict !Text+  | -- | the context authorized other actions, but not this one+    MemoryNotPermitted !MemoryPermission+  | -- | the command names a memory space the context was not minted for:+    -- @MemorySpaceMismatch requested authorized@+    MemorySpaceMismatch !MemorySpaceId !MemorySpaceId+  | -- | the command attributes the write to somebody other than the context's own principal+    MemoryActorMismatch !RecordedPrincipal !RecordedPrincipal   deriving stock (Generic, Show) +-- | Gate a write on the decision that authorized it.+--+-- Three things have to agree and none of them is redundant. The permission check is what stops a+-- context minted for reading from being spent on a write. The space check is the isolation+-- boundary itself. The actor check is what stops a caller authorized as one principal from+-- writing an event that says another principal acted — which would be a forged audit trail, and+-- is the reason the actor is checked rather than merely defaulted.+underContext ::+  (Applicative f) =>+  MemoryAccessContext ->+  MemoryPermission ->+  MemorySpaceId ->+  RecordedPrincipal ->+  f (Either MemoryWriteError a) ->+  f (Either MemoryWriteError a)+underContext context permission space actor run+  | not (memoryContextAllows permission context) =+      pure (Left (MemoryNotPermitted permission))+  | space /= authorizedSpace =+      pure (Left (MemorySpaceMismatch space authorizedSpace))+  | actor /= authorizedActor =+      pure (Left (MemoryActorMismatch actor authorizedActor))+  | otherwise = run+  where+    authorizedSpace = memoryContextSpace context+    authorizedActor = memoryContextRecordedActor context++-- | Gate a deprecated wrapper on the one space it is allowed to touch.+--+-- A wrapper that silently retargeted a payload into the legacy space would reintroduce exactly+-- the defaulting this whole change exists to remove, so it refuses instead.+inLegacySpaceOnly ::+  (Applicative f) =>+  MemorySpaceId ->+  f (Either MemoryWriteError a) ->+  f (Either MemoryWriteError a)+inLegacySpaceOnly space run+  | space /= legacyMemorySpaceId = pure (Left (MemorySpaceMismatch space legacyMemorySpaceId))+  | otherwise = run++-- | Record a new memory in the space the context authorizes.+recordWithContext ::+  (IOE :> es, KirokuStoreResource :> es, Store :> es, Error StoreError :> es) =>+  MemoryAccessContext ->+  RecordMemoryData ->+  Eff es (Either MemoryWriteError MemoryId)+recordWithContext context cmdData =+  underContext context MemoryRecord cmdData.memorySpaceId cmdData.actorPrincipal (recordIn cmdData)++{-# DEPRECATED record "Use recordWithContext. This wrapper accepts only legacyMemorySpaceId and will be removed." #-}++-- | Deprecated: record into the legacy memory space, with no authorization context. record ::   (IOE :> es, KirokuStoreResource :> es, Store :> es, Error StoreError :> es) =>   RecordMemoryData ->   Eff es (Either MemoryWriteError MemoryId)-record cmdData = do-  existing <- lookupMemory cmdData.memoryId+record cmdData = inLegacySpaceOnly cmdData.memorySpaceId (recordIn cmdData)++recordIn ::+  (IOE :> es, KirokuStoreResource :> es, Store :> es, Error StoreError :> es) =>+  RecordMemoryData ->+  Eff es (Either MemoryWriteError MemoryId)+recordIn cmdData = do+  existing <- lookupMemory cmdData.memorySpaceId cmdData.memoryId   case existing of     Left err -> pure (Left (MemoryReadFailed err))     Right (Just row) -> pure (idempotentOr "record" recordMismatch row cmdData.memoryId)     Right Nothing ->       runMemoryCommand cmdData.memoryId (RecordMemory cmdData)-        >>= acceptRejectedIfMatches cmdData.memoryId (isNothing . recordMismatch)+        >>= acceptRejectedIfMatches cmdData.memorySpaceId cmdData.memoryId (isNothing . recordMismatch)   where     recordMismatch = mismatchOf memoryRecordFields cmdData +-- | Retire a memory in favour of a newer one, in the space the context authorizes.+supersedeWithContext ::+  (IOE :> es, KirokuStoreResource :> es, Store :> es, Error StoreError :> es) =>+  MemoryAccessContext ->+  SupersedeMemoryData ->+  Eff es (Either MemoryWriteError MemoryId)+supersedeWithContext context cmdData =+  underContext context MemoryForget cmdData.memorySpaceId cmdData.actorPrincipal (supersedeIn cmdData)++{-# DEPRECATED supersede "Use supersedeWithContext. This wrapper accepts only legacyMemorySpaceId and will be removed." #-}++-- | Deprecated: supersede within the legacy memory space, with no authorization context. supersede ::   (IOE :> es, KirokuStoreResource :> es, Store :> es, Error StoreError :> es) =>   SupersedeMemoryData ->   Eff es (Either MemoryWriteError MemoryId)-supersede cmdData = do-  existing <- lookupMemory cmdData.memoryId+supersede cmdData = inLegacySpaceOnly cmdData.memorySpaceId (supersedeIn cmdData)++supersedeIn ::+  (IOE :> es, KirokuStoreResource :> es, Store :> es, Error StoreError :> es) =>+  SupersedeMemoryData ->+  Eff es (Either MemoryWriteError MemoryId)+supersedeIn cmdData = do+  existing <- lookupMemory cmdData.memorySpaceId cmdData.memoryId   case existing of     Left err -> pure (Left (MemoryReadFailed err))     Right Nothing -> pure (Left MemoryNotFound)@@ -86,16 +221,34 @@       | row.status /= "active" -> pure (idempotentOr "supersede" supersedeMismatch row cmdData.memoryId)       | otherwise ->           runMemoryCommand cmdData.memoryId (SupersedeMemory cmdData)-            >>= acceptRejectedIfMatches cmdData.memoryId (isNothing . supersedeMismatch)+            >>= acceptRejectedIfMatches cmdData.memorySpaceId cmdData.memoryId (isNothing . supersedeMismatch)   where     supersedeMismatch = mismatchOf memorySupersedeFields cmdData +-- | Archive a memory, in the space the context authorizes.+archiveWithContext ::+  (IOE :> es, KirokuStoreResource :> es, Store :> es, Error StoreError :> es) =>+  MemoryAccessContext ->+  ArchiveMemoryData ->+  Eff es (Either MemoryWriteError MemoryId)+archiveWithContext context cmdData =+  underContext context MemoryForget cmdData.memorySpaceId cmdData.actorPrincipal (archiveIn cmdData)++{-# DEPRECATED archive "Use archiveWithContext. This wrapper accepts only legacyMemorySpaceId and will be removed." #-}++-- | Deprecated: archive within the legacy memory space, with no authorization context. archive ::   (IOE :> es, KirokuStoreResource :> es, Store :> es, Error StoreError :> es) =>   ArchiveMemoryData ->   Eff es (Either MemoryWriteError MemoryId)-archive cmdData = do-  existing <- lookupMemory cmdData.memoryId+archive cmdData = inLegacySpaceOnly cmdData.memorySpaceId (archiveIn cmdData)++archiveIn ::+  (IOE :> es, KirokuStoreResource :> es, Store :> es, Error StoreError :> es) =>+  ArchiveMemoryData ->+  Eff es (Either MemoryWriteError MemoryId)+archiveIn cmdData = do+  existing <- lookupMemory cmdData.memorySpaceId cmdData.memoryId   case existing of     Left err -> pure (Left (MemoryReadFailed err))     Right Nothing -> pure (Left MemoryNotFound)@@ -103,16 +256,34 @@       | row.status /= "active" -> pure (idempotentOr "archive" archiveMismatch row cmdData.memoryId)       | otherwise ->           runMemoryCommand cmdData.memoryId (ArchiveMemory cmdData)-            >>= acceptRejectedIfMatches cmdData.memoryId (isNothing . archiveMismatch)+            >>= acceptRejectedIfMatches cmdData.memorySpaceId cmdData.memoryId (isNothing . archiveMismatch)   where     archiveMismatch = mismatchOf memoryArchiveFields cmdData +-- | Replace a memory's tags, in the space the context authorizes.+updateTagsWithContext ::+  (IOE :> es, KirokuStoreResource :> es, Store :> es, Error StoreError :> es) =>+  MemoryAccessContext ->+  UpdateMemoryTagsData ->+  Eff es (Either MemoryWriteError MemoryId)+updateTagsWithContext context cmdData =+  underContext context MemoryRecord cmdData.memorySpaceId cmdData.actorPrincipal (updateTagsIn cmdData)++{-# DEPRECATED updateTags "Use updateTagsWithContext. This wrapper accepts only legacyMemorySpaceId and will be removed." #-}++-- | Deprecated: retag within the legacy memory space, with no authorization context. updateTags ::   (IOE :> es, KirokuStoreResource :> es, Store :> es, Error StoreError :> es) =>   UpdateMemoryTagsData ->   Eff es (Either MemoryWriteError MemoryId)-updateTags cmdData = do-  existing <- lookupMemory cmdData.memoryId+updateTags cmdData = inLegacySpaceOnly cmdData.memorySpaceId (updateTagsIn cmdData)++updateTagsIn ::+  (IOE :> es, KirokuStoreResource :> es, Store :> es, Error StoreError :> es) =>+  UpdateMemoryTagsData ->+  Eff es (Either MemoryWriteError MemoryId)+updateTagsIn cmdData = do+  existing <- lookupMemory cmdData.memorySpaceId cmdData.memoryId   case existing of     Left err -> pure (Left (MemoryReadFailed err))     Right Nothing -> pure (Left MemoryNotFound)@@ -121,12 +292,30 @@       | row.tags == cmdData.tags -> pure (Right cmdData.memoryId)       | otherwise -> runMemoryCommand cmdData.memoryId (UpdateMemoryTags cmdData) +-- | Re-score a memory's confidence, in the space the context authorizes.+updateConfidenceWithContext ::+  (IOE :> es, KirokuStoreResource :> es, Store :> es, Error StoreError :> es) =>+  MemoryAccessContext ->+  UpdateMemoryConfidenceData ->+  Eff es (Either MemoryWriteError MemoryId)+updateConfidenceWithContext context cmdData =+  underContext context MemoryRecord cmdData.memorySpaceId cmdData.actorPrincipal (updateConfidenceIn cmdData)++{-# DEPRECATED updateConfidence "Use updateConfidenceWithContext. This wrapper accepts only legacyMemorySpaceId and will be removed." #-}++-- | Deprecated: re-score within the legacy memory space, with no authorization context. updateConfidence ::   (IOE :> es, KirokuStoreResource :> es, Store :> es, Error StoreError :> es) =>   UpdateMemoryConfidenceData ->   Eff es (Either MemoryWriteError MemoryId)-updateConfidence cmdData = do-  existing <- lookupMemory cmdData.memoryId+updateConfidence cmdData = inLegacySpaceOnly cmdData.memorySpaceId (updateConfidenceIn cmdData)++updateConfidenceIn ::+  (IOE :> es, KirokuStoreResource :> es, Store :> es, Error StoreError :> es) =>+  UpdateMemoryConfidenceData ->+  Eff es (Either MemoryWriteError MemoryId)+updateConfidenceIn cmdData = do+  existing <- lookupMemory cmdData.memorySpaceId cmdData.memoryId   case existing of     Left err -> pure (Left (MemoryReadFailed err))     Right Nothing -> pure (Left MemoryNotFound)@@ -135,19 +324,50 @@       | row.confidence == confidenceToText cmdData.confidence -> pure (Right cmdData.memoryId)       | otherwise -> runMemoryCommand cmdData.memoryId (UpdateMemoryConfidence cmdData) --- | Merge @loser@ into @winner@.+-- | Merge @loser@ into @winner@, in the space the context authorizes. -- -- Unlike the other writes, @mergedAt@ is generated here rather than supplied by the caller, -- so a retry cannot re-deliver an identical timestamp. Idempotency therefore matches on the -- merge target alone: merging into the same winner twice is a duplicate, merging into a -- different one is a conflict.+--+-- Both memories must live in the authorized space. The loser is checked by the aggregate guard+-- on the command below; the winner is only referenced, and 'Kioku.Distill.L1' — the one caller+-- that supplies a winner it did not just write — resolves both from the same session.+mergeWithContext ::+  (IOE :> es, KirokuStoreResource :> es, Store :> es, Error StoreError :> es) =>+  MemoryAccessContext ->+  MemoryId ->+  MemoryId ->+  Eff es (Either MemoryWriteError MemoryId)+mergeWithContext context loser winner =+  underContext context MemoryForget space actor (mergeIn space actor loser winner)+  where+    space = memoryContextSpace context+    actor = memoryContextRecordedActor context++{-# DEPRECATED merge "Use mergeWithContext. This wrapper writes only into legacyMemorySpaceId and will be removed." #-}++-- | Deprecated: merge within the legacy memory space, with no authorization context.+--+-- The recorded actor is 'UnattributedPrincipal' rather than an invented one: this path has no+-- context, so nothing here knows who is merging. merge ::   (IOE :> es, KirokuStoreResource :> es, Store :> es, Error StoreError :> es) =>   MemoryId ->   MemoryId ->   Eff es (Either MemoryWriteError MemoryId)-merge loser winner = do-  existing <- lookupMemory loser+merge = mergeIn legacyMemorySpaceId UnattributedPrincipal++mergeIn ::+  (IOE :> es, KirokuStoreResource :> es, Store :> es, Error StoreError :> es) =>+  MemorySpaceId ->+  RecordedPrincipal ->+  MemoryId ->+  MemoryId ->+  Eff es (Either MemoryWriteError MemoryId)+mergeIn memorySpaceId actorPrincipal loser winner = do+  existing <- lookupMemory memorySpaceId loser   case existing of     Left err -> pure (Left (MemoryReadFailed err))     Right Nothing -> pure (Left MemoryNotFound)@@ -155,8 +375,18 @@       | row.status /= "active" -> pure (idempotentOr "merge" mergeMismatch row loser)       | otherwise -> do           now <- liftIO getCurrentTime-          runMemoryCommand loser (MergeMemory (MergeMemoryData loser winner now))-            >>= acceptRejectedIfMatches loser (isNothing . mergeMismatch)+          runMemoryCommand+            loser+            ( MergeMemory+                MergeMemoryData+                  { memoryId = loser,+                    memorySpaceId,+                    actorPrincipal,+                    mergedInto = winner,+                    mergedAt = now+                  }+            )+            >>= acceptRejectedIfMatches memorySpaceId loser (isNothing . mergeMismatch)   where     mergeMismatch = mismatchOf memoryMergeFields winner @@ -177,6 +407,13 @@ -- Everything that carries meaning — content, scope, type, priority, confidence, tags, -- lineage, and the merge/supersession target — is compared, which is what the review -- actually asked for: a reused id with different /content/ must not report success.+--+-- The memory space is absent from these comparisons because it can no longer differ. Every+-- lookup that produces the row is now scoped to the command's own space, so a row from another+-- space is simply not found and the write proceeds to the aggregate, which refuses it. That+-- closes the residual this comment used to describe: presenting the id of a memory in another+-- space no longer reveals, through an idempotent answer, that the id exists or that it is+-- active. mismatchOf :: [FieldCheck cmd] -> cmd -> MemoryRow -> Maybe Text mismatchOf checks cmd row =   fst <$> find (\(_, matches) -> not (matches cmd row)) checks@@ -199,13 +436,14 @@ -- 'Kioku.Session.acceptRejectedIfMatches' — same contract, memory side. acceptRejectedIfMatches ::   (IOE :> es, Store :> es) =>+  MemorySpaceId ->   MemoryId ->   (MemoryRow -> Bool) ->   Either MemoryWriteError MemoryId ->   Eff es (Either MemoryWriteError MemoryId)-acceptRejectedIfMatches mid matches = \case+acceptRejectedIfMatches space mid matches = \case   Left err@(MemoryCommandRejected CommandRejected) -> do-    reread <- lookupMemory mid+    reread <- lookupMemory space mid     pure case reread of       Right (Just row) | matches row -> Right mid       _ -> Left err@@ -244,15 +482,23 @@     ("mergedInto", \winner row -> row.supersededBy == Just (idText winner))   ] +-- | Look a memory up inside one space. A memory that lives elsewhere is 'Nothing' here, which+-- is what makes the write paths' idempotency prechecks unable to answer questions about it. lookupMemory ::   (IOE :> es, Store :> es) =>+  MemorySpaceId ->   MemoryId ->   Eff es (Either ReadModelError (Maybe MemoryRow))-lookupMemory mid =-  runQueryWith Nothing Eventual memoryByIdReadModel (MemoryByIdQuery (idText mid))+lookupMemory space mid =+  runQueryWith+    Nothing+    Eventual+    memoryByIdReadModel+    MemoryByIdQuery {memorySpaceId = space, memoryId = idText mid}  getMemoryRowById ::   (IOE :> es, Store :> es) =>+  MemorySpaceId ->   MemoryId ->   Eff es (Either ReadModelError (Maybe MemoryRow)) getMemoryRowById =@@ -260,43 +506,73 @@  getActiveRowsInNamespace ::   (IOE :> es, Store :> es) =>+  MemorySpaceId ->   Namespace ->   Eff es (Either ReadModelError [MemoryRow])-getActiveRowsInNamespace (Namespace ns) =-  runQueryWith Nothing Eventual memoriesByNamespaceRowsReadModel (MemoriesByNamespaceQuery ns)+getActiveRowsInNamespace space (Namespace ns) =+  runQueryWith+    Nothing+    Eventual+    memoriesByNamespaceRowsReadModel+    MemoriesByNamespaceQuery {memorySpaceId = space, namespace = ns}  getActiveRowsByScope ::   (IOE :> es, Store :> es) =>+  MemorySpaceId ->   MemoryScope ->   Eff es (Either ReadModelError [MemoryRow])-getActiveRowsByScope scope =+getActiveRowsByScope space scope =   runQueryWith     Nothing     Eventual     memoriesByScopeRowsReadModel-    (MemoriesByScopeQuery (scopeNamespaceText scope) (scopeKindText scope) (scopeRefText scope))+    MemoriesByScopeQuery+      { memorySpaceId = space,+        namespace = scopeNamespaceText scope,+        scopeKind = scopeKindText scope,+        scopeRef = scopeRefText scope+      }  getRowsBySession ::   (IOE :> es, Store :> es) =>+  MemorySpaceId ->   SessionId ->   Eff es (Either ReadModelError [MemoryRow])-getRowsBySession sid =-  runQueryWith Nothing Eventual memoriesBySessionRowsReadModel (MemoriesBySessionQuery (idText sid))+getRowsBySession space sid =+  runQueryWith+    Nothing+    Eventual+    memoriesBySessionRowsReadModel+    MemoriesBySessionQuery {memorySpaceId = space, sessionId = idText sid}  getActiveRowsByType ::   (IOE :> es, Store :> es) =>+  MemorySpaceId ->   Namespace ->   MemoryType ->   Eff es (Either ReadModelError [MemoryRow])-getActiveRowsByType (Namespace ns) memoryType =-  runQueryWith Nothing Eventual memoriesByTypeRowsReadModel (MemoriesByTypeQuery ns (memoryTypeToText memoryType))+getActiveRowsByType space (Namespace ns) memoryType =+  runQueryWith+    Nothing+    Eventual+    memoriesByTypeRowsReadModel+    MemoriesByTypeQuery+      { memorySpaceId = space,+        namespace = ns,+        memoryType = memoryTypeToText memoryType+      }  getSupersessionChain ::   (IOE :> es, Store :> es) =>+  MemorySpaceId ->   MemoryId ->   Eff es (Either ReadModelError [MemoryRow])-getSupersessionChain mid =-  runQueryWith Nothing Eventual memorySupersessionChainReadModel (MemorySupersessionChainQuery (idText mid))+getSupersessionChain space mid =+  runQueryWith+    Nothing+    Eventual+    memorySupersessionChainReadModel+    MemorySupersessionChainQuery {memorySpaceId = space, memoryId = idText mid}  runMemoryCommand ::   (IOE :> es, KirokuStoreResource :> es, Store :> es, Error StoreError :> es) =>

@@ -12,6 +12,7 @@     MergeMemoryData (..),     MemoryCommand (..),     commandMemoryId,+    commandMemorySpaceId,     MemoryRecordedData (..),     MemorySupersededData (..),     MemoryArchivedData (..),@@ -20,27 +21,41 @@     MemoryMergedData (..),     MemoryEvent (..),     eventMemoryId,+    eventMemorySpaceId,     memoryTransducer,   ) where +import Data.Aeson.Types (withObject, (.:), (.:?)) import Data.Set (Set)+import Keiki.Builder ((=:)) import Keiki.Builder qualified as B-import Keiki.Core (HsPred, SymTransducer)+import Keiki.Core (HsPred, SymTransducer, (.==)) import Keiki.Generics (emptyRegFile) import Keiki.Generics.TH (deriveAggregate)+import Kioku.Api.Access (MemorySpaceId, PrincipalRef, RecordedPrincipal) import Kioku.Api.Scope (MemoryScope) import Kioku.Api.Types (Confidence, MemoryType) import Kioku.Id (MemoryId, SessionId)+import Kioku.Partition (parsePartitionSpace, parseRecordedActor, parseRecordedActorFromAgent, parseRecordedOwner) import Kioku.Prelude  data MemoryVertex = NotCreated | Active | Superseded | Merged | Archived   deriving stock (Eq, Ord, Show, Enum, Bounded) -type MemoryRegs = '[]+-- | The memory space this aggregate was created in, replayed from its @MemoryRecorded@ event.+--+-- It is aggregate state rather than a read-model lookup because that is what makes the+-- cross-space check survive a concurrency retry: keiro re-runs the edge against the post-conflict+-- state, so a command naming a different space is refused by the state machine itself and never+-- by a racy precheck. A memory is created in exactly one space and never moves.+type MemoryRegs = '[ '("memorySpaceId", MemorySpaceId)]  data RecordMemoryData = RecordMemoryData   { memoryId :: !MemoryId,+    memorySpaceId :: !MemorySpaceId,+    actorPrincipal :: !RecordedPrincipal,+    ownerPrincipal :: !(Maybe PrincipalRef),     agentId :: !Text,     sessionId :: !(Maybe SessionId),     scope :: !MemoryScope,@@ -56,6 +71,8 @@  data SupersedeMemoryData = SupersedeMemoryData   { memoryId :: !MemoryId,+    memorySpaceId :: !MemorySpaceId,+    actorPrincipal :: !RecordedPrincipal,     supersededBy :: !MemoryId,     supersededAt :: !UTCTime   }@@ -63,12 +80,16 @@  data ArchiveMemoryData = ArchiveMemoryData   { memoryId :: !MemoryId,+    memorySpaceId :: !MemorySpaceId,+    actorPrincipal :: !RecordedPrincipal,     archivedAt :: !UTCTime   }   deriving stock (Generic, Eq, Show)  data UpdateMemoryTagsData = UpdateMemoryTagsData   { memoryId :: !MemoryId,+    memorySpaceId :: !MemorySpaceId,+    actorPrincipal :: !RecordedPrincipal,     tags :: !(Set Text),     updatedAt :: !UTCTime   }@@ -76,6 +97,8 @@  data UpdateMemoryConfidenceData = UpdateMemoryConfidenceData   { memoryId :: !MemoryId,+    memorySpaceId :: !MemorySpaceId,+    actorPrincipal :: !RecordedPrincipal,     confidence :: !Confidence,     updatedAt :: !UTCTime   }@@ -83,6 +106,8 @@  data MergeMemoryData = MergeMemoryData   { memoryId :: !MemoryId,+    memorySpaceId :: !MemorySpaceId,+    actorPrincipal :: !RecordedPrincipal,     mergedInto :: !MemoryId,     mergedAt :: !UTCTime   }@@ -106,8 +131,27 @@   UpdateMemoryConfidence d -> d.memoryId   MergeMemory d -> d.memoryId +-- | The memory space a command claims to act in. Every command names one; the aggregate refuses+-- any that disagrees with the space the memory was created in.+commandMemorySpaceId :: MemoryCommand -> MemorySpaceId+commandMemorySpaceId = \case+  RecordMemory d -> d.memorySpaceId+  SupersedeMemory d -> d.memorySpaceId+  ArchiveMemory d -> d.memorySpaceId+  UpdateMemoryTags d -> d.memorySpaceId+  UpdateMemoryConfidence d -> d.memorySpaceId+  MergeMemory d -> d.memorySpaceId++-- | The @FromJSON@ instances below are hand-written for one reason: every payload already on+-- disk was written before memory spaces existed, and it has to keep decoding. 'Kioku.Partition'+-- owns what an older payload means; these instances only say which rule applies to which event.+--+-- @ToJSON@ stays derived, so encoding only ever emits the new form. data MemoryRecordedData = MemoryRecordedData   { memoryId :: !MemoryId,+    memorySpaceId :: !MemorySpaceId,+    actorPrincipal :: !RecordedPrincipal,+    ownerPrincipal :: !(Maybe PrincipalRef),     agentId :: !Text,     sessionId :: !(Maybe SessionId),     scope :: !MemoryScope,@@ -120,47 +164,127 @@     recordedAt :: !UTCTime   }   deriving stock (Generic, Eq, Show)-  deriving anyclass (FromJSON, ToJSON)+  deriving anyclass (ToJSON) +-- | The one memory event that carried an agent label, so the one whose legacy actor is a real+-- value rather than "unrecorded".+instance FromJSON MemoryRecordedData where+  parseJSON =+    withObject "MemoryRecordedData" \o ->+      MemoryRecordedData+        <$> o .: "memoryId"+        <*> parsePartitionSpace o+        <*> parseRecordedActorFromAgent o+        <*> parseRecordedOwner o+        <*> o .: "agentId"+        <*> o .:? "sessionId"+        <*> o .: "scope"+        <*> o .: "memoryType"+        <*> o .: "content"+        <*> o .: "priority"+        <*> o .: "confidence"+        <*> o .: "tags"+        <*> o .:? "supersedes"+        <*> o .: "recordedAt"+ data MemorySupersededData = MemorySupersededData   { memoryId :: !MemoryId,+    memorySpaceId :: !MemorySpaceId,+    actorPrincipal :: !RecordedPrincipal,     supersededBy :: !MemoryId,     supersededAt :: !UTCTime   }   deriving stock (Generic, Eq, Show)-  deriving anyclass (FromJSON, ToJSON)+  deriving anyclass (ToJSON) +instance FromJSON MemorySupersededData where+  parseJSON =+    withObject "MemorySupersededData" \o ->+      MemorySupersededData+        <$> o .: "memoryId"+        <*> parsePartitionSpace o+        <*> parseRecordedActor o+        <*> o .: "supersededBy"+        <*> o .: "supersededAt"+ data MemoryArchivedData = MemoryArchivedData   { memoryId :: !MemoryId,+    memorySpaceId :: !MemorySpaceId,+    actorPrincipal :: !RecordedPrincipal,     archivedAt :: !UTCTime   }   deriving stock (Generic, Eq, Show)-  deriving anyclass (FromJSON, ToJSON)+  deriving anyclass (ToJSON) +instance FromJSON MemoryArchivedData where+  parseJSON =+    withObject "MemoryArchivedData" \o ->+      MemoryArchivedData+        <$> o .: "memoryId"+        <*> parsePartitionSpace o+        <*> parseRecordedActor o+        <*> o .: "archivedAt"+ data MemoryTagsUpdatedData = MemoryTagsUpdatedData   { memoryId :: !MemoryId,+    memorySpaceId :: !MemorySpaceId,+    actorPrincipal :: !RecordedPrincipal,     tags :: !(Set Text),     updatedAt :: !UTCTime   }   deriving stock (Generic, Eq, Show)-  deriving anyclass (FromJSON, ToJSON)+  deriving anyclass (ToJSON) +instance FromJSON MemoryTagsUpdatedData where+  parseJSON =+    withObject "MemoryTagsUpdatedData" \o ->+      MemoryTagsUpdatedData+        <$> o .: "memoryId"+        <*> parsePartitionSpace o+        <*> parseRecordedActor o+        <*> o .: "tags"+        <*> o .: "updatedAt"+ data MemoryConfidenceUpdatedData = MemoryConfidenceUpdatedData   { memoryId :: !MemoryId,+    memorySpaceId :: !MemorySpaceId,+    actorPrincipal :: !RecordedPrincipal,     confidence :: !Confidence,     updatedAt :: !UTCTime   }   deriving stock (Generic, Eq, Show)-  deriving anyclass (FromJSON, ToJSON)+  deriving anyclass (ToJSON) +instance FromJSON MemoryConfidenceUpdatedData where+  parseJSON =+    withObject "MemoryConfidenceUpdatedData" \o ->+      MemoryConfidenceUpdatedData+        <$> o .: "memoryId"+        <*> parsePartitionSpace o+        <*> parseRecordedActor o+        <*> o .: "confidence"+        <*> o .: "updatedAt"+ data MemoryMergedData = MemoryMergedData   { memoryId :: !MemoryId,+    memorySpaceId :: !MemorySpaceId,+    actorPrincipal :: !RecordedPrincipal,     mergedInto :: !MemoryId,     mergedAt :: !UTCTime   }   deriving stock (Generic, Eq, Show)-  deriving anyclass (FromJSON, ToJSON)+  deriving anyclass (ToJSON) +instance FromJSON MemoryMergedData where+  parseJSON =+    withObject "MemoryMergedData" \o ->+      MemoryMergedData+        <$> o .: "memoryId"+        <*> parsePartitionSpace o+        <*> parseRecordedActor o+        <*> o .: "mergedInto"+        <*> o .: "mergedAt"+ data MemoryEvent   = MemoryRecorded !MemoryRecordedData   | MemorySuperseded !MemorySupersededData@@ -185,6 +309,17 @@   MemoryConfidenceUpdated d -> d.memoryId   MemoryMerged d -> d.memoryId +-- | The memory space a stored event belongs to. Every event carries one, including every event+-- written before memory spaces existed: those decode into 'legacyMemorySpaceId'.+eventMemorySpaceId :: MemoryEvent -> MemorySpaceId+eventMemorySpaceId = \case+  MemoryRecorded d -> d.memorySpaceId+  MemorySuperseded d -> d.memorySpaceId+  MemoryArchived d -> d.memorySpaceId+  MemoryTagsUpdated d -> d.memorySpaceId+  MemoryConfidenceUpdated d -> d.memorySpaceId+  MemoryMerged d -> d.memorySpaceId+ $(deriveAggregate ''MemoryCommand ''MemoryRegs ''MemoryEvent)  memoryTransducer ::@@ -198,10 +333,16 @@   B.buildTransducer NotCreated emptyRegFile isTerminal do     B.from NotCreated do       B.onCmd inCtorRecordMemory $ \d -> B.do+        -- 'emptyRegFile' binds the slot to a deferred error, so this edge -- the only way into+        -- Active, and thus the only way to reach any guard below -- must initialize it.+        B.slot @"memorySpaceId" =: d.memorySpaceId         B.emit           wireMemoryRecorded           MemoryRecordedTermFields             { memoryId = d.memoryId,+              memorySpaceId = d.memorySpaceId,+              actorPrincipal = d.actorPrincipal,+              ownerPrincipal = d.ownerPrincipal,               agentId = d.agentId,               sessionId = d.sessionId,               scope = d.scope,@@ -216,50 +357,69 @@         B.goto Active      B.from Active do+      -- Every edge below repeats the same guard: the command must name the space this memory+      -- was created in. A caller holding a context for one space cannot supersede, archive,+      -- retag, re-score, or merge a memory that lives in another, and the refusal comes from the+      -- state machine rather than from a read-model precheck that a concurrent write could stale.       B.onCmd inCtorSupersedeMemory $ \d -> B.do+        B.requireGuard (d.memorySpaceId .== B.reg @"memorySpaceId")         B.emit           wireMemorySuperseded           MemorySupersededTermFields             { memoryId = d.memoryId,+              memorySpaceId = d.memorySpaceId,+              actorPrincipal = d.actorPrincipal,               supersededBy = d.supersededBy,               supersededAt = d.supersededAt             }         B.goto Superseded        B.onCmd inCtorArchiveMemory $ \d -> B.do+        B.requireGuard (d.memorySpaceId .== B.reg @"memorySpaceId")         B.emit           wireMemoryArchived           MemoryArchivedTermFields             { memoryId = d.memoryId,+              memorySpaceId = d.memorySpaceId,+              actorPrincipal = d.actorPrincipal,               archivedAt = d.archivedAt             }         B.goto Archived        B.onCmd inCtorUpdateMemoryTags $ \d -> B.do+        B.requireGuard (d.memorySpaceId .== B.reg @"memorySpaceId")         B.emit           wireMemoryTagsUpdated           MemoryTagsUpdatedTermFields             { memoryId = d.memoryId,+              memorySpaceId = d.memorySpaceId,+              actorPrincipal = d.actorPrincipal,               tags = d.tags,               updatedAt = d.updatedAt             }         B.goto Active        B.onCmd inCtorUpdateMemoryConfidence $ \d -> B.do+        B.requireGuard (d.memorySpaceId .== B.reg @"memorySpaceId")         B.emit           wireMemoryConfidenceUpdated           MemoryConfidenceUpdatedTermFields             { memoryId = d.memoryId,+              memorySpaceId = d.memorySpaceId,+              actorPrincipal = d.actorPrincipal,               confidence = d.confidence,               updatedAt = d.updatedAt             }         B.goto Active        B.onCmd inCtorMergeMemory $ \d -> B.do+        B.requireGuard (d.memorySpaceId .== B.reg @"memorySpaceId")         B.emit           wireMemoryMerged           MemoryMergedTermFields             { memoryId = d.memoryId,+              memorySpaceId = d.memorySpaceId,+              actorPrincipal = d.actorPrincipal,               mergedInto = d.mergedInto,               mergedAt = d.mergedAt             }

@@ -1,6 +1,32 @@+-- | The embedding worker: it computes a vector for each memory's content and writes it back onto+-- the same row.+--+-- Like the distillation timers, this worker discovers its own work, so it cannot arrive holding+-- an authorization context. It takes the memory space out of the delivered @MemoryRecorded@+-- event and asks a 'MemoryContextProvider' for a decision about /that/ space; a refusal+-- dead-letters, because a worker that is not allowed to embed a space is a configuration fact+-- and retrying it every second would hide it.+--+-- Three things then carry the partition, and each closes a different hole:+--+-- * the state read returns the row's /own/ space, and a disagreement with the envelope is+--   'EmbedSpaceMismatch' — dead-lettered, never mutated. Scoping that read by the envelope's+--   space instead would turn the disagreement into "no such memory", which acks as a success;+-- * the update names the space as well as the id, so a redelivery cannot enrich a row outside+--   the space its event named however stale the envelope has become;+-- * the backfill scan takes an 'EmbeddingBackfillScope', so an operator can run the pass for one+--   space rather than for every space in the database.+--+-- None of this is an authorization boundary in the sense recall is: a memory's embedding is a+-- property of the memory, no content reaches a caller, and a process holding the database+-- credentials may already act in any space in that database — which is what+-- 'Kioku.Api.Access.assumeAuthorizedContextProvider' says out loud. It is a /durable work+-- identity/ boundary: at-least-once delivery means the same envelope is handled repeatedly, and+-- every one of those attempts must land in the space the event named. module Kioku.Memory.Embedding.Worker   ( EmbeddingWorkerEnv (..),     EmbedOutcome (..),+    EmbeddingBackfillScope (..),     backfillMissingEmbeddings,     embeddingHandler,     embeddingWorkerProcessor,@@ -26,10 +52,20 @@ import Hasql.Statement (Statement, preparable) import Hasql.Transaction qualified as Tx import Keiro.Codec (decodeRecorded)+import Kioku.Api.Access+  ( MemoryContextProvider (..),+    MemoryPermission (..),+    MemorySpaceId,+    memoryContextAllows,+    memoryContextSpace,+    memorySpaceIdText,+  )+import Kioku.Database.Schema (memoriesTable) import Kioku.Id (MemoryId, idText) import Kioku.Memory.Domain (MemoryEvent (..), MemoryRecordedData (..)) import Kioku.Memory.Embedding (EmbedError, embedWithRetry, sha256Hex) import Kioku.Memory.EventStream (memoryCodec)+import Kioku.Partition (memorySpaceColumn, memorySpaceParam) import Kioku.Prelude import Kioku.Recall.Capability (VectorCapability (..)) import Kioku.Worker.Failure (embeddingRetryDelay, isTransientStoreError)@@ -56,7 +92,8 @@ import System.IO qualified as IO  data EmbeddingCandidate = EmbeddingCandidate-  { memoryId :: !Text,+  { memorySpaceId :: !MemorySpaceId,+    memoryId :: !Text,     content :: !Text,     contentHash :: !(Maybe Text),     hasEmbedding :: !Bool@@ -64,7 +101,8 @@   deriving stock (Generic, Eq, Show)  data EmbeddingUpdate = EmbeddingUpdate-  { memoryId :: !Text,+  { memorySpaceId :: !MemorySpaceId,+    memoryId :: !Text,     embedding :: !(Vector Double),     embeddingModel :: !Text,     dimensions :: !Int,@@ -72,12 +110,28 @@   }   deriving stock (Generic, Eq, Show) +-- | What the row itself says, including which space it is in.+--+-- The space is read back rather than asserted because that is the only way the handler can tell+-- a stale envelope from a missing memory. See 'EmbedSpaceMismatch'. data EmbeddingState = EmbeddingState-  { contentHash :: !(Maybe Text),+  { memorySpaceId :: !MemorySpaceId,+    contentHash :: !(Maybe Text),     hasEmbedding :: !Bool   }   deriving stock (Generic, Eq, Show) +-- | Which memory spaces one backfill pass covers.+--+-- 'BackfillEverySpace' is what the continuous worker runs at startup: it serves every space the+-- database holds, so recovering embeddings for only one of them would leave the rest silently+-- unsearchable. 'BackfillOneSpace' is for an operator repairing a single tenant, and for the+-- case where a pass over every space would be too large to finish.+data EmbeddingBackfillScope+  = BackfillEverySpace+  | BackfillOneSpace !MemorySpaceId+  deriving stock (Generic, Eq, Show)+ -- | Everything the embedding path needs from the outside world. -- -- The provider call is a field rather than a direct 'embedWithRetry' call so@@ -104,21 +158,28 @@ -- "the memory is not there to embed"; neither is a failure. The distinction -- that matters to the handler is 'EmbedFailed', which used to be indistinguishable -- from success.+--+-- 'EmbedSpaceMismatch' is the one outcome that must never be quiet. It means a delivered event+-- named one memory space and the row it names is in another, which is a forged or corrupt+-- envelope rather than an ordinary failure — no retry can fix it and nothing was written. It+-- carries the envelope's space first and the row's second. data EmbedOutcome   = EmbedSkipped   | EmbedStored   | EmbedFailed !EmbedError+  | EmbedSpaceMismatch !MemorySpaceId !MemorySpaceId   deriving stock (Generic, Eq, Show)  runEmbeddingWorkerHost ::   (IOE :> es, Store :> es, Error StoreError :> es, Tracing :> es) =>   KirokuStore ->+  MemoryContextProvider (Eff es) ->   VectorCapability ->   EmbeddingModel ->   Int ->   Eff es ()-runEmbeddingWorkerHost store capability model dims = do-  processor <- embeddingWorkerProcessor capability model dims store+runEmbeddingWorkerHost store contexts capability model dims = do+  processor <- embeddingWorkerProcessor contexts capability model dims store   started <- runApp defaultAppConfig [processor]   case started of     Left appErr ->@@ -129,12 +190,13 @@  embeddingWorkerProcessor ::   (IOE :> es, Store :> es, Error StoreError :> es) =>+  MemoryContextProvider (Eff es) ->   VectorCapability ->   EmbeddingModel ->   Int ->   KirokuStore ->   Eff es (ProcessorId, QueueProcessor es)-embeddingWorkerProcessor capability model dims store = do+embeddingWorkerProcessor contexts capability model dims store = do   adapter <- kirokuAdapter store embeddingAdapterConfig   pure     ( ProcessorId embeddingWorkerName,@@ -143,7 +205,7 @@           -- The kiroku bridge is ack-coupled: a synchronous exception escaping           -- the handler leaves the ack unfinalized and blocks the subscription           -- worker forever. The guard turns that into a one-second retry.-          handler = guardKirokuHandler (embeddingMessageHandler capability (mkEmbeddingWorkerEnv model dims)),+          handler = guardKirokuHandler (embeddingMessageHandler contexts capability (mkEmbeddingWorkerEnv model dims)),           ordering = StrictInOrder,           concurrency = Serial         }@@ -161,31 +223,40 @@ -- * a permanent store error (a dimension mismatch, a broken schema) would fail --   identically for every subsequent event — halting is the honest response, --   because dead-lettering would quietly drain the whole stream.+--+-- Two branches are about the partition rather than about durability. A provider that refuses+-- this event's memory space dead-letters, matching 'Kioku.Distill.Timer.Worker.fireL1Timer': a+-- worker that may not embed a space is a configuration fact, and an operator requeues the+-- dead-letter row once it is fixed. An envelope whose space disagrees with the row's own space+-- dead-letters too, and writes nothing. embeddingHandler ::   (IOE :> es, Store :> es, Error StoreError :> es) =>+  MemoryContextProvider (Eff es) ->   VectorCapability ->   EmbeddingWorkerEnv ->   Ingested es RecordedEvent ->   Eff es AckDecision-embeddingHandler capability env ingested =-  handleEmbeddingEnvelope capability env ingested.envelope+embeddingHandler contexts capability env ingested =+  handleEmbeddingEnvelope contexts capability env ingested.envelope  embeddingMessageHandler ::   (IOE :> es, Store :> es, Error StoreError :> es) =>+  MemoryContextProvider (Eff es) ->   VectorCapability ->   EmbeddingWorkerEnv ->   Message es RecordedEvent ->   Eff es AckDecision-embeddingMessageHandler capability env message =-  handleEmbeddingEnvelope capability env message.envelope+embeddingMessageHandler contexts capability env message =+  handleEmbeddingEnvelope contexts capability env message.envelope  handleEmbeddingEnvelope ::   (IOE :> es, Store :> es, Error StoreError :> es) =>+  MemoryContextProvider (Eff es) ->   VectorCapability ->   EmbeddingWorkerEnv ->   Envelope RecordedEvent ->   Eff es AckDecision-handleEmbeddingEnvelope capability env envelope =+handleEmbeddingEnvelope contexts capability env envelope =   EffError.catchError @StoreError run \_callStack storeErr ->     if isTransientStoreError storeErr       then do@@ -203,13 +274,48 @@           logWorker ("undecodable event, dead-lettering: " <> Text.pack (show codecErr))           pure (AckDeadLetter (InvalidPayload (Text.pack (show codecErr))))         Right (MemoryRecorded d) -> do-          outcome <- embedMemoryContent capability env (idText (d.memoryId :: MemoryId)) d.content-          case outcome of-            EmbedFailed err -> do-              logWorker ("embedding failed, retrying: " <> Text.pack (show err))-              pure (AckRetry retryDelay)-            EmbedStored -> pure AckOk-            EmbedSkipped -> pure AckOk+          decision <- contexts.contextForSpace d.memorySpaceId+          case decision of+            Left denial -> do+              let reason =+                    "not authorized to embed memory space "+                      <> memorySpaceIdText d.memorySpaceId+                      <> ": "+                      <> Text.pack (show denial)+              logWorker ("dead-lettering: " <> reason)+              pure (AckDeadLetter (InvalidPayload reason))+            Right context+              | not (memoryContextAllows MemoryDistill context) -> do+                  let reason =+                        "context for memory space "+                          <> memorySpaceIdText d.memorySpaceId+                          <> " does not grant distill"+                  logWorker ("dead-lettering: " <> reason)+                  pure (AckDeadLetter (InvalidPayload reason))+              | otherwise -> do+                  outcome <-+                    embedMemoryContent+                      capability+                      env+                      (memoryContextSpace context)+                      (idText (d.memoryId :: MemoryId))+                      d.content+                  case outcome of+                    EmbedFailed err -> do+                      logWorker ("embedding failed, retrying: " <> Text.pack (show err))+                      pure (AckRetry retryDelay)+                    EmbedSpaceMismatch expected actual -> do+                      let reason =+                            "event claims memory space "+                              <> memorySpaceIdText expected+                              <> " but memory "+                              <> idText (d.memoryId :: MemoryId)+                              <> " is in "+                              <> memorySpaceIdText actual+                      logWorker ("dead-lettering: " <> reason)+                      pure (AckDeadLetter (InvalidPayload reason))+                    EmbedStored -> pure AckOk+                    EmbedSkipped -> pure AckOk         -- The subscription is filtered to MemoryRecorded, so this is unreachable         -- today; acking is the harmless answer if the filter ever widens.         Right _ -> pure AckOk@@ -218,23 +324,35 @@ logWorker msg =   liftIO (IO.hPutStrLn IO.stderr (Text.unpack (embeddingWorkerName <> ": " <> msg))) +-- | Embed every active memory that is missing a current vector, in one space or in all of them.+--+-- A candidate carries the space it was read from, so the update writes back into that same+-- space. There is no mismatch branch here and there cannot be one: unlike the subscription+-- handler, this pass has no envelope to disagree with the row.+-- It takes a whole 'EmbeddingWorkerEnv' rather than a model and a dimension count, for the+-- reason that record exists: a test can drive the pass with a fake provider, which is the only+-- way to assert /which rows/ a scope selected without an embedding API key and a network. backfillMissingEmbeddings ::   (IOE :> es, Store :> es) =>   VectorCapability ->-  EmbeddingModel ->-  Int ->+  EmbeddingWorkerEnv ->+  EmbeddingBackfillScope ->   Eff es Int-backfillMissingEmbeddings VectorAvailable model dims = do-  candidates <- runTransaction (Tx.statement () selectEmbeddingCandidatesStmt)+backfillMissingEmbeddings VectorAvailable env scope = do+  candidates <- runTransaction candidateQuery   foldM embedCandidate 0 candidates   where-    env = mkEmbeddingWorkerEnv model dims+    candidateQuery =+      case scope of+        BackfillEverySpace -> Tx.statement () selectEmbeddingCandidatesStmt+        BackfillOneSpace space -> Tx.statement space selectEmbeddingCandidatesInSpaceStmt      embedCandidate count candidate       | shouldSkipEmbedding candidate.hasEmbedding candidate.contentHash contentHash =           pure count       | otherwise = do-          outcome <- embedAndStore env candidate.memoryId candidate.content contentHash+          outcome <-+            embedAndStore env candidate.memorySpaceId candidate.memoryId candidate.content contentHash           case outcome of             EmbedStored -> pure (count + 1)             EmbedSkipped -> pure count@@ -243,29 +361,49 @@             EmbedFailed err -> do               logWorker ("backfill skipped " <> candidate.memoryId <> ": " <> Text.pack (show err))               pure count+            -- Unreachable: the candidate's space came from the row being updated.+            EmbedSpaceMismatch expected actual -> do+              logWorker+                ( "backfill skipped "+                    <> candidate.memoryId+                    <> ": read in "+                    <> memorySpaceIdText expected+                    <> " but now in "+                    <> memorySpaceIdText actual+                )+              pure count       where         contentHash = sha256Hex candidate.content backfillMissingEmbeddings _ _ _ = pure 0 +-- | Embed one memory, refusing to touch it if it is not in the space the caller named.+--+-- The state read is keyed by the memory id alone, which is globally unique, and returns the+-- row's own space. That is deliberate and is the opposite of a leak: reading the space in order+-- to compare it is what makes a disagreement loud. Scoping the read by @space AND id@ would+-- report a memory in another space as absent, and absent is an ack. embedMemoryContent ::   (IOE :> es, Store :> es) =>   VectorCapability ->   EmbeddingWorkerEnv ->+  MemorySpaceId ->   Text ->   Text ->   Eff es EmbedOutcome-embedMemoryContent VectorAvailable env memoryId content = do+embedMemoryContent VectorAvailable env memorySpaceId memoryId content = do   existing <- runTransaction (Tx.statement memoryId selectEmbeddingStateStmt)   case existing of     Nothing -> pure EmbedSkipped     Just state+      | state.memorySpaceId /= memorySpaceId ->+          pure (EmbedSpaceMismatch memorySpaceId state.memorySpaceId)       | shouldSkipEmbedding state.hasEmbedding state.contentHash contentHash ->           pure EmbedSkipped       | otherwise ->-          embedAndStore env memoryId content contentHash+          embedAndStore env memorySpaceId memoryId content contentHash   where     contentHash = sha256Hex content-embedMemoryContent _ _ _ _ = pure EmbedSkipped+embedMemoryContent _ _ _ _ _ = pure EmbedSkipped  shouldSkipEmbedding :: Bool -> Maybe Text -> Text -> Bool shouldSkipEmbedding hasEmbedding storedContentHash contentHash =@@ -274,11 +412,12 @@ embedAndStore ::   (IOE :> es, Store :> es) =>   EmbeddingWorkerEnv ->+  MemorySpaceId ->   Text ->   Text ->   Text ->   Eff es EmbedOutcome-embedAndStore env memoryId content contentHash = do+embedAndStore env memorySpaceId memoryId content contentHash = do   result <- liftIO (env.embed content)   case result of     Left err -> pure (EmbedFailed err)@@ -286,7 +425,8 @@       runTransaction $         Tx.statement           EmbeddingUpdate-            { memoryId,+            { memorySpaceId,+              memoryId,               embedding,               embeddingModel = env.model.modelId,               dimensions = env.dimensions,@@ -298,57 +438,105 @@ selectEmbeddingCandidatesStmt :: Statement () [EmbeddingCandidate] selectEmbeddingCandidatesStmt =   preparable-    """-    SELECT memory_id, content, content_hash, embedding IS NOT NULL AS has_embedding-    FROM kiroku.kioku_memories-    WHERE status = 'active'-    ORDER BY created_at ASC-    """+    ( """+      SELECT memory_space_id, memory_id, content, content_hash, embedding IS NOT NULL AS has_embedding+      FROM+      """+        <> " "+        <> memoriesTable+        <> " "+        <> """+           WHERE status = 'active'+           ORDER BY created_at ASC+           """+    )     E.noParams     (D.rowList embeddingCandidateDecoder) +-- | The same scan bounded to one space, so an operator can repair one tenant.+--+-- @memory_space_id@ leads @kioku_memories_space_namespace_idx@, but this predicate carries no+-- namespace and orders by @created_at@, so the planner is free to prefer a scan. That is+-- correct: a backfill visits every unembedded row in the space by definition, and the point of+-- the predicate here is which rows are eligible, not how they are reached.+selectEmbeddingCandidatesInSpaceStmt :: Statement MemorySpaceId [EmbeddingCandidate]+selectEmbeddingCandidatesInSpaceStmt =+  preparable+    ( """+      SELECT memory_space_id, memory_id, content, content_hash, embedding IS NOT NULL AS has_embedding+      FROM+      """+        <> " "+        <> memoriesTable+        <> " "+        <> """+           WHERE status = 'active' AND memory_space_id = $1+           ORDER BY created_at ASC+           """+    )+    memorySpaceParam+    (D.rowList embeddingCandidateDecoder)+ selectEmbeddingStateStmt :: Statement Text (Maybe EmbeddingState) selectEmbeddingStateStmt =   preparable-    """-    SELECT content_hash, embedding IS NOT NULL AS has_embedding-    FROM kiroku.kioku_memories-    WHERE memory_id = $1 AND status = 'active'-    """+    ( """+      SELECT memory_space_id, content_hash, embedding IS NOT NULL AS has_embedding+      FROM+      """+        <> " "+        <> memoriesTable+        <> " "+        <> """+           WHERE memory_id = $1 AND status = 'active'+           """+    )     (E.param (E.nonNullable E.text))     (D.rowMaybe embeddingStateDecoder)  embeddingCandidateDecoder :: D.Row EmbeddingCandidate embeddingCandidateDecoder =   EmbeddingCandidate-    <$> D.column (D.nonNullable D.text)+    <$> memorySpaceColumn     <*> D.column (D.nonNullable D.text)+    <*> D.column (D.nonNullable D.text)     <*> D.column (D.nullable D.text)     <*> D.column (D.nonNullable D.bool)  embeddingStateDecoder :: D.Row EmbeddingState embeddingStateDecoder =   EmbeddingState-    <$> D.column (D.nullable D.text)+    <$> memorySpaceColumn+    <*> D.column (D.nullable D.text)     <*> D.column (D.nonNullable D.bool) +-- | The write names the space as well as the id.+--+-- 'embedMemoryContent' has already compared the two, so this predicate can never be the thing+-- that rejects a row — but the comparison and the write are two statements, and between them a+-- memory could in principle be rewritten into another space. The predicate is what makes the+-- write itself, rather than a check that preceded it, the thing that is partition-safe. upsertEmbeddingStmt :: Statement EmbeddingUpdate () upsertEmbeddingStmt =   preparable-    """-    UPDATE kiroku.kioku_memories-    SET embedding = $2::vector,-        embedding_model = $3,-        dimensions = $4,-        content_hash = $5-    WHERE memory_id = $1-    """+    ( "UPDATE "+        <> memoriesTable+        <> "\n"+        <> """+           SET embedding = $3::vector,+               embedding_model = $4,+               dimensions = $5,+               content_hash = $6+           WHERE memory_space_id = $1 AND memory_id = $2+           """+    )     embeddingUpdateEncoder     D.noResult  embeddingUpdateEncoder :: E.Params EmbeddingUpdate embeddingUpdateEncoder =-  ((\update -> update.memoryId) >$< E.param (E.nonNullable E.text))+  ((\update -> update.memorySpaceId) >$< memorySpaceParam)+    <> ((\update -> update.memoryId) >$< E.param (E.nonNullable E.text))     <> ((\update -> vectorLiteral update.embedding) >$< E.param (E.nonNullable E.text))     <> ((\update -> update.embeddingModel) >$< E.param (E.nonNullable E.text))     <> ((\update -> fromIntegral @Int @Int32 update.dimensions) >$< E.param (E.nonNullable E.int4))

@@ -17,6 +17,7 @@ import Keiro.EventStream.Validate (ValidatedEventStream, mkEventStreamOrThrow) import Keiro.Stream (Stream) import Keiro.Stream qualified as Stream+import Kioku.Api.Access (RecordedPrincipal (..), legacyMemorySpaceId, legacyPrincipalRef) import Kioku.Api.Scope (MemoryScope (..), Namespace (..), ScopeKind (..)) import Kioku.Id (MemoryId, SessionId, idText, parseIdLenient) import Kioku.Memory.Domain@@ -92,18 +93,26 @@       "agent_memory_confidence_updated" -> MemoryConfidenceUpdated <$> parseLegacyMemoryConfidenceUpdated payload       other -> fail ("Unknown Rei AgentMemoryEvent tag: " <> Text.unpack other) +-- | Rei payloads predate memory spaces by even more than Kioku's own older events do, so they+-- take the same two rules: the legacy space, and the legacy agent label kept verbatim. Rei's+-- @agentId@ is exactly the free-text label 'LegacyPrincipal' exists to mark. parseLegacyMemoryRecorded :: Value -> Parser MemoryRecordedData parseLegacyMemoryRecorded =   withObject "Rei AgentMemoryRecordedData" $ \o -> do     memoryId <- parseLegacyMemoryId =<< o .: "memoryId"+    agentId <- o .: "agentId"     sessionId <- traverse parseLegacySessionId =<< o .:? "sessionId"     scope <- parseLegacyAnchor =<< o .: "anchor"     supersedes <- traverse parseLegacyMemoryId =<< o .:? "supersedes"-    MemoryRecordedData memoryId-      <$> o .: "agentId"-      <*> pure sessionId-      <*> pure scope-      <*> o .: "memoryType"+    MemoryRecordedData+      memoryId+      legacyMemorySpaceId+      (LegacyPrincipal (legacyPrincipalRef agentId))+      Nothing+      agentId+      sessionId+      scope+      <$> o .: "memoryType"       <*> o .: "content"       <*> pure 100       <*> o .: "confidence"@@ -116,6 +125,8 @@   withObject "Rei AgentMemorySupersededData" $ \o ->     MemorySupersededData       <$> (parseLegacyMemoryId =<< o .: "memoryId")+      <*> pure legacyMemorySpaceId+      <*> pure UnattributedPrincipal       <*> (parseLegacyMemoryId =<< o .: "supersededBy")       <*> o .: "supersededAt" @@ -124,6 +135,8 @@   withObject "Rei AgentMemoryArchivedData" $ \o ->     MemoryArchivedData       <$> (parseLegacyMemoryId =<< o .: "memoryId")+      <*> pure legacyMemorySpaceId+      <*> pure UnattributedPrincipal       <*> o .: "archivedAt"  parseLegacyMemoryTagsUpdated :: Value -> Parser MemoryTagsUpdatedData@@ -131,6 +144,8 @@   withObject "Rei AgentMemoryTagsUpdatedData" $ \o ->     MemoryTagsUpdatedData       <$> (parseLegacyMemoryId =<< o .: "memoryId")+      <*> pure legacyMemorySpaceId+      <*> pure UnattributedPrincipal       <*> o .: "tags"       <*> o .: "updatedAt" @@ -139,6 +154,8 @@   withObject "Rei AgentMemoryConfidenceUpdatedData" $ \o ->     MemoryConfidenceUpdatedData       <$> (parseLegacyMemoryId =<< o .: "memoryId")+      <*> pure legacyMemorySpaceId+      <*> pure UnattributedPrincipal       <*> o .: "confidence"       <*> o .: "updatedAt" 

@@ -1,3 +1,10 @@+-- | The @kioku.memories@ projection and every query over it.+--+-- Every row belongs to exactly one memory space, and every statement below names that space+-- first. The predicate is not redundant with the primary key even though @memory_id@ is+-- globally unique: it is what stops a caller holding a leaked id from reading, or a projection+-- from writing, outside the space it was authorized for, and it makes the partition visible in+-- every query a reviewer reads. module Kioku.Memory.ReadModel   ( memoryInlineProjection,     MemoryRow (..),@@ -20,7 +27,6 @@   ) where -import Contravariant.Extras (contrazip2, contrazip3) import Data.Aeson qualified as Aeson import Data.ByteString.Lazy qualified as BL import Data.Functor.Contravariant ((>$<))@@ -35,15 +41,19 @@ import Hasql.Transaction qualified as Tx import Keiro.Projection (InlineProjection (..)) import Keiro.ReadModel (ConsistencyMode (..), ReadModel (..), StrongScope (..))+import Kioku.Api.Access (MemorySpaceId) import Kioku.Api.Scope (scopeFromColumns, scopeKindText, scopeNamespaceText, scopeRefText) import Kioku.Api.Types (MemoryRecord (..), confidenceToText, memoryTypeToText)+import Kioku.Database.Schema (kiokuSchema, memoriesRelation, memoriesTable) import Kioku.Id (idText) import Kioku.Memory.Domain+import Kioku.Partition (memorySpaceColumn, memorySpaceParam) import Kioku.Prelude import Kiroku.Store.Types (RecordedEvent)  data MemoryRow = MemoryRow-  { memoryId :: !Text,+  { memorySpaceId :: !MemorySpaceId,+    memoryId :: !Text,     agentId :: !Text,     sessionId :: !(Maybe Text),     namespace :: !Text,@@ -62,17 +72,40 @@   }   deriving stock (Generic, Eq, Show) -newtype MemoryByIdQuery = MemoryByIdQuery Text+-- | Every query names its memory space in a field rather than a tuple position, so a call site+-- cannot transpose the partition with the namespace it happens to sit beside.+data MemoryByIdQuery = MemoryByIdQuery+  { memorySpaceId :: !MemorySpaceId,+    memoryId :: !Text+  } -newtype MemoriesByNamespaceQuery = MemoriesByNamespaceQuery Text+data MemoriesByNamespaceQuery = MemoriesByNamespaceQuery+  { memorySpaceId :: !MemorySpaceId,+    namespace :: !Text+  } -data MemoriesByScopeQuery = MemoriesByScopeQuery Text (Maybe Text) (Maybe Text)+data MemoriesByScopeQuery = MemoriesByScopeQuery+  { memorySpaceId :: !MemorySpaceId,+    namespace :: !Text,+    scopeKind :: !(Maybe Text),+    scopeRef :: !(Maybe Text)+  } -newtype MemoriesBySessionQuery = MemoriesBySessionQuery Text+data MemoriesBySessionQuery = MemoriesBySessionQuery+  { memorySpaceId :: !MemorySpaceId,+    sessionId :: !Text+  } -data MemoriesByTypeQuery = MemoriesByTypeQuery Text Text+data MemoriesByTypeQuery = MemoriesByTypeQuery+  { memorySpaceId :: !MemorySpaceId,+    namespace :: !Text,+    memoryType :: !Text+  } -newtype MemorySupersessionChainQuery = MemorySupersessionChainQuery Text+data MemorySupersessionChainQuery = MemorySupersessionChainQuery+  { memorySpaceId :: !MemorySpaceId,+    memoryId :: !Text+  }  memoryInlineProjection :: InlineProjection MemoryEvent memoryInlineProjection =@@ -81,27 +114,63 @@       apply = applyMemoryEvent     } +-- | Project one memory event.+--+-- Each non-recording event carries the memory space its aggregate is pinned to, and the update+-- statements below match on it as well as on the id. That is not defensive noise: the aggregate+-- refuses a command naming the wrong space, so a mismatch here can only mean the projection and+-- the event stream disagree, and quietly rewriting a row in another space is the one outcome+-- worse than writing nothing. applyMemoryEvent :: MemoryEvent -> RecordedEvent -> Tx.Transaction () applyMemoryEvent event _recorded =   case event of     MemoryRecorded d -> Tx.statement (recordedRow d) upsertMemoryStmt     MemorySuperseded d ->       Tx.statement-        (idText d.memoryId, idText d.supersededBy, d.supersededAt)+        (MemoryStatusChange d.memorySpaceId (idText d.memoryId) (Just (idText d.supersededBy)) d.supersededAt)         updateMemorySupersededStmt     MemoryArchived d ->-      Tx.statement (idText d.memoryId, d.archivedAt) updateMemoryArchivedStmt+      Tx.statement+        (MemoryStatusChange d.memorySpaceId (idText d.memoryId) Nothing d.archivedAt)+        updateMemoryArchivedStmt     MemoryTagsUpdated d ->-      Tx.statement (idText d.memoryId, d.tags, d.updatedAt) updateMemoryTagsStmt+      Tx.statement (MemoryTagsChange d.memorySpaceId (idText d.memoryId) d.tags d.updatedAt) updateMemoryTagsStmt     MemoryConfidenceUpdated d ->-      Tx.statement (idText d.memoryId, confidenceToText d.confidence, d.updatedAt) updateMemoryConfidenceStmt+      Tx.statement+        (MemoryConfidenceChange d.memorySpaceId (idText d.memoryId) (confidenceToText d.confidence) d.updatedAt)+        updateMemoryConfidenceStmt     MemoryMerged d ->-      Tx.statement (idText d.memoryId, idText d.mergedInto, d.mergedAt) updateMemoryMergedStmt+      Tx.statement+        (MemoryStatusChange d.memorySpaceId (idText d.memoryId) (Just (idText d.mergedInto)) d.mergedAt)+        updateMemoryMergedStmt +-- | The parameters of a retirement: which memory, in which space, retired in favour of what.+data MemoryStatusChange = MemoryStatusChange+  { memorySpaceId :: !MemorySpaceId,+    memoryId :: !Text,+    supersededBy :: !(Maybe Text),+    updatedAt :: !UTCTime+  }++data MemoryTagsChange = MemoryTagsChange+  { memorySpaceId :: !MemorySpaceId,+    memoryId :: !Text,+    tags :: !(Set Text),+    updatedAt :: !UTCTime+  }++data MemoryConfidenceChange = MemoryConfidenceChange+  { memorySpaceId :: !MemorySpaceId,+    memoryId :: !Text,+    confidence :: !Text,+    updatedAt :: !UTCTime+  }+ recordedRow :: MemoryRecordedData -> MemoryRow recordedRow d =   MemoryRow-    { memoryId = idText d.memoryId,+    { memorySpaceId = d.memorySpaceId,+      memoryId = idText d.memoryId,       agentId = d.agentId,       sessionId = idText <$> d.sessionId,       namespace = scopeNamespaceText d.scope,@@ -123,147 +192,167 @@ memoryByIdReadModel =   ReadModel     { name = "kioku-memory-by-id",-      schema = "kiroku",-      tableName = "kioku_memories",+      schema = kiokuSchema,+      tableName = memoriesRelation,       subscriptionName = "kioku-memory-inline",-      version = 1,-      shapeHash = "kioku-memory-v1",+      version = memoryReadModelVersion,+      shapeHash = memoryReadModelShapeHash,       defaultConsistency = Eventual,       strongScope = EntireLog,-      query = \(MemoryByIdQuery mid) -> Tx.statement mid selectMemoryByIdStmt+      query = \q -> Tx.statement q selectMemoryByIdStmt     }  memoriesByNamespaceReadModel :: ReadModel MemoriesByNamespaceQuery [MemoryRecord] memoriesByNamespaceReadModel =   ReadModel     { name = "kioku-memories-by-namespace",-      schema = "kiroku",-      tableName = "kioku_memories",+      schema = kiokuSchema,+      tableName = memoriesRelation,       subscriptionName = "kioku-memory-inline",-      version = 1,-      shapeHash = "kioku-memory-v1",+      version = memoryReadModelVersion,+      shapeHash = memoryReadModelShapeHash,       defaultConsistency = Eventual,       strongScope = EntireLog,-      query = \(MemoriesByNamespaceQuery ns) -> Tx.statement ns selectActiveByNamespaceStmt+      query = \q -> Tx.statement q selectActiveByNamespaceStmt     }  memoriesByNamespaceRowsReadModel :: ReadModel MemoriesByNamespaceQuery [MemoryRow] memoriesByNamespaceRowsReadModel =   ReadModel     { name = "kioku-memory-rows-by-namespace",-      schema = "kiroku",-      tableName = "kioku_memories",+      schema = kiokuSchema,+      tableName = memoriesRelation,       subscriptionName = "kioku-memory-inline",-      version = 1,-      shapeHash = "kioku-memory-v1",+      version = memoryReadModelVersion,+      shapeHash = memoryReadModelShapeHash,       defaultConsistency = Eventual,       strongScope = EntireLog,-      query = \(MemoriesByNamespaceQuery ns) -> Tx.statement ns selectActiveByNamespaceRowsStmt+      query = \q -> Tx.statement q selectActiveByNamespaceRowsStmt     }  memoriesByScopeReadModel :: ReadModel MemoriesByScopeQuery [MemoryRecord] memoriesByScopeReadModel =   ReadModel     { name = "kioku-memories-by-scope",-      schema = "kiroku",-      tableName = "kioku_memories",+      schema = kiokuSchema,+      tableName = memoriesRelation,       subscriptionName = "kioku-memory-inline",-      version = 1,-      shapeHash = "kioku-memory-v1",+      version = memoryReadModelVersion,+      shapeHash = memoryReadModelShapeHash,       defaultConsistency = Eventual,       strongScope = EntireLog,-      query = \(MemoriesByScopeQuery ns sk sr) -> Tx.statement (ns, sk, sr) selectActiveByScopeStmt+      query = \q -> Tx.statement q selectActiveByScopeStmt     }  memoriesByScopeRowsReadModel :: ReadModel MemoriesByScopeQuery [MemoryRow] memoriesByScopeRowsReadModel =   ReadModel     { name = "kioku-memory-rows-by-scope",-      schema = "kiroku",-      tableName = "kioku_memories",+      schema = kiokuSchema,+      tableName = memoriesRelation,       subscriptionName = "kioku-memory-inline",-      version = 1,-      shapeHash = "kioku-memory-v1",+      version = memoryReadModelVersion,+      shapeHash = memoryReadModelShapeHash,       defaultConsistency = Eventual,       strongScope = EntireLog,-      query = \(MemoriesByScopeQuery ns sk sr) -> Tx.statement (ns, sk, sr) selectActiveByScopeRowsStmt+      query = \q -> Tx.statement q selectActiveByScopeRowsStmt     }  memoriesBySessionReadModel :: ReadModel MemoriesBySessionQuery [MemoryRecord] memoriesBySessionReadModel =   ReadModel     { name = "kioku-memories-by-session",-      schema = "kiroku",-      tableName = "kioku_memories",+      schema = kiokuSchema,+      tableName = memoriesRelation,       subscriptionName = "kioku-memory-inline",-      version = 1,-      shapeHash = "kioku-memory-v1",+      version = memoryReadModelVersion,+      shapeHash = memoryReadModelShapeHash,       defaultConsistency = Eventual,       strongScope = EntireLog,-      query = \(MemoriesBySessionQuery sid) -> Tx.statement sid selectBySessionStmt+      query = \q -> Tx.statement q selectBySessionStmt     }  memoriesBySessionRowsReadModel :: ReadModel MemoriesBySessionQuery [MemoryRow] memoriesBySessionRowsReadModel =   ReadModel     { name = "kioku-memory-rows-by-session",-      schema = "kiroku",-      tableName = "kioku_memories",+      schema = kiokuSchema,+      tableName = memoriesRelation,       subscriptionName = "kioku-memory-inline",-      version = 1,-      shapeHash = "kioku-memory-v1",+      version = memoryReadModelVersion,+      shapeHash = memoryReadModelShapeHash,       defaultConsistency = Eventual,       strongScope = EntireLog,-      query = \(MemoriesBySessionQuery sid) -> Tx.statement sid selectBySessionRowsStmt+      query = \q -> Tx.statement q selectBySessionRowsStmt     }  memoriesByTypeReadModel :: ReadModel MemoriesByTypeQuery [MemoryRecord] memoriesByTypeReadModel =   ReadModel     { name = "kioku-memories-by-type",-      schema = "kiroku",-      tableName = "kioku_memories",+      schema = kiokuSchema,+      tableName = memoriesRelation,       subscriptionName = "kioku-memory-inline",-      version = 1,-      shapeHash = "kioku-memory-v1",+      version = memoryReadModelVersion,+      shapeHash = memoryReadModelShapeHash,       defaultConsistency = Eventual,       strongScope = EntireLog,-      query = \(MemoriesByTypeQuery ns mt) -> Tx.statement (ns, mt) selectByTypeStmt+      query = \q -> Tx.statement q selectByTypeStmt     }  memoriesByTypeRowsReadModel :: ReadModel MemoriesByTypeQuery [MemoryRow] memoriesByTypeRowsReadModel =   ReadModel     { name = "kioku-memory-rows-by-type",-      schema = "kiroku",-      tableName = "kioku_memories",+      schema = kiokuSchema,+      tableName = memoriesRelation,       subscriptionName = "kioku-memory-inline",-      version = 1,-      shapeHash = "kioku-memory-v1",+      version = memoryReadModelVersion,+      shapeHash = memoryReadModelShapeHash,       defaultConsistency = Eventual,       strongScope = EntireLog,-      query = \(MemoriesByTypeQuery ns mt) -> Tx.statement (ns, mt) selectByTypeRowsStmt+      query = \q -> Tx.statement q selectByTypeRowsStmt     }  memorySupersessionChainReadModel :: ReadModel MemorySupersessionChainQuery [MemoryRow] memorySupersessionChainReadModel =   ReadModel     { name = "kioku-memory-supersession-chain",-      schema = "kiroku",-      tableName = "kioku_memories",+      schema = kiokuSchema,+      tableName = memoriesRelation,       subscriptionName = "kioku-memory-inline",-      version = 1,-      shapeHash = "kioku-memory-v1",+      version = memoryReadModelVersion,+      shapeHash = memoryReadModelShapeHash,       defaultConsistency = Eventual,       strongScope = EntireLog,-      query = \(MemorySupersessionChainQuery mid) -> Tx.statement mid selectSupersessionChainStmt+      query = \q -> Tx.statement q selectSupersessionChainStmt     } +-- | The registry identity of every memory read model.+--+-- v2 was the memory-space partition: the row carries @memory_space_id@ and every query filters+-- on it. v3 is the relocation of this projection from @kiroku.kioku_memories@ to+-- @kioku.memories@. Keiro's registry stores a logical name, version, and shape hash but no+-- physical relation locator, so the version bump is the only signal available — and it is the+-- one that matters, because it makes a binary compiled before the move fail closed with+-- @ReadModelStaleSchema@ instead of issuing SQL at a relation that is no longer there.+--+-- Neither bump requires a rebuild: the migration leaves the table data correct for the new+-- version (v2 backfilled every pre-existing row into the legacy space; v3 moved the rows+-- without touching them), so @Kioku.ReadModel.reconcileReadModelRegistry@ can advance the guard+-- on its own.+memoryReadModelVersion :: Int+memoryReadModelVersion = 3++memoryReadModelShapeHash :: Text+memoryReadModelShapeHash = "kioku-memory-v3"+ memoryRowDecoder :: D.Row MemoryRow memoryRowDecoder =   MemoryRow-    <$> D.column (D.nonNullable D.text)+    <$> memorySpaceColumn     <*> D.column (D.nonNullable D.text)+    <*> D.column (D.nonNullable D.text)     <*> D.column (D.nullable D.text)     <*> D.column (D.nonNullable D.text)     <*> D.column (D.nullable D.text)@@ -308,11 +397,13 @@  memoryRowColumns :: Text memoryRowColumns =-  "memory_id, agent_id, session_id, namespace, scope_kind, scope_ref, memory_type, content, priority, confidence, tags::text, status, superseded_by, supersedes, created_at, updated_at"+  "memory_space_id, memory_id, agent_id, session_id, namespace, scope_kind, scope_ref, memory_type, content, priority, confidence, tags::text, status, superseded_by, supersedes, created_at, updated_at"  qualifiedMemoryRowColumns :: Text -> Text qualifiedMemoryRowColumns prefix =   prefix+    <> ".memory_space_id, "+    <> prefix     <> ".memory_id, "     <> prefix     <> ".agent_id, "@@ -345,168 +436,208 @@     <> prefix     <> ".updated_at" -selectMemoryByIdStmt :: Statement Text (Maybe MemoryRow)+selectMemoryByIdStmt :: Statement MemoryByIdQuery (Maybe MemoryRow) selectMemoryByIdStmt =   preparable     ( "SELECT "         <> memoryRowColumns-        <> " FROM kioku_memories WHERE memory_id = $1"+        <> " FROM "+        <> memoriesTable+        <> " WHERE memory_space_id = $1 AND memory_id = $2"     )-    (E.param (E.nonNullable E.text))+    ( ((\q -> q.memorySpaceId) >$< memorySpaceParam)+        <> ((\q -> q.memoryId) >$< E.param (E.nonNullable E.text))+    )     (D.rowMaybe memoryRowDecoder) -selectActiveByNamespaceStmt :: Statement Text [MemoryRecord]+selectActiveByNamespaceStmt :: Statement MemoriesByNamespaceQuery [MemoryRecord] selectActiveByNamespaceStmt =   preparable-    ( "SELECT "-        <> memoryRowColumns-        <> " FROM kioku_memories WHERE status = 'active' AND namespace = $1 ORDER BY priority ASC, created_at DESC"-    )-    (E.param (E.nonNullable E.text))+    (activeByNamespaceSql memoryRowColumns)+    namespaceQueryEncoder     (D.rowList memoryRecordDecoder) -selectActiveByNamespaceRowsStmt :: Statement Text [MemoryRow]+selectActiveByNamespaceRowsStmt :: Statement MemoriesByNamespaceQuery [MemoryRow] selectActiveByNamespaceRowsStmt =   preparable-    ( "SELECT "-        <> memoryRowColumns-        <> " FROM kioku_memories WHERE status = 'active' AND namespace = $1 ORDER BY priority ASC, created_at DESC"-    )-    (E.param (E.nonNullable E.text))+    (activeByNamespaceSql memoryRowColumns)+    namespaceQueryEncoder     (D.rowList memoryRowDecoder) --- | Active memories carrying __exactly__ the given scope.+activeByNamespaceSql :: Text -> Text+activeByNamespaceSql columns =+  "SELECT "+    <> columns+    <> " FROM "+    <> memoriesTable+    <> " WHERE status = 'active' AND memory_space_id = $1 AND namespace = $2 ORDER BY priority ASC, created_at DESC"++namespaceQueryEncoder :: E.Params MemoriesByNamespaceQuery+namespaceQueryEncoder =+  ((\q -> q.memorySpaceId) >$< memorySpaceParam)+    <> ((\q -> q.namespace) >$< E.param (E.nonNullable E.text))++-- | Active memories carrying __exactly__ the given scope, inside one memory space. -- -- Recall searches namespace-wide for a global scope; scoped reads are exact-scope. The -- predicate below /requires/ @scope_kind@ and @scope_ref@ to be NULL for a global scope, -- where 'Kioku.Recall.selectFtsCandidatesStmt' would drop the scope filter entirely and--- return the whole namespace. Both behaviours are intentional; see docs/user/recall.md.-selectActiveByScopeStmt :: Statement (Text, Maybe Text, Maybe Text) [MemoryRecord]+-- return the whole namespace. Both behaviours are intentional; see docs/user/recall.md. The+-- memory-space predicate is not part of that asymmetry — it never widens, in either query.+selectActiveByScopeStmt :: Statement MemoriesByScopeQuery [MemoryRecord] selectActiveByScopeStmt =   preparable-    ( "SELECT "-        <> memoryRowColumns-        <> " FROM kioku_memories WHERE status = 'active' AND namespace = $1 AND ((scope_kind = $2 AND scope_ref = $3) OR ($2 IS NULL AND scope_kind IS NULL AND $3 IS NULL AND scope_ref IS NULL)) ORDER BY priority ASC, created_at DESC"-    )-    ( contrazip3-        (E.param (E.nonNullable E.text))-        (E.param (E.nullable E.text))-        (E.param (E.nullable E.text))-    )+    (activeByScopeSql memoryRowColumns)+    scopeQueryEncoder     (D.rowList memoryRecordDecoder) -selectActiveByScopeRowsStmt :: Statement (Text, Maybe Text, Maybe Text) [MemoryRow]+selectActiveByScopeRowsStmt :: Statement MemoriesByScopeQuery [MemoryRow] selectActiveByScopeRowsStmt =   preparable-    ( "SELECT "-        <> memoryRowColumns-        <> " FROM kioku_memories WHERE status = 'active' AND namespace = $1 AND ((scope_kind = $2 AND scope_ref = $3) OR ($2 IS NULL AND scope_kind IS NULL AND $3 IS NULL AND scope_ref IS NULL)) ORDER BY priority ASC, created_at DESC"-    )-    ( contrazip3-        (E.param (E.nonNullable E.text))-        (E.param (E.nullable E.text))-        (E.param (E.nullable E.text))-    )+    (activeByScopeSql memoryRowColumns)+    scopeQueryEncoder     (D.rowList memoryRowDecoder) -selectBySessionStmt :: Statement Text [MemoryRecord]+activeByScopeSql :: Text -> Text+activeByScopeSql columns =+  "SELECT "+    <> columns+    <> " FROM "+    <> memoriesTable+    <> " WHERE status = 'active' AND memory_space_id = $1 AND namespace = $2 AND ((scope_kind = $3 AND scope_ref = $4) OR ($3 IS NULL AND scope_kind IS NULL AND $4 IS NULL AND scope_ref IS NULL)) ORDER BY priority ASC, created_at DESC"++scopeQueryEncoder :: E.Params MemoriesByScopeQuery+scopeQueryEncoder =+  ((\q -> q.memorySpaceId) >$< memorySpaceParam)+    <> ((\q -> q.namespace) >$< E.param (E.nonNullable E.text))+    <> ((\q -> q.scopeKind) >$< E.param (E.nullable E.text))+    <> ((\q -> q.scopeRef) >$< E.param (E.nullable E.text))++selectBySessionStmt :: Statement MemoriesBySessionQuery [MemoryRecord] selectBySessionStmt =   preparable-    ( "SELECT "-        <> memoryRowColumns-        <> " FROM kioku_memories WHERE session_id = $1 ORDER BY created_at DESC"-    )-    (E.param (E.nonNullable E.text))+    (bySessionSql memoryRowColumns)+    sessionQueryEncoder     (D.rowList memoryRecordDecoder) -selectBySessionRowsStmt :: Statement Text [MemoryRow]+selectBySessionRowsStmt :: Statement MemoriesBySessionQuery [MemoryRow] selectBySessionRowsStmt =   preparable-    ( "SELECT "-        <> memoryRowColumns-        <> " FROM kioku_memories WHERE session_id = $1 ORDER BY created_at DESC"-    )-    (E.param (E.nonNullable E.text))+    (bySessionSql memoryRowColumns)+    sessionQueryEncoder     (D.rowList memoryRowDecoder) -selectByTypeStmt :: Statement (Text, Text) [MemoryRecord]+bySessionSql :: Text -> Text+bySessionSql columns =+  "SELECT "+    <> columns+    <> " FROM "+    <> memoriesTable+    <> " WHERE memory_space_id = $1 AND session_id = $2 ORDER BY created_at DESC"++sessionQueryEncoder :: E.Params MemoriesBySessionQuery+sessionQueryEncoder =+  ((\q -> q.memorySpaceId) >$< memorySpaceParam)+    <> ((\q -> q.sessionId) >$< E.param (E.nonNullable E.text))++selectByTypeStmt :: Statement MemoriesByTypeQuery [MemoryRecord] selectByTypeStmt =   preparable-    ( "SELECT "-        <> memoryRowColumns-        <> " FROM kioku_memories WHERE status = 'active' AND namespace = $1 AND memory_type = $2 ORDER BY priority ASC, created_at DESC"-    )-    ( contrazip2-        (E.param (E.nonNullable E.text))-        (E.param (E.nonNullable E.text))-    )+    (byTypeSql memoryRowColumns)+    typeQueryEncoder     (D.rowList memoryRecordDecoder) -selectByTypeRowsStmt :: Statement (Text, Text) [MemoryRow]+selectByTypeRowsStmt :: Statement MemoriesByTypeQuery [MemoryRow] selectByTypeRowsStmt =   preparable-    ( "SELECT "-        <> memoryRowColumns-        <> " FROM kioku_memories WHERE status = 'active' AND namespace = $1 AND memory_type = $2 ORDER BY priority ASC, created_at DESC"-    )-    ( contrazip2-        (E.param (E.nonNullable E.text))-        (E.param (E.nonNullable E.text))-    )+    (byTypeSql memoryRowColumns)+    typeQueryEncoder     (D.rowList memoryRowDecoder) -selectSupersessionChainStmt :: Statement Text [MemoryRow]+byTypeSql :: Text -> Text+byTypeSql columns =+  "SELECT "+    <> columns+    <> " FROM "+    <> memoriesTable+    <> " WHERE status = 'active' AND memory_space_id = $1 AND namespace = $2 AND memory_type = $3 ORDER BY priority ASC, created_at DESC"++typeQueryEncoder :: E.Params MemoriesByTypeQuery+typeQueryEncoder =+  ((\q -> q.memorySpaceId) >$< memorySpaceParam)+    <> ((\q -> q.namespace) >$< E.param (E.nonNullable E.text))+    <> ((\q -> q.memoryType) >$< E.param (E.nonNullable E.text))++-- | Walk a memory's supersession chain, without leaving the space it started in.+--+-- The space predicate is repeated on the recursive arm, not just the anchor. Supersession+-- lineage is stored as bare ids in @supersedes@ and @superseded_by@, so an id written before+-- the partition existed — or a bug anywhere upstream — could otherwise walk the chain straight+-- into another space and return its content.+selectSupersessionChainStmt :: Statement MemorySupersessionChainQuery [MemoryRow] selectSupersessionChainStmt =   preparable     ( "WITH RECURSIVE chain AS ("         <> "SELECT "         <> memoryRowColumns-        <> " FROM kioku_memories WHERE memory_id = $1 "+        <> " FROM "+        <> memoriesTable+        <> " WHERE memory_space_id = $1 AND memory_id = $2 "         <> "UNION "         <> "SELECT "         <> qualifiedMemoryRowColumns "m"-        <> " FROM kioku_memories m JOIN chain c ON "+        <> " FROM "+        <> memoriesTable+        <> " m JOIN chain c ON m.memory_space_id = c.memory_space_id AND ("         <> "m.memory_id = c.supersedes "         <> "OR m.supersedes = c.memory_id "         <> "OR m.memory_id = c.superseded_by "         <> "OR m.superseded_by = c.memory_id"-        <> ") SELECT "+        <> ")) SELECT "         <> memoryRowColumns         <> " FROM chain ORDER BY created_at ASC, memory_id ASC"     )-    (E.param (E.nonNullable E.text))+    ( ((\q -> q.memorySpaceId) >$< memorySpaceParam)+        <> ((\q -> q.memoryId) >$< E.param (E.nonNullable E.text))+    )     (D.rowList memoryRowDecoder)  upsertMemoryStmt :: Statement MemoryRow () upsertMemoryStmt =   preparable-    """-    INSERT INTO kioku_memories-      (memory_id, agent_id, session_id, namespace, scope_kind, scope_ref, memory_type, content,-       priority, confidence, tags, status, superseded_by, supersedes, created_at, updated_at)-    VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11::jsonb, $12, $13, $14, $15, $16)-    ON CONFLICT (memory_id) DO UPDATE SET-      agent_id = EXCLUDED.agent_id,-      session_id = EXCLUDED.session_id,-      namespace = EXCLUDED.namespace,-      scope_kind = EXCLUDED.scope_kind,-      scope_ref = EXCLUDED.scope_ref,-      memory_type = EXCLUDED.memory_type,-      content = EXCLUDED.content,-      priority = EXCLUDED.priority,-      confidence = EXCLUDED.confidence,-      tags = EXCLUDED.tags,-      status = EXCLUDED.status,-      superseded_by = EXCLUDED.superseded_by,-      supersedes = EXCLUDED.supersedes,-      updated_at = EXCLUDED.updated_at-    """+    ( "INSERT INTO "+        <> memoriesTable+        <> "\n"+        <> """+           (memory_space_id, memory_id, agent_id, session_id, namespace, scope_kind, scope_ref,+              memory_type, content, priority, confidence, tags, status, superseded_by, supersedes,+              created_at, updated_at)+           VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12::jsonb, $13, $14, $15, $16, $17)+           ON CONFLICT (memory_id) DO UPDATE SET+             memory_space_id = EXCLUDED.memory_space_id,+             agent_id = EXCLUDED.agent_id,+             session_id = EXCLUDED.session_id,+             namespace = EXCLUDED.namespace,+             scope_kind = EXCLUDED.scope_kind,+             scope_ref = EXCLUDED.scope_ref,+             memory_type = EXCLUDED.memory_type,+             content = EXCLUDED.content,+             priority = EXCLUDED.priority,+             confidence = EXCLUDED.confidence,+             tags = EXCLUDED.tags,+             status = EXCLUDED.status,+             superseded_by = EXCLUDED.superseded_by,+             supersedes = EXCLUDED.supersedes,+             updated_at = EXCLUDED.updated_at+           """+    )     memoryRowEncoder     D.noResult  memoryRowEncoder :: E.Params MemoryRow memoryRowEncoder =-  ((\row -> row.memoryId) >$< E.param (E.nonNullable E.text))+  ((\row -> row.memorySpaceId) >$< memorySpaceParam)+    <> ((\row -> row.memoryId) >$< E.param (E.nonNullable E.text))     <> ((\row -> row.agentId) >$< E.param (E.nonNullable E.text))     <> ((\row -> row.sessionId) >$< E.param (E.nullable E.text))     <> ((\row -> row.namespace) >$< E.param (E.nonNullable E.text))@@ -523,53 +654,52 @@     <> ((\row -> row.createdAt) >$< E.param (E.nonNullable E.timestamptz))     <> ((\row -> row.updatedAt) >$< E.param (E.nonNullable E.timestamptz)) -updateMemorySupersededStmt :: Statement (Text, Text, UTCTime) ()+statusChangeEncoder :: E.Params MemoryStatusChange+statusChangeEncoder =+  ((\c -> c.memorySpaceId) >$< memorySpaceParam)+    <> ((\c -> c.memoryId) >$< E.param (E.nonNullable E.text))+    <> ((\c -> c.supersededBy) >$< E.param (E.nullable E.text))+    <> ((\c -> c.updatedAt) >$< E.param (E.nonNullable E.timestamptz))++updateMemorySupersededStmt :: Statement MemoryStatusChange () updateMemorySupersededStmt =   preparable-    "UPDATE kioku_memories SET status = 'superseded', superseded_by = $2, updated_at = $3 WHERE memory_id = $1"-    ( contrazip3-        (E.param (E.nonNullable E.text))-        (E.param (E.nonNullable E.text))-        (E.param (E.nonNullable E.timestamptz))-    )+    ("UPDATE " <> memoriesTable <> " SET status = 'superseded', superseded_by = $3, updated_at = $4 WHERE memory_space_id = $1 AND memory_id = $2")+    statusChangeEncoder     D.noResult -updateMemoryArchivedStmt :: Statement (Text, UTCTime) ()+updateMemoryArchivedStmt :: Statement MemoryStatusChange () updateMemoryArchivedStmt =   preparable-    "UPDATE kioku_memories SET status = 'archived', updated_at = $2 WHERE memory_id = $1"-    (contrazip2 (E.param (E.nonNullable E.text)) (E.param (E.nonNullable E.timestamptz)))+    ("UPDATE " <> memoriesTable <> " SET status = 'archived', updated_at = $4 WHERE memory_space_id = $1 AND memory_id = $2")+    statusChangeEncoder     D.noResult -updateMemoryTagsStmt :: Statement (Text, Set Text, UTCTime) ()-updateMemoryTagsStmt =+updateMemoryMergedStmt :: Statement MemoryStatusChange ()+updateMemoryMergedStmt =   preparable-    "UPDATE kioku_memories SET tags = $2::jsonb, updated_at = $3 WHERE memory_id = $1"-    ( contrazip3-        (E.param (E.nonNullable E.text))-        (encodeTags >$< E.param (E.nonNullable E.text))-        (E.param (E.nonNullable E.timestamptz))-    )+    ("UPDATE " <> memoriesTable <> " SET status = 'merged', superseded_by = $3, updated_at = $4 WHERE memory_space_id = $1 AND memory_id = $2")+    statusChangeEncoder     D.noResult -updateMemoryConfidenceStmt :: Statement (Text, Text, UTCTime) ()-updateMemoryConfidenceStmt =+updateMemoryTagsStmt :: Statement MemoryTagsChange ()+updateMemoryTagsStmt =   preparable-    "UPDATE kioku_memories SET confidence = $2, updated_at = $3 WHERE memory_id = $1"-    ( contrazip3-        (E.param (E.nonNullable E.text))-        (E.param (E.nonNullable E.text))-        (E.param (E.nonNullable E.timestamptz))+    ("UPDATE " <> memoriesTable <> " SET tags = $3::jsonb, updated_at = $4 WHERE memory_space_id = $1 AND memory_id = $2")+    ( ((\c -> c.memorySpaceId) >$< memorySpaceParam)+        <> ((\c -> c.memoryId) >$< E.param (E.nonNullable E.text))+        <> ((encodeTags . (\c -> c.tags)) >$< E.param (E.nonNullable E.text))+        <> ((\c -> c.updatedAt) >$< E.param (E.nonNullable E.timestamptz))     )     D.noResult -updateMemoryMergedStmt :: Statement (Text, Text, UTCTime) ()-updateMemoryMergedStmt =+updateMemoryConfidenceStmt :: Statement MemoryConfidenceChange ()+updateMemoryConfidenceStmt =   preparable-    "UPDATE kioku_memories SET status = 'merged', superseded_by = $2, updated_at = $3 WHERE memory_id = $1"-    ( contrazip3-        (E.param (E.nonNullable E.text))-        (E.param (E.nonNullable E.text))-        (E.param (E.nonNullable E.timestamptz))+    ("UPDATE " <> memoriesTable <> " SET confidence = $3, updated_at = $4 WHERE memory_space_id = $1 AND memory_id = $2")+    ( ((\c -> c.memorySpaceId) >$< memorySpaceParam)+        <> ((\c -> c.memoryId) >$< E.param (E.nonNullable E.text))+        <> ((\c -> c.confidence) >$< E.param (E.nonNullable E.text))+        <> ((\c -> c.updatedAt) >$< E.param (E.nonNullable E.timestamptz))     )     D.noResult

@@ -0,0 +1,92 @@+-- | Reading the memory-space partition off events that predate it.+--+-- Every command and event Kioku writes now names the memory space it belongs to and the+-- principal that acted. Events already on disk name neither, and they must keep decoding+-- forever: an event that stops parsing is an aggregate that can no longer be rebuilt and a+-- projection that can no longer be replayed.+--+-- These helpers are the single place that decides what an older payload means, so that no+-- module invents its own default. The rules are:+--+-- * A payload with no @memorySpaceId@ belongs to 'legacyMemorySpaceId'. Absence of a partition+--   never means "visible everywhere" — see @docs\/adr\/legacy-data-lands-in-one-explicit-space.md@.+-- * A payload with no @actorPrincipal@ but with the old free-text @agentId@ is attributed to+--   that label, marked as legacy. It is never rewritten into a directory-issued principal id.+-- * A payload with neither is 'UnattributedPrincipal'. Most pre-partition events — archiving a+--   memory, completing a session, recording a turn — genuinely recorded no actor, and inventing+--   one would put a fabricated identity into an audit trail.+--+-- Encoding always writes the new form. There is no path that emits a payload without a space.+--+-- The same module owns how a memory space is written down in PostgreSQL, for the same reason:+-- @memory_space_id@ is a plain @text@ column, and exactly one pair of functions turns a+-- 'MemorySpaceId' into it and back.+module Kioku.Partition+  ( parsePartitionSpace,+    parseRecordedActor,+    parseRecordedActorFromAgent,+    parseRecordedOwner,+    memorySpaceColumn,+    memorySpaceParam,+  )+where++import Data.Aeson.Types (Object, Parser, (.!=), (.:), (.:?))+import Data.Functor.Contravariant ((>$<))+import Hasql.Decoders qualified as D+import Hasql.Encoders qualified as E+import Kioku.Api.Access+  ( LegacyPrincipalRef,+    MemorySpaceId,+    PrincipalRef,+    RecordedPrincipal (..),+    legacyMemorySpaceId,+    legacyPrincipalRef,+    memorySpaceIdText,+    mkMemorySpaceId,+  )+import Kioku.Prelude++-- | The memory space a payload belongs to, defaulting an older payload into the legacy space.+parsePartitionSpace :: Object -> Parser MemorySpaceId+parsePartitionSpace o = o .:? "memorySpaceId" .!= legacyMemorySpaceId++-- | The actor a payload records, for events that never carried an agent label.+parseRecordedActor :: Object -> Parser RecordedPrincipal+parseRecordedActor o = o .:? "actorPrincipal" .!= UnattributedPrincipal++-- | The actor a payload records, for events that carried the old free-text @agentId@.+--+-- The legacy label is kept verbatim and marked. Turning @demo-agent@ into @agent_demo-agent@+-- would manufacture an identifier no directory ever issued, and every later authorization+-- decision made against it would be a decision about a string somebody typed.+parseRecordedActorFromAgent :: Object -> Parser RecordedPrincipal+parseRecordedActorFromAgent o = do+  explicit <- o .:? "actorPrincipal"+  case explicit of+    Just actor -> pure actor+    Nothing -> legacyActor <$> o .: "agentId"+  where+    legacyActor :: Text -> RecordedPrincipal+    legacyActor = LegacyPrincipal . (legacyPrincipalRef :: Text -> LegacyPrincipalRef)++-- | The owning principal, which only writes made through the memory-space API can carry.+--+-- There is no legacy fallback and there must not be one: ownership did not exist before this+-- field did, so an older payload has no owner rather than an implied one.+parseRecordedOwner :: Object -> Parser (Maybe PrincipalRef)+parseRecordedOwner o = o .:? "ownerPrincipal"++-- | Decode a non-null @memory_space_id@ column.+--+-- It goes through 'mkMemorySpaceId' rather than being taken as raw text, so a row that somehow+-- holds a value no caller could have constructed — an empty string, something with a @:@ in it —+-- fails the read loudly instead of becoming a space id that compares equal to nothing.+memorySpaceColumn :: D.Row MemorySpaceId+memorySpaceColumn =+  D.column (D.nonNullable (D.refine mkMemorySpaceId D.text))++-- | Encode one @memory_space_id@ query parameter.+memorySpaceParam :: E.Params MemorySpaceId+memorySpaceParam =+  memorySpaceIdText >$< E.param (E.nonNullable E.text)

@@ -1,9 +1,43 @@+-- | Running a recall request, and the unranked scope scans beside it.+--+-- A recall call names two things that used to be one. The __target__ says what to search — one+-- exact scope, or every scope in one namespace — and comes from the caller. The __memory space__+-- says whose memories those are, and comes from the 'MemoryAccessContext' that authorized the+-- call. Widening the first can never widen the second, which is the property the vocabulary in+-- "Kioku.Api.Recall" exists to make visible at every call site.+--+-- The old entry point is still here. 'legacyRecall' takes the pre-target 'RecallRequest', maps+-- its 'MemoryScope' through 'legacyRecallTarget', and returns exactly the rows it returns today;+-- it is deprecated so that an unmigrated caller finds out at compile time rather than by counting+-- rows. See @docs\/user\/recall.md@ for the migration table and the removal condition. module Kioku.Recall-  ( RecallStrategy (..),-    RecallRequest (..),+  ( -- * What to search for+    RecallTarget (..),+    RecallQuery (..),+    RecallStrategy (..),+    RecallLimit,+    mkRecallQuery,+    mkRecallLimit,+    recallLimitInt,+    defaultRecallLimit,+    maxRecallLimit,+    recallStrategyText,+    parseRecallStrategy,+    allRecallStrategies,+    recallTargetNamespace,+    recallTargetExactScope,+    recallTargetIsNamespaceWide,++    -- * Running it+    RecallError (..),     RecallHit (..),     RecallExecutionPlan (..),     recall,++    -- * The pre-target API, kept for one release+    RecallRequest (..),+    legacyRecall,+    legacyRecallTarget,     planRecallExecution,     fuseRecallCandidates,     blendScore,@@ -21,17 +55,22 @@      -- * Test seams     -- $testSeams+    ResolvedRecall,+    resolveRecall,     selectFtsCandidates,     selectVectorCandidates,     vectorLiteral,-    selectVectorCandidatesStmt,-    selectVectorCandidatesExactStmt,     selectVectorCandidatesDiagnosed,     VectorChannelOutcome (..),     vectorChannelStarved,-    VectorCandidateQuery,-    vectorCandidateQuery,-    memoryRecordColumns,+    FtsCandidateSql,+    ftsCandidateSql,+    explainFtsCandidates,+    VectorCandidateSql,+    vectorCandidateSql,+    runVectorAnnCandidates,+    explainVectorAnnCandidates,+    explainVectorExactCandidates,     candidatePoolSize,   ) where@@ -58,8 +97,28 @@ import Hasql.Statement (Statement, preparable) import Hasql.Transaction qualified as Tx import Keiro.ReadModel (ConsistencyMode (..), ReadModelError, runQueryWith)-import Kioku.Api.Scope (MemoryScope (..), Namespace (..), scopeFromColumns, scopeKindText, scopeNamespaceText, scopeRefText)+import Kioku.Api.Access (MemoryAccessContext, MemorySpaceId, memoryContextSpace)+import Kioku.Api.Recall+  ( RecallLimit,+    RecallQuery (..),+    RecallStrategy (..),+    RecallTarget (..),+    allRecallStrategies,+    defaultRecallLimit,+    legacyRecallTarget,+    maxRecallLimit,+    mkRecallLimit,+    mkRecallQuery,+    parseRecallStrategy,+    recallLimitInt,+    recallStrategyText,+    recallTargetExactScope,+    recallTargetIsNamespaceWide,+    recallTargetNamespace,+  )+import Kioku.Api.Scope (MemoryScope (..), Namespace (..), ScopeKind (..), scopeFromColumns, scopeKindText, scopeNamespaceText, scopeRefText) import Kioku.Api.Types (MemoryRecord (..), MemoryType, memoryTypeToText)+import Kioku.Database.Schema (memoriesTable) import Kioku.Id (MemoryId, SessionId, idText) import Kioku.Memory.Embedding (embedWithRetry) import Kioku.Memory.ReadModel@@ -75,6 +134,7 @@     memoriesByTypeReadModel,     memoryByIdReadModel,   )+import Kioku.Partition (memorySpaceParam) import Kioku.Prelude import Kioku.Recall.Capability (VectorCapability (..)) import Kiroku.Store.Effect (Store)@@ -82,38 +142,64 @@  -- $testSeams -- Exported so the candidate SQL can be exercised directly against a real database--- (@Kioku.RecallSqlSpec@) rather than only through 'recall', which would drag in an--- embedding endpoint. They are not part of the intended public API.+-- (@Kioku.RecallSqlSpec@, @Kioku.RecallTargetSpec@) rather than only through 'recall', which+-- would drag in an embedding endpoint. They are not part of the intended public API. ----- 'selectVectorCandidatesStmt', 'vectorCandidateQuery', 'memoryRecordColumns' and--- 'candidatePoolSize' are exported for @Kioku.RecallHarness@, the recall-quality instrument. It--- needs the statement itself (rather than 'selectVectorCandidates', which wraps it in its own--- transaction) so that it can run it under a @SET LOCAL@, and it needs the projection and the--- pool size so that its @EXPLAIN@ describes the query that actually runs. That last one is not a--- nicety: the projection's row width sets the cost of the top-N sort the /exact/ plan needs, and--- that cost is what the planner weighs against the HNSW scan — so an @EXPLAIN@ carrying a--- different select list can silently choose a different plan and report a different answer.--- Restating them in the harness rather than exporting them is how the harness got that wrong--- once.--data RecallStrategy = Keyword | Embedding | Hybrid-  deriving stock (Generic, Eq, Show)+-- 'vectorCandidateSql', 'runVectorAnnCandidates' and 'explainVectorAnnCandidates' are exported+-- for @Kioku.RecallHarness@, the recall-quality instrument. It needs the approximate pass on its+-- own — 'selectVectorCandidates' runs the fallback too, and wraps both in its own transaction —+-- so that it can run it under a @SET LOCAL@ and measure the approximate pass in isolation. And+-- it needs an @EXPLAIN@ of /that/ statement, which is why 'explainVectorAnnCandidates' lives+-- here beside the statement it describes rather than in the harness.+--+-- __The harness used to restate the SQL and it went wrong twice.__ An @EXPLAIN@ whose SQL differs+-- from the shipping statement in any way the planner cares about can choose a different plan and+-- report a different answer, silently and flatteringly. Once the copy selected @memory_id@ alone:+-- the narrow row made the top-N sort look cheap, the planner took the exact plan, and the+-- @EXPLAIN@ reported fifty happy rows while the real query took the HNSW plan and returned zero.+-- Once it omitted the @memory_space_id@ predicate, which is the leading column of every+-- partition-first index, and reported an access path no live query can produce. There is now no+-- copy to drift: the @EXPLAIN@ is built from the same SQL text and the same parameters as the+-- statement it explains. --- | A recall request.+-- | The pre-'RecallTarget' recall request. ----- __Global scope means "namespace-wide" here.__ Recall searches namespace-wide for a global--- scope; scoped reads are exact-scope. A 'ScopeGlobal' request returns every active memory in--- the namespace, entity-scoped rows included — the scope filter simply vanishes. That is the--- opposite of what 'getActiveByScope' does with the same value. See docs/user/recall.md.+-- __Global scope means \"namespace-wide\" here.__ A 'ScopeGlobal' request returns every active+-- memory in the namespace, entity-scoped rows included — the scope filter simply vanishes. That+-- is the opposite of what 'getActiveByScope' does with the same value, and it is the ambiguity+-- 'RecallTarget' replaces. The behaviour is preserved exactly for one release; see+-- 'legacyRecall'.+--+-- __The memory space was never part of that asymmetry.__ It is an equality predicate on every+-- channel and it never widens, whatever the scope says. data RecallRequest = RecallRequest-  { -- | 'ScopeGlobal' searches the whole namespace; an entity scope matches exactly.+  { memorySpaceId :: !MemorySpaceId,+    -- | 'ScopeGlobal' searches the whole namespace; an entity scope matches exactly.     scope :: !MemoryScope,     query :: !Text,     strategy :: !RecallStrategy,     maxResults :: !Int   }   deriving stock (Generic, Eq, Show)+{-# DEPRECATED RecallRequest "Use RecallQuery and a RecallTarget. ScopeGlobal here means namespace-wide; the exact global bucket is ExactScope (ScopeGlobal ns)." #-} +-- | Why a recall call could not run at all, as distinct from running and matching nothing.+--+-- Keeping those apart is the whole point of returning an 'Either' here. A caller cannot tell+-- \"this could not be asked\" from \"there is nothing here\" if both arrive as an empty list, and+-- only one of them is worth acting on.+-- Every 'RecallTarget' is now executable, so the only way to reach this channel is the legacy+-- request's own memory space disagreeing with the context that authorized it. The channel stays+-- on 'recall' rather than collapsing to a total function: removing it is a public signature+-- change for every call site, which belongs with the consumer migration in+-- @docs\/plans\/30-migrate-recall-consumers-to-explicit-targets.md@ rather than here.+data RecallError+  = -- | A 'RecallRequest' named a memory space that is not the one its context authorizes:+    -- @RecallSpaceMismatch requested authorized@. Only 'legacyRecall' can produce this, because+    -- only the legacy request carries a space of its own.+    RecallSpaceMismatch !MemorySpaceId !MemorySpaceId+  deriving stock (Generic, Eq, Show)+ data RecallHit = RecallHit   { memory :: !MemoryRecord,     score :: !Double,@@ -129,24 +215,119 @@   }   deriving stock (Generic, Eq, Show) -data RecallCandidateQuery = RecallCandidateQuery-  { query :: !Text,+-- | Which rows inside one namespace a resolved target admits.+--+-- Three targets, three predicates, and — this is the whole point — no value that means two of+-- them. The representation this replaces spelled all three with a nullable @scope_kind@ and+-- @scope_ref@ pair, in which NULL meant /omit the scope filter/; the exact global bucket, whose+-- rows are exactly the ones whose scope columns /are/ NULL, therefore had no way to say so and+-- was refused rather than answered wrongly. See+-- @docs\/adr\/each-recall-target-gets-its-own-statement.md@.+data ScopeBound+  = -- | Only the rows recorded with no entity scope: @scope_kind IS NULL AND scope_ref IS NULL@.+    GlobalBucketOnly+  | -- | Only the rows carrying exactly this kind and ref: @scope_kind = $4 AND scope_ref = $5@.+    EntityScopeOnly !Text !Text+  | -- | Every scope in the namespace: no scope comparison at all. The memory-space and namespace+    -- predicates still apply, which is why this widens breadth without widening tenancy.+    EveryScopeInNamespace+  deriving stock (Generic, Eq, Show)++-- | A recall request bound to the memory space that authorized it, with its target already+-- compiled to the scope predicate the candidate SQL will carry.+--+-- 'resolveRecall' is the only way to build one, which is what makes the binding trustworthy: the+-- space comes from a 'MemoryAccessContext' and the bound comes from a 'RecallTarget', and neither+-- can be supplied independently of the other. Everything downstream of this type — all three+-- candidate statement families, the fusion, the budgets — sees a request that has already had its+-- authority and its breadth decided.+data ResolvedRecall = ResolvedRecall+  { memorySpaceId :: !MemorySpaceId,     namespace :: !Text,-    scopeKind :: !(Maybe Text),-    scopeRef :: !(Maybe Text),+    scopeBound :: !ScopeBound,+    query :: !Text,+    strategy :: !RecallStrategy,+    maxResults :: !Int+  }+  deriving stock (Generic, Eq, Show)++-- | Bind a request to one authorized memory space and compile its target to a scope bound.+--+-- This is the single mapping from what a caller asked for to what the SQL is given, and it is+-- deliberately the only one:+--+-- @+-- 'ExactScope' ('ScopeGlobal' ns)       -> namespace = ns, 'GlobalBucketOnly'+-- 'ExactScope' ('ScopeEntity' ns k r)   -> namespace = ns, 'EntityScopeOnly' k r+-- 'NamespaceWide' ns                  -> namespace = ns, 'EveryScopeInNamespace'+-- @+--+-- It is total. Every target has a predicate, the limit was validated into a 'RecallLimit' before+-- the request was built, and the space is an argument rather than a field of the request — so no+-- call site can widen a target and a tenancy in the same edit, and none of the three meanings can+-- fail to be expressible.+resolveRecall :: MemorySpaceId -> RecallQuery -> ResolvedRecall+resolveRecall space request =+  case request.target of+    ExactScope (ScopeGlobal (Namespace ns)) -> bind ns GlobalBucketOnly+    ExactScope (ScopeEntity (Namespace ns) (ScopeKind kind) ref) ->+      bind ns (EntityScopeOnly kind ref)+    NamespaceWide (Namespace ns) -> bind ns EveryScopeInNamespace+  where+    bind ns bound =+      ResolvedRecall+        { memorySpaceId = space,+          namespace = ns,+          scopeBound = bound,+          query = request.query,+          strategy = request.strategy,+          maxResults = recallLimitInt request.maxResults+        }++-- | The parameters a candidate query takes when its scope predicate needs none of its own:+-- @$1@ the match text, @$2@ the memory space, @$3@ the namespace, @$4@ the row limit.+--+-- Both bounds that use this record — 'GlobalBucketOnly' and 'EveryScopeInNamespace' — carry no+-- scope /values/, and that is precisely why they must not share a statement: they differ by the+-- SQL they compile to, not by a parameter, so which one ran is visible in the statement's name+-- and in its query plan rather than hidden in a NULL.+data BoundedCandidateParams = BoundedCandidateParams+  { match :: !Text,+    memorySpaceId :: !MemorySpaceId,+    namespace :: !Text,     limit :: !Int32   }   deriving stock (Generic, Eq, Show) -data VectorCandidateQuery = VectorCandidateQuery-  { queryVector :: !Text,+-- | 'BoundedCandidateParams' plus the two scope comparisons an entity bound makes: @$4@ the+-- scope kind and @$5@ the scope ref, which moves the row limit to @$6@. Both are non-nullable,+-- so this record cannot express \"no scope filter\" even by accident.+data EntityCandidateParams = EntityCandidateParams+  { match :: !Text,+    memorySpaceId :: !MemorySpaceId,     namespace :: !Text,-    scopeKind :: !(Maybe Text),-    scopeRef :: !(Maybe Text),+    scopeKind :: !Text,+    scopeRef :: !Text,     limit :: !Int32   }   deriving stock (Generic, Eq, Show) +-- | A full-text candidate query, already committed to one of the three statement families.+data FtsCandidateSql+  = FtsInGlobalBucket !BoundedCandidateParams+  | FtsInEntityScope !EntityCandidateParams+  | FtsAcrossNamespace !BoundedCandidateParams+  deriving stock (Generic, Eq, Show)++-- | A vector candidate query, already committed to one of the three statement families. The same+-- value drives the approximate pass, the exact fallback, and the @EXPLAIN@ of the approximate+-- pass, so those three can never describe different queries.+data VectorCandidateSql+  = VectorInGlobalBucket !BoundedCandidateParams+  | VectorInEntityScope !EntityCandidateParams+  | VectorAcrossNamespace !BoundedCandidateParams+  deriving stock (Generic, Eq, Show)+ data FusedCandidate = FusedCandidate   { memory :: !MemoryRecord,     ftsRank :: !(Maybe Int),@@ -157,16 +338,81 @@ -- | Run a recall request: plan, optionally embed the query, select candidates from each -- active channel, fuse by reciprocal rank, score, and trim. ----- Recall searches namespace-wide for a global scope; scoped reads are exact-scope.+-- The memory space searched is 'Kioku.Api.Access.memoryContextSpace' of the context, and nothing+-- in the request can change it. That is why the context is passed here rather than a bare space:+-- a target that widens from one scope to a whole namespace is a retrieval choice, and it must be+-- impossible for that choice to also select whose memories are searched.+--+-- The context is not asked for a second permission. A 'MemoryAccessContext' exists only for+-- permissions 'Kioku.Api.Access.authorizeMemoryAccess' already checked against this space, which+-- is the same reason the read functions below take only a space — see "Kioku.Memory". recall ::   (IOE :> es, Store :> es) =>   EmbeddingModel ->   VectorCapability ->+  MemoryAccessContext ->+  RecallQuery ->+  Eff es (Either RecallError [RecallHit])+recall model capability context request =+  Right <$> runResolvedRecall model capability (resolveRecall (memoryContextSpace context) request)++{-# DEPRECATED legacyRecall "Use recall with a RecallQuery. ScopeGlobal in a RecallRequest means namespace-wide, which is legacyRecallTarget's mapping; the exact global bucket is ExactScope (ScopeGlobal ns)." #-}++-- | Run a pre-'RecallTarget' 'RecallRequest' and return exactly what it returns today.+--+-- The scope is mapped through 'legacyRecallTarget', so a global scope stays namespace-wide. The+-- request's own @memorySpaceId@ must be the one the context authorizes; a request naming another+-- space is refused with 'RecallSpaceMismatch' rather than quietly retargeted, for the same reason+-- the deprecated write wrappers in "Kioku.Memory" refuse rather than rewrite.+--+-- Two edges of @maxResults@ are handled here rather than by 'mkRecallLimit', because this+-- function's contract is "what you get today":+--+-- * a zero or negative limit returns no hits, which is what @take (max 0 n)@ did;+-- * a limit above 'maxRecallLimit' is clamped to it, which is unobservable — each channel+--   contributes at most 50 candidates, so a fused result set holds at most 100 distinct+--   memories and a larger @take@ never had anything more to take.+legacyRecall ::+  (IOE :> es, Store :> es) =>+  EmbeddingModel ->+  VectorCapability ->+  MemoryAccessContext ->   RecallRequest ->+  Eff es (Either RecallError [RecallHit])+legacyRecall model capability context req+  | req.memorySpaceId /= authorized =+      pure (Left (RecallSpaceMismatch req.memorySpaceId authorized))+  | req.maxResults <= 0 = pure (Right [])+  | otherwise =+      recall+        model+        capability+        context+        RecallQuery+          { target = legacyRecallTarget req.scope,+            query = req.query,+            strategy = req.strategy,+            maxResults = legacyRecallLimit req.maxResults+          }+  where+    authorized = memoryContextSpace context++-- | Total by construction: 'legacyRecall' reaches this only with @requested >= 1@, so the+-- 'defaultRecallLimit' fallback is unreachable and exists to keep the function total rather than+-- to define behaviour.+legacyRecallLimit :: Int -> RecallLimit+legacyRecallLimit requested =+  either (const defaultRecallLimit) id (mkRecallLimit (max 1 (min maxRecallLimit requested)))++runResolvedRecall ::+  (IOE :> es, Store :> es) =>+  EmbeddingModel ->+  VectorCapability ->+  ResolvedRecall ->   Eff es [RecallHit]-recall model capability req = do+runResolvedRecall model capability resolved = do   now <- liftIO getCurrentTime-  executeRecallPlan now model req (planRecallExecution capability req.strategy)+  executeRecallPlan now model resolved (planRecallExecution capability resolved.strategy)  planRecallExecution :: VectorCapability -> RecallStrategy -> RecallExecutionPlan planRecallExecution capability strategy =@@ -194,7 +440,7 @@   (IOE :> es, Store :> es) =>   UTCTime ->   EmbeddingModel ->-  RecallRequest ->+  ResolvedRecall ->   RecallExecutionPlan ->   Eff es [RecallHit] executeRecallPlan now model req execution@@ -208,7 +454,7 @@   (IOE :> es, Store :> es) =>   UTCTime ->   EmbeddingModel ->-  RecallRequest ->+  ResolvedRecall ->   RecallExecutionPlan ->   Eff es [RecallHit] embedThenRecall now model req execution = do@@ -224,7 +470,7 @@ keywordOnly ::   (Store :> es) =>   UTCTime ->-  RecallRequest ->+  ResolvedRecall ->   Eff es [RecallHit] keywordOnly now req = do   ftsRows <- selectFtsCandidates req@@ -234,21 +480,18 @@ selectIf True action = action selectIf False _ = pure [] -finishRecall :: UTCTime -> RecallRequest -> [MemoryRecord] -> [MemoryRecord] -> [RecallHit]+finishRecall :: UTCTime -> ResolvedRecall -> [MemoryRecord] -> [MemoryRecord] -> [RecallHit] finishRecall now req ftsRows vecRows =   applyCharacterBudgets perMemoryCharacterBudget totalCharacterBudget $-    take (max 0 req.maxResults) $+    take req.maxResults $       fuseRecallCandidates now ftsRows vecRows  selectFtsCandidates ::   (Store :> es) =>-  RecallRequest ->+  ResolvedRecall ->   Eff es [MemoryRecord] selectFtsCandidates req =-  runTransaction $-    Tx.statement-      (candidateQuery req)-      selectFtsCandidatesStmt+  runTransaction (runFtsCandidates (ftsCandidateSql req))  -- | What the vector channel did, so that a degraded semantic half stops being invisible. --@@ -278,7 +521,7 @@  selectVectorCandidates ::   (Store :> es) =>-  RecallRequest ->+  ResolvedRecall ->   Vector Double ->   Eff es [MemoryRecord] selectVectorCandidates req queryVector =@@ -319,7 +562,7 @@ -- fills the pool and the fallback never fires, so the common path is unchanged. selectVectorCandidatesDiagnosed ::   (Store :> es) =>-  RecallRequest ->+  ResolvedRecall ->   Vector Double ->   Eff es (VectorChannelOutcome, [MemoryRecord]) selectVectorCandidatesDiagnosed req queryVector =@@ -338,7 +581,7 @@     -- remedy a previous plan prescribed — /does/ move the planner, onto an ANN scan that then     -- starves, which is how this defect was originally mis-diagnosed.     Tx.sql efSearchSetting-    annRows <- Tx.statement query selectVectorCandidatesStmt+    annRows <- runVectorAnnCandidates candidates     if length annRows >= fromIntegral candidatePoolSize       then         pure@@ -350,7 +593,7 @@             annRows           )       else do-        exactRows <- Tx.statement query selectVectorCandidatesExactStmt+        exactRows <- runVectorExactCandidates candidates         pure           ( VectorChannelOutcome               { annRows = length annRows,@@ -360,7 +603,7 @@             exactRows           )   where-    query = vectorCandidateQuery req queryVector+    candidates = vectorCandidateSql req queryVector  -- | @SET LOCAL@, so it lives exactly as long as the transaction the query runs in and cannot -- leak into the rest of the connection.@@ -368,23 +611,43 @@ efSearchSetting =   TE.encodeUtf8 ("SET LOCAL hnsw.ef_search = " <> Text.pack (show candidatePoolSize)) -candidateQuery :: RecallRequest -> RecallCandidateQuery-candidateQuery req =-  RecallCandidateQuery-    { query = req.query,-      namespace = scopeNamespaceText req.scope,-      scopeKind = scopeKindText req.scope,-      scopeRef = scopeRefText req.scope,+-- | Compile a resolved request into a full-text candidate query. The match text is the caller's+-- query, which @websearch_to_tsquery@ reads twice: once to filter and once to rank.+ftsCandidateSql :: ResolvedRecall -> FtsCandidateSql+ftsCandidateSql req =+  case req.scopeBound of+    GlobalBucketOnly -> FtsInGlobalBucket (boundedParams req req.query)+    EntityScopeOnly kind ref -> FtsInEntityScope (entityParams req req.query kind ref)+    EveryScopeInNamespace -> FtsAcrossNamespace (boundedParams req req.query)++-- | Compile a resolved request and an embedded query into a vector candidate query. The match+-- text is the vector literal the @$1::vector@ cast reads.+vectorCandidateSql :: ResolvedRecall -> Vector Double -> VectorCandidateSql+vectorCandidateSql req queryVector =+  case req.scopeBound of+    GlobalBucketOnly -> VectorInGlobalBucket (boundedParams req literal)+    EntityScopeOnly kind ref -> VectorInEntityScope (entityParams req literal kind ref)+    EveryScopeInNamespace -> VectorAcrossNamespace (boundedParams req literal)+  where+    literal = vectorLiteral queryVector++boundedParams :: ResolvedRecall -> Text -> BoundedCandidateParams+boundedParams req match =+  BoundedCandidateParams+    { match,+      memorySpaceId = req.memorySpaceId,+      namespace = req.namespace,       limit = candidatePoolSize     } -vectorCandidateQuery :: RecallRequest -> Vector Double -> VectorCandidateQuery-vectorCandidateQuery req queryVector =-  VectorCandidateQuery-    { queryVector = vectorLiteral queryVector,-      namespace = scopeNamespaceText req.scope,-      scopeKind = scopeKindText req.scope,-      scopeRef = scopeRefText req.scope,+entityParams :: ResolvedRecall -> Text -> Text -> Text -> EntityCandidateParams+entityParams req match scopeKind scopeRef =+  EntityCandidateParams+    { match,+      memorySpaceId = req.memorySpaceId,+      namespace = req.namespace,+      scopeKind,+      scopeRef,       limit = candidatePoolSize     } @@ -517,31 +780,64 @@ clamp01 :: Double -> Double clamp01 = max 0 . min 1 +-- * The three statement families++-- $+-- Every candidate statement is one of nine: three channels (full text, the approximate vector+-- pass, the exact vector pass) times three bounds ('GlobalBucketOnly', 'EntityScopeOnly',+-- 'EveryScopeInNamespace'). They are generated from one SQL template per channel and one scope+-- clause per bound, so the three bounds can only ever differ in the scope clause — the memory+-- space, the namespace and the @status@ filter are written once and cannot drift apart between+-- families.+--+-- The nine exist instead of three parameterised statements because the widening is the security+-- property. A single statement with a nullable scope pair has to spell the predicate+-- @(($4 IS NULL AND $5 IS NULL) OR (scope_kind = $4 AND scope_ref = $5))@, in which passing NULL+-- silently drops the scope filter — so a caller that meant \"the global bucket\" and a caller+-- that meant \"the whole namespace\" issue the identical query with the identical parameters, and+-- neither a reviewer nor a query plan can tell them apart. Splitting them puts the difference in+-- the statement name and in the @Index Cond@.++-- | How a bound is spelled in SQL, and which positional parameter the row limit therefore lands+-- on. An entity bound consumes @$4@ and @$5@ for its comparisons, which pushes its limit to @$6@.+data ScopeClause = ScopeClause+  { predicate :: !Text,+    limitParam :: !Text+  }++globalBucketClause, entityScopeClause, namespaceWideClause :: ScopeClause+globalBucketClause = ScopeClause "AND scope_kind IS NULL AND scope_ref IS NULL" "$4"+entityScopeClause = ScopeClause "AND scope_kind = $4 AND scope_ref = $5" "$6"+namespaceWideClause = ScopeClause "" "$4"++-- | The predicates every candidate query carries before its scope clause: one authorized memory+-- space, one namespace, active rows only. @$1@ is the match text, @$2@ the space, @$3@ the+-- namespace.+--+-- The memory space is first and mandatory in all nine statements. Namespace-wide means every+-- scope in one space, never every space — see+-- @docs\/adr\/namespace-is-not-a-security-boundary.md@.+partitionPredicates :: Text+partitionPredicates =+  "WHERE status = 'active' AND memory_space_id = $2 AND namespace = $3 "+ -- | Full-text candidates. ----- The scope predicate @(($3 IS NULL AND $4 IS NULL) OR (scope_kind = $3 AND scope_ref = $4))@--- is why recall searches namespace-wide for a global scope; scoped reads are exact-scope. For--- a global scope both parameters are NULL, the first disjunct is always true, and the filter--- vanishes. 'Kioku.Memory.ReadModel.selectActiveByScopeStmt' requires the columns to be NULL--- instead. The @ORDER BY@ here is free to carry a recency tiebreak: a GIN index provides no--- ordering, so there is no pathkey to preserve.-selectFtsCandidatesStmt :: Statement RecallCandidateQuery [MemoryRecord]-selectFtsCandidatesStmt =-  preparable-    ( "SELECT "-        <> memoryRecordColumns-        <> """-            FROM kiroku.kioku_memories-           WHERE status = 'active'-             AND namespace = $2-             AND (($3 IS NULL AND $4 IS NULL) OR (scope_kind = $3 AND scope_ref = $4))-             AND content_tsv @@ websearch_to_tsquery('english', $1)-           ORDER BY ts_rank(content_tsv, websearch_to_tsquery('english', $1)) DESC, created_at DESC-           LIMIT $5-           """-    )-    recallCandidateQueryEncoder-    (D.rowList memoryRecordDecoder)+-- The @ORDER BY@ is free to carry a recency tiebreak: a GIN index provides no ordering, so+-- there is no pathkey to preserve.+ftsCandidateQuerySql :: ScopeClause -> Text+ftsCandidateQuerySql scope =+  "SELECT "+    <> memoryRecordColumns+    <> "FROM "+    <> memoriesTable+    <> " "+    <> partitionPredicates+    <> scope.predicate+    <> " AND content_tsv @@ websearch_to_tsquery('english', $1) "+    <> "ORDER BY ts_rank(content_tsv, websearch_to_tsquery('english', $1)) DESC, created_at DESC "+    <> "LIMIT "+    <> scope.limitParam  -- | Vector candidates, ordered by cosine distance and nothing else. --@@ -554,80 +850,140 @@ -- so a caller could not re-break ties anyway, and exact ties between 1536-dimension float -- vectors essentially do not occur. ----- Recall that this is a *post-filtered* ANN scan: the namespace, scope and status predicates--- are applied to rows the index has already chosen by distance. See 'candidatePoolSize' for--- what that costs.------ The scope predicate is the same one 'selectFtsCandidatesStmt' carries: recall searches--- namespace-wide for a global scope; scoped reads are exact-scope.-selectVectorCandidatesStmt :: Statement VectorCandidateQuery [MemoryRecord]-selectVectorCandidatesStmt =-  preparable-    ( "SELECT "-        <> memoryRecordColumns-        <> """-            FROM kiroku.kioku_memories-           WHERE status = 'active'-             AND namespace = $2-             AND (($3 IS NULL AND $4 IS NULL) OR (scope_kind = $3 AND scope_ref = $4))-             AND embedding IS NOT NULL-           ORDER BY embedding <=> $1::vector-           LIMIT $5-           """-    )-    vectorCandidateQueryEncoder-    (D.rowList memoryRecordDecoder)+-- Recall that this is a *post-filtered* ANN scan: the space, namespace, scope and status+-- predicates are applied to rows the index has already chosen by distance. See+-- 'candidatePoolSize' for what that costs and 'selectVectorCandidatesDiagnosed' for the pass+-- that rescues it.+vectorAnnCandidateQuerySql :: ScopeClause -> Text+vectorAnnCandidateQuerySql scope =+  "SELECT "+    <> memoryRecordColumns+    <> "FROM "+    <> memoriesTable+    <> " "+    <> partitionPredicates+    <> scope.predicate+    <> " AND embedding IS NOT NULL "+    <> "ORDER BY embedding <=> $1::vector "+    <> "LIMIT "+    <> scope.limitParam --- | The exact vector scan: every embedded row in the caller's scope, ranked by distance, top-N.+-- | The exact vector scan: every embedded row inside the bound, ranked by distance, top-N. -- It cannot starve, because the filter is applied /before/ the ranking rather than after it. -- -- The @OFFSET 0@ is the whole mechanism and must not be "tidied away". It is an optimisation -- fence: it stops Postgres from pulling the subquery up into the outer query, which in turn stops -- the outer @ORDER BY embedding <=> …@ from reaching the HNSW index. Without it the planner--- flattens the two levels back into 'selectVectorCandidatesStmt' and we are measuring — and+-- flattens the two levels back into 'vectorAnnCandidateQuerySql' and we are measuring — and -- shipping — the very query we are trying to avoid. ----- A @MATERIALIZED@ CTE would also fence it, and was rejected: materialising forces every in-scope+-- A @MATERIALIZED@ CTE would also fence it, and was rejected: materialising forces every in-bound -- row's 1536-dimension embedding into memory (about 6KB each, so ~120MB for a 20000-row scope), -- whereas the fence streams and the top-N sort holds only 50 rows. ----- The predicates are identical to 'selectVectorCandidatesStmt''s, including @embedding IS NOT--- NULL@ — here it is a correctness filter rather than an index-matching one, but it must stay--- either way, since a NULL embedding has no distance to anything.-selectVectorCandidatesExactStmt :: Statement VectorCandidateQuery [MemoryRecord]-selectVectorCandidatesExactStmt =-  preparable-    ( "SELECT "-        <> memoryRecordColumns-        <> """-            FROM (SELECT *-                    FROM kiroku.kioku_memories-                   WHERE status = 'active'-                     AND namespace = $2-                     AND (($3 IS NULL AND $4 IS NULL) OR (scope_kind = $3 AND scope_ref = $4))-                     AND embedding IS NOT NULL-                  OFFSET 0) AS scoped-           ORDER BY embedding <=> $1::vector-           LIMIT $5-           """-    )-    vectorCandidateQueryEncoder-    (D.rowList memoryRecordDecoder)+-- The predicates are identical to the approximate pass's, including @embedding IS NOT NULL@ —+-- here it is a correctness filter rather than an index-matching one, but it must stay either way,+-- since a NULL embedding has no distance to anything.+vectorExactCandidateQuerySql :: ScopeClause -> Text+vectorExactCandidateQuerySql scope =+  "SELECT "+    <> memoryRecordColumns+    <> "FROM (SELECT * FROM "+    <> memoriesTable+    <> " "+    <> partitionPredicates+    <> scope.predicate+    <> " AND embedding IS NOT NULL OFFSET 0) AS scoped "+    <> "ORDER BY embedding <=> $1::vector "+    <> "LIMIT "+    <> scope.limitParam -recallCandidateQueryEncoder :: E.Params RecallCandidateQuery-recallCandidateQueryEncoder =-  ((\q -> q.query) >$< E.param (E.nonNullable E.text))+-- | Run the full-text channel against whichever family the target chose.+--+-- The @case@ is total over 'FtsCandidateSql', so a fourth bound cannot be added without deciding+-- what SQL it compiles to.+runFtsCandidates :: FtsCandidateSql -> Tx.Transaction [MemoryRecord]+runFtsCandidates = \case+  FtsInGlobalBucket params -> Tx.statement params (boundedRows ftsCandidateQuerySql globalBucketClause)+  FtsInEntityScope params -> Tx.statement params (entityRows ftsCandidateQuerySql)+  FtsAcrossNamespace params -> Tx.statement params (boundedRows ftsCandidateQuerySql namespaceWideClause)++-- | Run the approximate vector pass against whichever family the target chose.+runVectorAnnCandidates :: VectorCandidateSql -> Tx.Transaction [MemoryRecord]+runVectorAnnCandidates = \case+  VectorInGlobalBucket params -> Tx.statement params (boundedRows vectorAnnCandidateQuerySql globalBucketClause)+  VectorInEntityScope params -> Tx.statement params (entityRows vectorAnnCandidateQuerySql)+  VectorAcrossNamespace params -> Tx.statement params (boundedRows vectorAnnCandidateQuerySql namespaceWideClause)++-- | Run the exact vector pass against whichever family the target chose.+runVectorExactCandidates :: VectorCandidateSql -> Tx.Transaction [MemoryRecord]+runVectorExactCandidates = \case+  VectorInGlobalBucket params -> Tx.statement params (boundedRows vectorExactCandidateQuerySql globalBucketClause)+  VectorInEntityScope params -> Tx.statement params (entityRows vectorExactCandidateQuerySql)+  VectorAcrossNamespace params -> Tx.statement params (boundedRows vectorExactCandidateQuerySql namespaceWideClause)++-- | @EXPLAIN (ANALYZE, BUFFERS)@ over the full-text channel, built from the same SQL text and+-- given the same parameters as 'runFtsCandidates'.+explainFtsCandidates :: FtsCandidateSql -> Tx.Transaction [Text]+explainFtsCandidates = \case+  FtsInGlobalBucket params -> Tx.statement params (boundedPlan ftsCandidateQuerySql globalBucketClause)+  FtsInEntityScope params -> Tx.statement params (entityPlan ftsCandidateQuerySql)+  FtsAcrossNamespace params -> Tx.statement params (boundedPlan ftsCandidateQuerySql namespaceWideClause)++-- | @EXPLAIN (ANALYZE, BUFFERS)@ over the approximate vector pass, built from the same SQL text+-- and given the same parameters as 'runVectorAnnCandidates'. See the test-seam note at the top of+-- this module for why these live here rather than in the harness that uses them.+explainVectorAnnCandidates :: VectorCandidateSql -> Tx.Transaction [Text]+explainVectorAnnCandidates = explainVector vectorAnnCandidateQuerySql++-- | @EXPLAIN (ANALYZE, BUFFERS)@ over the exact vector pass — the one whose access path is a+-- scan of the bound rather than of the embedding index, and therefore the one where a+-- partition-leading index earns its keep.+explainVectorExactCandidates :: VectorCandidateSql -> Tx.Transaction [Text]+explainVectorExactCandidates = explainVector vectorExactCandidateQuerySql++explainVector :: (ScopeClause -> Text) -> VectorCandidateSql -> Tx.Transaction [Text]+explainVector sqlFor = \case+  VectorInGlobalBucket params -> Tx.statement params (boundedPlan sqlFor globalBucketClause)+  VectorInEntityScope params -> Tx.statement params (entityPlan sqlFor)+  VectorAcrossNamespace params -> Tx.statement params (boundedPlan sqlFor namespaceWideClause)++boundedPlan :: (ScopeClause -> Text) -> ScopeClause -> Statement BoundedCandidateParams [Text]+boundedPlan sqlFor scope =+  preparable (explained (sqlFor scope)) boundedCandidateEncoder planDecoder++entityPlan :: (ScopeClause -> Text) -> Statement EntityCandidateParams [Text]+entityPlan sqlFor =+  preparable (explained (sqlFor entityScopeClause)) entityCandidateEncoder planDecoder++explained :: Text -> Text+explained sql = "EXPLAIN (ANALYZE, BUFFERS) " <> sql++planDecoder :: D.Result [Text]+planDecoder = D.rowList (D.column (D.nonNullable D.text))++boundedRows :: (ScopeClause -> Text) -> ScopeClause -> Statement BoundedCandidateParams [MemoryRecord]+boundedRows sqlFor scope =+  preparable (sqlFor scope) boundedCandidateEncoder (D.rowList memoryRecordDecoder)++entityRows :: (ScopeClause -> Text) -> Statement EntityCandidateParams [MemoryRecord]+entityRows sqlFor =+  preparable (sqlFor entityScopeClause) entityCandidateEncoder (D.rowList memoryRecordDecoder)++boundedCandidateEncoder :: E.Params BoundedCandidateParams+boundedCandidateEncoder =+  ((\q -> q.match) >$< E.param (E.nonNullable E.text))+    <> ((\q -> q.memorySpaceId) >$< memorySpaceParam)     <> ((\q -> q.namespace) >$< E.param (E.nonNullable E.text))-    <> ((\q -> q.scopeKind) >$< E.param (E.nullable E.text))-    <> ((\q -> q.scopeRef) >$< E.param (E.nullable E.text))     <> ((\q -> q.limit) >$< E.param (E.nonNullable E.int4)) -vectorCandidateQueryEncoder :: E.Params VectorCandidateQuery-vectorCandidateQueryEncoder =-  ((\q -> q.queryVector) >$< E.param (E.nonNullable E.text))+entityCandidateEncoder :: E.Params EntityCandidateParams+entityCandidateEncoder =+  ((\q -> q.match) >$< E.param (E.nonNullable E.text))+    <> ((\q -> q.memorySpaceId) >$< memorySpaceParam)     <> ((\q -> q.namespace) >$< E.param (E.nonNullable E.text))-    <> ((\q -> q.scopeKind) >$< E.param (E.nullable E.text))-    <> ((\q -> q.scopeRef) >$< E.param (E.nullable E.text))+    <> ((\q -> q.scopeKind) >$< E.param (E.nonNullable E.text))+    <> ((\q -> q.scopeRef) >$< E.param (E.nonNullable E.text))     <> ((\q -> q.limit) >$< E.param (E.nonNullable E.int4))  memoryRecordColumns :: Text@@ -771,55 +1127,82 @@ -- not by this. For the read-side equivalent of recall's breadth, use 'getActiveInNamespace'. getActiveByScope ::   (IOE :> es, Store :> es) =>+  MemorySpaceId ->   MemoryScope ->   Eff es (Either ReadModelError [MemoryRecord])-getActiveByScope scope =+getActiveByScope space scope =   runQueryWith     Nothing     Eventual     memoriesByScopeReadModel-    (MemoriesByScopeQuery (scopeNamespaceText scope) (scopeKindText scope) (scopeRefText scope))+    MemoriesByScopeQuery+      { memorySpaceId = space,+        namespace = scopeNamespaceText scope,+        scopeKind = scopeKindText scope,+        scopeRef = scopeRefText scope+      }  -- | Every active memory in the namespace, whatever its scope. This is the read-side--- equivalent of what 'recall' does with a global scope.+-- equivalent of what 'recall' does with a global scope — inside one memory space. getActiveInNamespace ::   (IOE :> es, Store :> es) =>+  MemorySpaceId ->   Namespace ->   Eff es (Either ReadModelError [MemoryRecord])-getActiveInNamespace (Namespace ns) =-  runQueryWith Nothing Eventual memoriesByNamespaceReadModel (MemoriesByNamespaceQuery ns)+getActiveInNamespace space (Namespace ns) =+  runQueryWith+    Nothing+    Eventual+    memoriesByNamespaceReadModel+    MemoriesByNamespaceQuery {memorySpaceId = space, namespace = ns}  -- | The global bucket of a namespace: rows recorded with no entity scope. Not the same as a -- 'recall' scoped to the namespace, which also returns entity-scoped rows. getGlobal ::   (IOE :> es, Store :> es) =>+  MemorySpaceId ->   Namespace ->   Eff es (Either ReadModelError [MemoryRecord])-getGlobal ns =-  getActiveByScope (ScopeGlobal ns)+getGlobal space ns =+  getActiveByScope space (ScopeGlobal ns)  getById ::   (IOE :> es, Store :> es) =>+  MemorySpaceId ->   MemoryId ->   Eff es (Either ReadModelError (Maybe MemoryRecord))-getById mid =+getById space mid =   fmap (fmap (fmap memoryRowToRecord)) $-    runQueryWith Nothing Eventual memoryByIdReadModel (MemoryByIdQuery (idText mid))+    runQueryWith+      Nothing+      Eventual+      memoryByIdReadModel+      MemoryByIdQuery {memorySpaceId = space, memoryId = idText mid}  getBySession ::   (IOE :> es, Store :> es) =>+  MemorySpaceId ->   SessionId ->   Eff es (Either ReadModelError [MemoryRecord])-getBySession sid =-  runQueryWith Nothing Eventual memoriesBySessionReadModel (MemoriesBySessionQuery (idText sid))+getBySession space sid =+  runQueryWith+    Nothing+    Eventual+    memoriesBySessionReadModel+    MemoriesBySessionQuery {memorySpaceId = space, sessionId = idText sid}  getByType ::   (IOE :> es, Store :> es) =>+  MemorySpaceId ->   Namespace ->   MemoryType ->   Eff es (Either ReadModelError [MemoryRecord])-getByType (Namespace ns) mt =-  runQueryWith Nothing Eventual memoriesByTypeReadModel (MemoriesByTypeQuery ns (memoryTypeToText mt))+getByType space (Namespace ns) mt =+  runQueryWith+    Nothing+    Eventual+    memoriesByTypeReadModel+    MemoriesByTypeQuery {memorySpaceId = space, namespace = ns, memoryType = memoryTypeToText mt}  memoryRowToRecord :: MemoryRow -> MemoryRecord memoryRowToRecord row =

@@ -21,7 +21,7 @@   | VectorExtensionUnavailable   | VectorColumnsUnavailable ![Text]   | -- | @KIOKU_EMBEDDING_DIMENSIONS@ disagrees with the declared width of the-    -- @kioku_memories.embedding@ column: configured first, actual second. Every embedding+    -- @kioku.memories.embedding@ column: configured first, actual second. Every embedding     -- write would fail on the @::vector@ cast, one event at a time, forever.     VectorDimensionMismatch !Int !Int   deriving stock (Generic, Eq, Show)@@ -80,6 +80,12 @@ -- query would fail with @42704@ while capability detection reported everything healthy. -- @to_regtype@ resolves against the live @search_path@, which is exactly the question the -- query asks.+--+-- The column probes name @kioku.memories@ because that is where the projection lives; the+-- @vector@ type probe deliberately does /not/ name a schema, because the extension was never+-- moved and its resolution is still whatever the connection's search path makes it. Those two+-- questions are separate on purpose — see+-- @docs\/adr\/projections-live-in-the-kioku-schema.md@. detectVectorCapabilityStmt :: Statement () CapabilityProbe detectVectorCapabilityStmt =   preparable@@ -89,30 +95,30 @@       EXISTS (         SELECT 1         FROM information_schema.columns-        WHERE table_schema = 'kiroku' AND table_name = 'kioku_memories' AND column_name = 'embedding'+        WHERE table_schema = 'kioku' AND table_name = 'memories' AND column_name = 'embedding'       ) AS has_embedding,       EXISTS (         SELECT 1         FROM information_schema.columns-        WHERE table_schema = 'kiroku' AND table_name = 'kioku_memories' AND column_name = 'embedding_model'+        WHERE table_schema = 'kioku' AND table_name = 'memories' AND column_name = 'embedding_model'       ) AS has_embedding_model,       EXISTS (         SELECT 1         FROM information_schema.columns-        WHERE table_schema = 'kiroku' AND table_name = 'kioku_memories' AND column_name = 'dimensions'+        WHERE table_schema = 'kioku' AND table_name = 'memories' AND column_name = 'dimensions'       ) AS has_dimensions,       EXISTS (         SELECT 1         FROM information_schema.columns-        WHERE table_schema = 'kiroku' AND table_name = 'kioku_memories' AND column_name = 'content_hash'+        WHERE table_schema = 'kioku' AND table_name = 'memories' AND column_name = 'content_hash'       ) AS has_content_hash,       (         SELECT a.atttypmod         FROM pg_attribute a         JOIN pg_class c ON c.oid = a.attrelid         JOIN pg_namespace n ON n.oid = c.relnamespace-        WHERE n.nspname = 'kiroku'-          AND c.relname = 'kioku_memories'+        WHERE n.nspname = 'kioku'+          AND c.relname = 'memories'           AND a.attname = 'embedding'           AND NOT a.attisdropped       ) AS embedding_typmod

@@ -1,6 +1,33 @@+-- | Starting, driving, and reading agent sessions.+--+-- Every write takes a 'MemoryAccessContext' first, for the reasons set out in "Kioku.Memory":+-- Kioku's core never decides who may write where, it only refuses to write without a decision.+-- All session writes ask for the 'MemoryRecord' permission — a session, its turns, and its+-- lifecycle are memory being recorded.+--+-- A session belongs to the space it was started in, and the aggregate refuses every later+-- command that names a different one. That includes 'forceResumeWithContext': waiving the+-- correlation-key check is an operator override for a lost key, not for the isolation boundary.+--+-- The unsuffixed functions ('start', 'complete', …) remain for one release as deprecated+-- compatibility wrappers confined to 'legacyMemorySpaceId'. Every read takes a 'MemorySpaceId'+-- first and returns nothing outside it; see "Kioku.Memory" for why it takes the space rather+-- than the whole context, and @docs\/user\/upgrading-to-memory-spaces.md@ for the upgrade. module Kioku.Session   ( SessionRow (..),     SessionWriteError (..),++    -- * Writing sessions+    startWithContext,+    awaitInputWithContext,+    resumeWithContext,+    forceResumeWithContext,+    completeWithContext,+    failSessionWithContext,+    recordInteractiveWithContext,+    recordTurnWithContext,++    -- * Deprecated compatibility wrappers, confined to the legacy memory space     start,     awaitInput,     resume,@@ -9,6 +36,8 @@     failSession,     recordInteractive,     recordTurn,++    -- * Reading sessions     getById,     getRecentInNamespace,     getByScope,@@ -28,6 +57,16 @@ import Keiro.Command (CommandError (..), defaultRunCommandOptions) import Keiro.Projection (runCommandWithProjections) import Keiro.ReadModel (ConsistencyMode (..), ReadModelError, runQueryWith)+import Kioku.Api.Access+  ( MemoryAccessContext,+    MemoryPermission (..),+    MemorySpaceId,+    RecordedPrincipal (..),+    legacyMemorySpaceId,+    memoryContextAllows,+    memoryContextRecordedActor,+    memoryContextSpace,+  ) import Kioku.Api.Scope (MemoryScope, Namespace (..), scopeKindText, scopeNamespaceText, scopeRefText) import Kioku.Distill.Timer (l1TimerScheduleProjection) import Kioku.Id (SessionId, idText)@@ -70,28 +109,86 @@   | SessionCorrelationMismatch   | SessionInvalidLineage !Text   | SessionConflict !Text+  | -- | the context authorized other actions, but not this one+    SessionNotPermitted !MemoryPermission+  | -- | the command names a memory space the context was not minted for:+    -- @SessionSpaceMismatch requested authorized@+    SessionSpaceMismatch !MemorySpaceId !MemorySpaceId+  | -- | the command attributes the write to somebody other than the context's own principal+    SessionActorMismatch !RecordedPrincipal !RecordedPrincipal   deriving stock (Generic, Show) +-- | Gate a write on the decision that authorized it. See 'Kioku.Memory.underContext' — same+-- three checks, same reasons: a context minted for one action cannot be spent on another, on+-- another space, or in somebody else's name.+underContext ::+  (Applicative f) =>+  MemoryAccessContext ->+  MemoryPermission ->+  MemorySpaceId ->+  RecordedPrincipal ->+  f (Either SessionWriteError a) ->+  f (Either SessionWriteError a)+underContext context permission space actor run+  | not (memoryContextAllows permission context) =+      pure (Left (SessionNotPermitted permission))+  | space /= authorizedSpace =+      pure (Left (SessionSpaceMismatch space authorizedSpace))+  | actor /= authorizedActor =+      pure (Left (SessionActorMismatch actor authorizedActor))+  | otherwise = run+  where+    authorizedSpace = memoryContextSpace context+    authorizedActor = memoryContextRecordedActor context++-- | Gate a deprecated wrapper on the one space it is allowed to touch.+inLegacySpaceOnly ::+  (Applicative f) =>+  MemorySpaceId ->+  f (Either SessionWriteError a) ->+  f (Either SessionWriteError a)+inLegacySpaceOnly space run+  | space /= legacyMemorySpaceId = pure (Left (SessionSpaceMismatch space legacyMemorySpaceId))+  | otherwise = run+ -- | The deepest delegation chain a session may declare. Far above any legitimate agent -- hierarchy; it exists to bound absurd input, not to express a product limit. maxDelegationDepth :: Int maxDelegationDepth = 64 +-- | Start a session in the space the context authorizes.+startWithContext ::+  (IOE :> es, KirokuStoreResource :> es, Store :> es, Error StoreError :> es) =>+  MemoryAccessContext ->+  StartSessionData ->+  Eff es (Either SessionWriteError SessionId)+startWithContext context cmdData =+  underContext context MemoryRecord cmdData.memorySpaceId cmdData.actorPrincipal (startIn cmdData)++{-# DEPRECATED start "Use startWithContext. This wrapper accepts only legacyMemorySpaceId and will be removed." #-}++-- | Deprecated: start a session in the legacy memory space, with no authorization context. start ::   (IOE :> es, KirokuStoreResource :> es, Store :> es, Error StoreError :> es) =>   StartSessionData ->   Eff es (Either SessionWriteError SessionId)-start cmdData =+start cmdData = inLegacySpaceOnly cmdData.memorySpaceId (startIn cmdData)++startIn ::+  (IOE :> es, KirokuStoreResource :> es, Store :> es, Error StoreError :> es) =>+  StartSessionData ->+  Eff es (Either SessionWriteError SessionId)+startIn cmdData =   case validateLineage cmdData of     Just reason -> pure (Left (SessionInvalidLineage reason))     Nothing -> do-      existing <- getById cmdData.sessionId+      existing <- getById cmdData.memorySpaceId cmdData.sessionId       case existing of         Left err -> pure (Left (SessionReadFailed err))         Right (Just row) -> pure (idempotentOr "start" startMismatch row cmdData.sessionId)         Right Nothing ->           runSessionCommand cmdData.sessionId (StartSession cmdData)-            >>= acceptRejectedIfMatches cmdData.sessionId (isNothing . startMismatch)+            >>= acceptRejectedIfMatches cmdData.memorySpaceId cmdData.sessionId (isNothing . startMismatch)   where     startMismatch = mismatchOf sessionStartFields cmdData @@ -146,11 +243,12 @@ -- | Look up the session and hand its row plus parsed status to the caller. withExistingSession ::   (IOE :> es, Store :> es) =>+  MemorySpaceId ->   SessionId ->   (SessionRow -> SessionStatus -> Eff es (Either SessionWriteError SessionId)) ->   Eff es (Either SessionWriteError SessionId)-withExistingSession sid k = do-  existing <- getById sid+withExistingSession space sid k = do+  existing <- getById space sid   case existing of     Left err -> pure (Left (SessionReadFailed err))     Right Nothing -> pure (Left SessionNotFound)@@ -200,13 +298,14 @@ -- genuinely conflicting loser still gets its rejection. acceptRejectedIfMatches ::   (IOE :> es, Store :> es) =>+  MemorySpaceId ->   SessionId ->   (SessionRow -> Bool) ->   Either SessionWriteError SessionId ->   Eff es (Either SessionWriteError SessionId)-acceptRejectedIfMatches sid matches = \case+acceptRejectedIfMatches space sid matches = \case   Left err@(SessionCommandRejected CommandRejected) -> do-    reread <- getById sid+    reread <- getById space sid     pure case reread of       Right (Just row) | matches row -> Right sid       _ -> Left err@@ -257,12 +356,30 @@ sessionFailFields =   [("errorMessage", \d row -> row.errorMessage == Just d.errorMessage)] +-- | Complete a session in the space the context authorizes.+completeWithContext ::+  (IOE :> es, KirokuStoreResource :> es, Store :> es, Error StoreError :> es) =>+  MemoryAccessContext ->+  CompleteSessionData ->+  Eff es (Either SessionWriteError SessionId)+completeWithContext context cmdData =+  underContext context MemoryRecord cmdData.memorySpaceId cmdData.actorPrincipal (completeIn cmdData)++{-# DEPRECATED complete "Use completeWithContext. This wrapper accepts only legacyMemorySpaceId and will be removed." #-}++-- | Deprecated: complete within the legacy memory space, with no authorization context. complete ::   (IOE :> es, KirokuStoreResource :> es, Store :> es, Error StoreError :> es) =>   CompleteSessionData ->   Eff es (Either SessionWriteError SessionId)-complete cmdData =-  withExistingSession cmdData.sessionId \row status ->+complete cmdData = inLegacySpaceOnly cmdData.memorySpaceId (completeIn cmdData)++completeIn ::+  (IOE :> es, KirokuStoreResource :> es, Store :> es, Error StoreError :> es) =>+  CompleteSessionData ->+  Eff es (Either SessionWriteError SessionId)+completeIn cmdData =+  withExistingSession cmdData.memorySpaceId cmdData.sessionId \row status ->     case status of       StatusRunning -> runComplete       StatusAwaiting -> runComplete@@ -274,14 +391,32 @@     completeMismatch = mismatchOf sessionCompleteFields cmdData     runComplete =       runSessionCommand cmdData.sessionId (CompleteSession cmdData)-        >>= acceptRejectedIfMatches cmdData.sessionId (isNothing . completeMismatch)+        >>= acceptRejectedIfMatches cmdData.memorySpaceId cmdData.sessionId (isNothing . completeMismatch) +-- | Fail a session in the space the context authorizes.+failSessionWithContext ::+  (IOE :> es, KirokuStoreResource :> es, Store :> es, Error StoreError :> es) =>+  MemoryAccessContext ->+  FailSessionData ->+  Eff es (Either SessionWriteError SessionId)+failSessionWithContext context cmdData =+  underContext context MemoryRecord cmdData.memorySpaceId cmdData.actorPrincipal (failSessionIn cmdData)++{-# DEPRECATED failSession "Use failSessionWithContext. This wrapper accepts only legacyMemorySpaceId and will be removed." #-}++-- | Deprecated: fail within the legacy memory space, with no authorization context. failSession ::   (IOE :> es, KirokuStoreResource :> es, Store :> es, Error StoreError :> es) =>   FailSessionData ->   Eff es (Either SessionWriteError SessionId)-failSession cmdData =-  withExistingSession cmdData.sessionId \row status ->+failSession cmdData = inLegacySpaceOnly cmdData.memorySpaceId (failSessionIn cmdData)++failSessionIn ::+  (IOE :> es, KirokuStoreResource :> es, Store :> es, Error StoreError :> es) =>+  FailSessionData ->+  Eff es (Either SessionWriteError SessionId)+failSessionIn cmdData =+  withExistingSession cmdData.memorySpaceId cmdData.sessionId \row status ->     case status of       StatusRunning -> runFail       StatusAwaiting -> runFail@@ -294,19 +429,37 @@     failMismatch = mismatchOf sessionFailFields cmdData     runFail =       runSessionCommand cmdData.sessionId (FailSession cmdData)-        >>= acceptRejectedIfMatches cmdData.sessionId (isNothing . failMismatch)+        >>= acceptRejectedIfMatches cmdData.memorySpaceId cmdData.sessionId (isNothing . failMismatch) +-- | Park a session in the space the context authorizes.+awaitInputWithContext ::+  (IOE :> es, KirokuStoreResource :> es, Store :> es, Error StoreError :> es) =>+  MemoryAccessContext ->+  AwaitInputData ->+  Eff es (Either SessionWriteError SessionId)+awaitInputWithContext context cmdData =+  underContext context MemoryRecord cmdData.memorySpaceId cmdData.actorPrincipal (awaitInputIn cmdData)++{-# DEPRECATED awaitInput "Use awaitInputWithContext. This wrapper accepts only legacyMemorySpaceId and will be removed." #-}++-- | Deprecated: park within the legacy memory space, with no authorization context. awaitInput ::   (IOE :> es, KirokuStoreResource :> es, Store :> es, Error StoreError :> es) =>   AwaitInputData ->   Eff es (Either SessionWriteError SessionId)-awaitInput cmdData =-  withExistingSession cmdData.sessionId \row status ->+awaitInput cmdData = inLegacySpaceOnly cmdData.memorySpaceId (awaitInputIn cmdData)++awaitInputIn ::+  (IOE :> es, KirokuStoreResource :> es, Store :> es, Error StoreError :> es) =>+  AwaitInputData ->+  Eff es (Either SessionWriteError SessionId)+awaitInputIn cmdData =+  withExistingSession cmdData.memorySpaceId cmdData.sessionId \row status ->     case status of       StatusAwaiting -> pure (idempotentOr "awaitInput" awaitMismatch row cmdData.sessionId)       StatusRunning ->         runSessionCommand cmdData.sessionId (AwaitInput cmdData)-          >>= acceptRejectedIfMatches cmdData.sessionId (isNothing . awaitMismatch)+          >>= acceptRejectedIfMatches cmdData.memorySpaceId cmdData.sessionId (isNothing . awaitMismatch)       _ -> pure (Left SessionNotRunning)   where     awaitMismatch = mismatchOf sessionAwaitFields cmdData@@ -320,12 +473,29 @@ -- The precheck below only shapes a friendly early error. The real enforcement is the -- aggregate's own guard, which keiro re-evaluates after any optimistic-concurrency retry — -- so a stale caller cannot resume a wait that was already resumed and re-parked.+resumeWithContext ::+  (IOE :> es, KirokuStoreResource :> es, Store :> es, Error StoreError :> es) =>+  MemoryAccessContext ->+  ResumeSessionData ->+  Eff es (Either SessionWriteError SessionId)+resumeWithContext context cmdData =+  underContext context MemoryRecord cmdData.memorySpaceId cmdData.actorPrincipal (resumeIn cmdData)++{-# DEPRECATED resume "Use resumeWithContext. This wrapper accepts only legacyMemorySpaceId and will be removed." #-}++-- | Deprecated: resume within the legacy memory space, with no authorization context. resume ::   (IOE :> es, KirokuStoreResource :> es, Store :> es, Error StoreError :> es) =>   ResumeSessionData ->   Eff es (Either SessionWriteError SessionId)-resume cmdData =-  withExistingSession cmdData.sessionId \row status ->+resume cmdData = inLegacySpaceOnly cmdData.memorySpaceId (resumeIn cmdData)++resumeIn ::+  (IOE :> es, KirokuStoreResource :> es, Store :> es, Error StoreError :> es) =>+  ResumeSessionData ->+  Eff es (Either SessionWriteError SessionId)+resumeIn cmdData =+  withExistingSession cmdData.memorySpaceId cmdData.sessionId \row status ->     case status of       -- Already running: a re-delivery of *this* resume is a success; a different input       -- means someone else answered the wait, which is a conflict, not an idempotent hit.@@ -335,7 +505,7 @@             pure (Left SessionCorrelationMismatch)         | otherwise ->             runSessionCommand cmdData.sessionId (ResumeSession cmdData)-              >>= acceptRejectedIfMatches cmdData.sessionId (isNothing . resumeMismatch)+              >>= acceptRejectedIfMatches cmdData.memorySpaceId cmdData.sessionId (isNothing . resumeMismatch)       _ -> pure (Left SessionNotAwaiting)   where     resumeMismatch = mismatchOf sessionResumeFields cmdData@@ -344,7 +514,25 @@ -- -- An operator/host override for unsticking a session whose awaited key is lost or wrong. -- It is inherently last-writer-wins: if the session is concurrently re-parked on a new--- wait, a force resume may answer the wrong one. Prefer 'resume'.+-- wait, a force resume may answer the wrong one. Prefer 'resumeWithContext'.+--+-- @force@ waives the correlation-key check and nothing else. The session must still belong to+-- the space this context authorizes, and the aggregate enforces that independently.+forceResumeWithContext ::+  (IOE :> es, KirokuStoreResource :> es, Store :> es, Error StoreError :> es) =>+  MemoryAccessContext ->+  SessionId ->+  Text ->+  UTCTime ->+  Eff es (Either SessionWriteError SessionId)+forceResumeWithContext context sid input resumedAt =+  resumeWithContext+    context+    (forcedResumeData (memoryContextSpace context) (memoryContextRecordedActor context) sid input resumedAt)++{-# DEPRECATED forceResume "Use forceResumeWithContext. This wrapper acts only in legacyMemorySpaceId and will be removed." #-}++-- | Deprecated: force-resume within the legacy memory space, with no authorization context. forceResume ::   (IOE :> es, KirokuStoreResource :> es, Store :> es, Error StoreError :> es) =>   SessionId ->@@ -352,27 +540,50 @@   UTCTime ->   Eff es (Either SessionWriteError SessionId) forceResume sid input resumedAt =-  resume-    ResumeSessionData-      { sessionId = sid,-        correlationKey = Nothing,-        force = True,-        input,-        resumedAt-      }+  resumeIn (forcedResumeData legacyMemorySpaceId UnattributedPrincipal sid input resumedAt) +forcedResumeData :: MemorySpaceId -> RecordedPrincipal -> SessionId -> Text -> UTCTime -> ResumeSessionData+forcedResumeData memorySpaceId actorPrincipal sid input resumedAt =+  ResumeSessionData+    { sessionId = sid,+      memorySpaceId,+      actorPrincipal,+      correlationKey = Nothing,+      force = True,+      input,+      resumedAt+    }++-- | Record an interactive session in the space the context authorizes.+recordInteractiveWithContext ::+  (IOE :> es, KirokuStoreResource :> es, Store :> es, Error StoreError :> es) =>+  MemoryAccessContext ->+  RecordInteractiveSessionData ->+  Eff es (Either SessionWriteError SessionId)+recordInteractiveWithContext context cmdData =+  underContext context MemoryRecord cmdData.memorySpaceId cmdData.actorPrincipal (recordInteractiveIn cmdData)++{-# DEPRECATED recordInteractive "Use recordInteractiveWithContext. This wrapper accepts only legacyMemorySpaceId and will be removed." #-}++-- | Deprecated: record an interactive session in the legacy memory space, with no context. recordInteractive ::   (IOE :> es, KirokuStoreResource :> es, Store :> es, Error StoreError :> es) =>   RecordInteractiveSessionData ->   Eff es (Either SessionWriteError SessionId)-recordInteractive cmdData = do-  existing <- getById cmdData.sessionId+recordInteractive cmdData = inLegacySpaceOnly cmdData.memorySpaceId (recordInteractiveIn cmdData)++recordInteractiveIn ::+  (IOE :> es, KirokuStoreResource :> es, Store :> es, Error StoreError :> es) =>+  RecordInteractiveSessionData ->+  Eff es (Either SessionWriteError SessionId)+recordInteractiveIn cmdData = do+  existing <- getById cmdData.memorySpaceId cmdData.sessionId   case existing of     Left err -> pure (Left (SessionReadFailed err))     Right (Just row) -> pure (idempotentOr "recordInteractive" interactiveMismatch row cmdData.sessionId)     Right Nothing ->       runSessionCommand cmdData.sessionId (RecordInteractiveSession cmdData)-        >>= acceptRejectedIfMatches cmdData.sessionId (isNothing . interactiveMismatch)+        >>= acceptRejectedIfMatches cmdData.memorySpaceId cmdData.sessionId (isNothing . interactiveMismatch)   where     interactiveMismatch = mismatchOf sessionInteractiveFields cmdData @@ -387,15 +598,32 @@ -- surfaced as @StoreFailed@: turn ids are host-generated, so a cross-session collision is a -- caller bug, and mapping that specific SQL error from inside keiro's projection -- transaction is not worth the machinery.+recordTurnWithContext ::+  (IOE :> es, KirokuStoreResource :> es, Store :> es, Error StoreError :> es) =>+  MemoryAccessContext ->+  RecordTurnData ->+  Eff es (Either SessionWriteError SessionId)+recordTurnWithContext context cmdData =+  underContext context MemoryRecord cmdData.memorySpaceId cmdData.actorPrincipal (recordTurnIn cmdData)++{-# DEPRECATED recordTurn "Use recordTurnWithContext. This wrapper accepts only legacyMemorySpaceId and will be removed." #-}++-- | Deprecated: record a turn within the legacy memory space, with no authorization context. recordTurn ::   (IOE :> es, KirokuStoreResource :> es, Store :> es, Error StoreError :> es) =>   RecordTurnData ->   Eff es (Either SessionWriteError SessionId)-recordTurn cmdData =-  withExistingSession cmdData.sessionId \_row status ->+recordTurn cmdData = inLegacySpaceOnly cmdData.memorySpaceId (recordTurnIn cmdData)++recordTurnIn ::+  (IOE :> es, KirokuStoreResource :> es, Store :> es, Error StoreError :> es) =>+  RecordTurnData ->+  Eff es (Either SessionWriteError SessionId)+recordTurnIn cmdData =+  withExistingSession cmdData.memorySpaceId cmdData.sessionId \_row status ->     case status of       StatusRunning -> do-        turns <- getTurns cmdData.sessionId+        turns <- getTurns cmdData.memorySpaceId cmdData.sessionId         case turns of           Left err -> pure (Left (SessionReadFailed err))           Right existingTurns ->@@ -415,7 +643,7 @@   Eff es (Either SessionWriteError SessionId) acceptRejectedTurnIfMatches d = \case   Left err@(SessionCommandRejected CommandRejected) -> do-    turns <- getTurns d.sessionId+    turns <- getTurns d.memorySpaceId d.sessionId     pure case turns of       Right rows         | Just row <- find (\row -> row.turnIndex == d.turnIndex) rows,@@ -450,78 +678,133 @@  getById ::   (IOE :> es, Store :> es) =>+  MemorySpaceId ->   SessionId ->   Eff es (Either ReadModelError (Maybe SessionRow))-getById sid =-  runQueryWith Nothing Eventual sessionByIdReadModel (SessionByIdQuery (idText sid))+getById space sid =+  runQueryWith+    Nothing+    Eventual+    sessionByIdReadModel+    SessionByIdQuery {memorySpaceId = space, sessionId = idText sid}  getRecentInNamespace ::   (IOE :> es, Store :> es) =>+  MemorySpaceId ->   Namespace ->   Int ->   Eff es (Either ReadModelError [SessionRow])-getRecentInNamespace ns limit =-  runQueryWith Nothing Eventual sessionsByNamespaceReadModel (SessionsByNamespaceQuery (namespaceText ns) limit)+getRecentInNamespace space ns limit =+  runQueryWith+    Nothing+    Eventual+    sessionsByNamespaceReadModel+    SessionsByNamespaceQuery {memorySpaceId = space, namespace = namespaceText ns, limit}  getByScope ::   (IOE :> es, Store :> es) =>+  MemorySpaceId ->   MemoryScope ->   Eff es (Either ReadModelError [SessionRow])-getByScope scope =+getByScope space scope =   runQueryWith     Nothing     Eventual     sessionsByScopeReadModel-    (SessionsByScopeQuery (scopeNamespaceText scope) (scopeKindText scope) (scopeRefText scope))+    SessionsByScopeQuery+      { memorySpaceId = space,+        namespace = scopeNamespaceText scope,+        scopeKind = scopeKindText scope,+        scopeRef = scopeRefText scope+      }  getByFocus ::   (IOE :> es, Store :> es) =>+  MemorySpaceId ->   Namespace ->   Text ->   Eff es (Either ReadModelError [SessionRow])-getByFocus ns focus =-  runQueryWith Nothing Eventual sessionsByFocusReadModel (SessionsByFocusQuery (namespaceText ns) focus)+getByFocus space ns focus =+  runQueryWith+    Nothing+    Eventual+    sessionsByFocusReadModel+    SessionsByFocusQuery {memorySpaceId = space, namespace = namespaceText ns, focus}  getByStartedRange ::   (IOE :> es, Store :> es) =>+  MemorySpaceId ->   Namespace ->   UTCTime ->   UTCTime ->   Eff es (Either ReadModelError [SessionRow])-getByStartedRange ns startedAfter startedBefore =-  runQueryWith Nothing Eventual sessionsByStartedRangeReadModel (SessionsByStartedRangeQuery (namespaceText ns) startedAfter startedBefore)+getByStartedRange space ns startedAfter startedBefore =+  runQueryWith+    Nothing+    Eventual+    sessionsByStartedRangeReadModel+    SessionsByStartedRangeQuery+      { memorySpaceId = space,+        namespace = namespaceText ns,+        startedAfter,+        startedBefore+      }  getChain ::   (IOE :> es, Store :> es) =>+  MemorySpaceId ->   SessionId ->   Eff es (Either ReadModelError [SessionRow])-getChain sid =-  runQueryWith Nothing Eventual sessionChainReadModel (SessionChainQuery (idText sid))+getChain space sid =+  runQueryWith+    Nothing+    Eventual+    sessionChainReadModel+    SessionChainQuery {memorySpaceId = space, sessionId = idText sid}  getDelegationChildren ::   (IOE :> es, Store :> es) =>+  MemorySpaceId ->   SessionId ->   Eff es (Either ReadModelError [SessionRow])-getDelegationChildren sid =-  runQueryWith Nothing Eventual sessionDelegationChildrenReadModel (SessionDelegationChildrenQuery (idText sid))+getDelegationChildren space sid =+  runQueryWith+    Nothing+    Eventual+    sessionDelegationChildrenReadModel+    SessionDelegationChildrenQuery {memorySpaceId = space, parentSessionId = idText sid}  getAwaitingByCorrelationKey ::   (IOE :> es, Store :> es) =>+  MemorySpaceId ->   Namespace ->   Text ->   Eff es (Either ReadModelError [SessionRow])-getAwaitingByCorrelationKey ns correlationKey =-  runQueryWith Nothing Eventual awaitingSessionsByCorrelationKeyReadModel (AwaitingSessionsByCorrelationKeyQuery (namespaceText ns) correlationKey)+getAwaitingByCorrelationKey space ns correlationKey =+  runQueryWith+    Nothing+    Eventual+    awaitingSessionsByCorrelationKeyReadModel+    AwaitingSessionsByCorrelationKeyQuery+      { memorySpaceId = space,+        namespace = namespaceText ns,+        correlationKey+      }  namespaceText :: Namespace -> Text namespaceText (Namespace ns) = ns  getTurns ::   (IOE :> es, Store :> es) =>+  MemorySpaceId ->   SessionId ->   Eff es (Either ReadModelError [TurnRow])-getTurns sid =-  runQueryWith Nothing Eventual turnsBySessionReadModel (TurnsBySessionQuery (idText sid))+getTurns space sid =+  runQueryWith+    Nothing+    Eventual+    turnsBySessionReadModel+    TurnsBySessionQuery {memorySpaceId = space, sessionId = idText sid}  runSessionCommand ::   (IOE :> es, KirokuStoreResource :> es, Store :> es, Error StoreError :> es) =>

@@ -13,6 +13,7 @@     RecordTurnData (..),     SessionCommand (..),     commandSessionId,+    commandMemorySpaceId,     SessionStartedData (..),     SessionCompletedData (..),     SessionFailedData (..),@@ -22,6 +23,7 @@     TurnRecordedData (..),     SessionEvent (..),     eventSessionId,+    eventMemorySpaceId,     sessionTransducer,   ) where@@ -32,8 +34,10 @@ import Keiki.Core (HsPred, SymTransducer, lit, (.==), (.||)) import Keiki.Generics (emptyRegFile) import Keiki.Generics.TH (deriveAggregate)+import Kioku.Api.Access (MemorySpaceId, PrincipalRef, RecordedPrincipal) import Kioku.Api.Scope (MemoryScope) import Kioku.Id (SessionId)+import Kioku.Partition (parsePartitionSpace, parseRecordedActor, parseRecordedActorFromAgent, parseRecordedOwner) import Kioku.Prelude  data SessionVertex = NotCreated | Running | Completed | Failed | Interactive | Awaiting@@ -48,13 +52,22 @@ -- @lastTurnIndex@ is the highest turn index committed so far (-1 before any turn), which -- makes @RecordTurn@'s strictly-increasing index contract enforceable in the state machine -- rather than only at the command layer.+--+-- @memorySpaceId@ is the space the session was started in. Every later command must name it,+-- so a caller authorized for one space cannot append a turn to, park, resume, complete, or fail+-- a session belonging to another. Keeping it in the register file rather than re-reading a row+-- is what makes that check survive an optimistic-concurrency retry. type SessionRegs =   '[ '("awaitedCorrelationKey", Maybe Text),-     '("lastTurnIndex", Int)+     '("lastTurnIndex", Int),+     '("memorySpaceId", MemorySpaceId)    ]  data StartSessionData = StartSessionData   { sessionId :: !SessionId,+    memorySpaceId :: !MemorySpaceId,+    actorPrincipal :: !RecordedPrincipal,+    ownerPrincipal :: !(Maybe PrincipalRef),     agentId :: !Text,     focus :: !Text,     scope :: !MemoryScope,@@ -68,6 +81,8 @@  data CompleteSessionData = CompleteSessionData   { sessionId :: !SessionId,+    memorySpaceId :: !MemorySpaceId,+    actorPrincipal :: !RecordedPrincipal,     completedAt :: !UTCTime,     modelUsed :: !(Maybe Text),     summary :: !(Maybe Text)@@ -76,6 +91,8 @@  data FailSessionData = FailSessionData   { sessionId :: !SessionId,+    memorySpaceId :: !MemorySpaceId,+    actorPrincipal :: !RecordedPrincipal,     failedAt :: !UTCTime,     errorMessage :: !Text   }@@ -99,6 +116,8 @@ -- fires and nothing expires when it passes (MasterPlan 2 decision, 2026-07-07). data AwaitInputData = AwaitInputData   { sessionId :: !SessionId,+    memorySpaceId :: !MemorySpaceId,+    actorPrincipal :: !RecordedPrincipal,     reason :: !Text,     correlationKey :: !(Maybe Text),     deadline :: !(Maybe UTCTime),@@ -113,6 +132,8 @@ -- inherently last-writer-wins. data ResumeSessionData = ResumeSessionData   { sessionId :: !SessionId,+    memorySpaceId :: !MemorySpaceId,+    actorPrincipal :: !RecordedPrincipal,     correlationKey :: !(Maybe Text),     force :: !Bool,     input :: !Text,@@ -122,6 +143,9 @@  data RecordInteractiveSessionData = RecordInteractiveSessionData   { sessionId :: !SessionId,+    memorySpaceId :: !MemorySpaceId,+    actorPrincipal :: !RecordedPrincipal,+    ownerPrincipal :: !(Maybe PrincipalRef),     agentId :: !Text,     focus :: !Text,     scope :: !MemoryScope,@@ -132,6 +156,8 @@  data RecordTurnData = RecordTurnData   { sessionId :: !SessionId,+    memorySpaceId :: !MemorySpaceId,+    actorPrincipal :: !RecordedPrincipal,     turnId :: !Text,     turnIndex :: !Int,     role :: !Text,@@ -163,8 +189,26 @@   RecordInteractiveSession d -> d.sessionId   RecordTurn d -> d.sessionId +-- | The memory space a command claims to act in. Every command names one; the aggregate refuses+-- any that disagrees with the space the session was started in.+commandMemorySpaceId :: SessionCommand -> MemorySpaceId+commandMemorySpaceId = \case+  StartSession d -> d.memorySpaceId+  CompleteSession d -> d.memorySpaceId+  FailSession d -> d.memorySpaceId+  AwaitInput d -> d.memorySpaceId+  ResumeSession d -> d.memorySpaceId+  RecordInteractiveSession d -> d.memorySpaceId+  RecordTurn d -> d.memorySpaceId++-- | As on the memory side, every @FromJSON@ instance below is hand-written so that payloads+-- written before memory spaces existed keep decoding. 'Kioku.Partition' owns the defaults;+-- @ToJSON@ stays derived so encoding only ever emits the new form. data SessionStartedData = SessionStartedData   { sessionId :: !SessionId,+    memorySpaceId :: !MemorySpaceId,+    actorPrincipal :: !RecordedPrincipal,+    ownerPrincipal :: !(Maybe PrincipalRef),     agentId :: !Text,     focus :: !Text,     scope :: !MemoryScope,@@ -182,6 +226,9 @@     withObject "SessionStartedData" \o ->       SessionStartedData         <$> o .: "sessionId"+        <*> parsePartitionSpace o+        <*> parseRecordedActorFromAgent o+        <*> parseRecordedOwner o         <*> o .: "agentId"         <*> o .: "focus"         <*> o .: "scope"@@ -193,33 +240,74 @@  data SessionCompletedData = SessionCompletedData   { sessionId :: !SessionId,+    memorySpaceId :: !MemorySpaceId,+    actorPrincipal :: !RecordedPrincipal,     completedAt :: !UTCTime,     modelUsed :: !(Maybe Text),     summary :: !(Maybe Text)   }   deriving stock (Generic, Eq, Show)-  deriving anyclass (FromJSON, ToJSON)+  deriving anyclass (ToJSON) +instance FromJSON SessionCompletedData where+  parseJSON =+    withObject "SessionCompletedData" \o ->+      SessionCompletedData+        <$> o .: "sessionId"+        <*> parsePartitionSpace o+        <*> parseRecordedActor o+        <*> o .: "completedAt"+        <*> o .:? "modelUsed"+        <*> o .:? "summary"+ data SessionFailedData = SessionFailedData   { sessionId :: !SessionId,+    memorySpaceId :: !MemorySpaceId,+    actorPrincipal :: !RecordedPrincipal,     failedAt :: !UTCTime,     errorMessage :: !Text   }   deriving stock (Generic, Eq, Show)-  deriving anyclass (FromJSON, ToJSON)+  deriving anyclass (ToJSON) +instance FromJSON SessionFailedData where+  parseJSON =+    withObject "SessionFailedData" \o ->+      SessionFailedData+        <$> o .: "sessionId"+        <*> parsePartitionSpace o+        <*> parseRecordedActor o+        <*> o .: "failedAt"+        <*> o .: "errorMessage"+ data SessionAwaitingData = SessionAwaitingData   { sessionId :: !SessionId,+    memorySpaceId :: !MemorySpaceId,+    actorPrincipal :: !RecordedPrincipal,     reason :: !Text,     correlationKey :: !(Maybe Text),     deadline :: !(Maybe UTCTime),     awaitedAt :: !UTCTime   }   deriving stock (Generic, Eq, Show)-  deriving anyclass (FromJSON, ToJSON)+  deriving anyclass (ToJSON) +instance FromJSON SessionAwaitingData where+  parseJSON =+    withObject "SessionAwaitingData" \o ->+      SessionAwaitingData+        <$> o .: "sessionId"+        <*> parsePartitionSpace o+        <*> parseRecordedActor o+        <*> o .: "reason"+        <*> o .:? "correlationKey"+        <*> o .:? "deadline"+        <*> o .: "awaitedAt"+ data SessionResumedData = SessionResumedData   { sessionId :: !SessionId,+    memorySpaceId :: !MemorySpaceId,+    actorPrincipal :: !RecordedPrincipal,     correlationKey :: !(Maybe Text),     force :: !Bool,     input :: !Text,@@ -236,14 +324,19 @@   parseJSON =     withObject "SessionResumedData" \o -> do       sessionId <- o .: "sessionId"+      memorySpaceId <- parsePartitionSpace o+      actorPrincipal <- parseRecordedActor o       correlationKey <- o .:? "correlationKey"       force <- o .:? "force" .!= isNothing correlationKey       input <- o .: "input"       resumedAt <- o .: "resumedAt"-      pure SessionResumedData {sessionId, correlationKey, force, input, resumedAt}+      pure SessionResumedData {sessionId, memorySpaceId, actorPrincipal, correlationKey, force, input, resumedAt}  data InteractiveSessionRecordedData = InteractiveSessionRecordedData   { sessionId :: !SessionId,+    memorySpaceId :: !MemorySpaceId,+    actorPrincipal :: !RecordedPrincipal,+    ownerPrincipal :: !(Maybe PrincipalRef),     agentId :: !Text,     focus :: !Text,     scope :: !MemoryScope,@@ -251,10 +344,26 @@     startedAt :: !UTCTime   }   deriving stock (Generic, Eq, Show)-  deriving anyclass (FromJSON, ToJSON)+  deriving anyclass (ToJSON) +instance FromJSON InteractiveSessionRecordedData where+  parseJSON =+    withObject "InteractiveSessionRecordedData" \o ->+      InteractiveSessionRecordedData+        <$> o .: "sessionId"+        <*> parsePartitionSpace o+        <*> parseRecordedActorFromAgent o+        <*> parseRecordedOwner o+        <*> o .: "agentId"+        <*> o .: "focus"+        <*> o .: "scope"+        <*> o .:? "subjectRef"+        <*> o .: "startedAt"+ data TurnRecordedData = TurnRecordedData   { sessionId :: !SessionId,+    memorySpaceId :: !MemorySpaceId,+    actorPrincipal :: !RecordedPrincipal,     turnId :: !Text,     turnIndex :: !Int,     role :: !Text,@@ -265,8 +374,24 @@     recordedAt :: !UTCTime   }   deriving stock (Generic, Eq, Show)-  deriving anyclass (FromJSON, ToJSON)+  deriving anyclass (ToJSON) +instance FromJSON TurnRecordedData where+  parseJSON =+    withObject "TurnRecordedData" \o ->+      TurnRecordedData+        <$> o .: "sessionId"+        <*> parsePartitionSpace o+        <*> parseRecordedActor o+        <*> o .: "turnId"+        <*> o .: "turnIndex"+        <*> o .: "role"+        <*> o .: "content"+        <*> o .:? "toolSummary"+        <*> o .:? "promptTokens"+        <*> o .:? "outputTokens"+        <*> o .: "recordedAt"+ data SessionEvent   = SessionStarted !SessionStartedData   | SessionCompleted !SessionCompletedData@@ -293,6 +418,18 @@   InteractiveSessionRecorded d -> d.sessionId   TurnRecorded d -> d.sessionId +-- | The memory space a stored event belongs to. Every event carries one, including every event+-- written before memory spaces existed: those decode into 'legacyMemorySpaceId'.+eventMemorySpaceId :: SessionEvent -> MemorySpaceId+eventMemorySpaceId = \case+  SessionStarted d -> d.memorySpaceId+  SessionCompleted d -> d.memorySpaceId+  SessionFailed d -> d.memorySpaceId+  SessionAwaiting d -> d.memorySpaceId+  SessionResumed d -> d.memorySpaceId+  InteractiveSessionRecorded d -> d.memorySpaceId+  TurnRecorded d -> d.memorySpaceId+ $(deriveAggregate ''SessionCommand ''SessionRegs ''SessionEvent)  sessionTransducer ::@@ -307,13 +444,17 @@     B.from NotCreated do       B.onCmd inCtorStartSession $ \d -> B.do         -- 'emptyRegFile' binds every slot to a deferred error, so this edge — the only way-        -- into Running, and thus into Awaiting and RecordTurn — must initialize both.+        -- into Running, and thus into Awaiting and RecordTurn — must initialize all three.         B.slot @"awaitedCorrelationKey" =: lit Nothing         B.slot @"lastTurnIndex" =: lit (-1)+        B.slot @"memorySpaceId" =: d.memorySpaceId         B.emit           wireSessionStarted           SessionStartedTermFields             { sessionId = d.sessionId,+              memorySpaceId = d.memorySpaceId,+              actorPrincipal = d.actorPrincipal,+              ownerPrincipal = d.ownerPrincipal,               agentId = d.agentId,               focus = d.focus,               scope = d.scope,@@ -326,10 +467,17 @@         B.goto Running        B.onCmd inCtorRecordInteractiveSession $ \d -> B.do+        -- Interactive is terminal, so nothing later reads this slot. It is still set, because a+        -- register left bound to 'emptyRegFile''s deferred error is a trap for the next edge+        -- somebody adds here.+        B.slot @"memorySpaceId" =: d.memorySpaceId         B.emit           wireInteractiveSessionRecorded           InteractiveSessionRecordedTermFields             { sessionId = d.sessionId,+              memorySpaceId = d.memorySpaceId,+              actorPrincipal = d.actorPrincipal,+              ownerPrincipal = d.ownerPrincipal,               agentId = d.agentId,               focus = d.focus,               scope = d.scope,@@ -339,11 +487,16 @@         B.goto Interactive      B.from Running do+      -- Every edge out of a live session repeats the space guard: the command must name the+      -- space the session was started in.       B.onCmd inCtorCompleteSession $ \d -> B.do+        B.requireGuard (d.memorySpaceId .== B.reg @"memorySpaceId")         B.emit           wireSessionCompleted           SessionCompletedTermFields             { sessionId = d.sessionId,+              memorySpaceId = d.memorySpaceId,+              actorPrincipal = d.actorPrincipal,               completedAt = d.completedAt,               modelUsed = d.modelUsed,               summary = d.summary@@ -351,10 +504,13 @@         B.goto Completed        B.onCmd inCtorFailSession $ \d -> B.do+        B.requireGuard (d.memorySpaceId .== B.reg @"memorySpaceId")         B.emit           wireSessionFailed           SessionFailedTermFields             { sessionId = d.sessionId,+              memorySpaceId = d.memorySpaceId,+              actorPrincipal = d.actorPrincipal,               failedAt = d.failedAt,               errorMessage = d.errorMessage             }@@ -365,12 +521,15 @@         -- re-delivered or out-of-order turn cannot silently overwrite a committed one.         -- 'turnIndex' is already in the event payload, so replay recovers it and existing         -- strictly-increasing streams rehydrate unchanged (verified by Audit B).+        B.requireGuard (d.memorySpaceId .== B.reg @"memorySpaceId")         B.requireGt d.turnIndex (B.reg @"lastTurnIndex")         B.slot @"lastTurnIndex" =: d.turnIndex         B.emit           wireTurnRecorded           TurnRecordedTermFields             { sessionId = d.sessionId,+              memorySpaceId = d.memorySpaceId,+              actorPrincipal = d.actorPrincipal,               turnId = d.turnId,               turnIndex = d.turnIndex,               role = d.role,@@ -383,11 +542,14 @@         B.goto Running        B.onCmd inCtorAwaitInput $ \d -> B.do+        B.requireGuard (d.memorySpaceId .== B.reg @"memorySpaceId")         B.slot @"awaitedCorrelationKey" =: d.correlationKey         B.emit           wireSessionAwaiting           SessionAwaitingTermFields             { sessionId = d.sessionId,+              memorySpaceId = d.memorySpaceId,+              actorPrincipal = d.actorPrincipal,               reason = d.reason,               correlationKey = d.correlationKey,               deadline = d.deadline,@@ -400,6 +562,11 @@         -- The resume must name the key this session actually parked on, unless it is an         -- explicit force. Enforcing it here rather than in a read-model precheck is what         -- closes the race: keiro re-runs this edge against the post-conflict state.+        --+        -- Note that 'force' waives the correlation-key check and nothing else. A forced resume+        -- still has to name the session's own memory space; an operator override for a lost key+        -- is not an override for the isolation boundary.+        B.requireGuard (d.memorySpaceId .== B.reg @"memorySpaceId")         B.requireGuard           ((d.force .== lit True) .|| (d.correlationKey .== B.reg @"awaitedCorrelationKey"))         B.slot @"awaitedCorrelationKey" =: lit Nothing@@ -407,6 +574,8 @@           wireSessionResumed           SessionResumedTermFields             { sessionId = d.sessionId,+              memorySpaceId = d.memorySpaceId,+              actorPrincipal = d.actorPrincipal,               correlationKey = d.correlationKey,               -- Mandatory for replay: the guard reads 'force', and hydration can only               -- recover command fields that the event payload carries.@@ -417,10 +586,13 @@         B.goto Running        B.onCmd inCtorCompleteSession $ \d -> B.do+        B.requireGuard (d.memorySpaceId .== B.reg @"memorySpaceId")         B.emit           wireSessionCompleted           SessionCompletedTermFields             { sessionId = d.sessionId,+              memorySpaceId = d.memorySpaceId,+              actorPrincipal = d.actorPrincipal,               completedAt = d.completedAt,               modelUsed = d.modelUsed,               summary = d.summary@@ -428,10 +600,13 @@         B.goto Completed        B.onCmd inCtorFailSession $ \d -> B.do+        B.requireGuard (d.memorySpaceId .== B.reg @"memorySpaceId")         B.emit           wireSessionFailed           SessionFailedTermFields             { sessionId = d.sessionId,+              memorySpaceId = d.memorySpaceId,+              actorPrincipal = d.actorPrincipal,               failedAt = d.failedAt,               errorMessage = d.errorMessage             }

@@ -17,6 +17,7 @@ import Keiro.EventStream.Validate (ValidatedEventStream, mkEventStreamOrThrow) import Keiro.Stream (Stream) import Keiro.Stream qualified as Stream+import Kioku.Api.Access (RecordedPrincipal (..), legacyMemorySpaceId, legacyPrincipalRef) import Kioku.Api.Scope (MemoryScope (..), Namespace (..), ScopeKind (..)) import Kioku.Id (SessionId, idText, parseIdLenient) import Kioku.Prelude@@ -93,15 +94,23 @@       "interactive_session_recorded" -> InteractiveSessionRecorded <$> parseLegacyInteractiveSessionRecorded payload       other -> fail ("Unknown Rei AgentSessionEvent tag: " <> Text.unpack other) +-- | Rei payloads predate memory spaces, so they take the legacy space; their @agentId@ is the+-- free-text label 'LegacyPrincipal' exists to mark, and is never rewritten into a+-- directory-issued principal id. parseLegacySessionStarted :: Value -> Parser SessionStartedData parseLegacySessionStarted =   withObject "Rei AgentSessionStartedData" $ \o -> do     sessionId <- parseLegacySessionId =<< o .: "sessionId"+    agentId <- o .: "agentId"     intentionId <- o .:? "intentionId"     previousSessionId <- traverse parseLegacySessionId =<< o .:? "previousSessionId"-    SessionStartedData sessionId-      <$> o .: "agentId"-      <*> (normalizeLegacyFocus <$> o .: "focusType")+    SessionStartedData+      sessionId+      legacyMemorySpaceId+      (LegacyPrincipal (legacyPrincipalRef agentId))+      Nothing+      agentId+      <$> (normalizeLegacyFocus <$> o .: "focusType")       <*> pure (sessionScope intentionId)       <*> o .:? "focusTarget"       <*> pure previousSessionId@@ -114,6 +123,8 @@   withObject "Rei AgentSessionCompletedData" $ \o ->     SessionCompletedData       <$> (parseLegacySessionId =<< o .: "sessionId")+      <*> pure legacyMemorySpaceId+      <*> pure UnattributedPrincipal       <*> o .: "completedAt"       <*> o .:? "modelUsed"       <*> o .:? "summary"@@ -123,6 +134,8 @@   withObject "Rei AgentSessionFailedData" $ \o ->     SessionFailedData       <$> (parseLegacySessionId =<< o .: "sessionId")+      <*> pure legacyMemorySpaceId+      <*> pure UnattributedPrincipal       <*> o .: "failedAt"       <*> o .: "errorMessage" @@ -130,10 +143,15 @@ parseLegacyInteractiveSessionRecorded =   withObject "Rei InteractiveSessionRecordedData" $ \o -> do     sessionId <- parseLegacySessionId =<< o .: "sessionId"+    agentId <- o .: "agentId"     intentionId <- o .:? "intentionId"-    InteractiveSessionRecordedData sessionId-      <$> o .: "agentId"-      <*> (normalizeLegacyFocus <$> o .: "focusType")+    InteractiveSessionRecordedData+      sessionId+      legacyMemorySpaceId+      (LegacyPrincipal (legacyPrincipalRef agentId))+      Nothing+      agentId+      <$> (normalizeLegacyFocus <$> o .: "focusType")       <*> pure (sessionScope intentionId)       <*> pure Nothing       <*> o .: "startedAt"

@@ -1,3 +1,8 @@+-- | The @kioku.sessions@ and @kioku.turns@ projections and every query over them.+--+-- A session belongs to the memory space it was started in, and a turn belongs to its session's+-- space. Both columns are written by the projection from the event payload rather than looked+-- up, and every query below filters on the space as well as on whatever it is keyed by. module Kioku.Session.ReadModel   ( sessionInlineProjection,     SessionRow (..),@@ -23,23 +28,33 @@   ) where -import Contravariant.Extras (contrazip2, contrazip3, contrazip4) import Data.Functor.Contravariant ((>$<)) import Data.Int (Int32)+import Data.Text qualified as Text import Hasql.Decoders qualified as D import Hasql.Encoders qualified as E import Hasql.Statement (Statement, preparable) import Hasql.Transaction qualified as Tx import Keiro.Projection (InlineProjection (..)) import Keiro.ReadModel (ConsistencyMode (..), ReadModel (..), StrongScope (..))+import Kioku.Api.Access (MemorySpaceId) import Kioku.Api.Scope (scopeKindText, scopeNamespaceText, scopeRefText)+import Kioku.Database.Schema+  ( kiokuSchema,+    sessionsRelation,+    sessionsTable,+    turnsRelation,+    turnsTable,+  ) import Kioku.Id (idText)+import Kioku.Partition (memorySpaceColumn, memorySpaceParam) import Kioku.Prelude import Kioku.Session.Domain import Kiroku.Store.Types (RecordedEvent)  data SessionRow = SessionRow-  { sessionId :: !Text,+  { memorySpaceId :: !MemorySpaceId,+    sessionId :: !Text,     agentId :: !Text,     focus :: !Text,     namespace :: !Text,@@ -63,7 +78,8 @@   deriving stock (Generic, Eq, Show)  data TurnRow = TurnRow-  { turnId :: !Text,+  { memorySpaceId :: !MemorySpaceId,+    turnId :: !Text,     sessionId :: !Text,     turnIndex :: !Int,     role :: !Text,@@ -75,23 +91,57 @@   }   deriving stock (Generic, Eq, Show) -newtype SessionByIdQuery = SessionByIdQuery Text+data SessionByIdQuery = SessionByIdQuery+  { memorySpaceId :: !MemorySpaceId,+    sessionId :: !Text+  } -data SessionsByNamespaceQuery = SessionsByNamespaceQuery Text Int+data SessionsByNamespaceQuery = SessionsByNamespaceQuery+  { memorySpaceId :: !MemorySpaceId,+    namespace :: !Text,+    limit :: !Int+  } -data SessionsByScopeQuery = SessionsByScopeQuery Text (Maybe Text) (Maybe Text)+data SessionsByScopeQuery = SessionsByScopeQuery+  { memorySpaceId :: !MemorySpaceId,+    namespace :: !Text,+    scopeKind :: !(Maybe Text),+    scopeRef :: !(Maybe Text)+  } -data SessionsByFocusQuery = SessionsByFocusQuery Text Text+data SessionsByFocusQuery = SessionsByFocusQuery+  { memorySpaceId :: !MemorySpaceId,+    namespace :: !Text,+    focus :: !Text+  } -data SessionsByStartedRangeQuery = SessionsByStartedRangeQuery Text UTCTime UTCTime+data SessionsByStartedRangeQuery = SessionsByStartedRangeQuery+  { memorySpaceId :: !MemorySpaceId,+    namespace :: !Text,+    startedAfter :: !UTCTime,+    startedBefore :: !UTCTime+  } -newtype SessionChainQuery = SessionChainQuery Text+data SessionChainQuery = SessionChainQuery+  { memorySpaceId :: !MemorySpaceId,+    sessionId :: !Text+  } -newtype SessionDelegationChildrenQuery = SessionDelegationChildrenQuery Text+data SessionDelegationChildrenQuery = SessionDelegationChildrenQuery+  { memorySpaceId :: !MemorySpaceId,+    parentSessionId :: !Text+  } -data AwaitingSessionsByCorrelationKeyQuery = AwaitingSessionsByCorrelationKeyQuery Text Text+data AwaitingSessionsByCorrelationKeyQuery = AwaitingSessionsByCorrelationKeyQuery+  { memorySpaceId :: !MemorySpaceId,+    namespace :: !Text,+    correlationKey :: !Text+  } -newtype TurnsBySessionQuery = TurnsBySessionQuery Text+data TurnsBySessionQuery = TurnsBySessionQuery+  { memorySpaceId :: !MemorySpaceId,+    sessionId :: !Text+  }  sessionInlineProjection :: InlineProjection SessionEvent sessionInlineProjection =@@ -107,26 +157,80 @@     InteractiveSessionRecorded d -> Tx.statement (interactiveRow d) upsertSessionStmt     SessionCompleted d ->       Tx.statement-        (idText d.sessionId, d.completedAt, d.modelUsed, d.summary)+        SessionCompletion+          { memorySpaceId = d.memorySpaceId,+            sessionId = idText d.sessionId,+            completedAt = d.completedAt,+            modelUsed = d.modelUsed,+            summary = d.summary+          }         updateSessionCompletedStmt     SessionFailed d ->       Tx.statement-        (idText d.sessionId, d.failedAt, d.errorMessage)+        SessionFailure+          { memorySpaceId = d.memorySpaceId,+            sessionId = idText d.sessionId,+            failedAt = d.failedAt,+            errorMessage = d.errorMessage+          }         updateSessionFailedStmt     SessionAwaiting d ->       Tx.statement-        (idText d.sessionId, d.reason, d.correlationKey, d.deadline)+        SessionPark+          { memorySpaceId = d.memorySpaceId,+            sessionId = idText d.sessionId,+            reason = d.reason,+            correlationKey = d.correlationKey,+            deadline = d.deadline+          }         updateSessionAwaitingStmt     SessionResumed d ->       Tx.statement-        (idText d.sessionId, d.input)+        SessionResumption+          { memorySpaceId = d.memorySpaceId,+            sessionId = idText d.sessionId,+            input = d.input+          }         updateSessionResumedStmt     TurnRecorded d -> Tx.statement (turnRow d) insertTurnStmt +-- | The parameters of each lifecycle update, as records rather than tuples, so that the+-- partition is named at every call site instead of being the first of five positional+-- arguments.+data SessionCompletion = SessionCompletion+  { memorySpaceId :: !MemorySpaceId,+    sessionId :: !Text,+    completedAt :: !UTCTime,+    modelUsed :: !(Maybe Text),+    summary :: !(Maybe Text)+  }++data SessionFailure = SessionFailure+  { memorySpaceId :: !MemorySpaceId,+    sessionId :: !Text,+    failedAt :: !UTCTime,+    errorMessage :: !Text+  }++data SessionPark = SessionPark+  { memorySpaceId :: !MemorySpaceId,+    sessionId :: !Text,+    reason :: !Text,+    correlationKey :: !(Maybe Text),+    deadline :: !(Maybe UTCTime)+  }++data SessionResumption = SessionResumption+  { memorySpaceId :: !MemorySpaceId,+    sessionId :: !Text,+    input :: !Text+  }+ startedRow :: SessionStartedData -> SessionRow startedRow d =   SessionRow-    { sessionId = idText d.sessionId,+    { memorySpaceId = d.memorySpaceId,+      sessionId = idText d.sessionId,       agentId = d.agentId,       focus = d.focus,       namespace = scopeNamespaceText d.scope,@@ -151,7 +255,8 @@ interactiveRow :: InteractiveSessionRecordedData -> SessionRow interactiveRow d =   SessionRow-    { sessionId = idText d.sessionId,+    { memorySpaceId = d.memorySpaceId,+      sessionId = idText d.sessionId,       agentId = d.agentId,       focus = d.focus,       namespace = scopeNamespaceText d.scope,@@ -176,7 +281,8 @@ turnRow :: TurnRecordedData -> TurnRow turnRow d =   TurnRow-    { turnId = d.turnId,+    { memorySpaceId = d.memorySpaceId,+      turnId = d.turnId,       sessionId = idText d.sessionId,       turnIndex = d.turnIndex,       role = d.role,@@ -191,25 +297,25 @@ sessionByIdReadModel =   ReadModel     { name = "kioku-session-by-id",-      schema = "kiroku",-      tableName = "kioku_sessions",+      schema = kiokuSchema,+      tableName = sessionsRelation,       subscriptionName = "kioku-session-inline",-      version = 3,-      shapeHash = "kioku-session-v3",+      version = sessionReadModelVersion,+      shapeHash = sessionReadModelShapeHash,       defaultConsistency = Eventual,       strongScope = EntireLog,-      query = \(SessionByIdQuery sid) -> Tx.statement sid selectSessionByIdStmt+      query = \q -> Tx.statement q selectSessionByIdStmt     }  sessionsByNamespaceReadModel :: ReadModel SessionsByNamespaceQuery [SessionRow] sessionsByNamespaceReadModel =   ReadModel     { name = "kioku-sessions-by-namespace",-      schema = "kiroku",-      tableName = "kioku_sessions",+      schema = kiokuSchema,+      tableName = sessionsRelation,       subscriptionName = "kioku-session-inline",-      version = 3,-      shapeHash = "kioku-session-v3",+      version = sessionReadModelVersion,+      shapeHash = sessionReadModelShapeHash,       defaultConsistency = Eventual,       strongScope = EntireLog,       query = \q -> Tx.statement q selectSessionsByNamespaceStmt@@ -219,11 +325,11 @@ sessionsByScopeReadModel =   ReadModel     { name = "kioku-sessions-by-scope",-      schema = "kiroku",-      tableName = "kioku_sessions",+      schema = kiokuSchema,+      tableName = sessionsRelation,       subscriptionName = "kioku-session-inline",-      version = 3,-      shapeHash = "kioku-session-v3",+      version = sessionReadModelVersion,+      shapeHash = sessionReadModelShapeHash,       defaultConsistency = Eventual,       strongScope = EntireLog,       query = \q -> Tx.statement q selectSessionsByScopeStmt@@ -233,11 +339,11 @@ sessionsByFocusReadModel =   ReadModel     { name = "kioku-sessions-by-focus",-      schema = "kiroku",-      tableName = "kioku_sessions",+      schema = kiokuSchema,+      tableName = sessionsRelation,       subscriptionName = "kioku-session-inline",-      version = 3,-      shapeHash = "kioku-session-v3",+      version = sessionReadModelVersion,+      shapeHash = sessionReadModelShapeHash,       defaultConsistency = Eventual,       strongScope = EntireLog,       query = \q -> Tx.statement q selectSessionsByFocusStmt@@ -247,11 +353,11 @@ sessionsByStartedRangeReadModel =   ReadModel     { name = "kioku-sessions-by-started-range",-      schema = "kiroku",-      tableName = "kioku_sessions",+      schema = kiokuSchema,+      tableName = sessionsRelation,       subscriptionName = "kioku-session-inline",-      version = 3,-      shapeHash = "kioku-session-v3",+      version = sessionReadModelVersion,+      shapeHash = sessionReadModelShapeHash,       defaultConsistency = Eventual,       strongScope = EntireLog,       query = \q -> Tx.statement q selectSessionsByStartedRangeStmt@@ -261,39 +367,39 @@ sessionChainReadModel =   ReadModel     { name = "kioku-session-chain",-      schema = "kiroku",-      tableName = "kioku_sessions",+      schema = kiokuSchema,+      tableName = sessionsRelation,       subscriptionName = "kioku-session-inline",-      version = 3,-      shapeHash = "kioku-session-v3",+      version = sessionReadModelVersion,+      shapeHash = sessionReadModelShapeHash,       defaultConsistency = Eventual,       strongScope = EntireLog,-      query = \(SessionChainQuery sid) -> Tx.statement sid selectSessionChainStmt+      query = \q -> Tx.statement q selectSessionChainStmt     }  sessionDelegationChildrenReadModel :: ReadModel SessionDelegationChildrenQuery [SessionRow] sessionDelegationChildrenReadModel =   ReadModel     { name = "kioku-session-delegation-children",-      schema = "kiroku",-      tableName = "kioku_sessions",+      schema = kiokuSchema,+      tableName = sessionsRelation,       subscriptionName = "kioku-session-inline",-      version = 3,-      shapeHash = "kioku-session-v3",+      version = sessionReadModelVersion,+      shapeHash = sessionReadModelShapeHash,       defaultConsistency = Eventual,       strongScope = EntireLog,-      query = \(SessionDelegationChildrenQuery sid) -> Tx.statement sid selectDelegationChildrenStmt+      query = \q -> Tx.statement q selectDelegationChildrenStmt     }  awaitingSessionsByCorrelationKeyReadModel :: ReadModel AwaitingSessionsByCorrelationKeyQuery [SessionRow] awaitingSessionsByCorrelationKeyReadModel =   ReadModel     { name = "kioku-sessions-awaiting-by-correlation-key",-      schema = "kiroku",-      tableName = "kioku_sessions",+      schema = kiokuSchema,+      tableName = sessionsRelation,       subscriptionName = "kioku-session-inline",-      version = 3,-      shapeHash = "kioku-session-v3",+      version = sessionReadModelVersion,+      shapeHash = sessionReadModelShapeHash,       defaultConsistency = Eventual,       strongScope = EntireLog,       query = \q -> Tx.statement q selectAwaitingByCorrelationKeyStmt@@ -303,23 +409,48 @@ turnsBySessionReadModel =   ReadModel     { name = "kioku-turns-by-session",-      schema = "kiroku",-      tableName = "kioku_turns",+      schema = kiokuSchema,+      tableName = turnsRelation,       subscriptionName = "kioku-session-inline",-      version = 1,-      shapeHash = "kioku-turn-v1",+      version = turnReadModelVersion,+      shapeHash = turnReadModelShapeHash,       defaultConsistency = Eventual,       strongScope = EntireLog,-      query = \(TurnsBySessionQuery sid) -> Tx.statement sid selectTurnsBySessionStmt+      query = \q -> Tx.statement q selectTurnsBySessionStmt     } +-- | The registry identity of every session read model.+--+-- The session model reshaped v1 -> v2 (delegation lineage) -> v3 (awaiting park/resume) -> v4+-- (the memory-space partition) -> v5 (the move from @kiroku.kioku_sessions@ to+-- @kioku.sessions@). Turns followed the same last step, v2 -> v3.+--+-- Each step was a migration that left the table data correct for the newer version, so+-- @Kioku.ReadModel.reconcileReadModelRegistry@ advances the guard rather than rebuilding. The+-- last one is not additive in the usual sense — no column changed, the relation moved — but the+-- version still has to advance, because Keiro's registry records no physical relation name and+-- the version is therefore the only thing that can stop a binary compiled before the move from+-- querying a table that is no longer where it thinks it is.+sessionReadModelVersion :: Int+sessionReadModelVersion = 5++sessionReadModelShapeHash :: Text+sessionReadModelShapeHash = "kioku-session-v5"++turnReadModelVersion :: Int+turnReadModelVersion = 3++turnReadModelShapeHash :: Text+turnReadModelShapeHash = "kioku-turn-v3"+ sessionRowDecoder :: D.Row SessionRow sessionRowDecoder =   SessionRow-    <$> D.column (D.nonNullable D.text)+    <$> memorySpaceColumn     <*> D.column (D.nonNullable D.text)     <*> D.column (D.nonNullable D.text)     <*> D.column (D.nonNullable D.text)+    <*> D.column (D.nonNullable D.text)     <*> D.column (D.nullable D.text)     <*> D.column (D.nullable D.text)     <*> D.column (D.nullable D.text)@@ -340,8 +471,9 @@ turnRowDecoder :: D.Row TurnRow turnRowDecoder =   TurnRow-    <$> D.column (D.nonNullable D.text)+    <$> memorySpaceColumn     <*> D.column (D.nonNullable D.text)+    <*> D.column (D.nonNullable D.text)     <*> (fromIntegral @Int32 @Int <$> D.column (D.nonNullable D.int4))     <*> D.column (D.nonNullable D.text)     <*> D.column (D.nonNullable D.text)@@ -350,97 +482,122 @@     <*> (fmap (fromIntegral @Int32 @Int) <$> D.column (D.nullable D.int4))     <*> D.column (D.nonNullable D.timestamptz) -selectSessionByIdStmt :: Statement Text (Maybe SessionRow)+-- | The projection 'sessionRowDecoder' expects, in its exact order. The partition comes first,+-- so a reviewer reading any session query sees the space before anything it is keyed by.+sessionRowColumnNames :: [Text]+sessionRowColumnNames =+  [ "memory_space_id",+    "session_id",+    "agent_id",+    "focus",+    "namespace",+    "scope_kind",+    "scope_ref",+    "subject_ref",+    "previous_session_id",+    "parent_session_id",+    "delegation_depth",+    "status",+    "started_at",+    "completed_at",+    "model_used",+    "summary",+    "error_message",+    "awaiting_reason",+    "awaiting_correlation_key",+    "awaiting_deadline",+    "resume_input"+  ]++sessionRowColumns :: Text+sessionRowColumns = Text.intercalate ", " sessionRowColumnNames++qualifiedSessionRowColumns :: Text -> Text+qualifiedSessionRowColumns prefix =+  Text.intercalate ", " ((\column -> prefix <> "." <> column) <$> sessionRowColumnNames)++selectSessionByIdStmt :: Statement SessionByIdQuery (Maybe SessionRow) selectSessionByIdStmt =   preparable-    """-    SELECT session_id, agent_id, focus, namespace, scope_kind, scope_ref, subject_ref,-           previous_session_id, parent_session_id, delegation_depth, status, started_at,-           completed_at, model_used, summary, error_message,-           awaiting_reason, awaiting_correlation_key, awaiting_deadline, resume_input-    FROM kioku_sessions-    WHERE session_id = $1-    """-    (E.param (E.nonNullable E.text))+    ( "SELECT "+        <> sessionRowColumns+        <> " FROM "+        <> sessionsTable+        <> " WHERE memory_space_id = $1 AND session_id = $2"+    )+    ( ((\q -> q.memorySpaceId) >$< memorySpaceParam)+        <> ((\q -> q.sessionId) >$< E.param (E.nonNullable E.text))+    )     (D.rowMaybe sessionRowDecoder)  selectSessionsByNamespaceStmt :: Statement SessionsByNamespaceQuery [SessionRow] selectSessionsByNamespaceStmt =   preparable-    """-    SELECT session_id, agent_id, focus, namespace, scope_kind, scope_ref, subject_ref,-           previous_session_id, parent_session_id, delegation_depth, status, started_at,-           completed_at, model_used, summary, error_message,-           awaiting_reason, awaiting_correlation_key, awaiting_deadline, resume_input-    FROM kioku_sessions-    WHERE namespace = $1-    ORDER BY started_at DESC-    LIMIT $2-    """-    ( ((\(SessionsByNamespaceQuery ns _) -> ns) >$< E.param (E.nonNullable E.text))-        <> ((\(SessionsByNamespaceQuery _ limit) -> fromIntegral @Int @Int32 limit) >$< E.param (E.nonNullable E.int4))+    ( "SELECT "+        <> sessionRowColumns+        <> " FROM "+        <> sessionsTable+        <> " WHERE memory_space_id = $1 AND namespace = $2 ORDER BY started_at DESC LIMIT $3"     )+    ( ((\q -> q.memorySpaceId) >$< memorySpaceParam)+        <> ((\q -> q.namespace) >$< E.param (E.nonNullable E.text))+        <> ((\q -> fromIntegral @Int @Int32 q.limit) >$< E.param (E.nonNullable E.int4))+    )     (D.rowList sessionRowDecoder)  selectSessionsByScopeStmt :: Statement SessionsByScopeQuery [SessionRow] selectSessionsByScopeStmt =   preparable-    """-    SELECT session_id, agent_id, focus, namespace, scope_kind, scope_ref, subject_ref,-           previous_session_id, parent_session_id, delegation_depth, status, started_at,-           completed_at, model_used, summary, error_message,-           awaiting_reason, awaiting_correlation_key, awaiting_deadline, resume_input-    FROM kioku_sessions-    WHERE namespace = $1-      AND scope_kind IS NOT DISTINCT FROM $2-      AND scope_ref IS NOT DISTINCT FROM $3-    ORDER BY started_at DESC-    """-    ( ((\(SessionsByScopeQuery ns _ _) -> ns) >$< E.param (E.nonNullable E.text))-        <> ((\(SessionsByScopeQuery _ sk _) -> sk) >$< E.param (E.nullable E.text))-        <> ((\(SessionsByScopeQuery _ _ sr) -> sr) >$< E.param (E.nullable E.text))+    ( "SELECT "+        <> sessionRowColumns+        <> " FROM "+        <> sessionsTable+        <> " WHERE memory_space_id = $1 AND namespace = $2\+           \ AND scope_kind IS NOT DISTINCT FROM $3 AND scope_ref IS NOT DISTINCT FROM $4\+           \ ORDER BY started_at DESC"     )+    ( ((\q -> q.memorySpaceId) >$< memorySpaceParam)+        <> ((\q -> q.namespace) >$< E.param (E.nonNullable E.text))+        <> ((\q -> q.scopeKind) >$< E.param (E.nullable E.text))+        <> ((\q -> q.scopeRef) >$< E.param (E.nullable E.text))+    )     (D.rowList sessionRowDecoder)  selectSessionsByFocusStmt :: Statement SessionsByFocusQuery [SessionRow] selectSessionsByFocusStmt =   preparable-    """-    SELECT session_id, agent_id, focus, namespace, scope_kind, scope_ref, subject_ref,-           previous_session_id, parent_session_id, delegation_depth, status, started_at,-           completed_at, model_used, summary, error_message,-           awaiting_reason, awaiting_correlation_key, awaiting_deadline, resume_input-    FROM kioku_sessions-    WHERE namespace = $1-      AND focus = $2-    ORDER BY started_at DESC-    """-    ( ((\(SessionsByFocusQuery ns _) -> ns) >$< E.param (E.nonNullable E.text))-        <> ((\(SessionsByFocusQuery _ focus) -> focus) >$< E.param (E.nonNullable E.text))+    ( "SELECT "+        <> sessionRowColumns+        <> " FROM "+        <> sessionsTable+        <> " WHERE memory_space_id = $1 AND namespace = $2 AND focus = $3\+           \ ORDER BY started_at DESC"     )+    ( ((\q -> q.memorySpaceId) >$< memorySpaceParam)+        <> ((\q -> q.namespace) >$< E.param (E.nonNullable E.text))+        <> ((\q -> q.focus) >$< E.param (E.nonNullable E.text))+    )     (D.rowList sessionRowDecoder)  selectSessionsByStartedRangeStmt :: Statement SessionsByStartedRangeQuery [SessionRow] selectSessionsByStartedRangeStmt =   preparable-    """-    SELECT session_id, agent_id, focus, namespace, scope_kind, scope_ref, subject_ref,-           previous_session_id, parent_session_id, delegation_depth, status, started_at,-           completed_at, model_used, summary, error_message,-           awaiting_reason, awaiting_correlation_key, awaiting_deadline, resume_input-    FROM kioku_sessions-    WHERE namespace = $1-      AND started_at >= $2-      AND started_at < $3-    ORDER BY started_at DESC-    """-    ( ((\(SessionsByStartedRangeQuery ns _ _) -> ns) >$< E.param (E.nonNullable E.text))-        <> ((\(SessionsByStartedRangeQuery _ start _) -> start) >$< E.param (E.nonNullable E.timestamptz))-        <> ((\(SessionsByStartedRangeQuery _ _ end) -> end) >$< E.param (E.nonNullable E.timestamptz))+    ( "SELECT "+        <> sessionRowColumns+        <> " FROM "+        <> sessionsTable+        <> " WHERE memory_space_id = $1 AND namespace = $2\+           \ AND started_at >= $3 AND started_at < $4 ORDER BY started_at DESC"     )+    ( ((\q -> q.memorySpaceId) >$< memorySpaceParam)+        <> ((\q -> q.namespace) >$< E.param (E.nonNullable E.text))+        <> ((\q -> q.startedAfter) >$< E.param (E.nonNullable E.timestamptz))+        <> ((\q -> q.startedBefore) >$< E.param (E.nonNullable E.timestamptz))+    )     (D.rowList sessionRowDecoder) --- | Walk a session's continuation chain backwards through @previous_session_id@.+-- | Walk a session's continuation chain backwards through @previous_session_id@, without+-- leaving the memory space it started in. -- -- The @path@ array makes revisiting a session impossible, so the walk terminates on any -- data — including a cycle, which 'Kioku.Session.start' now refuses to create but which@@ -448,106 +605,135 @@ -- With a plain @UNION ALL@ and no guard, a cycle loops until timeout or OOM. The depth cap -- is defense in depth, far above any legitimate chain. --+-- @previous_session_id@ is a bare id with no foreign key, so the recursive arm carries the+-- space predicate too: without it a chain could be walked out of its space by any id written+-- before the partition existed.+-- -- The final @SELECT@ omits @depth@/@path@, so 'sessionRowDecoder' is unchanged.-selectSessionChainStmt :: Statement Text [SessionRow]+selectSessionChainStmt :: Statement SessionChainQuery [SessionRow] selectSessionChainStmt =   preparable-    """-    WITH RECURSIVE chain AS (-      SELECT session_id, agent_id, focus, namespace, scope_kind, scope_ref, subject_ref,-             previous_session_id, parent_session_id, delegation_depth, status, started_at,-             completed_at, model_used, summary, error_message,-             awaiting_reason, awaiting_correlation_key, awaiting_deadline, resume_input,-             1 AS depth, ARRAY[session_id] AS path-      FROM kioku_sessions-      WHERE session_id = $1-      UNION ALL-      SELECT s.session_id, s.agent_id, s.focus, s.namespace, s.scope_kind, s.scope_ref, s.subject_ref,-             s.previous_session_id, s.parent_session_id, s.delegation_depth, s.status, s.started_at,-             s.completed_at, s.model_used, s.summary, s.error_message,-             s.awaiting_reason, s.awaiting_correlation_key, s.awaiting_deadline, s.resume_input,-             c.depth + 1, c.path || s.session_id-      FROM kioku_sessions s-      INNER JOIN chain c ON s.session_id = c.previous_session_id-      WHERE NOT s.session_id = ANY (c.path)-        AND c.depth < 10000+    ( "WITH RECURSIVE chain AS ("+        <> "SELECT "+        <> sessionRowColumns+        <> ", 1 AS depth, ARRAY[session_id] AS path"+        <> " FROM "+        <> sessionsTable+        <> " WHERE memory_space_id = $1 AND session_id = $2"+        <> " UNION ALL "+        <> "SELECT "+        <> qualifiedSessionRowColumns "s"+        <> ", c.depth + 1, c.path || s.session_id"+        <> " FROM "+        <> sessionsTable+        <> " s INNER JOIN chain c"+        <> " ON s.session_id = c.previous_session_id AND s.memory_space_id = c.memory_space_id"+        <> " WHERE NOT s.session_id = ANY (c.path) AND c.depth < 10000"+        <> ") SELECT "+        <> sessionRowColumns+        <> " FROM chain ORDER BY started_at ASC"     )-    SELECT session_id, agent_id, focus, namespace, scope_kind, scope_ref, subject_ref,-           previous_session_id, parent_session_id, delegation_depth, status, started_at,-           completed_at, model_used, summary, error_message,-           awaiting_reason, awaiting_correlation_key, awaiting_deadline, resume_input-    FROM chain-    ORDER BY started_at ASC-    """-    (E.param (E.nonNullable E.text))+    ( ((\q -> q.memorySpaceId) >$< memorySpaceParam)+        <> ((\q -> q.sessionId) >$< E.param (E.nonNullable E.text))+    )     (D.rowList sessionRowDecoder) -selectDelegationChildrenStmt :: Statement Text [SessionRow]+selectDelegationChildrenStmt :: Statement SessionDelegationChildrenQuery [SessionRow] selectDelegationChildrenStmt =   preparable-    """-    SELECT session_id, agent_id, focus, namespace, scope_kind, scope_ref, subject_ref,-           previous_session_id, parent_session_id, delegation_depth, status, started_at,-           completed_at, model_used, summary, error_message,-           awaiting_reason, awaiting_correlation_key, awaiting_deadline, resume_input-    FROM kioku_sessions-    WHERE parent_session_id = $1-    ORDER BY started_at ASC, session_id ASC-    """-    (E.param (E.nonNullable E.text))+    ( "SELECT "+        <> sessionRowColumns+        <> " FROM "+        <> sessionsTable+        <> " WHERE memory_space_id = $1 AND parent_session_id = $2\+           \ ORDER BY started_at ASC, session_id ASC"+    )+    ( ((\q -> q.memorySpaceId) >$< memorySpaceParam)+        <> ((\q -> q.parentSessionId) >$< E.param (E.nonNullable E.text))+    )     (D.rowList sessionRowDecoder) -selectTurnsBySessionStmt :: Statement Text [TurnRow]+selectAwaitingByCorrelationKeyStmt :: Statement AwaitingSessionsByCorrelationKeyQuery [SessionRow]+selectAwaitingByCorrelationKeyStmt =+  preparable+    ( "SELECT "+        <> sessionRowColumns+        <> " FROM "+        <> sessionsTable+        <> " WHERE memory_space_id = $1 AND namespace = $2\+           \ AND status = 'awaiting' AND awaiting_correlation_key = $3 ORDER BY started_at DESC"+    )+    ( ((\q -> q.memorySpaceId) >$< memorySpaceParam)+        <> ((\q -> q.namespace) >$< E.param (E.nonNullable E.text))+        <> ((\q -> q.correlationKey) >$< E.param (E.nonNullable E.text))+    )+    (D.rowList sessionRowDecoder)++selectTurnsBySessionStmt :: Statement TurnsBySessionQuery [TurnRow] selectTurnsBySessionStmt =   preparable-    """-    SELECT turn_id, session_id, turn_index, role, content, tool_summary, prompt_tokens,-           output_tokens, recorded_at-    FROM kioku_turns-    WHERE session_id = $1-    ORDER BY turn_index ASC-    """-    (E.param (E.nonNullable E.text))+    ( """+      SELECT memory_space_id, turn_id, session_id, turn_index, role, content, tool_summary,+             prompt_tokens, output_tokens, recorded_at+      FROM+      """+        <> " "+        <> turnsTable+        <> " "+        <> """+           WHERE memory_space_id = $1+             AND session_id = $2+           ORDER BY turn_index ASC+           """+    )+    ( ((\q -> q.memorySpaceId) >$< memorySpaceParam)+        <> ((\q -> q.sessionId) >$< E.param (E.nonNullable E.text))+    )     (D.rowList turnRowDecoder)  upsertSessionStmt :: Statement SessionRow () upsertSessionStmt =   preparable-    """-    INSERT INTO kioku_sessions-      (session_id, agent_id, focus, namespace, scope_kind, scope_ref, subject_ref,-       previous_session_id, parent_session_id, delegation_depth, status, started_at,-       completed_at, model_used, summary, error_message,-       awaiting_reason, awaiting_correlation_key, awaiting_deadline, resume_input, updated_at)-    VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15, $16, $17, $18, $19, $20, NOW())-    ON CONFLICT (session_id) DO UPDATE SET-      agent_id = EXCLUDED.agent_id,-      focus = EXCLUDED.focus,-      namespace = EXCLUDED.namespace,-      scope_kind = EXCLUDED.scope_kind,-      scope_ref = EXCLUDED.scope_ref,-      subject_ref = EXCLUDED.subject_ref,-      previous_session_id = EXCLUDED.previous_session_id,-      parent_session_id = EXCLUDED.parent_session_id,-      delegation_depth = EXCLUDED.delegation_depth,-      status = EXCLUDED.status,-      started_at = EXCLUDED.started_at,-      completed_at = EXCLUDED.completed_at,-      model_used = EXCLUDED.model_used,-      summary = EXCLUDED.summary,-      error_message = EXCLUDED.error_message,-      awaiting_reason = EXCLUDED.awaiting_reason,-      awaiting_correlation_key = EXCLUDED.awaiting_correlation_key,-      awaiting_deadline = EXCLUDED.awaiting_deadline,-      resume_input = EXCLUDED.resume_input,-      updated_at = EXCLUDED.updated_at-    """+    ( "INSERT INTO "+        <> sessionsTable+        <> "\n"+        <> """+             (memory_space_id, session_id, agent_id, focus, namespace, scope_kind, scope_ref,+              subject_ref, previous_session_id, parent_session_id, delegation_depth, status, started_at,+              completed_at, model_used, summary, error_message,+              awaiting_reason, awaiting_correlation_key, awaiting_deadline, resume_input, updated_at)+           VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15, $16, $17, $18, $19, $20, $21, NOW())+           ON CONFLICT (session_id) DO UPDATE SET+             memory_space_id = EXCLUDED.memory_space_id,+             agent_id = EXCLUDED.agent_id,+             focus = EXCLUDED.focus,+             namespace = EXCLUDED.namespace,+             scope_kind = EXCLUDED.scope_kind,+             scope_ref = EXCLUDED.scope_ref,+             subject_ref = EXCLUDED.subject_ref,+             previous_session_id = EXCLUDED.previous_session_id,+             parent_session_id = EXCLUDED.parent_session_id,+             delegation_depth = EXCLUDED.delegation_depth,+             status = EXCLUDED.status,+             started_at = EXCLUDED.started_at,+             completed_at = EXCLUDED.completed_at,+             model_used = EXCLUDED.model_used,+             summary = EXCLUDED.summary,+             error_message = EXCLUDED.error_message,+             awaiting_reason = EXCLUDED.awaiting_reason,+             awaiting_correlation_key = EXCLUDED.awaiting_correlation_key,+             awaiting_deadline = EXCLUDED.awaiting_deadline,+             resume_input = EXCLUDED.resume_input,+             updated_at = EXCLUDED.updated_at+           """+    )     sessionRowEncoder     D.noResult  sessionRowEncoder :: E.Params SessionRow sessionRowEncoder =-  ((\row -> row.sessionId) >$< E.param (E.nonNullable E.text))+  ((\row -> row.memorySpaceId) >$< memorySpaceParam)+    <> ((\row -> row.sessionId) >$< E.param (E.nonNullable E.text))     <> ((\row -> row.agentId) >$< E.param (E.nonNullable E.text))     <> ((\row -> row.focus) >$< E.param (E.nonNullable E.text))     <> ((\row -> row.namespace) >$< E.param (E.nonNullable E.text))@@ -568,26 +754,26 @@     <> ((\row -> row.awaitingDeadline) >$< E.param (E.nullable E.timestamptz))     <> ((\row -> row.resumeInput) >$< E.param (E.nullable E.text)) -updateSessionCompletedStmt :: Statement (Text, UTCTime, Maybe Text, Maybe Text) ()+updateSessionCompletedStmt :: Statement SessionCompletion () updateSessionCompletedStmt =   preparable-    "UPDATE kioku_sessions SET status = 'completed', completed_at = $2, model_used = $3, summary = $4, awaiting_reason = NULL, awaiting_correlation_key = NULL, awaiting_deadline = NULL, updated_at = NOW() WHERE session_id = $1"-    ( contrazip4-        (E.param (E.nonNullable E.text))-        (E.param (E.nonNullable E.timestamptz))-        (E.param (E.nullable E.text))-        (E.param (E.nullable E.text))+    ("UPDATE " <> sessionsTable <> " SET status = 'completed', completed_at = $3, model_used = $4, summary = $5, awaiting_reason = NULL, awaiting_correlation_key = NULL, awaiting_deadline = NULL, updated_at = NOW() WHERE memory_space_id = $1 AND session_id = $2")+    ( ((\c -> c.memorySpaceId) >$< memorySpaceParam)+        <> ((\c -> c.sessionId) >$< E.param (E.nonNullable E.text))+        <> ((\c -> c.completedAt) >$< E.param (E.nonNullable E.timestamptz))+        <> ((\c -> c.modelUsed) >$< E.param (E.nullable E.text))+        <> ((\c -> c.summary) >$< E.param (E.nullable E.text))     )     D.noResult -updateSessionFailedStmt :: Statement (Text, UTCTime, Text) ()+updateSessionFailedStmt :: Statement SessionFailure () updateSessionFailedStmt =   preparable-    "UPDATE kioku_sessions SET status = 'failed', completed_at = $2, error_message = $3, awaiting_reason = NULL, awaiting_correlation_key = NULL, awaiting_deadline = NULL, updated_at = NOW() WHERE session_id = $1"-    ( contrazip3-        (E.param (E.nonNullable E.text))-        (E.param (E.nonNullable E.timestamptz))-        (E.param (E.nonNullable E.text))+    ("UPDATE " <> sessionsTable <> " SET status = 'failed', completed_at = $3, error_message = $4, awaiting_reason = NULL, awaiting_correlation_key = NULL, awaiting_deadline = NULL, updated_at = NOW() WHERE memory_space_id = $1 AND session_id = $2")+    ( ((\c -> c.memorySpaceId) >$< memorySpaceParam)+        <> ((\c -> c.sessionId) >$< E.param (E.nonNullable E.text))+        <> ((\c -> c.failedAt) >$< E.param (E.nonNullable E.timestamptz))+        <> ((\c -> c.errorMessage) >$< E.param (E.nonNullable E.text))     )     D.noResult @@ -596,70 +782,65 @@ -- -- @awaiting_deadline@ is advisory only: it is stored for hosts, and kioku does not enforce -- it (no timer fires, nothing expires). See MasterPlan 2's Decision Log (2026-07-07).-updateSessionAwaitingStmt :: Statement (Text, Text, Maybe Text, Maybe UTCTime) ()+updateSessionAwaitingStmt :: Statement SessionPark () updateSessionAwaitingStmt =   preparable-    "UPDATE kioku_sessions SET status = 'awaiting', awaiting_reason = $2, awaiting_correlation_key = $3, awaiting_deadline = $4, resume_input = NULL, updated_at = NOW() WHERE session_id = $1"-    ( contrazip4-        (E.param (E.nonNullable E.text))-        (E.param (E.nonNullable E.text))-        (E.param (E.nullable E.text))-        (E.param (E.nullable E.timestamptz))+    ("UPDATE " <> sessionsTable <> " SET status = 'awaiting', awaiting_reason = $3, awaiting_correlation_key = $4, awaiting_deadline = $5, resume_input = NULL, updated_at = NOW() WHERE memory_space_id = $1 AND session_id = $2")+    ( ((\c -> c.memorySpaceId) >$< memorySpaceParam)+        <> ((\c -> c.sessionId) >$< E.param (E.nonNullable E.text))+        <> ((\c -> c.reason) >$< E.param (E.nonNullable E.text))+        <> ((\c -> c.correlationKey) >$< E.param (E.nullable E.text))+        <> ((\c -> c.deadline) >$< E.param (E.nullable E.timestamptz))     )     D.noResult -updateSessionResumedStmt :: Statement (Text, Text) ()+updateSessionResumedStmt :: Statement SessionResumption () updateSessionResumedStmt =   preparable-    "UPDATE kioku_sessions SET status = 'running', resume_input = $2, awaiting_reason = NULL, awaiting_correlation_key = NULL, awaiting_deadline = NULL, updated_at = NOW() WHERE session_id = $1"-    (contrazip2 (E.param (E.nonNullable E.text)) (E.param (E.nonNullable E.text)))-    D.noResult--selectAwaitingByCorrelationKeyStmt :: Statement AwaitingSessionsByCorrelationKeyQuery [SessionRow]-selectAwaitingByCorrelationKeyStmt =-  preparable-    """-    SELECT session_id, agent_id, focus, namespace, scope_kind, scope_ref, subject_ref,-           previous_session_id, parent_session_id, delegation_depth, status, started_at,-           completed_at, model_used, summary, error_message,-           awaiting_reason, awaiting_correlation_key, awaiting_deadline, resume_input-    FROM kioku_sessions-    WHERE namespace = $1-      AND status = 'awaiting'-      AND awaiting_correlation_key = $2-    ORDER BY started_at DESC-    """-    ( ((\(AwaitingSessionsByCorrelationKeyQuery ns _) -> ns) >$< E.param (E.nonNullable E.text))-        <> ((\(AwaitingSessionsByCorrelationKeyQuery _ k) -> k) >$< E.param (E.nonNullable E.text))+    ("UPDATE " <> sessionsTable <> " SET status = 'running', resume_input = $3, awaiting_reason = NULL, awaiting_correlation_key = NULL, awaiting_deadline = NULL, updated_at = NOW() WHERE memory_space_id = $1 AND session_id = $2")+    ( ((\c -> c.memorySpaceId) >$< memorySpaceParam)+        <> ((\c -> c.sessionId) >$< E.param (E.nonNullable E.text))+        <> ((\c -> c.input) >$< E.param (E.nonNullable E.text))     )-    (D.rowList sessionRowDecoder)+    D.noResult  -- | @(session_id, turn_index)@ is the turn's identity; @turn_id@ is an idempotency token -- that travels with it. The conflict clause updates @turn_id@ as well, so rebuilding the -- projection from the event stream cannot leave a superseded turn's id attached to the -- winning event's content.+--+-- The conflict target stays @(session_id, turn_index)@ rather than gaining the space. A+-- session id is globally unique and the aggregate pins each session to exactly one space, so+-- two spaces cannot produce the same pair; widening the key would /weaken/ it by letting one+-- session's turn index be written twice. insertTurnStmt :: Statement TurnRow () insertTurnStmt =   preparable-    """-    INSERT INTO kioku_turns-      (turn_id, session_id, turn_index, role, content, tool_summary, prompt_tokens, output_tokens, recorded_at)-    VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9)-    ON CONFLICT (session_id, turn_index) DO UPDATE SET-      turn_id = EXCLUDED.turn_id,-      role = EXCLUDED.role,-      content = EXCLUDED.content,-      tool_summary = EXCLUDED.tool_summary,-      prompt_tokens = EXCLUDED.prompt_tokens,-      output_tokens = EXCLUDED.output_tokens,-      recorded_at = EXCLUDED.recorded_at-    """+    ( "INSERT INTO "+        <> turnsTable+        <> "\n"+        <> """+             (memory_space_id, turn_id, session_id, turn_index, role, content, tool_summary,+              prompt_tokens, output_tokens, recorded_at)+           VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10)+           ON CONFLICT (session_id, turn_index) DO UPDATE SET+             memory_space_id = EXCLUDED.memory_space_id,+             turn_id = EXCLUDED.turn_id,+             role = EXCLUDED.role,+             content = EXCLUDED.content,+             tool_summary = EXCLUDED.tool_summary,+             prompt_tokens = EXCLUDED.prompt_tokens,+             output_tokens = EXCLUDED.output_tokens,+             recorded_at = EXCLUDED.recorded_at+           """+    )     turnRowEncoder     D.noResult  turnRowEncoder :: E.Params TurnRow turnRowEncoder =-  ((\row -> row.turnId) >$< E.param (E.nonNullable E.text))+  ((\row -> row.memorySpaceId) >$< memorySpaceParam)+    <> ((\row -> row.turnId) >$< E.param (E.nonNullable E.text))     <> ((\row -> row.sessionId) >$< E.param (E.nonNullable E.text))     <> ((\row -> fromIntegral @Int @Int32 row.turnIndex) >$< E.param (E.nonNullable E.int4))     <> ((\row -> row.role) >$< E.param (E.nonNullable E.text))