# Governed Corpus Runtime And Context-As-Code Storage Model V01

Issue: #196

## Decision

The source-grounded assistant work is a governed corpus runtime pattern, not a generic chatbot, not a default vector-store RAG stack, and not a black-box enterprise copilot.

Core thesis:

```text
Corpus as code
  + generated reader surfaces
  + assistant-ready package
  + explicit source boundary
  + deterministic refusals
  + validation receipts
  + human-reviewable provenance
```

For finite, governed, high-value corpuses, context-as-code is the product-core storage model. The authoritative package starts as reviewed files, manifests, source maps, hashes, and receipts that humans can inspect in Git. Additional databases, search indexes, vector stores, object stores, graph databases, and enterprise front doors are optional derived or runtime layers. They should be introduced only when lifecycle, scale, permission, retrieval, or relationship problems justify them.

This does not claim files replace every database or retrieval architecture. It claims the default product core for governed corpuses should preserve source authority, citation identity, reviewability, deterministic package generation, refusal behavior, and validation evidence before adding opaque retrieval or app-state infrastructure.

## Product Category

Use these product-category terms when describing this pattern:

- governed corpus runtime
- corpus-as-code product architecture
- context-as-code knowledge instrument
- governed assistant source package
- advisory repository versus deterministic control-plane separation

The system should let an organization say:

```text
This is what the assistant is allowed to know, cite, refuse, and explain.
```

The governed knowledge instrument is the source package plus its evidence system. The assistant is an interpretation surface over that package. The model is not the source of truth.

## 1. Canonical Source Repository

Purpose: human-authored canonical doctrine, playbooks, standards, policies, operating models, and source notes under controlled review.

Required shape:

- Git repository remains the authoritative source for canonical source files and change control.
- Markdown, HTML source, source data, and companion metadata remain reviewable in pull requests.
- Major source files carry artifact identity, version or revision where needed, source family, owner, and source quality posture.
- Pull requests and issues remain the governance trail for why a change exists and how it was bounded.
- Validation receipts remain repo evidence that records commands, generated outputs, non-goals, limitations, and residual risks.

Canonical source is the human-reviewed material from which generated surfaces are built. It is not model memory, runtime logs, a SaaS retrieval layer, a chat transcript, or a hidden enterprise copilot knowledge base.

## 2. Generated Artifact Repository Surface

Purpose: deterministic human-reader and package surfaces generated from canonical source.

Required shape:

- Generated outputs live in deterministic build locations such as `docs/`, `context-pack/`, `releases/`, and published-site mirrors.
- Reader pages, portable HTML, manifests, source maps, hashes, package mirrors, and release artifacts must be reproducible from canonical source and generator code.
- Hashes and manifests provide generated-surface integrity evidence.
- Generated outputs are not manually edited unless the repository explicitly designates the file as source.
- Regeneration must leave a reviewable diff that distinguishes authored source changes from generated mirror updates.

Generated reader surfaces are publication and inspection surfaces. They are not the source authority unless the repository explicitly marks a generated artifact as canonical source.

## 3. Assistant Package Repository Surface

Purpose: model-ready source units, grounding rules, refusal patterns, source maps, source-quality notes, and token or context metadata that can be loaded by an assistant without surrendering source control.

Required shape:

- The assistant package is generated from canonical source and artifact metadata.
- Assistant-consumable source units retain source family, artifact title, section title or ID, source path, reader target, source quality status, claim boundary, and citation identity.
- Package output is portable and inspectable without requiring a vector store.
- Grounding rules define what may be answered, what must be cited, what requires owner validation, and what must be refused.
- Deterministic refusal is required when the answer is not found in approved sources or when the user asks for approval meaning the package cannot grant.

The assistant package may later feed retrieval tooling, but retrieval tooling does not become the authority. Source authority remains the package and its traceable source records.

## 4. Runtime State Boundary

Purpose: separate source authority from runtime telemetry, session state, and usage logs.

Required shape:

- Source authority stays in the package and repository, not in model memory.
- Runtime run logs, usage, token counts, latency, provider status, selected source counts, and sessions may eventually belong in runtime telemetry.
- Runtime telemetry must not become source authority.
- User or session uploads, if later added, must be labeled session-scoped and separate from the approved package corpus.
- Runtime prompts, chat history, and model output remain derivative interpretation unless separately promoted through source review.

Runtime state can support observability and debugging. It does not approve sources, change package authority, silently expand the corpus, or override deterministic refusal behavior.

## 5. Optional Future Data Stores

Additional stores are useful when they solve a specific problem. They should not be the starting assumption.

| Store | Introduce when | Boundary |
|---|---|---|
| Relational database | Authoring workflow, ownership, approvals, lifecycle states, user profiles, saved sessions, role-specific corpuses, or durable app state become hard to manage in files alone. | Database records support workflow and app state. They do not silently replace canonical source authority. |
| Object store | Large files, binary artifacts, attachments, rendered exports, or versioned downloadable assets exceed practical Git storage or distribution limits. | Object paths need manifests, hashes, provenance, and lifecycle rules. |
| Search index | Fast lexical or hybrid retrieval is needed because corpus size, latency, or query patterns outgrow simple package scanning. | Indexes are derived projections and must preserve source path, section identity, claim boundary, and citation identity. |
| Vector store | Semantic recall materially outperforms deterministic or curated section matching and provenance can still be preserved. | Embeddings are recall aids, not authority. They must fail closed when source identity, claim boundary, or source quality cannot be retained. |
| Graph database | Relationships, dependencies, controls, obligations, owners, evidence chains, or lineage become first-class query targets. | Graph nodes and edges need source-backed provenance and review semantics. |

## Scaling Model

| Stage | Architecture | When it is enough |
|---|---|---|
| 1 | Git repo, Markdown/HTML, generated JSONL corpus | Curated corpus, small team, strong governance |
| 2 | Generated manifests, source maps, anchors, validation receipts | Multiple artifacts, public/private exports, citations |
| 3 | Lightweight metadata DB | Many authors, workflow state, approvals, ownership, history |
| 4 | Search index or hybrid retrieval | Corpus grows beyond simple package scanning |
| 5 | Vector/embedding layer | Semantic recall is materially better than curated section matching |
| 6 | Graph/database model | Relationships, dependencies, controls, ownership, obligations matter as first-class entities |

Rule:

```text
Do not start at Stage 5 by default.
Introduce each layer only when the lifecycle, scale, permission, or retrieval problem justifies it.
```

Stage 1 and Stage 2 are enough for many governed corpuses because they preserve auditability, deterministic generation, static portability, explicit source boundaries, and human review. Stage 3 through Stage 6 are growth paths, not product identity.

## Copilot Studio And Enterprise Front Door Posture

Copilot Studio can be a useful enterprise front door. It should not be treated as the canonical product core by default.

Recommended posture:

- Keep the governed package engine independent.
- Expose the package engine through an API, action, or tool boundary.
- Let Copilot Studio call the governed package API instead of dumping the corpus into opaque knowledge retrieval.
- Preserve source selection, refusal behavior, citation identity, token and run telemetry, and provenance in the governed engine.
- Use Copilot Studio for enterprise reach, Microsoft 365 surfaces, identity/channel integration, and low-code orchestration when those are the deployment requirements.
- Do not let Copilot Studio become the authoritative source package or governance trail unless explicitly designed and validated.

This keeps enterprise access and channel convenience separate from package authority. The governed engine decides what can be known, cited, refused, and explained. The front door carries the user experience.

## Context-As-Code Storage Rule

Context-as-code is the core product storage model when the corpus is finite, curated, high-value, and governance-sensitive.

It is appropriate when:

- source material needs human review before assistant use
- generated reader and assistant surfaces must be reproducible
- citations must point back to source paths, sections, and reader targets
- source quality and claim boundaries matter
- deterministic refusals are part of the control model
- portable packages matter more than SaaS retrieval lock-in
- validation receipts and hash checks are part of delivery evidence

It is not enough by itself when:

- authoring workflow state exceeds file-review ergonomics
- access control requires per-user or per-role corpus assembly at runtime
- session state, saved work, or collaboration history must persist
- retrieval latency or corpus size exceeds package scanning
- semantic recall is materially better than curated section matching
- relationship queries across controls, obligations, owners, and evidence become the main product
- large binary assets or attachments exceed practical repository storage

The right posture is not anti-database or anti-RAG. The right posture is package-first governance with derived stores added when they preserve, not dilute, source authority.

## Relationship To Active Backlog

- #186 should still handle Package + current context mode.
- #187 should still handle session-scoped uploaded sources.
- #188 should still handle whole-site Access posture.
- #189 should still handle runtime model routing and tokenomics telemetry.
- #193 and #194 should still complete immediate UX repairs first if not already merged.
- #196 strengthens product doctrine before or alongside those implementation lanes.

## Non-Goals

This note does not:

- implement runtime behavior
- implement assistant source upload behavior
- implement Package + current context mode
- implement runtime routing or tokenomics telemetry
- add a database, vector store, search index, object store, or graph database
- change Cloudflare Access, WAF, Pages, Functions, or provider configuration
- mutate source registries
- mutate approved source sets
- change package authority
- weaken deterministic source boundaries or refusal behavior
- imply Copilot Studio is the authoritative product core
- imply default vector-store RAG is required
- reopen #269
- reopen #271
- apply `codex-automerge`

## Validation Expectations

Validation for this architecture note should prove:

- the product/source files describe the governed corpus runtime pattern
- context-as-code is explained as the core product storage model for governed corpuses
- canonical source, generated artifacts, assistant package, runtime telemetry, and optional future stores are separated
- scaling thresholds are present for relational DB, object store, search, vector, and graph layers
- Copilot Studio is framed as a possible enterprise front door, not the source package or governance trail
- generated context-pack and docs mirrors include the new note
- non-goals and hard boundaries remain explicit