Repository navigation
fix(tools): normalize injected write defaults - #296
Merged
Merged
Conversation
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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
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 typecheckThe running host uses an already-loaded bundle, so source-level tests provide the behavioral evidence for this change.