@odla-ai/chapter 0.60.0 → 0.62.0

package/dist/ui/admin/index.d.ts

@@ -1,8 +1,8 @@
 import * as preact from 'preact';
 import { ComponentChildren, JSX } from 'preact';
-import { CrmClient, Crm, CrmRecord, FieldType } from '@odla-ai/crm';
-import { a as Chapter, b as ChapterCopy, M as MemberContentDocument, E as EffectiveMemberContent, c as MemberContentTierAuthority } from '../../copy-context-BP3G1iBd.js';
-export { C as ChapterCopyProvider, u as useChapterCopy } from '../../copy-context-BP3G1iBd.js';
+import { CrmClient, CrmConfig, Crm, FieldConditions, CrmRecord, FieldType } from '@odla-ai/crm';
+import { a as ChapterBrand, b as ChapterCopyInput, c as ChapterCopy, M as MemberContentDocument, E as EffectiveMemberContent, d as MemberContentTierAuthority } from '../../copy-context-BJUkVUjE.js';
+export { C as ChapterCopyProvider, u as useChapterCopy } from '../../copy-context-BJUkVUjE.js';
 import { CrmLifecycleAdapter, CrmWorkspaceMasterContext, CrmWorkspaceRecordContext, RecordPanelTab } from '@odla-ai/crm/ui';
 
 /** Normalized public auth configuration consumed by the Clerk gate. */
@@ -130,6 +130,675 @@ interface AdminShellProps {
     renderWorkspaceFrame?: (props: AdminWorkspaceFrameProps) => ComponentChildren;
 }
 
+/**
+ * A tier as declared in `defineChapter`, before it becomes a row.
+ *
+ * `groupId` is absent here because the chapter owns exactly one group at seed
+ * time; the seeder fills it in.
+ */
+interface ChapterTierConfig {
+    id: string;
+    name: string;
+    priceCents: number;
+    currency?: string;
+    interval?: "year" | "month";
+    stripePriceId?: string;
+    blurb?: string;
+    /** Defaults to declaration order when omitted. */
+    sortOrder?: number;
+    /** Defaults to true; set false to retire a tier without deleting it. */
+    active?: boolean;
+}
+
+/** A code-declared mail event. Copy stays in settings; this describes who receives it and the values the event supplies. */
+interface ChapterEmailEvent {
+    label: string;
+    trigger: string;
+    audience: string;
+    variables: readonly string[];
+    /** Values deliberately allowed to render empty, such as a free tier's amount suffix. */
+    optionalVariables?: readonly string[];
+    /** Require a resolved tier display name even when the copy does not mention it. */
+    requiresTier?: boolean;
+}
+
+/** Explicit authority a chapter grants to one Built Not Found-style hub. */
+interface ChapterSignupControl {
+    /** Stable app id expected in the signed delivery envelope. */
+    sourceId: string;
+    /** Follower-vault key holding the dedicated edge secret. */
+    secretName?: string;
+    /** Optional per-runtime vault keys. When present, unlisted runtimes and legacy untargeted deliveries fail closed. */
+    runtimeSecrets?: Readonly<Record<string, string>>;
+    /** Stripe mode this deployed environment accepts. */
+    stripeMode: "test" | "live";
+}
+/** Validated signup-control authority carried on a resolved Chapter. */
+interface ResolvedSignupControl {
+    sourceId: string;
+    secretName: string;
+    runtimeSecrets?: Readonly<Record<string, string>>;
+    stripeMode: "test" | "live";
+}
+
+/** Optional authenticated member-content surface for a chapter site. */
+interface ChapterMemberContent {
+    /** Keep Chapter-admin authoring enabled. Defaults to true. */
+    localAuthoring?: boolean;
+    /** Optional Parent/Built Not Found authority for signed inherited revisions. */
+    parent?: {
+        sourceId: string;
+        /** Follower-vault key holding the dedicated content edge secret. */
+        secretName?: string;
+    };
+}
+/** Validated member-content settings carried on a resolved Chapter. */
+interface ResolvedMemberContent {
+    enabled: true;
+    localAuthoring: boolean;
+    parent: {
+        sourceId: string;
+        secretName: string;
+    } | null;
+}
+
+/** Invite links and referral credit for a chapter-mode site. */
+interface ChapterMemberReferrals {
+    /** Public path that invite links live under; `<path>/<code>`. Defaults to `/join`. */
+    path?: string;
+    /** Where an invite link sends a visitor (absolute https URL or site path). `?ref=<code>` is appended. */
+    membershipUrl: string;
+    /** Lifetime of the first-party referral cookie, in days. Defaults to 90. */
+    cookieDays?: number;
+    /**
+     * Credit a dues-paying referrer earns when a friend they referred is approved
+     * on a dues-paying tier. Omit or `false` for invite links without credit.
+     */
+    credit?: {
+        valueCents: number;
+    } | false;
+}
+/** The signed-in member portal. Its navigation and access come from the member-content catalog. */
+interface ChapterMemberPortal {
+    /** Prompts a member may answer on their profile, in display order. */
+    profilePrompts?: readonly string[];
+    /** How many prompts a member may answer. Defaults to 3. */
+    maxPrompts?: number;
+    /** Member profile photos in odla-db file storage. Defaults to true. */
+    photos?: boolean;
+    /** Cohort courses on one recurring Google Calendar event. Chapter mode only. */
+    courses?: boolean;
+    /** Personal invite links, Referred by, and optional credit. Chapter mode only. */
+    referrals?: ChapterMemberReferrals;
+}
+/** Resolved invite-link settings. */
+interface ResolvedMemberReferrals {
+    path: string;
+    membershipUrl: string;
+    cookieDays: number;
+    creditCents: number | null;
+}
+/** Resolved member portal settings. */
+interface ResolvedMemberPortal {
+    profilePrompts: readonly string[];
+    maxPrompts: number;
+    photos: boolean;
+    courses: boolean;
+    referrals: ResolvedMemberReferrals | null;
+}
+
+/** Optional private Builder Library shared across Built Not Found and Chapters. */
+interface ChapterBuilderLibrary {
+    /** Keep local admin authoring enabled. Defaults to true. */
+    localAuthoring?: boolean;
+    /** Existing Chapter-network peers this app accepts. Hub sources must be
+     * configured network targets; a Chapter source must be a configured reader. */
+    sources?: readonly {
+        sourceId: string;
+    }[];
+}
+interface ResolvedBuilderLibrarySource {
+    sourceId: string;
+}
+/** Validated Builder Library settings carried on a resolved Chapter. */
+interface ResolvedBuilderLibrary {
+    enabled: true;
+    localAuthoring: boolean;
+    sources: readonly ResolvedBuilderLibrarySource[];
+}
+
+/** Opt-in network-scoped Person registry. Shadow mode never gates Chapter work. */
+interface ChapterNetworkPersonRegistry {
+    mode: "shadow";
+    /** Chapter ids that may be attached to imported source rows. Defaults to the
+     * hub's configured network target ids. */
+    chapterIds?: readonly string[];
+}
+/** Validated network Person registry settings carried by a resolved Chapter. */
+interface ResolvedNetworkPersonRegistry {
+    mode: "shadow";
+    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. */
+interface Attr {
+    type: AttrType;
+    unique: boolean;
+    indexed: boolean;
+    optional: boolean;
+}
+/** One odla-db namespace: its attribute map. */
+interface Entity {
+    attrs: Record<string, Attr>;
+}
+/** A serialized odla-db schema fragment (namespaces + links). */
+interface DbSchema {
+    entities: Record<string, Entity>;
+    links: Record<string, unknown>;
+}
+/** Per-namespace CEL rule strings (deny-all is `"false"` for each action). */
+interface Rule {
+    view: string;
+    create: string;
+    update: string;
+    delete: string;
+}
+/** Namespace → rule set. */
+type DbRules = Record<string, Rule>;
+
+/** One follower site a leader can push CRM records to. The secret VALUE never
+ * lives in config: `secretName` names the leader tenant's vaulted copy of the
+ * follower's `network_share_secret`. Both slots are declared by
+ * `createChapterIntegration` and filled together by
+ * `odla-ai chapter edge pair --leader <leader> --follower <id>`; until then
+ * every leader-side surface reports the edge as `edge_unpaired`. */
+interface ChapterNetworkTarget {
+    /** Stable lowercase slug used by the UI, audit tags, and default secret name. */
+    id: string;
+    /** Human-facing site name. Defaults to `id`. */
+    name?: string;
+    /** Absolute follower origin, e.g. `https://chapter.example.com`. */
+    url: string;
+    /** Optional Cloudflare service-binding name for Worker-to-Worker delivery.
+     * The URL still defines the signed request origin; the binding only supplies
+     * the transport when a `workers.dev` subrequest cannot enter another Worker. */
+    binding?: string;
+    /** Leader-vault key holding this follower's share secret. Defaults to
+     * `network_share_<id-with-underscores>`. */
+    secretName?: string;
+    /** Per-record-type field allowlist. If present, omitted types cannot be sent
+     * to this target. Without it, package-safe person/company defaults apply. */
+    fields?: Record<string, readonly string[]>;
+    /** Record types on which leader admins may deliberately share notes with
+     * this follower. Omitted by default: a target never gains write permission
+     * merely because its records are browsable. */
+    sharedNotes?: readonly string[];
+    /** Per-record-type upper bound on profile fields this leader permits its
+     * admins to edit remotely. The follower must independently delegate the
+     * same field; readable fields never become writable implicitly. */
+    editableFields?: Record<string, readonly string[]>;
+    /** Record types on which this leader permits remote lifecycle transitions.
+     * The follower must independently opt in and remains pipeline authority. */
+    stageTransitions?: readonly string[];
+    /** 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
+ * cannot widen it. */
+interface ChapterNetworkReader {
+    /** Stable app/site slug expected in the signed federation envelope. */
+    id: string;
+    /** Per-record-type field allowlist. Omitted types and fields never leave
+     * this site. Record id, name, stage, and timestamps are bounded metadata. */
+    fields?: Record<string, readonly string[]>;
+    /** Record types on which this reader may append an explicitly shared note.
+     * Omitted by default: browse permission never silently grants write access.
+     * Shared notes land in the follower CRM activity feed. */
+    sharedNotes?: readonly string[];
+    /** Exact local CRM fields this reader may edit remotely, by record type.
+     * Every field must also be readable so the peer can perform an optimistic
+     * edit against the value and revision it actually reviewed. */
+    editableFields?: Record<string, readonly string[]>;
+    /** Local CRM record types on which this reader may request a lifecycle
+     * transition. Chapter still enforces the local pipeline and gates. */
+    stageTransitions?: readonly string[];
+    /** 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
+ * can browse its CRM. */
+interface ChapterNetwork {
+    /** Require the protected super-admin tier for remote mutations and operational
+     * detail. Ordinary admins retain routine name/email directory reads. */
+    requireSuperAdminWrites?: boolean;
+    targets?: readonly ChapterNetworkTarget[];
+    readers?: readonly ChapterNetworkReader[];
+}
+/** Public chapter-formation intake backed by one CRM record type. The host owns
+ * the branded form; Chapter owns the bounded, idempotent write contract. */
+interface LeaderFormationConfig {
+    /** CRM type receiving submissions. Default `"chapter_application"`. */
+    type?: string;
+    /** Public fields that must be non-empty strings. */
+    required?: readonly string[];
+    /** Additional public fields accepted by the route. */
+    optional?: readonly string[];
+    maxLen?: Record<string, number>;
+    /** Per-string cap when `maxLen` has no field override. Default 4000. */
+    defaultMaxLen?: number;
+    /** Maximum JSON request size in UTF-8 bytes, enforced while streaming. Default 32768. */
+    bodyCap?: number;
+}
+/** Fully resolved formation intake policy. */
+interface ResolvedLeaderFormation {
+    enabled: boolean;
+    type: string;
+    required: readonly string[];
+    optional: readonly string[];
+    maxLen: Record<string, number>;
+    defaultMaxLen: number;
+    bodyCap: number;
+}
+/** A validated network target carried on the resolved chapter engine. */
+interface ResolvedNetworkTarget {
+    id: string;
+    name: string;
+    url: string;
+    binding?: string;
+    secretName: string;
+    fields?: Record<string, readonly string[]>;
+    sharedNotes: readonly string[];
+    editableFields: Record<string, readonly string[]>;
+    stageTransitions: readonly string[];
+    admissionGrants?: boolean;
+    commercialParity?: boolean;
+}
+/** A validated follower-owned record projection for one signed reader. */
+interface ResolvedNetworkReader {
+    id: string;
+    fields: Record<string, readonly string[]>;
+    sharedNotes: readonly string[];
+    editableFields: Record<string, readonly string[]>;
+    stageTransitions: readonly string[];
+    admissionGrants?: boolean;
+    commercialParity?: boolean;
+}
+/** Fully-resolved leader network configuration. */
+interface ResolvedNetwork {
+    requireSuperAdminWrites?: boolean;
+    targets: readonly ResolvedNetworkTarget[];
+    readers: readonly ResolvedNetworkReader[];
+}
+
+/**
+ * Membership pricing for the group row (chapter mode).
+ *
+ * This is the single-price model that predates tiers. It still seeds the group
+ * row and remains the fallback a chapter reads when it declares no tiers, so
+ * existing chapters keep working; new work should prefer `tiers`.
+ */
+interface ChapterPrices {
+    standardCents: number;
+    foundingDiscountCents?: number;
+    /** ISO currency, default "usd". */
+    currency?: string;
+    /** Billing interval, default "year". */
+    interval?: "year" | "month";
+}
+/** Membership policy + compliance copy stored on the group row. */
+interface ChapterPolicy {
+    disclaimerText?: string;
+    refundPolicyText?: string;
+    /** Plain-language merchant identity shown immediately before payment consent. */
+    merchantDisclosureText?: string;
+    trustCopy?: string;
+    commitmentText?: string;
+    normsText?: string;
+}
+
+/** Which feature profile a site runs. `chapter` is the full public member site
+ * (join, Stripe membership, booking, member area, admin, CRM); `hub` is
+ * admin-only and CRM-focused (a directory/registry over the same CRM). */
+type ChapterMode = "chapter" | "hub";
+/** One owner-editable transactional email template. Automatic sends require explicit `enabled: true`. */
+interface EmailTemplate {
+    subject: string;
+    text: string;
+    enabled?: boolean;
+}
+/** Notification/reply/debug addresses + operational email templates. */
+interface ChapterEmails {
+    notificationEmail: string;
+    replyTo?: string;
+    /** Display name on outbound lifecycle mail (`Tori Horton <from@…>`); the
+     * address itself stays the Worker's `EMAIL_FROM`. Absent ⇒ bare address. */
+    fromName?: string;
+    debugEmail?: string;
+    /** Operational lifecycle templates: adminNotification / submitConfirmation /
+     * paymentConfirmation / prepEmail / onboardingInvite / namedSeatInvitation / seatAccepted,
+     * plus declared host events. Missing enabled flags block sending. */
+    templates?: Record<string, EmailTemplate>;
+    /** Additional host-owned email events shown and validated in the email editor. Declaring an event never sends it. */
+    events?: Record<string, ChapterEmailEvent>;
+}
+/** Booking rules for the intro-call scheduler (stored as schedulingJson). */
+interface ChapterScheduling {
+    slotMinutes?: number;
+    days?: readonly number[];
+    startHour?: number;
+    endHour?: number;
+    timezone?: string;
+    minNoticeHours?: number;
+    windowDays?: number;
+    summaryTemplate?: string;
+}
+/** How a signed-in user's role is determined.
+ *
+ * - `"clerk"` reads backend-only private Clerk roles for each authorization
+ *   check, without trusting public metadata or stale session roles.
+ * - `"claim"` reads a role ladder from a JWT claim (the legacy member-site model:
+ *   `provisional → member → admin`). Admin is the last (highest) rung; the
+ *   Studio-managed super-admin tier sits above it.
+ * - `"table"` gates on the deny-all `admins` allowlist (the hub model):
+ *   a binary "email is an admin or isn't", set only in odla Studio.
+ *
+ * Defaults: `"claim"` in `chapter` mode, `"table"` in `hub` mode. */
+interface ChapterAuth {
+    /** `clerk` reads backend-only private_metadata.role on each request, ignoring
+     * JWT/public roles. Select explicitly after the coordinated role migration. */
+    source?: "claim" | "table" | "clerk";
+    /** JWT claim holding the role, for `source: "claim"`. Default `"role"`. */
+    claim?: string;
+    /** Role ladder low→high, for claim or private Clerk roles. The last entry is admin.
+     *  Default `["provisional", "member", "admin"]`. */
+    ladder?: readonly string[];
+    /** Enable the Studio-managed super-admin tier — the only tier that may
+     *  create/modify admins. Default: `true` for `"claim"`/`"clerk"`, `false` for `"table"`. */
+    superAdmins?: boolean;
+    /** Authority behind the super-admin tier. `"table"` preserves the legacy
+     * app allowlist; `"odla"` reads protected `$users.role` by exact subject ID.
+     * Default `"odla"` for private Clerk mode, `"table"` for legacy modes. */
+    superAdminSource?: "table" | "odla";
+    /** Require a second sign-in factor on admin routes: `off` (default), `report` (allow and log), `enforce`. */
+    adminSecondFactor?: "off" | "report" | "enforce";
+}
+/** The fully-resolved auth policy (defaults applied) carried on the {@link Chapter}. */
+interface ResolvedAuth {
+    source: "claim" | "table" | "clerk";
+    claim: string;
+    ladder: readonly string[];
+    /** The highest ladder rung (last entry) — the "admin" gate. */
+    adminRole: string;
+    superAdmins: boolean;
+    superAdminSource: "none" | "table" | "odla";
+    adminSecondFactor: "off" | "report" | "enforce";
+}
+/** The application status pipeline. Which statuses exist, and the subsets a site
+ *  allows a call to be booked from / an application approved from. Defaults to
+ *  the reference pipeline. Status never moves backwards (package-enforced). */
+interface ChapterPipeline {
+    stages?: readonly string[];
+    bookableFrom?: readonly string[];
+    approvableFrom?: readonly string[];
+    /** The status a new application starts at. Default: the first stage. */
+    initial?: string;
+}
+/** The fully-resolved pipeline (defaults applied) carried on the {@link Chapter}. */
+interface ResolvedPipeline {
+    stages: readonly string[];
+    bookableFrom: readonly string[];
+    approvableFrom: readonly string[];
+    initial: string;
+}
+/** The application (join form) validation surface — which string fields are
+ *  required vs accepted, their max lengths, and the request body cap. Drives
+ *  submit validation, the generated `applications` schema, and the CRM slot
+ *  projection; defaults to the reference form. Built-in fields retain their
+ *  declared schema types/indexes, and site-defined fields become string attrs. */
+interface ChapterApplication {
+    required?: readonly string[];
+    optional?: readonly string[];
+    /** Per-field CEL conditions — show a field, or demand it, based on the
+     *  answers so far. Enforced server-side as well as rendered, so a hidden
+     *  field is never demanded and a conditionally-required one cannot be
+     *  skipped by posting directly. Validated when the chapter is defined. */
+    conditions?: Record<string, FieldConditions>;
+    /** Per-field character cap. Fields not listed use `defaultMaxLen`. */
+    maxLen?: Record<string, number>;
+    defaultMaxLen?: number;
+    /** Max JSON request body in UTF-8 bytes, enforced while streaming. Default 32768. */
+    bodyCap?: number;
+    /** Reject a submit that carries no truthy `disclaimerAck` (400), instead of
+     *  writing a row with no consent record. Default `true`. Set `false`
+     *  deliberately only when the site renders no consent control. */
+    requireDisclaimerAck?: boolean;
+    /** Allowlist of application fields mirrored into the Clerk account's
+     *  backend-only `private_metadata.profile`. Default `[]`. Use this for small
+     *  account/admin signals; the application row and CRM remain canonical. */
+    profileFields?: readonly string[];
+    /** Extra application fields carried into the one-way CRM projection, on top of
+     *  the built-in identity/contact set. Each MUST be declared on your crm person
+     *  type or the enrichment is dropped (the base person still projects). Default
+     *  none. */
+    crmFields?: readonly string[];
+    /** Cap on the element count of array-valued fields (e.g. `focus`), so a client
+     *  cannot post a 10k-element array into a row or into Clerk metadata.
+     *  Non-primitive elements are dropped. Default 100. */
+    maxArrayLen?: number;
+    /** Validate that a field literally named `email` looks like an email address,
+     *  returning a 400 rather than accepting input the downstream Clerk create will
+     *  reject anyway. Default `true`; a valid application is never newly rejected. */
+    validateEmail?: boolean;
+}
+/** The fully-resolved application config carried on the {@link Chapter}. */
+interface ResolvedApplication {
+    required: readonly string[];
+    optional: readonly string[];
+    maxLen: Record<string, number>;
+    defaultMaxLen: number;
+    bodyCap: number;
+    requireDisclaimerAck: boolean;
+    /** Resolved Clerk-metadata allowlist. Empty means no profile projection. */
+    profileFields: readonly string[];
+    crmFields: readonly string[];
+    maxArrayLen: number;
+    validateEmail: boolean;
+    /** Resolved per-field conditions. Empty means every field is unconditional. */
+    conditions: Record<string, FieldConditions>;
+}
+/** The `defineChapter()` config a site fills in. */
+interface ChapterConfig {
+    /** Slug: app id, tenant, group id, worker name. `[a-z0-9-]`. */
+    id: string;
+    name: string;
+    url?: string;
+    /** Default `"chapter"`. */
+    mode?: ChapterMode;
+    /** A `defineCrm()` config or a resolved `Crm`. Omit for the per-mode default. */
+    crm?: CrmConfig | Crm;
+    brand?: ChapterBrand;
+    /** User-visible language for packaged Chapter surfaces. Recursively partial;
+     * `defineChapter()` resolves every omitted leaf from the package defaults. */
+    copy?: ChapterCopyInput;
+    /** Signed network edges: leader delivery targets and follower-owned,
+     * privacy-bounded record readers. Secret values stay in tenant vaults. */
+    network?: ChapterNetwork;
+    /** A separate signed edge that may control this chapter's complete signup. */
+    signupControl?: ChapterSignupControl;
+    /** Authenticated parent + chapter member pages with server-enforced tier access. */
+    memberContent?: ChapterMemberContent;
+    /** Signed-in member portal: profile, photos, courses, invite links and credit. */
+    memberPortal?: ChapterMemberPortal;
+    /** Private docs, Brand asset references, and links for authorized site-building agents. */
+    builderLibrary?: ChapterBuilderLibrary;
+    /** 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;
+    /** Required in `chapter` mode, and the fallback when `tiers` is empty. */
+    prices?: ChapterPrices;
+    /** Membership tiers. A tier priced at 0 is free and never touches Stripe. */
+    tiers?: ChapterTierConfig[];
+    policy?: ChapterPolicy;
+    /** `notificationEmail` required in `chapter` mode. */
+    emails?: ChapterEmails;
+    scheduling?: ChapterScheduling;
+    /** Application status pipeline (stages + bookable/approvable subsets). */
+    pipeline?: ChapterPipeline;
+    /** Join-form validation (required/optional fields, max lengths, body cap). */
+    application?: ChapterApplication;
+    /** Role source + ladder + super-admin tier. Defaults by mode (see {@link ChapterAuth}). */
+    auth?: ChapterAuth;
+    /** odla services (db implied). Default `["db","calendar","o11y"]`. */
+    services?: readonly string[];
+    /** Apply-time account provisioning. Required in `chapter` mode so a site must
+     *  make the decision explicitly. `"none"` provisions nothing, `"create"` makes
+     *  the Clerk account server-side, and `"invite"` emails a real invitation.
+     *  Both side-effecting models need a `clerk_secret_key` vault secret. */
+    account?: AccountModel;
+    /** WHEN lifecycle email fires. Addressing and content live on the group row
+     *  (owner-editable at runtime); this is the trigger, which is a build-time
+     *  decision. See {@link ChapterSends}. */
+    sends?: ChapterSends;
+    /** Site policy for admin operations (approve side effects, refund rules).
+     *  See {@link ChapterOperations}. */
+    operations?: ChapterOperations;
+}
+/** Apply-time Clerk account provisioning model. */
+type AccountModel = "invite" | "create" | "none";
+/** Site policy for admin OPERATIONS: the DECISIONS, where the mechanics stay
+ *  package-owned. Same model as {@link ChapterSends} — a site declares the rule,
+ *  chapter enforces it. Distinct from {@link ChapterPolicy}, which is member-facing
+ *  copy. (The privilege-escalation rules are NOT here: they are package-enforced
+ *  in `canChangeRole`, gated on `auth.superAdmins`, so a site cannot weaken them.) */
+interface ChapterOperations {
+    /** What approving an application does. */
+    onApprove?: {
+        /** Role to promote the applicant to in Clerk. Defaults to the ladder rung
+         *  directly below admin (e.g. `"member"`); `false` promotes nobody. */
+        promoteTo?: string | false;
+        /** Group email template to send on approve. Default `"onboardingInvite"`;
+         *  `false` sends nothing. */
+        send?: string | false;
+    };
+    /** Refund rules. */
+    refund?: {
+        /** Application statuses a refund may be issued from. Default: any status. */
+        allowedFrom?: readonly string[];
+        /** Also cancel the Stripe subscription. Default `true`. */
+        cancelSubscription?: boolean;
+    };
+}
+/** The fully-resolved {@link ChapterOperations} carried on the {@link Chapter}. */
+interface ResolvedOperations {
+    onApprove: {
+        promoteTo: string | false;
+        send: string | false;
+    };
+    /** `allowedFrom: null` means "any status". */
+    refund: {
+        allowedFrom: readonly string[] | null;
+        cancelSubscription: boolean;
+    };
+}
+/** When the admin notification fires: on application `submit` (default), on the
+ *  first successful `payment`, or `never` (the site drives it itself). */
+type AdminNotificationTrigger = "submit" | "payment" | "never";
+/** Send-policy config: the trigger for each lifecycle email chapter owns. */
+interface ChapterSends {
+    adminNotification?: AdminNotificationTrigger;
+}
+/** Resolved send policy (every trigger present). */
+interface ResolvedSends {
+    adminNotification: AdminNotificationTrigger;
+}
+/** The resolved engine `defineChapter()` returns. */
+interface Chapter {
+    config: ChapterConfig;
+    id: string;
+    name: string;
+    url?: string;
+    mode: ChapterMode;
+    /** Resolved site identity. `wordmark` always falls back to `name`, so the
+     * admin/member UI never needs a second brand declaration. */
+    brand: ChapterBrand;
+    /** Fully resolved user-visible text for packaged Chapter surfaces. */
+    copy: ChapterCopy;
+    /** Validated follower targets for leader-driven record pushes. */
+    network: ResolvedNetwork;
+    /** Null unless this follower explicitly delegates signup authority. */
+    signupControl: ResolvedSignupControl | null;
+    /** Null unless the standard authenticated member-content surface is enabled. */
+    memberContent: ResolvedMemberContent | null;
+    /** Null unless the member portal is enabled. */
+    memberPortal: ResolvedMemberPortal | null;
+    /** Null unless the private scoped Builder Library is enabled. */
+    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`). */
+    crm: Crm;
+    /** Resolved auth policy (source, claim, ladder, super-admin tier). */
+    auth: ResolvedAuth;
+    /** Resolved application status pipeline (stages + bookable/approvable subsets). */
+    pipeline: ResolvedPipeline;
+    /** Resolved join-form validation config. */
+    application: ResolvedApplication;
+    /** The chapter's own odla-db namespaces (mode-dependent; excludes `crm_*`). */
+    schema: DbSchema;
+    rules: DbRules;
+    services: readonly string[];
+    /** Resolved apply-time account provisioning model. */
+    account: AccountModel;
+    /** Resolved send policy — when each lifecycle email fires. */
+    sends: ResolvedSends;
+    /** Resolved admin-operation policy (approve side effects, refund rules). */
+    operations: ResolvedOperations;
+    /** The seed `groups` row derived from config (chapter mode), else `null`. */
+    groupSeed(): Record<string, unknown> | null;
+}
+
 /** Configuration for the Clerk-gated, brand-scoped Chapter admin console. */
 interface ChapterAdminProps {
     chapter?: Chapter;