docs: harden Core 2.0 boundary and conformance documentation

README.md

@@ -20,6 +20,10 @@ The system ensures that knowledge snapshots can always be reconstructed and veri
 
 ---
 
+## Boundary Note
+
+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.
+
 ## Specification
 
 DigiEmu Core is moving toward a public standard structure for deterministic AI decision verification.
@@ -284,4 +288,4 @@ Links
 - [Docker Usage](docs/CORE_2_DOCKER_USAGE.md)
 - [OpenAPI Draft](docs/CORE_2_OPENAPI_DRAFT.md)
 - [Release Checklist](docs/CORE_2_RELEASE_CHECKLIST.md)
-- [Tagging Plan](docs/CORE_2_TAGGING_PLAN.md)
+- [Tagging Plan](docs/CORE_2_TAGGING_PLAN.md)

docs/ANDREI_REQUIREMENTS_TRACE.md

@@ -0,0 +1,15 @@
+# Andrei Requirements Trace — DigiEmu Core 2.0 Hardening
+
+| External / partner impulse | Interpreted requirement | DigiEmu Core 2.0 implementation | Status | Evidence / file reference | Remaining work |
+|---|---|---|---|---|---|
+| 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` |
+| 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` |
+| 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 |
+| 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 |
+| 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 |
+| 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 |
+| 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 |
+| 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 |
+| 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` |
+| 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` |
+| 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

@@ -0,0 +1,117 @@
+# DigiEmu Core 2.0 Conformance
+
+Status: draft / hardening phase
+
+---
+
+## Conformance Definition
+
+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.
+
+- Determinism: same input -> same canonical JSON -> same SHA-256 snapshot hash -> same verify result.
+- Independence: a third-party verifier can reproduce PASS/FAIL/ERROR with the same reason codes.
+
+---
+
+## Canonical JSON Requirement
+
+- Implement `canonical_json_v1` semantics.
+- Non-canonical serialization must be detected as a conformance failure when it changes the state identity.
+- Canonicalization scope excludes self-referential hash fields (e.g., `expected_hash_v1`).
+
+---
+
+## Snapshot Hash Requirement
+
+- Hash algorithm: `sha256(canonical_json_v1)`.
+- The same canonicalized snapshot MUST produce the exact same 64-hex digest.
+- Hash scope: explicitly excludes `expected_hash_v1` and includes all integrity-relevant fields.
+
+---
+
+## Replay Requirement
+
+- Given a bundle, the verifier MUST reconstruct the decision state deterministically using the documented reconstruction profile.
+- Any mismatch between reconstructed state and expected state MUST surface as a verification failure with a stable reason code.
+
+---
+
+## Verify Result Requirement
+
+- 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.
+- PASS/FAIL/ERROR MUST be deterministically determined from canonicalization, hashing, and replay outcomes.
+
+---
+
+## PASS / FAIL / ERROR Semantics
+
+- PASS: canonicalization and hashing succeed; computed digest equals expected; reconstruction matches profile; no schema violations.
+- FAIL: verification completes but evidence indicates mismatch (e.g., hash mismatch, rule mismatch), with a stable reason code.
+- ERROR: verification cannot complete due to malformed inputs, schema violations, or internal errors; includes a stable reason code.
+
+---
+
+## Required Test Vectors
+
+Implementations MUST pass all vectors under `testdata/core_2_conformance/`, including at minimum:
+- `basic_pass`
+- `hash_mismatch_fail`
+- `inside_payload_mutation_detected`
+- `invalid_schema_error`
+- `malformed_json_error`
+- `missing_required_field_error`
+- `outside_metadata_ignored`
+- `unknown_reason_code_error`
+- `unsupported_canonicalization_profile_error`
+- `unsupported_hash_algorithm_error`
+- `wrong_profile_fail`
+
+---
+
+## CLI Behavior
+
+- The CLI MUST support `--json` output with `pretty` and `canonical` modes.
+- In JSON mode, stdout is JSON-only; operational errors go to stderr.
+- Exit codes follow the Phase A2 contract; VERIFY failures yield a non-zero exit code.
+
+---
+
+## JSON Report Output
+
+- JSON verify results MUST validate against `schemas/VERIFY_RESULT_SCHEMA_v1.json` or `schemas/verify_result_v2.schema.json` (draft) when applicable.
+- The `--json=canonical` mode MUST produce byte-stable canonical JSON suitable for test vectors and audit evidence.
+
+---
+
+## Version Compatibility
+
+- Implementations MUST clearly declare the supported snapshot, canonicalization, and schema versions.
+- Conformance is version-bound. A change in schema or canonicalization profile requires re-validation against test vectors.
+
+---
+
+## Non-Goals
+
+- no agent identity certification
+- no trust scoring
+- no enterprise workflow
+- no legal compliance claim
+- no authorization framework
+
+---
+
+## CLI Examples
+
+Example: verify a bundle with canonical JSON output to stdout:
+
+```bash
+go run ./cmd/digiemu verify --bundle examples/bundles/demo_ok_bundle_v1/snapshots/snapshot_demo_v1 --json=canonical
+```
+
+Example: run conformance and emit a canonical JSON report:
+
+```bash
+go run ./cmd/digiemu experimental conformance run testdata/core_2_conformance --json=canonical
+```
+
+The resulting JSON MUST validate against `schemas/VERIFY_RESULT_SCHEMA_v1.json` or the v2 draft schema where explicitly used.

docs/RELEASE_SAFETY.md

@@ -0,0 +1,61 @@
+# Release Safety — Go Module and Tagging Strategy
+
+Status: draft / hardening phase
+
+---
+
+## Current Module Path
+
+- Detected module path from `go.mod`: `digiemu-core`
+
+---
+
+## Go Semantic Import Versioning Risk
+
+- Go modules treat major versions >= v2 specially: the module path MUST end with `/v2` (or `/vN`) to safely publish a `vN.0.0` tag.
+- If you tag `v2.0.0` without changing the module path to end with `/v2`, downstream `go get` may break or resolve incorrectly.
+
+---
+
+## Unsafe Tags
+
+- Using real `v2.0.0` (or `v2.x.y`) tags with a module path that does not end with `/v2` is unsafe.
+
+---
+
+## Safe Milestone Names
+
+Use pre-release milestone tags and names that do not trigger Go's major-version handling:
+
+- core-2.0-draft4
+- core-2.0-rc1
+- core-2.0-spec-stable
+- core-2-draft4-self-audit
+
+These are safe as Git tags or GitHub Releases notes, because they are not semantic import versions to the Go toolchain.
+
+---
+
+## When Real v2.0.0 Is Allowed
+
+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.
+
+- Update `module` directive in `go.mod` to `github.com/DigiEmu/core/v2`.
+- Update all internal imports to the new path.
+- Update README install instructions and examples.
+- Verify `go get github.com/DigiEmu/core/v2@v2.0.0` works in a clean module cache.
+
+---
+
+## Recommended Current Release Strategy
+
+- Do NOT publish real `v2.0.0` tags while the module path does not end with `/v2`.
+- Use safe milestone names listed above for partner-testable drafts and RCs.
+- Keep Core 2.0 in draft/RC tags until documentation and conformance are stable.
+- When ready to cut `v2.0.0`, perform a dedicated PR that updates the module path, internal imports, CI, and docs, then tag.
+
+---
+
+## Warning
+
+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

@@ -339,4 +339,15 @@ No release should be described as enterprise-ready unless:
 - full test suite passes
 - byte-exact repro tests pass
 - determinism guard findings are either zero or explicitly documented and approved
-- this threat model remains materially accurate
+- this threat model remains materially accurate
+---
+
+## Core 2.0 Verification Boundary Addendum
+
+DigiEmu Core 2.0 is limited to deterministic decision-state reconstruction and verification.
+
+It detects modified snapshots, hash mismatches, schema violations, non-canonical serialization problems, replay mismatches, malformed verification inputs, and incompatible schema or core versions.
+
+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.
+
+Agent identity, trust certification, authorization, and action attestation are outside DigiEmu Core and may be handled by complementary systems such as TBN.