flexlock 0.8.2__tar.gz → 0.10.0__tar.gz

flexlock-0.10.0/.github/scripts/check_public_docs.py

@@ -0,0 +1,16 @@
+"""Refuse personal filesystem paths in public documentation and shipped skills."""
+import re
+from pathlib import Path
+root = Path(__file__).resolve().parents[2]
+paths = [root / "README.md", * (root / "docs").rglob("*.md"),
+         *(root / "docs").rglob("*.rst"), *(root / "flexlock/skills").rglob("*.md")]
+bad = []
+for path in paths:
+    if "_build" in path.parts:
+        continue
+    for number, line in enumerate(path.read_text().splitlines(), 1):
+        if re.search(r"/(?:ontap|scale|home|jobscratch)/", line):
+            bad.append(f"{path.relative_to(root)}:{number}")
+if bad:
+    raise SystemExit("Personal filesystem paths in public docs: " + ", ".join(bad))
+print("Public documentation path check passed")

flexlock-0.10.0/.github/scripts/check_version.py

@@ -0,0 +1,35 @@
+"""Check that the version declarations agree (and match the tag, if given).
+
+The wheel version comes from ``flexlock/__init__.py`` (hatch dynamic version);
+the conda package version from ``[tool.pixi.package] version`` in
+pyproject.toml. Usage: ``python .github/scripts/check_version.py [vX.Y.Z]``.
+"""
+
+import re
+import sys
+import tomllib
+from pathlib import Path
+
+root = Path(__file__).resolve().parents[2]
+init = (root / "flexlock" / "__init__.py").read_text()
+m = re.search(r'^__version__\s*=\s*"([^"]+)"', init, re.M)
+if not m:
+    sys.exit("could not find __version__ in flexlock/__init__.py")
+py_version = m.group(1)
+
+pixi_version = tomllib.loads((root / "pyproject.toml").read_text())["tool"]["pixi"]["package"]["version"]
+
+errors = []
+if py_version != pixi_version:
+    errors.append(
+        f"flexlock/__init__.py __version__={py_version!r} != "
+        f"[tool.pixi.package] version={pixi_version!r}"
+    )
+if len(sys.argv) > 1:
+    tag = sys.argv[1].removeprefix("refs/tags/")
+    if tag != f"v{py_version}":
+        errors.append(f"tag {tag!r} does not match package version v{py_version}")
+
+if errors:
+    sys.exit("\n".join(errors))
+print(f"version OK: {py_version}")

flexlock-0.10.0/.github/workflows/ci.yml

@@ -0,0 +1,66 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  tests:
+    name: tests (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0  # git_utils / snapshot tests inspect history
+
+      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        with:
+          python-version: ${{ matrix.python-version }}
+          activate-environment: true
+
+      - name: Install package and test deps
+        # Mirrors [tool.pixi.feature.test]; attrs is needed by test_utils.
+        run: uv pip install -e . "pytest>=8.3.2,<9" "pytest-mock>=3.14.0,<4" ipython attrs
+
+      - name: Git identity (tests create repos and commits)
+        run: |
+          git config --global user.name "flexlock-ci"
+          git config --global user.email "flexlock-ci@users.noreply.github.com"
+
+      - name: Run tests
+        run: pytest -q
+
+  build:
+    name: build sdist/wheel
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        with:
+          python-version: "3.11"
+
+      - name: Check version declarations agree
+        run: python .github/scripts/check_version.py
+
+      - run: uv build
+
+      - name: Wheel installs into a clean venv and imports
+        run: |
+          uv venv /tmp/wheelcheck
+          uv pip install --python /tmp/wheelcheck/bin/python dist/*.whl
+          cd /tmp && /tmp/wheelcheck/bin/python -c "import flexlock; print(flexlock.__version__)"
+          /tmp/wheelcheck/bin/flexlock --help > /dev/null

flexlock-0.10.0/.github/workflows/docs.yml

@@ -0,0 +1,58 @@
+name: Docs
+
+# Builds the Sphinx docs on every PR; deploys to GitHub Pages
+# (https://quentinf00.github.io/flexlock/) on pushes to main.
+# Requires Settings > Pages > Source = "GitHub Actions".
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pages-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        with:
+          python-version: "3.11"
+          activate-environment: true
+
+      - name: Install docs deps
+        # Mirrors [tool.pixi.feature.docs]; conf.py imports flexlock.
+        run: uv pip install . sphinx myst-parser sphinx-rtd-theme
+
+      - name: Check portable documentation
+        run: python .github/scripts/check_public_docs.py
+
+      - name: Build HTML
+        run: |
+          sphinx-build -b html docs docs/_build/html
+          touch docs/_build/html/.nojekyll
+
+      - uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
+        with:
+          path: docs/_build/html
+
+  deploy:
+    if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1

flexlock-0.10.0/.github/workflows/release.yml

@@ -0,0 +1,93 @@
+name: Release
+
+# Push a tag vX.Y.Z (matching flexlock/__init__.py and [tool.pixi.package]
+# version) to build and publish the PyPI and conda packages.
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build-dist:
+    name: build sdist/wheel
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        with:
+          python-version: "3.11"
+
+      - name: Tag matches package versions
+        run: python .github/scripts/check_version.py "${GITHUB_REF_NAME}"
+
+      - run: uv build
+
+      - name: Wheel installs into a clean venv and imports
+        run: |
+          uv venv /tmp/wheelcheck
+          uv pip install --python /tmp/wheelcheck/bin/python dist/*.whl
+          cd /tmp && /tmp/wheelcheck/bin/python -c "import flexlock; print(flexlock.__version__)"
+
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  publish-pypi:
+    # Enable this repository variable after configuring the corresponding
+    # trusted publisher on PyPI. Local twine publishing works independently.
+    if: vars.PYPI_TRUSTED_PUBLISHING == 'true'
+    name: publish to PyPI (trusted publishing)
+    needs: build-dist
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/flexlock
+    permissions:
+      id-token: write  # OIDC token for PyPI trusted publishing; no stored secret
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+
+  conda:
+    name: build + upload conda package (anaconda.org/quentinf00)
+    runs-on: ubuntu-latest
+    env:
+      ANACONDA_API_TOKEN: ${{ secrets.ANACONDA_API_TOKEN }}
+    environment:
+      name: anaconda
+      url: https://anaconda.org/quentinf00/flexlock
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Tag matches package versions
+        run: python3 .github/scripts/check_version.py "${GITHUB_REF_NAME}"
+
+      - uses: prefix-dev/setup-pixi@d3f436a425481402e6a95a1d1fc10331c708cd9e # v0.10.2
+        with:
+          pixi-version: v0.73.0
+          run-install: false
+
+      - name: Build conda package ([tool.pixi.package], pixi-build-python)
+        run: pixi build --output-dir conda-out
+
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: conda-package
+          path: conda-out/*.conda
+          if-no-files-found: error
+
+      - name: Upload to anaconda.org
+        if: env.ANACONDA_API_TOKEN != ''
+        run: |
+          pixi exec --spec "anaconda-client>=1.14,<1.16" -- \
+            binstar -s api.anaconda.org -t "$ANACONDA_API_TOKEN" \
+            upload --user quentinf00 --label main conda-out/*.conda

{flexlock-0.8.2 → flexlock-0.10.0}/.gitignore

@@ -14,3 +14,6 @@ doc/_build
 docs/_build
 docs/_build
 outputs
+
+# Isolated scheduler acceptance runtime artifacts
+acceptance-runs/

flexlock-0.10.0/CHANGELOG.md

@@ -0,0 +1,78 @@
+# 0.10.0
+
+- Retire automatic cross-run cache search, marker-based partial-stage resume and
+  chained fanout; retain explicit producer selection, named sweeps and ordered stages.
+- Record invocation source scopes separately from shared source capture.
+- Preserve authoritative result records, pre-submission ownership guards, scheduler
+  dependencies and matching-worker queue continuation.
+- Publish portable workflow recipes and align shipped agent skills with explicit
+  producer selection and fresh-attempt recovery.
+
+# Changelog
+
+## 0.10.0rc1 (local candidate, 2026-10-16)
+
+- Remove automatic cross-run cache search, submission cache keywords and CLI
+  `--check-exists`, `Project.exists/get_result`, and chained fanout APIs.
+- Reject old marker-based stage-resume payloads and worker-time unpinned run
+  selectors under scheduler dependencies. Keep explicit future producer bindings.
+- Preserve exact-path reuse, authoritative output validation, recorded queue
+  continuation, ordered stages and provenance comparison. Tighten queue ownership
+  checks so foreign queues and changed payloads cannot bypass destination guards.
+- Include the unreleased source-attribution and project-feedback fixes described
+  in [candidate migration notes](release_0_10.md).
+
+This is an isolated validation candidate; no project environment upgrade or
+scientific rerun is implied.
+
+## 0.9.0 (2026-10-02)
+
+### Added
+- Composite pipelines across sweeps, local/HPC workers, and enqueue/dequeue.
+- Full per-stage run records in directories or the task DB, including upstream
+  references, code provenance, and code-drift detection.
+- Environment lockfiles in run fingerprints.
+- Preset tracking and `flexlock runs` / `flexlock presets`.
+- `${run:...}` references to completed preset runs and `key=@name` config swaps.
+
+### Fixed
+- Composite task snapshots retain every executed stage instead of overwriting
+  earlier stage records. Exports include each stage's inherited code and environment.
+
+### Release infrastructure
+- CI on Python 3.11–3.13, wheel/sdist checks, tag-driven PyPI and conda publishing,
+  and GitHub Pages documentation.
+
+The unreleased 0.8.3 fixes below are included in this release.
+
+## 0.8.3 (unreleased)
+
+### Fixed
+- **Single HPC / `isolated=True` runs now get a full `run.lock`.** They used to
+  keep the submit-time placeholder (`config` = `save_dir` + `_snapshot_` only)
+  because the worker stored the real snapshot only in `run.lock.tasks.db`. That
+  broke `${run_lock:...}` (`KeyError`), made `flexlock-run -c run.lock` a
+  silent no-op, showed empty configs in `show`/`diff`/`ls`, linked no commits
+  on `tag`, and let `gc` delete the upstreams of a tagged run. The worker now
+  writes the full snapshot (config, fingerprint, git state, `note`) atomically
+  when its task owns the master dir. Sweep roots keep their placeholder.
+- Readers (`${run_lock:...}`, `show`/`graph`/`why`/`report`, `flexlock-diff`,
+  `ls`/`gc`/`tag`, `load_stage`, lineage, `flexlock-run -c run.lock`) fall back
+  to the task-DB snapshot for placeholder `run.lock`s written by older versions.
+- The worker refreshes `run.lock.tasks` when its queue drains, so it is no
+  longer left at `[]` after a `wait=False` submit.
+- `force=True` on a single HPC / isolated submission deleted `run.complete` but
+  ran nothing: the old `done` row in the task DB was kept by `INSERT OR IGNORE`.
+  The task DB is now reset and the task re-executes. The reset also drops the
+  cached sqlite connection, which kept writing to the deleted DB file.
+- Slurm backend: forkserver compatibility fix.
+- `docs/hpc_integration.md`: the task DB lives inside `save_dir`, not in its
+  parent. The overview section, clobbered by an earlier edit, is restored.
+
+### Added
+- `flexlock.run_record.load_lock_data(run_dir)`: side-effect-free effective
+  `run.lock` (placeholder → task-DB snapshot).
+- `flexlock.run_record.materialize_lock(run_dir)`: one-off rewrite of a
+  placeholder `run.lock` (keeps `run.lock.placeholder.bak`).
+- `flexlock repair-locks <root> [-n]`: runs `materialize_lock` over a results tree.
+- `flexlock.taskdb.reset_db(db_path)`.

flexlock-0.10.0/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.5
+Name: flexlock
+Version: 0.10.0
+Summary: A lightweight and painless SciOps library
+Author-email: Quentin Febvre <quentin.febvre@gmail.com>
+License-Expression: MIT
+Requires-Python: >=3.11
+Requires-Dist: cloudpickle<4,>=3.0.0
+Requires-Dist: gitpython<4,>=3.1.46
+Requires-Dist: joblib<2,>=1.5.2
+Requires-Dist: loguru<0.8,>=0.7.3
+Requires-Dist: omegaconf<3,>=2.3.0
+Requires-Dist: xxhash<4,>=3.5.0
+Description-Content-Type: text/markdown
+
+# FlexLock
+
+Python configuration and run provenance for research and offline data processing.
+
+[Documentation](https://quentinf00.github.io/flexlock/) · MIT licensed
+
+FlexLock lets you write a config in Python, select and override it from the CLI,
+and execute locally or through cluster workers. Run records capture configuration,
+declared source/data dependencies, upstream producers, outputs and return values.
+
+The **0.10.0 release** removes automatic cross-run cache search and partial-stage
+resume policy. See [breaking changes](docs/release_0_10.md).
+
+## Configuration and execution
+
+```python
+# cfgmod.py
+from flexlock import py2cfg
+from myproject.stages import prepare, train
+
+cfg = dict(
+    runs_root='/shared/project/runs',
+    track='intensity', arm='baseline', run='20261016-seed3',
+    run_dir='${runs_root}/${track}/${arm}/${run}',
+    upstream_run='/shared/project/runs/preparation/base/20261001/prepare',
+    main=py2cfg(train,
+        save_dir='${run_dir}/train',
+        input_path='${run_lock:${upstream_run},config.output_path}',
+        checkpoint_path='${run_dir}/train/model.pt',
+        _snapshot_=dict(data=dict(dataset='${...input_path}')),
+        _outputs_=dict(model=dict(path='model.pt', sha256=True))),
+)
+```
+
+```bash
+flexlock-run -d cfgmod.cfg -s main -o upstream_run=/shared/runs/other/prepare
+flexlock-run -d cfgmod.cfg -s main --sweep-file configs/smoke.yaml --n_jobs 2
+flexlock-run -d cfgmod.cfg -s main --slurm-config configs/slurm_gpu.yaml
+```
+
+Choose fresh destinations for independent runs. Occupied run directories raise
+before scheduler submission; active ownership also prevents forced overwrites.
+Use the [workflow recipes](docs/workflow_guidelines.md) for named sweeps, per-item
+destinations and explicit producer selection.
+
+Python submission uses the same execution kernel:
+
+```python
+from flexlock import Project
+
+project = Project('cfgmod.cfg')
+result = project.submit('main')
+result.raise_on_failure()
+print(result.save_dir, result.result)
+```
+
+## Provenance and explicit reuse
+
+Source snapshots describe the declared repository scope, including include/exclude
+patterns. Data hashes and upstream bindings record what the callable consumed.
+Comparison tools provide evidence for deciding whether preparation remains acceptable
+after a code change; FlexLock does not choose that scientific policy.
+
+```bash
+flexlock-diff /shared/runs/producer_a /shared/runs/producer_b
+```
+
+Consumers bind concrete producer paths with `run_lock`. FlexLock resolves and records
+the selected producer accurately and rejects identity changes at consumption time.
+It does not silently substitute a newer producer.
+
+```python
+selected = project.submit(cfg, save_dir_policy='skip')
+```
+
+`skip` reuses exactly the selected complete destination after authoritative-record
+and declared-output validation. It returns the producer's recorded config. It does
+not certify equivalence to a new config or current source. `force=True` intentionally
+reruns in place and records the new attempt while keeping products in place.
+
+## Sweeps and ordered stages
+
+Sweep files keep large cohorts out of comma-separated CLI arguments. Workers claim
+tasks from a shared SQLite queue, allowing many items with a bounded worker allocation.
+Project coverage checks distinguish successful processing, valid empty outcomes,
+exclusions, missing products and failures.
+
+CLI `-s prepare train assess` executes selected stages in order on one allocation,
+with distinct provenance and fail-fast execution. Independent pipeline items can run
+in parallel. Stages needing different resources use separate scheduler jobs and
+`--after`, with concrete future producer paths and an accepted-ID ledger.
+
+An unchanged recorded queue can continue pending work without rerunning done rows.
+For a partially completed pipeline, explicitly select remaining stages, bind retained
+producers and use fresh destinations. There is no automatic marker-based stage skip.
+
+## Further reading
+
+- [Workflow guidelines and five executable recipes](docs/workflow_guidelines.md)
+- [Python API](docs/python_api.md) and [CLI reference](docs/cli_reference.md)
+- [Source attribution](docs/source_attribution.md) and [HPC integration](docs/hpc_integration.md)
+- [Slim-core design](docs/philosophy.md) and [migration notes](docs/release_0_10.md)
+
+Install this release with `pip install flexlock==0.10.0` or from the
+`quentinf00` Conda channel. See the migration notes before upgrading existing callers.

flexlock-0.10.0/README.md

@@ -0,0 +1,105 @@
+# FlexLock
+
+Python configuration and run provenance for research and offline data processing.
+
+[Documentation](https://quentinf00.github.io/flexlock/) · MIT licensed
+
+FlexLock lets you write a config in Python, select and override it from the CLI,
+and execute locally or through cluster workers. Run records capture configuration,
+declared source/data dependencies, upstream producers, outputs and return values.
+
+The **0.10.0 release** removes automatic cross-run cache search and partial-stage
+resume policy. See [breaking changes](docs/release_0_10.md).
+
+## Configuration and execution
+
+```python
+# cfgmod.py
+from flexlock import py2cfg
+from myproject.stages import prepare, train
+
+cfg = dict(
+    runs_root='/shared/project/runs',
+    track='intensity', arm='baseline', run='20261016-seed3',
+    run_dir='${runs_root}/${track}/${arm}/${run}',
+    upstream_run='/shared/project/runs/preparation/base/20261001/prepare',
+    main=py2cfg(train,
+        save_dir='${run_dir}/train',
+        input_path='${run_lock:${upstream_run},config.output_path}',
+        checkpoint_path='${run_dir}/train/model.pt',
+        _snapshot_=dict(data=dict(dataset='${...input_path}')),
+        _outputs_=dict(model=dict(path='model.pt', sha256=True))),
+)
+```
+
+```bash
+flexlock-run -d cfgmod.cfg -s main -o upstream_run=/shared/runs/other/prepare
+flexlock-run -d cfgmod.cfg -s main --sweep-file configs/smoke.yaml --n_jobs 2
+flexlock-run -d cfgmod.cfg -s main --slurm-config configs/slurm_gpu.yaml
+```
+
+Choose fresh destinations for independent runs. Occupied run directories raise
+before scheduler submission; active ownership also prevents forced overwrites.
+Use the [workflow recipes](docs/workflow_guidelines.md) for named sweeps, per-item
+destinations and explicit producer selection.
+
+Python submission uses the same execution kernel:
+
+```python
+from flexlock import Project
+
+project = Project('cfgmod.cfg')
+result = project.submit('main')
+result.raise_on_failure()
+print(result.save_dir, result.result)
+```
+
+## Provenance and explicit reuse
+
+Source snapshots describe the declared repository scope, including include/exclude
+patterns. Data hashes and upstream bindings record what the callable consumed.
+Comparison tools provide evidence for deciding whether preparation remains acceptable
+after a code change; FlexLock does not choose that scientific policy.
+
+```bash
+flexlock-diff /shared/runs/producer_a /shared/runs/producer_b
+```
+
+Consumers bind concrete producer paths with `run_lock`. FlexLock resolves and records
+the selected producer accurately and rejects identity changes at consumption time.
+It does not silently substitute a newer producer.
+
+```python
+selected = project.submit(cfg, save_dir_policy='skip')
+```
+
+`skip` reuses exactly the selected complete destination after authoritative-record
+and declared-output validation. It returns the producer's recorded config. It does
+not certify equivalence to a new config or current source. `force=True` intentionally
+reruns in place and records the new attempt while keeping products in place.
+
+## Sweeps and ordered stages
+
+Sweep files keep large cohorts out of comma-separated CLI arguments. Workers claim
+tasks from a shared SQLite queue, allowing many items with a bounded worker allocation.
+Project coverage checks distinguish successful processing, valid empty outcomes,
+exclusions, missing products and failures.
+
+CLI `-s prepare train assess` executes selected stages in order on one allocation,
+with distinct provenance and fail-fast execution. Independent pipeline items can run
+in parallel. Stages needing different resources use separate scheduler jobs and
+`--after`, with concrete future producer paths and an accepted-ID ledger.
+
+An unchanged recorded queue can continue pending work without rerunning done rows.
+For a partially completed pipeline, explicitly select remaining stages, bind retained
+producers and use fresh destinations. There is no automatic marker-based stage skip.
+
+## Further reading
+
+- [Workflow guidelines and five executable recipes](docs/workflow_guidelines.md)
+- [Python API](docs/python_api.md) and [CLI reference](docs/cli_reference.md)
+- [Source attribution](docs/source_attribution.md) and [HPC integration](docs/hpc_integration.md)
+- [Slim-core design](docs/philosophy.md) and [migration notes](docs/release_0_10.md)
+
+Install this release with `pip install flexlock==0.10.0` or from the
+`quentinf00` Conda channel. See the migration notes before upgrading existing callers.

{flexlock-0.8.2/.claude/worktrees/dedup-deps → flexlock-0.10.0}/docs/agentic_workflows.md

@@ -1,7 +1,7 @@
 # Agentic Workflows
 
 FlexLock already persists everything needed to reconstruct experiment history
-(`run.lock`, shadow git commits, data hashes, lineage, the fingerprint index, the
+(`run.lock`, shadow git commits, data hashes, lineage, the
 task DB, and tags as git refs). This page documents the **machine-readable query
 commands** that turn that on-disk state into a stable, agent-facing contract, the
 **shipped skills** that encode common workflows, and the **static HTML report**.
@@ -25,7 +25,7 @@ Every JSON payload is gated by a `schema_version` (currently `1`).
 
 ### `flexlock show --format json`
 
-```json
+```text
 {"schema_version":1, "path":"/abs", "kind":"run|sweep_master|sweep_task",
  "status":"complete|failed|interrupted|running|pending|unknown", "status_detail":null,
  "timestamp":"...", "note":null, "target":"myproject.train.train",
@@ -46,7 +46,7 @@ DB row; otherwise `run.complete` → `complete`, `run.error` → `failed`, `run.
 
 ### `flexlock graph --format json`
 
-```json
+```text
 {"schema_version":1, "root":"/abs", "generated_at":"...",
  "nodes":[{"id":"/abs/dir","label":"train","kind":"run","status":"complete",
            "timestamp":"...","note":null,"target":null,"fingerprint":null,"tag":null,
@@ -57,13 +57,13 @@ DB row; otherwise `run.complete` → `complete`, `run.error` → `failed`, `run.
 ```
 
 `id` is a resolved absolute path. `metrics` are the top-level numeric keys of
-`results.json`. Edges pointing outside the scanned tree materialise `kind:
+the authoritative return payload (including legacy `results.json`). Edges pointing outside the scanned tree materialise `kind:
 external` stub nodes so the graph is closed. `--groups` adds size-≥2 clusters of
 nodes sharing identical tree hashes / data dicts.
 
 ### `flexlock why --format json`
 
-```json
+```text
 {"schema_version":1,"run_a":"/a","run_b":"/b","match":false,
  "diffs":{"config":[...],"git":[...],"data":[...]},
  "commits":{"main":{"trees_identical":false,
@@ -89,16 +89,16 @@ query command. See [Reference › On-Disk Run Files](reference.md#on-disk-run-fi
 ## Failure records — `run.error`
 
 When a run's user function raises, FlexLock writes a `run.error` JSON sidecar next
-to `run.lock` (schema in the [Reference](reference.md#run-error-json-schema-v1)).
+to `run.lock` (schema in the [Reference](reference.md)).
 Triage a failure without touching sqlite:
 
 ```bash
 flexlock show <run_dir> --format json    # .error.exc_type / .error.traceback
 ```
 
-Classify by `exc_type`: user-code errors (fix + re-run with `--force`) vs.
-node/infra faults (CUDA `cudaErrorSystemNotReady`, OOM — retry elsewhere). A
-successful re-run clears the stale `run.error`.
+Inspect error and worker ownership before retrying. Code/config/data changes get
+a fresh attempt with explicit retained inputs. In-place force deliberately replaces
+prior provenance; it is not the default recovery.
 
 ## Shipped skills
 

{flexlock-0.8.2/.claude/worktrees/dedup-deps → flexlock-0.10.0}/docs/api.rst

@@ -111,6 +111,11 @@ FlexLock API Reference
    :undoc-members:
    :show-inheritance:
 
+.. automodule:: flexlock.run_record
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 .. automodule:: flexlock.taskdb
    :members:
    :undoc-members:

flexlock-0.10.0/docs/changelog.md

@@ -0,0 +1,2 @@
+```{include} ../CHANGELOG.md
+```