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:
```rust

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)