Skip to content

fix(tools): normalize injected write defaults - #296

Merged
hffmnnj merged 20 commits into
mainfrom
fix/write-boundary-contracts
Aug 12, 2026
Merged

hffmnnj merged 20 commits into
mainfrom
fix/write-boundary-contracts

Conversation

@hffmnnj

@hffmnnj hffmnnj commented Aug 12, 2026

Copy link
Copy Markdown
Owner

Summary

  • add regression coverage for host-injected optional defaults across write-tool boundaries
  • normalize empty booleans, collections, objects, and ambiguous patch groups using scoped policies
  • preserve intentional empty patch and metadata operations
  • pin direct-boundary distinctions and V1/V2 execution parity

Verification

  • rtk proxy bun test packages/opencode-plugin/src/shared/ packages/opencode-plugin/src/tools/index.test.ts packages/opencode-plugin/src/core/tools-v2.test.ts --bail=3 --timeout=10000 (178 passed)
  • bun run --cwd packages/opencode-plugin typecheck

The running host uses an already-loaded bundle, so source-level tests provide the behavioral evidence for this change.

hffmnnj and others added 20 commits August 11, 2026 20:46
Normalize host-injected optional defaults at the shared createTools boundary without using global falsy coercion. Preserve documented blank patches and wave metadata clears unless independent operation evidence identifies injected residue.
Normalize blank full-write content inside the document writer so direct factory and registry calls reject ambiguous destructive writes consistently. Wrap single document and patch mutations with their events in transactions, and clear stale sections before patched sidecars are rendered.\n\nChanges:\n- Reject empty full and batch-item content without overwriting documents\n- Roll back document, section, and event mutations when event storage fails\n- Add direct, wrapped, workflow-scope, sidecar, and rollback regressions
Align goop_write_section direct and createTools boundaries: empty content
coalesces to absent (loud none-mode error, never a wipe), replace_all:false
is semantically absent, batch items reject empty content and empty
section_key atomically, and single write/patch/delete are transactional so
an event failure rolls back section/document state with no orphan event.
Legacy migration upsert joins the write transaction; sidecar, workflow
scope, and patch-deletion pins added. Red-first: 7 regressions failed
before the fix.
Task 2.2 remediation before Task 2.3. Empty section_key can no longer
create a section on the direct write path: direct and wrapped calls reject
with the identical 'section_key is required for action write' guidance,
superseding the Wave 1 exploratory direct-authored-empty pin in the tools
boundary test. goop_write_db now treats replace_all:false as semantically
absent at top level and per batch item, matching the coalesced wrapped
path while keeping genuinely modifier-only calls rejected. Red-first: 5
regressions failed before the fixes.
Prevent injected metadata defaults and empty task payloads from selecting incorrect wave write modes. Validate wave-number targets, reject unsupported metadata clearing, and suppress events for side-payload-only writes.\n\nChanges:\n- Coalesce injected empty wave metadata as omitted\n- Reject invalid wave targets and no-intent requests\n- Add regression coverage for metadata, no-op, and event behavior
Wave 2 contract (03db89e) removed goop_write_wave metadata from the
audited empty-string exclusion map and made the tool reject intentional
clears. Update the stale shared coalesce pins that still expected
title/pr_branch/pr_url empties to be preserved at the host boundary:

- wave metadata empties now coalesce to omission (top-level and nested)
- exclusion-map audit no longer lists goop_write_wave and asserts its
  absence explicitly
- sibling-coalescing test repurposed onto the still-protected
  old_string patch field
- only-operation test now proves omission, with the tool-level clear
  rejection pinned in goop-write-wave/index.test.ts

Preserves all intentional empty patch pins (old_string/new_string).
Wave 3 Task 3.1: goop_save_note now agrees with the coalesced payload
the registry boundary already produces, field by field:

- note_id "" -> absent. An empty id can never address a note (fn_...),
  so patch mode must not activate on it; create wins on both paths.
  (Supersedes the Wave 1 pin that direct note_id:"" was "authored
  input"; the empty id carries no authored intent.)
- workflow_id/project_id "" -> null scope. An empty string is not a
  real workflow/project; absent means global, matching the wrapped path.
- tags [""] / ["  "] / "" -> rejected with guidance ("provide at least
  one non-empty tag, or pass [] for an untagged note"). Never silently
  create an untagged note from authored empty entries. tags: [] stays
  the documented explicit untagged value on both paths, so the shared
  boundary no longer treats tags:[] as injected residue, and presence
  of a tags array counts as create evidence against an injected empty
  patch pair (both edits in shared/coalesce.ts, proven by registry
  tests; this file is the note-normalization seam the factory uses).
- importance 0 -> rejected, never defaulted to 5. Unified the single
  and batch messages to "Importance must be between 1 and 10."
- old_string/new_string "" remain load-bearing (blank-document patch /
  delete) and are untouched by normalization; registry test proves the
  protection survives the boundary.
- Batch rollback preserved: tags/importance failures throw inside
  runBatch's transaction, leaving no partial rows.
Wave 3 Task 3.2: goop_append_chronicle now agrees with the coalesced
payload the registry boundary already produces, on both paths:

- entry "" -> absent. An empty-string entry can never be a meaningful
  chronicle entry, so it is rejected like a no-args call instead of
  appending a 0-char event. (Supersedes the Wave 1 pin that direct
  entry:"" was authored input; the empty string carries no authored
  intent.)
- workflow_id "" -> active workflow. An empty string is not a real
  workflow scope; absent means the active workflow, matching the
  wrapped path.
- no-args vs empty batch distinguished. {} now returns a none-mode
  error ("no entry or entries were provided") while an explicitly
  empty entries[] keeps its distinct "entries[] array is empty"
  message. The shared boundary no longer coalesces entries:[] for
  goop_append_chronicle, so the empty-batch distinction survives on
  the wrapped path too (proven by registry tests; an injected []
  never selects batch mode because the tool only batches on non-empty
  arrays).
- Auxiliary ADL/memory once-after-batch and chronicle transaction
  rollback preserved; no cross-store atomicity claims added.
- Workflow-scope coverage for the batch path.
Wave 3 Task 3.3: goop_blocker now agrees with the coalesced payload the
registry boundary produces on both paths, and rejects invalid authored
text with actionable guidance.

- action/description/severity/status/resolution/workflow_id "" -> absent.
  An empty action never selects a lifecycle operation; an empty description
  on resolve no longer overwrites the stored text; an empty severity
  defaults to medium; an empty status no longer filters list results; an
  empty workflow_id targets the active workflow.
- id 0 / wave_id 0 -> absent. Blocker row ids and wave numbers are 1-based,
  so 0 is the host-injected numeric default and can never address a real
  row. resolve(id: 0) reports "id is required" instead of "Blocker #0 not
  found"; open(wave_id: 0) attaches no wave and skips the completed-wave
  lookup.
- Whitespace-only descriptions are rejected on open and on resolve-amend
  with actionable retry guidance; whitespace-only resolutions are rejected
  too, leaving the blocker open and event-free. Batch rollback preserved.
- Absent-vs-empty messages split: {} says "no action or items were
  provided" while an explicitly empty items[] keeps the "items[] array is
  empty" message. The shared boundary no longer coalesces items:[] for
  goop_blocker so the distinction survives the wrapped path (proven by
  registry tests; an injected [] never selects batch mode).
- Completed-wave warning preserved for real wave numbers.
…mantics

Wave 4 Task 4.1 schema-and-description half. Synchronize the emitted
tool schemas and descriptions for the six write tools with the runtime
semantics landed in Waves 1-3:

- goop_write_wave: correct the stale 'empty strings overwrite' metadata
  claim — empty-string title/pr_branch/pr_url is rejected (intentional
  metadata clearing is not supported) and injected empty statuses /
  task_update:{} are treated as absent, never clobbering stored values.
- goop_write_section: drop the stale mode:"append" rejection (the tool
  has no mode arg); document section_key:'' rejection and the
  empty-items-batch distinction.
- goop_write_db / goop_save_note: state the load-bearing patch pair
  (old_string presence, empty new_string deletes), tags:[] vs empty-tag
  rejection, and importance:0 rejection.
- goop_append_chronicle: keep the cross-store non-atomicity caveat and
  add the empty-entry/empty-payload omission and empty-batch distinction.
- goop_blocker: document id:0/wave_id:0 as omitted (1-based ids),
  whitespace-only rejection guidance, and empty items[] vs no-args.

Contract pins (tools-v2.test.ts): complete INJECTED_DEFAULT_FIELDS for
all six tools, add batch-element requiredness pins for goop_write_wave
(items/task_updates/verifications/traceability), goop_blocker (items),
and goop_append_chronicle (entries), and update the two title-description
pins to the corrected wording.
… corrected descriptions

Wave-aligned markdown half of the write-tool contract alignment. The
factory descriptions and emitted schemas are the authority; prose now
mirrors them:

- Remove the stale empty-string metadata clearing contract from the
  load-bearing table (title/pr_branch/pr_url on goop_write_wave) and the
  'including empty strings, overwrite' semantic; intentional metadata
  clearing is not supported and empty metadata is treated as absent.
- Rewrite the empty-string coalescing contract to match coalesce.ts:
  exact "", false, [], {} are coalesced only per the per-tool policy,
  while 0, whitespace-only strings, and the load-bearing patch pairs
  (old_string/new_string) are always preserved.
- Add the six-tool batch inventory naming the exact batch array property
  per tool (entries/items) with schema-pinned per-item requiredness
  (blocker items require action; wave items require wave_number).
- Fix the stale 'Not available in entries batch mode' claim for
  goop_append_chronicle aux writes: alsoLogAdl/alsoSaveMemory apply once
  after the batch commits, only on full success; cross-store atomicity
  remains unavailable with per-store [OK]/[FAIL] reporting.
- Complete the goop_write_wave table row: allow_status_regression and
  per-item verifications/traceability inside items[].
Add registry and V2 integration coverage for all six write definitions under injected empty containers. Preserve save-note's explicit empty-batch diagnostic at the shared boundary so wrapped and direct calls agree.
Follow the wiring change that removed goop_save_note's items entry from
the injected-empty-container coalescing set: an empty items[] now stays
visible at the shared boundary so wrapped and direct calls agree on the
empty-batch error.

- tool-reference.md: add items on goop_save_note to the deliberately
  not-omitted list and to the empty-batch rejection list; trim absolute
  wording introduced by the prior commit so the reference stays within
  the prompt-audit budget (bytes +20, absolute-language hits -7 vs the
  previous head).
- AGENTS.md: replace the four-tool items[] claim with the real six-tool
  batch surface (goop_blocker via items[], goop_append_chronicle via
  entries[]), keeping the single-transaction and non-atomic aux caveats.
…t docs

tool-reference.md grew 27,620 -> 30,526 bytes (+2,906) documenting the
write-tool runtime contracts the schema does not state cross-tool: the
Six-tool batch inventory (per-item requiredness, sub-array element pins,
empty-batch rejection case), the corrected coalescing boundary with all
three omission categories and load-bearing exclusions, removal of the
stale pr_url/pr_branch/title clearing-operation rows (empty now preserves
stored value), and the corrected goop_append_chronicle batch-mode
aux-payload semantics. The growth is contract documentation, not bloat:
the rewrite also removed one absolute-language hit (tool-reference 27 ->
26, total 328 -> 327), so the budget's pressure lever moved the right
direction while the reference gained real contract content.
fix(tools): align write tool schemas, docs, and adapter coverage
fix(tools): harden note, change log, and blocker writes
fix(tools): harden mutation write paths
@hffmnnj
hffmnnj merged commit e78c1be into main Aug 12, 2026
0 of 2 checks passed
@hffmnnj
hffmnnj deleted the fix/write-boundary-contracts branch August 12, 2026 12:17
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant