@texuli/spec 0.0.0-stage → 0.1.0-next.0

package/dist/validate.js

@@ -0,0 +1,118 @@
+import { isRecord, validateInstance } from "./dialect.js";
+const MAX_TREE_DEPTH = 64;
+/**
+ * Validate a blueprint envelope against the spec alone: the envelope schema,
+ * then every node against the catalog vocabulary (closed ids, closed prop
+ * names, prop kinds and enum values, required props, no platform-extension
+ * props from data) and the declared profile. With `catalogHash`, an envelope
+ * bound to another catalog is refused. This is the shared, target-neutral
+ * contract; URL policy, limits, grammar and rendering stay in the runtime
+ * validators (`@texuli/catalog/validate`).
+ */
+export function validateBlueprint(input, documents, options = {}) {
+    const diagnostics = validateInstance(documents.blueprintSchema, input).map((issue) => ({ code: 'schema', path: issue.path, message: `${issue.code}: ${issue.message}` }));
+    if (!isRecord(input))
+        return { ok: false, diagnostics };
+    if (options.catalogHash !== undefined && input.catalog !== options.catalogHash) {
+        diagnostics.push({
+            code: 'catalog-mismatch',
+            path: '$.catalog',
+            message: 'The blueprint is bound to another catalog.',
+        });
+    }
+    const portable = input.profile === 'portable';
+    if (isRecord(input.tree)) {
+        diagnostics.push(...validateTree(input.tree, documents.catalog, { portable, path: '$.tree' }));
+    }
+    return { ok: diagnostics.length === 0, diagnostics };
+}
+/** Check one catalog tree against the vocabulary. See {@link validateBlueprint}. */
+export function validateTree(tree, catalog, options = {}) {
+    const byId = new Map(catalog.components.map((c) => [c.id, c]));
+    const out = [];
+    const visit = (node, path, depth) => {
+        if (!isRecord(node) || typeof node.id !== 'string' || depth > MAX_TREE_DEPTH)
+            return;
+        const component = byId.get(node.id);
+        if (!component) {
+            out.push({
+                code: 'unknown-id',
+                path: `${path}.id`,
+                id: node.id,
+                message: `"${node.id}" is not in the catalog.`,
+            });
+        }
+        else {
+            if (options.portable && component.capability !== 'portable-core') {
+                out.push({
+                    code: 'unsupported-profile',
+                    path,
+                    id: node.id,
+                    message: `"${node.id}" is ${component.capability}, not portable core.`,
+                });
+            }
+            checkProps(node.props, component, `${path}.props`, out);
+        }
+        if (Array.isArray(node.children)) {
+            node.children.forEach((child, index) => {
+                visit(child, `${path}.children[${index}]`, depth + 1);
+            });
+        }
+    };
+    visit(tree, options.path ?? '$', 0);
+    return out;
+}
+function checkProps(props, component, path, out) {
+    const given = isRecord(props) ? props : {};
+    const id = component.id;
+    const declared = new Map(component.props.map((p) => [p.name, p]));
+    for (const [name, value] of Object.entries(given)) {
+        const here = `${path}.${name}`;
+        const prop = declared.get(name);
+        if (!prop) {
+            out.push({ code: 'unknown-prop', path: here, id, message: `"${id}" has no "${name}" prop.` });
+            continue;
+        }
+        if (prop.extension) {
+            out.push({
+                code: 'extension-prop',
+                path: here,
+                id,
+                message: `"${name}" is a ${prop.extension} extension (${prop.kind}) and cannot come from data.`,
+            });
+            continue;
+        }
+        const kindOk = prop.kind === 'string' || prop.kind === 'enum'
+            ? typeof value === 'string'
+            : prop.kind === 'number'
+                ? typeof value === 'number' && Number.isFinite(value)
+                : prop.kind === 'boolean'
+                    ? typeof value === 'boolean'
+                    : prop.kind === 'array'
+                        ? Array.isArray(value)
+                        : prop.kind === 'object'
+                            ? isRecord(value)
+                            : false;
+        if (!kindOk) {
+            out.push({ code: 'prop-type', path: here, id, message: `"${name}" must be ${prop.kind}.` });
+        }
+        else if (prop.kind === 'enum' && !(prop.enumValues ?? []).includes(value)) {
+            out.push({
+                code: 'enum-value',
+                path: here,
+                id,
+                message: `"${name}" must be one of ${(prop.enumValues ?? []).join(', ')}.`,
+            });
+        }
+    }
+    for (const prop of component.props) {
+        if (prop.required && !prop.extension && !Object.hasOwn(given, prop.name)) {
+            out.push({
+                code: 'missing-required',
+                path: `${path}.${prop.name}`,
+                id,
+                message: `"${id}" needs "${prop.name}".`,
+            });
+        }
+    }
+}

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+/** The semantic version of the spec documents in this package. */
+export declare const SPEC_VERSION = "0.1.0";

package/dist/version.js

@@ -0,0 +1,2 @@
+/** The semantic version of the spec documents in this package. */
+export const SPEC_VERSION = '0.1.0';

package/generated/typescript/blueprint.d.ts

@@ -0,0 +1,83 @@
+export type BlueprintStatus = 'draft' | 'validated' | 'active' | 'superseded';
+export type BlueprintEmitTier = 'developer' | 'untrusted';
+/** ADR-003 capability profile; portable fails closed until ids are audited portable. */
+export type BlueprintProfile = 'web' | 'portable';
+/** ISO 8601 with a zone. */
+export type BlueprintTime = string;
+export interface BlueprintGenerator {
+    kind: 'agent' | 'person' | 'tool';
+    name: string;
+    model?: string;
+}
+export interface BlueprintSource {
+    label: string;
+    /** Must also pass the untrusted URL policy. */
+    href?: string;
+}
+export interface BlueprintTrigger {
+    kind: 'request' | 'schedule' | 'calendar' | 'event';
+    label: string;
+}
+export interface BlueprintMeetingRef {
+    id: string;
+    title?: string;
+    startsAt?: BlueprintTime;
+}
+export interface BlueprintActivation {
+    by: string;
+    at: BlueprintTime;
+    digest: string;
+}
+export interface BlueprintProvenanceEntry {
+    at: BlueprintTime;
+    actor: string;
+    kind: 'apply' | 'undo' | 'redo';
+    ops: readonly BlueprintEditOp[];
+}
+/** One edit op. The fields each op kind takes are checked by the edit parser. */
+export interface BlueprintEditOp {
+    op: 'insert' | 'remove' | 'move' | 'setProp' | 'unsetProp' | 'replace' | 'replaceAll';
+    path?: BlueprintNodePath;
+    parent?: BlueprintNodePath;
+    index?: number;
+    name?: string;
+    /** Any plain JSON value. */
+    value?: unknown;
+    node?: BlueprintNode;
+    tree?: BlueprintNode;
+}
+export type BlueprintNodePath = readonly number[];
+/** One catalog node: id, props and children only. */
+export interface BlueprintNode {
+    /** A catalog component id. */
+    id: string;
+    /** Props checked against the component's catalog entry. */
+    props?: Readonly<Record<string, unknown>>;
+    children?: readonly BlueprintNode[];
+}
+/**
+ * Envelope version 1 around one catalog tree (ADR-003, audit G13). Mirrors what
+ * @texuli/catalog/envelope reads today; a declared status, activation or tier is display data,
+ * never authority. Planned minor additions: a spec version range, the native profile and several
+ * roots.
+ */
+export interface BlueprintEnvelope {
+    format: 'texuli-blueprint';
+    version: 1;
+    id: string;
+    /** The catalog build hash the tree was written against. */
+    catalog: string;
+    status: BlueprintStatus;
+    createdAt: BlueprintTime;
+    updatedAt: BlueprintTime;
+    generator: BlueprintGenerator;
+    tier?: BlueprintEmitTier;
+    profile?: BlueprintProfile;
+    asOf?: BlueprintTime;
+    sources?: readonly BlueprintSource[];
+    trigger?: BlueprintTrigger;
+    meetingRef?: BlueprintMeetingRef;
+    activatedBy?: BlueprintActivation;
+    provenance?: readonly BlueprintProvenanceEntry[];
+    tree: BlueprintNode;
+}

package/generated/typescript/blueprint.js

@@ -0,0 +1,3 @@
+// Generated by @texuli/spec from schemas/blueprint.schema.json. Do not edit: run the spec generator.
+// Spec 0.1.0, digest 47afaa4f056320fc4111239e03afd97e8a073bd8dbd6d2ef0dec2d171acb2f8e
+export {};

package/generated/typescript/catalog-schema.d.ts

@@ -0,0 +1,33 @@
+export interface SpecComponent {
+    id: string;
+    label: string;
+    summary: string;
+    group: string;
+    /** Product placement: the manifest tier. */
+    placement: 'app' | 'content';
+    /** Emission trust: the tiers that may emit the id. */
+    emit: readonly ('developer' | 'untrusted')[];
+    /** ADR-003 portability. unknown until audited. */
+    capability: 'portable-core' | 'web-only' | 'native-only' | 'unknown';
+    props: readonly SpecProp[];
+}
+export interface SpecProp {
+    name: string;
+    kind: 'string' | 'number' | 'boolean' | 'enum' | 'array' | 'object' | 'slot' | 'event' | 'unknown';
+    required?: boolean;
+    enumValues?: readonly string[];
+    /**
+     * A named platform extension: the prop does not cross the shared boundary (slot, event and
+     * unknown kinds).
+     */
+    extension?: 'web';
+}
+/**
+ * The platform-neutral catalog vocabulary, bootstrapped from the built catalog. Placement, emission
+ * trust and portability are separate fields.
+ */
+export interface SpecCatalog {
+    /** The built catalog this vocabulary was projected from. */
+    catalogHash: string;
+    components: readonly SpecComponent[];
+}

package/generated/typescript/catalog-schema.js

@@ -0,0 +1,3 @@
+// Generated by @texuli/spec from schemas/catalog.schema.json. Do not edit: run the spec generator.
+// Spec 0.1.0, digest 47afaa4f056320fc4111239e03afd97e8a073bd8dbd6d2ef0dec2d171acb2f8e
+export {};

package/generated/typescript/diagnostics.d.ts

@@ -0,0 +1,12 @@
+export interface SpecDiagnostic {
+    code: SpecDiagnosticCode;
+    path: string;
+    message: string;
+    id?: string;
+}
+export type SpecDiagnosticCode = 'schema' | 'unknown-id' | 'unknown-prop' | 'prop-type' | 'enum-value' | 'missing-required' | 'extension-prop' | 'catalog-mismatch' | 'unsupported-profile';
+/** The stable result shape of validating a blueprint against the spec. */
+export interface SpecValidation {
+    ok: boolean;
+    diagnostics: readonly SpecDiagnostic[];
+}

package/generated/typescript/diagnostics.js

@@ -0,0 +1,3 @@
+// Generated by @texuli/spec from schemas/diagnostics.schema.json. Do not edit: run the spec generator.
+// Spec 0.1.0, digest 47afaa4f056320fc4111239e03afd97e8a073bd8dbd6d2ef0dec2d171acb2f8e
+export {};

package/generated/typescript/manifest.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The spec version, the dialect and a SHA-256 for every normative file (manifest.json) or generated
+ * file (generated-manifest.json).
+ */
+export interface SpecManifest {
+    specVersion: string;
+    dialect: 'https://json-schema.org/draft/2020-12/schema';
+    files: Readonly<Record<string, string>>;
+}

package/generated/typescript/manifest.js

@@ -0,0 +1,3 @@
+// Generated by @texuli/spec from schemas/manifest.schema.json. Do not edit: run the spec generator.
+// Spec 0.1.0, digest 47afaa4f056320fc4111239e03afd97e8a073bd8dbd6d2ef0dec2d171acb2f8e
+export {};