test(dogfood),spec,changeset: name the two derived surfaces the update grant moves (#15873 contract-review patch round)

Review FAIL was on the accept-set statement, not the code: granting `update`
also derives the update-mode import door (API_METHOD_DERIVATION: import =
any of create/update) and flips /auth/me/permissions for sys_organization
(allowEdit true, apiOperations gains update and import). Both named in the
changeset; pinned on the real door in the dogfood file (import: 200, timezone
lands, name stripped; better-auth-only row refused per row; insert mode 405
naming create; /me/permissions allowEdit true with update+import and a
sibling better-auth table as the clamp control); the SINGLE_RECORD_WRITE_ONLY
sentence now says what is true (bulk not granted; the derived import door
is, column-clamped per row).

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ADLdAs2pVcH17h9tZKWMBg

Author: claude

.changeset/organization-update-door.md

@@ -6,7 +6,11 @@
 
 The organization table carries four platform-owned columns better-auth never reads or writes — `require_mfa` (ADR-0069 D3), `parent_organization_id` and `sort_order` (ADR-0105 D6), `timezone` (#14238). plugin-auth declares them generically editable (`MANAGED_EXTENSION_EDITABLE_FIELDS.sys_organization`, the guard's per-object update whitelist), while the object's `enable.apiMethods: ['get', 'list']` answered every `PATCH /api/v1/data/sys_organization/:id` with 405 `OBJECT_API_METHOD_NOT_ALLOWED` before the engine — and the guard — was reached. Declared editable, reachable from no product surface: the columns could be set only by a system-context caller. The ruling answers the card's question — yes, an administrator sets these columns through the product — and refuses the alternative of declaring them system-writable only.
 
-What widens (Clause ②): the accept set of the published door. `enable.apiMethods` becomes `['get', 'list', 'update']`, and `userActions: { edit: true }` declares the affordance ADR-0103 D3's `reconcileManagedApiMethods` requires before it lets a `managedBy` object keep a write verb at registration (without it the verb is stripped with a warning and the door keeps answering 405 — the second silent gate #7727 measured on `sys_api_key`). `update` alone: `create` / `delete` still answer 405, and `bulk` is not granted (recorded in `SINGLE_RECORD_WRITE_ONLY`).
+What widens (Clause ②) — three published surfaces move, all column-clamped by the same guard:
+
+1. The data door's accept set. `enable.apiMethods` becomes `['get', 'list', 'update']`, and `userActions: { edit: true }` declares the affordance ADR-0103 D3's `reconcileManagedApiMethods` requires before it lets a `managedBy` object keep a write verb at registration (without it the verb is stripped with a warning and the door keeps answering 405 — the second silent gate #7727 measured on `sys_api_key`). `PATCH /api/v1/data/sys_organization/:id` is admitted; `create` / `delete` still answer 405; `bulk` (`/batch`, the `*Many` routes) is not granted (recorded in `SINGLE_RECORD_WRITE_ONLY`).
+2. The derived `import` door. `API_METHOD_DERIVATION` (`@objectstack/spec` `api-derivation.ts`) derives `import` from `any: ['create', 'update']`, so granting `update` admits `POST /api/v1/data/sys_organization/import` (and the async `/import/jobs` route) in `writeMode: 'update'` — one request updates N rows, each row clamped per row by the ADR-0092 D2 guard under the caller's context (a row carrying only better-auth columns is refused `PERMISSION_DENIED`; `treatAsHistorical` does not elevate). Insert-mode and upsert-mode import stay 405 (the conjunct named is `create`). The door's own 405 envelope advertises the derived set in `allowed`.
+3. `/auth/me/permissions`. For a principal the permission layer already admits (the seeded platform admin's `admin_full_access` wildcard), `sys_organization.allowEdit` goes `false → true` (`clampManagedObjectWrites` reads `userActions.edit` for the `better-auth` bucket) and `apiOperations` gains `update` and `import` (`annotateEffectiveApiOperations`) — the payload the console renders its edit affordance from. `organization_admin` / `member_default` stay hard-denied on every better-auth table by `managed-object-write-denies.ts`, unchanged.
 
 What does not widen: the column set. The guard clamps every user-context update on this table to the whitelist. A PATCH of a better-auth column sent alone (`name`, `slug`, `logo`, `metadata`) is now refused by the guard's own verdict — 403 `PERMISSION_DENIED` — instead of the method gate's 405; sent beside a whitelisted column it is stripped and the whitelisted column lands. better-auth's own columns keep changing through better-auth's `organization/update` (the `update_organization` row action, unchanged). Per ADR-0092 D4's form-rendering constraint the four better-auth columns are now `readonly: true` on the object, so a standard edit form offers exactly what the guard admits; the engine's static-readonly strip exempts system-context writers, so better-auth's adapter is unaffected.
 

packages/qa/dogfood/test/organization-update-door.dogfood.test.ts

@@ -40,6 +40,33 @@
  *
  * Refusal cases assert `code` AND `status` (ADR-0112): a status-only assertion
  * stays green against an implementation that answers the wrong refusal.
+ *
+ * ## Two more published surfaces move with the verb, and are pinned here too
+ *
+ * The contract review of PR #16687 measured what the first round did not name:
+ *
+ *  - the DERIVED `import` door. `API_METHOD_DERIVATION` (`@objectstack/spec`,
+ *    `api-derivation.ts`) derives `import` from `any: ['create', 'update']`, so
+ *    granting `update` admits `POST /data/sys_organization/import` in
+ *    `writeMode: 'update'` — one request updates N rows. It is column-safe for
+ *    the same reason the PATCH is: the import runner writes each row under the
+ *    caller's context, so the D2 guard clamps every row (`timezone` lands,
+ *    `name` is stripped; a row carrying only better-auth columns is refused
+ *    per row; `treatAsHistorical` does not elevate). Insert / upsert modes
+ *    stay 405, and the conjunct the envelope names is `create`;
+ *  - `/auth/me/permissions`, the payload the console renders its edit
+ *    affordance from: `clampManagedObjectWrites` reads `userActions.edit` for
+ *    the `better-auth` bucket and `annotateEffectiveApiOperations` reports the
+ *    effective operation set, so for a principal the permission layer already
+ *    admits, `sys_organization.allowEdit` goes false → true and
+ *    `apiOperations` gains `update` and `import`.
+ *
+ * ⚠️ Instrument note for anything `reconcileManagedApiMethods` touches: it runs
+ * at REGISTRATION, not at build, so a property-read of `dist/` cannot see it —
+ * with `userActions` removed, `dist` still says `["get","list","update"]` while
+ * the registered schema says `["get","list"]`. The registered-schema pin at the
+ * bottom of this file, and the `/me/permissions` pin, are the instruments that
+ * can.
  */
 
 import { describe, it, expect, beforeAll, afterAll } from 'vitest';
@@ -191,6 +218,106 @@ describe('#15873: sys_organization platform-owned columns through PATCH /data/sy
     expect(deletedBody.code).toBe('OBJECT_API_METHOD_NOT_ALLOWED');
   });
 
+  it('the payload the console consumes: /auth/me/permissions says sys_organization is editable, with update and import in apiOperations', async () => {
+    const res = await stack.apiAs(token, 'GET', '/auth/me/permissions');
+    expect(res.status).toBe(200);
+    const body: any = await res.json();
+    const entry = body.objects?.sys_organization;
+    expect(entry, 'sys_organization entry present in /me/permissions').toBeTruthy();
+
+    // `clampManagedObjectWrites` — the `better-auth` bucket is clamped to its
+    // `userActions`; `edit` is the one opened, `create` / `delete` stay off.
+    expect(entry.allowEdit).toBe(true);
+    expect(entry.allowCreate).toBe(false);
+    expect(entry.allowDelete).toBe(false);
+
+    // `annotateEffectiveApiOperations` — the effective set the console renders:
+    // the ruled verb and the door it derives, never the ones not granted.
+    expect(entry.apiOperations).toContain('update');
+    expect(entry.apiOperations).toContain('import');
+    expect(entry.apiOperations).not.toContain('create');
+    expect(entry.apiOperations).not.toContain('delete');
+    expect(entry.apiOperations).not.toContain('bulk');
+
+    // Control: the clamp is live, not a wildcard fold reporting everything
+    // editable — a sibling better-auth table with no `userActions` stays
+    // `allowEdit: false` for the very same principal.
+    const control = body.objects?.sys_member;
+    expect(control, 'sys_member entry present (control)').toBeTruthy();
+    expect(control.allowEdit).toBe(false);
+    expect(control.apiOperations ?? []).not.toContain('update');
+  });
+
+  it('the derived import door is open in update mode, and the guard clamps every row: timezone lands, name is stripped', async () => {
+    const before = await readOrg(orgId);
+
+    const res = await stack.apiAs(token, 'POST', '/data/sys_organization/import', {
+      format: 'json',
+      writeMode: 'update',
+      matchFields: ['id'],
+      rows: [{ id: orgId, name: 'Imported Name', timezone: 'Asia/Tokyo' }],
+    });
+    expect(res.status).toBe(200);
+    const body: any = await res.json();
+    expect(body.writeMode).toBe('update');
+    expect(body.updated).toBe(1);
+    expect(body.errors).toBe(0);
+
+    const after = await readOrg(orgId);
+    // The door is open: the whitelisted column landed through import…
+    expect(after.timezone).toBe('Asia/Tokyo');
+    // …and the row was written under the caller's context, not as system:
+    // `name` did not land. Measured (ablation, contract-review patch round):
+    // with `name` added to the guard's whitelist this assertion STAYS green,
+    // because `name` is `readonly` (ADR-0092 D4) and the engine's
+    // static-readonly strip — after the guard, non-system callers only — holds
+    // it too. Two layers, one observable. The guard-SPECIFIC control on the
+    // import path is the next pin (a better-auth-only row is refused per row):
+    // under the same cut it goes red. What THIS assertion fails on is the
+    // runner elevating rows to system context, which exempts both layers.
+    expect(after.name).toBe(before.name);
+    expect(after.name).not.toBe('Imported Name');
+  });
+
+  it('import: a row carrying only better-auth columns is refused per row, PERMISSION_DENIED — treatAsHistorical does not elevate', async () => {
+    const before = await readOrg(orgId);
+    const res = await stack.apiAs(token, 'POST', '/data/sys_organization/import', {
+      format: 'json',
+      writeMode: 'update',
+      matchFields: ['id'],
+      treatAsHistorical: true,
+      rows: [{ id: orgId, name: 'Imported Name 2' }],
+    });
+    // The import route's contract is a per-row outcome report: the request is
+    // answered 200 and the refusal lives on the row. This is the guard's own
+    // verdict on the import path (measured red the moment the whitelist admits
+    // `name`), the same way the name-only PATCH pin above is on the PATCH path.
+    expect(res.status).toBe(200);
+    const body: any = await res.json();
+    expect(body.updated).toBe(0);
+    expect(body.results?.[0]?.ok).toBe(false);
+    expect(body.results?.[0]?.code).toBe('PERMISSION_DENIED');
+    expect((await readOrg(orgId)).name).toBe(before.name);
+  });
+
+  it('import: insert mode is still refused at the method gate — 405, and the conjunct named is create', async () => {
+    const res = await stack.apiAs(token, 'POST', '/data/sys_organization/import', {
+      format: 'json',
+      writeMode: 'insert',
+      rows: [{ name: 'Forged Via Import', slug: 'forged-via-import' }],
+    });
+    expect(res.status).toBe(405);
+    const body: any = await res.json();
+    expect(body.code).toBe('OBJECT_API_METHOD_NOT_ALLOWED');
+    // `deniedConjunctName` names the primitive that actually failed: import
+    // in insert mode needs `create`, which stays off.
+    expect(String(body.error)).toContain("'create'");
+    // …and the same envelope advertises the derived door the ruling opened.
+    expect(body.allowed).toContain('update');
+    expect(body.allowed).toContain('import');
+    expect(body.allowed).not.toContain('create');
+  });
+
   it('the REGISTERED schema serves `update` (post-reconcile) and better-auth keeps its own door', async () => {
     // The original defect was a DECLARATION disagreeing with the runtime, so
     // pin what the runtime actually serves. `reconcileManagedApiMethods`

packages/spec/src/data/api-methods-batch-conformance.test.ts

@@ -113,11 +113,18 @@ const SINGLE_RECORD_WRITE_ONLY: Record<string, string> = {
   // verbatim 「同意」): the data door admits `update` so an administrator can set
   // the four platform-owned columns (`require_mfa`, `parent_organization_id`,
   // `sort_order`, `timezone`) the ADR-0092 D2 whitelist already admitted on
-  // the engine path. The ruling widened ONE verb on an identity table, and
+  // the engine path. The ruling named ONE verb on an identity table, and
   // `bulk` is a second widening it did not take: granting it would open
   // `POST /data/sys_organization/batch` and the `*Many` routes to every API
-  // client. The object's one list view (`all_orgs`) declares no `bulkActions`
-  // / selection, and the implicit bulk-delete entry gates on the `delete`
+  // client. What `update` DOES derive is admitted, and named: `import` is
+  // `any: ['create', 'update']` in `API_METHOD_DERIVATION`, so update-mode
+  // `POST /data/sys_organization/import` now passes the method gate and
+  // updates N rows in one request — each row clamped to the D2 whitelist under
+  // the caller's context, insert/upsert modes still 405. That is not the batch
+  // shape this ledger is about (`bulk` gates `/batch` and `*Many`, `import`
+  // does not read it), which is why the exemption stands beside it. The
+  // object's one list view (`all_orgs`) declares no `bulkActions` /
+  // selection, and the implicit bulk-delete entry gates on the `delete`
   // affordance — off three times over (`managedBy: 'better-auth'` denies by
   // default, `userActions` opens `edit` alone, `delete` is not in
   // `apiMethods`) — so there is no multi-select to batch today. The cost the
@@ -128,12 +135,13 @@ const SINGLE_RECORD_WRITE_ONLY: Record<string, string> = {
   // this entry and add `'bulk'`; the stale-entry test below refuses to let
   // both stand.
   sys_organization:
-    'Administrators set the platform-owned columns one organization at a time ' +
-    '(#15873 ruled `update` alone, column-gated by ADR-0092 D2). No console ' +
-    'surface multi-selects organizations — the list view declares no bulk ' +
-    'actions and the object grants no delete affordance — and a promoted bulk ' +
-    'edit would fan out per row through the action runner rather than hitting ' +
-    '/batch (#7802).',
+    'Administrators set the platform-owned columns through single-record PATCH ' +
+    'and the derived update-mode import door (#15873 ruled `update`; both are ' +
+    'column-clamped per row by ADR-0092 D2). `bulk` — /batch and the *Many ' +
+    'routes — is not granted: no console surface multi-selects organizations ' +
+    '(the list view declares no bulk actions and the object grants no delete ' +
+    'affordance), and a promoted bulk edit would fan out per row through the ' +
+    'action runner rather than hitting /batch (#7802).',
 };
 
 /** Every `*.object.ts` under `packages/`, skipping build output and deps. */