dorfl 0.0.0 → 0.1.0

package/dist/advance-lifecycle-template.js.map

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

package/dist/advance-loop-driver.d.ts

@@ -0,0 +1,325 @@
+import { type AdvanceResult } from './advance.js';
+import type { AdvanceTickRunner, AdvanceTickOptions } from './advance-drivers.js';
+import { type LedgerReadStrategy } from './ledger-read.js';
+import type { LifecyclePoolGates } from './lifecycle-pools.js';
+import { type ScanReport } from './scan.js';
+import type { Config } from './config.js';
+import type { RunTick } from './run.js';
+/**
+ * The **`advance` LOOP DRIVER** (prd `advance-loop`, task
+ * `advance-drivers-and-gates`, US #7/22/26/31) — the second of the two drivers
+ * over the substrate-agnostic advance TICK. Where the one-shot driver
+ * (`advance-drivers.ts`) runs the tick over named item(s) SEQUENTIALLY, this
+ * driver loops the tick over the ELIGIBLE SET with genuine PARALLELISM, each item
+ * independently lock-guarded by the `advancing` borrow.
+ *
+ * It WRAPS the EXISTING substrate, building NO new machinery:
+ *
+ *   - the eligible set comes from the SHARED `mirror-side-eligible-pool-scan`
+ *     ({@link scanMirrorPool}) — the SAME enumeration the one-shot/CI `advance`
+ *     driver + `do --remote -n` consume (NOT invented twice), gated per-action
+ *     (build→`autoBuild`, task→`autoTask`) by the SELECTION layer;
+ *   - parallelism is the SAME bounded scheduler `run`'s build tick uses
+ *     ({@link runConcurrent}) — `maxParallel` global / `perRepoMax` per repo;
+ *   - the per-item `advancing` borrow is held INSIDE {@link performAdvance}
+ *     (classify → lock → execute, winner-only), so a CAS loser among the parallel
+ *     ticks backs off having spent only the free classification — the lock is the
+ *     ONLY shared state across the in-flight ticks.
+ *
+ * `run` ≡ CI (US #7): the loop is just repeated batches of THIS tick (same
+ * contract, different substrate / cadence — a `run` daemon, a CI cron, the CI
+ * matrix). The tick is the contract; this driver owns ONLY the
+ * select-pool + run-batch-concurrently part, exactly mirroring how
+ * `runOnce`/`runLoop` separate the tick from the scheduling loop (so the
+ * advance-loop forward-pointer's "swap the tick without re-architecting the loop"
+ * holds — the loop machinery is `run.ts`'s `runLoop`, this is its advance tick).
+ *
+ * **Convergence / drain (US #31).** Each batch advances every eligible item one
+ * rung, surfaces+idles, or no-ops on a pending sidecar; the candidate pool shrinks
+ * MONOTONICALLY as answers arrive (an answered item flips from a no-op to an
+ * `apply` that resolves it) and is STABLE when there are none (a pending-sidecar
+ * pool is all no-ops — calm at rest, no thrash). {@link advanceBatchSummary}
+ * exposes the counts the convergence tests assert on.
+ */
+/** What {@link advanceOnce} needs: which bare mirror + the gate config + the tick seam. */
+export interface AdvanceOnceOptions {
+    /** The bare hub mirror whose committed `main` the eligible pool is scanned from. */
+    mirrorPath: string;
+    /**
+     * The resolved (remote) repo config — `autoBuild`/`autoTask` gate the pool
+     * scan, `selectionOrder` the cross-pool order. The per-action gate family is
+     * applied at the SELECTION layer, exactly as the one-shot driver applies it.
+     */
+    config: Config;
+    /**
+     * The mirror-LOCAL ref whose `work/` to scan (default `main`). A bare hub
+     * mirror's `main` is a LOCAL branch.
+     */
+    ref?: string;
+    /**
+     * Global cap on advance ticks IN FLIGHT at once (the daemon's `maxParallel`).
+     * Defaults to `config.maxParallel`.
+     */
+    maxParallel?: number;
+    /**
+     * Per-repo cap on ticks in flight (the daemon's `perRepoMax`). The mirror is one
+     * repo, so this also bounds the whole batch. Defaults to `config.perRepoMax`.
+     */
+    perRepoMax?: number;
+    /**
+     * The per-item advance tick context (everything BUT `arg`): the run context the
+     * tick threads to each item (cwd, arbiter, doOptions, the surface/triage gate
+     * seams, …). Each selected item's `arg` is filled in by this driver.
+     */
+    context: Omit<AdvanceTickOptions, 'arg'>;
+    /** Override the single-tick runner (tests inject a stub). Defaults to {@link performAdvance}. */
+    run?: AdvanceTickRunner;
+    /** Override the read seam (mirror pool); defaults to the active {@link ledgerRead}. */
+    read?: LedgerReadStrategy;
+    /** Sink for a non-fatal mirror-config-read warning, forwarded to the scan. */
+    warn?: (message: string) => void;
+    /** The git env the mirror scan's read ops run under (identity/non-interactive). */
+    env?: NodeJS.ProcessEnv;
+    /**
+     * The LIFECYCLE-POOL create-gates (task `advance-autopick-lifecycle-pools`),
+     * forwarded to {@link scanMirrorPool}. INTERIM, born OFF: omitted ⇒ BOTH
+     * create-gates off, so the loop/CI advance auto-triages / auto-surfaces nothing
+     * (the apply sub-pool is always-on). The gate tasks wire this to
+     * `observationTriage` / `surfaceBlockers`.
+     */
+    lifecycleGates?: LifecyclePoolGates;
+}
+/** One advanced item's result + the identity it was for (input order preserved). */
+export interface AdvanceBatchItem {
+    /** The namespaced arg the tick was run on (`prd:<slug>` / bare slug). */
+    arg: string;
+    /** The tick's result, or a captured throw mapped to a usage-error result. */
+    result: AdvanceResult;
+}
+/** The aggregate outcome of ONE loop-driver batch (the convergence signal). */
+export interface AdvanceBatchResult {
+    /** Every selected item's result, in selection (priority) order. */
+    items: AdvanceBatchItem[];
+}
+/**
+ * Run ONE batch of the loop driver: scan the mirror's eligible pool, select +
+ * order it (gated per-action), and run the advance TICK per item CONCURRENTLY,
+ * each independently `advancing`-lock-guarded inside {@link performAdvance}.
+ * Returns every item's result (input order preserved). A `run` daemon / CI cron
+ * loops THIS — the loop owns cadence, the batch owns one round's work.
+ */
+export declare function advanceOnce(options: AdvanceOnceOptions): Promise<AdvanceBatchResult>;
+/**
+ * One mirror's slot in a {@link advanceRegistrySet} batch: which mirror drained,
+ * and that mirror's batch result (or a captured throw mapped to a usage-error
+ * batch — one mirror can never abort the whole registry sweep).
+ */
+export interface AdvanceRegistryMirrorResult {
+    /** The bare hub mirror that was drained this batch. */
+    mirrorPath: string;
+    /** That mirror's {@link advanceOnce} batch result. */
+    batch: AdvanceBatchResult;
+}
+/** The aggregate outcome of ONE registry-set advance batch (every mirror's batch). */
+export interface AdvanceRegistrySetResult {
+    /** Each drained mirror's batch, in registry-discovery order. */
+    mirrors: AdvanceRegistryMirrorResult[];
+}
+/**
+ * What {@link advanceRegistrySet} needs: the global config (the registry +
+ * caps), the per-mirror advance CONTEXT factory, and the execution workspace.
+ */
+export interface AdvanceRegistrySetOptions {
+    /**
+     * The global config. Its `workspacesDir` IS the registry (the hub-mirror set
+     * {@link scan} enumerates); `maxParallel`/`perRepoMax` are the SAME caps the
+     * build tick's scheduler uses.
+     */
+    config: Config;
+    /**
+     * Build the per-mirror advance CONTEXT (everything BUT `arg` and the build/task
+     * `doDriver`). The driver INJECTS the per-mirror job-worktree `doDriver`
+     * ({@link jobWorktreeDoDriver}) on top of what this returns, so the build/task
+     * rungs run isolated off THAT mirror's arbiter — the caller supplies the gate
+     * seams + `doOptions` base (harness, verify, review, …), exactly as the CLI
+     * wires them for the single-mirror path. `cwd` here is irrelevant to the
+     * build/task rungs (the worktree driver replaces it); the tree-less
+     * surface/triage/apply rungs use it as their ledger-write cwd.
+     */
+    contextFor: (input: {
+        mirrorPath: string;
+        originUrl: string;
+    }) => Omit<AdvanceTickOptions, 'arg' | 'doDriver'>;
+    /**
+     * The execution working area (bare hub mirrors + per-job worktrees). Defaults
+     * to `config.workspacesDir`. The per-mirror worktree `doDriver` materialises its
+     * worktree under here — the agents' area, the SAME isolation `run` uses.
+     */
+    workspace?: string;
+    /** Pre-computed registry scan (tests); omitted ⇒ the live `scan(config)`. */
+    report?: ScanReport;
+    /** Override the single-tick runner (tests). Defaults to {@link performAdvance}. */
+    run?: AdvanceTickRunner;
+    /** Override the read seam (mirror pool); defaults to the active {@link ledgerRead}. */
+    read?: LedgerReadStrategy;
+    /** Sink for non-fatal warnings (mirror-config read; forwarded to scan + pool scan). */
+    warn?: (message: string) => void;
+    /** The git env the registry scan + per-mirror pool scans run under. */
+    env?: NodeJS.ProcessEnv;
+    /**
+     * The LIFECYCLE-POOL create-gates, forwarded to each mirror's
+     * {@link advanceOnce}. INTERIM, born OFF (omitted ⇒ both off). The CLI wires
+     * this to `observationTriage`/`surfaceBlockers`, exactly as the single-mirror
+     * path does.
+     */
+    lifecycleGates?: LifecyclePoolGates;
+    /**
+     * The per-machine config-override map (ADR
+     * `per-machine-config-override-layer`), forwarded to the registry {@link scan}
+     * so per-mirror `autoTask`/`observationTriage`/`surfaceBlockers` resolutions
+     * honour the override. Default: empty (no override).
+     */
+    override?: import('./config-override.js').ConfigOverrideMap;
+}
+/**
+ * The **registry-set advance DRIVER** with **per-mirror job-worktree isolation**
+ * (task `advance-loop-driver-registry-set-job-worktrees`) — the advance-tick TWIN
+ * of `runOnce`/`runOneItem`'s build substrate, the substrate `run-uses-advance-tick`
+ * needs to become a clean tick swap. Where {@link advanceOnce} drains ONE named
+ * mirror's pool IN-PLACE (the single-mirror path), this driver:
+ *
+ *   1. **discovers the REGISTRY SET** the SAME way `runOnce` does — via
+ *      {@link scan} over `config.workspacesDir`'s hub mirrors (NOT a single
+ *      `--advance <mirror>` arg); and
+ *   2. loops {@link advanceOnce}'s batch over that set, GENUINELY CONCURRENT
+ *      ACROSS REPOS under {@link runConcurrent} (`maxParallel` global /
+ *      `perRepoMax` per repo — the SAME scheduler `run`'s build tick uses), each
+ *      mirror's pool itself drained concurrently by `advanceOnce` (reusing the
+ *      per-item `advancing` borrow INSIDE {@link performAdvance} — no new lock,
+ *      no new scheduler); and
+ *   3. threads a **per-mirror job-worktree `doDriver`** ({@link jobWorktreeDoDriver})
+ *      into each mirror's advance context, so the build/task rungs run isolated
+ *      in their OWN worktree off THAT mirror's arbiter (the SAME isolation
+ *      `runOneItem` gives the build tick) instead of in `process.cwd()`. The
+ *      surface/triage/apply rungs stay on their tree-less ledger-write moves
+ *      (no build worktree needed) — the worktree driver governs ONLY the
+ *      build/task orchestration target.
+ *
+ * Under calm gates (both lifecycle create-gates off) this is the OBSERVABLE-
+ * OUTCOME equivalent of plain `run`'s build tick over the same registry: build
+ * ready tasks / task ready prds, each per-job-worktree-isolated off the
+ * mirror's arbiter, same integration result — two callers of one
+ * `performIntegration` band (the advance build rung reaches it via `performDo`
+ * → `performDoRemote`; `runOneItem` reaches it directly), NOT a shared code path.
+ */
+export declare function advanceRegistrySet(options: AdvanceRegistrySetOptions): Promise<AdvanceRegistrySetResult>;
+/** Project a whole registry-set batch onto the convergence counts (a pure sum). */
+export declare function advanceRegistrySetSummary(result: AdvanceRegistrySetResult): AdvanceBatchSummary;
+/** The convergence counts of one batch (the drain/idle signal US #31 asserts on). */
+export interface AdvanceBatchSummary {
+    /** Items the batch ADVANCED a rung (build/task/surface/apply/triage). */
+    advanced: number;
+    /** Items that NO-OPed (a pending sidecar idling — the calm-at-rest population). */
+    idle: number;
+    /** Items that FAILED / contended (non-zero, non-no-op). */
+    stuck: number;
+    /** Total selected this batch (= the candidate pool size). */
+    total: number;
+}
+/** Summarise a batch into the convergence counts (a pure projection). */
+export declare function advanceBatchSummary(result: AdvanceBatchResult): AdvanceBatchSummary;
+/**
+ * Is this batch CALM-AT-REST (US #31) — every selected item idled (a pending
+ * sidecar awaiting a human) and nothing failed? A pending-sidecar pool is STABLE:
+ * the loop re-ticks it, finds all no-ops, and idles without thrash. As answers
+ * arrive the idle count shrinks MONOTONICALLY (an answered item flips to an
+ * advance), so the loop converges.
+ */
+export declare function isBatchCalmAtRest(result: AdvanceBatchResult): boolean;
+/**
+ * The advance-specific dependencies the {@link RunTick} adapter closes over —
+ * everything the {@link advanceOnce} batch needs that is NOT carried by the
+ * generic per-tick {@link RunOnceOptions} (which describe the BUILD tick's
+ * checkout-scan world). The CLI builds these ONCE (the mirror to drain, the
+ * resolved remote config, the per-item advance context) and hands them to
+ * {@link advanceRunTick}; the loop ({@link runLoop}) then drives the resulting
+ * tick exactly as it drives the build tick.
+ */
+export interface AdvanceRunTickDeps extends Omit<AdvanceOnceOptions, 'maxParallel' | 'perRepoMax' | 'warn' | 'env'> {
+    /**
+     * Override the per-batch caps. Defaults to `config.maxParallel` /
+     * `config.perRepoMax` (the SAME knobs the build tick's scheduler uses), so a
+     * `run` daemon caps advance ticks identically.
+     */
+    maxParallel?: number;
+    perRepoMax?: number;
+}
+/**
+ * Adapt the {@link advanceOnce} LOOP DRIVER to the {@link RunTick} swap SEAM so
+ * `run` (≡ CI, US #7) drives the ADVANCE tick over the mirror-side eligible pool
+ * instead of the build tick. `run.ts` deliberately writes {@link runLoop} against
+ * {@link RunTick} (NOT against `runOnce`) precisely so the advance-loop prd can
+ * swap the tick WITHOUT re-architecting the loop — this is that swap.
+ *
+ * The seam is `(RunOnceOptions) => Promise<RunOnceResult>`; one advance batch is
+ * `(AdvanceOnceOptions) => Promise<AdvanceBatchResult>`. The deps the advance
+ * batch needs that the generic per-tick options do NOT carry (the mirror to
+ * drain, the remote config, the per-item advance context) are CLOSED OVER here;
+ * the per-tick `RunOnceOptions` contribute only the cross-cutting seams that DO
+ * generalise — `onWarn` (the warning sink) and `env` (the git env). The batch's
+ * own item-level pool scan supersedes `RunOnceOptions.report` (the build tick's
+ * checkout scan), so that field is ignored for the advance tick.
+ *
+ * The {@link AdvanceBatchResult} is projected onto {@link RunOnceResult} so the
+ * loop's aggregation/reporting (`claimedAndDone` / `skipped` / `failed` /
+ * `needsAttention`) works UNCHANGED — an `advanced` item is `claimed-done`, an
+ * idling pending-sidecar `no-op` is `lost-race` (skipped, calm-at-rest), a CAS
+ * loser is `claim-contended` (skipped), and any error is `needs-attention`. So
+ * the loop's existing convergence signal (`claimedAndDone` falls to 0 once the
+ * pool is all idle) doubles as the advance loop's drain/idle signal (US #31).
+ */
+export declare function advanceRunTick(deps: AdvanceRunTickDeps): RunTick;
+/**
+ * The deps the {@link advanceRegistrySetRunTick} adapter closes over — everything
+ * the {@link advanceRegistrySet} batch needs that the generic per-tick
+ * {@link RunOnceOptions} does NOT carry. This is the REGISTRY-SET twin of
+ * {@link AdvanceRunTickDeps}: where that adapter drives ONE named mirror in-place
+ * ({@link advanceRunTick}), this one discovers the WHOLE registry via
+ * `scan(config)` and runs each mirror's pool in a per-mirror job worktree — the
+ * substrate `run` needs so plain `run` (no flag) ≡ advance with calm-default gates.
+ * The CLI builds these ONCE (the resolved config, the per-mirror advance-context
+ * factory, the execution workspace) and hands them to {@link advanceRegistrySetRunTick};
+ * the loop ({@link runLoop}) then drives the resulting tick exactly as it drove the
+ * build tick.
+ */
+export interface AdvanceRegistrySetRunTickDeps extends Omit<AdvanceRegistrySetOptions, 'warn' | 'env' | 'report'> {
+}
+/**
+ * Adapt the REGISTRY-SET advance DRIVER ({@link advanceRegistrySet}) onto the
+ * {@link RunTick} swap SEAM so plain `run` (no flag) drives the ADVANCE tick over
+ * the WHOLE registry instead of the build tick (`runOnce`) — the task
+ * `run-uses-advance-tick`. `run.ts` deliberately writes {@link runLoop} against
+ * {@link RunTick} (NOT against `runOnce`) precisely so the advance-loop design can
+ * swap the tick WITHOUT re-architecting the loop; this is that swap, now pointing
+ * the seam at the REGISTRY-SET advance driver the precursor built (registry-set
+ * discovery + per-mirror job-worktree isolation — the SAME substrate plain `run`'s
+ * build tick uses).
+ *
+ * Under calm gates (both lifecycle create-gates off) this is the OBSERVABLE-
+ * OUTCOME equivalent of plain `run`'s build tick over the same registry: build
+ * ready tasks / task ready prds, each per-job-worktree-isolated off the
+ * mirror's arbiter, same integration result; touch no observations, surface no
+ * questions. Flip a gate and the SAME tick performs the lifecycle
+ * (triage / surface / apply) for free — no separate `--advance` mode to discover.
+ *
+ * The seam is `(RunOnceOptions) => Promise<RunOnceResult>`; one registry-set
+ * batch is `(AdvanceRegistrySetOptions) => Promise<AdvanceRegistrySetResult>`. The
+ * deps the batch needs that the generic per-tick options do NOT carry (the config,
+ * the per-mirror context factory, the workspace) are CLOSED OVER here; the
+ * per-tick `RunOnceOptions` contribute only the cross-cutting seams that DO
+ * generalise — `onWarn` (the warning sink) and `env` (the git env). The batch's
+ * own registry discovery supersedes `RunOnceOptions.report` (the build tick's
+ * checkout scan), so that field is ignored for the advance tick.
+ */
+export declare function advanceRegistrySetRunTick(deps: AdvanceRegistrySetRunTickDeps): RunTick;
+//# sourceMappingURL=advance-loop-driver.d.ts.map

package/dist/advance-loop-driver.d.ts.map

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