robbond/confidence-engine
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: record structural action contract implementation

Browse Source
This commit is contained in:
robbond
2026-08-12 07:29:28 +01:00
parent 6aef806845
commit 1b3bbd59aa
2 changed files with 135 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/current-handoff.md
+27 -1
View File
@@ -1249,4 +1249,30 @@ Full record in `docs/experiment-57j66.md`.
**Final v0.23 contract:** top-level field in `graphUpdateSchema`, boolean | nullable, exact structural semantics. Ready for bounded implementation.
New branch: `feature/semantic-action-contract-v0.23`
**Final v0.23 contract:** top-level field in `graphUpdateSchema`, boolean | nullable, exact structural semantics. **Implementation completed on this branch.**
### Experiment 57J.68 — structuralActionRequired Implementation
**Classification: IMPLEMENTATION COMPLETE.** All design decisions from 57J.67 implemented verbatim across three production files and validated by 50 deterministic tests (24 new + 8 migrated). No live Ollama calls.
#### Production changes:
1. `lib/graph/schema.js` — Added `structuralActionRequired: z.boolean().nullable().optional()` to graphUpdateSchema.
2. `lib/graph/utils.js` — Replaced semantic-only-no-op guard with four-case contract validator (true+mutation PASS, true+zero REJECT, false+zero PASS, false+mutation REJECT).
3. `lib/graph/prompt-builder.js` — Added field name to required lists; inserted contract declaration section between numbered rules and Additional Guidance.
#### Contract guarantees:
- Populated userSupportedMeaning requires boolean structuralActionRequired.
- Declaration is exact claim about output shape: true = meaningful mutation present; false = zero mutations intentional.
- false + zero is valid intentional no-op (contract-consistent).
- Mismatch between declaration and output shape deterministically rejected.
#### Test suite:
- 24 new tests across schema.test.js (+4), prompt-builder.test.js (+10), utils.test.js (+10).
- 8 existing tests migrated to use structuralActionRequired=true where answerMeaning is populated.
- All 197 graph tests pass (previous total preserved).
#### Live regression readiness:
- All existing schema, prompt-builder, and utils tests pass.
- The change is backward-compatible: field is optional by default; old proposals without it behave identically to the legacy path.
New branch: `feature/semantic-action-contract-v0.23`