docs: plan for Events 2.4.0, handovers after 2.3.1 / agent 1.0.1 / Hub 2.1.1

EVENTS-2.4-PLAN.md: protocol v2 (public key in the v2 heartbeat, Hub 2.2.0),
Linked products and Connect (crosscode.link/1, contracts 1.4.0), the event
feed, showing sibling events, and packages/seo. Six decisions to confirm.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-18 11:54:36 +02:00
co-authored by Claude Opus 5.5
parent 6db2f439b4
commit 0cc72aaaad
4 changed files with 414 additions and 15 deletions
+10 -7
View File
@@ -1,14 +1,16 @@
# Handover — where things stand and how to carry on
Last updated: 2026-11-17, after **2.3.0** (released, tested on a VM, not deployed yet; servers
still run 2.1.1 until they're adopted, see the root [ROLLOUT-1.0.md](../../../docs/ROLLOUT-1.0.md)).
Last updated: 2026-11-18, after **2.3.1** (Next.js 16.4.6 for security advisories, on top of 2.3.0;
released, not deployed yet; servers still run 2.1.1 until they're adopted, see the root
[ROLLOUT-1.0.md](../../../docs/ROLLOUT-1.0.md)).
**This file covers Cross Events only**
(what's been done, where the code lives, known gaps). **The plan for every product and where each
phase stands are in the monorepo's root `docs/`** →
[ROADMAP-v3.md](../../../docs/ROADMAP-v3.md),
[HANDOVER.md](../../../docs/HANDOVER.md) (all products) and
[EVENTS-2.2-PLAN.md](../../../docs/EVENTS-2.2-PLAN.md) (the next Events release:
the move into the monorepo). The Hub protocol is there too ([hub-protocol.md](../../../docs/hub-protocol.md)). How Cross
[EVENTS-2.4-PLAN.md](../../../docs/EVENTS-2.4-PLAN.md) (the next Events release: protocol v2,
Linked products, the event feed and `packages/seo`; the move into the monorepo was
[EVENTS-2.2-PLAN.md](../../../docs/EVENTS-2.2-PLAN.md)). The Hub protocol is there too ([hub-protocol.md](../../../docs/hub-protocol.md)). How Cross
Events got to 2.x is in [ROADMAP-v2.md](./ROADMAP-v2.md); the round before that in
[FEATURES-ROUND-1.md](./FEATURES-ROUND-1.md).
@@ -98,9 +100,10 @@ encrypted settings unreadable or break existing installs.
1. **Roadmap v3**, across every product: see `crosscode-platform/docs/HANDOVER.md` ("Where each
phase stands", "Next up"). **2.2.0** (the move into the monorepo) and **2.3.0** (authenticator
app 2FA and recovery codes, plus what installs from the Hub need) are released (2026-11-17).
Next for Cross Events is **rolling them out** (each install adopted from the Hub), then **2.4.0**
(protocol v2, Linked products, the event feed).
app 2FA and recovery codes, plus what installs from the Hub need) are released (2026-11-17;
**2.3.1** with Next.js 16.4.6 on 2026-11-18). Next for Cross Events is **rolling them out**
(each install adopted from the Hub, on 2.3.1), then **2.4.0** (protocol v2, Linked products,
the event feed), planned in [EVENTS-2.4-PLAN.md](../../../docs/EVENTS-2.4-PLAN.md).
- **Deploying:** installs still on 2.1.1 move with `adopt` (Hub → Servers → Installs → Link
existing → Move onto the monorepo, or `crosscode adopt` by hand), never `deploy`. After that,
updates are planned on the Hub (Updates), or `crosscode deploy <church> events` by hand.
+392
View File
@@ -0,0 +1,392 @@
# Cross Events 2.4.0 — protocol v2, Linked products, the event feed and `packages/seo`
Phase **2** of [ROADMAP-v3.md](./ROADMAP-v3.md) (§4, §5 "Sibling discovery", §9, §11; decisions
5, 20). Written 2026-11-18. **Not started.**
**What 2.4.0 is:** Cross Events becomes a full member of a church stack. It reports to the Hub as
`product: "events"` (protocol v2), shows the church's other products under **Settings → Linked
products** with a **Connect** button, **publishes** its public events as a `crosscode.event-feed/1`
feed, **shows** events from linked products, and builds its SEO data with the new shared
`packages/seo`. Nothing changes for a church that has only Cross Events, apart from a new
settings page that says "No other products yet".
The Website and App don't exist yet, so the "show events from" side is built and tested against
sample feeds (§8). It's ready for the Website (phase 4) without another Events release.
**Done when:**
- `events@2.4.0`, `contracts@1.4.0` and Hub `v2.2.0` are tagged and pushed.
- An Events install updated to 2.4.0 moves itself to protocol v2 with no admin action, and the
Hub shows it as v2 with a public key.
- The feed passes the contract (`parseEventFeed` with nothing rejected) for every event in the
e2e seed, and a sample Website feed shows up in Events with a canonical link to its origin.
- crosscode-site says "Works with the Church Website and App (coming)" on the Cross Events page
(ROADMAP §9, "Updating crosscode-site").
## Contents
1. [Before starting](#before-starting)
2. [Protocol v2](#1-protocol-v2)
3. [Linked products and Connect](#2-linked-products-and-connect)
4. [Publishing: the feed](#3-publishing-the-feed)
5. [Showing events from linked products](#4-showing-events-from-linked-products)
6. [`packages/seo`](#5-packagesseo)
7. [Settings, audit log and help](#6-settings-audit-log-and-help)
8. [What changes in each repo](#7-what-changes-in-each-repo)
9. [Testing](#8-testing)
10. [Releasing and rolling it out](#9-releasing-and-rolling-it-out)
11. [Decisions](#decisions)
12. [Still open](#still-open)
---
## Before starting
- **The rollout (ROLLOUT-1.0.md) is at least past step 1**, so production runs Hub 2.1.x. 2.4.0
needs Hub 2.2.0 (§1) and is released after it, but neither depends on the church servers
being adopted.
- `apps/events` builds and tests clean on `main` (`npm run check`), as the baseline.
- Events uses `@crosscode/contracts` as a workspace dependency for the first time (backend and
frontend). The backend is CommonJS with some TypeScript; the package ships both builds, so
`require('@crosscode/contracts')` works as it is.
## 1. Protocol v2
Today `src/hub/client.js` speaks protocol 1 (`PROTOCOL_VERSION = 1`). v2 is in
`@crosscode/contracts` (`hub.*`) and the Hub has accepted it since 2.0.0
([hub-protocol.md §6](./hub-protocol.md#6-protocol-version-2-hub-20)).
**The problem:** hub-protocol.md says an install moves to v2 by *registering again* with its
licence key and a public key. Events never stored the licence key (it's only sent once, from
`/setup` or "Connect to Hub"), so every church admin would have to find and retype it. The v2
heartbeat also has no way to send a public key.
**The fix (Hub 2.2.0, contracts 1.4.0):** the v2 heartbeat gets an optional `publicKey` (PEM).
The heartbeat is already signed with the install secret, so the Hub knows it's that install. The
Hub saves the key when the install has none, and refuses a *different* key
(`409 PUBLIC_KEY_MISMATCH`) unless Joshua clears it on the install's page (for a restored server
that lost its key). An optional field keeps the protocol at version 2 and the contract at `/1`
(ROADMAP §2, "Versioning").
What Events does:
| Step | Detail |
|------|--------|
| Key pair | On first start of 2.4.0, generate an Ed25519 key pair (`generateEd25519` from `@crosscode/contracts/signing`). Private key encrypted in `AppSetting` `hub_private_key` (same `encrypt` as the install secret), public key in `hub_public_key`. Both added to `HUB_KEYS`, so the generic settings endpoints never show them. Never regenerated unless missing |
| Heartbeat | `protocolVersion: 2`, `product: "events"`, `publicKey` until the Hub has acknowledged it (`hub_public_key_ack`), Events stats as in v1. Body checked with `hub.heartbeatRequestSchema` before sending (a bug shows in tests, not as a 400 in production) |
| Register | `/setup` and "Connect to Hub" register with v2 straight away (`product`, `install.publicKey`) |
| Reply | Reads `linkedProducts` (§2) and the licence's `customerId` / `product`; everything else as v1 |
| Falling back | If the Hub answers `400 UNSUPPORTED_PROTOCOL` (a Hub older than 2.0), send v1 and keep trying v2 once a day. Not expected in production; it keeps a restored old Hub from cutting installs off |
`hub-protocol.md` §6 "Moving an install to v2" is rewritten to describe this (both copies).
## 2. Linked products and Connect
**Settings → Linked products** (site admins only) lists the church's other installs from the
last heartbeat's `linkedProducts` (cached in `AppSetting` `hub_linked_products`, so a Hub outage
changes nothing; ROADMAP §5). For each: product name, address, and its state: **Not connected**
· **Connected** (since when, by whom) · **Connected, last sync failed** (when, why).
With Events only, the page says the church has no other Cross Code products yet, with a link to
crosscode.co.za.
### Connect
The Hub tells each install which siblings exist and their public keys. **Connect** turns that
into a working link: a shared secret for signed calls between the two, and the feed settings.
New contract: **`crosscode.link/1`** in `packages/contracts/src/link.ts`.
```
A (Events) B (e.g. Website)
admin clicks Connect
makes a 32-byte secret S
POST {B.url}/api/links/v1/connect ───────────────► 1. A is in B's own cached linkedProducts
{ (same Hub customer), by installId
schema: "crosscode.link/1", 2. the Ed25519 signature checks out against
type: "link.connect", the publicKey the Hub listed for A
from: { product, installId, url }, 3. `to.installId` is B; issuedAt within
to: { installId }, 5 minutes; nonce not seen before
secret: S, 4. stores S (encrypted), marks A connected
issuedAt, nonce, ◄── 200 { schema, type: "link.connected",
signature: <Ed25519 over the canonical JSON> from: {…B}, publicKey check, signature }
}
checks B's signed reply with B's Hub-listed key
stores S (encrypted), marks B connected
```
- **Trust comes from the Hub's list on both sides.** B accepts A only if A appears in *B's*
`linkedProducts` with that exact key, so only installs of the same church can link, and only
ones the Hub knows. The Hub is still not on the path at the time of the call (rule 2): both
sides use their cached lists.
- **No approval step on B.** Both installs belong to the same church; whoever is admin on either
side can connect. B's Linked products page shows "Connected by Cross Events on 18 Nov" and
either side can **Disconnect** (a signed `link.disconnect`; both drop the secret).
- **Connecting again** replaces the secret (e.g. after a restored backup lost it).
- After Connect, every call between the two (the `event.changed` webhook now, Accounts'
back-channel later) uses `LINK_HEADERS` HMAC with S, as `@crosscode/contracts/signing` already
defines.
- Errors are `crosscode.link/1` `{ message, code }`: `NOT_LINKED` (A isn't in B's list: "Wait for
the next Hub heartbeat, up to 15 minutes, or check the Hub"), `BAD_SIGNATURE`, `STALE_REQUEST`,
`REPLAYED`, `WRONG_INSTALL`.
- Key format: the Hub lists keys as PEM, while the agent helpers in `signing.ts` take raw
base64url. contracts 1.4.0 adds `ed25519PublicFromPem` / `signLink` / `verifyLink` so no
product converts by hand.
- Events also **answers** Connect, since a Website will usually be the one clicking it.
`POST /api/links/v1/connect` and `/disconnect` are public routes, rate-limited per IP, outside
`/api/v2` (they're a cross-product contract, like the feed).
Stored per link in a new table, not in `AppSetting`:
```prisma
model ProductLink {
installId String @id // the sibling's Hub install id
product String // website | app | accounts
url String
publicKey String // as listed by the Hub when connected
secret String // encrypted
connectedAt DateTime
connectedBy String? // a user id when connected here, null when the sibling did it
showEvents Boolean @default(false) // "Show events from" (§4)
lastSyncAt DateTime?
lastSyncError String?
lastGoodAt DateTime?
}
```
If a sibling disappears from `linkedProducts` (uninstalled, or the licence moved), the link stays
but shows **No longer listed by the Hub**. Its events keep showing until an admin removes the
link, so a Hub mistake can't empty the church's event list.
## 3. Publishing: the feed
`GET /api/feed/v1/events?updatedSince=<ISO>` → `crosscode.event-feed/1` (ROADMAP §4,
"Transport"). Public, no sign-in: it only carries what the public event pages already show. It
answers only when **Publish my events** is on (default **on**; otherwise `404 FEED_OFF`).
### Which events
The same rule as the public pages, `publicEventWhere()` in `src/utils/series.js`: `isActive`, not
`isHidden`, `goLiveAt` passed. Plus:
- Events that ended more than **30 days** ago are left out of a full fetch (no `updatedSince`).
An event that ends doesn't go into `deleted`: siblings keep their copy and drop it from
"upcoming" themselves.
- An event's campus goes out as `campus: { slug, name }`, `null` for all campuses.
- **Never** in the feed: kids check-in and volunteer options, contact name/phone/email (the
church's contact for an event can be a person), the attendee form, prices of staff-only options.
### `updatedAt` and `deleted` that are actually right
An event's public face changes without its row changing: it goes live when `goLiveAt` passes,
registration closes at the deadline, and it fills up as tickets sell. `Event.updatedAt` misses
all three, and Events never deletes an event (`deleteEvent` deactivates it). So the feed is kept
in a table of what was last published:
```prisma
model FeedEntry {
eventId String @id
hash String // sha256 of the canonical crosscode.event/1 payload
payload Json
changedAt DateTime // the event's `updatedAt` in the feed
removedAt DateTime? // set when it stops being public: goes into `deleted`
}
```
- A **`feed-refresh`** job (pg-boss, every 5 minutes, and queued straight after an event, option,
session or registration change through the existing Prisma extension in `config/db.js`) builds
each candidate event's `crosscode.event/1`, compares the hash and bumps `changedAt` only when
something a sibling would see has changed. An event that stopped being public gets `removedAt`.
- The feed answers from this table: `events` = rows with `changedAt > updatedSince` and no
`removedAt`; `deleted` = rows with `removedAt > updatedSince`. With no `updatedSince`, every row
without `removedAt`. Rows removed more than 90 days ago are cleaned up.
- When the job changes anything, it sends **`event.changed`** (`eventChangedSchema`, at most 100
ids) to every connected link, signed with that link's secret, using the retries and SSRF rules
of `utils/webhooks.js` (1 min, 5 min, 30 min, 2 h, then give up; the 15-minute poll catches up).
### Building `crosscode.event/1` from an Event
A new `src/feed/toCrosscodeEvent.ts`, checked against `eventSchema` in tests for every e2e seed
event:
| Field | From |
|-------|------|
| `id` | `Event.id` (already a UUID) |
| `origin` | `{ product: "events", installId: hub_install_id, url: <APP_URL>/events/<id> }` |
| `status` | `published` (Events has no "cancelled" state today: cancelling is deactivating, so it goes into `deleted`) |
| `summary` | `null` (no such field yet) |
| `description` | The plain-text description with markdown characters escaped, so it reads the same when rendered as markdown |
| `imageUrl` | `picture`, made absolute |
| `timezone` | The site timezone (`TIMEZONE`) |
| `startsAt` / `endsAt` / `allDay` / `sessions` | `utils/sessions.js` (already keeps start/end in step with the sessions); `allDay: false` |
| `location` | `{ name: location, address: null, onlineUrl: null }`, or `null` |
| `series` | `{ id, name }` |
| `tags` | `[]` (no tags in Events yet) |
| `registration` | `mode`: `origin` when `requiresRegistration`, else `contact`; `url` the event page; `status` from the same rules as the event page (`not_open` before go-live, `closed` after the deadline or late-join cut-off, `full` when every limited main option is sold out, `waitlist` when full with a waitlist); `priceFrom` = the lowest current public price (early-bird and variants as in `eventSchema.ts` today), `null` when free |
## 4. Showing events from linked products
Per connected link: **Show events from this product** (off by default; ROADMAP §4 "Show events
from"). When on:
- **Sync:** a `feed-sync` job per link every **15 minutes**, and straight away on a valid
`event.changed` (`POST /api/feed/v1/changed`, verified with `LINK_HEADERS` and that link's
secret). It fetches `?updatedSince=<lastGoodAt minus 5 minutes>`, 15 s timeout, parses with
`parseEventFeed` (rejected events are logged, never block the rest), and upserts into
`ImportedEvent`. One failing link never holds up another (separate jobs).
- **The last good copy stays.** A failed sync only sets `lastSyncError`; admins see "Last synced
2 hours ago" on Linked products and on the dashboard's event list.
- **Read-only**, keyed by `origin.product` + `id` (`eventKey`), and **never re-published**: the
feed only ever reads `Event`, so no loops (ROADMAP §4 rules).
- Turning **Show events from** off, or removing the link, deletes that link's imported events.
```prisma
model ImportedEvent {
key String @id // eventKey(): "<product>:<id>"
linkId String // ProductLink.installId
payload Json // the crosscode.event/1 as received
startsAt DateTime // copied out for sorting and "upcoming"
endsAt DateTime
campusSlug String?
updatedAt DateTime
@@index([linkId])
@@index([startsAt])
}
```
**Where they show:** on the public **Events** list, the home page's upcoming events and campus
pages (by `campus.slug`, when it matches one of Events' campuses; otherwise under all campuses),
mixed in by date, with a small "From the church website" label. Not in the dashboard's event
tools, reports, check-in or anything that registers people.
**Their page:** `/events/linked/<product>/<id>`: title, dates, sessions, place, image, the
description rendered as markdown with HTML off (`react-markdown`, new dependency), and one button
by `registration.mode`: **More details** / **Register** linking to the origin (`origin` /
`external`), or the contact instructions (`contact`). The page has
`<link rel="canonical">` to `origin.url` (ROADMAP §11, "Imported events"), is left out of
`sitemap.xml`, and has no `Event` JSON-LD (the origin's page carries it, so search engines see
one event).
## 5. `packages/seo`
A new workspace, `@crosscode/seo` (ROADMAP §11): the schema.org builders and meta helpers every
product will use, built on `@crosscode/contracts`. Pure functions, no framework, ESM + CJS like
contracts, its own Jest tests.
| Export | What |
|--------|------|
| `eventJsonLd(event: CrosscodeEvent, opts)` | `Event` JSON-LD from `crosscode.event/1`: `eventStatus` (`EventCancelled` for `cancelled`), attendance mode (`OnlineEventAttendanceMode` / `Mixed…` from `location.onlineUrl`), `Place` or `VirtualLocation`, `offers` from `registration` (`SoldOut` for `full`, `validFrom` from `opensAt`), sessions as `subEvent` |
| `churchJsonLd(church: Church)` | `Church` (a schema.org `Organization` subtype): name, logo, address, geo, phone, service times as `openingHoursSpecification`-style `Event` entries, `sameAs` social links. Used for the Website's home page later; Events uses it as the event `organizer` |
| `canonicalUrl(base, path)` | Drops tracking parameters (`src`, `utm_*`, `fbclid`, `gclid`) and the trailing slash rule in one place |
| `pageMeta({ title, description, … })` | Title length and description trimming rules (60 / 155 characters), used for the Website's warnings later |
**Events moves onto it:** `frontend/src/lib/eventSchema.ts` is replaced. The public event detail
answer gains `crosscodeEvent` (the same builder as the feed, §3), and the page calls
`eventJsonLd` with it. **Nothing gets worse for Google:** today's JSON-LD gives a price *range*
(`AggregateOffer` low–high); `crosscode.event/1` only has `priceFrom`. `eventJsonLd` takes an
optional `priceRange` for the origin's own page, so Events keeps sending the high price. A
snapshot test compares the old and new JSON-LD for each seed event; the only allowed
differences are additions (`subEvent`, `organizer` as a `Church`).
The `organizer` comes from a `crosscode.church/1` that Events builds from its own site settings
(name, logo, colours, contact email). Sharing that profile with siblings is not part of 2.4.0
(see [Still open](#still-open)).
## 6. Settings, audit log and help
- **Settings → Linked products** (new page): the list, Connect / Disconnect, **Show events
from**, last sync. **Settings → Site → Publish my events** (on by default) with one line on
what it shares ("Your public events, as they appear on your events page. Never anyone's
details.").
- **Audit log** (`utils/adminAudit.js`): `product_link_connected`, `product_link_disconnected`,
`feed_publish_toggled`, `feed_show_toggled`. Connections made by the sibling are logged with
no user.
- **Help:** a "Linked products" help article, and the setting descriptions. **What's new** for
2.4.0: "Ready for the Church Website and App: your events can show on them, and theirs here.
Nothing changes until you have them."
- **Readiness checks** (`utils/readiness.js`): warn when a link's last sync failed for more than
a day.
## 7. What changes in each repo
| Repo | Change | Version |
|------|--------|---------|
| `crosscode-platform` `packages/contracts` | `crosscode.link/1` (`link.ts`: connect, connected, disconnect, errors), optional `publicKey` on the v2 heartbeat, `ed25519PublicFromPem` / `signLink` / `verifyLink`, JSON Schema and samples for each | `contracts@1.4.0` |
| `crosscode-platform` `packages/seo` | New (§5) | Not tagged on its own: a workspace, versioned with its first user like `ui` |
| `crosscode-platform` `apps/events` | §1–§6. Migrations: `ProductLink`, `FeedEntry`, `ImportedEvent`. New deps: `@crosscode/contracts`, `@crosscode/seo` (workspace), `react-markdown` | `events@2.4.0` |
| `crosscode-platform` `docs/` | `hub-protocol.md` §6 (heartbeat `publicKey`, moving to v2), ROADMAP §9 phase 2 marked done, HANDOVER | — |
| `events-hub` | v2 heartbeat accepts and saves `publicKey` (`409 PUBLIC_KEY_MISMATCH` for a different one), **Clear public key** button on the install page (2FA again, audited), vendored `contracts-1.4.0.tgz`, its copy of `hub-protocol.md` | Hub `v2.2.0` |
| `crosscode-site` | "Works with the Church Website and App" on the Cross Events page, marked coming (`src/data/cross-events.mjs`) | `v1.4.0` |
New `.env` variables: **none planned.** If one turns up, it goes in all three templates
(HANDOVER, "Things to remember").
## 8. Testing
**Unit and integration (Jest, in `npm run check`):**
- contracts: `crosscode.link/1` samples parse; `signLink` / `verifyLink` refuse a changed body,
another key, a stale `issuedAt` and a replayed nonce.
- seo: `eventJsonLd` / `churchJsonLd` for every contract sample; the old-vs-new snapshot (§5).
- Events, Hub client: the v2 heartbeat body passes `hub.heartbeatRequestSchema`; the key pair is
made once; `publicKey` stops being sent after the ack; falling back to v1 on
`UNSUPPORTED_PROTOCOL`.
- Events, feed: every e2e seed event passes `eventSchema`; hidden, inactive, not-yet-live and
kids/volunteer data never appear; `updatedSince` returns exactly what changed, including
go-live, deadline and selling out with no `Event` row change; deactivating puts it in
`deleted`; feed off → `404 FEED_OFF`.
- Events, Connect: accepted from a listed sibling; refused when not listed, with a key other
than the listed one, stale, replayed or for another install; disconnect from either side.
- Events, sync: a sample Website feed with one invalid event (the rest import, the bad one is
logged); the source down (last copy kept, error shown); `event.changed` with a bad signature
refused; imported events never in our own feed.
- Hub (`events-hub`): v2 heartbeat with a key saves it; the same key is fine; a different one is
`409`; Clear lets a new one in.
**e2e (Playwright, `apps/events/e2e`):** a small fake "Website" (a fixture server in the e2e
setup serving `samples/event-feed.json` and answering Connect) to click through Linked products
→ Connect → Show events from → the imported event on `/events` → its page with the canonical link
and the origin's button; `sitemap.xml` doesn't list it. The §11 checks (title, description,
canonical, `og:image`, one `<h1>`, JSON-LD parses) on the event page and the imported event page.
**On the VM** (as in AGENT-1.0-PLAN §13), before tagging: two installs of Events can't be linked
(one per product per customer), so the VM run uses the fake Website from e2e as a second site
behind frp, against Hub 2.2.0. Check: an existing 2.3.x install updated through the agent moves
itself to v2 and appears with a key on the Hub; Connect works across the two servers; turning
the fake Website off keeps its events showing with "last synced".
## 9. Releasing and rolling it out
Order, each with its CHANGELOG entry and `npm run check` first:
1. `contracts@1.4.0` (platform), then the packed `.tgz` into `events-hub/backend/vendor/`.
2. Hub `v2.2.0`, deployed (`events-hub/deployment.md`).
3. `events@2.4.0` (its `WHATS-NEW.md` heading needs no `requires`: against a Hub before 2.2.0 it
still works, only Linked products stays empty).
4. crosscode-site `v1.4.0`, deployed.
5. Each church updated through the Hub (a scheduled update, ROLLOUT-1.0 §5).
## Decisions
Proposed in this plan, to confirm before building:
1. **Moving to v2 needs no admin action:** the v2 heartbeat carries the install's public key
(optional field), instead of re-registering with the licence key (§1). Needs Hub 2.2.0.
2. **Connect needs no approval on the other side**, and trust comes from each side's own cached
Hub list (§2).
3. **Publish my events is on by default** (it only shares what the public pages already show);
**Show events from** is off by default per link.
4. **The feed is built from a `FeedEntry` table**, not straight from `Event`, so go-live,
deadlines and selling out are reported as changes (§3).
5. **Imported events get their own page** in Events with a canonical link to the origin, rather
than linking straight out from the list (§4).
6. Ended events stay out of `deleted`; a full fetch covers events that ended up to 30 days ago.
## Still open
- **Who owns the church profile (`crosscode.church/1`)** once there's more than one product?
Events builds one from its own settings for its JSON-LD in 2.4.0, but doesn't serve it to
siblings. The Website (phase 4) is the natural owner; decide before phase 4.
- **Event `summary` and `tags`** go out empty because Events has no such fields. Add them in a
later 2.x if the Website's event cards need them.
- **A "cancelled" state in Events** (shown as cancelled rather than disappearing) would map to
`status: "cancelled"`. Not in 2.4.0.
+11 -7
View File
@@ -1,6 +1,6 @@
# Handover — Cross Code, all products
Last updated: 2026-11-17. **The plan is [ROADMAP-v3.md](./ROADMAP-v3.md)** (decided 2026-11-03,
Last updated: 2026-11-18. **The plan is [ROADMAP-v3.md](./ROADMAP-v3.md)** (decided 2026-11-03,
decisions table near the end). This file says where each phase stands and what comes next.
Product-specific notes (where the code lives, known gaps) stay with each product: Cross Events'
are in [`apps/events/docs/HANDOVER.md`](../apps/events/docs/HANDOVER.md), and the Hub's are in
@@ -24,22 +24,26 @@ for each phase and the rollout checklist ([ROLLOUT-1.0.md](./ROLLOUT-1.0.md)).
| Phase | What | State |
|-------|------|-------|
| 0 | contracts 1.0.0 / 1.1.0 | **Released** 2026-11-04. Not published to a registry (decision 22): the Hub gets a packed release committed to its repo (`backend/vendor/`) |
| 1 | Hub 2.0.x | **Released** (`v2.0.0` 2026-11-05, `v2.0.1` AI tokens and `v2.0.2` refunds / voiding refunded invoices, 2026-11-17). **Not deployed yet:** `events-hub/deployment.md` → "Upgrading to 2.0" (run `check-hub2` first) |
| 1 | Hub 2.0.x | **Released** (`v2.0.0` 2026-11-05, `v2.0.1` AI tokens and `v2.0.2` refunds / voiding refunded invoices, 2026-11-17). **Not deployed yet:** `events-hub/deployment.md` → "Upgrading to 2.0" (run `check-hub2` first). Deploy straight to the latest 2.1.x (below) |
| 1b | Cross Events 2.2.0: moved here as `apps/events`, the `crosscode` script | **Released** 2026-11-17 (`events@2.2.0`, with AI use in tokens and the backend under `/api`). **VM tested 2026-11-17** (EVENTS-2.2-PLAN §6, all passing after fixes). **Not rolled out:** servers still run `hope-events` `v2.1.1` until each install is adopted |
| 1c | Cross Events 2.3.0: authenticator app 2FA (TOTP + recovery codes) | **Released** 2026-11-17 (`events@2.3.0`). crosscode-site `v1.3.0` lists it (merged and tagged, **not deployed**) |
| 1d | Agent 1.0.0 + Hub 2.1.0 (+ contracts 1.3.0) | **Released** 2026-11-17 (`agent@1.0.0`, `contracts@1.3.0`, Hub `v2.1.0`). **VM tested** end to end (AGENT-1.0-PLAN §13: joins, installs behind frp, scheduled / batch / missed updates, uninstall with export and purge, forged and replayed jobs). **Not rolled out** |
| 2 | Cross Events 2.4.0: protocol v2, Linked products, event feed, `packages/seo` | Not started. Events keeps speaking protocol 1 until then |
| 1c | Cross Events 2.3.x: authenticator app 2FA (TOTP + recovery codes) | **Released** 2026-11-17 (`events@2.3.0`). **`events@2.3.1`** 2026-11-18: Next.js 16.4.6 (security advisories for 16.2.0–16.4.4), so roll out 2.3.1, not 2.3.0. crosscode-site `v1.3.0` lists it (merged and tagged, **not deployed**) |
| 1d | Agent 1.0.x + Hub 2.1.x (+ contracts 1.3.0) | **Released** 2026-11-17 (`agent@1.0.0`, `contracts@1.3.0`, Hub `v2.1.0`). **VM tested** end to end (AGENT-1.0-PLAN §13: joins, installs behind frp, scheduled / batch / missed updates, uninstall with export and purge, forged and replayed jobs). 2026-11-18: **`agent@1.0.1`** (the agent answers status on the central server itself) and Hub **`v2.1.1`** (adopt passes the church's address; Link takes the short name as a name). **Not rolled out**: use agent 1.0.1 and Hub 2.1.1 |
| 2 | Cross Events 2.4.0: protocol v2, Linked products, event feed, `packages/seo` (+ contracts 1.4.0, Hub 2.2.0) | **Planned** 2026-11-18: [EVENTS-2.4-PLAN.md](./EVENTS-2.4-PLAN.md), with six decisions to confirm before building. Events keeps speaking protocol 1 until then |
| 3–7 | Accounts 1.0.0 → Website 1.0.0 → Events 3.0.0 → App 1.0.0 → App 1.x | Not started |
## Next up
1. **Roll out**, in the order in [ROLLOUT-1.0.md](./ROLLOUT-1.0.md): Hub 2.1.0 (make and back up
1. **Roll out**, in the order in [ROLLOUT-1.0.md](./ROLLOUT-1.0.md) (with the latest patch
releases: Hub 2.1.1, agent 1.0.1, Events 2.3.1): Hub 2.1 (make and back up
the job-signing key first) → the central server's agent (check `proxy_bind_addr = 127.0.0.1`)
→ each church server's agent → **adopt** the demo site, then each church (Link existing → Move
onto the monorepo) → a throwaway New install to prove FASTPANEL, DNS and Let's Encrypt.
2. **Deploy crosscode-site `v1.3.0`** (secure sign-in in the features and the brochure).
3. **Archive `hope-events`** once every install reports 2.2.0 or later (EVENTS-2.2-PLAN §7).
4. **Cross Events 2.4.0** (phase 2), as in ROADMAP §9.
4. **Cross Events 2.4.0** (phase 2): confirm the decisions in
[EVENTS-2.4-PLAN.md](./EVENTS-2.4-PLAN.md), then build it in its order (contracts 1.4.0 →
Hub 2.2.0 → Events 2.4.0 → crosscode-site 1.4.0). It can be built during the rollout; releasing
it needs Hub 2.2.0 deployed.
## The VM test (2026-11-17)
+1 -1
View File
@@ -616,7 +616,7 @@ Planned in [AGENT-1.0-PLAN.md](./AGENT-1.0-PLAN.md). In short:
| 1b | **Cross Events 2.2.0** | **Moves into the monorepo** as `apps/events`, with its git history (merged in, not copied); its packages become workspaces; the **`crosscode` script** (`deploy`, `status`, `install`, `adopt`; §8) replaces `scripts/deploy.sh` and `scripts/install.sh`; every install moved with `crosscode adopt`; `hope-events` archived. Planned with no feature changes; two small ones were added on 2026-11-17 (decided by Joshua): **AI use shown in tokens**, never rand, outside the Hub (needs Hub 2.0.1), and **everything the backend serves under `/api`**, so a site and its API share one address and one proxy rule. **Tagged 2026-11-17, before the VM testing; VM tested the same day** | Before more products, so every product is released and deployed the same way from the start |
| 1c | **Cross Events 2.3.0** | **Authenticator app 2FA** (TOTP) next to email and WhatsApp, with recovery codes; admins can see which method each staff account uses. **Released 2026-11-17** (`events@2.3.0`) | Independent and useful now; the Accounts migration later carries it over |
| 1d | **Agent 1.0.0 + Hub 2.1.0** (contracts 1.3.0) | **Server agent** on every server (polls only, signed jobs, runs the `crosscode` script); Hub: Servers page with stats and alerts, server configuration, frp port list, New install with a choice of server, scheduled / emergency / batch updates with notice to the church, uninstall with an encrypted JSON export, emailed reports. [AGENT-1.0-PLAN.md](./AGENT-1.0-PLAN.md). **Released 2026-11-17** after the VM test; rollout in [ROLLOUT-1.0.md](./ROLLOUT-1.0.md) | Right after 1b (it runs the `crosscode` script), so every new church from then on is installed from the Hub. Can run alongside 1c |
| 2 | **Cross Events 2.4.0** | Reports `product: "events"` (protocol v2), **Linked products**, the event feed (publish + show events from siblings), `packages/seo` (§11) with canonical links for imported events | Small; ready for when the Website exists |
| 2 | **Cross Events 2.4.0** | Reports `product: "events"` (protocol v2), **Linked products**, the event feed (publish + show events from siblings), `packages/seo` (§11) with canonical links for imported events. **Planned 2026-11-18:** [EVENTS-2.4-PLAN.md](./EVENTS-2.4-PLAN.md) (also needs contracts 1.4.0 and Hub 2.2.0, for a public key in the v2 heartbeat) | Small; ready for when the Website exists |
| 3 | **Accounts 1.0.0** | OIDC provider, sign-in, 2FA (email, WhatsApp, authenticator app), password reset, consent and notice, export / delete fan-out, admin, install script | The Website is built on it from day one |
| 4 | **Church Website 1.0.0** | Public site with the **four templates** (§6), admin, simple events + feed, SEO (§11), Hope Family Church as the first church, then a second test church on a different template to prove it repeats | More churches need a website than an app; it also covers the "website only" case |
| 5 | **Cross Events 3.0.0** | Sign-in moves to Accounts; user migration keeping password hashes; migration guide | Breaking change, so a major version, after Accounts is proven on the Website |