docs(spec): ISharingService.canEdit documents the modifyAllRecords bypass (#5125) (#5818)

`canEdit`'s contract doc listed ownership and an `edit`-level share and
stopped there, while the implementation has carried a third branch since
#4647: the `modifyAllRecords` super-user write bypass, probed through
`ISecurityService.hasWriteBypass` after ownership and shares both fail
(`packages/plugins/plugin-sharing/src/sharing-service.ts:398-400`, via
`hasModifyAllBypass` at :341-351).

The omission was worse than silence because `canDelete` sits four lines
below naming the same bypass ("ownership (widened by write DEPTH) or the
`modifyAllRecords` super-user bypass ONLY"), so the pair read as a
deliberate exclusion on the update gate -- the exact opposite of the code.
The wording now matches `canDelete`'s, and names the same permission the
implementation actually checks (`bit: 'modify'` -> `op.modifyAllRecords`,
`permission-evaluator.ts:superuserBypassSets`).

Adds a parity pin over the interface's own JSDoc: the three write gates
(`canEdit` / `canDelete` / `canManageShares`) must each name the bypass,
`buildReadFilter` must not (the read path has no `hasWriteBypass` branch),
and the member enumeration is asserted whole so a rename cannot empty it.
Nothing type-checks a doc comment, and prose is what drifted here.

Comment + test only: no schema, type, export or behaviour change.


Claude-Session: https://claude.ai/code/session_01559M8FVm6W6vDLABL3jvdW

Co-authored-by: Claude <noreply@anthropic.com>

Author: baozhoutao

packages/spec/src/contracts/sharing-service.test.ts

@@ -51,3 +51,78 @@ describe('Sharing Service Contract — recipient vocabularies (#4539)', () => {
     expect(ruleRecipient).toBe(notAuthorable);
   });
 });
+
+/**
+ * [#5125] The three WRITE gates must all document the `modifyAllRecords`
+ * super-user bypass.
+ *
+ * #4647 made the bypass EXPLICIT on the enforcement side: `canEdit`,
+ * `canDelete` and `canManageShares` all fold through the one
+ * `ISecurityService.hasWriteBypass` predicate (`hasModifyAllBypass` in
+ * `@objectstack/plugin-sharing`'s `SharingService`). Two of the three
+ * docstrings said so; `canEdit`'s did not, and its omission read as a
+ * deliberate exclusion — the exact opposite of the implementation, and
+ * strictly worse than silence because `canDelete` sits four lines below
+ * naming the bypass it supposedly does not share.
+ *
+ * A prose pin rather than a behavioural one, because prose is what drifted:
+ * nothing type-checks a doc comment, and this interface's whole job is to be
+ * the thing cross-package callers read instead of the plugin. Deleting the
+ * sentence again turns this red.
+ */
+describe('[#5125] ISharingService write-gate bypass documentation parity', () => {
+  it('canEdit / canDelete / canManageShares each name the `modifyAllRecords` bypass', async () => {
+    const ts = (await import('typescript')).default;
+    const { readFileSync } = await import('node:fs');
+    const { dirname, resolve } = await import('node:path');
+    const { fileURLToPath } = await import('node:url');
+
+    const file = resolve(dirname(fileURLToPath(import.meta.url)), 'sharing-service.ts');
+    const source = ts.createSourceFile(
+      file,
+      readFileSync(file, 'utf8'),
+      ts.ScriptTarget.Latest,
+      /* setParentNodes */ true,
+    );
+
+    const iface = source.statements.find(
+      (s): s is import('typescript').InterfaceDeclaration =>
+        ts.isInterfaceDeclaration(s) && s.name.text === 'ISharingService',
+    );
+    expect(iface, 'ISharingService must still be an interface in this file').toBeDefined();
+
+    // `getFullText` carries a member's LEADING TRIVIA — its doc comment — so
+    // the pin reads exactly what an IDE shows on hover, with no assumption
+    // about how the comment is wrapped.
+    const docOf = new Map<string, string>();
+    for (const member of iface!.members) {
+      if (!ts.isMethodSignature(member) || !member.name || !ts.isIdentifier(member.name)) continue;
+      docOf.set(member.name.text, member.getFullText(source));
+    }
+
+    // Anti-vacuity 1: the enumeration found the real contract surface, so a
+    // rename cannot quietly empty the assertions below.
+    expect([...docOf.keys()].sort()).toEqual([
+      'buildReadFilter',
+      'canDelete',
+      'canEdit',
+      'canManageShares',
+      'grant',
+      'listShares',
+      'revoke',
+    ]);
+
+    for (const gate of ['canEdit', 'canDelete', 'canManageShares'] as const) {
+      expect(docOf.get(gate), `${gate} must document the modifyAllRecords bypass`)
+        .toContain('modifyAllRecords');
+    }
+
+    // Anti-vacuity 2: the search DISCRIMINATES — it is not matching text every
+    // member happens to carry. `buildReadFilter` is the honest negative: the
+    // read path has no `hasWriteBypass` branch at all (a View/Modify All Data
+    // holder reaches every row because the security layer resolves read DEPTH
+    // to `org`, which short-circuits the filter before sharing is consulted),
+    // so naming the write bypass there would itself be drift.
+    expect(docOf.get('buildReadFilter')).not.toContain('modifyAllRecords');
+  });
+});

packages/spec/src/contracts/sharing-service.ts

@@ -126,9 +126,18 @@ export interface ISharingService {
 
   /**
    * Return `true` when the principal in `context` may UPDATE the record
-   * `(object, recordId)`. Ownership (widened by write DEPTH) OR a write-level
-   * ({@link ShareAccessLevel} `edit`) share. Always true for system context,
+   * `(object, recordId)`. Ownership (widened by write DEPTH), a write-level
+   * ({@link ShareAccessLevel} `edit`) share, OR — [#4647] — the
+   * `modifyAllRecords` super-user bypass. Always true for system context,
    * `public` objects, and objects with no owner field.
+   *
+   * The bypass is the same `ISecurityService.hasWriteBypass` predicate
+   * {@link canDelete} and {@link canManageShares} consult, so the three write
+   * gates cannot drift from each other or from what `security/explain`
+   * reports. It is asked LAST — after ownership and shares — so an ordinary
+   * write costs no extra resolution, and it **fails CLOSED** (ADR-0111 D2):
+   * no security service, a throwing probe, or a principal-less /
+   * on-behalf-of context leaves the answer at owner-plus-share only.
    */
   canEdit(
     object: string,