octave_write
Create, modify, or normalize OCTAVE files with full content or targeted changes, including schema validation and dry-run support.
Instructions
Unified entry point for writing OCTAVE files. Handles creation (new files) and modification (existing files). Use content for full payload, changes for delta updates. Omit both content and changes to normalize an existing file in-place. Replaces octave_create and octave_amend.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| target_path | Yes | File path to write to | |
| content | No | Full content for new files or overwrites. Accepts raw OCTAVE or a single markdown fenced code block. Mutually exclusive with changes. | |
| changes | No | Dictionary of field updates for existing files. Each value is either a bare value (full replacement, default) or a $op descriptor: {"$op":"DELETE"} removes the target; {"$op":"APPEND","value":x} pushes x (or each item of list x) onto the end of an array target; {"$op":"PREPEND","value":x} unshifts onto the front of an array; {"$op":"MERGE","value":{...}} deep-merges into a block target, preserving unmentioned children (use inner $op:DELETE to remove). Op/target-type mismatches return E_OP_TARGET_MISMATCH; missing paths return E_UNRESOLVABLE_PATH (no auto-create, I3); malformed descriptors return E_INVALID_OP_DESCRIPTOR. Paths support: top-level KEY, META.FIELD, PARENT.CHILD into a top-level Block, and §N.KEY / §N::NAME.KEY into Sections. (GH#373) | |
| mutations | No | META field overrides (applies to both modes). | |
| base_hash | No | Expected SHA-256 hash of existing file for consistency check (CAS). | |
| schema | No | Schema name for validation (I5). Common schemas: META, SKILL, CRS_REVIEW, COGNITION_DEFINITION, DEBATE_TRANSCRIPT. Use 'frozen@<hash>' or 'latest' for hermetic resolution. If an unknown schema is provided, the response includes available_schemas. | |
| debug_grammar | No | If True, include compiled regex/grammar in output for debugging constraint evaluation. | |
| grammar_hint | No | If True and validation returns INVALID, include compiled GBNF grammar in response to guide correction. | |
| lenient | No | If True, enable deterministic lenient parsing + optional schema repairs. Default: false (strict parsing). | |
| corrections_only | No | If True, return corrections/diff without writing to disk (dry run). | |
| dry_run | No | Alias for corrections_only. If True, return corrections/diff without writing to disk (default: false). | |
| parse_error_policy | No | Policy when tokenization/parsing fails in lenient mode: "error" (default) or "salvage". | |
| format_style | No | Output formatting style for canonical emission. 'preserve' (Strategy A, GH#377): span-aware preserve mode — clean nodes slice from baseline_bytes, dirty/repaired nodes re-emit canonically. Diff footprint ≤0.5% of file size on single-key edits against representative documents. Subsumes GH#248 mixed annotation form drift. 'expanded': lift inline-map shapes (KEY::[K::V,...]) into Block form before emit. 'compact': collapse atom-only Blocks (no comments, arity-bounded) into inline-list-of-InlineMap form. Comment-bearing subtrees vetoed with W_COMPACT_REFUSED (I3 Mirror Constraint, I4 Auditability). DEPRECATED v1.13.0: Passing format_style=null explicitly emits a DeprecationWarning; the default will change from full canonical re-emit to 'preserve' in v1.14.0. To keep canonical re-emit past the flip, pass 'expanded' explicitly. To opt in to the new default early, pass 'preserve'. Omitting the parameter accepts the future default silently. |