run_workbook_recipe
Destructive
Preview or commit a reusable JSON recipe to group, filter, and aggregate workbook data into a reserved output range, with token and hash checks for safe writes.
Instructions
Preview or commit a reusable JSON recipe without echoing intermediate rows.
Recipe v1 requires version=1, source={table_name, optional sheet_name},
group_by=[exact header names], metrics=[{op, field, as}], and
output={sheet_name, range_ref, optional allow_overwrite=false}.
Optional filters use query_table operators; optional checks support unique_key
(fields), row_count (min/max), and sum_matches (source_field/output_field).
count metrics omit field. Other metrics: sum, avg, min, max, count_non_null,
count_distinct. Only literal finite JSON cells in referenced fields are supported.
Optional workbook_contract enforces Contract v1: source selectors must match,
ALL Recipe input references must use contract fields[].name, NEVER physical
fields[].headers. Copy names from inspection.recipe_input_fields (binding keys).
Example: net bound to NetSales -> metrics=[{op:"sum",field:"net",as:"Revenue"}];
currency bound to Currency -> group_by=["currency"]. The as label stays Revenue.
This also applies to filters.field, unique_key.fields and sum_matches.source_field.
Contract field errors return bounded details.examples with Recipe JSON-pointer
paths and exact replace_with names where known: fix the Recipe references only,
keep workbook_contract unchanged, then make a NEW preview before commit.
Contract filters are mandatory
AND predicates. All contract rows are checked before filtering and again on
the saved workbook. Repeat the identical contract on commit; changed contracts
invalidate recipe tokens. Declared meanings are not verified business truth.
Output is one reserved rectangle in the same workbook, fully replaced including
blank padding. Occupied output requires allow_overwrite=true; table/merge overlap
is rejected. Preview first, then commit the unchanged recipe with recipe_token
and expected_workbook_sha256 from preview. A verified snapshot is always enabled.
Limits: 50,000 source cells, 64 source columns, 10,000 output cells; sample_limit 1-10.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | preview | |
| recipe | Yes | ||
| filepath | Yes | Reuse supplied server path; NEVER prepend client cwd. Rooted: relative OK; unrooted stdio: absolute, ask if missing. | |
| recipe_token | No | ||
| sample_limit | No | ||
| workbook_contract | No | ||
| expected_workbook_sha256 | No |