feat(aiac/phase-3): Knowledge-base-backed onboarding — searchable policy replaces the single document

[oblinder]

Parent

Sub-issue of the AIAC epic — #643.

Depends on

• Phase 2 — feat(aiac/phase-2): Platform integration — live onboarding trigger + live enforcement #646 complete and merged.

Summary

Replace the single written policy document with a searchable knowledge base. The same UC-1
onboarding proven in Phase 2 now reads its policy from the knowledge base instead of a file, so the
policy can be updated and queried live. The access decisions AIAC produces are unchanged; only
where the policy comes from changes.

Goal

UC-1 onboarding runs against a live, queryable policy source: ingesting the policy into the
knowledge base and onboarding the services yields the same rules and the same enforcement
behavior as Phase 2's written-document run.

Scope / Out of Scope

In scope

• A searchable knowledge base for the policy — a vector store that holds the access-control
  policy, plus an ingest capability that accepts a policy document and stores it as searchable
  content.
• Sourcing policy from the knowledge base during onboarding — instead of reading a single file,
  the agent queries the knowledge base for the policy relevant to the entity it is onboarding and
  models access from what it retrieves.
• Preserving the onboarding flow — the classify, discover, provision, model, and emit sequence
  and the resulting rules are unchanged from Phase 2; only the policy source is swapped, so the
  behavior stays identical.

Out of scope

• UC-2 (Policy Update) and UC-3 (Role Update) — reacting to policy or role changes. (Phase 4.)
• Changes to onboarding logic or to the rule/enforcement shape — only the policy source changes.

Future work

• Showcasing the outbound agent-role gate needs a second tool the agent isn't mapped to.
  Deferred to a future extended demo.

---

Demo

Scenario

Same as Phase 2 — github-agent, github-tool, and users dev-user (developer), test-user
(tester), devops-user (no access) — but the policy now lives in the knowledge base.

Part 1 — Offline: model the access control (ingest → query → rules)

1. Ingest the policy document into the knowledge base, which stores it as searchable content.
2. Register the tool and agent clients (as in Phase 2). The live trigger path drives AIAC to
   onboard each service — but now, instead of reading a file, AIAC queries the knowledge base
   for the policy relevant to the entity it is onboarding, models access from what it retrieves, and
   writes the inbound and outbound rules to the enforcement layer's policy resource.

sequenceDiagram
    actor Operator
    participant Ingest as Policy Ingest
    participant KB as Knowledge Base
    participant IdP as Identity Provider
    participant Bus as Event Broker
    participant AIAC as AIAC Agent
    participant Policy as Enforcement Policy resource
    Operator->>Ingest: Ingest the policy document
    Ingest->>KB: Store policy as searchable content
    Operator->>IdP: Register github-tool and github-agent clients
    IdP-->>Bus: client-created events
    Bus->>AIAC: onboard services
    AIAC->>KB: Query for policy relevant to this entity
    AIAC->>IdP: Provision scopes and roles and wire token exchange
    AIAC->>AIAC: Model access from the retrieved policy
    AIAC->>Policy: Write inbound and outbound rules

Loading

Part 2 — Online: enforce and validate (live request flow)

Identical enforcement behavior to Phase 2 — the knowledge-base swap is transparent to the
enforcement layer.

Request	Inbound	Token carried onward to github-tool
dev-user → github-agent	✅	source-read, source-write, issues-read
test-user → github-agent	✅	issues-read, issues-write
devops-user → github-agent	❌	none
dev-user → github-tool directly (no agent)	❌	none — no direct user→tool access

Outbound rule: an operation is allowed only when it is both in the user's permitted tool
operations and in the agent-role's tool scopes (an intersection). The agent holds all of
github-tool's scopes here, so this demo exercises the user-gating dimension only (see
Future work).

---

Acceptance criteria

• The searchable knowledge base and the ingest capability are deployed; ingesting a policy
  document makes it queryable.
• During onboarding, AIAC reads its policy from the knowledge base (querying per entity)
  rather than from a file.
• The generated rules — and the enforcement matrix above — are the same as the equivalent
  written-document policy from Phase 2.
• A policy-update event emitted when a document is ingested is received but ignored (no
  handler yet — that arrives in Phase 4); nothing errors.
• UC-2 and UC-3 handlers are not wired; policy-update and role-update paths are not
  activated.