wip(plugin-security): defer a transfer's record verdict as its door does, as an update; changeset

Claude-Session: https://claude.ai/code/session_011TdZ8GjixNZFLz1xJD9zzK
Co-authored-by: Claude <noreply@anthropic.com>

Author: claude

.changeset/24647-explain-authored-row-write.md

@@ -0,0 +1,11 @@
+---
+'@objectstack/plugin-security': patch
+---
+
+fix(plugin-security): `security/explain`'s record-grained `update` and `delete` verdicts compose the by-id write gate's authored-row-write deferral, so a row an app-authored row-level write policy admits is reported writable, as its `PATCH` / `DELETE` answers
+
+Clause-②: no (no accept set or public surface moves: enforcement is unchanged, and explain's record verdict now gives the answer the by-id write already gives)
+
+- **What was wrong.** The sharing middleware's by-id write gate does not stop at record sharing's refusal: it asks the security service whether an app-authored row-level policy admits the row for that verb (`checkAuthoredRowWrite`), and on `admit` hands the row to the pre-image gate, which admits it. Explain's record-grained write verdict asked record sharing's per-record gate alone, so on a private object, for a row owned by someone else that only such a policy lets the caller write, the `PATCH` / `DELETE` landed while explain answered `record.visible: false`, decided by `sharing`.
+- **What explain answers now.** The same deferral, on the same condition: only when the per-record update or delete gate refuses the row, asked through the sharing service's own probe with the context that gate is asked with. Only the literal `admit` lifts the refusal; `abstain`, any other answer and a failed probe leave it standing. The record verdict is then `visible: true`, `decidedBy: 'rls'`, the layer that last admitted the row; the `sharing` layer still reports `excluded`, and its detail names the deferral. A sharing service without the probe defers nothing, as before.
+- **What does not move.** No enforcement answer changes. The `sys_attachment` and `sys_comment` parent gates ask record sharing first and refuse on its `deny` without asking explain, so a row this deferral admits is still refused there at the record-sharing step.

packages/plugins/plugin-security/src/explain-enforce-parity.test.ts

@@ -1010,7 +1010,8 @@ const TABLE: Row[] = [
     })),
   },
   {
-    card: '#24647 probe', shape: 'private OWD, the same writer, a row owned by someone else the policy admits, transfer',
+    // A transfer's door is the by-id update of `owner_id`, deferred as an update.
+    card: '#24647', shape: 'private OWD, an `own` writer holding the transfer grant whose authored update policy admits a row owned by someone else, transfer',
     position: 'record.visible',
     enforced: 'admitted',
     run: withSharing({ authored: true }, async (r) => ({

packages/plugins/plugin-security/src/explain-engine.ts

@@ -393,7 +393,9 @@ export interface ExplainEngineDeps {
    *
    * Asked on the same condition here: for a by-id `update` or `delete` whose
    * gate above ({@link canEditRecord} / {@link canDeleteRecord}) answered
-   * `false`, with that gate's verb and the context being EXPLAINED. Every
+   * `false`, with that gate's verb and the context being EXPLAINED, and for a
+   * `transfer` as an `update` (its door is the by-id update of `owner_id`,
+   * which the update gate judges). Every
    * other answer leaves the refusal standing, and so does a rejection: the
    * door's probe catches its own failure and keeps its refusal, so a failing
    * probe is not a failing request and is not reported as one.
@@ -1592,9 +1594,13 @@ async function applyRecordAttribution(
   // pre-image gate (the `rls` layer below). Asked on that condition alone, so
   // a row the gate admits, abstains on or faulted on is explained as before;
   // every answer but `admit`, and a rejection, keeps the refusal, as at the door.
-  const authoredRowWriteAdmits = canEdit === false && (engineOp === 'update' || engineOp === 'delete')
-    && deps.probeAuthoredRowWrite
-    ? (await deps.probeAuthoredRowWrite(object, recordId, engineOp, context).catch(() => 'abstain')) === 'admit'
+  // A transfer's door is the by-id update of `owner_id`, so it is deferred as
+  // an update; restore and purge have no by-id door (the object gate refuses
+  // both), so nothing defers them.
+  const authoredDeferralVerb: AuthoredRowWriteOperation | undefined =
+    engineOp === 'update' || engineOp === 'transfer' ? 'update' : engineOp === 'delete' ? 'delete' : undefined;
+  const authoredRowWriteAdmits = canEdit === false && authoredDeferralVerb && deps.probeAuthoredRowWrite
+    ? (await deps.probeAuthoredRowWrite(object, recordId, authoredDeferralVerb, context).catch(() => 'abstain')) === 'admit'
     : false;
   // [ADR-0055] A by-id write of a `controlled_by_parent` record (an update, a
   // delete, a transfer: {@link MASTER_CHECKED_BY_ID_WRITES}) is judged by the
@@ -1737,7 +1743,7 @@ async function applyRecordAttribution(
                     : 'The sharing service grants write on this record (ownership or an edit/full share).')
                 : 'No ownership and no edit/full share grants write on this record.' +
                   (authoredRowWriteAdmits
-                    ? ` The by-id ${engineOp} does not stop at that refusal: an app-authored row-level ${engineOp} ` +
+                    ? ` The by-id ${engineOp} does not stop at that refusal: an app-authored row-level ${authoredDeferralVerb} ` +
                       'policy admits this record, so the write gate defers to row-level security (see the rls layer).'
                     : ''))
             : depthAdmitsRow