uor-model.md

Universal Object Reference (UOR) Model

The UOR Model provides a meta-mathematical framework for defining and manipulating ontologies using the principles of prime decomposition, observer invariance, and coherence. This document details the model's architecture, implementation, and usage patterns.

Core Principles

The UOR Model embodies the essential principles of the UOR Framework:

1. Prime Decomposition: Objects are represented through their decomposition into irreducible elements
2. Observer Invariance: Representations remain consistent across different perspectives
3. Canonical Representation: Objects have a unique, minimal, basis-independent representation
4. Coherence Norm: Representational complexity is measurable and minimizable
5. Universal Mapping: Translating between frameworks via prime coordinate mapping

Model Architecture

The UOR Model implements these principles through a simple, elegant architecture integrated with content-addressable storage systems like OCI/Docker:

┌──────────────────────────────────────────────────────────┐
│                    UOR Object Layer                      │
│                                                          │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐   │
│  │   Schema    │  │  Instance   │  │   Reference     │   │
│  │ Definitions │  │   Data      │  │   Resolution    │   │
│  └─────────────┘  └─────────────┘  └─────────────────┘   │
│                                                          │
└──────────────────────────────────────────────────────────┘
                            ▲
                            │
                            ▼
┌──────────────────────────────────────────────────────────┐
│                   UOR Prime Layer                        │
│                                                          │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐   │
│  │  Universal  │  │ Prime Space │  │   Coherence     │   │
│  │  Digests    │  │   Mapping   │  │    Metrics      │   │
│  └─────────────┘  └─────────────┘  └─────────────────┘   │
│                                                          │
└──────────────────────────────────────────────────────────┘
                            ▲
                            │
                            ▼
┌──────────────────────────────────────────────────────────┐
│                  UOR Storage Layer                       │
│                                                          │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐   │
│  │  Embedded   │  │  External   │  │   Distributed   │   │
│  │  Content    │  │   Blobs     │  │     Storage     │   │
│  └─────────────┘  └─────────────┘  └─────────────────┘   │
│                                                          │
└──────────────────────────────────────────────────────────┘

Universal Digests

At the heart of the UOR Model are Universal Digests - identifiers that transcend traditional content-addressing while maintaining compatibility with existing standards:

Multihash Compatibility

Universal Digests are formatted as multihash-compatible structures, allowing seamless integration with content-addressable systems:

┌───────────┬────────────┬────────────────────────────────────┐
│  0x1F56   │  Length    │   Universal Prime Digest Payload   │
│ (2 bytes) │ (2 bytes)  │           (up to 512 bits)         │
└───────────┴────────────┴────────────────────────────────────┘

• 0x1F56: Proposed multihash code for UOR Universal Digest
• Length: Size of the digest payload (typically 64 bytes/512 bits)
• Payload: The universal number-derived prime coordinates

OCI Descriptor Integration

Universal Digests integrate directly into OCI descriptors to maintain compatibility with container ecosystems:

{
  "mediaType": "application/vnd.uor.object.v1",
  "digest": "uor:1F56:a1b2c3...",
  "size": 1024,
  "annotations": {
    "uor.coherence": "0.95",
    "uor.conversionRatio": "2.4"
  }
}

Core Implementation

interface UniversalDigest {
  // Multihash-compatible prefix (0x1F56 for UOR)
  prefix: number;
  
  // The prime factorization encoding of the object
  primeCoordinates: PrimeVector;
  
  // The conversion ratio between full content and digest representation
  conversionRatio: number;
  
  // For oversized content: Fallback to standard digest mechanism
  oversized: boolean;
}

Reversible Content Encoding

Unlike traditional cryptographic hashes, Universal Digests directly encode content through prime factorization:

1. For small objects (conversion ratio ≤ 5:1):

   • Content is encoded directly in the prime coordinates
   • The 512-bit digest contains the complete, reversible representation
   • Extraction of content requires only prime coordinate transformation

2. For large objects (conversion ratio > 5:1):

   • Digest functions like a standard multihash
   • Separate OCI descriptor references the content blob
   • Universal number-derived prime coordinates may be included as metadata

Mathematical Foundation

Universal Digests leverage the mathematical properties of universal numbers:

UDigest(X) = φ(X) = (p₁^α₁, p₂^α₂, ..., pₙ^αₙ)

Where:

• X is the object to be represented
• φ is the prime coordinate mapping function
• pᵢ are the prime elements
• αᵢ are the exponents in the prime factorization

Schema.org Implementation

The UOR Model is formally defined using Schema.org meta schemas, creating a self-describing system:

UORDigest Type Definition

{
  "@context": "https://schema.org",
  "@type": "Class",
  "@id": "uor:UORDigest",
  "name": "UORDigest",
  "description": "A universal object reference digest that contains or references object content",
  "subClassOf": {
    "@type": "Class",
    "@id": "schema:Identifier"
  },
  "properties": [
    "uor:multihashPrefix",
    "uor:primeCoordinates",
    "uor:conversionRatio",
    "uor:oversized"
  ]
}

PrimeCoordinates Property Definition

{
  "@context": "https://schema.org",
  "@type": "Property",
  "@id": "uor:primeCoordinates",
  "name": "primeCoordinates",
  "description": "The prime factorization coordinates of an object",
  "domainIncludes": {
    "@id": "uor:UORDigest"
  },
  "rangeIncludes": {
    "@id": "uor:PrimeVector"
  }
}

Object Representation

The UOR Model represents all objects through a consistent pattern:

{
  "@context": "https://schema.org",
  "@type": "Thing",
  "@id": "uor:1F56:a1b2c3...",
  "identifier": {
    "@type": "uor:UORDigest",
    "multihashPrefix": "0x1F56",
    "primeCoordinates": {
      "basis": "standard",
      "coordinates": [3, 7, 0, 2, 11, ...]
    },
    "conversionRatio": 2.4,
    "oversized": false
  },
  "name": "Example Object",
  "description": "An example of UOR object representation"
}

Storage and Retrieval

The UOR Model implements a hybrid storage approach that works with existing content-addressable systems:

Storage Algorithm

1. Calculate the object's prime decomposition
2. Compute the conversion ratio for embedding in a digest
3. If ratio ≤ 5:1:
   • Store the complete prime coordinates in the digest payload
   • Format as a multihash with UOR prefix (0x1F56)
4. If ratio > 5:1:
   • Mark digest as oversized
   • Generate standard content hash (e.g., SHA-256)
   • Create OCI descriptor with UOR annotations
5. Record the UORDigest as the object's canonical identifier

Retrieval Algorithm

1. Parse the UORDigest from the multihash format
2. Check if the digest is oversized:
   • If not oversized, reverse the prime coordinate mapping to recover content
   • If oversized, resolve the OCI descriptor to retrieve content from blob storage
3. Verify integrity by recomputing the digest from the retrieved content

Client Implementation

The UOR Client provides a simple, intuitive interface to interact with the UOR Model:

// Creating an object with automatic digest generation
const objectRef = await uorClient.create({
  type: "Thing",
  name: "Example Object",
  properties: { ... }
});

// Retrieving an object by its UOR digest
const object = await uorClient.get("uor:1F56:a1b2c3...");

// Updating an object with coherence preservation
const newRef = await uorClient.update("uor:1F56:a1b2c3...", {
  name: "Updated Example"
}, { preserveCoherence: true });

// Finding objects by semantic query
const results = await uorClient.query({
  type: "CreativeWork",
  about: "UOR Framework"
});

Observer Reference Frames

The UOR Model supports multiple observer perspectives through reference frames:

// Creating a new observer reference frame
const frame = uorClient.createFrame({
  name: "Semantic Perspective",
  basisMapping: { ... },
  coherenceMetric: "semantic-distance"
});

// Retrieving an object through a specific frame
const object = await uorClient.get("uor:1F56:a1b2c3...", { frame });

// Translating between frames
const translatedObject = await uorClient.translate(object, {
  fromFrame: frame1,
  toFrame: frame2
});

Coherence Metrics

The UOR Model implements coherence metrics to quantify representational efficiency:

// Calculate coherence norm of an object representation
const norm = await uorClient.calculateCoherence(object);

// Find most coherent representation across frames
const optimalRep = await uorClient.optimizeCoherence(object, {
  frames: [frame1, frame2, frame3],
  method: "minimizeNorm"
});

Integration with Standards

The UOR Model integrates with existing standards for maximum interoperability:

Multihash Integration

Multihash integration enables UOR Digests to work with IPFS, content-addressable storage, and other distributed systems:

// Format UOR digest as multihash
const multihash = uorClient.formatMultihash(digest);

// Parse UOR digest from multihash
const digest = uorClient.parseMultihash(multihash);

// Register UOR digest type with multihash systems
uorClient.registerMultihashCodec("0x1F56", "uor-digest-v1");

OCI Descriptor Integration

Seamless integration with OCI registries and container systems:

// Convert UOR digest to OCI descriptor
const descriptor = uorClient.toOciDescriptor(digest, {
  mediaType: "application/vnd.uor.object.v1",
  size: contentSize
});

// Extract UOR digest from OCI descriptor
const digest = uorClient.fromOciDescriptor(descriptor);

// Push object to OCI registry with UOR digest
const reference = await uorClient.pushToRegistry(object, {
  registry: "ghcr.io/example",
  repository: "uor-objects"
});

Schema.org Integration

The UOR Model extends Schema.org's capabilities:

1. Schema Definition: Schema.org types are defined in the UOR Model with prime factorization
2. Extension Mechanism: New types/properties inherit coherence properties from their parents
3. Cross-Domain Mapping: Schema.org domains are connected through prime coordinate transforms

Example of a UOR-enhanced Schema.org type:

{
  "@context": "https://schema.org",
  "@type": "uor:SchemaType",
  "@id": "schema:CreativeWork",
  "name": "CreativeWork",
  "description": "A creative work",
  "primeDecomposition": {
    "irreducibleElements": ["expression", "creative", "work"],
    "coordinates": [2, 1, 3]
  },
  "coherenceProperties": {
    "minimality": 0.92,
    "invariance": 0.88
  }
}

Practical Implementation

Implementing the UOR Model requires:

1. Prime Factorization Engine: Efficient algorithms for decomposing objects into primes
2. Universal Number Library: Implementation of universal number operations
3. Multihash Adapter: Integration with multihash encoding/decoding
4. OCI Compatibility Layer: Interface to OCI registries and descriptors
5. Reference Frame Registry: Management of different observer perspectives
6. Coherence Calculator: Implementation of the coherence norm and metric

A reference implementation can be structured as:

└── uor-model/
    ├── src/
    │   ├── core/
    │   │   ├── digest.ts        # Universal digest implementation
    │   │   ├── primes.ts        # Prime factorization algorithms
    │   │   └── coherence.ts     # Coherence metrics and calculations
    │   ├── compat/
    │   │   ├── multihash.ts     # Multihash integration
    │   │   └── oci.ts           # OCI descriptor integration
    │   ├── storage/
    │   │   ├── embedded.ts      # Embedded content storage
    │   │   └── external.ts      # External blob storage integration
    │   ├── schema/
    │   │   ├── types.ts         # Schema.org type definitions
    │   │   └── extensions.ts    # UOR extensions to Schema.org
    │   └── client/
    │       ├── api.ts           # Client API implementation
    │       └── frames.ts        # Observer reference frame management
    ├── test/
    │   ├── digest.test.ts       # Tests for digest functionality
    │   └── coherence.test.ts    # Tests for coherence metrics
    └── examples/
        ├── basic-usage.ts       # Simple usage examples
        └── advanced-frames.ts   # Advanced reference frame examples

Conclusion

The UOR Model represents a pragmatic implementation of the UOR Framework principles in a system that integrates seamlessly with existing standards. By balancing theoretical elegance with practical compatibility, it enables:

1. Information Integrity: Content and identifier are intrinsically linked through prime decomposition
2. Standard Compatibility: Works with multihash, OCI, and existing content-addressed systems
3. Semantic Richness: Objects carry their meaning in their structure
4. Perspective Flexibility: Multiple valid viewpoints through observer frames
5. Representational Efficiency: Optimized encoding through coherence principles

This model serves as both a practical implementation of the UOR Framework's theoretical principles and a powerful tool for defining, storing, and manipulating information in a coherent, observer-invariant manner while maintaining compatibility with widely-adopted standards.