isomorphic-shift/README.md

Isomorphic Shift — Formal Translation & State Correspondence Layer

Repository: SnapKitty Collective
Status: IMPLEMENTATION IN PROGRESS
Authority: Datalog/Prolog source-of-truth
Governance Motto: EVIDENCE OR SILENCE

---

Mission

The Isomorphic Shift layer provides formally defined, bidirectional transformations connecting:

1. Notebook Instructions → Surface-level operation requests (EmojiCode, HolyC, Ada, Python, JavaScript)
2. Runtime Representations → Executable states (Rust, Erlang, Lean 4 proof obligations)
3. Proof Representations → Formal verification goals (Lean 4, Agda theorems)
4. Execution Events → Runtime state transitions logged to WORM
5. Receipt Records → Immutable evidence of execution and authorization

Each mapping is:

• Bidirectional with verified round-trip laws
• Semantically preserving (meaning survives transformation)
• Authority-preserving (no unauthorized permission escalation)
• Invertible (unless explicitly rejected as unsupported)
• Classified by category (isomorphism, embedding, projection, normalization, serialization, etc.)

---

Core Principle: Round-Trip Laws

For every isomorphic shift M:

• Forward then Inverse: inverse(forward(X)) = canonicalize(X)
• Inverse then Forward: forward(inverse(Y)) = canonicalize(Y)
• Semantic Preservation: meaning(X) = meaning(forward(X))
• Authority Preservation: Shifts must NOT increase permissions, proof status, or release status

Lossy transformations are explicitly rejected as non-isomorphic.

---

Eight Required Mappings (M1–M8)

ID	Source Domain	Target Domain	Direction	Classification	Status
M1	SurfaceInstruction	CanonicalInstruction	↔	Normalization	Design
M2	CanonicalInstruction	LogicTerm	↔	Serialization	Design
M3	AuthorizedLogicDecision	RuntimeCommand	↔	Projection	Design
M4	ProofObligation	VerifierInvocation	↔	Embedding	Design
M5	ExecutionEvent	LogicEventFact	↔	Serialization	Design
M6	ExecutionEvent	ReceiptRecord	→	Projection	Design
M7	NotebookCellRecord	LogicCellFact	↔	Serialization	Design
M8	RuntimeSpecificValue	CanonicalValue	↔	Normalization	Design

---

Canonical Intermediate Representation (ISIR)

All shifts pass through a deterministic canonical form with fields:

• schema_version: u32 — Versioning
• shift_id: String — Unique shift identifier
• shift_version: u32 — Shift-specific version
• source_domain: String — Domain of origin
• target_domain: String — Target domain
• direction: String — "forward", "inverse", or "bidirectional"
• value_type: String — "instruction", "decision", "event", "proof", "receipt", etc.
• payload: Vec<u8> — CBOR-encoded canonical representation
• invariant_set: Vec<String> — List of preserved invariants
• required_permission: String — Authorization level required
• source_hash: String — Blake3 hash of source
• canonical_hash: String — Blake3 hash of canonical form (deterministic)
• parent_receipt_hash: Option<String> — Ancestry chain

Canonical encoding: Deterministic CBOR (RFC 7049) with canonical item ordering.

---

Authority Protocol (12-Step Sequence)

1. Parse source → Validate syntax
2. Validate source schema → Check structural requirements
3. Canonicalize → Produce deterministic ISIR
4. Identify shift → Look up M1–M8 mapping
5. Query Prolog → Check authorization facts and rules
6. Validate schema compatibility → Verify domain/codomain match
7. Execute bounded transformation → Apply adapter with timeout
8. Validate target → Check output schema
9. Verify invariants → Confirm all invariants preserved
10. Generate evidence → Produce manifest and receipt
11. Commit transaction (if applicable) → Atomic append to ledger
12. Append receipt → WORM-seal the result

---

Datalog/Prolog Integration

Source-of-truth authority: All shifts, domains, schemas, authorizations, and permissions are registered as Prolog facts.

Required files:

• logic/shifts.pl — All isomorphic shifts registered
• logic/domains.pl — Domain definitions with types and constraints
• logic/schemas.pl — Schema versions and compatibility rules
• logic/invariants.pl — Preserved invariants per shift
• logic/shift_authorization.pl — Authorization rules
• logic/shift_validity.pl — Validity checking rules
• logic/semantic_equivalence.pl — Semantic preservation rules
• logic/shift_release.pl — Release-readiness rules

Prohibition: Isomorphic Shift MUST NOT maintain independent copies of:

• Capabilities or revocations
• Proof verification status
• Release status
• Authorization decisions

All queries flow through Prolog.

---

Implementation Stack

Rust Adapters (adapters/)

• m1_surface_to_canonical.rs — Surface instruction normalization
• m2_canonical_to_logic.rs — Canonical to logic term serialization
• m3_logic_to_runtime.rs — Authorized logic decision to runtime command
• m4_proof_to_verifier.rs — Proof obligation to verifier invocation
• m5_event_to_logic.rs — Execution event to logic event fact
• m6_event_to_receipt.rs — Execution event to receipt record
• m7_notebook_to_logic.rs — Notebook cell to logic cell fact
• m8_value_normalization.rs — Runtime value to canonical value

Each adapter implements:

pub fn forward(source: &Source) -> Result<Target, ShiftError>
pub fn inverse(target: &Target) -> Result<Source, ShiftError>
pub fn verify_round_trip(source: &Source) -> Result<bool, ShiftError>

Logic Engine (logic/)

• Facts: Shift definitions, domain definitions, schema versions
• Rules: Authorization, validity checking, semantic equivalence
• Queries: shift_available/1, shift_permitted/3, round_trip_verified/2
• Tests: Logic-level tests for rule correctness

Tests (tests/)

• RoundTrip: Forward→Inverse→canonicalize, Inverse→Forward→canonicalize
• SemanticPreservation: Meaning, types, authority survive
• Authority: No permission escalation, no proof status change
• Failure: Malformed rejected, unsupported versions rejected, lossy mappings rejected
• Logic: Unregistered shifts denied, unauthorized agents denied, contradictions detected

---

Transaction Model

States

• prepared — Source parsed, schema validated
• validated — Canonical form generated, shift identified
• authorized — Prolog authorization successful
• transformed — Adapter executed successfully
• invariants_checked — All invariants verified
• committed — Transaction written to ledger (if applicable)
• receipted — Receipt WORM-sealed
• rejected — Operation denied (authorization, validation, or semantic failure)
• failed — Adapter timeout, malformed target, or other runtime error

Atomicity

• Commit all or nothing
• Failed stages → automatic rollback

Idempotency

• Same transaction ID + canonical input → returns existing result from ledger

---

Evidence Bundle

All completed shifts produce:

1. Manifest — Metadata about the shift (source, target, timestamp, adapters used)
2. Receipt — WORM-sealed proof of execution
3. Invariant Proof — Evidence that all invariants were preserved
4. Authorization Log — Prolog query results proving authorization
5. Test Results — Round-trip verification evidence

---

Restrictions

✗ NO additional sub-agents
✗ NO destructive repository operations
✗ NO deletion of existing Isomorphic Shift artifacts
✗ NO Git history rewriting
✗ NO replacing functioning implementations without evidence
✗ NO self-authorized runtime mutations
✗ NO isomorphism claims without verified inverse behavior
✗ NO completion reports based on scaffolding

---

Directories

isomorphic-shift/
├── README.md (this file)
├── schemas/
│   ├── domains.schema.json
│   ├── canonical.schema.json
│   ├── shift.schema.json
│   └── receipt.schema.json
├── logic/
│   ├── shifts.pl
│   ├── domains.pl
│   ├── schemas.pl
│   ├── invariants.pl
│   ├── shift_authorization.pl
│   ├── shift_validity.pl
│   ├── semantic_equivalence.pl
│   ├── shift_release.pl
│   └── tests/
├── adapters/
│   ├── lib.rs
│   ├── m1_surface_to_canonical.rs
│   ├── m2_canonical_to_logic.rs
│   ├── m3_logic_to_runtime.rs
│   ├── m4_proof_to_verifier.rs
│   ├── m5_event_to_logic.rs
│   ├── m6_event_to_receipt.rs
│   ├── m7_notebook_to_logic.rs
│   ├── m8_value_normalization.rs
│   └── tests/
├── proofs/
│   ├── round_trip_laws.lean
│   ├── semantic_preservation.lean
│   └── authority_preservation.lean
├── tests/
│   ├── round_trip_tests.rs
│   ├── semantic_preservation_tests.rs
│   ├── authority_tests.rs
│   ├── failure_tests.rs
│   └── logic_integration_tests.rs
├── evidence/
│   ├── manifests/
│   ├── receipts/
│   └── invariant_proofs/
└── docs/
    ├── architecture.md
    ├── mapping-catalog.md
    ├── invariants.md
    ├── source-of-truth-integration.md
    ├── threat-model.md
    └── limitations.md

---

Next Steps

1. Define domain types and constraints (domains.pl, domains.schema.json)
2. Implement M1–M8 adapters with round-trip verification
3. Register shifts in Prolog (shifts.pl)
4. Implement authorization rules (shift_authorization.pl)
5. Build and test adapters
6. Integrate with existing notebook/ledger systems
7. Generate evidence bundle

---

References

• LOC Agent: DEVFLOW-FINANCE/snapkitty-core/src/agents/loc_agent.rs (Triad execution)
• Sovereign Kernel: bob-orchestrator/prolog/sovereign_kernel.pl (Authorization logic)
• Bifrost Transform: DEVFLOW-FINANCE/collectivekitty/lib/bifrost/transform.ts (Event transformation pattern)
• EmojiCode Mapping: EmojiCode → HolyC/Ada/Rust/Haskell (loc_agent.rs emoji_map)
• Notebook: DEVFLOW-FINANCE/sovereign_notebook.ipynb (Triad pipeline trace)