# Reconstruct Boundary Contract

> Status: active reconstruct contract.
> Purpose: define `reconstruct` as a host-LLM-authored, runtime-validated
> process that produces an actionable ontology seed.

## 1. Position

`reconstruct` turns a source material set into an `ActionableOntologySeed`.

The seed is not a complete ontology and is not generated by deterministic
runtime code. It is a small, evidence-backed semantic contract that lets later
work decide, design, review, and act against the target with clear limits.

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
-> ActionableOntologySeed
-> competency questions and assessment
-> seed, question, assessment, confirmation, and handoff 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 actionable seed content. 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/foundry-style-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.

## 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. Multi-round observation delta and re-entry
validation are planned authority seats until their validators are implemented
and promoted 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

Each new observation record in `source-observations.yaml` must carry the same
`observation_batch_id` and `round_id`. Later directives, lens judgments,
exploration synthesis, candidate inventory, and seed artifacts must reference
the relevant observation ids. A run cannot finalize candidate inventory from
frontier-triggered evidence until that evidence has re-entered directive,
lens judgment, and synthesis.

`source-observation-delta.yaml` is lineage evidence, not gate truth. When the
planned multi-round validators are promoted, 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, and round and batch ids match before downstream semantic
use.

`source_frontier_gate` must validate duplicate status against
`source-observations.yaml` as well as inventory bounds.
The planned `observation_reentry_gate` must declare the downstream re-entry
authorities it checks, including lens judgments, exploration synthesis,
candidate inventory/disposition, and seed validation artifacts.

## 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
`round_lineage_gate`, `observation_reentry_gate`,
`ontology_handoff_mapping_gate`, query proof, visualization proof, graph
exploration proof, and explicit required-when-evaluation 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 handoff
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 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 decision and action planning.

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 declared purpose
- what remains unsupported or uncertain
- what the next action should be
- 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 under `development-records/`. 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.
