index.md
HTML wrapper for HTML-only fetchers; content is shown verbatim.
Raw file
Links (extracted)
Clickable list for reviewers; avoids copy/paste line-wrap issues.
# if.context — full-auto context engine (external review, single-file)
Danny Stocker | Infrafabric Research | ds@infrafabric.io | 2026-01-27
**Purpose:** describe what `if.context` does today (VERIFIED) and specify the last-mile work needed to make it fully automatic when enabled (PROPOSED), in a way a zero-context agent can debug/iterate without guesswork.
Black/white:
- Verified claims in this document are limited to publicly retrievable bytes, deterministic CLI behaviors, and repo-local source code that can be inspected and executed.
- This document does not claim correctness of decisions, completeness of detection, model truthfulness, or compliance guarantees.
- “Quantum ready” means a PQ receipt exists (if.trace supports PQ receipts); it does not mean “quantum-secure”.
---
## 0) The review surface stack (where this fits)
This section borrows the required scaffolding discipline from `if.whitepapers.bible` (actual product id: `if.whitepapers.bible`).
Registry (canonical IDs; do not invent product ids):
https://infrafabric.io/llm/if.registry.json.txt
`/llm` entrypoint + manifests:
https://infrafabric.io/llm/entrypoint.json.txt
https://infrafabric.io/llm/index.json.txt
https://infrafabric.io/llm/README.md.txt
Current bindings (latest artifacts + receipts):
https://infrafabric.io/llm/sot/index.json.txt
Integrity proofs (byte integrity only):
https://infrafabric.io/if/trace/
*If this can’t be found via the registry/manifest/discover stack, we didn’t ship a review surface — we shipped a rumor.*
---
## 1) What `if.context` is (and isn’t)
`if.context` is an **evidence environment** for agent work:
- **Artifacts** are bytes with hashes and retrieval provenance (what was fetched, when, from where, how many bytes, what media type).
- **Read plans** log what was read vs skipped and why (auditable intent, not just “final answer”).
- **Derived artifacts** are outputs (summaries/claims/etc) that include a **verification chain** linking claims back to exact source spans.
`if.context` is not:
- “More prompt text” or a monolithic “RAG system”.
- A replacement for `if.bus` (control plane) or `if.trace` (integrity receipts).
- A guarantee of truth/correctness; it binds claims to bytes, it does not certify the claims.
*If we treat “context” like a bag of tokens instead of a ledger of evidence, we’ll keep debugging the wrong failure mode.*
---
## 2) Current status (VERIFIED vs NOT YET IMPLEMENTED)
### 2.1 VERIFIED (repo-local implementation exists)
Schemas (public-safe JSON Schema; full text embedded in §4):
- `schemas/if-context/artifact.schema.json`
- `schemas/if-context/derived_artifact.schema.json`
- `schemas/if-context/read_plan.schema.json`
CLI tooling:
- `scripts/if_context_store.py` (append-only ledger + blob layout; deterministic IDs)
- `scripts/if_context_ingest.py` (ingest `--file` or `--url` into store)
- `scripts/if_context_spans.py` (byte↔line helpers + read_plan emitter)
- `scripts/if_context_derive.py` (derived_artifact emitter; verification_chain scaffolding)
- `scripts/if_context_pack.py` (export a public-safe review pack from a store)
- `scripts/if_context_validate.py` (schema validation for examples and instances)
Published packs (public no-login, HTML-first + `.md` + `.md.txt`):
- Architecture paper v0.6:
https://infrafabric.io/static/hosted/review/if-context-architecture/2026-01-25/index.html
https://infrafabric.io/static/hosted/review/if-context-architecture/2026-01-25/index.md
https://infrafabric.io/static/hosted/review/if-context-architecture/2026-01-25/index.md.txt
- MVP review pack (public-safe sample store snapshot):
https://infrafabric.io/static/hosted/review/if-context-mvp/2026-01-25/index.html
https://infrafabric.io/static/hosted/review/if-context-mvp/2026-01-25/index.md
https://infrafabric.io/static/hosted/review/if-context-mvp/2026-01-25/index.md.txt
https://infrafabric.io/static/hosted/review/if-context-mvp/2026-01-25/manifest.json
Blackboard tasks (latest snapshot on this host; informational only):
- IF-722 done (paper v0.6)
- IF-724 done (internal implementation bible)
- IF-725..IF-730 done (schemas/store/ingest/spans/derive/pack)
- IF-723 still shows `in_progress` even though its sub-tasks shipped; treat umbrella status as stale until explicitly closed.
### 2.2 NOT YET IMPLEMENTED (do not assume)
The “full-auto” requirement from this request is not shipped:
- Automatic **viewpoint selection** (choosing which evidence to read for a task without a human curating files/links).
- Automatic **folding/orchestration** (iterative budgeted reading + compression + re-reading + derived artifact emission + publish) that runs end-to-end when enabled.
- Automatic **tenant/NDA wall** runtime (`/mcp`) and any multi-tenant service posture.
- Automatic “semantic stability scoring” or dispute routing to `if.gov` (only conceptual notes exist).
*The MVP proves the evidence primitives; the missing part is the planner/executor that uses them without human babysitting.*
---
## 3) How it works today (VERIFIED mechanics)
### 3.1 Source of truth (SoT): append-only ledgers + blobs
Default store root:
- `/root/tmp/if_context_store`
Layout (as created by `scripts/if_context_store.py init`):
```text
<store_root>/
ledgers/
artifacts.jsonl
derived.jsonl
read_plans.jsonl
blobs/
sha256/<first2>/<sha256>
```
SoT rule:
- If it can’t be rebuilt from ledgers + blobs, it’s not an “accelerator”; it’s an accidental second source of truth.
*If we let Redis/Chroma become the truth, we lose auditability the first time the cache lies.*
### 3.2 Ingest: file/URL → artifact record + blob + ledger append
Shape:
- Ingest computes `content.sha256` and writes blob bytes to `blobs/sha256/...`.
- Ingest appends the artifact row to `ledgers/artifacts.jsonl`.
- Artifact id is content-addressed: `artifact_id = "art_" + sha256`.
Verify (local, no secrets; produces a disposable demo pack):
```bash
set -euo pipefail
STORE=/root/tmp/if_context_store_demo
PACK=/root/tmp/if_context_pack_demo
rm -rf "$STORE" "$PACK"
python3 scripts/if_context_store.py --root "$STORE" init
python3 scripts/if_context_ingest.py --root "$STORE" --classification public --file docs/213-if-context-v1-comple.md --validate
python3 scripts/if_context_pack.py --store-root "$STORE" --out-dir "$PACK" --classification public --include-blobs
ls -la "$PACK"
```
*If ingest can’t be run deterministically on a single file, “full auto” will fail for every larger dataset.*
### 3.3 Read plans + spans
`if.context.read_plan.v1` exists to answer: “what did the agent/tool read vs skip, and why?”
Spans:
- `byte_range` and `line_range` are supported today for text.
- `scripts/if_context_spans.py` provides byte↔line mapping helpers and emits `read_plan` records.
*If we can’t log “what we skipped”, reviewers will assume we skipped the inconvenient part.*
### 3.4 Derived artifacts + verification chains
`if.context.derived_artifact.v1` exists to store derived work products with provenance:
- `derivation.derived_from[]` points to source spans.
- `verification_chain[]` binds individual claims to source spans.
This is scaffolding, not automatic verification:
- `verification_status` can be `unverified` and is expected to be in early stages.
*If we confuse “has citations” with “is verified”, we’ll build an integrity theater machine.*
### 3.5 Pack exporter: store → public-safe review pack
`scripts/if_context_pack.py` exports:
- `index.html` (HTML wrapper)
- `index.md` and `index.md.txt` (Markdown and strict-client fallback)
- `manifest.json` (hashes of pack outputs)
- filtered ledgers and (optionally) blobs, by `classification`
Publishing (hosted-static, backup-first):
- `scripts/hosted_static_publish.py` copies a pack to the web root and rebuilds wrappers.
*If publishing isn’t backup-first, we’ll destroy evidence surfaces right when scrutiny starts.*
---
## 4) Full schemas (VERIFIED; embedded verbatim)
### 4.1 `if.context.artifact.v1` schema
```json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "if-context/artifact.schema.json",
"title": "IF.CONTEXT Artifact",
"description": "Content-addressed artifact metadata with retrieval provenance.",
"type": "object",
"additionalProperties": false,
"properties": {
"schema": {
"type": "string",
"enum": ["if.context.artifact.v1"]
},
"artifact_id": {
"type": "string",
"minLength": 3,
"maxLength": 128
},
"classification": {
"type": "string",
"enum": ["public", "tenant", "nda"]
},
"content": {
"type": "object",
"additionalProperties": false,
"properties": {
"sha256": {"$ref": "#/$defs/sha256"},
"bytes": {
"type": "integer",
"minimum": 0
},
"media_type": {
"type": "string"
},
"content_encoding": {
"type": "string",
"enum": ["identity", "gzip", "zstd"]
},
"encryption_key_id": {
"type": "string"
}
},
"required": ["sha256", "bytes", "media_type"]
},
"source": {
"type": "object",
"additionalProperties": false,
"properties": {
"origin_type": {
"type": "string",
"enum": ["url", "api_event", "upload", "filesystem"]
},
"origin_ref": {
"type": "string"
},
"source_url": {
"type": "string",
"format": "uri"
},
"retrieved_utc": {
"type": "string",
"format": "date-time"
},
"etag": {
"type": "string"
},
"last_modified": {
"type": "string"
},
"tenant_id": {
"type": "string"
},
"producer_trust_level": {
"type": "string",
"enum": ["untrusted", "verified", "internal"]
}
},
"required": ["origin_type", "origin_ref", "retrieved_utc"]
},
"addressing": {
"type": "object",
"additionalProperties": false,
"properties": {
"method": {
"type": "string",
"enum": ["byte_range", "line_range", "jsonpath", "image_region"]
},
"spec_version": {
"type": "string"
}
},
"required": ["method", "spec_version"]
},
"type_schema": {
"type": "string"
},
"lifecycle": {
"type": "object",
"additionalProperties": false,
"properties": {
"created_utc": {
"type": "string",
"format": "date-time"
},
"retention_policy": {
"type": "string"
},
"shred_eligible": {
"type": "boolean"
}
}
},
"notes": {
"type": "string"
}
},
"required": ["schema", "artifact_id", "classification", "content", "source"],
"examples": [
{
"schema": "if.context.artifact.v1",
"artifact_id": "art_01jhgxv2n0t0k4d0e8q9g2q2k3",
"classification": "public",
"content": {
"sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"bytes": 1204,
"media_type": "text/markdown",
"content_encoding": "identity"
},
"source": {
"origin_type": "url",
"origin_ref": "https://example.invalid/review/if-context/example.md",
"source_url": "https://example.invalid/review/if-context/example.md",
"retrieved_utc": "2026-01-25T13:40:00Z",
"etag": "\"abc123\"",
"last_modified": "Sat, 25 Jan 2026 13:39:00 GMT",
"producer_trust_level": "verified"
},
"addressing": {
"method": "byte_range",
"spec_version": "1.0"
},
"lifecycle": {
"created_utc": "2026-01-25T13:40:00Z",
"retention_policy": "indefinite",
"shred_eligible": false
}
},
{
"schema": "if.context.artifact.v1",
"artifact_id": "art_01jhgxv2n0t0k4d0e8q9g2q2k4",
"classification": "tenant",
"content": {
"sha256": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
"bytes": 48291,
"media_type": "application/pdf",
"content_encoding": "identity",
"encryption_key_id": "key_tenant_001"
},
"source": {
"origin_type": "upload",
"origin_ref": "upload:tenant/t_123/docs/contract.pdf",
"retrieved_utc": "2026-01-25T13:41:00Z",
"tenant_id": "t_123",
"producer_trust_level": "internal"
}
}
],
"$defs": {
"sha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
}
}
}
```
### 4.2 `if.context.read_plan.v1` schema
```json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "if-context/read_plan.schema.json",
"title": "IF.CONTEXT Read Plan",
"description": "Explicit record of what was read vs skipped and why.",
"type": "object",
"additionalProperties": false,
"properties": {
"schema": {
"type": "string",
"enum": ["if.context.read_plan.v1"]
},
"read_plan_id": {
"type": "string",
"minLength": 3,
"maxLength": 128
},
"artifact_id": {
"type": "string"
},
"classification": {
"type": "string",
"enum": ["public", "tenant", "nda"]
},
"created_utc": {
"type": "string",
"format": "date-time"
},
"reader": {
"type": "object",
"additionalProperties": false,
"properties": {
"kind": {
"type": "string",
"enum": ["human", "model", "tool"]
},
"id": {
"type": "string"
},
"version": {
"type": "string"
},
"session_id": {
"type": "string"
}
},
"required": ["kind", "id"]
},
"actions": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"action": {
"type": "string",
"enum": ["read", "skip"]
},
"byte_range": {"$ref": "#/$defs/byte_range"},
"line_range": {"$ref": "#/$defs/line_range"},
"reason": {
"type": "string"
},
"notes": {
"type": "string"
}
},
"required": ["action", "reason"],
"anyOf": [
{"required": ["byte_range"]},
{"required": ["line_range"]}
]
},
"minItems": 1
},
"notes": {
"type": "string"
}
},
"required": ["schema", "read_plan_id", "artifact_id", "classification", "created_utc", "reader", "actions"],
"examples": [
{
"schema": "if.context.read_plan.v1",
"read_plan_id": "rp_01jhgxv2n0t0k4d0e8q9g2q2k7",
"artifact_id": "art_01jhgxv2n0t0k4d0e8q9g2q2k3",
"classification": "public",
"created_utc": "2026-01-25T13:50:00Z",
"reader": {
"kind": "model",
"id": "example-model-2026-01",
"version": "2026-01-25"
},
"actions": [
{
"action": "read",
"byte_range": {"start": 0, "end": 2048},
"reason": "Initial context sweep"
},
{
"action": "skip",
"line_range": {"start": 120, "end": 220},
"reason": "Non-relevant appendix"
}
]
},
{
"schema": "if.context.read_plan.v1",
"read_plan_id": "rp_01jhgxv2n0t0k4d0e8q9g2q2k8",
"artifact_id": "art_01jhgxv2n0t0k4d0e8q9g2q2k4",
"classification": "tenant",
"created_utc": "2026-01-25T13:51:00Z",
"reader": {
"kind": "tool",
"id": "if.context.ingest"
},
"actions": [
{
"action": "read",
"line_range": {"start": 1, "end": 40},
"reason": "Extract header metadata"
}
]
}
],
"$defs": {
"byte_range": {
"type": "object",
"additionalProperties": false,
"properties": {
"start": {
"type": "integer",
"minimum": 0
},
"end": {
"type": "integer",
"minimum": 0
}
},
"required": ["start", "end"]
},
"line_range": {
"type": "object",
"additionalProperties": false,
"properties": {
"start": {
"type": "integer",
"minimum": 1
},
"end": {
"type": "integer",
"minimum": 1
}
},
"required": ["start", "end"]
}
}
}
```
### 4.3 `if.context.derived_artifact.v1` schema
```json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "if-context/derived_artifact.schema.json",
"title": "IF.CONTEXT Derived Artifact",
"description": "Derived artifacts with verification-chain pointers to source spans.",
"type": "object",
"additionalProperties": false,
"properties": {
"schema": {
"type": "string",
"enum": ["if.context.derived_artifact.v1"]
},
"derived_artifact_id": {
"type": "string",
"minLength": 3,
"maxLength": 128
},
"classification": {
"type": "string",
"enum": ["public", "tenant", "nda"]
},
"created_utc": {
"type": "string",
"format": "date-time"
},
"derivation": {
"type": "object",
"additionalProperties": false,
"properties": {
"type": {
"type": "string",
"enum": ["fold", "summary", "claims_table", "embedding", "transform"]
},
"algorithm_version": {
"type": "string"
},
"derived_from": {
"type": "array",
"items": {"$ref": "#/$defs/span_pointer"},
"minItems": 1
}
},
"required": ["type", "derived_from"]
},
"verification_chain": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"claim_id": {
"type": "string"
},
"claim_text": {
"type": "string"
},
"confidence": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"source_pointer": {"$ref": "#/$defs/span_pointer"},
"verification_status": {
"type": "string",
"enum": ["verified", "unverified", "disputed"]
},
"notes": {
"type": "string"
}
},
"required": ["claim_id", "claim_text", "source_pointer", "verification_status"]
}
},
"model_context": {
"type": "object",
"additionalProperties": false,
"properties": {
"model_id": {
"type": "string"
},
"params_hash": {"$ref": "#/$defs/sha256"},
"temperature": {
"type": "number",
"minimum": 0
},
"semantic_stability_expectation": {
"type": "number",
"minimum": 0,
"maximum": 1
}
}
},
"replay_classification": {
"type": "object",
"additionalProperties": false,
"properties": {
"type": {
"type": "string",
"enum": ["deterministic", "llm_inference"]
},
"hash_identical_expected": {
"type": "boolean"
},
"provenance_chain_required": {
"type": "boolean"
}
},
"required": ["type", "provenance_chain_required"]
},
"notes": {
"type": "string"
}
},
"required": ["schema", "derived_artifact_id", "classification", "derivation"],
"examples": [
{
"schema": "if.context.derived_artifact.v1",
"derived_artifact_id": "der_01jhgxv2n0t0k4d0e8q9g2q2k5",
"classification": "public",
"created_utc": "2026-01-25T13:45:00Z",
"derivation": {
"type": "summary",
"algorithm_version": "fold.recursive.v2",
"derived_from": [
{
"artifact_id": "art_01jhgxv2n0t0k4d0e8q9g2q2k3",
"byte_range": {"start": 405, "end": 448},
"content_sha256_of_range": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"
}
]
},
"verification_chain": [
{
"claim_id": "clm_001",
"claim_text": "Budget is capped at 500 USD.",
"confidence": 0.95,
"source_pointer": {
"artifact_id": "art_01jhgxv2n0t0k4d0e8q9g2q2k3",
"byte_range": {"start": 405, "end": 448},
"decoded_snippet": "MAX_SPEND = 500"
},
"verification_status": "verified"
}
],
"model_context": {
"model_id": "example-model-2026-01",
"params_hash": "dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd",
"temperature": 0.0,
"semantic_stability_expectation": 0.95
},
"replay_classification": {
"type": "llm_inference",
"hash_identical_expected": false,
"provenance_chain_required": true
}
},
{
"schema": "if.context.derived_artifact.v1",
"derived_artifact_id": "der_01jhgxv2n0t0k4d0e8q9g2q2k6",
"classification": "tenant",
"created_utc": "2026-01-25T13:46:00Z",
"derivation": {
"type": "embedding",
"algorithm_version": "embed.v1",
"derived_from": [
{
"artifact_id": "art_01jhgxv2n0t0k4d0e8q9g2q2k4",
"line_range": {"start": 1, "end": 40}
}
]
}
}
],
"$defs": {
"sha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
},
"byte_range": {
"type": "object",
"additionalProperties": false,
"properties": {
"start": {
"type": "integer",
"minimum": 0
},
"end": {
"type": "integer",
"minimum": 0
}
},
"required": ["start", "end"]
},
"line_range": {
"type": "object",
"additionalProperties": false,
"properties": {
"start": {
"type": "integer",
"minimum": 1
},
"end": {
"type": "integer",
"minimum": 1
}
},
"required": ["start", "end"]
},
"span_pointer": {
"type": "object",
"additionalProperties": false,
"properties": {
"artifact_id": {
"type": "string"
},
"byte_range": {"$ref": "#/$defs/byte_range"},
"line_range": {"$ref": "#/$defs/line_range"},
"jsonpath": {
"type": "string"
},
"content_sha256_of_range": {"$ref": "#/$defs/sha256"},
"decoded_snippet": {
"type": "string"
}
},
"required": ["artifact_id"],
"anyOf": [
{"required": ["byte_range"]},
{"required": ["line_range"]},
{"required": ["jsonpath"]}
]
}
}
}
```
*If we don’t embed the full schemas, downstream agents will re-invent them and drift starts immediately.*
---
## 5) The “full auto” last mile (PROPOSED, implementation-grade)
This section specifies what must be implemented so that when `if.context` is enabled, it:
1) selects the correct evidence viewpoints automatically,
2) folds/compresses to strict budgets automatically,
3) emits read plans + derived artifacts automatically,
4) exports and publishes a review pack automatically,
5) does all of the above without human involvement.
### 5.1 Required control surface (enable/disable; budgets; classification)
Minimum config (environment variables or a single JSON config file; exact carrier is implementer choice):
- `IF_CONTEXT_ENABLED` (bool; default false)
- `IF_CONTEXT_STORE_ROOT` (path; default `/root/tmp/if_context_store`)
- `IF_CONTEXT_CLASSIFICATION_MAX` (`public|tenant|nda`; default `public`)
- `IF_CONTEXT_BUDGET_BYTES` (int; maximum bytes to present to the model per run)
- `IF_CONTEXT_BUDGET_TOKENS` (int; optional, if a tokenizer is used)
- `IF_CONTEXT_FAIL_CLOSED` (bool; default true)
Fail-closed requirements:
- If classification is unknown → treat as non-public and do not publish.
- If a URL is not obviously public/no-login → do not fetch in public mode (require explicit allowlist).
*If “enabled” isn’t an explicit flag with fail-closed defaults, it will be accidentally on in the worst environment.*
### 5.2 Define “viewpoint” (the missing entity)
Definition (proposed):
- A **viewpoint** is a repeatable evidence selection + folding recipe for a task.
- A run may require multiple viewpoints (e.g., “product surface”, “schemas”, “ops status”, “security posture”).
Proposed viewpoint record (new schema, not yet implemented):
```json
{
"schema": "if.context.viewpoint.v1",
"viewpoint_id": "vp_<sha256>",
"name": "stack-and-schema",
"goal": "Explain what it is and how it works; include full schemas; include verify commands.",
"selection": {
"max_artifacts": 30,
"allow_media_types": ["text/markdown", "application/json", "text/plain"],
"required_paths": ["schemas/if-context/**", "scripts/if_context_*.py"],
"rankers": ["path_relevance.v1", "recency.v1", "explicit_refs.v1"]
},
"budgets": {
"max_input_bytes": 200000,
"max_summary_bytes": 40000
},
"fold": {
"algorithm_version": "fold.recursive.v2",
"chunk_bytes": 12000,
"overlap_bytes": 800,
"passes_max": 6
}
}
```
*If “viewpoint” stays implicit, every agent will reinvent it slightly differently and automation will never converge.*
### 5.3 Automatic viewpoint selection (planner)
Inputs:
- Task request (user prompt / work order / blackboard task text).
- Evidence inventory (artifacts already in store + repo file candidates + public URLs).
Outputs:
- A list of viewpoint specs to execute (ordered), plus budgets per viewpoint.
Proposed algorithm (deterministic-first; LLM as optional helper, never as SoT):
1) Parse the task request into required deliverable types:
- “external review doc” → needs schemas + stack + verify commands
- “update status” → needs blackboard snapshots + current published URLs
2) Map deliverable types to a fixed small viewpoint library (checked into repo):
- `vp.stack-and-seams`
- `vp.schemas-and-data-model`
- `vp.current-status`
- `vp.full-auto-last-mile`
- `vp.debug-playbook`
3) For each viewpoint, compute candidate evidence set:
- Start with explicit required paths (viewpoint config).
- Add “linked refs” discovered via `rg` over the required files (bounded).
- Add published pack URLs (public only) if `IF_CONTEXT_CLASSIFICATION_MAX=public`.
4) Score candidates using simple deterministic rankers:
- `path_relevance`: exact match > prefix match > fuzzy match
- `explicit_ref`: file is referenced by another selected file
- `recency`: prefer newer docs (when dates exist)
5) Emit a `read_plan` before reading:
- include “read” ranges for the chosen evidence,
- include “skip” entries for candidates not selected, with reasons.
Optional (LLM-assisted, but recorded as `llm_inference` and never trusted blindly):
- LLM suggests additional candidates; all suggestions are filtered through publish/classification rules and deterministic rankers.
*If viewpoint selection is “LLM magic” without a deterministic backbone, every run will drift and audits will fail.*
### 5.4 Automatic folding (executor)
Goal:
- Reduce a large evidence set into a bounded “working context” while preserving provenance pointers.
Constraints:
- Folding must be budgeted (`IF_CONTEXT_BUDGET_BYTES` / tokens) and iterative.
- Every fold output must be stored as a `derived_artifact` with:
- `derivation.derived_from[]` pointing to the exact spans folded,
- `model_context` when LLM is used,
- `replay_classification.type="llm_inference"` when applicable.
Proposed folding loop (implementation-grade pseudocode):
```text
for viewpoint in selected_viewpoints:
evidence = select_evidence(viewpoint)
emit_read_plan(evidence, viewpoint)
while size(evidence) > viewpoint.budgets.max_input_bytes:
chunks = chunk(evidence, chunk_bytes, overlap_bytes)
summaries = []
for chunk in chunks:
summary = fold_chunk(chunk) # may call LLM
store_derived_artifact(summary, chunk) # derivation + verification_chain scaffolding
summaries.append(summary)
evidence = summaries
final_context = evidence
store_derived_artifact(final_context, viewpoint, derived_from=all_inputs)
```
Verification chain policy (minimum viable):
- For every paragraph/bullet in the fold output, store at least one span pointer to a supporting source range.
- Mark `verification_status="unverified"` by default (until a verifier exists).
This is “automatic citations” scaffolding, not truth verification.
*If folding produces text without span pointers, it will look like a hallucination even when it isn’t.*
### 5.5 Orchestration: “when enabled, runs end-to-end”
Proposed orchestration entrypoint (CLI first, service later):
- `python3 scripts/if_context_auto.py --task <text|file|task_id> --out-pack <dir> [--publish <review/path>]`
Minimum responsibilities:
1) Resolve inputs (task text + any referenced artifacts).
2) Run viewpoint planner (§5.3).
3) Run viewpoint executors (§5.4) producing:
- `read_plan` records
- `derived_artifact` fold products
4) Export a pack (`scripts/if_context_pack.py`) at classification `public` (or stricter).
5) Publish (optional but required for “no human involvement” in public mode):
- `scripts/hosted_static_publish.py --src <pack> --dst review/<slug>/<date>/`
6) (Optional) Seed an `if.trace` receipt for the published pack index or for the single-file doc.
Failure posture (must be explicit):
- Any uncertainty about classification or public-ness → stop, emit a derived artifact describing the stop condition, and do not publish.
- Any fold/model failure → stop, produce a pack containing read plans + partial outputs + error summary (still publish-safe), and mark outcome “incomplete”.
*If failure posture is implicit, the system will fail open under pressure.*
---
## 6) Zero-context debugging checklist (VERIFIED + PROPOSED)
### 6.1 Verify the shipped primitives (today)
Schema examples validate:
```bash
python3 scripts/if_context_validate.py --kind artifact --examples
python3 scripts/if_context_validate.py --kind derived_artifact --examples
python3 scripts/if_context_validate.py --kind read_plan --examples
```
Spans self-test:
```bash
python3 scripts/if_context_spans.py self-test
```
Published pack reachable:
```bash
curl -fsSI https://infrafabric.io/static/hosted/review/if-context-mvp/2026-01-25/index.html | head -n 1
curl -fsSI https://infrafabric.io/static/hosted/review/if-context-mvp/2026-01-25/index.md.txt | head -n 1
```
### 6.2 Common traps (observed patterns)
- `if.context` is not registered in `if.registry.json` yet; avoid claiming product-pack paths under `/llm/products/` until it is.
- Classification is the safety boundary; treat any unknown as non-public (fail closed).
- `payload_ref.source_url` (if you later emit `if.bus.envelope`) must be public/no-login; never put tenant/NDA URLs there.
*If we don’t write down the traps, the next agent will rediscover them the slow way.*
---
## 7) Task list for implementation (NOT on blackboard yet)
This is the “task out” section requested: concrete work items other agents can pick up. None of these tasks are created on the blackboard by this document.
### T1) Add `if.context.viewpoint.v1` schema + examples
Acceptance:
- Schema exists under `schemas/if-context/viewpoint.schema.json` (public-safe).
- At least 2 examples: (a) “schemas-and-stack”, (b) “ops-status”.
- Validator updated to support `--kind viewpoint`.
### T2) Implement deterministic viewpoint library + selector
Acceptance:
- A repo-local viewpoint catalog exists (JSON files) and is deterministic.
- Given a task string, selector returns a stable ordered viewpoint list.
- Selector emits a `read_plan` that includes both chosen reads and explicit skips with reasons.
### T3) Implement folding executor with provenance pointers
Acceptance:
- Folding loop takes an evidence set and produces derived artifacts with span pointers.
- Budget enforcement is measurable (bytes/tokens) and recorded in outputs.
- Produces a publish-safe pack even on partial failure.
### T4) Implement “full auto” orchestration entrypoint
Acceptance:
- One CLI command runs: plan → execute viewpoints → fold → export pack → (optional) publish.
- Default behavior is fail-closed and publish-safe.
- Includes verify commands and a deterministic “dry-run” mode that emits read_plans but does not call any model.
### T5) Optional: integrate `if.trace` receipt seeding
Acceptance:
- Can seed a receipt for the generated single-file report or pack index (no secrets in the published surfaces).
- Receipt URLs are added to the pack index (one URL per line).
*If we don’t slice this into tasks with acceptance criteria, “full auto” will remain an aspiration instead of a ship plan.*