@odla-ai/chapter 0.44.0 → 0.46.0

package/README.md

@@ -811,6 +811,8 @@ export const chapter = defineChapter({
       name: "Example Chapter",
       url: "https://chapter.example.com",
       fields: { person: ["name", "email"] },
+      // Independent consent to compare the chapter's commercial projection.
+      commercialParity: true,
     }],
   },
 });
@@ -859,6 +861,61 @@ and relations by composing its own config before passing it to Chapter.
 Formation is off unless configured. Chapter intentionally does not ship a
 public form design: the site renders the fields in its own voice and brand.
 
+### Shared-Stripe commercial shadow
+
+A hub may opt into a read-only network commercial projection when multiple
+chapters intentionally bill through one Stripe account. Every accepted source
+is an exact partition, including Stripe test/live mode:
+
+```ts
+networkCommercialReadModel: {
+  mode: "shadow",
+  sources: [{
+    stripeMode: "test",
+    appId: "example-chapter",
+    chapterId: "example-chapter",
+    environment: "dev",
+    dataEnvironment: "dev",
+    runtime: "cory",
+  }],
+},
+```
+
+The dedicated `/api/network-commercial/stripe-webhook` verifies Stripe's
+signature with `network_commercial_stripe_webhook_secret` before writing an
+append-only, PII-free event fact. The projector is rebuildable and deterministic:
+late metadata-less events may inherit a partition only through an unambiguous
+provider customer/subscription/invoice/charge reference. Wrong, missing,
+ambiguous, unsupported, and colliding events remain explained exceptions.
+
+`GET /api/admin/network-commercial-read-model` is super-admin-only and exposes
+current customer, subscription, invoice, refund, and currency-total facts for a
+BNF operator surface. `POST` with `{ command: "rebuild", mutationId }` rebuilds
+from the local event log without calling or mutating Stripe. `POST` with
+`{ command: "reconcile-stripe" }` performs bounded, GET-only current-object
+reads through the hub's vaulted `stripe_secret_key` and reports missing,
+unexpected, mismatched, truncated, and totals exceptions without changing the
+event log or projection. Objects outside the configured exact partitions are
+counted as ignored rather than adopted. This shadow never
+authorizes charges, refunds, subscription changes, or Chapter lifecycle writes;
+removing it changes no customer-facing behavior. The BNF frontend may be down
+while the webhook continues to ingest. Registering a Stripe endpoint and
+enabling production remain separate reviewed operations.
+
+`POST` with `{ command: "reconcile-chapters" }` is a separate, two-sided opt-in
+comparison. A hub target and the matching follower reader must both set
+`commercialParity: true`; neither record browsing nor Stripe shadow mode grants
+it implicitly. The hub signs a `GET /api/network/commercial-parity` request with
+the edge's `network_share_*` secret. The chapter returns only bounded status,
+cancellation, counts, completeness, and domain-separated HMAC-SHA-256 digests of
+application, Stripe customer, and Stripe subscription identifiers. Name, email,
+raw identifiers, and arbitrary application fields never cross the edge. The hub
+compares those digests with its exact Stripe partition and reports chapter-only,
+shadow-only, cancellation, count, unavailable, invalid, and truncation
+exceptions without persisting or changing either side. Chapter application
+status and Stripe subscription status remain distinct vocabularies and are shown
+side by side rather than falsely compared for equality.
+
 For a hub with network targets, the standard admin catalog is Dashboard,
 Network, People, Portfolio, and Settings. Dashboard Overview renders aggregate network
 health; People contains CRM types whose `workspace` is absent or `"people"`;
@@ -893,6 +950,8 @@ export const chapter = defineChapter({
       editableFields: { person: ["name", "email", "phone", "linkedin"] },
       stageTransitions: ["person"],
       admissionGrants: true,
+      // Independent disclosure consent. This may be the reader's only ability.
+      commercialParity: true,
     }],
   },
 });

package/dist/{copy-context-B4SCy6vx.d.ts → copy-context-GaxckY3T.d.ts}

@@ -147,6 +147,26 @@ interface ResolvedNetworkPersonRegistry {
     chapterIds: readonly string[];
 }
 
+/** One exact Stripe event partition accepted by the network commercial shadow. */
+interface NetworkCommercialSource {
+    appId: string;
+    chapterId: string;
+    environment: string;
+    dataEnvironment: string;
+    runtime: string;
+    stripeMode: "test" | "live";
+}
+/** Opt-in, read-only projection of a shared Stripe account. */
+interface ChapterNetworkCommercialReadModel {
+    mode: "shadow";
+    sources: readonly NetworkCommercialSource[];
+}
+/** Validated settings carried by a resolved hub. */
+interface ResolvedNetworkCommercialReadModel {
+    mode: "shadow";
+    sources: readonly NetworkCommercialSource[];
+}
+
 /** Scalar kinds accepted by the Chapter schema adapter. */
 type AttrType = "string" | "number" | "boolean" | "json";
 /** One odla-db attribute: its type and index/uniqueness/optionality flags. */
@@ -209,6 +229,10 @@ interface ChapterNetworkTarget {
     /** Allow package-owned desired admission decisions for existing leader CRM
      * people to be delivered to this target. Omitted means default deny. */
     admissionGrants?: boolean;
+    /** Allow this leader to request a PII-free commercial parity snapshot from
+     * this follower. The follower must independently enable the same reader;
+     * omitted means no application or Stripe identifier digest crosses. */
+    commercialParity?: boolean;
 }
 /** One signed peer allowed to browse a privacy-bounded projection of this
  * site's CRM. The follower owns this allowlist; a leader target declaration
@@ -233,6 +257,9 @@ interface ChapterNetworkReader {
     /** Accept signed desired admission decisions from this reader. Independent
      * of record browsing; an admission-only reader may omit `fields`. */
     admissionGrants?: boolean;
+    /** Disclose a bounded, PII-free commercial parity snapshot to this signed
+     * reader. Identifiers leave only as edge-keyed, domain-separated HMACs. */
+    commercialParity?: boolean;
 }
 /** Leader/follower network configuration. A follower needs no code config to
  * receive pushed records. It must explicitly declare `readers` before any peer
@@ -278,6 +305,7 @@ interface ResolvedNetworkTarget {
     editableFields: Record<string, readonly string[]>;
     stageTransitions: readonly string[];
     admissionGrants?: boolean;
+    commercialParity?: boolean;
 }
 /** A validated follower-owned record projection for one signed reader. */
 interface ResolvedNetworkReader {
@@ -287,6 +315,7 @@ interface ResolvedNetworkReader {
     editableFields: Record<string, readonly string[]>;
     stageTransitions: readonly string[];
     admissionGrants?: boolean;
+    commercialParity?: boolean;
 }
 /** Fully-resolved leader network configuration. */
 interface ResolvedNetwork {
@@ -554,6 +583,8 @@ interface ChapterConfig {
     /** Network-scoped canonical Person registry. Shadow mode is additive only:
      * Chapter workflows and access continue to read their existing authority. */
     networkPersonRegistry?: ChapterNetworkPersonRegistry;
+    /** Read-only, rebuildable commercial projection from a shared Stripe account. */
+    networkCommercialReadModel?: ChapterNetworkCommercialReadModel;
     /** Enable a public, host-rendered formation application workflow. */
     formation?: LeaderFormationConfig;
     thesis?: unknown;
@@ -656,6 +687,8 @@ interface Chapter {
     builderLibrary: ResolvedBuilderLibrary | null;
     /** Null unless this hub explicitly enables the shadow Person registry. */
     networkPersonRegistry: ResolvedNetworkPersonRegistry | null;
+    /** Null unless this hub explicitly enables the commercial shadow. */
+    networkCommercialReadModel: ResolvedNetworkCommercialReadModel | null;
     /** Resolved public formation intake contract (disabled when omitted). */
     formation: ResolvedLeaderFormation;
     /** Resolved CRM engine (from `defineCrm`). */