@odla-ai/chapter 0.40.1 → 0.40.3

package/dist/index.d.cts

@@ -1213,6 +1213,9 @@ interface BuilderLibraryValidationOptions {
     sourceType?: BuilderLibrarySourceType;
     sourceAppId?: string;
     targetAppId?: string;
+    /** Chapter IDs a Built Not Found document may address. An empty or omitted
+     * allowlist keeps the historical global-or-private-only behavior. */
+    allowedChapterIds?: readonly string[];
 }
 /** A validated document or actionable strict-contract errors. */
 type BuilderLibraryValidationResult = {
@@ -1260,7 +1263,8 @@ interface BuilderLibraryReceipt {
 declare function canViewBuilderLibraryResource(resource: BuilderLibraryResource, viewer: BuilderLibraryViewer): boolean;
 /** Produce deterministic, published-only input for a site-building agent. */
 declare function buildBuilderLibraryManifest(documents: readonly BuilderLibraryDocument[], viewer: BuilderLibraryViewer, generatedAt?: number, limit?: number): BuilderLibraryManifest;
-/** Build the exact signed layer for one peer; BNF-only material never crosses to a Chapter. */
+/** Build the exact signed layer for one peer; private and sibling material
+ * never crosses to a Chapter. */
 declare function projectBuilderLibraryDelivery(document: BuilderLibraryDocument, target: BuilderLibraryTarget): BuilderLibraryDocument;
 /** Copy a Chapter item into global authority while preserving its exact origin. */
 declare function promoteBuilderLibraryResource(input: {
@@ -2103,6 +2107,8 @@ declare function stripeCall(sk: string, method: "GET" | "POST" | "DELETE", path:
 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. */
     refreshed?: boolean;
@@ -2221,14 +2227,16 @@ interface IntegrationSetting {
 /**
  * A secret the capability needs, held in the tenant vault.
  *
- * Structurally the odla CLI's `IntegrationSecret`: `name` is the vault name
- * byte-for-byte, so `odla-ai doctor`, `odla-ai secrets status`, and the
+ * Structurally the odla CLI's `IntegrationSecret`: `name` is the effective
+ * runtime vault name, so `odla-ai doctor`, `odla-ai secrets status`, and the
  * repo's `check:secrets` gate can hold this declaration against the name the
- * platform actually reads. `mode` is chapter's own addition and the CLI
- * ignores it.
+ * package requests. The Clerk backend key is stored once in the reserved
+ * `$clerk_secret` slot and odla-db resolves its released `clerk_secret_key`
+ * compatibility name. `mode` is chapter's own addition and the CLI ignores it.
  */
 interface IntegrationSecret {
-    /** Vault name, exactly as `odla-ai secrets set <name>` writes it. */
+    /** Effective runtime vault name. Dedicated platform commands may keep the
+     * canonical value in a reserved slot and resolve this compatibility name. */
     name: string;
     description: string;
     pattern?: string;

package/dist/index.d.ts

@@ -1213,6 +1213,9 @@ interface BuilderLibraryValidationOptions {
     sourceType?: BuilderLibrarySourceType;
     sourceAppId?: string;
     targetAppId?: string;
+    /** Chapter IDs a Built Not Found document may address. An empty or omitted
+     * allowlist keeps the historical global-or-private-only behavior. */
+    allowedChapterIds?: readonly string[];
 }
 /** A validated document or actionable strict-contract errors. */
 type BuilderLibraryValidationResult = {
@@ -1260,7 +1263,8 @@ interface BuilderLibraryReceipt {
 declare function canViewBuilderLibraryResource(resource: BuilderLibraryResource, viewer: BuilderLibraryViewer): boolean;
 /** Produce deterministic, published-only input for a site-building agent. */
 declare function buildBuilderLibraryManifest(documents: readonly BuilderLibraryDocument[], viewer: BuilderLibraryViewer, generatedAt?: number, limit?: number): BuilderLibraryManifest;
-/** Build the exact signed layer for one peer; BNF-only material never crosses to a Chapter. */
+/** Build the exact signed layer for one peer; private and sibling material
+ * never crosses to a Chapter. */
 declare function projectBuilderLibraryDelivery(document: BuilderLibraryDocument, target: BuilderLibraryTarget): BuilderLibraryDocument;
 /** Copy a Chapter item into global authority while preserving its exact origin. */
 declare function promoteBuilderLibraryResource(input: {
@@ -2103,6 +2107,8 @@ declare function stripeCall(sk: string, method: "GET" | "POST" | "DELETE", path:
 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. */
     refreshed?: boolean;
@@ -2221,14 +2227,16 @@ interface IntegrationSetting {
 /**
  * A secret the capability needs, held in the tenant vault.
  *
- * Structurally the odla CLI's `IntegrationSecret`: `name` is the vault name
- * byte-for-byte, so `odla-ai doctor`, `odla-ai secrets status`, and the
+ * Structurally the odla CLI's `IntegrationSecret`: `name` is the effective
+ * runtime vault name, so `odla-ai doctor`, `odla-ai secrets status`, and the
  * repo's `check:secrets` gate can hold this declaration against the name the
- * platform actually reads. `mode` is chapter's own addition and the CLI
- * ignores it.
+ * package requests. The Clerk backend key is stored once in the reserved
+ * `$clerk_secret` slot and odla-db resolves its released `clerk_secret_key`
+ * compatibility name. `mode` is chapter's own addition and the CLI ignores it.
  */
 interface IntegrationSecret {
-    /** Vault name, exactly as `odla-ai secrets set <name>` writes it. */
+    /** Effective runtime vault name. Dedicated platform commands may keep the
+     * canonical value in a reserved slot and resolve this compatibility name. */
     name: string;
     description: string;
     pattern?: string;

package/dist/index.js

@@ -1955,7 +1955,14 @@ function createChapterIntegration(chapter, options = {}) {
     },
     rules: { ...crmDesc.rules, ...chapter.rules },
     seeds,
-    secrets: [],
+    secrets: chapter.account === "none" ? [] : [{
+      // Released Chapter workers request this effective name. odla-db maps
+      // it to the canonical reserved `$clerk_secret` value written by
+      // `odla-ai secrets set-clerk-key`.
+      name: "clerk_secret_key",
+      description: "Clerk backend key (set with odla-ai secrets set-clerk-key) required by the configured Chapter account model.",
+      required: true
+    }],
     probes: [
       ...crmDesc.probes ?? [],
       // The snapshot route is deliberately private. A credential-free smoke
@@ -2455,8 +2462,8 @@ function validateBuilderLibraryDocument(value, options = {}) {
     if (sourceType === "chapter" && (resource.scope.kind !== "chapter" || resource.scope.chapterId !== sourceAppId)) {
       errors.push(`document.resources.${resource.id}: Chapter sources may author only their own chapter scope`);
     }
-    if (sourceType === "built_not_found" && resource.scope.kind === "chapter") {
-      errors.push(`document.resources.${resource.id}: Built Not Found sources may author only built_not_found or global scope`);
+    if (sourceType === "built_not_found" && resource.scope.kind === "chapter" && !(options.allowedChapterIds ?? []).includes(resource.scope.chapterId)) {
+      errors.push(`document.resources.${resource.id}: Built Not Found may target only configured Chapters`);
     }
   }
   if (errors.length) return { ok: false, errors };
@@ -2488,7 +2495,7 @@ function projectBuilderLibraryDelivery(document, target) {
   return {
     ...document,
     target,
-    resources: document.source.type === "built_not_found" ? document.resources.filter((resource) => resource.scope.kind === "global") : document.resources
+    resources: document.source.type === "built_not_found" ? document.resources.filter((resource) => resource.scope.kind === "global" || resource.scope.kind === "chapter" && resource.scope.chapterId === target.appId) : document.resources
   };
 }
 function promoteBuilderLibraryResource(input) {
@@ -3465,7 +3472,14 @@ async function createClerkUser(secretKey, input, fetchImpl = fetch) {
     headers: { authorization: `Bearer ${secretKey}`, "content-type": "application/json" },
     body: JSON.stringify(body)
   });
-  if (res.ok) return { ok: true, status: res.status };
+  if (res.ok) {
+    const body2 = typeof res.json === "function" ? await res.json().catch(() => null) : null;
+    return {
+      ok: true,
+      status: res.status,
+      ...typeof body2?.id === "string" && body2.id ? { userId: body2.id } : {}
+    };
+  }
   const healed = heal(res.status);
   const repair = input.repairMetadata ?? {
     ...input.publicMetadata !== void 0 ? { publicMetadata: input.publicMetadata } : {},
@@ -3567,7 +3581,7 @@ var clerkIntegration = {
     },
     {
       name: "clerk_secret_key",
-      description: "Clerk backend key (sk_*) \u2014 powers account creation, the public role claim, and backend-only private profile signals; it also lets odla-db resolve user email/name via the Clerk API.",
+      description: "Effective Clerk backend key (sk_*), stored canonically by set-clerk-key in reserved $clerk_secret \u2014 powers account creation, the public role claim, backend-only private profile signals, and odla-db user resolution.",
       pattern: "sk_",
       mode: "full",
       required: false
@@ -3600,15 +3614,16 @@ var clerkIntegration = {
   provision: {
     human: [
       "Run `npx clerk auth login` \u2014 the one interactive step; the agent then creates + configures the Clerk app with the Clerk CLI (no pk_ to hand-paste).",
-      'For auth mode "full": create the Clerk user-sync webhook and store its whsec_, plus the sk_ as clerk_secret_key, in the tenant vault (Studio, write-only).'
+      'For auth mode "full": create the Clerk user-sync webhook, store its whsec_, and transfer the sk_ with `odla-ai secrets set-clerk-key --env <env> --stdin` (write-only).'
     ],
     cli: [
       "Clerk CLI (`npx clerk apps create/link/config patch`) creates + configures the instance and pulls the pk_.",
-      "odla `provision` records it: setAuth(env, publishableKey) -> apps-registry (issuer/JWKS derived from the key)."
+      "odla `provision` records it: setAuth(env, publishableKey) -> apps-registry (issuer/JWKS derived from the key).",
+      "odla `secrets set-clerk-key` stores one environment-scoped reserved credential consumed by odla-db and Chapter."
     ],
     doctor: [
       "registry auth[env] present when the app mounts <SignIn>?",
-      'auth mode "full" => whsec_ and clerk_secret_key present in the tenant vault?'
+      'auth mode "full" => whsec_ present and the effective clerk_secret_key reports set via the reserved Clerk credential status?'
     ]
   }
 };