lastlight-shared 0.4.0 → 0.6.0

package/dist/config-types.d.ts

@@ -132,13 +132,290 @@ export declare function isReviewTrigger(value: unknown): value is ReviewTrigger;
 /** Position of a trigger mode on the automation scale. */
 export declare function reviewTriggerRank(trigger: ReviewTrigger): number;
 /**
- * The `review:` block. Every key is repo-settable, and every one is CLAMPED
- * towards less automation: `postsCheck` and `skipDraft` are add-only `true` (a
- * repo may ask for the check and may skip drafts; it may not suppress an
- * operator's check or force reviews onto drafts), `trigger` takes the lower
- * {@link reviewTriggerRank} of repo and operator, `generatedPaths` is
- * superset-only (a longer list suppresses MORE re-reviews), and `requestLabel`
- * is free — naming a label only ever adds an explicit, human-initiated route.
+ * The `review.analysis:` sub-block — the evidence pipeline
+ * (`docs/plans/deterministic-pr-levers.md`).
+ *
+ * **OFF by default, and that is a locked decision** (README locked decision 8):
+ * `enabled: false` must reproduce today's two-phase review byte-for-byte, so
+ * every projection this block governs is *absent* from the template context
+ * rather than present-and-empty. Each stage lands dark and is switched on per
+ * deployment once it has been measured.
+ *
+ * **Operator-only, unlike every other `review:` leaf.** It buys analysis on the
+ * operator's budget, which is the same argument that made `review.trigger`
+ * clamped rather than free (#256) — except there is no "more conservative"
+ * direction here to clamp towards, so a repo asking for it answers
+ * `key-not-allowed` exactly as `fix.escalateModelAfterAttempt` does.
+ */
+export interface ReviewAnalysisConfig {
+    /** `false` ⇒ today's two-phase review, byte-for-byte. */
+    enabled: boolean;
+    /**
+     * How many `spec` obligations one PR may carry.
+     *
+     * A **safety bound**, not a budget — it should never bind on a real PR. The
+     * extractor still ranks, truncates, and records in the rendered block how
+     * many it dropped (a silently truncated list is the failure locked decision 6
+     * exists to prevent); this number exists only to stop a pathological PR
+     * blowing the prompt.
+     *
+     * It shipped at 6, which was inert while the spec axis produced nothing. The
+     * moment the axis started working it bound on FIVE of the six linked cases in
+     * the gate set, discarding acceptance criteria a human wrote on the issue —
+     * the most direct statement of intent this pipeline ever gets. Capping
+     * GENERATION also inverts locked decision 2: we over-generate deliberately and
+     * let the probe oracle and WP6b's attention boundary narrow. Truncating
+     * obligations truncates DISCOVERY, which is the measured ceiling.
+     */
+    maxSpecObligations: number;
+    /**
+     * A TOTAL BACKSTOP over the **facts-derived** obligations one PR may carry,
+     * across all five families `lastlight-facts seed` produces (`contract`,
+     * `enforcement`, `security`, `state`, `tests`). The `spec` family has its own
+     * bound above, because it is built harness-side from the issue text and
+     * shares no ranking axis with these.
+     *
+     * **Truncation is per FAMILY, not here.** The seeder caps each family at its
+     * own ceiling — `contract` 12, `enforcement` 12, `state` 8, `security` 8,
+     * `tests` 8 (`FAMILY_CAPS` in `packages/code-facts/src/seed.ts`) — because
+     * each family's obligations feed exactly ONE survey branch, so the cost is
+     * per branch rather than per document, and cross-family ranking prices
+     * incommensurable mechanism classes against each other. Measured: `contract`
+     * minted 89 across the eight gate cases while `security` minted 3, and the
+     * pooled budget went to `contract`.
+     *
+     * This number is applied AFTER those ceilings and defaults to their sum, so
+     * it cannot bind on a shipped configuration — it is there so that raising one
+     * ceiling is a bounded act. What it drops is counted in `obligations.json`
+     * with the reason (naming the ceiling or the backstop), never silently.
+     */
+    maxObligations: number;
+    /**
+     * Which obligation BLOCK the six survey families are handed — the CONTROL for
+     * 2026-08-23, and the only key in this block that exists to make a result
+     * readable rather than to buy compute.
+     *
+     * `full` (the default) is that day's block: a mandatory discharge contract
+     * with a `discharge` field to record a code in, an un-truncated id checklist,
+     * and one worked exemplar. It moved discharge compliance 0/33 → 33/33 on
+     * `prreview__skillspro-1587-r2` — and moved the union of matched gold
+     * **4-of-5 → 0-of-5**, over three repeats, with half to two thirds of every
+     * hypothesis becoming a clean quote (`QUOTE`, `failureScenario: null`).
+     *
+     * Two variables changed in the same commit, so the run cannot say which:
+     * whether the obligations ask the WRONG QUESTION and making a wrong question
+     * mandatory turns hunting into checklist-clearing, or whether RELIABLE SEEDING
+     * itself suppresses discovery (the same commit stopped ~24% of survey branches
+     * losing their seed entirely). `minimal` renders the pre-2026-08-23 block —
+     * same obligations, delivered just as reliably, asking the old question — so
+     * one arm separates them.
+     *
+     * It reaches the five facts-derived families as `lastlight-facts seed
+     * --contract`, is stamped into `obligations.json`, and the `spec` family reads
+     * it directly (`renderSpecObligations`) because it is rendered harness-side.
+     * **`lastlight-facts discharge` degrades to its `test -s` floor under
+     * `minimal`**: measured compliance under that block was 0/31, 0/34 and 0/40,
+     * so a gate demanding a code the block never asked for would fail every family
+     * of every run.
+     */
+    obligationContract: "full" | "minimal";
+    /**
+     * Which D2 minting arms `lastlight-facts seed` runs, as a comma-list over
+     * `all-in-diff` (contract obligations for symbols whose every reference is
+     * inside the diff) and `registrations` (security obligations for route/hook
+     * registration order).
+     *
+     * BOTH ON by default — the measured shipped shape (8-case confirm: internal
+     * paired +10/−1, p=0.006, the only lever measured to GROW the recall union
+     * rather than rotate it; external validation +7/−0, p=0.008). `""` is
+     * NEITHER — the pre-D2 baseline set, byte-identical to a run before the
+     * toggle existed. Reaches the seeder as `--mint <spec>`
+     * on the seed phase's command line, appended ONLY when non-empty, and the
+     * seeder stamps what it was asked into `obligations.json` (`minting`) so an
+     * artifact answers "which arm produced this". Kept a plain string rather
+     * than a validated union because the CLI is the loud gate: any unknown token
+     * exits 2 before the document is read — a typo'd arm can never silently run
+     * baseline and report a number for an experiment that never happened.
+     */
+    mint: string;
+    /**
+     * How many of the six survey families actually run.
+     *
+     * **Six, and the default is not negotiable down without saying which.** The
+     * previous design defaulted this to 3 against six families and never recorded
+     * which three ran — so half the families silently never executed, and
+     * `enforcement`, the one that produced the only gold match, could have been
+     * among them (§D4). A value below 6 takes the families in the seeder's rank
+     * order and the run says so in its artifact.
+     */
+    surveyPasses: number;
+    /**
+     * How many survey families run CONCURRENTLY (WP11c).
+     *
+     * A CEILING, not a guarantee: the run clamps it to what the active sandbox
+     * backend can actually hold. `none` and `docker` take the declared value;
+     * `gondolin` boots a QEMU micro-VM per agent session inside the harness
+     * process and pins to 1, as do `smol` and `kubernetes` until measured. So on
+     * a stock deployment (gondolin) this key changes nothing at all today.
+     *
+     * Six by default because six is what the fan-out exists for. The six families
+     * write six disjoint append-only files and never read each other's, so there
+     * was never an ordering constraint between them — only a scheduler that ran
+     * one DAG node at a time. Chained, they were 851s of a 29-minute review (49%
+     * of the wall clock); concurrent, they are the slowest single family.
+     *
+     * Lower it to bound provider rate-limit pressure or memory, not to bound
+     * spend: the six passes cost the same in tokens either way.
+     */
+    surveyConcurrency: number;
+    /**
+     * WP4 — the `prepare` + `falsify` pair: install dependencies so a probe can be
+     * **run**, then write probes and run them.
+     *
+     * A second switch under an already-gated block, deliberately. `prepare` is the
+     * phase that decides whether the review workspace has a `node_modules`, and
+     * that one fact changes three things at once: it is what makes a
+     * package-extending `tsconfig` resolve (so `contract` can seed at all on a
+     * normal monorepo), it is the only route to a coverage artifact (so `tests`
+     * can), and it re-arms the memory profile of a *different* phase. Bundling it
+     * into `enabled` would have made "run the surveys" and "install the PR
+     * author's dependencies" the same decision.
+     *
+     * `false` reproduces WP3 exactly. Default posture is **off in production, on
+     * in the eval overlay** — the ablation rung is what decides whether it ships
+     * on, and that is a number, not a judgement call.
+     */
+    probes: boolean;
+    /**
+     * Let `prepare`'s install run the tree's own lifecycle scripts.
+     *
+     * **Off, and it is a security default rather than a performance one.** The
+     * install runs against a PULL REQUEST HEAD, so a `postinstall` there is code
+     * the PR author wrote executing on the operator's infrastructure — and
+     * `pr-review`'s workspace has never installed anything, which makes `prepare`
+     * the first thing in the workflow that could. What `prepare` is FOR (making an
+     * `extends` resolve, putting library source on disk to be read) needs the
+     * files, not their scripts.
+     *
+     * Turning it on is legitimate for a repo whose install genuinely does not work
+     * without them; it is not the default for the same reason `probes` is not.
+     */
+    probeLifecycleScripts: boolean;
+    /**
+     * Run the repo's own `tsc --noEmit` in `prepare` and record the diagnostics.
+     *
+     * Cheap, independent of the other two, and **not** a CI re-run: CI reports a
+     * pass/fail summary over a matrix, this reports a per-file, per-line
+     * diagnostic that can be attached to a specific hypothesis (locked decision
+     * 11 — we never re-derive what `checksState` already said).
+     */
+    probeTypecheck: boolean;
+    /**
+     * Run a coverage command in `prepare` so the `tests` obligation family has an
+     * input for the first time.
+     *
+     * **The one step in this pipeline that runs a test suite**, which is the
+     * wall-clock item §D13 deleted along with `mutants` and `suite`. It is a
+     * separate switch because it is a separate price: everything else in `prepare`
+     * is seconds and this is minutes. It never guesses a command — only one the
+     * repo itself named (a `coverage` / `test:coverage` script) — because a
+     * guessed fifteen-minute run that produced nothing makes "no command" and "no
+     * artifact" the same row in the funnel.
+     */
+    probeCoverage: boolean;
+    /** Ceiling on `prepare`'s dependency install, in seconds. */
+    prepareTimeoutSeconds: number;
+    /** Ceiling on `prepare`'s coverage run, in seconds. Minutes, not seconds. */
+    coverageTimeoutSeconds: number;
+    /**
+     * How many rounds `falsify` gets to write and run probes.
+     *
+     * Two. v3's lesson 3 is the sizing argument: the loop's exit condition is a
+     * five-line existence gate, not a validator — v2's full quote validator was
+     * overkill and cost 2.4× for a worse result.
+     */
+    probeRounds: number;
+    /**
+     * The inline-comment attention budget (WP6b).
+     *
+     * Preserving internal recall and spending a human's attention are two
+     * different budgets, and conflating them is how a recall-first reviewer
+     * becomes unreadable. Everything past this rank goes to the review BODY —
+     * still posted, still visible, just not an inline comment. Nothing is dropped.
+     *
+     * Ten, on the evidence in *"Does AI Code Review Lead to Code Changes?"*
+     * (22k+ real review comments): concise, hunk-level, actionable findings are
+     * substantially likelier to lead to a change, and the wall the paper warns
+     * about is TWENTY — twenty inline comments is not twice the signal of ten,
+     * it is a muted bot. Ten is a ceiling, not a budget that bites: measured
+     * inline volume is 1–5 per PR, so this has never bound, and anything past it
+     * goes to the body rather than away.
+     */
+    maxInlineComments: number;
+    /**
+     * Per-obligation-family confidence bar for an INLINE comment. Below the bar a
+     * finding goes to the body; it is never deleted.
+     *
+     * **Per-family, not global, and that is a measured choice.** AutoCommenter
+     * (Google Critique) found a global threshold catastrophic — at `t = 0.98`,
+     * ~80% of below-threshold predictions were still correct — while per-URL
+     * thresholds raised recall without hurting precision.
+     *
+     * **These numbers are initial guesses to be tuned on the train split, not
+     * measurements.** Record each retune in the eval journal.
+     */
+    thresholds: Record<string, number>;
+    /**
+     * Below this confidence a finding is recorded but not posted at all.
+     *
+     * The one tier that costs recall, so it is deliberately low and deliberately
+     * auditable. A finding carrying NO confidence is never affected — see
+     * `tierFindings`; treating an absent field as zero would silently delete every
+     * finding from any prompt that has not been taught to self-score.
+     */
+    internalFloor: number;
+    /**
+     * Cap on findings rendered into the review BODY (the "Additional findings"
+     * section) — the body-side sibling of `maxInlineComments`, and the one
+     * budget that DOES filter: everything past it is recorded `internal` with
+     * the machine reason `body-budget` in `disposition.json`, never posted.
+     * Nothing is deleted — the demotion stays auditable like every other
+     * `internal` entry.
+     *
+     * - `null` — unlimited: the legacy funnel, where everything demoted from
+     *   inline lands in the body.
+     * - `0` — no overflow at all: nothing tiers to body; anything that would
+     *   have gone there is recorded `internal` instead.
+     * - `N > 0` — at most N body findings, ranked by severity × confidence
+     *   exactly as the inline overflow ranks (an absent confidence ranks as
+     *   1.0, so an unscored document degenerates to severity order).
+     *
+     * **`5` is the shipped default, and the number it replaced is the reason.**
+     * `0` was measured rather than assumed: under the production
+     * Sonnet-adjudicator shape no-overflow keeps 29/36 matched gold and lifts
+     * precision 0.263 → 0.492 / F1 0.362 → 0.479 on the Martian external set.
+     * But the same $0 sweep showed that result is
+     * **adjudicator-shape-conditional** — under Haiku-everywhere the body tier
+     * carries most of the matched gold and cap 0 costs posted recall 0.42 →
+     * 0.12, while MID caps keep nearly all of it (skillspro cap 4: 0.300, cap 8:
+     * 0.380 against 0.420 unlimited; Martian cap 4: 0.548, cap 8: 0.581 against
+     * 0.581 unlimited, at slightly better precision). `5` is the
+     * recall-preserving compromise pending a real boundary tune, not a measured
+     * optimum — which is also why eval overlays keep pinning this key
+     * explicitly instead of inheriting whatever it currently is.
+     */
+    maxBodyComments: number | null;
+}
+/**
+ * The `review:` block. Every key except `analysis` is repo-settable, and every
+ * one of those is CLAMPED towards less automation: `postsCheck` and `skipDraft`
+ * are add-only `true` (a repo may ask for the check and may skip drafts; it may
+ * not suppress an operator's check or force reviews onto drafts), `trigger`
+ * takes the lower {@link reviewTriggerRank} of repo and operator,
+ * `generatedPaths` is superset-only (a longer list suppresses MORE
+ * re-reviews), and `requestLabel` is free — naming a label only ever adds an
+ * explicit, human-initiated route. {@link ReviewAnalysisConfig} is
+ * operator-only; see its own doc.
  */
 export interface ReviewConfig {
     /** Post the `last-light/review` Check Run. */
@@ -168,6 +445,8 @@ export interface ReviewConfig {
      * that also touched a hand-written file — see `resolveReviewTrigger`.
      */
     generatedPaths: string[];
+    /** The evidence pipeline. Off by default — see {@link ReviewAnalysisConfig}. */
+    analysis: ReviewAnalysisConfig;
 }
 /**
  * Where a repo's outbound notifications go — today, the weekly Slack digest.

package/dist/config-types.js

@@ -141,6 +141,52 @@ export function defaultReviewConfig() {
             "*.generated.*",
             "**/__generated__/**",
         ],
+        analysis: {
+            enabled: false,
+            // A safety bound, not a budget — see config/default.yaml for why this is
+            // 40 rather than the 6 it shipped with. It must not bind on a real PR:
+            // capping generation truncates discovery, which is the measured ceiling.
+            maxSpecObligations: 40,
+            // The TOTAL backstop, and it is the per-family ceilings' sum
+            // (12 + 12 + 8 + 8 + 8) so it cannot bind unless an operator raises one.
+            maxObligations: 48,
+            // `minimal` ships, measured in: under `full`, half to two-thirds of
+            // survey output arrives as clean-quote verification reports that reached
+            // real PRs as posted findings; under `minimal` the same recall union
+            // posts with 37–71% better SNR and half the run-to-run variance. `full`
+            // remains the opt-in telemetry arm (discharge codes + the
+            // clean-discharge demotion at the posting boundary).
+            obligationContract: "minimal",
+            // Both D2 rules — the measured shipped shape. See the field's doc.
+            mint: "all-in-diff,registrations",
+            surveyPasses: 6,
+            surveyConcurrency: 6,
+            probes: false,
+            probeLifecycleScripts: false,
+            probeTypecheck: false,
+            probeCoverage: false,
+            prepareTimeoutSeconds: 300,
+            coverageTimeoutSeconds: 900,
+            probeRounds: 2,
+            maxInlineComments: 10,
+            thresholds: {
+                contract: 0.35,
+                enforcement: 0.35,
+                security: 0.3,
+                state: 0.5,
+                tests: 0.6,
+                spec: 0.45,
+            },
+            internalFloor: 0.15,
+            // A bounded body overflow. Cap 0 measured better under the production
+            // Sonnet adjudicator (precision 0.263→0.492 / F1 0.362→0.479) but that
+            // win is adjudicator-shape-conditional — under Haiku-everywhere the body
+            // tier carries most of the matched gold (posted recall 0.42→0.12 at 0),
+            // and mid caps kept nearly all of it. 5 is the recall-preserving
+            // compromise; `null` restores the legacy unlimited funnel. See the
+            // field's doc.
+            maxBodyComments: 5,
+        },
     };
 }
 //# sourceMappingURL=config-types.js.map

package/dist/config-types.js.map

@@ -1 +1 @@
-{"version":3,"file":"config-types.js","sourceRoot":"","sources":["../src/config-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAeH,8EAA8E;AAC9E,qDAAqD;AACrD,8EAA8E;AAE9E;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,cAAc;IACd,cAAc;IACd,OAAO;IACP,iBAAiB;IACjB,iBAAiB;CACT,CAAC;AAIX,6DAA6D;AAC7D,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAC7C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAK,iBAAuC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAC/F,CAAC;AAiDD,qFAAqF;AACrF,MAAM,UAAU,gBAAgB;IAC9B,OAAO;QACL,WAAW,EAAE,CAAC;QACd,eAAe,EAAE,CAAC;QAClB,kBAAkB,EAAE,GAAG;QACvB,yBAAyB,EAAE,CAAC;QAC5B,UAAU,EAAE,GAAG;QACf,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,CAAC,cAAc,EAAE,cAAc,CAAC;KACnD,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,4DAA4D;AAC5D,8EAA8E;AAE9E,wEAAwE;AACxE,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,CAAU,CAAC;AAInF,oEAAoE;AACpE,MAAM,UAAU,kBAAkB,CAAC,KAAc;IAC/C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAK,wBAA8C,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AACtG,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,oBAAoB,CAAC,MAAwB;IAC3D,OAAO,wBAAwB,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;AAClD,CAAC;AAuBD,2FAA2F;AAC3F,MAAM,UAAU,yBAAyB;IACvC,OAAO;QACL,kBAAkB,EAAE,QAAQ;QAC5B,oBAAoB,EAAE,IAAI;QAC1B,gBAAgB,EAAE,CAAC;QACnB,YAAY,EAAE,IAAI;KACnB,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,kCAAkC;AAClC,8EAA8E;AAE9E;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,OAAO,EAAE,cAAc,EAAE,YAAY,CAAU,CAAC;AAIhF,2DAA2D;AAC3D,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAK,eAAqC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAC7F,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,yBAAyB,GAAkC;IAC/D,YAAY,EAAE,CAAC;IACf,cAAc,EAAE,CAAC;IACjB,KAAK,EAAE,CAAC;CACT,CAAC;AAEF,0DAA0D;AAC1D,MAAM,UAAU,iBAAiB,CAAC,OAAsB;IACtD,OAAO,yBAAyB,CAAC,OAAO,CAAC,CAAC;AAC5C,CAAC;AAmED,+FAA+F;AAC/F,MAAM,UAAU,0BAA0B;IACxC,OAAO,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE,CAAC;AACtC,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,mBAAmB;IACjC,OAAO;QACL,UAAU,EAAE,KAAK;QACjB,OAAO,EAAE,cAAc;QACvB,YAAY,EAAE,IAAI;QAClB,SAAS,EAAE,IAAI;QACf,2EAA2E;QAC3E,0EAA0E;QAC1E,yEAAyE;QACzE,qEAAqE;QACrE,cAAc,EAAE;YACd,QAAQ;YACR,mBAAmB;YACnB,qBAAqB;YACrB,gBAAgB;YAChB,WAAW;YACX,WAAW;YACX,QAAQ;YACR,UAAU;YACV,WAAW;YACX,eAAe;YACf,qBAAqB;SACtB;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"config-types.js","sourceRoot":"","sources":["../src/config-types.ts"],"names":[],"mappings":"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"}

package/dist/database-url.d.ts

@@ -0,0 +1,55 @@
+/**
+ * State-database URL vocabulary — the small pure things both `lastlight-core`
+ * and the `lastlight` CLI have to agree about.
+ *
+ * It lives in `shared` for the same reason `repo-config-schema.ts` does: core
+ * needs it at runtime (`StateDb.open()` picks a driver, `/config` redacts a
+ * credential) and the CLI needs it offline (the setup wizard validates the URL
+ * the operator types and reports the driver it implies), and the CLI may never
+ * gain an edge to core. Nothing here imports a database driver — a `pg` import
+ * anywhere in this file would put node-postgres in the CLI's dependency graph.
+ */
+/** Which Postgres driver carries the `"postgres"` dialect. */
+export type PgDriver = "pg" | "neon";
+export declare const PG_DRIVERS: readonly PgDriver[];
+/** Does this DB URL name Postgres (rather than a libsql `file:` / `:memory:`)? */
+export declare function isPostgresUrl(input: string | undefined | null): boolean;
+export declare function isPgDriver(value: unknown): value is PgDriver;
+/**
+ * Which driver to run a `postgres://` URL over.
+ *
+ * `configured` (from `database.driver` / `DATABASE_DRIVER`) always wins — a Neon
+ * database fronted by a custom domain, or node-postgres pointed at Neon's TCP
+ * endpoint, both need to be expressible. Unset falls back to the host
+ * heuristic, which answers `"neon"` only for `*.neon.tech`.
+ *
+ * An unparseable URL resolves to `"pg"`: the driver builder is about to fail on
+ * it anyway, and node-postgres produces the better message.
+ */
+export declare function resolvePgDriver(url: string, configured?: PgDriver | null): PgDriver;
+/**
+ * A DB URL safe to log or echo from the dashboard's `/config` view.
+ *
+ * Masks the userinfo and any `password=` query parameter, keeping the host,
+ * port and database name — those are not secrets, and they are the whole reason
+ * the provenance view exists. `file:` URLs and `:memory:` pass through
+ * untouched; there is nothing in them to leak.
+ *
+ * Anything that carries a `@` but does not parse is masked WHOLESALE rather
+ * than returned — a redactor that fails open is not a redactor.
+ */
+export declare function redactDbUrl(url: string): string;
+/** The host of a DB URL, or undefined if it has none / does not parse. */
+export declare function dbUrlHost(url: string): string | undefined;
+/**
+ * Host + port for a `postgres://` URL, for a reachability probe that must not
+ * import a driver (the setup wizard opens a bare TCP socket).
+ *
+ * Hand-parsed for the same reason {@link redactDbUrl} is: `new URL()` throws on
+ * an unencoded `@` in the password, and a wizard that rejects a working URL
+ * because of its punctuation is worse than no check at all.
+ */
+export declare function parsePgEndpoint(url: string): {
+    host: string;
+    port: number;
+} | undefined;

package/dist/database-url.js

@@ -0,0 +1,118 @@
+/**
+ * State-database URL vocabulary — the small pure things both `lastlight-core`
+ * and the `lastlight` CLI have to agree about.
+ *
+ * It lives in `shared` for the same reason `repo-config-schema.ts` does: core
+ * needs it at runtime (`StateDb.open()` picks a driver, `/config` redacts a
+ * credential) and the CLI needs it offline (the setup wizard validates the URL
+ * the operator types and reports the driver it implies), and the CLI may never
+ * gain an edge to core. Nothing here imports a database driver — a `pg` import
+ * anywhere in this file would put node-postgres in the CLI's dependency graph.
+ */
+export const PG_DRIVERS = ["pg", "neon"];
+/** Case-insensitive, because URL schemes are and `POSTGRES://` is a real typo. */
+const POSTGRES_URL_RE = /^postgres(ql)?:\/\//i;
+/** Does this DB URL name Postgres (rather than a libsql `file:` / `:memory:`)? */
+export function isPostgresUrl(input) {
+    return !!input && POSTGRES_URL_RE.test(input.trim());
+}
+export function isPgDriver(value) {
+    return value === "pg" || value === "neon";
+}
+/**
+ * Hosts served by Neon's WebSocket pooler. An explicit `database.driver` always
+ * beats this, so the list only has to cover the common case.
+ */
+const NEON_HOST_RE = /(^|\.)neon\.tech$/i;
+/**
+ * Which driver to run a `postgres://` URL over.
+ *
+ * `configured` (from `database.driver` / `DATABASE_DRIVER`) always wins — a Neon
+ * database fronted by a custom domain, or node-postgres pointed at Neon's TCP
+ * endpoint, both need to be expressible. Unset falls back to the host
+ * heuristic, which answers `"neon"` only for `*.neon.tech`.
+ *
+ * An unparseable URL resolves to `"pg"`: the driver builder is about to fail on
+ * it anyway, and node-postgres produces the better message.
+ */
+export function resolvePgDriver(url, configured) {
+    if (isPgDriver(configured))
+        return configured;
+    return NEON_HOST_RE.test(dbUrlHost(url) ?? "") ? "neon" : "pg";
+}
+/**
+ * Splits `scheme://` + userinfo + the rest without `new URL()`, which rejects a
+ * password containing an unencoded `@` — exactly the case where getting
+ * redaction right matters most. The userinfo group is GREEDY so it runs to the
+ * LAST `@` in the authority: a lazy match would leave the tail of such a
+ * password in the "safe" remainder.
+ */
+const USERINFO_RE = /^([A-Za-z][A-Za-z0-9+.-]*:\/\/)([^/?#]*@)(.*)$/s;
+/**
+ * A DB URL safe to log or echo from the dashboard's `/config` view.
+ *
+ * Masks the userinfo and any `password=` query parameter, keeping the host,
+ * port and database name — those are not secrets, and they are the whole reason
+ * the provenance view exists. `file:` URLs and `:memory:` pass through
+ * untouched; there is nothing in them to leak.
+ *
+ * Anything that carries a `@` but does not parse is masked WHOLESALE rather
+ * than returned — a redactor that fails open is not a redactor.
+ */
+export function redactDbUrl(url) {
+    const trimmed = url.trim();
+    if (!trimmed || trimmed === ":memory:" || /^file:/i.test(trimmed))
+        return url;
+    const match = USERINFO_RE.exec(trimmed);
+    if (!match) {
+        // No userinfo at all (`postgres://host/db`) — nothing to mask beyond the
+        // query string. A string with an `@` that reached here is unparseable, so
+        // it gets the blunt treatment.
+        if (trimmed.includes("@"))
+            return "[redacted]";
+        return maskPasswordParam(trimmed);
+    }
+    const [, scheme, , rest] = match;
+    // Fail CLOSED. A surviving `@` means the authority did not end where the
+    // regex thought (an unencoded `/` in the password, say), so what looks like
+    // the safe remainder may still be part of the credential.
+    if (rest.includes("@"))
+        return "[redacted]";
+    return `${scheme}***:***@${maskPasswordParam(rest)}`;
+}
+function maskPasswordParam(input) {
+    return input.replace(/([?&](?:password|pgpassword)=)[^&]*/gi, "$1***");
+}
+/** The host of a DB URL, or undefined if it has none / does not parse. */
+export function dbUrlHost(url) {
+    return parsePgEndpoint(url)?.host;
+}
+/**
+ * Host + port for a `postgres://` URL, for a reachability probe that must not
+ * import a driver (the setup wizard opens a bare TCP socket).
+ *
+ * Hand-parsed for the same reason {@link redactDbUrl} is: `new URL()` throws on
+ * an unencoded `@` in the password, and a wizard that rejects a working URL
+ * because of its punctuation is worse than no check at all.
+ */
+export function parsePgEndpoint(url) {
+    const trimmed = url.trim();
+    const afterScheme = trimmed.replace(/^[A-Za-z][A-Za-z0-9+.-]*:\/\//, "");
+    if (afterScheme === trimmed)
+        return undefined; // no scheme → not a URL
+    // Authority ends at the first `/`, `?` or `#`; userinfo ends at the LAST `@`
+    // inside it, so a password containing `@` does not steal the host.
+    const authority = afterScheme.split(/[/?#]/, 1)[0] ?? "";
+    const hostPort = authority.slice(authority.lastIndexOf("@") + 1);
+    if (!hostPort)
+        return undefined;
+    // IPv6 literal: `[::1]:5432`.
+    const v6 = /^\[([^\]]+)\](?::(\d+))?$/.exec(hostPort);
+    if (v6)
+        return { host: v6[1], port: v6[2] ? Number(v6[2]) : 5432 };
+    const [host, port] = hostPort.split(":");
+    if (!host)
+        return undefined;
+    return { host, port: port && /^\d+$/.test(port) ? Number(port) : 5432 };
+}
+//# sourceMappingURL=database-url.js.map

package/dist/database-url.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"database-url.js","sourceRoot":"","sources":["../src/database-url.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH,MAAM,CAAC,MAAM,UAAU,GAAwB,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;AAE9D,kFAAkF;AAClF,MAAM,eAAe,GAAG,sBAAsB,CAAC;AAE/C,kFAAkF;AAClF,MAAM,UAAU,aAAa,CAAC,KAAgC;IAC5D,OAAO,CAAC,CAAC,KAAK,IAAI,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;AACvD,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,KAAc;IACvC,OAAO,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,MAAM,CAAC;AAC5C,CAAC;AAED;;;GAGG;AACH,MAAM,YAAY,GAAG,oBAAoB,CAAC;AAE1C;;;;;;;;;;GAUG;AACH,MAAM,UAAU,eAAe,CAAC,GAAW,EAAE,UAA4B;IACvE,IAAI,UAAU,CAAC,UAAU,CAAC;QAAE,OAAO,UAAU,CAAC;IAC9C,OAAO,YAAY,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;AACjE,CAAC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,GAAG,iDAAiD,CAAC;AAEtE;;;;;;;;;;GAUG;AACH,MAAM,UAAU,WAAW,CAAC,GAAW;IACrC,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IAC3B,IAAI,CAAC,OAAO,IAAI,OAAO,KAAK,UAAU,IAAI,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC;QAAE,OAAO,GAAG,CAAC;IAC9E,MAAM,KAAK,GAAG,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACxC,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,yEAAyE;QACzE,0EAA0E;QAC1E,+BAA+B;QAC/B,IAAI,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC;YAAE,OAAO,YAAY,CAAC;QAC/C,OAAO,iBAAiB,CAAC,OAAO,CAAC,CAAC;IACpC,CAAC;IACD,MAAM,CAAC,EAAE,MAAM,EAAE,AAAD,EAAG,IAAI,CAAC,GAAG,KAAK,CAAC;IACjC,yEAAyE;IACzE,4EAA4E;IAC5E,0DAA0D;IAC1D,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,YAAY,CAAC;IAC5C,OAAO,GAAG,MAAM,WAAW,iBAAiB,CAAC,IAAI,CAAC,EAAE,CAAC;AACvD,CAAC;AAED,SAAS,iBAAiB,CAAC,KAAa;IACtC,OAAO,KAAK,CAAC,OAAO,CAAC,uCAAuC,EAAE,OAAO,CAAC,CAAC;AACzE,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,SAAS,CAAC,GAAW;IACnC,OAAO,eAAe,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC;AACpC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAAC,GAAW;IACzC,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IAC3B,MAAM,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,+BAA+B,EAAE,EAAE,CAAC,CAAC;IACzE,IAAI,WAAW,KAAK,OAAO;QAAE,OAAO,SAAS,CAAC,CAAC,wBAAwB;IACvE,6EAA6E;IAC7E,mEAAmE;IACnE,MAAM,SAAS,GAAG,WAAW,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IACzD,MAAM,QAAQ,GAAG,SAAS,CAAC,KAAK,CAAC,SAAS,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;IACjE,IAAI,CAAC,QAAQ;QAAE,OAAO,SAAS,CAAC;IAChC,8BAA8B;IAC9B,MAAM,EAAE,GAAG,2BAA2B,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACtD,IAAI,EAAE;QAAE,OAAO,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IACnE,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACzC,IAAI,CAAC,IAAI;QAAE,OAAO,SAAS,CAAC;IAC5B,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;AAC1E,CAAC"}

package/dist/index.d.ts

@@ -19,5 +19,6 @@ export * from "./overlay-assets.js";
 export * from "./core-pin.js";
 export * from "./workflow-loader.js";
 export * from "./config-types.js";
+export * from "./database-url.js";
 export * from "./repo-config-schema.js";
 export * from "./sandbox-services.js";

package/dist/index.js

@@ -19,6 +19,7 @@ export * from "./overlay-assets.js";
 export * from "./core-pin.js";
 export * from "./workflow-loader.js";
 export * from "./config-types.js";
+export * from "./database-url.js";
 export * from "./repo-config-schema.js";
 export * from "./sandbox-services.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,cAAc,wBAAwB,CAAC;AACvC,cAAc,qBAAqB,CAAC;AACpC,cAAc,eAAe,CAAC;AAC9B,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,yBAAyB,CAAC;AACxC,cAAc,uBAAuB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,cAAc,wBAAwB,CAAC;AACvC,cAAc,qBAAqB,CAAC;AACpC,cAAc,eAAe,CAAC;AAC9B,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,yBAAyB,CAAC;AACxC,cAAc,uBAAuB,CAAC"}