# Byte Repository Intelligence

Byte Repository Intelligence records not only an answer and its citations, but the conditions under which that answer can still be used. Its core question is:

> What could change while every cited line stays the same, yet make this answer wrong?

The feature is automatic in the agent. Existing package, command, configuration, and storage identifiers retain their `zyte-agent`, `za`, `ZYTE_AGENT_`, and `.zyte` names for compatibility.

## Trust model

Claim outcome and current applicability are separate fields.

| Field | Values | Meaning |
|---|---|---|
| Outcome | `supported`, `refuted`, `unresolved` | What the recorded evidence establishes about the statement. |
| Applicability | `current`, `needs_recheck`, `unknown` | Whether that evidence boundary still applies to a target snapshot. |

A changed dependency never rewrites a historical observation. It revokes applicability and opens a scoped obligation. Model-authored answers are stored as `unresolved` interpretations even when their source spans are fresh; current code is not proof that the model interpreted it correctly.

## Turn lifecycle

```mermaid
flowchart LR
    Q[Repository question] --> S[Immutable snapshot]
    S --> B[Compiler and structural boundary]
    B --> A[Model answer]
    A --> C[Claim + evidence + dependencies]
    C --> E{Repository changes}
    E -->|Boundary unchanged| R[Reuse remains applicable]
    E -->|Boundary changed or incomplete| O[Recheck obligation]
```

Before a code-anchored turn, the agent captures a content-addressed snapshot and checks related claims and open obligations. Snapshot capture refuses a file larger than 64 MiB or a workspace payload larger than 256 MiB; reads are streamed against those fixed limits rather than buffered first. Git-based enumeration uses a resolved absolute executable outside the repository, so a repository-local `git` shim or relative `PATH` entry cannot replace it.

Impact questions such as “all callers,” “blast radius,” and “every implementation” also start an isolated TypeScript compiler worker against a materialization of that exact snapshot—not the mutable working tree. Compiler configuration and module reads are confined to that materialization, apart from the pinned TypeScript installation's standard library files. An attempted read outside those boundaries makes the result incomplete. The worker resolves aliases and symbol identity across discovered `tsconfig` projects, includes repository-owned declaration files, and returns definitions, consumers, positive domain-applicability and discovery-completeness signals, domain and resolution fingerprints, completeness, truncation, and explicit unknowns. An invalid configuration with TypeScript source remains applicable and incomplete; only a complete discovery with no TypeScript/JavaScript source or configuration is treated as language-inapplicable. Missing internal modules, configured types, requested declarations, or a transitive unresolved dependency of the requested symbol fail closed. An unrelated unavailable third-party package is reported explicitly but does not turn an otherwise closed repository-owned symbol boundary into a false negative. Compiler input is capped at 10,000 files and 64 MiB, the worker has a fixed 384 MiB V8 old-space ceiling, and stdout plus stderr share a 4 MiB live budget. Crossing a budget returns an unavailable or incomplete boundary.

After the turn, Byte stores the answer with its source spans, compiler query evidence, configuration and lockfile dependencies, and bounded query dependencies. Byte compares the target snapshot even when the current agent did not report an edit, so changes from another agent or external process are not dependent on lexical retrieval in a later prompt. Immediately before dispatching a tool from a compiler- or claim-grounded plan, Byte performs a best-effort working-snapshot recheck and blocks the action when the compiler boundary moved or an affected claim cannot be revalidated. A newly added consumer can therefore reopen a plan even when none of the originally cited lines changed.

## Durable data

The authoritative store is `.zyte/repository-intelligence.sqlite3`. SQLite runs in WAL mode. Source snapshots, evidence, claims, dependency baselines, checks, obligations, probes, results, and event cursors are durable. Before opening state, Byte rejects a linked or escaping `.zyte` directory and rejects non-regular, symbolic-linked, or hard-linked SQLite database, WAL, SHM, and journal paths. Byte creates `.zyte/.gitignore` with a deny-all rule and never edits the repository's root `.gitignore`. Snapshot blobs are compressed and content-addressed; materialization rejects escaping paths and symlinks.

The store supports three dependency forms:

- `exact_blob`: one path must retain its captured digest, including absence.
- `query_set`: a deterministic query must return the same bounded result.
- `negative_query`: a complete empty result remains valid only while no match appears in the declared domain.

Domain membership is tracked independently from query results. An added non-match causes a complete re-evaluation without needlessly reopening the claim. An added match, changed matching file, incomplete baseline, or analyzer-version change does reopen it.

## Public operations

The Python API, NDJSON host, and MCP server expose the same service operations:

| Python / host operation | MCP tool | Purpose |
|---|---|---|
| `snapshot_capture` | `byte_snapshot_capture` | Capture a stabilized immutable working-tree snapshot. |
| `typescript_boundary` | — | Resolve a TypeScript consumer set from the materialized immutable snapshot. |
| `claim_create` | — | Record a typed claim, evidence, and dependency baseline. |
| `knowledge_record_answer` | — | Store an agent interpretation and its validity boundary. |
| `knowledge_query` | `byte_knowledge_query` | Retrieve related claims and recheck applicability without executing code. |
| `claim_check` | `byte_claim_check` | Recheck named claims against a target snapshot. |
| `change_analyze` | `byte_change_analyze` | Produce obligations for changed or unknown dependencies. |
| `obligation_list` | `byte_obligation_list` | List unresolved decisions or checks. |
| `obligation_resolve` | `byte_obligation_resolve` | Resolve an obligation with a retained rationale. |
| `knowledge_events` | `byte_knowledge_events` | Consume monotonic snapshot, applicability, obligation, and probe events. |
| `probe_plan` | `byte_probe_plan` | Persist an immutable, non-executing experiment plan. |
| `probe_run` | `byte_probe_run` | Run a plan under the exact named user-configured policy. |
| `probe_get` | `byte_probe_get` | Read a stored probe plan. |

`capabilities` on the NDJSON host is the negotiation point. Older bundled engines do not expose these operations; the agent treats them as optional and retains normal retrieval and startup behavior.

## Trusted probes

Probe planning never executes repository code. Execution requires a policy whose ID exactly matches the plan and whose executable allowlist admits the resolved executable. Commands are argument arrays, never shell strings.

Policies are loaded from `~/.zyte/agent/probe-policies.json`, not accepted as a tool argument or discovered in the repository. `BYTE_PROBE_POLICY_FILE` can point the host process at an administrator-managed location. The file uses this shape:

```json
{
  "schema": 1,
  "policies": [
    {
      "id": "local-python-no-network",
      "allowed_executables": ["python3"],
      "timeout_seconds": 30,
      "max_output_bytes": 1000000,
      "allowed_domains": [],
      "environment": ["LANG", "LC_ALL", "PATH", "TMPDIR"]
    }
  ]
}
```

On Unix, group- or world-writable policy files are rejected. This protects the probe boundary from repository-supplied policy changes; it is not a privilege boundary against an administrator or another process already running as the same operating-system user.

On supported Linux and macOS hosts, the runner:

1. Reconstructs the immutable source snapshot in a disposable directory.
2. Materializes declared UTF-8 fixture files under `BYTE_PROBE_SCRATCH` and declared intervention files into the disposable snapshot.
3. Resolves the policy-approved executable only from an absolute administrator pin or fixed system directories. Relative, repository-local, ambient-`PATH`, and non-regular launchers are rejected; any outside-workspace link is canonicalized before its identity is captured.
4. Captures the executable's identity and SHA-256 digest, rechecks its identity immediately before launch, and starts it through the verified Anthropic Sandbox Runtime `0.0.55` layout with a root read deny, narrow runtime/source allow-backs, a stripped environment, read-only source, scratch-only writes, an explicit network domain list, output caps, and a timeout.
5. Records snapshot, policy, executable identity, executable and sandbox digests, plan, output digests, oracle result, and elapsed time.

Before repository code runs, a canary launches through the exact generated settings and must fail to read a fresh host-side secret outside `HOME`; this detects the runtime's permissive invalid-settings fallback. Stdout and stderr are drained concurrently into one bounded in-memory budget, and crossing it terminates the process group. There is no unrestricted fallback. Windows currently returns `unsupported`. Missing or unverified sandbox prerequisites, an unapproved executable, an invalid working directory, or a failed overlay also return an inconclusive result.

Only oracles declared as a published specification, user requirement, historical regression, or differential reference can produce `supports` or `refutes`, and each requires a concrete reference. A model-inferred oracle remains `inconclusive` even when its check passes. The source label is provenance, not cryptographic proof; callers are responsible for ensuring the referenced requirement is genuine and independent of the candidate implementation.

An oracle failure is `inconclusive` by default; the plan must explicitly declare when failure logically refutes its hypothesis. Recognized sandbox/bootstrap failures remain inconclusive even under such a declaration.

## Deliberate limits

- TypeScript completeness means complete within the discovered compiler projects. Runtime registration, reflection, generated sources outside those projects, remote consumers, and unsupported language semantics remain explicit unknowns.
- Compiler claims retain the adapter version, identifiers, domain/result fingerprints, and consumer locations. A cheap TypeScript-input/configuration fingerprint skips the compiler when nothing relevant changed; otherwise the target snapshot is materialized and the bundled worker reruns the query. Missing, mismatched, incomplete, or truncated worker results never authorize an impact-bearing action. Conservative identifier query sets remain as an additional invalidation signal.
- A stale plan remains blocked across continuation turns. The block clears only after a separate answer is grounded against a current snapshot and that snapshot remains stable through the end-of-turn check.
- An impact request without an extractable compiler identifier may use the structural evidence already attached for explanation, but all tool dispatch remains blocked until a fresh turn names a concrete symbol. The persistent IPython namespace is mutable, so Byte does not classify Python source text as a trustworthy read-only escape hatch.
- Boundary digests are consistency checks, not signatures. The bundled agent obtains boundaries from its host-validated compiler worker; callers of the lower-level public API can supply a self-consistent boundary record and must establish its provenance separately.
- Snapshot capture stabilizes file membership and metadata across the read. It is not an operating-system filesystem transaction against a hostile writer that preserves timestamps deliberately.
- The pre-tool recheck and subsequent tool dispatch are separate operations. Another writer can change the workspace between them, so this gate is not an atomic concurrency guarantee. Workflows that require a hard check-to-action guarantee must use an atomic workspace lease or execute in an isolated worktree whose write boundary is controlled for the full action.
- Ignored dependency directories are not embedded into snapshots. Probes must be self-contained or rely on tools available under the approved execution policy.
- A passing probe establishes its declared fixture, intervention, environment, and oracle. It is not a universal proof of arbitrary program behavior.
- The compiled Bun binary currently uses structural retrieval only; the separately bundled TypeScript worker runs in Node-based npm and R2 installations.

These limits are returned or documented because an unknown boundary is operationally different from an empty result.