@odla-ai/chapter 0.37.0 → 0.38.0

package/README.md

@@ -554,6 +554,32 @@ join-config, application tier validation, and checkout already read. Public
 application contract, and theme. Applicant requests therefore use local
 last-known-good state and never depend on the hub being reachable.
 
+#### One field contract for follower forms and CMS management
+
+Chapter owns field identity and storage authority; a hub such as Built Not
+Found owns the editor. Declare the follower's maximum application field set in
+`defineChapter({ application: { required, optional, conditions, maxLen } })`.
+A signed signup-control revision may select, reorder, and change requiredness
+only within that declared set. It cannot invent a field, change its value type,
+or expose an operational application attribute.
+
+`chapterFlowFieldContract(chapter, "join")` and
+`chapterFlowFieldContract(chapter, "formation")` return the same versioned,
+ordered shape: stable field id, label, CRM value type, requiredness, order,
+length cap, enum options, and conditions where the flow supports them.
+`GET /api/join-config` exposes the effective `fieldContract` after active
+signup control is applied. `GET /api/formation/config` exposes the same
+`fieldContract` and retains its legacy `fields` array as a compatibility alias.
+Use that document for a CMS preview or host renderer; submit to the packaged
+route so the server enforces the same effective selection.
+
+Email identity is literal. `normalizeChapterEmail()` trims and lowercases only;
+it never applies Gmail/provider alias rules. Consequently
+`foo+bar@gmail.com` and `foo@gmail.com` are distinct application, admission,
+purchase, and gift-beneficiary identities even if a mailbox provider delivers
+both to the same inbox. Email fields advertise `emailIdentity: "literal"` in
+the flow contract so editors and test fixtures do not collapse them.
+
 Materialization addresses provisioned groups and tiers by their unique public
 `id` attributes, not by assuming those values are odla-db entity ids. A failed
 materialization returns a bounded JSON `materialization_failed` rejection and
@@ -726,7 +752,8 @@ and relations by composing its own config before passing it to Chapter.
 
 `formation: {}` opts into a host-rendered public application:
 
-- `GET /api/formation/config` returns only configured public field metadata.
+- `GET /api/formation/config` returns only configured public field metadata in
+  the same versioned `fieldContract` shape as the join flow.
 - `POST /api/formation/applications` accepts only those fields and creates a
   normal `chapter_application` CRM record.
 - A stable base64url `submissionId` makes ambiguous retries resolve to the same
@@ -1261,7 +1288,8 @@ These bite silently — a smoke test won't catch them:
   against a permissive email shape (400 on `"notanemail"`, so it fails cleanly
   here rather than at the downstream Clerk create) — set
   `application: { validateEmail: false }` to opt out; `isValidEmail` is exported.
-  A valid application is never newly rejected.
+  A valid application is never newly rejected. Identity normalization trims
+  and lowercases but keeps the full local part: plus-addresses remain distinct.
 - **CRM enrichment.** `projectApplicant` writes the base identity/contact person.
   To carry more of the application into the CRM, list `application: { crmFields:
   [...] }`. Each name is **cross-checked against your crm `person` type at