docs(confidence-engine): define minimum finding handoff slice
This commit is contained in:
@@ -712,3 +712,121 @@ This contract defines the semantic boundaries needed for implementation to proce
|
||||
- Relevance representation details
|
||||
- Automatic reopening triggers/algorithm
|
||||
- UI presentation of dispositions
|
||||
|
||||
---
|
||||
|
||||
## Minimum v1 Finding Handoff Implementation Slice — August 2026
|
||||
|
||||
### Design decisions (design-only, not implementation)
|
||||
|
||||
#### 1. Runtime owner
|
||||
**ScenarioForm state beside focusedContributions.**
|
||||
`focusedInvestigations` lives in the SituationGraph as authoritative graph state. Findings are a separate reasoning-layer concept that the user reasons about. The ScenarioForm component already maintains `focusedContributions` (line 256) as parallel client-side state beside graph state. v1 Findings live alongside this: a transient, client-side reasoning array created from contributions and passed through to case/update when an update is submitted.
|
||||
|
||||
#### 2. Creation seam
|
||||
**After focused deconstruction — the same path that creates and stores a Contribution.**
|
||||
The existing `appendFocusedContribution` callback (scenario-form.jsx line 258) receives the model's deconstruction result. A new Finding is created from the same deconstruction output in the same turn, before or alongside contribution storage. The seam: after the focused-deconstruct LLM returns its result, each extracted observation becomes one provisional Finding with status `provisional`.
|
||||
|
||||
#### 3. v1 formation rule
|
||||
**ONE-CONTRIBUTION-MULTIPLE-OBSERVATION-FINDINGS.**
|
||||
Each extracted observation in a focused deconstruction produces one provisional Finding whose proposition is derived from that observation alone. This is a v1 simplification only — it does not constrain the domain model. Long-term Contribution↔Finding cardinality remains unresolved and may be many-to-many. No clustering, merging, embedding, semantic merge, or additional LLM call in v1. Each observation yields one deterministic Finding.
|
||||
|
||||
#### 4. Handoff trigger
|
||||
**On completed contribution, provisional unless explicitly disposed.**
|
||||
A Finding is created immediately when a focused deconstruction completes and contributes its result. It enters case/update alongside the normal update payload. Explicit disposition (Agree / Not relevant) is optional — silence means `provisional` which is still globally eligible for evaluation.
|
||||
|
||||
#### 5. Best case/update seam
|
||||
**ScenarioForm → /api/cases/update → orchestrator → applyValidatedProposal.**
|
||||
The smallest insertion point is: ScenarioForm sends `findings[]` as an optional field in the Update request body. The orchestrator passes these into the evaluation phase of the update cycle *before* or *alongside* proposal application, but *never* as a direct graph mutation trigger. The Finding enters case/update as advisory input; case/update decides its relevance during Current Understanding reconstruction independently.
|
||||
|
||||
#### 6. Request evolution
|
||||
**Extend existing /api/cases/update with optional findings.**
|
||||
Add an optional `findings` array to `updateCaseRequestSchema`. No separate endpoint. Each Finding in the array carries: `{ id, proposition, status, disposition, contributingContributionIds, originatingTargetNodeId }`. The schema addition is a zod extension with `findings: z.array(findingSchema).optional()` — backward-compatible.
|
||||
|
||||
#### 7. Required v1 validation
|
||||
|
||||
Three separate concerns:
|
||||
|
||||
**STRUCTURAL VALIDATION**
|
||||
- Non-empty proposition (string with trimmed length > 0)
|
||||
- At least one valid contributingContributionId reference
|
||||
- If disposition present, must be one of: `agreed`, `challenged`, `not relevant`
|
||||
- No direct graph-mutation fields (the Finding carries advisory data only)
|
||||
|
||||
**PROVENANCE VALIDATION**
|
||||
- Referenced contribution exists
|
||||
- Selected source observation exists within referenced contribution
|
||||
|
||||
**SEMANTIC AUTHORITY**
|
||||
- Source observation remains evidence/provenance
|
||||
- case/update does not treat proposition as truth merely because validation passed
|
||||
|
||||
Failing any structural or provenance check → reject that single Finding from active consideration (retain in provenance). No additional LLM validation call in v1. Semantic authority is a boundary contract, not an automated check.
|
||||
|
||||
#### 8. Minimum global effect
|
||||
**OPTION-1.**
|
||||
Finding reaches case/update → validated → can influence Current Understanding reconstruction only → graph structure unchanged.
|
||||
|
||||
This is the smallest, most conservative slice: Findings affect only what gets reported back to the user as "current understanding." They do not attach evidence to existing graph nodes or mutate any graph topology in v1. Graph mutations remain exclusively controlled by applyValidatedProposal from the LLM proposal path.
|
||||
|
||||
#### 9. Evaluation response
|
||||
**RETURN-EVALUATION-V1.**
|
||||
v1 includes minimal per-Finding evaluation status in the orchestrator's internal response: `considered`, `used`, `not_used`, or `rejected`. This is developer/provenance-oriented only — not a final API schema. It supports tests, manual debugging, and future UI decisions by proving case/update actually evaluated each Finding rather than silently accepting or ignoring it.
|
||||
|
||||
#### 10. Graph-authority invariant
|
||||
**Exact invariant:**
|
||||
> "Findings are advisory inputs to case/update. In v1, case/update may use a validated Finding only when reconstructing Current Understanding. The SituationGraph, activeUnknownNodeId and selectedQuestion must remain byte-for-byte unchanged as a consequence of Finding handoff."
|
||||
|
||||
Proof: The v1 code path ensures (a) Findings are typed as a separate schema from graph-update proposals, (b) Finding evaluation runs in a read-only phase of case/update that has no side effects on the graph object, and (c) applyValidatedProposal is never called with Finding-derived mutation instructions.
|
||||
|
||||
#### 11. File scope
|
||||
|
||||
| File | Classification |
|
||||
|------|---------------|
|
||||
| components/scenario-form.jsx | LIKELY-CHANGE |
|
||||
| components/reasoning-workspace.jsx | MAY-CHANGE |
|
||||
| /api/cases/update route | MAY-CHANGE |
|
||||
| case/update orchestrator (orchestrator.js) | LIKELY-CHANGE |
|
||||
| lib/graph/apply-proposal.js | DO-NOT-CHANGE |
|
||||
| lib/graph/utils.js | DO-NOT-CHANGE |
|
||||
| lib/graph/schema.js | LIKELY-CHANGE |
|
||||
| new Finding helper/module | MAY-CHANGE (or inline in orchestrator for v1) |
|
||||
| tests | LIKELY-CHANGE |
|
||||
|
||||
#### 12. Four deterministic v1 scenarios
|
||||
|
||||
**provisional Finding (valid, no explicit disposition)**
|
||||
- Boundary result: passes structural and provenance validation; status = provisional
|
||||
- Eligibility: eligible as unconfirmed evidence/context for Current Understanding evaluation
|
||||
- Must remain represented as provisional/unconfirmed
|
||||
- Graph mutation: none
|
||||
|
||||
**agreed Finding (valid, explicit user support is available to case/update)**
|
||||
- Boundary result: passes structural and provenance validation; disposition = agreed
|
||||
- Eligibility: eligible with explicit user support
|
||||
- May be represented differently in Current Understanding reconstruction if semantically appropriate — no numerical/ordinal weighting exists
|
||||
- Graph mutation: none
|
||||
|
||||
**not-relevant Finding (valid provenance, disposition = not relevant)**
|
||||
- Boundary result: passes structural and provenance validation; disposition = not relevant
|
||||
- Eligibility: eligible with qualification — must NOT affect Current Understanding for the current investigation context
|
||||
- Retained but excluded from current active relevance
|
||||
- Graph mutation: none
|
||||
|
||||
**malformed/untraceable Finding (empty proposition or missing contribution reference)**
|
||||
- Boundary result: fails handoff validation
|
||||
- Effect: does not affect Current Understanding; no graph effect
|
||||
- Retained in provenance with warning
|
||||
|
||||
#### 13. Implementation order (max 7 steps)
|
||||
|
||||
1. Deterministic Finding representation/formation helper — small module that creates one provisional Finding per extracted observation, no LLM call
|
||||
2. Deterministic validation — structural + provenance checks as described in section 8
|
||||
3. ScenarioForm ownership/storage — alongside `focusedContributions`, create and store provisional Findings after deconstruction; include in update payload
|
||||
4. Optional findings handoff through existing `/api/cases/update` — extend schema with optional `findings[]`; orchestrator passes as advisory input
|
||||
5. Current Understanding-only consumption — validated Findings influence reconstruction only; SituationGraph, activeUnknownNodeId, selectedQuestion byte-for-byte unchanged
|
||||
6. Invariant tests proving graph/frontier/question unchanged across all four deterministic scenarios (provisional accepted, agreed accepted, not-relevant excluded, malformed rejected)
|
||||
7. Manual walkthrough of the complete handoff path
|
||||
|
||||
### Decision gate
|
||||
**MINIMUM-V1-FINDING-HANDOFF-DESIGN-READY**
|
||||
|
||||
Reference in New Issue
Block a user