opencode-swarm 7.148.0 → 7.148.1

package/dist/hooks/skill-usage-log.d.ts

@@ -3,9 +3,19 @@
  *
  * Writes one JSONL line per skill-usage event to `.swarm/skill-usage.jsonl`.
  * Follows the same append-only JSONL pattern as knowledge-application.jsonl.
+ *
+ * Issue #2038 — the JSONL is the **operational** stream and is bounded by a
+ * hard global byte/age/count budget (`SKILL_USAGE_LIMITS`). The
+ * **authoritative** record of un-consumed feedback lives in the sidecar
+ * `.swarm/skill-usage-pending.json` (see `skill-usage-pending.ts`), so
+ * evicting from this stream can lose no correctness signal: every actionable
+ * verdict is enqueued in the sidecar *before* it is appended here.
  */
 import * as fs from 'node:fs';
 import type { ConfidenceFloorOptions } from './knowledge-store.js';
+import { bumpKnowledgeConfidenceBatchResult } from './knowledge-store.js';
+import { enqueueSkillUsageFeedback, isSkillUsageQueueUnderPressure, readPendingManifest, type SkillUsageCoverage } from './skill-usage-pending.js';
+export { isSkillWindowTrustworthy, SKILL_USAGE_LIMITS, type SkillUsageCoverage, type SkillUsagePendingRecord, } from './skill-usage-pending.js';
 /** Single entry in the skill-usage audit log. */
 export interface SkillUsageEntry {
     /** Auto-generated unique identifier (UUID v4). */
@@ -51,9 +61,24 @@ export interface PruneResult {
     pruned: number;
     /** Number of entries remaining in the log. */
     remaining: number;
-    /** Error message when the write/rename step fails; absent on success. */
+    /**
+     * Error message when the compaction could not be published; absent on
+     * success. Set both when the stream write/rename fails and when the
+     * manifest save that now precedes the rewrite fails (issue #2038 residual
+     * R1) — in the latter case nothing was dropped, so `pruned` is 0.
+     */
     error?: string;
 }
+/**
+ * What the window returned by a read can and cannot answer (issue #2038,
+ * requirement 4 / BLK-5). `complete === false` means entries the caller might
+ * have expected are not in `entries` — either this read was byte-truncated, or
+ * compaction has evicted history.
+ */
+export interface SkillUsageReadCoverage extends SkillUsageCoverage {
+    /** True when THIS read was bounded by `readMaxBytes` and saw only a suffix. */
+    truncatedRead: boolean;
+}
 /**
  * Normalize a compliance verdict to the canonical spelling.
  * The sole producer (`skill-propagation-gate.ts`) lowercases the regex
@@ -67,7 +92,8 @@ export declare function normalizeComplianceVerdict(verdict: string): string;
 /**
  * Test-only dependency-injection seam. Tests override these without
  * `mock.module` (which leaks across files in Bun's shared test-runner).
- * Restore in `afterEach`.
+ * Restore in `afterEach`, and call `_resetSkillUsageMaintenanceState()` to
+ * clear module-scoped maintenance counters.
  */
 export declare const _internals: {
     generateId: () => string;
@@ -81,33 +107,112 @@ export declare const _internals: {
     openSync: typeof fs.openSync;
     readSync: typeof fs.readSync;
     closeSync: typeof fs.closeSync;
+    unlinkSync: typeof fs.unlinkSync;
     pruneSkillUsageLog: typeof pruneSkillUsageLog;
     resolveSourceKnowledgeIds: typeof resolveSourceKnowledgeIds;
     applySkillUsageFeedback: typeof applySkillUsageFeedback;
+    /** Test seam: lets FB-008-style tests drive `failed:true` / partial-apply through the real consumption path without `mock.module`. */
+    bumpKnowledgeConfidenceBatchResult: typeof bumpKnowledgeConfidenceBatchResult;
     parseGeneratedFromKnowledge: typeof parseGeneratedFromKnowledge;
     computeComplianceByVersion: typeof computeComplianceByVersion;
     normalizeComplianceVerdict: typeof normalizeComplianceVerdict;
-    readFeedbackAppliedEntryIds: typeof readFeedbackAppliedEntryIds;
     appendFeedbackAppliedMarker: typeof appendFeedbackAppliedMarker;
+    /**
+     * Streaming read seam (issue #2038, BLK-11). The one-time migration and the
+     * compaction pass must see EVERY line of a legacy file — they are bounded in
+     * peak memory and per-read chunk size, never byte-truncated — so they cannot
+     * use `readFileSync` and cannot use the byte-bounded steady-state funnel.
+     */
+    streamLogLines: typeof streamLogLines;
+    enqueueSkillUsageFeedback: typeof enqueueSkillUsageFeedback;
+    isQueueUnderPressure: typeof isSkillUsageQueueUnderPressure;
+    readPendingManifest: typeof readPendingManifest;
 };
-declare function readFeedbackAppliedEntryIds(directory: string): Set<string>;
+/**
+ * Reset the throttled-maintenance counters so an unswept run in Bun's shared
+ * test-runner process cannot shift a later test's first maintenance pass.
+ */
+export declare function _resetSkillUsageMaintenanceState(): void;
+/**
+ * Legacy acknowledgment writer.
+ *
+ * Post-migration, acknowledgment is the sidecar's job: consumption dequeues
+ * the record instead of appending a marker line, which is what removes the
+ * unbounded marker accumulation described in issue #2038. This function is
+ * retained so that a pre-migration on-disk log written by an older build
+ * still round-trips through the reader above.
+ */
 declare function appendFeedbackAppliedMarker(directory: string, processedEntryIds: string[]): void;
+/**
+ * Read `filePath` in `chunkBytes` slices and hand each complete, non-empty
+ * line to `onLine`. Peak resident memory is O(chunkBytes), independent of the
+ * file size — the metric requirement 4 actually cares about for the one-time
+ * migration and the compaction pass (BLK-11).
+ *
+ * A single line longer than 4x the chunk bound cannot be assembled without
+ * unbounded buffering; it is dropped and reported through `onOverlongLine` so
+ * the caller can fold it into the durable `corrupt` counter rather than
+ * losing it silently.
+ */
+declare function streamLogLines(filePath: string, chunkBytes: number, onLine: (line: string) => void, onOverlongLine?: () => void): void;
 /**
  * Validate and append a single skill-usage entry to the JSONL log.
  *
  * The `id` field is auto-generated; callers provide all other fields.
  * Uses synchronous I/O for consistency with the JSONL append pattern.
+ *
+ * Two behaviors matter for issue #2038:
+ *
+ * 1. **Actionable verdicts are enqueued FIRST, then appended** (approved plan
+ *    §2.2). A crash between the two leaves at worst an orphan queue record
+ *    with no stats row — harmless, the record is self-sufficient. The reverse
+ *    order leaves an authoritative gap. A failed enqueue **aborts the append
+ *    and propagates**; the sole actionable caller already handles a throw.
+ * 2. **The `not_checked` path is a hard no-op for the queue** — no lock, no
+ *    queue read-modify-write. That keeps O(paths x queue) synchronous I/O out
+ *    of the hot delegation loop, and it is safe because `not_checked` carries
+ *    no correctness signal. Under queue pressure those optional appends stop
+ *    entirely (requirement 5).
  */
 export declare function appendSkillUsageEntry(directory: string, entry: Omit<SkillUsageEntry, 'id'>): void;
+/**
+ * Read and parse skill-usage entries together with the coverage of the window
+ * they came from (issue #2038, BLK-5).
+ *
+ * Additive: `readSkillUsageEntries` remains a wrapper returning `entries`
+ * only, so the DI seams in `corpus.ts` / `curator.ts` that are typed as
+ * `typeof readSkillUsageEntries` keep working unchanged.
+ *
+ * Takes no lock and never migrates — reads must stay cheap and must never
+ * mutate the store.
+ */
+export declare function readSkillUsageEntriesWithCoverage(directory: string, options?: SkillUsageFilterOptions): {
+    entries: SkillUsageEntry[];
+    coverage: SkillUsageReadCoverage;
+};
 /**
  * Read and parse skill-usage entries from the JSONL log, optionally filtered.
  *
  * Malformed lines are silently skipped (no throw). Returns an empty array
- * if the log file does not exist.
+ * if the log file does not exist. Bounded by `SKILL_USAGE_LIMITS.readMaxBytes`;
+ * use {@link readSkillUsageEntriesWithCoverage} when the caller needs to know
+ * whether the window it received is complete.
  */
 export declare function readSkillUsageEntries(directory: string, options?: SkillUsageFilterOptions): SkillUsageEntry[];
 /** Default maximum bytes to read from the end of the log file. */
 export declare const TAIL_BYTES_DEFAULT: number;
+/**
+ * Ceiling for an explicitly requested tail size.
+ *
+ * Deliberately equal to `TAIL_BYTES_DEFAULT`: the tail reader exists to serve
+ * the delegation dedup/scoring window, which is specified as 64 KiB, so an
+ * oversized request is clamped rather than honored. Issue #2038 §5 required
+ * that this ceiling and the global read budget must not disagree *in silence* —
+ * they no longer do, because the bounded read funnel
+ * ({@link readSkillUsageEntriesWithCoverage}) is routed around this constant
+ * and bounds itself with `SKILL_USAGE_LIMITS.readMaxBytes`, reporting
+ * `coverage.truncatedRead` when it cuts.
+ */
 export declare const MAX_TAIL_BYTES: number;
 /**
  * Read the last `maxBytes` of the skill-usage JSONL log and parse matching
@@ -131,11 +236,24 @@ export interface VersionComplianceStats {
 }
 export declare function computeComplianceByVersion(entries: SkillUsageEntry[], skillPath: string): Map<number | undefined, VersionComplianceStats>;
 /**
- * Prune the skill-usage log, keeping at most `maxEntriesPerSkill` entries
- * per unique skillPath. Oldest entries beyond the limit are removed.
+ * Prune the skill-usage log.
  *
- * Writes atomically (temp file + rename). No-op if the log file doesn't
- * exist or all skills are within their limits.
+ * Two budgets are enforced, in this order:
+ * 1. the legacy per-skill FIFO (`maxEntriesPerSkill`, default 500), and
+ * 2. the **hard global** byte / age / count ceiling from `SKILL_USAGE_LIMITS`.
+ *
+ * **BLK-3 — the highest-risk detail of issue #2038.** The old body returned
+ * early with `if (pruned === 0) return ...` immediately after per-skill
+ * pruning, so in the reported scenario — thousands of distinct skills, every
+ * one of them under 500 entries — nothing was ever pruned, the file was never
+ * rewritten, and the 1 MiB trigger simply re-fired on every append. The global
+ * budget is now evaluated by `applyRetention` **before** any early return, and
+ * the rewrite decision below is taken on the union of both budgets plus the
+ * marker set. There is deliberately no `pruned === 0` short-circuit ahead of it.
+ *
+ * Writes atomically (temp file + rename) in **global timestamp order**
+ * (BLK-12) so a rewrite can never push a live session's recent entries out of
+ * the 64 KiB tail window that the delegation dedup preload depends on.
  *
  * @returns Stats about how many entries were pruned and how many remain.
  */
@@ -165,25 +283,30 @@ export declare function resolveSourceKnowledgeIds(directory: string, skillPath:
  */
 declare function parseGeneratedFromKnowledge(content: string): string[];
 /**
- * Read skill-usage entries, resolve source knowledge IDs for each skill,
- * and apply confidence bumps/decays to the originating knowledge entries.
+ * Consume pending skill-usage feedback and apply confidence bumps/decays to
+ * the originating knowledge entries.
+ *
+ * Reads the **authoritative sidecar queue**, never the JSONL stream: the
+ * compliant/violated counts and the per-skill delta are computed from queue
+ * records only, so an entry evicted from the operational stream can never flip
+ * a pending record's delta sign (approved plan §2 corollary).
  *
- * For each unique skillPath with at least one compliance or violated entry:
+ * For each unique skillPath with at least one queued actionable record:
  * 1. Resolve source knowledge UUIDs from the skill's SKILL.md frontmatter.
- * 2. Count compliant and violated events for that skill.
+ * 2. Count compliant and violated records for that skill.
  * 3. Compute net delta: if compliant count > violation count → +0.05; else → -0.1.
- * 4. Call `bumpKnowledgeConfidenceBatch` with the aggregated deltas.
+ * 4. Call `bumpKnowledgeConfidenceBatchResult` with the aggregated deltas.
+ * 5. Dequeue, retain-with-retry, or terminal-dequeue each record per §3.
  *
  * @param directory       - Project root directory.
- * @param options.sinceTimestamp - Optional ISO 8601 cutoff; only process entries after this time.
+ * @param options.sinceTimestamp - Optional ISO 8601 cutoff; only process records after this time.
  * @returns Count of processed skills and total confidence bumps/decays applied.
  */
 export declare function applySkillUsageFeedback(directory: string, options?: {
     sinceTimestamp?: string;
-    /** G2: forwarded to bumpKnowledgeConfidenceBatch. */
+    /** G2: forwarded to bumpKnowledgeConfidenceBatchResult. */
     floorOptions?: ConfidenceFloorOptions;
 }): Promise<{
     processed: number;
     bumps: number;
 }>;
-export {};

package/dist/hooks/skill-usage-pending.d.ts

@@ -0,0 +1,392 @@
+/**
+ * Skill-usage pending sidecar — `.swarm/skill-usage-pending.json` (issue #2038).
+ *
+ * Two files back the skill-usage subsystem:
+ *
+ * 1. `.swarm/skill-usage.jsonl` — the **OPERATIONAL** stream. Pure JSONL usage
+ *    entries, no manifest header line, freely evictable under the global
+ *    byte/age/count budget.
+ * 2. `.swarm/skill-usage-pending.json` — this file, the **AUTHORITATIVE**
+ *    sidecar. A single JSON document holding the pending-feedback queue *and*
+ *    all manifest state: `{ version, migrated, records[], counters{}, coverage{} }`.
+ *
+ * The manifest lives here rather than in a JSONL header line so that
+ * `parseSkillUsageEntry` stays header-free and the tail reader and the full
+ * reader remain on one parser (approved plan §0).
+ *
+ * Evicting an entry from the JSONL can lose no correctness signal because
+ * every actionable verdict (`compliant` / `violated`) is enqueued here
+ * *before* it is appended to the stream (approved plan §2). The queue record
+ * is self-sufficient: consumption computes compliant/violated counts and the
+ * per-skill delta from queue records only, never from JSONL entries.
+ *
+ * All I/O is synchronous, matching `skill-usage-log.ts`. State lives only under
+ * `.swarm/` resolved from the injected `directory` (never `process.cwd()`).
+ */
+import * as fs from 'node:fs';
+/**
+ * The hard global budget for the skill-usage subsystem.
+ *
+ * | Key | Justification |
+ * |---|---|
+ * | `version` | requirement 1 "versioned"; stored in the sidecar |
+ * | `maxEntries` | must exceed 500 so the per-skill 500-entry fixture still prunes nothing |
+ * | `maxBytes` | must exceed the ~100 KB 600-entry fixture |
+ * | `maxAgeMs` | the age budget |
+ * | `floorPerSkill` | >= `curatorMinSample`, so the guaranteed window can still authorize a retirement |
+ * | `curatorMinSample` | minimum per-skill sample before the curator may retire/revise |
+ * | `readMaxBytes` | >= `maxBytes` + slack, so a bounded file always reads complete |
+ * | `migrationChunkBytes` | **chunk/buffer bound, NOT a total-bytes cap** — migration is single-pass streaming and is never byte-truncated |
+ * | `headerMaxBytes` | sidecar manifest-scalar bound |
+ * | `queueMaxRecords` | requirement 1 applies to marker types too; an upper guard, NOT the binding cap (see below) |
+ * | `queueMaxBytes` | **the binding cap** (see below) |
+ * | `maxAttempts` | bounds transient-failure retention |
+ * | `checkInterval` | throttled maintenance cadence, mirrors `telemetry.ts` |
+ *
+ * **Which queue cap binds, and why (issue #2038 review).** The approved plan
+ * justified `queueMaxBytes` as "~5,000 x ~100 B". That estimate is wrong by a
+ * factor of two. Measured `recordBytes` (`JSON.stringify(record).length + 1`,
+ * which is what {@link queueByteSize} sums):
+ *
+ * | `skillPath` | bytes/record | `queueMaxBytes` binds at |
+ * |---|---|---|
+ * | `skill-x` (a test-length path) | 200 | 2,621 records |
+ * | `.claude/skills/writing-tests/SKILL.md` | 230 | 2,279 records |
+ * | `.claude/skills/engineering-conventions/SKILL.md` | 240 | 2,184 records |
+ *
+ * A 36-char UUID id and two ISO-8601 timestamps (`timestamp`, `enqueuedAt`)
+ * are already 88 B of values before any key name. `queueMaxRecords` = 5,000
+ * would need <= 104.9 B/record to be reachable, and 5,000 realistic records
+ * would need a ~1,123 KiB byte budget.
+ *
+ * So `queueMaxBytes` (512 KiB) binds first, at roughly **2,200-2,600
+ * records**, and `queueMaxRecords` (5,000) is **not reachable** in practice.
+ * That is deliberate and left as-is: both numbers are published in
+ * `docs/observability-retention-registry.md` and
+ * `scripts/retention-registry.data.ts`, the byte budget is the one requirement
+ * 1 actually cares about (unbounded *growth*), and the eviction ladder in
+ * {@link enforceQueueBounds} is driven by `overBudget()`, which ORs the two —
+ * so the ladder and every counted discard behave identically whichever cap
+ * trips. `queueMaxRecords` remains as a cardinality guard for the degenerate
+ * case of pathologically short records. Do not "fix" the record count by
+ * shrinking the record: every field it carries has a consumer in
+ * `applySkillUsageFeedback`.
+ */
+export declare const SKILL_USAGE_LIMITS: {
+    readonly version: 1;
+    readonly maxEntries: 5000;
+    readonly maxBytes: number;
+    readonly maxAgeMs: number;
+    readonly floorPerSkill: 20;
+    readonly curatorMinSample: 10;
+    readonly readMaxBytes: 1677722;
+    readonly migrationChunkBytes: number;
+    readonly headerMaxBytes: number;
+    readonly queueMaxRecords: 5000;
+    readonly queueMaxBytes: number;
+    readonly maxAttempts: 5;
+    readonly checkInterval: 50;
+};
+/**
+ * Stale-break window for `.swarm/skill-usage.lock`, mirroring
+ * `src/context-map/telemetry.ts`. The knowledge-store bump holds its own
+ * lock for at most 5 retries / 5 s, so it cannot push a consumption cycle
+ * past this window.
+ */
+export declare const SKILL_USAGE_LOCK_STALE_MS: number;
+/** Lifecycle state of a queued feedback record. */
+export type SkillUsagePendingState = 'pending' | 'in_flight' | 'uncertain';
+/**
+ * Terminal outcomes. Every one of these DEQUEUES the record and increments a
+ * health counter; none of them increments `processed` / `bumps` on the
+ * `applySkillUsageFeedback` return value (approved plan §3, E7).
+ */
+export type SkillUsageTerminalOutcome = 'no_source_knowledge' | 'no_matching_knowledge' | 'bump_unrecoverable' | 'uncertain_expired';
+/** A single queued actionable verdict awaiting a confidence bump. */
+export interface SkillUsagePendingRecord {
+    /** Same id as the JSONL entry it mirrors — the dedupe key. */
+    id: string;
+    /**
+     * Canonical skill path — no `file:` prefix, forward slashes only — the
+     * same spelling written to the stream for this id (issue #2038 review,
+     * DEFECT 2). Both writers normalize through
+     * `skill-usage-log.ts` `canonicalSkillPath`, so a record and its stream row
+     * can never disagree; `applySkillUsageFeedback` groups on THIS field, so a
+     * disagreement would split one skill's feedback into two groups.
+     * Records migrated from a pre-fix sidecar may still carry a raw spelling
+     * until they drain; every consumer of this field strips `file:`
+     * idempotently, so both forms resolve.
+     */
+    skillPath: string;
+    /** Actionable verdict only. */
+    verdict: 'compliant' | 'violated';
+    /** ISO 8601 timestamp of the usage event. */
+    timestamp: string;
+    /** ISO 8601 mint time — the reference for queue age bounds. */
+    enqueuedAt: string;
+    state: SkillUsagePendingState;
+    /** Transient-failure retry counter, bounded by `maxAttempts`. */
+    attempts: number;
+    /** ISO 8601 time the record was claimed; only set while `in_flight`. */
+    inFlightAt?: string;
+}
+/** Durable lifetime counters. Fixed key set — bounded cardinality by construction. */
+export declare const SKILL_USAGE_COUNTER_KEYS: readonly ["accepted", "compacted", "dropped", "skills_dropped", "corrupt", "uncertain_expired", "pending_evicted", "no_source_knowledge", "no_matching_knowledge", "bump_retry", "bump_unrecoverable", "bump_applied_zero", "pressure", "curator_skipped"];
+export type SkillUsageCounterKey = (typeof SKILL_USAGE_COUNTER_KEYS)[number];
+/**
+ * What the retained JSONL window can and cannot answer.
+ *
+ * Per-skill coverage is DERIVED from these global facts plus the retained
+ * count for the skill (see {@link isSkillWindowTrustworthy}) rather than
+ * stored per skill — a per-skill map would be an unbounded key set, which is
+ * exactly the failure mode issue #2038 is about.
+ */
+export interface SkillUsageCoverage {
+    /** True when no entry has ever been evicted by compaction. */
+    complete: boolean;
+    /** Oldest retained entry timestamp at the last compaction, or null. */
+    oldestRetained: string | null;
+    /** Newest retained entry timestamp at the last compaction, or null. */
+    newestRetained: string | null;
+    /** Cumulative entries evicted by compaction. */
+    entriesDropped: number;
+    /** Cumulative skills dropped whole by the admit-by-most-recent-use step. */
+    skillsDropped: number;
+    /** The floor guarantee in force, so consumers do not hardcode it. */
+    floorPerSkill: number;
+}
+/** The whole sidecar document. */
+export interface SkillUsagePendingDocument {
+    version: number;
+    /** False (or absent) means the legacy migration has not completed yet. */
+    migrated: boolean;
+    records: SkillUsagePendingRecord[];
+    counters: Record<SkillUsageCounterKey, number>;
+    coverage: SkillUsageCoverage;
+}
+/** An enqueue request — the caller supplies the id minted for the JSONL entry. */
+export interface SkillUsageEnqueueInput {
+    id: string;
+    skillPath: string;
+    verdict: 'compliant' | 'violated';
+    timestamp: string;
+}
+/** Opaque handle for an acquired `.swarm/skill-usage.lock`. */
+export interface SkillUsageLockHandle {
+    readonly lockPath: string;
+}
+/**
+ * Test-only dependency-injection seam. Tests override these without
+ * `mock.module` (which leaks across files in Bun's shared test-runner).
+ * Restore in `afterEach`, and call `_resetSkillUsagePendingState()` to clear
+ * the module-scoped pressure cache.
+ */
+export declare const _internals: {
+    existsSync: typeof fs.existsSync;
+    readFileSync: typeof fs.readFileSync;
+    writeFileSync: typeof fs.writeFileSync;
+    renameSync: typeof fs.renameSync;
+    mkdirSync: typeof fs.mkdirSync;
+    statSync: any;
+    openSync: typeof fs.openSync;
+    closeSync: typeof fs.closeSync;
+    unlinkSync: typeof fs.unlinkSync;
+    now: () => number;
+    emitHealth: (payload: SkillUsageHealthPayload) => void;
+};
+/**
+ * Reset module-scoped caches so an unswept run in Bun's shared test-runner
+ * process cannot shift a later test's first read or pressure decision.
+ */
+export declare function _resetSkillUsagePendingState(): void;
+/** Absolute path to the authoritative sidecar. */
+export declare function resolvePendingPath(directory: string): string;
+/** Absolute path to the shared skill-usage lock file. */
+export declare function resolveSkillUsageLockPath(directory: string): string;
+/**
+ * Non-blocking lock acquisition. Returns `null` when the lock is held by a
+ * live holder — maintenance and consumption are then **skipped, never forced**.
+ * Injection still fails open because nothing here throws.
+ */
+export declare function acquireSkillUsageLock(directory: string): SkillUsageLockHandle | null;
+/**
+ * Lock acquisition for the **enqueue** path, which is exempt from the
+ * skip-not-force rule (approved plan §2.3, §9): a failed enqueue must abort
+ * the append and propagate rather than silently drop a correctness signal.
+ * Holders only perform a handful of synchronous file operations, so a short
+ * bounded retry absorbs ordinary contention.
+ */
+export declare function acquireSkillUsageLockOrThrow(directory: string): SkillUsageLockHandle;
+/** Release a lock acquired above. Never throws. */
+export declare function releaseSkillUsageLock(handle: SkillUsageLockHandle): void;
+/** A fresh, un-migrated document. */
+export declare function createPendingDocument(): SkillUsagePendingDocument;
+/** Result of loading the sidecar. */
+export interface LoadPendingResult {
+    doc: SkillUsagePendingDocument;
+    /** True when a corrupt sidecar was renamed aside and a fresh one substituted. */
+    quarantined: boolean;
+    /** Absolute path the corrupt document was moved to, when quarantined. */
+    quarantinePath?: string;
+}
+/**
+ * Read the sidecar.
+ *
+ * A corrupt or oversized document is **quarantined** (renamed aside) and
+ * counted — never silently reset to `[]`. The replacement document carries
+ * `migrated: false`, which makes the next lock-taking touch rebuild the queue
+ * from whatever the JSONL stream still holds (approved plan §6, requirement 3).
+ */
+export declare function loadPendingDocument(directory: string): LoadPendingResult;
+/**
+ * Atomically replace the sidecar (temp file + rename). Throws on failure so
+ * the enqueue path can abort its append and propagate (approved plan §2.3).
+ */
+export declare function savePendingDocument(directory: string, doc: SkillUsagePendingDocument): void;
+/**
+ * Read just the manifest scalars a reader needs, using a `statSync`-keyed
+ * cache so the 8 steady-state read sites do not each re-parse the sidecar.
+ */
+export declare function readPendingManifest(directory: string): {
+    coverage: SkillUsageCoverage;
+    migrated: boolean;
+};
+/**
+ * Per-skill coverage rule (approved plan §8 / BLK-8), derived rather than
+ * stored so the key set stays bounded.
+ *
+ * A skill's retained window may be used for a retire/revise decision when:
+ *   (i)  global coverage is COMPLETE — nothing has ever been evicted, so the
+ *        retained window IS the whole history and there is nothing for this
+ *        gate to protect against; OR
+ *   (ii) coverage is incomplete AND the sample is at least `curatorMinSample`
+ *        AND the retained window is at least the most-recent `floorPerSkill`
+ *        entries — retention guarantees each surviving skill
+ *        `min(count, floorPerSkill)` most-recent entries, so
+ *        `retained >= floorPerSkill` establishes the window's shape by
+ *        construction.
+ *
+ * **Why the minimum-sample floor sits behind `coverage.complete` (issue #2038
+ * implementation review, F2).** An earlier revision tested the floor FIRST, so a
+ * skill with 3 uses and 3 violations was never retired even on a fully complete,
+ * untruncated window. That silently narrowed shipped #1770/#1822 behavior, where
+ * the retire trigger was `violationRate > 0.3` with no sample floor, and it had
+ * nothing to do with compaction coverage — which is all this gate exists to
+ * judge. On complete coverage the sample IS the truth, so the pre-existing
+ * behavior applies unchanged; the floor is a statement about a TRUNCATED window
+ * and only applies to one.
+ *
+ * Note that under the shipped constants (`floorPerSkill` 20 >= `curatorMinSample`
+ * 10) the explicit `curatorMinSample` test below is subsumed by the floor
+ * comparison. It is kept because the constants are independently tunable and a
+ * sidecar may carry an older, smaller `coverage.floorPerSkill`; do not read it as
+ * load-bearing at today's values.
+ *
+ * Returns false when the decision must be skipped (and counted).
+ */
+export declare function isSkillWindowTrustworthy(coverage: SkillUsageCoverage, retainedCount: number): boolean;
+/** Total serialized size of the queue records. */
+export declare function queueByteSize(doc: SkillUsagePendingDocument): number;
+/**
+ * Apply the queue budget: age, record count, and byte size — to every record
+ * including `uncertain` ones. Every discard is counted; none is silent.
+ */
+export declare function enforceQueueBounds(doc: SkillUsagePendingDocument, nowMs?: number): void;
+/**
+ * Whether optional (`not_checked`) usage appends must stop.
+ *
+ * Deliberately cheap: the hot delegation loop appends one entry per skill
+ * path, so this must not take the lock or parse the sidecar. It reuses the
+ * value computed by the last write and otherwise refreshes from a `statSync`
+ * at most once per {@link PRESSURE_CACHE_MS}.
+ */
+export declare function isSkillUsageQueueUnderPressure(directory: string): boolean;
+/**
+ * Merge records into the document, deduped by `id` (approved plan BLK-10).
+ * Returns the number actually added.
+ */
+export declare function mergePendingRecords(doc: SkillUsagePendingDocument, incoming: SkillUsageEnqueueInput[], nowIso: string): number;
+/**
+ * Enqueue one actionable verdict.
+ *
+ * **Must be called BEFORE the JSONL append** (approved plan §2.2): a crash
+ * between the two then leaves at worst an orphan queue record with no stats
+ * row — harmless, because the record is self-sufficient. The reverse order
+ * leaves an authoritative gap.
+ *
+ * **Throws** on lock failure or write failure so the caller aborts the append
+ * and propagates (§2.3). This is the one path exempt from the skip-not-force
+ * rule; the sole actionable caller already handles a throw.
+ */
+export declare function enqueueSkillUsageFeedback(directory: string, input: SkillUsageEnqueueInput): void;
+/**
+ * Resolve claims abandoned by a crashed cycle.
+ *
+ * An `in_flight` record whose claim is older than the lock stale-break window
+ * becomes `uncertain`: it survives and stays visible, but is never replayed —
+ * satisfying both clauses of "survives ... and is consumed at most once".
+ * A claim younger than that window belongs to a cycle that may still be
+ * running in another process and is left alone.
+ */
+export declare function resolveStaleInFlight(doc: SkillUsagePendingDocument, nowMs?: number): number;
+/** Records eligible for consumption. `in_flight` and `uncertain` are excluded. */
+export declare function selectConsumableRecords(doc: SkillUsagePendingDocument, sinceTimestamp?: string): SkillUsagePendingRecord[];
+/** Mark records claimed. Persist before releasing the lock. */
+export declare function markRecordsInFlight(doc: SkillUsagePendingDocument, ids: Iterable<string>, nowIso?: string): void;
+/** Normal-path dequeue after a bump that actually applied. No terminal counter. */
+export declare function dequeueRecords(doc: SkillUsagePendingDocument, ids: Iterable<string>): number;
+/**
+ * Terminal dequeue. Counted in `skill_usage_health` only — terminal outcomes
+ * never increment `processed` / `bumps` (approved plan §3, E7).
+ */
+export declare function applyTerminalOutcome(doc: SkillUsagePendingDocument, ids: Iterable<string>, outcome: SkillUsageTerminalOutcome): number;
+/**
+ * Transient-failure handling: the record stays `pending` and its attempt
+ * counter advances. At `maxAttempts` it goes terminal `bump_unrecoverable`,
+ * so a permanently-locked directory cannot retain records forever.
+ */
+export declare function retainWithRetry(doc: SkillUsagePendingDocument, ids: Iterable<string>): {
+    retried: string[];
+    unrecoverable: string[];
+};
+/**
+ * Payload shape of `telemetry.skillUsageHealth`. Counts only — **no
+ * `skillPath` and no per-skill identifier**: the adversarial case in issue
+ * #2038 is thousands of one-off skill IDs, so a per-skill label would be an
+ * unbounded label set and nothing in `check-event-contract.ts` would catch it.
+ */
+export interface SkillUsageHealthPayload {
+    trigger: 'compaction' | 'migration' | 'consumption' | 'pressure';
+    accepted: number;
+    compacted: number;
+    dropped: number;
+    skills_dropped: number;
+    corrupt: number;
+    pending_retained: number;
+    uncertain_retained: number;
+    uncertain_expired: number;
+    /** Actionable records discarded by the queue budget (issue #2038 F3). */
+    pending_evicted: number;
+    no_source_knowledge: number;
+    no_matching_knowledge: number;
+    bump_retry: number;
+    bump_unrecoverable: number;
+    bump_applied_zero: number;
+    pressure: number;
+    curator_skipped: number;
+    bytes: number;
+    limit_bytes: number;
+    oldest_timestamp: string | null;
+    newest_timestamp: string | null;
+    coverage: boolean;
+}
+/** Build the health payload from durable counters plus live gauges. */
+export declare function buildSkillUsageHealthPayload(doc: SkillUsagePendingDocument, trigger: SkillUsageHealthPayload['trigger'], gauges: {
+    bytes: number;
+    limitBytes: number;
+}): SkillUsageHealthPayload;
+/** Emit the health signal. Never throws — observability must not break a write. */
+export declare function emitSkillUsageHealth(doc: SkillUsagePendingDocument, trigger: SkillUsageHealthPayload['trigger'], gauges: {
+    bytes: number;
+    limitBytes: number;
+}): void;