isomorphic-shift/docs/architecture.md

Isomorphic Shift Architecture — Complete Specification

Version: 1.0
Status: DESIGN & FOUNDATION COMPLETE
Authority: Prolog/Datalog source-of-truth
Last Updated: 2026-07-27

---

Table of Contents

1. Overview
2. Core Concepts
3. Eight Required Mappings
4. Authority Model
5. Transaction Model
6. Error Handling
7. Integration Points
8. Implementation Roadmap

---

Overview

The Isomorphic Shift layer is a formally-defined translation system that bridges multiple representation domains:

• Notebook Instructions (EmojiCode, HolyC, Python, JavaScript, Ada)
• Canonical Intermediate Representation (ISIR) (deterministic, CBOR-encoded)
• Logic Terms (Prolog/Datalog for reasoning)
• Authorized Decisions (with proof of authorization)
• Runtime Commands (executable on Rust, Erlang, LLVM, Ada targets)
• Formal Proofs (Lean 4, Agda proof obligations)
• Execution Events (runtime state changes)
• Receipts (WORM-sealed evidence of execution)
• Notebook Cells (Jupyter cells with sealed outputs)

Every transformation is bidirectional (or explicitly marked lossy), semantically preserving, authority-preserving, and invertible.

---

Core Concepts

Round-Trip Law

The fundamental property: For any isomorphic shift M,

inverse(forward(X)) = canonicalize(X)
forward(inverse(Y)) = canonicalize(Y)

This guarantees that information is not lost in either direction.

Semantic Preservation

All transformations preserve:

• Meaning: The runtime behavior of the transformed value
• Types: Numeric types, arrays, unions, capabilities
• Authority: Permissions, proof status, release status
• Structure: Argument count, ordering, nesting

Authority Preservation

Isomorphic Shift MUST NOT:

• Increase permissions (e.g., read-only → read-write)
• Change proof verification status (e.g., failed → passed)
• Modify release status (e.g., development → production)
• Escalate agent trust level
• Remove revocations

Classification

Each shift is classified as:

• Isomorphism: Fully bidirectional, bijective (round-trip perfect)
• Partial Isomorphism: Bidirectional but lossy in one direction (e.g., projection)
• Embedding: One-way injection into larger space
• Projection: One-way extraction from larger space
• Normalization: One-way canonicalization
• Serialization: One-way encoding to portable form

---

Eight Required Mappings

M1: SurfaceInstruction ↔ CanonicalInstruction

Direction: Bidirectional (full isomorphism)
Classification: Normalization
Source Domains: EmojiCode, HolyC, Python, JavaScript, Ada
Target: Deterministic CBOR-encoded canonical form

Forward Mapping:

1. Parse surface syntax for language
2. Extract verb and arguments
3. Validate shell safety (no metacharacters)
4. Reorder arguments in canonical order
5. Encode as deterministic CBOR
6. Compute Blake3 hash
7. Wrap in ISIR with metadata

Inverse Mapping:

1. Decode CBOR
2. Extract verb and arguments
3. Reconstruct surface syntax for target language
4. Validate reconstructed syntax
5. Verify round-trip: parse reconstructed, compare to original

Invariants Preserved:

• verb_identity
• argument_identity
• type_preservation
• authorization_identity

Example:

Forward:  ⚡ fn:FreqAnchor1618
→ CanonicalInstruction(verb=execute, args=[fn, FreqAnchor1618])

Inverse:  CanonicalInstruction(verb=execute, args=[fn, FreqAnchor1618])
→ ⚡ fn:FreqAnchor1618

M2: CanonicalInstruction ↔ LogicTerm

Direction: Bidirectional (full isomorphism)
Classification: Serialization
Source: Canonical instruction (CBOR)
Target: Prolog logic term (ground, fully instantiated)

Forward Mapping:

1. Decode CBOR from canonical instruction
2. Extract verb → functor
3. Extract arguments → argument list
4. Convert each argument type to Prolog representation
5. Ground all variables (instantiate with concrete values)
6. Construct logic_term(functor, args)

Inverse Mapping:

1. Extract functor → verb
2. Extract args → argument list
3. Convert Prolog types back to canonical types
4. Reconstruct canonical instruction
5. Encode as CBOR

Invariants Preserved:

• functor_identity
• argument_identity
• grounding_identity
• type_correspondence

Example:

Forward:  canonical_instruction(execute, [fn, 1618])
→ logic_term(execute, [fn, 1618])

Inverse:  logic_term(execute, [fn, 1618])
→ canonical_instruction(execute, [fn, 1618])

M3: AuthorizedLogicDecision → RuntimeCommand

Direction: Primarily forward (projection)
Classification: Projection (lossy in inverse)
Source: Authorized logic decision (with Prolog proof)
Target: Executable runtime command

Forward Mapping:

1. Extract agent and decision from authorized decision
2. Validate agent has sufficient trust for target
3. Query authorization rules: can_perform_shift/3
4. If authorized, extract command semantics
5. Map decision functor to runtime opcode
6. Map arguments to operands
7. Construct runtime_command(target, opcode, operands, context)

Inverse Mapping (Partial):

1. Extract opcode → decision functor
2. Extract operands → arguments
3. Reconstruct authorized_decision
4. Note: Authorization context may be lost (projection)

Invariants Preserved:

• semantics_preservation
• target_executability
• safety_preservation

Authorization Check:

• Agent must have execute permission
• Decision must pass authorization rules
• No permission escalation allowed

Example:

Forward:  authorized_decision(builder, logic_term(execute, [fn, 1618]), proof_hash, ts)
→ runtime_command(rust, execute_fn, [1618], {...})

Inverse:  runtime_command(rust, execute_fn, [1618], {...})
→ authorized_decision(?, logic_term(execute, [?, ?]), ?, ?)  [PARTIAL]

M4: ProofObligation ↔ VerifierInvocation

Direction: Bidirectional (full isomorphism)
Classification: Embedding
Source: Formal proof obligation
Target: Verifier invocation with result

Forward Mapping:

1. Extract theorem name and goal from obligation
2. Generate Blake3 hash of (theorem, hypotheses, goal)
3. Invoke verifier (Lean 4 or Agda)
4. Capture verification status (pending/verified/failed/timeout)
5. Wrap in verifier_invocation(proof_id, verifier, status, code, timestamp)

Inverse Mapping:

1. Extract proof_id
2. Extract theorem name from proof_code
3. Extract goal from proof_code
4. Reconstruct proof_obligation

Invariants Preserved:

• obligation_correspondence
• status_integrity
• proof_code_identity

Example:

Forward:  proof_obligation(Borrow_Step_Sound, [carry, borrow], goal_formula, bridge_verifier)
→ verifier_invocation(hash_xyz, lean4, verified, code, 1727404800)

Inverse:  verifier_invocation(hash_xyz, lean4, verified, code, 1727404800)
→ proof_obligation(Borrow_Step_Sound, [...], goal_formula, bridge_verifier)

M5: ExecutionEvent ↔ LogicEventFact

Direction: Bidirectional (full isomorphism)
Classification: Serialization
Source: Runtime execution event
Target: Prolog logic fact

Forward Mapping:

1. Extract event_id from event
2. Extract agent, action, outcome
3. Classify outcome (success/blocked/failed/timeout)
4. Generate WORM seal
5. Construct logic_event_fact(event_id, agent, action, outcome, worm_seal)

Inverse Mapping:

1. Extract event_id → find original event
2. Reconstruct execution_event from fact data
3. Verify WORM seal unchanged

Invariants Preserved:

• event_correspondence
• outcome_integrity
• worm_immutability

Example:

Forward:  execution_event(hash_abc, 1727404800, builder, generate, {result: ok}, parent_hash)
→ logic_event_fact(hash_abc, builder, generate, success, worm_seal_xyz)

Inverse:  logic_event_fact(hash_abc, builder, generate, success, worm_seal_xyz)
→ execution_event(hash_abc, 1727404800, builder, generate, {...}, parent_hash)

M6: ExecutionEvent → ReceiptRecord

Direction: Primarily forward (projection)
Classification: Projection (lossy in inverse)
Source: Execution event
Target: WORM-sealed receipt record

Forward Mapping:

1. Extract event_id from event
2. Generate receipt_id = hash(event_id, timestamp, authorization_proof)
3. Query authorization: was this event authorized?
4. Generate authorization_proof = hash(Prolog query result)
5. Determine verification_status (authorized/provisional/denied)
6. Generate WORM seal
7. Construct receipt_record(receipt_id, event_id, auth_proof, status, worm_seal, timestamp)

Inverse Mapping (Partial):

1. Extract event_id from receipt
2. Reconstruct partial execution_event
3. Note: Receipt-specific sealing and authorization proof may not be fully recoverable

Invariants Preserved:

• event_ancestry
• authorization_integrity
• worm_immutability
• timestamp_immutability

Example:

Forward:  execution_event(hash_abc, 1727404800, sentinel, verify, {...}, ...)
→ receipt_record(hash_receipt, hash_abc, proof_hash, authorized, worm_xyz, 1727404800)

Inverse:  receipt_record(hash_receipt, hash_abc, proof_hash, authorized, worm_xyz, 1727404800)
→ execution_event(hash_abc, 1727404800, sentinel, verify, {...}, ...)  [PARTIAL]

M7: NotebookCellRecord ↔ LogicCellFact

Direction: Bidirectional (full isomorphism)
Classification: Serialization
Source: Jupyter notebook cell
Target: Prolog logic fact

Forward Mapping:

1. Extract cell_id from notebook cell
2. Extract cell_type (code/markdown/raw)
3. Parse cell source to extract instructions
4. Extract proof obligations from cell comments
5. Generate WORM seal
6. Construct logic_cell_fact(cell_id, cell_type, instructions, obligations, worm_seal)

Inverse Mapping:

1. Extract cell_id
2. Find original notebook cell
3. Reconstruct cell record from fact

Invariants Preserved:

• cell_correspondence
• instruction_extraction_completeness
• worm_immutability

Example:

Forward:  notebook_cell(hash_c1, code, "⚡ fn:1618", [outputs], 5, metadata)
→ logic_cell_fact(hash_c1, code, [logic_term(execute, [fn, 1618])], [], worm_seal_m)

Inverse:  logic_cell_fact(hash_c1, code, [logic_term(execute, [fn, 1618])], [], worm_seal_m)
→ notebook_cell(hash_c1, code, "⚡ fn:1618", [...], 5, ...)

M8: RuntimeSpecificValue ↔ CanonicalValue

Direction: Bidirectional (full isomorphism)
Classification: Normalization
Source: Language-specific value (i32, f64, string, array, capability)
Target: Language-neutral canonical representation

Forward Mapping:

1. Inspect runtime value type
2. Map to canonical type:
   • i32, i64, u32, u64 → integer
   • f32, f64, f128 → float (with precision tag)
   • bool → boolean
   • string → string
   • bytes → bytes
   • array → list (with rank/shape)
   • map → map
   • tagged union → tagged_union
   • capability → capability_ref
   • hash/proof → hash_ref
3. Encode value as deterministic CBOR
4. Preserve all type information in type_tag
5. Construct canonical_value(type, cbor_bytes, type_tag)

Inverse Mapping:

1. Extract CBOR bytes
2. Decode using type_tag
3. Reconstruct runtime value in source language
4. Verify no type loss (array rank preserved, etc.)

Invariants Preserved:

• type_preservation
• value_preservation
• no_precision_loss
• no_capability_escalation

Example:

Forward:  runtime_value(i64, 1618, {})
→ canonical_value(integer, cbor_hex, i64_tag)

Inverse:  canonical_value(integer, cbor_hex, i64_tag)
→ runtime_value(i64, 1618, {})

---

Authority Model

Permission Hierarchy

none < read < write < execute < seal < verify < admin

Agent Classes

• sentinel: sovereign trust (all permissions)
• oracle: high trust (read, analyze only)
• builder: high trust (read, write, generate, execute, seal)
• archivist: high trust (read, analyze, index, provenance)
• berserker: medium trust (read, analyze, inject)

Shift Authorization

Each shift requires specific capabilities:

Shift	Required Capability	Min Trust
M1	read, write	low
M2	read, analyze	medium
M3	execute	high
M4	verify	high
M5	read, analyze	medium
M6	seal	high
M7	read, analyze	medium
M8	read, write	low

Rule: Agent must have required capability AND sufficient trust level.

Absolute Prohibition: No shift can escalate permissions or proof status.

---

Transaction Model

State Machine

   parsed
     ↓
 validated
     ↓
authorized  ← [Prolog query rejected: → rejected]
     ↓
transformed  ← [Adapter error: → failed]
     ↓
invariants_checked  ← [Invariant violated: → rejected]
     ↓
committed  ← [If applicable]
     ↓
receipted
     ↓
  [done]

Atomicity

• Commit phase: Write result and receipt atomically
• Failure: Automatic rollback
• Idempotency: Same (transaction_id, canonical_input) → same result from ledger

Transaction Record

{
  "transaction_id": "blake3_hash",
  "shift_id": "M1",
  "agent": "builder",
  "source_value": "...",
  "target_value": "...",
  "timestamp": 1727404800,
  "state": "committed",
  "receipt_hash": "blake3_hash",
  "error": null
}

---

Error Handling

Rejection Codes

Code	Meaning	Recoverable
MALFORMED_SOURCE	Source doesn't parse	Yes (fix input)
UNKNOWN_SHIFT	Shift not registered	No
UNSUPPORTED_VERSION	Shift version not supported	Yes (upgrade)
INCOMPATIBLE_SCHEMA	Source/target schema mismatch	No
AMBIGUOUS_MAPPING	Multiple interpretations	No
LOSSY_MAPPING	Claimed isomorphism but lossy	No (use projection)
INVALID_INVERSE	Inverse doesn't match forward	No (implementation bug)
MISSING_ADAPTER	Adapter not implemented	No
TIMEOUT	Transformation took too long	Yes (retry)
AUTHORIZATION_DENIED	Agent not authorized	No
INVARIANT_VIOLATION	Invariant not preserved	No (implementation bug)
SEMANTIC_MISMATCH	Meaning not preserved	No (implementation bug)

Failure Response

{
  "error": {
    "code": "AUTHORIZATION_DENIED",
    "message": "Agent 'oracle' cannot perform M3 (execute permission required)",
    "detail": {
      "agent": "oracle",
      "shift": "M3",
      "reason": "ORACLE_READ_ONLY_VIOLATION"
    }
  }
}

---

Integration Points

Notebook System

• Input: Notebook cell source (EmojiCode, Python, etc.)
• M1: Convert to canonical instruction
• M2: Convert to logic term
• M7: Extract cell facts to Prolog
• Output: Logic facts queryable in Prolog

Runtime Execution

• Input: Authorized decision from Prolog
• M3: Convert to runtime command
• Execution: Run on Rust/Erlang/Ada runtime
• M5: Record as execution event
• M6: Generate receipt
• Output: WORM-sealed receipt in ledger

Formal Verification

• Input: Proof obligation from system
• M4: Invoke verifier (Lean 4/Agda)
• Output: Verification status and proof

LOC Agent Integration

• Source: loc_agent.rs (DEVFLOW-FINANCE/snapkitty-core)
• Triad Execution: EmojiCode → M1 → M2 → M3 → Runtime → M5/M6
• WORM Sealing: Receipt → M6 → WORM ledger

---

Implementation Roadmap

Phase 1: Foundation (Current)

• Domain definitions (domains.schema.json, domains.pl)
• Shift registration (shifts.pl)
• Authorization rules (shift_authorization.pl)
• Semantic equivalence rules (semantic_equivalence.pl)
• Invariant definitions (invariants.pl)
• Release gates (shift_release.pl)

Phase 2: Adapters

• M1 adapter: SurfaceInstruction ↔ CanonicalInstruction (Rust)
• M2 adapter: CanonicalInstruction ↔ LogicTerm (Rust)
• M3 adapter: AuthorizedLogicDecision → RuntimeCommand (Rust)
• M4 adapter: ProofObligation ↔ VerifierInvocation (Rust + FFI)
• M5 adapter: ExecutionEvent ↔ LogicEventFact (Rust)
• M6 adapter: ExecutionEvent → ReceiptRecord (Rust)
• M7 adapter: NotebookCellRecord ↔ LogicCellFact (Rust)
• M8 adapter: RuntimeSpecificValue ↔ CanonicalValue (Rust)

Phase 3: Testing

• Round-trip tests for all isomorphic shifts
• Semantic preservation tests
• Authority tests (no permission escalation)
• Failure mode tests
• Logic integration tests

Phase 4: Integration

• Integrate with LOC agent
• Wire with Prolog reasoner
• Hook into notebook system
• WORM ledger integration
• Production deployment

---

References

• LOC Agent: /DEVFLOW-FINANCE/snapkitty-core/src/agents/loc_agent.rs
• Sovereign Kernel: /bob-orchestrator/prolog/sovereign_kernel.pl
• Notebook: /DEVFLOW-FINANCE/sovereign_notebook.ipynb
• Session Handoff: /SESSION_HANDOFF.md
• Previous Audits: /sov-kernel-monster/*.md