bridgebench 3.1.0-alpha.0

package/tasks/reasoning/public/stateful-retry-budget.yaml

@@ -0,0 +1,222 @@
+id: stateful-retry-budget
+version: 2.0.0
+category: reasoning
+cluster: stateful-execution
+difficulty: expert
+title: Shared Retry Budget Across Five Concurrent Requests With Cancellation
+summary: >-
+  Trace five concurrent requests through a retry state machine that share one token-bucket retry
+  budget, with deterministic backoff and jitter, per-request deadlines, cancellation, and three
+  distinct failure modes, then evaluate a proposed increase to the per-request attempt cap.
+prompt: |
+  A client library runs five requests (R1..R5) concurrently against one upstream. They share a single
+  retry budget. The state machine and its transition precedence are in [retry-state-machine]; the
+  dispatcher that implements it is [dispatcher-code]; numeric parameters are in [retry-config]; status
+  codes are classified by [status-classification]; retry start times use the deterministic offsets in
+  [jitter-table]; the raw global-ordered event stream is [event-log]. [ops-note] is an engineer's
+  post-incident summary. [proposed-change] is a config edit under review.
+
+  All times are milliseconds from an origin. The budget is shared: every request's retries draw from
+  and credit the same bucket, so you must process budget-affecting events in strict time order. Answer
+  every deliverable; the log alone does not state outcomes — you must apply the state machine.
+
+  1. Terminal state. For each of R1..R5 give the terminal state. Where a request FAILED, give the
+     specific reason (max-attempts, budget-exhausted, deadline, or non-retryable).
+  2. Call accounting. Give the total number of upstream calls, the per-request call count, and the
+     exact start time (ms) of R2's third attempt.
+  3. Budget. Give the exact final value of the shared retry budget after all events.
+  4. Failure modes. Exactly three requests do not end in SUCCESS. Identify which one ends by
+     max-attempts, which by budget-exhaustion, and which by cancellation — and justify each against
+     the precedence order in [retry-state-machine].
+  5. Cancellation and the stale timer. For R4: does attempt 3 begin? State what happens when the timer
+     scheduled for R4 fires at t=610. Then, using [event-log], identify every claim in [ops-note] that
+     is false and give the correct fact for each.
+  6. Proposed change. Under [proposed-change] (max_attempts_per_request 3 -> 5), state which requests'
+     terminal outcomes change, which requests' failure reason changes, whether the total upstream call
+     count changes, and explain why the change does or does not improve the success rate.
+artifacts:
+  - id: retry-state-machine
+    type: spec
+    label: Retry state machine and precedence
+    content: |
+      DEFINITIONS
+        - attempt: one call issued to the upstream. attempts_started counts attempts issued so far for
+          a request; when the response for attempt N arrives, attempts_started == N.
+        - RETRY_WAIT: the request is idle, holding a scheduled timer for its next attempt.
+        - budget: the shared token bucket in [retry-config]; there is exactly one, common to all
+          requests.
+
+      States: PENDING -> IN_FLIGHT -> one of { SUCCESS, RETRY_WAIT, FAILED, CANCELLED,
+      DEADLINE_EXCEEDED }. attempt 1 starts at admission (PENDING -> IN_FLIGHT).
+
+      On a response classified retryable (see [status-classification]), evaluate IN THIS ORDER and act
+      on the FIRST matching rule (later rules are not consulted once one fires):
+        (1) if attempts_started >= max_attempts_per_request -> terminal FAILED, reason max-attempts.
+        (2) else if now >= (admission_time + per_request_deadline_ms) -> terminal DEADLINE_EXCEEDED.
+        (3) else if budget < min_to_retry -> terminal FAILED, reason budget-exhausted.
+        (4) else schedule attempt N+1 at time (response_time + backoff_gap(N) + jitter); set
+            budget := budget - retry_cost; state RETRY_WAIT.
+      backoff_gap(N) = backoff_base_ms * backoff_multiplier^(N-1): after attempt 1 = 100 ms, after
+      attempt 2 = 200 ms. jitter is taken from [jitter-table] for (request, N).
+
+      On a response classified success -> terminal SUCCESS; budget := min(max, budget + success_credit).
+      On a response classified terminal-fail (non-retryable) -> terminal FAILED, reason non-retryable.
+
+      Cancellation (caller-initiated) is immediately terminal CANCELLED. It cancels any scheduled retry
+      timer. A timer that fires for an already-terminal request is IGNORED and starts no attempt. A
+      response that arrives for an attempt after the request is terminal is IGNORED. retry_cost spent
+      on a scheduled-but-not-yet-started retry is NOT refunded on cancellation.
+
+      Deadline reached while RETRY_WAIT or IN_FLIGHT -> terminal DEADLINE_EXCEEDED. Terminal states are
+      final and never re-enter the machine.
+
+      ILLUSTRATIVE ONLY (not one of R1..R5): a request admitted at t=1000 (deadline 1500) whose attempt
+      1 returns 500 at t=1040, with budget 4.0 at that instant: rule (1) no (1 < 3), rule (2) no
+      (1040 < 1500), rule (3) no (4.0 >= 1.0), so rule (4) fires — schedule attempt 2 at
+      1040 + 100 + jitter and set budget := 3.0. This example uses invented numbers to show the
+      precedence; do not fold it into the R1..R5 accounting.
+  - id: dispatcher-code
+    type: code
+    label: Shared dispatcher pseudocode
+    content: |
+      // One dispatcher serves all requests. `budget` is a single shared variable (the token bucket).
+      // Events are delivered in nondecreasing time order (see [event-log]).
+
+      budget = config.retry_budget.initial          // 8.0, cap config.retry_budget.max (8.0)
+
+      function onResponse(req, attemptN, status, nowMs):
+        if req.terminal: return                      // late response for a finished request: ignore
+        cls = classify(status)                       // see [status-classification]
+        if cls == "success":
+          req.finish(SUCCESS)
+          budget = min(config.max, budget + config.success_credit)   // +0.5
+          return
+        if cls == "terminal-fail":
+          req.finish(FAILED, reason = "non-retryable"); return
+        // cls == "retryable" -> precedence order:
+        if attemptN >= config.max_attempts_per_request:
+          req.finish(FAILED, reason = "max-attempts"); return        // rule (1)
+        if nowMs >= req.admittedAt + config.per_request_deadline_ms:
+          req.finish(DEADLINE_EXCEEDED); return                      // rule (2)
+        if budget < config.min_to_retry:
+          req.finish(FAILED, reason = "budget-exhausted"); return    // rule (3)
+        gap = config.backoff_base_ms * (config.backoff_multiplier ** (attemptN - 1))
+        startAt = nowMs + gap + jitter(req, attemptN)                // [jitter-table]
+        budget = budget - config.retry_cost                          // rule (4): -1.0, not refunded
+        req.scheduleAttempt(attemptN + 1, startAt)
+
+      function onCancel(req, nowMs):
+        if req.terminal: return
+        req.cancelTimer(); req.finish(CANCELLED)
+
+      function onTimer(req, attemptN):
+        if req.terminal: return                      // stale timer for a finished request: ignore
+        req.startAttempt(attemptN)
+  - id: retry-config
+    type: config
+    label: Retry parameters
+    content: |
+      max_attempts_per_request: 3
+      backoff_base_ms: 100
+      backoff_multiplier: 2                # gap after attempt N = base * multiplier^(N-1)
+      per_request_deadline_ms: 500         # absolute deadline = admission_time + 500
+      timer_resolution_ms: 1               # timers fire at their scheduled ms
+      upstream: "quote-svc"                # single upstream shared by all requests
+      retry_budget:
+        initial: 8.0                       # bucket starts full
+        max: 8.0                           # credits are capped here
+        retry_cost: 1.0                    # subtracted when a retry is scheduled (rule 4)
+        success_credit: 0.5                # added on SUCCESS, capped at max
+        min_to_retry: 1.0                  # a retry requires budget >= this value
+  - id: status-classification
+    type: table
+    label: Response classification
+    content: |
+      status        | class
+      200, 201, 204 | success
+      400, 401, 403, 404, 422 | terminal-fail (non-retryable)
+      429, 500, 502, 503 | retryable
+      TIMEOUT       | retryable
+      note: only the statuses that actually occur in [event-log] matter for the answer; the rest are
+      listed so the classification is unambiguous. TIMEOUT is a transport timeout of a single attempt,
+      not the per-request deadline.
+  - id: jitter-table
+    type: table
+    label: Deterministic retry jitter
+    content: |
+      request | attempt N | jitter_ms
+      R1      | 1         | 12
+      R1      | 2         | 0
+      R2      | 1         | 20
+      R2      | 2         | 15
+      R3      | 1         | 8
+      R3      | 2         | 25
+      R4      | 1         | 5
+      R4      | 2         | 10
+      R5      | 1         | 18
+      R5      | 2         | 0
+      note: jitter for (request, N) is added to attempt N+1's start. No entry is needed for attempt 3's
+      successor because max attempts is 3.
+  - id: event-log
+    type: log
+    label: Global-ordered event stream (raw; outcomes not annotated)
+    content: |
+      t_ms | request | phase                | status/detail | latency_ms | endpoint
+      0    | R1      | admitted             | deadline 500  | -          | -
+      0    | R1      | attempt 1 start      | -             | -          | quote-svc
+      30   | R1      | attempt 1 response   | 503           | 30         | quote-svc
+      50   | R2      | admitted             | deadline 550  | -          | -
+      50   | R2      | attempt 1 start      | -             | -          | quote-svc
+      90   | R2      | attempt 1 response   | TIMEOUT       | 40         | quote-svc
+      100  | R3      | admitted             | deadline 600  | -          | -
+      100  | R3      | attempt 1 start      | -             | -          | quote-svc
+      142  | R1      | attempt 2 start      | -             | -          | quote-svc
+      150  | R3      | attempt 1 response   | 503           | 50         | quote-svc
+      175  | R1      | attempt 2 response   | 200           | 33         | quote-svc
+      200  | R4      | admitted             | deadline 700  | -          | -
+      200  | R4      | attempt 1 start      | -             | -          | quote-svc
+      210  | R2      | attempt 2 start      | -             | -          | quote-svc
+      250  | R4      | attempt 1 response   | 500           | 50         | quote-svc
+      258  | R3      | attempt 2 start      | -             | -          | quote-svc
+      260  | R2      | attempt 2 response   | 429           | 50         | quote-svc
+      300  | R3      | attempt 2 response   | TIMEOUT       | 42         | quote-svc
+      310  | R5      | admitted             | deadline 810  | -          | -
+      310  | R5      | attempt 1 start      | -             | -          | quote-svc
+      340  | R5      | attempt 1 response   | 429           | 30         | quote-svc
+      355  | R4      | attempt 2 start      | -             | -          | quote-svc
+      400  | R4      | attempt 2 response   | 503           | 45         | quote-svc
+      458  | R5      | attempt 2 start      | -             | -          | quote-svc
+      475  | R2      | attempt 3 start      | -             | -          | quote-svc
+      480  | R4      | caller cancel        | -             | -          | -
+      500  | R5      | attempt 2 response   | TIMEOUT       | 42         | quote-svc
+      520  | R2      | attempt 3 response   | 503           | 45         | quote-svc
+      525  | R3      | attempt 3 start      | -             | -          | quote-svc
+      560  | R3      | attempt 3 response   | 200           | 35         | quote-svc
+      610  | R4      | retry timer fires    | for attempt 3 | -          | -
+  - id: ops-note
+    type: note
+    label: Post-incident summary (unverified)
+    content: |
+      On-call notes, filed after the incident (NOT independently verified):
+        - R2 exceeded its request deadline and timed out.
+        - R5 failed after using all 3 of its attempts.
+        - R4 completed its third attempt at t=610.
+        - Raising max_attempts_per_request to 5 will recover both R2 and R5, so the fix is a one-line
+          config bump.
+      Proposed remediation attached to the note: "Bump max attempts to 5; keep everything else the
+      same." Treat every line above as a claim to be checked against [event-log], not as fact.
+  - id: proposed-change
+    type: diff
+    label: Proposed configuration change
+    content: |
+      --- retry-config (current)
+      +++ retry-config (proposed)
+      - max_attempts_per_request: 3
+      + max_attempts_per_request: 5      # "let struggling requests try harder to succeed"
+        backoff_base_ms: 100             # unchanged
+        retry_budget:
+          initial: 8.0                   # unchanged
+          success_credit: 0.5            # unchanged
+          min_to_retry: 1.0              # unchanged
+      Only max_attempts_per_request changes; the shared budget parameters are untouched.
+tags: [state-machine, retries, token-bucket, backoff, cancellation, concurrency]

package/tasks/reasoning/public/synthesis-api-contract.yaml

@@ -0,0 +1,214 @@
+id: synthesis-api-contract
+version: 2.0.0
+category: reasoning
+cluster: multi-artifact-synthesis
+difficulty: expert
+title: Legacy API Clients Lose Exactly Their Renamed Fields After a Uniform Projection Allowlist
+summary: A shared profile handler serves both a frozen v4 contract and a current v5 contract through a per-route gateway pipeline. After a security ticket added a response-field allowlist to every route, v4 clients silently lose three fields while keeping two, all with HTTP 200. Reconcile the contracts, pipeline, handler, logs, and field observations to find the one misconfiguration, reject the decoys, and specify the minimal fix scoped to the affected route.
+prompt: |
+  v4 clients (mobile and a partner batch job) started getting HTTP 200 profile responses that are
+  missing required fields, while v5 clients are fine. Using only the artifacts, produce:
+
+  1. FAILURE SURFACE. State exactly which fields are missing, on which route, for which clients, and
+     which fields still arrive. Cite client-logs and the field-observation-table.
+  2. ROOT CAUSE. Explain the single misconfiguration that drops those fields and why it drops exactly
+     those and not the others. Cite gateway-pipeline, both contracts, and change-ticket.
+  3. AVATAR DECOY. Explain why the recent avatar-object rollout (PROJ-799 in change-ticket) is not the
+     cause, even though avatar_url is among the missing fields.
+  4. UPGRADE DECOY. Explain why "ship a mobile/partner client update" is not an acceptable resolution,
+     reconciling the dates in deprecation-policy.
+  5. MINIMAL FIX. Give the smallest correction, scoped to a single route, that restores the v4 fields
+     without changing v5 behavior and without discarding the security intent of the allowlist.
+  6. VERIFICATION. State the exact field set and value formats a correct v4 profile response must
+     contain, and confirm the v5 response must remain unchanged. Cite v4-contract and v5-contract.
+
+  Exactly one resolution is defensible per deliverable; it is fully determined by the artifacts.
+artifacts:
+  - id: v5-contract
+    type: spec
+    label: v5 profile response contract (current)
+    content: |
+      GET /api/v5/profile -> 200 application/json
+      Required fields:
+        id           string (uuid)
+        display_name string                     # renamed from v4 user_name
+        avatar       object { url: string, blurhash: string }   # replaced v4 avatar_url string
+        created_at   string (ISO-8601 UTC)      # replaced v4 integer "created"
+        plan         enum "pro" | "ultra"       # renamed values from v4 "plus" | "max"
+      The handler emits this shape natively; the v5 route performs no field renaming.
+
+      Canonical example (what a conforming v5 response looks like):
+        {
+          "id": "7b3f...e21",
+          "display_name": "Dana Okoro",
+          "avatar": { "url": "https://cdn.example/av/7b3f.png", "blurhash": "L6Pj0^" },
+          "created_at": "2025-02-11T09:30:00Z",
+          "plan": "pro"
+        }
+      Consumers: web-v5 (current web app) and any client that migrated to v5. These read the object
+      avatar and the ISO created_at directly. No v5 client depends on the legacy names.
+      Field notes:
+        - display_name is always present (never null); the handler falls back to the account handle.
+        - avatar.url is always a fully-qualified https URL; blurhash is a short placeholder string.
+  - id: v4-contract
+    type: spec
+    label: v4 profile response contract (frozen, deprecation window)
+    content: |
+      GET /api/v4/profile -> 200 application/json
+      Required fields (byte-stable; clients hard-fail if any are absent):
+        id         string (uuid)                # identical to v5
+        user_name  string                       # v5 display_name
+        avatar_url string (url)                 # v5 avatar.url
+        created    integer (epoch seconds)      # v5 created_at
+        plan       enum "plus" | "max"          # v5 "pro" -> "plus", "ultra" -> "max"
+      Note: only user_name, avatar_url, and created require a NAME change from the v5 shape.
+      id keeps its name; plan keeps its name (only its enum values are remapped).
+
+      Canonical example (what a conforming v4 response MUST look like for the same user):
+        {
+          "id": "7b3f...e21",
+          "user_name": "Dana Okoro",
+          "avatar_url": "https://cdn.example/av/7b3f.png",
+          "created": 1739266200,
+          "plan": "plus"
+        }
+      Consumers: mobile-v4 (shipped app binaries in the field) and partner-batch (a nightly partner
+      integration job). Both hard-validate the response against this schema and abort on any missing
+      required field, surfacing a user-visible error rather than degrading gracefully.
+      Field notes:
+        - created is the integer epoch-seconds form of the same instant v5 encodes as created_at ISO.
+        - "plus"/"max" are the ONLY plan values v4 clients accept; "pro"/"ultra" would be rejected too.
+  - id: deprecation-policy
+    type: note
+    label: API deprecation policy
+    content: |
+      Incident date: 2026-07-10.
+      Policy: v4 is deprecated but SUPPORTED through 2026-12-31. Until that date the server MUST keep
+      v4 responses byte-compatible with the frozen v4-contract above. Rules:
+        - Server-side compatibility is mandatory, not best-effort.
+        - Clients on v4 cannot be compelled to upgrade before the window closes.
+        - A change that makes a v4 response non-conforming is a Sev-2 regression, not an accepted cost
+          of shipping v5.
+      Forcing a client release inside the window (mobile store update, partner redeploy, etc.) is a
+      policy violation and is not an accepted remediation. As of 2026-07-10 the window is OPEN
+      (roughly six months remain).
+  - id: gateway-pipeline
+    type: config
+    label: gateway per-route response pipeline
+    content: |
+      # gateway/response-pipeline.yaml
+      # Each route runs an ORDERED list of steps, top to bottom, over the handler's JSON output.
+      # Step reference:
+      #   rename    { from_field: to_field }         renames keys
+      #   mapValues { field: { from_value: to } }    remaps enum values in place
+      #   coerce    { field: type }                  converts a value's type/shape
+      #   project   { allow: [fields...] }           DROPS any field not listed in `allow`
+      routes:
+        /api/v5/profile:
+          enabled: true
+          pipeline:
+            - project: { allow: [id, display_name, avatar, created_at, plan] }
+
+        /api/v4/profile:
+          enabled: true
+          pipeline:
+            - rename: { display_name: user_name, avatar: avatar_url, created_at: created }
+            - mapValues: { plan: { pro: plus, ultra: max } }
+            - coerce: { avatar_url: url_string, created: epoch_seconds }
+            - project: { allow: [id, display_name, avatar, created_at, plan] }
+      # NOTE: `project` filters on the field names present AT THAT POINT in the pipeline.
+      # Order matters: steps run top to bottom. A field dropped by `project` is absent from the
+      # response body entirely (not null); the client sees a shorter object.
+  - id: profile-handler
+    type: code
+    label: shared profile handler
+    content: |
+      // profile/handler.ts  — ONE implementation serves BOTH /api/v4/profile and /api/v5/profile.
+      // Per-route gateway pipelines (see gateway-pipeline) adapt this output to each contract.
+      export async function getProfile(userId: string) {
+        const u = await db.users.findById(userId);
+        return {
+          id: u.id,
+          display_name: u.displayName,                      // v5-native field names
+          avatar: { url: u.avatarUrl, blurhash: u.blurhash },
+          created_at: u.createdAt.toISOString(),            // ISO-8601 string
+          plan: normalizePlan(u.plan),                      // returns "pro" | "ultra"
+        };
+      }
+
+      function normalizePlan(raw: string): 'pro' | 'ultra' {
+        // Legacy stored values are normalized up to the v5 enum.
+        if (raw === 'plus' || raw === 'pro') return 'pro';
+        if (raw === 'max' || raw === 'ultra') return 'ultra';
+        return 'pro';
+      }
+      // The handler ALWAYS emits the v5 shape. It has no per-version branching.
+  - id: change-ticket
+    type: note
+    label: recent change tickets
+    content: |
+      PROJ-812 (merged 2 days before the incident): "Add a response-field allowlist (project step) to
+      ALL profile routes to prevent accidental field leakage." Implementation notes on the ticket:
+        - A single allowlist was written using the v5 field names.
+        - It was appended as the LAST step of every route's pipeline, including /api/v4/profile.
+        - No route-specific field names were used; the reviewer asked "does v4 rename before this?"
+          and the thread was never resolved before merge.
+      This is the only change to the v4 pipeline in the last 30 days.
+
+      PROJ-799 (merged 3 weeks before the incident): "Roll out v5 avatar as an object { url, blurhash }."
+      This changed the handler's avatar from a string to an object. v5 clients read avatar.url; the v4
+      route already had a `coerce` step to flatten avatar back to a url string. No client complaints
+      were filed when PROJ-799 shipped, and v4 traffic was healthy for the following two weeks.
+
+      Timeline:
+        - day -21: PROJ-799 merged and deployed. v4 and v5 both healthy afterward.
+        - day -14 to day -2: no profile-pipeline changes; v4 error rate ~0.
+        - day -2: PROJ-812 merged and deployed. v4 error rate begins climbing on the next deploy.
+        - day  0: incident opened; mobile-v4 and partner-batch failing on missing required fields.
+      The v4 failures start immediately after PROJ-812, not after PROJ-799.
+  - id: client-logs
+    type: log
+    label: client request outcomes and a captured v4 body
+    content: |
+      web-v5        GET /api/v5/profile   200  keys=[id, display_name, avatar, created_at, plan]  parsed OK
+      mobile-v4     GET /api/v4/profile   200  keys=[id, plan]  ERROR missing required: user_name, avatar_url, created
+      mobile-v4     GET /api/v4/profile   200  keys=[id, plan]  ERROR missing required: user_name, avatar_url, created
+      partner-batch GET /api/v4/profile   200  keys=[id, plan]  ERROR missing required: user_name, avatar_url, created
+      web-v5        GET /api/v5/profile   200  keys=[id, display_name, avatar, created_at, plan]  parsed OK
+      partner-batch GET /api/v4/profile   200  keys=[id, plan]  ERROR missing required: user_name, avatar_url, created
+
+      # Captured /api/v4/profile response body during the incident (same user as the contract examples):
+      #   { "id": "7b3f...e21", "plan": "plus" }
+      # Observations: the body is HTTP 200; `plan` is present AND correctly remapped to "plus"
+      # (so the mapValues step ran); id is present; the three renamed fields are gone.
+
+      # Captured /api/v5/profile response body during the same window (for contrast):
+      #   { "id": "7b3f...e21", "display_name": "Dana Okoro",
+      #     "avatar": { "url": "https://cdn.example/av/7b3f.png", "blurhash": "L6Pj0^" },
+      #     "created_at": "2025-02-11T09:30:00Z", "plan": "pro" }
+      # The v5 body is complete and conforming; only the v4 route sheds fields.
+  - id: field-observation-table
+    type: table
+    label: observed field presence by route
+    content: |
+      v4 response field  maps from (v5)  requires rename?  required by v4?  present for v4 clients?
+      id                 id              no                yes              yes
+      user_name          display_name    yes               yes              NO
+      avatar_url         avatar.url      yes               yes              NO
+      created            created_at      yes               yes              NO
+      plan               plan            no (value remap)  yes              yes (value = "plus")
+
+      value-format check on the fields that DID arrive for v4 clients:
+        id    -> uuid string, correct
+        plan  -> "plus", correctly remapped from "pro" (mapValues ran successfully)
+
+      counts:
+        v4 required fields:            5  (id, user_name, avatar_url, created, plan)
+        v4 fields present in response: 2  (id, plan)
+        v4 fields missing:            3  (user_name, avatar_url, created)
+        of the 3 missing, all 3 are the fields that require a name change from v5
+        of the 2 present, neither requires a name change from v5
+      # Fingerprint: every field that needs a NAME change is absent; the two fields whose name is
+      # unchanged across versions (id, plan) are present. v5 clients receive the full v5 shape.
+      # (All rows describe /api/v4/profile responses observed during the incident.)
+tags: [api, compatibility, versioning, gateway, multi-artifact-synthesis]

package/tasks/reasoning/public/synthesis-permission-migration.yaml

@@ -0,0 +1,190 @@
+id: synthesis-permission-migration
+version: 2.0.0
+category: reasoning
+cluster: multi-artifact-synthesis
+difficulty: expert
+title: Explicit-Grant Lockout Where the Backfill Ran but the Read Model Was Never Rebuilt
+summary: A role-to-grants authorization migration locked out every legacy editor and viewer while admins kept working. The obvious story (backfill never ran, or enforcement shipped first) is contradicted by the artifacts because the backfill completed and the source grants exist. Reconcile both models, the authz check, the rollout plan, and the audit evidence to find the real gap, reject three decoys, and specify a recovery that restores access without broadening it.
+prompt: |
+  After cutover to explicit grants, legacy editors and viewers are denied document.read while admins
+  are allowed. On-call's first guess was "enforcement shipped before the backfill." Using only the
+  artifacts, produce:
+
+  1. ROOT CAUSE. Name the single gap and cite the exact artifacts and lines that prove it. Explain
+     why grants exist yet authorization still denies.
+  2. REFUTE THE OBVIOUS STORY. Explain, with citations, why "the backfill never ran" and "enforcement
+     shipped before the backfill" are NOT the operative cause here.
+  3. ADMIN VS EVERYONE ELSE. Explain why admin-01 is allowed while editor-17 and viewer-04 are denied,
+     even though all three have rows in the grants source table.
+  4. DEAD-FLAG DECOY. Explain why `useLegacyRoleFallback` cannot rescue the locked-out accounts.
+  5. BLAST RADIUS. State exactly which subjects are locked out and which are safe, tied to how each was
+     provisioned, and which operations are affected.
+  6. MINIMAL RECOVERY. Give the smallest fix that restores access without granting anyone more than
+     their legacy role implied and without making role names authoritative again. State what must NOT
+     be done.
+
+  Exactly one resolution is defensible per deliverable; it is fully determined by the artifacts.
+artifacts:
+  - id: legacy-model
+    type: spec
+    label: legacy role model (pre-migration)
+    content: |
+      Legacy role model (in force until cutover):
+        editor -> implicit document.read AND document.write
+        viewer -> implicit document.read
+        admin  -> implicit all permissions
+      Authorization was derived directly from role membership; a check looked up the caller's role
+      and expanded it to the implied permission set at request time. There was no grants table, and
+      no per-subject permission rows existed anywhere. Role assignments live in a legacy table
+      `role_assignments(subject_id, role)`, which the backfill reads (see backfill-script).
+
+      Population at cutover (from role_assignments):
+        editors: 1812   (each should end with document.read + document.write = 3624 grant rows)
+        viewers:  455   (each should end with document.read            =  455 grant rows)
+      Expected backfill output: 3624 + 455 = 4079 grant rows for editors and viewers (all via direct SQL).
+      Separately, 6 admins plus service accounts were provisioned through the grants API; those account
+      for the 41 rows currently visible in grant_view and are included in the 4120-row grants total.
+      The intent of the migration is to preserve EXACTLY these permissions as explicit grants and
+      nothing more (viewers must not gain write; editors must not gain admin).
+  - id: grant-model
+    type: spec
+    label: new explicit-grant model
+    content: |
+      New authorization model:
+        - All permissions are explicit rows in the `grants` table: (subject, permission, scope).
+        - The authorization service NEVER reads `grants` directly. It reads ONLY `grant_view`, a
+          materialized read model derived from `grants`.
+        - `grant_view` is maintained by a projector that reacts to writes made THROUGH the grants API.
+          A grants-API write updates `grants` AND emits a change event the projector consumes to
+          upsert `grant_view`.
+        - Direct SQL writes to `grants` do NOT emit a change event, so they do NOT appear in
+          `grant_view` until a projector rebuild (full re-projection from `grants`) is run.
+        - Role names (editor, viewer, admin) are retained for display only and confer no permissions.
+
+      Schema:
+        CREATE TABLE grants (subject text, permission text, scope text);     -- source of truth
+        CREATE MATERIALIZED VIEW-LIKE grant_view (subject, permission, scope); -- projector output
+      Example rows AFTER a correct grants-API write for admin-01 (both tables in sync):
+        grants:     (admin-01, document.read, global)
+        grant_view: (admin-01, document.read, global)
+      Example rows AFTER the direct-SQL backfill for editor-17 (source only, view missing):
+        grants:     (editor-17, document.read, global), (editor-17, document.write, global)
+        grant_view: <no rows>
+      The projector's only trigger is the grants-API change event. A `rebuild` command re-projects the
+      entire `grants` table into `grant_view` from scratch; it is the supported way to reconcile rows
+      that were inserted out-of-band. Until it runs, out-of-band rows are invisible to authorization.
+  - id: authz-check
+    type: code
+    label: authorization check (enforcement, current)
+    content: |
+      // authz-service/src/check.ts  (enforcement.mode = strict)
+      export async function can(subject, permission, scope) {
+        const rows = await db.query(
+          `SELECT 1 FROM grant_view
+             WHERE subject = $1 AND permission = $2 AND scope IN ('global', $3)
+             LIMIT 1`,
+          [subject, permission, scope],
+        );
+        return rows.length > 0;   // deny if the read model has no matching grant
+      }
+
+      // Called by the document service on every read/write:
+      //   if (!await can(user.id, 'document.read', doc.workspaceId)) throw Forbidden();
+      // NOTE: this query targets grant_view (the projected read model), NEVER the grants source
+      // table. There is no role lookup and no fallback path; an empty grant_view result = deny.
+  - id: deploy-plan
+    type: table
+    label: migration deployment plan and status
+    content: |
+      step  action                                              via              owner       status
+      1     create grants table                                 migration        platform    complete
+      2     deploy grant_view projector (grants -> grant_view)   deploy           platform    complete
+      3     deploy enforcement (authz reads grant_view only)     deploy           authz       complete
+      4     bootstrap admin grants                               grants API       authz       complete
+      5     backfill grants from legacy roles                    direct SQL       data-eng    complete
+      6     rebuild grant_view from backfilled grants rows       projector rerun  data-eng    NOT STARTED (scheduled)
+      # Steps 1-5 are all COMPLETE. Step 6 (the read-model rebuild after the direct-SQL backfill)
+      # was scheduled as a separate job and has not run. It is the only incomplete step.
+  - id: backfill-script
+    type: code
+    label: backfill script (deploy step 5)
+    content: |
+      // scripts/backfill-grants.ts  (ran to completion in step 5)
+      // Reads legacy role_assignments and materializes explicit grants.
+      let inserted = 0;
+      for (const a of await legacy.roleAssignments()) {   // SELECT subject_id, role FROM role_assignments
+        const perms =
+          a.role === 'editor' ? ['document.read', 'document.write'] :
+          a.role === 'viewer' ? ['document.read'] : [];
+        for (const p of perms) {
+          // Direct INSERT into the SOURCE table via the DB connection. This does NOT go through the
+          // grants API, so no change event is emitted and the grant_view projector is never notified.
+          await db.query(
+            `INSERT INTO grants (subject, permission, scope) VALUES ($1, $2, 'global')`,
+            [a.subjectId, p],
+          );
+          inserted++;
+        }
+      }
+      console.log(`backfill complete: inserted ${inserted} grants for legacy editors/viewers, 0 errors`);
+      // The script never calls grantsApi.create(); it writes the source table directly for speed.
+  - id: authz-audit
+    type: log
+    label: authorization decisions and ops reconciliation queries
+    content: |
+      # authorization path (reads grant_view) — sampled after cutover
+      editor-17  action=document.read   source=grant_view rows=0  -> DENY   role=editor
+      editor-17  action=document.write  source=grant_view rows=0  -> DENY   role=editor
+      editor-31  action=document.write  source=grant_view rows=0  -> DENY   role=editor
+      viewer-04  action=document.read   source=grant_view rows=0  -> DENY   role=viewer
+      admin-01   action=document.read   source=grant_view rows=1  -> ALLOW  role=admin
+      svc-88     action=document.read   source=grant_view rows=1  -> ALLOW  role=none
+
+      # ops reconciliation queries (run manually; NOT part of the authz path)
+      ops SELECT count(*) FROM grants     WHERE subject='editor-17' -> 2   # read + write present in SOURCE
+      ops SELECT count(*) FROM grant_view WHERE subject='editor-17' -> 0   # but absent from the VIEW
+      ops SELECT count(*) FROM grants     WHERE subject='editor-31' -> 2
+      ops SELECT count(*) FROM grant_view WHERE subject='editor-31' -> 0
+      ops SELECT count(*) FROM grants     WHERE subject='viewer-04' -> 1
+      ops SELECT count(*) FROM grant_view WHERE subject='viewer-04' -> 0
+      ops SELECT count(*) FROM grants     WHERE subject='admin-01'  -> 1
+      ops SELECT count(*) FROM grant_view WHERE subject='admin-01'  -> 1   # admin present in BOTH
+      ops SELECT count(*) FROM grants     WHERE subject='svc-88'    -> 3
+      ops SELECT count(*) FROM grant_view WHERE subject='svc-88'    -> 3   # API-provisioned; in BOTH
+      # Aggregate: SELECT count(*) FROM grants -> 4120 ; SELECT count(*) FROM grant_view -> 41
+      # The 41 rows in grant_view are exactly the admin/service subjects provisioned via the grants API.
+  - id: migration-ticket
+    type: note
+    label: migration ticket and on-call notes
+    content: |
+      SEC-4400 Migration to explicit grants.
+        - Backfill (step 5) completed successfully: grants inserted for every legacy editor and viewer
+          (see the ops counts in authz-audit and store-state-table). The `grants` source table now
+          holds 4120 rows; only 41 are visible in `grant_view`.
+        - enforcement.mode = strict. A flag `useLegacyRoleFallback` still exists in the OLD gateway
+          config, but it was REMOVED from the authorization service during the enforcement deploy and
+          is now ignored; it can no longer re-derive permissions from role names. Setting it true has
+          no effect on `can()`.
+        - Rollback of enforcement to permissive was considered; it would allow ALL actions (fail-open),
+          so it is only acceptable as short-term containment, not as the fix.
+        - On-call first hypothesis: "enforcement shipped before the backfill (deploy-order inversion)."
+          Recorded at 02:10 before the ops queries returned. Second note at 02:40: "backfill IS done and
+          grants exist — deny persists anyway; revisit against deploy-plan and the source-vs-view counts."
+  - id: store-state-table
+    type: table
+    label: source-vs-view grant reconciliation
+    content: |
+      subject    role     grants_source_rows  grant_view_rows  provisioned_via     authz_result
+      editor-17  editor   2 (read, write)     0                backfill (SQL)      DENY
+      editor-31  editor   2 (read, write)     0                backfill (SQL)      DENY
+      viewer-04  viewer   1 (read)            0                backfill (SQL)      DENY
+      viewer-77  viewer   1 (read)            0                backfill (SQL)      DENY
+      admin-01   admin    1 (all)             1                grants API (boot)   ALLOW
+      admin-02   admin    1 (all)             1                grants API (boot)   ALLOW
+      svc-88     none     3 (scoped)          3                grants API (new)    ALLOW
+      # Every subject provisioned via direct-SQL backfill has source rows but 0 view rows and is denied.
+      # Every subject provisioned through the grants API has matching source and view rows and is allowed.
+      # svc-88 was created via the grants API after cutover and works, isolating the projector path.
+      # The ONLY variable that predicts DENY is provisioned_via = backfill (SQL); role is not predictive
+      # (both admins and editors have source rows; only the API-written ones reached grant_view).
+tags: [authorization, migration, read-model, projection, multi-artifact-synthesis]