@cleocode/core 2026.9.22 → 2026.9.24

package/dist/decide/sites/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/decide/sites/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAElE,uFAAuF;AACvF,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;CAkBM,CAAC;AAE5C,8FAA8F;AAC9F,eAAO,MAAM,oCAAoC;;;;;;;;;;;;;;;;;;;CAoBN,CAAC;AAE5C,yEAAyE;AACzE,eAAO,MAAM,8BAA8B;;;;;;;;;;;;;;;;;;CAgBA,CAAC;AAE5C,uFAAuF;AACvF,eAAO,MAAM,4BAA4B;;;;;;;;;;;;;;;;;;CAmBE,CAAC;AAE5C,wEAAwE;AACxE,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;CAcM,CAAC;AAE5C;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;CAcI,CAAC;AAkP5C;;;GAGG;AACH,eAAO,MAAM,cAAc,EAAE,SAAS,sBAAsB,EAQ3D,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,sBAAsB,GAAG,SAAS,CAE9E"}

package/dist/decide/sites/registry.js

@@ -0,0 +1,398 @@
+/**
+ * The decision-site registry — every place CLEO makes a judgement, with its
+ * rung, ladder, fallback, owner-escalation rule, mode and go-live evidence
+ * (spec `system-one-integration` §3, D11158; naming and config keys per
+ * D11159: the `decide.*` keys stay).
+ *
+ * Pure data: importing this module loads nothing else, so the call sites can
+ * take their ids and config keys from here without a startup cost. Each id
+ * string exists once, here; the site modules re-export it under their old
+ * constant names (`DUPLICATE_DECISION_SITE` …) so no caller breaks.
+ *
+ * Phase 1 (T12662) records the sites and changes no behaviour. Executing the
+ * ladder (escalation, handoffs) is T12665; the CI gate over it is T12663.
+ *
+ * @task T12662
+ * @epic T12486
+ */
+/** `tasks.duplicate-detection` — is a new task a duplicate of an open one (T12492). */
+export const DUPLICATE_DETECTION_SITE = {
+    id: 'tasks.duplicate-detection',
+    title: 'Duplicate task detection on add',
+    files: ['packages/core/src/tasks/duplicate-detector.ts'],
+    questionType: 'noul',
+    primaryRung: 'system-one',
+    ladder: ['generative'],
+    fallback: 'rule',
+    floors: { '*': 0.6 },
+    ownerEscalation: 'never',
+    modeKey: 'decide.sites.duplicateDetection',
+    generativeKey: 'decide.generativeFallback.duplicateDetection',
+    defaultMode: 'shadow',
+    llmSystemKey: 'consolidation',
+    writePath: true,
+    sends: ['task-text'],
+    task: 'T12492',
+    note: 'Batched noul over at most 3 candidates; rule fallback is Tier-1/Jaccard similarity.',
+};
+/** `memory.decision-contradiction` — does a new decision contradict a stored one (T12493). */
+export const DECISION_CONTRADICTION_DECISION_SITE = {
+    id: 'memory.decision-contradiction',
+    title: 'Decision contradiction check on store',
+    files: [
+        'packages/core/src/memory/decision-contradiction.ts',
+        'packages/core/src/memory/decisions.ts',
+    ],
+    questionType: 'choice',
+    primaryRung: 'system-one',
+    ladder: ['generative'],
+    fallback: 'rule',
+    floors: { '*': 0.6 },
+    ownerEscalation: 'never',
+    modeKey: 'decide.sites.decisionContradiction',
+    generativeKey: 'decide.generativeFallback.decisionContradiction',
+    defaultMode: 'shadow',
+    writePath: true,
+    sends: ['memory-text'],
+    task: 'T12493',
+    note: 'Advisory: a contradiction is reported, never blocks the write.',
+};
+/** `memory.observation-type` — which type an observation is (T12494). */
+export const OBSERVATION_TYPE_DECISION_SITE = {
+    id: 'memory.observation-type',
+    title: 'Observation type classification',
+    files: ['packages/core/src/memory/observation-type-decision.ts'],
+    questionType: 'choice',
+    primaryRung: 'system-one',
+    ladder: [],
+    fallback: 'rule',
+    floors: { '*': 0.6 },
+    ownerEscalation: 'never',
+    modeKey: 'decide.sites.observationType',
+    defaultMode: 'shadow',
+    writePath: true,
+    sends: ['memory-text'],
+    task: 'T12494',
+    note: 'Interactive observations only; rule fallback is keyword typing.',
+};
+/** `orchestration.owner-decision` — does a task wait on an owner decision (T12494). */
+export const OWNER_DECISION_DECISION_SITE = {
+    id: 'orchestration.owner-decision',
+    title: 'Owner-decision readiness check',
+    files: [
+        'packages/core/src/orchestration/owner-decision-readiness.ts',
+        'packages/core/src/orchestration/classify-readiness.ts',
+    ],
+    questionType: 'noul',
+    primaryRung: 'rule',
+    ladder: ['system-one'],
+    fallback: 'rule',
+    floors: { '*': 0.6 },
+    ownerEscalation: 'escalate-only',
+    modeKey: 'decide.sites.ownerDecision',
+    defaultMode: 'shadow',
+    writePath: true,
+    sends: ['task-text'],
+    task: 'T12494',
+    note: 'Escalate-only: may add requiresOwnerDecision, never clears it.',
+};
+/** `cli.decide-ask` — the `cleo decide ask` debug question (T12491). */
+export const DECIDE_ASK_DECISION_SITE = {
+    id: 'cli.decide-ask',
+    title: 'cleo decide ask (debug question)',
+    files: ['packages/core/src/decide/operations.ts'],
+    questionType: 'noul',
+    primaryRung: 'system-one',
+    ladder: [],
+    fallback: 'none',
+    ownerEscalation: 'never',
+    defaultMode: 'on',
+    writePath: false,
+    sends: ['external-text'],
+    task: 'T12491',
+    note: 'Debug verb: the operator supplies the text; nothing acts on the answer.',
+};
+/**
+ * `cli.decide-bench` — the `cleo decide bench` accuracy benchmark (T12495).
+ *
+ * Replays labelled rows built from CLEO's own history through each compared
+ * provider. Its answers are scored against the labels and never acted on, so
+ * it runs `on` without go-live evidence (it produces that evidence).
+ */
+export const DECIDE_BENCH_DECISION_SITE = {
+    id: 'cli.decide-bench',
+    title: 'cleo decide bench (accuracy benchmark)',
+    files: ['packages/core/src/decide/bench/runner.ts'],
+    questionType: 'choice',
+    primaryRung: 'system-one',
+    ladder: [],
+    fallback: 'rule',
+    ownerEscalation: 'never',
+    defaultMode: 'on',
+    writePath: false,
+    sends: ['task-text', 'memory-text'],
+    task: 'T12495',
+    note: 'Benchmark verb: replays the duplicate, observation-type and contradiction questions; answers are scored, never acted on.',
+};
+/**
+ * Generative and agent-rung sites that predate the ladder: registered so every
+ * model call site is listed (spec §3.3). All `on`; none uses System One.
+ */
+const GENERATIVE_SITES = [
+    {
+        id: 'memory.derivation',
+        title: 'Memory derivation',
+        files: ['packages/core/src/deriver/deriver.ts'],
+        questionType: 'text',
+        primaryRung: 'generative',
+        ladder: [],
+        fallback: 'none',
+        ownerEscalation: 'never',
+        defaultMode: 'on',
+        llmSystemKey: 'derivation',
+        writePath: false,
+        sends: ['memory-text'],
+        task: 'T12662',
+    },
+    {
+        id: 'memory.extraction',
+        title: 'Memory and transcript extraction',
+        files: [
+            'packages/core/src/memory/llm-extraction.ts',
+            'packages/core/src/memory/transcript-extractor.ts',
+            'packages/core/src/memory/llm-backend-resolver.ts',
+        ],
+        questionType: 'text',
+        primaryRung: 'generative',
+        ladder: [],
+        fallback: 'none',
+        ownerEscalation: 'never',
+        defaultMode: 'on',
+        llmSystemKey: 'extraction',
+        writePath: false,
+        sends: ['memory-text'],
+        task: 'T12662',
+    },
+    {
+        id: 'memory.dialectic-evaluation',
+        title: 'Dialectic evaluation of memory claims',
+        files: ['packages/core/src/memory/dialectic-evaluator.ts'],
+        questionType: 'text',
+        primaryRung: 'generative',
+        ladder: [],
+        fallback: 'none',
+        ownerEscalation: 'never',
+        defaultMode: 'on',
+        writePath: false,
+        sends: ['memory-text'],
+        task: 'T12662',
+        note: 'Calls generateObject directly (a known chokepoint bypass, gate 13 baseline).',
+    },
+    {
+        id: 'memory.consolidation',
+        title: 'Sleep consolidation and dream cycle',
+        files: [
+            'packages/core/src/memory/sleep-consolidation.ts',
+            'packages/core/src/sentient/dream-cycle.ts',
+        ],
+        questionType: 'text',
+        primaryRung: 'generative',
+        ladder: [],
+        fallback: 'none',
+        ownerEscalation: 'never',
+        defaultMode: 'on',
+        llmSystemKey: 'consolidation',
+        writePath: false,
+        sends: ['memory-text'],
+        task: 'T12662',
+    },
+    {
+        id: 'memory.observer-reflection',
+        title: 'Observer / reflector',
+        files: ['packages/core/src/memory/observer-reflector.ts'],
+        questionType: 'text',
+        primaryRung: 'generative',
+        ladder: [],
+        fallback: 'none',
+        ownerEscalation: 'never',
+        defaultMode: 'on',
+        writePath: false,
+        sends: ['memory-text'],
+        task: 'T12662',
+    },
+    {
+        id: 'memory.specialists',
+        title: 'Memory specialists',
+        files: ['packages/core/src/memory/specialists.ts'],
+        questionType: 'text',
+        primaryRung: 'generative',
+        ladder: [],
+        fallback: 'none',
+        ownerEscalation: 'never',
+        defaultMode: 'on',
+        writePath: false,
+        sends: ['memory-text'],
+        task: 'T12662',
+    },
+    {
+        id: 'memory.summarization',
+        title: 'Context summarization',
+        files: [
+            'packages/core/src/llm/plugin-facade.ts',
+            'packages/core/src/memory/context-engines/llm-summarizer.ts',
+        ],
+        questionType: 'text',
+        primaryRung: 'generative',
+        ladder: [],
+        fallback: 'none',
+        ownerEscalation: 'never',
+        defaultMode: 'on',
+        writePath: false,
+        sends: ['memory-text'],
+        task: 'T12662',
+    },
+    {
+        id: 'sentient.hygiene',
+        title: 'Hygiene scan',
+        files: [
+            'packages/core/src/sentient/hygiene-scan.ts',
+            'packages/core/src/llm/auxiliary-fallback.ts',
+        ],
+        questionType: 'text',
+        primaryRung: 'generative',
+        ladder: [],
+        fallback: 'none',
+        ownerEscalation: 'never',
+        defaultMode: 'on',
+        llmSystemKey: 'hygiene',
+        writePath: false,
+        sends: ['task-text', 'memory-text'],
+        task: 'T12662',
+    },
+    {
+        id: 'selfimprove.fix-gen',
+        title: 'Self-improvement fix generation',
+        files: ['packages/core/src/selfimprove/fix-gen.ts'],
+        questionType: 'text',
+        primaryRung: 'generative',
+        ladder: [],
+        fallback: 'none',
+        ownerEscalation: 'never',
+        defaultMode: 'on',
+        llmSystemKey: 'fix-gen',
+        writePath: false,
+        sends: ['diff'],
+        task: 'T12662',
+    },
+    {
+        id: 'nexus.wiki',
+        title: 'Nexus wiki generation',
+        files: ['packages/core/src/nexus/wiki-orchestrator.ts'],
+        questionType: 'text',
+        primaryRung: 'generative',
+        ladder: [],
+        fallback: 'none',
+        ownerEscalation: 'never',
+        defaultMode: 'on',
+        writePath: false,
+        sends: ['diff'],
+        task: 'T12662',
+    },
+    {
+        id: 'tools.agent-tools',
+        title: 'Web and media agent tools',
+        files: [
+            'packages/core/src/tools/web-agent-tools.ts',
+            'packages/core/src/tools/media-agent-tools.ts',
+        ],
+        questionType: 'text',
+        primaryRung: 'generative',
+        ladder: [],
+        fallback: 'none',
+        ownerEscalation: 'never',
+        defaultMode: 'on',
+        llmSystemKey: 'task-executor',
+        writePath: false,
+        sends: ['external-text'],
+        task: 'T12662',
+    },
+    {
+        id: 'llm.probe',
+        title: 'Provider probes (cleo llm, login)',
+        files: [
+            'packages/core/src/llm/onboarding/login-engine.ts',
+            'packages/core/src/llm/cli-ops.ts',
+            'packages/cleo/src/cli/commands/llm-stream.ts',
+        ],
+        questionType: 'text',
+        primaryRung: 'generative',
+        ladder: [],
+        fallback: 'none',
+        ownerEscalation: 'never',
+        defaultMode: 'on',
+        writePath: false,
+        sends: [],
+        task: 'T12662',
+    },
+    {
+        id: 'llm.agent-transport',
+        title: 'Agent-rung transports',
+        files: [
+            'packages/core/src/llm/role-executor.ts',
+            'packages/core/src/llm/session-factory.ts',
+            'packages/core/src/llm/pi/pi-stream-fn.ts',
+            'packages/core/src/playbooks/cantbook-profile.ts',
+        ],
+        questionType: 'multi-step',
+        primaryRung: 'agent',
+        ladder: [],
+        fallback: 'none',
+        ownerEscalation: 'never',
+        defaultMode: 'on',
+        writePath: false,
+        sends: ['task-text'],
+        task: 'T12662',
+    },
+    {
+        id: 'harness.sdk-spawn',
+        title: 'Harness SDK adapters (Claude, OpenAI, Kimi)',
+        files: [
+            'packages/adapters/src/providers/claude-sdk/spawn.ts',
+            'packages/adapters/src/providers/openai-sdk/spawn.ts',
+            'packages/adapters/src/providers/kimi/spawn.ts',
+        ],
+        questionType: 'multi-step',
+        primaryRung: 'agent',
+        ladder: [],
+        fallback: 'none',
+        ownerEscalation: 'never',
+        defaultMode: 'on',
+        writePath: false,
+        sends: ['task-text'],
+        task: 'T12663',
+        note: 'Agent-rung transports (spec §6.4): registered, exempt from the rung check.',
+    },
+];
+/**
+ * Every registered decision site. The System One sites come first, then the
+ * generative and agent-rung sites.
+ */
+export const DECISION_SITES = [
+    DUPLICATE_DETECTION_SITE,
+    DECISION_CONTRADICTION_DECISION_SITE,
+    OBSERVATION_TYPE_DECISION_SITE,
+    OWNER_DECISION_DECISION_SITE,
+    DECIDE_ASK_DECISION_SITE,
+    DECIDE_BENCH_DECISION_SITE,
+    ...GENERATIVE_SITES,
+];
+/**
+ * The registry row for `id`.
+ *
+ * @param id - Site id.
+ * @returns The row, or `undefined` when no site has that id.
+ */
+export function getDecisionSite(id) {
+    return DECISION_SITES.find((site) => site.id === id);
+}
+//# sourceMappingURL=registry.js.map

package/dist/decide/sites/registry.js.map

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

package/dist/decide/spend.d.ts

@@ -0,0 +1,196 @@
+/**
+ * Monthly spend cap for System One decisions — the CLEO-enforced COST budget
+ * of owner decision D11159 (spec `system-one-integration` §7).
+ *
+ * Every CLEO process on the machine records provider-reported cost (integer
+ * micro-dollars) into ONE ledger, `<cleoHome>/decide/spend.json`, guarded by a
+ * `proper-lockfile` lock. Once the month-to-date spend reaches the cap
+ * (`decide.budget.monthlyMicros`, default
+ * {@link DEFAULT_MONTHLY_SPEND_CAP_MICROS} = $1), every site degrades to its
+ * heuristic with fallback reason `budget` until the UTC month rolls over. It
+ * never fails a command.
+ *
+ * ## Reserve, then commit
+ *
+ * A caller reserves its estimated cost BEFORE the provider call, under the
+ * same lock as the cap check, and commits the reported cost (or releases the
+ * reservation) after it. Concurrent callers therefore see each other's
+ * in-flight spend and cannot overshoot the cap together. A reservation still
+ * pending after {@link RESERVATION_TTL_MS} (its process died, or exited
+ * before its commit landed) is CHARGED at its estimate, not dropped: the
+ * request may have been billed, and the cap must not undercount it.
+ *
+ * The lock retries for about a second with backoff: a decision may wait for
+ * the ledger, but a cost is never dropped because 40 processes recorded at
+ * once (review of #1685: the first version lost 33 of 40 concurrent records).
+ *
+ * The ledger also carries the key-limit stop: a 403 `key_limit_exceeded`
+ * (an unverified provider extension) means the key's monthly decision limit
+ * is reached, so decisions stop until the end of the UTC month.
+ *
+ * A corrupt ledger fails closed (every site uses its heuristic) and
+ * `cleo decide status` says so; `cleo decide budget reset` repairs it, moving
+ * the bad file aside as a receipt. It refuses a readable ledger unless
+ * `--force` is given, and then keeps the month-to-date spend, so a reset can
+ * never lift a reached cap.
+ *
+ * @task T12664
+ * @epic T12486
+ */
+/** Default monthly cap: 1,000,000 micro-dollars = $1 (D11159). */
+export declare const DEFAULT_MONTHLY_SPEND_CAP_MICROS = 1000000;
+/** Config key holding the monthly cap in micro-dollars. */
+export declare const MONTHLY_SPEND_CAP_KEY = "decide.budget.monthlyMicros";
+/**
+ * How long a reservation stays pending, ms. After that it is charged at its
+ * estimate (it may have been billed). Decision deadlines are hundreds of ms,
+ * so a live call always commits or releases long before this.
+ */
+export declare const RESERVATION_TTL_MS = 60000;
+/** Verdict of a spend check or reservation. */
+export type SpendVerdict = 'ok' | 'over_budget' | 'key_limited' | 'unavailable';
+/** Month-to-date state, as `cleo decide status` reports it. */
+export interface SpendStatus {
+    /** UTC month, `YYYY-MM`. */
+    readonly month: string;
+    /** Micro-dollars committed this month. */
+    readonly spentMicros: number;
+    /** Micro-dollars reserved by calls still in flight. */
+    readonly reservedMicros: number;
+    /** Epoch ms until which the key's monthly limit stops decisions, when set. */
+    readonly keyLimitedUntil?: number;
+}
+/** Result of {@link SpendLedger.reserve}. */
+export interface SpendReservation {
+    /** The verdict; only `ok` carries a reservation. */
+    readonly verdict: SpendVerdict;
+    /** Reservation id to commit or release. */
+    readonly id?: string;
+}
+/** Result of {@link SpendLedger.inspect}. */
+export type SpendLedgerHealth = 'ok' | 'absent' | 'corrupt' | 'unavailable';
+/** A monthly spend ledger. Implementations never throw. */
+export interface SpendLedger {
+    /**
+     * Check the cap and, when there is room for `estimateMicros` on top of the
+     * committed and reserved spend, reserve it — atomically.
+     */
+    reserve(capMicros: number, estimateMicros: number): Promise<SpendReservation>;
+    /** Replace a reservation with the provider-reported cost. */
+    commit(id: string, costMicros: number): Promise<void>;
+    /** Drop a reservation (the call was not billed). */
+    release(id: string): Promise<void>;
+    /** Add a cost with no reservation. */
+    record(costMicros: number): Promise<void>;
+    /** Stop decisions until the end of the current UTC month (403 key limit). */
+    markKeyLimited(): Promise<void>;
+    /** Current month-to-date state; `null` when unreadable. */
+    status(): Promise<SpendStatus | null>;
+}
+/**
+ * The UTC month of `epochMs`, `YYYY-MM`.
+ *
+ * @param epochMs - Epoch milliseconds.
+ * @returns The month string.
+ */
+export declare function utcMonth(epochMs: number): string;
+/**
+ * Epoch ms of the first instant of the next UTC month.
+ *
+ * @param epochMs - Epoch milliseconds.
+ * @returns Start of the next UTC month.
+ */
+export declare function startOfNextUtcMonth(epochMs: number): number;
+/** Clock option shared by both ledgers. */
+export interface SpendLedgerOptions {
+    /** Wall clock, epoch ms. Default `Date.now`. */
+    readonly now?: () => number;
+}
+/**
+ * A process-local ledger (tests, callers that must not touch disk).
+ *
+ * @param opts - Clock.
+ * @returns A {@link SpendLedger} that does NOT coordinate across processes.
+ */
+export declare function createMemorySpendLedger(opts?: SpendLedgerOptions): SpendLedger;
+/** Options for {@link createFileSpendLedger}. */
+export interface FileSpendLedgerOptions extends SpendLedgerOptions {
+    /** Ledger path. Default {@link defaultSpendStatePath}. */
+    readonly statePath?: string;
+}
+/**
+ * Default ledger location: `<cleoHome>/decide/spend.json`.
+ *
+ * @returns Absolute path.
+ */
+export declare function defaultSpendStatePath(): string;
+/**
+ * A ledger shared by every process on the machine through a locked JSON file.
+ * A lock or read failure (including a corrupt file) makes `reserve` answer
+ * `unavailable`, which the client treats as a fallback: the cap fails closed,
+ * like the request bucket.
+ *
+ * @param opts - Clock and state path.
+ * @returns A {@link SpendLedger}.
+ */
+export declare function createFileSpendLedger(opts?: FileSpendLedgerOptions): SpendLedger;
+/**
+ * Whether the ledger file is readable.
+ *
+ * @param statePath - Ledger path. Default {@link defaultSpendStatePath}.
+ * @returns `ok`, `absent`, `corrupt` or `unavailable` (unreadable for another reason).
+ */
+export declare function inspectSpendLedger(statePath?: string): SpendLedgerHealth;
+/** Receipt of {@link resetSpendLedger}. */
+export interface SpendResetReceipt {
+    /** Ledger path. */
+    readonly statePath: string;
+    /** Health before the reset. */
+    readonly before: SpendLedgerHealth;
+    /** Where the previous file was moved, when there was one. */
+    readonly backupPath?: string;
+    /** ISO time of the reset. */
+    readonly resetAt: string;
+    /** Month-to-date spend carried into the new ledger (0 when the old file was unreadable). */
+    readonly spentMicros: number;
+    /** Whether `force` overrode the refusal to reset a readable ledger. */
+    readonly forced: boolean;
+}
+/** Options for {@link resetSpendLedger}. */
+export interface SpendResetOptions {
+    /**
+     * Reset a ledger that is NOT corrupt. The month-to-date spend is still
+     * carried over; only in-flight reservations and the key-limit stop are
+     * cleared (e.g. after raising the key's limit in the provider console).
+     */
+    readonly force?: boolean;
+}
+/**
+ * Thrown by {@link resetSpendLedger} when the ledger is not corrupt and
+ * `force` was not given. A reached cap is not a fault to repair.
+ */
+export declare class SpendResetRefusedError extends Error {
+    /** Health of the ledger that was not reset. */
+    readonly health: SpendLedgerHealth;
+    /** @param health - The ledger's health (anything but `corrupt`). */
+    constructor(health: SpendLedgerHealth);
+}
+/**
+ * Reset the ledger (`cleo decide budget reset`): move the current file aside
+ * to `spend.json.reset-<iso>` and start a new ledger for this month. The
+ * repair for a corrupt ledger, which otherwise fails closed forever.
+ *
+ * Refuses (throws {@link SpendResetRefusedError}) unless the ledger is
+ * corrupt or `opts.force` is set, so an agent cannot reset its way past a
+ * reached cap. When the old file is readable its month-to-date spend
+ * (expired reservations included) is carried over; only a corrupt file's
+ * spend is lost, and the moved file is kept as the receipt of it.
+ *
+ * @param statePath - Ledger path. Default {@link defaultSpendStatePath}.
+ * @param now - Wall clock, epoch ms.
+ * @param opts - `force` resets a ledger that is not corrupt.
+ * @returns What was reset, the spend carried over and where the old file went.
+ * @throws {SpendResetRefusedError} When the ledger is not corrupt and `force` is not set.
+ */
+export declare function resetSpendLedger(statePath?: string, now?: number, opts?: SpendResetOptions): Promise<SpendResetReceipt>;
+//# sourceMappingURL=spend.d.ts.map

package/dist/decide/spend.d.ts.map

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