@namzu/sdk 42.0.2 → 44.0.0

package/dist/turn/command-gate.d.ts

@@ -0,0 +1,107 @@
+/**
+ * A {@link ReviewAnswer} that runs shell commands and hands the failure back.
+ *
+ * `reviewAnswer` was the seam for exactly this — judge the answer at the point
+ * the model stops calling tools, and return it with feedback instead of
+ * settling — and nothing shipped supplied one, so an operator who wanted
+ * "don't finish until the build passes" had to write TypeScript. This is the
+ * supplier. With it, `--gate 'pnpm test'` is the whole unattended story: the
+ * model works, stops, the tests run, and a failure comes back as the next user
+ * turn rather than as a green run somebody discovers in CI.
+ *
+ * The kernel already bounds it. The reviewer is consulted only when the model
+ * stopped calling tools, never on the forced-final turn, and a rejection
+ * budget stops the turn with `answer_rejected` — a stop reason that names the
+ * reviewer rather than blaming a token budget. None of that is re-implemented
+ * here.
+ *
+ * ## The part that is not just "run a command"
+ *
+ * **Before re-running a command that already failed, the workspace is
+ * fingerprinted, and an identical fingerprint means the command is NOT run.**
+ *
+ * This is the difference between a bounded loop and one that spends its whole
+ * budget. A model that has run out of ideas answers again without editing
+ * anything; re-running the suite then costs a full execution — often the most
+ * expensive thing in the loop — to produce a failure already known character
+ * for character. Worse, the feedback is identical, so the model is handed the
+ * same prompt that just failed to help it. Saying instead "the workspace has
+ * not changed since that failure; edit something before trying to finish"
+ * is both cheaper and a different instruction.
+ *
+ * The attempt still advances. Skipping the command is a saving, not a pardon:
+ * an answer that changed nothing has been rejected, and the turn's budget must
+ * see that or a stuck model loops forever for free.
+ *
+ * And it fails open on the cheap side. No fingerprint — a git invocation that
+ * errored, a timeout, output past the cap, a tree with no commits — means the
+ * command runs. See {@link fingerprintWorkspace}: the cost of re-running
+ * unnecessarily is one execution; the cost of wrongly skipping is a
+ * verification that silently did not happen.
+ */
+import type { CommandOptions, CommandResult } from '../types/execution/index.js';
+import type { ReviewAnswer } from '../types/session/answer-review.js';
+/** How the gate runs a command. Injected so a test needs no shell. */
+export type GateExec = (command: string, args: string[], options?: CommandOptions) => Promise<CommandResult>;
+/** Default per-command deadline. A test suite is allowed to be slow. */
+export declare const DEFAULT_GATE_TIMEOUT_MS = 600000;
+/** How many attempts the gate will EXECUTE its commands for, by default. */
+export declare const DEFAULT_GATE_MAX_RETRIES = 3;
+/**
+ * Model-visible characters of a failing command's output.
+ *
+ * Head and tail, not head alone: a compiler names the file at the top and a
+ * test runner names the failure at the bottom, and a gate that only ever kept
+ * one end would be useless for one of them.
+ */
+export declare const DEFAULT_GATE_OUTPUT_CHARS = 4000;
+export interface CommandGateOptions {
+    /**
+     * Shell command lines, run in order, stopping at the first failure.
+     *
+     * In order and short-circuiting because that is what a person means by
+     * "typecheck then test": a type error makes the test output noise about
+     * the same cause, and handing the model both invites it to fix the
+     * symptom.
+     */
+    readonly commands: readonly string[];
+    /** Directory the commands run in, and the tree that is fingerprinted. */
+    readonly cwd: string;
+    /**
+     * How many attempts will actually EXECUTE the commands.
+     *
+     * Past it the gate rejects without running anything, naming the
+     * exhaustion. It does not accept: an answer that never passed the gate
+     * has not passed the gate, and a reviewer that gave up by accepting would
+     * hand back a green run over a red build — the exact outcome the gate
+     * exists to prevent. What ENDS the turn is the kernel's rejection budget,
+     * so set that to the same number (the CLI does).
+     */
+    readonly maxRetries?: number;
+    /** Per-command deadline. See {@link DEFAULT_GATE_TIMEOUT_MS}. */
+    readonly timeoutMs?: number;
+    /** Override the executor. Defaults to a local shell in `cwd`. */
+    readonly exec?: GateExec;
+    /** See {@link DEFAULT_GATE_OUTPUT_CHARS}. */
+    readonly maxOutputChars?: number;
+    /**
+     * Override the change detector. Defaults to
+     * {@link fingerprintWorkspace} over `cwd`.
+     *
+     * Returning `null` means "cannot tell", and the gate then runs its
+     * commands. A detector that returned a constant would silence the gate
+     * after its first failure, so this seam exists for tests and for a host
+     * whose workspace is not a git tree — not as a way to turn the check off.
+     */
+    readonly fingerprint?: () => Promise<string | null>;
+}
+/** Head and tail of a command's output, with the middle marked as dropped. */
+export declare function clipOutput(text: string, max: number): string;
+/**
+ * Build a reviewer that accepts an answer only when every command passes.
+ *
+ * Stateful across calls within one turn, deliberately: the whole point is that
+ * attempt N+1 can be compared with attempt N. Build one gate per turn.
+ */
+export declare function createCommandGate(options: CommandGateOptions): ReviewAnswer;
+//# sourceMappingURL=command-gate.d.ts.map

package/dist/turn/command-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-gate.d.ts","sourceRoot":"","sources":["../../src/turn/command-gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAA;AAChF,OAAO,KAAK,EAAgB,YAAY,EAAE,MAAM,mCAAmC,CAAA;AAGnF,sEAAsE;AACtE,MAAM,MAAM,QAAQ,GAAG,CACtB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,CAAC,EAAE,cAAc,KACpB,OAAO,CAAC,aAAa,CAAC,CAAA;AAE3B,wEAAwE;AACxE,eAAO,MAAM,uBAAuB,SAAU,CAAA;AAE9C,4EAA4E;AAC5E,eAAO,MAAM,wBAAwB,IAAI,CAAA;AAEzC;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,OAAQ,CAAA;AAE9C,MAAM,WAAW,kBAAkB;IAClC;;;;;;;OAOG;IACH,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;IACpC,yEAAyE;IACzE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB;;;;;;;;;OASG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAC5B,iEAAiE;IACjE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAC3B,iEAAiE;IACjE,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAA;IACxB,6CAA6C;IAC7C,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAA;IAChC;;;;;;;;OAQG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;CACnD;AAED,8EAA8E;AAC9E,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAa5D;AAyDD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,kBAAkB,GAAG,YAAY,CA0G3E"}

package/dist/turn/command-gate.js

@@ -0,0 +1,221 @@
+/**
+ * A {@link ReviewAnswer} that runs shell commands and hands the failure back.
+ *
+ * `reviewAnswer` was the seam for exactly this — judge the answer at the point
+ * the model stops calling tools, and return it with feedback instead of
+ * settling — and nothing shipped supplied one, so an operator who wanted
+ * "don't finish until the build passes" had to write TypeScript. This is the
+ * supplier. With it, `--gate 'pnpm test'` is the whole unattended story: the
+ * model works, stops, the tests run, and a failure comes back as the next user
+ * turn rather than as a green run somebody discovers in CI.
+ *
+ * The kernel already bounds it. The reviewer is consulted only when the model
+ * stopped calling tools, never on the forced-final turn, and a rejection
+ * budget stops the turn with `answer_rejected` — a stop reason that names the
+ * reviewer rather than blaming a token budget. None of that is re-implemented
+ * here.
+ *
+ * ## The part that is not just "run a command"
+ *
+ * **Before re-running a command that already failed, the workspace is
+ * fingerprinted, and an identical fingerprint means the command is NOT run.**
+ *
+ * This is the difference between a bounded loop and one that spends its whole
+ * budget. A model that has run out of ideas answers again without editing
+ * anything; re-running the suite then costs a full execution — often the most
+ * expensive thing in the loop — to produce a failure already known character
+ * for character. Worse, the feedback is identical, so the model is handed the
+ * same prompt that just failed to help it. Saying instead "the workspace has
+ * not changed since that failure; edit something before trying to finish"
+ * is both cheaper and a different instruction.
+ *
+ * The attempt still advances. Skipping the command is a saving, not a pardon:
+ * an answer that changed nothing has been rejected, and the turn's budget must
+ * see that or a stuck model loops forever for free.
+ *
+ * And it fails open on the cheap side. No fingerprint — a git invocation that
+ * errored, a timeout, output past the cap, a tree with no commits — means the
+ * command runs. See {@link fingerprintWorkspace}: the cost of re-running
+ * unnecessarily is one execution; the cost of wrongly skipping is a
+ * verification that silently did not happen.
+ */
+import { LocalExecutionContext } from '../execution/local.js';
+import { fingerprintWorkspace } from './workspace-fingerprint.js';
+/** Default per-command deadline. A test suite is allowed to be slow. */
+export const DEFAULT_GATE_TIMEOUT_MS = 600_000;
+/** How many attempts the gate will EXECUTE its commands for, by default. */
+export const DEFAULT_GATE_MAX_RETRIES = 3;
+/**
+ * Model-visible characters of a failing command's output.
+ *
+ * Head and tail, not head alone: a compiler names the file at the top and a
+ * test runner names the failure at the bottom, and a gate that only ever kept
+ * one end would be useless for one of them.
+ */
+export const DEFAULT_GATE_OUTPUT_CHARS = 4_000;
+/** Head and tail of a command's output, with the middle marked as dropped. */
+export function clipOutput(text, max) {
+    if (!Number.isSafeInteger(max) || max < 0) {
+        throw new RangeError('maxOutputChars must be a nonnegative safe integer.');
+    }
+    const trimmed = text.trimEnd();
+    if (trimmed.length <= max)
+        return trimmed;
+    const markerBudget = `\n… ${trimmed.length} characters omitted …\n`.length;
+    if (max < markerBudget)
+        return max === 0 ? '' : '…';
+    const retained = max - markerBudget;
+    const head = Math.ceil(retained / 2);
+    const tail = retained - head;
+    const marker = `\n… ${trimmed.length - retained} characters omitted …\n`;
+    return `${trimmed.slice(0, head)}${marker}${tail > 0 ? trimmed.slice(-tail) : ''}`;
+}
+function failureFeedback(command, attempt, result, maxOutputChars) {
+    const output = clipOutput(`${result.stdout}\n${result.stderr}`, maxOutputChars);
+    const truncatedStreams = [
+        result.stdoutTruncated === true ? 'stdout' : undefined,
+        result.stderrTruncated === true ? 'stderr' : undefined,
+    ].filter((stream) => stream !== undefined);
+    const truncationWarning = truncatedStreams.length === 0
+        ? []
+        : [
+            '',
+            `Retained output is incomplete: ${truncatedStreams.join(' and ')} ${truncatedStreams.length === 1 ? 'was' : 'were'} truncated by the execution context. Re-run with a narrower command or filter to recover the missing diagnostics.`,
+        ];
+    return [
+        `The answer was not accepted: \`${command}\` failed (attempt ${attempt}, exit ${result.exitCode}${result.termination ? `, terminated: ${result.termination.origin}` : ''}).`,
+        '',
+        'Output:',
+        '```',
+        output || '(no output)',
+        '```',
+        ...truncationWarning,
+        '',
+        'Fix the cause and then finish. Do not restate the failure back to me; change the code so the command passes.',
+    ].join('\n');
+}
+function unchangedFeedback(command, attempt) {
+    return [
+        `The answer was not accepted, and \`${command}\` was NOT re-run (attempt ${attempt}).`,
+        '',
+        'The configured change detector reports the same state as after the last failure. The default detector covers the Git commit and Git-visible working state; ignored files and external inputs may have changed.',
+        '',
+        'Check that the intended fix is present and addresses the reported failure. If verification depends on state outside the detector, the host should supply a matching fingerprint or return null to re-run checks.',
+    ].join('\n');
+}
+function exhaustedFeedback(command, maxRetries) {
+    return [
+        `The answer was not accepted: \`${command}\` has failed and this gate has spent its ${maxRetries} attempts.`,
+        '',
+        'No further command will be run.',
+    ].join('\n');
+}
+/**
+ * Build a reviewer that accepts an answer only when every command passes.
+ *
+ * Stateful across calls within one turn, deliberately: the whole point is that
+ * attempt N+1 can be compared with attempt N. Build one gate per turn.
+ */
+export function createCommandGate(options) {
+    const { commands, cwd } = options;
+    const timeoutMs = options.timeoutMs ?? DEFAULT_GATE_TIMEOUT_MS;
+    const maxRetries = options.maxRetries ?? DEFAULT_GATE_MAX_RETRIES;
+    const maxOutputChars = options.maxOutputChars ?? DEFAULT_GATE_OUTPUT_CHARS;
+    // Validate before a reviewer is installed: malformed limits cannot turn
+    // a formatting exception during verification into an unreviewed answer.
+    clipOutput('', maxOutputChars);
+    // Built once and reused: constructing a context per attempt would re-stat
+    // the directory for no gain, and the context holds nothing per-turn.
+    const context = new LocalExecutionContext({ id: 'namzu-command-gate', cwd });
+    const exec = options.exec ?? ((command, args, opts) => context.executeCommand(command, args, opts));
+    const readFingerprint = async (signal) => {
+        if (signal?.aborted)
+            return null;
+        try {
+            return options.fingerprint
+                ? await options.fingerprint()
+                : await fingerprintWorkspace({
+                    cwd,
+                    timeoutMs: 20_000,
+                    exec: (command, args, commandOptions) => exec(command, args, { ...commandOptions, ...(signal ? { signal } : {}) }),
+                });
+        }
+        catch {
+            return null;
+        }
+    };
+    let attempt = 0;
+    let last;
+    let executions = 0;
+    return async (_answer, reviewContext) => {
+        const signal = reviewContext.signal;
+        if (signal?.aborted)
+            return { accept: false, feedback: 'Verification was cancelled before admission.' };
+        attempt += 1;
+        // A gate that already failed, over a tree nothing has touched since.
+        // The command is skipped, and the attempt still counts.
+        //
+        // The comparison is a bare `===` rather than `now !== null && now ===
+        // …`. The guard above already establishes that the recorded
+        // fingerprint is non-null, so a `null` from this call cannot match it,
+        // and the extra clause was a branch nothing could reach — a mutation
+        // that deleted it killed no test, which is what a dead condition looks
+        // like from the outside.
+        if (last && last.fingerprint !== null) {
+            const now = await readFingerprint(signal);
+            if (now === last.fingerprint) {
+                return { accept: false, feedback: unchangedFeedback(last.command, attempt) };
+            }
+        }
+        if (last && executions >= maxRetries) {
+            return { accept: false, feedback: exhaustedFeedback(last.command, maxRetries) };
+        }
+        executions += 1;
+        for (const command of commands) {
+            if (signal?.aborted)
+                return { accept: false, feedback: 'Verification was cancelled before admission.' };
+            // `shell: true` because the operator handed over a command LINE —
+            // `pnpm test -- --run`, with its flags and its quoting — and taking
+            // that as an executable name plus literal arguments would fail on
+            // every gate anyone would actually write. Explicit, per the note on
+            // `LocalExecutionContext.executeCommand`: shell interpretation is
+            // opt-in, and this is the opt-in.
+            let result;
+            try {
+                result = await exec(command, [], {
+                    cwd,
+                    timeoutMs,
+                    shell: true,
+                    ...(signal ? { signal } : {}),
+                });
+            }
+            catch (error) {
+                // A command that could not be observed completing is not a pass.
+                // Keep this inside the builtin reviewer: generic review callbacks
+                // historically fail open on throws. No fabricated exit status.
+                last = { command, fingerprint: null };
+                return {
+                    accept: false,
+                    feedback: `The answer was not accepted: verification with \`${command}\` could not complete (attempt ${attempt}).\n${clipOutput(error instanceof Error ? error.message : String(error), maxOutputChars)}\nCheck the execution problem and any partial effects before retrying. Do not claim verification passed.`,
+                };
+            }
+            if (signal?.aborted)
+                return { accept: false, feedback: 'Verification was cancelled.' };
+            if (result.exitCode === 0 && result.termination === undefined)
+                continue;
+            // Taken AFTER the failure, not before the turn: the comparison next
+            // time is against the tree this verdict was formed over. A snapshot
+            // from before the command would miss anything the command itself
+            // wrote — a formatter, a snapshot updater, a lockfile.
+            // Interrupted verification is not a stable failure of these source
+            // bytes. Allow another check even when no tracked file has changed.
+            last = { command, fingerprint: result.termination ? null : await readFingerprint(signal) };
+            return { accept: false, feedback: failureFeedback(command, attempt, result, maxOutputChars) };
+        }
+        // Cleared, so a later rejection by a DIFFERENT command is not compared
+        // against a tree this one failed over.
+        last = undefined;
+        return { accept: true };
+    };
+}
+//# sourceMappingURL=command-gate.js.map

package/dist/turn/command-gate.js.map

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

package/dist/turn/drain.d.ts

@@ -0,0 +1,138 @@
+/**
+ * One pass over a queue of durable turns: list what nobody holds, take it,
+ * hand it to a worker, give it back.
+ *
+ * Every primitive this composes already exists — `SessionIndex` lists the
+ * parked turns (`listPendingDecisions`) and the sessions whose turn is
+ * still open, a session's lease arbitrates between processes, and
+ * `resumeSession` carries the lease's fence into every record. This
+ * composes them, so an approval inbox and a crash sweeper do not each have
+ * to get the release into a `finally` and the `null` claim out of the error
+ * path.
+ *
+ * ## What this deliberately is NOT
+ *
+ * A supervisor, a daemon, or a scheduler. There is no timer here, no
+ * process spawn, no retry backoff and no `while (true)`. `drainParkedTurns` makes
+ * ONE bounded pass and returns what happened; running it again is the
+ * caller's decision, made wherever that caller already has a scheduler. A
+ * per-platform supervisor is the same trade the deployment-adapter matrix
+ * was rejected for: one seam beats N adapters.
+ *
+ * Read the scope of that narrowly. This paragraph has been cited as the
+ * kernel's refusal of a model-facing "remind me tomorrow" capability, and
+ * it is not one: it says a HOST brings the timer, which presumes the host
+ * has one rather than ruling the capability out. Whether such a capability
+ * should exist -- and if so, as a store plus a host-driven sweep rather
+ * than a daemon here -- is open. `directory/types.ts` records the adjacent
+ * decision that cut a declarative `schedules/` slot, on grounds of
+ * double-fire and timezone; that is a different question from a runtime
+ * tool, and neither text settles the other.
+ *
+ * The unit of work is a callback, so this module never needs a provider, a
+ * tool registry or a sandbox — the half of a turn that cannot be serialized
+ * stays with the caller, exactly as `resumeSession` already splits it.
+ */
+import type { SessionIndex } from '../store/session-index/index.js';
+import { type SessionLease, type SessionLog } from '../store/session-log/index.js';
+import type { ProjectId, SessionId, TenantId, TurnId } from '../types/ids/index.js';
+import type { DurableTurnEntry, ParkState } from '../types/session/durable.js';
+/** Turns handled per pass when the caller names no page size. */
+export declare const DEFAULT_DRAIN_PAGE_SIZE = 100;
+/**
+ * What a drainer does with one turn it successfully took.
+ *
+ * Receives the lease, not just its fence: the holder and expiry are what a
+ * worker needs to decide whether it still has time to start. The intended
+ * body is a resume under that lease:
+ *
+ * ```ts
+ * onTurn: (entry, lease) =>
+ *   resumeSession({ ...yourQueryParams, scope: { ...entry, topicId }, sessionLog, checkpointStore, lease })
+ * ```
+ *
+ * A throw is recorded against that turn and the pass continues.
+ */
+export type DrainTurn = (entry: DurableTurnEntry, lease: SessionLease) => void | Promise<void>;
+export interface DrainTurnsParams {
+    /** Where the durable turns are listed from. */
+    readonly index: SessionIndex;
+    /** Attribution of every entry; the index is per `NAMZU_HOME`, which is per tenant. */
+    readonly tenantId: TenantId;
+    /** Narrow to one project. */
+    readonly projectId?: ProjectId;
+    /** Narrow to one session. */
+    readonly sessionId?: SessionId;
+    /**
+     * Opens the log of a listed session. Default: the disk log at the path
+     * the index files it under.
+     */
+    readonly openLog?: (sessionId: SessionId, logPath: string) => SessionLog;
+    /**
+     * Who is taking the turns. Per-PROCESS, never per-deployment: two drainers
+     * sharing a string would wait on each other's leases as their own.
+     */
+    readonly holder: string;
+    /** Lease length in ms. Long enough that the slowest turn finishes inside it. */
+    readonly ttlMs: number;
+    /** The work. See {@link DrainTurn}. */
+    readonly onTurn: DrainTurn;
+    /**
+     * Keep only turns whose park is in one of these states.
+     *
+     * **Absent means every open turn nobody holds, parked or not**: what a
+     * crash sweep wants, because a turn that died mid-flight never parked. An
+     * approval inbox passes `['outstanding']`; a reclamation sweep passes
+     * `['expired']`.
+     */
+    readonly park?: readonly ParkState[];
+    /** Stop taking new turns. Work already in flight is not interrupted. */
+    readonly signal?: AbortSignal;
+    /** How many turns may be in flight at once. Defaults to 1. */
+    readonly maxConcurrent?: number;
+    /** Candidates handled per pass. See {@link DEFAULT_DRAIN_PAGE_SIZE}. */
+    readonly pageSize?: number;
+    /** Clock for expiry, so one pass judges every lease and park against one instant. */
+    readonly now?: number;
+}
+/** A turn a pass could not finish, and why. */
+export interface DrainFailure {
+    readonly turnId: TurnId;
+    readonly error: string;
+}
+/** What one pass did. */
+export interface DrainTurnsResult {
+    /** Candidates listed, before any of them were contended for. */
+    readonly listed: number;
+    /** Turns whose `onTurn` returned. */
+    readonly drained: readonly TurnId[];
+    /** Turns whose session another worker held. Not failures. */
+    readonly skipped: readonly TurnId[];
+    /**
+     * Turns that stopped matching between the listing and the claim (another
+     * drainer finished them, or their park changed state), given straight back.
+     */
+    readonly stale: readonly TurnId[];
+    /** Turns whose `onTurn` threw. */
+    readonly failed: readonly DrainFailure[];
+    /** Turns that finished but whose lease could not be handed back. */
+    readonly unreleased: readonly DrainFailure[];
+    /** Whether the pass stopped early because the signal aborted. */
+    readonly stopped: boolean;
+}
+/**
+ * Take every open turn nobody holds, one bounded pass, and give each one
+ * back when its work returns.
+ *
+ * The shape is: list → claim the session's lease → re-read the turn under
+ * the lease → work → release in a `finally`. Only under the lease is the
+ * re-read stable, and a turn that no longer matches (settled, resumed by
+ * another drainer, or its park answered) is given straight back as
+ * {@link DrainTurnsResult.stale}. An inbox drain whose work answers the park
+ * is therefore exactly-once: doing the work removes the turn from the queue.
+ *
+ * @throws NamzuError `invalid_config` on a lease or concurrency that cannot
+ *   mean what it says.
+ */
+export declare function drainParkedTurns(params: DrainTurnsParams): Promise<DrainTurnsResult>;
+//# sourceMappingURL=drain.d.ts.map

package/dist/turn/drain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"drain.d.ts","sourceRoot":"","sources":["../../src/turn/drain.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAA;AACnE,OAAO,EAAkB,KAAK,YAAY,EAAE,KAAK,UAAU,EAAE,MAAM,+BAA+B,CAAA;AAGlG,OAAO,KAAK,EAAgB,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAA;AACjG,OAAO,KAAK,EAAE,gBAAgB,EAAE,SAAS,EAAe,MAAM,6BAA6B,CAAA;AAE3F,iEAAiE;AACjE,eAAO,MAAM,uBAAuB,MAAM,CAAA;AAE1C;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,KAAK,EAAE,gBAAgB,EAAE,KAAK,EAAE,YAAY,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;AAE9F,MAAM,WAAW,gBAAgB;IAChC,+CAA+C;IAC/C,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAA;IAC5B,sFAAsF;IACtF,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAA;IAC3B,6BAA6B;IAC7B,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAA;IAC9B,6BAA6B;IAC7B,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAA;IAC9B;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,KAAK,UAAU,CAAA;IACxE;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,gFAAgF;IAChF,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,uCAAuC;IACvC,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAA;IAC1B;;;;;;;OAOG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,SAAS,EAAE,CAAA;IACpC,wEAAwE;IACxE,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;IAC7B,8DAA8D;IAC9D,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;IAC/B,wEAAwE;IACxE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B,qFAAqF;IACrF,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CACrB;AAED,+CAA+C;AAC/C,MAAM,WAAW,YAAY;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CACtB;AAED,yBAAyB;AACzB,MAAM,WAAW,gBAAgB;IAChC,gEAAgE;IAChE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,qCAAqC;IACrC,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;IACnC,6DAA6D;IAC7D,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;IACnC;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;IACjC,kCAAkC;IAClC,QAAQ,CAAC,MAAM,EAAE,SAAS,YAAY,EAAE,CAAA;IACxC,oEAAoE;IACpE,QAAQ,CAAC,UAAU,EAAE,SAAS,YAAY,EAAE,CAAA;IAC5C,iEAAiE;IACjE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;CACzB;AAsED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CA6G1F"}