# Orchestrator Contract — Confidence Engine v0.4

## 1. Exported Function Signatures & Shape (JavaScript)

### lib/analysis.js

```js
export async function analyseScenario(scenario, opts = {})
// @param {string} scenario
// @param {{ promptVersion?: "v0.2" | "v0.3" }} [opts]
// @returns {Promise<{ success: boolean, validationStatus: "valid"|"invalid",
//     modelName: string|null, responseDurationMs: number, rawResponse: string|null,
//     promptVersion: string|null, inputClassification: object|null, reconstruction: object|null,
//     evidence: object[]|undefined, nextQuestion: string|undefined, errors: string[]|undefined,
//     error: string|undefined, statusCode: number|undefined }>}

export const PROMPT_VERSIONS    // { [key: string]: string }
export const DEFAULT_PROMPT_VERSION  // "v0.2"
```

### lib/graph/schema.js

```js
export const SituationKind          // { observation, reported_claim, metric, state, transition, relationship, assumption, unknown, conclusion }
export const SituationStatus        // { known, unknown, provisional, supported, weakened, contradicted, resolved }
export const ConfidenceLevel        // { low, medium, high }
export const SituationRelationship  // { supports, weakens, contradicts, depends_on, causes, may_cause, measures, compares_with, updates, other }

export const situationNodeSchema    // Zod → {@typedef SituationNode}
export const situationEdgeSchema    // Zod → {@typedef SituationEdge}
export const situationGraphSchema   // Zod → {@typedef SituationGraph}
export const graphUpdateSchema      // Zod → {@typedef GraphUpdate}
export const startCaseRequestSchema // { scenario: string (1-10000), promptVersion?: string }
export const updateCaseRequestSchema// { situationGraph: SituationGraph, previousQuestion: string, answer: string (1-5000), promptVersion?: string }

/** @param {string} label */ /** @returns {string} */ export function makeNodeId(label)
/** @param {{ id?, label, description, kind?, status?, confidence?, value?, unit?, ... }} opts */ /** @returns {SituationNode} */ export function makeNode(opts)
/** @param {{ id?, fromNodeId, toNodeId, relationship?, confidence?, description? }} opts */ /** @returns {SituationEdge} */ export function makeEdge(opts)
/** @param {{ centralStatement?, nodes?, edges?, activeUnknownNodeId?, resolvedNodeIds?, currentSummary? }} opts */ /** @returns {SituationGraph} */ export function makeGraph(opts)
```

### lib/graph/utils.js

```js
export function validateGraphReferences(graph)     // → { valid: boolean, errors: string[] }
export function detectDuplicateNodeIds(nodes)      // → { nodeId, count }[]
export function detectDuplicateEdges(edges)        // { edgeId, fromNodeId, toNodeId, relationship }[]
export function findDependentNodes(graph, nodeId)  // → string[] (transitive)
export function findAffectedNodes(graph, nodeId)   // → string[] (direct + indirect via affects/dependsOn)
/** @param {SituationGraph} graph */ /** @param {string} nodeId */ /** @param {string} newStatus */ /** @param {*} newValue */ /** @param {string} reason */
export function resolveUnknownNode(graph, nodeId, newStatus, newValue, reason)  // → { success, error?, previousStatus?, newStatus?, previousValue?, newValue?, reason?, affectedNodes? }
export function selectActiveUnknownCandidate(graph, resolvedNodeIds)  // → { nodeId, label, score } | null
/** @param {SituationGraph} graph */ /** @param {GraphUpdate} update */
export function applyGraphUpdate(graph, update)  // → { success: boolean, errors?, nodes?, edges?, resolvedNodeIds? }
/** @param {SituationGraph} graph */ /** @param {GraphUpdate} update */
export function validateGraphUpdate(graph, update)  // → { valid: boolean, errors: string[] }
```

### lib/graph/builder.js

```js
export function buildInitialGraph(analysisData)  // @param {{ reconstruction, evidence? }} → { nodes: SituationNode[], edges: SituationEdge[] }
export function buildMinimalGraph(scenario)       // @param {string} → { nodes, edges }
export function describeGraph(graph)              // @param {{ nodes, edges }} → string (summary text)
```

## 2. Dependencies Between Files

```
lib/analysis.js
  ├── getConfig()         from lib/config.js
  ├── getProvider()       from lib/llm/provider.js   [EXTERNAL]
  ├── buildPrompt()       from lib/reconstruction/prompt.js
  └── reconstructionV2/V1Schema  from lib/reconstruction/schema.js

lib/graph/utils.js      ← imports situationNodeSchema, situationEdgeSchema, situationGraphSchema from schema.js
lib/graph/builder.js    ← imports situationNodeSchema, situationEdgeSchema, makeNodeId from schema.js
docs/v0.4-handoff.md   → references CaseOrchestrator.startCase()/updateCase() (not in any inspected file)
```

## 3. Side Effects (LLM Calls)

| Function | LLM Call? | Details |
|---|---|---|
| `analyseScenario()` | **Yes** | `provider.generateReconstruction(prompt, model)` — POST to configured LLM. Prompt from `buildPrompt(scenario, version)`. |
| All graph functions (`schema.js`, `utils.js`, `builder.js`) | No | Pure/deterministic only. |
| `startCase()` / `updateCase()` (per handoff) | **Yes** | startCase: calls analyseScenario. updateCase: calls LLM via buildUpdatePrompt context + provider for GraphUpdate, then applyGraphUpdate(). |

## 4. Minimal Proposed Contract for API Functions

### startCase(body)
- **Input:** `{ scenario: string (1-10000), promptVersion?: string }` — validated by `startCaseRequestSchema`.
- **Flow:** validate → `analyseScenario()` → if ok, `buildInitialGraph(result)`; on failure return minimal graph via `buildMinimalGraph()`.
- **Output (success):** `{ success: true, graphSummary: string, nodeCount: number, edgeCount: number, activeUnknownNodeId: string|undefined, nextQuestion: string }`
- **Output (failure):** `{ success: false, error: string, graphSummary: string, nodeCount: number, edgeCount: number }`

### updateCase(body)
- **Input:** `{ situationGraph: SituationGraph, previousQuestion: string (1+), answer: string (1-5000), promptVersion?: string }` — validated by `updateCaseRequestSchema`.
- **Flow:** validate → `buildUpdatePrompt(ctx)` → LLM call for GraphUpdate proposal → `validateGraphUpdate()` → `applyGraphUpdate()` → resolve unknowns via `resolveUnknownNode()` → pick next candidate via `selectActiveUnknownCandidate()`.
- **Output (success):** `{ success: true, graphSummary: string, nodeChanges: { added, updated, removed }, edgeChanges: { added, removed }, resolvedNodes: string[], nextQuestion: string|null }`
- **Output (failure):** `{ success: false, error: string, graphSummary: string, nodeChanges: {}, edgeChanges: {}, resolvedNodes: [], nextQuestion: null }`

## 5. Missing Interfaces — TODO

1. **[TODO]** `CaseOrchestrator` class described in handoff but absent from all five inspected files. startCase()/updateCase() wrappers need implementation per above contract.
2. **[TODO]** `buildUpdatePrompt(ctx)` (per handoff lives in prompt-builder.js) — not reviewed; input/output needs a separate doc once the file is available.
3. **[TODO]** LLM provider interface (`getProvider()`, `generateReconstruction(prompt, model)`) — external dependency. Assumes rawResponse is parseable JSON matching v0.2/v0.1 schema; needs explicit contract.
4. **[TODO]** Error handling for updateCase() on malformed LLM JSON — handoff notes "generic 500"; needs structured retry/error contract.
5. **[TODO]** Completion heuristic `getCompletionStatus()` referenced in handoff but absent; needs contract (e.g., "complete" when no unresolved unknown nodes).

---

*End of contract.*