« Phase 17 README · Warmup · Hitchhiker's · Deep Dive · Principal Deep Dive · Staff Notes

Phase 17 — Core Contributor Notes: The Enterprise Agentic Platform

This capstone does not mirror a single framework; it mirrors the ensemble of production building blocks that a real enterprise agent platform is assembled from, plus the published reference architectures that constrain how you compose them. The maintainer's-eye view here is: for each miniature stage, what is the real system, what non-obvious decision does its maintainer make, and where does our teaching version deliberately simplify. If you know these mappings concretely, you can defend the platform in front of anyone who has built one.

Identity: OAuth2/OIDC and JWT verification

Our HMAC token is a stand-in for OAuth2/OIDC access tokens, typically JWTs. The real decisions a platform team makes: tokens are short-lived and rotated (minutes, not hours) so a leaked token has a small window; verification is signature-checking against the issuer's rotating public keys (a cached JWKS endpoint) — you validate iss, aud, exp, and the signature, and you never trust a claim you did not cryptographically verify. The tenant identity comes from a verified claim in the token, which is the production form of our "derive tenant from the token, not the body" rule. The sharp edge every implementer hits: clock skew on exp validation, and the temptation to skip audience validation, which turns a token minted for one service into a key for another.

Authorization: policy engines, not if statements

Our RBAC check is a miniature of a real policy engine — AWS's Cedar, or Open Policy Agent (OPA) with Rego. The maintainer-level decision is to externalize authorization into a declarative policy evaluated at request time with default-deny, so that "who can do what" is auditable, testable, and changeable without shipping code. Cedar in particular was designed around being analyzable — you can reason about whether a policy set can ever grant an access — which is the property that matters when a bank asks "prove no policy lets tenant A read tenant B." Our lab collapses this to a role check; the real thing is a policy language with a formally specified evaluation semantics.

Rate limiting, retrieval isolation, and the number-one leak

Our token bucket is the classic algorithm; production runs it as a distributed rate limiter (commonly Redis-backed) so the limit holds across replicas, with per-tenant keys. Our tenant-scoped retrieve is where the real platform's hardest isolation decision lives: production uses per-tenant vector namespaces or indexes plus Postgres row-level security (RLS) on the metadata store, so isolation is enforced by the datastore, not the application. The evolution of this space is instructive — early RAG platforms shared one index and filtered by a tenant_id field in application code, and the recurring, catastrophic incident was a query path that forgot the filter and surfaced another tenant's documents. The industry moved toward namespace-per-tenant and RLS precisely because "isolation enforced by a filter you can forget" is not isolation. AWS's SaaS Lens formalizes the tradeoff as silo vs pool vs bridge (dedicated vs shared vs hybrid tenancy), which is the vocabulary you use to defend where you drew the isolation line.

Guardrails: classifiers plus architecture

Our regex guardrails stand in for Llama Guard and similar safety classifiers — small models trained to flag unsafe or injection-bearing content. The maintainer's honest position, and the one our warmup insists on, is that a classifier is a probabilistic control with a false-negative rate, so it is layered with architectural controls (least-privilege tools, output scanning, sandboxing), never trusted alone. The OWASP Top 10 for LLM Applications is the reference the whole security posture is organized against — prompt injection (LLM01), insecure output handling, excessive agency — and a platform team maps each layer of the lifecycle to the OWASP risks it mitigates. That mapping is what turns "we have guardrails" into a defensible security story.

Evaluation and observability: judges and OpenTelemetry-GenAI

Our is_grounded heuristic is a miniature of an LLM-as-judge evaluation with a human-calibrated golden set and a regression suite in CI — the real quality gate is not a heuristic but a judge model whose agreement with human labels you have measured, run on a sample in production and on the full golden set in CI so a prompt or model change cannot silently regress quality. Our Span dataclass is a miniature of the OpenTelemetry GenAI semantic conventions — the emerging standard for tracing model calls, token usage, and agent steps — exported to a tracing backend, joined to the audit log (metadata only, never secret content, which is what SOC2-grade audit and data-residency controls require). The contributor-level point is that observability and eval are not add-ons; they are the substrate that makes every other layer debuggable and changeable.

What our miniature deliberately simplifies

In descending order of significance: (1) the datastore-enforced isolation — we scope retrieval in application code for teaching clarity; production pushes it into RLS and namespaces so it cannot be forgotten; (2) real cryptographic identity — HMAC instead of OIDC/JWT with rotation and JWKS; (3) probabilistic guards and judges — regex and a heuristic instead of Llama-Guard-class classifiers and a calibrated LLM-judge; (4) durability and sandboxing — a single process instead of durable workflows (Phase 08) and a real sandbox (Phase 09) wrapping the runtime; (5) the distributed reality — one function instead of an API gateway, a policy service, a rate-limit store, a vector DB, a model tier, and a tracing backend. None of these omissions change the thing the capstone teaches: the order of the stages and the boundaries between them. Describe these real systems by their documented patterns; do not invent version numbers or config keys — the reference architectures (OWASP LLM Top 10, AWS SaaS Lens, OpenTelemetry-GenAI) are the sources of truth, and the shape they describe is what survives every re-platforming.