# Changelog Every release and what changed in it. Newest first; versions follow calver (`YY.M.D`) and match `oryxflow.__version__`. All notable changes to **oryxflow** are recorded here. This file is read by humans *and* by AI coding agents diagnosing regressions after an upgrade, so the format is load-bearing: - Newest first. One `## [version] - YYYY-MM-DD` heading per release; version is calver `YY.M.D` matching `setup.py` / `oryxflow.__version__`. Unreleased work goes under `## [Unreleased]`. - Group bullets under `### Added` / `### Changed` / `### Deprecated` / `### Removed` / `### Fixed` / `### Security` (Keep a Changelog: https://keepachangelog.com/). - **Every breaking change is a bullet that STARTS with the literal token `BREAKING:`** and carries a same-bullet `Migration:` clause with the old→new fix. - **Name the actual symbol in backticks** (`` `Task.persist` ``, `` `RunResult.summary()` ``), never prose. Agents grep this file for the symbol in their traceback. ## \[26.11.6\] - 2026-11-06 ### Added - `oryxflow.codehash.strip_docstrings`, the public name of the docstring normalizer that code hashes use. - `task_ran` and `task_failed` events carry lineage in OpenLineage vocabulary, kept flat: `project` (the job namespace: the project folder's name), `inputs` and, on `task_ran`, `outputs`. Each entry is one dataset `{namespace, name, datasetVersion}`: `namespace` is the project that owns it, `name` its path relative to that project's root (`None` for a dependency without file outputs), and `datasetVersion` the `output_id` of that materialization (`None` when the task's code is not tracked). Inputs also carry the dependency's `task_id` and `family`. An input's `datasetVersion` equals the `datasetVersion` in the dependency's own `task_ran` outputs, across `FlowImport` too, so `jq '.inputs[] | {name, datasetVersion}'` answers "which build fed this", and the log converts to OpenLineage RunEvents without re-running. Events written before this change have none of these fields. Design: `docs/todo/20261028-sys-runlog-lineage.md`. - `oryxflow.utils.excel_write(..., format_float=None)` (also a per-sheet option, and passed through `save(formatted=True)`): the number format of float columns that no `formats` key or glob matches, e.g. `format_float='pct'` for a sheet of rates. Any name or code `formats` accepts; a mistyped name raises `KeyError`. `None` keeps the `'float'` preset. `oryxflow.report.resolve_formats` gains the matching `float_default` argument. - `bind(**values)` on a task loaded with `FlowImport` overrides its exported defaults where you require it: `@oryxflow.requires(exported.ReturnsMarket.bind(refresh='2026-07-18'))` (compare with last quarter). A `built` entry works as is (`X.bind(**X.built[0])`; its `prod` mark is ignored). Design: a bound parameter stays on the imported task (it is part of that task's id, which locates the producer's file) but is not copied onto the requiring task (`core._apply_spec` skips `_oryxflow_bound`) nor passed to it by `Task.clone()`, so it does not enter the consumer's flow parameters or any downstream task\_id. Reruns follow the input through the dependency fold (`TaskData._dep_state`): a new bound value, a new exported default, or the producer recomputing that build reruns the consumer; the exact input of every run is recorded in the `task_ran` event's `inputs`. - `Workflow(..., export=False)` and `WorkflowMulti(..., export=False)`: runs of that flow never update `tasks_export.py`, so an experiment flow cannot add its parameter values to `built`. - A run warns when a project module it did not import marks a class `export = True` that `tasks_export.py` does not list yet (`FlowExport.unloaded`). - `Workflow.get_task()` (and so `flow.outputLoad()`, `flow.run()`, `flow.preview()`) accepts a task instance, keeping its own parameter values: `flow.outputLoad(tasks.X(segment='a'))` for a task with a parameter the flow doesn't set. Before: `TypeError: 'X' object is not callable`. - `preview()` marks the parameters fixed on an imported task (its exported defaults or `bind()`): `Returns[bound: refresh=2026-07-18, sector=office]-{...}`, apart from the values that came through the flow. - `TaskNotebook.publish`: a path pattern (or list) filled with the task's parameters, such as `publish = 'reports/render/viz-{market}-performance.html'`. Every run also writes the report there (a `.ipynb` pattern gets the executed notebook), through a temporary file. The task counts as complete only while every published copy exists, so a deleted copy is rebuilt. Two reports of one run that would publish to the same file raise `ValueError` naming both. - `TaskNotebook.report_title` (pattern like `publish`) sets the html ``. Default: the published html's file name, else the task family. Before, every report's title was "Notebook". - `TaskNotebook.template_deps`: what else the report's code identity watches. Default `'auto'`: the project modules the template's code cells import, and the project modules those import. A list of file globs watches those files instead (`['auto', 'text/*.md']` keeps the imports too); `None` watches the template only. - `oryxflow.report.default_inputs(task, **params)`: one line after the parameters cell makes a template run both under `TaskNotebook` (it returns the injected `oryxflow_inputs`) and by hand in Jupyter (it builds `task`, a class plus parameters or an instance, and returns its inputs; `FileNotFoundError` when they are not built yet). - `oryxflow.tasks.notebook.NotebookCellError`, raised when a template cell fails: a `papermill.PapermillExecutionError` subclass whose message is two lines -- the template, the cell (`In[20]`), its failing source line, the exception, and the saved `.failed.ipynb` -- without terminal color codes. The kernel's full traceback, also without color codes, is in `.traceback` and in the chained cause (so in `TaskFailure.traceback` and the `task_failed` event). `NotebookCellError.failed_path` is the saved notebook. - `oryxflow.report.FORMATS['pct1']`, the same as `'pct'` (one decimal), next to `pct0` and `pct2`. - A template's parameters cell can be a code cell whose first line is `# parameters` instead of one tagged `parameters` (tags are hard to set outside Jupyter). The template file is not changed. ### Changed - BREAKING: an exported task's defaults are its prod values. `FlowImport` binds every imported parameter to its exported default, so `@oryxflow.requires(exported.X)` copies no parameter onto your task: before, the producer's parameters passed through the flow and entered your task ids. A same-named parameter of your task is no longer passed to the imported one either. Your task reruns when the producer changes a default (a new quarter) or recomputes that build. Other values: `exported.X.bind(sector='retail')`, or `exported.X(sector=self.sector)` in your own `requires()` for a value that varies with your task; `@oryxflow.requires_each(exported.X, sector=[...])` fans out over one. Migration: remove the producer's parameters from your `Workflow` params / `flow_params.py`; where you chose a non-default value, `bind()` it. Your tasks' ids change once, so they recompute once. - BREAKING: an exported task (`export = True`) needs a default for every parameter, the value consumers should get. `flow.run()` stops before building with `ValueError: <Task>.<param>: exported parameters need a default -- the value consumers should get (prod)`, and so does `FlowExport.generate()`. Parameters named `prod` or `bind` can't be exported (they clash with `built` and `bind()`). Migration: give each exported parameter its prod value as default (`date_asof = oryxflow.Parameter(default='2026Q1')`); `flow_params.py` overrides are for experiments, run with `Workflow(..., env='dev')`. When prod spans several values of a dimension (sectors), export an aggregator that holds them all. - `built` in `tasks_export.py` marks the entry whose values are the defaults with `'prod': True`; `external missing output` messages show it as `(prod)`. - A run in the published data folder that writes a non-default build of an exported task because the run asked for it (`Workflow(X, {'sector': 'retail'})`) warns: `X: experiment written to the prod data folder (non-default sector=retail); run experiments with Workflow(..., env='dev')`. A build another task needs (an aggregator over every sector) doesn't warn. An `env=` run beside the published folder no longer warns that `tasks_export.py` keeps pointing consumers at the published folder. - `state.RECORD_V` is 6. A code-status record written by 26.10.22 (v5), or by 26.10.21 (v4) under the same Python minor version, is compared with the code exactly: the code is re-hashed with that version's rules (`codehash.rules_of`, `codecheck.comparable_record`), so an edit made before or after upgrading reruns the task, and an unchanged task is re-stamped without rerunning. Before (26.10.22), every older record was trusted and re-stamped silently on the first build that touched it, which blessed edits made after the upgrade to tasks that build did not reach. A record that can't be compared (an older format, or v4 from another Python) is still kept without rerunning, but the build now says so: one `StalenessWarning` naming every such task, in `RunResult.warnings` and the log, and a `code_warning` event per task (`kind: 'old_record'`) that `events.print_status()` lists until it is rerun or accepted. Migration: none for this upgrade. Records that 26.10.22 already re-stamped blindly can't be checked: `reset()` any task you edited since its last run under 26.10.21. Don't go back: once a data dir has run on this version, don't run it on 26.10.22 again (another branch, another machine). 26.10.22 treats these records as an older format, trusts and re-stamps them without comparing code, so edits made meanwhile go undetected -- the same blind spot this release fixes. - Class attributes `export`, `export_source` and `built` are left out of the code hash (`codehash._METADATA_ATTRS`), like `code_version`: adding or removing `export = True` no longer reruns the task and everything downstream. Records from 26.10.22 that hashed them are compared with the old rules (above), so nothing reruns on upgrade. - BREAKING: `tasks_export.py` lists each class's parameters by name, and `built` entries hold Python values with their keys sorted (`{'debug': False, 'refresh': datetime.date(2026, 10, 18)}`; a value with no literal form, such as an enum, stays a string). Before, parameters followed module import order, so the file changed depending on which script ran, and `built` values were strings (`'False'`). Existing files are rewritten in the new form on the next producer run; the task ids are unchanged. Migration: compare `built` values with Python values (`b['debug'] is False`), not strings. - Adding a `code_version()` method to a task that was tracked automatically reruns it once. Before, its first value was adopted without rerunning, so the recipe `{'data': hash_files(path), 'code': ...}` never noticed that the file had changed since the cached run. Adding a plain `code_version = '1'` pin stays free. - A consumer of an imported task whose producer keeps no code-status record (its code tracking is off) reruns when the producer rewrites that output (by file time); before, it never reran for those. Consumers of such producers rerun once after upgrading. - `tasks_export.py` update failures are in `RunResult.warnings`, the log and an `export_failed` event, not only a `UserWarning`. - `TaskNotebook` reruns when a project module its template imports changes (for example `viz/report.py` after `from viz import report`). Before, only the template's cells and the task's own Python counted, so editing a plotting or text helper left a stale report while the run showed success. Comments and docstrings don't count, nor do installed packages, nor modules that define tasks or a flow (a template imports `tasks` to run by hand; a task edit already reaches the report through its data). Upgrading reruns every report whose template imports a project module (such as `viz/`, `utils/` or `cfg.py`) once, on the first run, even if nothing changed: expected, no action needed. Reports whose template imports none keep their cached output. The rerun reason names what changed: `code change (template dep viz/report.py)`, `code change (template cells)` or `code change (task code)`, for reports made by this version or later (older reports show the two code tokens). - BREAKING: `oryxflow.report.inputLoad(task=...)` on a dependency with several outputs and no `keys` returns `oryxflow.report.Outputs`, a list of the outputs in `persists` order as `self.inputLoad()` returns, that also takes an output's name (`out['series']`, `.keys()`, `.items()`). Before, it returned a dict, so `a, b = rpt.inputLoad(task='x')` silently unpacked the output NAMES. Migration: `out['name']` keeps working; replace iteration over the names (`for k in out`, `set(out)`) with `out.keys()`. - Two `@oryxflow.requires_each` fan-outs of different tasks over the same values are keyed by task family (`RegionChart_north`, and `inputLoad(flatten=False)['RegionChart']['north']`) instead of raising `ValueError: dependency key ... is produced by both`. Fan-outs whose values don't overlap keep the bare value keys; the same task fanned out twice over the same values still raises. - `oryxflow.utils.excel_write`: a sheet spec's `formats` is merged over the shared `formats=` (the sheet's keys win, and its globs are tried first; a `None` value drops a shared column format). Before, it replaced them. `formats=False` on a sheet still writes it without number formats. - `TaskNotebook` no longer makes papermill log `Passed unknown parameter: <name>` for each task parameter the template does not declare (a report inherits every parameter of its upstream band). Names added by `notebook_parameters()` still warn. The kernel runs with `PYDEVD_DISABLE_FILE_VALIDATION=1` unless you set it, which silences the debugger's "frozen modules" note. - `oryxflow.utils.excel_write`: a column named in a workbook-level `highlight`, `colorscale`, `wrap_columns`, `group_starts` or `id_columns` applies to the sheets that have it. Before, a sheet without the column raised `KeyError`. A name no sheet has still raises, and so does a sheet spec's own option naming a column that sheet lacks. - `oryxflow.report.table` shows a named index as ordinary leading columns headed by its name, so `formats` and `rename` can address it. Before, pandas put the name on its own header row with a blank band under the column headers. - `oryxflow.report.table` right-aligns columns of numbers stored with object dtype (a transposed frame), as it does float and int columns. - `excel_write` takes an open binary file handle as `path` (the atomic `.tmp` + `os.replace` recipe is in the Excel docs). The reports guide says which Python runs the `python3` kernel, how to pick another with `kernel_name`, and that the task's Python counts only with `code_version_auto` on. - `pip install "oryxflow[evals]"` installs `oryxeval` (Python 3.10+; nothing on 3.9). ### Removed - BREAKING: `oryxflow.evals` moved to its own package, `oryxeval` (same names; existing eval caches stay valid when only the import lines change). Migration: `pip install oryxeval`, then change only the import lines: `import oryxflow.evals as ev` -\> `import oryxeval as ev`, `from oryxflow.evals.<module> import X` -\> `from oryxeval.<module> import X`. Keep `import oryxflow` and leave every function body as it is: `code_version()`, `case()` and their helpers are hashed into the cache key, so any edit there (even `oryxflow.hash_files` -\> `ev.hash_files`) re-runs every arm. The next run reuses the cache but prints StalenessWarnings; clear them once, from `evals/`: `python -c "import oryxflow; oryxflow.accept_code()"` (re-stamps both stages of every cached arm; the `accept_code(<Eval>)` the warning names covers only the scoring stage). New evals use `ev.hash_files`. ### Fixed - Code-status records written by a NEWER oryxflow (record `v` above `oryxflow.state.RECORD_V`) are no longer re-stamped: the build's advisory sweep and `accept_code` leave them as they are, the task is kept without rerunning, and one `StalenessWarning` (event kind `newer_record`) names the tasks. Before, an older library rewrote them in its own format and silently blessed any edit made since. `oryxflow.state.is_newer(rec)` is the check. Releases up to 26.10.22 still re-stamp newer records: do not run a data folder a newer oryxflow built with them. - `TaskNotebook` html reports show dollar amounts as text: `$1.2bn to $3bn` was rendered as a LaTeX formula. The html no longer loads MathJax; set `html_mathjax = True` on the task to render formulas. - A task whose dependency check moved without any upstream task running in the build reports `upstream output changed since last run`, or `dependency check re-based (record from an older oryxflow)` on the first run after upgrading (`RunResult.reasons`, the `task_ran` event). Before, both read `upstream rerun`, pointing at an upstream that hadn't run. The reason names the input that moved: `upstream output changed since last run: now Returns_2026_10_18_... (was Returns_2026_07_18_...)` when an imported task is bound to other parameters, `...: rewritten <task_id>` when a dependency's output was rewritten (records carry a new `dep_ids` field; a record written before it gives the plain text). - A run whose flow imports another project's tasks no longer counts those imported classes as this project's when it updates `tasks_export.py` (which could drop entries when both projects share a data-dir parent). - Imported (`external`) tasks are no longer code-checked by the consumer: no false `StalenessWarning` comparing the export stub with the producer's record (with the expensive-recompute text for a short task), and the consumer's advisory sweep and `accept_code()` never write records into the producer's data dir. - The code-change warning for a task with automatic tracking off (`settings.code_version_auto = False`) says so, instead of naming the expensive-recompute guard. - A tracked task (a `TaskNotebook`, or one with a `code_version`) whose dependency is not tracked (`settings.code_version_auto = False` and no `code_version`) reruns when that dependency recomputes. Before, the dependency kept no code-status record, so `TaskData._dep_state` saw no change and the tracked task stayed stale with a green run unless its own output was deleted. An untracked dependency now counts by its output file's modification time. A record written by 26.10.22 matches the old fold once and is re-stamped, so upgrading reruns nothing. - Two tasks sharing an upstream whose output was missing both rerun. Before, `core.build` visited the first, which reran the upstream, and the second then looked complete and was skipped: stale, with a green run, depending only on dependency order. Now a complete task whose upstream ran in the same build reruns (when `settings.check_dependencies` is on, the default). - `reset_downstream()`, `invalidate_downstream()` and `run(forced=...)` delete every task in the band that has output on disk. Before, they skipped a task that looked incomplete only because an upstream output was missing, and its stale files were kept. - A `@requires_each` grid computed from the task's own value of the fanned parameter (`period=lambda t: [prior(t.period)]`, "the same loader at the previous period") raises a `TypeError` that says what to write. Before, it raised a bare `AttributeError` from the lambda. The task can't carry the parameter it fans out over, by design. Write `requires()` by hand with `@oryxflow.inherits` and `self.clone(Loader, period=prior(self.period))`. - `TaskNotebook` runs a template that has no kernelspec in its metadata (one written with `nbformat`), using `kernel_name`. Before, papermill failed with `AttributeError: kernelspec`. - `excel_write` with the same option both shared and on a sheet spec (`excel_write(p, {'a': {'df': df, 'formats': {...}}}, formats={...})`) raised `TypeError: dict() got multiple values for keyword argument`. ## \[26.10.22\] - 2026-10-22 ### Added - Sharing outputs between projects. A task with `export = True` is part of the project's interface: every `run()` that includes one rewrites `tasks_export.py` at the project root (next to `data/`) with a read-only copy of each exported task -- docstring, output format, `persists`, parameters with defaults, `external = True`, the data path relative to the file, and `built`, the parameter values whose output exists. The file is only rewritten when it changes; `run(export=False)` skips it, and a failure to write it only warns. - `FlowImport('<project dir or export file>')` loads another project's `tasks_export.py`; its tasks are attributes (`exported.SectorReturns`, all in `.tasks`). `@oryxflow.requires` them like your own: parameters pass through the flow, and your task reruns when the other project recomputes. Each export loads under its own module name, so two projects with same-named files don't mix. ### Changed - BREAKING: `FlowExport(tasks=None, flows=None, save=False, path_export=None)` writes only tasks marked `export = True` (before: every task unless `export = False`), one class per task with the class's defaults (before: one per task instance, so a fanned-out flow repeated a class), paths relative to the export file and in posix form (a Windows path was written with backslashes, which Python reads as escapes), and `generate()` returns the source. The `path_export` default is `tasks_export.py` next to the data dir. Migration: add `export = True` to the tasks to share; `flow.run()` now writes the file, so drop explicit `FlowExport` calls. - BREAKING: `FlowImport(path, module='tasks_export')` replaces `FlowImport(path, module, path_data)`: the export file carries its data path, and the tasks are attributes. It raises load errors (it printed "Module ... not found." and returned an empty object) and warns when the file was not generated by oryxflow. Migration: `oryxflow.FlowImport('../project1').TaskName` instead of `FlowImport(path='../project1', module='tasks_export', path_data='data').tasks.TaskName` with `path=dirpath` on the workflow. - A run that meets two different task classes with the same task id (same name and parameters, e.g. an imported task and one of yours) raises a `ValueError` naming both; before, the engine silently treated them as one task. A flow's `path=` / `env=` no longer re-points tasks loaded with `FlowImport` (they read the other project's data folder). A class redefined in the same module (a re-run notebook cell) is not affected. - An external task with no output fails with `external missing output (looked for <path>); built: <values> -- this task is produced outside this flow: ...` instead of a bare `external missing output` (`TaskFailure.reason`, the `RuntimeError` from `run()`, the `task_failed` event). - BREAKING: `state.RECORD_V` is 5: code fingerprints use an interpreter-stable AST dump (`codehash._dump`), so they compare across Python versions, and `codehash.PY_TAG` and the records' `py` field are gone. On the first build after upgrading, every existing code-status record is trusted and re-stamped without comparing code, so an edit made before the upgrade and not yet rerun is not detected. Migration: `reset()` any task you edited but have not rerun since its last run; after that first build, detection is exact again. Upgrade every machine that shares a data dir together: an older oryxflow and this one re-stamp each other's records and neither detects edits. - `hash_files` reads files in 1 MB chunks and caches the digest by each file's size and modification time, so a large data file is not re-read on every completeness check. Digests are unchanged. The docs show the recipe for a task that reads a shared data file: return `{'data': hash_files(path), 'code': oryxflow.codehash.task_code_hash(self)}` from `code_version()` so edits to `run()` still rerun it. - BREAKING: a task with `task_group` writes under `<data dir>/group=<name>/`. Before, the folder was created at the root of the drive (`/group=<name>/`, `C:\group=<name>\`), outside the data dir. Migration: move an existing `group=<name>` folder from the drive root into the data dir, or let the task rerun. ### Removed - The `export` install extra (`oryxflow[export]`, Jinja2): `FlowExport` no longer needs it. ### Fixed - `state._write` retries `os.replace` on `PermissionError` (Windows: a sync client or virus scanner briefly holding `.oryxflow-code-status.json`) for about 4.5 s before raising (after a write gives up, writes in the next minute try once, so a read-only data dir does not stall every write). A failed record write in the build's sweep over complete tasks (`codecheck.Advisor.advise`) now warns instead of aborting the build -- the next build writes it -- and a failed write after a task ran is a warning instead of a debug line. - Code edits made under one Python version to a task last run under another are detected (the task reruns). Before, a record from another interpreter was treated as complete and silently re-stamped with the edited code's fingerprint. - Unused-input lint (`inputcheck.check_class`, `Workflow.check_inputs`, `preview()`): with keyed dependencies, a non-literal `task=` (`{n: self.inputLoad(task=n) for n in names}`) or a whole-input load used other than through `data['key']` is reported `unanalyzed`, not `unused`. ## \[26.10.21\] - 2026-10-21 ### Added - `oryxflow.utils.excel_write(path, data, **options)` writes finished-looking Excel files: styled header, filter arrows, frozen header, number formats and auto-sized columns. A sheet can also be a spec dict with `title`, `notes`, `highlight`, `colorscale`, `banded`, `wrap_columns`, `group_starts`, `id_columns` and `freeze`. - `ExcelPandasTarget.save(..., formatted=True)` and `ExcelPandasSheetsTarget.save(..., formatted=True)` (so `self.save(..., formatted=True, formats={'*_pct': 'pct'})` in `TaskExcelPandas` and `TaskExcelPandasSingle`) write through `excel_write`. The default `formatted=False` is unchanged. - `oryxflow.report`: the format presets `FORMATS` (`'pct'`, `'int'`, `'thousands'`, `'date'`, ...), `fmt(value, spec)` and `excel_code(spec)`. A misspelled preset name raises `KeyError` listing the valid names. - `oryxflow.tasks.notebook.TaskNotebook` runs a parameterized template notebook with papermill and saves the executed `.ipynb` plus a code-free `.html` report (via `oryxflow.targets.notebook.NotebookTarget`). It reruns when its upstream data, parameters, task code or the template's cells change, not when the template's saved outputs change. Needs the new `notebook` extra: `pip install "oryxflow[notebook]"`. - `oryxflow.report.table(df, formats=...)` (a pandas Styler), `format_frame(df, formats)`, `inputs_of(task)` and `inputLoad(spec=None, task=None, keys=None)` for report notebooks. `table` takes the same `formats=` dict as the Excel writer. ## \[26.10.8\] - 2026-10-08 ### Changed - BREAKING: `core.task_id_str` caps the readable parameter summary in a `task_id` (and so in every output file name) at 80 characters (`core.TASK_ID_TRUNCATE_SUMMARY`, set with `settings.set_parameter_len(summary=...)`). Before, only each value was truncated (64 chars, up to 20 values, a `ListParameter` counting its whole list), so a task inheriting several long or list parameters got a 269-character path -- past the Windows 260 limit, and past what the Excel desktop app opens (about 218). Uniqueness is unchanged: the 10-char hash still covers the full parameters. Tasks whose summary was already 80 characters or less keep their `task_id`. Migration: none required -- tasks with a longer summary get a new `task_id`, so they recompute once on the next run (their old output files and code-status records are left orphaned; delete them by hand if you want the space back). ## \[26.10.5\] - 2026-10-05 ### Added - `oryxflow.evals`: **a cell is now two cached stages -- the model calls, then the scoring.** `TaskEval` generates an `<Eval>Outputs` task (`TaskJson`, one record per case x repeat: output, inputs, timing, metrics, attributes) that the scoring task requires. Editing an evaluator, changing a judge rubric or swapping the judge model re-scores the stored outputs with ZERO calls to the model under test; editing what the arm reads re-runs both. Before, one `code_version()` keyed both, so a scorer change either re-billed every call or served stale scores. A subclass's `code_version()` keeps its meaning (what the ARM reads) and now keys the model-call stage only; the new `TaskEval.scorer_version()` keys the scoring stage and defaults to every evaluator's code and configuration (`as_spec()`). A typed output is rebuilt with `model_validate`, so `ctx.output.attr` scorers are unchanged. Evaluators that read the run's span tree (`HasMatchingSpan`, `ToolCorrectness`, `TrajectoryMatch`, `ArgumentCorrectness`, `MaxToolCalls`, `MaxModelRequests`, or any with `needs_trace = True`) score in the model-call stage, because spans are not stored. - `oryxflow.evals`: `sweep(rescore=True)` / `ev.cli --rescore` -- re-run only the scorers over the stored outputs (after a transient judge failure, say). The bill prints `re-scoring N arms from stored outputs: no model calls` and counts an LLM judge's calls separately. - `oryxflow.evals`: `baseline=` on `sweep()` (or a `baseline` attribute on a `TaskEval`; default: an arm named `baseline`). The verdict then reports every arm's paired difference from it with its interval, and names no winner -- mixed results need a written judgement, not a pass/fail. - `oryxflow.evals`: `EvalResult.side_by_side(path=None, all=False, template=None)` -- every arm's output per case as markdown, by default only the cases where the arms disagree on a column the verdict reads, plus failures. Rendered with Jinja from the stored outputs (no model call); `template=` takes a path or a string. - `oryxflow.evals`: `load_cases()` also takes a list of row dicts, routed exactly like a file's rows -- for a probe that keeps a handful of cases inline. - `oryxflow.evals`: `ev.cli --side-by-side` writes `EvalResult.side_by_side()` to the eval module's own `results/<date>-<arms>-side-by-side.md`, wherever the run was launched from. - `oryxflow.evals`: `ev.cli` warns when launched from a directory other than the eval script's own -- the cache and relative paths resolve against the working directory, so such a run reads and writes a different cache. - `oryxflow.codehash.callable_hashes(*fns)` / `callable_code_hash(*fns)` -- the function-level sibling of `task_hashes`: a function's own source plus the closure of the module-level symbols it references. What lets two stages of one class own disjoint code identities. - `settings.warn_nested_dir` (default `True`) — a one-time warning when the output directory resolved for a run is empty but a directory of the same name already exists in a parent. The output directory has always resolved against the current working directory, so running a flow from a subdirectory finds an empty `data/` beside it, reports every task incomplete and recomputes everything — re-paying for any metered API call those tasks make, with no signal that it happened. The warning names both directories and the fix; resolution is unchanged and nothing is relocated (searching upward for an existing cache and silently using it was rejected: a flow quietly reading a *different* cache is worse than one quietly rebuilding). Emitted from `set_dir()` only, never inside the execution loop, and suppressed when the local directory already holds output (a deliberate second project) or by `oryxflow.settings.warn_nested_dir = False`. - `code_version` may now be declared as a **method** instead of a constant token: whatever it returns is folded into that task's code identity, so a task can invalidate on bytes that are not Python — a `.sql` file it executes, a prompt template it renders, a `.yaml` config it loads, a resolved model snapshot id. Automatic tracking (`settings.code_version_auto`) hashes the AST of your Python and is blind to all of those, so until now the only escapes were pinning a constant `code_version` and remembering to bump it, or `reset()` by hand — and forgetting either one silently served a stale output. Precedence is unchanged: an explicit `code_version`, constant or method, overrides automatic tracking for that task, and no existing task changes behavior. Two constraints, documented rather than enforced: the method runs on **every completeness check** (memoized per traversal), so its body must stay local and cheap — never a network call; resolve remote values once outside the task and pass them in as a `Parameter`. And it must be deterministic — a `code_version()` returning a timestamp reruns the task every run, which is the declared consequence, not a bug. Editing the method body no longer fires a spurious stale-code warning: `_is_code_version_stmt()` (`oryxflow/codehash.py`) now strips a `code_version` `FunctionDef` from the advisory AST hash, as it already stripped a class-body `code_version = ...` pin. - `oryxflow.hash_files(*patterns, root=None)` — a stable digest of the **content** of every file matching these glob patterns, for use inside a task's `code_version()` when the bytes that determine its result are files (SQL, templates, config) rather than Python. Paths resolve relative to `root` (default: the current working directory) and are sorted, so the digest does not depend on filesystem enumeration order, and a rename registers as a change. Raises `FileNotFoundError` when a pattern matches nothing: a typo'd path that silently hashed to "no files" would report every run as unchanged, which is the failure this exists to prevent. - `oryxflow.evals` — an LLM-eval harness over [pydantic-evals](<https://pydantic.dev/docs/ai/evals/>), installed with the new `evals` extra (`pip install oryxflow[evals]`; pydantic-evals, scipy, typer). Nothing in it is imported by `oryxflow/__init__.py`, so a user without the extra is unaffected; import it explicitly as `import oryxflow.evals as ev`. pydantic-evals keeps scoring — cases, evaluators, repeats, concurrency, retries, the success/failure split — and oryxflow adds the matrix and the cache: one parquet per arm, so a re-run of an unchanged arm makes zero calls and editing the target function or the case file re-runs only the cells that read it. - `ev.sweep(target, cases=..., metric=..., **arms)` runs the grid and returns an `ev.EvalResult` (`.df`, `.verdict()`, `.report()`, `.best()`). `target` may be a plain async function — no class and no scaffold for a first eval — or an `ev.TaskEval` subclass. Any keyword holding a list is an axis. The projected call count, the cached/new split and a cost estimate print **before** anything is billed, and a swept parameter the function cannot accept raises rather than running N identical cells labelled as branches. `watch=` (glob patterns, or a callable) folds files the target **reads** — a prompt template, a `.sql` file — into the cache key, so editing one re-runs the arms that read it; without it a prompt sits outside the key entirely and an edit re-runs nothing. - `ev.TaskEval` is the class form (a `TaskPqPandas` with `persists = ['cases']`): declare `dataset`, `metric`, `guardrail`, `slices` and one `case()` coroutine. `preflight()` makes one real call before the sweep, so a credential failure costs one call instead of a matrix; above `max_failure_rate` (default 20%) the run raises `ev.EvalFailureRateError` and **saves nothing**, because a parquet of exceptions is indistinguishable from a measurement. `concurrency` is `significant=False`, so it cannot fragment the cache. - `ev.load_cases(path, inputs=..., expected=...)` reads cases from `.csv` / `.yaml` / `.jsonl`, routing columns by name; a `@path/to/file.md` value is replaced by that file's text. `synthetic` cases are reported beside the headline and never in it, and `holdout` cases are withheld from every arm with the count stated. - `ev.Metric(label, column, where=, higher_is_better=, budget=, coverage=)` is the number a sweep is judged on. `ev.rate_ci` / `ev.delta_ci` (scipy, clustered by case) put a confidence interval on it. The verdict names **no winner** when the delta interval spans zero, never says "wins" unqualified when a guardrail budget broke, flags a metric that is identically 0% or 100% in every arm, and flags a denominator that moved between arms. - `ev.git_tree(ref, paths, dest=, expect_absent=)` materializes a baseline arm from a git ref (byte-exact, and the only mechanism that can restore a *deleted* file); `ev.git_sha(ref)` is the resolved SHA to use as that arm's `code_version()`. `ev.Variant(old, new)` is the anchored-replacement probe for a rewrite that has not shipped, and raises when its anchor is gone rather than silently becoming a no-op. - `ev.cli(TaskEvalSubclass)` builds a Typer command line whose flags are **derived** from the task's Parameters, so adding a parameter adds a repeatable flag and the two cannot drift. Built-ins: `--repeats --concurrency --reset --check --csv --yes`; `--check` runs `preflight()` only and exits. `ev.cli` / `ev.build_app` resolve on first use, so `import oryxflow.evals` does not pay for Typer. ### Changed - `oryxflow.evals`: the `evals` extra now requires `pydantic-evals>=2` (for the tool-call evaluators, `CaseLifecycle` and Windows-safe report output) and adds `jinja2` (for `side_by_side()`). - `oryxflow.evals`: `reset=True` / `--reset` discards BOTH stages, model calls included. Use `rescore` to re-run only the scorers. - `oryxflow.evals`: the function form's arm identity now also follows what the target CALLS (`codehash.callable_code_hash`), not only the target's own body -- editing a project-local helper or prompt loader re-runs the arms that use it. - `oryxflow.evals`: `rep` is read from pydantic-evals' own `"<name> [i/N]"` naming when outputs are stored, instead of being re-derived from row order (`TaskEval._assign_reps` is now a no-op kept as an override point). - `requires_each`: the "declares a parameter and also fans out over it" `TypeError` now names the legitimate case it used to steer wrong - a task that compares its own value with others (`sector` vs `sector_compare`) - and points to `self.requires_grid(...)` in `requires()` rather than only "Remove the declaration". The `requires_each` docstring shows that form with `inputLoadConcat(tagkeys=[...])`. Message and docs only; behavior unchanged. - `state.RECORD_V` is now `4`: the code fingerprint folds in the resolved `code_version` token, and freshness records store that **resolved** token rather than the raw attribute. Records written at `v3` are treated as unverifiable and silently re-stamped by `build()`'s advisory sweep — a one-time re-baseline, never a mass rerun, exactly as the v2→v3 transition did. - `oryxflow.evals`: **judge validation.** `ev.judge_alignment(df, judge, human)` reports a judge's TPR, TNR and Cohen's kappa against human labels, and `ev.corrected_rate(observed, alignment)` applies the Rogan-Gladen correction -- the standard estimator for a proportion measured with an imperfect test, which is what an LLM judge is. Declare it on the metric (`ev.Metric('pairing', 'pairing_holds', human='pairing_human')`) and the verdict prints the alignment and the corrected rate per arm. Kappa is reported *and labelled* as the one to read, because raw agreement inflates under class imbalance: on a 90%-pass set a judge that passes everything scores 90% agreement and has learned nothing (kappa 0). The correction is REFUSED when `TPR + TNR <= 1`, where the estimator's denominator collapses and the "correction" is amplified noise. This matters beyond tidiness: an imperfect judge pulls every rate toward its own error floor, so it shrinks the very difference a sweep exists to detect -- a true 85% vs 55% reads as 78% vs 60% through a judge that is 88% accurate. - `oryxflow.evals`: a **guardrail inside budget on the point estimate but not on its interval** now says so (`the interval for prod reaches 25% -- at this sample size the guardrail is not demonstrated, only not yet violated`). At n=12, `0% (0/12)` is entirely consistent with a true rate above a 5% budget, and the bound is the thing to act on. - `oryxflow.evals`: a **lone arm scoring 100%** is flagged as saturated rather than reported as a win -- a case set that never fails cannot show a regression or an improvement, so the response is harder cases. (Multi-arm saturation was already caught by the dead-metric check.) - `oryxflow.evals`: `ev.PromptArm` -- where one arm READS its prompt files and the cache key that MATCHES them, in one object (`.dir()` and `.code_version()`). Written by hand those are two places that must agree, and when they drift the failure is silent: a baseline arm reading a checked-out tree but keyed on a hash of the LIVE files re-runs when a live prompt is edited, and does *not* re-run when it is pointed at a different ref. A working-tree arm is keyed on the content of its `globs`, a `ref` arm on the resolved sha; both hand back the same layout via `subdir=`, so a loader never has to know which arm it got. An arm with no key at all is refused at construction. - `oryxflow.evals`: the cost confirmation now offers the one-call preflight **at the prompt** -- `Run 56 new calls for X? (y/n/c=check one call first)`. `c` spends one call, reports whether the wiring works, and asks again. A `--check` flag only helps someone who already knows it exists, and the person who needs it most is running the eval for the first time. Deliberately still *offered* rather than run automatically before the bill: a tool that bills money should not make its first call unasked, however cheap. - `oryxflow.evals`: `sweep()` accepts `evaluators=` and passes them to the dataset it generates. The target function is handed only `inputs`, so scoring against a case's `expected_output` — the shape every classifier eval has — previously required building a `Dataset` by hand and passing both `cases=` and `dataset=`. - `oryxflow.evals`: a sweep axis with a **single value** no longer appears in the arm name. It is identical in every arm, so it added width to every row of every table and distinguished nothing: `model_id=['gemini-3.5-flash'], prompt_version=['prod','preship']` now names the arms `prod` and `preship` rather than `model_id_gemini-3.5-flash_prompt_version_prod`. When *no* axis varies the full name is kept, since a lone cell called `default` says less. - `oryxflow.evals`: `verdict()` no longer reprints the call-count header that `sweep()` already emitted as the bill, and "Weakest slices" lists only slices actually **below** the arm's own rate — a 100% slice under that heading reads as a warning about something that is fine. ### Fixed - `oryxflow.evals`: a `TaskEval` subclass now re-runs when its case set changes. Only the function form folded the cases into its cache key, so editing `cases.csv` under the class form served the previous cases' results. - `oryxflow.evals`: under pandas 3 the `<field>_preview` columns were never written, because text columns get a `str` dtype instead of `object`. - `oryxflow.evals`: the per-case frame was discarding most of what the report carried. `_to_frame()` read only assertions, scores, metadata and the output, so **six** things went on the floor. Now columns: `case.metrics` (what `increment_eval_metric` recorded -- token counts, retries, anything a task measures about its own call), `case.attributes` (`set_eval_attribute` -- a resolved model snapshot, say), `case.expected_output` (flattened to `expected` / `expected_*`), `case.labels`, `case.total_duration`, and `report.report_evaluator_failures`. The `expected_*` recovery is the one that changes how code reads: a confusion matrix or a per-label breakdown is now a crosstab of two frame columns instead of joining the answer key back on by case name. - `oryxflow.evals`: `EvalResult.verdict()` reports **measured usage** when the task recorded it -- `measured usage: input tokens 9,612, output tokens 2,720` -- read from the conventional `input_tokens` / `output_tokens` / `total_tokens` / `cost` columns. Before this, cost could only ever be the pre-run estimate, because the real numbers pydantic-evals collected were being thrown away. Reported by name rather than inferred from any numeric column: guessing which column is a token count eventually sums something that is not one. - `oryxflow.evals`: an evaluator that **raised** is no longer indistinguishable from one that declined to score. `ReportCase.evaluator_failures` was read by nothing, so a judge crashing on every case (a missing API key, say) left its column absent and the metric reported `n/a` with no hint that anything was wrong. The frame now carries `evaluator_errors` / `evaluator_error` and the verdict prints them above the rate. `case.labels` was likewise dropped and is now a column like assertions and scores. - `oryxflow.evals`: a sync `case()` (or a sync `sweep()` target) no longer silently serializes the run. `concurrency` is scheduled as coroutines by pydantic-evals, so a blocking case holds the event loop and the cases run one at a time while the setting still reads as honored -- same numbers, \~5x the wall clock (8 half-second cases at `concurrency=4`: 1.0s async, 4.9s sync). It now emits a `RuntimeWarning` naming the task and the ignored concurrency. Nothing about oryxflow itself is async; the requirement comes from the eval runner, and `concurrency=1` is the quiet way to opt out. - `oryxflow.evals`: the dead-metric flag no longer fires on a **guardrail sitting inside its budget in every arm**. `0%` false-positives on both sides is the outcome a guardrail exists to confirm, and reporting it as "this usually measures the harness" teaches the reader to ignore the one line that matters when it is real. A guardrail identically *over* budget is still flagged. - `oryxflow.evals`: declining the cost confirmation on the `ev.cli` path exits 0 with a one-line message instead of raising through to a traceback. Choosing not to spend is the outcome the confirmation exists to make easy. - `oryxflow.evals`: a `Metric` no longer counts an **unmeasured** row as a failed one. A row whose metric column is null (an LLM judge that grades only some cases, or one switched off with `--judge-model none`) is now excluded from the rate exactly as an errored row is, instead of being coerced to `False`. Previously that both deflated the numerator and padded the denominator: a prompt passing 2 of 2 judged rows out of 6 reported `33%`, and a metric with no verdicts at all reported a confident `0%` with a confidence interval. `Metric.compute()` now counts only measured rows, a wholly unmeasured metric returns `NaN` and renders `n/a`, and `Metric.unmeasured()` / the verdict state how many rows carried no verdict. New `Metric.eligible()` is the denominator before that filter. - `oryxflow.evals`: `sweep()` no longer silently overwrites a case metadata column named `arm` (or one named after a sweep axis) with its own cell label. `arm` is the natural word for a dataset that compares, say, an `outline` arm with a `guidelines` arm, and the tag destroyed it: any `slices=('arm',)` then reported the arm label back with no error and a plausible-looking table. The clash is knowable from the cases alone, so it now raises **before any call is made**, naming the key and the fix. `arm` joins `RESERVED_METADATA`. - Automatic code invalidation (`settings.code_version_auto`) no longer raises `RuntimeError: dictionary changed size during iteration` when a task's import graph includes a package inserted into `sys.path` at run time and a lazy import fires mid-hash. `oryxflow/codehash.py` now snapshots `sys.modules` before iterating it, which is also the correct semantics: the hash describes the module set as it stood when the traversal began, which is what `codehash.freeze()` already brackets `build()` to guarantee. ## \[26.8.2\] - 2026-08-02 ### Added - `Workflow.dependents(task, root=None, paths=False)` and `Workflow.dependencies(task=None, target=None, paths=False)` (plus `WorkflowMulti` variants with a `flow=` selector) — ask the DAG "what depends on this task" / "what does it depend on" instead of grepping or hand-rolling a walk over `requires()`. `task` may be a **class, family string, or instance**; a class/string is *not* instantiated, so it works for fanned-out / DAG-internal families that `get_task()` can't build. `paths=True` returns the ordered `root→task` routes (a list of task lists) instead of the deduped set. Backed by `core.find_deps` (set) and the new `core.find_paths` (ordered, re-exported as `oryxflow.find_paths`); both are now memoized, so the walk is polynomial on diamond-heavy DAGs instead of exponential. `dependents(X)` is the discoverable, correctly-named form of the confusingly-argued `taskflow_downstream(task, task_downstream)` (kept as an alias). - `Workflow.check_inputs(tasks=None, raise_on_unused=False, include_clean=False)` — static AST lint that reports a declared `@oryxflow.requires` dependency whose data `run()` **loads and never reads**. Such a dead dependency is invisible to every dependency query (the edge is real, only the data is dead) yet still forces its whole upstream band on every cold build. `preview()` surfaces these automatically in an `UNUSED INPUTS` block, deduped per family; `run()` does not lint, keeping the execution path free (call `check_inputs()` explicitly for CI). Three verdicts — `unused` / `clean` / `unanalyzed` (a shape it can't prove is `unanalyzed`, never silently `clean`); outer unpack elements are dependencies, inner are that dep's `persists` (a top-level `_` is a finding, an inner `_` is normal). Suppress a deliberately-unused dependency with a `# oryxflow: input-unused` comment. New module `oryxflow/inputcheck.py`. - `@oryxflow.requires_each(task, **grid)` — declare one dependency **per value** instead of one dependency: `@oryxflow.requires_each(ModelTrain, model=MODELS)` on the task that combines them. Like `@oryxflow.requires` it copies the dependency's parameters onto the decorated task, minus the ones being fanned out (those differ per branch, so the combining task must not carry them), and it defines `requires()` as a `requires_grid` over the values. Naming several parameters fans out over their cartesian product. Use it instead of hand-writing `{v: Task(param=v, shared=self.shared) for v in values}`, which only reaches the branches with the parameters you remember to forward. - `@oryxflow.requires`, `@oryxflow.inherits` and `@oryxflow.requires_each` now **stack** on the same task, in any order and any number. The normal combining task needs the fan-out *and* a shared dependency that is deliberately not fanned out — the table the branches were built from, a baseline to score them against, labels to render with: `@oryxflow.requires({'input': ReportInput})` above `@oryxflow.requires_each(RegionNarrative, region=REGIONS)`. Previously each decorator owned `requires()` outright, so the second one raised and the only way through was `@oryxflow.inherits` plus a hand-written `requires()`. The parameter rule holds across all of them: the combining task gets every dependency's parameters except the fanned-out ones. - `@oryxflow.requires_each` accepts a single-entry `{name: Task}` dict to name the fan-out group; the group defaults to the dependency's own task family. A named group qualifies its dependency keys with that name (`chart_north`), which is how two fan-outs over the same values are disambiguated. Unnamed groups keep bare value keys, so existing tasks are unaffected. - `@oryxflow.requires_each` and `Task.requires_grid` accept a **callable** grid value — `region=lambda self: REGIONS[self.sector]` — for a fan-out computed from the task's own parameters, which previously forced a hand-written `requires()`. The callable sees the task's parameters, not its inputs. - `@oryxflow.requires_each` and `Task.requires_grid` accept `derive={'name': fn}` — a further parameter set **per branch** from that branch's fanned values, for the setting that follows from the value the branch was built for: `@oryxflow.requires_each(RegionLoad, region=list(SOURCE), derive={'source': lambda v: SOURCE[v['region']]})`. Each function is handed that branch's values (`v['region']`) and its result is passed to the branch as a parameter, so it counts towards the branch's `task_id`: editing one entry in `SOURCE` invalidates exactly that branch. Previously the only places to put such a lookup were the branch's `run()` — where it is invisible to the cache, so changing it silently returned the old output — or a hand-written `requires()`, which drops every parameter you forget to forward. Derived names stay out of the dependency keys (`inputLoad(task='north')` is unchanged) and off the combining task, for the same reason fanned names are. - `inputLoad(flatten=False)` groups a fan-out's branches under one key (`{'input': df, 'RegionNarrative': {'north': ..., 'south': ...}}`), so a task that mixes a fan-out with shared dependencies no longer has to pop the keys it recognises and assume the rest are branches. `inputLoad(task='<group>')` and `inputLoadConcat(task='<group>')` select just the branches; `inputLoadConcat(flatten=False)` returns one DataFrame per group. ### Changed - Traversal-scoped memoization makes no-op re-runs and `preview()` near-instant on wide fan-out DAGs. Three engine questions used to recurse over each task's whole upstream closure once per **path** through the DAG, not once per task: `TaskData.complete(cascade=True)`, `_resolve_requires()`, and `Task._code_fingerprint`. On a 41-branch fan-out over a shared aggregator (75 tasks) a no-op `run()` did 1,428 completeness checks, 586 `requires()` resolutions and 8,439 fingerprint evaluations; `preview()` did 5,552 / 873 / 13,685. A new per-traversal memo (`oryxflow.core.traversal_scope`, opened by `build()`, `preview()`, `Workflow.complete()`, the `taskflow_*` walks, `dependents`/`dependencies` and `accept_code`) collapses each to **one execution per unique task** — the same no-op `run()` now does 75 / 43 / 75. Behaviour is unchanged: completeness answers are dropped whenever a task materializes (`save()`), is invalidated (`reset()`/`invalidate()`), or runs inside a build; the code/DAG-shape memos live for the traversal (the engine already forbids code changes mid-build, per `codehash.freeze()`). A bare `Task.complete()` outside any traversal is unmemoized, exactly as before. With cloud storage this also cuts the per-object existence API calls by the same factor. - BREAKING: `cls` and `derive` join `path` and `flows` as **reserved parameter names** — declaring `derive = oryxflow.Parameter(...)` (or `cls`) on a task now raises `ValueError` at class definition. Both are arguments of `Task.clone()` / `Task.requires_grid()`, so the argument shadows the parameter: `self.clone(cls=Other)` and `@oryxflow.requires_each(Dep, derive={...})` would bind to the argument and the parameter would never receive a value. Migration: rename the parameter (`derive_features`, `model_cls`). - BREAKING: fanning out over a name the dependency has no parameter for now raises `TypeError` (`@oryxflow.requires_each(RegionLoad, sector=[...])` where `RegionLoad` has no `sector`). It used to produce one dependency key per value all pointing at the **same** task, because `clone()` builds its kwargs from the target's `get_params()` and drops the rest — so `inputLoadConcat()` returned N copies of one branch's output, tagged as if they were different branches. The error lists the parameters the dependency does have. Migration: declare the parameter on the dependency, or fan out over one it has. - BREAKING: a task decorated with `@oryxflow.requires_each(Dep, x=[...])` that also declares its own `x = oryxflow.Parameter(...)` now raises `TypeError` at class definition. The declaration used to survive, putting one branch's value into the combining task's `task_id` — so you got one combining task *per value*, each combining all the branches, cached under different ids at N times the cost, with no warning. Migration: delete the declaration; the combining task is the point the branches converge into and must not carry the fanned parameter. - BREAKING: two dependencies resolving to the same key now raise `ValueError` from `requires()` instead of one silently replacing the other (previously reachable when a fan-out value collided with a named dependency). Migration: name one of them — `@oryxflow.requires_each({'chart': Chart}, region=REGIONS)` or `@oryxflow.requires({'input': ReportInput})`. - `python_requires` raised to `>=3.9` — up from `>=3.5`, which never held: the package has used f-strings (3.6+) throughout for some time, and `install_requires` already imposes 3.9 in practice via pandas and pyarrow. PyPI version classifiers added to match. This corrects the metadata; it does not drop support for any interpreter the package actually ran on. - BREAKING: `oryxflow.utils.requires_grid(task_cls, param, values, **base)` is now the `Task.requires_grid(cls, **grid)` method — same job, done properly. As a free function it had no `self`, so it could not carry the calling task's parameters down to the branches: every shared parameter had to be repeated in its `base` kwargs, and one left out was silently missing from the children (they got the default instead of the flow's value — a wrong result, not an error). The method clones per branch, so parameters propagate exactly as they do through `clone()`. It also fans out over several parameters at once — `self.requires_grid(ModelTrain, model=MODELS, horizon=[1, 5, 20])` gives the cartesian product. Keys are the value itself for one parameter, `name_value` pairs joined with `_` for several, and are what `inputLoad(task=...)` selects on. Migration: `requires_grid(ModelTrain, 'model', MODELS)` becomes `self.requires_grid(ModelTrain, model=MODELS)` inside `requires()`, and any parameter you were passing through `base` can be deleted — it is carried automatically. ### Fixed - Decorating a task with two dependency decorators no longer raises `"<Task>: defines requires() AND is decorated with @requires"` when the task defines no `requires()` at all. The check now distinguishes a hand-written `requires()` (still an error — the decorator would silently replace it) from a decorator-generated one. - `inputLoadConcat()` now warns when it would row-stack a shared dependency in with a fan-out's branches, which produces a union frame across unrelated schemas. Pass `task='<group>'` to concatenate just the branches, or `flatten=False` for one frame per group. - BREAKING: declaring a Parameter named `path` or `flows` now raises `ValueError` at class definition instead of failing silently. `path` is a keyword-only argument the engine uses for the flow's data directory, so `MyTask(path='a.csv')` never reached a Parameter of that name — it kept its **default**, meaning every value mapped to the same task, and that default was then used as the output directory (`x.csv/MyTask/...`). Migration: rename the parameter (`file`, `filename`). - BREAKING: decorating a task that defines its own `requires()` with `@oryxflow.requires` / `@oryxflow.requires_each` now raises `TypeError`. The decorator assigns `requires` after the class body is evaluated, so the hand-written method was silently discarded and the task ran with whatever the decorator declared. Migration: keep one — drop the decorator and write `requires()` (with `self.requires_grid(...)` for a fan-out), or delete the method. - `inputLoadConcat()` / `concat_iter()` warn when a tag column would overwrite an existing column whose values differ from the tag — previously real per-row data (a date column, a category) was silently replaced by one scalar parameter value. Re-tagging with the value already present is unchanged and silent, since that is how each level of a multi-level aggregation legitimately rewrites the level below's tag columns. Silence it with `tagkeys=[...]` or `tag=False`. - `preview()` / `oryxflow.utils.print_tree()` now show parameters for **every** task in the tree, not just the root. A positional-argument slip made the recursion pass `clip_params` as `show_params`, so every child rendered as `[TaskName- (PENDING)]` — in a fan-out over a parameter grid the branches were indistinguishable. `show_params=False` now also reaches the children. - The `RuntimeError` raised by `oryxflow.run()` / `Workflow.run()` on failure now names the failing task **and its parameters** instead of only `Exception found running flow, check trace` — e.g. `Exception found running flow: ModelTrain(model=forest, seed=7): ValueError: training diverged`. Up to three root-cause failures are listed. The original exception is still chained via `from`. ## \[26.7.26\] - 2026-07-26 ### Changed - BREAKING: `TaskAggregator` is now a `requires()`-based group node instead of a task that yields its members from `run()`. Because the group is a regular DAG node, it works with `Workflow` / `WorkflowMulti` (previously every call raised `UnknownParameterException: ... unknown parameter flows`), `preview()` expands it to show each member, and per-flow `path`/`env`, `reset_upstream()` and `FlowExport` reach its members. The group still saves nothing of its own and is complete when every task it requires is complete. The old form now raises a `RuntimeError` at construction naming the fix. Migration: move the members from `yield` statements in `run()` into `requires()` (or `@oryxflow.requires`) and leave `run()` empty — `class Agg(oryxflow.tasks.TaskAggregator): def run(self): yield T1(); yield T2()` becomes `class Agg(oryxflow.tasks.TaskAggregator): def requires(self): return [T1(), T2()]`. ## \[26.7.21\] - 2026-07-21 ### Security - Releases are now published to PyPI via GitHub Actions **Trusted Publishing** (OIDC) instead of a stored API token, and every uploaded file carries a PyPI-recorded **attestation** (PEP 740 / Sigstore) proving it was built from this repository by CI. Verify on the PyPI file detail page for this release. No install-side change — `pip install oryxflow` is unaffected. ## \[26.7.12\] - 2026-07-12 ### Added - Automatic code invalidation, on by default (`settings.code_version_auto = True`): every task derives its code identity from the AST hash of its own class plus the project-local symbols it transitively references (`codehash.task_hashes`, `'<relpath>::<symbol>'` granularity), so a real logic edit (in the task **or a helper it calls**) reruns the task and everything downstream on the next `run()`, overwriting in place — while editing an unrelated sibling task in the same file reruns nothing (one monolithic `tasks.py` stays cheap). References to other Task classes are dependency wiring, never a code dependency (a pinned upstream's unbumped edit can't ripple through `requires()` mentions); unresolvable constructs degrade conservatively to whole-module granularity. No attribute to maintain, and comment/docstring/formatting edits never rerun (AST normalization). Existing caches are grandfathered on first contact (baseline stamped, zero reruns). Set `settings.code_version_auto = False` for explicit-only tracking. The functional API is covered automatically (auto is ambient, no per-task surface). Records live in `<dirpath>/.oryxflow-code-status.json` and travel with the data dir. - `Task.code_version` (str or int, default `None`): a per-task **pin** that suspends automatic tracking of that task's own logic — it recomputes only on a deliberate bump (the task and everything downstream), for expensive tasks where a refactor-triggered recompute must be a decision, or logic the hash can't see. Records are mode-aware (they store both the token and the `source_hashes` as of the last materialization), and the `code_version` line itself is stripped by the AST normalization (typing it in / deleting / bumping it is a token change, never a source change), so pinning/unpinning unchanged code never recomputes ("just resumes"), an edit masked during a pinned-unbumped window is caught the moment the pin comes off, and pinning in the same edit as a logic change forces a rerun instead of blessing stale output. - Dependency propagation folds **output identity** (`output_id`, fresh per actual materialization, preserved across re-stamps and `accept_code`): downstream reruns exactly when an upstream rematerialized — pin toggles and accepts never ripple, and a `reset()`+rerun upstream propagates downstream even across separate builds. - Staleness advisory for pinned tasks: code changed without a bump → cached output is reused and the run warns via `StalenessWarning` (a `UserWarning` subclass, visible without `enable_logging()`), a loguru record, a `code_warning` event, and `RunResult.warnings`. The printed/logged channels dedupe per process on the message — parameterized instances of one family produce identical text, and a `WorkflowMulti` run is one build per flow over shared upstreams, so per-task dedupe would still flood stdout — re-arming when the condition changes or the affected tasks rerun/are accepted; `RunResult.warnings` lists each distinct message once per run (`MultiRunResult.warnings` dedupes across flows), and only the event stream records every occurrence. - `oryxflow.accept_code(task)` / `accept_code()`: acknowledge an output-equivalent code change without rerunning. With a task instance it re-stamps the task **and its entire upstream dep tree** (post-order), stamping a fresh baseline record for outputs that have none yet (this is what clears the `output predates current code` mtime-guard warning after an upgrade); `Workflow.accept_code(task=None)` / `WorkflowMulti.accept_code(task=None, flow=None)` wrap it; called bare they cover **every imported task family that resolves with the flow's parameters** (a multi-final pipeline is fully blessed in one call, from a fresh process — no prior run needed), and a list of tasks is accepted everywhere (on `WorkflowMulti` prefer the flow method — the module-level bulk form doesn't know the flows' parameters). Prints a one-line summary of what it re-stamped (or that nothing was accepted). The tree walk is fault-isolated: a task whose `requires()`/ `output()` raises is skipped and reported instead of aborting the walk (a broken `requires()` also can't poison the node's own blessing). Never touches `output_id`, so accepting never triggers downstream recomputes. - `TaskData.keep_versions` (default `False`): with `code_version` set, outputs live under a readable `.../<Task>/v<version>/` segment so old versions survive bumps (explicit pins only; auto-tracked tasks overwrite in place). - Expensive-recompute guard (`settings.code_version_auto_expensive_s`, default 600): an auto-tracked task whose last materialization (recorded as `duration_s`) took longer is held complete when its code changes and the run warns (`StalenessWarning`, all channels) with the three exits — `reset()` to recompute, `accept_code` if output-equivalent, or pin with `code_version` — so a refactor can't silently burn a long run. `None`/`0` disables the guard. - Records carry schema/interpreter tags (`state.RECORD_V`, `py`): a record with a different/missing `v` or Python minor is treated as unverifiable — complete, then silently re-stamped (grandfather trust level, `output_id` preserved) — never a mass rerun after an upgrade. - `build()` mtime-revalidates code hashes at most once per module per build (`codehash.freeze()`/`unfreeze()`), keeping the auto-hash overhead on small DAGs low. - Event stream `oryxflow.events`: every run appends `run_started` / `task_ran` / `task_failed` / `run_finished` / `code_warning` / `code_accepted` / `task_log` events to `.oryxflow/events.jsonl` (stable head; earlier months offload to `events-YYYYMM.jsonl`, immutable). Plain JSONL — `tail`/`grep`/`jq` work; writes are async and never fail a run; disable with `settings.events = False`. Query via `oryxflow.events.status()` (session-start: pending warnings, last run per family, recent failures), `events.runs(task_family=, flow=, last=)`, `events.iter_events()` — all return data and print nothing; `events.print_status()` prints the status summary (the session-start orientation call for scripts and `python -c`). - `RunResult.run_id`, `RunResult.reasons` (`{task_id: 'output missing' | 'code change (auto: <file>::<symbol>)' | 'code change (a -> b)' | 'upstream rerun'}`), `RunResult.warnings`. `MultiRunResult` gains aggregate `.ran`/`.complete`/`.failed`/`.reasons`/`.warnings` across flows. `task_ran` events carry params, code fingerprint, source hashes, `auto` flag, git SHA/dirty, duration and the rerun reason; `WorkflowMulti` stamps each per-flow build's events with its flow name. - Task-authored `self.logger.*(...)` lines are captured as `task_log` events during a build (works with logging disabled), so in-run scalars become queryable memory. - New settings: `settings.events`, `settings.eventspath`, `settings.state_filename`. ### Changed - `settings.db` (unused) renamed to `settings.state_filename` (the per-data-dir record file name, `.oryxflow-code-status.json`). ## \[26.7.11\] - 2026-07-11 ### Changed - Documentation rewrite and PyPI packaging updates; no API changes. ## \[26.6.6\] - 2026-06-06 ### Added - Initial release of `oryxflow`: the self-contained task engine (`Task`, `requires`/`inherits`, the parameter set, `Workflow`/`WorkflowMulti`, targets and task I/O formats), with no external workflow-engine dependency.