## Policy Store ↔ Policy Engine interface — 19.3 delivery plan Working plan for the **Store ↔ Engine Interface** workstream from the [19.3 Policy Engine planning issue](https://gitlab.com/gitlab-org/gitlab/-/work_items/607663): #607650 (trigger-based fetch) + #607657 (enforcement modes). DRI @arfedoro, with @imam_h. > **Architecture update (@mcavoj, Slack):** the lookup lives **in GLAZ** — the engine fetches policies from the Policy Store **via REST**. The `Gitlab::PolicyEngine.policy_lookup` port constraints on #604407 date from the earlier sandbox-gem design and are **outdated**; #604407 needs a rewrite. > > **Update 2026-08-06:** @mc_rocha [confirmed the direction](https://gitlab.com/gitlab-org/gitlab/-/work_items/608189#note_3653937257) — the scope key is **`organization_id`** (0b resolved: "back to organizations" after the CD meeting) and the store's engine-facing API is being built in #606971 (URLs pending naming discussion; the API will be aligned with this plan). The mock signature `lookup(trigger, organization_id)` is the final one. ### Definition of delivered - [ ] GLAZ fetch/evaluate keyed on `trigger`, callable from Ruby (#607650) - [ ] `evaluate` response carries `enforcement_mode`, with mode-compatible actions and the placement decision documented (#607657) - [ ] Interface doc #604407 matches the shipped signature - [ ] The prototype gate (!246660) can replace its `Gitlab::Glaz.evaluate_rego` stub with the real call — unblocking the 19.4 experiment (&22027) --- ## 1. Where this workstream sits in epic &22027 The highlighted node is this workstream — the narrowest in the epic (two issues, M), but the connector every store↔engine interaction passes through. ```mermaid flowchart TB subgraph PM["Policy Management team — #606247"] store["Store CRUD + REST API<br/>prototype !246660"] fe["Frontend policy editor"] ux["Enforcement-mode UX<br/>#604288"] contract{{"Interface contract #604407<br/>DRI @mc_rocha"}} end subgraph PE["Policy Engine team — #607663"] cdval["CD use-case validation · L<br/>#607649 #607656 #607659<br/>@mcavoj @bauerdominic"] iface["Store ↔ Engine Interface · M<br/>#607650 + #607657<br/>DRI @arfedoro, @imam_h"] evale["Evaluation engine · M<br/>#607652 #607653 #607655<br/>@imam_h @mcavoj"] labkit["Labkit::Policy · M<br/>#607651 · @bauerdominic"] end subgraph CDT["CD team — epic 21475"] ctx["Deployment context + gate hook"] beta["19.4 closed beta"] end store -- "policies via REST (rego + mode + actions)" --> iface contract -. "defines the seam" .-> iface ux -. "mode semantics" .-> iface ctx -- "evaluation context" --> iface iface -- "decisions + enforcement_mode" --> labkit iface -- "evaluate call" --> cdval evale -. "same proto surface" .-> iface labkit --> beta cdval --> beta classDef mine fill:#fff1f0,stroke:#d1242f,stroke-width:3px,color:#82071e; classDef dim fill:#f6f8fa,stroke:#b6bec8,color:#57606a; class iface mine; class store,fe,ux,contract,cdval,evale,labkit,ctx,beta dim; ``` ## 2. Delivery graph — repos as lanes, critical path in thick arrows ```mermaid flowchart LR subgraph DEC["Decisions & contracts"] d0{{"STEP 0 · decisions<br/>0b resolved: organization_id"}} d6{{"STEP 5 · docs<br/>#604407 rewrite — port constraints outdated"}} end subgraph GLAZ["gitlab-org/auth/glaz · Rust — the engine AND the lookup owner"] p1["STEP 1 · MR 1<br/>evaluate(trigger, scope) +<br/>PolicyLookup trait + mock · #607650"] p3a["STEP 3 · REST lookup client<br/>auth · cache · failure mode"] p4["STEP 4 · MR 4<br/>enforcement modes · #607657"] end subgraph GEM["gitlab-glaz gem · Ruby↔Rust"] p2["STEP 2 · MR 2<br/>bindings + 5-platform release"] end subgraph MONO["gitlab · monolith"] p3b["STEP 3 · gem bump +<br/>call Gitlab::Glaz.evaluate — no adapter"] g3["Store REST API<br/>#606971 · Policy Mgmt"] end subgraph HAND["Hand-off"] p5["STEP 5 · wire prototype<br/>!246660 stub → real call"] goal(("19.4<br/>unblocked")) end d0 ==> p1 ==> p2 ==> p3b ==> p5 ==> goal p1 --> p3a p3a --> p3b p3a -. "consumes policy endpoints" .-> g3 p3a --> p5 p1 --> p4 p4 --> p5 p4 --> d6 d6 --> goal g1["#607653 / #607655<br/>@imam_h"] -. "align proto naming" .-> p1 p4 -. "stable gating flag" .-> g2["#607651 Labkit<br/>@bauerdominic"] classDef mine fill:#fff1f0,stroke:#d1242f,stroke-width:3px,color:#82071e; classDef ghost fill:#f6f8fa,stroke:#1f75cb,stroke-dasharray:5 4,color:#57606a; classDef goalc fill:#2a78d6,stroke:#2a78d6,color:#ffffff; class d0,p1,p2,p3a,p3b,p4,p5,d6 mine; class g1,g2,g3 ghost; class goal goalc; ``` **Why this exact order (each arrow is a physical constraint):** the proto encodes the step-0 agreement → the mock `PolicyLookup` makes the branch self-sufficient (CD tests without the store) → Ruby can only bind Rust that exists → the monolith can only bundle a *released* gem (five platform builds — the long pole, start it on "proto stable") → the REST client swaps in behind the same trait once the store's endpoints (#606971) exist — the scope key is already settled → mode metadata rides those rails → the prototype swapping its stub is the proof, and the finish line. ## 3. The target call chain (runtime view) ```mermaid sequenceDiagram participant Gate as CI deployment gate<br/>(ProcessBuildService) participant Labkit as Labkit::Policy<br/>(#607651) participant GLAZ as GLAZ engine<br/>(via gitlab-glaz gem) participant Store as Policy Store<br/>REST API (#606971) Gate->>Labkit: can this deployment proceed? Labkit->>GLAZ: evaluate(trigger, scope, context) GLAZ->>Store: GET policies?trigger=…&organization_id=… Note over GLAZ,Store: lookup lives IN GLAZ (PolicyLookup trait):<br/>mock first, REST client later —<br/>auth, cache, failure mode = step 3 scope Store-->>GLAZ: policies[ rego, enforcement_mode, actions ] GLAZ-->>Labkit: decisions[ matched, reasons,<br/>mode-compatible actions, enforcement_mode ] Note over GLAZ: matches actions to mode,<br/>never routes on it Labkit-->>Gate: actions to execute (mode handler routes) ``` ## 4. Timeline ```mermaid gantt dateFormat YYYY-MM-DD title 19.3 — three weeks, five MRs section Decisions STEP 0 lock decisions (mc_rocha, imam_h) :d0, 2026-08-04, 4d escalation checkpoint :milestone, 2026-08-11, 0d section auth/glaz STEP 1 MR1 proto + evaluator :p1, 2026-08-05, 6d STEP 4 MR4 enforcement modes :p4, after p1, 5d section gitlab-glaz gem STEP 2 MR2 bindings + release (long pole) :p2, 2026-08-10, 7d section monolith STEP 3 MR3 REST lookup + gem bump :p3, after p2, 4d section Hand-off STEP 5 wire prototype + docs :p5, after p3, 4d ``` ## 5. Guided sequence <details><summary><b>STEP 0 — Lock the decisions — 0b resolved (scope key = organization_id)</b></summary> Where: #607650 + #604407 + this issue · With: @mc_rocha, @mcavoj, @imam_h **0a — remaining:** - [ ] **Lookup ownership — settled:** the lookup lives **in GLAZ**; the engine pulls policies from the Policy Store **via REST** (@mcavoj). Implicitly acked by @mc_rocha ([2026-08-06](https://gitlab.com/gitlab-org/gitlab/-/work_items/608189#note_3653937257): "to get the policies, we would need `trigger` and `organization_id`… adjust our API accordingly"). Remaining action: write the model on #604407 for the paper trail (its `policy_lookup` port constraints are outdated — pre-GLAZ sandbox-gem design). - [ ] **Mode enum:** three modes (`audit`/`warn`/`enforce`) per the promotion-ladder direction ([Grant's note](https://gitlab.com/groups/gitlab-org/-/work_items/22027#note_3638260221)), encoded extensibly — final UX with Michael - [ ] Post the proto sketch as a comment on #607650 **0b — ✅ resolved (2026-08-06):** - [x] **Scope key = `organization_id`** — the CD meeting landed "back to organizations" ([@mc_rocha](https://gitlab.com/gitlab-org/gitlab/-/work_items/608189#note_3653937257)); lookup is `trigger` + `organization_id`, exactly the mock's signature, so nothing needs swapping later - [ ] Store API endpoints in #606971 — naming/URLs pending, @mc_rocha will share and align the API with this plan - [ ] Feed `organization_id` into #607652 (scope evaluation) and the `input_json` context shape (#607655) **Nothing blocks STEP 1** — and its mock signature is now the final one. STEP 3 waits only on #606971's URLs. </details> <details><summary><b>STEP 1 — MR 1: evaluate signature + mock lookup (auth/glaz, Rust — feature branch, start now)</b></summary> Per @mcavoj's suggestion this starts immediately on a feature branch — the mock makes it self-sufficient, and **CD can test from the branch** without waiting for the store. - [ ] New `evaluate(trigger, scope, input)` signature replacing the `policy_rego`-keyed one, in `crates/glaz-proto/govern.proto` + evaluator - [ ] **`PolicyLookup` trait with a mock implementation** returning canned policies for `lookup(trigger, organization_id)` — confirmed as the final key by 0b; the trait is the permanent seam: mock now, REST client in step 3, no caller changes between them - [ ] Batch evaluation loop in `crates/glaz-govern` reusing the single-policy evaluator (64 KiB / 1 MiB caps stay per policy) - [ ] FFI entry point in `crates/glaz-module/src/govern.rs`; old single-policy message stays - [ ] Message naming agreed with @imam_h so #607653 `validate` + #607655 context schema extend the same surface Done when Rust tests cover trigger echo, batch, caps, empty batch, mock lookup — and CD confirms the branch works for their testing. </details> <details><summary><b>STEP 2 — MR 2: bindings + release (gitlab-glaz gem — the long pole, start on "proto stable")</b></summary> - [ ] Bump pinned GLAZ `rev` in root `Cargo.toml` - [ ] Bind `GovernPolicyEngine` in `ext/glaz/src/lib.rs` (magnus, follow `PermissionCheckEngine` pattern) — the govern path has **no Ruby binding today** - [ ] Regenerate `lib/proto/*_pb.rb`; add `Gitlab::Glaz.evaluate(trigger:, policies:, input:, data: nil)` - [ ] Cut release (native builds × 5 platforms) Done when gem specs are green on all platforms and the release is published. </details> <details><summary><b>STEP 3 — MR 3: swap the mock for the REST lookup (GLAZ client + monolith bump)</b></summary> Waits only on #606971's endpoint URLs — the scope key is settled (`organization_id`, same as the mock), which is exactly why the mock went first. - [ ] REST implementation of the `PolicyLookup` trait in GLAZ: HTTP client calling the Policy Store's policy endpoints (built in #606971; @mc_rocha shares URLs once naming settles); mock → REST behind the same trait, callers untouched - [ ] The old #604407 questions become **implementation scope here**: how GLAZ authenticates to the REST API, cache/invalidation, fail-open vs fail-closed when the store is unreachable — decide small, document on #604407 - [ ] Monolith side shrinks to: bump `gem 'gitlab-glaz'` (`Gemfile:84`) and call `Gitlab::Glaz.evaluate` — **no `Gitlab::PolicyEngine` adapter/port** (that concept died with the sandbox-gem design) Done when the gate can evaluate against real store policies end-to-end (mock retired, or kept only for tests). </details> <details><summary><b>STEP 4 — MR 4: enforcement modes ride on top (#607657, all three repos, small)</b></summary> - [ ] `enforcement_mode` on each **decision entry** (not top-level — a batch spans policies in different modes); rationale on #607657 - [ ] Mode–action compatibility matching per [Martin's note](https://gitlab.com/gitlab-org/gitlab/-/work_items/607657#note_3640408812): return only actions valid for the mode (`require_approval` → enforce only). One small isolated mapping — action names may still change - [ ] Engine *matches* actions to mode, never *routes* (routing = monolith handler, #604288) Done when mode flows end-to-end, console-verifiable. </details> <details><summary><b>STEP 5 — Hand off and close the loop (week 3)</b></summary> - [ ] Replace the prototype gate's stub with the real call (with @Andyschoenen, !246660) - [ ] Update interface doc on #604407; feed the transport/push-pull ADR with the implementation's actual assumptions - [ ] Confirm with @bauerdominic that Labkit's `gating` flag reads cleanly off mode-matched actions Done when all four "delivered" checkboxes at the top are checked. </details> ## 6. Repositories | Repo | Role | Files touched | |---|---|---| | [`gitlab-org/auth/glaz`](https://gitlab.com/gitlab-org/auth/glaz) | the engine **and the lookup owner** — steps 1, 3 & 4 | `crates/glaz-proto/govern.proto`, `crates/glaz-govern/src/evaluator.rs`, `crates/glaz-module/src/govern.rs`, `PolicyLookup` trait (mock + REST client: auth, cache, failure mode) | | [`gitlab-org/ruby/gems/gitlab-glaz`](https://gitlab.com/gitlab-org/ruby/gems/gitlab-glaz) | the bridge — step 2, schedule long pole | `Cargo.toml` (rev pin), `ext/glaz/src/lib.rs`, `lib/gitlab/glaz.rb`, `lib/proto/*_pb.rb` | | [`gitlab-org/gitlab`](https://gitlab.com/gitlab-org/gitlab) | the consumer — steps 3 (bump) & 5 | `Gemfile:84`, callers use `Gitlab::Glaz.evaluate` directly (no adapter layer), `ee/app/services/ee/ci/process_build_service.rb` (step 5 swap) | **Explicitly out of scope here:** store CRUD + the REST endpoints the lookup consumes (Policy Management, !246660) · mode routing & action execution (#604288 handler) · `lib/authz/glaz/permission_check.rb` (Cedar path, same gem, different engine) · the #604407 rewrite itself (@mc_rocha — we feed it the new model).