# Familiar timeline programs

Three executable reference services implement posting, following authors and
reading a chronological home feed. They move work between publication, delivery
and reading. These are public development demos for studying implementation
choices, not held-out evaluation cases or reconstructions of Twitter/X.

| Program | Read home | Publish and follow | Tradeoff |
|---|---|---|---|
| Birch | Gather own and followed authors' streams, hydrate canonical posts, filter, sort and page | Store the post and author index; maintain follow indexes | Reads repeat the gathering; no per-follower inbox materialization |
| Cedar | Hydrate IDs from the viewer's inbox, then filter, sort and page | Update the author's own inbox; queue followers' references and follow backfill | More stored references and delivery work; followers can see lag |
| Maple | Merge cached IDs with streams from followed broadcaster accounts | Deliver ordinary authors; retain broadcaster posts in their author stream | Less broadcaster fanout work, more work when their followers read |

## Authority and account policy

A trusted `timeline-worker` provisions each account through `/accounts/create`,
including its immutable Ordinary/Broadcaster tier. Ordinary users cannot provision
accounts or invoke `/deliver`. Every variant refuses publication from an
unprovisioned account. Maple reads the stored tier, including when reading a
home feed; no account name determines policy in the program. The test setup
chooses `news` as one broadcaster. There is no tier migration or automatic
follower-count threshold.

Following rows and cached inbox rows carry a nominal owner and use
`GuardedOrRoles`: ordinary routes must prove the owner is the authenticated
Principal; worker routes may operate across owners. Muted rows are OwnerScoped.
Worker reads/writes have separate definitions so ordinary routes cannot inherit
worker authority through a shared binding. Posts, author streams and the inverse
follower index remain public as explicitly declared. These are not private-account
examples. The [access contract](generated/access-contract.json.gz) includes the
three successful proofs and a compiling counterexample that forges a Principal;
the checker rejects that counterexample rather than accepting its owner-shaped
value as authenticated identity.

## Common behavior

- Publication keys are scoped by author and request key with the existing
  length-framed encoding. An identical retry replays the original acknowledgement;
  different text under that key is a conflict. Deletion keeps the receipt, so a
  retry cannot resurrect a post. A replayed acknowledgement describes the original
  publication, including its original `deleted: false`.
- A new follow or refollow includes retained history. Cached variants queue
  backfill; repeating an existing follow returns false without another backfill.
  Self-follow and self-mute are invalid.
- Home includes own and currently followed authors' posts, excluding muted authors
  and canonical tombstones. Visibility is checked before the limit, even with
  stale inbox references. Delivery ignores mute, so unmute restores eligible
  retained history without another backfill.
- Order is descending `(created_at, post_id)`, with String ordering on IDs. A cursor
  is that value pair and means strictly older; deleting its anchor does not break
  paging. Requests observe a live view, without a cross-request snapshot.
- Before delivery drains, cached feeds may omit eligible posts but must not return
  ineligible ones. After a finite successful drain they agree with the independent
  oracle. The author's own publication is visible immediately.
- A delivery transaction consumes at most the requested number of queued references,
  including skipped stale work. Inbox insertion deduplicates. Another invocation
  can consume the next batch; there is no distributed lease or scheduler.
- Every queued reference the worker consumes, stored or skipped, adds its outcome to
  `delivery_outcomes`, keyed by viewer and post. The same pair can be queued again
  (follow, unfollow, follow), so the row keeps every outcome, newest first: a later
  delivery never hides an earlier one. A row grows by one entry per delivery of its
  pair, without limit. The inbox, not this table, says what a viewer sees. Only the
  worker role writes the table; like `followers`, it is readable by any route.
  `check-outcomes.mjs` replays that history on the emitted Cedar and Maple services
  and reads the row back.

Validation faults use the existing `Invalid` reply (HTTP 400). Missing accounts
or posts use `NotFound` (404). Business conflicts use `Refused` (422). An unknown
commit outcome also uses 422, with the distinct code `unconfirmed` and instructions
to inspect state before another command. The current Reply contract has no
separate unknown-commit status: 503/`TryAgain` invites a retry. No new reply constructor or wire status is
invented for these demos. Follow/delivery may have committed without their acknowledgement;
their next response need not replay the original result. The actual store-adapter
acknowledgement-loss experiment pins this distinction.

## Organization and existing tools

`model.bosatsu` defines visibility and paging; `store.bosatsu` owns the common
nominal tables and transaction plans; `inbox.bosatsu` owns cached owner-private
rows; `http.bosatsu` owns shared commands, route values and the outcome boundary;
`delivery.bosatsu` owns backfill, privileged provisioning and delivery. The three
small roots connect these capabilities. Birch imports neither inbox nor delivery.

The examples reuse `Yichus/Transaction`, `Yichus/Access::length_framed` and the
vendored `Zafu/Control/IterState` kit. Shared route lists work directly. A real
compiler probe also found that unused alternative Route constants are discovered
as routes, so root-specific account declarations must stay in the appropriate
package. Direct nominal owner-read skeletons remain where an attempted generic
helper lost the checker's row/guard provenance. These limits and the accepted
organization findings are recorded in the [fresh nonauthor audit](../../../docs/audits/2026-11-08-retained-timelines.md); the delivery outcomes and later source changes are in the [11-10 audit](../../../docs/audits/2026-11-10-timeline-delivery-outcomes.md).

## Reproduce

From the repository root:

```sh
nix-shell --run 'sbt -J-Xmx3G --no-server mcpjs/fastLinkJS'
pnpm install --frozen-lockfile
node demos/compare/timelines/check-access.mjs
node demos/compare/timelines/verify.mjs
node demos/compare/timelines/check-ack-loss.mjs
node demos/compare/timelines/check-outcomes.mjs
node demos/compare/timelines/generate.mjs
```

The scripts use that checkout's compiled engine. Set `YICHUS_APIMCP_BUNDLE` to
reuse another explicitly built bundle; its SHA-256 is recorded. The HTTP harness
uses the real generated services, runtime JWT verification and an independent
sequential oracle with no inbox, author index or queue. A random in-process
signing key supplies test identities/roles; no credentials are committed. A
production deployment needs its own trusted identity and account-provisioning
integration.

The acknowledgement-loss harness commits a real follow through the public store
adapter, then drops its acknowledgement. To observe the same assertion fail
against the checked-in original retry policy:

```sh
YICHUS_TIMELINE_OLD_RETRY=1 node demos/compare/timelines/check-ack-loss.mjs
```

The [red log](generated/ack-loss-red.txt), [green log](generated/ack-loss-green.txt)
and [receipt](generated/ack-loss.json) record the observed 503 failure followed by
422/unconfirmed, with a later follow returning false because the first committed.

The gallery is published at `/demos/compare/timelines/index.html` and linked from
the demos index. Its imports use the published site's layout, so build the site
(`./scripts/build_web_deploy.sh`), serve it with
`node scripts/serve-static.mjs 8094 web_deploy`, and open that path.
`tests/e2e/timelines-gallery.spec.ts` exercises program/view switching, URL
state, keyboard route navigation and the phone layout against the built site. The gallery consumes
actual compiled system/request records through the retained renderers. This PR
does not expose the archived experimental diagram MCP catalog.

The full CI tier runs the access, HTTP, acknowledgement-loss and delivery-outcome contracts. The
three service variants are also registered with many-instance topology in
`verify/programs.json`, with canonical verdict records under `verify/records/`.

## Evidence and limits

The HTTP experiment runs the directed histories and seeded mixed commands in
`verify.mjs` against the independent oracle described above. Its business-command
traces contain 210 Birch, 295 Cedar and 293 Maple requests, plus three actual
compiled equal-time cursor checks per variant. Trusted account setup and
rejection probes are additional requests, recorded separately from those counts.
All checked outcomes agreed. Source hashes, emitted hashes, method and trace
hashes are in the [execution receipt](generated/execution.json); full traces are
in each variant's `execution.json.gz`. These are bounded behavior observations,
not universal equivalence, throughput or scalability measurements.

Generated static receipts include overview, scoped agenda, IO audit, stack,
conventions, organization page and abstraction map. The source audit records
accepted findings and tool friction. Bosatsu is outside Scala line instrumentation:
this PR documents a non-instrumented demo-source exception and makes no claimed
95% source-line measurement. The example harnesses are measured by
`scripts/ci/timeline-demo-coverage.mjs`; the gallery's logic lives in
`web/timeline-gallery.js`, measured with the site's browser coverage
(`tests/site/timeline-gallery.test.mjs`, `tests/e2e/timelines-gallery.spec.ts`).

- Histories, adjacency lists and inboxes are unbounded lists. Paging hydrates and
  sorts gathered rows instead of seeking an indexed range.
- One global queue row is a contention and memory/copying bottleneck. A bounded
  batch does not bound the cost of loading that row, and publication materializes
  its task list. Partitioning the queue or using per-viewer work would change the
  transaction boundary and interleavings, not merely the diagram's labels.
- Explicit worker invocation establishes no autonomous scheduler, parallel worker
  deployment, recovery lease, retention or tier migration.
- Ranking, search, media and private accounts are out of scope.
- The current system map overemphasizes common transaction machinery; request
  views still require too much navigation through low-level decisions. Keeping
  useful executable examples is not declaring these pictures a successful
  overview or evidence of human ease.

## Prior art

Selective push/pull materialization predates these demos. See Silberstein,
Terrace, Cooper and Ramakrishnan, [Feeding Frenzy: Selectively Materializing Users'
Event Feeds (SIGMOD 2010)](https://jeffterrace.com/docs/feeding-frenzy-sigmod10-web.pdf).
It studies producer/consumer choices based on update and view rates. Maple's
immutable operator-assigned tier is a deliberately smaller teaching policy, not
an implementation of that optimization algorithm. The property to lift into a
future overview is the visible relationship between producer streams,
materialized consumer feeds, repeated work and the read/write boundary.
