rea-agents 2.1.0 → 2.3.0

package/dist/domain/processReactiveCheckpointDataflow.js

@@ -0,0 +1,32 @@
+/** Checkpoints guaranteed on every known path entering each reactive state. */
+export const definitelyAvailableCheckpoints = (scenario) => {
+    const available = new Map([
+        [scenario.initial_state, new Set()],
+    ]);
+    let changed = true;
+    while (changed) {
+        changed = false;
+        for (const state of scenario.states) {
+            const before = available.get(state.id);
+            if (before === undefined)
+                continue;
+            for (const transition of state.on) {
+                if (transition.target.kind !== "goto")
+                    continue;
+                const after = new Set(before);
+                for (const name of transition.actions.flatMap((action) => action.type === "checkpoint" ? [action.name] : []))
+                    after.add(name);
+                const prior = available.get(transition.target.state);
+                const next = prior === undefined
+                    ? after
+                    : new Set([...prior].filter((name) => after.has(name)));
+                if (prior !== undefined && setsEqual(prior, next))
+                    continue;
+                available.set(transition.target.state, next);
+                changed = true;
+            }
+        }
+    }
+    return available;
+};
+const setsEqual = (left, right) => left.size === right.size && [...left].every((value) => right.has(value));

package/dist/domain/processReactiveMatching.js

@@ -0,0 +1,210 @@
+import canonicalize from "canonicalize";
+import { comparableProcessObservationPayload } from "./processObservation.js";
+import { PROCESS_REACTIVE_LIMITS, } from "./processReactiveScenario.js";
+const spendEvaluationWork = (budget, units) => {
+    if (units > budget.remaining)
+        return false;
+    budget.remaining -= units;
+    return true;
+};
+const noMatch = (overflow = false) => ({
+    matched: false,
+    eventIds: [],
+    consumeIds: [],
+    lastOrder: -1,
+    overflow,
+});
+const frontierOrder = (frontier, snapshot) => {
+    switch (frontier.kind) {
+        case "scenario_start":
+            return -1;
+        case "state_entry":
+            return snapshot.state_entry_capture_order - 1;
+        case "checkpoint":
+            return (snapshot.checkpoints.findLast(({ name }) => name === frontier.name)
+                ?.capture_order ?? null);
+        case "event_id":
+            return (snapshot.observations.find(({ event_id }) => event_id === frontier.event_id)?.capture_order ?? null);
+    }
+};
+const eligibleObservations = (frontier, context) => {
+    const frontierValue = frontierOrder(frontier, context.snapshot);
+    if (frontierValue === null)
+        return [];
+    const lowerBound = Math.max(frontierValue, context.afterOrder);
+    const consumed = new Set(context.snapshot.consumed_event_ids);
+    return context.snapshot.observations.filter(({ capture_order, event_id }) => capture_order > lowerBound &&
+        (context.upperOrder === null || capture_order <= context.upperOrder) &&
+        !consumed.has(event_id));
+};
+const canonicalJson = (value) => {
+    const serialized = canonicalize(value);
+    if (serialized === undefined)
+        throw new TypeError("Reactive scenario value is not canonical JSON");
+    return serialized;
+};
+const matchEvent = (trigger, context) => {
+    const expected = canonicalJson(comparableProcessObservationPayload(trigger.exact, trigger.ignore_fields));
+    const matches = [];
+    for (const observation of eligibleObservations(trigger.since, context)) {
+        if (!spendEvaluationWork(context.budget, 1))
+            return noMatch(true);
+        if (observation.source === trigger.source &&
+            canonicalJson(comparableProcessObservationPayload(observation.payload, trigger.ignore_fields)) === expected)
+            matches.push(observation);
+    }
+    if (matches.length < trigger.cardinality.min ||
+        matches.length > trigger.cardinality.max)
+        return noMatch();
+    const eventIds = matches.map(({ event_id }) => event_id);
+    return {
+        matched: true,
+        eventIds,
+        consumeIds: trigger.consume ? eventIds : [],
+        lastOrder: matches.at(-1)?.capture_order ?? context.afterOrder,
+        overflow: false,
+    };
+};
+const occurrenceRange = (haystack, needle, occurrence) => {
+    let offset = 0;
+    let start = -1;
+    for (let found = 0; found < occurrence; found += 1) {
+        start = haystack.indexOf(needle, offset);
+        if (start < 0)
+            return null;
+        offset = start + needle.length;
+    }
+    return { start, end: offset };
+};
+const matchTerminalText = (trigger, context) => {
+    const chunks = [];
+    for (const observation of eligibleObservations(trigger.since, context)) {
+        if (!spendEvaluationWork(context.budget, 1))
+            return noMatch(true);
+        if (observation.source === "terminal_raw" &&
+            typeof observation.payload === "object" &&
+            observation.payload !== null &&
+            !Array.isArray(observation.payload) &&
+            typeof observation.payload["data"] === "string")
+            chunks.push({ observation, text: observation.payload["data"] });
+    }
+    let rawBytes = 0;
+    for (const { text } of chunks) {
+        if (text.length > PROCESS_REACTIVE_LIMITS.terminalMatchBytes)
+            return noMatch(true);
+        const bytes = Buffer.byteLength(text);
+        rawBytes += bytes;
+        if (rawBytes > PROCESS_REACTIVE_LIMITS.terminalMatchBytes ||
+            !spendEvaluationWork(context.budget, bytes))
+            return noMatch(true);
+    }
+    const range = occurrenceRange(chunks.map(({ text }) => text).join(""), trigger.literal, trigger.occurrence);
+    if (range === null)
+        return noMatch();
+    let firstChunk = 0;
+    let lastChunk = 0;
+    let characters = 0;
+    for (const [index, chunk] of chunks.entries()) {
+        characters += chunk.text.length;
+        if (characters <= range.start)
+            firstChunk = index + 1;
+        if (characters >= range.end) {
+            lastChunk = index;
+            break;
+        }
+    }
+    const matched = chunks
+        .slice(firstChunk, lastChunk + 1)
+        .map(({ observation }) => observation);
+    const eventIds = matched.map(({ event_id }) => event_id);
+    return {
+        matched: true,
+        eventIds,
+        consumeIds: trigger.consume ? eventIds : [],
+        lastOrder: matched.at(-1)?.capture_order ?? context.afterOrder,
+        overflow: false,
+    };
+};
+const mergeMatches = (matches) => ({
+    matched: matches.every(({ matched }) => matched),
+    eventIds: [...new Set(matches.flatMap(({ eventIds }) => eventIds))],
+    consumeIds: [...new Set(matches.flatMap(({ consumeIds }) => consumeIds))],
+    lastOrder: Math.max(-1, ...matches.map(({ lastOrder }) => lastOrder)),
+    overflow: matches.some(({ overflow }) => overflow),
+});
+const matchEarliestPrefix = (trigger, context) => {
+    for (const observation of context.snapshot.observations) {
+        if (observation.capture_order <= context.afterOrder)
+            continue;
+        if (context.upperOrder !== null &&
+            observation.capture_order > context.upperOrder)
+            break;
+        const matched = matchTrigger(trigger, {
+            ...context,
+            upperOrder: observation.capture_order,
+        });
+        if (matched.matched || matched.overflow)
+            return matched;
+    }
+    return noMatch();
+};
+const matchTrigger = (trigger, context) => {
+    if (trigger.kind === "event")
+        return matchEvent(trigger, context);
+    if (trigger.kind === "terminal_text")
+        return matchTerminalText(trigger, context);
+    if (trigger.kind === "all")
+        return mergeMatches(trigger.triggers.map((child) => matchTrigger(child, context)));
+    if (trigger.kind === "any") {
+        const evaluated = trigger.triggers.map((child) => matchTrigger(child, context));
+        const matches = evaluated.filter(({ matched }) => matched);
+        return matches.length === 0
+            ? noMatch(evaluated.some(({ overflow }) => overflow))
+            : mergeMatches(matches);
+    }
+    if (trigger.kind === "sequence") {
+        const matches = [];
+        let cursor = context.afterOrder;
+        for (const child of trigger.triggers) {
+            const matched = matchEarliestPrefix(child, {
+                ...context,
+                afterOrder: cursor,
+            });
+            if (!matched.matched)
+                return noMatch(matched.overflow);
+            matches.push(matched);
+            cursor = matched.lastOrder;
+        }
+        return mergeMatches(matches);
+    }
+    const matches = [];
+    let cursor = context.afterOrder;
+    while (matches.length < trigger.max) {
+        const matched = matchEarliestPrefix(trigger.trigger, {
+            ...context,
+            afterOrder: cursor,
+        });
+        if (!matched.matched || matched.lastOrder <= cursor)
+            break;
+        matches.push(matched);
+        cursor = matched.lastOrder;
+    }
+    if (matches.length === trigger.max) {
+        const excess = matchEarliestPrefix(trigger.trigger, {
+            ...context,
+            afterOrder: cursor,
+        });
+        if (excess.matched || excess.overflow)
+            return noMatch(excess.overflow);
+    }
+    if (matches.length < trigger.min)
+        return noMatch(matches.some(({ overflow }) => overflow));
+    return mergeMatches(matches);
+};
+/** Match one trigger using a shared deterministic work budget. */
+export const matchProcessReactiveTrigger = (trigger, snapshot, budget) => matchTrigger(trigger, {
+    snapshot,
+    budget,
+    afterOrder: -1,
+    upperOrder: null,
+});

package/dist/domain/processReactiveRuntime.js

@@ -0,0 +1,109 @@
+import { matchProcessReactiveTrigger } from "./processReactiveMatching.js";
+import { PROCESS_REACTIVE_LIMITS, } from "./processReactiveScenario.js";
+export { commitProcessReactiveProposal } from "./processReactiveTransition.js";
+const counterValue = (counters, id) => counters.find((counter) => counter.id === id)?.count ?? 0;
+/** Create the initial immutable reducer state for one validated scenario. */
+export const createProcessReactiveSnapshot = (scenario) => ({
+    status: "running",
+    outcome: null,
+    active_state: scenario.initial_state,
+    state_entry_capture_order: 0,
+    observations: [],
+    consumed_event_ids: [],
+    transition_uses: [],
+    state_visits: [{ id: scenario.initial_state, count: 1 }],
+    checkpoints: [],
+    transitions: [],
+});
+const finishedDecision = (snapshot, outcome, evaluations = []) => ({
+    kind: "finished",
+    outcome,
+    evaluations,
+    snapshot: { ...snapshot, status: "finished", outcome },
+});
+const reduceControlInput = (snapshot, input) => {
+    if (input.kind === "cleanup_failed")
+        return finishedDecision(snapshot, "cleanup_failed");
+    if (snapshot.status === "finished")
+        return { kind: "already_finished", snapshot, evaluations: [] };
+    if (input.kind === "observation")
+        return null;
+    if (input.kind === "state_deadline")
+        return input.state_id === snapshot.active_state &&
+            input.state_entry_capture_order === snapshot.state_entry_capture_order
+            ? finishedDecision(snapshot, "predicate_timeout")
+            : { kind: "waiting", snapshot, evaluations: [] };
+    if (input.kind === "scenario_deadline")
+        return finishedDecision(snapshot, "scenario_deadline");
+    return finishedDecision(snapshot, "cancelled");
+};
+/** Advance one validated scenario using only an observation or explicit deadline. */
+export const reduceProcessReactiveScenario = (scenario, snapshot, input) => {
+    const controlDecision = reduceControlInput(snapshot, input);
+    if (controlDecision !== null)
+        return controlDecision;
+    if (input.kind !== "observation")
+        return finishedDecision(snapshot, "capture_incomplete");
+    const prior = snapshot.observations.at(-1);
+    if ((prior !== undefined &&
+        input.observation.capture_order <= prior.capture_order) ||
+        snapshot.observations.some(({ event_id }) => event_id === input.observation.event_id))
+        return finishedDecision(snapshot, "capture_incomplete");
+    if (snapshot.observations.length >= PROCESS_REACTIVE_LIMITS.retainedObservations)
+        return finishedDecision(snapshot, "capture_incomplete");
+    const observed = {
+        ...snapshot,
+        observations: [...snapshot.observations, input.observation],
+    };
+    const state = scenario.states.find(({ id }) => id === observed.active_state);
+    if (state === undefined)
+        return finishedDecision(observed, "target_lost");
+    const budget = { remaining: PROCESS_REACTIVE_LIMITS.evaluationWork };
+    const matches = state.on.map((transition) => ({
+        transition,
+        match: matchProcessReactiveTrigger(transition.when, observed, budget),
+        uses: counterValue(observed.transition_uses, transition.id),
+    }));
+    if (matches.some(({ match }) => match.overflow))
+        return finishedDecision(observed, "capture_incomplete");
+    const evaluations = matches.map(({ transition, match, uses }) => ({
+        transition_id: transition.id,
+        status: uses >= transition.max_uses
+            ? "exhausted"
+            : match.matched
+                ? "matched"
+                : "unmatched",
+        matched_event_ids: match.eventIds,
+    }));
+    const eligible = matches.filter(({ transition, match, uses }) => match.matched && uses < transition.max_uses);
+    if (eligible.length === 0)
+        return { kind: "waiting", snapshot: observed, evaluations };
+    const minimumPriority = Math.min(...eligible.map(({ transition }) => transition.priority));
+    const winners = eligible.filter(({ transition }) => transition.priority === minimumPriority);
+    if (winners.length !== 1)
+        return finishedDecision(observed, "ambiguous_match", evaluations);
+    const winner = winners[0];
+    if (winner === undefined)
+        return finishedDecision(observed, "capture_incomplete", evaluations);
+    const targetDeclaration = winner.transition.target;
+    if (targetDeclaration.kind === "goto") {
+        const target = scenario.states.find(({ id }) => id === targetDeclaration.state);
+        if (target === undefined ||
+            counterValue(observed.state_visits, target.id) >= target.max_visits)
+            return finishedDecision(observed, "capture_incomplete", evaluations);
+    }
+    return {
+        kind: "proposal",
+        snapshot: observed,
+        evaluations,
+        effects: winner.transition.actions,
+        proposal: {
+            transition_id: winner.transition.id,
+            transition_identity: canonicalize(winner.transition) ?? "",
+            observation_event_id: input.observation.event_id,
+            trigger_event_ids: winner.match.eventIds,
+            consume_event_ids: winner.match.consumeIds,
+        },
+    };
+};
+import canonicalize from "canonicalize";