loopforge 3.9.4 → 4.0.7

package/skills/forge/references/recovery-and-views.md

@@ -0,0 +1,188 @@
+# Recovery, Prompt Levels, and Read-Only Views
+
+This reference explains concepts and flows. The live `submission_guidance`
+remains the only source for field applicability, legal shapes, real ids, and
+usable commands.
+
+## Backtrack and Agent recovery
+
+A progress stall requires observable Git history over the lookback window. Only
+the Git workspace coverage participates: a custom evidence provider's
+changed/unknown facts are recorded and displayed but cannot prevent a stall or
+keep the prompt at L1. Committed work counts as motion through the Git HEAD
+change, even when the closing worktree is clean, and the round you are
+submitting counts too: if it moved files or committed, it cancels the verdict.
+If machine history cannot be read, no stall verdict is made.
+
+LoopForge can trigger a machine backtrack when a rule requires it. The Agent may
+also abandon the current branch deliberately by submitting a top-level
+`recovery: { target_checkpoint_id, reason }` instead of an `evaluation`, using
+the current `submissionHandle`.
+
+Recovery is an action, not an evaluation:
+
+- it requires none of the four core evaluation fields;
+- it requires the current handle and a non-empty reason;
+- the target must resolve to a checkpoint ref visible through the held
+  transaction or a committed evaluation transaction on the current branch;
+- error-level verification findings on the target round do not disqualify it,
+  because it is recovery material, not a success claim;
+- the reason is recorded verbatim and rendered in the Recovery Brief as
+  report-only text, never as a LoopForge instruction.
+
+LoopForge commits the rollback directive, executes the restore itself, verifies
+the complete Git fingerprint boundary and recorded HEAD, then compiles the redo
+prompt. A failed restore leaves the directive pending, sets the session to
+`stalled`, and `resume` retries the SAME directive. The directive survives the
+redo as an audit event. A restore is not round progress and never satisfies a
+redo-time verification check.
+
+When backtrack occurs:
+
+1. Read the protected Recovery Brief and the current prompt. Do not restore the
+   workspace yourself: LoopForge already did, and re-running git reset/stash/
+   checkout would move outside the verified target.
+2. The redo prompt is already compiled from the verified post-restore baseline.
+   Submit its work and evidence using the new `submissionHandle` returned with
+   it.
+3. Do not repeat a failed approach without addressing its cause. Carry valid
+   discoveries into the redo evaluation.
+
+If the rolled-back work used an active contract, follow the Recovery Brief and
+live `submission_guidance` for that contract. Do not blindly restate or replace
+it; a successor proposal is subject to the same contract lifecycle rules.
+
+## Workspace checkpoints
+
+A workspace checkpoint is recovery material, not history. Its authority is the
+`CheckpointRef` inside a transaction snapshot; the content-addressed manifest
+and blobs hold only what HEAD cannot reproduce.
+
+- The before-image is captured automatically when a round is prepared.
+- `loopforge_checkpoint` creates an explicit mid-round savepoint. The call is
+  the Agent's decision that this state is worth restoring to.
+- A checkpoint creates no round, no commit, and no progress. It is visible as a
+  recovery target only through the held transaction's ref list.
+- A successful checkpoint leaves the `submissionHandle` unchanged.
+- Re-capturing the same state is idempotent; distinct savepoints are capped.
+- Checkpoints never feed Canonical State, prompts, acceptance, progress, or
+  stall.
+
+## Prompt levels
+
+L0, L1, and L2 select prompt density only; they never control which evaluation
+fields you may use. Each density can accompany a clean-context model
+conversation or an in-context retry; read `contextMode` and `contextReason`.
+The runtime selection rules and the context boundary live in the prompt's
+`## Round Boundary` section, its context-strategy label, and the MCP server
+instructions; this reference does not restate them.
+
+The optional `currentUserInstruction` on `loopforge_next` / `loopforge_resume`
+is invocation input: it is rendered in the prompt and recorded in that prompt's
+artifact, and never rewrites the task, Objective, criteria, constraints or
+Round Contract. Omitting it means the prompt says "not provided"; never infer
+it from the old task or transcript.
+
+Every level renders the same protected normative set: active criteria, every
+active constraint, the active contract and all its items, every active sub-goal
+id, every current verification finding, and the committed recovery brief. A
+clean-context prompt also renders the previous committed round's **Machine
+Evidence** when present. Display caps may shorten
+descriptions but never remove ids. If a protected active id is missing,
+LoopForge fails closed with `projection_incomplete` instead of delivering a
+partial prompt. The delivered prompt equals the compiled `renderedPrompt` on
+every path.
+
+A clean-context (`fresh_invocation`) prompt may render a bounded **Working
+Memory** section derived from committed history. L1 and L2 render the same full fixed projection: up to
+five reports, eight assumptions, six open questions, three recoveries and
+three contract redirects, with per-item text limits. L0 stays compact (one
+report, two assumptions, two questions, one recovery and one redirect). The
+underlying source window is five committed rounds for reports, assumptions and
+redirects; open questions remain active until resolved, and recovery directives
+have their own fixed limit. These limits are code constants, not policy. The
+default whole-prompt ceilings are
+5,000 / 50,000 / 100,000 characters for L0 / L1 / L2. They are safety ceilings,
+not routine targets for memory omission.
+
+Working Memory is optional but INDIVISIBLE: if it cannot fit, it is dropped
+whole, and the artifact records `rendered:false` with source counts. Every
+omission has source/rendered/omitted counts and a deterministic abbreviation
+notice. It declares no normative ids and never changes coverage, level,
+freshness, gates or success. A `same_round_retry` renders neither Working Memory
+nor Machine Evidence at any density; it relies on the rejection notice and
+Verification Gate. A `fresh_invocation` retry with `rejection_escalation` may
+render the previous posture plus the rejected attempt's transient, explicitly
+`not committed` posture. A `fresh_invocation` / `invocation_recovery` prompt is
+the cold replacement of a lost in-context retry for the SAME round/attempt:
+`loopforge_resume(loopId, invocationLost: true)` recompiles it at L2 with the
+rejection notice, findings, previous Machine Evidence, bounded Working Memory
+and the rejected attempt's posture. The state
+file carries the full fixed Working Memory window.
+
+## Read-only views
+
+Use these to inspect, never to advance:
+
+- `loopforge_status` `view: "session"`: live session status, current round,
+  the current held `submissionHandle`, `machineBackedSuccessTrajectory`,
+  `evidencePosture`/`machineBackedSuccess`, checkpoints, capability, current
+  guidance, and the latest committed receipt. Accepts the
+  live `sessionId` or the durable `loopId`. A persisted STOPPED loop is
+  readable by `loopId` without resuming: it returns `status`, the committed
+  `loopStopReason`, the Agent stop facts, `stopDetail` and `last_submission`.
+  A running/paused/stalled loop without a live session still means call
+  `loopforge_resume`. It never returns the held prompt: a
+  null handle, a missing live session, or a lost prompt means call
+  `loopforge_resume`. A paused or stalled session may still show its handle, but
+  submissions are refused until resume.
+- `loopforge_status` `view: "loop"`: committed health counts.
+- `loopforge_status` `view: "all"`: every persisted loop summary.
+- `loopforge_status` `view: "audit"`: end-of-loop verification completeness.
+- `loopforge_status` `view: "explain"` (with `round`): the per-round "why" view
+  over committed facts, including the committed report (even without an
+  execution_report), context boundary, assumptions, open questions, blocker,
+  the persisted `evidencePosture`, full before/after command observations,
+  committed checkpoints and restore marker, and rollback digest facts.
+- `loopforge_replay`: committed round timeline and diffs. Pass `loopId` (or a
+  live `sessionId`) and optional `start` / `end`. With no window it returns the
+  last 10 committed rounds; an explicit window may span at most 50 rounds. The
+  response includes `window: { start, end, totalRounds, hasBefore, hasAfter }`
+  and each round's `attempt`, `context_mode`, `context_reason`, `outcome`,
+  bounded `report`, `wrong_assumptions`, `retracted_constraints`,
+  `open_questions`, `blocker` and `contract_redirect`. `rollbacks` carries
+  `failedRounds`, `approaches` and `wrongAssumptions`. Legacy envelope rows stay
+  visible instead of disappearing.
+- `loopforge_status` `view: "session"` / `view: "loop"` / `view: "audit"`: live
+  and committed health views.
+
+The optional `.loopforge/state/<loopId>-state.md` is derived and regenerable.
+Read it when the prompt points to it (current governance + bounded Working
+Memory + diagnostic views), but never treat it as a second source of truth:
+committed typed rounds are authoritative, the file's Agent-reported summaries
+are claims, and a state hash that differs from the prompt header means the file
+is stale. Re-align with status or resume.
+
+## Gates and delegation
+
+The two gate tools are opt-in through `policy.gate.enabled`. When enabled:
+
+- `loopforge_gate_check` preflights a structured action with its description,
+  scope, effects, reversibility, and authorization. It takes the current
+  `submissionHandle` and the action; it never executes or approves anything.
+- Classification is conservative: anything not provably safe becomes
+  `user_required`.
+- Present the approval question, record the decision with
+  `loopforge_gate_resolve` (`sessionId` + `gateId`), and cite the approved gate
+  id in `evaluation.gate_ids`.
+- LoopForge records the process, but cannot prove a human was present because
+  the Agent submits the resolve call.
+- Safe investigation and dry-runs need no gate.
+
+Delegation does not create another LoopForge mode. Give each worker a
+self-contained subtask and hard constraints, then place the result in
+`worker_results` with `agentId`, `subTask`, `resultSummary`, and `outcome`.
+The result is saved with the committed transaction as an audit report. It does
+not enter the global constraint set by itself. If you accept a worker's finding,
+state it in top-level `discovered_constraints`; that is the only promotion
+channel.

package/dist/cognitive-facts.d.ts

@@ -1,30 +0,0 @@
-/** Shared cognitive facts used by typed projections and handoff views. */
-import type { CommittedRoundView } from "./committed-round.js";
-import type { LoopForgeResponse, LoopProjection } from "./protocol.js";
-import type { RoundFacts } from "./round-facts.js";
-export interface DerivedCognitiveFacts {
-    focus: LoopProjection["focus"];
-    todo: LoopProjection["todo"];
-    phase: LoopProjection["phase"];
-    delegation: LoopProjection["delegation"];
-    handoff: LoopProjection["handoff"];
-    /** v3.8: forwarded, not re-derived — the same facts the canonical state
-     *  embeds, so the projection and the prompt cannot disagree. */
-    verified_subgoals: LoopProjection["verified_subgoals"];
-}
-/** Re-exported from round-facts.ts. The contract-fact derivation (walker,
- *  item reducer, verified sub-goals, verification debt) lives with the bundle
- *  every consumer reads — one implementation, one history window. */
-export { deriveVerifiedSubGoals, deriveVerificationDebt } from "./round-facts.js";
-export declare function deriveCognitiveFacts(input: {
-    compileResponse: LoopForgeResponse | null;
-    rounds: ReadonlyArray<CommittedRoundView>;
-    /** v3.8.1: the contract facts, REQUIRED and already derived by the caller via
-     *  `deriveRoundFacts`. This function used to run the same reducers again over
-     *  its own window, which let the projection and the prompt disagree about
-     *  what the machine had verified. */
-    facts: RoundFacts;
-    verifiedClaims?: string[];
-    openGates?: string[];
-}): DerivedCognitiveFacts;
-//# sourceMappingURL=cognitive-facts.d.ts.map

package/dist/cognitive-facts.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"cognitive-facts.d.ts","sourceRoot":"","sources":["../src/cognitive-facts.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAE1E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAG/D,OAAO,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAW,MAAM,eAAe,CAAC;AAChF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,cAAc,CAAC,OAAO,CAAC,CAAC;IAC/B,IAAI,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;IAC7B,KAAK,EAAE,cAAc,CAAC,OAAO,CAAC,CAAC;IAC/B,UAAU,EAAE,cAAc,CAAC,YAAY,CAAC,CAAC;IACzC,OAAO,EAAE,cAAc,CAAC,SAAS,CAAC,CAAC;IACnC;oEACgE;IAChE,iBAAiB,EAAE,cAAc,CAAC,mBAAmB,CAAC,CAAC;CACxD;AAID;;qEAEqE;AACrE,OAAO,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAkDlF,wBAAgB,oBAAoB,CAAC,KAAK,EAAE;IAC1C,eAAe,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAC1C,MAAM,EAAE,aAAa,CAAC,kBAAkB,CAAC,CAAC;IAC1C;;;yCAGqC;IACrC,KAAK,EAAE,UAAU,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB,GAAG,qBAAqB,CA2ExB"}

package/dist/cognitive-facts.js

@@ -1,113 +0,0 @@
-/** Shared cognitive facts used by typed projections and handoff views. */
-import { deriveTodoId } from "./cognitive-governance.js";
-const TODO_LIMIT = 10;
-/** Re-exported from round-facts.ts. The contract-fact derivation (walker,
- *  item reducer, verified sub-goals, verification debt) lives with the bundle
- *  every consumer reads — one implementation, one history window. */
-export { deriveVerifiedSubGoals, deriveVerificationDebt } from "./round-facts.js";
-function deriveTodo(compileResponse, contractItemStatuses) {
-    const candidates = [];
-    const seen = new Set();
-    const push = (item, reason, source, priority) => {
-        const text = item.trim().slice(0, 200);
-        if (!text)
-            return;
-        const id = deriveTodoId(text);
-        if (seen.has(id))
-            return;
-        seen.add(id);
-        candidates.push({ id, item: text, reason, source, priority });
-    };
-    // v3.8: the only sources are machine/cognitive derivations — the agent's
-    // own next_action and emerged_subtasks are no longer projection inputs
-    // (emerged items already surface through their compiled sub-goals).
-    //
-    // The ACTIVE contract's unresolved items come first: they are the bounded
-    // work this round executes under, and `insufficient` items are the
-    // verification debt the agent must close.
-    for (const item of contractItemStatuses?.items ?? []) {
-        if (item.status === "insufficient") {
-            push(item.description, "contract item claimed met, not machine-verified", "derived", 10);
-        }
-        else if (item.status === "pending") {
-            push(item.description, "pending contract item", "derived", 8);
-        }
-    }
-    for (const subGoal of compileResponse?.sub_goals ?? []) {
-        const goal = subGoal;
-        if (goal.status === "blocked") {
-            push(goal.description, "blocked sub-goal", "derived", 9);
-        }
-        else if (goal.status === "pending") {
-            push(goal.description, "pending sub-goal", "derived", goal.priority ?? 5);
-        }
-    }
-    return candidates
-        .sort((a, b) => b.priority - a.priority || a.id.localeCompare(b.id))
-        .slice(0, TODO_LIMIT);
-}
-export function deriveCognitiveFacts(input) {
-    const { compileResponse, rounds } = input;
-    const latestFocus = [...rounds].reverse().find((round) => round.outcome !== "failed" &&
-        typeof round.evaluation?.output_summary === "string" &&
-        round.evaluation.output_summary.length > 0);
-    const milestones = compileResponse?.rolling_summary?.milestones ?? [];
-    const boundaries = milestones
-        .filter((milestone) => typeof milestone.round_range?.end === "number")
-        .map((milestone) => ({ label: milestone.label, round: milestone.round_range.end }));
-    const lastBoundary = boundaries[boundaries.length - 1];
-    const workerRounds = rounds.filter((round) => (round.evaluation?.worker_results?.length ?? 0) > 0);
-    const latestWorkerRound = workerRounds[workerRounds.length - 1];
-    const workerResults = latestWorkerRound?.evaluation?.worker_results ?? [];
-    const rolling = compileResponse?.rolling_summary;
-    // v3.8.1: read from the caller's derivation — do NOT re-run the reducers
-    // here. Two derivations of the same fact is how the projection and the
-    // prompt start disagreeing.
-    const { activeContract, itemStatuses: contractItemStatuses, verifiedSubGoals, verificationDebt, } = input.facts;
-    const currentTask = activeContract?.work_item ??
-        compileResponse?.loop_objective?.objective ?? "";
-    const latestOutcome = rolling?.key_outcomes[rolling.key_outcomes.length - 1] ??
-        latestFocus?.evaluation?.output_summary ?? "";
-    const remainingCriteria = (compileResponse?.criterion_statuses ?? [])
-        .filter((criterion) => criterion.status !== "verified" && criterion.status !== "claimed")
-        .map((criterion) => criterion.text)
-        .slice(0, 5);
-    const summary = [
-        currentTask ? `Current task: ${currentTask.slice(0, 200)}` : "",
-        latestOutcome ? `Latest outcome: ${latestOutcome.slice(0, 200)}` : "",
-        remainingCriteria.length > 0
-            ? `Remaining criteria: ${remainingCriteria.join("; ").slice(0, 300)}`
-            : "",
-    ].filter(Boolean).join(" | ");
-    const latestBlocker = [...rounds].reverse()
-        .find((round) => round.outcome === "blocked")?.evaluation?.blocker;
-    return {
-        focus: latestFocus
-            ? { what: latestFocus.evaluation.output_summary.slice(0, 200), since_round: latestFocus.round }
-            : null,
-        todo: deriveTodo(compileResponse, contractItemStatuses),
-        phase: lastBoundary
-            ? { current: lastBoundary.label, label: lastBoundary.label, boundaries }
-            : null,
-        delegation: {
-            pending: workerResults.filter((worker) => worker.outcome === "partial" || worker.outcome === "failed").length,
-            last_results: workerResults.slice(-5).map((worker) => ({
-                agentId: worker.agentId,
-                outcome: worker.outcome,
-                round: latestWorkerRound?.round ?? 0,
-                summary: worker.resultSummary.slice(0, 200),
-            })),
-        },
-        handoff: {
-            summary,
-            verified: [...(input.verifiedClaims ?? [])],
-            open_risks: [...new Set([
-                    ...(latestBlocker ? [latestBlocker] : []),
-                    ...verificationDebt,
-                    ...(input.openGates ?? []).slice(0, 3).map((gate) => `user gate pending: ${gate}`),
-                ])],
-        },
-        verified_subgoals: verifiedSubGoals,
-    };
-}
-//# sourceMappingURL=cognitive-facts.js.map

package/dist/cognitive-facts.js.map

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

package/dist/loop-extras-parser.d.ts

@@ -1,81 +0,0 @@
-/** LoopExtrasParser — Typed extraction pipeline for LoopForgeRequest extras.
- *
- * invokeLoopCompile receives a LoopForgeRequest whose extra fields arrive as
- * untyped `Record<string, unknown>`. Before this module, each field was
- * extracted inline with ad-hoc `typeof` guards spread across ~80 lines of
- * engine.ts — brittle, untestable, and error-prone.
- *
- * ExtractionContext provides a single-pass, type-safe extraction surface:
- * - Every method returns a typed value or a sensible default.
- * - Type mismatches and out-of-range values are collected in `errors[]`
- *   rather than thrown, so the caller can log them and continue with
- *   best-effort defaults.
- * - All extraction is synchronous and pure (no I/O, no side effects).
- *
- * Design constraint: zero runtime dependencies (Node.js stdlib only).
- */
-import type { VerificationFlag } from "./protocol.js";
-export interface FieldError {
-    field: string;
-    message: string;
-    received: unknown;
-}
-export declare class ExtractionContext {
-    /** Errors collected during extraction. The caller decides whether to
-     *  log them, fail fast, or ignore them. Never populated for optional
-     *  fields when the value is absent — only for present-but-invalid values. */
-    readonly errors: FieldError[];
-    private readonly source;
-    constructor(source: Record<string, unknown>);
-    /** Extract a required string field. Returns `fallback` (default `""`) when
-     *  the key is missing or the value is not a string. */
-    string(key: string, fallback?: string): string;
-    /** Extract an optional string field. Returns `null` when absent,
-     *  `fallback` when present-but-invalid. */
-    optionalString(key: string, fallback?: string | null): string | null;
-    /** Extract a number field. Returns `fallback` when missing or invalid.
-     *  Applies optional `min`/`max` clamping and `truncate` (Math.trunc). */
-    number(key: string, fallback: number, opts?: {
-        min?: number;
-        max?: number;
-        truncate?: boolean;
-    }): number;
-    /** Extract a boolean field. Returns `fallback` when missing or invalid. */
-    boolean(key: string, fallback?: boolean): boolean;
-    /** Extract a string array. Returns `fallback` (default `[]`) when missing.
-     *  Filters out non-string elements and records them as errors individually. */
-    stringArray(key: string, fallback?: string[]): string[];
-    /** Extract a plain object field. Returns `null` when missing or when the
-     *  value is not a non-array object. Does not recurse into the value. */
-    object(key: string): Record<string, unknown> | null;
-    /** Check whether a key exists (is not undefined). Useful for gating
-     *  optional structured fields — call object() only when present. */
-    has(key: string): boolean;
-}
-export interface ParsedLoopExtras {
-    loop_id: string;
-    round: number;
-    goal_id: string;
-    domain: string;
-    next_task_proposal: string;
-    plan_source: string | null;
-    constraints_from_plan: string[];
-    new_since_last_round: string;
-    force_level: string;
-    external_context: string;
-    max_rounds: number | undefined;
-    verification_flags: VerificationFlag[];
-    attempt: number;
-    consecutive_rejections: number;
-    rejection_notice: string;
-    last_round_result: Record<string, unknown> | null;
-    loop_objective: Record<string, unknown> | null;
-}
-/** Parse all extras fields from a LoopForgeRequest into a typed structure.
- *  Extraction errors are attached to the returned context for inspection.
- *  This function never throws — every field has a safe default. */
-export declare function parseLoopExtras(extras: Record<string, unknown>, taskId: string): {
-    parsed: ParsedLoopExtras;
-    ctx: ExtractionContext;
-};
-//# sourceMappingURL=loop-extras-parser.d.ts.map

package/dist/loop-extras-parser.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"loop-extras-parser.d.ts","sourceRoot":"","sources":["../src/loop-extras-parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAItD,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAID,qBAAa,iBAAiB;IAC5B;;iFAE6E;IAC7E,QAAQ,CAAC,MAAM,EAAE,UAAU,EAAE,CAAM;IAEnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0B;gBAErC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAM3C;2DACuD;IACvD,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,SAAK,GAAG,MAAM;IAY1C;+CAC2C;IAC3C,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAM,GAAG,IAAW,GAAG,MAAM,GAAG,IAAI;IAY1E;6EACyE;IACzE,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAC3C,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,QAAQ,CAAC,EAAE,OAAO,CAAC;KACpB,GAAG,MAAM;IAkBV,2EAA2E;IAC3E,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,UAAQ,GAAG,OAAO;IAc/C;mFAC+E;IAC/E,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAM,EAAO,GAAG,MAAM,EAAE;IA4B3D;4EACwE;IACxE,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAcnD;wEACoE;IACpE,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;CAG1B;AAID,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,kBAAkB,EAAE,MAAM,CAAC;IAC3B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,qBAAqB,EAAE,MAAM,EAAE,CAAC;IAChC,oBAAoB,EAAE,MAAM,CAAC;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,gBAAgB,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,kBAAkB,EAAE,gBAAgB,EAAE,CAAC;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,sBAAsB,EAAE,MAAM,CAAC;IAC/B,gBAAgB,EAAE,MAAM,CAAC;IACzB,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAClD,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAChD;AAED;;mEAEmE;AACnE,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,MAAM,EAAE,MAAM,GACb;IAAE,MAAM,EAAE,gBAAgB,CAAC;IAAC,GAAG,EAAE,iBAAiB,CAAA;CAAE,CAgCtD"}

package/dist/loop-extras-parser.js

@@ -1,213 +0,0 @@
-/** LoopExtrasParser — Typed extraction pipeline for LoopForgeRequest extras.
- *
- * invokeLoopCompile receives a LoopForgeRequest whose extra fields arrive as
- * untyped `Record<string, unknown>`. Before this module, each field was
- * extracted inline with ad-hoc `typeof` guards spread across ~80 lines of
- * engine.ts — brittle, untestable, and error-prone.
- *
- * ExtractionContext provides a single-pass, type-safe extraction surface:
- * - Every method returns a typed value or a sensible default.
- * - Type mismatches and out-of-range values are collected in `errors[]`
- *   rather than thrown, so the caller can log them and continue with
- *   best-effort defaults.
- * - All extraction is synchronous and pure (no I/O, no side effects).
- *
- * Design constraint: zero runtime dependencies (Node.js stdlib only).
- */
-// ── ExtractionContext ──────────────────────────────────────────────────────
-export class ExtractionContext {
-    /** Errors collected during extraction. The caller decides whether to
-     *  log them, fail fast, or ignore them. Never populated for optional
-     *  fields when the value is absent — only for present-but-invalid values. */
-    errors = [];
-    source;
-    constructor(source) {
-        this.source = source;
-    }
-    // ── Primitives ─────────────────────────────────────────────────────────
-    /** Extract a required string field. Returns `fallback` (default `""`) when
-     *  the key is missing or the value is not a string. */
-    string(key, fallback = "") {
-        const raw = this.source[key];
-        if (raw === undefined || raw === null)
-            return fallback;
-        if (typeof raw === "string")
-            return raw;
-        this.errors.push({
-            field: key,
-            message: `expected string, got ${typeof raw}`,
-            received: raw,
-        });
-        return fallback;
-    }
-    /** Extract an optional string field. Returns `null` when absent,
-     *  `fallback` when present-but-invalid. */
-    optionalString(key, fallback = null) {
-        const raw = this.source[key];
-        if (raw === undefined || raw === null)
-            return null;
-        if (typeof raw === "string")
-            return raw;
-        this.errors.push({
-            field: key,
-            message: `expected string or null, got ${typeof raw}`,
-            received: raw,
-        });
-        return fallback;
-    }
-    /** Extract a number field. Returns `fallback` when missing or invalid.
-     *  Applies optional `min`/`max` clamping and `truncate` (Math.trunc). */
-    number(key, fallback, opts) {
-        const raw = this.source[key];
-        if (raw === undefined || raw === null)
-            return fallback;
-        if (typeof raw === "number" && !Number.isNaN(raw)) {
-            let value = raw;
-            if (opts?.truncate)
-                value = Math.trunc(value);
-            if (opts?.min !== undefined)
-                value = Math.max(opts.min, value);
-            if (opts?.max !== undefined)
-                value = Math.min(opts.max, value);
-            return value;
-        }
-        this.errors.push({
-            field: key,
-            message: `expected number, got ${typeof raw}`,
-            received: raw,
-        });
-        return fallback;
-    }
-    /** Extract a boolean field. Returns `fallback` when missing or invalid. */
-    boolean(key, fallback = false) {
-        const raw = this.source[key];
-        if (raw === undefined || raw === null)
-            return fallback;
-        if (typeof raw === "boolean")
-            return raw;
-        this.errors.push({
-            field: key,
-            message: `expected boolean, got ${typeof raw}`,
-            received: raw,
-        });
-        return fallback;
-    }
-    // ── Collections ────────────────────────────────────────────────────────
-    /** Extract a string array. Returns `fallback` (default `[]`) when missing.
-     *  Filters out non-string elements and records them as errors individually. */
-    stringArray(key, fallback = []) {
-        const raw = this.source[key];
-        if (raw === undefined || raw === null)
-            return fallback;
-        if (!Array.isArray(raw)) {
-            this.errors.push({
-                field: key,
-                message: `expected array, got ${typeof raw}`,
-                received: raw,
-            });
-            return fallback;
-        }
-        const result = [];
-        for (let i = 0; i < raw.length; i++) {
-            if (typeof raw[i] === "string") {
-                result.push(raw[i]);
-            }
-            else {
-                this.errors.push({
-                    field: `${key}[${i}]`,
-                    message: `expected string in array, got ${typeof raw[i]}`,
-                    received: raw[i],
-                });
-            }
-        }
-        return result;
-    }
-    // ── Structured ─────────────────────────────────────────────────────────
-    /** Extract a plain object field. Returns `null` when missing or when the
-     *  value is not a non-array object. Does not recurse into the value. */
-    object(key) {
-        const raw = this.source[key];
-        if (raw === undefined || raw === null)
-            return null;
-        if (typeof raw === "object" && !Array.isArray(raw)) {
-            return raw;
-        }
-        this.errors.push({
-            field: key,
-            message: `expected object, got ${Array.isArray(raw) ? "array" : typeof raw}`,
-            received: raw,
-        });
-        return null;
-    }
-    /** Check whether a key exists (is not undefined). Useful for gating
-     *  optional structured fields — call object() only when present. */
-    has(key) {
-        return this.source[key] !== undefined;
-    }
-}
-/** Parse all extras fields from a LoopForgeRequest into a typed structure.
- *  Extraction errors are attached to the returned context for inspection.
- *  This function never throws — every field has a safe default. */
-export function parseLoopExtras(extras, taskId) {
-    const ctx = new ExtractionContext(extras);
-    const parsed = {
-        loop_id: ctx.string("loop_id") || taskId,
-        round: ctx.number("round", 1, { min: 1, truncate: true }),
-        goal_id: ctx.string("goal_id"),
-        domain: ctx.string("domain"),
-        next_task_proposal: ctx.string("next_task_proposal"),
-        plan_source: ctx.optionalString("plan_source"),
-        constraints_from_plan: ctx.stringArray("constraints_from_plan"),
-        new_since_last_round: ctx.string("new_since_last_round"),
-        force_level: ctx.string("force_level", "auto"),
-        external_context: ctx.string("external_context"),
-        max_rounds: ctx.has("max_rounds")
-            ? ctx.number("max_rounds", 0, { min: 1, truncate: true }) || undefined
-            : undefined,
-        verification_flags: validateVerificationFlags(extras.verification_flags, ctx),
-        attempt: ctx.number("attempt", 1, { min: 1, truncate: true }),
-        consecutive_rejections: ctx.number("consecutive_rejections", 0, {
-            min: 0,
-            truncate: true,
-        }),
-        rejection_notice: ctx.string("rejection_notice"),
-        last_round_result: ctx.object("last_round_result"),
-        loop_objective: ctx.object("loop_objective"),
-    };
-    return { parsed, ctx };
-}
-// ── Specialized validators ────────────────────────────────────────────────
-function validateVerificationFlags(raw, ctx) {
-    if (!Array.isArray(raw)) {
-        if (raw !== undefined && raw !== null) {
-            ctx.errors.push({
-                field: "verification_flags",
-                message: `expected array, got ${typeof raw}`,
-                received: raw,
-            });
-        }
-        return [];
-    }
-    const flags = [];
-    for (let i = 0; i < raw.length; i++) {
-        const item = raw[i];
-        if (item !== null &&
-            typeof item === "object" &&
-            !Array.isArray(item) &&
-            typeof item.severity === "string" &&
-            typeof item.field === "string" &&
-            typeof item.check === "string" &&
-            typeof item.detail === "string") {
-            flags.push(item);
-        }
-        else {
-            ctx.errors.push({
-                field: `verification_flags[${i}]`,
-                message: "expected VerificationFlag object",
-                received: item,
-            });
-        }
-    }
-    return flags;
-}
-//# sourceMappingURL=loop-extras-parser.js.map