tallylock 0.1.0a1__tar.gz

tallylock-0.1.0a1/.github/workflows/ci.yml

@@ -0,0 +1,88 @@
+name: CI
+
+on: [push, pull_request, workflow_dispatch]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test-and-distribute:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 20
+    strategy:
+      fail-fast: false
+      max-parallel: 2
+      matrix:
+        python-version: ['3.11', '3.12', '3.13']
+    env:
+      PIP_NO_INPUT: '1'
+      PIP_DISABLE_PIP_VERSION_CHECK: '1'
+      PIP_DEFAULT_TIMEOUT: '30'
+      PIP_RETRIES: '2'
+    steps:
+      - name: Check out source
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install contributor dependencies
+        shell: bash
+        run: |
+          for attempt in 1 2 3; do
+            if python -m pip install 'setuptools>=77' wheel '.[dev]'; then
+              break
+            fi
+            if (( attempt == 3 )); then
+              exit 1
+            fi
+            sleep "$(( attempt * 5 ))"
+          done
+          python -m pip check
+
+      - name: Run full test suite
+        run: python -m pytest
+
+      - name: Audit and check clean installs
+        shell: bash
+        run: |
+          set -euo pipefail
+          dist_dir="$(mktemp -d "$RUNNER_TEMP/tallylock-dist.XXXXXX")"
+          wheel_env="$(mktemp -d "$RUNNER_TEMP/tallylock-wheel.XXXXXX")"
+          source_env="$(mktemp -d "$RUNNER_TEMP/tallylock-source.XXXXXX")"
+          expected_version="$(python -c 'import tomllib; from pathlib import Path; print(tomllib.loads(Path("pyproject.toml").read_text())["project"]["version"])')"
+
+          pip_install() {
+            local python_bin="$1"
+            shift
+            for attempt in 1 2 3; do
+              if "$python_bin" -m pip install "$@"; then
+                return 0
+              fi
+              if (( attempt == 3 )); then
+                return 1
+              fi
+              sleep "$(( attempt * 5 ))"
+            done
+          }
+
+          python -m build --no-isolation --outdir "$dist_dir" .
+          python tools/check_distribution.py --dist "$dist_dir" --source-root .
+
+          python -m venv "$wheel_env"
+          pip_install "$wheel_env/bin/python" "$dist_dir"/*.whl
+          "$wheel_env/bin/python" -m pip check
+          python tools/check_install.py --python "$wheel_env/bin/python" --expected-version "$expected_version"
+
+          python -m venv "$source_env"
+          pip_install "$source_env/bin/python" "$dist_dir"/*.tar.gz
+          "$source_env/bin/python" -m pip check
+          python tools/check_install.py --python "$source_env/bin/python" --expected-version "$expected_version"

tallylock-0.1.0a1/.github/workflows/release.yml

@@ -0,0 +1,54 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions: {}
+
+jobs:
+  build:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+    permissions:
+      contents: read
+    steps:
+      - name: Check out source
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
+        with:
+          python-version: '3.12'
+
+      - name: Build distributions
+        run: |
+          python -m pip install "setuptools>=77" wheel "build>=1,<2"
+          python -m build --no-isolation
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    needs: build
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI with trusted publishing
+        uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3

tallylock-0.1.0a1/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

tallylock-0.1.0a1/MANIFEST.in

@@ -0,0 +1,21 @@
+include LICENSE NOTICE README.md RUNBOOK.md PLAN.md pyproject.toml
+
+# Public source inputs needed to rebuild, test, and audit an sdist.
+graft src/tallylock
+graft tests
+graft docs
+graft .github
+graft examples/basic
+graft conformance
+graft tools
+
+# Local planning, worker state, and generated files are never source inputs.
+prune .git
+prune .planning
+prune .superpowers
+prune .worker
+prune .venv
+prune build
+prune dist
+prune .pytest_cache
+global-exclude *.pyc *.pyo .DS_Store

tallylock-0.1.0a1/NOTICE

@@ -0,0 +1,7 @@
+TallyLock
+Copyright 2026 Christopher Ayers
+Developed by TriplePass Labs.
+
+TallyLock is licensed under Apache-2.0. Runtime dependencies are separate
+projects and retain their own licenses. Their observed versions, metadata,
+license files, and project links are listed in docs/DEPENDENCIES.md.

tallylock-0.1.0a1/PKG-INFO

@@ -0,0 +1,89 @@
+Metadata-Version: 2.4
+Name: tallylock
+Version: 0.1.0a1
+Summary: Standalone evaluation receipts with independently checkable artifact and timestamp evidence
+Author: Christopher Ayers
+License-Expression: Apache-2.0
+Project-URL: Repository, https://github.com/TriplePassLabs/tallylock
+Requires-Python: <3.14,>=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: rfc8785==0.1.4
+Requires-Dist: opentimestamps==0.5.0
+Requires-Dist: python-bitcoinlib==0.12.2
+Requires-Dist: jsonschema==4.26.0
+Provides-Extra: dev
+Requires-Dist: pytest<10,>=8; extra == "dev"
+Requires-Dist: build<2,>=1; extra == "dev"
+Dynamic: license-file
+
+# TallyLock
+
+TallyLock was named Prove until 2026-11-07. The command is `tallylock` and the package is `tallylock`. Protocol v1 wire identifiers keep their original `prove.` prefix (for example `prove.manifest.v1`), and receipts keep their `.prove/` state directory, so existing receipt IDs and anchored timestamps stay valid.
+
+TallyLock freezes evaluation plans and ordinary output files into standalone receipts. Its Python CLI verifies byte integrity offline and separates that evidence from reported scores, model identity and execution claims. Developed by [TriplePass Labs](https://github.com/TriplePassLabs). Created and maintained by [Christopher Ayers](https://github.com/BrianBoitano).
+
+[Lab website](https://triplepasslabs.com) · [GitHub organization](https://github.com/TriplePassLabs) · [Founder profile](https://github.com/BrianBoitano)
+
+It binds an evaluation plan, recorded artifacts and reported results to commitments with optional OpenTimestamps evidence. Verification distinguishes artifact integrity from claims about execution, model identity, timing and scientific validity.
+
+Version `0.1.0a1` is an unreleased implementation candidate for Linux with Python 3.11 through 3.13. Use a supported interpreter and install the reviewed wheel in its own environment. The example below selects Python 3.12; substitute your supported interpreter when needed.
+
+On Ubuntu or Debian, that interpreter needs its matching venv package before environment creation. Ubuntu 24.04 users selecting Python 3.12 need `python3.12-venv`. The [offline quickstart](docs/QUICKSTART.md) gives the prerequisite and an optional fallback when `uv` is already installed. See the [Ubuntu Python setup guide](https://ubuntu.com/developers/docs/howto/python-setup/) and [package record](https://packages.ubuntu.com/noble/python3.12-venv).
+
+```sh
+python3.12 -m venv .venv-tallylock
+. .venv-tallylock/bin/activate
+python -m pip install /absolute/path/to/tallylock-0.1.0a1-py3-none-any.whl
+tallylock --version
+```
+
+From a reviewed source checkout, `python -m pip install .` works in the same environment. Installation may fetch dependencies. No unpublished PyPI release is assumed.
+
+Future install path (after the first PyPI release): `pipx install tallylock`. It does not work yet, so use the reviewed wheel above for now. Distribution acceptance and release status are recorded in [the readiness audit](docs/READINESS.md).
+
+The [offline quickstart](docs/QUICKSTART.md) uses only the installed CLI, a fresh manifest and an ordinary output directory. It needs no model, provider account, research checkout or hosted service. `python -m tallylock` can replace `tallylock` in every command.
+
+```sh
+tallylock init --out manifest.json --name "My evaluation"
+tallylock pre-register manifest.json --receipt receipt
+mkdir outputs
+printf 'ordinary external output\n' > outputs/result.txt
+tallylock seal receipt --artifacts outputs
+tallylock verify receipt
+```
+
+Edit the manifest before preregistration. Run your external evaluation program yourself and pass its output directory to `seal`. TallyLock never launches a model or executes a scorer named in metadata. See [generic integration](docs/INTEGRATION.md) for explicit score/trace options, bounded reports and recovery.
+
+Anchoring is explicit: `tallylock anchor receipt`, then `tallylock upgrade receipt` as calendars gain attestations. Submission and pending proofs are not completed anchoring. Plain `tallylock verify receipt` checks integrity and reports the timestamp as not checked, exiting 0 when integrity passes. With `--chain-cache FILE` it also runs the anchored check. `--policy anchored` is the strict form: it requires qualifying Bitcoin attestations and an explicitly selected local chain cache, and exits 3 without them. Verification never contacts a node or calendar. Independently assess the cache's provenance and freshness.
+
+Output is one JSON object per stdout line when piped and a short plain-language summary on a terminal. Force either with `--json` or `--human` (not both). `tallylock doctor [RECEIPT]` checks the installation and a receipt's timestamp state without writing or using the network. Statuses are 0 for the requested action/check, 2 invalid input, 3 insufficient evidence, 4 unsupported evidence, 5 operational failure and 130 interruption. A returned timestamp action can still be pending or retry-wait. After optional anchoring fails, completed local state and IDs remain in the report. Resume with `anchor`/`upgrade` without the original outputs.
+
+Static examples and canonical conformance assets ship under `tallylock/data/examples/basic` and `tallylock/data/conformance`, accessible through `importlib.resources`. Basic use requires no optional harness importer.
+
+- [Project plan](PLAN.md): scope, protocol decisions, milestones and release gates.
+- [Threat model](docs/THREAT_MODEL.md): attacks, defenses and remaining trust.
+- [Acceptance tests](docs/ACCEPTANCE.md): tests required before implementation claims.
+- [Sources and alternatives](docs/SOURCES.md): primary references and reuse decisions.
+- [Review log](docs/reviews/REVIEW_LOG.md): critiques and their disposition.
+- [Proposed flagship roadmap](docs/roadmap/README.md): setup choices, AI instructions and twenty staged features. Design for review; proposed commands are not implemented.
+
+## License
+
+Licensed under [Apache-2.0](LICENSE). Copyright 2026 Christopher Ayers.
+
+## Record every run
+
+```sh
+tallylock run --repeat 5 -- python eval.py --seed {seed}
+tallylock score
+```
+
+Every attempt is recorded, including failures. `score` reports the best result, the real score with its range, and a claim line others can check with `tallylock check`. See [the quickstart](docs/QUICKSTART.md#record-every-run-and-get-the-real-score) and [the method](docs/METHODS.md).
+
+## What a receipt means
+
+A valid completed timestamp establishes that a commitment existed by a Bitcoin block. Artifact hashes reveal changes to committed bytes. Neither establishes that an evaluator ran honestly, used the claimed model, disclosed all attempts, or produced a scientifically sound result.
+
+TallyLock works alongside evaluation harnesses. A preregistration ID alone establishes no independently witnessed chronology. External research experiments remain separate from the protocol's cryptographic checks.

tallylock-0.1.0a1/PLAN.md

@@ -0,0 +1,131 @@
+# TallyLock project plan
+
+Revision 5, 2026-11-06. Chris authorized implementation through a standalone CLI candidate ready for external research-session testing, with adversarial critique and documented feedback. Implementation begins from the reviewed plan. This revision replaces earlier approval holds for that scope.
+
+## Standalone product requirement
+
+Chris clarified on 2026-11-06: TallyLock is an independent, general-purpose, easily installable CLI. Colony Zero and Ouroboros are external consumers used for acceptance testing. The shipped package, core manifest and receipt formats, generic workflow, verifier and quickstart must have no dependency on those repositories, their naming, internal paths, schemas, services or hardware. A clean user must be able to install a built wheel with pip or pipx and complete the documented generic example without a research-project checkout, private credentials or a TriplePass Labs service. Public PyPI publication remains a later release step; the candidate must be installable from its versioned wheel and source distribution now.
+
+Generic manifests, artifact ingestion and data-only verification are the primary interfaces. Harness-specific import adapters are optional conveniences; they cannot be required by the core package or the primary installation path. Colony/Ouroboros integration belongs in external instructions and examples, never in project-specific core behavior. Keep the first public-facing quickstart domain-neutral. The testing handoff asks a separate research session to use the installed CLI as an ordinary external user and document friction, defects and missing general capabilities.
+
+## Goal and product decision
+
+Make one real evaluation auditable without requiring its author to remain online or requiring trust in TriplePass Labs. Publish a portable receipt connecting a frozen plan, preserved execution artifacts and declared results to independent timestamp evidence. A verifier must explain exactly what it checked and what remains an assertion.
+
+The narrow product is an evidence layer for existing harnesses. The first milestone does not include a production inference runner, generic agent framework, dashboard, transparency service, signatures, trusted execution, custom Bitcoin consensus implementation, or paid evaluation sweep.
+
+The useful distinction from hashing a log is the explicit binding of plan, artifacts, ordered records, final outcome and verification policy, with interoperable timestamp proofs and honest evidence reporting. Novelty and market demand are hypotheses, not established facts. See [alternatives](docs/SOURCES.md).
+
+## Problems in the original plan and decisions
+
+| Original weakness | Revised decision |
+|---|---|
+| “Proof that an evaluation ran” exceeds timestamp guarantees | Evidence dimensions replace an unqualified verified badge |
+| Timestamping a plan can happen after private rehearsal | Never infer no prior runs or honest chronology from a receipt |
+| A new runner makes the first build larger and less adoptable | Ingest a documented fixture format first; adapt an existing harness later |
+| “Offline” hides the source of Bitcoin trust | Verifier controls a previously validated chain snapshot; current freshness is reported separately |
+| A sealed score may be mathematically wrong | Integrity and score recomputation are separate checks; one deterministic fixture scorer is independently reproducible |
+| “Preregistered” conflates anchors with an observed start | Report plan anchoring and operator-declared launch policy separately |
+| Generic parity claims mix tokens, money and compute | Separate token, measured-resource and API-cost comparisons |
+| 100 runs can become a volume vanity metric | Count unique scheduled, completed executions; expose missing attempts and uncertainty |
+| Three downloads are not adoption | Require independently published, independently verified real receipts and usability evidence |
+
+## Evidence contract
+
+An offline report contains separate fields for schema support, artifact integrity, Merkle membership or full-tree verification, plan and result timestamp status, chain evidence source and cached tip, confirmation policy, declared execution outcome, model evidence, score recomputation, issuer identity and launch-policy assertions. The report never equates an operator declaration with an independent observation. Issuer identity is `unverified` in v0.1, even when an author name appears in metadata. Model evidence is one of `self_declared`, `provider_metadata_recorded`, or `weight_digest_recorded`; none means executed-model attestation.
+
+Verification has two scopes. `full` checks every committed artifact and recomputes the complete ordered tree. `inclusion` checks one explicitly identified record against a committed root and tree size; it cannot claim complete artifacts or complete execution history. Neither scope establishes that omitted, unrecorded calls never happened.
+
+A valid record may describe failed, aborted or budget-exceeded work. Those are evaluation outcomes, not necessarily invalid receipts. Missing required artifacts or broken commitments are invalid evidence. Unsupported versions, absent chain evidence and pending anchors must not look like successful anchored verification.
+
+Proposed exit codes: 0 means all checks required by the selected scope and policy passed; 2 malformed or invalid evidence; 3 pending or insufficient evidence; 4 unsupported version or algorithm; 5 operational failure. Human and JSON output both name scope and remaining assertions. The default verification policy requires both completed anchors and all artifacts; an explicit `--integrity-only` policy can pass hashes while plainly reporting timestamps unchecked.
+
+## Minimal receipt format
+
+Use a plain directory in the first version. No archive extraction, remote artifact resolution or plugin execution during verification.
+
+| File | Role |
+|---|---|
+| `manifest.json` | Frozen plan core, canonical UTF-8 bytes |
+| `result.json` | Final result core binding the manifest digest and artifact inventory |
+| `artifacts/` | Exact recorded bytes, including original harness output and normalized fixture records |
+| `proofs/manifest.ots` and `proofs/result.ots` | Detached timestamp proofs for the exact canonical core files |
+
+The core excludes mutable proof files, chain caches and verifier reports to avoid circular digests. Proof upgrades preserve core bytes and receipt identity. A registration ID is SHA-256 of canonical manifest bytes; the manifest includes a 128-bit random nonce to distinguish intentional repeated registrations. Fixed published test fixtures use an explicitly fixed nonce. A receipt ID is SHA-256 of canonical result bytes. Multiple result receipts may reference a registration. Each manifest predeclares its permitted attempt IDs, using unique lowercase ASCII identifiers matching `[a-z0-9][a-z0-9_-]{0,63}`, and expected sample coverage for each. Results must reference one such ID. The protocol cannot prove no other receipts or undeclared executions exist.
+
+The manifest binds a protocol version, registration nonce, experiment description, task/split content digests, evaluation harness revision and effective configuration, prompts and generation settings, model evidence, scorer and analysis revisions, attempt and retry policies, resource ceilings, stopping rules, expected sample IDs, and declared execution policy. Fields unsupported by a provider are explicit unknowns. References alone are not substitutes for content digests. Expected sample IDs are explicit in v0.1. Private-inventory commitment and reveal verification is deferred to G5 and requires a separately versioned schema, exact domain-separated commitment preimage and reveal format, and mutation vectors before it can be claimed supported. A v0.1 receipt cannot claim verified secret-inventory membership.
+
+The result binds the registration digest, attempt ID, final outcome, artifact inventory with SHA-256 and byte counts, tree algorithm and event count, ordered event root, resource ledger and reported score artifact. The inventory is a canonical JSON mapping sorted by relative path with digest, byte length, media type and role per entry. For v0.1 artifact paths are lowercase ASCII POSIX paths, with only letters, digits, dot, underscore, hyphen and slash; reject empty, dot and parent components, repeated slashes, duplicate paths and unlisted files beneath `artifacts/`. Completeness applies to that directory, not detached proofs. Fixed core/proof paths are protocol files; other root content must be rejected or explicitly designated non-normative local state by the schema. An inclusion proof does not imply the inventory is available. Any operator-reported start and end times are labeled as such. A finalization timestamp is never labeled as execution time.
+
+Canonical JSON uses RFC 8785 with a deliberately narrower first-version profile: no duplicate keys, no non-finite numbers, no floats, no lone surrogate code points, and integers in the inclusive range -9007199254740991 through 9007199254740991. Counters and lengths must also be nonnegative. Represent decimal quantities as schema-constrained decimal strings with named units. Reject unknown normative fields or versions rather than silently ignoring semantics. Preserve raw artifacts byte-for-byte; canonicalization applies to protocol JSON, not arbitrary source logs. Pin a conforming implementation after its conformance vectors pass.
+
+Use the RFC 9162 Merkle tree hash construction with SHA-256, leaf/internal-node domain separation and its defined split rule; do not duplicate odd leaves. Leaves are canonical normalized event objects. Each binds the registration digest, attempt ID, contiguous zero-based event index, event kind and relevant sample ID. The result commits tree size. For zero events use the specified empty-tree hash; only a failed, aborted or budget-exceeded attempt with an explicit reason can finalize empty. Validate inclusion index, tree size and exact proof consumption. [Construction reference](https://www.rfc-editor.org/rfc/rfc9162.html#section-2.1)
+
+G1 begins by freezing a closed versioned schema table before implementation: `sample_start`, `call`, `sample_end`, and `attempt_end`; each records its event index and identifiers. That table must define required/optional fields, absent/null rules, identifier syntax and exact canonical leaf bytes, and cover every event type in fixed vectors. Unknown event fields fail. A call records status, visible input/output artifact references, token usage or unknown, and retry linkage to an earlier call in the same attempt. Artifact references use the inventory path grammar and resolve to a listed entry. A sample end records its terminal status. Every expected sample has one terminal status or the attempt declares incomplete coverage. The core checks that call/sample/attempt IDs, event ordering, artifact references and final counts agree. It cannot validate that an untrusted producer told the truth.
+
+The score binding is an object naming exactly one inventory path with role `score`, its SHA-256 and byte length, a scoring-profile identifier and a declared aggregate as a rational numerator/denominator pair or an explicit unavailable state. Resolve the path and require all copied digest/size fields to match the inventory. Freeze score, resource and event schemas together at the start of G1; no independent implementation can rely on prose guesses about these fields. G1 also freezes outcome/coverage and policy/exit-code tables: completed evaluations require full declared coverage; failed, aborted and budget-exceeded attempts may declare incomplete coverage with explicit reasons. Valid receipts may describe unsuccessful evaluations. Test pending anchors under integrity-only policy, wrong fixture scores under recomputation policy, and unavailable artifacts under inclusion policy.
+
+## Timestamp and trust workflow
+
+1. `tallylock pre-register manifest.json`: validate, canonicalize to a new receipt directory and freeze core bytes atomically. With `--anchor ots`, request a timestamp after writing durable local state. A submitted proof is pending until completed and checked.
+2. An external evaluator runs. The first version includes a deterministic fixture producer for tests, not a general inference runner. A later harness integration may enforce waiting for a confirmed plan anchor locally. Its attestation remains an operator assertion unless independently witnessed.
+3. `tallylock seal RECEIPT --artifacts DIR --anchor ots`: snapshot immutable artifact copies, validate internal consistency and finalize a result core before network work. A failed anchor request cannot erase or change the local result. No overwrite of finalized core files; corrections create a new receipt referencing the superseded ID.
+4. `tallylock upgrade RECEIPT`: complete proofs using the pinned OpenTimestamps implementation, with bounded timeouts, backoff and concurrency. Recover interrupted work from local state; preserve prior proof bytes before atomic replacement. Never rewrite cores. Identical repeated commands must be safe.
+5. `tallylock verify RECEIPT --offline --chain-cache PATH`: perform only local reads. Default full verification requires completed proofs for both cores and independently obtained chain data. A separate `tallylock inspect` reports available evidence without asserting verification.
+
+OpenTimestamps stamping and upgrading may contact public calendars; proof submission is not finality. Use upstream formats and verification operations, not invented timestamp cryptography. A proof request has a durable idempotency key based on its core digest. A retry may receive different valid proof bytes while the commitment stays identical. [Upstream workflow](https://github.com/opentimestamps/opentimestamps-client)
+
+The first offline cache is explicitly local trust material, not part of the receipt. A separate `tallylock evidence export --bitcoin-rpc ...` command reads the verifier's own fully validated Bitcoin Core node and exports the required block headers, heights, block hashes, confirmation observations and observed tip into a versioned cache. RPC credentials come from a configuration file or cookie, never a CLI URL. Do not deploy a node as part of this project phase; first assess access to an existing independently validated source. If none exists, the real offline-anchor milestone remains blocked on evidence acquisition, not silently downgraded to explorer trust.
+
+The exporter confirms the required blocks belong to the node's active chain and records its synchronization state. Its cache schema binds format version, creation time, tip hash/height, node validation/synchronization observations and required anchor headers with their hashes, heights and cached confirmations. Export captures the tip before and after reading all anchor data and retries the bounded snapshot operation if the chain view changes. Verification recomputes header hashes, matches anchor Merkle roots and checks the cache's height/hash mapping and confirmation arithmetic. Authenticity of the cache comes from the verifier's independent acquisition, not a self-asserted JSON field. An attacker who can replace that trust store can subvert the check. A receipt-provided cache is rejected as an implicit trust source. Only an explicitly supplied verifier-owned `--chain-cache` is used; no bundle-relative discovery is allowed. The software cannot determine who originally created an explicitly trusted cache. This validated-node-export design intentionally does not claim to validate cumulative work offline.
+
+Default Bitcoin confirmation policy is six blocks including the anchor, recorded as a project policy rather than a guarantee of irreversibility. Cached confirmations are relative to the exported chain view. No timestamp or confirmation count establishes the current chain after disconnection. Live refresh can detect reorganizations later; offline output must retain the cached tip and provenance.
+
+There is no cryptographic “ran after registration” verdict in v0.1. Future unpredictable task selection may constrain which task set could be finalized in advance, but seed grinding, leaked generators, rehearsals and operator control remain relevant. Witnesses, trusted execution and randomness beacons require separate threat models and are deferred.
+
+## Safe processing and persistence
+
+Treat manifests, logs and proofs as hostile data. Never run harness/scorer code during ordinary verification. Score evidence is `recorded_only`, `recomputed_fixture`, or `not_available`; v0.1 recomputation uses only a built-in deterministic fixture scoring profile with exact per-sample rules, denominators, exclusion policy and rational aggregate arithmetic. The verifier never imports arbitrary scorer code from a receipt. Accept only regular files beneath the receipt root: reject symlinks, absolute paths, traversal, duplicate or case-colliding artifact paths and changed files during snapshot. No artifacts are fetched from embedded URLs. Limit metadata to 8 MiB per core, 1 MiB per event, 10 million events and 16 MiB per detached proof in the first parser policy; hash artifact data by streaming and make bounded policy overrides explicit. Limits are operational bounds, not wire-format promises. End-to-end score recomputation for other scorers is a separate explicitly sandboxed action and is outside v0.1.
+
+Verification also treats concurrent filesystem mutation as hostile. Resolve files beneath an opened receipt-root descriptor without following symlinks; use no-follow descriptor-relative opens, require regular-file descriptor metadata, and compare device/inode/type/size and change metadata before and after streaming. Reject changes and any digest/byte-count mismatch. Apply equivalent handling to core and proof reads, not only artifact hashing. Fail closed on platforms without tested primitives. This is read-time race resistance, not a guarantee against an attacker controlling the operating system.
+
+One writer per receipt directory, using exclusive lock creation with an explicit recovery procedure. Write temporary files, flush and atomically replace local state; refuse conflicting repeated inputs. Tests interrupt each persistence boundary. Proof pending, network failure and invalid data produce distinct machine-readable states. Online calendar work has one active request per receipt and capped retries; offline verification has no network fallback.
+
+Do not mutate private logs to sanitize them after sealing. Before public export, choose a deliberate disclosure profile: public-reproducible includes all necessary permitted artifacts; commitment-only discloses hashes and optional later reveals while reporting unavailable evidence. Low-entropy private task material needs a random nonce in its commitment preimage; hold that nonce until reveal. No parallel unsalted digest of the same withheld plaintext may appear in an exported inventory or metadata, or the intended guessing protection is lost. The private-inventory/reveal profile is deferred and must test this boundary before G5. Never include credentials or personal data in fixture content. Changes in disclosure create distinct artifacts and receipts, not silent replacements.
+
+## Work packages and acceptance gates
+
+| Gate | Deliverable | Verification |
+|---|---|---|
+| G0, this phase | Reviewed plan, threat model, test matrix and dedicated repo | Every blocking critique has a disposition; unresolved external prerequisites are explicit; Chris approves the first implementation scope |
+| G1, receipt core | Freeze versioned manifest/result/event/score/resource schemas and vectors first; then deterministic fixture and local hash/tree verifier | Independent fixed vectors, mutation tests, score recomputation, hostile path/parser tests and interrupted-finalization recovery pass; no inference required |
+| G2, timestamp round trip | Upstream OTS adapter, local evidence export and offline verification | Fresh plan anchors, fixture execution follows the local gate, separate result anchors; a clean disconnected verifier validates both against independently acquired cache; pending/invalid/untrusted cases fail honestly |
+| G3, external-harness pilot | One pinned Inspect import adapter plus Colony Zero example | Original log bytes retained; mapping report accounts for every source record as mapped, preserved-unmapped or unsupported; unsupported semantics prevent strict normalized-execution claims; two unfamiliar people verify a pilot and explain the remaining trust |
+| G4, release | Stable v1 protocol, clean PyPI install and compatibility corpus | External pilot has no blocking correctness/usability issues; install and quickstart succeed without development checkout; distribution name cleared; supported Python/OS matrix documented |
+| G5, research deployments | Observatory and swarm report | Scientific and adoption gates below, approved model roster and budget, public downloadable evidence |
+
+G1 does not claim Bitcoin anchoring. G2 must use a real anchor and a real independently prepared chain view; mocks establish only unit behavior. Historical fixtures cannot substitute for the fresh G2 experiment. No paid inference, new node deployment or production service changes occur in G0-G1. Timing depends on evidence access, review and Bitcoin confirmation, not a promised number of days.
+
+Implementation modules should separate core data/hash/tree logic, read-only verification, local store/finalization, timestamp transport, chain-evidence export and CLI presentation. Verification must not import model-provider SDKs or call writer operations. Publish vectors before optimizing performance. The first supported runtime is Python 3.11-3.13 on Linux; qualify other platforms only after their atomic-write, path and locking behavior is tested. Third-party adapters and a pure-node-free chain verifier are outside the first implementation. G3 accepts only a pinned exported Inspect JSON representation, parsed as data without loading task code, resolving external paths, fetching attachments or activating plugins. Binary `.eval` ingestion is deferred until its parser boundary is separately reviewed.
+
+## Scientific gates
+
+The observatory tracks evaluated service behavior, not unobservable weight changes. Freeze a core task panel and scorer; changing either starts a new comparable series. Keep a fixed public sentinel panel and separately version private holdouts with salted commitments and delayed reveals. Record disclosure times and stop using revealed holdouts as secret tests. A frozen open-weight reference runs through the evaluator/control path on each sweep, so changes in that control trigger an evaluator-drift investigation. Daily sentinel measurements are descriptive; weekly preregistered comparisons are confirmatory. Specify one primary endpoint per series, a smallest meaningful change, paired sampling units, replicate structure, power calculation, missing-data handling and multiple-comparison/continual-testing policy before calling a change “drift.” Repeated API calls to one prompt are not independent task samples. Track outages and missingness separately from accuracy, and account for repeated peeking. Choose and simulate the actual error-control procedure before G5, rather than treating repeated ordinary confidence intervals as sequential evidence. Run simulation/calibration against a fixed local fixture before funding live collection.
+
+The 100-run target counts unique scheduled executions with complete result receipts and confirmed anchors, not proof upgrades, retries or duplicated views. An anchored published schedule enumerates intended run IDs and deadlines; publish terminal dispositions for each. This detects missing outcomes relative to that schedule, not secret off-schedule evaluations or a dishonest schedule author. Archive schedule revisions and periodically anchor their inventory. A signed/witnessed global transparency service is not implied.
+
+Swarm studies have distinct token-budget, API-cost and controlled-resource tracks. Count routing, coordination, all members, retries, failures, judging and tool use consistently. Report unavailable hidden reasoning usage, tokenizer differences and training/amortization assumptions. A closed API track cannot claim strict compute parity. Controlled open-weight comparisons name hardware, precision, measured resource units and accounting boundaries. Include best single member, best-of-N and simple voting controls; pair tasks and repeat seeds where supported. Preregister superiority or noninferiority margins, multiplicity rules and stopping criteria. Negative and inconclusive results satisfy the research objective.
+
+No arbitrary sample-size promise replaces a powered design. A report's headline scores must be independently recomputable from disclosed records or clearly labeled non-recomputable. Model-graded outcomes need pinned judge settings and calibration; changing judges creates a new analysis version. Hugging Face publication requires permission to redistribute the actual data, not only permission to run a benchmark.
+
+## Adoption and stop rules
+
+Before expanding the platform, test whether an unfamiliar maintainer can wrap existing logs without rerunning a model. Pilot target: integration within one working day, active verification within 15 minutes after chain evidence is prepared, and correct interpretation of what the receipt does not prove. Record setup time, failed steps, provider/harness version and a short comprehension check. Bitcoin synchronization and anchoring wait are measured separately rather than hidden in a speed claim.
+
+Three independent external adopters means three unaffiliated maintainers or researchers publishing their own real receipts; team-produced fixtures, forks and downloads do not count. This remains a project success metric after release, not a prerequisite that prevents shipping the tool needed for adoption. Outreach remains owner-authorized work, not automatic messaging. If pilots prefer signed logs or existing attestations and cannot identify useful incremental assurance, simplify or reposition before building the observatory. If independent chain preparation dominates usability, report it as a blocker and evaluate an explicitly different trust mode rather than marketing it as solved.
+
+## Costs and open decisions
+
+This design phase uses existing tools at no new spend. Public calendars currently offer free submissions. Future API evaluations, hosting and any Bitcoin node storage/network costs require a separately costed roster and hard budget. The repository is TriplePassLabs/tallylock; Chris selected public visibility and Apache-2.0 on 2026-11-05, then moved TallyLock under the business organization. The PyPI distribution and CLI command names still need availability/conflict checks before release; TallyLock is a working product name. Do not reuse private project implementation merely because public receipts are available.
+
+G0 can finish with an explicit chain-evidence acquisition prerequisite; G2 cannot pass without satisfying it. G1 still requires Chris's approval after the adversarial review, as requested. No implementation is authorized by the presence of this plan.