# Reconstruct Boundary Contract

> Status: active reconstruct contract.
> Purpose: define `reconstruct` as a host-LLM-authored, runtime-validated
> two-stage process that first produces an `OntologySeed` and later matures it
> into an `ActionableOntology`.

## 1. Position

`reconstruct` has two named stages:

| Stage | Output | Boundary |
|---|---|---|
| `Ontology Seeding` | `OntologySeed` / `ontology-seed.yaml` | creates an evidence-backed seed and maturation frontier from source material |
| `Ontology Maturation` | `ActionableOntology` | repeatedly asks ontology-derived questions, collects convergent source evidence, answers the questions, and expands the ontology |

The seed is not a complete ontology, not action-ready, and not generated by
deterministic runtime code. It is a small, evidence-backed semantic contract
that lets later maturation work continue with clear source truth, gaps, and
frontiers.

The active reconstruct contract set is registry-owned. Runtime prompt packets,
validation gates, status surfaces, and result explanations must load the active
refs from
`.onto/processes/reconstruct/reconstruct-contract-registry.yaml#active_contract_refs`;
this boundary document explains ownership semantics but does not enumerate the
active set independently.

## 2. Ownership Boundary

The host LLM owns semantic authorship:

- purpose interpretation
- semantic naming and grouping
- object, actor, action, workflow, permission, and data-binding interpretation
- candidate disposition decisions
- competency-question authorship and assessment
- user-facing explanation

Runtime owns deterministic authority:

- target material classification
- selected source profile determination
- source inventory and observation
- evidence-ref closure
- artifact schema validation
- cross-artifact id closure
- validation gate reports
- execution manifests, progress state, and artifact refs
- fail-loud errors when required authored content is absent or malformed

Runtime must not silently fill missing ontology meaning. If a semantic field is
required but not LLM-authored, the run must fail a validation gate or present the
gap as an explicit handoff limitation.

## 3. Material Boundary

Every run starts by classifying the target with `target_material_kind`.

The material kind determines how runtime can observe source structure:

| Material kind | Runtime observation examples |
|---|---|
| `code` | files, symbols, imports, exported APIs, route handlers, configs, tests |
| `spreadsheet` | sheets, tables, formulas, named ranges, charts, protected ranges |
| `document` | headings, sections, tables, figures, references, metadata |
| `database` | schemas, tables, columns, keys, views, procedures, grants |
| `mixed` | explicit bundle members and per-member material kinds |
| `unknown` | bounded file metadata and unsupported-material failure details |

Material classification is orthogonal to domain. A code repository may describe
finance, education, legal, product operations, or another domain; a spreadsheet
may contain software planning, accounting, or sales operations.

## 4. Process Boundary

The reconstruct process is an evidence loop with semantic authoring gates:

```text
target refs
-> target material profile
-> source inventory
-> source observations
-> selected evidence directive
-> reconstruct lens judgments
-> exploration synthesis
-> next source frontier or source closure
-> candidate inventory and disposition
-> OntologySeed
-> competency questions and assessment
-> seed, question, assessment, confirmation, and seed-readiness validation gates
-> failure classification and revision proposal
-> final output and reconstruct record
```

Source exploration may repeat while the host LLM identifies unobserved source
refs that could change seed content or maturation frontier. Runtime validates the requested
frontier before observing additional source. Frontier-triggered observations
must carry round lineage before they can be used by later semantic authoring.

## 5. Active Artifacts

The canonical reconstruct session root is `.onto/reconstruct/<session-id>/`.

The complete artifact authority catalog is registry-owned at
`reconstruct-contract-registry.yaml#artifact_authorities`. This boundary groups
artifact responsibilities only:

- runtime preparation and observation artifacts;
- LLM-authored semantic artifacts;
- runtime validation artifacts;
- conditional proof authorities for query, visualization, and graph exploration;
- terminal handoff, final output, manifest, and record projections.

If implementation still writes a different artifact name, that name is an
implementation mismatch to remove before this contract can be called complete.

## 6. Seed Boundary

The primary semantic artifact is `ontology-seed.yaml`.

Its target shape is defined by
`.onto/processes/reconstruct/operational-ontology-seed-contract.md`.

The seed must include these layers:

- `seed_identity`
- `purpose`
- `decision_context`
- `conceptual_frame`
- `semantic_layer`
- `kinetic_layer`
- `dynamic_layer`
- `data_binding_layer`
- `validation_layer`
- `candidate_disposition_authority_ref`
- `ontology_handoff`
- `source_authority`
- `handoff_limitations`

The conceptual frame orients the reader. It does not replace object, actor,
action, workflow, permission, and data-binding content.

Seed validity also exposes three actionability coverage surfaces:

- `static_surface` — what exists, what it means, and what evidence grounds it
- `kinetic_surface` — who can do what and what changes or is recorded
- `dynamic_surface` — which conditions, permissions, states, exceptions,
  runtime contexts, external dependencies, or unresolved decisions change the
  answer

These surfaces are coverage axes over the existing seed layers, not separate
artifact authorities.

## 7. Candidate Disposition Boundary

High-salience candidates must not disappear.

When source evidence suggests a possible object, actor, action, workflow,
permission, data source, constraint, or domain concept, the seed must either
promote it into a layer or record why it is represented differently.

Allowed root dispositions and their meanings are owned by
`reconstruct-contract-registry.yaml#candidate_disposition_registry`. This
boundary document does not carry an independent disposition enum.

Every disposition needs a rationale and evidence refs.

`candidate-inventory.yaml` and `candidate-disposition.yaml` are the canonical
candidate authority seats. `ontology-seed.yaml` may only reference them through
`candidate_disposition_authority_ref`; it must not restate a second independent
disposition ledger.

## 8. Exploration Lineage Boundary

Repeated exploration is round-scoped. The current active runtime validates the
requested source frontier before use. Round-scoped observation delta,
delta-validation, re-entry validation, the session lineage index, and lineage
index validation are active authority seats in
`reconstruct-contract-registry.yaml`.

When `rounds/<round-id>/source-frontier.yaml` requests additional source refs,
runtime writes `rounds/<round-id>/source-observation-delta.yaml` after
observation. That delta must record:

- `round_id`
- `observation_batch_id`
- `triggering_frontier_ref`
- observed source refs
- created or updated observation ids
- validation ref for the frontier that authorized the observation
- `frontier_kind`
- `triggering_frontier_validation_ref`

Each new observation record in `source-observations.yaml` must carry the same
`observation_batch_id` and `round_id`. Later semantic artifacts that cite
frontier-triggered evidence must reference the relevant observation ids. Active
runtime validation proves prompt/context re-entry before the evidence is shown
to an LLM again, and answer-support validation proves consumption when the
evidence supports maturation answers. Broader downstream artifact-specific
consumption scanning remains planned until the relevant predicate evaluator is
promoted.

`source-observation-delta.yaml` is lineage evidence, not gate truth. Runtime
writes `rounds/<round-id>/source-observation-delta-validation.yaml` as the
pass/fail authority for `round_lineage_gate`. That validation artifact must
check that the delta cites an accepted frontier validation, every created or
updated observation exists, source refs and hashes match, and round, batch, and
triggering frontier validation ids match before downstream semantic use.

`source_frontier_gate` must validate duplicate status against
`source-observations.yaml` as well as inventory bounds.
`observation_reentry_gate` declares the prompt/context re-entry authorities it
checks. Answer-support consumption of newly observed delta observations is closed
by `answer-support-ledger-validation.yaml`; broader downstream artifact scanners
remain planned until their runtime evaluator is promoted.

## 9. Validation Boundary

Runtime validates structure, closure, and evidence. It does not validate truth by
inventing semantic content.

Active runtime gates are the entries in
`reconstruct-contract-registry.yaml#validation_gate_catalog`. This document does
not duplicate the active gate catalog; prose here explains boundary intent only.

Planned gates are kept in
`reconstruct-contract-registry.yaml#planned_validation_gate_catalog` and do not
block current handoff until promoted. That planned set includes
`ontology_handoff_mapping_gate`, query proof, visualization proof, graph
exploration proof, and explicit required-when-evaluation gates. Round lineage
and observation re-entry gates are active gates.

Non-terminal gate failures must be visible in `reconstruct-record.yaml`, status
reads, and final output when `handoff_gate` passes and terminal projection is
emitted. A failed `handoff_gate` is visible through status/result failure
surfaces and `handoff-decision-validation.yaml`; it does not require
`final-output.md` or `reconstruct-record.yaml` to be emitted as successful
validated handoff projections. A failed gate may still produce a useful partial
result, but the handoff limitation must be explicit.

Gate status authority belongs only to runtime-owned validation artifacts. The
LLM-authored seed may state validation requirements and refs, but it must not
state pass/fail gate truth.

`reconstruct-contract-registry.yaml` is the canonical machine-readable authority
for active artifact seats, validation gate catalog, source profile records,
reconstruct lens judgment records, validator records, version policy, and
readiness projection. Prose contracts define the semantics; runtime uses the
registry to decide which artifacts and gates are active for dispatch,
validation, status projection, and record assembly. A fact artifact and a gate
artifact must remain separate whenever pass/fail truth has a lifecycle of its
own; `target-material-profile.yaml` records selected material facts, while
`target-material-profile-validation.yaml` records `material_profile_gate` truth.

Seed confirmation is a lifecycle-required gate for seed validity and seed
iteration readiness, not an artifact-existence-only gate. If confirmation or its
runtime validation is absent when readiness is projected, status/result surfaces must
project `blocked` unless a valid confirmation-validation artifact records an
explicit limitation state. Handoff validation must consume the validation-result
authorities that contribute to readiness, not only raw authored artifacts or
`reconstruct-record.yaml` projections.
Those contributing authorities are selected through the registry's
`required_when` conditions. Missing required-and-applicable validation artifacts
project `blocked`; conditional artifacts whose `required_when` condition is not
met project `not_applicable` and do not block handoff by themselves.
Runtime evaluates each `required_when` through the registry-owned predicate
catalog, including input artifact refs, field-level truth expressions, unknown
projection, and status explanation text.
If an active gate uses a predicate expression without runtime evaluator support,
handoff validation fails closed with an unknown gate projection. It must not
silently treat that gate as `not_applicable`.
Terminal `handoff-decision-validation.yaml` is produced by `handoff_gate`.
`final-output.md` and `reconstruct-record.yaml` are emitted after that validation
passes; they are projections from the validated terminal readiness result, not inputs to
`handoff-decision-validator`.
`final-output-provenance-validation.yaml` is a post-handoff projection check, not
an input to readiness projection.
Terminal handoff validation also requires
`reconstruct-run-manifest.pre-handoff-validation.yaml` so final projection cannot
rely on an unvalidated registry, contract, source-profile, validator,
reference-standard, version, or migration snapshot. The final
`reconstruct-run-manifest.post-publication-validation.yaml` is a post-publication audit for the
complete manifest after final output and record refs exist; it is not an input to
pre-handoff seed iteration readiness projection.
Earlier validators consume only already-authored authorities. In particular,
`ontology-seed-validation.yaml` may validate expected competency coverage axes,
but it must not require downstream competency-question ids before the question
artifact is authored; later question validation closes question refs back to the
validated seed.

## 10. User-Facing Boundary

The result must be useful for the next `Ontology Maturation` iteration.

The final output must show:

- what the seed says the target is for
- which objects, actors, actions, workflows, permissions, and data bindings were
  found
- what can be trusted for the next maturation iteration
- what remains unsupported or uncertain
- what questions, evidence targets, or maturation steps should come next
- which artifacts contain the structured authority

The final output must not present orientation concepts as if they were the full
ontology seed.

## 11. MCP Surface Boundary

MCP tools expose bounded reconstruct operations:

| Tool | Responsibility |
|---|---|
| `onto_list_source_profiles` | list supported material profiles |
| `onto_observe_source` | produce runtime source observations |
| `onto_validate_reconstruct_directive` | validate an authored directive against runtime observations |
| `onto_reconstruct` | run the reconstruct process |
| `onto_reconstruct_status` | read progress, liveness, stage state, and artifact refs |
| `onto_reconstruct_result` | read final output, record refs, and structured result projection |

Tool responses should expose artifact refs and validation state, not duplicate a
second semantic authority.

## 12. Source Profile And Extension Boundary

`SourceProfileDefinition` is contract-owned and lives under
`.onto/processes/reconstruct/source-profiles/`.

`SelectedSourceProfile` is runtime-owned and recorded in
`target-material-profile.yaml` after material classification. The host LLM may
use the selected profile as context, but it must not choose the profile or expand
the observation boundary.

Source profile status is split. `contract_status` says whether a profile
definition or public material kind is authoritative. `runtime_implementation_status`
says whether the current runtime can execute that profile. A contract-active
profile may still be planned, partially wired, unsupported, or halt-only at
runtime.

Candidate kinds and dispositions have stable base enums in
`candidate_kind_registry` and `candidate_disposition_registry`. Source profiles
may add profile-specific qualifiers through `candidate_subkind` or
`disposition_detail`, but adding a new root candidate kind, disposition, or
material kind requires a contract change and registry update.

## 13. Documentation Hygiene

Active reconstruct prompts and contracts may load only the active contract set
listed in Section 1.

Development history belongs outside runtime reference paths. Historical notes
must not be referenced by runtime prompt packets, active source profiles, active
UX contracts, or MCP result wording unless a user explicitly asks for that
history.
