# Iris learning map and pinned-code boundaries

Source revision: `1ceae52c7896a59ac74a4429d410f3218f0b91c6`. The original
partial review below has now been completed by the
[forty-four-slide Iris guide](../decks/iris.html) and the
[depth review](../authoring/v1-iris-depth.md). This establishes complete
teaching of the two pinned Iris pages, not memory safety, consumer UI or
deployed-service acceptance.

## Learning sequence and reviewed units

The Iris guide now separates identity, scope, recall, relevance scoring,
consent, inspection and a worked write/recall comparison. Two focused slides
were added for scoring and inspection; the count follows those learning tasks,
not a fixed guide-size target. The shared substrate explanation remains
unchanged. The Eve memory-consent slide is corrected in both Iris and the Eve
context guide so the overview does not repeat the disproven guarantee.

[Six reviewed assignments](../assignments/iris-memory-boundaries.json) bind the
assembled explanations, including inherited chapter/release, to complete units
in `V1/architecture/substrate-iris.md`:

| Unit                                           | Lines   | Teaching home                 |
| ---------------------------------------------- | ------- | ----------------------------- |
| Scope: eight kinds, not five                   | 132–164 | `iris-scope-model`            |
| Consent on the entry vs. the ledger            | 192–210 | `iris-consent-and-inspection` |
| Per-surface budgets                            | 295–312 | `iris-recall-resolution`      |
| The ranker and its honest approximation        | 313–336 | `iris-ranker-factors`         |
| The audit envelope                             | 337–350 | `iris-recall-resolution`      |
| Conflict resolution — provenance beats recency | 375–395 | `iris-worked`                 |

The full architecture and Iris feature pages were reviewed. Implementation
review covered the complete pinned entry/primitives schemas, recall pipeline,
in-memory store, write-conflict helper, consent ledger and inspection state
machine, plus the adapter scope declaration. The privacy feature introduction
and consent/withdrawal discussion establish its stated pure-core/runtime
boundary; this is not a full privacy implementation review.

## Corrections backed by executable code

`tools/presentations/tests/pinned-iris-memory.test.mjs` transpiles and executes
the original pinned modules. The entry schema uses the actual pinned primitives
with the installed contracts package's Zod dependency. Recall calls the actual
sensitive-category predicate. Write-plan tests guard unused audit/redaction
dependencies with throwing replacements; they do not claim that append-audit
integration was exercised. Controlled dates, candidate records, requests and
sink acknowledgements keep these examples deterministic. Transpilation is not a
TypeScript project typecheck or a deployed authorization test.

### Write policy is not recall deduplication

The write helper compares adapter records using explicit metadata keys or a
short text prefix. Matching different-content candidates are ordered by
`createdAt`, not `assertedAt`. Metadata source-kind overrides precede consumer
and ordinary source inference; integrations must validate their provenance.

Prior user-stated/confirmed facts are protected from inferred writes, including
admin-copilot inference. Other conflicts need a response even when their rule is
named `most-recent-wins`. `accept_new` and `merge` allow a plan; neither
persists data in this function.

Recall independently groups canonical entries by category, actor handle and
normalized subject, then picks the newer `updatedAt`, regardless of origin or
score. Equal times retain the first ranked candidate. Different wording can
produce different keys; this is not semantic contradiction detection. The
architecture's claim that the provenance ladder also runs during recall is
contradicted by its pinned implementation. The short-versus-long preference
example executes both paths and demonstrates opposite winners.

### Relevance, reachability and audit

- Scoring blends recency 0.40, lexical Jaccard 0.35, capped reference frequency
  0.15 and origin 0.10. Thirty days is the recency **e-folding time**, not the
  half-life stated in the prose: the factor is `exp(-1)` at thirty days and
  halves at about 20.8 days. A last reference supersedes the update timestamp
  for this calculation; nonpositive age scores one.
- All eight canonical scope shapes and eleven adapter names are distinguished.
  Pose-to-scene recall does not check room ID. Crisis scope alone is not
  `crisisFrame`; tenant entries are excluded from crisis scope by an earlier
  branch. Tenant-null entries can pass the separate tenant check; matching
  scope/user constraints still apply. Top-level entry user ID is not checked
  against scope user ID by either the entry schema or recall.
- Gates precede scoring: tenant, scope, crisis, suppression/lifecycle, then
  sensitive consent/context. Sensitive multi-actor entries accept either their
  category consent or `multi-actor-sensitive`, with relationship/safety/crisis
  context instead of the category's ordinary context mapping.
- `suppression.endsAt` governs suppression; `startedAt` is ignored. Recall does
  not inspect entry `expiresAt`, entry consent `revokedAt`, the consent ledger
  or a revision store. Current grants and eligible revisions must be derived by
  its caller.
- Budgets are 12/3/999/100 for assistant/shell/notebook/admin. Rationale is
  marked visible only for notebook/admin; it is a template, not a factor-level
  explanation. Missing surface budgets fall back to shell.
- Gate reason counts omit conflict and budget losers. Optional audit ingestion
  is not awaited, so a successful result is not a persisted receipt. Admin
  non-DSAR redaction removes `multiActor`, not body text.

### Revisions and erasure

The schema has 29 categories, not approximately 28; 19 are sensitive. It
validates a 1–4000-character body but accepts whitespace-only text and does not
validate consent, revision topology or identity agreement across fields.

`MemoryStore` holds in-memory maps, not durable storage. Updates produce linked
revisions but also change the prior stored lifecycle to `superseded`; the old
record is not byte-for-byte immutable. External returned copies cannot mutate
the stored snapshot. A mutator can remove original provenance links, while the
audit chain is preserved separately. `recordReference` adds another revision.
`summarize` adds ancestor references without changing source-entry lifecycles.

Tombstones retain body/history and block subsequent updates to that entry in
this store. They do not erase data or invalidate a previously copied active
entry supplied to recall. Full erasure and non-revival require evidence from the
persistence, replication, summaries and rights integrations.

### Consent and inspection

Consent append checks user, duplicate IDs and capture chronology, but does not
call the full ledger validator. Invalid supersession/fingerprints can be
appended and then rejected by explicit validation. Events/arrays are not durable
immutable storage merely because their TypeScript fields are readonly.

The 64-bit FNV-1a event fingerprint binds selected fields; it excludes metadata
and witness display labels and is not an authenticated signature. Rewriting a
bound field and recomputing its fingerprint passes. Stored terms hashes are not
automatically compared against live rendered terms. Active views choose the
latest captured event per consent type, not per scope, and do not honor future
effective/capture times. Only time-expired grants are downgraded.

The inspection state machine enforces transitions and a policy over supplied
request fields. Consent snapshot IDs and signed incident references are checked
for presence, not fetched or authenticated here. Target sensitivity and granted
entries come from the caller; the gate does not validate each entry against
target identity or recompute sensitivity. Non-DSAR metadata redaction leaves
body text intact. Audit objects and a 72-hour pending-notice queue are local
artifacts, not persisted audit records or delivered notices. No production
privacy violation or authenticated exploit is inferred from these module-level
counterexamples.

## Completed source decomposition and remaining product verification

The generated `v1-iris-depth.json` assignment now binds every meaningful unit
that was open in these two source pages. Keep the following product and
integration work open:

- Complete entry field, category, provenance, suppression and audit inventories;
  schema constraints and runtime refinements must be taught distinctly.
- Trace adapters, storage admission, retention envelopes, promotion thresholds,
  compaction and provenance through actual consuming routes. The write helper
  and canonical recall are not assumed to share one integrated pipeline.
- Teach privacy-suppression storage/recall helpers, revocation cascade, PII
  tokenization and multi-actor namespace/association forgetting in full.
- Cover all consent enums, validation errors, transport conversion, mutable
  aliasing boundaries, scope derivation and current-terms integration.
- Cover data-rights payloads, transitions, verification/deadline/retention
  behavior, result fingerprints, actual erasers, export artifacts and fan-out.
- Trace authenticated inspection callers, all policy conditions, snapshot
  selection, audit persistence, carveouts, notice delivery and replay.
- Inspect the partial customer memory UI and mobile equivalent against all
  intended edit/pause/forget/export flows, with actual screenshots and deep
  applicable browser/mobile automation. No UI-completeness assertion follows
  from these pure-module tests.
- Teach canonical continuation tokens, cross-device conflict/reconnect,
  scene/pose and shell bridge paths with end-to-end evidence.
- Reconcile every claimed evaluation/release gate with executable definitions
  and results. Module tests do not establish global leakage, deletion,
  deployed-service or full-library acceptance.
- Finish narration for the entire library, normal-speed listening, final
  all-slide/PDF/diagram review, whole-monorepo inventory expansion and actual
  Eve integration in the order required by the TODOs.

The design keeps one dominant comparison or sequence per slide. Detailed
counterexamples stay in notes and cited source context. Browser playback and
decoded-pause checks must not be reported as a human normal-speed listening
review.
