[Shards-inc]

Objective — reproducible offline acceptance demo for #69

A developer can python -m pip install -e ".[crypto]" and run shards-kernel demo --json without writing custom glue. The scenario exercises seven real local governance decisions:

1. Missing permit DENY
2. Valid Ed25519 permit, exact actor/audience/parameters, ALLOW for built-in echo
3. Duplicate permit DENY/replay
4. Changed tool argument DENY/scope
5. Expired signed permit DENY
6. Revoked signing public key DENY
7. Restore verified ledger evidence to fresh kernel; repeat original permit DENY.

Every gate is individually asserted; command returns non-zero on failure, redacts exception details and never reports production_ready=true. Includes unit tests and operator documentation.

Proof required

• Python 3.9–3.12 CI/coverage, security scans, docs and smoke checks all pass
• Demonstration executable via installed CLI and JSON output verifiable
• Test audit restoration and prevent misleading production readiness

Explicit limitations

The issuer key is ephemeral in the same demo process, clock virtual, ledger copied in-memory, and transport not an independently authenticated remote MCP connection. These are production blockers under #68/#69/#63, not claims that those issues are solved. No wallets, financial operations or network calls.

[codacy-production]

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

🟢 Metrics 30 complexity · 0 duplication

Metric	Results
Complexity	30
Duplication	0

View in Codacy

AI Reviewer: first review requested successfully. AI can make mistakes. Always validate suggestions.

_{TIP This summary will be updated as you push new changes.}

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-11-02T00:55:05.270397Z	0f8aaf4	Draft marked ready

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[codacy-production]

Pull Request Overview

⚠️ Resolve issues before merging

The scope-mismatch gate reuses a permit after successful consumption, so replay detection may occur before parameter validation. This means the demonstration does not independently prove parameter enforcement and can fail its own acceptance sequence. A fresh permit should be used for that gate.

The installed-command workflow is not covered by the current tests, leaving one acceptance scenario unverified.

Test suggestions

• Run the complete seven-gate scenario and verify every gate passes.
• Verify valid permit execution invokes the built-in echo behavior.
• Verify JSON CLI output is parseable and explicitly non-production.
• Verify human-readable CLI output includes every gate.
• Verify a failed gate produces a nonzero exit code.
• Verify exception contents and sensitive values are redacted.
• Verify evidence restoration into a fresh kernel preserves replay denial.
• Verify the installed CLI works in a subprocess/environment matching the documented installation flow.

Prompt proposal for missing tests

Consider implementing these tests if applicable:
1. Verify the installed CLI works in a subprocess/environment matching the documented installation flow.

_{TIP Improve review quality by adding custom instructions
TIP How was this review? Give us feedback}

[codacy-production]

_{🔴 HIGH RISK}

Use a fresh, otherwise-valid permit for the changed-parameter request, preserving the original permit for the successful execution and replay gates.

_{TIP React 👍 if this review is right, or reply with what's wrong and how it could be better to help improve the reviewer.}

[codacy-production]

_{⚪ LOW RISK}

Suggestion: Describe the scenario as behaviorally reproducible rather than deterministic, or use fixed cryptographic inputs for this non-production harness.

_{TIP React 👍 if this review is right, or reply with what's wrong and how it could be better to help improve the reviewer.}