Tracking: core work needed by the site-generator project, and the order it wants doing in

[cuibonobo]

Motivation

A static-site generator reading a stack is the first real consumer of the commons
publishing types. page@1 already names it as its intended writer:

Status: Draft. Intended writer: a static-site-generator integration reading a
stack (in progress by the project maintainer — either a standalone generator or an
Eleventy data source).

That project is now concrete. It is three pieces:

• @haverstack/eleventy — an Eleventy plugin that builds a site from a stack
• @haverstack/cli — a general-purpose, type-agnostic record editing tool
• A migration of an existing Cloudflare Pages + D1 + R2 site onto a stack, including
  a one-time import of several years of dated records

Between them they exercise most of the commons publishing cluster, the attachment path,
the query path, permissions, and the change feed — which is why they surface a specific
set of core gaps rather than a diffuse wish list.

This issue exists to say what those gaps are and why they want doing in a particular
order, so the sequencing is a recorded decision rather than something rediscovered
later. None of the linked issues is blocked on this one; it is a map, not a gate.

---

The issues

Issue	What it is	Track
#202	unlisted permission tier — reachable by URI, absent from feeds	Types
#204	Commons post@1 — the broadcast utterance	Types
#203	Settable createdAt/updatedAt for owner-side imports	Core
#16	Discriminated union for relationship targets	Core
#160	blob-adapter-s3	Deployment
#161	record-adapter-do-sqlite	Deployment
#194	subscribe() cannot resume	Later

---

Dependencies

graph TD
  A["#202 unlisted<br/><i>decision</i>"] --> S["sidecar type set"]
  B["#204 post@1"] --> I["one-time import"]
  C["#203 settable createdAt"] --> I
  D["#16 relationship union"] --> E["@haverstack/eleventy"]
  D --> F["@haverstack/cli"]
  S --> E
  I --> E
  G["#194 resume"] -.-> H["incremental builds<br/><i>v2</i>"]
  E -.-> H

Loading

Three tracks that barely touch each other:

Types track — #202, then #204. #202 is a decision, not an implementation: it
determines whether the generator's sidecar type carries a hidden field or defers to a
permission tier. Cheap to settle, and settling it late means rewriting a type that
already has records written against it. #204 is independent of #202 and can proceed in
parallel.

Core track — #203 and #16. Independent of each other and of the types track.

Deployment track — #160 and #161. Entirely independent of everything above. These
decide where the stack runs, which no type or API decision depends on.

---

Ordering, and why

1. #202 — unlisted. First because it is the cheapest and the most downstream-shaping.
The sidecar type set is waiting on the answer, and it is a design decision rather than
work. Deciding it wrong is recoverable; deciding it late is not, because by then there
are records.

2. #203 — settable createdAt. A hard blocker for the import, not a convenience.
Without it every imported record is stamped with the import moment and years of archive
collapse to a single day. It is also load-bearing for #204 specifically: post@1
carries no content date by design, so native createdAt is the only ordering key a post
will ever have.

3. #16 — relationship target union. Before the two new repos exist, not after. Both
read and write relationship associations — the commons cross-type conventions
(author, location, series, about), curated collection membership, and
Filter.relatedTo on the generator's read path. Landing it afterwards means paying the
migration across two fresh codebases simultaneously, neither of which has users to
justify the churn. The window where this is nearly free is open now and closes when the
first of those repos gets written.

4. #204 — post@1. Blocks the import from landing short-form entries on a correct
type. The fallback — filing them as note@1 and migrating later — collides with the
commons' own rule that contracts don't convert in place, and re-minting records would
destroy permalinks that are otherwise preserved exactly. Can start any time; needs to
finish before the import runs.

5. #160 — blob-adapter-s3. Only if attachment bytes stay in R2. Determines whether
media is a data migration or a config change.

6. #161 — record-adapter-do-sqlite. The deployment fork: VPS versus staying on
Cloudflare. Needs deciding before deployment work starts, since almost none of that work
transfers between the two targets. The decision is urgent; the implementation may well
be "not now."

7. #194 — feed resume. Incremental builds. Full rebuilds work at this scale, so this
is a v2 improvement rather than a launch requirement.

---

What can run in parallel

• An unlisted permission tier — reachable by URI, absent from feeds and listings (split from #15) #202, createdAt/updatedAt can't be set, so importing an existing archive collapses it to one timestamp #203, Commons: post@1 — the broadcast utterance, with a concrete intended writer #204 and RFC: discriminated union for RelationshipAssociation targets #16 have no dependencies on each other. Four independent
  workstreams.
• The deployment track (blob-adapter-s3 — blob storage is Node-disk-only, so object storage means writing your own #160, record-adapter-do-sqlite — a Workers story that fits the sync SqlExecutor and the ownership rule #161) shares nothing with the type or core tracks and
  can run at any point.
• Once createdAt/updatedAt can't be set, so importing an existing archive collapses it to one timestamp #203 and Commons: post@1 — the broadcast utterance, with a concrete intended writer #204 are done, the import script can be written and run — and the
  import is the real test of the type mapping, so it wants to happen before the plugin
  and CLI are far along.
• The plugin and the CLI are independent of each other and can proceed in parallel
  once RFC: discriminated union for RelationshipAssociation targets #16 has landed.

What is explicitly not blocking

• Streaming BlobAdapter methods: the byte-array contract forces full buffering of every attachment (deferred until triggers hit) #72 (streaming blob methods) — deferred by design, additive when woken, and the
  wake-up triggers are not met by a site with modestly sized images.
• Optional adapter capabilities (deleteUnreferencedAttachmentRecords, listFiles) have no discovery mechanism for implementors #93 (optional capability discovery) — documentation. Only tangentially relevant, in
  that blob-adapter-s3 — blob storage is Node-disk-only, so object storage means writing your own #160 needs listFiles() for GC against object storage and Optional adapter capabilities (deleteUnreferencedAttachmentRecords, listFiles) have no discovery mechanism for implementors #93 is the checklist
  that would make that obvious to whoever writes it.
• RFC: ATProto compatibility layer — core type and API changes #15 as a whole — the post@1 proposal in Commons: post@1 — the broadcast utterance, with a concrete intended writer #204 argues that the ATProto chain gates
  the bridge machinery, not the content type. If that argument fails, Commons: post@1 — the broadcast utterance, with a concrete intended writer #204 is blocked and
  this ordering changes materially; if it holds, RFC: ATProto compatibility layer — core type and API changes #15 is not on this project's path at
  all.

---

Notes

The site generator's own design documents — the type set it uses and the shape of the
two new packages — live outside this repository for now, since neither package exists
yet. Sidecar types are namespaced under the integration rather than under any one site,
so org.haverstack stays reserved for the commons as specified.

[cuibonobo]

Addition to the types track: #206 — site@1

Filed #206, which adds one item to this plan. Recording it here so the map stays current.

What it is. The generator project turns out to have a second site in it: a personal site
(hobbies, photos, art) and a professional one, both carrying pages and articles, both built
from the one personal stack. The page tree already survives that — page.md anticipates a
site container, and path derivation stops at the first non-page ancestor, so a container
changes no rule. Collections do not survive it: collection.typeId is stack-global, so both
sites' article listings select every article@1 in the stack.

#206 proposes org.haverstack/site@1 plus a site relationship-association convention for
membership, and a page.md convention that scopes a collection root to its ancestor site.

Why it lands in the commons rather than in @haverstack/eleventy. "The site container is
app territory" is right for single-site, where the container is absent and root pages are the
site. At multi-site the container becomes the thing that makes a page tree a site and says
which articles a site publishes — neither derivable by a second generator. Keeping it app-side
reintroduces the generator lock-in page@1 exists to prevent, one level up.

Where it goes in the ordering. Types track, alongside #202, and before the import, for
the same reason #203 is before it: membership stamped as records are written is free, and
backfilled across several years of archive afterwards is a second pass. It is independent of
#202 and #204 and can run in parallel with both.

Updated view of the track:

Issue	What it is	Track	Note
#202	unlisted permission tier	Types	decision, shapes the sidecar set
#206	site@1 + site convention	Types	new — before the import
#204	Commons post@1	Types	before the import
#203	Settable createdAt/updatedAt	Core	hard blocker for the import
#16	Relationship target union	Core	before the two new repos

Effect on #16's urgency: it goes up. This issue lists two consumers of relationship
associations on the read path — the cross-type conventions and curated collection membership.
Site membership is a third, and unlike the others it would be written across every published
record during the one-time import. Landing #16 after the import means migrating the whole
archive; landing it before means the import writes the final shape once. The window this issue
describes as "nearly free, and closing" is narrower than it was.

No effect on the core, deployment, or later tracks. #206 needs no change to Stack, to
RecordFilter, or to any adapter — parentId, relationship associations and
Filter.relatedTo already carry it, so it is entirely commons vocabulary. #160, #161 and #194
are untouched.

One limitation worth recording here, since it is the kind of thing that gets assumed later:
multi-site gives no per-site read isolation. Grants are type-level plus per-record permissions,
with no association-scoped grant, so a credential that builds the professional site can read
the personal records too. Fine for owner-run builds, which is what this project has, but it is
not a boundary and shouldn't be leaned on as one if the professional site ever builds somewhere
less trusted.

---

Generated by Claude Code