Skip to content

Commit 759014f

Browse files
DigiEmuDigiEmu
committed
docs: harden Core 2.0 boundary and conformance documentation
1 parent b741a8f commit 759014f

5 files changed

Lines changed: 210 additions & 2 deletions

File tree

‎README.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,10 @@ The system ensures that knowledge snapshots can always be reconstructed and veri
2020

2121
---
2222

23+
## Boundary Note
24+
25+
DigiEmu Core verifies deterministic decision-state integrity through canonical JSON, SHA-256 snapshot hashing, and replay/verify checks. It does not certify agent identity, trustworthiness, authorization, action legitimacy, or legal compliance. These concerns belong to complementary external trust and attestation layers such as TBN.
26+
2327
## Specification
2428

2529
DigiEmu Core is moving toward a public standard structure for deterministic AI decision verification.
@@ -284,4 +288,4 @@ Links
284288
- [Docker Usage](docs/CORE_2_DOCKER_USAGE.md)
285289
- [OpenAPI Draft](docs/CORE_2_OPENAPI_DRAFT.md)
286290
- [Release Checklist](docs/CORE_2_RELEASE_CHECKLIST.md)
287-
- [Tagging Plan](docs/CORE_2_TAGGING_PLAN.md)
291+
- [Tagging Plan](docs/CORE_2_TAGGING_PLAN.md)

‎docs/ANDREI_REQUIREMENTS_TRACE.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Andrei Requirements Trace — DigiEmu Core 2.0 Hardening
2+
3+
| External / partner impulse | Interpreted requirement | DigiEmu Core 2.0 implementation | Status | Evidence / file reference | Remaining work |
4+
|---|---|---|---|---|---|
5+
| Minimal standardizable core | Keep Core small and reproducible | Core functions limited to canonicalization, hashing, replay, verify result | In progress | `cmd/digiemu/verify.go`, `cmd/digiemu/json_output.go`, `schemas/VERIFY_RESULT_SCHEMA_v1.json` | Finalize docs: `docs/CONFORMANCE.md`, prune non-core mentions in `README.md` |
6+
| Deterministic state representation | Stable snapshot structure | Canonical JSON v1 scope and stable fields for hashing | In progress | `internal/canonicaljson/`, `docs/SNAPSHOT_HASH_v1.0.md` (if present), `testdata/core_2_conformance/*` | Document explicit field scope in `CONFORMANCE.md` |
7+
| Canonical JSON serialization | Same input produces same canonical representation | `--json=canonical` path and internal canonicalization for verify outputs | Implemented | `cmd/digiemu/json_output.go`, `internal/canonicaljson/` | Add conformance note linking to schema validation |
8+
| SHA-256 state identity | Stable hash identity for snapshots | `sha256(canonical_json_v1)` for snapshot hashing | Implemented | `schemas/VERIFY_RESULT_SCHEMA_v1.json`, `cmd/digiemu/verify_*_test.go` | Expand vector coverage across edge cases |
9+
| Independent replay / reconstruction | External verifier can reproduce verification result | Replay + verify pipeline with deterministic profiles | In progress | `cmd/digiemu/replay_*.go`, `cmd/digiemu/verify_replay.go` | Publish minimal reconstruction profile note |
10+
| PASS / FAIL / ERROR semantics | Clear machine-readable verification outcome | PASS/FAIL/ERROR with reason codes | Implemented | `schemas/verify_result_v2.schema.json`, `schemas/VERIFY_RESULT_SCHEMA_v1.json` | Align README examples with schema naming |
11+
| Verify result schema | Standard report format | v1 stable schema; v2 draft | Implemented | `schemas/VERIFY_RESULT_SCHEMA_v1.json`, `schemas/verify_result_v2.schema.json` | Confirm CI validation step |
12+
| Test vectors | Conformance examples and edge cases | Core 2.0 conformance vectors | Implemented | `testdata/core_2_conformance/` | Keep vectors stable; add negative cases as needed |
13+
| CLI conformance path | Developer-testable verification path | `--json` pretty/canonical, deterministic stdout/stderr contract | Implemented | `cmd/digiemu/json_output.go`, `cmd/digiemu/verify.go` | Add explicit CLI examples in `CONFORMANCE.md` |
14+
| Separation from enterprise/governance features | No dashboards or workflow logic in Core | Core has no enterprise UI/roles/workflow | Implemented | Repo scan; absence of such features | Keep boundary statement in `THREAT_MODEL.md` |
15+
| Separation from external trust/identity layers such as TBN | DigiEmu verifies decision-state integrity, not agent trust | Identity/trust attestation is out-of-scope for Core 2.0 | Implemented (boundary) | `docs/THREAT_MODEL.md` (to be updated), `README.md` (should avoid overclaims) | Ensure README avoids implying trust certification |

‎docs/CONFORMANCE.md‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
# DigiEmu Core 2.0 Conformance
2+
3+
Status: draft / hardening phase
4+
5+
---
6+
7+
## Conformance Definition
8+
9+
An implementation is DigiEmu Core 2.0 conformant if, given the same canonical snapshot and verification inputs, it produces the same verification result as the reference implementation and passes the required test vectors.
10+
11+
- Determinism: same input -> same canonical JSON -> same SHA-256 snapshot hash -> same verify result.
12+
- Independence: a third-party verifier can reproduce PASS/FAIL/ERROR with the same reason codes.
13+
14+
---
15+
16+
## Canonical JSON Requirement
17+
18+
- Implement `canonical_json_v1` semantics.
19+
- Non-canonical serialization must be detected as a conformance failure when it changes the state identity.
20+
- Canonicalization scope excludes self-referential hash fields (e.g., `expected_hash_v1`).
21+
22+
---
23+
24+
## Snapshot Hash Requirement
25+
26+
- Hash algorithm: `sha256(canonical_json_v1)`.
27+
- The same canonicalized snapshot MUST produce the exact same 64-hex digest.
28+
- Hash scope: explicitly excludes `expected_hash_v1` and includes all integrity-relevant fields.
29+
30+
---
31+
32+
## Replay Requirement
33+
34+
- Given a bundle, the verifier MUST reconstruct the decision state deterministically using the documented reconstruction profile.
35+
- Any mismatch between reconstructed state and expected state MUST surface as a verification failure with a stable reason code.
36+
37+
---
38+
39+
## Verify Result Requirement
40+
41+
- The implementation MUST emit verify results that validate against `schemas/VERIFY_RESULT_SCHEMA_v1.json` (v1) or `schemas/verify_result_v2.schema.json` (v2 draft) when in the respective mode.
42+
- PASS/FAIL/ERROR MUST be deterministically determined from canonicalization, hashing, and replay outcomes.
43+
44+
---
45+
46+
## PASS / FAIL / ERROR Semantics
47+
48+
- PASS: canonicalization and hashing succeed; computed digest equals expected; reconstruction matches profile; no schema violations.
49+
- FAIL: verification completes but evidence indicates mismatch (e.g., hash mismatch, rule mismatch), with a stable reason code.
50+
- ERROR: verification cannot complete due to malformed inputs, schema violations, or internal errors; includes a stable reason code.
51+
52+
---
53+
54+
## Required Test Vectors
55+
56+
Implementations MUST pass all vectors under `testdata/core_2_conformance/`, including at minimum:
57+
- `basic_pass`
58+
- `hash_mismatch_fail`
59+
- `inside_payload_mutation_detected`
60+
- `invalid_schema_error`
61+
- `malformed_json_error`
62+
- `missing_required_field_error`
63+
- `outside_metadata_ignored`
64+
- `unknown_reason_code_error`
65+
- `unsupported_canonicalization_profile_error`
66+
- `unsupported_hash_algorithm_error`
67+
- `wrong_profile_fail`
68+
69+
---
70+
71+
## CLI Behavior
72+
73+
- The CLI MUST support `--json` output with `pretty` and `canonical` modes.
74+
- In JSON mode, stdout is JSON-only; operational errors go to stderr.
75+
- Exit codes follow the Phase A2 contract; VERIFY failures yield a non-zero exit code.
76+
77+
---
78+
79+
## JSON Report Output
80+
81+
- JSON verify results MUST validate against `schemas/VERIFY_RESULT_SCHEMA_v1.json` or `schemas/verify_result_v2.schema.json` (draft) when applicable.
82+
- The `--json=canonical` mode MUST produce byte-stable canonical JSON suitable for test vectors and audit evidence.
83+
84+
---
85+
86+
## Version Compatibility
87+
88+
- Implementations MUST clearly declare the supported snapshot, canonicalization, and schema versions.
89+
- Conformance is version-bound. A change in schema or canonicalization profile requires re-validation against test vectors.
90+
91+
---
92+
93+
## Non-Goals
94+
95+
- no agent identity certification
96+
- no trust scoring
97+
- no enterprise workflow
98+
- no legal compliance claim
99+
- no authorization framework
100+
101+
---
102+
103+
## CLI Examples
104+
105+
Example: verify a bundle with canonical JSON output to stdout:
106+
107+
```bash
108+
go run ./cmd/digiemu verify --bundle examples/bundles/demo_ok_bundle_v1/snapshots/snapshot_demo_v1 --json=canonical
109+
```
110+
111+
Example: run conformance and emit a canonical JSON report:
112+
113+
```bash
114+
go run ./cmd/digiemu experimental conformance run testdata/core_2_conformance --json=canonical
115+
```
116+
117+
The resulting JSON MUST validate against `schemas/VERIFY_RESULT_SCHEMA_v1.json` or the v2 draft schema where explicitly used.

‎docs/RELEASE_SAFETY.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
# Release Safety — Go Module and Tagging Strategy
2+
3+
Status: draft / hardening phase
4+
5+
---
6+
7+
## Current Module Path
8+
9+
- Detected module path from `go.mod`: `digiemu-core`
10+
11+
---
12+
13+
## Go Semantic Import Versioning Risk
14+
15+
- Go modules treat major versions >= v2 specially: the module path MUST end with `/v2` (or `/vN`) to safely publish a `vN.0.0` tag.
16+
- If you tag `v2.0.0` without changing the module path to end with `/v2`, downstream `go get` may break or resolve incorrectly.
17+
18+
---
19+
20+
## Unsafe Tags
21+
22+
- Using real `v2.0.0` (or `v2.x.y`) tags with a module path that does not end with `/v2` is unsafe.
23+
24+
---
25+
26+
## Safe Milestone Names
27+
28+
Use pre-release milestone tags and names that do not trigger Go's major-version handling:
29+
30+
- core-2.0-draft4
31+
- core-2.0-rc1
32+
- core-2.0-spec-stable
33+
- core-2-draft4-self-audit
34+
35+
These are safe as Git tags or GitHub Releases notes, because they are not semantic import versions to the Go toolchain.
36+
37+
---
38+
39+
## When Real v2.0.0 Is Allowed
40+
41+
A real `v2.0.0` tag is only safe if the module path is changed to `github.com/DigiEmu/core/v2` and all imports and installation instructions are updated accordingly.
42+
43+
- Update `module` directive in `go.mod` to `github.com/DigiEmu/core/v2`.
44+
- Update all internal imports to the new path.
45+
- Update README install instructions and examples.
46+
- Verify `go get github.com/DigiEmu/core/v2@v2.0.0` works in a clean module cache.
47+
48+
---
49+
50+
## Recommended Current Release Strategy
51+
52+
- Do NOT publish real `v2.0.0` tags while the module path does not end with `/v2`.
53+
- Use safe milestone names listed above for partner-testable drafts and RCs.
54+
- Keep Core 2.0 in draft/RC tags until documentation and conformance are stable.
55+
- When ready to cut `v2.0.0`, perform a dedicated PR that updates the module path, internal imports, CI, and docs, then tag.
56+
57+
---
58+
59+
## Warning
60+
61+
Do not use real Git tags starting with `v2.0.0` unless the Go module path intentionally ends in `/v2` and all internal imports are updated accordingly.

‎docs/THREAT_MODEL.md‎

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -339,4 +339,15 @@ No release should be described as enterprise-ready unless:
339339
- full test suite passes
340340
- byte-exact repro tests pass
341341
- determinism guard findings are either zero or explicitly documented and approved
342-
- this threat model remains materially accurate
342+
- this threat model remains materially accurate
343+
---
344+
345+
## Core 2.0 Verification Boundary Addendum
346+
347+
DigiEmu Core 2.0 is limited to deterministic decision-state reconstruction and verification.
348+
349+
It detects modified snapshots, hash mismatches, schema violations, non-canonical serialization problems, replay mismatches, malformed verification inputs, and incompatible schema or core versions.
350+
351+
It does not prove that an AI decision was ethically correct, that model reasoning was truthful, that a human operator acted responsibly, that an agent identity is trusted, that an action was authorized, that a deployed system is legally compliant, or that a model or agent is certified.
352+
353+
Agent identity, trust certification, authorization, and action attestation are outside DigiEmu Core and may be handled by complementary systems such as TBN.

0 commit comments

Comments
 (0)