wicked-crew 0.6.0 → 0.7.1

package/dist/core/deliver.js

@@ -0,0 +1,241 @@
+/**
+ * The first-class deliver phase (crew#293) — a run opens its own PR, opt-in.
+ *
+ * Productizes the operator-side `feature-pr` overlay proven during the DES-MERGE-001 campaign:
+ * a Tool phase appended after the workflow's last phase that COMMITS the run's work, pushes the
+ * run's branch and opens a PR via `gh`. What was data on one machine becomes a launch option
+ * (`deliver: "pr"` on `POST /runs`), composed PER RUN — the shared workflow def is never mutated.
+ *
+ * Field-proven hardening, replicated here:
+ *  (a) the branch is derived from the run worktree's basename (`wicked/<run-id>`), falling back
+ *      to the current branch when that ref does not exist;
+ *  (b) the script REFUSES to push `main`/`master` (or an empty/detached branch name) — the
+ *      deliver phase only ever pushes run branches;
+ *  (c) it STAGES AND COMMITS the run's work, then rebases onto origin's default branch before
+ *      pushing, and a conflicting rebase FAILS the phase visibly (aborting the rebase, pushing
+ *      nothing) rather than pushing a conflicted tree;
+ *  (d) `git push -u origin <branch>`;
+ *  (e) `gh pr create --head <branch> --fill`, with gh's output and exit status captured
+ *      SEPARATELY so a gh failure fails the phase carrying gh's own message;
+ *  (f) the PR URL is the last line of the phase output.
+ *
+ * One deliberate change from the field version: NO gh account is baked into crew code (the
+ * overlay guarded a personal account). Instead, when the `GH_ACCOUNT` env var is set the script
+ * compares it against `gh api user -q .login` and runs
+ * `gh auth switch --hostname github.com --user "$GH_ACCOUNT"` only when they differ.
+ *
+ * Merge stays human: the phase opens the PR, never merges it.
+ *
+ * ## crew#317 — "pushed an empty branch and reported success"
+ *
+ * Run `d1bc72c2` (wicked-studio) delivered nothing while reporting `completed`. The persisted
+ * unit is the evidence, and it names the cause precisely. Its `tool_cmd` was NOT this script —
+ * it was the operator's hand-written `feature-pr` OVERLAY def, which begins `set -e` with **no
+ * `pipefail`**, so `gh pr create … | tail -1` reported `tail`'s status (0) and the phase passed
+ * with gh's error text where the PR URL belongs:
+ *
+ * ```text
+ * could not compute title or body defaults: could not find any commits between origin/main and
+ * wicked/d1bc72c2-…
+ * ```
+ *
+ * So the masking mechanism the issue hypothesised is real, but it belonged to the overlay, not
+ * here: `pipefail` IS in force for this executor (it is line 1 of this script, `bash -lc` runs it
+ * verbatim, and core's `run_tool_cmd` maps any non-zero exit to `StepStatus::Failed`). The three
+ * defects this script genuinely shared with the overlay are fixed below:
+ *
+ *  1. **No commit.** Agents write files and do not commit, so the pushed branch equalled the
+ *     default branch. The script now stages and commits the run's work itself, and REFUSES to
+ *     push when there is nothing to deliver.
+ *  2. **A masked result.** `| tail -1` discarded everything gh said except one line and made the
+ *     phase's verdict depend on a pipe option. gh's output and status are now captured
+ *     separately, and success is re-derived from a real PR URL rather than from an exit code.
+ *  3. **Ungoverned.** The phase shipped `verified_evidence: false` / `validator_pin: null`, so
+ *     nothing re-derived what it claimed. It now declares `verified_evidence: true` — see
+ *     {@link deliverPrPhase}.
+ */
+/** The id of the appended phase — also the collision probe when a def already delivers. */
+export const DELIVER_PHASE_ID = 'deliver';
+/** How much of the run's intent rides in the commit subject before it is truncated. */
+const INTENT_SUBJECT_CAP = 72;
+/**
+ * The run's intent, reduced to something safe to embed in a single-quoted shell assignment and
+ * to use as a one-line commit subject.
+ *
+ * The intent is caller-supplied free text off `POST /runs`, and it is being spliced into a bash
+ * script — so this is a containment boundary, not cosmetics. Control characters (newlines
+ * included) and the single quote are REMOVED: with no `'` left, the value cannot escape the
+ * single-quoted assignment the script wraps it in, and with no control characters it cannot add
+ * a line. Everything else (unicode, `$`, backticks, backslashes) is inert inside single quotes
+ * and is kept, so the subject still reads like the intent it came from.
+ */
+function commitSubjectIntent(intent) {
+    return (intent ?? '')
+        .replace(/[\u0000-\u001f\u007f]+/g, ' ')
+        .replace(/'/g, '')
+        .replace(/\s+/g, ' ')
+        .trim()
+        .slice(0, INTENT_SUBJECT_CAP)
+        .trim();
+}
+/**
+ * The hardened deliver script, run as `bash -lc <script>` (login shell so the operator's PATH —
+ * where `gh` lives — is loaded, same as the field overlay).
+ *
+ * `set -euo pipefail` is load-bearing and verified in force for this executor (crew#317): the
+ * engine spawns `bash -lc` with this text verbatim, and `run_tool_cmd` turns a non-zero exit into
+ * `StepStatus::Failed`. It is no longer the ONLY thing standing between a failed `gh` and a green
+ * phase, though — the gh result is captured explicitly and success is re-derived from evidence.
+ *
+ * `intent` (the run's problem statement) rides in the commit subject; it is sanitised by
+ * {@link commitSubjectIntent} before it is spliced in.
+ */
+export function deliverPrScript(intent) {
+    return [
+        'set -euo pipefail',
+        // The engine concatenates the child's stdout and THEN its stderr, so anything git writes to
+        // stderr would land after the PR URL and break "(f) the URL is the last line". Folding stderr
+        // into stdout for the whole phase keeps the output in true chronological order and makes the
+        // final `echo "$URL"` genuinely last.
+        'exec 2>&1',
+        // Account guard — env-driven, never a name baked into crew code. Unset ⇒ whatever account
+        // gh already holds is used as-is.
+        'if [ -n "${GH_ACCOUNT:-}" ]; then L=$(gh api user -q .login); [ "$L" = "$GH_ACCOUNT" ] || gh auth switch --hostname github.com --user "$GH_ACCOUNT"; fi',
+        // (a) The run branch: wicked/<worktree-basename> (the engine names run worktrees by run id),
+        // falling back to the currently checked-out branch when that ref does not exist.
+        'R=$(basename "$PWD")',
+        'B="wicked/$R"',
+        'git rev-parse --verify "$B" >/dev/null 2>&1 || B=$(git branch --show-current)',
+        // Derive origin's default branch FIRST — the refusal below must cover a repo whose
+        // default is trunk/develop/anything, not just main/master (Copilot on #303).
+        'git fetch origin',
+        'D=$(git symbolic-ref -q --short refs/remotes/origin/HEAD || echo origin/main)',
+        'DEF="${D#origin/}"',
+        // (b) Refuse the repo's own default branch (by derived name), the classic names, and an
+        // empty name (detached HEAD), which would otherwise turn the push into a garbage ref.
+        'case "$B" in ""|main|master|"$DEF") echo "deliver: refusing to push branch \'$B\' — the deliver phase only pushes run branches, never the default branch"; exit 1;; esac',
+        // The commit below writes to whatever HEAD is, while the push sends $B. When those differ
+        // (a `wicked/<run-id>` ref exists but is NOT what this worktree has checked out) committing
+        // would put one branch's work on another and push a branch that never saw it. Refuse instead.
+        'C=$(git branch --show-current)',
+        '[ "$C" = "$B" ] || { echo "deliver: the worktree is on \'$C\' but the run branch is \'$B\' — refusing to commit one branch\'s work onto another; nothing was pushed"; exit 1; }',
+        // (c1) COMMIT THE RUN'S WORK (crew#317). Agents write files; they do not commit — which is
+        // the premise of core#291 and the reason `d1bc72c2` pushed a branch identical to origin/main.
+        // Author identity is deliberately NOT set here: the run worktree belongs to the operator's
+        // own clone, so `git commit` uses the repo/user config that already exists (and fails loudly,
+        // pushing nothing, if that config is missing). `git add -A` respects .gitignore.
+        `I='${commitSubjectIntent(intent)}'`,
+        'if [ -n "$I" ]; then M="wicked-crew run $R: $I"; else M="wicked-crew run $R"; fi',
+        'git add -A',
+        // Only commit when something is staged — a run that committed incrementally (core#280's
+        // liveness contract) leaves a clean tree and must not gain an empty commit here.
+        'git diff --cached --quiet || git commit -q -m "$M"',
+        // (c2) NOTHING TO DELIVER — no staged work AND no commits of its own. Fail LOUDLY before the
+        // remote is touched: an empty ref pushed under a run id is worse than a failed phase.
+        'A=$(git rev-list --count "$D..$B")',
+        '[ "$A" -ge 1 ] || { echo "deliver: nothing to deliver — the run produced no committed change ($B is not ahead of $D); nothing was pushed"; exit 1; }',
+        // (c3) Rebase onto origin's default branch so the PR opens mergeable. A conflict must fail
+        // the phase VISIBLY with nothing pushed — the abort leaves the worktree on the pre-rebase
+        // branch tip instead of mid-rebase.
+        'git rebase "$D" "$B" || { git rebase --abort >/dev/null 2>&1 || true; echo "deliver: rebase of $B onto $D failed (conflicts) — resolve on the branch and re-run; nothing was pushed"; exit 1; }',
+        // Re-derive after the rebase: it drops commits already upstream (patch-id equal), so a branch
+        // that WAS ahead can come out of a rebase carrying nothing of its own.
+        'A=$(git rev-list --count "$D..$B")',
+        '[ "$A" -ge 1 ] || { echo "deliver: nothing to deliver — the run produced no committed change (after rebasing onto $D, $B carries no commit of its own); nothing was pushed"; exit 1; }',
+        // (d) Push.
+        'git push -u origin "$B"',
+        // (e) Open the PR with gh's OUTPUT and EXIT STATUS captured separately (crew#317). The old
+        // `| tail -1` threw away everything gh said but one line and made the phase's verdict a
+        // property of a shell option; a gh failure now fails the phase carrying gh's own message.
+        'if ! OUT=$(gh pr create --head "$B" --fill 2>&1); then echo "$OUT"; echo "deliver: gh pr create failed for $B — no PR was opened"; exit 1; fi',
+        'echo "$OUT"',
+        // (f) DONE IS RE-DERIVED, NOT ASSERTED — twice, from two independent facts, before the phase
+        // is allowed to report a delivery:
+        //   1. gh actually produced a PR URL (an exit code alone is a claim, not evidence);
+        //   2. the ref ON THE REMOTE is ahead of origin's default branch by at least one commit.
+        "URL=$(printf '%s\\n' \"$OUT\" | grep -Eo 'https://[^[:space:]]+/pull/[0-9]+' | tail -1 || true)",
+        '[ -n "$URL" ] || { echo "deliver: gh pr create exited 0 but produced no PR URL for $B — refusing to report a delivery nothing can be pointed at"; exit 1; }',
+        'P=$(git rev-list --count "$D..origin/$B")',
+        '[ "$P" -ge 1 ] || { echo "deliver: $B is not ahead of $D on the remote after the push — refusing to report a delivery with no commits"; exit 1; }',
+        'echo "$URL"',
+    ].join('\n');
+}
+/**
+ * The deliver phase definition — the PhaseDef JSON shape core accepts, fully spelled out so the
+ * composed def round-trips through `registerWorkflow` (core's serde) and crew's own `WorkflowDef`
+ * type without casts. `gate: 'auto'` + `executes_code: false`: the phase is deterministic tooling,
+ * not governed agent work — its failure surface is the exit code + output, which core reports as
+ * a failed unit.
+ *
+ * ## Why `verified_evidence: true` and `validator_pin: null` (crew#317)
+ *
+ * The phase that touches the remote was the one phase nothing re-derived. The engine's phase model
+ * DOES let a Tool-executor phase carry a deterministic floor, and the mechanism is the flag rather
+ * than a pin crew mints itself:
+ *
+ *  - a pin is a CONTENT ADDRESS into core's validator vault, and `attach_pinned_validators` is
+ *    fail-closed on one that does not resolve — it BAILS the run at plan time. Authoring and
+ *    approving a validator is `wicked-core provision-validator` + `approve-validator`, neither of
+ *    which is exposed through the napi surface crew drives, so a pin invented here would fail
+ *    every run of every deliver-composed workflow on a machine that had not been seeded by hand;
+ *  - `verified_evidence: true` with no pin of its own is armed AT REGISTRATION by
+ *    `enforce_verified_evidence` with the built-in evidence floor (`EVIDENCE_FLOOR_PIN`,
+ *    criterion: "the run left a change in its worktree (done is re-derived from the diff, never
+ *    asserted)"), which `pre_distribute` seeds on the plan path so it always resolves. Same
+ *    mechanism `feature/test`, `bug/verify` and `migration/verify` reach it by.
+ *
+ * The floor then re-runs against the run's worktree at the gate, INDEPENDENTLY of anything this
+ * script printed, and denies the phase when the run left no change. Layer 2 (the agent judge)
+ * stays out of it: core hands the Tool path `agent_verdict: None`, so a tool phase's floor is
+ * deterministic and costs no LLM call. The PR-URL and branch-ahead assertions stay in the script
+ * because no vaulted floor can see the remote.
+ */
+export function deliverPrPhase(dependsOn = [], intent) {
+    return {
+        id: DELIVER_PHASE_ID,
+        kind: 'build',
+        executor: { type: 'tool', cmd: ['bash', '-lc', deliverPrScript(intent)] },
+        gate_type: null,
+        gate: 'auto',
+        executes_code: false,
+        verified_evidence: true,
+        required_deliverables: [],
+        depends_on: dependsOn,
+        role: 'neutral',
+        skill_ref: null,
+        allowed_skills: [],
+        validator_pin: null,
+    };
+}
+/**
+ * Compose a PER-RUN workflow def: `base`'s phases (untouched — the shared def is never mutated)
+ * plus the deliver phase appended last, under a run-scoped id. The caller registers the result
+ * with the engine for THIS run only; nothing is written to the overlay dir and the composed id
+ * never enters the user-workflow registry, so the catalog (`GET /workflows`) stays clean.
+ *
+ * `intent` is the run's problem statement — it names WHAT was delivered in the commit subject
+ * (`wicked-crew run <run-id>: <intent>`); omit it and the subject carries the run id alone.
+ *
+ * Throws when `base` already carries a `deliver` phase — appending a second phase with the same
+ * id would be ambiguous at best; the caller launches such a def as-is instead (see
+ * `CoreAdapter.launchRun`).
+ */
+export function composeDeliverWorkflow(base, runId, intent) {
+    if (base.phases.some((p) => p.id === DELIVER_PHASE_ID)) {
+        throw new Error(`workflow '${base.id}' already has a '${DELIVER_PHASE_ID}' phase — launch it without deliver: "pr"`);
+    }
+    const last = base.phases[base.phases.length - 1];
+    // Run ids are UUIDs from the route, but the CLI path accepts caller-supplied ids — keep the
+    // composed id inside the same safe charset `registerWorkflow` enforces for user defs.
+    const safeRunId = runId.replace(/[^a-zA-Z0-9._-]/g, '_');
+    // registerWorkflow enforces id.length <= 128; a caller-supplied CLI session id can be long.
+    // Truncate the run-id TAIL, keeping the base+marker prefix intact (Copilot on #303).
+    const composedId = `${base.id}-deliver-${safeRunId}`.slice(0, 128);
+    return {
+        // No `is_system` on purpose: core's overlay/register schema rejects unknown fields, and the
+        // composed def is engine-input, not catalog data.
+        id: composedId,
+        phases: [...base.phases, deliverPrPhase(last !== undefined ? [last.id] : [], intent)],
+    };
+}
+//# sourceMappingURL=deliver.js.map

package/dist/core/deliver.js.map

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

package/dist/core/deliverable-floor.d.ts

@@ -0,0 +1,155 @@
+/**
+ * THE DELIVERABLE FLOOR (crew#311) — "done" is re-derived from the artifact, never asserted.
+ *
+ * ## The defect
+ *
+ * A governed unit that produced NOTHING still passed its execution gate on the strength of a
+ * prose reply. The engine's only universal floor is the SUBSTANCE floor
+ * (wicked-core `actor.rs`, "phase produced no reviewable substance"): a governed
+ * Creator/Neutral unit is rejected only when its output carries BOTH under 200 trimmed chars
+ * of prose AND no worktree change. So ~200 characters of narration — "I'll read the design
+ * spec, let me check the API types…" — clears it, with no file anywhere. Prose length stood in
+ * for evidence.
+ *
+ * The engine has two real evidence instruments, and neither reaches a run of this shape:
+ *
+ *  1. `validator_pin` → the built-in EVIDENCE floor (`builtin_floors::EVIDENCE_FLOOR_PIN`,
+ *     criterion "the run left a change in its worktree (done is re-derived from the diff, never
+ *     asserted)"). It re-verifies a git DIFF, and is fail-closed on a run with no worktree — so
+ *     an UNBOUND run (`repoRef` omitted, `workdir: null`) can never satisfy it. Every crew
+ *     interactive seam launches unbound on purpose (wicked-core#293/#294), and their deliverable
+ *     is a FILE in a declared write root, invisible to a diff.
+ *  2. `required_deliverables` → enforced by wicked-core as of FINDING-101, but only in the
+ *     WRAPPED-CLI runner (`execute_wrapped.rs`), only against the unit's own cwd, and any
+ *     absolute or `..`-escaping path is counted MISSING by construction. The ACP runner — the
+ *     path a real seat takes — never consults it. So for a run whose deliverable is an absolute
+ *     path under `extraWriteRoots`, declaring it there would fail every run on one runner and
+ *     check nothing on the other. That gap is wicked-core's to close
+ *     (wicked-core#297, items 1 and 3); once it is, this phase can retire in favour of the
+ *     engine field. Crew must not paper over it meanwhile by declaring something unverifiable.
+ *
+ * ## What this module does
+ *
+ * It gives crew the instrument it can honestly own: a deterministic TOOL phase, appended to a
+ * PER-RUN copy of the workflow def (the exact mechanism `core/deliver.ts` proved for
+ * `deliver: "pr"` — the shared def is never mutated, nothing lands in the overlay dir, the
+ * catalog never grows a per-run entry), which asserts that the artifacts the launcher declared
+ * EXIST, are non-empty, and were written by THIS run (crew#320 — existence alone re-derives
+ * nothing at a path a prior run already populated). A Tool phase's failure surface is its exit
+ * code: wicked-core's
+ * `run_tool_cmd` maps a non-zero exit to `StepStatus::Failed`, which fails the unit and the run
+ * through the unchanged completion path. No LLM, no worktree, no judgement about the content —
+ * only "the phase promised this file; is it there".
+ *
+ * That is deliberately a FLOOR and not a review, in exactly the sense `builtin_floors` documents:
+ * it proves an artifact exists. It says nothing about whether the artifact is correct, or even
+ * related to the task. What it removes is the failure mode crew#311 recorded — a unit whose
+ * `Write` was policy-denied, which therefore produced no file at all, reporting done.
+ *
+ * ## The report
+ *
+ * The script prints what was EXPECTED and what was FOUND before it exits, on both branches, so
+ * the failure is legible from the unit output alone: which paths were declared, which exist
+ * (with their size), and which are missing and why (absent / empty file / empty directory).
+ * An operator reading a failed run must never have to guess what the phase was supposed to
+ * produce.
+ */
+import type { PhaseDef, WorkflowDef } from './types.js';
+/** The id of the appended floor phase — also the collision probe when a def already carries one. */
+export declare const DELIVERABLE_FLOOR_PHASE_ID = "verify-deliverables";
+/** The marker line the failing branch prints. Asserted by tests and greppable in a unit output. */
+export declare const DELIVERABLE_FLOOR_FAILURE_MARKER = "[wicked-crew] DELIVERABLE FLOOR FAILED";
+/**
+ * Slack allowed on the freshness comparison, in milliseconds (crew#320).
+ *
+ * The launch timestamp comes from the daemon's `Date.now()` (millisecond resolution); the
+ * artifact timestamp comes from the FILESYSTEM, and not every filesystem keeps milliseconds —
+ * HFS+ and ext3 truncate mtime to whole seconds, and some SMB/NFS mounts are coarser still. A
+ * file genuinely written 400 ms after a launch at `…:07.600Z` can therefore report an mtime of
+ * `…:07.000Z` and read as older than the launch that produced it.
+ *
+ * One second absorbs that truncation without weakening the check this exists to make: the stale
+ * artifact crew#320 describes is the PREVIOUS run's output, which predates this run's launch by
+ * that run's whole remaining lifetime plus the turnaround before the next one — orders of
+ * magnitude more than a timestamp-granularity rounding error.
+ */
+export declare const DELIVERABLE_FLOOR_MTIME_SLACK_MS = 1000;
+/**
+ * The floor program, run as `node -e <script> <launchedAtMs> <path...>`.
+ *
+ * Node rather than a shell: this must work identically on macOS, Linux, and Windows, and the
+ * daemon already IS node, so `process.execPath` is a guaranteed-present absolute interpreter
+ * (see {@link deliverableFloorPhase}). `-e` runs CommonJS, so `require` is available; the launch
+ * timestamp and the declared paths arrive as `process.argv.slice(1)`, passed as argv rather than
+ * interpolated into a shell string so a path containing a space, a quote, or a `$` cannot be
+ * re-parsed.
+ *
+ * A path counts as PRODUCED when it exists, carries bytes, and was written by THIS RUN:
+ *
+ *  - a non-empty file whose `mtimeMs` is at or after the launch timestamp;
+ *  - a directory holding at least one direct entry whose `mtimeMs` is at or after it (a phase may
+ *    declare a directory of outputs; the directory's own mtime is not enough, because a directory
+ *    left over from a prior run keeps its entries and its mtime).
+ *
+ * A zero-byte file is NOT evidence — it is the same "nothing was produced" this exists to catch,
+ * and the draft/chat seams already treated an empty deliverable as a failure at their own
+ * post-hoc check.
+ *
+ * ## Why the timestamp (crew#320)
+ *
+ * Existence alone re-derives nothing when the path can be pre-populated. The interactive seams
+ * copy their deliverable to `outPath` and never remove it, and demo/draft/edit run directories
+ * are keyed by DOCUMENT ID (edit by `doc:version`) — so a second run over the same key starts
+ * with the previous run's file already sitting at the declared path. The floor would find it,
+ * find bytes, and pass: the artifact exists, but this run did not produce it. "Done" would be
+ * asserted by a leftover rather than derived from this run's work — the exact failure shape one
+ * level in from the one crew#311 closed.
+ *
+ * The comparison is the stronger of the two available fixes. Clearing `outPath` at launch would
+ * also work, but only for as long as every seam remembers to clear it; the mtime check survives
+ * a seam that forgets, and it survives a seam that has not been written yet.
+ *
+ * A launch timestamp that does not parse FAILS CLOSED. An armed floor that cannot judge freshness
+ * is not a floor, and passing on the grounds that the check itself is broken is precisely the
+ * "assert done" move this module exists to refuse.
+ */
+export declare function deliverableFloorScript(): string;
+/**
+ * The floor PhaseDef for `paths`, judged against `launchedAtMs`.
+ *
+ * `launchedAtMs` is positional and required rather than defaulted (crew#320): a default would let
+ * a new caller arm a floor that checks existence only, and the resulting run would report done on
+ * a leftover with nothing in its output saying the freshness half was never applied. The compiler
+ * asking the question is the point.
+ *
+ * `cmd[0]` is `process.execPath` — the ABSOLUTE path of the node binary already running the
+ * daemon — not the bare name `node`. wicked-core preflights every Tool phase at launch
+ * (`workflow::preflight_tool_phases`) and REFUSES to start a run whose tool binary does not
+ * resolve; a bare `node` resolves only if the engine's PATH happens to carry one, which is
+ * exactly the kind of environment-dependent gate that fails in production and passes in tests.
+ * The composed def is per-run and hot-registered only, so baking a machine-local path into it
+ * costs nothing: it never reaches the catalog or the overlay dir.
+ *
+ * `role: 'neutral'` + `executes_code: false` + `governed`-free Tool dispatch: this phase is
+ * deterministic tooling, so the substance floor, the agent judge, and the input-governance fold
+ * do not apply to it — its verdict IS its exit code.
+ */
+export declare function deliverableFloorPhase(paths: readonly string[], launchedAtMs: number, dependsOn?: string[]): PhaseDef;
+/**
+ * Compose a PER-RUN def: `base`'s phases (untouched — the shared def is never mutated) plus the
+ * deliverable floor appended last, under a run-scoped id. Mirrors `composeDeliverWorkflow`'s
+ * contract exactly, including the id charset/length rules `registerWorkflow` enforces and the
+ * deliberate absence of `is_system` (core's register schema rejects unknown fields on this path,
+ * and a composed def is engine input, not catalog data).
+ *
+ * Throws on an empty `paths` list — a floor over nothing would pass vacuously, which is the
+ * defect, not the fix. Throws on a def that already carries the floor phase, for the same
+ * ambiguity reason `composeDeliverWorkflow` does.
+ *
+ * `launchedAtMs` defaults to composition time, which is the correct instant on every path that
+ * exists: composition is the last thing that happens before `core.launchRun`, so nothing this run
+ * produces can predate it, and a nonsense value is rejected here rather than being discovered by
+ * the tool phase minutes later (crew#320).
+ */
+export declare function composeDeliverableFloor(base: WorkflowDef, runId: string, paths: readonly string[], launchedAtMs?: number): WorkflowDef;
+//# sourceMappingURL=deliverable-floor.d.ts.map

package/dist/core/deliverable-floor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deliverable-floor.d.ts","sourceRoot":"","sources":["../../src/core/deliverable-floor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAExD,oGAAoG;AACpG,eAAO,MAAM,0BAA0B,wBAAwB,CAAC;AAEhE,mGAAmG;AACnG,eAAO,MAAM,gCAAgC,2CACH,CAAC;AAE3C;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,gCAAgC,OAAQ,CAAC;AAEtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,CAuC/C;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,YAAY,EAAE,MAAM,EACpB,SAAS,GAAE,MAAM,EAAO,GACvB,QAAQ,CA4BV;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,WAAW,EACjB,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,YAAY,GAAE,MAAmB,GAChC,WAAW,CAiCb"}