@ashlr/hub 3.2.6 → 3.3.0

package/dist/core/fleet/post-merge-credit.js

@@ -1,11 +1,56 @@
 /**
- * Positive post-merge learning authority.
+ * Positive post-merge learning authority — the release protocol.
  *
- * A realized merge is an immutable operational fact, not proof that the change
- * remained beneficial. Only the future purpose-built release protocol may mint
- * this label. Existing merge receipts and observation-only stability witnesses
- * deliberately do not satisfy it.
+ * A realized merge is an immutable operational fact, not proof that the
+ * change remained beneficial. This module is the ONLY place allowed to mint
+ * "post-merge credit release" authority, and it does so conservatively:
+ *
+ *   1. The proposal must carry an AUTHENTICATED realized-merge witness
+ *      (authenticatedRealizedMergeOf — binds to this exact proposal via a
+ *      local receipt HMAC or host reconciliation; shape alone is never
+ *      authority).
+ *   2. At least MIN_POST_MERGE_OBSERVATION_WINDOW_MS must have elapsed since
+ *      the merge was observed. The regression sentinel / outcome watcher
+ *      (outcome-watcher.ts) sweeps merged proposals on a 6h throttle with a
+ *      7-day follow-up window; 14 days gives ~2x that follow-up window and
+ *      dozens of scan cycles of headroom before we trust the silence.
+ *   3. The signed, observation-only post-merge-observations ledger
+ *      (post-merge-observations.ts) must contain NO adverse record
+ *      ('regressed' | 'reverted' | 'followed-up') for this exact
+ *      (repo, proposalId, mergeCommit) event, and the ledger must have read
+ *      back healthy/complete (a degraded read fails closed — we never treat
+ *      "couldn't check" as "checked clean").
+ *
+ * That ledger is adverse-only (it never records a positive "we checked, it's
+ * clean" row), so eligibility here is inherently a "silence after a
+ * conservative window" heuristic, not a positive confirmation. That is a
+ * known, documented limitation — see sweepPostMergeCreditReleases' doc
+ * comment — not an oversight.
+ *
+ * MINTING: hasReleasedPostMergeCredit(labelBasis) verifies a self-describing,
+ * HMAC-signed token — NOT bare string equality against
+ * POST_MERGE_CREDIT_RELEASE_LABEL. This is deliberate: several downstream
+ * consumers persist labelBasis-shaped fields on structures that are, at least
+ * in tests and in caller-authored proposal/ledger data, fully attacker/
+ * test-controlled. A bare literal is trivially replayable; only a value
+ * carrying a valid local-key HMAC over the specific (repo, proposalId,
+ * mergeCommit) event can pass. isPostMergeCreditReleaseLabel() remains
+ * "structural recognition only" — matching the bare literal — for the
+ * existing defensive filters elsewhere that specifically reject the
+ * unauthenticated literal (e.g. skill-records.ts, decisions-ledger.ts).
  */
+import { createHmac, timingSafeEqual } from 'node:crypto';
+import { resolve } from 'node:path';
+import { loadOrCreateKey, signSkillCardAttestation } from '../foundry/provenance.js';
+import { authenticatedRealizedMergeOf } from '../inbox/realized-merge.js';
+import { listProposalsDetailed } from '../inbox/store.js';
+import { causalMetadataFromProposal } from '../learning/causal.js';
+import { readDecisions, recordDecision } from './decisions-ledger.js';
+import { postMergeObservationEventId, readPostMergeObservations } from './post-merge-observations.js';
+import { skillCardContentHash } from './skill-attestation.js';
+// ---------------------------------------------------------------------------
+// Structural constants
+// ---------------------------------------------------------------------------
 export const POST_MERGE_CREDIT_POLICY_VERSION = 'post-merge-credit-v1';
 export const POST_MERGE_CREDIT_RELEASE_LABEL = 'post-merge-credit-release-v1';
 /** Structural recognition only; this string is not release authority. */
@@ -13,11 +58,306 @@ export function isPostMergeCreditReleaseLabel(labelBasis) {
     return labelBasis === POST_MERGE_CREDIT_RELEASE_LABEL;
 }
 /**
- * No authenticated release verifier exists in this protocol version.
- * Deliberately return false even for the reserved label so raw ledgers,
- * injected dependencies, and caller-controlled metadata cannot mint credit.
+ * Minimum wall-clock time since the realized merge before credit MAY be
+ * released. See module doc for rationale (~2x the outcome-watcher follow-up
+ * window, dozens of throttled scan cycles of headroom).
+ */
+export const MIN_POST_MERGE_OBSERVATION_WINDOW_MS = 14 * 24 * 60 * 60 * 1000;
+/** Domain-separated HMAC payload prefix for minted credit tokens. */
+const CREDIT_TOKEN_DOMAIN = 'ashlr:post-merge-credit-release:v1';
+/**
+ * Both segments are truncated to 24 hex chars (96 bits each) — plenty for
+ * MAC-forgery infeasibility and event-identifier collision-resistance at
+ * fleet scale, and DELIBERATELY short for two independent reasons discovered
+ * empirically (see test/post-merge-credit-release.test.ts):
+ *   1. decisions-ledger.ts's generic secret-scrubber (util/scrub.ts) redacts
+ *      any bare 64+ char hex run as a likely API key/hash — a 64-char segment
+ *      would be silently corrupted the moment it passed through
+ *      recordDecision().
+ *   2. recordDecision() -> sanitizeDecisionEntry() unconditionally ends with
+ *      normalizeDecisionLearningFields() (learning/causal.ts), which re-runs
+ *      causalMetadata() and applies boundedText(labelBasis, 80) — ANY
+ *      labelBasis over 80 chars is silently truncated, with no way to opt
+ *      out from a caller outside that module. The full token
+ *      ("post-merge-credit-release-v1:" (30 chars) + eventRef + ':' + mac)
+ *      must fit in 80 chars total, so each hex segment is capped at 24
+ *      (30 + 24 + 1 + 24 = 79).
+ * Neither constraint is owned by this module; 24 hex chars satisfies both
+ * with margin.
+ */
+const CREDIT_REF_HEX_CHARS = 24;
+/** `post-merge-credit-release-v1:<event-ref-hex32>:<hmac-hex32>` */
+const CREDIT_TOKEN_RE = new RegExp(`^post-merge-credit-release-v1:([a-f0-9]{${CREDIT_REF_HEX_CHARS}}):([a-f0-9]{${CREDIT_REF_HEX_CHARS}})$`);
+/** Truncate a full sha256 eventId to the reference used inside the token. */
+function creditEventRef(eventId) {
+    return eventId.slice(0, CREDIT_REF_HEX_CHARS);
+}
+function computeCreditMac(eventRef) {
+    try {
+        return createHmac('sha256', loadOrCreateKey())
+            .update(`${CREDIT_TOKEN_DOMAIN}:${eventRef}`)
+            .digest('hex')
+            .slice(0, CREDIT_REF_HEX_CHARS);
+    }
+    catch {
+        return null;
+    }
+}
+function equalHex(left, right) {
+    try {
+        const a = Buffer.from(left, 'hex');
+        const b = Buffer.from(right, 'hex');
+        return a.length === b.length && a.length > 0 && timingSafeEqual(a, b);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Verify that `labelBasis` is a validly-signed post-merge-credit release
+ * token minted by evaluatePostMergeCreditRelease. Pure, synchronous
+ * (host-local key read only), never throws. Deliberately rejects the bare
+ * POST_MERGE_CREDIT_RELEASE_LABEL literal and any other string that is not a
+ * correctly-formed, correctly-signed token — so raw ledgers, injected
+ * dependencies, and caller-controlled metadata cannot mint credit.
+ */
+export function hasReleasedPostMergeCredit(labelBasis) {
+    try {
+        if (typeof labelBasis !== 'string')
+            return false;
+        const match = CREDIT_TOKEN_RE.exec(labelBasis);
+        if (!match)
+            return false;
+        const eventRef = match[1];
+        const mac = match[2];
+        const expected = computeCreditMac(eventRef);
+        if (!expected)
+            return false;
+        return equalHex(mac, expected);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Determine whether `proposal` is eligible for post-merge credit release
+ * RIGHT NOW, and mint the signed token when it is. Fail-closed on every
+ * ambiguous path (missing witness, unparseable timestamp, window not yet
+ * elapsed, degraded/incomplete observation-ledger read, any adverse
+ * observation for this exact merge event, signing failure). Never throws.
+ *
+ * This function does NOT persist anything — see sweepPostMergeCreditReleases
+ * for the write-back that records a minted label to the decisions ledger.
+ */
+export function evaluatePostMergeCreditRelease(proposal, opts = {}) {
+    try {
+        if (!proposal || typeof proposal.id !== 'string' || proposal.id.length === 0) {
+            return { eligible: false, label: null, reason: 'no-authenticated-merge-witness' };
+        }
+        const evidence = authenticatedRealizedMergeOf(proposal);
+        if (!evidence || typeof proposal.repo !== 'string' || proposal.repo.length === 0) {
+            return { eligible: false, label: null, reason: 'no-authenticated-merge-witness' };
+        }
+        const observedAtIso = evidence.source === 'github-host'
+            ? evidence.reconciliation.observedAt
+            : evidence.observedAt;
+        const mergedAtMs = Date.parse(observedAtIso);
+        if (!Number.isFinite(mergedAtMs)) {
+            return { eligible: false, label: null, reason: 'invalid-merge-timestamp' };
+        }
+        const nowMs = opts.nowMs ?? Date.now();
+        if (nowMs < mergedAtMs || nowMs - mergedAtMs < MIN_POST_MERGE_OBSERVATION_WINDOW_MS) {
+            return { eligible: false, label: null, reason: 'observation-window-not-elapsed' };
+        }
+        let repoAbs;
+        try {
+            repoAbs = resolve(proposal.repo);
+        }
+        catch {
+            return { eligible: false, label: null, reason: 'no-authenticated-merge-witness' };
+        }
+        const eventId = postMergeObservationEventId({
+            repo: repoAbs,
+            proposalId: proposal.id,
+            mergeCommit: evidence.mergeCommitOid.toLowerCase(),
+        });
+        // Adverse-only ledger: absence of a row is the only "clean" signal it can
+        // ever give us. A degraded/incomplete read must NOT be treated as clean.
+        const read = readPostMergeObservations({ requireComplete: true });
+        if (read.sourceState === 'degraded' || !read.complete) {
+            return { eligible: false, label: null, reason: 'observation-ledger-degraded' };
+        }
+        if (read.observations.some((observation) => observation.eventId === eventId)) {
+            return { eligible: false, label: null, reason: 'adverse-outcome-observed' };
+        }
+        const eventRef = creditEventRef(eventId);
+        const mac = computeCreditMac(eventRef);
+        if (!mac)
+            return { eligible: false, label: null, reason: 'signing-unavailable' };
+        return {
+            eligible: true,
+            label: `${POST_MERGE_CREDIT_RELEASE_LABEL}:${eventRef}:${mac}`,
+            reason: 'clean-window-elapsed',
+        };
+    }
+    catch {
+        return { eligible: false, label: null, reason: 'error' };
+    }
+}
+// ---------------------------------------------------------------------------
+// sweepPostMergeCreditReleases — periodic write-back
+// ---------------------------------------------------------------------------
+/**
+ * Bound on candidates inspected per sweep pass — mirrors outcome-watcher.ts's
+ * own bounding so a large backlog degrades gracefully instead of blocking.
+ */
+const MAX_SWEEP_CANDIDATES = 200;
+/**
+ * Sweep applied proposals for newly-eligible post-merge credit and record it
+ * to the decisions ledger (a new 'merged' row with the signed labelBasis
+ * token — decisions-ledger.ts's own newest-row-wins semantics let this
+ * supersede the plain merge-fact row written at merge time). Idempotent: a
+ * proposal that already carries a released decision row is left alone.
+ *
+ * KNOWN LIMITATION (by design, not a bug): the post-merge-observations ledger
+ * only ever records ADVERSE outcomes. This sweep therefore releases credit on
+ * "no adverse record after a conservative window", not on a positive
+ * "actively confirmed clean" signal — there is no such positive signal
+ * anywhere in the fleet today. If a repo's outcome-watcher coverage were
+ * somehow disabled for a specific proposal's repo (not enrolled, or the local
+ * clone was deleted), this sweep cannot detect that and would release credit
+ * on elapsed time alone. The MIN_POST_MERGE_OBSERVATION_WINDOW_MS margin
+ * exists specifically to bound that risk; closing it fully would require
+ * outcome-watcher.ts (unowned here) to also persist a positive "swept clean"
+ * marker per merge event.
+ *
+ * SCALING NOTE: unlike outcome-watcher.ts, this sweep has no persistent
+ * cursor — it re-scans applied proposals from the top of listProposalsDetailed
+ * every pass, bounded by MAX_SWEEP_CANDIDATES. At small-to-moderate applied-
+ * proposal counts this converges fine (already-released proposals are
+ * skipped instantly via the decisions-ledger dedup check, so the cap mostly
+ * matters for proposals still awaiting their window). At very large scale a
+ * persistent cursor (mirroring monitoring-cursor.ts) would be needed to
+ * guarantee every proposal eventually gets swept; out of scope here.
+ *
+ * Never throws.
+ */
+export function sweepPostMergeCreditReleases(opts = {}) {
+    const result = {
+        scanned: 0, released: 0, skipped: 0, sourceComplete: true,
+    };
+    try {
+        const nowMs = opts.nowMs ?? Date.now();
+        let proposals;
+        if (typeof opts.listProposals === 'function') {
+            try {
+                proposals = opts.listProposals();
+            }
+            catch {
+                proposals = [];
+            }
+        }
+        else {
+            const read = listProposalsDetailed({ status: 'applied', requireComplete: true });
+            if (!read.complete || read.sourceState === 'degraded') {
+                result.sourceComplete = false;
+                return result;
+            }
+            proposals = read.proposals;
+        }
+        let inspected = 0;
+        for (const proposal of proposals) {
+            if (proposal.status !== 'applied')
+                continue;
+            if (inspected >= MAX_SWEEP_CANDIDATES) {
+                result.sourceComplete = false;
+                break;
+            }
+            inspected++;
+            result.scanned++;
+            try {
+                const existing = readDecisions({ proposalId: proposal.id, requireComplete: true });
+                const existingQuality = existing.sourceQuality;
+                if (existingQuality && (existingQuality.sourceState === 'degraded' || existingQuality.complete === false)) {
+                    result.skipped++;
+                    result.sourceComplete = false;
+                    continue;
+                }
+                const alreadyReleased = existing.some((entry) => entry.action === 'merged' && hasReleasedPostMergeCredit(entry.labelBasis));
+                if (alreadyReleased)
+                    continue;
+                const eligibility = evaluatePostMergeCreditRelease(proposal, { nowMs });
+                if (!eligibility.eligible || !eligibility.label) {
+                    result.skipped++;
+                    continue;
+                }
+                const ts = new Date(nowMs).toISOString();
+                recordDecision({
+                    ts,
+                    proposalId: proposal.id,
+                    // NOTE: labelBasis is intentionally NOT routed through
+                    // causalMetadataFromProposal's `input.labelBasis` — causalMetadata()
+                    // (learning/causal.ts) applies boundedText(value, 80) to that field,
+                    // which would silently truncate our signed token (>80 chars) into
+                    // an unverifiable fragment. Set it directly below instead, after the
+                    // spread, so the full token survives.
+                    ...causalMetadataFromProposal(proposal, { ts, learningSource: 'outcome-record' }),
+                    action: 'merged',
+                    verdict: 'applied',
+                    labelBasis: eligibility.label,
+                    repo: proposal.repo ?? '',
+                    engine: proposal.engineModel ?? '',
+                    model: '',
+                });
+                result.released++;
+            }
+            catch {
+                result.skipped++;
+            }
+        }
+        return result;
+    }
+    catch {
+        return result;
+    }
+}
+// ---------------------------------------------------------------------------
+// attestPostMergeCreditSkillCard — dedicated signing boundary
+// ---------------------------------------------------------------------------
+/**
+ * Sign a SkillCard that legitimately carries released post-merge credit.
+ *
+ * skill-attestation.ts's generic attestSkillCard() deliberately refuses any
+ * card for which hasReleasedPostMergeCredit(card.labelBasis) is true — its
+ * signature payload doesn't cover the credit-release claim, so it must not
+ * be the thing vouching for it. This module owns that proof, so it owns this
+ * signing boundary too: same crypto primitive (signSkillCardAttestation),
+ * same payload shape, so verifyAttestedSkillCard() on the read side still
+ * validates cards signed here — only the gating differs (this function signs
+ * ONLY when hasReleasedPostMergeCredit is true; attestSkillCard signs only
+ * when it is false).
+ *
+ * Never throws.
  */
-export function hasReleasedPostMergeCredit(_labelBasis) {
-    return false;
+export function attestPostMergeCreditSkillCard(card) {
+    try {
+        if (!hasReleasedPostMergeCredit(card.labelBasis))
+            return null;
+        const diffHash = card.verification?.diffHash;
+        if (!card.proposalId || !diffHash)
+            return null;
+        const contentHash = skillCardContentHash(card);
+        const attestation = signSkillCardAttestation({
+            contentHash,
+            skillId: card.skillId,
+            revision: card.revision,
+            proposalId: card.proposalId,
+            diffHash,
+        });
+        return attestation ? { ...card, contentHash, attestation } : null;
+    }
+    catch {
+        return null;
+    }
 }
 //# sourceMappingURL=post-merge-credit.js.map

package/dist/core/fleet/post-merge-credit.js.map

@@ -1 +1 @@
-{"version":3,"file":"post-merge-credit.js","sourceRoot":"","sources":["../../../src/core/fleet/post-merge-credit.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,gCAAgC,GAAG,sBAA+B,CAAC;AAChF,MAAM,CAAC,MAAM,+BAA+B,GAAG,8BAAuC,CAAC;AAEvF,yEAAyE;AACzE,MAAM,UAAU,6BAA6B,CAAC,UAAmB;IAC/D,OAAO,UAAU,KAAK,+BAA+B,CAAC;AACxD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,0BAA0B,CAAC,WAAoB;IAC7D,OAAO,KAAK,CAAC;AACf,CAAC"}
+{"version":3,"file":"post-merge-credit.js","sourceRoot":"","sources":["../../../src/core/fleet/post-merge-credit.ts"],"names":[],"mappings":"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"}

package/dist/core/fleet/quota.d.ts

@@ -6,30 +6,70 @@
  * ledger records each dispatch and answers "how many in the last window?" and
  * "are we still under the configured cap?".
  *
- * Persistence discipline mirrors daemon/state.ts EXACTLY:
- *  - Atomic writes (tmp file + POSIX rename).
- *  - NEVER throws — load returns a fresh empty ledger on missing/corrupt file;
- *    record swallows any persistence error.
+ * Observation compatibility remains deliberately tolerant: load returns a fresh
+ * empty ledger on missing/corrupt state and recordUse remains best-effort. The
+ * authority-bearing reservation API is stricter:
+ *  - One local-store lock serializes read/check/append publication.
+ *  - Configured limits fail closed on ambiguous or unavailable persistence.
+ *  - Reservation identities are hashed and idempotent across retries.
+ *  - The replacement file and containing directory are fsynced before success.
  *  - mkdir -p the parent dir.
- *  - Bounded history (last ~2000 events).
+ *  - Bounded authority history (last 2000 events per known backend, max 30d).
  *  - Homedir re-resolved at call time so tests can relocate HOME.
  *
  * No new runtime deps; node builtins only. evalQuota mirrors evalBudget's
  * three-level (ok/warn/over) semantics with a null-cap-disabled path.
  */
 import type { AshlrConfig, EngineId } from '../types.js';
+import { type LocalStoreLock } from './local-store-lock.js';
 /** A single recorded backend dispatch. */
 export interface FleetQuotaEvent {
     /** Backend that was dispatched. */
     backend: EngineId;
     /** ISO timestamp of the dispatch. */
     ts: string;
+    /** Opaque idempotency identity for an authority-bearing reservation. */
+    reservationIdHash?: string;
 }
 /** The persisted fleet quota ledger. */
 export interface FleetQuota {
     /** Bounded list of recent dispatch events (oldest first). */
     events: FleetQuotaEvent[];
 }
+export interface FleetQuotaReservationRequest {
+    backend: EngineId;
+    dispatchId: string;
+}
+export interface FleetQuotaReservationReceipt {
+    backend: EngineId;
+    status: 'unlimited' | 'reserved';
+    used: number;
+    limit: number | null;
+}
+export type FleetQuotaReservationResult = {
+    kind: 'unlimited' | 'reserved';
+    launchAuthorized: true;
+    reservations: FleetQuotaReservationReceipt[];
+} | {
+    kind: 'invalid' | 'duplicate' | 'conflict' | 'exhausted' | 'unavailable' | 'capacity';
+    launchAuthorized: false;
+    backend?: EngineId;
+    used?: number;
+    limit?: number;
+    /** True means the durable reservation exists, but this call must not launch. */
+    reservationConsumed?: boolean;
+};
+export interface FleetQuotaReservationOptions {
+    /** Bounded local lock wait. Defaults to 250ms. */
+    lockWaitMs?: number;
+}
+export type FleetQuotaAuthorityHealth = 'unlimited' | 'healthy' | 'invalid' | 'unavailable' | 'capacity';
+interface FleetQuotaTestHooks {
+    now?: () => number;
+    releaseLock?: (lock: LocalStoreLock) => boolean;
+}
+/** Test-only fault injection; production callers must never configure this. */
+export declare function setFleetQuotaTestHooksForTests(hooks?: FleetQuotaTestHooks): void;
 /**
  * Convert a window label to milliseconds. Extends rollup.ts's day-granularity
  * vocabulary with sub-day windows used by rate limits. Unknown labels fall back
@@ -38,15 +78,37 @@ export interface FleetQuota {
 export declare function windowToMs(window: string): number;
 /** Absolute path to the fleet quota ledger file. */
 export declare function fleetQuotaPath(): string;
+/**
+ * Private authority ledger. It is deliberately separate from quota.json:
+ * quota.json remains backwards-compatible, best-effort operator telemetry,
+ * while this file is the fail-closed idempotency/capacity boundary.
+ */
+export declare function fleetQuotaReservationPath(): string;
+/** Lock path used by the authority-bearing quota reservation transaction. */
+export declare function fleetQuotaReservationLockPath(): string;
 /**
  * Read and parse fleetQuotaPath(). NEVER throws.
  * Returns a fresh empty ledger when the file is missing or malformed.
  */
 export declare function loadFleetQuota(): FleetQuota;
 /**
- * Append a dispatch event for `backend` (ts = now) and persist. Never throws.
+ * Append an actual dispatch-attempt event for `backend` (ts = now) and
+ * persist. Never throws. This is intentionally not launch authority; the
+ * strict reservation ledger above is separate so legacy 0644 telemetry files
+ * cannot block or overwrite authority state.
  */
 export declare function recordUse(backend: EngineId): void;
+export declare function reserveFleetQuotaUses(requests: readonly FleetQuotaReservationRequest[], cfg: AshlrConfig, options?: FleetQuotaReservationOptions): FleetQuotaReservationResult;
+/** Single-dispatch convenience wrapper over the atomic batch transaction. */
+export declare function reserveFleetQuotaUse(backend: EngineId, cfg: AshlrConfig, dispatchId: string, options?: FleetQuotaReservationOptions): FleetQuotaReservationResult;
+/** Read-only conservative health projection for operator/status surfaces. */
+export declare function inspectFleetQuotaAuthority(backend: EngineId, cfg: AshlrConfig, now?: number): FleetQuotaAuthorityHealth;
+/**
+ * Quota standing derived from reserved authority slots, not attempt telemetry.
+ * This intentionally counts conservative pre-effect reservations that may not
+ * have reached a provider: those slots still consume the configured window.
+ */
+export declare function evalFleetQuotaAuthority(backend: EngineId, cfg: AshlrConfig, now?: number): 'ok' | 'warn' | 'over' | 'unlimited';
 /**
  * Count events for `backend` whose ts is within the last `windowMs`
  * (ts >= now - windowMs). Reads the ledger internally; `now` is injectable for
@@ -58,7 +120,11 @@ export declare function usesInWindow(backend: EngineId, windowMs: number, now?:
  *
  * Mirrors evalBudget's null-cap-disabled logic: when no
  * cfg.foundry.limits[backend] is configured, the backend is unlimited ⇒ always
- * within limit. Otherwise true iff usesInWindow(...) < limit.max. `now` is
+ * within limit. Healthy configured state follows reservation standing so a
+ * consumed slot can route to an eligible peer. Invalid, unavailable, or
+ * capacity-ambiguous authority deliberately remains advisory-eligible here so
+ * the final provider-effect reservation returns the structured fail-closed
+ * refusal instead of silently capability-downgrading to builtin. `now` is
  * injectable for tests.
  */
 export declare function withinLimit(backend: EngineId, cfg: AshlrConfig, now?: number): boolean;
@@ -68,3 +134,4 @@ export declare function withinLimit(backend: EngineId, cfg: AshlrConfig, now?: n
  * cap is configured the backend is unlimited ⇒ always 'ok'. `now` is injectable.
  */
 export declare function evalQuota(backend: EngineId, cfg: AshlrConfig, now?: number): 'ok' | 'warn' | 'over';
+export {};