Ocura OSS 0.8.0

This release renames stored state and cannot read ledgers written by earlier versions.

• Use the names ledger, run, and branch point in stored state and JSON output, as
  0.7 did in Python. State is now ledger.json, runs/, and branch-points/; IDs
  start with ledger-, run-, and branch-point-, and logs are named for the run
  ID. JSON keys are ledger_id, run_id, branch_point_id, and
  source_branch_point_id, and verify --json counts runs and branch_points.
  Records carry schema version 3.
• Refuse state written by 0.5 to 0.7 (schema 2) with exit status 2 and a message
  to keep using ocura-oss<0.8 for it or start a new ledger. The old directory is
  not modified, and there is no conversion.
• Remove the names 0.7 kept for compatibility: Den, Atom, Chokepoint, their
  attributes, fields, and keyword arguments, load_atom() and the other old
  Store methods, the chokepoints command, and the --atom option.
  docs/naming-migration.md maps each one to its replacement.

Ocura OSS 0.7.2

• On Python 3.11 and 3.12, record a stop request that arrives between polls of the
  command as an interrupted run. It could instead end run with a traceback, leaving
  the attempt for recover and, on macOS, the command still running.

Ocura OSS 0.7.1

This documentation release changes no code or record formats.

• Use full URLs for README links so they resolve on PyPI. The release check now
  reports relative links in a built package description.
• Show how to fetch the history inspector after installing from PyPI; the script
  is not in the distributions.
• Introduce opt-in log compression in the overview.
• Replace pre-release wording in the example guide that shipped in the 0.7.0 source
  distribution.

Ocura OSS 0.7.0

• Keep the demo and history inspection as the primary example in the core
  repository. Move the autoregressive demonstration and its backend tests to the
  semi-permanent examples/0.7 branch, alongside the CI-report and Dream examples.
  Link their setup and compatibility requirements from the use-case catalog.
• On Windows, verify no longer reports an unreadable attempt when a concurrent
  run finalizes while it reads; a read denied while the record still exists is
  retried briefly, and one denied throughout is still reported.
• Preserve both filenames and Windows error details when wrapping operating-system
  failures, and accept indexing-only command sequences supported by earlier callers.
• Add run --from BRANCH_POINT_ID --reason TEXT -- COMMAND and Python
  run(..., source_branch_point_id=ID, reason=TEXT) to create and execute a
  variation in one call. Parameters override the new child pathway's inherited
  labels; labels declared only on the source run are not copied. Existing run
  results, defaults, and the separate branch/run --pathway workflow remain unchanged. Input
  is checked before the child is created. A later storage or execution failure can
  leave the child in place; structured errors retain known child and source IDs for
  inspection and explicit continuation without automatic retries.
• Record a stop request arriving between process-polling timeouts as an interrupted
  run, stopping the command and retaining its evidence through the existing result
  interface.
• Add canonical public names Ledger, RunRecord, and BranchPoint; retain
  Pathway and the legacy Den, Atom, and Chokepoint class aliases. Add
  descriptive result properties, Store readers, source keywords, and the
  branch-points CLI alias and --run storage selector. Existing constructor
  fields, success JSON, schema-2 records, IDs, checksums, and retained manifests
  remain compatible.
• Add opt-in --json-errors for JSON results and structured failures, including
  argument errors, stable error categories, known run IDs, execution state, and
  recovery guidance. Existing --json behavior and exit statuses remain unchanged.
  logs still prints log bytes. Python StoreError exposes diagnostic fields too;
  run() errors that were ValidationError or OSError still are. A failure after launch directs
  callers to inspect retained attempts and runs before considering resubmission.
• Add an executable history inspection example for a fresh caller with only a
  ledger root. It includes failed retries, empty variations, unfinished attempts,
  and verified bounded log excerpts with original-content references. It never
  executes or recovers a workload. Update terminology and migration guidance.
• Fixed: validating a pathway no longer doubles its work for every branch
  generation. A history built by branching each run from the previous one made
  run, branch, compare, and verify take seconds after about ten generations
  and far longer after that. Each record is now validated once per operation.
• ocura-oss --version prints the installed version.
• pathways and compare read the atom records once per command, instead of
  once for every pathway or child pathway.
• Add ocura-oss runs and Store.list_runs(): finalized runs ordered by terminal
  record timestamp and ID, including failed retries, each with the chokepoint_id
  to branch from.
  Filter by pathway or outcome, page with --limit and --after, or list every
  match with --all. Each page counts the runs still unfinished, which can finish
  behind its cursor; a walk whose pages count none lists every finished run.
• Add ocura-oss show and Store.inspect_run(): one run with its pathway, terminal
  chokepoint, and the pathways branched from it. Command arguments are included
  only with --command. Neither command reads log contents.
• Add --archive to the commands that only read, and Store(root, archive=True),
  to read a stable copy of a ledger without creating lock files. Archive mode
  refuses every change, and refuses a ledger with unfinished attempts, saying how
  to list and recover them.
• Add ocura-oss logs, Store.open_verified_log(), and Store.log_info(): a
  run's verified original log bytes, --offset/--length excerpts, and storage
  metadata with --info or --json.
• Add opt-in lossless log compression. run --compress (or --compress-min-bytes N)
  stores a run's captured logs of at least 1 MiB as gzip once it finishes, when that
  saves at least 10%; compress and decompress convert finalized logs, and
  --dry-run previews either. Logs stay raw by default. Records, IDs, digests, and
  retained manifests do not change, and every reader returns the original bytes.
  run and show print each log's current file, reported as log_files in JSON
  and by Store.log_files(), so standard gzip tools can open compressed logs.
  Ocura OSS 0.6 cannot read compressed logs: run decompress and verify before
  opening the ledger with it.
• Keep completed run results available when optional compression or log-path
  reporting fails. Interrupted compression reports a storage warning and leaves
  finalized evidence intact. Refused locks fail promptly for writes; verified
  reads can fall back to unlocked access where locks are unavailable.
• Support linked log directories when reporting storage paths, classify conversion
  failures by their underlying cause, and stop log output quietly when its reader
  closes the pipe.

Ocura OSS 0.6.0

• License: Ocura OSS is now released under the Apache License 2.0. Versions 0.5.0
  and earlier remain under MPL-2.0. Contributions are accepted under Apache-2.0.
• branch --from, compare --from, and run --pathway accept a shortened ID: at
  least four of its leading hexadecimal characters, with or without the kind word.
  The prefix must match exactly one record; an ambiguous one is rejected with the
  matches listed. Output and records still carry full IDs. Add Store.resolve_id().
  The Python workflow functions still take full IDs.
• Changed: a run now records its pathway's effective parameters together with
  its own, so a run on a branch no longer repeats the branch's --param values. A
  parameter declared on the run replaces the pathway's value for the same key. Before
  this release a run recorded only what it declared, plus any pathway parameter that
  --substitute used. compare therefore reports a child run's inherited labels
  under run_parameters where it previously reported none. Atoms already recorded
  are not changed.
• A command run where there is no state now names ocura-oss init in its error.
  When a directory above the root holds state, the error names that directory
  instead. State is never created implicitly.
• ocura-oss run now handles SIGTERM, SIGHUP, and Ctrl+Break on Windows as it
  handles the first Ctrl+C: the command is stopped and the run is recorded as
  interrupted with exit status 1. Before this release those requests ended the
  recorder, left an abandoned attempt, and left the command running. A signal the
  caller ignores, as under nohup, stays ignored. The Python run() function
  installs no signal handlers.
• Changed: a command no longer outlives a killed recorder on Windows or Linux.
  On Windows the operating system ends the command and the processes it started,
  and an interrupted run now ends those processes too. On Linux the kernel kills
  the command itself. On macOS the command still keeps running. A command that
  finishes on its own is not affected. See "When the recorder stops" in
  docs/state-and-verification.md.
• Documentation: the README and overview show what compare prints, say when a
  different tool is the better choice, and state how to remove the package's data.
• Add an optional, standalone tool to copy complete 0.4 ledgers into schema 2.
  It verifies the source, preserves IDs and log bytes, and writes a separate copy
  with a migration receipt. Download it from tools/migrations/; it is excluded
  from both the wheel and source distribution and adds no runtime dependencies.

Ocura OSS 0.5.0

• Breaking: change the record format to schema version 2. State written by 0.4 and
  earlier is rejected with exit status 2 and left untouched; there is no migration. To
  keep using existing records, stay on 0.4 for that project (ocura-oss<0.5). To record
  with 0.5, move the old .ocura-oss/ aside and run ocura-oss init. See "Upgrading
  from 0.4" in docs/state-and-verification.md. Atom log fields, finished_at, and duration_seconds
  may now be None, and RunSummary.duration_seconds may be None.
• Journal each run under .ocura-oss/attempts/ before its command launches. An attempt
  whose recording process is interrupted twice or killed stays visible instead of leaving
  orphaned logs. Add ocura-oss attempts and Store.list_attempts() to list unfinished
  attempts as running or abandoned.
• Add ocura-oss recover, recover(), and Store.recover() to close abandoned attempts.
  One with no recorded outcome becomes an atom with the new abandoned outcome: its
  captured output is retained, and no finish time, duration, or return code is invented.
• Support several processes recording runs under one state root at once. verify and
  compare work while runs are in flight and report them as running rather than as damage.
  Of several concurrent init calls, exactly one succeeds.
• Report an atom that does not have exactly one chokepoint as a verification problem.
• Add run --no-capture and run(capture=False) to retain no stdout or stderr. The atom
  records output_capture: none instead of log paths.
• Add run --mask-arg POSITION and run(masked_arguments=[...]) to store a placeholder for
  chosen command tokens while the command still receives the real values.
• Add run --substitute and run(substitute=True) to replace {KEY} in command tokens
  with declared or pathway parameter values and record every parameter used, so one
  declaration both labels and configures a run.
• Add opt-in launch context: run --context records the platform and the git revision and
  dirty state, and run --context-file PATH records a file's size and SHA-256. Nothing is
  queried, executed, or read for context unless requested.
• Add ocura-oss manifest, verify --against FILE, and verify(against=...). A manifest
  kept outside the state detects records later rewritten together with their checksums.
  verify also reports a digest of the manifest.
• State how the format evolves: readers ignore payload fields they do not recognize, so a
  schema version can gain optional fields without another break.
• Publish releases from GitHub Actions through PyPI Trusted Publishing.
• Keep the core runtime dependency-free.

Ocura OSS 0.4.0

Ocura OSS 0.4.0 adds Store.read_verified_log(), so scripts and agents can consume recorded stdout or stderr as bytes checked against the stored run's byte count and SHA-256 digest. The autoregressive example's report now uses this method to read saved output.

The method validates the stored atom and its lineage, checks log path containment, and verifies the exact bytes it returns. It checks the selected stream; use verify() or Store.verify_state() to verify the full ledger. Decoding and metric interpretation remain with the caller.

Install the published release with Python 3.11 or later:

python -m pip install ocura-oss==0.4.0

The core continues to use only Python's standard library at runtime. The autoregressive example and its optional framework dependencies remain repository-only.

Validation for this release publication: the published wheel and source distribution passed SHA-256 checks against PyPI metadata, and all nine Python source modules in each distribution match the v0.4.0 tag at 240843038a744b906ed6dffa8836dd827ea50691.

PyPI release · Changelog · Python API

Ocura OSS 0.3.0

Ocura OSS 0.3.0 adds init --json and run --json, so scripts and AI agents can record a baseline, branch, rerun, verify, and compare using returned identifiers throughout. Command output stays in its recorded logs while stdout contains one JSON result; existing exit codes and text output remain available. JSON also handles Unicode paths on legacy Windows encodings.

The source repository includes a small autoregressive example with PyTorch and JAX backends and an optional local Ray Core executor. It records two training runs and reconstructs their comparison from verified logs. Examples and framework requirements are excluded from both package distributions; the core remains dependency-free with the existing storage format.

See the CLI reference, automation guide, and autoregressive example.

Validation: all 126 packaged tests passed from fresh wheel and source-distribution installations on Windows with Python 3.12/3.14 and Linux under WSL with Python 3.12. All four example combinations passed with a fresh Windows CPU installation of PyTorch 2.14.0, JAX 0.11.1, and Ray 2.58.0. Build, Twine, lint, formatting, and type checks passed.