Skip to content

[codex] Name the proofchain primitive#494

Merged
TSavo merged 1 commit into
mainfrom
codex/proofchain-docs
May 9, 2026
Merged

[codex] Name the proofchain primitive#494
TSavo merged 1 commit into
mainfrom
codex/proofchain-docs

Conversation

@TSavo
Copy link
Copy Markdown
Owner

@TSavo TSavo commented May 8, 2026

Summary

  • introduce proofchain as the high-level name for the linked evidence object ProvekIt already builds
  • frame proofchains as portable evidence for logically true claims, not software-only truth claims
  • update paper 03 with the formal consensus lemma: proof validity is local; distributed timestamp-server claims require consensus

Scope

Docs only. No protocol, catalog, schema, or generated artifact changes.

Validation

  • git diff origin/main...HEAD --check
  • searched touched docs for stale software truth claims and 12-proofchains references

Summary by CodeRabbit

  • Documentation
    • Added comprehensive explanation of proofchains as locally verifiable chains of signed, content-addressed evidence
    • Introduced new documentation detailing proofchain structure, layers, and composition
    • Updated core documentation to emphasize proofchains as ProvekIt's primary output
    • Added formal definitions clarifying proof validity versus consensus requirements

Copilot AI review requested due to automatic review settings May 8, 2026 23:49
@coderabbitai
Copy link
Copy Markdown

coderabbitai Bot commented May 8, 2026

Review Change Stack

Warning

Rate limit exceeded

@TSavo has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 46 minutes and 1 second before requesting another review.

You’ve run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 2801af66-7b47-4fe0-b100-14a019e498db

📥 Commits

Reviewing files that changed from the base of the PR and between f81dce7 and 97c33d6.

📒 Files selected for processing (7)
  • README.md
  • docs/explanation/pitch.md
  • docs/explanation/product.md
  • docs/explanation/proofchain.md
  • docs/index.md
  • docs/papers/03-substrate-not-blockchain.md
  • docs/papers/README.md

Walkthrough

This PR introduces "proofchain" as the central organizing concept throughout ProvekIt's documentation. Changes span the README, landing docs, pitch, product description, and formal papers, all reinforcing that ProvekIt produces portable, signed, locally verifiable chains of content-addressed evidence.

Changes

Proofchain Concept Introduction and Documentation

Layer / File(s) Summary
Core Concept Definition
docs/explanation/proofchain.md
New document defining proofchain as a portable evidence structure for logically true claims, explains payload concept (formal proofs vs. blockchain state transitions), maps proofchain layers to existing ProvekIt artifacts (claim, identity, evidence step, signature, transport, acceptance), and clarifies how .proof containers, mementos, witnesses, and attestations compose into a verifier-walkable object.
Landing Page and Navigation
docs/index.md, README.md
Adds proofchain definition to landing documentation and updates navigation tables to link "What is a proofchain?" to the new explanation file. README gains a descriptive section clarifying proofchains as locally verifiable, signed, content-addressed evidence checked against the evidence object itself without requiring a global ledger.
Pitch and Product Value
docs/explanation/pitch.md, docs/explanation/product.md
Reframes pitch to explicitly describe ProvekIt as transforming verification tool outputs into proofchains. Clarifies that proofchain is the high-level load-bearing primitive enabling portable, signed, composable publication of verification findings. Product documentation now emphasizes that deliverables include a proofchain carrying claims, witnesses, attestations, and policy context for local verification. Expands "Read further" links to reference proofchain and formal papers.
Formal Theoretical Grounding
docs/papers/03-substrate-not-blockchain.md, docs/papers/README.md
Opens paper with proofchain vs. blockchain-derived framing. Adds formal lemma in §1 proving that proof validity is local and communication-free (deterministic verdict from identical inputs to honest verifiers) without requiring distributed consensus. Rephrases sovereignty argument to explicitly tie consensus to timestamp-server ordering while treating proof validity as independent of consensus. Updates paper index to highlight the lemma distinguishing when consensus is and is not required.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

  • TSavo/provekit#480: Larger v1.6.2 doc refresh overlapping the same documentation surfaces (README.md, docs/index.md, pitch, product) with proofchain-focused concept alignment.

Poem

🐰 A chain of proofs, locally true,
No consensus ledger needed to verify through,
Content-addressed, portable, and signed,
The missing primitive ProvekIt finds,
Verification tools now compose with glee!

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title '[codex] Name the proofchain primitive' directly and accurately reflects the main objective: introducing and naming 'proofchain' as a formal primitive throughout the documentation.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch codex/proofchain-docs

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

Copy link
Copy Markdown

@coderabbitai coderabbitai Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/papers/03-substrate-not-blockchain.md`:
- Line 110: Replace the unhyphenated compound adjective "Turing complete
substrate" with the hyphenated form "Turing-complete substrate" in the sentence
that reads "A Turing complete substrate already contains every program a smart
contract could embed; the substrate is the bigger set." to correctly form the
compound adjective.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 54c54262-7823-4d64-a145-ee7a739c2316

📥 Commits

Reviewing files that changed from the base of the PR and between 61b31e0 and f81dce7.

📒 Files selected for processing (7)
  • README.md
  • docs/explanation/pitch.md
  • docs/explanation/product.md
  • docs/explanation/proofchain.md
  • docs/index.md
  • docs/papers/03-substrate-not-blockchain.md
  • docs/papers/README.md

Once you accept that, "what should the substrate add next?" becomes a malformed question. There is nothing above Turing complete. Anyone proposing a more general substrate is either building a less general one (a special-purpose chain, a fixed VM, a typed but narrower envelope) or reinventing the same four invariants under a different brand. The design space above the substrate is full of applications. The space at the substrate level is small because it has to be. This is why §3's "EVM is the floor" is structural rather than aspirational. The ceiling is theorem, not promise.

Conventional blockchains pick one tape format (state-machine deltas) and one consensus discipline (totally ordered chain over a globally shared ledger). That is a restriction on the substrate, not an extension. They left generality on the floor to buy something they did not actually need (consensus on subjective state) for the thing they actually wanted (verifiable transitions). Strip the consensus, keep the verification. You get more, not less. A Turing complete substrate already contains every program a smart contract could embed; the substrate is the bigger set.
Conventional blockchains pick one tape format (state-machine deltas) and one consensus discipline (totally ordered chain over a globally shared ledger). That is a restriction on the substrate, not an extension. They buy timestamp-server ordering for state transitions. Proofchains do not need that ordering for logical validity. Strip the consensus, keep the verification. You get more, not less. A Turing complete substrate already contains every program a smart contract could embed; the substrate is the bigger set.
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Hyphenate compound adjective at Line 110.

Use “Turing-complete substrate” instead of “Turing complete substrate” for correct compound-adjective usage.

🧰 Tools
🪛 LanguageTool

[grammar] ~110-~110: Use a hyphen to join words.
Context: ...cation. You get more, not less. A Turing complete substrate already contains ever...

(QB_NEW_EN_HYPHEN)

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/papers/03-substrate-not-blockchain.md` at line 110, Replace the
unhyphenated compound adjective "Turing complete substrate" with the hyphenated
form "Turing-complete substrate" in the sentence that reads "A Turing complete
substrate already contains every program a smart contract could embed; the
substrate is the bigger set." to correctly form the compound adjective.

@TSavo TSavo force-pushed the codex/proofchain-docs branch 4 times, most recently from 8eb8587 to 1a601c5 Compare May 9, 2026 00:01
@TSavo TSavo force-pushed the codex/proofchain-docs branch from 1a601c5 to 97c33d6 Compare May 9, 2026 00:03
@TSavo TSavo merged commit d05a8c1 into main May 9, 2026
3 checks passed
@TSavo TSavo review requested due to automatic review settings May 9, 2026 00:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant