looply-cli 0.0.0-stage → 0.2.0

package/dist/goal-compile.d.ts

@@ -0,0 +1,342 @@
+import { type Evidence, type Item, type TaskPacket } from '@looply/core';
+import type { AgentInvoke } from './agent-exec';
+/**
+ * Turning a written intention into work the loop can actually pick up.
+ *
+ * This is `scan` narrowed to one goal. Scan asks "what is wrong with this
+ * repository"; this asks "what would have to be true for THIS outcome to be
+ * reached", and both answer with the same thing — candidate items, born
+ * `draft`, for the existing verify pass to confirm or throw away.
+ *
+ * WHAT THIS IS NOT. It does not execute anything, create a branch, touch a
+ * file, or decide that a goal has been met. It produces candidates and stops.
+ * The agent it calls has the same filesystem authority as every other agent in
+ * this repository — which is to say, all of it; there is no read-only agent
+ * path here and describing this one as read-only would be a lie. The guarantee
+ * that a compilation cannot change the repository is not sandboxing: it is that
+ * nothing downstream of this file applies a diff, and that everything it
+ * returns is a plain data shape that has to survive the verifier before a round
+ * will look at it.
+ */
+/**
+ * How many steps one compilation may produce.
+ *
+ * Not a taste judgement — arithmetic, and the whole of it is asserted in
+ * `goal-compile.spec.ts` against the real constants:
+ *
+ *   the command redelivery window is ONE HOUR from issue, and a start-run that
+ *   is not acked inside it is marked expired and never offered again. The ack
+ *   waits for `run.started`. Everything before `run.started` therefore spends
+ *   that window: this compilation (bounded by COMPILE_TIMEOUT_MS), and then the
+ *   verify pass, which is SEQUENTIAL at up to VERIFIER_TIMEOUT_MS per draft.
+ *
+ *     60m window − 10m compile − (6 × 5m verify) = 20m spare, a third of it
+ *
+ * Producing more than the verify pass can reach inside that window would not
+ * make more work happen; it would make the excess sit as drafts nobody has
+ * looked at while the command that asked for them expires.
+ */
+export declare const COMPILE_MAX_STEPS = 6;
+/** One reasoning call over a repository. Generous, and bounded. */
+export declare const COMPILE_TIMEOUT_MS: number;
+/**
+ * WHY THIS DOES NOT USE `capByShape`, though scan does.
+ *
+ * `itemShape` matches a fixed vocabulary — add/remove/fix/wire/cover against
+ * test/onError/toast/route — drawn from what scanning actually produces. A
+ * compiled plan is written in the goal's language, not that one, so its titles
+ * fall through to the same `other:other` bucket regardless of content: "hash
+ * passwords with argon2", "expire a session token" and "lock an account after
+ * five failed sign-ins" are one shape by that measure. Applying the cap would
+ * silently truncate EVERY plan to `maxSameShape` steps for reasons unrelated to
+ * repetition, which is worse than not applying it — the flagship exercise
+ * caught it doing exactly that.
+ *
+ * What remains against a model that repeats itself: exact repeats collapse,
+ * because two steps that say the same thing derive the same id and therefore
+ * the same item; and COMPILE_MAX_STEPS bounds the whole plan whatever it says.
+ * Near-clones with different nouns are not caught, and that is a known gap
+ * rather than a solved problem.
+ */
+/** A step of a plan, after it has survived narrowing. */
+export interface PlanStep {
+    title: string;
+    tag: string;
+    evidence: Evidence[];
+    /**
+     * WHAT THIS STEP CLAIMS TO SERVE — the model's item→requirement mapping.
+     *
+     * ⚠️ `unknown` ON PURPOSE, and the same convention the server's
+     * `SetItemRequirementsInput.serves` already uses: `servedRequirementTrouble`
+     * (requirement-receipt.ts) is the ONLY thing that says this is a claim. A
+     * parser that pre-filtered it to well-formed links would become a second
+     * authority on what a claim is, and the two would drift.
+     *
+     * ⚠️ A MALFORMED `serves` NEVER REFUSES THE STEP. The step is the work; the
+     * claim is provenance about the work. Losing a real plan step because a model
+     * mis-shaped an optional field would be the expensive half of the trade.
+     */
+    serves?: unknown;
+}
+export type PlanExtract = 
+/**
+ * `malformed` counts steps that were PRESENT and unreadable, as distinct from
+ * a plan that legitimately proposed none.
+ *
+ * Without it the two are the same answer — `ok: true` with no steps — and the
+ * caller cannot tell "the compiler read the goal and had nothing to add" from
+ * "the compiler answered in a shape nobody could parse". They deserve
+ * opposite treatment: the first is a real plan and spends its revision, the
+ * second is a failure and must not.
+ */
+{
+    ok: true;
+    steps: PlanStep[];
+    malformed: number;
+} | {
+    ok: false;
+    steps: [];
+    reason: string;
+};
+/**
+ * The stable identity of a step within one goal version.
+ *
+ * The title, normalised. Two steps that say the same thing ARE the same step,
+ * and a plan that lists one twice should collapse rather than produce two
+ * items — which this makes automatic, because they derive the same id.
+ *
+ * NOT the array position: reordering a plan does not change what its steps
+ * are, and position-keyed ids would make a reordered identical plan into a
+ * second, duplicate one. The model does not get to choose the id either — it
+ * chooses words, and the id is a hash of them.
+ *
+ * A consequence worth stating plainly: the id is deterministic given the PLAN,
+ * not given the goal. Re-running the agent may word a step differently and so
+ * produce a different id. That is why compilation is skipped entirely when the
+ * goal already owns work, rather than relying on the id alone to deduplicate
+ * across two separate reasoning calls.
+ */
+export declare function stepKey(title: string): string;
+/**
+ * The id a compiled step will have.
+ *
+ * Derived, so materialising the same plan twice writes the same rows and the
+ * second write is a no-op rather than a twin. The goal AND its version are in
+ * the seed: a goal whose wording changed is a different intention, and its
+ * steps must not silently reuse the previous version's items.
+ */
+export declare function compiledItemId(goalId: string, goalVersion: number, key: string): string;
+/**
+ * The id a compiled step will have, in a plan that is not the first one.
+ *
+ * A SEPARATE NAMESPACE, and that is the whole point. `seedOf` is
+ * `JSON.stringify` over the entire parts array, so adding a fifth element to
+ * the tuple above would change every id it has ever produced — re-identifying
+ * revision 1 for every goal already in flight, and breaking the convergence
+ * that makes a crash between compiling and materialising cost nothing. Revision
+ * 1 therefore keeps the four-part seed exactly, byte for byte, for ever.
+ *
+ * Revisions after the first get their own domain tag. Two consequences, both
+ * wanted: a step worded identically in revision 1 and revision 2 is two rows,
+ * so the second attempt starts with its own state and its own attempts rather
+ * than silently reusing a `closed` row nothing can pick; and a retry of
+ * revision 2 converges on the same ids as revision 2, so a crash mid-write
+ * lands what is missing and nothing else.
+ */
+export declare function compiledItemRevisionId(goalId: string, goalVersion: number, revision: number, key: string): string;
+/**
+ * The id of the row that records a revision happened at all.
+ *
+ * Its own domain tag, so it can never collide with a step: a plan is free to
+ * contain a step worded like anything, including the marker's own title.
+ */
+export declare function planMarkerId(goalId: string, goalVersion: number, revision: number): string;
+/**
+ * A durable receipt that revision R was materialised, whatever it contained.
+ *
+ * WHY THIS EXISTS. The current revision is read back as the highest one among
+ * the goal's own compiled rows, and that is the only home for it that fails
+ * closed: if a stale writer clobbers queue.json, the revision number and the
+ * plan it counts vanish in the same rename, so the next Start sees the earlier
+ * revision and re-materialises THAT one rather than skipping ahead. Budget and
+ * work are lost together or not at all.
+ *
+ * But a plan can legitimately contain no steps — the compiler answers "none"
+ * when it thinks the goal is met, and a timed-out compilation produces nothing
+ * either. Without a row, such a revision would leave no trace, the budget would
+ * never be spent, and the same empty attempt could be made for ever. This is
+ * that row.
+ *
+ * It is born `closed`, which is doing three jobs at once: `releaseOnAbandon`
+ * keeps a closed row rather than un-owning it, so the receipt survives an
+ * abandonment that frees everything else; nothing picks it, because `isPickable`
+ * rejects it; and nothing verifies it, because the verify pass only looks at
+ * drafts. It can never be `done`, so it can never make `workLeft` say a goal
+ * finished when nothing did.
+ */
+export declare function planMarker(ctx: {
+    goalId: string;
+    goalVersion: number;
+    revision: number;
+    projectId: string;
+    orderKey: string;
+}): Omit<Item, 'version'>;
+/**
+ * Whether this row IS the receipt for its own goal, version and revision.
+ *
+ * THE ONE PREDICATE, because asking it by eye has now gone wrong twice.
+ *
+ * Both times the test was `tag === 'goal'`, and both times it looked like a
+ * marker signature and was not: `'goal'` is what `normalizeStep` gives any plan
+ * step whose tag the model omitted, which it documents as legitimate. The first
+ * occurrence made KEY 2 skip genuinely delivered work and put completion out of
+ * reach; the second hid a step that had FAILED from the evaluator, which then
+ * said the goal was met. A value cannot distinguish these rows. Only the
+ * derived id can.
+ *
+ * Deliberately state-blind. `goal-ownership` has a sibling that also requires
+ * `state === 'closed'`, which is right where it lives — it guards the rule that
+ * rows are born `draft` — and wrong for callers asking "is this row work?",
+ * where a receipt in an unexpected state is more suspect, not less.
+ */
+export declare function isPlanMarker(item: Pick<Item, 'id' | 'goalId' | 'compiledForGoalVersion' | 'compiledForPlanRevision'>): boolean;
+/**
+ * The id for either, chosen by the revision alone.
+ *
+ * Callers never pick the namespace themselves — the revision is the only input,
+ * and it is assigned by the machine. A model cannot reach this.
+ */
+export declare function planItemId(goalId: string, goalVersion: number, revision: number, key: string): string;
+/**
+ * Pull the plan out of what the agent said.
+ *
+ * Scans from the END, like `extractFindings`, and for the same hard-won
+ * reason: an agent often echoes the example object from its own prompt before
+ * producing the real one, and taking the first match reads the example back as
+ * data. Tries the whole transcript as one document first, because a
+ * pretty-printed answer spans many lines.
+ *
+ * Anything malformed is DROPPED rather than thrown on. A plan is a proposal;
+ * the parts of it that arrive unreadable are simply not proposals.
+ */
+export declare function extractPlan(transcript: string): PlanExtract;
+/**
+ * One step, narrowed — or `null` when what arrived is not one.
+ *
+ * A title is required and everything else is optional, which is the one place
+ * this deliberately differs from `normalizeFinding`. A scan finding with no
+ * evidence is a guess about code that already exists, and scanning drops it. A
+ * plan step is work that does not exist yet: "add a spec for the empty-name
+ * case" cites nothing because the spec is the thing being asked for. Evidence
+ * is accepted and passed on where the model can give it — it makes the verify
+ * pass cheaper and likelier to confirm — but requiring it would refuse most of
+ * what a compiler legitimately produces.
+ */
+export declare function normalizeStep(v: unknown): PlanStep | null;
+/** What a compilation asks for, and what it is allowed to know. */
+export interface CompileGoalInput {
+    goalId: string;
+    goalVersion: number;
+    /** The user's own wording. Never rewritten, never summarised. */
+    goalText: string;
+    projectId: string;
+    /** Names the plan may cite. Kept short; the agent can read the repo itself. */
+    projectName: string;
+    /**
+     * What this project has already established, as labelled prose.
+     *
+     * The audit that opened Phase 11 found this function received NOTHING from
+     * past runs — five fields, none of them history — so a plan was recompiled
+     * from the goal text every time and could propose an approach that had
+     * already failed three times. This is that gap.
+     *
+     * Optional because a project with no memory yet must plan exactly as it did
+     * before, and absent means absent rather than "we looked and found nothing".
+     */
+    readonly memory?: string | null;
+    /**
+     * The task packet (M2-3): the requirements a person linked this goal to,
+     * quoted verbatim as data with their standing, the other constraints of those
+     * documents, the tree the standing was measured at, and the links that could
+     * not be read. Absent or empty renders exactly the prompt of before.
+     */
+    readonly packet?: TaskPacket;
+    /**
+     * The CHECKS a claim may cite — this project's gate step names, which ARE
+     * its frozen acceptance map (`ServedRequirement.provenBy`).
+     *
+     * 🔴 THE PLAN COULD NEVER CLAIM A REQUIREMENT, BECAUSE NOBODY ASKED IT TO.
+     * `PlanStep.serves` is parsed and carried, `produceClaims` validates it, and
+     * the lane builds receipts from it — but the prompt's answer shape was
+     * `{"title","tag","evidence"}` and never named `serves`, and a valid
+     * serving REQUIRES a `provenBy` naming a gate step the prompt never listed.
+     * MEASURED, LIVE, 2026-09-24 (LIVE-2): two compiles, four steps each, zero
+     * claims, `servings: []` recorded twice — and the coverage gate can only
+     * ever withhold what no item claims.
+     *
+     * ⚠️ ASKED ONLY WITH A PACKET AND AT LEAST ONE CHECK. A claim names a linked
+     * requirement and a check; with either list empty there is nothing a valid
+     * claim could say, and the prompt is exactly the prompt of before.
+     */
+    readonly checks?: readonly string[];
+}
+/** Why there was no plan: the transport gave up, the transport failed, or the answer could not be read as a plan. */
+export type CompileFailure = 'timed-out' | 'failed' | 'unreadable';
+export type CompileOutcome = 
+/** `requestDigest`: sha256 of the prompt as asked — the compile record's provenance (M3-2). The prompt itself is not kept. */
+{
+    ok: true;
+    steps: PlanStep[];
+    dropped: number;
+    malformed: number;
+    transcript: string;
+    requestDigest: string;
+} | {
+    ok: false;
+    reason: string;
+    failure: CompileFailure;
+    transcript: string;
+    requestDigest: string;
+};
+export interface CompileDeps {
+    invoke: AgentInvoke;
+    timeoutMs?: number;
+    maxSteps?: number;
+}
+export declare function buildCompilePrompt(input: CompileGoalInput, maxSteps?: number): string;
+/**
+ * Compile one goal into candidate steps.
+ *
+ * ONE agent call. Not one per step, not a loop that refines — a plan that needs
+ * several calls to settle is a plan whose cost nobody can predict, and this runs
+ * inside the window a start-run has to be acknowledged in.
+ */
+export declare function compileGoal(input: CompileGoalInput, deps: CompileDeps): Promise<CompileOutcome>;
+/**
+ * Turn a compiled plan into items ready to be written.
+ *
+ * Every one is born owned by the goal that produced it. That is forced rather
+ * than chosen: selection is symmetric, so an unowned compiled item would be
+ * invisible to the very run that compiled it AND visible to an unbound run that
+ * knows nothing about the goal. Both are wrong.
+ *
+ * Every one is born `draft`, like everything else in this system. A compiled
+ * step is a claim that some work is worth doing; the verify pass is what turns
+ * a claim into something a round may pick.
+ */
+export declare function planToItems(steps: readonly PlanStep[], ctx: {
+    goalId: string;
+    goalVersion: number;
+    projectId: string;
+    orderKeyAt: (i: number) => string;
+    /**
+     * Which plan this is for that version. Absent is the first one, which is
+     * what every pre-6C caller means and what keeps their ids unchanged.
+     *
+     * ASSIGNED BY THE MACHINE. The compiler is told which revision it is
+     * producing; it does not get to choose, and no part of the model's answer
+     * reaches this number.
+     */
+    planRevision?: number;
+}): Omit<Item, 'version'>[];
+//# sourceMappingURL=goal-compile.d.ts.map

package/dist/goal-compile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"goal-compile.d.ts","sourceRoot":"","sources":["../src/goal-compile.ts"],"names":[],"mappings":"AACA,OAAO,EAA2E,KAAK,QAAQ,EAAE,KAAK,IAAI,EAAE,KAAK,UAAU,EAAE,MAAM,cAAc,CAAC;AAClJ,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAGhD;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,iBAAiB,IAAI,CAAC;AAEnC,mEAAmE;AACnE,eAAO,MAAM,kBAAkB,QAAiB,CAAC;AAEjD;;;;;;;;;;;;;;;;;;GAkBG;AAEH,yDAAyD;AACzD,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,QAAQ,EAAE,CAAC;IACrB;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,MAAM,WAAW;AACrB;;;;;;;;;GASG;AACD;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,QAAQ,EAAE,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAClD;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,EAAE,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7C;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE7C;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAEvF;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,GACV,MAAM,CAER;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE1F;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;CAClB,GAAG,IAAI,CAAC,IAAI,EAAE,SAAS,CAAC,CAiBxB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,GAAG,QAAQ,GAAG,wBAAwB,GAAG,yBAAyB,CAAC,GACvF,OAAO,CAMT;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAIrG;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,WAAW,CAY3D;AAsBD;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,OAAO,GAAG,QAAQ,GAAG,IAAI,CA6BzD;AAED,mEAAmE;AACnE,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,iEAAiE;IACjE,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,+EAA+E;IAC/E,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC;IAC7B;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED,qHAAqH;AACrH,MAAM,MAAM,cAAc,GAAG,WAAW,GAAG,QAAQ,GAAG,YAAY,CAAC;AAEnE,MAAM,MAAM,cAAc;AACxB,8HAA8H;AAC5H;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,QAAQ,EAAE,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,GAC9G;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,cAAc,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtG,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,WAAW,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,gBAAgB,EAAE,QAAQ,SAAoB,GAAG,MAAM,CAyDhG;AAED;;;;;;GAMG;AACH,wBAAsB,WAAW,CAAC,KAAK,EAAE,gBAAgB,EAAE,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,cAAc,CAAC,CA6CrG;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,SAAS,QAAQ,EAAE,EAC1B,GAAG,EAAE;IACH,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;IAClC;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,GACA,IAAI,CAAC,IAAI,EAAE,SAAS,CAAC,EAAE,CA2BzB"}