@odla-ai/chapter 0.25.0 → 0.25.1

package/README.md

@@ -641,9 +641,14 @@ These bite silently — a smoke test won't catch them:
 - **CRM projection points.** chapter projects the person on application submit
   (`projectApplicant`), not on booking or on webhook status change. If you mirror
   pipeline stage into the CRM, keep those routes.
-- **Route names.** chapter serves `/api/config`, `/api/join-config`, etc. Alias
-  legacy names in ~4 lines with a host route in `chapterWorker({ routes })` rather
-  than rewriting pages.
+- **Route contracts, not route names.** Chapter serves `/api/config`,
+  `/api/join-config`, etc. Alias a legacy URL with a host route only after
+  method, auth, request, response shape, units, status, and header parity are
+  proven. Equal values with different JSON contracts are not compatible. For a
+  join flow, adopt `JoinIsland` end to end or keep an explicit tested adapter;
+  do not merely repoint an existing page at `/api/join-config`. `PaymentStep`
+  obtains Stripe's `clientSecret`, `publishableKey`, and `lineItems` from
+  `POST /api/payments/subscription`, not from the public join-config response.
 
 ### Install + scope notes
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@odla-ai/chapter",
-  "version": "0.25.0",
+  "version": "0.25.1",
   "description": "A leader/follower foundation for branded membership sites: shared CRM, admin, auth, payments, booking, and explicit record delivery from one defineChapter config.",
   "license": "MIT",
   "homepage": "https://odla.ai/docs/packages/chapter",

package/runbooks/adopt-existing.md

@@ -68,6 +68,16 @@ Create or extend root `MIGRATION.md`; never replace its history. Record state
   render sink;
 - telemetry, freshness/error alerts, deploy commands, and CI auto-deploys.
 
+For every route, record the method/path, current consumer, owning implementation
+(`legacy`, Chapter, or an explicit host adapter), request and response schemas,
+status/error/auth/cache behavior, and its evidence. Source evidence names the
+checked-in path plus commit; deployment evidence names the origin plus immutable
+Worker/deployment version. A response observed on an unversioned deployment
+describes only that deployed build at that moment. It does not establish route
+ownership or the contract of the branch being changed. Treat old branches, git
+history, and unrelated deployments as leads to verify, never as the migration
+specification.
+
 ### Freeze visual and behavior evidence
 
 Capture representative production screenshots and measured layouts at 390,
@@ -150,13 +160,20 @@ explicit:
 
 Before deleting old schema/rules/provisioning:
 
-1. freeze the legacy schema and rules as reviewed test fixtures;
-2. normalize only approved representational differences;
-3. compare `createChapterIntegration(chapter)` namespaces, attrs, links, rules,
-   and seeds to the fixtures;
-4. fail on missing fields, widened rules, cardinality changes, renamed natural
+1. freeze the legacy schema and rules from an exact reviewed source path and
+   commit, with a recorded content digest;
+2. make that baseline independent: use the untouched legacy source or a literal
+   fixture that does not import Chapter, the active descriptor/schema alias, or
+   another generated candidate; do not modify baseline and candidate in the
+   same approval;
+3. normalize only approved representational differences;
+4. compare `createChapterIntegration(chapter)` namespaces, attrs, links, rules,
+   and seeds to the independent baseline;
+5. run a negative control by removing or changing a known field/rule on one side
+   and prove the parity test fails before trusting a green result;
+6. fail on missing fields, widened rules, cardinality changes, renamed natural
    keys, new client-readable data, or unapproved seed differences;
-5. record every intentional delta and migration mapping in `MIGRATION.md`.
+7. record every intentional delta and migration mapping in `MIGRATION.md`.
 
 `createChapterIntegration()` inserts the group seed only when absent. Existing
 runtime owner edits do not update from later config changes. Compare the current
@@ -343,10 +360,25 @@ Do not replace schema, worker, routes, and UI in one unreviewable change.
    routes run before built-ins and receive Chapter's existing context
    (`verifyUser`, `makeDb`, `roleFor`, `isAdmin`); do not verify JWTs twice.
 3. Initially keep every bespoke endpoint as a host route. Alias legacy URLs to
-   Chapter behavior instead of breaking clients.
-4. Compare built-in and legacy behavior route by route; only then remove a host
-   route that Chapter fully owns.
-5. Keep static fallback and API handling explicit so unknown APIs cannot fall
+   Chapter behavior only when the route-contract matrix proves method, auth,
+   request body, response status, JSON keys/types/nesting, units, null/omission
+   semantics, and relevant headers are compatible. Matching business values
+   alone is not response-shape parity.
+4. When contracts differ, keep the legacy route until its consumer adopts the
+   packaged Chapter component end to end, or add an explicit adapter with
+   contract tests. Do not simply repoint the existing browser code.
+5. In Chapter 0.25, `/api/join-config` is Chapter-owned and returns the
+   group-scoped join configuration, raw cent values, policy copy, and readiness;
+   it is not a promise to reproduce a legacy route's prebuilt Stripe line items
+   or publishable key. `JoinIsland` delegates payment to `PaymentStep`, which
+   obtains `clientSecret`, `publishableKey`, and `lineItems` from
+   `POST /api/payments/subscription` after application submission and refund
+   acknowledgement. Verify this installed-version contract before retiring a
+   legacy join route.
+6. Compare built-in and legacy behavior route by route; only then remove a host
+   route that Chapter fully owns and whose consumers use the verified Chapter
+   contract or adapter.
+7. Keep static fallback and API handling explicit so unknown APIs cannot fall
    through to a successful SPA document.
 
 Test public/private method policies, body limits, idempotency, auth 401 vs 403,
@@ -493,9 +525,12 @@ selected account invitation effect. Never let dev send to imported members.
 
 Check in an executable acceptance manifest with:
 
-- actual dev URLs and Worker version ids;
+- actual dev URLs and immutable Worker version ids, paired with the source
+  commit they are expected to run;
 - deterministic synthetic member/application ids;
-- expected routes/statuses, schema/counts/freshness, and Chapter backend marker;
+- expected route owners and full request/response contracts—not only paths,
+  statuses, or equal values—plus schema/counts/freshness and Chapter backend
+  marker;
 - expected migration-readiness inputs and a `200` only when each is green;
 - expected account, payment, booking, email, CRM, and admin outcomes;
 - expected o11y service/release and safe trace;
@@ -521,6 +556,14 @@ Run the real journey:
 `doctor`, unit tests, build, CLI smoke, a login page, and a human-looking admin
 screen are necessary but not sufficient.
 
+Before filing a route bug from deployed evidence, prove that the probed
+deployment runs the intended commit/version. Repeat the request against the
+direct candidate origin and the public domain with a unique non-secret query
+value, capture `Age`, `Cache-Control`, `CF-Cache-Status`, `ETag`, and the Worker
+version marker, and re-test after the documented edge/config propagation
+window. A cached pre-deploy or pre-credential `404` is not evidence that the
+current route is absent.
+
 ## Phase 8 — Production parallel run and cutover
 
 Do not add production until the human approves the full dev report and both