# 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.*
