@alisio/core 0.2.0 → 0.3.0

package/dist/decisions/breaker.js

@@ -0,0 +1,61 @@
+/**
+ * Circuit breaker with an injected clock. The caller reports only the failures that count (the
+ * service maps provider errors to `failure()`, `success()` or `neutral()`):
+ * - `closed`: calls flow; `threshold` consecutive failures open it.
+ * - `open`: `allow()` answers "open" until `openMs` pass, then the next caller is the single probe.
+ * - `half-open`: one probe in flight; concurrent callers get "open". The probe's `success()`
+ *   closes the circuit and its `failure()` re-opens it for another `openMs`.
+ * `neutral()` ends a call that says nothing about the provider's health (a fast `not_ready`, a
+ * caller abort): it releases the probe without counting or resetting anything.
+ */
+export class CircuitBreaker {
+    threshold;
+    openMs;
+    now;
+    failures = 0;
+    openedAt;
+    probing = false;
+    constructor(options = {}) {
+        this.threshold = options.threshold ?? 3;
+        this.openMs = options.openMs ?? 30_000;
+        this.now = options.now ?? (() => Date.now());
+    }
+    /** Asks to run one call. "half-open" means the caller IS the single probe. */
+    allow() {
+        if (this.openedAt === undefined)
+            return "closed";
+        if (this.probing)
+            return "open";
+        if (this.now() - this.openedAt < this.openMs)
+            return "open";
+        this.probing = true;
+        return "half-open";
+    }
+    success() {
+        this.reset();
+    }
+    failure() {
+        this.probing = false;
+        if (this.openedAt !== undefined) {
+            this.openedAt = this.now();
+            return;
+        }
+        this.failures++;
+        if (this.failures >= this.threshold)
+            this.openedAt = this.now();
+    }
+    neutral() {
+        this.probing = false;
+    }
+    reset() {
+        this.failures = 0;
+        this.openedAt = undefined;
+        this.probing = false;
+    }
+    /** Read-only view for diagnostics; it never consumes the probe. */
+    state() {
+        if (this.openedAt === undefined)
+            return "closed";
+        return this.probing || this.now() - this.openedAt >= this.openMs ? "half-open" : "open";
+    }
+}

package/dist/decisions/format.d.ts

@@ -0,0 +1,15 @@
+import type { DecisionStats } from "@alisio/sdk";
+import type { DecisionMetricsSnapshot } from "./metrics.ts";
+import type { DecisionStatus, DecisionsConfig } from "./service.ts";
+/**
+ * The "Decision Intelligence" block of `/stats` (spec §9.2), shared by the core handler and the
+ * TUI report. `undefined` when no decision happened, so the section is omitted.
+ */
+export declare function formatDecisionStatsSection(stats: DecisionStats): string | undefined;
+/** The `/decisions` report (spec §9.1). */
+export declare function formatDecisionsReport(input: {
+    status: DecisionStatus;
+    config: Pick<DecisionsConfig, "timeoutMs" | "minConfidence" | "telemetry">;
+    session: DecisionMetricsSnapshot;
+    process: DecisionMetricsSnapshot;
+}): string;

package/dist/decisions/format.js

@@ -0,0 +1,89 @@
+/** `12:04:31 UTC`: deterministic, independent of the viewer's time zone. */
+const clock = (iso) => {
+    const date = new Date(iso);
+    return Number.isNaN(date.getTime()) ? iso : `${date.toISOString().slice(11, 19)} UTC`;
+};
+const latency = (s) => s.avgLatencyMs === undefined ? undefined : `avg ${s.avgLatencyMs} ms · p95 ${s.p95LatencyMs} ms`;
+const packsLine = (packs) => Object.entries(packs)
+    .map(([id, count]) => `${id} (${count})`)
+    .join(", ");
+const lastFallbackLine = (f) => `Last fallback: ${f.reason} (${f.decisionId}) at ${clock(f.at)}`;
+/**
+ * The "Decision Intelligence" block of `/stats` (spec §9.2), shared by the core handler and the
+ * TUI report. `undefined` when no decision happened, so the section is omitted.
+ */
+export function formatDecisionStatsSection(stats) {
+    if (stats.requests <= 0)
+        return undefined;
+    const lat = latency(stats);
+    const packs = packsLine(stats.packs);
+    return [
+        "**Decision Intelligence**",
+        "",
+        ...(stats.provider ? [`- Provider: ${stats.provider}`] : []),
+        `- Requests: ${stats.requests} · completed ${stats.completed} · fallbacks ${stats.fallbacks}`,
+        ...(lat ? [`- Latency: ${lat}`] : []),
+        ...(stats.lastFallback ? [`- ${lastFallbackLine(stats.lastFallback)}`] : []),
+        ...(packs ? [`- Packs: ${packs}`] : []),
+    ].join("\n");
+}
+const MESSAGE_LIMIT = 200;
+/** The `/decisions` report (spec §9.1). */
+export function formatDecisionsReport(input) {
+    const { status, config, session, process } = input;
+    let head;
+    if (!status.enabled)
+        head = "disabled";
+    else if (status.configured === null)
+        head = "enabled · no provider configured (set decisions.provider)";
+    else if (!status.active)
+        head = `enabled · provider "${status.configured}" is not registered`;
+    else {
+        const health = status.health
+            ? `${status.health.status}${status.health.detail ? ` (${status.health.detail})` : ""}`
+            : "unknown";
+        head = `enabled · provider: ${status.active.id} (${status.active.name}) · health: ${health}`;
+    }
+    const caps = status.active
+        ? Object.entries(status.active.capabilities)
+            .filter(([, on]) => on === true)
+            .map(([name]) => name)
+        : [];
+    const err = status.lastLifecycleError;
+    const row = (label, m) => `| ${label} | ${m.requests} | ${m.completed} | ${m.fallbacks} |`;
+    const lat = [
+        latency(session) ? `session ${latency(session)}` : undefined,
+        latency(process) ? `process ${latency(process)}` : undefined,
+    ].filter(Boolean);
+    const fallback = session.lastFallback ?? process.lastFallback;
+    const packScope = Object.keys(session.packs).length ? session.packs : process.packs;
+    const packs = packsLine(packScope);
+    return [
+        "**Decision Intelligence**",
+        "",
+        `- Status: ${head}`,
+        ...(caps.length ? [`- Capabilities: ${caps.join(", ")}`] : []),
+        ...(status.active ? [`- Circuit: ${status.circuit}`] : []),
+        `- Timeout: ${config.timeoutMs} ms · min confidence: ${config.minConfidence} · telemetry: ${config.telemetry ? "on" : "off"}`,
+        ...(err
+            ? [
+                `- Lifecycle error: ${err.phase} of ${err.provider} failed: ${err.message.slice(0, MESSAGE_LIMIT)}`,
+            ]
+            : []),
+        "",
+        ...(process.requests > 0
+            ? [
+                "| Scope | Requests | Completed | Fallbacks |",
+                "| --- | --- | --- | --- |",
+                row("This session", session),
+                row("Process", process),
+                "",
+                ...(lat.length ? [`- Latency: ${lat.join("; ")}`] : []),
+                ...(fallback ? [`- ${lastFallbackLine(fallback)}`] : []),
+                ...(packs
+                    ? [`- Packs${Object.keys(session.packs).length ? "" : " (process)"}: ${packs}`]
+                    : []),
+            ]
+            : ["No decisions yet in this process."]),
+    ].join("\n");
+}

package/dist/decisions/index.d.ts

@@ -0,0 +1,7 @@
+export { bindDecisions, type DecisionAnnouncer, outcomeEvent } from "./bound.ts";
+export { CircuitBreaker, type CircuitBreakerOptions, type CircuitState } from "./breaker.ts";
+export { formatDecisionStatsSection, formatDecisionsReport } from "./format.ts";
+export { type DecisionMetricEntry, DecisionMetrics, type DecisionMetricsSnapshot, } from "./metrics.ts";
+export { DecisionRegistry, type RegisteredDecisionProvider } from "./registry.ts";
+export { DEFAULT_DECISIONS_CONFIG, type DecisionAttempt, DecisionError, type DecisionOutcome, DecisionService, type DecisionServiceDeps, type DecisionStatus, type DecisionsConfig, HEALTH_TIMEOUT_MS, } from "./service.ts";
+export { DECISION_LIMITS, splitSupported, validateAnswers, validateRequest } from "./validate.ts";

package/dist/decisions/index.js

@@ -0,0 +1,7 @@
+export { bindDecisions, outcomeEvent } from "./bound.js";
+export { CircuitBreaker } from "./breaker.js";
+export { formatDecisionStatsSection, formatDecisionsReport } from "./format.js";
+export { DecisionMetrics, } from "./metrics.js";
+export { DecisionRegistry } from "./registry.js";
+export { DEFAULT_DECISIONS_CONFIG, DecisionError, DecisionService, HEALTH_TIMEOUT_MS, } from "./service.js";
+export { DECISION_LIMITS, splitSupported, validateAnswers, validateRequest } from "./validate.js";

package/dist/decisions/metrics.d.ts

@@ -0,0 +1,45 @@
+import type { DecisionFallbackReason } from "@alisio/sdk";
+export type DecisionMetricEntry = {
+    status: "completed";
+    decisionId: string;
+    pack?: {
+        id: string;
+        version: number;
+    };
+    provider: string;
+    latencyMs: number;
+} | {
+    status: "fallback";
+    decisionId: string;
+    pack?: {
+        id: string;
+        version: number;
+    };
+    provider: string;
+    latencyMs: number;
+    reason: DecisionFallbackReason;
+};
+export interface DecisionMetricsSnapshot {
+    requests: number;
+    completed: number;
+    fallbacks: number;
+    avgLatencyMs?: number;
+    p95LatencyMs?: number;
+    lastFallback?: {
+        reason: DecisionFallbackReason;
+        decisionId: string;
+        at: string;
+    };
+    packs: Record<string, number>;
+    provider?: string;
+}
+/** In-memory, per-process decision metrics with an optional per-session view. Never persisted. */
+export declare class DecisionMetrics {
+    private now;
+    private process;
+    private sessions;
+    constructor(now?: () => number);
+    record(entry: DecisionMetricEntry, sessionId?: string): void;
+    /** The session's view, or the whole process when no session is given. */
+    snapshot(sessionId?: string): DecisionMetricsSnapshot;
+}

package/dist/decisions/metrics.js

@@ -0,0 +1,79 @@
+const LATENCY_RING = 200;
+const MAX_SESSIONS = 200;
+class Tally {
+    completed = 0;
+    fallbacks = 0;
+    provider;
+    lastFallback;
+    packs = new Map();
+    /** Ring of the last completed latencies. */
+    latencies = [];
+    next = 0;
+    add(entry, at) {
+        this.provider = entry.provider;
+        if (entry.pack)
+            this.packs.set(entry.pack.id, (this.packs.get(entry.pack.id) ?? 0) + 1);
+        if (entry.status === "completed") {
+            this.completed++;
+            if (this.latencies.length < LATENCY_RING)
+                this.latencies.push(entry.latencyMs);
+            else
+                this.latencies[this.next] = entry.latencyMs;
+            this.next = (this.next + 1) % LATENCY_RING;
+        }
+        else {
+            this.fallbacks++;
+            this.lastFallback = { reason: entry.reason, decisionId: entry.decisionId, at };
+        }
+    }
+    snapshot() {
+        const out = {
+            requests: this.completed + this.fallbacks,
+            completed: this.completed,
+            fallbacks: this.fallbacks,
+            packs: Object.fromEntries(this.packs),
+        };
+        if (this.latencies.length) {
+            const sorted = [...this.latencies].sort((a, b) => a - b);
+            out.avgLatencyMs = Math.round(sorted.reduce((sum, v) => sum + v, 0) / sorted.length);
+            out.p95LatencyMs = sorted[Math.ceil(0.95 * sorted.length) - 1];
+        }
+        if (this.lastFallback)
+            out.lastFallback = { ...this.lastFallback };
+        if (this.provider)
+            out.provider = this.provider;
+        return out;
+    }
+}
+/** In-memory, per-process decision metrics with an optional per-session view. Never persisted. */
+export class DecisionMetrics {
+    now;
+    process = new Tally();
+    sessions = new Map();
+    constructor(now = () => Date.now()) {
+        this.now = now;
+    }
+    record(entry, sessionId) {
+        const at = new Date(this.now()).toISOString();
+        this.process.add(entry, at);
+        if (!sessionId)
+            return;
+        let tally = this.sessions.get(sessionId);
+        if (!tally) {
+            if (this.sessions.size >= MAX_SESSIONS) {
+                const oldest = this.sessions.keys().next().value;
+                if (oldest !== undefined)
+                    this.sessions.delete(oldest);
+            }
+            tally = new Tally();
+            this.sessions.set(sessionId, tally);
+        }
+        tally.add(entry, at);
+    }
+    /** The session's view, or the whole process when no session is given. */
+    snapshot(sessionId) {
+        if (sessionId === undefined)
+            return this.process.snapshot();
+        return (this.sessions.get(sessionId) ?? new Tally()).snapshot();
+    }
+}

package/dist/decisions/registry.d.ts

@@ -0,0 +1,22 @@
+import type { DecisionProvider } from "@alisio/sdk";
+export interface RegisteredDecisionProvider {
+    owner: string;
+    provider: DecisionProvider;
+}
+/** Catalog of decision providers. Registering never activates: the configuration picks one. */
+export declare class DecisionRegistry {
+    private entries;
+    private listeners;
+    /** Notified after every successful registration and removal (never throws into callers). */
+    onChange(listener: () => void): () => void;
+    private changed;
+    /** Returns the function that removes this registration (a no-op once it was replaced). */
+    register(owner: string, provider: DecisionProvider): () => void;
+    get(id: string): RegisteredDecisionProvider | undefined;
+    list(): Array<{
+        id: string;
+        name: string;
+        owner: string;
+        capabilities: DecisionProvider["capabilities"];
+    }>;
+}

package/dist/decisions/registry.js

@@ -0,0 +1,64 @@
+const PROVIDER_ID = /^[a-z0-9][a-z0-9.-]{0,63}$/;
+/** Catalog of decision providers. Registering never activates: the configuration picks one. */
+export class DecisionRegistry {
+    entries = new Map();
+    listeners = new Set();
+    /** Notified after every successful registration and removal (never throws into callers). */
+    onChange(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    changed() {
+        for (const listener of this.listeners) {
+            try {
+                listener();
+            }
+            catch {
+                /* Observers cannot break registration. */
+            }
+        }
+    }
+    /** Returns the function that removes this registration (a no-op once it was replaced). */
+    register(owner, provider) {
+        if (!provider || typeof provider !== "object")
+            throw new Error("Invalid decision provider");
+        if (typeof provider.id !== "string" || !PROVIDER_ID.test(provider.id))
+            throw new Error(`Invalid decision provider id: ${String(provider.id)}`);
+        if (typeof provider.name !== "string" || !provider.name.trim())
+            throw new Error(`Decision provider ${provider.id} needs a name`);
+        const capabilities = provider.capabilities;
+        if (!capabilities ||
+            typeof capabilities.select !== "boolean" ||
+            typeof capabilities.boolean !== "boolean" ||
+            typeof capabilities.ordinal !== "boolean")
+            throw new Error(`Decision provider ${provider.id} needs boolean capabilities`);
+        if (typeof provider.decide !== "function")
+            throw new Error(`Decision provider ${provider.id} needs a decide function`);
+        if (this.entries.has(provider.id))
+            throw new Error(`Duplicate decision provider: ${provider.id}`);
+        const entry = { owner, provider };
+        this.entries.set(provider.id, entry);
+        this.changed();
+        return () => {
+            if (this.entries.get(provider.id) !== entry)
+                return;
+            this.entries.delete(provider.id);
+            this.changed();
+        };
+    }
+    get(id) {
+        return this.entries.get(id);
+    }
+    list() {
+        return [...this.entries.values()]
+            .map(({ owner, provider }) => ({
+            id: provider.id,
+            name: provider.name,
+            owner,
+            capabilities: { ...provider.capabilities },
+        }))
+            .sort((a, b) => a.id.localeCompare(b.id));
+    }
+}

package/dist/decisions/service.d.ts

@@ -0,0 +1,137 @@
+import { type DecisionFallbackReason, type DecisionOptions, type DecisionProvider, type DecisionRequest, type DecisionResponse, type DecisionsApi } from "@alisio/sdk";
+import { type CircuitBreakerOptions, type CircuitState } from "./breaker.ts";
+import type { DecisionMetrics } from "./metrics.ts";
+import type { DecisionRegistry } from "./registry.ts";
+/** The slice of the `decisions` configuration block the service reads (live, per call). */
+export interface DecisionsConfig {
+    enabled: boolean;
+    /** Id of the active provider; `null` disables the feature. */
+    provider: string | null;
+    timeoutMs: number;
+    minConfidence: number;
+    telemetry: boolean;
+}
+export declare const DEFAULT_DECISIONS_CONFIG: DecisionsConfig;
+/** `/decisions` asks the provider's health with its own short limit. */
+export declare const HEALTH_TIMEOUT_MS = 1000;
+type Pack = {
+    id: string;
+    version: number;
+};
+export type DecisionOutcome = {
+    status: "completed";
+    decisionId: string;
+    pack?: Pack;
+    provider: string;
+    latencyMs: number;
+    decisionCount: number;
+    rejectedCount: number;
+    confidenceMin: number;
+} | {
+    status: "fallback";
+    decisionId: string;
+    pack?: Pack;
+    provider: string;
+    latencyMs: number;
+    reason: DecisionFallbackReason;
+};
+export interface DecisionAttempt {
+    response: DecisionResponse | null;
+    /** Absent when no attempt happened (disabled or no active provider). */
+    outcome?: DecisionOutcome;
+}
+/** `decide()` failure: the typed counterpart of a `null` from `tryDecide`. */
+export declare class DecisionError extends Error {
+    readonly reason: DecisionFallbackReason | "disabled" | "no_provider";
+    constructor(reason: DecisionFallbackReason | "disabled" | "no_provider", message?: string);
+}
+export interface DecisionStatus {
+    enabled: boolean;
+    /** The configured provider id, whether or not it is registered. */
+    configured: string | null;
+    active: {
+        id: string;
+        name: string;
+        capabilities: DecisionProvider["capabilities"];
+    } | null;
+    registered: ReturnType<DecisionRegistry["list"]>;
+    health?: {
+        status: "ready" | "starting" | "unavailable";
+        detail?: string;
+    };
+    circuit: CircuitState;
+    /** Last `activate`/`deactivate` failure of any provider (cleared by a later successful activate). */
+    lastLifecycleError?: {
+        provider: string;
+        phase: "activate" | "deactivate";
+        message: string;
+        at: number;
+    };
+}
+export interface DecisionServiceDeps {
+    registry: DecisionRegistry;
+    /** Read on every call so configuration changes apply to the next decision. */
+    config: () => DecisionsConfig;
+    metrics: DecisionMetrics;
+    now?: () => number;
+    breaker?: CircuitBreakerOptions;
+    /** Provider lifecycle (ADR-11): the limit of each call and where failures are logged. */
+    lifecycle?: {
+        timeoutMs?: () => number;
+        log?: (message: string) => void;
+    };
+}
+/**
+ * Decision Intelligence service: one active provider (chosen by configuration), request and answer
+ * validation per decision, a core-enforced time limit and a circuit breaker. Without an active
+ * provider it is a silent null object: no metrics, no events.
+ */
+export declare class DecisionService implements Omit<DecisionsApi, "registerProvider"> {
+    private readonly registry;
+    private readonly config;
+    private readonly metrics;
+    private readonly now;
+    private readonly breaker;
+    /** Registration the breaker state belongs to; a change of provider resets it. */
+    private breakerOwner;
+    private readonly lifecycle;
+    /** The registration `activate` was last requested for (the one that is active, lifecycle-wise). */
+    private lifecycleEntry;
+    private lifecycleOn;
+    private closed;
+    /** Per-registration queue: `deactivate` never crosses a still-running `activate`. */
+    private queues;
+    private lifecycleError;
+    constructor(deps: DecisionServiceDeps);
+    /**
+     * Lifecycle (ADR-11): makes `activate`/`deactivate` follow what the configuration and the
+     * registry say is the active provider. Idempotent, synchronous and never throws: the hooks run
+     * in the background (bounded, serialized per provider, failures recorded). The first call (after
+     * the plugins loaded) also arms the follow-up on registry changes.
+     */
+    syncActive(): void;
+    /** Close: deactivates the active provider (bounded by `timeoutMs`) and stops following changes. */
+    shutdown(timeoutMs?: number): Promise<void>;
+    private enqueue;
+    /** Runs one hook with a limit; resolves always (a failure is recorded, never propagated). */
+    private runLifecycle;
+    private active;
+    available(): boolean;
+    activeProvider(): {
+        id: string;
+        name: string;
+    } | null;
+    tryDecide(req: DecisionRequest, opts?: DecisionOptions): Promise<DecisionResponse | null>;
+    /** Like `tryDecide`, but a missing response throws a typed `DecisionError`. */
+    decide(req: DecisionRequest, opts?: DecisionOptions): Promise<DecisionResponse>;
+    /**
+     * The full result of one call, with the outcome the run integration turns into an event.
+     * Throws `DecisionRequestError` for a malformed request and rethrows the caller's abort.
+     */
+    attempt(req: DecisionRequest, opts?: DecisionOptions, ctx?: {
+        sessionId?: string;
+    }): Promise<DecisionAttempt>;
+    /** For `/decisions` only: the one place `health()` is called, with its own short limit. */
+    status(signal?: AbortSignal): Promise<DecisionStatus>;
+}
+export {};