research: Notion deep dive (closed block-DB SaaS, external REST API only, database-as-pages); UC-57/58/59

The closed/hosted/schema-rich extreme: everything is a block (UUID id,
type, properties, ordered child content, single parent), pages are blocks
and database rows are pages with a schema, Postgres-backed hosted SaaS.
Databases add typed properties + relations + rollups + formulas across
many views = the apex of wiki-page-as-structured-record. Extension model
has no in-app plugin runtime; the only extensibility is the external REST
API (+ webhooks 2026) inside a tight envelope (~3 rps, eventual
consistency, recursive child fetch, scoped/revocable per-page grants).
Adds the third attachment mode (external-API-only) alongside file-store
(Obsidian/TWiki) and in-engine host (Roam/XWiki); Notion enforces no
silent remote mutation via scoped grants. Added UC-57 (attach closed
external-API-only shard w/ operational envelope + scoped grant), UC-58
(typed database w/ schema+relations+views, no flattening), UC-59
(lossy-aware translation w/ fidelity report); enriched
UC-31/34/36/39/50/51/52/54/56. Boundary: one external-API candidate shard,
best as projection/mirror/overlay/backup, not a substrate and not the
federation layer.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

spec/UseCaseCatalog.md

@@ -7,7 +7,8 @@ Promoted from `research/260608-c2-wiki-origins/`,
 `research/260608-wikiengines-overview/`, `research/260613-xwiki-deep-dive/`,
 `research/260613-twiki-deep-dive/`, `research/260613-foswiki-deep-dive/`,
 `research/260614-xanadu-deep-dive/`, `research/260614-zigzag-deep-dive/`,
-`research/260614-roam-deep-dive/`, and `research/260614-obsidian-deep-dive/`.
+`research/260614-roam-deep-dive/`, `research/260614-obsidian-deep-dive/`, and
+`research/260614-notion-deep-dive/`.
 See InfoTechPrimers on coulomb.social for use-case catalog conventions.
 
 ## Conventions
@@ -177,7 +178,10 @@ triggering projection refresh or reconciliation review.
 Transport is adapter concern; freshness surfaced in UC-24. XWiki deep dive adds a
 concrete push transport: an engine event bus (`ObservationManager`
 `DocumentUpdatedEvent`) consumed by a listener, vs polling REST history
-(`research/260613-xwiki-deep-dive/findings.md` §2.5, §8 Q4).  
+(`research/260613-xwiki-deep-dive/findings.md` §2.5, §8 Q4). Notion adds **webhooks**
+(2026) delivering page/database change events — a SaaS push transport, weighed against
+eventual consistency and the rate limit (`research/260614-notion-deep-dive/findings.md`
+§4).  
 **Priority:** Later
 
 ### UC-32 — Transclude remote span with live freshness
@@ -230,7 +234,9 @@ topic text file*, so structure is diffable rather than locked in a DB
 sidecar metadata, and a candidate for query delegation (UC-52). Obsidian shows the
 **git-diffable in-file** variant: YAML frontmatter/properties live in the Markdown text
 and are queried by the Dataview plugin (`research/260614-obsidian-deep-dive/findings.md`
-§3) — structure as portable text, not DB state.  
+§3) — structure as portable text, not DB state. **Notion** is the apex of the DB-locked
+end: typed database properties with relations/rollups/formulas, lossy to Markdown —
+see UC-58 (`research/260614-notion-deep-dive/findings.md` §2).  
 **Priority:** Later
 
 ### UC-35 — Attach a shard with coarse write granularity
@@ -265,7 +271,10 @@ internal RCS table (`xwikircs`) is a concrete instance
 (TWiki RCS `.txt,v`) it can instead be **imported** — see UC-41. Demand evidence:
 **Obsidian Git is a top-7 plugin (2.7M)** — users manually bolt portable git history
 onto a vault that has none natively (`research/260614-obsidian-deep-dive/findings.md`
-§5, §7), exactly the gap the coordination journal fills as core.  
+§5, §7), exactly the gap the coordination journal fills as core. **Notion** is the
+closed-SaaS instance: internal page history bounded by plan, **not portable** and not
+exported as git (`research/260614-notion-deep-dive/findings.md` §4) — a supplementation
+case like Confluence/MediaWiki, not an import case.  
 **Priority:** Later
 
 ### UC-37 — Attach a static engine export as a read-only backup shard
@@ -317,7 +326,9 @@ or can a page be purely typed data (`research/260613-xwiki-deep-dive/findings.md
 §8 Q2)? Affects union views, diff, and search. Deferred to `SHARD-WP-0002`.
 Foswiki shows a middle point: MetaDataPlugin stores **multiple** structured records
 per topic, still as `%META%` in text (`research/260613-foswiki-deep-dive/findings.md`
-§4) — the page model must allow N typed records, not one form.  
+§4) — the page model must allow N typed records, not one form. **Notion** pushes
+further: a *database* is a collection with a schema whose rows are pages joined by typed
+relations — see UC-58 (`research/260614-notion-deep-dive/findings.md` §2).  
 **Priority:** Later
 
 ### UC-40 — Attach a file-backed engine's on-disk store directly
@@ -482,7 +493,11 @@ flattening the structure.
 = page, nested blocks = spans, attributes = sidecar metadata (honors UC-34 no-lossy-
 flatten). DB-backed/API-attached path (like XWiki UC-38), **not** the file-store path
 (UC-40). Write-through requires hosting the adapter inside the engine (Roam Depot),
-else degrade to read/projection/overlay-target (findings §11 Q2).  
+else degrade to read/projection/overlay-target (findings §11 Q2). **Notion** is the
+external-API variant of the same block-DB family: a server Postgres store with a real
+**external** REST API, so write-through needs **no in-engine hosting** — but is bounded
+by rate limits and eventual consistency (UC-57,
+`research/260614-notion-deep-dive/findings.md` §4).  
 **Priority:** Later
 
 ### UC-51 — Adopt a shard's native span IDs as portable span addresses
@@ -501,7 +516,8 @@ a shard-scoped address to avoid cross-shard collision and survive projection (fi
 §11 Q1). Obsidian shows the **text-embedded** variant: `^block-id` and heading anchors
 live in the Markdown text — git-diffable and portable (survives a file copy) but opt-in
 (`research/260614-obsidian-deep-dive/findings.md` §2), vs Roam's mandatory DB-minted
-UID.  
+UID. Notion is a second store-minted case: per-block **UUID v4**, exposed via the REST
+API (`research/260614-notion-deep-dive/findings.md` §1).  
 **Priority:** Later
 
 ### UC-52 — Delegate derived views to a shard's native query engine
@@ -517,7 +533,9 @@ projection). Operationalizes the ZigZag "dimensions + rasters" insight
 (`research/260614-zigzag-deep-dive/findings.md` §5) and relates to UC-05/UC-34. Obsidian
 nuance: query can be an *ecosystem plugin* (Dataview), **not core** — so "native query"
 is adapter/plugin-provided and must not be assumed
-(`research/260614-obsidian-deep-dive/findings.md` §7).  
+(`research/260614-obsidian-deep-dive/findings.md` §7). **Notion** ships a native
+database **query API** (filters/sorts) — a strong delegation target
+(`research/260614-notion-deep-dive/findings.md` §2, §4).  
 **Priority:** Later
 
 ### UC-53 — Attach a local-first Markdown vault with a live concurrent native editor
@@ -547,7 +565,9 @@ Roam `{{query}}` — query-defined dynamic pages
 (`research/260614-obsidian-deep-dive/findings.md` §7). Distinct from UC-44 (reference/
 span manifest) and UC-52 (delegating *computation* of an existing view): here the *page
 itself* is a query. Open: core page type vs. adapter vs. reference-UI/plugin (findings
-§11 Q2). May delegate execution to a shard's native query engine (UC-52).  
+§11 Q2). May delegate execution to a shard's native query engine (UC-52). **Notion**
+linked/filtered databases are the commercial instance — one row-set surfaced through many
+filtered views (`research/260614-notion-deep-dive/findings.md` §2).  
 **Priority:** Later
 
 ### UC-55 — Carry non-Markdown content types as typed or opaque assets
@@ -575,7 +595,61 @@ read-only target — a static site or hosted page set — preserving provenance.
 publish (`research/260614-obsidian-deep-dive/findings.md` §7, §10). Formalizes the
 `publish` capability from INTENT's adapter-capability list; **complements UC-37**
 (inbound static-export *attach*) as its outbound mirror. Open: core vs. publish-adapter
-family; interaction with overlays and projection freshness (findings §11 Q4).  
+family; interaction with overlays and projection freshness (findings §11 Q4). **Notion**
+adds the closed-SaaS instance: **publish-to-web** renders pages as read-only public
+pages (`research/260614-notion-deep-dive/findings.md` §4).  
+**Priority:** Later
+
+### UC-57 — Attach a closed hosted shard via its external API only
+
+**Actor:** Maintainer  
+**Goal:** Attach a closed, hosted SaaS (Notion-style) that has no file store and no
+in-app plugin runtime, reachable only through its external REST API — honoring its rate
+limits, eventual consistency, payload/pagination caps, and a scoped, revocable access
+grant.  
+**Source:** notion, intent  
+**Notes:** Notion is external-REST-attachable with **no in-engine hosting** (contrast
+Roam UC-50) but inside a tight operational envelope: ~3 req/s, eventual consistency,
+recursive first-level-children fetch, and integrations that see **only explicitly
+connected pages** (`research/260614-notion-deep-dive/findings.md` §4, §6). The capability
+profile must encode this **operational envelope** and **scoped/revocable grant**;
+projection is cache/poll/webhook, not a live read model. Best as projection/mirror/
+overlay/backup; write-through possible but bounded. Links the authz-in-core decision and
+"no silent remote mutation". Third attachment mode alongside file-store (UC-40) and
+in-engine host (UC-38/50).  
+**Priority:** Later
+
+### UC-58 — Attach a typed database with schema, relations, and views
+
+**Actor:** Maintainer  
+**Goal:** Attach a structured database (Notion-style) as a shard — preserving its
+schema (typed properties), its inter-record **relations** and **rollups/formulas**, and
+its multiple **views** — without flattening the schema or the relations into prose.  
+**Source:** notion, intent  
+**Notes:** The apex of UC-34/UC-39: not annotations on prose, nor one form per page, but
+a **collection with a schema** whose rows are pages joined by **typed, bidirectional
+relations**, shown through many views (table/board/calendar/gallery)
+(`research/260614-notion-deep-dive/findings.md` §2). Presses the page model: collection +
+schema + relations, not just a page (findings §9). Relations map to the union link graph
+and/or a relation index (cf. ZigZag many-to-many, UC-47/48); views relate to UC-54.
+Deferred to `SHARD-WP-0002`.  
+**Priority:** Later
+
+### UC-59 — Translate a proprietary content model with an explicit fidelity report
+
+**Actor:** Orchestrator / adapter  
+**Goal:** Project and edit a shard whose content model does not round-trip to Markdown
+(Notion blocks/rich-text, databases, relations) by translating **lossily but
+transparently** — surfacing what degraded or did not map, rather than silently dropping
+it.  
+**Source:** notion, intent  
+**Notes:** Notion is the heaviest translation case — proprietary block + rich-text model,
+and its own Markdown/CSV export is lossy (`research/260614-notion-deep-dive/findings.md`
+§3). **Distinct from UC-42** (Foswiki TML↔HTML *lossless* round-trip): here translation
+is fundamentally lossy, so **fidelity becomes data** — a per-shard/per-page report of
+what projects cleanly vs. degrades, with non-mappable elements preserved as
+provenance/sidecar. Embodies union-without-erasure by making *loss of fidelity* visible.
+Open: report format and where it surfaces (findings §10 Q3).  
 **Priority:** Later
 
 ---
@@ -822,6 +896,9 @@ CamelCase and `[[free links]]`. Markdown-first link semantics TBD.
 | UC-54 | | | | ¶ | ✓ |
 | UC-55 | | | | ¶ | ✓ |
 | UC-56 | | | | ¶ | ✓ |
+| UC-57 | | | | ◊ | ✓ |
+| UC-58 | | | | ◊ | ✓ |
+| UC-59 | | | | ◊ | ✓ |
 | UC-08 | ✓ | | |
 | UC-09 | ✓ | | |
 | UC-10 | ✓ | | |
@@ -1041,6 +1118,39 @@ target (`research/260614-obsidian-deep-dive/findings.md` §8.2). Architecture lo
 non-Markdown content types in the page model, outbound publish, external-writer
 tolerance.
 
+### notion mapping
+
+(◊ UC-57–UC-59 are placed in the **wikiengines** matrix column as the nearest existing
+source — Notion is a shipped tool — but their true lineage is the **Notion deep dive**,
+`research/260614-notion-deep-dive/findings.md`.)
+
+| Notion mechanism (findings §) | Catalog UC |
+|-------------------------------|------------|
+| Closed hosted SaaS, external-REST-only, rate-limited/eventually-consistent, scoped grant (§4, §6) | UC-57 (new) |
+| Database = schema + typed properties + relations + rollups + views (§2) | UC-58 (new) |
+| Proprietary block/rich-text, lossy to Markdown (§3) | UC-59 (new) |
+| Per-block UUID v4 via REST = store-minted span address (§1) | UC-51 (enriched) |
+| Server Postgres + external REST API = block-DB without in-engine hosting (§4) | UC-50 (enriched) |
+| Database query API; filtered/linked DBs (§2, §4) | UC-52, UC-54 (enriched) |
+| Database-as-pages apex; typed records + relations (§2) | UC-34, UC-39 (enriched) |
+| Webhooks (2026) as push transport (§4) | UC-31 (enriched) |
+| Internal-only page history, not portable (§4) | UC-36 (enriched) |
+| Publish-to-web outbound (§4) | UC-56 (enriched) |
+| Scoped, revocable per-integration grant; no silent mutation (§6) | UC-57 + [[shard-wiki-auth-in-core-decision]] |
+
+Note: Notion is the **closed/hosted/schema-rich** extreme and the dive that stress-tests
+*graceful degradation*, *no silent remote mutation*, and *Markdown-first that must
+degrade*. It adds the **third attachment mode** — external-API-only (full write-through
+without in-engine hosting, but bounded by rate limits and eventual consistency) —
+alongside file-store (UC-40) and in-engine host (UC-38/50). It also *enforces* no silent
+mutation via scoped, revocable per-integration page grants
+(`research/260614-notion-deep-dive/findings.md` §6). **Boundary recorded:** one
+external-API candidate shard — best as projection/mirror/overlay/backup — not a
+substrate and not the federation layer. Architecture logged for `SHARD-WP-0002` (T14):
+an operational-envelope capability section (rate limit, consistency class, payload caps,
+push-vs-poll), access-grant semantics, a translation-fidelity capability, and the
+three-way attachment-mode taxonomy.
+
 ---
 
 ## Open questions
@@ -1065,4 +1175,9 @@ tolerance.
 10. How does shard-wiki represent **non-Markdown content** (UC-55) — typed asset with a
     Markdown stub, opaque blob with provenance, or a pluggable content-type registry?
 11. Is a **query-defined page** (UC-54) a core page type, an adapter feature, or a
-    reference-UI/plugin concern? (Shared with catalog Q7.)
+    reference-UI/plugin concern? (Shared with catalog Q7.)
+12. Is **external-API-only write-through** under a tight rate limit (Notion) viable at
+    wiki scale, or do we default such shards to read/projection/overlay/backup? (Notion
+    dive §10 Q1; ties UC-57.)
+13. How are **inter-database relations** (UC-58) represented in the union — typed links
+    in the link graph, a separate relation index (cf. ZigZag many-to-many), or both?