@odla-ai/chapter 0.48.0 → 0.48.2

package/dist/index.d.cts

@@ -388,7 +388,7 @@ interface LeaderFormationConfig {
     maxLen?: Record<string, number>;
     /** Per-string cap when `maxLen` has no field override. Default 4000. */
     defaultMaxLen?: number;
-    /** Maximum JSON request size in characters. Default 32768. */
+    /** Maximum JSON request size in UTF-8 bytes, enforced while streaming. Default 32768. */
     bodyCap?: number;
 }
 /** Fully resolved formation intake policy. */
@@ -691,7 +691,7 @@ interface ChapterApplication {
     /** Per-field character cap. Fields not listed use `defaultMaxLen`. */
     maxLen?: Record<string, number>;
     defaultMaxLen?: number;
-    /** Max JSON request body in bytes. Default 32768. */
+    /** 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`
@@ -1230,7 +1230,9 @@ interface ChapterRunbookHints {
  * Build the one CLI-consumable integration for a chapter/hub: the crm_*
  * namespaces + crm_config seed + route probe, merged with the chapter's own
  * namespaces and a guarded `groups`-row seed. Drop it in odla.config.mjs's
- * `integrations` array.
+ * `integrations` array. Claim/private-Clerk policies also seed the exact role
+ * ladder and metadata source for Studio. Seeds are insert-only: when changing
+ * auth policy, reconcile that stored policy explicitly before enabling editing.
  */
 declare function createChapterIntegration(chapter: Chapter, options?: ChapterIntegrationOptions): ChapterIntegrationDescriptor;
 
@@ -1248,7 +1250,7 @@ declare function createChapterIntegration(chapter: Chapter, options?: ChapterInt
  * `superAdminSource: "odla"` uses reserved `$users` and adds no app namespace. A `"claim"`
  * chapter therefore emits the reference namespace set — `applications`,
  * `groups`, `meetings`, `emailLog`, `stripeEventReceipts`,
- * `subscriptionCheckoutIntents`, `superAdmins` — with
+ * `subscriptionCheckoutIntents`, `chapterAccountPolicy`, `superAdmins` — with
  * no `admins` table. */
 declare function chapterDb(mode: ChapterMode, auth: ResolvedAuth, includeNetworkNotes?: boolean, application?: ResolvedApplication, includeSignupControl?: boolean, includeMemberContent?: boolean, includeBuilderLibrary?: boolean, includeLeaderAdmissions?: boolean, includeNetworkPersonRegistry?: boolean, includeNetworkCommercialReadModel?: boolean): {
     schema: DbSchema;
@@ -2567,7 +2569,7 @@ declare function hasDisclaimerAck(fields: Record<string, unknown>): boolean;
  * them. Pure; returns `undefined` when there is nothing to write.
  */
 declare function applicantProfile(chapter: Chapter, fields: Record<string, unknown>): Record<string, unknown> | undefined;
-/** A validated submission, or a 400-worthy validation error the route returns.
+/** A validated submission, or a validation/duplicate-email error the route returns.
  *  `disclaimerAckAt` reports what THIS request recorded — a number when consent
  *  was stamped, `null` when none was supplied. It is always present so a missing
  *  consent record is visible in the response rather than silently absent from a
@@ -2581,6 +2583,8 @@ type SubmitResult = {
 } | {
     ok: false;
     error: string;
+    code?: string;
+    status?: number;
 };
 /**
  * Submit a membership application (B2 + B3). Validates the configured required
@@ -2590,6 +2594,9 @@ type SubmitResult = {
  * create two applications. The application id is derived from that same stable
  * input, so the duplicate response returns the first request's canonical id
  * rather than a fresh, nonexistent one. Idempotency is package-enforced.
+ * A unique normalized signup email key prevents concurrent submissions with
+ * different ids from creating two applications; a conflict returns status 409.
+ * Apply the current Chapter schema before deploying this writer.
  * `now`/`newId` are injected (deterministic in tests).
  */
 declare function submitApplication(db: ChapterDb, chapter: Chapter, fields: Record<string, unknown>, opts: {
@@ -3072,16 +3079,15 @@ type StripeResult = StripeRequestResult<Record<string, unknown>>;
  *  of each re-deriving the auth + encoding. */
 declare function stripeCall(sk: string, method: "GET" | "POST" | "DELETE", path: string, params?: Record<string, unknown>, idempotencyKey?: string): Promise<StripeResult>;
 
-/** The outcome of a Clerk provisioning call. `existed` marks the heal case: Clerk
- *  rejected it because the account/invitation is already there, which is the end
- *  state we wanted anyway. */
+/** The outcome of provisioning. An existing identifier is a conflict unless
+ * the account proves it belongs to the original application being retried. */
 interface ClerkResult {
     ok: boolean;
     status: number;
     /** Stable Clerk user id returned by a successful fresh account create. */
     userId?: string;
     existed?: boolean;
-    /** Set when an `existed` heal also refreshed the account's metadata. */
+    /** Legacy result field; signup never refreshes an existing account. */
     refreshed?: boolean;
 }
 /** Inputs for a Clerk invitation. */
@@ -3100,9 +3106,8 @@ declare function clerkInviteRequest(input: ClerkInviteInput): {
     path: string;
     body: Record<string, unknown>;
 };
-/** POST the invitation to the Clerk Backend API. A repeat invite for an
- *  already-invited email heals to `{ ok: true, existed: true }` rather than
- *  reporting a failure the caller would have to special-case. */
+/** POST a new invitation. Existing identifiers and all validation failures are
+ * rejected; invitations never authorize changes to an existing account. */
 declare function createClerkInvitation(secretKey: string, input: ClerkInviteInput, fetchImpl?: typeof fetch): Promise<ClerkResult>;
 /** Inputs for a server-side Clerk user create. */
 interface ClerkUserInput {
@@ -3113,9 +3118,8 @@ interface ClerkUserInput {
     publicMetadata?: Record<string, unknown>;
     /** Backend-only account signals and profile data. */
     privateMetadata?: Record<string, unknown>;
-    /** Optional metadata merge used only when create returns 422 for an existing
-     * account. This lets migrations remove legacy keys without putting tombstone
-     * values on a newly-created user. Defaults to the create metadata. */
+    /** @deprecated Ignored. Use an explicitly authorized metadata update for repairs;
+     * signup must never modify an account found by email. */
     repairMetadata?: ClerkMetadataInput;
 }
 /** Build the Clerk Backend API user-create request. The account is created
@@ -3137,15 +3141,13 @@ declare function updateClerkUserMetadata(secretKey: string, userId: string, inpu
 /** Look a Clerk account up by email and merge its metadata.
  *
  * Returns `false` when no matching user can be resolved or Clerk rejects the
- * lookup or update. Chapter uses this for create-healing and invitation
- * adoption so a repeated application repairs the private account snapshot.
+ * lookup or update. This is an explicit administrative repair primitive;
+ * never call it from public signup or use email knowledge as authorization.
  */
 declare function updateClerkUserMetadataByEmail(secretKey: string, email: string, input: ClerkMetadataInput, fetchImpl?: typeof fetch): Promise<boolean>;
-/** Create the applicant's Clerk account server-side. A repeat for an email that
- *  already has an account heals to `{ ok: true, existed: true }` — the account
- *  exists, which is the state apply-time provisioning wanted — and refreshes
- *  supplied public/private metadata on the existing account so a re-application
- *  repairs a previously missed create (`refreshed: true`). */
+/** Create a new passwordless account. A provider collision never patches the
+ * existing account. A retry may return its id only when backend-private metadata
+ * already names the same original application, preserving all current claims. */
 declare function createClerkUser(secretKey: string, input: ClerkUserInput, fetchImpl?: typeof fetch): Promise<ClerkResult>;
 
 /** Backend metadata field selected for all role reads and writes. */

package/dist/index.d.ts

@@ -388,7 +388,7 @@ interface LeaderFormationConfig {
     maxLen?: Record<string, number>;
     /** Per-string cap when `maxLen` has no field override. Default 4000. */
     defaultMaxLen?: number;
-    /** Maximum JSON request size in characters. Default 32768. */
+    /** Maximum JSON request size in UTF-8 bytes, enforced while streaming. Default 32768. */
     bodyCap?: number;
 }
 /** Fully resolved formation intake policy. */
@@ -691,7 +691,7 @@ interface ChapterApplication {
     /** Per-field character cap. Fields not listed use `defaultMaxLen`. */
     maxLen?: Record<string, number>;
     defaultMaxLen?: number;
-    /** Max JSON request body in bytes. Default 32768. */
+    /** 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`
@@ -1230,7 +1230,9 @@ interface ChapterRunbookHints {
  * Build the one CLI-consumable integration for a chapter/hub: the crm_*
  * namespaces + crm_config seed + route probe, merged with the chapter's own
  * namespaces and a guarded `groups`-row seed. Drop it in odla.config.mjs's
- * `integrations` array.
+ * `integrations` array. Claim/private-Clerk policies also seed the exact role
+ * ladder and metadata source for Studio. Seeds are insert-only: when changing
+ * auth policy, reconcile that stored policy explicitly before enabling editing.
  */
 declare function createChapterIntegration(chapter: Chapter, options?: ChapterIntegrationOptions): ChapterIntegrationDescriptor;
 
@@ -1248,7 +1250,7 @@ declare function createChapterIntegration(chapter: Chapter, options?: ChapterInt
  * `superAdminSource: "odla"` uses reserved `$users` and adds no app namespace. A `"claim"`
  * chapter therefore emits the reference namespace set — `applications`,
  * `groups`, `meetings`, `emailLog`, `stripeEventReceipts`,
- * `subscriptionCheckoutIntents`, `superAdmins` — with
+ * `subscriptionCheckoutIntents`, `chapterAccountPolicy`, `superAdmins` — with
  * no `admins` table. */
 declare function chapterDb(mode: ChapterMode, auth: ResolvedAuth, includeNetworkNotes?: boolean, application?: ResolvedApplication, includeSignupControl?: boolean, includeMemberContent?: boolean, includeBuilderLibrary?: boolean, includeLeaderAdmissions?: boolean, includeNetworkPersonRegistry?: boolean, includeNetworkCommercialReadModel?: boolean): {
     schema: DbSchema;
@@ -2567,7 +2569,7 @@ declare function hasDisclaimerAck(fields: Record<string, unknown>): boolean;
  * them. Pure; returns `undefined` when there is nothing to write.
  */
 declare function applicantProfile(chapter: Chapter, fields: Record<string, unknown>): Record<string, unknown> | undefined;
-/** A validated submission, or a 400-worthy validation error the route returns.
+/** A validated submission, or a validation/duplicate-email error the route returns.
  *  `disclaimerAckAt` reports what THIS request recorded — a number when consent
  *  was stamped, `null` when none was supplied. It is always present so a missing
  *  consent record is visible in the response rather than silently absent from a
@@ -2581,6 +2583,8 @@ type SubmitResult = {
 } | {
     ok: false;
     error: string;
+    code?: string;
+    status?: number;
 };
 /**
  * Submit a membership application (B2 + B3). Validates the configured required
@@ -2590,6 +2594,9 @@ type SubmitResult = {
  * create two applications. The application id is derived from that same stable
  * input, so the duplicate response returns the first request's canonical id
  * rather than a fresh, nonexistent one. Idempotency is package-enforced.
+ * A unique normalized signup email key prevents concurrent submissions with
+ * different ids from creating two applications; a conflict returns status 409.
+ * Apply the current Chapter schema before deploying this writer.
  * `now`/`newId` are injected (deterministic in tests).
  */
 declare function submitApplication(db: ChapterDb, chapter: Chapter, fields: Record<string, unknown>, opts: {
@@ -3072,16 +3079,15 @@ type StripeResult = StripeRequestResult<Record<string, unknown>>;
  *  of each re-deriving the auth + encoding. */
 declare function stripeCall(sk: string, method: "GET" | "POST" | "DELETE", path: string, params?: Record<string, unknown>, idempotencyKey?: string): Promise<StripeResult>;
 
-/** The outcome of a Clerk provisioning call. `existed` marks the heal case: Clerk
- *  rejected it because the account/invitation is already there, which is the end
- *  state we wanted anyway. */
+/** The outcome of provisioning. An existing identifier is a conflict unless
+ * the account proves it belongs to the original application being retried. */
 interface ClerkResult {
     ok: boolean;
     status: number;
     /** Stable Clerk user id returned by a successful fresh account create. */
     userId?: string;
     existed?: boolean;
-    /** Set when an `existed` heal also refreshed the account's metadata. */
+    /** Legacy result field; signup never refreshes an existing account. */
     refreshed?: boolean;
 }
 /** Inputs for a Clerk invitation. */
@@ -3100,9 +3106,8 @@ declare function clerkInviteRequest(input: ClerkInviteInput): {
     path: string;
     body: Record<string, unknown>;
 };
-/** POST the invitation to the Clerk Backend API. A repeat invite for an
- *  already-invited email heals to `{ ok: true, existed: true }` rather than
- *  reporting a failure the caller would have to special-case. */
+/** POST a new invitation. Existing identifiers and all validation failures are
+ * rejected; invitations never authorize changes to an existing account. */
 declare function createClerkInvitation(secretKey: string, input: ClerkInviteInput, fetchImpl?: typeof fetch): Promise<ClerkResult>;
 /** Inputs for a server-side Clerk user create. */
 interface ClerkUserInput {
@@ -3113,9 +3118,8 @@ interface ClerkUserInput {
     publicMetadata?: Record<string, unknown>;
     /** Backend-only account signals and profile data. */
     privateMetadata?: Record<string, unknown>;
-    /** Optional metadata merge used only when create returns 422 for an existing
-     * account. This lets migrations remove legacy keys without putting tombstone
-     * values on a newly-created user. Defaults to the create metadata. */
+    /** @deprecated Ignored. Use an explicitly authorized metadata update for repairs;
+     * signup must never modify an account found by email. */
     repairMetadata?: ClerkMetadataInput;
 }
 /** Build the Clerk Backend API user-create request. The account is created
@@ -3137,15 +3141,13 @@ declare function updateClerkUserMetadata(secretKey: string, userId: string, inpu
 /** Look a Clerk account up by email and merge its metadata.
  *
  * Returns `false` when no matching user can be resolved or Clerk rejects the
- * lookup or update. Chapter uses this for create-healing and invitation
- * adoption so a repeated application repairs the private account snapshot.
+ * lookup or update. This is an explicit administrative repair primitive;
+ * never call it from public signup or use email knowledge as authorization.
  */
 declare function updateClerkUserMetadataByEmail(secretKey: string, email: string, input: ClerkMetadataInput, fetchImpl?: typeof fetch): Promise<boolean>;
-/** Create the applicant's Clerk account server-side. A repeat for an email that
- *  already has an account heals to `{ ok: true, existed: true }` — the account
- *  exists, which is the state apply-time provisioning wanted — and refreshes
- *  supplied public/private metadata on the existing account so a re-application
- *  repairs a previously missed create (`refreshed: true`). */
+/** Create a new passwordless account. A provider collision never patches the
+ * existing account. A retry may return its id only when backend-private metadata
+ * already names the same original application, preserving all current claims. */
 declare function createClerkUser(secretKey: string, input: ClerkUserInput, fetchImpl?: typeof fetch): Promise<ClerkResult>;
 
 /** Backend metadata field selected for all role reads and writes. */

package/dist/index.js

@@ -1,6 +1,13 @@
 // src/config.ts
 import { defineCrm } from "@odla-ai/crm";
 
+// src/schema-account-policy.ts
+var chapterAccountPolicy = { attrs: {
+  id: { type: "string", unique: true, indexed: true, optional: false },
+  metadata: { type: "string", unique: false, indexed: false, optional: false },
+  roles: { type: "json", unique: false, indexed: false, optional: false }
+} };
+
 // src/member.ts
 import { assertFieldCondition, resolveFieldStates } from "@odla-ai/crm";
 
@@ -124,8 +131,10 @@ async function submitApplication(db, chapter, fields, opts) {
   if (fields.focus !== void 0) row2.focus = clampArray(fields.focus, app.maxArrayLen);
   if (opts.groupId) row2.groupId = opts.groupId;
   if (opts.runtime) row2.stripeRuntime = opts.runtime;
+  if (chapter.account !== "none") row2.clerkAccountPending = true;
   if (typeof fields.email === "string" && isValidEmail(fields.email.trim())) {
     row2.emailNormalized = normalizeChapterEmail(fields.email);
+    row2.signupEmailKey = row2.emailNormalized;
   }
   if (opts.admissionGrant?.decision === "waive_interview") {
     row2.admissionGrantId = opts.admissionGrant.id;
@@ -149,11 +158,21 @@ async function submitApplication(db, chapter, fields, opts) {
       consumedApplicationId: id10
     } });
   }
-  const { duplicate } = await db.transact(
-    ops,
-    opts.submissionId ? { mutationId: `join:${opts.submissionId}` } : void 0
-  );
-  return { ok: true, id: id10, duplicate, status: chapter.pipeline.initial, disclaimerAckAt: acked ? opts.now : null };
+  try {
+    const { duplicate } = await db.transact(
+      ops,
+      opts.submissionId ? { mutationId: `join:${opts.submissionId}` } : void 0
+    );
+    return { ok: true, id: id10, duplicate, status: chapter.pipeline.initial, disclaimerAckAt: acked ? opts.now : null };
+  } catch (error) {
+    if (error.code === "unique_violation") return {
+      ok: false,
+      code: "account_already_exists",
+      status: 409,
+      error: "An account or application already exists for this email. Please sign in to continue."
+    };
+    throw error;
+  }
 }
 function joinConfig(group, paymentsReady2, tiers2 = [], conditions = {}) {
   return {
@@ -228,6 +247,9 @@ var applicationAttrs = {
   refundPolicyAckAt: attr("number", { optional: true }),
   prepEmailSentAt: attr("number", { optional: true }),
   canceled: attr("boolean", { optional: true }),
+  signupEmailKey: attr("string", { unique: true, indexed: true, optional: true }),
+  clerkInvitationSentAt: attr("number", { optional: true }),
+  clerkAccountPending: attr("boolean", { optional: true }),
   emailNormalized: attr("string", { indexed: true, optional: true }),
   admissionGrantId: attr("string", { unique: true, indexed: true, optional: true }),
   admissionSource: attr("string", { indexed: true, optional: true }),
@@ -900,6 +922,7 @@ function chapterDb(mode, auth, includeNetworkNotes = false, application = resolv
       entities.memberContentLocal = memberContentLocal;
     }
   }
+  if (auth.source !== "table") entities.chapterAccountPolicy = chapterAccountPolicy;
   if (auth.source === "table") entities.admins = admins;
   if (auth.superAdminSource === "table") entities.superAdmins = superAdmins;
   if (includeNetworkNotes) entities.networkNotes = networkNotes;
@@ -2979,6 +3002,12 @@ function createChapterIntegration(chapter, options = {}) {
     ...emails?.debugEmail ? { debugEmail: emails.debugEmail } : {}
   });
   const seeds = [...crmDesc.seeds ?? []];
+  if (chapter.auth.source !== "table") seeds.push({
+    id: "account-policy",
+    ns: "chapterAccountPolicy",
+    key: { attr: "id", value: chapter.id },
+    attrs: { metadata: chapter.auth.source === "clerk" ? "private" : "public", roles: [...chapter.auth.ladder] }
+  });
   const group = chapter.groupSeed();
   if (group) {
     seeds.push({ id: "group", ns: "groups", key: { attr: "id", value: chapter.id }, attrs: { ...group, createdAt: now } });
@@ -7147,8 +7176,30 @@ async function stripeCall(sk, method, path, params, idempotencyKey) {
   );
 }
 
+// src/clerk-signup.ts
+async function findSignupAccount(secret, email, fetchImpl = fetch) {
+  const response = await fetchImpl(`https://api.clerk.com/v1/users?email_address=${encodeURIComponent(normalizeChapterEmail(email))}&limit=2`, {
+    headers: { authorization: `Bearer ${secret}` },
+    redirect: "manual",
+    signal: AbortSignal.timeout(5e3)
+  });
+  if (!response.ok) throw new Error("signup account lookup unavailable");
+  const users = await response.json();
+  if (!Array.isArray(users) || users.length > 1 || users.length === 1 && (typeof users[0]?.id !== "string" || !users[0].id)) {
+    throw new Error("signup account lookup unavailable");
+  }
+  return users[0] ?? null;
+}
+function belongsToSignup(account, applicationId) {
+  return typeof applicationId === "string" && applicationId.length > 0 && account.private_metadata?.applicationId === applicationId;
+}
+
 // src/clerk.ts
-var heal = (status2) => status2 === 422 ? { ok: true, status: status2, existed: true } : { ok: false, status: status2 };
+async function rejectedCreate(res) {
+  const body = typeof res.json === "function" ? await res.json().catch(() => null) : null;
+  const existed = Array.isArray(body?.errors) && body.errors.some((error) => error?.code === "form_identifier_exists" || error?.code === "duplicate_record");
+  return { ok: false, status: res.status, ...existed ? { existed: true } : {} };
+}
 function clerkInviteRequest(input) {
   return {
     path: "/v1/invitations",
@@ -7167,7 +7218,7 @@ async function createClerkInvitation(secretKey, input, fetchImpl = fetch) {
     headers: { authorization: `Bearer ${secretKey}`, "content-type": "application/json" },
     body: JSON.stringify(body)
   });
-  return res.ok ? { ok: true, status: res.status } : heal(res.status);
+  return res.ok ? { ok: true, status: res.status } : rejectedCreate(res);
 }
 function clerkUserRequest(input) {
   return {
@@ -7219,20 +7270,10 @@ async function createClerkUser(secretKey, input, fetchImpl = fetch) {
       ...typeof body2?.id === "string" && body2.id ? { userId: body2.id } : {}
     };
   }
-  const errorBody = res.status === 400 && typeof res.json === "function" ? await res.json().catch(() => null) : null;
-  const existingIdentifier = Array.isArray(errorBody?.errors) && errorBody.errors.some((error) => error.code === "form_identifier_exists");
-  const healed = existingIdentifier ? { ok: true, status: res.status, existed: true } : heal(res.status);
-  const repair = input.repairMetadata ?? {
-    ...input.publicMetadata !== void 0 ? { publicMetadata: input.publicMetadata } : {},
-    ...input.privateMetadata !== void 0 ? { privateMetadata: input.privateMetadata } : {}
-  };
-  if (!healed.existed || repair.publicMetadata === void 0 && repair.privateMetadata === void 0) return healed;
-  const userId = await existingClerkUserId(secretKey, input.email, fetchImpl).catch(() => null);
-  const refreshed = userId ? await updateClerkUserMetadata(secretKey, userId, {
-    ...repair.publicMetadata !== void 0 ? { publicMetadata: repair.publicMetadata } : {},
-    ...repair.privateMetadata !== void 0 ? { privateMetadata: repair.privateMetadata } : {}
-  }, fetchImpl).catch(() => false) : false;
-  return { ...healed, refreshed, ...refreshed && userId ? { userId } : {} };
+  const failure = await rejectedCreate(res);
+  if (!failure.existed) return failure;
+  const account = await findSignupAccount(secretKey, input.email, fetchImpl).catch(() => null);
+  return account && belongsToSignup(account, input.privateMetadata?.applicationId) ? { ok: true, status: res.status, existed: true, userId: account.id } : failure;
 }
 
 // src/clerk-roles.ts