@usesource/registry

The canonical SOURCE token registry as a versioned, signed, immutable npm artifact. Embeds a RegistrySnapshot (Token + Property + Element + cryptographic integrity) plus a pure deterministic query layer.

What you get

• Embedded snapshot. Hundreds of canonical tokens, properties, and elements baked into the package. No network round-trip; no DB. Pin the version, get reproducible queries forever.
• Cryptographic integrity. The snapshot is signed with the curation layer's Ed25519 key. On import this package verifies the signature against the public key shipped in @usesource/schema. Tampering throws.
• Pure query layer. Same input → same output, always. No async, no cache, no side effects. Memoize freely; use in tests; rely on it.

Install

npm install @usesource/registry

Use

import {
  getToken,
  searchTokens,
  tokensInDimension,
  getElement,
  elementsWithCapability,
  SNAPSHOT_MANIFEST,
} from "@usesource/registry";

// Single token by canonical ID
const blue = getToken("source.core.color.blue.500");
// → { id, value, dimension, kind, description, evidence, ... }

// All tokens in a dimension
const spacings = tokensInDimension("spacing");

// Free-text search with optional filters
const results = searchTokens({
  q: "primary",
  dimension: "color",
  includeDeprecated: false,
  limit: 20,
});
// → { total, results: Token[] }

// Look up an element by ID
const button = getElement("source.element.button");

// Find all elements that have a given capability
const cards = elementsWithCapability("interactive");

// Inspect the snapshot identity (version, hash, signature)
console.log(SNAPSHOT_MANIFEST);
// → { version: "0.1.0", contentHash: "...", curationKeyId: "...", ... }

Integrity guarantees

1. Schema validation. On import, the embedded snapshot is parsed through RegistrySnapshotSchema from @usesource/schema. A corrupt payload throws.
2. Content hash check. SHA-256 over the canonical JSON form of the data must match the published contentHash. Mismatch throws.
3. Signature verification. Ed25519 signature over the content hash must verify against the curation public key referenced by curationKeyId. Failure throws.

This means: if import "@usesource/registry" succeeds, you know the data is exactly what the curation layer published.

What lives here vs. elsewhere

| Concern | Lives in | |---|---| | Type definitions, Zod schemas, codegen | @usesource/schema | | Embedded snapshot + query layer | @usesource/registry (this package) | | HTTP API over the snapshot | @usesource/api | | MCP tools wrapping the API | @usesource/mcp | | Local codebase scanner | @usesource/scan | | Library mappings (MUI, shadcn, Chakra...) | @usesource/adapter-* |

Versioning

The package version (0.1.0) is the snapshot version. Snapshot semver:

• patch — curation correction, no canonical-ID change
• minor — new canonical IDs added (additive only, never removed)
• major — canonical IDs renamed under deprecation (rare; old IDs remain queryable, marked via deprecatedBy)

License

Apache-2.0. See LICENSE at the repository root.