@sayknow-cli/coding-agent 0.4.1 → 0.4.3

package/dist/types/commit/agentic/tools/recent-commits.d.ts

@@ -0,0 +1,7 @@
+import * as z from "zod/v4";
+import type { CustomTool } from "../../../extensibility/custom-tools/types";
+declare const recentCommitsSchema: z.ZodObject<{
+    count: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export declare function createRecentCommitsTool(cwd: string): CustomTool<typeof recentCommitsSchema>;
+export {};

package/dist/types/commit/agentic/tools/schemas.d.ts

@@ -0,0 +1,27 @@
+import * as z from "zod/v4";
+export declare const commitTypeSchema: z.ZodEnum<{
+    style: "style";
+    feat: "feat";
+    fix: "fix";
+    refactor: "refactor";
+    perf: "perf";
+    docs: "docs";
+    test: "test";
+    build: "build";
+    ci: "ci";
+    chore: "chore";
+    revert: "revert";
+}>;
+export declare const detailSchema: z.ZodObject<{
+    text: z.ZodString;
+    changelog_category: z.ZodOptional<z.ZodEnum<{
+        "Breaking Changes": "Breaking Changes";
+        Added: "Added";
+        Changed: "Changed";
+        Deprecated: "Deprecated";
+        Removed: "Removed";
+        Fixed: "Fixed";
+        Security: "Security";
+    }>>;
+    user_visible: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;

package/dist/types/commit/agentic/tools/split-commit.d.ts

@@ -0,0 +1,53 @@
+import * as z from "zod/v4";
+import type { CommitAgentState } from "../../../commit/agentic/state";
+import type { CustomTool } from "../../../extensibility/custom-tools/types";
+declare const splitCommitSchema: z.ZodObject<{
+    commits: z.ZodArray<z.ZodObject<{
+        changes: z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            hunks: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                type: z.ZodLiteral<"all">;
+            }, z.core.$strip>, z.ZodObject<{
+                type: z.ZodLiteral<"indices">;
+                indices: z.ZodArray<z.ZodNumber>;
+            }, z.core.$strip>, z.ZodObject<{
+                type: z.ZodLiteral<"lines">;
+                start: z.ZodNumber;
+                end: z.ZodNumber;
+            }, z.core.$strip>], "type">;
+        }, z.core.$strip>>;
+        type: z.ZodEnum<{
+            style: "style";
+            feat: "feat";
+            fix: "fix";
+            refactor: "refactor";
+            perf: "perf";
+            docs: "docs";
+            test: "test";
+            build: "build";
+            ci: "ci";
+            chore: "chore";
+            revert: "revert";
+        }>;
+        scope: z.ZodUnion<readonly [z.ZodString, z.ZodNull]>;
+        summary: z.ZodString;
+        details: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            text: z.ZodString;
+            changelog_category: z.ZodOptional<z.ZodEnum<{
+                "Breaking Changes": "Breaking Changes";
+                Added: "Added";
+                Changed: "Changed";
+                Deprecated: "Deprecated";
+                Removed: "Removed";
+                Fixed: "Fixed";
+                Security: "Security";
+            }>>;
+            user_visible: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>>>;
+        issue_refs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        rationale: z.ZodOptional<z.ZodString>;
+        dependencies: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare function createSplitCommitTool(cwd: string, state: CommitAgentState, changelogTargets: string[]): CustomTool<typeof splitCommitSchema>;
+export {};

package/dist/types/commit/agentic/topo-sort.d.ts

@@ -0,0 +1,4 @@
+import type { SplitCommitGroup } from "./state";
+export declare function computeDependencyOrder(groups: SplitCommitGroup[]): number[] | {
+    error: string;
+};

package/dist/types/commit/agentic/trivial.d.ts

@@ -0,0 +1,7 @@
+import type { CommitType } from "../../commit/types";
+export interface TrivialChangeResult {
+    isTrivial: true;
+    type: CommitType;
+    summary: string;
+}
+export declare function detectTrivialChange(diff: string): TrivialChangeResult | null;

package/dist/types/commit/agentic/validation.d.ts

@@ -0,0 +1,20 @@
+import type { CommitType, ConventionalDetail } from "../../commit/types";
+export declare const SUMMARY_MAX_CHARS = 72;
+export declare const MAX_DETAIL_ITEMS = 6;
+export declare function normalizeSummary(summary: string, type: CommitType, scope: string | null): string;
+export declare function validateSummaryRules(summary: string): {
+    errors: string[];
+    warnings: string[];
+};
+export declare function capDetails(details: ConventionalDetail[]): {
+    details: ConventionalDetail[];
+    warnings: string[];
+};
+export declare function validateTypeConsistency(type: CommitType, files: string[], options?: {
+    diffText?: string;
+    summary?: string;
+    details?: ConventionalDetail[];
+}): {
+    errors: string[];
+    warnings: string[];
+};

package/dist/types/commit/analysis/conventional.d.ts

@@ -0,0 +1,22 @@
+import type { ThinkingLevel } from "@sayknow-cli/agent-core";
+import type { Api, Model } from "@sayknow-cli/ai";
+import type { ConventionalAnalysis } from "../../commit/types";
+export interface ConventionalAnalysisInput {
+    model: Model<Api>;
+    apiKey: string;
+    thinkingLevel?: ThinkingLevel;
+    contextFiles?: Array<{
+        path: string;
+        content: string;
+    }>;
+    userContext?: string;
+    typesDescription?: string;
+    recentCommits?: string[];
+    scopeCandidates: string;
+    stat: string;
+    diff: string;
+}
+/**
+ * Generate conventional analysis data from a diff and metadata.
+ */
+export declare function generateConventionalAnalysis({ model, apiKey, thinkingLevel, contextFiles, userContext, typesDescription, recentCommits, scopeCandidates, stat, diff, }: ConventionalAnalysisInput): Promise<ConventionalAnalysis>;

package/dist/types/commit/analysis/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./conventional";
+export * from "./scope";
+export * from "./summary";
+export * from "./validation";

package/dist/types/commit/analysis/scope.d.ts

@@ -0,0 +1,6 @@
+import type { NumstatEntry } from "../../commit/types";
+export interface ScopeCandidatesResult {
+    scopeCandidates: string;
+    isWide: boolean;
+}
+export declare function extractScopeCandidates(numstat: NumstatEntry[]): ScopeCandidatesResult;

package/dist/types/commit/analysis/summary.d.ts

@@ -0,0 +1,19 @@
+import type { ThinkingLevel } from "@sayknow-cli/agent-core";
+import type { Api, Model } from "@sayknow-cli/ai";
+import type { CommitSummary } from "../../commit/types";
+export interface SummaryInput {
+    model: Model<Api>;
+    apiKey: string;
+    thinkingLevel?: ThinkingLevel;
+    commitType: string;
+    scope: string | null;
+    details: string[];
+    stat: string;
+    maxChars: number;
+    userContext?: string;
+}
+/**
+ * Generate a commit summary line for the conventional commit header.
+ */
+export declare function generateSummary({ model, apiKey, thinkingLevel, commitType, scope, details, stat, maxChars, userContext, }: SummaryInput): Promise<CommitSummary>;
+export declare function stripTypePrefix(summary: string, commitType: string, scope: string | null): string;

package/dist/types/commit/analysis/validation.d.ts

@@ -0,0 +1,8 @@
+import type { ConventionalAnalysis } from "../../commit/types";
+export interface ValidationResult {
+    valid: boolean;
+    errors: string[];
+}
+export declare function validateSummary(summary: string, maxChars: number): ValidationResult;
+export declare function validateScope(scope: string | null): ValidationResult;
+export declare function validateAnalysis(analysis: ConventionalAnalysis): ValidationResult;

package/dist/types/commit/changelog/detect.d.ts

@@ -0,0 +1,2 @@
+import type { ChangelogBoundary } from "../../commit/types";
+export declare function detectChangelogBoundaries(cwd: string, stagedFiles: string[]): Promise<ChangelogBoundary[]>;

package/dist/types/commit/changelog/generate.d.ts

@@ -0,0 +1,30 @@
+import type { ThinkingLevel } from "@sayknow-cli/agent-core";
+import type { Api, Model } from "@sayknow-cli/ai";
+import * as z from "zod/v4";
+import { type ChangelogGenerationResult } from "../../commit/types";
+export declare const changelogTool: {
+    name: string;
+    description: string;
+    parameters: z.ZodObject<{
+        entries: z.ZodObject<{
+            "Breaking Changes": z.ZodOptional<z.ZodArray<z.ZodString>>;
+            Added: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            Changed: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            Deprecated: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            Removed: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            Fixed: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            Security: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+};
+export interface ChangelogPromptInput {
+    model: Model<Api>;
+    apiKey: string;
+    thinkingLevel?: ThinkingLevel;
+    changelogPath: string;
+    isPackageChangelog: boolean;
+    existingEntries?: string;
+    stat: string;
+    diff: string;
+}
+export declare function generateChangelogEntries({ model, apiKey, thinkingLevel, changelogPath, isPackageChangelog, existingEntries, stat, diff, }: ChangelogPromptInput): Promise<ChangelogGenerationResult>;

package/dist/types/commit/changelog/index.d.ts

@@ -0,0 +1,30 @@
+import type { ThinkingLevel } from "@sayknow-cli/agent-core";
+import type { Api, Model } from "@sayknow-cli/ai";
+export interface ChangelogFlowInput {
+    cwd: string;
+    model: Model<Api>;
+    apiKey: string;
+    thinkingLevel?: ThinkingLevel;
+    stagedFiles: string[];
+    dryRun: boolean;
+    maxDiffChars?: number;
+    onProgress?: (message: string) => void;
+}
+export interface ChangelogProposalInput {
+    cwd: string;
+    proposals: Array<{
+        path: string;
+        entries: Record<string, string[]>;
+        deletions?: Record<string, string[]>;
+    }>;
+    dryRun: boolean;
+    onProgress?: (message: string) => void;
+}
+/**
+ * Update CHANGELOG.md entries for staged changes.
+ */
+export declare function runChangelogFlow({ cwd, model, apiKey, thinkingLevel, stagedFiles, dryRun, maxDiffChars, onProgress, }: ChangelogFlowInput): Promise<string[]>;
+/**
+ * Apply changelog entries provided by the commit agent.
+ */
+export declare function applyChangelogProposals({ cwd, proposals, dryRun, onProgress, }: ChangelogProposalInput): Promise<string[]>;

package/dist/types/commit/changelog/parse.d.ts

@@ -0,0 +1,2 @@
+import type { UnreleasedSection } from "../../commit/types";
+export declare function parseUnreleasedSection(content: string): UnreleasedSection;

package/dist/types/commit/cli.d.ts

@@ -0,0 +1,3 @@
+import type { CommitCommandArgs } from "./types";
+export declare function parseCommitArgs(args: string[]): CommitCommandArgs | undefined;
+export declare function printCommitHelp(): void;

package/dist/types/commit/git/diff.d.ts

@@ -0,0 +1,5 @@
+import type { FileDiff, FileHunks, NumstatEntry } from "../../commit/types";
+export declare function parseNumstat(output: string): NumstatEntry[];
+export declare function parseFileDiffs(diff: string): FileDiff[];
+export declare function parseDiffHunks(diff: string): FileHunks[];
+export declare function parseFileHunks(fileDiff: FileDiff): FileHunks;

package/dist/types/commit/index.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Entry points for the skc commit command.
+ */
+export { runCommitCommand } from "./pipeline";

package/dist/types/commit/map-reduce/index.d.ts

@@ -0,0 +1,28 @@
+import type { ThinkingLevel } from "@sayknow-cli/agent-core";
+import type { Api, Model } from "@sayknow-cli/ai";
+import type { ConventionalAnalysis } from "../../commit/types";
+export interface MapReduceSettings {
+    enabled?: boolean;
+    minFiles?: number;
+    maxFileTokens?: number;
+    maxConcurrency?: number;
+    timeoutMs?: number;
+}
+export interface MapReduceInput {
+    model: Model<Api>;
+    apiKey: string;
+    thinkingLevel?: ThinkingLevel;
+    smolModel: Model<Api>;
+    smolApiKey: string;
+    smolThinkingLevel?: ThinkingLevel;
+    diff: string;
+    stat: string;
+    scopeCandidates: string;
+    typesDescription?: string;
+    settings?: MapReduceSettings;
+}
+export declare function shouldUseMapReduce(diff: string, settings?: MapReduceSettings): boolean;
+/**
+ * Run map-reduce analysis for large diffs using smol + primary models.
+ */
+export declare function runMapReduceAnalysis(input: MapReduceInput): Promise<ConventionalAnalysis>;

package/dist/types/commit/map-reduce/map-phase.d.ts

@@ -0,0 +1,17 @@
+import type { ThinkingLevel } from "@sayknow-cli/agent-core";
+import type { Api, Model } from "@sayknow-cli/ai";
+import type { FileDiff, FileObservation } from "../../commit/types";
+export interface MapPhaseInput {
+    model: Model<Api>;
+    apiKey: string;
+    thinkingLevel?: ThinkingLevel;
+    files: FileDiff[];
+    config?: {
+        maxFileTokens?: number;
+        maxConcurrency?: number;
+        timeoutMs?: number;
+        maxRetries?: number;
+        retryBackoffMs?: number;
+    };
+}
+export declare function runMapPhase({ model, apiKey, thinkingLevel, files, config, }: MapPhaseInput): Promise<FileObservation[]>;

package/dist/types/commit/map-reduce/reduce-phase.d.ts

@@ -0,0 +1,13 @@
+import type { ThinkingLevel } from "@sayknow-cli/agent-core";
+import type { Api, Model } from "@sayknow-cli/ai";
+import type { ConventionalAnalysis, FileObservation } from "../../commit/types";
+export interface ReducePhaseInput {
+    model: Model<Api>;
+    apiKey: string;
+    thinkingLevel?: ThinkingLevel;
+    observations: FileObservation[];
+    stat: string;
+    scopeCandidates: string;
+    typesDescription?: string;
+}
+export declare function runReducePhase({ model, apiKey, thinkingLevel, observations, stat, scopeCandidates, typesDescription, }: ReducePhaseInput): Promise<ConventionalAnalysis>;

package/dist/types/commit/map-reduce/utils.d.ts

@@ -0,0 +1,2 @@
+export declare function estimateTokens(text: string): number;
+export declare function truncateToTokenLimit(text: string, maxTokens: number): string;

package/dist/types/commit/message.d.ts

@@ -0,0 +1,2 @@
+import type { ConventionalAnalysis } from "./types";
+export declare function formatCommitMessage(analysis: ConventionalAnalysis, summary: string): string;

package/dist/types/commit/model-selection.d.ts

@@ -0,0 +1,15 @@
+import type { ThinkingLevel } from "@sayknow-cli/agent-core";
+import type { Api, Model } from "@sayknow-cli/ai";
+import { type ModelLookupRegistry } from "../config/model-resolver";
+import type { Settings } from "../config/settings";
+export interface ResolvedCommitModel {
+    model: Model<Api>;
+    apiKey: string;
+    thinkingLevel?: ThinkingLevel;
+}
+type CommitModelRegistry = ModelLookupRegistry & {
+    getApiKey: (model: Model<Api>) => Promise<string | undefined>;
+};
+export declare function resolvePrimaryModel(override: string | undefined, settings: Settings, modelRegistry: CommitModelRegistry): Promise<ResolvedCommitModel>;
+export declare function resolveSecondaryCommitModel(settings: Settings, modelRegistry: CommitModelRegistry, fallbackModel: Model<Api>, fallbackApiKey: string): Promise<ResolvedCommitModel>;
+export {};

package/dist/types/commit/pipeline.d.ts

@@ -0,0 +1,5 @@
+import type { CommitCommandArgs } from "./types";
+/**
+ * Execute the skc commit pipeline for staged changes.
+ */
+export declare function runCommitCommand(args: CommitCommandArgs): Promise<void>;

package/dist/types/commit/shared-llm.d.ts

@@ -0,0 +1,54 @@
+import type { AssistantMessage } from "@sayknow-cli/ai";
+import * as z from "zod/v4";
+import type { ConventionalAnalysis } from "./types";
+/**
+ * Shared Zod schema for the `create_conventional_analysis` tool used by
+ * both the single-pass analysis call and the map-reduce reduce phase. Schemas
+ * are identical across phases — only the surrounding tool `description`
+ * differs to reflect the input the phase is summarizing.
+ */
+export declare const conventionalAnalysisParameters: z.ZodObject<{
+    type: z.ZodEnum<{
+        style: "style";
+        feat: "feat";
+        fix: "fix";
+        refactor: "refactor";
+        perf: "perf";
+        docs: "docs";
+        test: "test";
+        build: "build";
+        ci: "ci";
+        chore: "chore";
+        revert: "revert";
+    }>;
+    scope: z.ZodUnion<readonly [z.ZodString, z.ZodNull]>;
+    details: z.ZodArray<z.ZodObject<{
+        text: z.ZodString;
+        changelog_category: z.ZodOptional<z.ZodEnum<{
+            "Breaking Changes": "Breaking Changes";
+            Added: "Added";
+            Changed: "Changed";
+            Deprecated: "Deprecated";
+            Removed: "Removed";
+            Fixed: "Fixed";
+            Security: "Security";
+        }>>;
+        user_visible: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    issue_refs: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export interface ConventionalAnalysisTool {
+    name: "create_conventional_analysis";
+    description: string;
+    parameters: typeof conventionalAnalysisParameters;
+}
+/**
+ * Build a `create_conventional_analysis` tool descriptor. Phase-specific
+ * `description` text is the only thing that varies between callers.
+ */
+export declare function createConventionalAnalysisTool(description: string): ConventionalAnalysisTool;
+/**
+ * Extract a {@link ConventionalAnalysis} from an assistant response, preferring
+ * a structured tool call and falling back to JSON embedded in text content.
+ */
+export declare function parseConventionalAnalysisResponse(message: AssistantMessage, tool: ConventionalAnalysisTool): ConventionalAnalysis;

package/dist/types/commit/types.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Types for the skc commit pipeline.
+ */
+export type CommitType = "feat" | "fix" | "refactor" | "perf" | "docs" | "test" | "build" | "ci" | "chore" | "style" | "revert";
+export type ChangelogCategory = "Breaking Changes" | "Added" | "Changed" | "Deprecated" | "Removed" | "Fixed" | "Security";
+export declare const CHANGELOG_CATEGORIES: ChangelogCategory[];
+export interface CommitCommandArgs {
+    /** Push after commit */
+    push: boolean;
+    /** Preview without committing */
+    dryRun: boolean;
+    /** Skip changelog updates */
+    noChangelog: boolean;
+    /** Use legacy deterministic pipeline */
+    legacy?: boolean;
+    /** Additional user context for the model */
+    context?: string;
+    /** Override the model selection */
+    model?: string;
+}
+export interface NumstatEntry {
+    path: string;
+    additions: number;
+    deletions: number;
+}
+export interface ConventionalDetail {
+    text: string;
+    changelogCategory?: ChangelogCategory;
+    userVisible: boolean;
+}
+export interface ConventionalAnalysis {
+    type: CommitType;
+    scope: string | null;
+    details: ConventionalDetail[];
+    issueRefs: string[];
+}
+export interface CommitSummary {
+    summary: string;
+}
+export interface FileObservation {
+    file: string;
+    observations: string[];
+    additions: number;
+    deletions: number;
+}
+export interface FileDiff {
+    filename: string;
+    content: string;
+    additions: number;
+    deletions: number;
+    isBinary: boolean;
+}
+export interface DiffHunk {
+    index: number;
+    header: string;
+    oldStart: number;
+    oldLines: number;
+    newStart: number;
+    newLines: number;
+    content: string;
+}
+export interface FileHunks {
+    filename: string;
+    isBinary: boolean;
+    hunks: DiffHunk[];
+}
+export interface ChangelogBoundary {
+    changelogPath: string;
+    files: string[];
+}
+export interface UnreleasedSection {
+    startLine: number;
+    endLine: number;
+    entries: Record<string, string[]>;
+}
+export interface ChangelogGenerationResult {
+    entries: Record<string, string[]>;
+}

package/dist/types/commit/utils/exclusions.d.ts

@@ -0,0 +1,4 @@
+export declare function isExcludedFile(path: string): boolean;
+export declare function filterExcludedFiles<T extends {
+    filename: string;
+}>(files: T[]): T[];

package/dist/types/commit/utils.d.ts

@@ -0,0 +1,20 @@
+import type { AssistantMessage, ToolCall } from "@sayknow-cli/ai";
+import type { ChangelogCategory, ConventionalAnalysis, ConventionalDetail } from "./types";
+export declare function extractToolCall(message: AssistantMessage, name: string): ToolCall | undefined;
+export declare function extractTextContent(message: AssistantMessage): string;
+export declare function parseJsonPayload(text: string): unknown;
+export declare function normalizeAnalysis(parsed: {
+    type: ConventionalAnalysis["type"];
+    scope: string | null;
+    details: Array<{
+        text: string;
+        changelog_category?: ChangelogCategory;
+        user_visible?: boolean;
+    }>;
+    issue_refs: string[];
+}): ConventionalAnalysis;
+export declare function normalizeDetails(details: Array<{
+    text: string;
+    changelog_category?: ConventionalDetail["changelogCategory"];
+    user_visible?: boolean;
+}>): ConventionalDetail[];

package/dist/types/config/atomic-yaml-patch.d.ts

@@ -0,0 +1,103 @@
+export interface AtomicYamlExpectedPrecondition {
+    path: string;
+    hash: string;
+}
+export interface AtomicYamlSetPatch {
+    path: string;
+    op: "set";
+    value: unknown;
+    expected?: AtomicYamlExpectedPrecondition;
+}
+export interface AtomicYamlUnsetPatch {
+    path: string;
+    op: "unset";
+    expected?: AtomicYamlExpectedPrecondition;
+}
+export type AtomicYamlPatch = AtomicYamlSetPatch | AtomicYamlUnsetPatch;
+/** Raised when a compare-and-swap precondition no longer matches durable YAML. */
+export declare class AtomicYamlConflictError extends Error {
+    readonly path: string;
+    readonly expectedHash: string;
+    readonly actualHash: string;
+    readonly code = "ATOMIC_YAML_CONFLICT";
+    constructor(path: string, expectedHash: string, actualHash: string);
+}
+export interface AtomicYamlPatchRevision {
+    path: string;
+    beforeHash: string;
+    afterHash: string;
+    beforeRevision: number;
+    afterRevision: number;
+}
+export type CasRestoreResult = {
+    status: "restored";
+    receipt: CasReceipt;
+} | {
+    status: "conflict";
+    paths: readonly string[];
+} | {
+    status: "discarded";
+};
+/**
+ * A receipt intentionally exposes only path-level hashes and opaque revisions.
+ * The before values needed by restore stay in this module's closure.
+ */
+export interface CasReceipt {
+    readonly revisions: readonly AtomicYamlPatchRevision[];
+    restore(): Promise<CasRestoreResult>;
+    discard(): void;
+}
+export interface AtomicYamlUpdate<T> {
+    apply(current: Record<string, unknown>): T | Promise<T>;
+    shouldWrite?(result: T): boolean;
+    committed?(current: Record<string, unknown>, result: T): void | Promise<void>;
+}
+export interface AtomicYamlPatchOptions {
+    /** Test seam for deterministic pre-rename and Windows sharing-violation failures. */
+    rename?: (from: string, to: string) => Promise<void>;
+    /** Test seam for bounded retry timing. */
+    sleep?: (ms: number) => Promise<void>;
+    /** Test seam for Windows rename retry behavior. */
+    platform?: NodeJS.Platform;
+    /** Called under the config lock before patches are applied. */
+    validateRoot?: (root: unknown, patches: readonly AtomicYamlPatch[]) => void | Promise<void>;
+    /** Called under the config lock after a successful CAS restore. */
+    onRestored?: (patches: readonly AtomicYamlPatch[]) => void | Promise<void>;
+}
+/** A replacement failure never unlinks the destination as a fallback. */
+export declare class AtomicYamlReplaceError extends Error {
+    readonly configPath: string;
+    readonly attempts: number;
+    readonly cause: unknown;
+    readonly code = "ATOMIC_YAML_REPLACE_FAILED";
+    constructor(configPath: string, attempts: number, cause: unknown);
+}
+/** Set a dotted YAML path, creating object intermediates as needed. */
+export declare function setByPath(value: Record<string, unknown>, segments: readonly string[], nextValue: unknown): void;
+/** Delete a dotted YAML path without disturbing sibling keys or parent objects. */
+export declare function deleteByPath(value: Record<string, unknown>, segments: readonly string[]): void;
+/** Hash a dotted YAML path state for an expected-hash patch precondition. */
+export declare function atomicYamlPathHash(value: Record<string, unknown>, path: string): string;
+/** Build patches from current durable YAML while holding the shared queue and file lock. */
+export declare function applyAtomicYamlPatchesWithCurrent(configPath: string, buildPatches: (current: Readonly<Record<string, unknown>>) => Promise<readonly AtomicYamlPatch[]> | readonly AtomicYamlPatch[], options?: AtomicYamlPatchOptions): Promise<CasReceipt>;
+/**
+ * Reserve a FIFO operation for a config file immediately. The patch supplier runs
+ * only when this operation reaches the front of the in-process queue, which lets
+ * Settings debounce/coalesce inside its already-reserved causal slot.
+ */
+export declare function enqueueAtomicYamlOperation<T>(configPath: string, operation: (canonicalConfigPath: string) => Promise<T>): Promise<T>;
+/**
+ * Reserve an atomic patch slot now, producing patches only after earlier slots
+ * complete. Writers with state-aware merges use {@link reserveAtomicYamlUpdateSlot}.
+ */
+export declare function reserveAtomicYamlPatchSlot(configPath: string, patches: () => Promise<readonly AtomicYamlPatch[]> | readonly AtomicYamlPatch[], options?: AtomicYamlPatchOptions): Promise<CasReceipt>;
+/**
+ * Reserve a FIFO update slot and atomically persist a caller-owned YAML mutation.
+ * The supplier runs only when its operation reaches the front of the queue.
+ */
+export declare function reserveAtomicYamlUpdateSlot<T>(configPath: string, update: () => Promise<AtomicYamlUpdate<T>> | AtomicYamlUpdate<T>, options?: AtomicYamlPatchOptions): Promise<T>;
+/**
+ * Apply tagged patches through the one per-file in-process queue and the shared
+ * cross-process file lock. Success means the temp file was fsynced and renamed.
+ */
+export declare function applyAtomicYamlPatches(configPath: string, patches: readonly AtomicYamlPatch[], options?: AtomicYamlPatchOptions): Promise<CasReceipt>;