Source revision: 1ceae52c7896a59ac74a4429d410f3218f0b91c6. Review date:
2026-09-06. This record supports the architecture and communication/discovery
narration continuation. These two overview guides do not exhaust the shared
systems or whole-monorepo scope in TODOS.md.
Reading and evidence boundary#
Read the complete pinned high-level architecture, foundations, communication patterns, data architecture/tenancy and search/discovery architecture pages, and both customer-curation architecture and feature pages. Also read the opening search/discovery feature sections, curation package metadata, public barrel, collection-kind declaration and collection union, the three additional module entry points, complete clip minting, and selected clip parsing, review-session, share-card rendering, bookmark pace and version-diff code. Read the entire pinned partial-failure-envelope and EventBus implementations. Compared the 21 ordered guide-slide instances and their explanations with this material. This is source review, not a current deployment trace, live provider test, or whole-guide normal-speed listening review.
Two units are newly assigned as reviewed: the communication-patterns partial-failure contract and the curation package inventory/responsibility boundary. Similar units in Foundations and Data Architecture remain separately accountable, as do all neighboring event, queue, tenancy, discovery and curation algorithm units. Source reading and executable examples do not automatically close those units.
Corrections supported by executable examples#
The complete communication-patterns unit The partial-failure envelope
contract, lines 310–353, is covered by
architecture-partial-failure.json.
It binds the assembled partial-failure-contract and architecture-failure
slides to the exact unit and slide hashes.
- The base schema's results array can be empty even when
partialis true. The flag is equivalent to nonempty errors, not a guarantee of a successful item. The closing recovery table now identifies a reported failure without inventing a completed effect. - The error schema requires nonempty domain and message, and validates an optional nonempty stage. The generic factory supplies typed results and an optional custom error schema while retaining both flag invariants.
- The builder copies the two arrays and derives the flag; it rejects an explicitly contradictory flag but does not parse element payloads. The structural guard only checks two arrays and a boolean. Counterexamples pass that guard and fail real schema parsing.
- Seven Node regressions execute the pinned contract with the contracts package's installed Zod 4.4.3. They cover both flag contradictions, default and generic schemas, malformed errors, empty results, the structural guard and shallow array copying. This is not route or persistence acceptance.
The event-bus-reality explanation also gains code-grounded caveats, without
claiming a whole event-bus unit has been taught:
- Persistence defaults on with an 86,400-second event TTL, but can be disabled. A publication identifier does not prove any subscriber completed work.
replayUnacked()returns zero when persistence is disabled. Otherwise its count is the number of events republished, not successful handler effects.- The scheduler executes separate
zrangebyscore,zremandpublishcalls, despite a comment describing a Lua transaction. Its caught publication error is not followed by reinsertion into the scheduled set. Retained event keys are a separate, TTL- and configuration-dependent recovery mechanism. - Group claim keys use
SET ... EX eventTtl NX. An existing claim refuses another claimant; a stored claim is not an acknowledgement or a completed effect. Real restart/replay acceptance must account for this lifetime. - Five Node regressions execute the original pinned methods with controlled Redis replies and a manually triggered scheduler callback. No Redis server, real timer, network or worker deployment is exercised. These tests prove the observed command and return-value boundaries, not durable recovery.
The complete curation architecture unit Where the logic actually lives, lines
34–56, is covered by
shared-curation-surface.json.
- Both curation pages say seven collection kinds, but the enum and concrete union contain six: notebook, collection, study-queue, ritual-set, reading-list and saved-search. The overview now explicitly corrects that count.
- The package is private, version 0.1.0, declares no runtime dependencies and marks side effects false. Its public entry exports nine groups, not the six listed in the architecture page. Review, importers and web clipper are the additional groups; their internal algorithms still need detailed guides.
- The explanation covers the listed collections, sharing, share-card, annotations, bookmarks and version-awareness responsibilities. HTML/oEmbed indicators are generated output, not proof that an external consumer preserves them. Package metadata does not establish database writes, deletion, audit or cross-device transport.
- Three additional Node regressions check the pinned enum and union, metadata, module inventory and authored correction. They do not exercise live or persisted journeys. The three new code citations expose the exact package, barrel and taxonomy behind the corrected counts.
Further source findings, not automatic teaching assignments#
- Pinned BFF source search finds the actual
@oshun/search-discoveryimport insearch/offline-eval-route.ts; the other hits include commentary and a docs fixture, not additional live ranking imports. Keep implementation imports distinct from source-index mentions. - The high-level map's universal layer-by-layer path and registry URL labels are not production route evidence. The current architecture overview already separates registry metadata, mounted requests and actual owner traces.
- The event-bus source also requires explicit acknowledgement, uses generated broadcast subscription identities and has group-claim and replay lifetimes that need detailed restart analysis. Do not turn the header's broad crash-recovery language into an unqualified guarantee.
Coherent guides still needed#
Architecture, contracts and data#
Explain the exact registry/adapter boundary and compare representative mounted routes, including Metis's dedicated application/service/mobile stack. Teach the full shell and surface inventory, dynamic deep-tool routes, connection/release gates and the distinction between a reachable route and an active domain. A single layered map cannot establish that every request uses every substrate or store.
Complete the contract namespaces, generated OpenAPI/client and persistence artifacts, round-trip fixtures, drift/index/migration tests and compatibility procedures with real worked changes. The existing renamed-field example is an illustration, not a performed migration. Teach each BFF cache-hit and cache-miss branch with actual authorization, replay scope, result storage and event/audit ordering; a conceptual middleware list is not a verified mounted composition.
Give domain-owned authoritative state and derived projections explicit lifecycles. Development database names and example pooler URLs are not proof of production topology. Work through every tenancy/consent field, inheritance override, home-zone decision, role/scope projection, cache boundary and erasure outcome. The simplified five-scope tenancy diagram must not replace the actual Iris scope contract. Preserve denial, legal hold, retained audit, derived-copy invalidation and provider boundaries without claiming a complete deletion from one tombstoned row.
Events, queues and integration#
Build separate mechanism and recovery explanations for publication, explicit acknowledgement, broadcast/group identity, retained replay, delayed scheduling, retry exhaustion and dead letters. Teach topic lifecycle/version resolution and the advisory versus enforced validation distinction. Trace loss, duplicate, expiry and restart cases against the actual Redis configuration and consuming worker. Document each result independently: domain commit, publication, subscriber effect and acknowledgement are different evidence.
Keep durable queue storage, in-memory development behavior, priority, deduplication, lease/worker policy, retries, dead letters and per-job-class SLA monitoring distinct. Explain all inbound connector modules and outbound webhook signing/rotation/audit, with separate simulator and real-provider acceptance. No fixed slide or guide count limits that decomposition.
Discovery and curation#
Teach search's authorized feed, seed and owner-object candidate pools; query guards; exact lexical/kind/domain-intent weights and tie-breaking; partial responses; caching and telemetry. Recommendations need their full adapter inputs, nine reasons, five scoring dimensions, preference curve and feedback semantics. The documented feedback endpoint validates, logs and emits telemetry; that alone does not establish durable suppression or model training.
Explain the adopted offline gate's six metrics, baseline/candidate matching, minimum-detectable-effect thresholds, drift checks and failing examples. Keep the retired rich ranker, signal pipelines, cold start, concept-graph candidates and online experimentation visible as their own implementation/adoption work, not quietly connected to live search by a diagram.
Curation needs all six collection kinds and artifact types, field/refinement rules, ordering and normalization, cycle-safe nesting, templates, authorized import, CNF smart rules, visibility/permission resolution, annotation recovery and thread integrity, exports, cursor merge/pace estimation and version diffs. Distinguish the pure library's own notebook model from the separate contracts Notebook and Iris notebook memory. Generated share-card metadata cannot itself force an external embedder to preserve indicators. Actual consumer rendering, persisted sharing, revocation, deletion, audit and cross-device replication remain separate integration evidence.
Teach the additional review, importer and web-clipper modules as actual code surfaces, not invisible extensions of the architecture page's older six-group list. Reading their entry points and selected implementations establishes their presence and responsibilities, not complete algorithm or security acceptance.
Continue the full implementation, operational, UI/UX, generation, Domains and actual Eve work in the master checklist. This map records uncovered depth; it does not replace the inventory or narrow the requested final scope.