RSM ID — Core Identity Reference Implementation

#Abstract

This reference implementation defines the first executable foundation for RSM ID, the universal RSM resource identity system. It provides permanent RSM Identifiers (RIDs), structured RSM Resource Names (RRNs), RSM Space Names (RSNs), controlled identifier issuance, an auditable registry, HTTP resolution, and federation with independently managed Semantic Spaces.

RSM ID is the encompassing infrastructure, not another identifier type. The design deliberately separates identity from content and deployment. RID identifies; RRN names; RSN identifies a Semantic Space; the registry preserves identity and authority; the resolver connects identifiers to permitted representations; Locus serves authoritative knowledge; Atlas explores relationships. The initial demonstration consists of three independent Locus nodes—RSM, Wellzai, and Musewoods—sharing one identity contract without sharing a content database.

All diagrams in this document use portable fenced Mermaid syntax. Code listings describe reference interfaces and implementation patterns; they are not claims that these components have already been built.

#1. Architecture and scope

RSM ID SHALL be implemented as one logical identity system whose interoperable constructs are RID, RRN, RSN, authoritative Identity Records, registry authority, and trusted resolution. A deployment MAY split these responsibilities across modules and services, but MUST NOT create separate competing RID/RRN/RSN authorities or independently invent a second canonical identity for the same registered referent. The normative specification, not this reference implementation, controls the identity contract.

#1.1. Reference architecture

The implementation has five independently testable responsibilities:

1. Identity: Generate, validate, parse, format, and compare permanent RIDs.
2. Naming: Validate RRNs and RSNs, enforce registration, and associate names with RIDs.
3. Registry: Preserve identities, prefixes, authority delegations, binding history, lifecycle, and provenance.
4. Resolution: Convert identifiers into verified, policy-permitted metadata and representations.
5. Federation: Discover authoritative Semantic Spaces and delegate retrieval without centralizing their knowledge.

The implementation SHOULD support three operating modes: an embedded pure Go library, a standalone registry/resolver service, and a federated gateway connecting independent Locus nodes.

#1.2. Architectural ownership

RSM Core SHALL own the identity types, naming grammar, validation, registry contracts, resolver interfaces, and conformance fixtures. A reference runtime MAY use SQLite and HTTP, but neither SQLite nor a particular Go web framework becomes part of the identity standard.

Locus SHALL own authoritative resource content, revisions, and semantic relationships for the spaces it serves. Atlas SHALL consume federated metadata and relationships for exploration. Wellzai, Musewoods, and other applications SHALL use RSM identity rather than creating incompatible cross-system identities. Ana MAY form and reconcile knowledge, but SHALL not redefine RID issuance or resource equivalence.

#1.3. Explicit non-goals

The initial release SHALL NOT build a general CMS, graph database, distributed consensus platform, blockchain, embedding engine, global search service, or custom enterprise identity provider. It SHALL NOT require Docker or an external database for pure identity package tests.

#1.4. Foundational invariants

#2. Canonical identity and naming types

#2.1. RID

RID is the permanent, compact identifier in DOI-style prefix/suffix form:

<prefix>.<suffix>
451.7K4M9Q2X8D5P0R6T

The v1.0 default suffix is 16 uppercase Crockford Base32 symbols, encoding 80 bits of cryptographic randomness. The alphabet is:

0123456789ABCDEFGHJKMNPQRSTVWXYZ

The prefix is a registered decimal namespace, not a hostname. Lexical RID parsing and registry-aware RID validation are different operations: syntactically valid RIDs may have unregistered prefixes and must not be represented as authoritative until issuance succeeds.

#2.2. RRN

RRN is the registered structured naming descriptor:

rrn:<realm>:<authority>:<jurisdiction>:<space>:<kind>/<resource-id>
rrn:451:451labs:us-ca:wellzai:document/outcome-formation-model

The grammar SHALL enforce normalized lowercase structural segments, nonempty parts, bounded lengths, and disallow ambiguous percent encodings, wildcards, and path traversal. Registered RRNs resolve to an RID. A resource may acquire an additional RRN after a governed namespace transfer without changing RID; historical RRNs remain reserved.

#2.3. RSN

RSN is an RRN whose kind is space:

rrn:451:451labs:us-ca:rsm:space/root
rrn:451:451labs:us-ca:wellzai:space/root
rrn:451:451labs:us-ca:musewoods:space/root

These are proposed namespace registrations, not claims of issued identities. Each space SHALL also have its own permanent RID. The identity registry, not a hostname or application build, determines the space's current authoritative runtime.

#2.4. Identity and representation

A RID identifies a resource, while its RRN represents structured issuance context. A resolver supplies one or more views of the same referent. An HTML landing page for a watershed, for example, is a description of the watershed, not the watershed itself.

#3. Repository and Go package boundaries

#3.1. Recommended logical layout

Adapt these paths to the existing RSM repository; do not reorganize working modules merely to match this example.

rsm/
  core/
    identity/
      rid/
      rrn/
      rsn/
      model/
      validation/
      issuance/
      registry/
      resolution/
      authority/
      governance/
      provenance/
      interop/
  services/
    identityd/
  clients/
    go/
    typescript/
  schemas/
    identity/v1/
      rid.schema.json
      rrn.schema.json
      identity-record.schema.json
      space-record.schema.json
      resolution.schema.json
      registry-events.schema.json
      openapi.yaml
  migrations/identity/
  conformance/v1/
    valid-rids.json
    invalid-rids.json
    valid-rrns.json
    invalid-rrns.json
    registry-cases.json
    resolution-cases.json
    policy-cases.json
  examples/
    identity-cli/
    local-registry/
    three-space-federation/
  docs/identity/

#3.2. Layering

The rid, rrn, and rsn packages SHALL be deterministic and free of network or SQL dependencies. RID generation uses cryptographic randomness; issuance requires a transactional registry and delegated authority. Resolution requires registry lookup, trust verification, policy evaluation, and representation access.

The core types MUST be importable without starting an HTTP service. Storage and network adapters must not leak into canonical formatting or identifier comparisons.

#3.3. Dependencies

Prefer the Go standard library for parsing, HTTP, cryptography, and testing. Select a maintained SQLite driver based on supported Go versions, licensing, deployment portability, and transactional behavior. Keep authentication, JOSE, JSON-LD, and policy libraries behind replaceable interfaces.

#4. Registry logical data model

#4.1. Entities

#4.1.1. RSM Identity Record mapping

The identities table is the local persistence projection of the normative RSM Identity Record. The complete logical record spans identities, resource_names, resource_bindings, identity_events, external_identifiers, prefixes, authorities, and delegations; it is not a new independent table or resource identifier. APIs SHOULD assemble a consistent identity-record view from these records while retaining authoritative provenance and effective-dated history. The durable primary key is RID, including when RRNs, space bindings, or endpoints change.

The reference schema below is intentionally incomplete. In particular, production conformance must explicitly model authoritative space RID/RSN, issuer provenance, binding verification, delegation and transfer history, and protected disclosure, as required by the normative Identity Record. Do not silently treat a database row or example YAML envelope as the final serialized schema.

#4.2. Relationships

#4.3. Representative SQLite migration

PRAGMA foreign_keys = ON;

CREATE TABLE prefixes (
    prefix TEXT PRIMARY KEY,
    controller_authority TEXT NOT NULL,
    status TEXT NOT NULL
      CHECK (status IN ('active','suspended','retired','reserved')),
    created_at TEXT NOT NULL
);

CREATE TABLE authorities (
    authority_id TEXT PRIMARY KEY,
    display_name TEXT NOT NULL,
    status TEXT NOT NULL
      CHECK (status IN ('active','suspended','retired'))
);

CREATE TABLE identities (
    rid TEXT PRIMARY KEY,
    prefix TEXT NOT NULL REFERENCES prefixes(prefix),
    kind TEXT NOT NULL,
    status TEXT NOT NULL
      CHECK (status IN
        ('active','deprecated','superseded','retired','reserved')),
    referent_descriptor TEXT NOT NULL,
    created_at TEXT NOT NULL,
    updated_at TEXT NOT NULL
);

CREATE TABLE spaces (
    rid TEXT PRIMARY KEY REFERENCES identities(rid),
    rsn TEXT NOT NULL UNIQUE,
    authority_id TEXT NOT NULL REFERENCES authorities(authority_id),
    status TEXT NOT NULL
      CHECK (status IN ('active','suspended','retired'))
);

CREATE TABLE resource_names (
    rrn TEXT PRIMARY KEY,
    rid TEXT NOT NULL REFERENCES identities(rid),
    status TEXT NOT NULL
      CHECK (status IN ('active','superseded','retired')),
    registered_at TEXT NOT NULL,
    superseded_at TEXT
);

CREATE TABLE resource_bindings (
    binding_id TEXT PRIMARY KEY,
    rid TEXT NOT NULL REFERENCES identities(rid),
    space_rid TEXT NOT NULL REFERENCES spaces(rid),
    endpoint TEXT NOT NULL,
    valid_from TEXT NOT NULL,
    valid_to TEXT
);

CREATE UNIQUE INDEX one_active_binding_per_resource
ON resource_bindings(rid)
WHERE valid_to IS NULL;

CREATE TABLE identity_events (
    event_id TEXT PRIMARY KEY,
    rid TEXT REFERENCES identities(rid),
    actor_id TEXT NOT NULL,
    action TEXT NOT NULL,
    details_json TEXT NOT NULL,
    occurred_at TEXT NOT NULL
);

CREATE TABLE idempotency_records (
    issuer_id TEXT NOT NULL,
    key TEXT NOT NULL,
    request_hash TEXT NOT NULL,
    rid TEXT NOT NULL REFERENCES identities(rid),
    created_at TEXT NOT NULL,
    PRIMARY KEY (issuer_id, key)
);

CREATE TABLE external_identifiers (
    id TEXT PRIMARY KEY,
    rid TEXT NOT NULL REFERENCES identities(rid),
    scheme TEXT NOT NULL,
    external_value TEXT NOT NULL,
    relation TEXT NOT NULL
);

This is a representative migration rather than a production-complete schema. Production implementation SHALL add delegated permissions, verification keys, binding transfer state, registry revision counters, immutability enforcement, and migration tests. SQL constraints do not replace RID/RRN parsing. For SQLite, enforce foreign keys on every connection, not only during schema creation.

#4.4. Transactions and history

Identity issuance SHALL atomically commit the RID registration, initial RRN, authoritative binding, and audit event. A resource transfer SHALL preserve historical bindings with effective periods. Remote Locus provisioning cannot be part of the same SQLite ACID transaction; use an explicit provisioning state and an idempotent coordination workflow.

#5. Go reference interfaces

The following presents interface shapes; production code will split packages and add constructors, typed errors, authorization context, and transaction interfaces.

package identity

import (
    "context"
    "time"
)

type RID struct { value string }
func (r RID) String() string { return r.value }

type RRN struct { value string }
func (r RRN) String() string { return r.value }

type IssueRequest struct {
    Prefix         string
    Kind           string
    SpaceRID       RID
    RequestedRRN   RRN
    Referent       string
    IdempotencyKey string
}

type IdentityRecord struct {
    RID       RID
    Kind      string
    State     string
    CreatedAt time.Time
}

type Issuer interface {
    Issue(ctx context.Context, principal string,
        request IssueRequest) (IdentityRecord, error)
}

type Registry interface {
    GetIdentity(ctx context.Context, rid RID) (IdentityRecord, error)
    ResolveName(ctx context.Context, name RRN) (RID, error)
}

type RepresentationRequest struct {
    RID       RID
    Principal string
    MediaType string
    Revision  string
}

type Representation struct {
    RID         RID
    MediaType   string
    Content     []byte
    ETag        string
    RetrievedAt time.Time
}

type Resolver interface {
    Resolve(ctx context.Context,
        request RepresentationRequest) (Representation, error)
}

type AuthorityVerifier interface {
    CanIssue(ctx context.Context, principal string,
        prefix string, space RID, kind string) (bool, error)
}

The RID and RRN constructors SHALL validate before creating value objects. Real packages SHOULD use non-exported fields and validated factory functions. Typed errors SHOULD include invalid syntax, unregistered prefix, forbidden issuance, conflict, unavailable authority, and retired identity.

#6. RID issuance

#6.1. Algorithm

1. Authenticate the requesting principal and authorize prefix/space/kind issuance.
2. Validate the resource's kind, requested RRN, referent descriptor, and idempotency input.
3. Look up an existing idempotency record, scoped to authenticated issuer and request fingerprint.
4. Generate 80 cryptographically random bits and encode them into a 16-character suffix.
5. Construct the candidate RID and validate its canonical syntax.
6. Begin a transaction and insert RID, initial RRN mapping, binding, issuance event, and idempotency record.
7. Commit atomically; if the RID unique constraint collides, retry with a new suffix.
8. Return the persisted RID and authoritative registration metadata.

Authorization failures, malformed input, and network/storage failures MUST NOT be misclassified as RID collisions. SQLite writes should not remain open across remote network requests.

#6.2. Candidate generator

package rid

import (
    "crypto/rand"
    "fmt"
    "strconv"
    "strings"
)

const alphabet = "0123456789ABCDEFGHJKMNPQRSTVWXYZ"

func Generate(prefix string) (string, error) {
    if err := validatePrefix(prefix); err != nil {
        return "", err
    }

    var raw [10]byte // 80 random bits
    if _, err := rand.Read(raw[:]); err != nil {
        return "", err
    }

    var suffix [16]byte
    for i := 0; i < 16; i++ {
        bit := i * 5
        byteIndex := bit / 8
        shift := uint(bit % 8)
        value := uint16(raw[byteIndex]) << 8
        if byteIndex+1 < len(raw) {
            value |= uint16(raw[byteIndex+1])
        }
        index := byte((value >> (11 - shift)) & 31)
        suffix[i] = alphabet[index]
    }

    return prefix + "." + string(suffix[:]), nil
}

func validatePrefix(prefix string) error {
    if len(prefix) < 1 || len(prefix) > 16 {
        return fmt.Errorf("invalid prefix length")
    }
    if strings.HasPrefix(prefix, "0") && prefix != "0" {
        return fmt.Errorf("noncanonical leading zero")
    }
    for _, c := range prefix {
        if c < '0' || c > '9' {
            return fmt.Errorf("nondecimal prefix")
        }
    }
    if _, err := strconv.ParseUint(prefix, 10, 64); err != nil {
        return err
    }
    return nil
}

This generates a candidate, not a registered identity. Generation alone does not guarantee uniqueness. At one billion independent 80-bit suffix generations under a single prefix, the approximate birthday collision probability is about 4.1 × 10^-7, so atomic uniqueness checks and bounded collision retries are mandatory.

#6.3. Idempotency

The issuer SHALL scope idempotency keys to the authenticated issuer and a stable hash of the normalized request. Repeating an identical request returns the originally committed RID. Repeating the same key with different request content returns a conflict.

#6.4. Non-reuse

An issued RID reservation must survive resource retirement, withdrawal, transfer, and legal erasure workflows to the extent permitted by law. Never expose a deleted RID for reassignment to a new resource.

#7. Resolver API and representations

#7.1. HTTP routes

Registry-mutation routes require authentication and least-privilege authorization. The public identifier path is a resolution interface, not a permission grant.

#7.2. Issuance request

POST /v1/identities HTTP/1.1
Host: identity.example.test
Authorization: Bearer <access-token>
Content-Type: application/json
Idempotency-Key: formation-model-001

{
  "prefix": "451",
  "kind": "document",
  "spaceRid": "<registered-wellzai-space-rid>",
  "rrn": "rrn:451:451labs:us-ca:wellzai:document/outcome-formation-model",
  "referent": "Wellzai Outcome Formation Model"
}

On successful first issuance, return 201 Created with canonical RID, registration status, and a web identifier. For identical retried requests, return the original issuance result without minting a second RID.

#7.3. Resolution request

GET /451.7K4M9Q2X8D5P0R6T HTTP/1.1
Host: rsmid.org
Accept: application/ld+json

The rsmid.org hostname is proposed, not a claimed live or verified authoritative resolver. Its use requires domain control, stewardship, and trust configuration. A conforming resolver MAY operate under another approved hostname.

The JSON-LD shape might be:

{
  "@context": {
    "rid": "https://example.org/rsm/context/rid",
    "rrn": "https://example.org/rsm/context/rrn",
    "kind": "https://example.org/rsm/context/kind",
    "space": {
      "@id": "https://example.org/rsm/context/space",
      "@type": "@id"
    }
  },
  "@id": "https://rsmid.org/451.7K4M9Q2X8D5P0R6T",
  "rid": "451.7K4M9Q2X8D5P0R6T",
  "rrn": "rrn:451:451labs:us-ca:wellzai:document/outcome-formation-model",
  "kind": "document",
  "title": "Outcome Formation Model",
  "space": "https://rsmid.org/<wellzai-space-rid>",
  "identityStatus": "active"
}

The example context IRIs and placeholder space identifier are not valid production vocabulary mappings. Assign stable RSM vocabulary IRIs, expand and validate the JSON-LD, and replace placeholders before promoting a fixture into the conformance suite.

#7.4. Resolver sequence

Resolvers SHOULD support text/html, application/json, and application/ld+json, with suitable HTTP Vary and cache controls. A representation may vary according to Accept, language preference, and authenticated authorization without changing the identified referent.

#7.5. Resolution statuses and privacy

Internal statuses SHOULD distinguish resolved, not_found, forbidden, retired, superseded, unavailable, untrusted, and invalid. Externally, restricted and nonexistent resources MAY need indistinguishable responses to avoid resource-existence leaks. HTTP response behavior and diagnostics must implement that policy deliberately.

The default persistent web identifier SHOULD yield a durable identity landing page rather than always forwarding to a transient application URL. Optional redirects to authoritative representations may be supported. Content hashes and revision identifiers remain separate from RID.

#7.6. Security and caches

Verify registered prefixes, delegated issuers, signed or otherwise authenticated endpoint bindings, token audience and expiry, and policy-permitted representation access. Federation HTTP clients must defend against SSRF, unsafe redirects, private-network destinations, and credential forwarding. Public caches must never store principal-specific restricted responses; binding revocation, authority transfers, and policy changes require explicit cache invalidation or bounded freshness.

#8. Semantic Space federation

#8.1. Initial topology

Ports are proposed local-development defaults, not existing deployed services. Each node maintains independent content and revisions; the registry maintains permanent identities, namespace ownership, and endpoint bindings.

#8.2. Cross-space references

A Wellzai formation resource can reference an RSM concept by RID and a Musewoods fieldnote by RID. Atlas resolves those references through registered authorities and retrieves representations from the spaces owning them. Cached projections may carry identity, revision, retrieval time, and provenance, but MUST NOT silently become independent authoritative copies.

#8.3. Resource transfer

This is a coordinated transfer, not a distributed ACID transaction. Define handling for loss of the target after cutover, rollback eligibility, stale resolver caches, and split-brain prevention. The canonical RID persists throughout.

#8.4. Contextual governance

The registered RRN records issuance jurisdiction, not necessarily the resource's current legal location, ecological extent, or hosting region. The semantic governance model MAY record multiple bioregions, watersheds, legal jurisdictions, data residency constraints, and stewardship authorities. A resolver SHALL enforce disclosure policy based on current trusted attributes, not on RID prefix or RRN jurisdiction alone.

#9. Portable conformance fixtures

#9.1. Parser vectors

{
  "spec": "rsm-identity-v1",
  "cases": [
    {
      "input": "451.7K4M9Q2X8D5P0R6T",
      "valid": true,
      "prefix": "451",
      "suffix": "7K4M9Q2X8D5P0R6T"
    },
    {
      "input": "451.7K4M9Q2X8D5P0R6I",
      "valid": false,
      "reason": "invalid Crockford Base32 character"
    },
    {
      "input": "0451.7K4M9Q2X8D5P0R6T",
      "valid": false,
      "reason": "noncanonical prefix"
    },
    {
      "input": "451.7K4M9Q2X8D5P0R6T",
      "valid": true,
      "registryValidation": "depends on prefix registration"
    }
  ]
}

Lexical fixtures must be separate from registry-aware issuance tests. Test cryptographic generation with a controlled random source and fixed expected outputs, and fuzz the parser with invalid encodings, lengths, unsupported characters, and malformed RRNs.

#9.2. Acceptance scenarios

Tests must include issuer authorization, conflicting idempotency keys, collision retries, non-reuse, transfer races, registry corruption handling, revoked endpoint keys, untrusted redirects, and appropriate cache behavior.

#10. Operational development workflow

#10.1. Local commands

A reference CLI SHOULD support:

rsm identity init
rsm identity prefix add
rsm identity issue
rsm identity inspect
rsm identity resolve
rsm identity register-name
rsm identity register-space
rsm identity retire
rsm identity doctor

Suggested developer targets:

make identity-test
make identity-lint
make identity-fuzz
make identity-conformance
make federation-up
make federation-seed
make federation-test
make federation-down

Sample resolution:

rsm identity resolve 451.7K4M9Q2X8D5P0R6T

Illustrative authorized output:

RID:          451.7K4M9Q2X8D5P0R6T
Kind:         document
Name:         Outcome Formation Model
Authority:    451 Labs
Space:        Wellzai
Identity:     active
Revision:     7

#10.2. Observability and recovery

Expose readiness checks, issuance and collision counts, denied requests, registry failures, remote resolution errors, and structured tracing with appropriate privacy controls. Never log credentials or restricted data indiscriminately. Support transactionally consistent SQLite backups and restoration tests; verify that restoration preserves historical IDs, RRN reservations, active bindings, delegation history, and tombstones.

#11. Implementation phases and release gates

#11.1. Gate 1 — Identity primitives

Deliver pure Go RID/RRN/RSN packages, canonical parser/formatter, random suffix generation, shared conformance fixtures, and fuzz tests. The release gate requires deterministic tests and no network/database dependency for pure identity operations.

#11.2. Gate 2 — Registry integrity

Implement SQLite migrations, prefix/authority registration, delegations, transactional issuance, RRN mappings, space records, idempotency, and append-only events. Verify concurrent uniqueness, rollback, collision retries, and permanent non-reuse.

#11.3. Gate 3 — Persistent resolution

Deliver content-negotiated HTML/JSON/JSON-LD identity responses, trust validation, resource-binding lookup, lifecycle responses, and policy-aware disclosure. Validate the actual RSM JSON-LD context rather than relying on placeholder vocabulary mappings.

#11.4. Gate 4 — Federation interoperability

Run RSM, Wellzai, and Musewoods as distinct Locus nodes with separate persistence. Traverse cross-space RID relationships, verify authoritative endpoints, and prove identity persistence after content edits and endpoint relocation.

#11.5. Gate 5 — Operational hardening

Complete authority spoofing tests, HTTP security controls, caching/revocation tests, backup and recovery drills, concurrency stress tests, CI, schemas, OpenAPI, and compatibility documentation. Production deployment additionally requires legitimate prefix governance, trust roots, and stewardship procedures.

#12. Initial three-node demonstration

The initial lab SHOULD seed approximately 20–30 representative resources from each of RSM, Wellzai, and Musewoods. Use non-destructive imports into isolated demonstration storage; do not modify original application repositories during the prototype.

The end-to-end demonstration SHALL prove that:

1. Each node has its own RSN and RID, plus independently managed content.
2. The shared registry can issue, register, and resolve permanent resource RIDs.
3. Each resource's registered RRN resolves to its canonical RID.
4. Atlas can traverse an RSM → Wellzai → Musewoods chain using RID references.
5. A content revision appears without rebuilding the consuming application.
6. A Locus endpoint relocation preserves RID and historical naming associations.
7. Governance restrictions are respected in human and machine-readable resolution.
8. Retired resources cannot have their RIDs reassigned.

#13. Implementation guardrails

Before coding, inspect the existing RSM Core canonical object, identity, subject, schema, and registry facilities. Implement the RSM ID contract defined in Document 08 rather than a parallel identity platform. Reuse or migrate the present implementation instead of creating a parallel identity model. Keep the canonical RID contract language-neutral and drive every Go, TypeScript, and Rust implementation from the same fixtures.

Do not conflate a registered resource name with canonical identity, a space with its Locus deployment, a DOI-like identity with an immutable content hash, or issuance jurisdiction with all present-day geographic policy. Never assume a global identity registry implies a global content database.

#14. Conclusion

The reference implementation makes resource identity durable while permitting Semantic Spaces to remain independently owned and operated. RSM Core provides the canonical rules, the registry preserves issuance and authority, the resolver exposes contextual representations, and Locus nodes maintain authoritative knowledge. Atlas connects those spaces through semantic relationships anchored to permanent RIDs.

Identity is permanent. Naming is governed. Resolution is federated. Knowledge remains independently owned.

#15. v1.1 Reference Implementation Addendum — Resolution and Conformance

This addendum implements the normative requirements in Document 08 Section 18. It is reference guidance, not a mandate to use Go, SQLite, Next.js, 451x libraries, or a centralized deployment. The published interface schemas and fixtures SHALL conform to the normative specification when that reference implementation claims conformance.

#15.1. Suggested package and contract additions

Add naming/abnf, naming/kinds, identity/lifecycle, resolution/http, resolution/problem, resolution/jsonld, resolution/cache, and conformance/v1.1 under the existing implementation boundaries. Keep deterministic lexical parsing independent of registry lookups; separate ParseRRN, ValidateRegisteredRRN, ResolveRRN, and AuthorizeRepresentation. Preserve the existing identity records, resource-name mappings and append-only events in migrations, with explicit migration checks rather than destructive table replacement.

#15.2. Go contract example

package identity

import "context"

type LogicalStatus string
const (
  Resolved LogicalStatus = "resolved"
  Invalid LogicalStatus = "invalid"
  NotFound LogicalStatus = "not_found"
  Forbidden LogicalStatus = "forbidden"
  Retired LogicalStatus = "retired"
  Superseded LogicalStatus = "superseded"
  Unavailable LogicalStatus = "unavailable"
  Untrusted LogicalStatus = "untrusted"
)

type ResolveInput struct {
  Identifier string // RID, approved HTTPS identifier, RRN, or RSN
  MediaType string
  Principal string
  Revision string // representation selector, never part of RID
}

type ResolveResult struct {
  Status LogicalStatus
  RID string
  IdentityStatus string
  IdentityMetadata []byte
  Representation []byte
  ContentType string
}

type IdentityResolutionService interface {
  Resolve(ctx context.Context, request ResolveInput) (ResolveResult, error)
}

Parsing and status classification MUST happen before rendering. Application transport errors and logical identity statuses remain distinct; public error redaction may map forbidden to the same outward 404 as not_found.

#15.3. HTTP implementation profile

Reserve canonical GET and HEAD root RID paths on the gateway; keep application paths for documentation and demos separate. Serve the gateway as a reverse-proxy or router on rsmid.org without embedding deployment location in the RID. For current website deployments with no operational resolver, do not intercept plausible RID strings to fabricate successful resolution. Register actual prefixes, endpoint-binding trust, recovery processes, and privacy policies before enabling operational public resolution.

Implement: GET /{rid}, HEAD /{rid}, GET /v1/identities/{rid}, GET /v1/names/resolve?rrn=... and authenticated mutation routes defined earlier. Introduce Accept negotiation and application/problem+json errors. Centralize mapping of logical statuses to transport codes, including disclosure-dependent 403/404 and 410/404. Apply Vary: Accept; restrict private or principal-specific cache storage; use verified endpoint bindings only. Do not equate 403, 401, 406, 429 or 503 with new identity lifecycle states.

#15.4. JSON and JSON-LD profile example

{
  "@context": {
    "rid": "https://rsmid.org/vocab/rid",
    "rrn": "https://rsmid.org/vocab/rrn",
    "kind": "https://rsmid.org/vocab/kind",
    "title": "https://purl.org/dc/terms/title",
    "identityStatus": "https://rsmid.org/vocab/identityStatus",
    "space": {"@id": "https://rsmid.org/vocab/space", "@type": "@id"}
  },
  "@id": "https://rsmid.org/451.7K4M9Q2X8D5P0R6T",
  "rid": "451.7K4M9Q2X8D5P0R6T",
  "rrn": "rrn:451:451labs:us-ca:wellzai:document/outcome-formation-model",
  "kind": "document",
  "title": "Outcome Formation Model",
  "identityStatus": "active"
}

The https://rsmid.org/vocab/... terms above are proposed illustrative vocabulary IRIs, not asserted deployed or registered context mappings. Before production use, publish and freeze the versioned vocabulary context at verified dereferenceable IRIs, run JSON-LD expansion tests, and ensure every profile property survives processing. The earlier Document 09 example's unmapped title and identityStatus properties MUST be corrected in implemented fixtures.

#15.5. Test fixtures and recommended file layout

conformance/v1.1/
  rrn-valid.json
  rrn-invalid.json
  kinds.json
  lifecycle-transitions.json
  http-resolution.json
  problem-responses.json
  content-negotiation.json
  privacy-redaction.json
  trust-and-cache.json
  jsonld-expansion.json
  federation-loops.json
schemas/identity/v1.1/
  resolution-envelope.schema.json
  resolution-problem.schema.json
  kind-registration.schema.json
  lifecycle-event.schema.json
  openapi.yaml

Acceptance gates SHALL include examples for all valid status mappings, forbidden/not-found indistinguishability when required, HEAD/GET header parity, authority revocation, stale cache prevention, invalid parser cases, concurrency, historical mapping retention, and invalid JSON-LD context behavior. Use a shared language-neutral corpus to check Go, TypeScript, Rust and future implementations. An implementation must not mark a test as passed if it was only illustrated by a simulated website resolver.

#15.6. Migration, operational sequence, and release gates

1. Freeze versioned conformance fixtures and the reference OpenAPI/JSON Schemas; review them against Document 08.
2. Implement RRN ABNF parser and kind registration with existing RSM Core facilities, not a parallel catalog.
3. Add durable lifecycle transitions and audit events with migration and rollback tests.
4. Implement structured resolution outcomes and HTTP transport mapping, including disclosure rules.
5. Fix JSON-LD contexts and expansion checks before exposing machine-readable identity responses.
6. Deploy locally against an isolated, registered demonstration namespace; separately validate authority, trust, caching, and unavailable dependencies.
7. Only after genuine prefix governance and service-operations approval, enable live public RID resolution through the chosen gateway.

#15.7. 451x experience integration — informative, non-normative

The existing private @451x/* Experience Libraries MAY be used by rsmid.org to publish structured learning materials (journals, fieldnotes, seednotes, viewgraphs, reels and diagrams). They are website publishing and learning presentation dependencies, not identity standards, protocol dependencies, or authoritative registries. Document 08 and 09 remain portable Markdown with fenced Mermaid diagrams; specifications must remain readable without the private packages. Adopt 451x through versioned packages and authorized private package access, preserving provenance from lesson to specification section, without duplicating Musewoods implementations or altering Musewoods repositories. Do not claim a published package export or learning behavior exists before inspecting the actual installed version and its APIs.

#References

DOI Foundation. (n.d.). DOI handbook. https://www.doi.org/doi-handbook/html/

Berners-Lee, T., Fielding, R., & Masinter, L. (2005). Uniform resource identifier (URI): Generic syntax (RFC 3986). Internet Engineering Task Force. https://doi.org/10.17487/RFC3986

Davis, K., Peabody, B., & Leach, P. (2024). Universally unique identifiers (UUIDs) (RFC 9562). Internet Engineering Task Force. https://doi.org/10.17487/RFC9562

Fielding, R., Nottingham, M., & Reschke, J. (2022). HTTP semantics (RFC 9110). Internet Engineering Task Force. https://doi.org/10.17487/RFC9110

World Wide Web Consortium. (2020). JSON-LD 1.1: A JSON-based serialization for linked data. https://www.w3.org/TR/json-ld11/