OpenAI Codex annotations shape (Nov 2026 enterprise launch)
made a typed primitive: given an artifact + a Selection over
part of it, ask the agent to explain or edit JUST THAT SPAN
without re-running the whole produce-the-artifact loop. The
last-mile collaboration primitive JouleClaw was missing.
Different slot from existing primitives:
- jouleclaw-revise iterates whole artifacts until threshold
- jouleclaw-contract verifies whole deliverables against rubrics
- jouleclaw-mission orchestrates feature-by-feature work
- jouleclaw-annotate operates on SUB-artifact selections
Surface:
- Artifact { id, kind, content, content_hash }. ArtifactKind
picks valid Selection variants.
- Selection enum, five variants: TextRange { start, end },
Cells { sheet?, range }, SlideRegion { slide_index,
element_id? }, DomSelector { selector }, Custom { path }.
Each variant's validate_for(kind) catches structural
mismatches.
- AnnotationRequest { artifact_id, selection, instruction,
expects_edit } — Explain (read) or Edit (write) mode.
- AnnotationResult enum: Explanation { text, joules_uj } |
Patches { patches, joules_uj } | Refused { reason }. Caller
sees joules_uj on success for receipt-stream integration.
- PatchSet — ordered list of Patch deltas. Four typed
variants: ReplaceRange (text), SetCell (spreadsheet),
ReplaceSlideElement (slide), Custom (caller-defined). Pure
data — caller's apply layer dispatches.
- Annotator async trait + EchoAnnotator deterministic
reference.
- AnnotationLog — append-only, content-hashed entries
carrying request_hash + result_hash + artifact_content_hash
so a JCR-1 receipt can join the annotation back to the
exact artifact version it was applied against.
- run(annotator, artifact, request, log) — one-shot
orchestration with mode-mismatch enforcement: a request
with expects_edit=true that gets back an Explanation
result (or vice-versa) raises ModeMismatch. Refused is
valid in either mode. Mode-mismatch failures do NOT log.
15 tests cover: content-hash stability, every Selection
variant validation (and cross-kind rejection), Echo backend
in read + edit modes, wrong-selection-kind rejection, run
logs round-trip, mode-mismatch refusal, Refused in either
mode, PatchSet JSON round-trip, log total_joules sums,
request JSON round-trip.
Workspace stays 0 errors / 0 warnings.
SOTA backlog after this wave: every primitive from the
2026-06-03 audit + every subsequent talk / repo input is
shipped. Cumulative across waves 28-40: 14 new crates +
1 module + ~219 net-new tests.
Co-Authored-By: Claude Opus 4.7 <[email protected]>
905dc2df77