@a-company/gnomon 0.0.0-stage → 8.0.2

package/dist/loops.d.ts

@@ -0,0 +1,440 @@
+/** TD-2026-10-23-268: at most this many env files per loop (mirrored in kernel/loops/loop-env.ts). */
+declare const LOOP_ENV_FILES_MAX = 8;
+declare const LOOP_SCHEMA: "loop:v2";
+declare const LOOP_COMPILED_VERSION: 1;
+declare const LOOP_TERMINALS: readonly ["@goal", "@stop", "@pause"];
+type LoopTerminal = (typeof LOOP_TERMINALS)[number];
+declare const LOOP_ID_MAX = 64;
+declare const LOOP_CALL_DEPTH_MAX = 3;
+declare const LOOP_CONTINUOUS_MIN_COOLDOWN_SEC: number;
+declare const LANDS_IN_8_1: "LANDS_IN_8_1";
+/**
+ * BUILD_TOOLS entries a `run` argv0 may still name: direct type checkers and test runners whose config is part
+ * of the config closure (LP2). Every other build tool or package manager (npm, npm exec, make, cargo run …)
+ * runs repo-controlled scripts and is refused as argv0.
+ */
+declare const LOOP_ARGV0_CHECKER_ALLOW: ReadonlySet<string>;
+/** Always in a compiled loop's protected set: act nodes never edit installed dependencies. */
+declare const LOOP_ALWAYS_PROTECTED: readonly ["node_modules/**", "**/node_modules/**"];
+declare const LOOP_BUILTINS: readonly ["paradigm.flow-check", "paradigm.flow-affected", "paradigm.ripple", "paradigm.purpose-validate", "paradigm.drift", "paradigm.reindex", "git.clean"];
+type LoopBuiltin = (typeof LOOP_BUILTINS)[number];
+declare const LOOP_AUTONOMY: readonly ["act", "propose", "observe"];
+declare const LOOP_DECIDE: readonly ["none", "before-land", "on-stop"];
+declare const LOOP_NOTIFY_ON: readonly ["goal", "stop", "fail", "landed"];
+declare const LOOP_NOTIFY_AS: readonly ["toast", "quiet"];
+declare const LOOP_EVENT_KINDS: readonly ["file.changed", "commit.landed", "session.ended", "card.decided"];
+declare const LOOP_WEEKDAYS: readonly ["mon", "tue", "wed", "thu", "fri", "sat", "sun"];
+declare const LOOP_PARSERS: readonly ["tap", "junit", "tsc"];
+declare const LOOP_JSON_OPS: readonly ["==", "!=", "<", "<=", ">", ">="];
+declare const LOOP_MODEL_ROLES: readonly ["judge", "summarize", "act"];
+declare const LOOP_PARADIGM_TOOLS: readonly ["ripple", "flow.check", "flow.affected", "purpose.validate", "drift"];
+/** Input-reference roots that are not node ids (§2 `inputs`, `attach`). */
+declare const LOOP_INPUT_ROOTS: readonly ["trigger", "last", "day", "loop", "failed", "run"];
+/** Verdicts per node type (the edge keys a node may name, besides `any`). */
+declare const CHECK_VERDICTS: readonly ["pass", "fail", "error"];
+declare const MODEL_VERDICTS: readonly ["pass", "fail", "unsure", "unavailable", "error"];
+declare const CALL_VERDICTS: readonly ["pass", "fail", "unsure", "error"];
+declare const TOAST_VERDICTS: readonly ["pass"];
+/**
+ * Global budget defaults, used for any field a definition leaves out (LL3: never unbounded). The live values
+ * come from root-signed `~/.gnomon/config.yaml` `loops:` once LP3 reads it; compileLoop takes them as an option.
+ * Escalations default to 0: loops are local only in 8.0 (D4).
+ */
+interface LoopBudgets {
+    run: {
+        rounds: number;
+        wallMin: number;
+        tokens: number;
+        computeSec: number;
+    };
+    day: {
+        runs: number;
+        tokens: number;
+        computeSec: number;
+    };
+    escalations: {
+        perRun: number;
+        perDay: number;
+    };
+}
+declare const LOOP_BUDGET_DEFAULTS: Readonly<LoopBudgets>;
+declare const LOOP_DEFAULTS: Readonly<{
+    autonomy: "act";
+    decide: "none";
+    notify: Readonly<{
+        on: readonly string[];
+        as: "toast";
+    }>;
+    catchUp: "skip";
+    debounceSec: 0;
+    effect: "read";
+    timeoutSec: 600;
+    landMaxWaitMin: 120;
+    modelLimits: Readonly<{
+        turns: 20;
+        tokens: 80000;
+    }>;
+    minConfidence: 0.7;
+}>;
+type Duration = number | string;
+type Count = number | string;
+type EdgeMap = Record<string, string>;
+type LoopSchedule = {
+    every: Duration;
+} | {
+    daily: string;
+} | {
+    weekly: {
+        day: (typeof LOOP_WEEKDAYS)[number];
+        at: string;
+    };
+};
+type LoopTrigger = {
+    schedule: LoopSchedule;
+    catchUp?: 'skip' | 'once';
+} | {
+    event: {
+        kind: 'file.changed';
+        flow: string;
+    } | {
+        kind: 'commit.landed';
+    } | {
+        kind: 'session.ended';
+    } | {
+        kind: 'card.decided';
+        loop: string;
+        node: string;
+    };
+    debounce?: Duration;
+} | {
+    continuous: {
+        cooldown: Duration;
+    };
+};
+type CheckPass = {
+    exit: number;
+} | {
+    parse: (typeof LOOP_PARSERS)[number];
+    failed: number;
+} | {
+    json: string;
+    op: (typeof LOOP_JSON_OPS)[number];
+    value: string | number | boolean | null;
+};
+interface NodeExit {
+    maxVisits?: number;
+    maxFailStreak?: number;
+}
+interface CheckNode {
+    id: string;
+    type: 'check';
+    run?: string[];
+    builtin?: LoopBuiltin;
+    args?: Record<string, unknown>;
+    effect?: 'read' | 'write';
+    pass?: CheckPass;
+    timeoutSec?: number;
+    /** TD-2026-10-23-268: variables from the human's environment this check's child gets (names only here) */
+    env?: string[];
+    exit?: NodeExit;
+    on?: EdgeMap;
+}
+type ModelTool = 'read' | 'edit' | {
+    paradigm: string[];
+};
+interface ModelNode {
+    id: string;
+    type: 'model';
+    role: (typeof LOOP_MODEL_ROLES)[number];
+    model?: {
+        use?: 'local';
+        profile?: string;
+        escalate?: 'never';
+        minConfidence?: number;
+    };
+    prompt?: string;
+    inputs?: string[];
+    tools?: 'none' | ModelTool[];
+    verdict?: {
+        classes: string[];
+    };
+    limits?: {
+        turns?: number;
+        tokens?: Count;
+    };
+    /** TD-2026-10-23-268: role act only: variables from the human's environment the act session gets */
+    env?: string[];
+    exit?: NodeExit;
+    on?: EdgeMap;
+}
+interface NotifyNode {
+    id: string;
+    type: 'notify';
+    as: 'toast' | 'card';
+    text?: string;
+    attach?: string[];
+    choices?: string[];
+    exit?: NodeExit;
+    on?: EdgeMap;
+}
+interface CallNode {
+    id: string;
+    type: 'call';
+    loop: string;
+    exit?: NodeExit;
+    on?: EdgeMap;
+}
+type LoopNode = CheckNode | ModelNode | NotifyNode | CallNode;
+interface LoopDefinition {
+    schema: typeof LOOP_SCHEMA;
+    id: string;
+    title?: string;
+    repo?: string;
+    flows?: string[];
+    triggers?: LoopTrigger[];
+    autonomy?: (typeof LOOP_AUTONOMY)[number];
+    notify?: {
+        on?: (typeof LOOP_NOTIFY_ON)[number][];
+        as?: (typeof LOOP_NOTIFY_AS)[number];
+    };
+    decide?: (typeof LOOP_DECIDE)[number];
+    budgets?: {
+        run?: {
+            rounds?: number;
+            wallMin?: number;
+            tokens?: Count;
+            computeSec?: number;
+        };
+        day?: {
+            runs?: number;
+            tokens?: Count;
+            computeSec?: number;
+        };
+        escalations?: {
+            perRun?: number;
+            perDay?: number;
+        };
+    };
+    goal?: {
+        node: string;
+        verdict?: 'pass';
+        inputs?: string[];
+    };
+    land?: {
+        paths: string[];
+        message: string;
+        maxWaitMin?: number;
+    };
+    /** TD-2026-10-23-268: `off` shows check output unredacted (no secret scrubbing) for this loop; default on */
+    redact?: 'on' | 'off' | boolean;
+    /** TD-2026-10-23-268: where the nodes' `env` values are read, in order (then ~/.gnomon/loop-env) */
+    envFiles?: string[];
+    /** TD-2026-10-23-268: `on` lets this loop's checks reach the network; default off */
+    network?: 'on' | 'off' | boolean;
+    start: string;
+    nodes: LoopNode[];
+}
+type CompiledTrigger = {
+    type: 'schedule';
+    every?: number;
+    daily?: string;
+    weekly?: {
+        day: string;
+        at: string;
+    };
+    catchUp: 'skip' | 'once';
+} | {
+    type: 'event';
+    kind: string;
+    flow?: string;
+    paths?: string[];
+    loop?: string;
+    node?: string;
+    debounceSec: number;
+} | {
+    type: 'continuous';
+    cooldownSec: number;
+};
+type CompiledNode = {
+    id: string;
+    type: 'check';
+    run?: string[];
+    argv0Interpreter?: string;
+    builtin?: string;
+    args?: Record<string, unknown>;
+    effect: 'read' | 'write';
+    pass: CheckPass;
+    timeoutSec: number;
+    env?: string[];
+    exit?: NodeExit;
+    on: Record<string, string>;
+} | {
+    id: string;
+    type: 'model';
+    role: string;
+    model: {
+        use: 'local';
+        profile?: string;
+        escalate: 'never';
+        minConfidence: number;
+    };
+    prompt?: string;
+    inputs: string[];
+    tools: ModelTool[];
+    verdict?: {
+        classes: string[];
+    };
+    limits: {
+        turns: number;
+        tokens: number;
+    };
+    env?: string[];
+    exit?: NodeExit;
+    on: Record<string, string>;
+} | {
+    id: string;
+    type: 'notify';
+    as: 'toast' | 'card';
+    text?: string;
+    attach: string[];
+    choices?: string[];
+    exit?: NodeExit;
+    on: Record<string, string>;
+} | {
+    id: string;
+    type: 'call';
+    loop: string;
+    callee: string;
+    hash8: string;
+    exit?: NodeExit;
+    on: Record<string, string>;
+};
+interface CompiledLoop {
+    schema: typeof LOOP_SCHEMA;
+    /**
+     * `sourceHash` (LP2): loopContentHash of the PARSED source definition (the YAML), the hash a caller's `id@hash8`
+     * pin names. The kernel never sees the YAML, so it resolves a pin against the TRUSTED callee's sourceHash.
+     */
+    compiled: {
+        version: typeof LOOP_COMPILED_VERSION;
+        flowsResolved: boolean;
+        callsResolved: boolean;
+        sourceHash?: string;
+    };
+    id: string;
+    title?: string;
+    scope: 'repo' | 'personal';
+    repo?: string;
+    flows: string[];
+    flowPaths?: Record<string, string[]>;
+    triggers: CompiledTrigger[];
+    autonomy: string;
+    notify: {
+        on: string[];
+        as: string;
+    };
+    decide: string;
+    budgets: LoopBudgets;
+    goal?: {
+        node: string;
+        verdict: 'pass';
+        inputs: string[];
+    };
+    land?: {
+        paths: string[];
+        message: string;
+        maxWaitMin: number;
+    };
+    /** TD-2026-10-23-268: present only when off (check output unredacted); absent = on */
+    redact?: 'off';
+    /** TD-2026-10-23-268: the env files, as written (present only when non-empty) */
+    envFiles?: string[];
+    /** TD-2026-10-23-268: present only when on (checks can reach the network) */
+    network?: 'on';
+    start: string;
+    nodes: CompiledNode[];
+    /**
+     * Paths act nodes may not edit (the kernel enforces): node_modules, plus goal.inputs and the repo-relative
+     * argv words of run checks across this loop and every loop it calls (transitively, when known).
+     */
+    protected: string[];
+}
+interface LoopIssue {
+    /** JSON-ish path into the definition: `nodes[2].run[0]`, `triggers[0].schedule.cron`, or `` for the root. */
+    path: string;
+    code: string;
+    message: string;
+}
+interface LoopValidateOptions {
+    /** repo loops live in `.paradigm/loops/` and never name `repo`; personal loops (`~/.gnomon/loops`) must. Default repo. */
+    scope?: 'repo' | 'personal';
+    /**
+     * Other loops in the same scope, by id (parsed definitions; only their `call` nodes are read). Given, the
+     * validator refuses unknown callees, call cycles and call depth > 3. Absent, only a self-call is detected.
+     */
+    knownLoops?: ReadonlyMap<string, unknown> | Readonly<Record<string, unknown>>;
+    /** Flow id → path globs (from the flow index). Given, flows resolve; an unknown flow is refused. */
+    flowIndex?: Readonly<Record<string, readonly string[]>>;
+}
+interface LoopCompileOptions extends LoopValidateOptions {
+    /** Global budget defaults (the `loops:` block of ~/.gnomon/config.yaml); default LOOP_BUDGET_DEFAULTS. */
+    budgetDefaults?: LoopBudgets;
+    /**
+     * The shebang line (without `#!`) of a run argv0 that is a script, or null. Given, compiled check nodes carry
+     * `argv0Interpreter` so the trust card can show it (hashing the interpreter is LP2).
+     */
+    readShebang?: (argv0: string) => string | null;
+}
+interface LoopValidation {
+    ok: boolean;
+    errors: LoopIssue[];
+    warnings: LoopIssue[];
+    /** The definition, typed, when ok. */
+    loop?: LoopDefinition;
+}
+interface LoopCompilation extends LoopValidation {
+    compiled?: CompiledLoop;
+}
+/** Parse a duration (`30m`, `90s`, `2h`, `1d`, or integer seconds) to integer seconds; null when malformed. */
+declare function parseDurationSec(v: unknown): number | null;
+/** Parse a count (`400k`, `2M`, or an integer) to a positive integer; null when malformed. */
+declare function parseCount(v: unknown): number | null;
+/** The program argv0 names: its basename without trailing dots, spaces, `.exe` or `.com` (the denylists name programs). */
+declare function programName(argv0: string): string;
+/** The §3.1 issues of a `run` argv (empty when it passes); paths are rooted at `path`. */
+declare function argvIssues(argv: unknown, path: string): LoopIssue[];
+/** sha256 hex of canonicalJson(parsed definition): the content hash a call pin (`id@hash8`) names. */
+declare function loopContentHash(parsed: unknown): string;
+/** Repo-relative path words of an argv (`--opt=value` values too); absolute, `~`, `\\` and `..` words are not repo paths. */
+declare function argvPathWords(argv: readonly unknown[]): string[];
+/** Validate a parsed `loop:v2` definition. Pure: never reads the filesystem. */
+declare function validateLoop(input: unknown, opts?: LoopValidateOptions): LoopValidation;
+/**
+ * Validate, then compile to the kernel's form: every default filled (an absent budget field is the global
+ * default), durations in seconds, edges expanded, flows resolved when a flow index is given.
+ */
+declare function compileLoop(input: unknown, opts?: LoopCompileOptions): LoopCompilation;
+/** The stable hashing form of a compiled loop: sorted keys, no whitespace (gnomon-contracts canonicalJson). */
+declare function canonicalLoopJson(compiled: CompiledLoop): string;
+/** The file form (`<id>.loop.json`): the canonical key order, indented, with a trailing newline. */
+declare function loopFileJson(compiled: CompiledLoop): string;
+/** One-line rendering of an issue for CLI and MCP output. */
+declare function formatLoopIssue(i: LoopIssue): string;
+
+interface CompiledValidation {
+    ok: boolean;
+    errors: LoopIssue[];
+    /** The normalized compiled loop (the re-compile), when ok. Its `protected` is the loop's OWN set (no callees). */
+    compiled?: CompiledLoop;
+}
+/**
+ * Re-validate a parsed `<id>.loop.json` (see the header). `scope` is where the registry found it; `fileId` the file
+ * name's id (they must agree with the content).
+ */
+declare function validateCompiledLoop(value: unknown, opts: {
+    scope: 'repo' | 'personal';
+    fileId?: string;
+}): CompiledValidation;
+
+export { CALL_VERDICTS, CHECK_VERDICTS, LANDS_IN_8_1, LOOP_ALWAYS_PROTECTED, LOOP_ARGV0_CHECKER_ALLOW, LOOP_AUTONOMY, LOOP_BUDGET_DEFAULTS, LOOP_BUILTINS, LOOP_CALL_DEPTH_MAX, LOOP_COMPILED_VERSION, LOOP_CONTINUOUS_MIN_COOLDOWN_SEC, LOOP_DECIDE, LOOP_DEFAULTS, LOOP_ENV_FILES_MAX, LOOP_EVENT_KINDS, LOOP_ID_MAX, LOOP_INPUT_ROOTS, LOOP_JSON_OPS, LOOP_MODEL_ROLES, LOOP_NOTIFY_AS, LOOP_NOTIFY_ON, LOOP_PARADIGM_TOOLS, LOOP_PARSERS, LOOP_SCHEMA, LOOP_TERMINALS, LOOP_WEEKDAYS, MODEL_VERDICTS, TOAST_VERDICTS, argvIssues, argvPathWords, canonicalLoopJson, compileLoop, formatLoopIssue, loopContentHash, loopFileJson, parseCount, parseDurationSec, programName, validateCompiledLoop, validateLoop };
+export type { CallNode, CheckNode, CheckPass, CompiledLoop, CompiledNode, CompiledTrigger, CompiledValidation, Count, Duration, EdgeMap, LoopBudgets, LoopBuiltin, LoopCompilation, LoopCompileOptions, LoopDefinition, LoopIssue, LoopNode, LoopSchedule, LoopTerminal, LoopTrigger, LoopValidateOptions, LoopValidation, ModelNode, ModelTool, NodeExit, NotifyNode };