@protoyard/blueprint 0.0.0-stage → 1.1.1

package/dist/generator-version.js

@@ -0,0 +1,51 @@
+import { hashString } from '@protoyard/core';
+import { GENERATOR_SDK_VERSION } from '@protoyard/scenarios';
+/**
+ * The world generator's version, apart from the generator itself: the
+ * runtime definition needs it synchronously, while the generator
+ * (`@protoyard/blueprint/generator`) loads lazily when a scenario seeds.
+ */
+/** Bump when the same blueprint + seed can produce a different world shape. */
+export const BLUEPRINT_GENERATOR_SDK = 6;
+/** Stable hash of a blueprint's generative surface (entities, fields, features). */
+export function hashBlueprint(blueprint) {
+    // Json fields a canvas screen stores boards in seed a canvas instead of the generic value.
+    const canvasFields = new Set(blueprint.screens.flatMap((screen) => screen.type === 'canvas' ? [`${screen.entity}.${screen.field}`] : []));
+    const payload = {
+        name: blueprint.name,
+        entities: blueprint.entities.map((entity) => ({
+            name: entity.name,
+            plural: entity.plural,
+            table: entity.table ?? null,
+            titleField: entity.titleField,
+            ownerField: entity.ownerField ?? null,
+            seedCount: entity.seedCount ?? null,
+            features: entity.features,
+            fields: entity.fields.map((field) => ({
+                name: field.name,
+                kind: field.kind,
+                required: field.required,
+                fake: 'fake' in field ? (field.fake ?? null) : null,
+                ...('values' in field ? { values: field.values } : {}),
+                ...('min' in field ? { min: field.min ?? null, max: field.max ?? null } : {}),
+                ...('minLength' in field
+                    ? { minLength: field.minLength ?? null, maxLength: field.maxLength ?? null }
+                    : {}),
+                ...('cardinality' in field ? { to: field.to, cardinality: field.cardinality } : {}),
+                ...(field.kind === 'geo' ? { region: field.region ?? null } : {}),
+                ...('weights' in field ? { weights: field.weights ?? null } : {}),
+                ...('window' in field ? { window: field.window ?? null } : {}),
+                ...('trend' in field ? { trend: field.trend ?? null } : {}),
+                ...('default' in field ? { default: field.default ?? null } : {}),
+                ...(canvasFields.has(`${entity.name}.${field.name}`) ? { canvas: true } : {}),
+            })),
+        })),
+    };
+    return hashString(JSON.stringify(payload));
+}
+export function blueprintGeneratorVersion(blueprint) {
+    return ((hashBlueprint(blueprint) ^
+        ((BLUEPRINT_GENERATOR_SDK * 1_000_003) >>> 0) ^
+        ((GENERATOR_SDK_VERSION * 97) >>> 0)) >>>
+        0);
+}

package/dist/generator.d.ts

@@ -0,0 +1,34 @@
+import type { GenerateContext, WorldSeed } from '@protoyard/core';
+import { type GeoRegionId } from '@protoyard/scenarios';
+import type { Blueprint, BlueprintEntity } from './schema.ts';
+/**
+ * Deterministic world generator for a blueprint. Import from
+ * `@protoyard/blueprint/generator` (lazy) so Faker never enters the initial chunk.
+ *
+ * Determinism only: ctx.rng, ctx.faker, ctx.ids, ctx.time (no ambient clocks or PRNGs).
+ */
+export { BLUEPRINT_GENERATOR_SDK, blueprintGeneratorVersion, hashBlueprint, } from './generator-version.ts';
+/** Region for geo fields that do not name one. */
+export declare const DEFAULT_GEO_REGION: GeoRegionId;
+/** Faker paths blueprints may name in `field.fake` (everything else is ignored). */
+export declare const ALLOWED_FAKE_PATHS: readonly ["company.name", "company.catchPhrase", "person.fullName", "person.firstName", "person.lastName", "person.jobTitle", "lorem.sentence", "lorem.paragraph", "lorem.words", "internet.email", "internet.url", "internet.username", "phone.number", "commerce.productName", "location.city", "location.country", "location.streetAddress", "commerce.department", "company.buzzPhrase", "word.words"];
+export type AllowedFakePath = (typeof ALLOWED_FAKE_PATHS)[number];
+export interface BlueprintGenerator {
+    /** Builds a WorldSeed for the scenario context. */
+    generate(ctx: GenerateContext): WorldSeed;
+    /**
+     * Trace id for ActiveScenarioInfo: mixes blueprint content hash with the
+     * blueprint generator SDK and the scenarios package SDK version.
+     */
+    readonly generatorVersion: number;
+}
+/**
+ * Entity order so relation targets are generated before dependents.
+ * Cycles fall back to declaration order for the remaining nodes.
+ */
+export declare function topologicalEntities(blueprint: Blueprint): BlueprintEntity[];
+/**
+ * Builds a generator bound to one blueprint. Prefer:
+ * `const { generate } = await import('@protoyard/blueprint/generator').then(m => m.createBlueprintGenerator(bp))`
+ */
+export declare function createBlueprintGenerator(blueprint: Blueprint): BlueprintGenerator;

package/dist/generator.js

@@ -0,0 +1,445 @@
+import { createAvatarPool, generateTeam, geoPoints, timeSeries, } from '@protoyard/scenarios';
+import { canvasFieldsByEntity, seedCanvas } from "./canvas-seed.js";
+import { blueprintGeneratorVersion } from "./generator-version.js";
+import { dateWindowDays, entityTable } from "./schema.js";
+import { FEATURE_TABLES } from "./storage.js";
+import { inputProperty } from "./validation.js";
+/**
+ * Deterministic world generator for a blueprint. Import from
+ * `@protoyard/blueprint/generator` (lazy) so Faker never enters the initial chunk.
+ *
+ * Determinism only: ctx.rng, ctx.faker, ctx.ids, ctx.time (no ambient clocks or PRNGs).
+ */
+// The version hash lives in a small module so the runtime definition can read
+// it without pulling this generator into the initial chunk.
+export { BLUEPRINT_GENERATOR_SDK, blueprintGeneratorVersion, hashBlueprint, } from "./generator-version.js";
+/** Region for geo fields that do not name one. */
+export const DEFAULT_GEO_REGION = 'metro-grid';
+/** Faker paths blueprints may name in `field.fake` (everything else is ignored). */
+export const ALLOWED_FAKE_PATHS = [
+    'company.name',
+    'company.catchPhrase',
+    'person.fullName',
+    'person.firstName',
+    'person.lastName',
+    'person.jobTitle',
+    'lorem.sentence',
+    'lorem.paragraph',
+    'lorem.words',
+    'internet.email',
+    'internet.url',
+    'internet.username',
+    'phone.number',
+    'commerce.productName',
+    'location.city',
+    'location.country',
+    'location.streetAddress',
+    'commerce.department',
+    'company.buzzPhrase',
+    'word.words',
+];
+const ALLOWED = new Set(ALLOWED_FAKE_PATHS);
+const EXAMPLE_DOMAINS = ['example.com', 'example.org'];
+/**
+ * Entity order so relation targets are generated before dependents.
+ * Cycles fall back to declaration order for the remaining nodes.
+ */
+export function topologicalEntities(blueprint) {
+    const byName = new Map(blueprint.entities.map((e) => [e.name, e]));
+    const deps = new Map();
+    for (const entity of blueprint.entities) {
+        const need = new Set();
+        for (const field of entity.fields) {
+            if (field.kind === 'relation' && byName.has(field.to) && field.to !== entity.name) {
+                need.add(field.to);
+            }
+        }
+        deps.set(entity.name, need);
+    }
+    const remaining = new Set(blueprint.entities.map((e) => e.name));
+    const ordered = [];
+    while (remaining.size > 0) {
+        const ready = [...remaining].filter((name) => [...(deps.get(name) ?? [])].every((d) => !remaining.has(d)));
+        const batch = ready.length > 0 ? ready : [[...remaining][0]];
+        // Stable: keep declaration order within each batch.
+        const sorted = blueprint.entities.map((e) => e.name).filter((name) => batch.includes(name));
+        for (const name of sorted) {
+            remaining.delete(name);
+            ordered.push(byName.get(name));
+        }
+    }
+    return ordered;
+}
+function baseCountFor(entity, blueprint) {
+    // Roots (nothing points at them less) get a smaller base; dependents a larger one.
+    const incoming = blueprint.entities.some((other) => other.fields.some((f) => f.kind === 'relation' && f.to === entity.name));
+    return incoming ? 8 : 4;
+}
+function callFake(faker, path) {
+    if (!ALLOWED.has(path))
+        return undefined;
+    const [mod, method] = path.split('.');
+    const namespace = faker[mod];
+    const fn = namespace?.[method];
+    if (typeof fn !== 'function')
+        return undefined;
+    return fn.call(namespace);
+}
+function emailFrom(faker, rng) {
+    const local = String(faker.internet.username())
+        .toLowerCase()
+        .replace(/[^a-z0-9._+-]/g, '')
+        .slice(0, 24) || 'user';
+    const domain = rng.pick([...EXAMPLE_DOMAINS]);
+    return `${local}@${domain}`;
+}
+function exampleUrl(faker, rng) {
+    return `https://${rng.pick([...EXAMPLE_DOMAINS])}/${faker.internet.username().toLowerCase()}`;
+}
+function examplePhone(rng) {
+    return `+1-555-${String(rng.int(100, 999))}-${String(rng.int(1000, 9999))}`;
+}
+/**
+ * Faker emails, URLs and phone numbers can name real domains and numbers, so a
+ * hint for one of them (on a text field) is replaced by the fictional form.
+ */
+function exampleOnly(path, hinted, faker, rng) {
+    if (path === 'internet.email')
+        return emailFrom(faker, rng);
+    if (path === 'internet.url')
+        return exampleUrl(faker, rng);
+    if (path === 'phone.number')
+        return examplePhone(rng);
+    return hinted;
+}
+const MS_PER_DAY = 86_400_000;
+/**
+ * An instant inside a date field's window: a uniform day, then business hours
+ * (09:00–17:00 UTC, quarter hours) for datetimes and noon for dates. Never
+ * before the organization started; after now only when the window says so.
+ */
+function windowInstant(field, ctx, orgStart) {
+    const { from, to } = dateWindowDays(field.window);
+    const now = ctx.time.now.getTime();
+    const floor = orgStart.getTime();
+    const lo = from === null ? floor : Math.max(floor, now + from * MS_PER_DAY);
+    const hi = Math.max(lo, now + to * MS_PER_DAY);
+    const day = Math.floor((lo + ctx.rng.next() * (hi - lo)) / MS_PER_DAY) * MS_PER_DAY;
+    const minutes = field.kind === 'date'
+        ? 12 * 60
+        : ctx.rng.int(9, 16) * 60 + ctx.rng.pick([0, 15, 30, 45]);
+    return Math.min(hi, Math.max(lo, day + minutes * 60_000));
+}
+const TREND_RATES = { flat: 0, growth: 0.2, decline: -0.12, seasonal: 0 };
+/**
+ * Daily values for a trended field from the organization start to now, built
+ * with `timeSeries` (level at now = middle of the field's range). A row takes
+ * the value of its `createdAt` day, so charts over createdAt show the trend.
+ */
+function trendByDay(field, entity, ctx, orgCreatedAt) {
+    const lo = field.min ?? 0;
+    const hi = field.max ?? (field.kind === 'money' ? 100_000 : lo + 100);
+    const days = Math.max(1, Math.ceil((ctx.time.now.getTime() - Date.parse(orgCreatedAt)) / MS_PER_DAY) + 1);
+    const seasonality = field.trend === 'seasonal' ? 'weekly+annual' : 'none';
+    const points = timeSeries({
+        ctx,
+        key: `blueprint:${entity.name}.${field.name}`,
+        days,
+        base: (lo + hi) / 2,
+        trend: TREND_RATES[field.trend ?? 'flat'],
+        seasonality,
+        noise: 0.08,
+        min: lo,
+        max: hi,
+        integer: field.kind !== 'number',
+    });
+    return new Map(points.map((p) => [p.at.slice(0, 10), p.value]));
+}
+function valueForField(field, ctx, personas, tables, byName, orgCreatedAt) {
+    const { faker, rng, time } = ctx;
+    const orgStart = new Date(orgCreatedAt);
+    // Faces are dealt per entity field from a seeded pool (see createBlueprintGenerator).
+    if (field.kind === 'avatar')
+        return null;
+    if ('default' in field && field.default !== undefined && !field.required && rng.chance(0.15)) {
+        return field.default;
+    }
+    // URL and phone fields keep their example-only generators (example.com, 555 numbers).
+    if (field.fake && field.kind !== 'url' && field.kind !== 'phone') {
+        const hinted = callFake(faker, field.fake);
+        if (hinted !== undefined) {
+            if (field.kind === 'email')
+                return emailFrom(faker, rng);
+            if (typeof hinted === 'string') {
+                let text = exampleOnly(field.fake, hinted, faker, rng);
+                if ('maxLength' in field && typeof field.maxLength === 'number') {
+                    text = text.slice(0, field.maxLength);
+                }
+                if ('minLength' in field &&
+                    typeof field.minLength === 'number' &&
+                    text.length < field.minLength) {
+                    text = (text + ' example').slice(0, Math.max(field.minLength, text.length));
+                }
+                return text;
+            }
+            return hinted;
+        }
+    }
+    switch (field.kind) {
+        case 'text': {
+            let text = String(faker.lorem.words(rng.int(2, 4)));
+            if (field.maxLength)
+                text = text.slice(0, field.maxLength);
+            if (field.minLength && text.length < field.minLength) {
+                text = `${text} ${'x'.repeat(field.minLength)}`.slice(0, field.minLength);
+            }
+            return text;
+        }
+        case 'longText':
+            return String(faker.lorem.paragraph()).slice(0, field.maxLength ?? 500);
+        case 'number': {
+            const min = field.min ?? 0;
+            const max = field.max ?? min + 100;
+            return rng.float(min, max === min ? min + 1 : max);
+        }
+        case 'integer': {
+            const min = field.min ?? 0;
+            const max = field.max ?? min + 100;
+            return rng.int(min, max);
+        }
+        case 'money': {
+            const min = field.min ?? 0;
+            const max = field.max ?? 100_000;
+            return rng.int(min, max);
+        }
+        case 'boolean':
+            return rng.chance(0.5);
+        case 'date':
+        case 'datetime': {
+            // Integrity compares parsed instants to org.createdAt. Date-only
+            // `YYYY-MM-DD` is UTC midnight and can fall before org.createdAt on the
+            // same calendar day, so both kinds store full ISO instants ≥ org start.
+            if (field.window === undefined) {
+                const d = time.between(orgStart, time.now, rng.next);
+                const ms = Math.max(d.getTime(), orgStart.getTime());
+                return new Date(ms).toISOString();
+            }
+            return new Date(windowInstant(field, ctx, orgStart)).toISOString();
+        }
+        case 'enum':
+            return field.weights
+                ? rng.weighted(field.values.map((value, i) => [value, field.weights?.[i] ?? 0]))
+                : rng.pick(field.values);
+        case 'email':
+            return emailFrom(faker, rng);
+        case 'url':
+            return exampleUrl(faker, rng);
+        case 'phone':
+            return examplePhone(rng);
+        case 'tags': {
+            const n = rng.int(0, Math.min(3, field.maxItems ?? 8));
+            const tags = new Set();
+            while (tags.size < n)
+                tags.add(faker.lorem.word().toLowerCase());
+            return [...tags];
+        }
+        case 'relation': {
+            const target = byName.get(field.to);
+            if (!target)
+                return field.cardinality === 'many' ? [] : null;
+            const pool = tables[entityTable(target)] ?? [];
+            if (pool.length === 0)
+                return field.cardinality === 'many' ? [] : null;
+            if (field.cardinality === 'many') {
+                const count = rng.int(0, Math.min(3, pool.length));
+                return rng.sample(pool.map((r) => r.id), count);
+            }
+            if (field.required)
+                return rng.pick(pool).id;
+            return rng.chance(0.85) ? rng.pick(pool).id : null;
+        }
+        case 'persona':
+            if (personas.length === 0)
+                return null;
+            return field.required || rng.chance(0.9) ? rng.pick([...personas]).id : null;
+        case 'file':
+            return field.multiple ? [] : null;
+        case 'json':
+            return { note: String(faker.lorem.words(2)) };
+        default:
+            return null;
+    }
+}
+function stampRow(ctx, orgCreatedAt) {
+    const start = new Date(orgCreatedAt);
+    const createdAt = ctx.time.between(start, ctx.time.now, ctx.rng.next).toISOString();
+    const createdMs = Date.parse(createdAt);
+    const updatedAt = createdMs >= ctx.time.now.getTime()
+        ? createdAt
+        : ctx.time.between(new Date(createdMs), ctx.time.now, ctx.rng.next).toISOString();
+    return { createdAt, updatedAt };
+}
+function seedAuditHistory(ctx, blueprint, tables, personas) {
+    if (personas.length === 0)
+        return [];
+    const audited = blueprint.entities.filter((e) => e.features.audit);
+    if (audited.length === 0)
+        return [];
+    const rng = ctx.rng.fork('blueprint:audit-history');
+    const entries = [];
+    let seq = 0;
+    for (const entity of audited) {
+        const rows = tables[entityTable(entity)] ?? [];
+        const sample = rng.sample(rows, Math.min(rows.length, Math.max(1, Math.floor(rows.length / 2))));
+        for (const row of sample) {
+            const at = typeof row.createdAt === 'string' ? row.createdAt : ctx.time.now.toISOString();
+            entries.push({
+                id: ctx.ids.next('audit'),
+                entity: entity.name,
+                recordId: row.id,
+                actorId: rng.pick([...personas]).id,
+                action: 'create',
+                at,
+                seq: ++seq,
+                changes: {},
+            });
+        }
+    }
+    return entries;
+}
+function seedNotificationHistory(ctx, blueprint, tables, personas) {
+    if (personas.length === 0)
+        return [];
+    const wants = blueprint.notifications.length > 0 || blueprint.entities.some((e) => e.features.notifications);
+    if (!wants)
+        return [];
+    const rng = ctx.rng.fork('blueprint:notification-history');
+    const count = ctx.scale(3);
+    const rows = [];
+    for (let i = 0; i < count; i++) {
+        const persona = rng.pick([...personas]);
+        const entity = rng.pick(blueprint.entities);
+        const pool = tables[entityTable(entity)] ?? [];
+        const record = pool.length > 0 ? rng.pick(pool) : null;
+        const at = record && typeof record.createdAt === 'string'
+            ? record.createdAt
+            : ctx.time.now.toISOString();
+        rows.push({
+            id: ctx.ids.next('notification'),
+            personaId: persona.id,
+            kind: `${entity.name}.create`,
+            title: `Update on ${entity.name}`,
+            body: '',
+            createdAt: at,
+            readAt: rng.chance(0.4) ? at : null,
+            recordId: record?.id ?? null,
+        });
+    }
+    return rows;
+}
+/**
+ * Builds a generator bound to one blueprint. Prefer:
+ * `const { generate } = await import('@protoyard/blueprint/generator').then(m => m.createBlueprintGenerator(bp))`
+ */
+export function createBlueprintGenerator(blueprint) {
+    const order = topologicalEntities(blueprint);
+    const byName = new Map(blueprint.entities.map((e) => [e.name, e]));
+    const generatorVersion = blueprintGeneratorVersion(blueprint);
+    const canvasFields = canvasFieldsByEntity(blueprint);
+    const generate = (ctx) => {
+        const team = generateTeam(ctx);
+        const tables = {};
+        const orgCreatedAt = team.organization.createdAt;
+        for (const entity of order) {
+            const table = entityTable(entity);
+            const count = ctx.scale(entity.seedCount ?? baseCountFor(entity, blueprint));
+            const rows = [];
+            const rng = ctx.rng.fork(`entity:${entity.name}`);
+            // One point set per geo field: point i belongs to row i, and more rows keep earlier points.
+            const geo = entity.fields.flatMap((field) => field.kind === 'geo'
+                ? [
+                    {
+                        prop: inputProperty(field),
+                        required: field.required,
+                        points: geoPoints({
+                            ctx,
+                            region: field.region ?? DEFAULT_GEO_REGION,
+                            count,
+                            key: `${entity.name}.${field.name}`,
+                        }),
+                    },
+                ]
+                : []);
+            // One seeded face per row and avatar field: no repeats until the library runs out, and
+            // the team's faces are dealt last so records rarely share a face with a persona.
+            const avatars = entity.fields.flatMap((field) => field.kind === 'avatar'
+                ? [
+                    {
+                        prop: inputProperty(field),
+                        ids: createAvatarPool(ctx.rng.fork(`blueprint:avatars:${entity.name}.${field.name}`), {
+                            avoid: team.personas.map((persona) => persona.avatar),
+                        }).take(count),
+                    },
+                ]
+                : []);
+            const trends = entity.fields.flatMap((field) => (field.kind === 'number' || field.kind === 'integer' || field.kind === 'money') &&
+                field.trend !== undefined
+                ? [{ prop: inputProperty(field), byDay: trendByDay(field, entity, ctx, orgCreatedAt) }]
+                : []);
+            // A canvas screen's json field gets a seeded planning board, not the generic json value.
+            const canvases = entity.fields.flatMap((field) => canvasFields.get(entity.name)?.has(field.name) ? [inputProperty(field)] : []);
+            const titleProp = entity.fields.find((field) => field.name === entity.titleField);
+            for (let i = 0; i < count; i++) {
+                const fieldCtx = {
+                    ...ctx,
+                    rng: rng.fork(`row:${i}`),
+                };
+                const values = {};
+                for (const field of entity.fields) {
+                    values[inputProperty(field)] = valueForField(field, fieldCtx, team.personas, tables, byName, orgCreatedAt);
+                }
+                for (const { prop, required, points } of geo) {
+                    const point = points[i];
+                    values[prop] =
+                        point && (required || fieldCtx.rng.chance(0.9))
+                            ? { lat: point.lat, lng: point.lng }
+                            : null;
+                }
+                for (const { prop, ids } of avatars)
+                    values[prop] = ids[i] ?? null;
+                for (const prop of canvases) {
+                    const title = titleProp ? values[inputProperty(titleProp)] : undefined;
+                    values[prop] = seedCanvas(ctx.rng.fork(`blueprint:canvas:${entity.name}.${prop}:${i}`), typeof title === 'string' ? title : '');
+                }
+                const stamps = stampRow(fieldCtx, orgCreatedAt);
+                for (const { prop, byDay } of trends) {
+                    values[prop] = byDay.get(stamps.createdAt.slice(0, 10)) ?? values[prop];
+                }
+                rows.push({
+                    id: ctx.ids.next(entity.name.replace(/-/g, '_')),
+                    ...values,
+                    ...stamps,
+                    ...(entity.features.softDelete ? { deletedAt: null, deletedBy: null } : {}),
+                });
+            }
+            tables[table] = rows;
+        }
+        if (blueprint.entities.some((e) => e.features.audit)) {
+            tables[FEATURE_TABLES.audit] = seedAuditHistory(ctx, blueprint, tables, team.personas);
+        }
+        if (blueprint.notifications.length > 0 ||
+            blueprint.entities.some((e) => e.features.notifications)) {
+            tables[FEATURE_TABLES.notifications] = seedNotificationHistory(ctx, blueprint, tables, team.personas);
+        }
+        if (blueprint.entities.some((e) => e.features.files)) {
+            tables[FEATURE_TABLES.files] = [];
+        }
+        return {
+            organizations: team.organizations,
+            personas: team.personas,
+            memberships: team.memberships,
+            tables,
+        };
+    };
+    return { generate, generatorVersion };
+}

package/dist/identity.d.ts

@@ -0,0 +1,34 @@
+import type { AnyBlueprint } from './kinds/envelope.ts';
+/**
+ * Content identity for blueprints (ADR-030). A blueprint's identity is the
+ * SHA-256 of its canonical JSON, and its default storage namespace is derived
+ * from that digest, so every edit opens a fresh world and two different
+ * blueprints on one origin never share IndexedDB data.
+ *
+ * Uses Web Crypto (`crypto.subtle`), available in browsers and Node 20+.
+ * Never the 32-bit `hashString`: generator versions tolerate collisions,
+ * storage identity does not.
+ */
+export interface BlueprintIdentity {
+    /** Lowercase hex SHA-256 of `canonicalJson(blueprint)` (64 chars). */
+    readonly sha256: string;
+    /** `bp-` plus 26 base32 chars (130 bits of the digest): a valid manifest namespace. */
+    readonly namespace: string;
+}
+/** Prefix of every content-derived namespace. */
+export declare const BLUEPRINT_NAMESPACE_PREFIX = "bp-";
+/**
+ * JSON with object keys sorted (by UTF-16 code unit) at every depth and no
+ * whitespace. Array order is kept, `undefined` properties are dropped (as
+ * `JSON.stringify` does), and values JSON cannot represent (non-finite
+ * numbers, functions, symbols, bigints) throw instead of being silently changed.
+ */
+export declare function canonicalJson(value: unknown): string;
+/**
+ * The content identity of a parsed blueprint of any kind. Parse first (`parseBlueprint`, `parseAnyBlueprint`)
+ * so defaults are applied: a blueprint that omits `tags` and one that sets
+ * `tags: []` are the same product and share an identity. Key order and
+ * whitespace never matter. `$schema` is an editor hint, not content, and is
+ * left out.
+ */
+export declare function blueprintIdentity(blueprint: AnyBlueprint): Promise<BlueprintIdentity>;

package/dist/identity.js

@@ -0,0 +1,91 @@
+/** Prefix of every content-derived namespace. */
+export const BLUEPRINT_NAMESPACE_PREFIX = 'bp-';
+/** Base32 characters in a content-derived namespace (130 bits). */
+const NAMESPACE_CHARS = 26;
+/** RFC 4648 base32, lowercased so the namespace stays lowercase kebab-case. */
+const BASE32 = 'abcdefghijklmnopqrstuvwxyz234567';
+/**
+ * JSON with object keys sorted (by UTF-16 code unit) at every depth and no
+ * whitespace. Array order is kept, `undefined` properties are dropped (as
+ * `JSON.stringify` does), and values JSON cannot represent (non-finite
+ * numbers, functions, symbols, bigints) throw instead of being silently changed.
+ */
+export function canonicalJson(value) {
+    return render(value, new Set());
+}
+function render(value, seen) {
+    if (value === null)
+        return 'null';
+    switch (typeof value) {
+        case 'string':
+        case 'boolean':
+            return JSON.stringify(value);
+        case 'number':
+            if (!Number.isFinite(value))
+                throw new TypeError(`canonicalJson: ${value} is not JSON`);
+            return JSON.stringify(value);
+        case 'object':
+            break;
+        default:
+            throw new TypeError(`canonicalJson: a ${typeof value} is not JSON`);
+    }
+    const node = value;
+    if (seen.has(node))
+        throw new TypeError('canonicalJson: circular structure');
+    seen.add(node);
+    let out;
+    if (Array.isArray(node)) {
+        out = `[${node.map((item) => (item === undefined ? 'null' : render(item, seen))).join(',')}]`;
+    }
+    else {
+        const record = node;
+        const keys = Object.keys(record)
+            .filter((key) => record[key] !== undefined)
+            .sort();
+        out = `{${keys.map((key) => `${JSON.stringify(key)}:${render(record[key], seen)}`).join(',')}}`;
+    }
+    seen.delete(node);
+    return out;
+}
+function toHex(bytes) {
+    return Array.from(bytes, (byte) => byte.toString(16).padStart(2, '0')).join('');
+}
+/** The first `length` base32 characters of `bytes`, most significant bits first. */
+function toBase32(bytes, length) {
+    let out = '';
+    let buffer = 0;
+    let bits = 0;
+    for (const byte of bytes) {
+        buffer = ((buffer << 8) | byte) & 0xffff;
+        bits += 8;
+        while (bits >= 5 && out.length < length) {
+            out += BASE32[(buffer >> (bits - 5)) & 31];
+            bits -= 5;
+        }
+        if (out.length === length)
+            break;
+    }
+    return out;
+}
+async function sha256(text) {
+    const subtle = globalThis.crypto?.subtle;
+    if (!subtle)
+        throw new Error('blueprintIdentity needs Web Crypto (crypto.subtle)');
+    const digest = await subtle.digest('SHA-256', new TextEncoder().encode(text));
+    return new Uint8Array(digest);
+}
+/**
+ * The content identity of a parsed blueprint of any kind. Parse first (`parseBlueprint`, `parseAnyBlueprint`)
+ * so defaults are applied: a blueprint that omits `tags` and one that sets
+ * `tags: []` are the same product and share an identity. Key order and
+ * whitespace never matter. `$schema` is an editor hint, not content, and is
+ * left out.
+ */
+export async function blueprintIdentity(blueprint) {
+    const { $schema: _schema, ...content } = blueprint;
+    const bytes = await sha256(canonicalJson(content));
+    return {
+        sha256: toHex(bytes),
+        namespace: `${BLUEPRINT_NAMESPACE_PREFIX}${toBase32(bytes, NAMESPACE_CHARS)}`,
+    };
+}