diff --git a/SCOPE.md b/SCOPE.md index 4a90955..37598fd 100644 --- a/SCOPE.md +++ b/SCOPE.md @@ -19,9 +19,9 @@ Learnings update both SCOPE and INTENT where necessary. |-------|-------| | Code | Python package scaffold (`src/shard_wiki/`, smoke tests only) | | Intent | `INTENT.md` established; authorization-in-core amendments drafted | -| Research | yawex prior art; c2 origins; federation concepts; wikiengines overview (`research/260608-*/`); XWiki/TWiki/Foswiki deep dives (`research/260613-*/`); Xanadu + ZigZag + Roam + Obsidian + Notion + Joplin + Logseq + local-first workspaces (Anytype/AFFiNE/AppFlowy) + Trilium + Wiki.js + Federated Wiki + Wikibase + git-forge wikis + TiddlyWiki + ikiwiki deep dives & shard-spectrum synthesis (`research/260614-*/`) | +| Research | yawex prior art; c2 origins; federation concepts; wikiengines overview (`research/260608-*/`); XWiki/TWiki/Foswiki deep dives (`research/260613-*/`); Xanadu + ZigZag + Roam + Obsidian + Notion + Joplin + Logseq + local-first workspaces (Anytype/AFFiNE/AppFlowy) + Trilium + Wiki.js + Federated Wiki + Wikibase + git-forge wikis + TiddlyWiki + ikiwiki + Quip deep dives & shard-spectrum synthesis (`research/260614-*/`) | | Demand | NetKingdom integration asks captured, not yet negotiated | -| Spec | Architecture blueprint drafted; UseCaseCatalog 79 UCs from research; PRD/TSD scaffolds | +| Spec | Architecture blueprint drafted; UseCaseCatalog 80 UCs from research; PRD/TSD scaffolds | | Work | `SHARD-WP-0001` active (6 tasks); `SHARD-WP-0002` active (16 tasks: T1–T10 federation + T11–T16 adapter contract); `SHARD-WP-0003` active (9 engine dives); `SHARD-WP-0004` active (8 computational-knowledge dives) | ## In Scope (today) diff --git a/research/260614-quip-deep-dive/README.md b/research/260614-quip-deep-dive/README.md new file mode 100644 index 0000000..0a6eef6 --- /dev/null +++ b/research/260614-quip-deep-dive/README.md @@ -0,0 +1,15 @@ +# 260614 — Salesforce Quip deep dive + +Deep dive on **Salesforce Quip**: a closed SaaS of **live collaborative documents** with +**embedded spreadsheets and live apps**, a REST API (HTML import/export), and +**Salesforce-tied identity/permissions**. A hosted-collab contrast to Notion: the +document+spreadsheet hybrid under enterprise auth. + +- `findings.md` — the doc/spreadsheet model, REST API, enterprise auth, capability profile, + INTENT mapping, UC seed (UC-80), architecture notes for SHARD-WP-0002, open questions, + sources, traceability. + +Catalog yield: UC-80 (attach a SaaS live-doc shard whose pages **mix prose + embedded live +structured objects** — spreadsheets/apps — via REST with lossy HTML import/export, under +enterprise identity). Enriched UC-57/55/58/36/06. Feeds SHARD-WP-0002 T11 (capability / +content opacity), T14 (external-API binding). diff --git a/research/260614-quip-deep-dive/findings.md b/research/260614-quip-deep-dive/findings.md new file mode 100644 index 0000000..3427109 --- /dev/null +++ b/research/260614-quip-deep-dive/findings.md @@ -0,0 +1,148 @@ +# Salesforce Quip — deep dive (findings) + +**Date:** 2026-06-14 · **Source:** SHARD-WP-0003 T6 · **Subject:** Quip (Salesforce), a +collaborative-document SaaS. + +## Why this dive + +Notion (UC-57/58/59) gave us the closed-SaaS, external-REST-only, database-as-pages model. +Quip is the **enterprise document-collab** contrast: a **document+spreadsheet hybrid** where +a page is **prose interleaved with embedded live structured objects** (spreadsheets, +calendars, kanban "live apps"), reachable only through a REST API, gated by **Salesforce +identity**. The question: how does shard-wiki attach a shard whose "page" is a *mixed +prose+live-object document* behind enterprise auth? + +## 1. The document + live-object model + +- A Quip **document** is a real-time collaborative doc (concurrent editing). Its body is + rich content — headings, lists, prose — **interleaved with embedded objects**: + - **Spreadsheets** are *first-class, inline* — a doc can contain live spreadsheet sections + with formulas, not just static tables. + - **Live apps** (calendars, kanban boards, project trackers, polls) embed interactive + structured widgets inside the document. +- **Folders** organize documents; **threads** (docs and chat are unified — every doc is also + a conversation thread) carry **messages/comments** inline. +- So a Quip "page" is a **hybrid**: prose + embedded structured/live content in one + document, with conversation attached. Not Markdown; a proprietary rich model. + +## 2. The REST API (the only door) + +Quip exposes a **REST API**: threads/documents (get, create, **edit-document** with an HTML +fragment + a location/section anchor), folders, messages, users, and spreadsheet cell +access. Content crosses the API as **HTML** (import and export) — there is **no native +Markdown** and no file/git access. Implications: + +- **Import/export is HTML → lossy** to Markdown (like Notion's export, UC-59): embedded + spreadsheets and live apps **do not round-trip** to Markdown cleanly — they degrade to + tables or links. +- Editing is **section/anchor-scoped HTML splice** (`edit-document` targets a location) — a + mid-granularity write (a section, not the whole doc, not a character). +- **Rate-limited** like any SaaS API; history is internal (revisions exist in-product, with + limited API exposure). + +## 3. Enterprise identity / permissions + +Quip is tied to **Salesforce** (acquired 2016): authentication and access run through the +Salesforce org / Quip site; **folder and document sharing ACLs** govern visibility, with +enterprise SSO. So this is an **enterprise-ACL, authn-delegated** shard (UC-06) — shard-wiki +honors Salesforce-side permissions and never bypasses them. + +## 4. Capability profile + +| Dimension (synthesis spectrum) | Quip | +|--------------------------------|------| +| Attachment mode | **external-API** (REST; HTML import/export) — closed SaaS | +| Addressing granularity | document; **section/anchor** for edits; spreadsheet cell | +| Content identity | Quip thread/document ID (opaque) | +| Identity vs placement | API-id identity; folder placement separate | +| Structure | **hybrid doc**: prose + embedded spreadsheets + live apps + thread | +| History | **internal** revisions (limited API exposure) | +| Merge model | server-side real-time collab (OT-like); no external merge | +| Native query | none exposed (spreadsheet formulas internal) | +| Translation | **HTML** in/out → **lossy** to Markdown (spreadsheets/apps degrade) | +| Write granularity | **section/anchor HTML splice** (mid) | +| Operational envelope | rate-limited SaaS REST | +| Access grant | **Salesforce identity + folder/doc ACL** (enterprise SSO) | +| Content opacity | proprietary rich model; not E2EE but not transparent files | +| Provenance | author/edit metadata in-product; API-limited | + +## 5. INTENT mapping + +### Reinforcements + +- **External-API attachment** (UC-57): Quip is a second concrete instance beside Notion of + the closed-SaaS REST-only shard — generalizes the external-API mode (REST + HTML payload, + vs Notion's REST + block-JSON, vs Wiki.js GraphQL). +- **Union without erasure / no silent flatten**: embedded spreadsheets and live apps must be + **surfaced as what they are** with provenance, and the **HTML→Markdown lossiness made + explicit** (UC-59) — never silently drop a live spreadsheet to a static table. +- **Authz-in-core, authn-delegated** (settled decision): Quip's Salesforce-tied ACL is the + enterprise case — honor delegated identity and the shard's ACL (UC-06). +- **Graceful degradation**: with only a lossy HTML export, Quip is still usable as a + read/projection/overlay-target/backup shard. + +### Divergences (boundaries / notes) + +- **Mixed prose+live-object page** is a content shape beyond "Markdown body + frontmatter": + the page model must allow **embedded typed/live objects within a prose page** (not just a + whole-page-is-a-record like Notion DB, but *inline* structured content) — feeds T12 and the + non-Markdown-content question (UC-55). +- **HTML is the only interchange** — no Markdown, no files, no git. Content opacity is + "proprietary-but-exportable": transparent-ish via lossy HTML, not via files (T11 + content-opacity tier between transparent-files and E2EE-opaque). +- **Write granularity = section-anchor HTML splice** — a mid tier (between whole-file and + block/character) realized over an API, distinct from fedwiki's story-item op-log. + +### What to keep + +1. **External-API mode generalized** to carry an **HTML payload** variant (Quip) beside + block-JSON (Notion) and GraphQL (Wiki.js) — capability/payload-format is part of the + adapter profile (UC-57/UC-80). +2. **Inline embedded live/structured objects** as a page-model element (prose + embedded + spreadsheet/app), with **explicit lossy projection** to Markdown (UC-55/UC-58/UC-59). +3. **Enterprise-ACL + delegated identity** honored, not bypassed (UC-06). + +## 6. UC seed + +| # | Seed | Disposition | +|---|------|-------------| +| UC-80 | Attach a **SaaS live-doc shard** whose pages **mix prose + embedded live structured objects** (spreadsheets / live apps) via **REST with lossy HTML import/export**, under **enterprise (Salesforce) identity** | **new** | +| — | external-API mode w/ HTML payload variant | enrich **UC-57** | +| — | inline embedded spreadsheet/live-app = non-Markdown content | enrich **UC-55** | +| — | embedded structured objects within a prose page | enrich **UC-58** | +| — | internal (API-limited) revision history | enrich **UC-36** | +| — | Salesforce-tied enterprise ACL + SSO | enrich **UC-06** | + +## 7. Architecture notes for SHARD-WP-0002 + +- **T11 (capability / content opacity):** add a **payload-format** facet to external-API + shards (HTML / block-JSON / GraphQL) and a **content-opacity tier** "proprietary but + lossy-exportable" between transparent-files and E2EE-opaque. Write granularity = + section-anchor splice. +- **T12 (page model):** support **inline embedded structured/live objects** within a prose + page (not only whole-page-as-record) — with explicit lossy render to Markdown. +- **T14 (binding):** external-API binding with **HTML import/export**; honor Salesforce + identity/ACL; default to read/projection/overlay given rate limits + lossy export. + +## 8. Open questions + +1. Does shard-wiki represent an **embedded live spreadsheet** as a typed sub-object with + provenance (preferred) or flatten it to a static Markdown table (lossy) — and can overlays + target a spreadsheet cell via the API, or only the prose? +2. Given **HTML-only, lossy** interchange and rate limits, is Quip ever a **write-through** + shard, or read/projection/overlay/backup by default? (cf. Notion Q1, UC-57.) +3. How is **Salesforce identity** mapped to shard-wiki's delegated-authn model — pass-through + token, service account, or per-user OAuth? + +## 9. Sources + +- Quip Automation API (REST) docs — quip.com / Salesforce developer docs (threads/documents, + `edit-document`, folders, messages, spreadsheets) +- Salesforce Quip product docs (live apps, spreadsheets, sharing/permissions) +- prior: `research/260614-notion-deep-dive/` (closed-SaaS external-API contrast, UC-57/59) + +## 10. Traceability + +New UC **UC-80** carries the marker **◧** in the wikiengines column of +`spec/UseCaseCatalog.md`. Enriched: UC-57, UC-55, UC-58, UC-36, UC-06. Architecture +cross-refs: SHARD-WP-0002 T11 (payload-format + content-opacity), T12 (inline objects), T14. diff --git a/research/README.md b/research/README.md index a54721f..07f95f5 100644 --- a/research/README.md +++ b/research/README.md @@ -32,4 +32,5 @@ when multiple files or sources are involved. Findings here inform `spec/` and | 2026-06-14 | `260614-wikibase-deep-dive/` | Wikibase/Wikidata — typed entity-statement knowledge graph (claim+qualifiers+refs+rank), SPARQL/RDF + federated SERVICE, opaque stable IDs, statement-level provenance; structure & query far-end; UC-73/74/75 | | 2026-06-14 | `260614-forge-wikis-deep-dive/` | Gitea · GitLab · GitHub wikis — a wiki is a separate `.wiki.git` of Markdown; git-clone universal, wiki API capability-varying (GitHub git-only); git IS the store (resolves UC-68 race); the home case; UC-76/77 | | 2026-06-14 | `260614-tiddlywiki-deep-dive/` | TiddlyWiki — entire wiki (content + app) in one self-contained HTML file = whole-file write-granularity extreme; Node `.tid` file-per-tiddler substrate (git-diffable); tiddler/field records, filter-expression query; UC-78 | -| 2026-06-14 | `260614-ikiwiki-deep-dive/` | ikiwiki — wiki compiler: git-canonical Markdown source → static HTML (derived publish/projection); git-distributed clone federation + XML-RPC pinger (third federation flavor); UC-79 | \ No newline at end of file +| 2026-06-14 | `260614-ikiwiki-deep-dive/` | ikiwiki — wiki compiler: git-canonical Markdown source → static HTML (derived publish/projection); git-distributed clone federation + XML-RPC pinger (third federation flavor); UC-79 | +| 2026-06-14 | `260614-quip-deep-dive/` | Salesforce Quip — closed-SaaS live docs + embedded spreadsheets/live apps; REST + lossy HTML import/export; Salesforce enterprise ACL; external-API payload-format facet + inline-object page model; UC-80 | \ No newline at end of file diff --git a/spec/UseCaseCatalog.md b/spec/UseCaseCatalog.md index 5825e0a..6cbe04c 100644 --- a/spec/UseCaseCatalog.md +++ b/spec/UseCaseCatalog.md @@ -16,7 +16,8 @@ Promoted from `research/260608-c2-wiki-origins/`, `research/260614-wikibase-deep-dive/`, and `research/260614-forge-wikis-deep-dive/`, and `research/260614-tiddlywiki-deep-dive/`, and -`research/260614-ikiwiki-deep-dive/`. +`research/260614-ikiwiki-deep-dive/`, and +`research/260614-quip-deep-dive/`. See InfoTechPrimers on coulomb.social for use-case catalog conventions. ## Conventions @@ -712,7 +713,12 @@ in-engine host (UC-38/50). Self-hostable variants: **AFFiNE Cloud** / **AppFlowy user's trust boundary (`research/260614-localfirst-workspaces-deep-dive/findings.md` §4, §9) — see also UC-65 (P2P, no single endpoint). **Wiki.js** uses **GraphQL** (typed, introspectable, selective-field) rather than REST — schema discovery + reduced over-fetch, -see UC-69 (`research/260614-wikijs-deep-dive/findings.md` §3). +see UC-69 (`research/260614-wikijs-deep-dive/findings.md` §3). **Quip** adds a third payload +form: REST with an **HTML** import/export payload (vs Notion block-JSON, Wiki.js GraphQL) — +**lossy** to Markdown, embedded spreadsheets/live apps degrade, under **Salesforce** +enterprise identity (UC-80, `research/260614-quip-deep-dive/findings.md` §2, §3). So the +external-API mode carries a **payload-format facet** (block-JSON / GraphQL / HTML) in the +adapter profile. **Priority:** Later ### UC-58 — Attach a typed database with schema, relations, and views @@ -1097,6 +1103,24 @@ the git+Markdown adapter with forge wikis (UC-76). Feeds SHARD-WP-0002 T4 (feder (publish/projection). **Priority:** Later +### UC-80 — Attach a SaaS live-doc shard with embedded structured objects + +**Actor:** Orchestrator / adapter +**Goal:** Attach a **SaaS live-document shard** (Salesforce Quip) whose pages **mix prose +with embedded live structured objects** (spreadsheets, live apps) via a **REST API with +lossy HTML import/export**, under **enterprise (Salesforce) identity**. +**Source:** wikiengines, intent +**Notes:** Quip is a closed-SaaS document+spreadsheet hybrid — a page is prose interleaved +with **inline spreadsheets/live apps**, reachable only by REST, content crossing as **HTML** +(lossy to Markdown; embedded objects degrade) (`research/260614-quip-deep-dive/findings.md` +§1, §2). Generalizes the external-API mode (UC-57) with an **HTML payload** variant beside +Notion block-JSON and Wiki.js GraphQL, and adds **inline embedded structured objects** to +the page model (UC-55/UC-58) — surface them with provenance, never silent-flatten (UC-59). +Honor **Salesforce ACL** (UC-06); default to read/projection/overlay given rate limits + +lossy export. Feeds SHARD-WP-0002 T11 (payload-format + content-opacity), T12 (inline +objects), T14. +**Priority:** Later + --- ## B. Knowledge work and collaboration @@ -1373,6 +1397,7 @@ CamelCase and `[[free links]]`. Markdown-first link semantics TBD. | UC-77 | | | | ⎇ | ✓ | | UC-78 | | | | ⊡ | ✓ | | UC-79 | | | ✓ | ⊟ | ✓ | +| UC-80 | | | | ◧ | ✓ | | UC-08 | ✓ | | | | UC-09 | ✓ | | | | UC-10 | ✓ | | | @@ -1931,6 +1956,35 @@ recorded:** never attach the build output as canonical; the pinger is a subscrib (T4/T6/T14): git-replication+ping federation, compile-to-static publish, source-repo attach sharing the git+Markdown adapter. +### quip mapping + +(◧ UC-80 lineage = the **Quip deep dive**, `research/260614-quip-deep-dive/findings.md`.) + +| Quip mechanism (findings §) | Catalog UC | +|-----------------------------|------------| +| Closed-SaaS doc + embedded spreadsheets/live apps; REST + HTML import/export (§1, §2) | UC-80 (new) | +| External-API mode with **HTML payload** variant (vs Notion block-JSON, Wiki.js GraphQL) (§2) | UC-57 (enriched) | +| Inline spreadsheets/live apps = non-Markdown content (§1) | UC-55 (enriched) | +| Embedded structured objects within a prose page (§1) | UC-58 (enriched) | +| Internal revisions, API-limited (§2) | UC-36 (enriched) | +| Salesforce-tied enterprise ACL + SSO (§3) | UC-06 (enriched) | +| HTML→Markdown lossy; embedded objects degrade (§2) | links UC-59 | +| Section/anchor HTML splice = mid write granularity (§2) | links UC-35 | + +Note: Quip is the **enterprise document-collab** contrast to Notion — a **document + +spreadsheet hybrid** where a page is **prose interleaved with embedded live structured +objects** (spreadsheets, kanban/calendar "live apps"), reachable **only by REST** with +content crossing as **HTML** (lossy to Markdown; embedded objects don't round-trip), gated by +**Salesforce identity/ACL**. It generalizes the external-API mode with an **HTML payload** +variant (beside Notion block-JSON and Wiki.js GraphQL) and pushes the page model toward +**inline embedded structured objects** (not just whole-page-as-record). **Boundary +recorded:** surface embedded spreadsheets/apps **as what they are** with provenance and make +the HTML→Markdown lossiness explicit (never silent-flatten, UC-59); honor Salesforce ACL; +default to read/projection/overlay given rate limits + lossy export. Architecture logged for +`SHARD-WP-0002` (T11/T12/T14): external-API payload-format facet + a "proprietary +lossy-exportable" content-opacity tier, inline-embedded-object page model, enterprise-ACL +binding. + --- ## Open questions @@ -2005,5 +2059,9 @@ sharing the git+Markdown adapter. **publish the union** as a static site (act as the compiler), or only attach existing source repos — and is the **pinger** modeled as shard-wiki's own subscribe/notify primitive or only recognized when bridging two ikiwiki instances? (ikiwiki dive §8.) +28. For a **SaaS live-doc shard** (UC-80), is an **embedded live spreadsheet** a typed + sub-object with provenance (preferred) or a flattened static Markdown table — can + overlays target a spreadsheet cell or only prose — and given HTML-only lossy interchange, + is Quip ever write-through or read/projection/overlay/backup by default? (Quip dive §8.) 23. How does shard-wiki **honor/surface a shard's path-based access rules** (UC-06) in a projection without re-implementing its ACL engine? (Wiki.js dive §9.) \ No newline at end of file diff --git a/workplans/SHARD-WP-0003-engine-dives-batch.md b/workplans/SHARD-WP-0003-engine-dives-batch.md index 983f7f4..951be84 100644 --- a/workplans/SHARD-WP-0003-engine-dives-batch.md +++ b/workplans/SHARD-WP-0003-engine-dives-batch.md @@ -133,7 +133,7 @@ feed `SHARD-WP-0002` T14. ```task id: SHARD-WP-0003-T6 -status: todo +status: done priority: medium state_hub_task_id: "3e55128a-161c-48d0-9ab4-75fd48616dad" ```