@almadar/core 10.129.0 → 11.0.1

package/dist/state-machine/index.d.ts

@@ -1,359 +0,0 @@
-import { EventPayload, SExpr } from '../index.js';
-import 'zod';
-
-/**
- * State Machine Graph Algorithm Types
- *
- * Pure types used by BFS, guard payload, and replay path algorithms.
- * These are decoupled from the verify-specific types (no Playwright, no HTTP).
- *
- * @packageDocumentation
- */
-
-/** An edge in the state graph adjacency list */
-interface StateEdge {
-    event: string;
-    to: string;
-}
-/** A node in the BFS queue */
-interface BFSNode {
-    state: string;
-    depth: number;
-}
-/** A node in the BFS queue with a replay path */
-interface BFSPathNode {
-    fromState: string;
-    replayPath: ReplayStep[];
-}
-/** A single step to replay to reach a given state */
-interface ReplayStep {
-    /** Event to fire */
-    event: string;
-    /** State we're coming from */
-    fromState: string;
-    /** State we're transitioning to */
-    toState: string;
-    /** Slot the pattern renders in */
-    slot: string;
-    /** Pattern expected in the slot after this step */
-    expectedPattern?: string;
-    /** True if this step requires entity rows to be visible before clicking */
-    needsEntityData: boolean;
-    /** Payload to supply for this step (derived from guard pass case if guarded) */
-    guardPayload?: EventPayload;
-    /** Full payload schema for mock data generation */
-    payloadSchema?: PayloadFieldSchema[];
-}
-/** Payload field definition (name + type) */
-interface PayloadFieldSchema {
-    name: string;
-    type: string;
-    required?: boolean;
-}
-/** Pass and fail payloads derived from a guard s-expression */
-interface GuardPayload {
-    pass: EventPayload;
-    fail: EventPayload;
-}
-/**
- * Minimal transition interface for graph algorithms.
- * Compatible with both @almadar/core Transition and orbital-verify UnifiedTransition.
- */
-interface GraphTransition {
-    from: string;
-    event: string;
-    to: string;
-}
-/**
- * Transition input for the edge-covering walk algorithm.
- * Extends GraphTransition with guard metadata for generating pass/fail walk steps.
- */
-interface EdgeWalkTransition extends GraphTransition {
-    hasGuard: boolean;
-    /**
-     * Guard expression (when present). Mirrors `@almadar/core`'s `SExpr`
-     * union — a string atom (e.g. `"@payload.row"` for bare-binding
-     * existence guards declared by std-confirmation) OR an array
-     * (`["or", ...]`, `["=", ...]`). Pre-fix, the type was `unknown[]`
-     * which rejected the string form and `toEdgeWalkTransition`
-     * silently dropped it; downstream `buildGuardPayloads` then saw no
-     * guard and synthesized `{}` for the verifier's pass-case bus
-     * replay, leaving the modal closed and the portal observer
-     * reporting "slot not mounted" for every single-binding-guarded
-     * event.
-     */
-    guard?: SExpr;
-    /** Event payload field declarations (e.g., [{ name: "id", type: "string", mockValue: "mock-products-1" }]).
-     *  Used to generate mock payloads for events that require data (VIEW, EDIT).
-     *  Callers should set mockValue for id fields using their entity context. */
-    payloadSchema?: Array<{
-        name: string;
-        type: string;
-        required?: boolean;
-        mockValue?: unknown;
-    }>;
-}
-/**
- * A single step in an edge-covering walk.
- * The walk visits every transition (edge) in the state graph at least once.
- */
-interface WalkStep {
-    /** Source state */
-    from: string;
-    /** Event to fire */
-    event: string;
-    /** Target state */
-    to: string;
-    /** Guard branch: null for unguarded, 'pass' or 'fail' for guarded */
-    guardCase: 'pass' | 'fail' | null;
-    /** Payload to send with the event */
-    payload: EventPayload;
-    /** True if this step is a repositioning step (navigating to reach a source state with uncovered edges) */
-    isRepositioning: boolean;
-}
-
-/**
- * State Graph Construction
- *
- * Build an adjacency list from state machine transitions.
- * Extracted from orbital-verify-unified/src/analyze.ts.
- *
- * @packageDocumentation
- */
-
-/**
- * Builds an adjacency list from state machine transitions.
- *
- * Constructs a state transition graph where each state maps to an array
- * of outgoing edges (events and target states). Wildcard transitions
- * (from === '*') are excluded since they don't represent fixed edges.
- * Used as the foundation for state machine analysis, traversal, and verification.
- *
- * @param {GraphTransition[]} transitions - Array of state transitions
- * @returns {Map<string, StateEdge[]>} State transition graph
- *
- * @example
- * const graph = buildStateGraph(transitions);
- * const edgesFromInitial = graph.get('initial'); // Array of outgoing edges
- * console.log(`Initial state has ${edgesFromInitial?.length} transitions`);
- */
-declare function buildStateGraph(transitions: GraphTransition[]): Map<string, StateEdge[]>;
-
-/**
- * BFS Reachability Algorithms
- *
- * Breadth-first search over state machine graphs.
- * Extracted from orbital-verify-unified/src/analyze.ts and phase3-server.ts.
- *
- * @packageDocumentation
- */
-
-/**
- * Collects all reachable states from an initial state using breadth-first search.
- *
- * Performs BFS traversal of the state machine to find all states reachable
- * from the initial state, up to the specified maximum depth. Used for
- * state machine analysis, verification, and test coverage assessment.
- *
- * @param {GraphTransition[]} transitions - Array of state transitions
- * @param {string} initialState - Starting state name
- * @param {number} [maxDepth=5] - Maximum search depth
- * @returns {Set<string>} Set of reachable state names
- *
- * @example
- * const reachable = collectReachableStates(transitions, 'initial', 10);
- * console.log('Reachable states:', Array.from(reachable));
- */
-declare function collectReachableStates(transitions: GraphTransition[], initialState: string, maxDepth?: number): Set<string>;
-/**
- * Walks all reachable (state, event) pairs using BFS and invokes callback for each.
- *
- * Traverses the state machine using breadth-first search and calls the visitor
- * function for each (state, edge) pair encountered. Used by server verification
- * to test transitions by POSTing to endpoints and checking responses.
- *
- * @param {GraphTransition[]} transitions - Array of state transitions
- * @param {string} initialState - Starting state name
- * @param {number} maxDepth - Maximum BFS depth
- * @param {(state: string, edge: StateEdge, depth: number) => Promise<boolean>} visitor - Callback for each pair
- * @returns {Promise<{ visitedPairs: Set<string>; walkedEdges: number }>} Traversal statistics
- *
- * @example
- * const result = await walkStatePairs(transitions, 'initial', 5, async (state, edge) => {
- *   console.log(`Transition: ${state} --${edge.event}--> ${edge.to}`);
- *   return true; // Continue exploration
- * });
- * console.log(`Visited ${result.visitedPairs.size} state-event pairs`);
- */
-declare function walkStatePairs(transitions: GraphTransition[], initialState: string, maxDepth: number, visitor: (state: string, edge: StateEdge, depth: number) => Promise<boolean>): Promise<{
-    visitedPairs: Set<string>;
-    walkedEdges: number;
-}>;
-
-/**
- * Guard Payload Builder
- *
- * Derive pass and fail payloads from guard s-expressions.
- * Extracted from orbital-verify-unified/src/analyze.ts.
- *
- * @packageDocumentation
- */
-
-/**
- * Extracts the first segment of a payload field reference.
- *
- * Parses binding references in the format "@payload.field" and extracts
- * the first field name segment. Used for identifying payload fields in
- * guard conditions for test data generation.
- *
- * @param {unknown} ref - Binding reference to extract from
- * @returns {string | null} First field segment or null for non-payload references
- *
- * @example
- * extractPayloadFieldRef('@payload.item'); // returns 'item'
- * extractPayloadFieldRef('@payload.data.weight'); // returns 'data'
- * extractPayloadFieldRef('@entity.id'); // returns null
- * extractPayloadFieldRef('@user.name'); // returns null
- */
-declare function extractPayloadFieldRef(ref: unknown): string | null;
-/**
- * Full dotted path of a payload reference — `'@payload.data.providerName'`
- * → `['data', 'providerName']`. `extractPayloadFieldRef` keeps only the
- * first segment, which made every guard on a NESTED payload field
- * unsatisfiable by synthesis: `when ?data.providerName` was seeded as
- * `{data: 'mock-test-value'}`, the runtime read `.providerName` off a
- * string, and the pass-case dispatch was correctly rejected (std-booking
- * BookingWizard NEXT — the whole step chain became unwalkable). Returns
- * `null` for non-payload references.
- */
-declare function extractPayloadFieldPath(ref: unknown): string[] | null;
-/**
- * Builds test payloads that satisfy or violate guard conditions.
- *
- * Generates pass/fail test data for guard s-expressions used in state machine
- * transitions. Pass payloads satisfy the guard condition (allowing transition),
- * fail payloads violate it (blocking transition). Used for automated testing
- * and validation of state machine behavior.
- *
- * Supports operators: not-nil, nil, eq, not-eq, gt, gte, lt, lte, and, or, not
- *
- * @param {unknown} guard - Guard s-expression to analyze
- * @returns {GuardPayload} Object with pass and fail payloads
- *
- * @example
- * // Guard: ['not-nil', '@payload.completed']
- * buildGuardPayloads(['not-nil', '@payload.completed']);
- * // Returns: { pass: { completed: 'mock-test-value' }, fail: { completed: null } }
- *
- * @example
- * // Guard: ['eq', '@payload.status', 'active']
- * buildGuardPayloads(['eq', '@payload.status', 'active']);
- * // Returns: { pass: { status: 'active' }, fail: { status: 'not-active' } }
- *
- * @example
- * // Guard: ['and', ['not-nil', '@payload.id'], ['eq', '@payload.status', 'ready']]
- * buildGuardPayloads(['and', ['not-nil', '@payload.id'], ['eq', '@payload.status', 'ready']]);
- * // Returns: { pass: { id: 'mock-test-value', status: 'ready' }, fail: { id: null } }
- */
-/**
- * Evaluate a guard that is fully constant (no `@payload`/`@entity`/`@config`
- * bindings — e.g. after molecule/organism inlining folds `@config.mode` to a
- * literal). Returns the constant truth value, or `null` when the guard depends
- * on a binding (so a payload must be synthesized). This lets callers (a) emit
- * an empty payload for a constant guard (no field to satisfy) and (b) skip the
- * meaningless variant: an always-true guard has no fail case, an always-false
- * guard has no pass case. Without it, `(or (= "create" "create") @payload.row)`
- * (create-mode modal OPEN) was synthesized with a spurious `row`, which the
- * runtime read as edit-mode and rejected.
- */
-declare function constTruth(guard: unknown): boolean | null;
-declare function buildGuardPayloads(guard: unknown): GuardPayload;
-
-/**
- * Replay Path Builder
- *
- * Compute the shortest path (replay steps) from an initial state
- * to every reachable state in a state machine. Used by browser
- * verification to navigate through states before running assertions.
- *
- * Extracted from orbital-verify-unified/src/analyze.ts (collectDataMutationTests).
- *
- * @packageDocumentation
- */
-
-/**
- * Extended transition with render and payload info needed for replay path building.
- * Compatible with orbital-verify's UnifiedTransition.
- */
-interface ReplayTransition extends GraphTransition {
-    hasGuard: boolean;
-    guard?: unknown[];
-    payloadFields: string[];
-    payloadSchema: PayloadFieldSchema[];
-    renderEffects: Array<{
-        slot: string;
-        patternType: string | null;
-    }>;
-}
-/**
- * Builds the shortest replay paths from initial state to all reachable states.
- *
- * Computes step-by-step navigation paths for state machine testing and verification.
- * Uses breadth-first search to find shortest paths up to specified depth limit.
- * Each path contains replay steps with event, state, and payload information
- * needed to reproduce state transitions in tests.
- *
- * @param {ReplayTransition[]} transitions - Transitions with render/payload information
- * @param {string} initialState - Starting state name
- * @param {number} [maxDepth=3] - Maximum path length (default: 3)
- * @returns {Map<string, ReplayStep[]>} Map of state names to replay step arrays
- *
- * @example
- * // Build paths from 'initial' state
- * const paths = buildReplayPaths(transitions, 'initial', 5);
- *
- * // Get steps to reach 'completed' state
- * const stepsToComplete = paths.get('completed');
- *
- * // Execute replay steps
- * for (const step of stepsToComplete) {
- *   await dispatchEvent(step.event, step.payload);
- * }
- */
-declare function buildReplayPaths(transitions: ReplayTransition[], initialState: string, maxDepth?: number): Map<string, ReplayStep[]>;
-
-/**
- * Edge-Covering Walk Algorithm
- *
- * Computes an ordered sequence of events (WalkStep[]) that attempts to cover
- * every transition (edge) in a state machine graph. This is a greedy chained
- * walk: it does NOT guarantee 100% coverage. With no reset concept it can
- * strand on absorbing states (no outgoing edges and no path back to uncovered
- * edges), and a guard-fail misprediction desyncs the chained walk so later
- * steps fire from the wrong state. Superseded by the hermetic per-frame walk
- * in @almadar-io/verify, which re-seeds each frame independently.
- *
- * Algorithm:
- * 1. Build adjacency list and edge universe (guarded transitions produce two edges)
- * 2. Precompute BFS shortest paths between all state pairs (for repositioning)
- * 3. Greedy DFS: at each state, prefer uncovered outgoing edges
- * 4. When stuck, insert repositioning steps to nearest state with uncovered edges
- * 5. Guard-fail steps don't advance state (guard blocks transition)
- *
- * Used by StateWalkEngine in @almadar-io/verify. Both orbital-verify and
- * runtime-verify share this algorithm for consistent coverage.
- *
- * @packageDocumentation
- */
-
-/**
- * Build an ordered walk that covers every edge in the state machine.
- *
- * @param transitions - All transitions in the state machine
- * @param initialState - Starting state
- * @returns Ordered walk steps covering every edge
- */
-declare function buildEdgeCoveringWalk(transitions: EdgeWalkTransition[], initialState: string): WalkStep[];
-
-export { buildEdgeCoveringWalk, buildGuardPayloads, buildReplayPaths, buildStateGraph, collectReachableStates, constTruth, extractPayloadFieldPath, extractPayloadFieldRef, walkStatePairs };
-export type { BFSNode, BFSPathNode, EdgeWalkTransition, GraphTransition, GuardPayload, PayloadFieldSchema, ReplayStep, ReplayTransition, StateEdge, WalkStep };

package/dist/state-machine/index.js

@@ -1,3 +0,0 @@
-export { buildEdgeCoveringWalk, buildGuardPayloads, buildReplayPaths, buildStateGraph, collectReachableStates, constTruth, extractPayloadFieldPath, extractPayloadFieldRef, walkStatePairs } from '../chunk-GIUA3NUJ.js';
-//# sourceMappingURL=index.js.map
-//# sourceMappingURL=index.js.map

package/dist/state-machine/index.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}