Janus — the decision engine that lets a model advise without taking the wheel

Janus — the decision ledger: one row per evaluated request, its directive, the matrix row that fired, and what the execution fabric did with it

Directive per request, always

Matrix rows — every case covered

Actions Janus executes

The Problem

Every agentic system eventually has to answer one question: how do you let a model take part in a decision without letting it take the wheel? The common answers put the model in the driver's seat and bolt checks around it — a guardrail on what it says, a human interrupt before a tool call, a trace to read afterwards. The model still picks the action; the system hopes to catch a bad pick.

Janus inverts that. It is a decision authority with two faces: one reads the request — a persona, an event, the caller's state — and the other reads versioned policy. Exactly one directive comes out: ADVISE, ACTIVATE_SHARD or REQUEST_INPUT. Janus executes nothing, stores nothing and ships no model adapter. What happens next belongs to a different system, which has to be convinced separately.

Janus Decides. Fabric Acts.

The boundary is the design. Janus owns the decision schemas and the policy records. The execution fabric owns tickets, scopes, timeouts and outcomes. Neither can do the other's job, and the contract between them is a versioned set of JSON Schemas, not a shared codebase.

Ownership diagram: Janus owns decision schemas and policy; the execution fabric owns tickets, timeouts and outcomes; the model port, the trusted caller, the shard and the provider layer sit outside both — Who owns what. The calling runtime asks Janus for a directive; only an `ACTIVATE_SHARD` directive ever crosses to the fabric, and it crosses with the caller's *separately authenticated* context — grants and authority Janus never sees. In the demo's governed path the shard is `lead.crm`, which pushes through Aether SDK.

Two Things a Policy Engine or a Guardrail Doesn't Put in One Place

Open Policy Agent and Cedar set the bar for policy as a versioned, validated, reviewable artifact. Guardrail libraries bound what a model may say. Agent frameworks trace what an agent did and let a human interrupt it. Janus matches that table — per-decision explanations, offline validate / diff / scaffold for policy, fail-closed defaults — and the demo carries two workflows that are the reason it exists.

The governed path. A lead.received event under an action policy. Six pre-matrix checks run in order — policy, identity and context, event, route, continuation, input projection — and any failure stops the evaluation before a model is ever called. Then the outcome matrix: route × model participation × model result, eleven rows, total. The model's candidate is one bounded input to that table; the route and the action policy fix the shard, the action and the inputs. A model that is unavailable under advisory participation changes nothing. A missing tenant_id becomes REQUEST_INPUT, naming the field.
The actionless Advisor. A persona whose policy has no route and no ACTIVATE_SHARD in its allowlist. It requires a model and holds its candidate to a minimum confidence; below the bar, it asks for input instead. A model candidate that "wants" an action changes nothing — not because a filter caught it, but because there is no row in the matrix that could produce one for this persona. It can only advise, structurally.

Sequence diagram of the governed path: request, allowlisted inputs to the model port, a bounded candidate back, exactly one directive, then the fabric's least-authority ticket, the shard's provider call and a correlated outcome — The governed path, end to end. Three identifiers tie it together — request, directive, ticket — and the protocol states the equalities that must hold between them, so an outcome can always be walked back to the request that caused it.

The Ticket Is Someone Else's Decision

An ACTIVATE_SHARD directive is a request, not a permission. The fabric re-derives everything it needs from the directive, the action policy the directive references, and the caller's trusted context — and rejects from a closed list of codes if anything disagrees: an unknown policy, a policy version mismatch, inputs the policy does not allow, a caller context that does not match the request.

When it does issue a ticket, the ticket carries exactly the scopes the action policy requires — never the caller's full grant set — under the policy's maximum authority level and timeout. A caller missing one required scope gets missing_trusted_scope and no ticket at all. The system that decided and the system that authorized share a contract and nothing else; compromising one does not hand you the other.

Continuations Carry Nothing

When Janus asks for input it returns a continuation the caller holds. It is stateless correlation, and the doctrine is blunt about what it is not: no authority, no expiry, no single-use guarantee, no replay protection — those belong to the caller. It is safe anyway, because a continuation grants nothing: the follow-up is a complete request, and every check runs again against the current policy version. An edited continuation fails its own content-derived id; a stale one fails closed with no replacement. The demo lets you tamper with one and watch.

Lifecycle diagram: request, six pre-matrix checks, at most one model call, the eleven-row outcome matrix, then one of three directives; a failed check or a need for input leads to REQUEST_INPUT and a caller-held continuation that returns as a later complete request — One evaluation. Every path ends in exactly one of three directives; a failed check never reaches the model; the continuation loops back as a whole new request rather than resuming anything.

Architecture

Request       DecisionRequestV2 — persona + policy ref · event · caller state
          ↓
Pre-matrix    policy → identity/context → event → route → continuation → input projection
              any failure: fail closed — no model call
          ↓
Model port    participation: none | advisory | required · at most one call
              allowlisted inputs out · a bounded candidate back · adapter is external
          ↓
Outcome       route × participation × model result → 11 rows, total
matrix        the model is an input to the table, never the selector
          ↓
Directive     exactly one: ADVISE · ACTIVATE_SHARD · REQUEST_INPUT (+ caller-held continuation)
  ─ ─ ─ ─  the boundary — a versioned contract, no shared code  ─ ─ ─ ─
Fabric        directive + trusted caller context → closed rejection list
              or a ticket: scopes = the action policy's required scopes, exactly
          ↓
Shard         runs under the ticket, inside its timeout → correlated OutcomeV2
          

Built Like a Product

The engine is a typed Python library and CLI — Pydantic models over JSON Schema contracts, policies as versioned data files, structured logs — released as v2.1.0 with wire schema 2.0. It carries 2,466 tests, including a suite that builds the wheel, installs it into a fresh environment and proves the public decision surface works from the installed artifact alone, with an import guard that fails the run if anything undeclared is reachable.

pytest main @ 35695df · 2026-09-21 2463 passed · 2 skipped · 1 blocked on this workstation — 2466 collected the blocked test is the fresh-wheel isolation check refusing a machine that also holds a development install: "non-fresh Janus origin" — the guard doing its job janus policy --help validate Validate one canonical policy directory. diff Compare two canonical policy directories. scaffold Emit one canonical policy scaffold without writing it.

The cockpit is an invented operator surface over a documented contract — the engine has no UI and keeps no history — so every screen traces to a contract artifact, and the ledger is framed as the fabric's history, not Janus's. Its fixtures are not typed in: each ledger row is produced by running a JavaScript port of the outcome matrix and the fabric's ticket derivation, and unit gates hold the protocol's equalities — one directive per request, a fabric result only beside an activation, ticket scopes equal to the policy's. It ships behind lint, those gates, a WCAG contrast gate over both themes, and phone, tablet and desktop sweeps in portrait and landscape that a desktop layout squeezed onto a phone is proven to fail. The phone is a separate companion — what needs attention, one decision's story, the Advisor — with policy authoring marked desk-only rather than squeezed.

Access: the live demo is a frontend-only cockpit on mock data — the cockpit, not the engine. The decision engine, the execution fabric and the policy records are private codebases, available to walk through in a working session. Janus ships no model or provider adapter; the model port in the demo is a scripted stand-in, and says so.