Unit URI Format & Validation

ELI5

A unit URI is a postal address with four parts: which neighbourhood (domain), what kind of building (type), the street name (slug), and the apartment number (version). Get any part wrong and the parser refuses to deliver.

Technical Deep Dive

Source: packages/schema/src/uri.ts, packages/schema/src/constants.ts.

Format

stratt://{domain}/{type}/{slug}@{version}

Canonical Regex

^stratt:\/\/(dev|ops|docs|neuro|finance|nutrition|legal|film|artist|core|shared)\/(role|rule|task|chain|supply)\/([a-z0-9-]+)@(\d+\.\d+\.\d+)$

Components

Parse Flow

flowchart TD
    A[input string] --> B{matches regex?}
    B -->|no| C[UriError]
    B -->|yes| D[extract domain/type/slug/version]
    D --> E{domain in URI enum?}
    E -->|no| C
    E -->|yes| F[ParsedUri]
    F --> G[validate.ts: id decomposition matches unit fields]
    G -->|mismatch| H[ValidationFailure: URI inconsistency]
    G -->|match| I[Unit accepted]

Functions

• parseUri(uri: string): ParsedUri | UriError — uri.ts:21–32
• formatUri(parts): string — uri.ts:43–62
• isValidUri(uri: string): boolean — uri.ts:65–67

Fingerprint Independence

The URI does NOT contain the fingerprint. Fingerprints live in the unit body and are verified separately (SPEC-02). Two units at the same URI can drift fingerprints — that is the FM-01 detection surface.

Key Terms

• Slug → Human-readable identifier inside a (domain, type) pair; must be unique.
• Domain enum mismatch → URI parser rejects 4 of the 15 declared domains (security/product/data/marketing) until they are added to the regex.
• Strict semver → No 1.0.0-rc.1. Pre-release versions are not currently representable in URIs.

Q&A

Q: Why doesn’t the URI carry the fingerprint? A: URIs are addresses; fingerprints are seals. Embedding a fingerprint in the URI would make every legitimate edit a URI break.

Q: What happens if the URI domain is marketing but a chain imports it? A: Today the URI regex rejects it (FM-02 broken import). The constants file lists 15 domains for the type system, but uri.ts ships with 11 — closing this gap is open work.

Q: Are uppercase characters allowed in slugs? A: No. Slug regex ^[a-z0-9-]+$ is strict lowercase + digits + hyphen.

Examples

Valid: stratt://dev/chain/sol-1-boot@0.1.0 Valid: stratt://core/chain/domain-extension-pipeline@1.0.0 Invalid: stratt://Dev/task/boot@0.1.0 — uppercase domain. Invalid: stratt://dev/task/boot_review@0.1.0 — underscore in slug. Invalid: stratt://dev/task/boot@0.1 — incomplete semver.