fix(spec): the RLS check clause's enumerated-values @example is CEL, and compiles (#6641) (#6729)

* fix(spec): the RLS check clause's enumerated-values @example is CEL, and compiles (#6641)

`RowLevelSecurityPolicySchema.check` documented set membership as
`status IN ('draft', 'pending')`, which does not compile. The deprecated
SQL bridge (ADR-0058 D1) rewrites the word `IN` to `in` and never the
parentheses, and CEL's list literal is bracketed, so the bridged
`status in ('draft', 'pending')` is a parse error. `compileExpression`
then returns null, `compileFilter` sees `filters.length === 0`, and a
single-policy object falls to `RLS_DENY_FILTER` — an author copying the
schema's own example gets a policy that denies every row, plus a lint
error from `validateRlsPredicateEnforceability`.

Route 1 (document side): the example now reads the canonical CEL
`status in ['draft', 'pending']`. The deprecated bridge is deliberately
NOT widened. The `using` examples and the neighbouring single-element
`IN (current_user.<array>)` form were measured compilable and are
unchanged.

`@objectstack/formula`'s `rls-predicate.test.ts` gains the guard this
defect class never had: every `@example` on `using` / `check` is read out
of the spec source and pushed through the ADR-0056 D4 shape gate, plus a
substance pin that the enumerated-values idiom compiles to a set
membership and, under CHECK semantics, admits exactly the values it names.

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

* fix(formula): resolve this test file's directory once, keeping TEST_DEBT at 17

The new #6641 pin introduced a SECOND `import.meta.url` in
`rls-predicate.test.ts`. This package's `tsconfig.json` excludes
`*.test.ts`, so `pnpm typecheck` never reads the file — but
`check-type-check-coverage --re-measure` reads it with the exclusion
lifted and holds the count to a shrink-only TEST_DEBT ledger (#5278).
Under the package's CommonJS-targeted config each `import.meta` costs two
raw errors (TS1470 + TS2339), so the second occurrence took the entry
from its recorded 17 to 19 and tripped the ratchet.

Hoisted to one module-level `HERE` constant, read by both the existing
import-graph assertion and the new `@example` pin. Measured with the
gate's own method (formula's tsconfig, test exclusion lifted, its `spec`
closure built): 19 before, 17 after — exactly the ledger's number, so no
ledger edit is needed and no debt is being laundered.

No pin was weakened: the `@example` extraction, the shape-gate round
trip, the anti-vacuity guard and the post-image semantics all stand, and
restoring the old example still turns both new tests red.

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

---------

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

Author: os-project-manager

.changeset/rls-check-example-cel-bracket-list.md

@@ -0,0 +1,41 @@
+---
+'@objectstack/spec': patch
+---
+
+fix(spec): the RLS `check` clause's enumerated-values `@example` is CEL, and compiles (#6641)
+
+`RowLevelSecurityPolicySchema.check` in `security/rls.zod.ts` documented
+set membership as `status IN ('draft', 'pending')`. That predicate does not
+compile, and the failure is not cosmetic — an author who copies the schema's
+own example gets a policy that **denies every row**.
+
+The runtime path is `RLSCompiler.compileExpression` → `sqlPredicateToCel` →
+`compileCelToFilter`. The deprecated SQL bridge (ADR-0058 D1) rewrites the
+*word* `IN` to `in` and never the parentheses, and CEL's list literal is
+**bracketed**, so the bridged `status in ('draft', 'pending')` is a parse error
+(`Expected RPAREN, got COMMA`). `compileExpression` then returns `null`,
+`compileFilter` sees `filters.length === 0`, and a single-policy object falls to
+`RLS_DENY_FILTER`. `@objectstack/lint`'s `validateRlsPredicateEnforceability`
+rejects the same predicate at authoring time, so the symptom is "I followed the
+schema's example, and now lint errors and every query comes back empty".
+
+The neighbouring `IN (current_user.team_member_ids)` examples were never broken
+and are unchanged: a single `(expr)` happens to be a legal CEL parenthesised
+group, so that spelling survives the bridge. It collapses only once the list
+holds a second element — which is why measuring one example never covered the
+other.
+
+The example now reads `status in ['draft', 'pending']`, the canonical CEL
+spelling. Measured through the runtime's own path, it compiles to
+`{ status: { $in: ['draft', 'pending'] } }`, and under CHECK-clause semantics it
+accepts a post-image whose `status` is `draft` or `pending` while refusing
+`published`, `null`, and an absent field — which is what "Only allow certain
+statuses" has to mean.
+
+Documentation only: no schema key, type, or accepted value changed, and the
+deprecated bridge was deliberately **not** widened to rewrite parenthesised SQL
+lists (that would add surface to a dialect being retired, and would change what
+compiles). `@objectstack/formula`'s `rls-predicate.test.ts` now pins every
+`@example` on `using` / `check` through the ADR-0056 D4 shape gate, so a
+documentation example that stops compiling fails a test instead of an author's
+first policy.

packages/formula/src/rls-predicate.test.ts

@@ -18,7 +18,23 @@ import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { isSupportedRlsExpression, sqlPredicateToCel } from './rls-predicate';
-import { isPushdownableCel } from './cel-to-filter';
+import { compileCelToFilter, isPushdownableCel } from './cel-to-filter';
+import { matchesFilterCondition } from './matches-filter';
+import type { FilterCondition } from '@objectstack/spec/data';
+
+/**
+ * This file's own directory, resolved ONCE.
+ *
+ * Deliberately a single module-level constant rather than a `const here = …` in
+ * each test that needs it. This package's `tsconfig.json` excludes `*.test.ts`,
+ * so `pnpm typecheck` never reads this file — but `check-type-check-coverage`
+ * re-measures it with the exclusion lifted and holds the count to a shrink-only
+ * TEST_DEBT ledger (#5278). `import.meta` costs two raw errors there (TS1470 +
+ * TS2339) under the package's CommonJS-targeted config, so a SECOND occurrence
+ * would raise the ledger by two for no behavioural reason. One occurrence, two
+ * readers.
+ */
+const HERE = dirname(fileURLToPath(import.meta.url));
 
 // ---------------------------------------------------------------------------
 // ADR-0056 D4 — RLS predicates that won't compile must not vanish in silence
@@ -130,14 +146,106 @@ describe('isSupportedRlsExpression — composition and dependency direction', ()
    * a dependency that is only wrong at build time produces no failing assertion.
    */
   it('never imports a runtime — the hoist direction is pinned, not just intended', () => {
-    const here = dirname(fileURLToPath(import.meta.url));
-    const source = readFileSync(join(here, 'rls-predicate.ts'), 'utf8');
+    const source = readFileSync(join(HERE, 'rls-predicate.ts'), 'utf8');
     const specifiers = [...source.matchAll(/from\s+'([^']+)'/g)].map((m) => m[1]);
     expect(specifiers).toEqual(['./cel-to-filter']);
 
-    const pkg = JSON.parse(readFileSync(join(here, '..', 'package.json'), 'utf8')) as {
+    const pkg = JSON.parse(readFileSync(join(HERE, '..', 'package.json'), 'utf8')) as {
       dependencies?: Record<string, string>;
     };
     expect(Object.keys(pkg.dependencies ?? {}).sort()).toEqual(['@marcbachmann/cel-js', '@objectstack/spec']);
   });
 });
+
+// ---------------------------------------------------------------------------
+// #6641 — the schema's own `@example` predicates must COMPILE
+// ---------------------------------------------------------------------------
+//
+// `packages/spec/src/security/rls.zod.ts` documents `using` / `check` with
+// `@example` predicates, and an author copies them verbatim. An example that
+// does not compile is therefore not a typography defect: `compileExpression`
+// returns `null`, `compileFilter` sees `filters.length === 0` and returns
+// `RLS_DENY_FILTER`, so with a single policy the object denies EVERY row — and
+// `@objectstack/lint`'s `validateRlsPredicateEnforceability` rejects the same
+// predicate at authoring time, because it asks the very function above. The
+// symptom an author gets is "I followed the schema's example, and now lint
+// errors and every query is empty".
+//
+// #6641 was exactly that. `check`'s enumerated-values example read
+// `status IN ('draft', 'pending')`; `sqlPredicateToCel` rewrites the WORD `IN`
+// and never the parentheses, and CEL's list literal is BRACKETED, so the
+// bridged `status in ('draft', 'pending')` is a parse error. The neighbouring
+// `IN (current_user.<array>)` form survives only because a single `(expr)`
+// happens to be a legal CEL parenthesised group — it collapses the moment a
+// second element appears, which is why measuring one example never covered the
+// other.
+//
+// Asserted against the SOURCE TEXT on purpose: a documentation example is not
+// reachable from any import, so no ordinary unit test can ever go red on it.
+// This is the guard that whole defect class was missing.
+
+/** `packages/spec/src/security/rls.zod.ts`, from this file's own location. */
+const RLS_ZOD_SOURCE = join(HERE, '..', '..', 'spec', 'src', 'security', 'rls.zod.ts');
+
+/** The `@example "…"` predicates declared on ONE property's own TSDoc block. */
+function predicateExamples(property: 'using' | 'check'): string[] {
+  const source = readFileSync(RLS_ZOD_SOURCE, 'utf8');
+  const decl = source.indexOf(`\n  ${property}: z.string()`);
+  expect(decl, `\`${property}: z.string()\` not found in rls.zod.ts`).toBeGreaterThan(-1);
+  const block = source.slice(source.lastIndexOf('/**', decl), decl);
+  return [...block.matchAll(/@example\s+"([^"]+)"/g)].map((m) => m[1]!);
+}
+
+describe('rls.zod.ts @example — the schema documents only predicates that compile (#6641)', () => {
+  it.each(['using', 'check'] as const)('every `%s` @example passes the ADR-0056 D4 shape gate', (property) => {
+    const examples = predicateExamples(property);
+    // Anti-vacuity. A green loop over an empty list is this pin's own failure
+    // mode: reshape the docblock, or move the examples, and a bare `for` would
+    // keep reporting success while guarding nothing.
+    expect(examples.length).toBeGreaterThanOrEqual(3);
+    expect(examples.map((source) => ({ source, supported: isSupportedRlsExpression(source) })))
+      .toEqual(examples.map((source) => ({ source, supported: true })));
+  });
+
+  it('the `check` enumerated-values example is a CEL bracket list that means "one of these"', () => {
+    // Substance, not wording: find the example by the idiom it demonstrates,
+    // then read the expectations out of what it COMPILES to, so renaming the
+    // field or the statuses keeps this green while breaking the idiom fails.
+    // Case-INSENSITIVE on purpose: the SQL spelling `IN (…)` must be caught by
+    // this test and fail on the bracket assertion below, not slip past the
+    // filter and leave an empty list that a laxer pin would call green.
+    const [enumerated, ...extra] = predicateExamples('check').filter((e) => /\bin\b/i.test(e));
+    expect(extra).toEqual([]);
+    expect(enumerated).toBeTypeOf('string');
+
+    // Bracketed, never parenthesised — `(a, b)` is not a CEL expression.
+    expect(enumerated).toMatch(/\bin\s*\[/);
+    // Already canonical CEL, so the deprecated SQL bridge is a no-op on it
+    // (ADR-0058 D1): the example teaches the canonical dialect, not the bridge.
+    expect(sqlPredicateToCel(enumerated!)).toBe(enumerated);
+
+    const compiled = compileCelToFilter(enumerated!, { variables: {} });
+    expect(compiled.ok).toBe(true);
+    const filter = (compiled as { ok: true; filter: unknown }).filter as Record<string, { $in?: unknown[] }>;
+    const [field, ...moreFields] = Object.keys(filter);
+    expect(moreFields).toEqual([]);
+    const allowed = filter[field!]?.$in;
+    // More than one member is the whole point — the one-element spelling was
+    // never the broken case.
+    expect(Array.isArray(allowed) && allowed.length > 1).toBe(true);
+
+    // CHECK-clause semantics: the write path validates the POST-IMAGE against
+    // this filter (`plugin-security/security-plugin.ts` step 3.6, via
+    // `matchesFilterCondition`). Only the enumerated values may be written;
+    // anything else — including an absent or null field — is refused. That is
+    // what "Only allow certain statuses" has to mean to be a true example.
+    for (const value of allowed as unknown[]) {
+      expect(matchesFilterCondition({ [field!]: value }, filter as FilterCondition)).toBe(true);
+    }
+    const notEnumerated = '__status_not_in_the_example__';
+    expect(allowed).not.toContain(notEnumerated);
+    expect(matchesFilterCondition({ [field!]: notEnumerated }, filter as FilterCondition)).toBe(false);
+    expect(matchesFilterCondition({ [field!]: null }, filter as FilterCondition)).toBe(false);
+    expect(matchesFilterCondition({}, filter as FilterCondition)).toBe(false);
+  });
+});

packages/spec/src/security/rls.zod.ts

@@ -374,7 +374,7 @@ export const RowLevelSecurityPolicySchema = lazySchema(() => strictObject(
    * - Restrict certain operations (e.g., only allow creating "draft" status)
    * 
    * @example "organization_id = current_user.organization_id"
-   * @example "status IN ('draft', 'pending')" - Only allow certain statuses
+   * @example "status in ['draft', 'pending']" - Only allow certain statuses
    * @example "created_by = current_user.id" - Must be the creator
    */
   check: z.string()