@i18nprune/core 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,1345 @@
+import { D as DynamicKeySite } from './index-DdjljwMj.js';
+export { a as DynamicKeySiteKind } from './index-DdjljwMj.js';
+import { K as KeyObservation, C as ConstSubstitutionStep } from './index-Csm1w7XD.js';
+export { D as DynamicKeyRef, L as LiteralKeyObservation, S as SourceSpan, T as TemplatePartialKeyObservation, a as TemplateResolvedKeyObservation } from './index-Csm1w7XD.js';
+import { P as ProjectLiteralKeyUsage } from './sourceSurface-mDtwGo1E.js';
+export { a as CleanupHostHooks, e as CleanupJsonOutput, f as CleanupJsonRunSummary, b as CleanupRunOptions, c as CleanupRunResult, g as CleanupSegmentWrite, d as CleanupSourceSegmentRef, C as CleanupWritePlan } from './sourceSurface-mDtwGo1E.js';
+import { d as CacheRebuildMode, e as CacheProjectFileRecord, f as CachedLocalesLayout, g as CacheRebuildConfig, h as ListSourceFilesOptions, i as CacheDispatchInfo, R as ResolvedLocalesLayout, j as CacheDispatchStatus, C as CoreContext } from './coreContext-DMaWLvmB.js';
+export { A as AnalysisRebuildDecision, k as AnalysisRebuildReason, l as AnalysisRebuildStrategy, m as CacheDisableReason, n as CacheDispatchPaths, o as CacheDispatchReason, p as CacheDispatchResult, q as CacheFileDelta, r as CacheHashText, s as CacheInputFilesEpochDebug, t as CacheProducerContext, u as CacheProjectFilesState, v as CacheProjectRunState, w as CacheProjectsIndex, x as CacheRuntime, y as CacheState, z as CacheStateInput, b as CacheWarning, B as CachedProjectInput, D as ClassifiedCacheFileDelta, E as ClassifiedSrcDelta, c as CoreResolvedPaths, F as FilesIndexStatus, G as LocaleCodeReadSnapshot, H as LocaleReadCache, L as LocaleReadDiagnostic, I as LocaleReadDiagnosticLevel, J as LocaleSegmentReadSnapshot, K as LocalesLayoutMode, M as LocalesLayoutStructure, N as RunOptions, S as ScanDebugEvent, O as ScanDebugSkipDirectoryEvent, P as ScanDebugSkipFileEvent, T as TranslationSurfaceLeaf, Q as TranslationSurfaceShape, U as filesIndexIsUsable } from './coreContext-DMaWLvmB.js';
+import { R as RunEmitter, O as OperationId, b as ShareProjectManifest, c as ShareReportManifest, d as ShareKind, e as ShareCacheEntry, f as ShareManifest, g as ShareLinks, h as ShareJsonFile, i as ShareJsonHealReport } from './index-BgG01AKL.js';
+export { C as CleanupCounts, D as DoctorCounts, G as GenerateCounts, j as GeneratePhase, k as GenerateProgressEvent, L as LoadShareJsonResult, l as LocalesDynamicCounts, M as MissingCounts, P as ProgressEvent, Q as QualityCounts, m as ReportCounts, n as ReviewCounts, o as RunCompletedEvent, p as RunCountsByOperation, q as RunErrorEvent, a as RunEvent, r as RunEventBase, s as RunFailedEvent, t as RunMessageChannel, u as RunMessageEvent, v as RunMessageLevel, w as RunShareLinksEvent, x as RunShareManifestEvent, y as RunShareSkippedEvent, z as RunShareUploadedEvent, A as RunStartedEvent, B as RunSummaryEvent, E as RunWarningEvent, F as ShareCounts, H as ShareJsonHealKind, I as SyncCounts, J as SyncPhase, S as SyncProgressEvent, V as ValidateCounts, K as ValidatePhase, N as ValidateProgressEvent, W as WorkerShareEnvelope } from './index-BgG01AKL.js';
+import { I as Issue } from './index-X50E1FIX.js';
+export { C as CliJsonEnvelope, E as ErrResult, a as IssueSeverity, O as OkResult, R as Result, b as ResultMeta } from './index-X50E1FIX.js';
+import { H as HOSTED_PROJECT_SNAPSHOT_SCHEMA_VERSION } from './syncSegment-Bx6He2Mu.js';
+export { C as CliErrorCode, L as ListLocaleCodesResult, a as ListLocaleSegmentsResult, b as LocaleLeafProjection, c as LocaleSegmentRef, d as LocaleSegmentTarget, e as LocaleSegmentWritePlan, f as LocaleSegmentWriteRole, g as LocaleSegmentWriteTarget, M as MaskedText, N as NormalizedCliError, P as PathSegment, R as ReadFlatLocaleJsonSurfaceResult, h as ReadLocaleBundleResult, i as ResolveLocaleSegmentTargetsInput, S as SourceScanResult, j as SyncLangSelection, k as SyncSegmentSourcePlan, W as WalkedJsonSegment, l as WriteFlatLocaleJsonDocumentResult } from './syncSegment-Bx6He2Mu.js';
+import { C as CoreEngineRuntime } from './capabilities-x74cD2Hu.js';
+export { b as ConfigPathSystemRuntime, P as ProjectFilesystemRuntime, c as RuntimeFsCap, R as RuntimeNetworkCap, d as RuntimeNetworkPort, e as RuntimePathCap, f as RuntimeSystemCap, a as RuntimeSystemPort } from './capabilities-x74cD2Hu.js';
+import { R as RuntimePathPort } from './path-Bfn3SAts.js';
+import { T as TranslatePolicy, H as TranslatePolicyVerb, G as ScanExcludeConfig, J as PatchingCommandName, K as PatchingAction, N as PatchingLocaleRecord, Q as PatchingConfigInput, V as PatchingRuntimePorts } from './root-2-kCaBvQ.js';
+export { E as EffectiveReferenceConfig, W as KeyReferenceContext, X as LocaleConfigMismatch, Y as LocaleDirection, c as LocaleLeafPathApi, F as LocaleSegmentSource, Z as OnAuthFailureVerb, _ as OnIdentityOutputVerb, $ as OnIncompleteRunVerb, a0 as OnProviderUnavailableVerb, a1 as OnQuotaExceededVerb, a2 as OnRateLimitVerb, a3 as OnTransientFailureVerb, P as ParityPolicy, a4 as PatchingAnalyzeOutput, a5 as PatchingDiagnostic, a6 as PatchingFileEdit, a7 as PatchingLocaleImportSpec, a8 as PatchingMode, a9 as PatchingPlan, aa as PatchingRecipeId, ab as PatchingResult, ac as PatchingSkipReason, a as PreservePolicy, g as ReferenceCommandOverrides, m as ReferenceCommands, n as ReferenceConfig, ad as ReferenceConfigSource, o as ReferenceDefaults, ae as RepairPatchingConfigLocalesResult, af as ResolvePatchingLocalesResult, R as ResolveScannerConfigOptions, ag as ResolvedPatchingConfig, ah as ScanExcludePreset, ai as ScanExcludeRule, d as ScannerConfigInput, e as ScannerConfigResolved, aj as ScannerExecutionMode, S as StringPresencePolicy, ak as TRANSLATE_POLICY_DEFAULTS, al as TranslateHandoffMode, am as TranslateRoutingMode, U as UncertainKeyPolicy } from './root-2-kCaBvQ.js';
+import { c as TranslateFailureOutcome, P as ProviderAttemptOutcome, d as TranslateRunPartialStats, b as TranslationTickProgressFn } from './resumeCandidates-xR13eEwt.js';
+export { B as BuildTranslateCacheKeyForLocaleFileInput, g as BuildTranslateCacheKeyInput, f as GenerateResumeCandidateLeafInput, G as GenerateResumeRefContext, e as GenerateTranslateCache, h as GenerateTranslateCacheBase, i as HandoffCatalogBuildResult, H as HandoffEligibilityRow, j as IdentitySample, k as IdentityStreakConfirmFn, l as IdentityStreakConfirmInput, I as IdentityStreakGuard, m as IdentityStreakGuardOptions, n as IdentityStreakInteractive, o as IdentityStreakState, O as OpenTranslateCacheL2Options, p as TranslateCacheHitLayer, q as TranslateCacheL1Port, r as TranslateCacheL2Port, T as TranslateContext, s as TranslateLeafWithL1Result, t as TranslationCacheEntry, u as TranslationLocaleCacheFile } from './resumeCandidates-xR13eEwt.js';
+export { B as BuildInitConfigTemplateOptions, I as InitConfigFormat, j as InitDetectResult, d as InitFilesystemHost, l as InitJsonPayload, f as InitLocaleLayoutHint, c as InitPackageJsonSignals, k as InitPresetConfigFields, h as InitPresetId, g as InitPresetScore, i as InitProjectSignals, a as InitRunOptions, b as InitRunResult, m as InitScoreFactor, e as InitTopologySignals, R as RunInitHostInput } from './template-CGM-_WLT.js';
+export { S as StringLeaf } from './index-BQuLEQ9b.js';
+import { a as TranslationLeafMeta } from './index-B_ow_Xvr.js';
+export { A as ApplyLocaleMetadataModeInput, H as HeuristicLeafMetaInput, L as LeafDecision, R as ResolveLocaleLeafModeInput, d as TranslateRequest, b as TranslateTargetLanguage, e as TranslationLeafMetaPatch, f as TranslationProviderYield, T as TranslationResult, c as Translator, g as TranslatorRetryOptions } from './index-B_ow_Xvr.js';
+export { b as LocaleLeafDecisionAction, a as LocaleLeafMode, c as LocaleLeafRuntimeKind, d as LocaleMetadataLeafDecision, e as LocaleMetadataPathChange, f as LocaleMetadataRepairReason, L as LocaleMetadataReport, S as StructuredLocaleLeaf } from './index-DLwTogCo.js';
+import { L as LocaleListRow } from './sourceContext-1LQg3HiQ.js';
+export { A as AssertGenerateTargetCodesInput, R as ResolveResumeTargetCodesFromRawInput, S as SourceLocaleContext } from './sourceContext-1LQg3HiQ.js';
+export { R as ResolveLocaleTargetCodesInput } from './localeTargetCodes-BBIQjauw.js';
+export { M as MissingHostHooks, g as MissingJsonOutput, h as MissingJsonTarget, a as MissingPlaceholderLeaf, i as MissingPlaceholderLeafList, c as MissingRunOptions, d as MissingRunResult, f as MissingSegmentWrite, j as MissingSkippedTarget, k as MissingTargetKind, b as MissingTargetPlan, l as MissingTargetState, e as MissingWriteInput, R as ResolveMissingPathsPlanInput } from './index-CIzZl4W8.js';
+export { C as ComputeEnglishIdenticalCountsInput, Q as QualityFileLine, c as QualityHostHooks, a as QualityJsonData, b as QualityRunOptions, d as QualityRunResult } from './index-DVT26v11.js';
+export { CompiledScanExclude } from './types/shared.js';
+export { d as SyncFileLine, S as SyncHostHooks, c as SyncHumanLeafSummary, e as SyncJsonOutput, f as SyncLocaleDisplayGroup, b as SyncRunOptions, a as SyncRunResult } from './humanEmit-ygNlYX-S.js';
+import { C as CacheProfileId } from './profile-BwOP9WKh.js';
+export { a as CacheProfileDefaults } from './profile-BwOP9WKh.js';
+import { T as TranslationProviderId } from './providers-0uMEfT6q.js';
+export { D as DeeplResolvedTranslationOptions, G as GoogleResolvedTranslationOptions, L as LibreResolvedTranslationOptions, a as LlmResolvedTranslationOptions, M as MymemoryResolvedTranslationOptions, R as ResolvedTranslationProviderOptions, b as TranslationClientHints, c as TranslationProviderDescriptor, d as TranslationProviderEnvVar, e as TranslationProviderKind } from './providers-0uMEfT6q.js';
+export { P as ProviderRateLimitProfile, g as ProviderRateLimitRegistry, a as TranslateStartRateLimit } from './translate-CIHYp7wi.js';
+export { R as RuntimeAdapters, a as RuntimeKind } from './adapters-gp1lXp0T.js';
+export { a as RuntimeDirEntry, c as RuntimeFsPathKind, R as RuntimeFsPort, b as RuntimeReadFsPort } from './fs-BUYD8ZhA.js';
+import 'zod';
+import './index-DeIw-cZd.js';
+
+/**
+ * Outcome class accepted by {@link ProviderHealthMonitor.onAttemptResult}. Extends the failure
+ * taxonomy with `'success'`, which resets the consecutive-backoff counter for that provider.
+ */
+type ProviderHealthOutcome = 'success' | TranslateFailureOutcome;
+/**
+ * One attempt's worth of evidence the resolver feeds into the monitor.
+ *
+ * @remarks
+ * The monitor does not interpret which outcomes "deserve" a backoff. Callers (the policy
+ * resolver in step 5) decide which attempts to report — typically only when the resolved
+ * verb is `'backoff'`. Reporting an attempt always advances the counter (unless `outcome`
+ * is `'success'`) and may extend the no-start-before deadline if a hint is supplied or the
+ * exponential fallback applies.
+ */
+type ProviderAttemptObservation = {
+    readonly providerId: string;
+    readonly outcome: ProviderHealthOutcome;
+    /**
+     * Optional `Retry-After`-derived hint. When present and positive, extends the
+     * "no-start-before" deadline by `retryAfterMs`. The exponential fallback is skipped
+     * for this attempt — host hint always wins.
+     */
+    readonly hint?: {
+        readonly retryAfterMs?: number;
+    };
+};
+/**
+ * Per-provider start-gate health state. The interface is the **load-bearing primitive** of
+ * step 3 in `translate-policy (shipped)`; the start-rate gate consults
+ * {@link ProviderHealthMonitor.shouldDelayStartFor} on top of `rpm` / `rps` / `intervalMs`
+ * pacing, and the policy resolver consults {@link ProviderHealthMonitor.shouldEscalate}
+ * to upgrade `backoff` → `fallback` after consecutive backoffs exhaust.
+ */
+interface ProviderHealthMonitor {
+    /** Record one attempt for `providerId`. */
+    onAttemptResult(input: ProviderAttemptObservation): void;
+    /** Extra delay (ms) the start gate should add before launching a job for this provider. `0` if healthy. */
+    shouldDelayStartFor(providerId: string): number;
+    /** Consecutive non-success outcomes recorded since the last `'success'` (or process start). */
+    consecutiveBackoffsFor(providerId: string): number;
+    /** True when this provider's consecutive-backoff count is at or above the resolver's threshold. */
+    shouldEscalate(providerId: string, policy: {
+        readonly maxBackoffsBeforeEscalate: number;
+    }): boolean;
+}
+
+type TranslatePolicyAction = {
+    readonly verb: TranslatePolicyVerb;
+    readonly escalatedFrom?: TranslatePolicyVerb;
+    readonly reason: string;
+};
+type ResolveProviderActionInput = {
+    readonly outcome: TranslateFailureOutcome;
+    readonly policy: TranslatePolicy;
+    readonly health: ProviderHealthMonitor;
+    readonly providerId: string;
+    readonly escalationThreshold?: number;
+    readonly hint?: {
+        readonly retryAfterMs?: number;
+    };
+};
+
+/**
+ * Per-leaf input keyed by an arbitrary stable identifier. The translator preserves order; the
+ * **`key`** is echoed back in **`TranslateResultItem.key`** so callers can re-zip with their source.
+ */
+type TranslateLeafInput = {
+    readonly key: string;
+    readonly source: string;
+};
+/**
+ * Outcome of a single provider attempt within the translator's per-provider chain. Aggregated into
+ * **`TranslateOutput.providerAttempts`** so callers can render attempt history (CLI summary, SDK logs)
+ * without re-deriving it.
+ */
+type ProviderAttemptReport = {
+    readonly providerId: TranslationProviderId;
+    readonly outcome: ProviderAttemptOutcome;
+    /** Provider error message (when **`outcome !== 'success'`**); not always set on early failures. */
+    readonly errorMessage?: string;
+    /** Per-attempt stats (request attempts, retries, success/failure counts). */
+    readonly stats?: TranslateRunPartialStats;
+    /** Wall-clock duration of this attempt in milliseconds. */
+    readonly durationMs?: number;
+};
+/** Per-leaf result preserving input order; **`key`** present when input used **`leaves`**. */
+type TranslateResultItem = {
+    readonly ok: true;
+    readonly key?: string;
+    readonly value: string;
+    readonly providerId: TranslationProviderId;
+    readonly leafMeta?: TranslationLeafMeta;
+} | {
+    readonly ok: false;
+    readonly key?: string;
+    readonly reason: 'identity' | 'failed' | 'skipped';
+    readonly sourceValue: string;
+};
+/**
+ * Hooks let hosts observe the translator without owning orchestration. **`onTick`** drives a UI
+ * progress bar; **`onProviderAttempt`** records each attempt for an envelope; **`onTranslatedLeaf`**
+ * fires per leaf so the host can drive identity-streak prompts or write-through caches.
+ */
+type TranslateHooks = {
+    readonly onTick?: TranslationTickProgressFn;
+    readonly onProviderAttempt?: (attempt: ProviderAttemptReport) => void;
+    readonly onTranslatedLeaf?: (sourceText: string, translatedText: string, key: string | number) => void | Promise<void>;
+};
+/**
+ * Identity-streak guard wiring. Disabled by default; when **`enabled: true`** the translator wires the
+ * core **`createIdentityStreakGuard`** with the supplied threshold and surfaces accumulated streak
+ * issues on **`TranslateOutput.issues`**. Hosts that need an interactive confirm prompt should keep
+ * owning the guard themselves and pass results in via **`hooks.onTranslatedLeaf`**.
+ */
+type TranslateIdentityGuardOptions = {
+    readonly enabled?: boolean;
+    readonly threshold?: number;
+};
+/**
+ * Per-call options for **`runTranslate`**. The translator owns no project state — config / adapters /
+ * env are bundled in **`TranslateContext`** (the first argument). Use **`texts`** for plain string
+ * lists or **`leaves`** for keyed pairs; the output preserves input order.
+ */
+type TranslateOptions = {
+    /** Plain strings to translate; mutually exclusive with **`leaves`**. */
+    readonly texts?: readonly string[];
+    /** Keyed leaves; mutually exclusive with **`texts`**. */
+    readonly leaves?: readonly TranslateLeafInput[];
+    readonly targetLang: string;
+    readonly sourceLang?: string;
+    /** Pin a provider id (CLI **`--provider`**) and/or a **`workers`** override for this run. */
+    readonly pin?: {
+        providerId?: TranslationProviderId;
+        workers?: number;
+    };
+    readonly hooks?: TranslateHooks;
+    readonly identityGuard?: TranslateIdentityGuardOptions;
+};
+/**
+ * Result of **`runTranslate`** — translations preserve input order; **`providerAttempts`** records
+ * the attempted chain (success ends the chain, retryable failures advance it, non-retryable failures
+ * end the run); **`warnings`** is forwarded from **`resolveTranslateConfig`** so hosts can display
+ * default-applied notes.
+ */
+type TranslateOutput = {
+    readonly translations: ReadonlyArray<TranslateResultItem>;
+    readonly providerAttempts: ReadonlyArray<ProviderAttemptReport>;
+    readonly winnerProviderId: TranslationProviderId | null;
+    readonly fallbackCount: number;
+    readonly translateStats: TranslateRunPartialStats;
+    readonly issues: ReadonlyArray<Issue>;
+    readonly warnings: ReadonlyArray<Issue>;
+};
+
+/** Raw `cache` block from config (file, init template, or host flag layer). */
+type CacheConfigSource = {
+    enabled?: boolean;
+    dir?: string;
+    profile?: CacheProfileId;
+    mode?: 'readWrite' | 'readOnly';
+    rebuild?: CacheRebuildMode;
+    fullRescanThresholdPercent?: number;
+};
+/** Fully resolved cache policy after profile expansion and overrides. */
+type ResolvedCacheConfig = {
+    enabled: boolean;
+    profile: CacheProfileId;
+    mode: 'readWrite' | 'readOnly';
+    rebuild: CacheRebuildMode;
+    fullRescanThresholdPercent: number;
+    dir?: string;
+};
+
+/** Current tracked src + locale segment maps and layout fingerprint for one scan. */
+type TrackedProjectFilesCurrent = {
+    files: Record<string, CacheProjectFileRecord>;
+    localeSegments: Record<string, CacheProjectFileRecord>;
+    localesLayout: CachedLocalesLayout;
+    merged: Record<string, CacheProjectFileRecord>;
+};
+
+type AnalysisCacheInvalidationAction = 'delete' | 'skip';
+type AnalysisCacheInvalidationReason = 'cache_disabled' | 'no_locale_writes' | 'config_rebuild_full' | 'target_locale_writes_only' | 'locale_writes_dispatch_handles';
+type AnalysisCacheInvalidationDecision = {
+    action: AnalysisCacheInvalidationAction;
+    reason: AnalysisCacheInvalidationReason;
+};
+type LocaleWriteInvalidationInput = {
+    enabled: boolean;
+    rebuildConfig: CacheRebuildConfig;
+    sourceLocaleSegmentKey: string;
+    mutatedLocaleSegmentKeys: readonly string[];
+};
+
+type ScanProjectFileInput = {
+    filePath: string;
+    displayPath: string;
+    text: string;
+};
+type ScanProjectSourceFilesInput<T> = {
+    srcRoot: string;
+    /** Optional scan exclusions (dirs while walking, files, extensions, path patterns). */
+    exclude?: ScanExcludeConfig;
+    /** Optional scan debug sink (same contract as {@link listSourceFiles} fourth argument). */
+    scanDebug?: ListSourceFilesOptions['onScanDebug'];
+    cwd?: string;
+    /**
+     * When `readFile` / `listFiles` are omitted, **`runtime`** supplies defaults (host `fs` + `path` + `system.cwd()`).
+     * Type is {@link CoreEngineRuntime} (includes `system`), not only {@link ProjectFilesystemRuntime}.
+     * When both **`readFile`** and **`listFiles`** are set, also pass **`path`** (or **`runtime`**) so display paths can use `path.relative`.
+     */
+    runtime?: CoreEngineRuntime;
+    /** Used for `relative` when injecting `readFile`/`listFiles` without a full `runtime`. */
+    path?: RuntimePathPort;
+    readFile?: (filePath: string) => string;
+    listFiles?: (srcRoot: string) => string[];
+    scanFile: (input: ScanProjectFileInput) => readonly T[];
+};
+
+/**
+ * Shared filesystem + override fields for project-wide scans (key sites, dynamic sites, literal usage).
+ * Keeps orchestration `Pick<>` types aligned.
+ */
+type ScanProjectFilesystemInputBase = Pick<ScanProjectSourceFilesInput<unknown>, 'srcRoot' | 'cwd' | 'runtime' | 'path' | 'readFile' | 'listFiles' | 'exclude'>;
+
+type ScanProjectDynamicKeySitesInput = ScanProjectFilesystemInputBase & {
+    functions: string[];
+};
+
+type DynamicRunOptions = {
+    top?: number;
+    full?: boolean;
+};
+type DynamicHostHooks = {
+    emit?: RunEmitter;
+    runId?: string;
+};
+type DynamicJsonPayload = {
+    kind: 'locales-dynamic';
+    sourceLocalePath: string;
+    sourceLocaleCode: string;
+    top: number | null;
+    full: boolean;
+    shown: number;
+    dynamic: {
+        count: number;
+        sites: DynamicKeySite[];
+    };
+};
+type DynamicRunResult = {
+    payload: DynamicJsonPayload;
+    issues: Issue[];
+    allSites: DynamicKeySite[];
+};
+
+type ListJsonPayload = {
+    kind: 'locales-list';
+    sourceLocaleCode: string;
+    sourceLocalePath: string;
+    localesDir: string;
+    localeCount: number;
+    targetLocaleCount: number;
+    rows: LocaleListRow[];
+};
+type ListRunResult = {
+    payload: ListJsonPayload;
+    issues: Issue[];
+};
+
+type DeleteTargetResult = {
+    target: string;
+    /** Segment paths removed for this locale code (e.g. `app/ar.json`). */
+    deletedSegmentRelativePaths: string[];
+    deletedJsonCount: number;
+};
+type DeleteJsonPayload = {
+    kind: 'locales-delete';
+    targets: string[];
+    /** JSON segment files removed on disk. */
+    deletedJson: number;
+    /** Distinct locale codes that had at least one segment file removed. */
+    deletedLocaleCount: number;
+    aborted: boolean;
+    supportsAutoPatching: false;
+};
+type DeleteRunResult = {
+    payload: DeleteJsonPayload;
+    issues: Issue[];
+    deletedTargets: DeleteTargetResult[];
+};
+
+type ScanKeyObservationsOptions = {
+    /** When set, skip calls whose start offset lies inside these comment ranges (line/block). */
+    commentRanges?: Array<{
+        start: number;
+        end: number;
+    }>;
+};
+
+type ScanProjectKeyObservationsInput = ScanProjectFilesystemInputBase & {
+    functions: string[];
+};
+
+type ScanProjectLiteralKeyUsageInput = ScanProjectFilesystemInputBase & {
+    functions: string[];
+};
+
+type ProjectAnalysisCounts = {
+    keyObservations: number;
+    dynamicSites: number;
+    sourceFilesScanned: number;
+    missingKeys: number;
+};
+/** On-disk `analysis.json` payload (`data` field of the run envelope). */
+type ProjectAnalysisCacheData = {
+    version: 1;
+    keyObservations: KeyObservation[];
+    dynamicSites: DynamicKeySite[];
+    missingKeys: string[];
+    counts: ProjectAnalysisCounts;
+};
+type ProjectAnalysis = ProjectAnalysisCacheData & {
+    usage: ProjectLiteralKeyUsage;
+    cache?: CacheDispatchInfo;
+};
+type ProjectAnalysisResolveOptions = {
+    emit?: RunEmitter;
+    op?: OperationId;
+    runId?: string;
+};
+
+/** Stable identifiers for the built-in doctor checks. */
+type DoctorCheckId = 'runtime' | 'tools' | 'config' | 'paths';
+/** Single finding produced by a doctor check. */
+type DoctorFinding = {
+    id: DoctorCheckId;
+    ok: boolean;
+    severity: 'ok' | 'warn' | 'error';
+    title: string;
+    detail?: string;
+};
+
+/** Per-call options for `runDoctor`. */
+type DoctorRunOptions = {
+    /** Comma-separated list of check IDs to run (e.g. `"runtime,paths"`). Omit to run all. */
+    only?: string;
+    /** When true, warnings are treated as errors for exit-code purposes. */
+    strict?: boolean;
+};
+/**
+ * Host-supplied environment facts that core cannot discover on its own.
+ *
+ * @remarks Doctor checks are pure — core never calls `process.*` or probes the filesystem
+ * directly. The host (CLI, SDK consumer, test harness) reads the real environment and
+ * passes the facts here.
+ */
+type DoctorHostHooks = {
+    emit?: RunEmitter;
+    runId?: string;
+    /** `process.version` string (e.g. `"v20.18.2"`). */
+    nodeVersion: string;
+    /** Whether `rg` (ripgrep) is available on `$PATH`. */
+    rgAvailable: boolean;
+    /** Whether an `i18nprune.config.*` file was found. */
+    hasConfigFile: boolean;
+    /** Display label for the resolved config file path (or `null` when no file). */
+    configPathLabel: string | null;
+};
+/** Result returned by `runDoctor`. */
+type DoctorRunResult = {
+    payload: DoctorJsonPayload;
+    issues: Issue[];
+    exitCode: number;
+};
+/** JSON `data` shape for the `doctor` envelope. */
+type DoctorJsonPayload = {
+    kind: 'doctor';
+    findings: DoctorFinding[];
+    strict: boolean;
+};
+
+type TranslationCallSite = {
+    functionName: string;
+    matchIndex: number;
+    openParenIndex: number;
+    closeParenIndex: number;
+    firstArgStart: number;
+    firstArgEnd: number;
+    firstArgRaw: string;
+    isEmptyCall: boolean;
+    isMultilineCall: boolean;
+};
+
+/** Result of resolving `${IDENT}` placeholders in a template fragment. */
+type ResolveKeyPlaceholdersTraceResult = {
+    /** Fully resolved dotted key, or `null` if a placeholder could not be substituted. */
+    resolved: string | null;
+    /** Ordered substitutions applied from `constMap`. */
+    substitutions: ConstSubstitutionStep[];
+    /** Fragment after the last successful step, if resolution failed mid-way. */
+    remainder: string;
+};
+
+/**
+ * Where a binding came from syntactically (regex scan — no AST).
+ *
+ * @remarks Arbitrary variable propagation (e.g. `const x = getI18n()`) is intentionally out of scope.
+ */
+type ImportBindingSource = 'esm' | 'cjs_require' | 'dynamic_import' | 'ts_import_equals';
+/**
+ * A resolved import-related binding used to expand configured `functions[]`.
+ *
+ * @remarks Two shapes: **named** (direct calls `t()`, `translate()`) and **module**
+ * (member calls `i18n.t()`, `i18n?.t()` after expansion). Regex-based only — string literals
+ * and nested generics can false-positive. Bracket calls like `i18n['t']()` are not modeled here;
+ * call-site regex would need a separate extension.
+ */
+type ImportBinding = {
+    kind: 'named';
+    /** Exported / property name (`t` in `import { t as translate }`). */
+    imported: string;
+    /** Local identifier used in the file. */
+    local: string;
+    source: ImportBindingSource;
+    /**
+     * When set, runtime call detection must ignore this binding
+     * (e.g. `import type { TFunction }`).
+     */
+    isTypeOnly?: true;
+} | {
+    kind: 'module';
+    /** Local identifier (`i18n` in `import * as i18n`). */
+    local: string;
+    moduleKind: 'default' | 'namespace';
+    source: ImportBindingSource;
+    isTypeOnly?: true;
+};
+
+type PatchingRunInput = {
+    command: PatchingCommandName;
+    action: PatchingAction;
+    changedLocaleCodes: string[];
+    /** Optional records for upsert operations that need exact metadata rather than catalog defaults. */
+    upsertLocaleRecords?: readonly PatchingLocaleRecord[];
+    sourceLocaleCode?: string;
+    config?: PatchingConfigInput;
+    runtime: PatchingRuntimePorts;
+    /**
+     * Root for resolving relative **`configPath`**, **`loaderPath`**, and **`localeJsonImportBase`** (directory of
+     * **`i18nprune.config.*`** in normal CLI runs). Unit tests may omit and resolve **`localeJsonImportBase`**
+     * from **`loaderPath`**’s directory instead.
+     */
+    projectRoot?: string;
+    /**
+     * When **`true`**, completeness checks behave as if **`--patch`** forced a patching run
+     * (e.g. **doctor** with global **`--patch`** even if **`patching.enabled`** is false).
+     */
+    treatAsPatchRequested?: boolean;
+    /** Resolved i18nprune locales layout — enables multi-segment locale discovery and loader imports. */
+    localesLayout?: ResolvedLocalesLayout;
+};
+
+/** Per-locale aggregates (plain strings + optional structured `{ value, status, … }` leaves). */
+type ReviewLocaleStats = {
+    stringPaths: number;
+    englishIdentical: number;
+    legacyLeaves: number;
+    structuredLeaves: number;
+    needsReviewTrue: number;
+    needsReviewFalse: number;
+    needsReviewUnset: number;
+    /** Structured `{ value, … }` leaves where `needsReview` is missing, non-boolean, or absent. */
+    structuredLeavesMissingNeedsReview: number;
+    /** Structured leaves where `confidence` is missing, non-finite, or JSON `null`. */
+    structuredLeavesMissingConfidence: number;
+    byStatus: Record<string, number>;
+    bySource: Record<string, number>;
+    confidenceBuckets: {
+        none: number;
+        low: number;
+        mid: number;
+        high: number;
+    };
+};
+/** Options for the review operation. */
+type ReviewRunOptions = {
+    /** Comma-separated locale basenames, or `all` / omit for every non-source file. */
+    target?: string;
+};
+/** Payload returned by `runReview`; CLI wraps this in its stable JSON envelope. */
+type ReviewJsonData = {
+    kind: 'localeReview';
+    sourceLocale: string;
+    localesDir: string;
+    dynamicKeySites: number;
+    locales: Record<string, ReviewLocaleStats>;
+};
+type ReviewHostHooks = {
+    emit?: RunEmitter;
+    runId?: string;
+    /** Max locale blocks in human output (from CLI list window). */
+    listLimit?: number;
+};
+type ReviewRunResult = {
+    payload: ReviewJsonData;
+    issues: Issue[];
+    keyObservationsCount: number;
+};
+
+type SaveShareJsonResult = {
+    warning?: Issue;
+};
+type ShareJsonBackupResult = {
+    created: boolean;
+    /** Absolute path to the backup file when {@link created} is true. */
+    bakPath?: string;
+};
+type ShareCacheDebugLine = {
+    level: 'info' | 'detail';
+    message: string;
+};
+
+/** Host hooks for share human stderr lines (`emit` + optional `runId`). */
+type ShareHumanMessageHost = {
+    emit?: RunEmitter;
+    runId?: string;
+};
+
+/**
+ * Environment snapshot captured by the host at report-generation time.
+ *
+ * Core never probes `process.*` or `os.*` directly — the CLI (or any host)
+ * fills this and passes it via {@link ReportHostHooks}.
+ *
+ * @remarks Fields mirror `ProjectReportEnvironment` from `@i18nprune/core/report-schema`
+ * so the document shape stays consistent without a hard type dependency.
+ */
+type ReportEnvironmentSnapshot = {
+    /** Node.js `process.platform` (e.g. `'linux'`, `'darwin'`, `'win32'`). */
+    platform: string;
+    /** Node.js `process.arch` (e.g. `'x64'`, `'arm64'`). */
+    arch: string;
+    /** Node.js version string (e.g. `'v20.12.0'`). */
+    nodeVersion: string;
+    /** OS kernel release string from `os.release()`. */
+    osRelease: string;
+    /** Linux distribution name from `/etc/os-release`, if available. */
+    distro?: string;
+    /** WSL distribution name from `WSL_DISTRO_NAME` env var, if running under WSL. */
+    wslDistroName?: string;
+    /**
+     * Runtime/filesystem compatibility family.
+     * `edge-worker` is a synthetic hosted runtime (no local filesystem assumptions).
+     */
+    runtimeFamily: 'windows' | 'darwin' | 'linux' | 'linux-wsl' | 'edge-worker';
+};
+
+/** Machine-facing scalar for transport payloads. */
+type MetadataScalar = string | number | null;
+/** Built-in ingest routes; hosts/SDKs may send other route ids via `processorContext.route`. */
+type KnownIngestRouteKind = 'prepared' | 'archive';
+/** `prepared` | `archive` | `custom` | any SDK-specific route id (e.g. `ci-upload`). */
+type IngestRouteKind = KnownIngestRouteKind | 'custom' | (string & {});
+/** Built-in prepare surfaces; SDKs may set `processorContext.surface` to any stable id. */
+type KnownPayloadProcessorSurface = 'cli' | 'web' | 'worker';
+/** `cli` | `web` | `worker` | `custom` | any SDK label (e.g. `github-action`, `acme-ci`). */
+type PayloadProcessorSurface = KnownPayloadProcessorSurface | 'custom' | (string & {});
+type PayloadProcessorEnvironment = {
+    platform: MetadataScalar;
+    arch: MetadataScalar;
+    nodeVersion: MetadataScalar;
+    osRelease: MetadataScalar;
+    distro?: MetadataScalar;
+    wslDistroName?: MetadataScalar;
+    runtimeFamily: MetadataScalar;
+};
+/**
+ * Analysis/files cache state at prepare time (host only).
+ * Helps interpret sub-second `timing.prepare` when analysis was served from cache.
+ */
+type HostPrepareCacheMeta = {
+    analysis: CacheDispatchStatus | 'unavailable';
+    analysisReason: MetadataScalar;
+    /** False when analysis cache hit and prepare ms are not a full rescan (trust extraction counts, not prepare ms). */
+    timingsTrustworthy: boolean;
+    filesEpoch: MetadataScalar;
+    projectCacheEnabled: boolean;
+};
+/** Stable `processor` block on GET metadata — same keys for every surface. */
+type PayloadProcessorInfo = {
+    surface: PayloadProcessorSurface;
+    surfaceLabel: MetadataScalar;
+    route: IngestRouteKind;
+    routeLabel: MetadataScalar;
+    prepareHost: MetadataScalar;
+    toolVersion: MetadataScalar;
+    sdk: MetadataScalar;
+    /** Semver of `@i18nprune/core` used to prepare the payload. */
+    sdkVersion: MetadataScalar;
+    prepareSummary: MetadataScalar;
+    environment: PayloadProcessorEnvironment | null;
+};
+/** Optional host context on JSON ingest (CLI / web / custom SDK). */
+type HostedIngestProcessorContext = {
+    /** Surface id; built-ins: cli | web | worker | custom — any string allowed for SDK hosts. */
+    surface?: string;
+    /** Display name override (e.g. "Acme CI", "GitHub Action"). */
+    surfaceLabel?: string;
+    /** Route id; built-ins: prepared | archive | custom. */
+    route?: string;
+    routeLabel?: string;
+    prepareSummary?: string;
+    /** SDK package or integration name when not i18nprune CLI/web. */
+    sdk?: string;
+    /** Semver of `@i18nprune/core` (SDK) used at prepare time. */
+    sdkVersion?: string;
+    toolVersion?: string;
+    environment?: ReportEnvironmentSnapshot;
+};
+type ProjectMetadataPrepareTiming = {
+    zipParsedMs: MetadataScalar;
+    analysisMs: MetadataScalar;
+    extractionMs: MetadataScalar;
+    totalMs: MetadataScalar;
+};
+type ProjectMetadataExtractionTiming = {
+    startedAt: MetadataScalar;
+    computedAt: MetadataScalar;
+    durationMs: MetadataScalar;
+};
+type ProjectMetadataEdgeTiming = {
+    persistMs: MetadataScalar;
+};
+/** Ordered timing block for `GET /v1/projects/:id` and upload meta. */
+type ProjectMetadataTiming = {
+    /** Payload ready to persist (host prepare on prepared route; worker zip parse end on archive). */
+    preparedAt: MetadataScalar;
+    requestReceivedAt: MetadataScalar;
+    storedAt: MetadataScalar;
+    lastAccessedAt: MetadataScalar;
+    prepare: ProjectMetadataPrepareTiming;
+    extraction: ProjectMetadataExtractionTiming;
+    edge: ProjectMetadataEdgeTiming;
+};
+type ProjectExtractionCacheMeta = {
+    available: boolean;
+    analysis: CacheAnalysisState;
+    analysisReason: MetadataScalar;
+    timingsTrustworthy: boolean;
+    filesEpoch: MetadataScalar;
+    projectCacheEnabled: boolean;
+};
+type CacheAnalysisState = 'hit' | 'miss' | 'disabled' | 'unavailable' | 'bypassed' | null;
+type ProjectStoredSummary = {
+    localeCount: number;
+    missingKeysCount: number | null;
+    ok: boolean | null;
+};
+type ProjectStoredArtifactMeta = {
+    kind: 'project';
+    id: string;
+    contentHash: string;
+    byteSize: number;
+    fileCount: number;
+    textFileCount: number;
+    detectedConfigPath: string | null;
+    localeTags: string[];
+};
+type ProjectStoredExecutionMeta = {
+    surface: MetadataScalar;
+    host: MetadataScalar;
+    route: MetadataScalar;
+    transport: 'https-json';
+    computeLocation: 'edge';
+};
+type ProjectStoredAnalysisMeta = {
+    localeTags: string[];
+    detectedConfigPath: string | null;
+    configHash: MetadataScalar;
+    sourceLocalePath: MetadataScalar;
+    srcRoot: MetadataScalar;
+    localesDir: MetadataScalar;
+    keyObservationsCount: number;
+    dynamicSitesCount: number;
+};
+type ProjectStoredStorageMeta = {
+    backend: 'durable-object';
+    dedupByContentHash: true;
+    contentAddressed: true;
+};
+type ProjectStoredRetentionMeta = {
+    policy: 'idle-7d';
+    expiresAt: MetadataScalar;
+    lastAccessedAt: MetadataScalar;
+};
+type ProjectStoredCapabilitiesMeta = {
+    preparedUploads: true;
+    archiveUploads: true;
+    readOperations: readonly ['metadata', 'snapshot', 'tree', 'validate', 'review', 'missing', 'locales', 'doctor', 'report'];
+    project: true;
+    report: false;
+};
+type ReportMetadataDocumentTiming = {
+    requestReceivedAt?: MetadataScalar;
+    preparedAt: MetadataScalar;
+    storedAt: MetadataScalar;
+    lastAccessedAt: MetadataScalar;
+    prepare?: ProjectMetadataPrepareTiming;
+    edge: ProjectMetadataEdgeTiming;
+};
+type ProjectStoredMetadata = {
+    /** Metadata envelope contract version. */
+    schemaVersion: 1;
+    /** Underlying hosted artifact format version. */
+    formatVersion: 1;
+    artifact: ProjectStoredArtifactMeta;
+    timing: ProjectMetadataTiming;
+    processor: PayloadProcessorInfo;
+    execution: ProjectStoredExecutionMeta;
+    analysis: ProjectStoredAnalysisMeta | null;
+    summary: ProjectStoredSummary;
+    cache: ProjectExtractionCacheMeta;
+    storage: ProjectStoredStorageMeta;
+    retention: ProjectStoredRetentionMeta;
+    capabilities: ProjectStoredCapabilitiesMeta;
+};
+
+/**
+ * Project zip tree nodes for worker + web runtime (`GET .../tree`, `snapshot.tree`).
+ * `path` appears once per node; file fields live under `meta` (no nested duplicate `path`/`kind`).
+ */
+type ProjectTreeFileMeta = {
+    kind: 'file';
+    size: number;
+    ext: string;
+    mimeGuess: string;
+    textLike: boolean;
+};
+type ProjectTreeDirMeta = {
+    kind: 'directory';
+};
+type ProjectTreeNode = {
+    path: string;
+    meta: ProjectTreeFileMeta | ProjectTreeDirMeta;
+    children?: ProjectTreeNode[];
+};
+
+type ProjectUploadExtractionSummary = {
+    configHash: string;
+    sourceLocalePath: string;
+    srcRoot: string;
+    localesDir: string;
+    resolvedKeys: string[];
+    keyObservationsCount: number;
+    dynamicSitesCount: number;
+    keyObservationsPreview: unknown[];
+    dynamicSitesPreview: unknown[];
+    /** ISO timestamp immediately before key/dynamic extraction scan. */
+    extractionStartedAt?: string;
+    /** ISO timestamp after locale map + previews are assembled. */
+    computedAt: string;
+};
+/** Parsed project zip snapshot (worker DO + web local session). */
+type ProjectSnapshot = {
+    projectId: string;
+    projectHash: string;
+    /** ISO timestamp when the worker ingest handler received the request. */
+    requestReceivedAt?: string;
+    /** ISO timestamp when the payload was fully prepared (host prepare or worker zip parse + extraction). */
+    preparedAt: string;
+    /** ISO timestamp when the DO row was persisted successfully. */
+    storedAt?: string;
+    zipBytes: number;
+    fileCount: number;
+    textFileCount: number;
+    detectedConfigPath: string | null;
+    detectedConfigRaw: string | null;
+    tree: ProjectTreeNode[];
+    resolvedConfig: Record<string, unknown> | null;
+    sourceLocaleJson: Record<string, unknown> | null;
+    localeJsonByTag: Record<string, Record<string, unknown>>;
+    /** Locale codes discovered at prepare (flat_file or locale_directory layouts). */
+    localeTags?: string[];
+    extraction: ProjectUploadExtractionSummary | null;
+};
+type ParsedProjectUpload = {
+    snapshot: ProjectSnapshot;
+    textFiles: Record<string, string>;
+};
+
+/** High-resolution prepare timings (measured where prepare runs on the host). */
+type ProjectPrepareMeta = {
+    prepareHost?: string;
+    zipParsedMs?: number;
+    analysisMs?: number;
+    extractionMs?: number;
+    totalMs?: number;
+    /** Measured DO persist on worker ingest (ms). */
+    persistMs?: number;
+    /** Host project-cache dispatch at prepare time (CLI/web/SDK). */
+    hostCache?: HostPrepareCacheMeta;
+};
+/** Primary worker ingest body: prepared snapshot from core (CLI / web / edge zip mode). */
+type HostedProjectIngestEnvelope = {
+    schemaVersion: typeof HOSTED_PROJECT_SNAPSHOT_SCHEMA_VERSION;
+    snapshot: ProjectSnapshot;
+    prepareMeta?: ProjectPrepareMeta;
+    /** Host SDK context (CLI / web); omitted on worker-only archive uploads. */
+    processorContext?: HostedIngestProcessorContext;
+    /** When true, worker stores payload even if content hash already exists (replaces prior row). */
+    force?: boolean;
+};
+type PrepareProjectSnapshotResult = {
+    ok: true;
+    parsed: ParsedProjectUpload;
+    prepareMeta: ProjectPrepareMeta;
+} | {
+    ok: false;
+    issues: Issue[];
+};
+type PrepareHostKind = 'cli-share' | 'web' | 'worker-archive';
+type PrepareProjectSnapshotFromRootInput = {
+    ctx: CoreContext;
+    projectRoot: string;
+    projectId: string;
+    projectHash: string;
+    prepareHost?: PrepareHostKind;
+    requestReceivedAt?: string;
+    analysisOpts?: Pick<ProjectAnalysisResolveOptions, 'emit' | 'runId'>;
+};
+
+type HostedProjectShareArtifacts = {
+    envelope: HostedProjectIngestEnvelope;
+    serialized: string;
+    manifest: ShareProjectManifest;
+};
+type BuildHostedProjectShareArtifactsResult = ({
+    ok: true;
+} & HostedProjectShareArtifacts) | {
+    ok: false;
+    issues: Issue[];
+};
+type HostedReportShareArtifacts = {
+    document: unknown;
+    manifest: ShareReportManifest;
+};
+
+/** Host-facing options for `runShare` upload (CLI maps Commander flags here; SDK/IDE pass fields directly). */
+type ShareUploadOptions = {
+    project?: boolean;
+    report?: boolean;
+    /** Report JSON path when `report` is set (optional — hosts may scan in-process instead). */
+    from?: string;
+    workerUrl?: string;
+    force?: boolean;
+};
+type ShareListOptions = {
+    /** Filter to one worker-hosted project id. */
+    project?: string;
+    /** Filter to one worker-hosted report id. */
+    report?: string;
+    workerUrl?: string;
+};
+type ShareViewOptions = {
+    project?: string;
+    report?: string;
+    workerUrl?: string;
+    /** Extra worker metadata sections (processor, cache, timings) in human and JSON output. */
+    verbose?: boolean;
+};
+type ShareDeleteOptions = {
+    project?: string;
+    report?: string;
+    workerUrl?: string;
+    /** When true, skip `DELETE /v1/projects/:id` or `/v1/reports/:id` (local `share.json` only). */
+    localOnly?: boolean;
+    /** Delete every row in `share.json` for this project (mutually exclusive with `--project` / `--report`). */
+    all?: boolean;
+};
+
+/** One key=value block in share view verbose output (`--verbose` / `--json`). */
+type ShareViewVerboseSectionValue = string | number | boolean | null | readonly string[];
+type ShareViewVerboseSection = Record<string, ShareViewVerboseSectionValue>;
+/** Structured sections returned on `share view --verbose` (human + JSON `verbose` field). */
+type ShareViewVerboseDetail = {
+    kind: 'project' | 'report';
+    workerId: string;
+    processor: ShareViewVerboseSection;
+    extraction?: ShareViewVerboseSection;
+    snapshot?: ShareViewVerboseSection;
+    cache?: ShareViewVerboseSection;
+    timings?: ShareViewVerboseSection;
+    edge?: ShareViewVerboseSection;
+    local?: ShareViewVerboseSection;
+    links: ShareViewVerboseSection;
+};
+
+type ShareUploadJsonPayload = {
+    kind: 'share';
+    shareKind: ShareKind;
+    action: 'uploaded' | 'skipped' | 'link-only';
+    manifest?: ShareManifest;
+    links: ShareLinks;
+    workerIds: {
+        projectId?: string;
+        reportId?: string;
+    };
+    skippedReason?: string;
+    cacheEntry?: ShareCacheEntry;
+    workerExpiresAt?: string;
+    workerDeduped?: boolean;
+};
+type ShareListJsonPayload = {
+    kind: 'share-list';
+    entries: ShareCacheEntry[];
+};
+type ShareViewJsonPayload = {
+    kind: 'share-view';
+    shareKind: ShareKind;
+    workerId: string;
+    /** Canonical raw worker metadata payload. */
+    remote?: unknown;
+    local?: ShareCacheEntry;
+    links: ShareLinks;
+    /** Present when CLI passed `--verbose` (including with `--json`). */
+    verbose?: ShareViewVerboseDetail;
+};
+type ShareDeleteRowResult = {
+    shareKind: ShareKind;
+    workerId: string;
+    deletedLocal: boolean;
+    deletedRemote: boolean;
+    remoteAlreadyAbsent?: boolean;
+};
+type ShareDeleteJsonPayload = {
+    kind: 'share-delete';
+    shareKind: ShareKind;
+    workerId: string;
+    deletedLocal: boolean;
+    deletedRemote: boolean;
+    remoteAlreadyAbsent?: boolean;
+};
+type ShareDeleteAllJsonPayload = {
+    kind: 'share-delete-all';
+    deletions: ShareDeleteRowResult[];
+    aborted?: boolean;
+};
+
+type BuildProjectPayloadResult = {
+    ok: true;
+    zipBytes: Uint8Array;
+    manifest: ShareProjectManifest;
+} | {
+    ok: false;
+    issues: Issue[];
+};
+type BuildPreparedProjectPayloadResult = {
+    ok: true;
+    envelope: HostedProjectIngestEnvelope;
+    serialized: string;
+    manifest: ShareProjectManifest;
+    prepare: PrepareProjectSnapshotResult & {
+        ok: true;
+    };
+} | {
+    ok: false;
+    issues: Issue[];
+};
+type BuildPreparedProjectPayloadInput = {
+    ctx: CoreContext;
+    projectRoot: string;
+    analysisOpts?: Pick<ProjectAnalysisResolveOptions, 'emit' | 'runId'>;
+    prepareHost?: PrepareProjectSnapshotFromRootInput['prepareHost'];
+    requestReceivedAt?: string;
+    processorContext?: HostedIngestProcessorContext;
+};
+/** Issue emitted while assembling share zip bytes from collected paths. */
+type ShareZipBuildIssue = Issue;
+
+type ValidateReportIngestResult = {
+    ok: true;
+    document: Record<string, unknown>;
+    serialized: string;
+    manifest: ShareReportManifest;
+    /** Present when report was built from archive prepare (worker zip path). */
+    prepareMeta?: ProjectPrepareMeta;
+    /** When true, worker stores even if payload content hash already exists. */
+    force?: boolean;
+} | {
+    ok: false;
+    issues: Issue[];
+};
+
+type PrepareShareHostedInput = {
+    ctx: CoreContext;
+    projectRoot: string;
+    projectId: string;
+    projectHash: string;
+    wantProject: boolean;
+    wantReport: boolean;
+    prepareHost?: PrepareHostKind;
+    requestReceivedAt?: string;
+    analysisOpts?: Pick<ProjectAnalysisResolveOptions, 'emit' | 'runId'>;
+    reportHost?: {
+        environment: ReportEnvironmentSnapshot;
+        cwd: string;
+        toolVersion: string;
+    };
+};
+type PrepareShareHostedResult = {
+    ok: true;
+    prepareMeta: ProjectPrepareMeta;
+    project?: PrepareProjectSnapshotResult & {
+        ok: true;
+    };
+    report?: ValidateReportIngestResult & {
+        ok: true;
+    };
+    analysis?: ProjectAnalysis;
+} | {
+    ok: false;
+    issues: Issue[];
+};
+
+/** Summary fields extracted from a stored report document (metadata GET). */
+type StoredReportSummary = {
+    missingKeysCount: number;
+    dynamicSitesCount: number;
+    keyObservationsCount: number;
+    ok: boolean;
+};
+type StoredReportArtifactMeta = {
+    kind: 'report';
+    id: string;
+    contentHash: string;
+    byteSize: number;
+    formatVersion: number;
+    toolVersion: MetadataScalar;
+};
+type StoredReportExecutionMeta = {
+    surface: MetadataScalar;
+    host: MetadataScalar;
+    route: MetadataScalar;
+    transport: 'https-json';
+    computeLocation: 'edge';
+};
+type StoredReportAnalysisMeta = {
+    sourceLocalePath: MetadataScalar;
+    localesDir: MetadataScalar;
+    srcRoot: MetadataScalar;
+    missingKeysCount: number;
+    dynamicSitesCount: number;
+    keyObservationsCount: number;
+    ok: boolean;
+};
+type StoredReportStorageMeta = {
+    backend: 'durable-object';
+    dedupByContentHash: true;
+    contentAddressed: true;
+};
+type StoredReportRetentionMeta = {
+    policy: 'idle-7d';
+    expiresAt: MetadataScalar;
+    lastAccessedAt: MetadataScalar;
+};
+type StoredReportCapabilitiesMeta = {
+    preparedUploads: true;
+    archiveUploads: true;
+    readOperations: readonly ['metadata', 'document'];
+    project: false;
+    report: true;
+};
+/** Worker `GET /v1/reports/:id` payload (metadata only). */
+type StoredReportMetadata = {
+    /** Metadata envelope contract version. */
+    schemaVersion: 1;
+    /** Underlying hosted artifact format version. */
+    formatVersion: 1;
+    artifact: StoredReportArtifactMeta;
+    timing: ReportMetadataDocumentTiming;
+    processor: PayloadProcessorInfo;
+    summary: StoredReportSummary;
+    execution: StoredReportExecutionMeta;
+    analysis: StoredReportAnalysisMeta;
+    cache: ProjectExtractionCacheMeta;
+    storage: StoredReportStorageMeta;
+    retention: StoredReportRetentionMeta;
+    capabilities: StoredReportCapabilitiesMeta;
+};
+
+/** Reused across multiple {@link runShare} calls in one host command (e.g. CLI `--project` + `--report`). */
+type ShareRunShareJsonSession = {
+    sharePath?: string;
+    shareFile: ShareJsonFile;
+    /** After the first load, suppress repeated `share.json` / `entries loaded` `[cache]` lines. */
+    shareJsonLoadDebugDone?: boolean;
+};
+
+type ShareWorkerProjectRef = {
+    kind: 'project';
+    workerBaseUrl: string;
+    workerProjectId: string;
+};
+type ShareWorkerReportRef = {
+    kind: 'report';
+    workerBaseUrl: string;
+    workerReportId: string;
+};
+type ShareRunInputProjectBuild = {
+    ctx: CoreContext;
+    /** Absolute project root (host resolves from config path / cwd). */
+    projectRoot: string;
+    workerBaseUrl: string;
+    kind: 'project';
+    source: 'build';
+    force?: boolean;
+    hooks: ShareHostHooks;
+    /** When set, skips disk prepare (e.g. combined `prepareShareHostedFromContext`). */
+    prepared?: {
+        envelope: HostedProjectIngestEnvelope;
+        serialized: string;
+        manifest: ShareProjectManifest;
+    };
+};
+type ShareRunInputProjectWorkerRef = {
+    ctx: CoreContext;
+    projectRoot: string;
+    workerBaseUrl: string;
+    kind: 'project';
+    source: 'worker-ref';
+    workerRef: ShareWorkerProjectRef;
+    hooks: ShareHostHooks;
+};
+type ShareRunInputReportDocument = {
+    ctx: CoreContext;
+    projectRoot: string;
+    workerBaseUrl: string;
+    kind: 'report';
+    source: 'document';
+    reportDocument: unknown;
+    force?: boolean;
+    hooks: ShareHostHooks;
+    /** When set, skips {@link validateReportIngest} (document + manifest already validated). */
+    prepared?: {
+        document: unknown;
+        manifest: ShareReportManifest;
+    };
+};
+type ShareRunInputReportWorkerRef = {
+    ctx: CoreContext;
+    projectRoot: string;
+    workerBaseUrl: string;
+    kind: 'report';
+    source: 'worker-ref';
+    workerRef: ShareWorkerReportRef;
+    hooks: ShareHostHooks;
+};
+type ShareRunInput = ShareRunInputProjectBuild | ShareRunInputProjectWorkerRef | ShareRunInputReportDocument | ShareRunInputReportWorkerRef;
+type ShareHostHooks = {
+    emit?: RunEmitter;
+    runId?: string;
+    /** When true, emit `[cache]` diagnostics (host maps to `--debug-cache`). */
+    debugCache?: boolean;
+    /** When true, core stops after manifest + policy (no upload hooks). */
+    dryRun?: boolean;
+    /** When false, core skips `confirmUpload` and uploads immediately after manifest (unless policy skips). */
+    interactive?: boolean;
+    confirmUpload?: (input: {
+        message: string;
+        defaultValue: boolean;
+    }) => Promise<boolean>;
+    fetchRemoteProjectRow?: (input: {
+        workerBaseUrl: string;
+        projectId: string;
+    }) => Promise<{
+        httpStatus: number;
+        body: unknown;
+    }>;
+    fetchRemoteReportRow?: (input: {
+        workerBaseUrl: string;
+        reportId: string;
+    }) => Promise<{
+        httpStatus: number;
+        body: unknown;
+    }>;
+    uploadProject?: (input: {
+        workerBaseUrl: string;
+        envelope: HostedProjectIngestEnvelope;
+        serialized: string;
+        /** CLI `--force` → worker accepts duplicate content hash (replaces prior row). */
+        force?: boolean;
+    }) => Promise<{
+        httpStatus: number;
+        body: unknown;
+    }>;
+    uploadReport?: (input: {
+        workerBaseUrl: string;
+        document: unknown;
+        force?: boolean;
+    }) => Promise<{
+        httpStatus: number;
+        body: unknown;
+    }>;
+    deleteRemoteProject?: (input: {
+        workerBaseUrl: string;
+        projectId: string;
+    }) => Promise<{
+        httpStatus: number;
+        body: unknown;
+    }>;
+    deleteRemoteReport?: (input: {
+        workerBaseUrl: string;
+        reportId: string;
+    }) => Promise<{
+        httpStatus: number;
+        body: unknown;
+    }>;
+    /** When set, reuse in-memory `share.json` across back-to-back uploads in one CLI invocation. */
+    shareJsonSession?: ShareRunShareJsonSession;
+    /** Host SDK / machine context attached to JSON ingest envelopes. */
+    processorContext?: HostedIngestProcessorContext;
+};
+type ShareSkippedReason = 'dry_run' | 'hash_unchanged' | 'cache_epoch_unchanged' | 'user_cancelled_confirm' | 'worker_ref_link_only';
+type ShareRunResult = {
+    action: 'uploaded' | 'skipped' | 'link-only';
+    kind: 'project' | 'report';
+    manifest?: ShareManifest;
+    links: ShareLinks;
+    workerIds: {
+        projectId?: string;
+        reportId?: string;
+    };
+    cacheEntry?: ShareCacheEntry;
+    issues: Issue[];
+    skippedReason?: ShareSkippedReason;
+    /** Worker `expiresAt` from upload response (ISO). */
+    workerExpiresAt?: string;
+    /** Worker returned `HASH_ALREADY_EXISTS` (reused existing row). */
+    workerDeduped?: boolean;
+    /** Rows removed from `share.json` after worker 404 during skip probe (re-upload follows). */
+    purgedStaleCacheRows?: Array<{
+        kind: 'project' | 'report';
+        workerId: string;
+    }>;
+};
+type ShareListInput = {
+    ctx: CoreContext;
+};
+type ShareListResult = {
+    entries: ShareCacheEntry[];
+    issues: Issue[];
+    heal: ShareJsonHealReport;
+};
+type ShareViewInput = {
+    ctx: CoreContext;
+    kind: 'project' | 'report';
+    workerBaseUrl: string;
+    workerId: string;
+    hooks: Pick<ShareHostHooks, 'fetchRemoteProjectRow' | 'fetchRemoteReportRow'>;
+    /** When true (default), drop matching `share.json` rows after worker not-found (not on network errors). */
+    purgeStaleLocalOnNotFound?: boolean;
+};
+type ShareViewResult = {
+    kind: 'project' | 'report';
+    workerId: string;
+    remote?: unknown;
+    /** Parsed worker GET metadata when the response matches the stored-metadata shape. */
+    remoteMetadata?: ProjectStoredMetadata | StoredReportMetadata;
+    local?: ShareCacheEntry;
+    links: ShareLinks;
+    issues: Issue[];
+    /** True when a matching `share.json` row was removed after worker not-found. */
+    purgedLocalCache?: boolean;
+};
+type ShareDeleteInput = {
+    ctx: CoreContext;
+    kind: 'project' | 'report';
+    workerBaseUrl: string;
+    workerId: string;
+    /** When false, skip worker DELETE (local `share.json` only). Default true when host supplies delete hooks. */
+    remote?: boolean;
+    hooks?: Pick<ShareHostHooks, 'deleteRemoteProject' | 'deleteRemoteReport'>;
+};
+type ShareDeleteResult = {
+    deletedLocal: boolean;
+    deletedRemote: boolean;
+    /** Worker returned 404 / not-found — DELETE treated as done. */
+    remoteAlreadyAbsent?: boolean;
+    issues: Issue[];
+};
+
+type VerboseRow = {
+    key: string;
+    value: string;
+};
+type VerboseSection = {
+    title: string;
+    rows: VerboseRow[];
+};
+
+export { type AnalysisCacheInvalidationAction, type AnalysisCacheInvalidationDecision, type AnalysisCacheInvalidationReason, type BuildHostedProjectShareArtifactsResult, type BuildPreparedProjectPayloadInput, type BuildPreparedProjectPayloadResult, type BuildProjectPayloadResult, type CacheConfigSource, CacheDispatchInfo, CacheDispatchStatus, CacheProfileId, CacheProjectFileRecord, CacheRebuildConfig, CacheRebuildMode, CachedLocalesLayout, ConstSubstitutionStep, CoreContext, CoreEngineRuntime, type DeleteJsonPayload, type DeleteRunResult, type DeleteTargetResult, type DoctorCheckId, type DoctorFinding, type DoctorHostHooks, type DoctorJsonPayload, type DoctorRunOptions, type DoctorRunResult, type DynamicHostHooks, type DynamicJsonPayload, DynamicKeySite, type DynamicRunOptions, type DynamicRunResult, type HostedProjectShareArtifacts, type HostedReportShareArtifacts, type ImportBinding, type ImportBindingSource, Issue, KeyObservation, type ListJsonPayload, type ListRunResult, ListSourceFilesOptions, LocaleListRow, type LocaleWriteInvalidationInput, OperationId, PatchingAction, PatchingCommandName, PatchingConfigInput, PatchingLocaleRecord, type PatchingRunInput, PatchingRuntimePorts, type PrepareShareHostedInput, type PrepareShareHostedResult, type ProjectAnalysis, type ProjectAnalysisCacheData, type ProjectAnalysisCounts, type ProjectAnalysisResolveOptions, ProjectLiteralKeyUsage, ProviderAttemptOutcome, type ProviderAttemptReport, type ResolveKeyPlaceholdersTraceResult, type ResolveProviderActionInput, type ResolvedCacheConfig, ResolvedLocalesLayout, type ReviewHostHooks, type ReviewJsonData, type ReviewLocaleStats, type ReviewRunOptions, type ReviewRunResult, RunEmitter, RuntimePathPort, type SaveShareJsonResult, ScanExcludeConfig, type ScanKeyObservationsOptions, type ScanProjectDynamicKeySitesInput, type ScanProjectFileInput, type ScanProjectFilesystemInputBase, type ScanProjectKeyObservationsInput, type ScanProjectLiteralKeyUsageInput, type ScanProjectSourceFilesInput, type ShareCacheDebugLine, ShareCacheEntry, type ShareDeleteAllJsonPayload, type ShareDeleteInput, type ShareDeleteJsonPayload, type ShareDeleteOptions, type ShareDeleteResult, type ShareDeleteRowResult, type ShareHostHooks, type ShareHumanMessageHost, type ShareJsonBackupResult, ShareJsonFile, ShareJsonHealReport, ShareKind, ShareLinks, type ShareListInput, type ShareListJsonPayload, type ShareListOptions, type ShareListResult, ShareManifest, ShareProjectManifest, ShareReportManifest, type ShareRunInput, type ShareRunInputProjectBuild, type ShareRunInputProjectWorkerRef, type ShareRunInputReportDocument, type ShareRunInputReportWorkerRef, type ShareRunResult, type ShareRunShareJsonSession, type ShareSkippedReason, type ShareUploadJsonPayload, type ShareUploadOptions, type ShareViewInput, type ShareViewJsonPayload, type ShareViewOptions, type ShareViewResult, type ShareViewVerboseDetail, type ShareViewVerboseSection, type ShareViewVerboseSectionValue, type ShareWorkerProjectRef, type ShareWorkerReportRef, type ShareZipBuildIssue, type TrackedProjectFilesCurrent, TranslateFailureOutcome, type TranslateHooks, type TranslateIdentityGuardOptions, type TranslateLeafInput, type TranslateOptions, type TranslateOutput, TranslatePolicy, type TranslatePolicyAction, TranslatePolicyVerb, type TranslateResultItem, TranslateRunPartialStats, type TranslationCallSite, TranslationLeafMeta, TranslationProviderId, type VerboseRow, type VerboseSection };