# Shared architecture: source review and remaining learning depth

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](../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`](../assignments/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 `partial` is 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`, `zrem` and `publish` calls,
  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`](../assignments/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-discovery` import in
  `search/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.
