docs(spec): correct the reuse-safety claim on the filter-subtree mark, and pin the invariant it rests on (#9073)

The mark's docblock called itself "safe on filter objects that are reused
across requests (view metadata, cached scopes)". The #8794 survey measured
that claim: it holds only where provenance is INTRINSIC to the subtree. A
'policy' scope is intrinsically policy, so a stale mark is still correct and
can only withhold. A caller's `where` is contextual — a stale 'author' mark
discloses under a root the next request never vouched, and first-mark-wins
makes the corrective 'policy' stamp a silent no-op.

Corrects both docblocks (the mark's, and `getReadFilter`'s — the public
method whose documented use puts a platform predicate in the vouched slot),
and adds four pin tests naming the invariant verbatim: no filter object that
can be vouched 'author' may outlive the request that vouched it.

No mechanism change: first-mark-wins, the non-writable symbol and positional
resolution are untouched, and the accepted metadata set is unmoved.

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

Author: os-zhuang

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

@@ -211,6 +211,27 @@ export interface ISecurityService {
    * that cannot compute the delegator intersection, returns a DENY filter that
    * matches zero rows — never `undefined`. `undefined` means one thing only:
    * this caller has no row restriction on this object.
+   *
+   * **⚠️ Request-scoped: call it per request, and never memoise what it
+   * returns.** The documented use — `engine.find(object, { where: await
+   * security.getReadFilter(object, ctx) })` — puts a PLATFORM-authored
+   * predicate into the `options.where` slot, and that slot is exactly what the
+   * read-scope merge boundaries vouch as the CALLER's own predicate (the
+   * `'author'` mark of `../data/filter-subtree-provenance.js`). Two
+   * consequences, neither of which a host may design around:
+   *
+   *  - the vouch is consumed as *"safe to disclose to this caller"*, not as
+   *    *"this caller passed it"*. A policy predicate sitting in that slot can
+   *    therefore carry its own `{ $field }` operands into a refusal message
+   *    that the #7929 redaction exists to withhold;
+   *  - the mark is permanent — first mark wins, and it is non-writable — so a
+   *    filter cached across requests keeps the FIRST request's vouch, and no
+   *    later boundary can correct it. The invariant this rests on is that no
+   *    filter object which can be vouched `'author'` outlives the request that
+   *    vouched it (#8794 / #8836).
+   *
+   * A host that must scope repeated queries re-calls this method; it does not
+   * hold the returned object.
    */
   getReadFilter(object: string, context?: SecurityContext): Promise<FilterCondition | undefined>;
 

packages/spec/src/data/filter-subtree-provenance.test.ts

@@ -9,6 +9,10 @@
  * frozen subtree, a serialized round-trip, a corrupted mark value, a rewritten
  * tree, an aliased node under conflicting arms — must land on `null`, never on
  * `'author'`.
+ *
+ * [#8836] The last block pins the one shape that does NOT land there — a
+ * vouchable filter object reused across requests — and the caller-side
+ * invariant that keeps it out of reach. Grep for "may outlive the request".
  */
 
 import { describe, it, expect } from 'vitest';
@@ -158,3 +162,129 @@ describe('resolveFilterSubtreeProvenance', () => {
     expect(resolveFilterSubtreeProvenance('root' as never, {})).toBe(null);
   });
 });
+
+/**
+ * [#8836, from the #8794 survey] The invariant the fail-closed direction
+ * silently depends on, made executable:
+ *
+ * > no filter object that can be vouched `'author'` may outlive the request
+ * > that vouched it.
+ *
+ * ⚠️ **These tests assert what IS, not what SHOULD BE.** The mark's mechanism
+ * is #8220's and is deliberately untouched here: first-mark-wins, the
+ * non-writable symbol, and positional resolution all stay exactly as declared.
+ * What this block pins is the COST of breaking the invariant — the disclosure a
+ * reused vouchable object produces, measured against the control that makes the
+ * measurement mean something. `packages/spec` cannot enforce the invariant
+ * itself: "the request" is not a concept this module can see, and the callers
+ * that must honour it live in `plugin-security` / `plugin-sharing`
+ * (`markFilterSubtreeProvenance(…, 'author')` is reachable only on
+ * `options.where` itself or on the arms of a pure `$and` root). So the guard
+ * this block can offer is that the consequence stays visible and stays
+ * asserted: a future change that makes any expectation below go red is a
+ * change to the mark's mechanism, which #8794's ruling routes to a spec-seat
+ * ruling BEFORE implementation — not something to fix by editing these
+ * numbers.
+ */
+describe("invariant: no filter object that can be vouched 'author' may outlive the request that vouched it", () => {
+  /**
+   * The identity vouch both read-scope merge boundaries perform, reduced to the
+   * decision that matters: `options.where` is stamped `'author'` only while the
+   * AST still holds that exact object. Written out rather than imported because
+   * `packages/spec` sits UNDER both plugins — the real sites are
+   * `plugin-security`'s CRUD injection and `plugin-sharing`'s read-filter merge,
+   * and the survey measured both. Nothing here is a stand-in for behaviour under
+   * test; the subject is this module's exports.
+   */
+  const vouchCallerWhere = (ast: { where: unknown }, options: { where: object }): void => {
+    if (ast.where !== options.where) return; // re-shaped between the two: no vouch
+    markFilterSubtreeProvenance(options.where, 'author');
+  };
+
+  /**
+   * One request. `composeScope` is the ordinary case where a sibling middleware
+   * (or ADR-0061 search expansion) ANDs its own predicate into the AST BEFORE
+   * the vouch runs, so this request's boundary no longer recognises the caller's
+   * object and vouches nothing at all.
+   */
+  const runRequest = (callerWhere: object, opts: { composeScope?: boolean } = {}) => {
+    const options = { where: callerWhere };
+    const ast: { where: unknown } = { where: options.where };
+    if (opts.composeScope) {
+      ast.where = {
+        $and: [callerWhere, markFilterSubtreeProvenance({ organization_id: 'org_1' }, 'policy')],
+      };
+    }
+    vouchCallerWhere(ast, options);
+    return ast;
+  };
+
+  it('a vouched filter that OUTLIVES its request discloses under a root the next request never vouched', () => {
+    // A module-level constant, a cached scope, view metadata: one object, two requests.
+    const reusedWhere = { amount: { $gt: { $field: 'budget' } } };
+
+    // Request 1 — identity holds, so this request's boundary vouches it.
+    runRequest(reusedWhere);
+    expect(filterSubtreeProvenanceOf(reusedWhere)).toBe('author');
+
+    // Request 2 — a sibling middleware composed first, so this boundary vouches NOTHING.
+    const ast = runRequest(reusedWhere, { composeScope: true });
+    expect(filterSubtreeProvenanceOf(ast.where)).toBe(null);
+
+    // …and the caller's comparand still answers 'author' — request 1's vouch,
+    // spent as a licence to disclose inside request 2. This is the whole cost.
+    expect(resolveFilterSubtreeProvenance(ast.where, reusedWhere.amount.$gt)).toBe('author');
+  });
+
+  it('CONTROL: the same shape built FRESH per request resolves null in that same position', () => {
+    const buildWhere = () => ({ amount: { $gt: { $field: 'budget' } } });
+
+    const first = buildWhere();
+    runRequest(first);
+    expect(filterSubtreeProvenanceOf(first)).toBe('author'); // the vouch still happens
+
+    // Structurally identical, same position, same middleware — only the object's
+    // lifetime differs, and the verdict flips to withheld. That difference is
+    // the invariant, and it is the reason the test above is not a tautology.
+    const second = buildWhere();
+    const ast = runRequest(second, { composeScope: true });
+    expect(resolveFilterSubtreeProvenance(ast.where, second.amount.$gt)).toBe(null);
+  });
+
+  it('a later boundary cannot repair a stale author mark — the corrective policy stamp is a silent no-op', () => {
+    // The mirror of the "first mark wins" case above, and the load-bearing one:
+    // there a stale 'policy' mark resisted an 'author' overwrite (fail-closed);
+    // here a stale 'author' mark resists the 'policy' correction (fail-open).
+    const reused = markFilterSubtreeProvenance({ owner: { $field: 'manager_id' } }, 'author');
+
+    markFilterSubtreeProvenance(reused, 'policy');
+    expect(filterSubtreeProvenanceOf(reused)).toBe('author');
+
+    // Nor can a boundary force it: the mark is non-writable and non-configurable.
+    expect(() =>
+      Object.defineProperty(reused, FILTER_SUBTREE_PROVENANCE, { value: 'policy' }),
+    ).toThrow(TypeError);
+    expect(filterSubtreeProvenanceOf(reused)).toBe('author');
+  });
+
+  it('the asymmetry: reuse degrades a policy mark toward WITHHOLDING and an author mark toward DISCLOSING', () => {
+    // Why "the classification of one subtree does not change between requests"
+    // is sound for a policy scope and unsound for a caller's `where`: provenance
+    // is intrinsic to the first and contextual to the second. Same reuse, same
+    // unvouched root, opposite fail direction.
+    const unvouchedRoot = (arm: object) => ({ $and: [{ stage: 'won' }, arm] });
+
+    const staleScope = markFilterSubtreeProvenance(
+      { organization_id: { $field: 'ctx_org' } },
+      'policy',
+    );
+    expect(
+      resolveFilterSubtreeProvenance(unvouchedRoot(staleScope), staleScope.organization_id),
+    ).toBe('policy'); // still correct next request, and it can only withhold
+
+    const staleWhere = markFilterSubtreeProvenance({ amount: { $gt: { $field: 'budget' } } }, 'author');
+    expect(resolveFilterSubtreeProvenance(unvouchedRoot(staleWhere), staleWhere.amount.$gt)).toBe(
+      'author',
+    ); // no longer this request's caller, and it DISCLOSES
+  });
+});

packages/spec/src/data/filter-subtree-provenance.ts

@@ -120,9 +120,45 @@ export const FILTER_SUBTREE_PROVENANCE: symbol = Symbol.for(
  * unchanged: the actor closest to the subtree's creation is the one that knows
  * its provenance, and letting a later, more distant actor overwrite that would
  * let a generic boundary re-vouch a policy predicate as the caller's. Marking
- * is therefore idempotent, and safe on filter objects that are reused across
- * requests (view metadata, cached scopes): the classification of one subtree
- * does not change between requests.
+ * is therefore idempotent.
+ *
+ * ## ⚠️ Idempotent is NOT "safe to reuse across requests"
+ *
+ * This paragraph used to end by calling the mark *"safe on filter objects that
+ * are reused across requests (view metadata, cached scopes): the
+ * classification of one subtree does not change between requests"*. The
+ * #8794 survey measured that claim and it is true in ONE direction only; the
+ * correction is pinned by `filter-subtree-provenance.test.ts` (#8836). The
+ * claim holds where provenance is **intrinsic** to the subtree, and a caller's
+ * `where` is the half where it is not:
+ *
+ *  - a `'policy'` scope IS intrinsically policy — the platform's predicate in
+ *    every request — so a stale `'policy'` mark is still correct next request,
+ *    and first-mark-wins is what stops a distant boundary re-vouching it. This
+ *    is the direction the rule was written for, and it degrades toward
+ *    WITHHOLDING;
+ *  - a caller's `where` is **contextual** — the same object is the caller's own
+ *    predicate in one request and not in another. A stale `'author'` mark
+ *    degrades toward DISCLOSING, and because first-mark-wins is absolute the
+ *    corrective `'policy'` stamp a later boundary would apply is a silent
+ *    no-op — the already-marked guard below returns the subtree unchanged.
+ *    Nothing downstream can repair it either: the mark is non-writable and
+ *    non-configurable.
+ *
+ * So "the classification does not change between requests" is an assumption
+ * about the CALLER POPULATION, not a property of this mark. The invariant the
+ * design actually rests on is:
+ *
+ * > no filter object that can be vouched `'author'` may outlive the request
+ * > that vouched it.
+ *
+ * It holds across every in-repo caller today — enumerated with controls in
+ * #8794 — and it holds *incidentally*: every caller in a markable position
+ * (`options.where` itself, or an arm of a pure `$and` root) happens to build
+ * its filter fresh per request. This module does not and cannot enforce it,
+ * because "the request" is not a concept it can see. What is enforced is that
+ * the cost of breaking it stays visible: the pin test asserts the disclosure a
+ * reused vouchable object produces, and its fresh-object control.
  *
  * Fail-closed by silence: a non-object subtree, a frozen/sealed one, or any
  * `defineProperty` refusal leaves the subtree unmarked — and unmarked is