Namespace URI System (iris:// ↔ strat://)

ELI5

The namespace system is like having two different address books for the same person. In your phone, they’re “John (Work)” with a work number. In your home address book, they’re “John Smith” with a home address. The namespace system ensures both books point to the same person by creating a link between the two entries.

Technical Deep Dive

URI Formats

URI Structure Breakdown

packet-beta
  title IRIS Namespace URI
  0-5: "scheme"
  6-6: ":"
  7-8: "//"
  9-19: "domain"
  20-20: "/"
  21-28: "name"
  29-29: "@"
  30-34: "version"

IRIS URI components:

• scheme = iris
• domain = Council domain (e.g., engineering)
• name = Sprite name (e.g., SOL-FORGE)
• version = SemVer (e.g., 1.0.0)

MERIDIAN URI components:

• scheme = strat
• council = MERIDIAN council ID (e.g., core-council)
• role = Mapped role in MERIDIAN (e.g., architect)
• name = Sprite name (e.g., SOL-FORGE)

Mapping Data Model

erDiagram
    SPRITE_MAPPING {
        uuid mapping_id PK
        uuid iris_sprite_id
        string iris_namespace_uri
        uuid meridian_council_id
        string meridian_namespace_uri
        string status
        datetime created_at
        datetime last_verified_at
    }

MappingStore Implementation

class MappingStore:
    def __init__(self):
        self._mappings: dict[tuple[UUID, UUID], SpriteMappingRecord] = {}
        # Key: (iris_sprite_id, meridian_council_id)

    def create_mapping(self, iris_sprite_id, meridian_council_id, role):
        mapping_id = uuid4()
        iris_uri = f"iris://{domain}/{name}@{version}"
        meridian_uri = f"strat://{council_id}/{role}/{name}"

        record = SpriteMappingRecord(
            mapping_id=mapping_id,
            iris_identity=SpriteIdentityRecord(...),
            meridian_mapping=MeridianCouncilMappingRecord(...),
            status=MappingStatus.ACTIVE,
            iris_namespace_uri=iris_uri
        )
        self._mappings[(iris_sprite_id, meridian_council_id)] = record
        return record

Composite Key Design

flowchart LR
    A["iris_sprite_id"] --> C{"Composite Key"}
    B["meridian_council_id"] --> C
    C --> D["Unique Mapping"]
    D --> E["One sprite can map to<br/>multiple councils"]

The mapping store uses a composite key of (iris_sprite_id, meridian_council_id):

• A single IRIS sprite can be mapped to multiple MERIDIAN councils
• Each (sprite, council) pair has exactly one active mapping
• This enables flexible federation without one-to-one constraints

Mapping Status Lifecycle

stateDiagram-v2
    [*] --> ACTIVE: create_mapping
    ACTIVE --> PENDING_VERIFICATION: schedule_reverification
    PENDING_VERIFICATION --> ACTIVE: fingerprint_match
    PENDING_VERIFICATION --> SUSPENDED: fingerprint_mismatch
    ACTIVE --> SUSPENDED: manual_suspend
    SUSPENDED --> ACTIVE: reverify
    ACTIVE --> REVOKED: revoke
    SUSPENDED --> REVOKED: revoke
    REVOKED --> [*]

ListMappings Pagination

def list_mappings(self, iris_domain=None, meridian_council_id=None,
                  status_filter=None, page_size=20, page_token=None):
    # Filter
    results = [m for m in self._mappings.values()
               if (not iris_domain or m.iris_identity.domain == iris_domain)
               and (not meridian_council_id or m.meridian_mapping.meridian_council_id == meridian_council_id)
               and (not status_filter or m.status == status_filter)]

    # Sort
    results.sort(key=lambda m: m.created_at, reverse=True)

    # Paginate with base64 offset token
    offset = decode_token(page_token) if page_token else 0
    page = results[offset:offset + page_size]
    next_token = encode_token(offset + page_size) if offset + page_size < len(results) else None

    return page, len(results), next_token

Page size: Clamped to 1–100 records

Cross-System Resolution

flowchart TD
    A["Client has: strat://core-council/architect/SOL-FORGE"]
    A --> B["Parse MERIDIAN URI"]
    B --> C{"Lookup mapping store"}
    C -->|Found| D["Get iris_sprite_id"]
    C -->|Not found| E["Return: mapping not found"]
    D --> F["Fetch sprite from iris-service"]
    F --> G["Return: Sprite + mapping metadata"]

Key Terms

• Namespace URI → A structured identifier mapping entities between systems (iris:// and strat://)
• Composite key → A primary key composed of multiple fields: (iris_sprite_id, meridian_council_id)
• Mapping status → ACTIVE, PENDING_VERIFICATION, SUSPENDED, REVOKED
• Cursor-based pagination → Using base64-encoded offset tokens instead of numeric offsets for stable pagination
• Force remap → Overwriting an existing mapping when force_remap=true
• Cross-system resolution → Converting a MERIDIAN URI to an IRIS sprite via the mapping store

Q&A

Q: Can the same sprite have different roles in different MERIDIAN councils? A: Yes. The meridian_role is stored per mapping, so SOL-FORGE could be an architect in one council and a reviewer in another.

Q: What happens if I delete a sprite in IRIS? A: The mapping becomes orphaned. The mapping status should transition to SUSPENDED when the next VerifyFingerprint or ListMappings query detects the sprite is missing.

Q: Why base64-encoded page tokens instead of numeric offsets? A: Numeric offsets are unstable when items are inserted/deleted during pagination. Cursor-based tokens encode the exact position, preventing skipped or duplicated items.

Q: Can I filter ListMappings by multiple statuses? A: The current implementation accepts a single status_filter. For multiple statuses, make multiple requests or extend the filter to accept an array.

Q: Is the mapping store persistent? A: No. Like the in-memory registries, the MappingStore is an in-memory dict. Future versions will persist to PostgreSQL.

Examples

The namespace system is like dual citizenship:

• IRIS namespace = Your home country’s passport (iris://canada/john-doe@2.0.0)
• MERIDIAN namespace = Your work visa in another country (strat://tech-corp/engineer/john-doe)
• Mapping = The embassy record linking your two identities
• Composite key = The embassy looks you up by both your home passport number and your work permit number
• Multiple councils = You can have work visas in multiple countries (USA, UK, Japan) simultaneously
• SUSPENDED = If your home country revokes your passport, all your work visas freeze until resolved
• REVOKED = If you renounce citizenship, the embassy permanently closes your file