@odla-ai/chapter 0.42.0 → 0.42.1

package/README.md

@@ -888,6 +888,10 @@ export const chapter = defineChapter({
       },
       // Separate write consent: browsing never implies note permission.
       sharedNotes: ["person"],
+      // Separate again: name the exact profile fields and record types the
+      // parent may mutate. Omission keeps the edge read-only.
+      editableFields: { person: ["name", "email", "phone", "linkedin"] },
+      stageTransitions: ["person"],
     }],
   },
 });
@@ -896,14 +900,24 @@ export const chapter = defineChapter({
 `GET /api/network/records` requires the edge HMAC and rejects signed senders not
 listed in `network.readers`. Results are capped at 50 records, offset-paged,
 search-bounded, and projected to the reader's field list. Pipeline stage and
-record timestamps are the only metadata outside that list; application
+record timestamps, optimistic `revision`, and explicitly delegated edit
+metadata are the only metadata outside that list; application
 narrative, billing, account state, activities, and notes do not cross unless
 the follower explicitly names a corresponding CRM field.
 
 The leader's authenticated `GET /api/admin/network/records` proxy signs the
 follower request server-to-server, so neither the browser session nor the
-vaulted edge secret crosses sites. The Network detail view has two deliberate
-lanes:
+vaulted edge secret crosses sites. When both halves of an edge opt in,
+`PATCH /api/admin/network/records` accepts one bounded field patch or lifecycle
+destination with the follower-authored `expectedRevision`, current stage, and a
+stable mutation id. The follower revalidates its CRM schema, identity/email
+rules, pipeline gates, and atomic revision guard; it remains source of truth and
+records the leader peer plus initiating admin in the CRM activity audit. A
+retry with the same input is idempotent, while stale state is `409`, an
+undelegated operation is `403`, invalid fields or transitions are `422`, and
+ordinary browse-only edges remain read-only.
+
+The Network detail view also has two deliberate note lanes:
 
 - `GET/POST /api/admin/network/notes` stores private annotations in the
   leader's deny-all `networkNotes` namespace. They are keyed to the follower's
@@ -935,6 +949,8 @@ export const chapter = defineChapter({
         company: ["name", "domain", "industry", "location", "linkedin"],
       },
       sharedNotes: ["person"],
+      editableFields: { person: ["name", "email", "phone", "linkedin"] },
+      stageTransitions: ["person"],
     }],
   },
 });
@@ -945,7 +961,7 @@ Treat the network as websites connected by explicit delivery edges:
 - each website is a node with its own `appId`, ODLA tenants/keys, CRM config,
   Clerk application, publishable keys, issuer, roles, and local users;
 - each `network.targets[]` entry is a directed edge from one leader to one
-  follower: `{ id, name, url, binding?, secretName?, fields }`;
+  follower: `{ id, name, url, binding?, secretName?, fields, editableFields?, stageTransitions? }`;
 - the payload is a versioned, allowlisted business record
   `{ version: 2, source: { siteId, recordId }, type, input }`, never an
   identity-provider session, another site's pipeline/account/billing state, or

package/dist/{copy-context-DuJkH4U9.d.ts → copy-context-BNUzbL5g.d.ts}

@@ -186,6 +186,13 @@ interface ChapterNetworkTarget {
      * 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[];
 }
 /** One signed peer allowed to browse a privacy-bounded projection of this
  * site's CRM. The follower owns this allowlist; a leader target declaration
@@ -200,6 +207,13 @@ interface ChapterNetworkReader {
      * 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[];
 }
 /** Leader/follower network configuration. A follower needs no code config to
  * receive pushed records. It must explicitly declare `readers` before any peer
@@ -242,12 +256,16 @@ interface ResolvedNetworkTarget {
     secretName: string;
     fields?: Record<string, readonly string[]>;
     sharedNotes: readonly string[];
+    editableFields: Record<string, readonly string[]>;
+    stageTransitions: readonly string[];
 }
 /** 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[];
 }
 /** Fully-resolved leader network configuration. */
 interface ResolvedNetwork {

package/dist/index.cjs

@@ -1553,6 +1553,12 @@ function formationFields(crm, formation) {
   return resolveFormationFlowFields(crm, formation);
 }
 
+// src/network-contract.ts
+var DEFAULT_SHARE_FIELDS = {
+  person: ["name", "email", "firstName", "lastName", "phone", "linkedin"],
+  company: ["name", "domain", "industry", "location", "linkedin", "notes"]
+};
+
 // src/config-network.ts
 var SLUG = /^[a-z0-9][a-z0-9-]{1,62}$/;
 var FIELD = /^[a-z][a-zA-Z0-9_]*$/;
@@ -1564,6 +1570,27 @@ function validateSharedNotes(opts) {
     throw new Error(`${opts.path}: must contain unique CRM types allowed by fields`);
   }
 }
+function validateEditableFields(opts) {
+  for (const [type, names] of Object.entries(opts.values)) {
+    const readable = opts.readable?.[type];
+    const def = opts.crm.config.types[type];
+    const duplicate = names.some((name, index) => names.indexOf(name) !== index);
+    const unknown = names.some((name) => !FIELD.test(name) || !def?.fields[name]);
+    const hidden = opts.readable ? !readable || names.some((name) => !readable.includes(name)) : false;
+    if (!FIELD.test(type) || names.length === 0 || duplicate || !def || unknown || hidden) {
+      throw new Error(
+        `${opts.path}.${type}: must contain unique, readable fields declared on CRM type "${type}"`
+      );
+    }
+  }
+}
+function validateStageTransitions(opts) {
+  const duplicate = opts.values.some((type, index) => opts.values.indexOf(type) !== index);
+  const invalid = opts.values.some((type) => !FIELD.test(type) || !opts.crm.config.types[type]?.pipeline || (opts.readable ? !opts.readable[type] : false));
+  if (duplicate || invalid) {
+    throw new Error(`${opts.path}: must contain unique, readable CRM types with pipelines`);
+  }
+}
 function resolveNetwork(config, crm) {
   const seen = /* @__PURE__ */ new Set();
   const targets = [];
@@ -1622,6 +1649,21 @@ function resolveNetwork(config, crm) {
       crm,
       fields
     });
+    const readableFields = fields ?? DEFAULT_SHARE_FIELDS;
+    const editableFields = target.editableFields ?? {};
+    validateEditableFields({
+      path: `defineChapter.network.targets.${target.id}.editableFields`,
+      values: editableFields,
+      crm,
+      readable: readableFields
+    });
+    const stageTransitions = target.stageTransitions ?? [];
+    validateStageTransitions({
+      path: `defineChapter.network.targets.${target.id}.stageTransitions`,
+      values: stageTransitions,
+      crm,
+      readable: readableFields
+    });
     targets.push({
       id: target.id,
       name: target.name?.trim() || target.id,
@@ -1629,7 +1671,9 @@ function resolveNetwork(config, crm) {
       ...binding ? { binding } : {},
       secretName,
       ...fields ? { fields } : {},
-      sharedNotes
+      sharedNotes,
+      editableFields,
+      stageTransitions
     });
   }
   const readerIds = /* @__PURE__ */ new Set();
@@ -1676,7 +1720,21 @@ function resolveNetwork(config, crm) {
       crm,
       fields: reader.fields
     });
-    readers.push({ id: reader.id, fields: reader.fields, sharedNotes });
+    const editableFields = reader.editableFields ?? {};
+    validateEditableFields({
+      path: `defineChapter.network.readers.${reader.id}.editableFields`,
+      values: editableFields,
+      crm,
+      readable: reader.fields
+    });
+    const stageTransitions = reader.stageTransitions ?? [];
+    validateStageTransitions({
+      path: `defineChapter.network.readers.${reader.id}.stageTransitions`,
+      values: stageTransitions,
+      crm,
+      readable: reader.fields
+    });
+    readers.push({ id: reader.id, fields: reader.fields, sharedNotes, editableFields, stageTransitions });
   }
   return { targets, readers };
 }
@@ -3254,14 +3312,6 @@ function findGiftOffer(catalog, offerId, now) {
 
 // src/network.ts
 var import_crm5 = require("@odla-ai/crm");
-
-// src/network-contract.ts
-var DEFAULT_SHARE_FIELDS = {
-  person: ["name", "email", "firstName", "lastName", "phone", "linkedin"],
-  company: ["name", "domain", "industry", "location", "linkedin", "notes"]
-};
-
-// src/network.ts
 function sharedPersonInput(person) {
   const email = person.email.toLowerCase();
   const fullName = [person.firstName, person.lastName].filter(Boolean).join(" ").trim();