@acquiredintelligence/attend 0.0.0-stage → 0.1.0

package/dist/core/state.js

@@ -0,0 +1,90 @@
+import { fnvStart, foldId } from './ids.js';
+import { seenFrom, seenIds } from './seen.js';
+import { assertWindow, openWindow, windowEntries, windowFrom, windowSize } from './window.js';
+import { nextDue } from './reducer.js';
+/** An empty, owned scope at version zero. */
+export function initialState(scope, _policy) {
+    return {
+        scope, version: 0, cursors: {}, ...seenFrom([], [], []), open: openWindow(scope),
+        batch: null, outbox: { decisions: [], deadLetters: [] }, recent: [], dueAt: null,
+    };
+}
+/** Builds owned state from a snapshot. Copies every array it will mutate and never mutates `record`. O(W + S + outbox). */
+export function fromRecord(record, policy) {
+    const held = record.batch;
+    const state = {
+        scope: record.scope, version: record.version, cursors: record.cursors,
+        ...seenFrom(record.seen, record.buffer.entries, held?.window.events ?? []),
+        open: windowFrom(record.scope, record.buffer),
+        batch: held ? { window: held.window, phase: held.phase, hash: heldHash(record.scope, held.window.events) } : null,
+        outbox: { decisions: [...record.outbox.decisions], deadLetters: [...record.outbox.deadLetters] },
+        recent: record.recent, dueAt: null,
+    };
+    state.dueAt = nextDue(policy, state);
+    return state;
+}
+function heldHash(scope, events) {
+    const hash = fnvStart(scope);
+    for (const entry of events)
+        foldId(hash, entry.id);
+    return hash;
+}
+/** The state as a fresh `ScopeRecord`, deep-equal to the copying reducer's. Shares immutable parts. O(W + S + outbox). */
+export function toRecord(state) {
+    const open = state.open;
+    const buffer = { entries: windowEntries(open), dropped: open.dropped, gap: open.gap, forcedAt: open.forcedAt };
+    if (open.endedAt !== null)
+        buffer.endedAt = open.endedAt;
+    return {
+        version: state.version, scope: state.scope, cursors: state.cursors, seen: seenIds(state.seen), buffer,
+        batch: state.batch ? { window: state.batch.window, phase: state.batch.phase } : null,
+        outbox: { decisions: [...state.outbox.decisions], deadLetters: [...state.outbox.deadLetters] },
+        recent: state.recent, dueAt: state.dueAt,
+    };
+}
+/** True when the scope holds nothing: an empty window, no batch, empty lanes and `dueAt === null`. Such a scope may be evicted from the cache. */
+export function quiescent(state) {
+    return windowSize(state.open) === 0 && state.batch === null && state.outbox.decisions.length === 0
+        && state.outbox.deadLetters.length === 0 && state.dueAt === null;
+}
+/** Checks the state's invariants after an apply, in tests and debug builds. Throws, naming the broken invariant. */
+export function assertInvariants(state, policy) {
+    const ring = state.seen;
+    if (ring.size > Math.max(0, policy.seenCount) || ring.ids.length !== ring.capacity || ring.head < 0
+        || (ring.capacity > 0 && ring.head >= ring.capacity) || ring.size < 0 || ring.size > ring.capacity) {
+        throw new Error('I2: seen ring');
+    }
+    const expected = new Map();
+    for (const id of seenIds(ring))
+        expected.set(id, (expected.get(id) ?? 0) + 1);
+    const windows = new Set();
+    for (const entries of [windowEntries(state.open), state.batch?.window.events ?? []]) {
+        for (const entry of entries) {
+            if (windows.has(entry.id))
+                throw new Error('I1: duplicate window id');
+            windows.add(entry.id);
+            expected.set(entry.id, (expected.get(entry.id) ?? 0) + 1);
+        }
+    }
+    if (expected.size !== state.known.size)
+        throw new Error('I1: known ids');
+    for (const [id, count] of expected)
+        if (state.known.get(id) !== count)
+            throw new Error('I1: known count');
+    assertWindow(state.scope, state.open);
+    if (state.batch?.hash) {
+        const hash = heldHash(state.scope, state.batch.window.events);
+        if (hash.hi !== state.batch.hash.hi || hash.lo !== state.batch.hash.lo)
+            throw new Error('I5: held hash');
+    }
+    if (state.open.endedAt !== null && windowSize(state.open) === 0)
+        throw new Error('I3: endedAt on an empty window');
+    if (!Object.is(state.dueAt, nextDue(policy, state)))
+        throw new Error('I6: dueAt');
+    for (const lane of [state.outbox.decisions, state.outbox.deadLetters]) {
+        for (let i = 1; i < lane.length; i += 1)
+            if (lane[i]?.phase.phase === 'inFlight')
+                throw new Error('outbox: more than one in flight in a lane');
+    }
+}
+//# sourceMappingURL=state.js.map

package/dist/core/state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../../src/core/state.ts"],"names":[],"mappings":"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"}

package/dist/core/step.d.ts

@@ -0,0 +1,14 @@
+import type { EndInput, EventsInput, FlushInput, Input, JudgeDeferredInput, ReleasedInput, ScopeRecord, StepConfig, Stepped, TraceEffect } from './types.js';
+export type { StepConfig } from './types.js';
+export { deadline, isAct } from './window.js';
+export { offeredRoutes, validate } from './reducer.js';
+export { windowId } from './ids.js';
+/**
+ * The pure reducer for tests, evals and replays: `fromRecord`, then `apply`, then `toRecord`.
+ * Never mutates `record`. O(W + S) per call, so a runtime that owns its state calls `apply`.
+ */
+export declare function step(config: StepConfig, record: ScopeRecord, input: EventsInput | FlushInput | EndInput | ReleasedInput | JudgeDeferredInput, now: number): Stepped<TraceEffect>;
+export declare function step(config: StepConfig, record: ScopeRecord, input: Input, now: number): Stepped;
+/** The empty snapshot at version zero. */
+export declare function initialRecord(scope: string): ScopeRecord;
+//# sourceMappingURL=step.d.ts.map

package/dist/core/step.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"step.d.ts","sourceRoot":"","sources":["../../src/core/step.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,UAAU,EAAE,KAAK,EAAE,kBAAkB,EAAE,aAAa,EAAE,WAAW,EAAE,UAAU,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAI7J,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AACvD,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAEpC;;;GAGG;AACH,wBAAgB,IAAI,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,WAAW,GAAG,UAAU,GAAG,QAAQ,GAAG,aAAa,GAAG,kBAAkB,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;AAClL,wBAAgB,IAAI,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;AAQlG,0CAA0C;AAC1C,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,CAGxD"}

package/dist/core/step.js

@@ -0,0 +1,17 @@
+import { fromRecord, toRecord } from './state.js';
+import { apply, newOutput } from './reducer.js';
+export { deadline, isAct } from './window.js';
+export { offeredRoutes, validate } from './reducer.js';
+export { windowId } from './ids.js';
+export function step(config, record, input, now) {
+    const state = fromRecord(record, config.policy);
+    const out = newOutput();
+    apply({ policy: config.policy, decisions: config.decisions ?? 'lane', deadLetters: config.deadLetters ?? 'lane', traces: true }, state, { input, now }, out);
+    return { record: toRecord(state), effects: out.effects };
+}
+/** The empty snapshot at version zero. */
+export function initialRecord(scope) {
+    return { version: 0, scope, cursors: {}, seen: [], buffer: { entries: [], dropped: 0, gap: false, forcedAt: null },
+        batch: null, outbox: { decisions: [], deadLetters: [] }, recent: [], dueAt: null };
+}
+//# sourceMappingURL=step.js.map

package/dist/core/step.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"step.js","sourceRoot":"","sources":["../../src/core/step.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAClD,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAGhD,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AACvD,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAQpC,MAAM,UAAU,IAAI,CAAC,MAAkB,EAAE,MAAmB,EAAE,KAAY,EAAE,GAAW;IACrF,MAAM,KAAK,GAAG,UAAU,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;IAChD,MAAM,GAAG,GAAG,SAAS,EAAE,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,CAAC,SAAS,IAAI,MAAM,EAAE,WAAW,EAAE,MAAM,CAAC,WAAW,IAAI,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE,GAAG,CAAC,CAAC;IAC7J,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC;AAC3D,CAAC;AAED,0CAA0C;AAC1C,MAAM,UAAU,aAAa,CAAC,KAAa;IACzC,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE;QAChH,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,SAAS,EAAE,EAAE,EAAE,WAAW,EAAE,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;AACvF,CAAC"}

package/dist/core/threshold.d.ts

@@ -0,0 +1,40 @@
+import { type Judgment, type Route } from './types.js';
+/**
+ * The act-threshold rule. `act` is p(interrupt) + p(ask) from the judgment's own probabilities,
+ * with missing entries counted as 0. Only finite probabilities in [0, 1] count, as `validate`
+ * reads them. Returns the route to stage instead of the judge's, with `act`, or null when the
+ * judge's route stands. A judgment with no usable probability is never changed.
+ * At or above the threshold, choose the offered interrupt or ask with the higher probability;
+ * ties go to ask. If neither is offered, the judge's route stands. Below the threshold, replace
+ * an acting route with the highest-probability offered non-acting route; ties prefer skip,
+ * note, queue, then wait. Otherwise the judge's route stands.
+ */
+export declare function thresholdRoute(judgment: Judgment, offered: readonly Route[], actThreshold: number): {
+    route: Route;
+    act: number;
+} | null;
+/** Replay duration and the maximum acceptable act rate. */
+export interface SuggestThresholdOptions {
+    /** How long the replay that recorded the judgments covered. */
+    durationMs: number;
+    maxActsPerHour: number;
+}
+/** The observed act count and hourly rate at one candidate threshold. */
+export interface ThresholdCandidate {
+    threshold: number;
+    acts: number;
+    actsPerHour: number;
+}
+/** Candidate rates and the smallest threshold that meets the budget. */
+export interface ThresholdSuggestion {
+    /** The smallest threshold whose act rate fits the budget, or null when none does. */
+    threshold: number | null;
+    candidates: ThresholdCandidate[];
+}
+/**
+ * Picks an `actThreshold` offline from the judgments a replay recorded, with no extra judge calls.
+ * The candidates are every `act` above 0 that the judgments reach, capped at 1, plus 1. A judgment
+ * with no usable probability acts at every threshold when its own route is interrupt or ask.
+ */
+export declare function suggestThreshold(judgments: readonly Pick<Judgment, 'route' | 'probabilities'>[], options: SuggestThresholdOptions): ThresholdSuggestion;
+//# sourceMappingURL=threshold.d.ts.map

package/dist/core/threshold.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"threshold.d.ts","sourceRoot":"","sources":["../../src/core/threshold.ts"],"names":[],"mappings":"AAAA,OAAO,EAAU,KAAK,QAAQ,EAAE,KAAK,KAAK,EAAE,MAAM,YAAY,CAAC;AAE/D;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,SAAS,KAAK,EAAE,EAAE,YAAY,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,KAAK,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAcxI;AAED,2DAA2D;AAC3D,MAAM,WAAW,uBAAuB;IACtC,+DAA+D;IAC/D,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,yEAAyE;AACzE,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,wEAAwE;AACxE,MAAM,WAAW,mBAAmB;IAClC,qFAAqF;IACrF,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,UAAU,EAAE,kBAAkB,EAAE,CAAC;CAClC;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,SAAS,IAAI,CAAC,QAAQ,EAAE,OAAO,GAAG,eAAe,CAAC,EAAE,EAAE,OAAO,EAAE,uBAAuB,GAAG,mBAAmB,CAoBvJ"}

package/dist/core/threshold.js

@@ -0,0 +1,72 @@
+import { ROUTES } from './types.js';
+/**
+ * The act-threshold rule. `act` is p(interrupt) + p(ask) from the judgment's own probabilities,
+ * with missing entries counted as 0. Only finite probabilities in [0, 1] count, as `validate`
+ * reads them. Returns the route to stage instead of the judge's, with `act`, or null when the
+ * judge's route stands. A judgment with no usable probability is never changed.
+ * At or above the threshold, choose the offered interrupt or ask with the higher probability;
+ * ties go to ask. If neither is offered, the judge's route stands. Below the threshold, replace
+ * an acting route with the highest-probability offered non-acting route; ties prefer skip,
+ * note, queue, then wait. Otherwise the judge's route stands.
+ */
+export function thresholdRoute(judgment, offered, actThreshold) {
+    const act = actProbability(judgment);
+    if (act === null)
+        return null;
+    const choices = act >= actThreshold ? ['ask', 'interrupt'] : acting(judgment.route) ? ['skip', 'note', 'queue', 'wait'] : [];
+    let route;
+    let best = -1;
+    for (const choice of choices) {
+        const p = probability(judgment.probabilities?.[choice]) ?? 0;
+        if (offered.includes(choice) && p > best) {
+            route = choice;
+            best = p;
+        }
+    }
+    return route === undefined || route === judgment.route ? null : { route, act };
+}
+/**
+ * Picks an `actThreshold` offline from the judgments a replay recorded, with no extra judge calls.
+ * The candidates are every `act` above 0 that the judgments reach, capped at 1, plus 1. A judgment
+ * with no usable probability acts at every threshold when its own route is interrupt or ask.
+ */
+export function suggestThreshold(judgments, options) {
+    const { durationMs, maxActsPerHour } = options;
+    if (!Number.isFinite(durationMs) || durationMs <= 0)
+        throw new RangeError(`attend: suggestThreshold needs a positive durationMs, got ${durationMs}`);
+    if (!Number.isFinite(maxActsPerHour) || maxActsPerHour < 0)
+        throw new RangeError(`attend: suggestThreshold needs a maxActsPerHour of 0 or more, got ${maxActsPerHour}`);
+    const acts = [];
+    let fixed = 0;
+    for (const judgment of judgments) {
+        const act = actProbability(judgment);
+        if (act === null)
+            fixed += Number(acting(judgment.route));
+        else if (act > 0)
+            acts.push(act);
+    }
+    acts.sort((a, b) => a - b);
+    const thresholds = [...new Set([...acts.map((act) => Math.min(act, 1)), 1])];
+    let below = 0;
+    const candidates = thresholds.map((threshold) => {
+        while (below < acts.length && (acts[below] ?? 0) < threshold)
+            below += 1;
+        const count = fixed + acts.length - below;
+        return { threshold, acts: count, actsPerHour: (count * 3_600_000) / durationMs };
+    });
+    return { threshold: candidates.find((candidate) => candidate.actsPerHour <= maxActsPerHour)?.threshold ?? null, candidates };
+}
+function probability(value) {
+    return value !== undefined && Number.isFinite(value) && value >= 0 && value <= 1 ? value : undefined;
+}
+function acting(route) {
+    return route === 'interrupt' || route === 'ask';
+}
+function actProbability(judgment) {
+    const { probabilities } = judgment;
+    if (probabilities === undefined || !ROUTES.some((route) => probability(probabilities[route]) !== undefined))
+        return null;
+    // Decimal sums such as 0.7 + 0.1 must meet an exact 0.8 threshold.
+    return Math.round(((probability(probabilities.interrupt) ?? 0) + (probability(probabilities.ask) ?? 0)) * 1e12) / 1e12;
+}
+//# sourceMappingURL=threshold.js.map

package/dist/core/threshold.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"threshold.js","sourceRoot":"","sources":["../../src/core/threshold.ts"],"names":[],"mappings":"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"}