@protoyard/blueprint 0.0.0-stage → 1.1.0

package/dist/variants.js

@@ -0,0 +1,283 @@
+import { createRng } from '@protoyard/core';
+import { entityLabel } from "./app-model.js";
+import { canonicalJson } from "./identity.js";
+import { parseBlueprint } from "./schema.js";
+/**
+ * Deterministic blueprint variants for `protoyard quick --variants` (ADR-031).
+ * Each variant changes the shell, not the domain: its layout, theme, spacing
+ * density and which entity comes first. Entities, fields, roles and data stay
+ * the same, so variants of one idea compare like for like.
+ *
+ * The theme and layout catalogs come from the caller (the CLI reads them from
+ * @protoyard/themes and @protoyard/core), so this module needs no theme code.
+ * Randomness is a core seeded RNG over the caller's seed plus the blueprint's
+ * canonical JSON: the same input always yields byte-identical variants.
+ */
+/** Built-in theme presets a brand can name (`brand.preset`); other theme ids are library themes. */
+export const VARIANT_THEME_PRESETS = [
+    'violet',
+    'ocean',
+    'emerald',
+    'rose',
+    'amber',
+    'monochrome',
+];
+export const VARIANT_DENSITIES = ['compact', 'comfortable', 'spacious'];
+/** `brand.density` multipliers (the schema allows 0.75–1.25). */
+export const VARIANT_DENSITY_SCALE = {
+    compact: 0.85,
+    comfortable: 1,
+    spacious: 1.15,
+};
+export const VARIANT_MAX_COUNT = 8;
+const PRESETS = new Set(VARIANT_THEME_PRESETS);
+function titleCase(id) {
+    return id
+        .split('-')
+        .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+        .join(' ');
+}
+function unique(values) {
+    return [...new Set(values)];
+}
+/** Whether a brand built from `theme` (or the current brand) can carry `brand.density`. */
+function densityApplies(blueprint, theme) {
+    if (theme !== null)
+        return PRESETS.has(theme);
+    const brand = blueprint.brand;
+    return brand !== undefined && brand.libraryTheme === undefined;
+}
+function combos(blueprint, axes) {
+    const layouts = axes.layouts?.length ? unique(axes.layouts) : [null];
+    const themes = axes.themes?.length ? unique(axes.themes) : [null];
+    const densities = unique(axes.densities ?? VARIANT_DENSITIES);
+    const primaries = axes.emphasis === false || blueprint.entities.length < 2
+        ? [null]
+        : blueprint.entities.map((entity) => entity.name);
+    const out = [];
+    for (const layout of layouts) {
+        for (const theme of themes) {
+            const options = densities.length > 0 && densityApplies(blueprint, theme) ? densities : [null];
+            for (const density of options) {
+                for (const primary of primaries)
+                    out.push({ layout, theme, density, primary });
+            }
+        }
+    }
+    return out;
+}
+function themedBrand(blueprint, combo) {
+    const current = blueprint.brand;
+    if (combo.theme === null) {
+        if (combo.density === null || current === undefined)
+            return current;
+        const { density: _density, ...rest } = current;
+        return { ...rest, ...densityKey(combo.density) };
+    }
+    const name = current?.name;
+    if (PRESETS.has(combo.theme)) {
+        return {
+            ...(name === undefined ? {} : { name }),
+            preset: combo.theme,
+            ...(combo.density === null ? {} : densityKey(combo.density)),
+        };
+    }
+    return { ...(name === undefined ? {} : { name }), libraryTheme: combo.theme };
+}
+/** `comfortable` is the default spacing, so it drops `brand.density` instead of writing 1. */
+function densityKey(density) {
+    return density === 'comfortable' ? {} : { density: VARIANT_DENSITY_SCALE[density] };
+}
+function moveFirst(items, matches) {
+    return [...items.filter(matches), ...items.filter((item) => !matches(item))];
+}
+function apply(blueprint, combo) {
+    const next = structuredClone(blueprint);
+    if (combo.layout !== null) {
+        const mobile = next.layout?.mobile;
+        next.layout = { id: combo.layout, ...(mobile === undefined ? {} : { mobile }) };
+    }
+    const brand = themedBrand(next, combo);
+    if (brand === undefined)
+        delete next.brand;
+    else
+        next.brand = brand;
+    if (combo.primary !== null) {
+        const primary = combo.primary;
+        next.entities = moveFirst(next.entities, (entity) => entity.name === primary);
+        next.screens = moveFirst(next.screens, (screen) => 'entity' in screen && screen.entity === primary);
+    }
+    return parseBlueprint(next);
+}
+function label(blueprint, combo) {
+    const parts = [];
+    if (combo.layout !== null)
+        parts.push(`${titleCase(combo.layout)} layout`);
+    if (combo.theme !== null)
+        parts.push(`${titleCase(combo.theme)} theme`);
+    if (combo.density !== null)
+        parts.push(titleCase(combo.density));
+    if (combo.primary !== null) {
+        const entity = blueprint.entities.find((candidate) => candidate.name === combo.primary);
+        if (entity)
+            parts.push(`${entityLabel(entity)} first`);
+    }
+    return parts.length > 0 ? parts.join(' · ') : 'As written';
+}
+function changes(combo) {
+    return {
+        ...(combo.layout === null ? {} : { layout: combo.layout }),
+        ...(combo.theme === null ? {} : { theme: combo.theme }),
+        ...(combo.density === null ? {} : { density: combo.density }),
+        ...(combo.primary === null ? {} : { primaryEntity: combo.primary }),
+    };
+}
+/**
+ * Returns `count` distinct, valid variants of `blueprint`, none identical to
+ * the blueprint itself. Throws a RangeError when the axes cannot produce that
+ * many, and the schema's error when a catalog id is invalid (for example an
+ * unknown layout).
+ */
+export function deriveVariants(blueprint, options) {
+    const { count } = options;
+    if (!Number.isInteger(count) || count < 1 || count > VARIANT_MAX_COUNT) {
+        throw new RangeError(`count must be an integer from 1 to ${VARIANT_MAX_COUNT} (got ${count}).`);
+    }
+    const base = parseBlueprint(blueprint);
+    const baseJson = canonicalJson(base);
+    const rng = createRng(`protoyard-variants:${options.seed ?? ''}:${baseJson}`);
+    const seen = new Set([baseJson]);
+    const variants = [];
+    for (const combo of rng.shuffle(combos(base, options.axes ?? {}))) {
+        if (variants.length === count)
+            break;
+        const next = apply(base, combo);
+        const json = canonicalJson(next);
+        if (seen.has(json))
+            continue;
+        seen.add(json);
+        variants.push({
+            id: `v${variants.length + 1}`,
+            label: label(base, combo),
+            changes: changes(combo),
+            blueprint: next,
+        });
+    }
+    if (variants.length < count) {
+        throw new RangeError(`Only ${variants.length} distinct variant(s) are possible with these axes; add layouts or themes, or lower the count.`);
+    }
+    return variants;
+}
+// ── Content kinds (decks, pages, docs) ───────────────────────────────────────
+/** Deck transitions a variant may set (`deck.style.transition`). */
+export const VARIANT_DECK_TRANSITIONS = ['none', 'fade', 'slide', 'zoom', 'morph'];
+function kindCombos(kind, axes) {
+    const deck = kind === 'deck';
+    const themes = axes.themes?.length ? unique(axes.themes) : [null];
+    const transitions = deck
+        ? unique(axes.transitions ?? VARIANT_DECK_TRANSITIONS)
+        : [null];
+    const densities = unique(axes.densities ?? VARIANT_DENSITIES);
+    const fontPairs = deck && axes.fontPairs?.length ? unique(axes.fontPairs) : [null];
+    const out = [];
+    for (const theme of themes) {
+        // A page or doc brand carries a density only with a preset (a library theme has its own).
+        const options = densities.length === 0 || (!deck && theme !== null && !PRESETS.has(theme))
+            ? [null]
+            : densities;
+        for (const transition of transitions.length > 0 ? transitions : [null]) {
+            for (const density of options) {
+                for (const fontPair of fontPairs)
+                    out.push({ theme, transition, density, fontPair });
+            }
+        }
+    }
+    return out;
+}
+function applyKind(blueprint, combo) {
+    const next = structuredClone(blueprint);
+    if (next.kind === 'deck') {
+        const style = { ...next.deck.style };
+        if (combo.theme !== null) {
+            // A theme and a palette seed are exclusive (as in Deck Studio).
+            delete style.paletteSeed;
+            style.theme = combo.theme;
+        }
+        if (combo.transition !== null)
+            style.transition = combo.transition;
+        if (combo.density !== null)
+            style.density = combo.density;
+        if (combo.fontPair !== null)
+            style.fontPair = combo.fontPair;
+        next.deck = { ...next.deck, style };
+        return next;
+    }
+    const brand = themedBrand(next, {
+        layout: null,
+        theme: combo.theme,
+        density: combo.density,
+        primary: null,
+    });
+    if (brand === undefined)
+        delete next.brand;
+    else
+        next.brand = brand;
+    return next;
+}
+function kindLabel(combo) {
+    const parts = [];
+    if (combo.theme !== null)
+        parts.push(`${titleCase(combo.theme)} theme`);
+    if (combo.transition !== null)
+        parts.push(`${titleCase(combo.transition)} transition`);
+    if (combo.density !== null)
+        parts.push(titleCase(combo.density));
+    if (combo.fontPair !== null)
+        parts.push(`${titleCase(combo.fontPair)} fonts`);
+    return parts.length > 0 ? parts.join(' · ') : 'As written';
+}
+function kindChanges(combo) {
+    return {
+        ...(combo.theme === null ? {} : { theme: combo.theme }),
+        ...(combo.transition === null ? {} : { transition: combo.transition }),
+        ...(combo.density === null ? {} : { density: combo.density }),
+        ...(combo.fontPair === null ? {} : { fontPair: combo.fontPair }),
+    };
+}
+/**
+ * `count` distinct variants of a deck, page or doc, none identical to it:
+ * only the style axes change (see `KindVariantAxes`). Deterministic like
+ * `deriveVariants`: the same blueprint, seed and axes give byte-identical
+ * variants. The caller validates the result (`safeParseAnyBlueprint`) when
+ * an axis value may be unknown. Throws a RangeError when the axes cannot
+ * produce that many.
+ */
+export function deriveKindVariants(blueprint, options) {
+    const { count } = options;
+    if (!Number.isInteger(count) || count < 1 || count > VARIANT_MAX_COUNT) {
+        throw new RangeError(`count must be an integer from 1 to ${VARIANT_MAX_COUNT} (got ${count}).`);
+    }
+    const baseJson = canonicalJson(blueprint);
+    const rng = createRng(`protoyard-kind-variants:${options.seed ?? ''}:${baseJson}`);
+    const seen = new Set([baseJson]);
+    const variants = [];
+    for (const combo of rng.shuffle(kindCombos(blueprint.kind, options.axes ?? {}))) {
+        if (variants.length === count)
+            break;
+        const next = applyKind(blueprint, combo);
+        const json = canonicalJson(next);
+        if (seen.has(json))
+            continue;
+        seen.add(json);
+        variants.push({
+            id: `v${variants.length + 1}`,
+            label: kindLabel(combo),
+            changes: kindChanges(combo),
+            blueprint: next,
+        });
+    }
+    if (variants.length < count) {
+        throw new RangeError(`Only ${variants.length} distinct variant(s) are possible with these axes; add themes or lower the count.`);
+    }
+    return variants;
+}

package/dist/workflows/index.d.ts

@@ -0,0 +1,3 @@
+export { type WorkflowAuthorization, WorkflowAuthorizationSchema, type WorkflowDefinition, type WorkflowDefinitionInput, WorkflowDefinitionSchema, type WorkflowState, WorkflowStateSchema, type WorkflowTransition, WorkflowTransitionSchema, } from './schema.ts';
+export { checkWorkflowTransition, type WorkflowTransitionCheck, type WorkflowTransitionContext, } from './transition.ts';
+export { validateWorkflowDefinition, type WorkflowDiagnostic, type WorkflowValidationResult, } from './validate.ts';

package/dist/workflows/index.js

@@ -0,0 +1,3 @@
+export { WorkflowAuthorizationSchema, WorkflowDefinitionSchema, WorkflowStateSchema, WorkflowTransitionSchema, } from "./schema.js";
+export { checkWorkflowTransition, } from "./transition.js";
+export { validateWorkflowDefinition, } from "./validate.js";

package/dist/workflows/schema.d.ts

@@ -0,0 +1,50 @@
+import { z } from 'zod';
+export declare const WorkflowAuthorizationSchema: z.ZodObject<{
+    roles: z.ZodArray<z.ZodString>;
+    capability: z.ZodString;
+}, z.core.$strict>;
+export declare const WorkflowStateSchema: z.ZodObject<{
+    id: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const WorkflowTransitionSchema: z.ZodObject<{
+    from: z.ZodString;
+    to: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+    guards: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        field: z.ZodString;
+        equals: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>;
+    }, z.core.$strict>>>;
+    authorization: z.ZodOptional<z.ZodObject<{
+        roles: z.ZodArray<z.ZodString>;
+        capability: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/** A data-only state machine bound to one enum field on one blueprint entity. */
+export declare const WorkflowDefinitionSchema: z.ZodObject<{
+    entity: z.ZodString;
+    field: z.ZodString;
+    initialState: z.ZodString;
+    states: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    transitions: z.ZodArray<z.ZodObject<{
+        from: z.ZodString;
+        to: z.ZodString;
+        label: z.ZodOptional<z.ZodString>;
+        guards: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            field: z.ZodString;
+            equals: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>;
+        }, z.core.$strict>>>;
+        authorization: z.ZodOptional<z.ZodObject<{
+            roles: z.ZodArray<z.ZodString>;
+            capability: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type WorkflowDefinition = z.infer<typeof WorkflowDefinitionSchema>;
+export type WorkflowDefinitionInput = z.input<typeof WorkflowDefinitionSchema>;
+export type WorkflowState = z.infer<typeof WorkflowStateSchema>;
+export type WorkflowTransition = z.infer<typeof WorkflowTransitionSchema>;
+export type WorkflowAuthorization = z.infer<typeof WorkflowAuthorizationSchema>;

package/dist/workflows/schema.js

@@ -0,0 +1,34 @@
+import { z } from 'zod';
+const identifier = z.string().min(1).max(80);
+export const WorkflowAuthorizationSchema = z.strictObject({
+    /** Blueprint roles permitted to take this transition. */
+    roles: z.array(identifier).min(1),
+    /** Capability these roles must hold on the workflow entity. */
+    capability: z.string().min(1).max(120),
+});
+export const WorkflowStateSchema = z.strictObject({
+    /** Stable state id; when validated, this must be one of the enum values. */
+    id: identifier,
+    label: z.string().min(1).max(60).optional(),
+});
+export const WorkflowTransitionSchema = z.strictObject({
+    from: identifier,
+    to: identifier,
+    label: z.string().min(1).max(60).optional(),
+    /** Simple field equality guards only; no predicates or executable expressions. */
+    guards: z
+        .array(z.strictObject({
+        field: identifier,
+        equals: z.union([z.string(), z.number().finite(), z.boolean(), z.null()]),
+    }))
+        .default([]),
+    authorization: WorkflowAuthorizationSchema.optional(),
+});
+/** A data-only state machine bound to one enum field on one blueprint entity. */
+export const WorkflowDefinitionSchema = z.strictObject({
+    entity: identifier,
+    field: identifier,
+    initialState: identifier,
+    states: z.array(WorkflowStateSchema).min(1),
+    transitions: z.array(WorkflowTransitionSchema),
+});

package/dist/workflows/transition.d.ts

@@ -0,0 +1,15 @@
+import type { WorkflowDefinition } from './schema.ts';
+export type WorkflowTransitionCheck = {
+    allowed: true;
+    transition: WorkflowDefinition['transitions'][number];
+} | {
+    allowed: false;
+    reason: 'unknown-state' | 'transition-not-allowed' | 'field-guard-failed' | 'role-not-authorized' | 'capability-not-held';
+};
+export type WorkflowTransitionContext = {
+    role?: string;
+    capabilities?: readonly string[];
+    record?: Readonly<Record<string, unknown>>;
+};
+/** Pure deterministic check; callers still enforce real service policy before a write. */
+export declare function checkWorkflowTransition(workflow: WorkflowDefinition, from: string, to: string, context?: WorkflowTransitionContext): WorkflowTransitionCheck;

package/dist/workflows/transition.js

@@ -0,0 +1,25 @@
+/** Pure deterministic check; callers still enforce real service policy before a write. */
+export function checkWorkflowTransition(workflow, from, to, context = {}) {
+    const states = new Set(workflow.states.map((state) => state.id));
+    if (!states.has(from) || !states.has(to))
+        return { allowed: false, reason: 'unknown-state' };
+    const transition = workflow.transitions.find((candidate) => candidate.from === from && candidate.to === to);
+    if (!transition)
+        return { allowed: false, reason: 'transition-not-allowed' };
+    if (transition.guards.some((guard) => !Object.hasOwn(context.record ?? {}, guard.field) ||
+        !Object.is(context.record?.[guard.field], guard.equals))) {
+        return { allowed: false, reason: 'field-guard-failed' };
+    }
+    const authorization = transition.authorization;
+    if (authorization) {
+        if (context.role === undefined || !authorization.roles.includes(context.role)) {
+            return { allowed: false, reason: 'role-not-authorized' };
+        }
+        const capabilities = context.capabilities ?? [];
+        if (capabilities.includes(`-${authorization.capability}`) ||
+            (!capabilities.includes('*') && !capabilities.includes(authorization.capability))) {
+            return { allowed: false, reason: 'capability-not-held' };
+        }
+    }
+    return { allowed: true, transition };
+}

package/dist/workflows/validate.d.ts

@@ -0,0 +1,17 @@
+import type { Blueprint } from '../schema.ts';
+import { type WorkflowDefinition } from './schema.ts';
+export type WorkflowDiagnostic = {
+    path: (string | number)[];
+    message: string;
+};
+export type WorkflowValidationResult = {
+    valid: true;
+    workflow: WorkflowDefinition;
+    diagnostics: [];
+} | {
+    valid: false;
+    workflow: null;
+    diagnostics: WorkflowDiagnostic[];
+};
+/** Validate the workflow shape and its entity, enum states, role and capability references. */
+export declare function validateWorkflowDefinition(input: unknown, blueprint: Blueprint): WorkflowValidationResult;

package/dist/workflows/validate.js

@@ -0,0 +1,140 @@
+import { WorkflowDefinitionSchema } from "./schema.js";
+const ENTITY_ACTIONS = [
+    'read',
+    'create',
+    'update',
+    'update:own',
+    'delete',
+    'delete:own',
+    'import',
+    'export',
+];
+function hasCapability(blueprint, roleName, capability) {
+    const role = blueprint.roles.find((candidate) => candidate.name === roleName);
+    if (!role)
+        return false;
+    const separator = capability.indexOf(':');
+    const entity = capability.slice(0, separator);
+    const action = capability.slice(separator + 1);
+    if (!ENTITY_ACTIONS.includes(action))
+        return false;
+    let granted = false;
+    let denied = false;
+    for (const [target, permissions] of Object.entries(role.permissions)) {
+        if (target !== '*' && target !== entity)
+            continue;
+        for (const permission of permissions) {
+            if (permission === '*') {
+                granted = true;
+                continue;
+            }
+            if (permission.startsWith('-')) {
+                const blocked = permission.slice(1);
+                if (blocked === '*' ||
+                    blocked === capability ||
+                    (!blocked.includes(':') && (action === blocked || action.startsWith(`${blocked}:`)))) {
+                    denied = true;
+                }
+            }
+            else if (permission === action) {
+                granted = true;
+            }
+        }
+    }
+    return granted && !denied;
+}
+/** Validate the workflow shape and its entity, enum states, role and capability references. */
+export function validateWorkflowDefinition(input, blueprint) {
+    const parsed = WorkflowDefinitionSchema.safeParse(input);
+    if (!parsed.success) {
+        return {
+            valid: false,
+            workflow: null,
+            diagnostics: parsed.error.issues.map((issue) => ({
+                path: issue.path.filter((part) => typeof part === 'string' || typeof part === 'number'),
+                message: issue.message,
+            })),
+        };
+    }
+    const workflow = parsed.data;
+    const diagnostics = [];
+    const add = (path, message) => diagnostics.push({ path, message });
+    const entityIndex = blueprint.entities.findIndex((entity) => entity.name === workflow.entity);
+    const entity = blueprint.entities[entityIndex];
+    if (!entity) {
+        add(['entity'], `Unknown workflow entity "${workflow.entity}".`);
+    }
+    const fieldIndex = entity?.fields.findIndex((field) => field.name === workflow.field) ?? -1;
+    const field = fieldIndex >= 0 ? entity?.fields[fieldIndex] : undefined;
+    if (entity && !field) {
+        add(['field'], `Unknown field "${workflow.field}" on entity "${workflow.entity}".`);
+    }
+    else if (field && field.kind !== 'enum') {
+        add(['field'], `Workflow field "${workflow.field}" must be an enum field.`);
+    }
+    const stateIds = new Set();
+    for (const [index, state] of workflow.states.entries()) {
+        if (stateIds.has(state.id))
+            add(['states', index, 'id'], `Duplicate workflow state "${state.id}".`);
+        stateIds.add(state.id);
+        if (field?.kind === 'enum' && !field.values.includes(state.id)) {
+            add(['states', index, 'id'], `State "${state.id}" is not a value of enum field "${workflow.field}".`);
+        }
+    }
+    if (!stateIds.has(workflow.initialState)) {
+        add(['initialState'], `Initial state "${workflow.initialState}" is not declared.`);
+    }
+    const roleNames = new Set(blueprint.roles.map((role) => role.name));
+    const transitionPairs = new Set();
+    for (const [index, transition] of workflow.transitions.entries()) {
+        const path = ['transitions', index];
+        if (!stateIds.has(transition.from)) {
+            add([...path, 'from'], `Unknown source state "${transition.from}".`);
+        }
+        if (!stateIds.has(transition.to)) {
+            add([...path, 'to'], `Unknown destination state "${transition.to}".`);
+        }
+        if (transition.from === transition.to) {
+            add(path, 'A transition must move to a different state.');
+        }
+        const pair = `${transition.from}\u0000${transition.to}`;
+        if (transitionPairs.has(pair))
+            add(path, 'Duplicate transition for this state pair.');
+        transitionPairs.add(pair);
+        for (const [guardIndex, guard] of transition.guards.entries()) {
+            const guardField = entity?.fields.find((candidate) => candidate.name === guard.field);
+            const guardPath = [...path, 'guards', guardIndex, 'field'];
+            if (!guardField) {
+                add(guardPath, `Unknown guard field "${guard.field}" on entity "${workflow.entity}".`);
+            }
+            else {
+                const compatible = (['text', 'longText', 'email', 'url', 'phone', 'date', 'datetime', 'enum'].includes(guardField.kind) &&
+                    typeof guard.equals === 'string') ||
+                    (['number', 'integer', 'money'].includes(guardField.kind) &&
+                        typeof guard.equals === 'number') ||
+                    (guardField.kind === 'boolean' && typeof guard.equals === 'boolean');
+                if (!compatible) {
+                    add([...path, 'guards', guardIndex, 'equals'], `Guard value type does not match field "${guard.field}" (${guardField.kind}).`);
+                }
+            }
+        }
+        const authorization = transition.authorization;
+        if (!authorization)
+            continue;
+        const capabilityPrefix = `${workflow.entity}:`;
+        if (!authorization.capability.startsWith(capabilityPrefix)) {
+            add([...path, 'authorization', 'capability'], `Capability must belong to workflow entity "${workflow.entity}".`);
+        }
+        for (const [roleIndex, roleName] of authorization.roles.entries()) {
+            if (!roleNames.has(roleName)) {
+                add([...path, 'authorization', 'roles', roleIndex], `Unknown role "${roleName}".`);
+            }
+            else if (!hasCapability(blueprint, roleName, authorization.capability)) {
+                add([...path, 'authorization', 'roles', roleIndex], `Role "${roleName}" does not grant capability "${authorization.capability}".`);
+            }
+        }
+    }
+    return diagnostics.length > 0
+        ? { valid: false, workflow: null, diagnostics }
+        : { valid: true, workflow, diagnostics: [] };
+}