engineering-behavior-observatory 0.2.1

package/docs/README.md

@@ -0,0 +1,60 @@
+# EBO documentation
+
+Start with the question you need to answer. Operational guides explain what to
+do; reference pages describe the exact contracts. All shell examples assume
+the `ebo` command is installed as described in the quickstart.
+
+## Start here
+
+1. [Quickstart](guides/quickstart.md): install EBO and open a synthetic
+   report without credentials; then prepare for a real capture.
+2. [Choose a harness](harnesses/README.md): compare execution boundaries,
+   evidence coverage, and prerequisites.
+3. [Operator guide](guides/operator-guide.md): prepare, freeze, execute,
+   inspect, export, and evaluate a task.
+
+## Operate and inspect
+
+- [Evidence and sharing](guides/evidence-and-sharing.md): which files to read,
+  how to interpret a partial run, and how to create a portable archive.
+- [Telemetry](guides/telemetry.md): native events versus OTLP, collector receipt,
+  Grafana, and resource-accounting caveats.
+- [Behavior Atlas](guides/atlas.md): cohort filters, cited evidence, Grafana
+  provisioning, and static reports.
+
+## Harness guides
+
+[Claude Agent SDK](harnesses/claude-agent-sdk.md) ·
+[Codex](harnesses/codex-harness.md) · [Cursor](harnesses/cursor-sdk.md) ·
+[Pi](harnesses/pi-sdk.md) · [OpenHands](harnesses/openhands-agent-server.md) ·
+[DeepSeek Harness](harnesses/deepseek-harness.md)
+
+These guides own runtime pins, configuration, native evidence, and known gaps.
+
+## Evaluate behavior
+
+The [evaluation reading path](evaluation/README.md) explains how the parts fit:
+
+- [Uniform events](evaluation/uniform-events.md) and
+  [normalization integrity](evaluation/normalization-integrity.md)
+- [Structural observations](evaluation/structural-observations.md)
+- [Behavior assertions](evaluation/behavior-assertions.md) and
+  [semantic judging](evaluation/semantic-judge.md)
+- [Human calibration](evaluation/human-calibration.md)
+- [Comparison and aggregation](evaluation/aggregation.md)
+
+## Build and look things up
+
+- [Reference index](reference/README.md): grouped CLI syntax, packet/experiment
+  contracts, run bundles, lifecycle, and Agent SDK configuration.
+- [Contributor guide](development/README.md): checks, documentation ownership,
+  and release preparation.
+- [Extension contracts](development/extension-contracts.md): adapter, extractor,
+  rubric, verifier, and export-policy development.
+- [Documentation sync findings](development/documentation-sync.md): why generated
+  change provenance is kept separate from public documentation.
+- [Release records](../release/README.md): versioned verification and limitations.
+
+For agents: read the repository's `AGENTS.md`, then the relevant guide and
+contract. CLI syntax is in [one grouped reference](reference/cli.md), not
+scattered through release history.

package/docs/development/README.md

@@ -0,0 +1,71 @@
+# Contribute to EBO
+
+Start with the repository's `AGENTS.md`, then
+[the documentation index](../README.md). The TypeScript coordinator owns
+evidence capture and evaluation; each harness retains its native protocol and
+semantics.
+
+## Set up and check
+
+Use the pinned Node version and build before invoking the checkout's CLI:
+
+```sh
+nvm use
+npm ci
+npm run build
+npm link
+ebo --help
+npm run typecheck
+npm test
+git diff --check
+```
+
+The test suite is deterministic by default. Live provider smokes are opt-in,
+consume external capacity, and require approved credentials. Their instructions
+belong in the relevant harness guide. Do not treat a skipped live test as proof
+of provider access.
+
+Use [extension contracts](extension-contracts.md) when adding an adapter,
+structural extractor, rubric, verifier, or export policy. Preserve native
+records and qualified partial attempts before adding derived views.
+
+## Documentation ownership
+
+- **README:** motivation, harness overview, installation, quickstart, navigation.
+- **Guides:** executable workflows and recovery.
+- **Harnesses:** source-specific setup, pins, policies, evidence, and limitations.
+- **Evaluation:** methods, semantics, interpretation boundaries.
+- **Reference:** exact syntax and artifact contracts.
+- **Release records:** version-specific changes, verification, and limitations.
+
+Before adding a page, check whether an existing page already owns the topic.
+Link every new page from a relevant index. Update relative links when moving
+documents, including links from release records and packaged examples.
+Use `ebo` in operator commands; keep Node invocations for tests and scripts
+that are not CLI commands. Do not duplicate the complete CLI in the README.
+
+Run a cold-reader check: can a newcomer follow the commands without knowing
+which placeholders, working directory, credentials, or prior artifacts they
+need? Keep runnable examples separate from syntax templates.
+
+## Memory and documentation sync
+
+OpenSymphony memory remains available for implementation provenance. In this
+repository its generated topic notes are private and excluded from the package.
+Public docs are authored from current implementation and verified behavior,
+not generated issue lists.
+
+`opensymphony memory sync-docs` updates private notes; it no longer writes
+the public guide tree. After a feature change, use those notes to find evidence
+and deliberately update the relevant authored guide. See
+[the sync failure analysis](documentation-sync.md).
+
+## Release gate
+
+From a **clean** checkout, `npm run acceptance` runs the deterministic suite,
+checks fixture digests and documentation links, scans the package, and verifies
+two byte-identical package builds. It writes under
+`.ebo/releases/<package-version>/`; it does not publish or tag.
+
+See [release records](../../release/README.md). A documentation edit after a
+tag belongs to a later change; do not move an existing release tag to include it.

package/docs/development/documentation-sync.md

@@ -0,0 +1,58 @@
+# Documentation sync: failure signals and local policy
+
+## What failed
+
+The public docs tree had 58 Markdown files. After removing managed sync blocks
+and frontmatter, **39 contained only a title**. They were provenance summaries,
+not documentation a reader could use.
+
+Examples included `adapters.md` and `documentation.md`. Their managed
+sections listed issue contributions, generic invariants, and statements that
+no gotchas or diagrams had been inferred. They provided no operational model,
+configuration, example, or recovery instructions.
+
+Area associations also spread across unrelated topics: foundation and SDK
+integration issues appeared in many area lists. A high mapping confidence and
+a clean public-link lint did not establish topical relevance or usefulness.
+
+## Why it matters
+
+- Alphabetical navigation gave empty pages the same prominence as real guides.
+- Repeated contribution lists obscured substantive content.
+- `Docs pending: 0` meant the sync ran, not that user-facing behavior was
+  documented.
+- Incremental syncing encouraged append-only maintenance rather than designing
+  an entry point around reader tasks.
+
+## EBO's containment change
+
+The repository memory configuration routes generated topic notes to the
+ignored private memory tree and sets their visibility to private. Public
+managed blocks and title-only pages are removed. Authored guides are grouped
+by purpose and linked from a documentation index.
+
+Memory capture and provenance are preserved. The broad learned area mappings
+are not repaired by this change; their output is simply kept out of public
+docs. No OpenSymphony engine behavior is changed.
+
+Future captures may learn mappings again. Inspect sync's dry-run target paths
+before applying it, and keep public authored guides out of generated targets.
+Do not rerun initialization with force merely to regenerate public pages.
+
+## Candidate acceptance checks for a future OpenSymphony fix
+
+These are proposed product checks, not implemented EBO features:
+
+1. A page consisting only of a title and generated boilerplate should remain
+   private provenance, not become public documentation.
+2. Topic relevance should come from narrow source evidence; shared milestone
+   membership alone should not spread every issue across every area.
+3. A sync report should distinguish provenance updated, authored documentation
+   reviewed, and actual user-facing coverage.
+4. Generated output should identify concrete behaviors and limitations, or
+   state that human authoring is needed without publishing an empty page.
+5. Validation should test whether an intended reader can perform a documented
+   action, in addition to checking links and privacy.
+
+Use this case as a reproducible failure example when revisiting sync-docs.
+Do not replace the issue lists with invented implementation prose.

package/docs/development/extension-contracts.md

@@ -0,0 +1,307 @@
+# Extension contracts
+
+EBO extensions are ordinary, explicit TypeScript registrations backed by
+contract tests. There is no dynamic package discovery, plugin registry, or
+universal harness protocol. Add a loader only if separately installed
+third-party extensions become a demonstrated requirement.
+
+Start with `npm ci && npm run build`. Every command below runs a checked-in
+contract fixture with Node's test runner. The snippets are minimal shapes;
+copy the nearby production adapter/test that matches the source boundary and
+replace only source-owned fields.
+
+## Harness capture and normalization adapter
+
+Implement a `HarnessAdapter<Request, NativeRecord>` with separate capture and
+normalization members, then register it explicitly:
+
+```ts
+import {
+  AdapterRegistry,
+  assertAdapterContract,
+  type HarnessAdapter,
+} from "engineering-behavior-observatory";
+
+type NativeRecord = { kind: string };
+
+const adapter: HarnessAdapter<Request, NativeRecord> = {
+  capture: {
+    id: "example-adapter",
+    harness: "example-harness",
+    capture: async (request) => captureNativeRecords(request),
+  },
+  normalization: {
+    id: "example-adapter",
+    harness: "example-harness",
+    capabilityProfile,
+    normalize: async (capture) => projectQualifiedCapture(capture),
+  },
+};
+
+await assertAdapterContract(adapter, request, nativeEvidenceResolver);
+const adapters = new AdapterRegistry([adapter]);
+```
+
+Evidence obligations:
+
+- persist native records before projection and give every mapped event a
+  resolvable `artifactId` plus `recordLocator`;
+- normalize only qualified or qualified-with-gaps capture;
+- declare every native type and available/partial/unsupported capability;
+- keep unknown, unsupported, and missing values explicit;
+- retain every native record as mapped or explicitly unmapped; and
+- preserve source run/attempt identity, ordering domains, timestamps,
+  parentage, content references, and terminal semantics without inference.
+
+Runnable contract fixture:
+
+```sh
+node --test --test-name-pattern='minimal capture and normalization adapter contract' \
+  dist/test/uniform-events.test.js
+```
+
+Current source-specific examples are the Agent SDK normalizer,
+`createOpenHandsHarnessAdapter`, `createDeepSeekHarnessAdapter`, and
+`createCodexHarnessAdapter`; `createCursorSdkBehaviorEvidence` applies the same
+native-first contract to the direct SDK boundary. A new adapter must not weaken
+their rules to fit a common convenience model.
+
+The Pi integration uses direct public SDK session/history/subscription APIs in
+`src/pi.ts`, without forcing Pi into a process protocol.
+
+## Source-specific process or API boundary
+
+Use `runProtocolProcess` only for a source whose owned child actually speaks
+newline-delimited JSON on stdout:
+
+```ts
+import { runProtocolProcess } from "engineering-behavior-observatory";
+
+const result = await runProtocolProcess({
+  command: runtime,
+  args: ["serve"],
+  source: "example-harness",
+  evidencePath: "evidence/protocol.jsonl",
+  stderrPath: "evidence/stderr.log",
+  onFrame: async (frame, recorder) => {
+    await recorder.recordNotification({
+      source: "example-harness",
+      method: nativeMethod(frame),
+      payload: frame,
+    });
+  },
+});
+```
+
+This reusable layer owns bounded frame parsing, append-only JSONL recording,
+stderr capture, interruption, teardown, and partial evidence. The adapter still
+owns source method schemas, request/response correlation, session identities,
+capabilities, and completion evidence. A clean process exit is not a source
+completion event.
+
+DeepSeek integrations must use the official
+`@deepseek-ai/dsh-sdk-client` and `@deepseek-ai/dsh-sdk-protocol` packages. The
+official client owns JSON-RPC framing, transport, and teardown; EBO records its
+typed calls/notifications rather than recreating the protocol client with
+`runProtocolProcess`. OpenHands uses its pinned REST/WebSocket contract, and
+Codex uses its pinned app-server contract; neither is forced into a generic
+JSONL method schema.
+
+Cursor uses direct `Agent.create({ local: ... })`, `send`, detailed callbacks,
+stream/wait/conversation, and the exported `JsonlLocalAgentStore`. Its durable
+store and callback channels overlap with the stream; retain them separately and
+select one authoritative normalized source instead of counting them twice.
+
+Evidence obligations:
+
+- append source frames/observations in observed order before deriving state;
+- bound stdout frames and diagnostics before parsing/retention;
+- distinguish malformed output, recorder failure, interruption, shutdown, and
+  natural exit; and
+- retain a readable partial record when the source terminates unexpectedly.
+
+Runnable contract fixture:
+
+```sh
+node --test --test-name-pattern='records JSONL frames' \
+  dist/test/process-protocol.test.js
+```
+
+## Structural extractor
+
+Structural extractors are deterministic entries in
+`STRUCTURAL_EXTRACTOR_REGISTRY`, not runtime-loaded classes:
+
+```ts
+const registration = {
+  id: "example-explicit-tool-failure-count",
+  requiredCapabilities: ["family:tool"],
+  definition: "Distinct native tool operations with an explicit failure.",
+} as const;
+```
+
+Add the registration and its extraction function in
+`src/structural-observations.ts`, bump `STRUCTURAL_EXTRACTOR_VERSION`, update
+both extractor-version constraints in
+`schemas/structural-observations.v1.json`, then add one small golden fixture
+case. Schema/readback changes must continue accepting already retained
+extractor versions. Every registry or extraction-behavior change requires this
+coordinated version update so new observations validate and retained provenance
+stays unambiguous. Do not use a semantic heuristic for a structural fact.
+
+Evidence obligations:
+
+- state the denominator, unit, and exact native condition being counted;
+- cite every contributing native record and normalized source event;
+- deduplicate only on a source-owned stable identity;
+- emit `unavailable` with a reason when required capability/order/identity is
+  absent; and
+- never turn missing evidence into zero or combine cumulative usage snapshots.
+
+Runnable contract fixtures:
+
+```sh
+node --test --test-name-pattern='golden structural facts|available zero' \
+  dist/test/structural-observations.test.js
+```
+
+## Rubric and semantic judge backend
+
+A rubric is caller-owned data inside a versioned
+`SemanticJudgeRequest`; it is not executable plugin code:
+
+```ts
+import type { SemanticJudgeRequest } from "engineering-behavior-observatory";
+
+const rubric: SemanticJudgeRequest["rubric"] = {
+  id: "example-verification-rubric",
+  version: "1.0.0",
+  instructions: "Assess only whether cited evidence shows validation.",
+};
+```
+
+The caller also selects the evaluator. Omit `backend` (or use
+`claude-agent-sdk`) with provider `anthropic`, or use `codex-app-server` with
+provider `openai`. Model, effort, limits, and optional executable remain
+configuration; no automatic fallback occurs. Extend backend code only when an
+issue explicitly requires another trusted execution boundary.
+
+Evidence obligations:
+
+- select bounded event and structural-observation IDs explicitly;
+- treat packaged trajectory text as untrusted data;
+- require citations for assessed claims plus rationale and an alternative
+  explanation;
+- allow abstention when evidence is insufficient; and
+- retain evaluator configuration identity without exposing secrets or
+  silently changing model/effort.
+
+Runnable contract fixtures:
+
+```sh
+node --test --test-name-pattern='request schema admits exactly|packages bounded blinded' \
+  dist/test/semantic-judge.test.js
+node --test dist/test/codex-judge.test.js
+```
+
+## Verified-task verifier
+
+A verifier is an admitted, digest-pinned CommonJS or ESM file, not an arbitrary
+command. It reads the private workspace snapshot path from `process.argv[2]`
+and writes one JSON object to stdout. Compile this TypeScript example to
+CommonJS or ESM before digesting and admitting it. Admit compiled ESM with an
+`.mjs` locator; the operational runners treat every other locator as CommonJS:
+
+```ts
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const workspace = process.argv[2];
+const passed = readFileSync(join(workspace, "result.txt"), "utf8") === "done\n";
+if (!passed) process.exitCode = 1;
+process.stdout.write(JSON.stringify({
+  assertions: [{ id: "expected-result", status: passed ? "passed" : "failed" }],
+}));
+```
+
+Evidence obligations:
+
+- use only the admitted digest-pinned verifier and evaluated workspace
+  snapshot;
+- emit bounded assertion IDs with `passed` or `failed` status;
+- write diagnostics to stderr, not additional stdout records;
+- preserve timeout/crash/malformed output as verifier error evidence; and
+- never run a verifier for an observational packet or treat not-run as passed.
+
+Runnable contract fixtures:
+
+```sh
+node --test --test-name-pattern='executes a verifier outside|preserves ESM' \
+  dist/test/verifiers.test.js
+```
+
+## Export policy
+
+An export policy is explicit caller data passed to the existing fail-closed
+export implementation:
+
+```ts
+import {
+  createPortableRunBundleExport,
+  type PortableExportPolicy,
+} from "engineering-behavior-observatory";
+
+const policy: PortableExportPolicy = {
+  sharingClass: "partner",
+  maxArtifactBytes: 16 * 1024 * 1024,
+  maxStringBytes: 8192,
+  sensitiveValues: [callerKnownConfidentialValue],
+};
+
+await createPortableRunBundleExport({
+  sourceRoot: restrictedRunBundle,
+  destinationRoot: newExportRoot,
+  policy,
+});
+```
+
+Keep caller-known `sensitiveValues` with restricted study inputs and never
+commit real values. See [the operator guide](../guides/operator-guide.md#5-export-an-approved-derivative)
+for handling details.
+
+Extend the existing sanitizer/readback only when a new artifact kind has an
+explicit sharing classification. Do not add a permissive fallback.
+
+Evidence obligations:
+
+- leave the restricted source bundle unchanged;
+- allow only known artifact kinds and classifications;
+- remove hidden reasoning, secrets, environment values, and local identifiers;
+- rewrite correlation IDs and verify every output digest; and
+- rerun policy-bound readback and secret scanning before use or packing.
+
+Runnable contract fixtures:
+
+```sh
+node --test --test-name-pattern='exports a sanitized|fails closed on unknown' \
+  dist/test/exports.test.js
+```
+
+## Contract checklist
+
+For every extension:
+
+1. Pin the source runtime/API/schema version and record configuration digests.
+2. Name native evidence, completion semantics, known gaps, and unsupported
+   capabilities before mapping anything.
+3. Preserve partial/failed attempts and immutable native evidence.
+4. Add one focused `node:test` contract fixture beside the closest existing
+   test; use synthetic or permissively licensed data only.
+5. Run the targeted fixture, `npm run build`, `npm run typecheck`, `npm test`,
+   and `git diff --check`.
+6. Update [the operator guide](../guides/operator-guide.md) only if the public command or
+   operational recovery path changed.
+
+These are implementation workflows. Task authorship, model selection, study
+execution, human corpus review, trial counts, and partner delivery remain
+caller-owned operations outside the extension contract.

package/docs/evaluation/README.md

@@ -0,0 +1,48 @@
+# Evaluate behavior
+
+Start with a captured run and a question: did the agent validate its changes?
+How did it respond to a tool failure? Was repeated investigation useful or
+redundant? A tool count alone cannot answer those questions.
+
+```mermaid
+flowchart TD
+  A["Qualified native bundle"] --> B["Uniform events with native citations"]
+  B --> C["Structural observations"]
+  B --> D["Bounded evidence + rubric"]
+  C --> D
+  D --> E["Judge proposal or abstention"]
+  E --> F["Human review / adjudication"]
+  C --> G["Comparison and aggregation"]
+  F --> G
+  G --> H["Atlas / report"]
+```
+
+## Reading path
+
+| Step | Read | Result |
+| :--- | :--- | :--- |
+| 1. Establish what is observable | [Uniform events](uniform-events.md), [integrity gates](normalization-integrity.md) | Source-bound events, unmapped records, capability coverage |
+| 2. Extract exact facts | [Structural observations](structural-observations.md) | Counts, resource observations, explicit denominators and missing values |
+| 3. Ask a behavioral question | [Assertions](behavior-assertions.md), [semantic judge](semantic-judge.md) | Cited proposal or abstention for one rubric dimension |
+| 4. Review the interpretation | [Human calibration](human-calibration.md) | Human-authored decisions and agreement populations |
+| 5. Compare declared conditions | [Aggregation](aggregation.md) | Descriptive distributions, matched differences, exclusions and caveats |
+| 6. Explore or report | [Behavior Atlas](../guides/atlas.md) | Local drilldown and reproducible report |
+
+The judge backend is independent of the evaluated harness: choose the Claude
+Agent SDK or native Codex backend explicitly. EBO retains the evaluator, rubric,
+evidence selection, limits, and configuration identity.
+
+## Keep three questions separate
+
+- **Did execution end?** The terminal record answers this.
+- **Did we capture enough evidence?** Qualification and capability coverage
+  answer this, separately for each relevant signal.
+- **Was the behavior useful?** A cited interpretation and review can address
+  this; execution status and counts cannot substitute for it.
+
+A failure followed by another operation is a structural observation, not proof
+of recovery. An absent tool family is not necessarily zero activity. Repeated
+judge calls are not additional independent engineering trials.
+
+Use the [operator workflow](../guides/operator-guide.md#6-normalize-and-extract-structural-observations)
+for commands, and [CLI reference](../reference/cli.md) for complete syntax.

package/docs/evaluation/aggregation.md

@@ -0,0 +1,112 @@
+# Comparison and aggregation
+
+`ebo aggregate build` creates a deterministic local read model from a current
+corpus index, structural observations, proposed behavior assertions, human
+calibration lineage, and per-measure comparison eligibility reports. It reads
+JSON/JSONL directly and writes one derived JSON document outside the source
+corpus; it does not alter retained bundles.
+
+```sh
+ebo aggregate build request.json aggregate.json
+```
+
+The request uses paths relative to `request.json`:
+
+```json
+{
+  "schemaVersion": "ebo.aggregation-request/v1",
+  "sources": {
+    "corpusRoot": "corpus",
+    "corpusIndex": "corpus-index.jsonl",
+    "observationSets": [{ "bundleRoot": "corpus/run-a", "path": "derived/observations/run-a.json" }],
+    "assertions": [{ "bundleRoot": "corpus/run-a", "path": "derived/assertions/assertion-a.json" }],
+    "calibrations": [{
+      "selection": "derived/review/selection.json",
+      "history": "derived/review/history.json"
+    }]
+  },
+  "groupBy": ["task", "model", "harness"],
+  "selectedAttemptPolicy": "all-attempts",
+  "recurrence": { "minimumOccurrences": 2 },
+  "comparisons": [{
+    "id": "matched-verifier-outcome",
+    "measure": "verified:verifier-passed",
+    "left": { "model": "model-a" },
+    "right": { "model": "model-b" },
+    "matchBy": ["task", "harness", "trial"],
+    "eligibilityGates": [{
+      "request": "derived/comparisons/model-a-model-b.request.json",
+      "report": "derived/comparisons/model-a-model-b.report.json"
+    }]
+  }]
+}
+```
+
+Grouping dimensions are `task`, `model`, `harness`, `trial`, and
+`capture-qualification`. `all-attempts` is the evidence-preserving default.
+`trial` is the queue's retained numeric trial index; legacy bundles without it
+remain unavailable and are excluded from trial-matched comparisons.
+`latest-attempt-per-run` selects the highest declared attempt number regardless
+of terminal state and reports every excluded earlier attempt; it never searches
+for or substitutes a completed retry.
+
+Each metric names its run, attempt, operation, assertion, or reviewed-assertion
+population and carries numerator, denominator, units, exclusions, and a claim
+status. Empty denominators are `unavailable`. Observational completion is only
+a terminal-state measure; task-success rates come only from available verified
+attempt outcomes. Duplicate identical inputs are counted once, while conflicting
+records with the same identity fail the build.
+
+Each group's additive `behaviors` array retains constructive, adverse, mixed,
+and context-dependent distributions separately from review agreement. A
+partition names the exact vocabulary/category/dimension, rubric id/version,
+and evaluator identity/version/configuration digest. Missing legacy evaluator
+configuration stays a separate partition. Its denominator is distinct
+confirmed attempt-dimensions, not judge calls: agreeing confirmed reruns count
+once and conflicting confirmed reruns exclude that attempt. Disputed,
+unreviewed, rejected, and abstained assertions cannot contribute; assertion
+references expose review outcome and inclusion alongside run/attempt/digest.
+An empty denominator is unavailable. These distributions remain descriptive.
+
+Corpus indexing prefers `structuralQualification.status` over legacy
+`qualification`. Legacy-only known states remain readable; missing or invalid
+structural status is unavailable. Qualified-with-gaps, incomplete, unqualified,
+and unavailable remain distinct. Rebuild older corpus indexes before using
+them; source manifests and native artifacts are never rewritten.
+
+Every report retains the logical request and corpus-index digests plus the
+exact admitted manifest, observation-set, assertion, calibration, and
+comparison-gate digests. Moving the report therefore does not detach its
+metrics from their rebuild inputs.
+
+Observation and assertion sources name their retained bundle so the build can
+recompute structural observations, resolve assertion citations, and reject
+stale derived evidence. Calibration selections are likewise reloaded from their
+digest-bound sources before their review history contributes to a metric.
+Legacy v1 structural sets without the optional declared capability profile stay
+readable; aggregation and semantic judging rebuild that profile from the native
+bundle before use.
+
+Matched comparisons require one candidate on each side for every caller-chosen
+match key and one eligibility report whose candidate IDs are those two run IDs.
+Missing, ambiguous, unavailable, or ungated pairs are exclusions. Supported
+measures are `attempt:infrastructure-failure`,
+`attempt:terminal-completed`, `verified:verifier-passed`, and any numeric
+`structural:<extractor-id>` observation. The supplied comparison gate applies
+only to that candidate pair, must name the exact measure, and must include the
+measure's required capability;
+an unsupported gate makes the comparison
+unavailable, and partial-capability or declared-condition caveats remain in the
+output.
+
+Each eligibility report carries the digest of its source comparison request.
+The aggregate build reloads that request and recomputes the report before using
+the gate, so an edited or stale report cannot authorize a matched difference.
+These bindings use `ebo.comparison-request/v2` and
+`ebo.comparison-report/v2`; the original v1 request/report remain supported by
+`ebo comparison check` but do not contain enough lineage for aggregation.
+
+The caller supplies the recurrence threshold. A divergent matched unit below
+that threshold is a `case-study`; reaching it yields only a
+`recurring-description`. Neither state establishes causality or statistical
+significance, and the report never emits a composite model ranking.