# Customer Curation Customer Curation is the V1 **personal-knowledge layer**: the surfaces that let a member keep, organize, annotate, share, and re-find anything they encounter anywhere on the platform — a Veritas claim, a Nisaba passage, a Nyx sky event, a Metis lesson, a Tara meditation transcript, an Arete habit, or a generated artifact. It serves every customer-facing domain rather than belonging to any one of them, and it is the substrate that Search and Recommendations read back from (see [Search, Discovery, and Knowledge Graph](./search-discovery-knowledge-graph.md)). This page sits among the cross-cutting product-surface deep-dives in the V1 architecture set hubbed at [../ARCHITECTURE.md](../ARCHITECTURE.md); product scope lives in [`V1/features.md` § Customer Curation, Notebooks, Collections, and Sharing](../features.md#customer-curation-notebooks-collections-and-sharing), and the backlog is [`V1/TODOS.md` § 17](../TODOS.md). > **Read this page for what is _shipping_ vs. _spec_.** The curation **logic is > real and non-stub**: it ships as a pure, dependency-free contracts-and-logic > library, `@oshun/customer-curation` (`libs/oshun/customer-curation`), whose > seven collection kinds, sharing-permission resolver, smart-collection rule > engine, W3C-style annotation anchoring, oEmbed share cards, and version-diff > engine are all implemented with domain-specific algorithms and exercised by a > large test file (`src/customer-curation.test.ts`). What is **aspirational > relative to this library** is the _platform plumbing_ the architecture text > attributes to it: durable database persistence, tombstone-deletion > propagation, audit-logging, cross-device progress _sync_, and the binding to > the Iris `notebook` memory scope. All of them live **outside** this pure > library (in infra and other libs) or remain partial. The completeness audit > (2026-06-22) flags `library-save-collection-share` and `scene-keep-and-share` > as **PARTIAL** walkthrough journeys — consistent with the library being > contract-complete while the end-to-end persisted flow is still thinner than > the prose implies. ## Where the logic actually lives Everything described below is implemented in one package: - **Package:** `@oshun/customer-curation`, version `0.1.0`, `private: true`. - **Dependencies:** **none at runtime.** `package.json` declares only `devDependencies` (`typescript`, `vitest`) — it is a pure data-and-functions library with `sideEffects: false`. Notably it does **not** depend on `@oshun/persistence`, does not import any database client, and contains no code that references "tombstone" or writes an audit log. Those behaviors, where they exist, belong to other libraries wired at the call site. - **Barrel:** `src/index.ts` re-exports six modules — `collections`, `sharing`, `share-cards`, `annotations`, `bookmarks`, and `version-awareness`. | Module | Path | Responsibility | | ----------------- | -------------------------------------------- | ---------------------------------------------------------------------------------- | | collections | `src/collections/` | Seven collection kinds, validation, smart collections, ordering, templates, import | | sharing | `src/sharing/sharing.ts` | Visibility/permission matrix and viewer-resolution | | share-cards | `src/share-cards/share-cards.ts` | Embeddable cards, oEmbed and HTML rendering, indicator preservation | | annotations | `src/annotations/annotations.ts` | Highlights, notes, threads, citations, selector-chain anchoring, exports | | bookmarks | `src/bookmarks/bookmarks.ts` | Per-device cursors, EWMA pace, time-to-finish, reading-list progress | | version-awareness | `src/version-awareness/version-awareness.ts` | Staleness verdicts and Myers/LCS passage diff | ## Collections — seven kinds, one taxonomy The heart of the library is a single collection taxonomy, defined in `src/collections/types.ts`. `COLLECTION_KINDS` enumerates six canonical container kinds — `notebook`, `collection`, `study-queue`, `ritual-set`, `reading-list`, and `saved-search` — and `collections.ts` adds an `OrderedCollection` for the bare `collection` kind, so seven concrete `CustomerCollection` shapes exist in total. Every kind extends a shared `CollectionBase` (`collectionId`, `kind`, `ownerId`, `tenantId`, `parentCollectionId`, `title`, timestamps, `archivedAtUnixSeconds`, and an ordered `items: CollectionArtifactRef[]` list). Each kind then layers on **kind-specific schema fields** that the prose "study queues, ritual sets, reading lists, saved searches" hides: | Kind | Interface | Kind-specific fields | | -------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------- | | `notebook` | `NotebookCollection` | `layout: 'linear' \| 'kanban' \| 'grid'` (`NOTEBOOK_LAYOUTS`) | | `collection` | `OrderedCollection` | (ordered set; base only) | | `study-queue` | `StudyQueueCollection` | `masteryTarget: 'familiar' \| 'developing' \| 'proficient' \| 'master'`, `perDayCap: number \| null` | | `ritual-set` | `RitualSetCollection` | `cadenceLocalTime: string \| null` (`HH:MM`), `cadenceDaysOfWeek: ReadonlyArray<0..6>` mask (0 = Sun … 6 = Sat) | | `reading-list` | `ReadingListCollection` | `targetFinishUnixSeconds: number \| null` | | `saved-search` | `SavedSearchCollection` | `queryText`, `filters` AST, `artifactKindFilter`, `lastExecutedCursor` | Membership is by **typed reference, not by copy**. A `CollectionArtifactRef` records the `artifactId`, an `artifactKind` drawn from the large cross-domain `ARTIFACT_KINDS` union (e.g. `nisaba.edition`, `veritas.claim`, `metis.lesson`, `tara.ritual-script`, `nyx.sky-event`, `arete.habit`, `oshun.generated-artifact`), a `pinnedVersion: number | null` (where `null` means _always-latest_ and a number pins the exact version saved), a free-form `note`, an `ordinal`, and `addedAtUnixSeconds`. Pinning is what makes the version-awareness feature later in this page possible. ### Validation is the contract `validateCollection(collection, { tenantId })` returns a typed `CollectionValidationError[]` — never throws — so callers compose it into their own request handling. The error union is exhaustive and kind-aware. Beyond the generic checks (`empty-title`, `tenant-mismatch`, `created-after-updated`, `archive-before-created`, duplicate-artifact and duplicate/invalid-ordinal, `invalid-pinned-version`), it enforces each kind's rules: - **notebook** — `layout` must be one of `NOTEBOOK_LAYOUTS` (`invalid-notebook-layout`). - **ritual-set** — every `cadenceDaysOfWeek` entry must be in `0..6` (`invalid-cadence-day`), no duplicates (`duplicate-cadence-day`), and `cadenceLocalTime` must match `^([01]\d|2[0-3]):([0-5]\d)$` (`invalid-cadence-time`). - **study-queue** — `perDayCap`, when set, must be an integer in `1..200` (`per-day-cap-out-of-range`). - **reading-list** — `targetFinishUnixSeconds`, when set, must be an integer not earlier than `createdAtUnixSeconds` (`invalid-target-finish`). - **saved-search** — non-empty `queryText`, non-empty `artifactKindFilter` whose entries are real `ARTIFACT_KINDS`, and well-formed filter predicates (`facet` and operator in `eq | in | gte | lte | contains`). The kinds also carry **real behavioral helpers**, not just shape: `nextStudyQueueItem` ranks queue items by a mastery ladder (`novice < familiar < developing < proficient < master`) and returns the first item still below `masteryTarget`, breaking ties by `ordinal`; `pendingReadingListItems` filters a reading list to artifacts whose progress fraction is `< 1`, ordered by `ordinal`; and `ritualSetDueToday` answers the day-of-week-mask question (an empty mask means _every day_). ### Ordering, nesting, templates, import Four supporting files round out the collections module — the features promised by "drag-and-drop ordering, nested collections, … templates, and import from another collection": - **`ordering.ts`** implements gap-based drag-to-order. `reorderArtifact` places an item immediately after another (or at the front) by computing a new ordinal — midpoint between neighbors, or `± DEFAULT_ORDINAL_GAP` (`1024`) at the edges — and triggers a `normalizeOrdinals` pass when gaps collapse below threshold. It also exposes `validateNestedParent` and `buildBreadcrumb` for nested collections. - **`templates.ts`** defines `CollectionTemplate` / `CollectionTemplateItem`, `instantiateTemplate`, and `templateVisibleTo` for the role-aware template gallery. - **`import-from-another.ts`** implements `importCollection`, which **requires an authorization grant from the sharing layer**: the input carries a `grant` whose `sourceCollectionId` must match the source, whose `grantedToOwnerId` must be the importer, and which must be `copy`-tier; cross-tenant copy must be opted in via `allowCrossTenantCopy`. The result is a tagged union — `{ ok: true, collection }` carrying `originCollectionId` / `originOwnerId` provenance, or `{ ok: false, reason: 'grant-mismatch' | 'insufficient-tier' | 'tenant-isolation' }`. ## Smart collections — a real rule engine The features line "smart collections (rule-based)" undersells what `src/collections/smart-collections.ts` ships: a small but real predicate engine in **conjunctive normal form** (AND-of-OR). A `SmartCollectionRules` has `allOf: SmartCollectionRuleGroup[]` (every group must match), each group an `anyOf: SmartCollectionPredicate[]` (any predicate inside it matches), plus a `limit` and an `orderBy` (`recency-desc | recency-asc | relevance-desc | alphabetical`). The `SmartCollectionPredicate` union covers artifact-kind eq/in, tenant/owner equality, `tag-in`/`tag-contains`, `created-at` gte/lte, `domain-eq` (over a `SmartCollectionDomain` of the ten platform domains), `synthetic-indicator-eq`, `grounding-state-eq` (`grounded | partial | ungrounded | abstained | retracted-source`), and a case-insensitive `text-contains` over title or description. Three public functions drive it: - `validateSmartCollectionRules(rules)` returns typed errors (`empty-rule-set`, `empty-rule-group`, `invalid-limit`, `empty-text-query`, `empty-tag-list`, `unknown-artifact-kind`) so a rule set is checked before it is ever evaluated. - `evaluateSmartCollection(rules, candidates)` filters candidates through the CNF, then sorts by `orderBy` and applies `limit`. - `materializeSmartCollectionForOwner(rules, candidates, scope)` is the **scoped** entry point that ad-hoc callers should use: it keeps tenant/owner isolation out of caller hands by first dropping any candidate whose `tenantId` differs, then admitting only owner-owned artifacts **or** artifacts whose `${artifactKind}:${artifactId}` key appears in `scope.sharedArtifactKeys` (which must already be authorized by the sharing layer) — before delegating to `evaluateSmartCollection`. A `smartRulesEqual` helper canonicalizes rule groups (sorting predicates and `tag-in`/`artifact-kind-in` value lists) so two rule sets can be compared for equivalence — used to dedupe smart collections in a library and to short-circuit re-evaluation when nothing changed. ## Sharing — visibility × permission, with a viewer resolver `src/sharing/sharing.ts` models sharing as **two orthogonal axes**. Visibility (`SHARE_VISIBILITY`, least → most permissive) is `private`, `named-users`, `link`, `public-profile`; permission grants (`SHARE_PERMISSION`) are `view`, `comment`, `copy`. A `SharePolicy` carries the visibility plus the named-user grants, tokenized link grants, and the public-profile surface. The core is `resolveSharePermission(input)`, which decides what a specific viewer gets. Viewers are typed — `owner`, `authenticated` (with `userId` and `tenantId`), `link` (with `providedTokenHash`), or `public-profile-visitor` — and the resolver returns either `{ granted: true, tier, via }` (where `via` is `'owner' | 'named' | 'link' | 'public-profile'`) or `{ granted: false, reason }`. The denial reasons are an honest enumerable set: | `ShareDenialReason` | When it fires | | ----------------------------- | ---------------------------------------------------------- | | `private` | Visibility is private (or wrong viewer for the visibility) | | `not-in-named-list` | Authenticated viewer absent from `namedUserGrants` | | `link-expired` | Link grant past `expiresAtUnixSeconds` | | `link-revoked` | Link grant has a `revokedAtUnixSeconds` | | `link-token-mismatch` | No link grant matches the provided token hash | | `public-profile-not-enabled` | `public-profile` visibility but surface disabled | | `public-profile-missing-slug` | Surface enabled but no `profileSlug` | | `tenant-isolation` | Authenticated viewer's `tenantId` ≠ policy's | Security-relevant details are real, not hand-waved. The owner always resolves to `copy` tier. Link verification uses a `timingSafeEqual` constant-time comparison (length-masked to avoid early-return timing leaks) — the module **compares** token hashes but explicitly leaves crypto-secure **generation** to the caller. A named-user grant takes precedence even when visibility is `link` or `public-profile`, so an explicitly named viewer is never _down_-graded by a broader surface. Companion functions cover the lifecycle: `validateSharePolicy` (duplicate grants, expiry/revocation before creation, public-profile enabled without slug), `revokeLinkGrant`, `revokeNamedUserGrant`, `sharePermissionSatisfies` / `sharePermissionRank` (view = 1, comment = 2, copy = 3), and `publicProfileSurfacedSlugs` to build a member's public profile page. ## Annotations — W3C-style selector chains `src/annotations/annotations.ts` is far more concrete than "highlights, threaded notes, citations." Annotations attach to one of four reading surfaces (`ANNOTATION_SURFACES`: `nisaba.edition`, `veritas.story`, `metis.lesson`, `tara.transcript`) and come in four kinds (`ANNOTATION_KINDS`: `highlight`, `note`, `thread-comment`, `citation`). Spans use the same **selector-chain model as Hypothes.is / W3C Web Annotations**: an `AnnotationTarget` carries a `TextQuoteSelector` (`exact`, `prefix`, and `suffix`) and a `TextPositionSelector` (`start`/`end` offsets), so anchors survive small edits. `resolveAnnotationAnchor(annotation, currentText)` is the recovery algorithm, with a documented strategy precedence: 1. **`exact`** — the saved `position` still slices to `quote.exact` in the current text; reuse it verbatim. 2. **`context`** — `prefix + exact + suffix` occurs exactly once; re-anchor to the `exact` substring inside it. 3. **`quote-only`** — `exact` alone occurs exactly once (lossy); use it. 4. Otherwise **unresolved** (`null`) — the library refuses to guess rather than anchor to the wrong place. Threads are validated for durability across a batch by `validateAnnotationThreadIntegrity`, which catches `thread-parent-not-found`, `thread-parent-cross-tenant`, `thread-parent-cross-owner`, `thread-parent-not-threadable`, `thread-parent-target-mismatch`, and `thread-parent-cycle`. `buildAnnotationThread` assembles a tree while keeping a deleted node only if it still has live children (preserving thread cohesion), and `deriveBacklinks` materializes the **cross-artifact backlinks** the features doc mentions: each non-deleted `citation` annotation yields an `AnnotationBacklink` record on its target. Export is implemented for all three formats: `exportAnnotationsAsJson` (canonical, stable-sorted), `exportAnnotationsAsMarkdown` (grouped by artifact, chronological), and `exportAnnotationsAsCsv` (**RFC-4180** escaping, deleted rows excluded so the export matches what the reader sees). ## Share cards — provenance that survives the embed `src/share-cards/share-cards.ts` implements embeddable cards for the kinds in `SHARE_CARD_KINDS` (`veritas.story`, `veritas.claim`, `nisaba.passage`, `nyx.sky-event`, `tara.meditation`, `metis.module`, `metis.lesson-module`). A `ShareCard` bundles three signal blocks that **must never be stripped** during an embed: a `ProvenanceBlock` (source attribution, author ids, evidence-pack and citation-trail refs, publish time), a `GroundingBlock` (state, citation count, `retrievalMethods` such as `bm25`/`dense`/`hybrid`/`graph`, retracted-source count), and a `SyntheticIndicatorBlock` (voice/avatar/text synthesized flags plus the persona/voice/avatar resource ids). The architecture text notes the indicators are "preserved" but omits that the **rendering is implemented**: - `renderShareCardHtml(card)` emits an `
` with every author-controlled field HTML-escaped (`escapeHtml`) to prevent XSS, and encodes provenance/grounding/synthetic state as **visible badges** plus an embedded `