Feature: typeid explain — Human-Readable Explanations from ID Schemas

[akhundMurad]

Problem

In most systems, IDs are opaque strings (UUIDs, ULIDs, etc.).
When an engineer encounters an ID like:

usr_live_eu_01HZR9K7M4W0XK8R1V9F3N5A2B

they must rely on:

• tribal knowledge
• documentation
• Slack messages
• database queries
• logs and dashboards

This makes debugging, compliance checks, and system understanding slow and error-prone.

---

Proposal

Introduce a schema-driven ID explanation mechanism that allows TypeID to answer the question:

“What is this ID?”

by combining:

1. Deterministic facts derived from the ID itself
2. User-declared semantic schemas bound to ID prefixes
3. (Optional) read-only enrichment from external systems

---

Core Idea

Users define TypeID schemas (YAML/JSON) that describe the meaning, ownership, policies, and expected behavior of IDs by prefix.

TypeID then executes these schemas to generate a structured, human-readable explanation for any valid ID.

This is conceptually similar to:

• OpenAPI → HTTP APIs
• CRDs → Kubernetes resources

…but applied to identities instead of endpoints.

---

Example Schema (Draft)

schema_version: 1

types:
  usr:
    name: User
    description: End-user account
    pii: true
    retention: 7y
    owner_team: identity-platform

    environment:
      required: true
      allowed: [live, test, dev]

    region:
      required: true

    storage:
      primary:
        kind: postgres
        table: users
        shard_by: region

    services:
      - user-service
      - auth-service

    events:
      - user.created
      - user.updated
      - user.deleted

    policies:
      delete:
        allowed: false
        reason: GDPR retention

---

CLI Usage

typeid explain usr_live_eu_01HZR9K7M4W0XK8R1V9F3N5A2B

---

Example Output (Draft)

id: usr_live_eu_01HZR9K7M4W0XK8R1V9F3N5A2B
valid: true

parsed:
  prefix: usr
  environment: live
  region: eu
  created_at: 2025-03-12T10:41:23Z
  sortable: true

schema:
  entity_name: User
  pii: true
  owner_team: identity-platform
  retention: 7y

storage:
  primary: postgres.users (sharded by region)

policies:
  delete:
    allowed: false
    reason: GDPR retention

provenance:
  created_at: derived_from_id
  retention: schema

Even offline, this command should always produce meaningful output.

---

Scope

Must Have (v1)

• Deterministic ID parsing & validation
• Schema binding by prefix
• Local schema loading (repo + user config)
• typeid explain CLI command
• Clear provenance of each field (id vs schema vs external)
• Machine-readable output (--json)

Nice to Have (Later)

• Remote schema registry
• Enrichment plugins (DB / logs / tracing)
• Signed schemas
• IDE integration
• Policy enforcement commands (typeid delete, typeid validate)

---

Non-Goals

• Automatic inference of meaning
• Mutating external systems
• Replacing observability tools
• Complex DSLs or imperative logic in schemas

---

Why This Matters

This feature:

• Turns IDs into executable documentation
• Makes debugging start from the ID, not the logs
• Enables future features (policy enforcement, migrations, impact analysis)
• Clearly differentiates TypeID from “just another ID format”

---

Open Questions

• Schema file naming & discovery (typeid.schema.yaml?)
• Registry precedence rules
• Schema versioning strategy
• Minimal schema spec for v1

---

Acceptance Criteria

• Given a valid TypeID and a matching schema, typeid explain produces a deterministic, structured explanation
• Works offline with no external dependencies
• Output clearly distinguishes derived vs declared information
• Adding a new prefix schema requires no code changes