@cynodia/axiom-ui 0.7.0-alpha.1

package/dist/example/domain.js

@@ -0,0 +1,469 @@
+import { ApplicationGraph, binary, call, collectionType, entityType, expressionRef, field, fieldId, fieldLocation, filter, find, forEach, group, groupType, identitySelector, itemLocation, literal, map, nodeId, optionalType, primitiveType, ref, stateLocation, } from '@cynodia/axiom-core';
+/**
+ * The order-management domain used by both research applications.
+ *
+ * **Business semantics only** — entities, state, actions, constraints. No UI, no
+ * presentation, no routes. Both the baseline application and the toolkit application build
+ * their UI on top of this identical graph, which is what makes the comparison a comparison of
+ * UI authoring rather than of two different applications.
+ */
+export const ENTITY_PRODUCT = nodeId('entity_product');
+export const F_PRODUCT_ID = fieldId('field_product_id');
+export const F_PRODUCT_NAME = fieldId('field_product_name');
+export const F_PRODUCT_PRICE = fieldId('field_product_price');
+export const F_PRODUCT_STOCK = fieldId('field_product_stock');
+export const F_PRODUCT_ACTIVE = fieldId('field_product_active');
+export const ENTITY_CUSTOMER = nodeId('entity_customer');
+export const F_CUSTOMER_ID = fieldId('field_customer_id');
+export const F_CUSTOMER_NAME = fieldId('field_customer_name');
+export const F_CUSTOMER_EMAIL = fieldId('field_customer_email');
+export const F_CUSTOMER_SINCE = fieldId('field_customer_since');
+export const ENTITY_ORDER = nodeId('entity_order');
+export const F_ORDER_ID = fieldId('field_order_id');
+export const F_ORDER_CUSTOMER = fieldId('field_order_customer');
+export const F_ORDER_PRODUCT = fieldId('field_order_product');
+export const F_ORDER_QUANTITY = fieldId('field_order_quantity');
+export const F_ORDER_TOTAL = fieldId('field_order_total');
+export const F_ORDER_STATUS = fieldId('field_order_status');
+export const STATE_PRODUCTS = nodeId('state_products');
+export const STATE_CUSTOMERS = nodeId('state_customers');
+export const STATE_ORDERS = nodeId('state_orders');
+export const STATE_DRAFT_PRODUCT = nodeId('state_draft_product');
+export const STATE_DRAFT_ORDER = nodeId('state_draft_order');
+export const STATE_DRAFT_CUSTOMER = nodeId('state_draft_customer');
+export const STATE_ORDER_COUNT = nodeId('state_order_count');
+export const STATE_REVENUE = nodeId('state_revenue');
+export const STATE_LOW_STOCK = nodeId('state_low_stock');
+export const STATE_LOW_STOCK_PRODUCTS = nodeId('state_low_stock_products');
+/** Orders partitioned by status: a `group` expression, not four filters. */
+export const STATE_ORDERS_BY_STATUS = nodeId('state_orders_by_status');
+/** Which order the person has asked to cancel. Ephemeral: a UI fact, not a domain one. */
+export const STATE_CANCELLING = nodeId('state_cancelling');
+/** The reorder threshold, so the rule below reads it rather than hard-coding it. */
+export const STATE_THRESHOLD = nodeId('state_threshold');
+/**
+ * "the products at or below the reorder threshold", named once.
+ *
+ * Three consumers read it: the dashboard figure, the restock warning's visibility, and the
+ * guard on the bulk-restock action. Written out, that is the same filter three times with
+ * three scope ids — which is where the Phase 2 agent collided with itself.
+ */
+export const EXPRESSION_LOW_STOCK = nodeId('expression_low_stock');
+export const PARAM_STOCK_SOURCE = nodeId('param_stock_source');
+export const ACTION_ADD_PRODUCT = nodeId('action_add_product');
+export const ACTION_DELETE_PRODUCT = nodeId('action_delete_product');
+export const ACTION_RESTOCK = nodeId('action_restock');
+export const ACTION_ADD_CUSTOMER = nodeId('action_add_customer');
+export const ACTION_PLACE_ORDER = nodeId('action_place_order');
+export const ACTION_CONFIRM_ORDER = nodeId('action_confirm_order');
+export const ACTION_CANCEL_ORDER = nodeId('action_cancel_order');
+export const ACTION_ASK_CANCEL = nodeId('action_ask_cancel');
+export const ACTION_DISMISS_CANCEL = nodeId('action_dismiss_cancel');
+export const ACTION_RESTOCK_ALL = nodeId('action_restock_all');
+export const PARAM_PRODUCT = nodeId('param_product');
+export const PARAM_ORDER = nodeId('param_order');
+export const PARAM_AMOUNT = nodeId('param_amount');
+const SCOPE_PRODUCT = nodeId('scope_product');
+const SCOPE_LOW_STOCK = nodeId('scope_low_stock');
+const SCOPE_STATUS = nodeId('scope_status');
+const SCOPE_RESTOCK = nodeId('scope_restock');
+const SCOPE_ORDER = nodeId('scope_order');
+const SCOPE_LOW = nodeId('scope_low');
+const SCOPE_TOTAL = nodeId('scope_total');
+const CONSTRAINT_STOCK = nodeId('constraint_stock');
+const CONSTRAINT_QUANTITY = nodeId('constraint_quantity');
+const TRANSITION_CONFIRMED = nodeId('transition_confirmed');
+const SCOPE_PREVIOUS = nodeId('scope_previous');
+const SCOPE_PROPOSED = nodeId('scope_proposed');
+const productById = (id) => find(ref(STATE_PRODUCTS), SCOPE_PRODUCT, binary('eq', field(ref(SCOPE_PRODUCT), F_PRODUCT_ID), id));
+/** The one calculation, referenced. Every consumer says this and nothing more. */
+export const lowStock = () => expressionRef(EXPRESSION_LOW_STOCK, { [PARAM_STOCK_SOURCE]: ref(STATE_PRODUCTS) });
+/** Entities, state, behaviour and rules. Nothing here knows a UI exists. */
+export function createOrderDomain() {
+    const graph = new ApplicationGraph('order-desk', 'Order Desk');
+    graph.addNode({
+        id: ENTITY_PRODUCT,
+        kind: 'entity',
+        name: 'Product',
+        identityFieldId: F_PRODUCT_ID,
+        fields: [
+            { id: F_PRODUCT_ID, name: 'Code', valueType: primitiveType('string'), required: true },
+            { id: F_PRODUCT_NAME, name: 'Name', valueType: primitiveType('string'), required: true },
+            { id: F_PRODUCT_PRICE, name: 'Unit price', valueType: primitiveType('number'), required: true },
+            { id: F_PRODUCT_STOCK, name: 'On hand', valueType: primitiveType('number'), required: true },
+            { id: F_PRODUCT_ACTIVE, name: 'Active', valueType: primitiveType('boolean') },
+        ],
+    });
+    graph.addNode({
+        id: ENTITY_CUSTOMER,
+        kind: 'entity',
+        name: 'Customer',
+        identityFieldId: F_CUSTOMER_ID,
+        fields: [
+            { id: F_CUSTOMER_ID, name: 'Reference', valueType: primitiveType('string'), required: true },
+            { id: F_CUSTOMER_NAME, name: 'Name', valueType: primitiveType('string'), required: true },
+            { id: F_CUSTOMER_EMAIL, name: 'Email', valueType: primitiveType('string'), required: true },
+            { id: F_CUSTOMER_SINCE, name: 'Customer since', valueType: primitiveType('date') },
+        ],
+    });
+    graph.addNode({
+        id: ENTITY_ORDER,
+        kind: 'entity',
+        name: 'Order',
+        identityFieldId: F_ORDER_ID,
+        fields: [
+            { id: F_ORDER_ID, name: 'Number', valueType: primitiveType('string'), required: true },
+            { id: F_ORDER_CUSTOMER, name: 'Customer', valueType: primitiveType('string'), required: true },
+            { id: F_ORDER_PRODUCT, name: 'Product', valueType: primitiveType('string'), required: true },
+            { id: F_ORDER_QUANTITY, name: 'Quantity', valueType: primitiveType('number'), required: true },
+            { id: F_ORDER_TOTAL, name: 'Total', valueType: primitiveType('number'), required: true },
+            { id: F_ORDER_STATUS, name: 'Status', valueType: primitiveType('string'), required: true },
+        ],
+    });
+    graph.addNode({
+        id: STATE_PRODUCTS,
+        kind: 'state',
+        name: 'Products',
+        valueType: collectionType(entityType(ENTITY_PRODUCT)),
+        initialValue: [
+            { [F_PRODUCT_ID]: 'bolt', [F_PRODUCT_NAME]: 'Hex bolt', [F_PRODUCT_PRICE]: 12.5, [F_PRODUCT_STOCK]: 40, [F_PRODUCT_ACTIVE]: true },
+            { [F_PRODUCT_ID]: 'nut', [F_PRODUCT_NAME]: 'Hex nut', [F_PRODUCT_PRICE]: 4.25, [F_PRODUCT_STOCK]: 2, [F_PRODUCT_ACTIVE]: true },
+            { [F_PRODUCT_ID]: 'washer', [F_PRODUCT_NAME]: 'Flat washer', [F_PRODUCT_PRICE]: 1.75, [F_PRODUCT_STOCK]: 500, [F_PRODUCT_ACTIVE]: false },
+        ],
+    });
+    graph.addNode({
+        id: STATE_CUSTOMERS,
+        kind: 'state',
+        name: 'Customers',
+        valueType: collectionType(entityType(ENTITY_CUSTOMER)),
+        initialValue: [
+            { [F_CUSTOMER_ID]: 'c1', [F_CUSTOMER_NAME]: 'Nordvik AS', [F_CUSTOMER_EMAIL]: 'post@nordvik.example', [F_CUSTOMER_SINCE]: '2024-03-01' },
+            { [F_CUSTOMER_ID]: 'c2', [F_CUSTOMER_NAME]: 'Fjell Bygg', [F_CUSTOMER_EMAIL]: 'kontakt@fjell.example', [F_CUSTOMER_SINCE]: '2025-11-14' },
+        ],
+    });
+    graph.addNode({
+        id: STATE_ORDERS,
+        kind: 'state',
+        name: 'Orders',
+        valueType: collectionType(entityType(ENTITY_ORDER)),
+        initialValue: [],
+    });
+    graph.addNode({
+        id: STATE_DRAFT_PRODUCT,
+        kind: 'state',
+        name: 'New product',
+        draft: true,
+        valueType: entityType(ENTITY_PRODUCT),
+        initialValue: { [F_PRODUCT_ID]: '', [F_PRODUCT_NAME]: '', [F_PRODUCT_PRICE]: 0, [F_PRODUCT_STOCK]: 0, [F_PRODUCT_ACTIVE]: true },
+    });
+    graph.addNode({
+        id: STATE_DRAFT_ORDER,
+        kind: 'state',
+        name: 'New order',
+        draft: true,
+        valueType: entityType(ENTITY_ORDER),
+        initialValue: {
+            [F_ORDER_ID]: '',
+            [F_ORDER_CUSTOMER]: '',
+            [F_ORDER_PRODUCT]: '',
+            [F_ORDER_QUANTITY]: 1,
+            [F_ORDER_TOTAL]: 0,
+            [F_ORDER_STATUS]: 'draft',
+        },
+    });
+    graph.addNode({
+        id: STATE_DRAFT_CUSTOMER,
+        kind: 'state',
+        name: 'New customer',
+        draft: true,
+        valueType: entityType(ENTITY_CUSTOMER),
+        initialValue: {
+            [F_CUSTOMER_ID]: '',
+            [F_CUSTOMER_NAME]: '',
+            [F_CUSTOMER_EMAIL]: '',
+            [F_CUSTOMER_SINCE]: '2026-01-01',
+        },
+    });
+    graph.addNode({
+        id: STATE_ORDER_COUNT,
+        kind: 'state',
+        name: 'Order count',
+        valueType: primitiveType('number'),
+        derivation: call('count', ref(STATE_ORDERS)),
+    });
+    graph.addNode({
+        id: STATE_REVENUE,
+        kind: 'state',
+        name: 'Revenue',
+        valueType: primitiveType('number'),
+        derivation: call('sum', map(ref(STATE_ORDERS), SCOPE_TOTAL, field(ref(SCOPE_TOTAL), F_ORDER_TOTAL))),
+    });
+    graph.addNode({
+        id: STATE_THRESHOLD,
+        kind: 'state',
+        name: 'Reorder threshold',
+        valueType: primitiveType('number'),
+        initialValue: 5,
+    });
+    /**
+     * The calculation exists **once**, as a node.
+     *
+     * Its parameter is the collection to look in, so the definition says nothing about where
+     * the products live; its body reads the threshold from state. Isolated scope: `SCOPE_LOW`
+     * belongs to this definition and can never meet a caller's iteration scope.
+     */
+    graph.addNode({
+        id: EXPRESSION_LOW_STOCK,
+        kind: 'expression',
+        name: 'Low stock',
+        description: 'Products at or below the reorder threshold.',
+        parameters: [
+            { id: PARAM_STOCK_SOURCE, name: 'products', valueType: collectionType(entityType(ENTITY_PRODUCT)) },
+        ],
+        expression: filter(ref(PARAM_STOCK_SOURCE), SCOPE_LOW, binary('lte', field(ref(SCOPE_LOW), F_PRODUCT_STOCK), ref(STATE_THRESHOLD))),
+    });
+    graph.addNode({
+        id: STATE_LOW_STOCK,
+        kind: 'state',
+        name: 'Low stock',
+        valueType: primitiveType('number'),
+        derivation: call('count', lowStock()),
+    });
+    // The same calculation again, as a collection this time. Two consumers, one definition.
+    graph.addNode({
+        id: STATE_LOW_STOCK_PRODUCTS,
+        kind: 'state',
+        name: 'Needs restocking',
+        valueType: collectionType(entityType(ENTITY_PRODUCT)),
+        derivation: lowStock(),
+    });
+    /**
+     * Orders by status, as a semantic partition.
+     *
+     * Before `group`, this was four filters over four statuses known at authoring time — which
+     * could not have handled a status the domain gained later, and could not have grouped by
+     * customer at all.
+     */
+    graph.addNode({
+        id: STATE_ORDERS_BY_STATUS,
+        kind: 'state',
+        name: 'Orders by status',
+        valueType: collectionType(groupType(primitiveType('string'), entityType(ENTITY_ORDER))),
+        derivation: group(ref(STATE_ORDERS), SCOPE_STATUS, field(ref(SCOPE_STATUS), F_ORDER_STATUS)),
+    });
+    graph.addNode({
+        id: STATE_CANCELLING,
+        kind: 'state',
+        name: 'Order awaiting cancellation',
+        // A UI fact, not a domain fact: instance validation skips it and it may not be persisted.
+        ephemeral: true,
+        valueType: primitiveType('string'),
+        initialValue: '',
+    });
+    graph.addNode({
+        id: ACTION_ADD_PRODUCT,
+        kind: 'action',
+        name: 'Add product',
+        guards: [
+            {
+                condition: call('non-empty', field(ref(STATE_DRAFT_PRODUCT), F_PRODUCT_NAME)),
+                failureMode: { code: 'name-required', message: 'A product needs a name.' },
+            },
+            {
+                condition: binary('gt', field(ref(STATE_DRAFT_PRODUCT), F_PRODUCT_PRICE), literal(0)),
+                failureMode: { code: 'price-required', message: 'A product needs a price above zero.' },
+            },
+        ],
+        operations: [{ kind: 'insert', target: stateLocation(STATE_PRODUCTS), value: ref(STATE_DRAFT_PRODUCT) }],
+    });
+    graph.addNode({
+        id: ACTION_DELETE_PRODUCT,
+        kind: 'action',
+        name: 'Delete product',
+        destructive: true,
+        requiresConfirmation: true,
+        confirmationMessage: 'Delete this product?',
+        parameters: [{ id: PARAM_PRODUCT, valueType: primitiveType('string'), required: true }],
+        operations: [
+            {
+                kind: 'remove',
+                target: itemLocation(stateLocation(STATE_PRODUCTS), identitySelector(F_PRODUCT_ID, ref(PARAM_PRODUCT))),
+            },
+        ],
+    });
+    graph.addNode({
+        id: ACTION_RESTOCK,
+        kind: 'action',
+        name: 'Restock',
+        parameters: [
+            { id: PARAM_PRODUCT, valueType: primitiveType('string'), required: true },
+            { id: PARAM_AMOUNT, valueType: primitiveType('number'), required: true },
+        ],
+        guards: [
+            {
+                condition: binary('gt', ref(PARAM_AMOUNT), literal(0)),
+                failureMode: { code: 'invalid-amount', message: 'Restock by a positive amount.' },
+            },
+        ],
+        operations: [
+            {
+                kind: 'set',
+                target: fieldLocation(itemLocation(stateLocation(STATE_PRODUCTS), identitySelector(F_PRODUCT_ID, ref(PARAM_PRODUCT))), F_PRODUCT_STOCK),
+                value: binary('add', field(productById(ref(PARAM_PRODUCT)), F_PRODUCT_STOCK), ref(PARAM_AMOUNT)),
+            },
+        ],
+    });
+    graph.addNode({
+        id: ACTION_ADD_CUSTOMER,
+        kind: 'action',
+        name: 'Add customer',
+        guards: [
+            {
+                condition: call('non-empty', field(ref(STATE_DRAFT_CUSTOMER), F_CUSTOMER_NAME)),
+                failureMode: { code: 'name-required', message: 'A customer needs a name.' },
+            },
+            {
+                condition: call('non-empty', field(ref(STATE_DRAFT_CUSTOMER), F_CUSTOMER_EMAIL)),
+                failureMode: { code: 'email-required', message: 'A customer needs an email address.' },
+            },
+        ],
+        operations: [{ kind: 'insert', target: stateLocation(STATE_CUSTOMERS), value: ref(STATE_DRAFT_CUSTOMER) }],
+    });
+    graph.addNode({
+        id: ACTION_PLACE_ORDER,
+        kind: 'action',
+        name: 'Place order',
+        guards: [
+            {
+                condition: call('non-empty', field(ref(STATE_DRAFT_ORDER), F_ORDER_CUSTOMER)),
+                failureMode: { code: 'customer-required', message: 'Choose a customer.' },
+            },
+            {
+                condition: binary('gte', field(productById(field(ref(STATE_DRAFT_ORDER), F_ORDER_PRODUCT)), F_PRODUCT_STOCK), field(ref(STATE_DRAFT_ORDER), F_ORDER_QUANTITY)),
+                failureMode: { code: 'insufficient-stock', message: 'Not enough stock for that quantity.' },
+            },
+        ],
+        operations: [
+            { kind: 'insert', target: stateLocation(STATE_ORDERS), value: ref(STATE_DRAFT_ORDER) },
+            {
+                kind: 'set',
+                target: fieldLocation(itemLocation(stateLocation(STATE_PRODUCTS), identitySelector(F_PRODUCT_ID, field(ref(STATE_DRAFT_ORDER), F_ORDER_PRODUCT))), F_PRODUCT_STOCK),
+                value: binary('subtract', field(productById(field(ref(STATE_DRAFT_ORDER), F_ORDER_PRODUCT)), F_PRODUCT_STOCK), field(ref(STATE_DRAFT_ORDER), F_ORDER_QUANTITY)),
+            },
+        ],
+    });
+    graph.addNode({
+        id: ACTION_CONFIRM_ORDER,
+        kind: 'action',
+        name: 'Confirm order',
+        parameters: [{ id: PARAM_ORDER, valueType: primitiveType('string'), required: true }],
+        operations: [
+            {
+                kind: 'set',
+                target: fieldLocation(itemLocation(stateLocation(STATE_ORDERS), identitySelector(F_ORDER_ID, ref(PARAM_ORDER))), F_ORDER_STATUS),
+                value: literal('confirmed'),
+            },
+        ],
+    });
+    graph.addNode({
+        id: ACTION_CANCEL_ORDER,
+        kind: 'action',
+        name: 'Cancel order',
+        destructive: true,
+        parameters: [{ id: PARAM_ORDER, valueType: primitiveType('string'), required: true }],
+        guards: [
+            {
+                // The rule, not the dialog: an invocation that never went through the confirmation
+                // is refused here, whatever the UI did or did not render.
+                condition: binary('eq', ref(STATE_CANCELLING), ref(PARAM_ORDER)),
+                failureMode: { code: 'not-confirmed', message: 'Confirm the cancellation first.' },
+            },
+        ],
+        operations: [
+            {
+                kind: 'remove',
+                target: itemLocation(stateLocation(STATE_ORDERS), identitySelector(F_ORDER_ID, ref(PARAM_ORDER))),
+            },
+            // Closing is this action's business: it cancelled the order, so the dialog is done.
+            { kind: 'set', target: stateLocation(STATE_CANCELLING), value: literal('') },
+        ],
+    });
+    /**
+     * Bulk restock, guarded by the same named calculation the dashboard displays.
+     *
+     * The guard cannot disagree with the figure, because there is only one calculation.
+     */
+    graph.addNode({
+        id: ACTION_RESTOCK_ALL,
+        kind: 'action',
+        name: 'Restock everything low',
+        parameters: [{ id: PARAM_AMOUNT, valueType: primitiveType('number'), required: true }],
+        guards: [
+            {
+                condition: call('non-empty', lowStock()),
+                failureMode: { code: 'nothing-low', message: 'Nothing is at or below the threshold.' },
+            },
+        ],
+        operations: [
+            forEach(lowStock(), SCOPE_RESTOCK, [
+                {
+                    kind: 'set',
+                    target: fieldLocation(itemLocation(stateLocation(STATE_PRODUCTS), identitySelector(F_PRODUCT_ID, field(ref(SCOPE_RESTOCK), F_PRODUCT_ID))), F_PRODUCT_STOCK),
+                    value: binary('add', field(ref(SCOPE_RESTOCK), F_PRODUCT_STOCK), ref(PARAM_AMOUNT)),
+                },
+            ]),
+        ],
+    });
+    /**
+     * Asking to cancel is not cancelling.
+     *
+     * Opening the dialog writes ephemeral state; the destructive action is guarded on that
+     * state, so invoking it without having asked is refused. Presentation never authorizes —
+     * a hidden or unrendered control is not a rule, and this is the rule.
+     */
+    graph.addNode({
+        id: ACTION_ASK_CANCEL,
+        kind: 'action',
+        name: 'Cancel order…',
+        parameters: [{ id: PARAM_ORDER, valueType: primitiveType('string'), required: true }],
+        operations: [{ kind: 'set', target: stateLocation(STATE_CANCELLING), value: ref(PARAM_ORDER) }],
+    });
+    graph.addNode({
+        id: ACTION_DISMISS_CANCEL,
+        kind: 'action',
+        name: 'Keep order',
+        operations: [{ kind: 'set', target: stateLocation(STATE_CANCELLING), value: literal('') }],
+    });
+    graph.addNode({
+        id: CONSTRAINT_STOCK,
+        kind: 'constraint',
+        name: 'Stock is never negative',
+        entityId: ENTITY_PRODUCT,
+        message: 'Stock can never fall below zero.',
+        expression: binary('gte', field(ref(ENTITY_PRODUCT), F_PRODUCT_STOCK), literal(0)),
+    });
+    graph.addNode({
+        id: CONSTRAINT_QUANTITY,
+        kind: 'constraint',
+        name: 'An order is for at least one unit',
+        entityId: ENTITY_ORDER,
+        message: 'An order must be for at least one unit.',
+        expression: binary('gte', field(ref(ENTITY_ORDER), F_ORDER_QUANTITY), literal(1)),
+    });
+    graph.addNode({
+        id: TRANSITION_CONFIRMED,
+        kind: 'transition-constraint',
+        name: 'A confirmed order never changes quantity',
+        entityId: ENTITY_ORDER,
+        previousScopeId: SCOPE_PREVIOUS,
+        proposedScopeId: SCOPE_PROPOSED,
+        message: 'A confirmed order cannot change quantity.',
+        expression: binary('or', binary('neq', field(ref(SCOPE_PREVIOUS), F_ORDER_STATUS), literal('confirmed')), binary('eq', field(ref(SCOPE_PROPOSED), F_ORDER_QUANTITY), field(ref(SCOPE_PREVIOUS), F_ORDER_QUANTITY))),
+    });
+    return graph;
+}
+/** Unused import guard: `optionalType`, `map` and `SCOPE_ORDER` are kept for domain growth. */
+void optionalType;
+void SCOPE_ORDER;
+void map;
+void SCOPE_LOW_STOCK;

package/dist/example/index.d.ts

@@ -0,0 +1,3 @@
+export * from './domain.js';
+export { createToolkitApplication } from './app.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/example/index.js

@@ -0,0 +1,2 @@
+export * from './domain.js';
+export { createToolkitApplication } from './app.js';

package/dist/expand.d.ts

@@ -0,0 +1,119 @@
+import type { ApplicationGraph, NodeId, UINode } from '@cynodia/axiom-core';
+import type { ExpansionModel, Ownership, PatternDeclaration, PatternDefinition, PatternFinding } from './pattern.js';
+/**
+ * Expansion: a pattern declaration becomes canonical Axiom UI, and nothing else happens.
+ *
+ * No node kind is invented, no runtime is told anything, and the graph that comes out is a
+ * graph an author could have written by hand. The three models differ only in what, if
+ * anything, is remembered about where the nodes came from.
+ */
+export interface ExpansionOptions {
+    /** Default: `provenance`. `macro` records nothing; `pattern-node` is the Model C probe. */
+    model?: ExpansionModel;
+    /**
+     * Who owns the generated nodes afterwards. Default `declaration`: the toolkit is an
+     * authoring layer, so the declaration is the source of truth and re-expansion is
+     * authoritative. Pass `graph` to expand once and own the result.
+     */
+    ownership?: Ownership;
+}
+/** What one pattern instance produced, for `inspectPattern` and for diagnostics. */
+export interface PatternExpansion {
+    instance: string;
+    pattern: string;
+    declaration: PatternDeclaration;
+    ownership: Ownership;
+    patternVersion: string;
+    rootId: NodeId;
+    nodeIds: NodeId[];
+    /** Every generated node as expansion produced it, for drift comparison. */
+    generated: Record<string, UINode>;
+    /** Why the expansion chose what it chose, in the order it decided. */
+    explanations: string[];
+    findings: PatternFinding[];
+    parent?: string;
+}
+export declare class PatternExpansionError extends Error {
+    readonly findings: PatternFinding[];
+    constructor(findings: PatternFinding[]);
+}
+export interface Toolkit {
+    /** Every pattern this toolkit offers, by name. */
+    readonly patterns: ReadonlyMap<string, PatternDefinition<never>>;
+    expand(graph: ApplicationGraph, declaration: PatternDeclaration, options?: ExpansionOptions): NodeId;
+    /** Everything expanded into this graph, newest last. */
+    expansions(graph: ApplicationGraph): PatternExpansion[];
+    inspect(graph: ApplicationGraph, instance: string): PatternExpansion | undefined;
+}
+export declare function createToolkit(definitions: readonly PatternDefinition<never>[]): Toolkit;
+/**
+ * Which pattern instance owns a node, read from the graph alone.
+ *
+ * This is the Model B claim under test: an agent holding only the expanded graph — no
+ * toolkit, no expansion record, no build step — can still recover the grouping.
+ */
+export declare function nodesOfInstance(graph: ApplicationGraph, instance: string): NodeId[];
+export declare function instancesOfPattern(graph: ApplicationGraph, pattern: string): string[];
+/** One way a generated node no longer matches what expansion produced. */
+export interface ExpansionDrift {
+    code: 'TOOLKIT_EXPANSION_DRIFT';
+    instance: string;
+    pattern: string;
+    nodeId: NodeId;
+    /** `removed`, `provenance-lost`, or the property that differs. */
+    property: string;
+    expected: unknown;
+    actual: unknown;
+    message: string;
+}
+/**
+ * Compares the graph against what expansion produced, property by property.
+ *
+ * Under `declaration` ownership this is the safety net: the declaration is the source of
+ * truth, so a hand-edited generated node will be silently overwritten on the next build
+ * unless something says so first. Under `graph` ownership drift is expected and this is
+ * merely a record of how far the graph has moved from its origin.
+ *
+ * It reports what changed rather than only that something did, because "your edit will be
+ * lost" is only actionable if it names the edit.
+ */
+export declare function detectDrift(graph: ApplicationGraph, expansion: PatternExpansion): ExpansionDrift[];
+/**
+ * Hands ownership of a pattern's generated nodes to the graph.
+ *
+ * The alternative to accidental drift. After this the declaration is history: the nodes stay
+ * exactly as they are, edits to them are legitimate, and re-expanding the declaration would
+ * be a mistake rather than a refresh. Provenance is kept — it still answers "where did this
+ * come from" — but re-marked so nothing treats the declaration as authoritative again.
+ *
+ * There is no un-detach. Recovering a declaration from an expanded graph is a different
+ * problem and this prototype does not attempt it.
+ */
+export declare function materializePattern(graph: ApplicationGraph, expansion: PatternExpansion): PatternExpansion;
+/**
+ * What would change if a declaration were expanded under a different toolkit.
+ *
+ * A toolkit upgrade must not silently reshape an application. This expands the same
+ * declaration into a throwaway graph under the target toolkit and reports the difference, so
+ * an upgrade is something an author approves rather than something an `npm install` performs.
+ */
+export interface ExpansionDiff {
+    added: NodeId[];
+    removed: NodeId[];
+    changed: Array<{
+        nodeId: NodeId;
+        property: string;
+        from: unknown;
+        to: unknown;
+    }>;
+}
+export declare function diffPatternExpansion(expansion: PatternExpansion, target: Toolkit, graphForTarget: ApplicationGraph): ExpansionDiff;
+/**
+ * Strips every trace of the toolkit from an expanded graph.
+ *
+ * §37 requires that doing this changes nothing but toolkit-aware introspection, and §66
+ * requires the result still validate, compile, execute and render. A function that performs
+ * the removal is how both are tested rather than asserted.
+ */
+export declare function stripProvenance(graph: ApplicationGraph): ApplicationGraph;
+//# sourceMappingURL=expand.d.ts.map