onto-mcp 0.3.0 → 0.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (27) hide show
  1. package/.onto/authority/core-lexicon.yaml +11 -0
  2. package/.onto/processes/evolve/material-kind-adapter-contract.md +6 -0
  3. package/.onto/processes/reconstruct/reconstruct-boundary-contract.md +246 -46
  4. package/.onto/processes/reconstruct/reconstruct-execution-ux-contract.md +144 -0
  5. package/.onto/processes/review/binding-contract.md +8 -0
  6. package/.onto/processes/review/pre-dispatch-contracts.md +34 -13
  7. package/.onto/processes/review/productized-live-path.md +3 -1
  8. package/.onto/processes/shared/pipeline-execution-ledger-contract.md +185 -0
  9. package/.onto/processes/shared/target-material-kind-contract.md +6 -0
  10. package/AGENTS.md +3 -2
  11. package/README.md +31 -14
  12. package/dist/core-api/reconstruct-api.js +70 -0
  13. package/dist/core-api/review-api.js +622 -4
  14. package/dist/core-runtime/cli/render-review-final-output.js +9 -0
  15. package/dist/core-runtime/cli/review-invoke.js +364 -7
  16. package/dist/core-runtime/cli/run-review-prompt-execution.js +239 -90
  17. package/dist/core-runtime/pipeline-execution-ledger.js +100 -0
  18. package/dist/core-runtime/reconstruct/artifact-types.js +28 -1
  19. package/dist/core-runtime/reconstruct/pipeline-execution-ledger.js +306 -0
  20. package/dist/core-runtime/reconstruct/post-seed-validation.js +617 -0
  21. package/dist/core-runtime/reconstruct/record.js +94 -1
  22. package/dist/core-runtime/reconstruct/run.js +479 -30
  23. package/dist/core-runtime/review/continuation-plan.js +160 -0
  24. package/dist/core-runtime/review/pipeline-execution-ledger.js +250 -0
  25. package/dist/mcp/server.js +134 -23
  26. package/dist/mcp/tool-schemas.js +6 -0
  27. package/package.json +2 -2
@@ -226,6 +226,14 @@ binding_notes:
226
226
  recommendation, explicit token, 주체자 확인 결과를
227
227
  최종 값으로 materialize한 결과여야 한다.
228
228
 
229
+ 단, interpretation/config 단계에서 explicit domain이 없고 configured domain도
230
+ 없으면 runtime은 review target의 path/content/intent와 available domain 문서의
231
+ bounded signal을 비교해 `domain_final_selection`을 자동 materialize할 수 있다.
232
+ 이 경우 `selection_mode`는 target 기반 자동 선택임을 드러내야 하며,
233
+ 왜 해당 domain을 골랐는지는 `binding_notes`에 사용자에게 설명 가능한 문장으로
234
+ 남긴다. 충분한 signal이 없어서 `none`으로 가는 경우도 같은 방식으로 이유를
235
+ 남긴다.
236
+
229
237
  ---
230
238
 
231
239
  ## 7. Prompt / MCP / Runtime Effect
@@ -252,16 +252,32 @@ lifecycle_state: dispatched
252
252
  Runtime-generated packet registration preserves `lifecycle_state: dispatched`
253
253
  and appends/upserts the generated packet ref before invoking the unit.
254
254
 
255
- ### 5.3 Freshness And Resume
255
+ ### 5.3 Freshness And Continuation
256
256
 
257
- Current canonical MCP review does not expose an explicit resume tool.
257
+ Current MCP review/status/result can read halted session artifacts. The planned
258
+ explicit continuation surface is `onto.review_continue`; its design lives in
259
+ `docs/architecture/review-continuation-surface.md`.
258
260
 
259
- `review-run-manifest.yaml` records a `resume_token` for audit, idempotency, and
260
- future operator-controlled resume design only. The token is not a dispatch
261
- capability and must not be accepted as authorization to restart, skip, or reuse
262
- worker stages.
261
+ The public concept is review continuation, not subagent management. A
262
+ continuation may re-dispatch failed or missing review execution units while
263
+ reusing completed units from the same session.
263
264
 
264
- A future resumed or reused session must validate:
265
+ Continuation planning should use the shared `PipelineExecutionLedger`
266
+ projection defined in
267
+ `.onto/processes/shared/pipeline-execution-ledger-contract.md`. For
268
+ `review`, the projection derives from the execution plan, run manifest,
269
+ execution result, lens barrier, semantic ledgers, and output seats. The ledger's
270
+ primary purpose is to verify artifact trust boundaries: which outputs were
271
+ produced by completed units, which outputs are untrusted because the producing
272
+ unit failed or upstream work is incomplete, and where execution should continue.
273
+ `finding-ledger.yaml` and `issue-ledger.yaml` remain semantic ledgers; they are
274
+ continuation inputs after they exist, not the full pipeline execution ledger.
275
+
276
+ `review-run-manifest.yaml` records a `resume_token` for audit and idempotency
277
+ only. The token is not a dispatch capability and must not be accepted as
278
+ authorization to restart, skip, continue, or reuse worker stages.
279
+
280
+ Any continued or reused session must validate:
265
281
 
266
282
  - manifest schema version
267
283
  - source hash for every required `context_source`
@@ -270,14 +286,19 @@ A future resumed or reused session must validate:
270
286
  - consumed context eligibility
271
287
  - generated packet refs before invoking issue-artifact, deliberation, or
272
288
  synthesize runtime units
289
+ - route consistency against the existing execution plan and actor invocation
290
+ profiles
291
+
292
+ Any mismatch stops before continuation dispatch and writes a
293
+ `manifest_lifecycle`, `context_eligibility`, or route-specific failure record.
273
294
 
274
- Any mismatch stops before lens execution and writes a `manifest_lifecycle` or
275
- `context_eligibility` failure record.
295
+ Continuation must not change inputs, settings, target scope, provider route,
296
+ domain, review mode, selected lens set, or manifest-governed artifacts. If any
297
+ of those must change, the caller must start a new review session.
276
298
 
277
- Until an explicit resume contract is implemented, MCP callers must start a new
278
- review session after changing inputs, settings, target scope, provider route, or
279
- manifest-governed artifacts. Runtime status/result tools may read existing
280
- session artifacts, but they do not resume execution.
299
+ Until `onto.review_continue` is implemented, MCP callers must still start a new
300
+ review session when they need execution to proceed. Runtime status/result tools
301
+ may read existing session artifacts, but they do not resume execution.
281
302
 
282
303
  ### 5.4 Synthesize Context
283
304
 
@@ -89,6 +89,8 @@ prompt-backed path에서도 이 단계의 결과는 최종적으로
89
89
  - configured domain이 하나면 바로 사용
90
90
  - configured domain이 여러 개면 interactive selection을 수행
91
91
  - interactive selection이 불가능한 non-interactive 환경이면 fail-fast 하고 explicit domain selection을 요구
92
+ - explicit token과 configured domain이 모두 없으면 review target path/content/intent를 기반으로 available domain 문서 중 하나를 자동 선택하고, 선택 domain과 이유를 start preview, `binding_notes`, opening brief input, final output에 기록한다
93
+ - target 기반 자동 선택에 충분한 signal이 없거나 available domain seat가 없으면 `session_domain=none`으로 진행하며 그 이유를 같은 표면에 기록한다
92
94
  - `--domain` 과 `--no-domain` 동시 지정은 parser layer 에서 fail-fast
93
95
 
94
96
  ### 3.4 호출 고정 (InvocationBinding)
@@ -395,4 +397,4 @@ Target rules:
395
397
  남은 follow-up은 live path 자체의 구조 변경이 아니라 운영/확장 품질이다.
396
398
 
397
399
  1. provider credentials/endpoints가 의도적으로 준비된 환경에서 provider별 live conformance를 수행한다.
398
- 2. replay, stale artifact, partial worker, duplicate-dispatch semantics가 닫힌 explicit resume command를 설계한다.
400
+ 2. `.onto/processes/shared/pipeline-execution-ledger-contract.md`의 shared ledger를 `review`에 먼저 투영하고, `docs/architecture/review-continuation-surface.md`의 설계에 따라 `onto.review_status` continuation plan과 `onto.review_continue`를 구현한다.
@@ -0,0 +1,185 @@
1
+ # Pipeline Execution Ledger Contract
2
+
3
+ > Status: shared design contract.
4
+ > Purpose: define the artifact trust and provenance ledger that every onto
5
+ > pipeline must expose or derive across `review`, `reconstruct`, and future
6
+ > `evolve`.
7
+
8
+ ## 1. Position
9
+
10
+ `PipelineExecutionLedger` is a shared runtime concept. It records how a
11
+ pipeline produced its artifacts at the unit level so a caller can determine:
12
+
13
+ - which artifacts are trustworthy;
14
+ - which artifacts are untrusted because their producing unit failed;
15
+ - which artifacts are blocked because upstream units did not complete;
16
+ - which unit is the first incomplete or failed boundary;
17
+ - where a later continuation or repair action may safely begin.
18
+
19
+ Continuation is one consumer of the ledger. The primary purpose is execution
20
+ audit, trust boundary inspection, and artifact provenance.
21
+
22
+ This contract applies to:
23
+
24
+ - `review`;
25
+ - `reconstruct`;
26
+ - future `evolve`;
27
+ - any later onto pipeline that materializes staged artifacts.
28
+
29
+ ## 2. Ownership
30
+
31
+ Runtime owns the ledger projection because it observes unit dispatch, validation,
32
+ file writes, hashes, and terminal status.
33
+
34
+ Host LLMs may read the ledger to explain trust boundaries or propose the next
35
+ action, but they do not author ledger truth.
36
+
37
+ Semantic ledgers remain separate:
38
+
39
+ - `review` semantic ledgers include `finding-ledger.yaml` and
40
+ `issue-ledger.yaml`.
41
+ - `reconstruct` semantic or decision artifacts include Seed, confirmation,
42
+ question, failure, revision, and stop-decision artifacts.
43
+ - future `evolve` may define design-specification or decision ledgers.
44
+
45
+ Semantic ledgers explain meaning. The pipeline execution ledger explains whether
46
+ the process that produced each artifact can be trusted.
47
+
48
+ ## 3. Minimum Model
49
+
50
+ Shared ledger shape:
51
+
52
+ ```ts
53
+ interface PipelineExecutionLedger {
54
+ schemaVersion: "1";
55
+ pipeline: "review" | "reconstruct" | "evolve" | string;
56
+ sessionId: string;
57
+ sourceRefs: string[];
58
+ units: PipelineExecutionLedgerUnitEntry[];
59
+ }
60
+
61
+ interface PipelineExecutionLedgerUnitEntry {
62
+ unitId: string;
63
+ unitKind: string;
64
+ owner: "runtime" | "host_llm" | "user_or_host_mediated";
65
+ producedArtifactRefs: string[];
66
+ consumedArtifactRefs: string[];
67
+ packetRef?: string | null;
68
+ packetSha256?: string | null;
69
+ outputRefs: string[];
70
+ outputHashes: Record<string, string | null>;
71
+ status:
72
+ | "planned"
73
+ | "completed"
74
+ | "failed"
75
+ | "missing"
76
+ | "skipped"
77
+ | "not_reached";
78
+ trustStatus: "trusted" | "untrusted" | "blocked_by_upstream";
79
+ trustReason: string;
80
+ attemptCount: number;
81
+ lastFailureMessage: string | null;
82
+ upstreamUnitIds: string[];
83
+ downstreamUnitIds: string[];
84
+ }
85
+ ```
86
+
87
+ Rules:
88
+
89
+ - `trusted` requires the producing unit to complete and all required output
90
+ artifacts to exist and validate.
91
+ - `untrusted` means the unit ran but failed, produced invalid output, or wrote
92
+ artifacts that failed validation.
93
+ - `blocked_by_upstream` means this unit's trust cannot be established because an
94
+ upstream required unit is missing, failed, or untrusted.
95
+ - `skipped` must include a reason and must not be confused with trusted output.
96
+ - A missing optional unit may be `skipped`; a missing required unit is
97
+ `missing` or `blocked_by_upstream`.
98
+ - The ledger is derived from existing run artifacts unless a pipeline contract
99
+ explicitly promotes it to a durable artifact.
100
+
101
+ ## 4. Source Inputs
102
+
103
+ Each pipeline maps its own runtime artifacts into the shared ledger.
104
+
105
+ | Pipeline | Required derivation sources |
106
+ |---|---|
107
+ | `review` | `execution-plan.yaml`, `review-run-manifest.yaml`, `execution-preparation/review-context-manifest.yaml`, `execution-result.yaml`, `lens-completion-barrier.yaml`, semantic ledgers when present, and output seats |
108
+ | `reconstruct` | `reconstruct-run-manifest.yaml`, `reconstruct-record.yaml`, stage registry, validation artifacts, metrics, stop decision, final output, and output seats |
109
+ | `evolve` | future evolve run manifest, target profile, adapter selection, observation/projection artifacts, design specification validation, final disposition, and output seats |
110
+
111
+ The pipeline-specific source artifacts remain authority. The ledger is a
112
+ normalized projection over them.
113
+
114
+ ## 5. Pipeline Mapping
115
+
116
+ ### Review
117
+
118
+ `review` units include:
119
+
120
+ - lens units;
121
+ - issue artifact units;
122
+ - per-lens deliberation units;
123
+ - controlled deliberation;
124
+ - synthesize;
125
+ - record/final-output assembly where runtime treats them as separate stages.
126
+
127
+ `finding-ledger.yaml` and `issue-ledger.yaml` remain semantic ledgers. They are
128
+ inputs for downstream trust once they exist, not replacements for the execution
129
+ ledger.
130
+
131
+ ### Reconstruct
132
+
133
+ `reconstruct` units follow stable `ReconstructStageId` values:
134
+
135
+ - material profiling;
136
+ - source inventory;
137
+ - source observation;
138
+ - LLM-authored directive production;
139
+ - runtime directive validation;
140
+ - Seed candidate, confirmation, competency-question, assessment,
141
+ failure-classification, revision, metrics, stop-decision, final-output, and
142
+ record assembly stages as the contract enables them.
143
+
144
+ Runtime validation units are the trust gates for LLM-authored artifacts. A
145
+ semantic artifact can exist but remain untrusted until its validation unit
146
+ completes.
147
+
148
+ ### Evolve
149
+
150
+ Future `evolve` units must begin with:
151
+
152
+ - target profiling;
153
+ - adapter selection;
154
+ - material-specific observation or projection;
155
+ - design inquiry/specification stages;
156
+ - validation and final disposition stages.
157
+
158
+ No future evolve adapter may bypass the ledger by writing design artifacts
159
+ without a producing unit and trust status.
160
+
161
+ ## 6. Status And Result Surfaces
162
+
163
+ Status tools should expose the ledger, or a bounded projection of it, whenever a
164
+ pipeline is prepared, running, halted, or completed.
165
+
166
+ Result tools should expose enough ledger refs or summary fields for callers to
167
+ audit why final artifacts are trusted.
168
+
169
+ Continuation tools, where implemented, must derive their frontier from the
170
+ ledger's trust and completion boundary rather than from ad hoc file existence.
171
+
172
+ ## 7. Durable Artifact Policy
173
+
174
+ First implementation may keep the ledger as a derived status projection.
175
+
176
+ Promote a durable root artifact such as `pipeline-execution-ledger.yaml`
177
+ only when at least one of these is true:
178
+
179
+ - external audit needs a stable standalone ledger file;
180
+ - continuation attempts need replayable pre/post trust snapshots;
181
+ - result artifacts need to cite a ledger ref as part of their trust contract.
182
+
183
+ If promoted, the durable artifact must still be derived from the pipeline's run
184
+ manifest, record, validation artifacts, and output seats. It must not become a
185
+ second execution truth.
@@ -4,6 +4,12 @@
4
4
  > Purpose: define the cross-process goal for material-aware target handling
5
5
  > across `review`, `reconstruct`, and future `evolve`.
6
6
 
7
+ Related shared contract:
8
+
9
+ ```text
10
+ .onto/processes/shared/pipeline-execution-ledger-contract.md
11
+ ```
12
+
7
13
  ## 1. Goal Statement
8
14
 
9
15
  Establish a material-aware runtime contract so `review`, `reconstruct`, and
package/AGENTS.md CHANGED
@@ -60,8 +60,9 @@ target material 관련 작업 시 추가로 읽을 문서:
60
60
  `reconstruct` 작업 시 추가로 읽을 문서:
61
61
 
62
62
  1. [reconstruct-boundary-contract.md](/Users/kangmin/cowork/onto-mcp/.onto/processes/reconstruct/reconstruct-boundary-contract.md)
63
- 2. [source-profile-contract.md](/Users/kangmin/cowork/onto-mcp/.onto/processes/reconstruct/source-profile-contract.md)
64
- 3. selected source profile under `.onto/processes/reconstruct/source-profiles/`
63
+ 2. [reconstruct-execution-ux-contract.md](/Users/kangmin/cowork/onto-mcp/.onto/processes/reconstruct/reconstruct-execution-ux-contract.md)
64
+ 3. [source-profile-contract.md](/Users/kangmin/cowork/onto-mcp/.onto/processes/reconstruct/source-profile-contract.md)
65
+ 4. selected source profile under `.onto/processes/reconstruct/source-profiles/`
65
66
 
66
67
  ---
67
68
 
package/README.md CHANGED
@@ -43,8 +43,10 @@ providers, validates evidence refs, computes deterministic metrics, and writes
43
43
  `reconstruct-record.yaml`. Code is the first fixture; the runner path is shared
44
44
  with spreadsheet/document/database material through source profiles and
45
45
  material-specific observers. The current public run path is an explicit mock
46
- semantic/confirmation happy path; domain context selection, failure
47
- classification, and revision proposal are recorded as deferred scope.
46
+ semantic/confirmation post-Seed artifact loop. It implements claim realization,
47
+ confirmation validation, competency-question assessment, failure classification,
48
+ revision proposal, metrics/status projection, and artifact-tethered final
49
+ output; domain context selection remains deferred.
48
50
  `evolve` has a future material-kind adapter contract at
49
51
  `.onto/processes/evolve/material-kind-adapter-contract.md`, but no active
50
52
  runtime or MCP tool. `learn` and `govern` remain separate design slices.
@@ -77,6 +79,7 @@ Available MCP tools:
77
79
  |---|---|
78
80
  | `onto.review` | Run the full review path and return artifact refs plus summary |
79
81
  | `onto.prepare_review` | Prepare a review session and prompt packets |
82
+ | `onto.review_continue` | Continue a prepared or halted review from the ledger frontier |
80
83
  | `onto.review_status` | Read structured status and artifact refs |
81
84
  | `onto.review_result` | Read `review-record.yaml` and final output |
82
85
  | `onto.list_lenses` | List canonical lens sets |
@@ -84,9 +87,9 @@ Available MCP tools:
84
87
  | `onto.list_source_profiles` | List reconstruct source profiles |
85
88
  | `onto.observe_source` | Materialize reconstruct material profile, inventory, source observations, and initial record |
86
89
  | `onto.validate_reconstruct_directive` | Validate LLM-authored reconstruct directive files |
87
- | `onto.reconstruct` | Run the material-aware reconstruct happy path with explicit mock semantic/confirmation realization |
88
- | `onto.reconstruct_status` | Read reconstruct session status and artifact refs |
89
- | `onto.reconstruct_result` | Read `reconstruct-record.yaml`, run manifest, and final output |
90
+ | `onto.reconstruct` | Run the material-aware reconstruct post-Seed loop with explicit mock semantic/confirmation realization |
91
+ | `onto.reconstruct_status` | Read reconstruct session status, progress, counts, and artifact refs |
92
+ | `onto.reconstruct_result` | Read `reconstruct-record.yaml`, run manifest, progress projection, and final output |
90
93
 
91
94
  MCP results include `llmPresentation` prompts. The runtime supplies bounded
92
95
  facts; the host LLM should use those prompts to explain the opening brief and
@@ -110,8 +113,8 @@ Minimal reconstruct MCP call shape:
110
113
 
111
114
  `semanticAuthorRealization` and `confirmationProviderRealization` are required
112
115
  so completed reconstruct runs are explicit about their current mock semantics.
113
- Today this proves the material-aware happy path, artifact gates, and MCP
114
- surface. It does not claim live host-LLM semantic authorship or live
116
+ Today this proves the material-aware post-Seed artifact loop, runtime gates, and
117
+ MCP surface. It does not claim live host-LLM semantic authorship or live
115
118
  user-mediated confirmation.
116
119
 
117
120
  Repository-local development harness:
@@ -235,7 +238,7 @@ Primary outputs:
235
238
 
236
239
  A reconstruct session writes artifacts under `.onto/reconstruct/<session-id>/`.
237
240
 
238
- Implemented happy-path outputs:
241
+ Implemented mock-authored, runtime-gated outputs:
239
242
 
240
243
  | Artifact | Owner | Purpose |
241
244
  |---|---|---|
@@ -246,19 +249,33 @@ Implemented happy-path outputs:
246
249
  | `source-observation-directive-validation.yaml` | runtime | validation of selected observation refs |
247
250
  | `seed-candidate.yaml` | mock/host author | evidence-backed Seed candidate |
248
251
  | `seed-candidate-validation.yaml` | runtime | Seed claim and evidence-ref validation |
249
- | `seed-confirmation.yaml` | mock/host/user mediated | accepted, rejected, or partial Seed confirmation |
252
+ | `claim-realization-map.yaml` | mock/host author | claim-level evidence stance |
253
+ | `claim-realization-map-validation.yaml` | runtime | claim id, stance enum, and evidence linkage validation |
254
+ | `seed-confirmation.yaml` | mock/host/user mediated | accepted, rejected, partial, or deferred Seed confirmation |
255
+ | `seed-confirmation-validation.yaml` | runtime | confirmation transition validation and derived claim sets |
250
256
  | `competency-questions.yaml` | mock/host author | questions linked to confirmed claims |
251
- | `reconstruct-metrics.yaml` | runtime | deterministic counts, unresolved count, and pass rate |
257
+ | `competency-questions-validation.yaml` | runtime | CQ id, claim-link, and evidence validation |
258
+ | `competency-question-assessment.yaml` | mock/host author | answer status for every authoritative CQ |
259
+ | `competency-question-assessment-validation.yaml` | runtime | exactly-once CQ assessment validation |
260
+ | `failure-classification.yaml` | mock/host author | material failure and gap classification |
261
+ | `failure-classification-validation.yaml` | runtime | failure enum, linkage, and materiality validation |
262
+ | `revision-proposal.yaml` | mock/host author | bounded revision/deferral proposals |
263
+ | `revision-proposal-validation.yaml` | runtime | proposal id, target, action, and regression guard validation |
264
+ | `reconstruct-metrics.yaml` | runtime | deterministic counts, unresolved/deferred counts, and pass rate |
252
265
  | `stop-decision.yaml` | mock/host author | stop, continue, or ask-user decision based on metrics |
253
- | `final-output.md` | mock/host author | user-facing result grounded in artifacts |
266
+ | `final-output.md` | mock/host author | user-facing result grounded in artifacts and provenance-checked by runtime |
254
267
  | `reconstruct-run-manifest.yaml` | runtime | step refs, `performed_by` provenance, execution profile, and happy-path scope |
255
268
  | `reconstruct-record.yaml` | runtime | primary structured reconstruct artifact |
256
269
 
257
270
  Current deferred reconstruct artifacts are recorded in
258
271
  `reconstruct-run-manifest.yaml` under `happy_path_scope.deferred_artifacts`:
259
- `domain_context_selection`, `failure_classification`, and `revision_proposal`.
260
- Those require additional host/user semantic decisions and are outside the
261
- current mock happy path.
272
+ `domain_context_selection` and `domain_context_selection_validation`. Those
273
+ require additional domain selection semantics and are outside the current mock
274
+ path.
275
+
276
+ The post-Seed design contract also defines validation artifacts for those
277
+ stages, stable reconstruct stage ids, cross-artifact id authority, and progress
278
+ UX expectations in `.onto/processes/reconstruct/reconstruct-execution-ux-contract.md`.
262
279
 
263
280
  ## Repository Map
264
281
 
@@ -2,12 +2,14 @@ import crypto from "node:crypto";
2
2
  import fs from "node:fs/promises";
3
3
  import path from "node:path";
4
4
  import { parse as parseYaml } from "yaml";
5
+ import { RECONSTRUCT_STAGE_IDS, } from "../core-runtime/reconstruct/artifact-types.js";
5
6
  import { materializeReconstructPreparationArtifacts, } from "../core-runtime/reconstruct/materialize-preparation.js";
6
7
  import { assembleReconstructRecord, } from "../core-runtime/reconstruct/record.js";
7
8
  import { createAutoAcceptReconstructConfirmationProvider, createMockReconstructDirectiveAuthor, runReconstruct, } from "../core-runtime/reconstruct/run.js";
8
9
  import { writeSeedCandidateValidationArtifact, } from "../core-runtime/reconstruct/seed-candidate-validation.js";
9
10
  import { writeSourceObservationDirectiveValidationArtifact, } from "../core-runtime/reconstruct/directive-validation.js";
10
11
  import { loadReconstructSourceProfiles, } from "../core-runtime/reconstruct/source-profiles.js";
12
+ import { buildReconstructPipelineExecutionLedger, } from "../core-runtime/reconstruct/pipeline-execution-ledger.js";
11
13
  async function directoryExists(directoryPath) {
12
14
  try {
13
15
  const stat = await fs.stat(directoryPath);
@@ -75,6 +77,58 @@ async function readTextIfPresent(filePath) {
75
77
  return null;
76
78
  }
77
79
  }
80
+ function deriveReconstructProgress(args) {
81
+ const stepById = new Map(args.runManifest?.steps.map((step) => [step.step_id, step]) ?? []);
82
+ const stages = RECONSTRUCT_STAGE_IDS.map((stageId) => {
83
+ const step = stepById.get(stageId);
84
+ return {
85
+ stageId,
86
+ state: step?.status === "completed"
87
+ ? "completed"
88
+ : step?.status === "skipped"
89
+ ? "skipped"
90
+ : step?.status === "failed"
91
+ ? "halted"
92
+ : "pending",
93
+ owner: step?.owner ?? null,
94
+ artifactRefs: step?.artifact_refs ?? [],
95
+ };
96
+ });
97
+ const lastReachedStage = [...stages].reverse().find((stage) => stage.state !== "pending") ??
98
+ stages[0];
99
+ return {
100
+ currentStageId: lastReachedStage.stageId,
101
+ stageCount: RECONSTRUCT_STAGE_IDS.length,
102
+ liveness: {
103
+ state: args.record.record_stage === "completed"
104
+ ? "completed"
105
+ : "halted_or_partial",
106
+ recommendedPollIntervalMs: args.record.record_stage === "completed" ? null : 1000,
107
+ },
108
+ countSummary: {
109
+ sourceObservationCount: args.metrics?.source_observation_count ?? null,
110
+ selectedObservationCount: args.metrics?.selected_observation_count ?? null,
111
+ semanticClaimCount: args.metrics?.semantic_claim_count ??
112
+ args.record.validation_summary.semantic_claim_count,
113
+ confirmedClaimCount: args.metrics?.confirmed_claim_count ??
114
+ args.record.validation_summary.confirmed_claim_count,
115
+ partialClaimCount: args.metrics?.partial_claim_count ??
116
+ args.record.validation_summary.partial_claim_count,
117
+ deferredClaimCount: args.metrics?.deferred_claim_count ??
118
+ args.record.validation_summary.deferred_claim_count,
119
+ competencyQuestionCount: args.metrics?.competency_question_count ??
120
+ args.record.validation_summary.competency_question_count,
121
+ assessmentCount: args.metrics?.competency_question_assessment_count ??
122
+ args.record.validation_summary.competency_question_assessment_count,
123
+ failureCount: args.record.validation_summary.failure_count,
124
+ revisionProposalCount: args.record.validation_summary.revision_proposal_count,
125
+ unresolvedCount: args.metrics?.unresolved_question_count ??
126
+ args.record.validation_summary.unresolved_count,
127
+ passRate: args.metrics?.pass_rate ?? args.record.validation_summary.pass_rate,
128
+ },
129
+ stages,
130
+ };
131
+ }
78
132
  function recordArtifactRefsFromPreparation(refs) {
79
133
  return {
80
134
  target_material_profile: refs.target_material_profile,
@@ -198,11 +252,27 @@ export function createOntoReconstructCoreApi(options = {}) {
198
252
  async getRunStatus(sessionRoot) {
199
253
  const resolvedSessionRoot = path.resolve(sessionRoot);
200
254
  const reconstructRecord = await readYamlArtifact(path.join(resolvedSessionRoot, "reconstruct-record.yaml"));
255
+ const reconstructRunManifest = await readYamlArtifactIfPresent(reconstructRecord.artifact_refs.reconstruct_run_manifest);
256
+ const reconstructMetrics = await readYamlArtifactIfPresent(reconstructRecord.artifact_refs.reconstruct_metrics);
257
+ const reconstructRecordRef = path.join(resolvedSessionRoot, "reconstruct-record.yaml");
258
+ const pipelineExecutionLedger = await buildReconstructPipelineExecutionLedger({
259
+ sessionRoot: resolvedSessionRoot,
260
+ reconstructRecord,
261
+ reconstructRecordRef,
262
+ reconstructRunManifest,
263
+ reconstructRunManifestRef: reconstructRecord.artifact_refs.reconstruct_run_manifest,
264
+ });
201
265
  return {
202
266
  sessionId: path.basename(resolvedSessionRoot),
203
267
  sessionRoot: resolvedSessionRoot,
204
268
  status: reconstructRecord.record_stage,
205
269
  artifactRefs: reconstructRecord.artifact_refs,
270
+ progress: deriveReconstructProgress({
271
+ record: reconstructRecord,
272
+ runManifest: reconstructRunManifest,
273
+ metrics: reconstructMetrics,
274
+ }),
275
+ pipelineExecutionLedger,
206
276
  reconstructRecord,
207
277
  };
208
278
  },