From f6f3c66d5d01def8907c110a56f21f7560845e67 Mon Sep 17 00:00:00 2001 From: mvschwarz Date: Wed, 5 Aug 2026 06:29:56 -0700 Subject: [PATCH] The front door names what the repo now ships MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `0a104fe` bundled an app and a provider into this repository and the README's "Where everything is" table still listed neither. That table is the front door — someone reading it got an incomplete map of two top-level directories that ship. Also states the thing the change could otherwise be read as: the SDK is still a shell and a contract, not a framework you import. A bundled app registers a row and calls verbs like any other, with no privileged access. VERIFIED rather than asserted — nothing under `app/` references `apps/` or `providers/`, and SDK_OWNED is unchanged, so the bundled app's verbs are as substitutable as anyone's. CONFORMANCE, checked rather than assumed: I expected the drive and focus rows saying "no shipped surface in this repository does this" to have gone stale. Measured — ARTIFACTS uses the three annotation messages and does NOT use drive or focus, so both rows are still accurate and are left alone. Understating the product costs as much as overstating it, and so does correcting a row that was right. What DID change is that annotations now has the in-repo consumer its siblings still lack, and that row is added — attributed to the QA seat that requested the seams and verified the migration, since evidence produced by the author of a feature is a different claim from evidence produced by someone else. No counts are restated here; they belong to that seat's proof and would rot in this file. 285 tests. --- README.md | 8 ++++++++ contract/annotations.md | 1 + 2 files changed, 9 insertions(+) diff --git a/README.md b/README.md index e549aa0..d57997d 100644 --- a/README.md +++ b/README.md @@ -26,6 +26,14 @@ Open http://127.0.0.1:8890/ — the shell. It starts with one surface on the rai | `app/surfaces.json` | The surface manifest the shell renders. | | `app/surfaces/` | Surface pages live here, served at `/surfaces/…`. | | `fixtures/` | The data behind the runtime's API verbs (rig floor state, files root). | +| `apps/` | Apps bundled with the SDK. An **app** is a surface plus whatever backend it needs — see `contract/app-manifest.md`. Most apps live in their own repositories; the ones here ship with the SDK because they exercise a primitive it defines. | +| `providers/` | The backends those bundled apps call. A provider declares how to run itself and which verbs it answers; nothing in `app/` depends on one. | + +**The SDK is still a shell and a contract, not a framework you import.** A bundled +app is an app like any other — it registers a row and calls verbs, with no +privileged access to the runtime. It is here so that a primitive the contract +defines has a real consumer in the same repository, which is the thing the +conformance tables kept having to say "no" about. ## Starting a new surface diff --git a/contract/annotations.md b/contract/annotations.md index aa93ccd..48b364f 100644 --- a/contract/annotations.md +++ b/contract/annotations.md @@ -256,6 +256,7 @@ default path: | marks surviving a runtime restart | **yes when `--annotations ` is configured**; in memory otherwise, and the layer says "session only" | | human and agent marks rendered distinguishably | **yes** | | an agent handle to add and remove marks | **yes** — `window.studioAnnotations.annotate()` / `.remove()` / `.list()` | +| **a SHIPPED app in this repository that actually consumes these seams** | **yes** — the bundled ARTIFACTS app uses the context, target and refresh messages and holds no annotation implementation of its own. Its migration was browser-verified by the QA seat that requested the seams, not by the author of them; the per-page isolation and element anchoring were measured against a live studio after a full restart. **This is the row the sibling primitives still answer "no" to** — `focus.md` and `drive.md` have no in-repo consumer, and both say so | | **a mark anchored across a CROSS-ORIGIN surface** | **no.** A cross-origin iframe cannot be read for element identity, so marks there are spatial only and say so. Same-origin surfaces get element anchoring | | **agreement about a mark between two people watching at once** | **no.** Last write for a scope wins. Concurrent annotation needs the write-path concurrency `change-signal.md` deliberately excludes, and inventing it before two real watchers exist would be the wrong shape |