Skip to content

AI_USAGE.md

Latest commit

 

History

History
72 lines (48 loc) · 16.7 KB

AI_USAGE.md

File metadata and controls

72 lines (48 loc) · 16.7 KB
Raw

AI Use and Human Contribution Record

This project uses Codex as an implementation assistant. Human team members define the problem, choose scope and assumptions, select and review cryptographic and exchange mechanisms, run acceptance experiments, interpret failures, and approve releases.

For every AI-assisted change, record:

  • date and contributor;
  • tool/model and the prompt or task brief;
  • files generated or modified;
  • human decisions, edits, and review performed;
  • commands run and their actual output;
  • reviewer and acceptance status.

Human ownership boundaries are defined in HUMAN_CONTRIBUTION.md. The goal is meaningful design, implementation, testing, and review by team members, not cosmetic authorship.

Do not describe AI-generated code as independently designed by a human. Do not claim a mechanism, audit, performance result, or sponsor integration until the repository contains the corresponding implementation and evidence.

Initial session record

  • 2026-09-09: Codex inspected the public OriginShift/ProofOrder repository and confirmed it contained only the initial README and MIT license.
  • 2026-09-09: The team supplied the ProofOrder product specification and execution rules through Notion. Codex converted the agreed scope into specs/mvp.md and docs/EXECUTION_PLAN.md; the team remains responsible for the technical decisions and acceptance.
  • 2026-09-11: Codex added the deterministic-evaluator evidence digest adapter and connected ECDSA signature recovery in the settlement contract. The team must decide whether to replace this trusted attestation with a real ZK verifier before submission; it is not represented as a ZK proof.
  • 2026-09-11: Codex added RecoveryBundle persistence and integrity checks, then ran the local Anvil flow. Team review must confirm the offline checkpoint and storage assumptions.
  • 2026-09-11: Codex resumed the interrupted failure-runner task. It implemented exact contract-error assertions, a valid-signature simulation, receipt-block refund accounting, bounded waits, cancellation and automatic local Anvil lifecycle in src/failure-flow.mjs and scripts/run-failure-demo.mjs; added test/failure-flow.test.mjs; and updated package.json, README and evidence records. A second Codex agent reviewed error classification, refund accounting and timeout handling. npm test passed 15 tests; forge test -vv passed 7 tests; the local failure flow passed 10 rejection checks and both refunds, including two runs on the same node without reset. See the run record for commands and source hashes. These are AI implementation and AI review; independent human reproduction, edits and acceptance remain pending.

Encrypted recovery session

  • 2026-09-12: User task brief: continue the next implementation step and resume after API interruptions. Codex implemented real HPKE envelope encryption, schema-2 signed recovery, independent-process decryption/re-evaluation, and a provider-abort prepayment-decryption/refund experiment. It also shared the automatic Anvil wrapper across both demos and added lifecycle regression tests.
  • 2026-09-12: Codex fixed the omitted chain ID in the on-chain EIP-191 evidence domain, updated offline recovery and fixtures, added the Foundry chain-ID regression test, and regenerated both local reports. forge test -vv passed 8 tests and npm test passed 84 tests; both demos passed. See decision 0012. Human review and acceptance remain pending.
  • 2026-09-12: Codex added the one-hour VERIFICATION_GRACE to the settlement contract, preventing immediate refund of a predeadline Submitted order during verifier processing and rejecting verification after the grace. It added Foundry tests for both boundaries, updated the failure flow and evidence ledger, and reran the demos. forge test -vv passed 10 tests and npm test passed 84 tests. See decision 0013. Human contract review and acceptance remain pending.
  • 2026-09-12: User-directed next step: Codex removed the buyer-only caller requirement from settle, kept the funded payee and amount immutable, added a relayer/buyer-offline Anvil trace, and added adversarial Foundry coverage for arbitrary callers, fixed-payee redirection, payout retry, reentrancy, duplicate settlement, and post-grace execution. npm test passed 84 tests; forge test -vv passed 24 tests; npm run demo and npm run demo:failures passed. See decision 0014. Human review and acceptance remain pending.
  • 2026-09-12: User-directed next step: Codex implemented and tested a separate payment-gated disclosure candidate. The public bundle excludes its data key and is pinned by an external envelope commitment, so prepayment decryption fails; a mined post-settlement release succeeds; provider withholding after payment remains unrecoverable. npm run experiment:payment-gated passed on fresh Anvil and npm test passed 112 tests, including 28 focused cases. See decision 0015. The candidate is retained as a failure experiment, not claimed as fair exchange.
  • AI-assisted files: src/sealed-result.mjs, src/order.mjs, src/recovery.mjs, src/demo-flow.mjs, src/failure-flow.mjs, scripts/local-demo.mjs, scripts/run-demo.mjs, scripts/run-failure-demo.mjs, scripts/recover-demo.mjs, test/sealed-result.test.mjs, test/encrypted-recovery.test.mjs, test/local-demo.test.mjs, package.json, README, execution/spec status and evidence records. Parallel Codex agents implemented the encryption helper, recovery validation and node wrapper; root integrated and ran the experiments. A separate agent reviewed the integration; its snapshot-ordering finding was fixed with shared canonical snapshot hashing and a regression test.
  • Actual validation for the latest scope: 84 JavaScript tests and 24 Foundry tests passed; both CLI demos passed their assertions. The exchange counterexample remains a security failure, retained in the evidence rather than marked as a satisfied guarantee. Full commands, environment and machine-readable output are in decision 0014.
  • Human contribution: no human code edit or acceptance was observed in this session. Substantial state-machine/replay/timeout work and adversarial contract tests remain assigned to a team member under HUMAN_CONTRIBUTION.md. These AI changes do not fulfill that ownership requirement.

Provider workflow session

  • 2026-09-12: Codex task brief: prepare the Teammate B provider workflow and state whether its allocation fixture is a credible purchasing case. Codex added src/provider-flow.mjs, routed src/demo-flow.mjs through the provider adapter, added test/provider-flow.test.mjs, and clarified the fixture's limits in README. The adapter rejects proposals before encryption or evidence creation, then seals accepted allocations and binds the evaluation to the order and ciphertext commitments.

  • The worktree also contains earlier uncommitted evaluator changes in src/evaluator.mjs and test/evaluator.test.mjs; the evaluator implementation was Codex-assisted, and the test file has changes from multiple turns. Review those diffs before deciding how to attribute them in the human contribution record.

  • The fixed task rules remain 10,000 units, at most 6,000 per target, minimum liquidity 5,000 bps and weighted score 7,500 bps. The targets and metrics are fixtures, so the current example is not a credible real purchasing case or evidence of a live procurement integration.

  • Codex did not run tests for this change. Human review, any substantive edits, clean-environment reproduction and acceptance remain pending. The user plans to create the commit after review. The AI-authored code and the act of committing it do not by themselves fulfill the personal implementation requirement in HUMAN_CONTRIBUTION.md.

  • 2026-09-12 follow-up: at the user's request, Codex tightened the evaluator's positive-safe-integer amount contract and added boundary tests for malformed numbers and frozen thresholds. Codex moved the recovery order and snapshot schema validation into shared helpers, then changed prepareProviderSubmission to accept the complete order, check its snapshot commitment and fixed task schema, derive the digest internally, reject missing or mismatched recipient keys, and evaluate and seal the same copied allocation values. Codex updated the recovery/provider tests, local demo integration, README, acceptance ledger note, and human contribution status. A second Codex agent performed a read-only static review; its findings were fixed, but that review is not independent human acceptance. See decision 0016. The user ran the four requested commands in the current working tree and supplied their logs: npm test passed 138/138; forge test -vv passed 24/24 across 2 suites; npm run demo and npm run demo:failures both produced status: passed reports. Raw test logs and demo reports are archived under evidence/runs/0016-*. Clean-environment reproduction, substantive Teammate B edits, independent human review, and the user's commit remain pending.

  • 2026-09-12 provider follow-up: Codex proposed snapshotting provider allocation fields once and returning a stable INVALID_ALLOCATION_INPUT rejection if reading them throws. Chris applied that suggestion, then the focused test exposed a missing early return for evaluation.ok === false; Codex identified the missing guard and Chris added it. Chris supplied post-fix logs showing node --test test/provider-flow.test.mjs passed 9/9, npm test passed 139/139, and npm run demo produced a status: passed report. See the post-fix provider log, JavaScript log, and demo report. forge test -vv was not rerun after this JavaScript-only change; the earlier 24/24 result remains linked in decision 0016. Chris self-reviewed these two provider changes and reported no issues; this is not an independent review. The applied edits follow an AI-supplied proposal and are not recorded as independently designed human implementation. Teammate B's own design decisions/substantive evaluator edit, independent human review, clean-environment reproduction, and commit remain pending.

2026-09-13 AI-authored CLI/verifier slice (unapproved, human review pending)

An AI implementation session (Codex/Hermes-family agents, no human code edit in that session) added the buyer/provider/verifier CLIs, the shared frozen-spec/status modules, the independent-verification module and the separate-process CLI end-to-end harness, and fixed the security defects listed in DELIVERY_REPORT.md (verifier no longer signs a provider-claimed evaluation; refund no longer requires a provider bundle; provider binds the order digest and refuses to overwrite a delivered ciphertext; init refuses an existing workflow; the wrong forge artifact path was corrected).

This is AI implementation and AI-run verification. It is not human work: no human wrote, reviewed, approved or accepted it, and the human-owned slice in HUMAN_CONTRIBUTION.md (final OrderSpec/buyer-workflow edits, clean-environment reproduction, independent review, commit) remains pending with Qy as the named future owner. Prior contributors' records above are preserved unchanged. The verifier still holds decryption capability in this trusted local demo; the attestation is a trusted ECDSA attestation, not a zero-knowledge proof, and it does not prove delivery or fair exchange.

2026-09-13 Chris-branch integration and WSL verification

  • Codex applied the handoff patch on feat/chris-workflow-completion, based on merged main at 1c6ffdebdd4358086f38db19cb191bec5b816516. Codex also fixed the new reproduction script's CRLF line endings and widened the lifecycle timeout test from 30 ms to 250 ms after the full run exposed a scheduling-sensitive assertion.
  • Codex ran bash scripts/reproduce.sh from an Ubuntu WSL Linux-filesystem snapshot of the branch: Node v26.5.1, npm 11.17.0, Foundry v1.8.1, local Anvil chain 31337. Results: npm test 196/196; forge test -vv 38/38; standalone CLI harness 5/5 (included in the 196); both demos passed. The final log is 0017-codex-wsl-reproduce.log.
  • WSL npm ci --ignore-scripts failed with ECONNRESET while fetching ethers, and WSL npm audit could not reach the advisory endpoint through its proxy. Windows npm ci --ignore-scripts then completed successfully; Windows npm audit on the same lockfile reported zero vulnerabilities. Dependencies were copied to the temporary WSL snapshot, where tests and demos ran with Linux Node and Foundry.
  • Codex inspected the generated demo reports: the encrypted-delivery path settled the fixed payee for 1 ETH, left escrow at zero and buyer nonce unchanged after checkpoint; the failure path refunded both orders to the buyer and kept payee balances unchanged. The exchange counterexample remains explicit (fairExchangeEstablished: false). The reproduction log was scanned for key/seed material; matches were test descriptions only. The run and review were performed by Codex, not by Chris or an independent human reviewer. Human review, Qy's final acceptance and T20 remain pending.

2026-09-13 chain-status and strict-reproduction follow-up

Codex changed src/settlement-status.mjs to always read the RPC network chain id, added the 31337-versus-1 CHAIN_MISMATCH regression, removed the misleading plaintext-result success-path wording from scripts/verifier-cli.mjs and FINAL_REVIEW_ZH.md, and removed the npm audit || echo ... fallback from scripts/reproduce.sh. The full reproduction passed 197 JavaScript tests, 38 Foundry tests, the 5-test standalone CLI harness, and both local Anvil demos. WSL could not reach the Windows loopback-bound npm proxy; the temporary out-of-repository wrapper used the real Windows npm 10.9.3 audit result only after verifying the snapshot's package-lock.json SHA-256, and returned the audit's exit status unchanged. The audit reported zero vulnerabilities. Full output: 0018-codex-wsl-reproduce.log. This follow-up is AI-authored and AI-run; it is not independent human review or acceptance.

2026-09-13 actual-address and verifier-input follow-up

Codex changed readSettlementStatus() to always report await contract.getAddress() and compare it against, rather than substitute, the expected address. A regression traverses readSettlementStatus() and verifies actual 0x0000000000000000000000000000000000000001 versus expected 0x0000000000000000000000000000000000000009 returns CONTRACT_MISMATCH; the unused getBlockNumber() request was removed. Codex removed the verifier CLI's --verification-result-file branch while retaining the lower-level UNBOUND_PLAINTEXT_REFUSED behavior and test.

node --test test/settlement-status.test.mjs passed 12/12. Windows npm ci --ignore-scripts completed with zero vulnerabilities. A fresh WSL Linux-filesystem snapshot, with old compiler artifacts removed, passed bash scripts/reproduce.sh: 198 JavaScript tests, 38 Foundry tests, the standalone 5-test CLI harness, and both local Anvil demos. WSL could not reach the Windows loopback proxy for npm audit, so an external wrapper verified the exact package-lock.json SHA-256 and passed through the real Windows npm 10.9.3 audit result and exit status (0 vulnerabilities). The run log is 0019-codex-wsl-reproduce.log. It was scanned for private key/seed markers; matches were test descriptions only. This is Codex-authored and Codex-run work, not Chris's personal implementation, independent human review, or human acceptance; T20 remains pending.

2026-09-13 Windows reproduction portability follow-up

Codex adjusted the recovery-bundle permission checks to assert POSIX mode bits only off Windows, while keeping the 0o600 checks on POSIX platforms. The local demo uses the same platform boundary. The SIGINT cleanup test now dispatches the registered signal event on Windows, where a self-sent SIGINT terminates Node without invoking its handler, and continues to send a real self-SIGINT on POSIX. Windows npm ci --ignore-scripts exited 0. The final bash scripts/reproduce.sh run on Node v22.18.0/npm 10.9.3 passed 198/198 JavaScript tests, 38/38 Foundry tests, the standalone 5/5 CLI harness, both local demos, and npm audit (0 vulnerabilities). This compatibility change and verification were Codex-authored/run; independent human review and acceptance remain pending.