Architecture dossier

Overview

Lex answers a narrow business question: what did this rule say on this date? It turns dated Luxembourg and EU publisher material into article-level research with an official link, an exact version and a verifiable evidence chain. It does not decide legal applicability or advise a reader what to do.

Open the system diagram at full size

The decision a reader can make

The architecture in one sentence

Official publisher records become immutable evidence, deterministic derivations and signed local indexes; one typed legal core serves the UI, MCP and a bounded agent whose model may plan and explain but cannot choose legal identity, dates, evidence or actions.

How to read this dossier

The first four tabs explain the legal and retrieval product. Assistant shows where the agent is useful and where it has no authority. Release shows how evaluated code and data become one rollback-safe revision. The final three tabs expose decisions, incidents and limits instead of hiding them behind a feature list.

The pages describe durable contracts, not a moment in one rollout. Mounted corpus identities, coverage and retrieval capabilities are read from the running revision, while latency, relevance, memory and promotion claims appear only when a signed report binds them to that exact artifact set.

Why this is more than a naive RAG

Lex is retrieval-augmented generation only when the reader asks for prose. Identity resolution, point-in-time selection, retrieval, comparison, citations and direct result cards work without generation. The default result is deterministic. Optional prose receives an already bounded evidence ledger and must bind each claim back to that ledger.

Legal model

The core modeling choice is to keep a law, a dated legal state, a language expression and the publisher file as different things. Collapsing them into one document would make a date lookup ambiguous and make provenance impossible to state precisely.

Open the legal model diagram at full size

FRBR and JOLux shape

The v4 version key is based on the full publisher version identifier, not its position in a list. The key combines valid_from with SHA-256 of that full identifier. A same-day reordering can no longer silently move text from one state to another.

Two clocks, two questions

For Legilux, the date is publisher-asserted legal applicability. For EUR-Lex, it is the state date of the consolidated wording. The UI and API keep those meanings distinct rather than claiming one cross-publisher definition they do not share.

Empty is a modeled outcome

A publisher can announce a state before supplying exploitable wording, or provide a manifestation that the current deterministic profile cannot safely segment. Lex keeps that state and returns a typed availability reason with the official link. It does not synthesize a consolidation or copy text from another date. In this product, an honest gap is useful data.

What stays outside the model

Human-authored aliases, model-inferred classifications and generated legal text do not become corpus authority. Official short titles may identify a work only when the source literal is an exact unique match. Official taxonomies remain discovery metadata and never prove historical applicability or legal wording.

Data authority

The evidence layer is append-only publisher material. The consumption layer is reproducible and disposable. That split lets an extraction improve without rewriting what the publisher served.

Open the data authority diagram at full size

Ingestion and derivation

Official discovery metadata

Luxembourg acquisition mirrors Legilux subjectLevel1 and subjectLevel2 assertions with the concept URI, French label, level, language and source. EU acquisition mirrors official short-title segments, EuroVoc assigned, alternative and broader relations, and directory classifications with their identifiers and source URIs. The two vocabulary systems remain distinct.

These values enter a weak, explainable discovery lane. They may surface a work whose provisions do not contain the query phrase and the result can say which official classification matched. They do not establish legal identity, support a legal claim or become historical evidence. No manual legal alias catalogue and no model-generated metadata enter production authority.

What the cryptography proves

Origin, integrity and release authorization are separate claims. Keeping all three is why a citation can be checked without treating a hash as a magical certificate of truth.

Retrieval

Most apparent RAG hallucinations begin before generation. Lex therefore treats legal identity as an authorization step and ranking as a later discovery step.

Open the retrieval diagram at full size

Retrieval funnel

1. Parse explicit dates, identifiers, article numbers and comparison intent.
2. Resolve the named subject against official work identity before asking the planner.
3. Clarify zero or several credible subjects instead of letting rank silently choose one.
4. Apply publisher, work, language and point-in-time scope.
5. Search article text with FTS5/BM25 by default; official metadata contributes a weaker work discovery signal and an explicit match reason.
6. Deduplicate text states and anchors, apply bounded per-work fairness only for unscoped discovery, then return typed rows and provenance.

There is no generation loop that reads page one, asks the model whether it is satisfied and keeps searching. The application decides the evidence budget before execution. This makes latency, population and failure behavior testable.

Failure taxonomy

Why keyword remains the default

The semantic encoder, local vectors and rank fusion exist, but activation is evidence-gated. Offline signed benchmarks authorize vector mounting during deployment and startup; benchmark logic never switches an individual query. The user or API caller explicitly chooses keyword or hybrid, and an explicit hybrid request receives a typed unavailable result for any publisher whose exact signed candidate did not pass. A compatible signed report binds relevance, latency, memory and size to that candidate before its vectors may mount. Keyword remains the default. A measured rejection is a valid architecture result, not a failed demo.

Assistant

Architectural decision: bounded plan -> validate and correct once -> freeze -> execute. This is ReWOO-inspired reasoning without an observation loop, not adaptive ReAct. Retrieval constrains what the model can know, so exact identity and time resolution happen before planning; the planner proposes a typed operation plan, while application code authorizes, executes and returns the normal cited result.

One bounded turn, time downward

Open the sequence diagram at full size

Boundary at a glance

The canonical LegalOperationCatalog is the shared contract. The planner receives its closed typed schemas but never calls MCP, SQL, vectors or the index. After validation and freeze, the executor calls the deterministic legal core. Public MCP projects the same operations independently for external clients; it is not the assistant's internal transport.

Why this design

The catalog, plan schema, executor, outcomes and evidence contracts are explicit application code; no LangChain or LlamaIndex loop hides chunking, tool selection or retry behavior. The planner cannot observe tool results and replan. The judge verifies only optional generated factual prose; deterministic typed results need no LLM judge.

Control flow

1. The web boundary validates the bounded request, idempotency key and evaluation admission when present, then acquires one server thread lease. Admission applies request ownership, concurrency, daily cost and first-result deadline limits.
2. The thread registry restores at most six accepted turns and deterministic subject context from a SHA-256 token digest. The browser presents the opaque token but owns no durable memory.
3. Subject preflight queries the signed work catalog before the planning model is called. Exact identifiers and exact publisher-provided short titles may authorize a work. Weaker official classifications remain discovery evidence only. Ambiguity is kept as clarification context, never converted into a silently selected law.
4. The bounded planning agent receives the question, bounded history, closed operation schemas and only opaque subject_ref values authorized by preflight. Without authority, work-specific operations receive no subject reference.
5. The canonical plan gate validates operation names and typed arguments. One bounded corrective turn is allowed for a contract-shape error; a second invalid plan becomes a typed invalid request.
6. The plan is frozen at no more than eight operations. There is no model observation or replanning after this point.
7. The shared legal core executes each operation against the signed index and returns a closed outcome, rows, hashes and publisher links. NeedsClarification, legal-boundary and transport gaps stay typed rather than being rewritten as apparent answers.
8. The outcome router builds the normal answer, result cards and citations deterministically. Its evidence ledger is bounded to 64 entries and 96,000 characters.
9. The planner may set synthesis=true only when the reader explicitly asks to explain, describe or summarise the accepted results. There is no hidden UI toggle. For example: "Show Article 6 on 1 Jan 2021 and explain it."
10. Runtime additionally requires no displayed clarification, no NeedsClarification result, no transport failure, and at least one accepted operation that is not an inventory. coverage, cited_by and in_force_on return closed typed lists the deterministic reply already renders in full and carry no publisher text to describe, so the same coverage question once served 294 output tokens and once 4,973 with a composer; the flag is now reconciled against the frozen plan rather than trusted, and never against the reader's words, which quoted content controls. The grounded composer and conditional judge are two separate logical Microsoft Agent Framework agents with separate sessions over the same configured Azure OpenAI chat client and deployment used by Ask. They are roles, not a second deployment or an autonomous observation loop.
11. The composer receives the deterministic draft plus typed evidence and gets at most one format or evidence-contract correction. The judge runs only for Answer or Gap drafts with factual claims, then returns Pass, Repair or Refuse. A synthesis deadline or outage preserves the deterministic verified result.

Authority matrix

Conversation memory

Open the memory boundary diagram at full size

Conversation memory is server-owned and ephemeral: at most 1,024 threads, six accepted turns, 32 KiB per thread, 16 MiB globally, two waiters per thread and a 30-minute idle lifetime. The browser holds the visible transcript and opaque capability in component memory, not local storage. Only the token's SHA-256 digest is retained server-side. Restart, expiry, eviction or reset loses the thread safely; an unknown token never falls through to another conversation.

The public default admits 200 accepted turns per ingress-derived client address and 400 globally per UTC day. Those process-local controls are honest cost and abuse limits, not user identity.

Latest signed assistant evaluation

These hashes intentionally differ: the 40-character Git commit identifies source code; the artifact-set, catalog and report values are separate SHA-256 identities. Verification on this page means the signed report embeds the former identities exactly and its own full digest matches the release tag; it does not rerun or independently rescore the evaluation.

Release

Code, legal data, retrieval artifacts and assistant behavior are one release unit. A deployment is not production merely because a container started.

Open the release diagram at full size

State machine

Why this design? A zero-traffic candidate can be tested against production-shaped services without changing the reader's route. Keeping the exact former production revision makes rollback an identity selection, not a rebuild that might fetch different bytes.

identities != signed_evaluation ? leave_traffic_unchanged : promote_once_and_retain_previous

maxInactiveRevisions is one in steady state and two only while a candidate waits. Azure Container Apps has no supported per-revision delete. An unresolved newer candidate cannot be discarded by lowering the limit without risking the older valid rollback, so cleanup follows identity and creation order rather than age.

Evidence before traffic

The deploy workflow creates a zero-traffic revision from the exact image and signed artifact set, then checks readiness, Model Context Protocol (MCP), Luxembourg and European Union (EU) search. The assistant evaluation binds the frozen cases, candidate, typed outcomes, latency and cost to a signed report under separate project-owner review. Only the traffic workflow may revalidate those records and promote; no automated actor approves its own output.

This page does not hard-code mounted state: runtime evidence supplies the active identities and capabilities. The traffic workflow also requires target and rollback to remain at min=max=1; quotas, idempotency and thread state must be externalized before multiple replicas are allowed.

Release evidence chain

This is the complete continuous integration and continuous delivery (CI/CD) chain at the level where an operator can decide whether traffic is safe. The detailed workflow and script mechanics stay in the linked runbooks rather than being copied into this dossier.

Status legend: Built means the implementation and deterministic tests exist; Measured means the named frozen artifact or result was reproduced; Quarantined means activation is denied by its gate; Next means exact-release evidence or an operator action is still outstanding. These labels describe the evidence cited here, not a claim about an uninspected live revision.

The offline retrieval benchmark and live assistant evaluation answer different questions. The first uses 200 fixed judgments and deterministic metrics to decide whether hybrid retrieval may activate; it does not call an answer model or a model grader. The second uses 25 natural-language cases against the real Azure-backed candidate and a separately authenticated release grader to test planning, typed execution and bounded final responses.

Why this design? Keyword retrieval remains the production default because a semantic model is a release artifact, not a configuration preference. Hybrid mounts only when the exact signed database, vectors, encoder and benchmark evidence pass together; a failed or missing result keeps the capability quarantined without weakening deterministic search.

Why this design? Every stage pins exact commits, digests and byte lengths because a tag, cache hit or protected branch can move after a build starts. Navigation may follow main; release authority comes only from the immutable identities recorded in signed evidence.

One article, followed end to end

This is the whole claim of the product in one table. It follows a single provision, Article 6 of the General Data Protection Regulation, from the bytes the publisher served through to the citation the interface renders. Every step carries the SHA-256 of what it produced, so any link in the chain can be recomputed instead of believed, and the right-hand column states what that step does not prove.

It was reproduced from the frozen EU database whose file SHA-256 is f827e089bddff64709926af4341bc0ddbfbef829a5c3e29400754aec3b649fd9. It is measured local evidence for that exact build, not a claim about any signed release.

Assistant evaluation gate

Evaluation flow

Server-Sent Events (SSE) carry the versioned intermediate contract; the equal terminal object is the authoritative completed response.

Question -> resolve identity -> Plan once -> validate or correct once -> freeze -> execute typed tools -> typed SSE and terminal result -> optional runtime prose check -> deterministic release checks -> separate release grade -> signed promotion gate

Why this design? One bounded correction recovers a malformed plan before it can touch legal tools, while the freeze prevents a model from adapting its legal request after seeing results. This keeps planning useful without creating an observation-driven agent loop.

plan = validate(first_proposal) ?? validate(one_corrected_proposal)
freeze(plan); execute_in_user_order(plan) // no observation, no replan

The Runtime grounding judge checks only optional generated factual prose during an ordinary request and falls back to the typed result. The separate Release grader receives the frozen question, rubric, bounded reply, typed operations and trace. Before grading, the deterministic runner checks tool arguments, legal and transport outcomes, UI effect, model identity, tokens, latency and stream equality. It reads typed SSE plus the matching terminal object—not Azure logs or model chain-of-thought—and the signed report omits prompts, legal text, raw tool payloads and free-form grader reasons.

Verified limits

These are present release boundaries, not generic risks. A limit stays visible until the named evidence exists; a model answer cannot waive it.

Operational thresholds are detailed under limits and scale, retrieval activation under local hybrid retrieval, dated gaps under known defects, and permanent guards derived from failures under incidents.

Container registry and Blob retention

The Azure Container Registry is shared and still has a legacy role-based access control (RBAC) boundary. Broad digest deletion is rejected because Lex cannot prove that another application does not pull a digest. The clean target is a dedicated registry or an audited move of every shared consumer to repository-scoped attribute-based access control (ABAC) and managed identities; only then can an exact-digest allowlist become an automated deletion plan.

Private Azure Blob staging objects have a narrower ownership proof. They are disposable coordination records, not the canonical release. The publisher may delete only the exact create-only staging names it created, with matching ETags, after the GitHub Immutable Release assets and signature have been downloaded and matched by hash and length, or after a failed draft has been reconciled. Canonical GitHub release tags and assets are outside Blob cleanup entirely. Moving the canonical boundary to Azure immutable write-once, read-many (WORM) storage is a future option only when retention or compliance requirements justify a separate architecture decision and migration evidence.

Mounted release evidence

The release model above is the invariant. This table reads process configuration and verified mounted indexes at request time. It reports the revision's identities and capabilities; signed promotion receipts separately prove whether traffic was authorized.

Mounted index identities

Mounted total: 2,652 works and 7,022 dated versions. Artifact verification remains a distinct job on Verify artifacts.

Trade-offs

An architecture decision is useful only when it names the alternative, the reason and the cost. The complete machine-readable register is rendered at Architecture decisions. This page is the interview path through the choices with the largest product consequences.

Three decisions to challenge

Why no ReAct loop? The measured dangerous failures were identity and evidence failures. Letting a model observe a deterministic refusal and try a different law can convert an honest gap into a plausible answer. One correction before execution fixes contract syntax without changing authority.

Why build semantic retrieval and leave it off? Because architecture is a reversible hypothesis. The vectors and encoder prove the path can run; the frozen holdout decides whether it should serve. The next activation can be category-specific rather than a global switch.

Why not unify taxonomies? EuroVoc and Legilux classifications have different authorities, languages and semantics. Preserving the source scheme makes a match explainable. A unified label would be a new assertion owned by Lex and would need its own governance and evaluation.

Why is the legislative history not the git log? Because they answer different questions. The corpus tree carries what the law said and when it said it, which is the publisher's timeline. The commit history carries when Lex observed and wrote it, which is ours. Collapsing them would be convenient and wrong: re-ingesting a work would appear to amend it, a correction we fetched late would date from the day we noticed, and no reader could separate a change in the law from a change in our knowledge of it. Keeping both axes is what makes a point-in-time answer defensible and a publisher correction visible as its own event rather than a silent overwrite.

Status vocabulary records implementation maturity, not current traffic: shipped means included in the release line, gated means activation still depends on evidence, and planned means no product claim yet. Mounted identities and signed promotion receipts separately establish what a running revision serves.

The decisions above are the ones worth arguing with. The complete register, every decision from D1 onward with its rejected alternative and admitted cost, is in the specification; this page does not reprint it, because a register nobody finishes reading persuades nobody.

Incidents

The useful story is not that a defect existed. It is which assumption failed, why ordinary tests missed it and which permanent guard changed the system.

Open the incident-learning diagram at full size

Case studies

The retrieval lesson

The CRR/EMIR case adds a failure class to the usual RAG discussion: right passage, wrong instrument. A groundedness judge cannot detect it because the generated sentence is faithful to the evidence it received. The control must sit earlier, at subject identity, and the answer must name the selected instrument so a reader can see the decision.

Incident template

Every new entry records symptom, business effect, detection, why it survived, root cause, fix, guard, deliberate-break proof and residual risk. That format prevents a postmortem from becoming a timeline without an architectural consequence.

Limits and scale

Scale decisions are tied to observable triggers. The system stays simple while the current bottleneck is bounded, and each next move names the capability it buys and the complexity it adds.

Open the scale diagram at full size

Current boundaries

Fresh v4 relevance, latency, memory, coverage and cold-start measurements are pending the exact candidate promotion. Older figures are historical observations and are not presented as current.

Triggered next moves

Known limitations that matter to a reader

• Some official states contain no safely extractable wording; they remain explicit gaps.
• Provision extraction quality has a historical empty-text backlog. The additive Memorial v2 profile is shipped in code, while the refreshed corpus measurement waits for the v4 ingestion.
• EU citation edges and amendment relations are not yet a complete query surface.
• MCP comparison identifies changed states but does not yet return every provision-level text diff.
• Production diagnostics are sanitized but not all are correlated end to end by request id.
• Shared ACR cleanup remains inventory-only until registry ownership is isolated or audited.

The detailed and dated backlog lives in known defects on GitHub. Deliberately absent: generated consolidation, model-derived legal identity, silent taxonomy merging, unbounded replanning and a framework rewrite.

Delivery registry

The target path is reviewed EU scope, official dated expressions, content-addressed text states, FTS5 keyword candidates plus local compact semantic candidates, temporal and hierarchy eligibility, fixed rank fusion, and the same typed result contracts. A capability is not described as live until its registry status and release evidence agree.

Program hybrid-eu/1, updated 2026-08-14, review status engineer-reviewed.

Repositories

Lex is five published repositories, not one. The split is deliberate: publisher evidence, the derived dataset, the product and the authority that signs releases have different lifetimes, different licences and different people who may write to them.

What is published

Why the product repository holds no data

The corpus is evidence and the index is a build output, so neither belongs beside the code that reads them. The index is roughly 947 MB, is gitignored, and is baked into the container image at build time. A container built from this repository alone therefore mounts zero indexes and must answer no_corpus_mounted rather than an empty list, which is the difference between saying nothing is held and saying nothing exists.

Working directories that are not repositories

Several sibling directories look like repositories and are not. Four are git worktrees of lex checked out on feature branches, so their contents are branches of the product, not separate history. Two more are local build outputs with no remote: one holds a built index database, the other holds compressed provision exports. None of the six is published, and none should be cited as a source.

Separation of authority

The evaluation that gates a release is authored in lex and published from lex-ops, by a different identity, against a catalog whose exact bytes the project owner has signed. That is separation from the catalog author, not third-party review or external audit, and the release page states it in those terms. The same boundary is why the signing key sits in the operations repository and the product repository can neither read nor produce a signature.