@zigrivers/surface-core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1753 @@
+import { aO as Lens, A as AppType, bY as Target, v as CaptureOptions, bt as Result, C as Capture, bR as SurfaceError, d as ArtifactWriter, q as CaptureBackend, bL as SurfaceConfig, bI as StateStore, bg as ProjectStateSnapshot, p as CaptureArtifactType, aU as ModelAvailability, aq as FrameworkAdapter, av as GateEvaluator, aB as GroundingTool, aI as IssueExporter, aN as KnowledgeSource, bp as ReportRenderer, G as ComponentMap, bC as SourceFileRef, ab as FindingDraft, bk as RedactionRule, c7 as TrackedFindingsDiff, al as FindingsEnvelope, aa as Finding, B as Backlog, ba as PersistedArtifactRef, bn as Report, aM as KnowledgeEntry, bm as RelevanceQuery, c0 as Theme } from './interfaces-OHgLgNLO.js';
+export { a as AppTypeSchema, b as ApplyWaiversInput, c as AriaAttributeSuggestedPatchSchema, e as BacklogEntry, f as BacklogEntrySchema, g as BacklogSchema, h as Baseline, i as BrokenFindingIdentityAssignment, j as BrokenFindingIdentityAssignmentSchema, k as BrokenIdentityDriftResultSchema, r as CaptureConfig, s as CaptureConfigLayerSchema, t as CaptureConfigSchema, y as CitedHeuristicEvidence, z as CitedHeuristicEvidenceSchema, D as CliErrorEnvelope, E as CliExitCode, F as CliExitCodeSchema, I as ConfidenceBand, J as ConfidenceBandSchema, K as ConfidenceCutoffs, L as ConfidenceCutoffsLayerSchema, M as ConfidenceCutoffsSchema, N as ContrastHexSuggestedPatchSchema, O as CreateBaselineInput, P as CreateSurfaceErrorOptions, Q as CreateTrackedFindingInput, R as DEFAULT_FINDINGS_POLICY, S as DEFAULT_SURFACE_CONFIG, U as Depth, V as DepthSchema, W as DiffableTrackedFinding, X as Dimensions, Y as DimensionsSchema, Z as DomEvidence, _ as DomEvidenceSchema, $ as EdgeErrorContext, a0 as EvaluationConfig, a1 as EvaluationConfigLayerSchema, a2 as EvaluationConfigSchema, a3 as EvaluationMethod, a4 as EvaluationMethodSchema, a5 as Evidence, a6 as EvidenceSchema, a7 as ExportTarget, a8 as ExportTargetSchema, ac as FindingDraftSchema, ad as FindingIdentity, ae as FindingIdentityAssignment, af as FindingIdentityAssignmentSchema, ag as FindingIdentityCandidate, ah as FindingIdentityCandidateSchema, ai as FindingIdentitySchema, aj as FindingSchema, ak as FindingStatus, am as FindingsEnvelopeSchema, an as FindingsPolicy, ao as FindingsPolicyLayerSchema, ap as FindingsPolicySchema, at as GateDisposition, aw as GatePolicy, ay as GatePolicyLayerSchema, az as GatePolicySchema, aC as IdentityAnchorKind, aD as IdentityAnchorKindSchema, aE as IdentityDriftResult, aF as IdentityDriftResultSchema, aJ as JUDGED_COVERAGE_UNAVAILABLE_MESSAGE, aR as Location, aS as LocationSchema, aT as McpStructuredError, aV as ModelAvailabilitySchema, aW as ModelCompletionAdapter, aX as ModelLensSkip, aY as ModelLensSkipSchema, aZ as ModelPrompt, a_ as ModelPromptSchema, a$ as ModelProvider, b0 as ModelProviderConfig, b1 as ModelProviderConfigInput, b2 as ModelProviderConfigSchema, b3 as ModelProviderId, b4 as ModelProviderResolution, b5 as ModelRequest, b6 as ModelRequestSchema, b7 as ModelResponse, b8 as ModelResponseSchema, bb as Preset, bc as PresetSchema, bi as Rect, bj as RectSchema, bl as RedactionRuleSchema, bq as ReportingConfig, br as ReportingConfigLayerSchema, bs as ReportingConfigSchema, bu as SURFACE_ERROR_DEFINITIONS, bv as ScreenshotRegionEvidence, bw as ScreenshotRegionEvidenceSchema, bx as SeverityBand, by as SeverityBandSchema, bz as SeverityCutoffs, bA as SeverityCutoffsLayerSchema, bB as SeverityCutoffsSchema, bD as StableFindingIdentityAssignment, bE as StableFindingIdentityAssignmentSchema, bF as StableIdentityDriftResultSchema, bG as Stack, bH as StackSchema, bJ as SuggestedPatch, bK as SuggestedPatchSchema, bM as SurfaceConfigLayer, bN as SurfaceConfigLayerSchema, bO as SurfaceConfigLayers, bP as SurfaceConfigLayersSchema, bQ as SurfaceConfigSchema, bS as SurfaceErrorCode, bT as SurfaceErrorCodeSchema, bU as SurfaceErrorDefinition, bV as SurfaceErrorKind, bW as SurfaceErrorKindSchema, bX as SurfaceErrorSchema, b_ as TargetSizeSuggestedPatchSchema, c2 as ToolResultEvidence, c3 as ToolResultEvidenceSchema, c4 as TrackedFinding, c5 as TrackedFindingHistoryEntry, c6 as TrackedFindingTransition, c8 as TrackedFindingsDiffEntry, c9 as ValidationCheck, ca as Viewport, cd as ViewportSchema, ce as Waiver, cf as applyWaiversToTrackedFindings, cg as assignFindingIdentities, ch as createBaseline, ci as createConfiguredModelProvider, cj as createSurfaceError, ck as createTrackedFinding, cl as createUnavailableModelProvider, cm as deriveFindingIdentity, cn as deriveFindingIdentityCandidate, co as diffTrackedFindings, cp as err, cq as exitCodeForSurfaceError, cr as identityInternalsForTesting, cs as isErr, ct as isOk, cu as isWaiverActive, cv as matchFindingIdentity, cw as modelSkipForLens, cx as ok, cy as resolveModelProviderConfig, cz as resolveSurfaceConfig, cA as scoreFinding, cB as synthesizeBacklog, cC as toCliErrorEnvelope, cD as toMcpError, cE as transitionTrackedFinding } from './interfaces-OHgLgNLO.js';
+import { z } from 'zod';
+import { DestinationStream, Logger } from 'pino';
+import { LockOptions } from 'proper-lockfile';
+
+/**
+ * Creates the built-in measured accessibility lens from normalized grounding evidence.
+ */
+declare function createAccessibilityLens(): Lens;
+
+declare const OverlayReleaseTierSchema: z.ZodEnum<{
+    gate: "gate";
+    committed: "committed";
+    should: "should";
+}>;
+type OverlayReleaseTier = z.infer<typeof OverlayReleaseTierSchema>;
+declare const OverlayAcceptanceCriteriaSchema: z.ZodObject<{
+    summary: z.ZodString;
+    checks: z.ZodArray<z.ZodString>;
+    riskSignals: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+type OverlayAcceptanceCriteria = z.infer<typeof OverlayAcceptanceCriteriaSchema>;
+declare const AppTypeOverlaySchema: z.ZodObject<{
+    appType: z.ZodEnum<{
+        generic: "generic";
+        "saas-dashboard": "saas-dashboard";
+        "e-commerce": "e-commerce";
+        marketing: "marketing";
+        admin: "admin";
+        "content-media": "content-media";
+    }>;
+    defaultPersona: z.ZodString;
+    defaultTask: z.ZodString;
+    discoverySignals: z.ZodArray<z.ZodString>;
+    label: z.ZodString;
+    releaseTier: z.ZodEnum<{
+        gate: "gate";
+        committed: "committed";
+        should: "should";
+    }>;
+    routeHints: z.ZodArray<z.ZodString>;
+    lensCriteria: z.ZodRecord<z.ZodString, z.ZodObject<{
+        summary: z.ZodString;
+        checks: z.ZodArray<z.ZodString>;
+        riskSignals: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+type AppTypeOverlay = z.infer<typeof AppTypeOverlaySchema>;
+declare const REGISTERED_APP_TYPE_OVERLAYS: readonly ["generic", "saas-dashboard", "e-commerce", "marketing"];
+type RegisteredAppTypeOverlay = (typeof REGISTERED_APP_TYPE_OVERLAYS)[number];
+declare const COMMITTED_WEB_APP_TYPE_OVERLAYS: readonly ["saas-dashboard", "e-commerce", "marketing"];
+declare const APP_TYPE_OVERLAY_YAML_HEADER = "# Generated from packages/core/src/app-type-overlays.ts. Do not edit by hand.";
+declare const APP_TYPE_OVERLAY_REGISTRY: Readonly<Record<"generic" | "saas-dashboard" | "e-commerce" | "marketing", {
+    appType: "generic" | "saas-dashboard" | "e-commerce" | "marketing" | "admin" | "content-media";
+    defaultPersona: string;
+    defaultTask: string;
+    discoverySignals: string[];
+    label: string;
+    releaseTier: "gate" | "committed" | "should";
+    routeHints: string[];
+    lensCriteria: Record<string, {
+        summary: string;
+        checks: string[];
+        riskSignals: string[];
+    }>;
+}>>;
+declare function hasRegisteredAppTypeOverlay(appType: AppType): appType is RegisteredAppTypeOverlay;
+declare function getAppTypeOverlay(appType?: AppType): Readonly<AppTypeOverlay>;
+declare function listAppTypeOverlays(): readonly Readonly<AppTypeOverlay>[];
+declare function serializeAppTypeOverlayToYaml(overlay: AppTypeOverlay): string;
+
+type CaptureIdFactory = (target: Target) => string;
+type CaptureClock = () => string;
+type CaptureRandomHex = () => string;
+interface CaptureService {
+    capture(target: Target, options: CaptureOptions): Promise<Result<Capture, SurfaceError>>;
+}
+interface CaptureServiceOptions {
+    readonly artifactWriter?: ArtifactWriter;
+    readonly backends: readonly CaptureBackend[];
+    readonly staticFallback: CaptureBackend;
+}
+interface PlaywrightCaptureBackendOptions {
+    readonly available?: boolean;
+    readonly clock?: CaptureClock;
+    readonly idFactory?: CaptureIdFactory;
+    readonly loadPlaywright?: () => Promise<unknown>;
+}
+interface AgentBrowserCommandResult {
+    readonly exitCode: number;
+    readonly stderr: string;
+    readonly stdout: string;
+}
+type AgentBrowserCommandRunner = (args: readonly string[]) => Promise<AgentBrowserCommandResult>;
+interface AgentBrowserCaptureBackendOptions {
+    readonly available?: boolean;
+    readonly clock?: CaptureClock;
+    readonly command?: string;
+    readonly idFactory?: CaptureIdFactory;
+    readonly runCommand?: AgentBrowserCommandRunner;
+    readonly sessionName?: string;
+}
+interface StaticCaptureBackendOptions {
+    /**
+     * Optional trusted source roots for static target refs. When omitted,
+     * target refs are treated as trusted local file inputs and may point to
+     * any readable image file on disk.
+     */
+    readonly allowedSourceRoots?: readonly string[];
+    readonly clock?: CaptureClock;
+    readonly idFactory?: CaptureIdFactory;
+}
+declare function createCaptureService(options: CaptureServiceOptions): CaptureService;
+declare function createPlaywrightCaptureBackend(options?: PlaywrightCaptureBackendOptions): CaptureBackend;
+declare function createAgentBrowserCaptureBackend(options?: AgentBrowserCaptureBackendOptions): CaptureBackend;
+/**
+ * Creates the degraded static fallback backend. Static target refs are trusted
+ * local file inputs unless allowedSourceRoots is configured. Do not pass
+ * attacker-controlled refs without constraining source roots.
+ */
+declare function createStaticCaptureBackend(options?: StaticCaptureBackendOptions): CaptureBackend;
+declare function selectCaptureBackend(backends: readonly CaptureBackend[]): CaptureBackend | undefined;
+declare function createDefaultCaptureIdFactory(options?: {
+    readonly clock?: CaptureClock;
+    readonly randomHex?: CaptureRandomHex;
+}): CaptureIdFactory;
+
+type MaybePromise<T> = T | Promise<T>;
+declare const ExecutablePipelineStageIdSchema: z.ZodEnum<{
+    capture: "capture";
+    validation: "validation";
+    accessibility: "accessibility";
+    conversion: "conversion";
+    persona: "persona";
+    routes: "routes";
+    content: "content";
+    responsiveness: "responsiveness";
+    discovery: "discovery";
+    heuristic: "heuristic";
+    visual: "visual";
+    "cognitive-walkthrough": "cognitive-walkthrough";
+    innovation: "innovation";
+    synthesis: "synthesis";
+}>;
+type ExecutablePipelineStageId = z.infer<typeof ExecutablePipelineStageIdSchema>;
+declare const PipelineStageIdSchema: z.ZodEnum<{
+    capture: "capture";
+    validation: "validation";
+    completed: "completed";
+    accessibility: "accessibility";
+    conversion: "conversion";
+    persona: "persona";
+    routes: "routes";
+    content: "content";
+    responsiveness: "responsiveness";
+    discovery: "discovery";
+    heuristic: "heuristic";
+    visual: "visual";
+    "cognitive-walkthrough": "cognitive-walkthrough";
+    innovation: "innovation";
+    synthesis: "synthesis";
+    "pending-completion": "pending-completion";
+}>;
+type PipelineStageId = z.infer<typeof PipelineStageIdSchema>;
+declare const PipelineEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"StageAdvanced">;
+    runId: z.ZodString;
+    stage: z.ZodUnion<readonly [z.ZodEnum<{
+        capture: "capture";
+        validation: "validation";
+        accessibility: "accessibility";
+        conversion: "conversion";
+        persona: "persona";
+        routes: "routes";
+        content: "content";
+        responsiveness: "responsiveness";
+        discovery: "discovery";
+        heuristic: "heuristic";
+        visual: "visual";
+        "cognitive-walkthrough": "cognitive-walkthrough";
+        innovation: "innovation";
+        synthesis: "synthesis";
+    }>, z.ZodLiteral<"finalization">]>;
+    sequence: z.ZodNumber;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"StageSkipped">;
+    runId: z.ZodString;
+    stage: z.ZodUnion<readonly [z.ZodEnum<{
+        capture: "capture";
+        validation: "validation";
+        accessibility: "accessibility";
+        conversion: "conversion";
+        persona: "persona";
+        routes: "routes";
+        content: "content";
+        responsiveness: "responsiveness";
+        discovery: "discovery";
+        heuristic: "heuristic";
+        visual: "visual";
+        "cognitive-walkthrough": "cognitive-walkthrough";
+        innovation: "innovation";
+        synthesis: "synthesis";
+    }>, z.ZodLiteral<"finalization">]>;
+    reason: z.ZodString;
+    sequence: z.ZodNumber;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"AuditRunFailed">;
+    runId: z.ZodString;
+    stage: z.ZodUnion<readonly [z.ZodEnum<{
+        capture: "capture";
+        validation: "validation";
+        accessibility: "accessibility";
+        conversion: "conversion";
+        persona: "persona";
+        routes: "routes";
+        content: "content";
+        responsiveness: "responsiveness";
+        discovery: "discovery";
+        heuristic: "heuristic";
+        visual: "visual";
+        "cognitive-walkthrough": "cognitive-walkthrough";
+        innovation: "innovation";
+        synthesis: "synthesis";
+    }>, z.ZodLiteral<"finalization">]>;
+    message: z.ZodString;
+    sequence: z.ZodNumber;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"AuditRunCompleted">;
+    runId: z.ZodString;
+    sequence: z.ZodNumber;
+}, z.core.$strict>], "type">;
+type PipelineEvent = z.infer<typeof PipelineEventSchema>;
+type PipelineStageDefinition = {
+    readonly id: ExecutablePipelineStageId;
+    readonly fr: `FR-PIPE-${number}`;
+    readonly minDepth: SurfaceConfig["evaluation"]["depth"];
+    readonly presets?: readonly SurfaceConfig["evaluation"]["preset"][];
+};
+type PipelineStageContext = {
+    readonly runId: string;
+    readonly stage: PipelineStageDefinition;
+    readonly config: SurfaceConfig;
+    readonly state: ProjectStateSnapshot;
+};
+type PipelineStageHandler = (context: PipelineStageContext) => MaybePromise<Result<unknown, SurfaceError>>;
+type PipelineOrchestratorOptions = {
+    readonly stateStore: StateStore;
+    readonly handlers: Partial<Record<ExecutablePipelineStageId, PipelineStageHandler>>;
+};
+type PipelineRunInput = {
+    readonly runId: string;
+    readonly config?: SurfaceConfig;
+};
+type PipelineRunResult = {
+    readonly runId: string;
+    readonly newlyCompletedStages: readonly ExecutablePipelineStageId[];
+    readonly skippedStages: readonly {
+        readonly stage: ExecutablePipelineStageId;
+        readonly reason: string;
+    }[];
+    readonly events: readonly PipelineEvent[];
+};
+interface PipelineOrchestrator {
+    /**
+     * Resume behavior is driven by matching pipeline metadata for the same run and
+     * stage plan. Legacy states without metadata, or states from a different plan,
+     * restart the active plan from the beginning. Project state stores one active
+     * pipeline run at a time; starting a different runId overwrites prior pipeline
+     * metadata rather than preserving concurrent run progress. Callers must
+     * serialize run() calls per runId; this orchestrator does not provide locking
+     * or compare-and-swap protection around StateStore read/write cycles.
+     * Pre-stage write failures happen before metadata can reserve a sequence, so
+     * those retries intentionally restart event numbering from the last durable
+     * metadata snapshot.
+     */
+    run(input: PipelineRunInput): Promise<Result<PipelineRunResult, SurfaceError>>;
+}
+declare const DEFAULT_PIPELINE_STAGE_DEFINITIONS: readonly [{
+    readonly id: "discovery";
+    readonly fr: "FR-PIPE-1";
+    readonly minDepth: 1;
+}, {
+    readonly id: "persona";
+    readonly fr: "FR-PIPE-2";
+    readonly minDepth: 1;
+}, {
+    readonly id: "routes";
+    readonly fr: "FR-PIPE-3";
+    readonly minDepth: 1;
+}, {
+    readonly id: "capture";
+    readonly fr: "FR-PIPE-4";
+    readonly minDepth: 1;
+}, {
+    readonly id: "heuristic";
+    readonly fr: "FR-PIPE-5";
+    readonly minDepth: 1;
+}, {
+    readonly id: "accessibility";
+    readonly fr: "FR-PIPE-6";
+    readonly minDepth: 1;
+}, {
+    readonly id: "visual";
+    readonly fr: "FR-PIPE-7";
+    readonly minDepth: 1;
+}, {
+    readonly id: "content";
+    readonly fr: "FR-PIPE-8";
+    readonly minDepth: 1;
+}, {
+    readonly id: "responsiveness";
+    readonly fr: "FR-PIPE-9";
+    readonly minDepth: 1;
+}, {
+    readonly id: "cognitive-walkthrough";
+    readonly fr: "FR-PIPE-10";
+    readonly minDepth: 4;
+}, {
+    readonly id: "conversion";
+    readonly fr: "FR-PIPE-11";
+    readonly minDepth: 4;
+    readonly presets: readonly ["agent-ready", "conversion-focused", "deep"];
+}, {
+    readonly id: "innovation";
+    readonly fr: "FR-PIPE-12";
+    readonly minDepth: 5;
+    readonly presets: readonly ["deep"];
+}, {
+    readonly id: "synthesis";
+    readonly fr: "FR-PIPE-13";
+    readonly minDepth: 1;
+}, {
+    readonly id: "validation";
+    readonly fr: "FR-PIPE-14";
+    readonly minDepth: 1;
+}];
+/** Select the executable pipeline stages for the configured depth and preset. */
+declare function selectPipelineStages(config?: SurfaceConfig): readonly PipelineStageDefinition[];
+/** Create explicit no-op handlers for tests and metadata-only prototype wiring. */
+declare function createNoopPipelineHandlers(overrides?: Partial<Record<ExecutablePipelineStageId, PipelineStageHandler>>): Record<ExecutablePipelineStageId, PipelineStageHandler>;
+/** Create a stateless orchestrator with metadata-backed resume semantics. */
+declare function createPipelineOrchestrator(options: PipelineOrchestratorOptions): PipelineOrchestrator;
+
+type LensFactoryOptions = {
+    readonly maxDomChars?: number;
+    readonly projectRoot?: string;
+};
+type LensRegistration = {
+    readonly id: string;
+    readonly method: "measured" | "judged";
+    readonly requiresModel: boolean;
+    readonly requiresLiveDom: boolean;
+    readonly requiredArtifacts?: readonly CaptureArtifactType[];
+    readonly presets: readonly SurfaceConfig["evaluation"]["preset"][];
+    readonly create?: (options?: LensFactoryOptions) => Lens;
+};
+type LensSkipReason = "model_unavailable" | "live_dom_unavailable";
+type LensExecutionSkip = {
+    readonly lensId: string;
+    readonly reason: LensSkipReason;
+    readonly message: string;
+};
+type LensExecutionPlan = {
+    readonly overlay: Readonly<AppTypeOverlay>;
+    readonly preset: SurfaceConfig["evaluation"]["preset"];
+    readonly selected: readonly LensRegistration[];
+    readonly skipped: readonly LensExecutionSkip[];
+};
+type InstantiatedLens = {
+    readonly lens: Lens;
+    readonly registration: LensRegistration;
+};
+type SelectLensExecutionPlanInput = {
+    readonly config: SurfaceConfig;
+    readonly capture?: Capture;
+    readonly modelAvailability?: ModelAvailability;
+    readonly registry?: readonly LensRegistration[];
+};
+type SynthesisDecision = {
+    readonly factKey: string;
+    readonly sourceOfTruth: "measured" | "judged";
+    readonly reason: string;
+    readonly measuredSource: string;
+    readonly measuredValue: string;
+    readonly judgedSource: string;
+    readonly judgedValue: string;
+};
+type SynthesizeMeasuredWinsInput = {
+    readonly factKey: string;
+    readonly measuredSource: string;
+    readonly measuredValue: string;
+    readonly judgedSource: string;
+    readonly judgedValue: string;
+};
+declare const BUILT_IN_LENS_REGISTRY: readonly [{
+    readonly id: "accessibility";
+    readonly method: "measured";
+    readonly requiresModel: false;
+    readonly requiresLiveDom: true;
+    readonly presets: readonly ["quick", "mvp", "standard", "deep", "accessibility-first", "agent-ready"];
+    readonly create: () => Lens;
+}, {
+    readonly id: "usability";
+    readonly method: "judged";
+    readonly requiresModel: true;
+    readonly requiredArtifacts: readonly ["dom-snapshot"];
+    readonly requiresLiveDom: true;
+    readonly presets: readonly ["quick", "mvp", "standard", "deep", "agent-ready"];
+    readonly create: (options: LensFactoryOptions | undefined) => Lens;
+}, {
+    readonly id: "visual-hierarchy";
+    readonly method: "judged";
+    readonly requiredArtifacts: readonly ["dom-snapshot", "computed-styles"];
+    readonly requiresModel: false;
+    readonly requiresLiveDom: true;
+    readonly presets: readonly ["mvp", "standard", "deep", "accessibility-first", "design-system-focused"];
+    readonly create: (options: LensFactoryOptions | undefined) => Lens;
+}, {
+    readonly id: "content";
+    readonly method: "judged";
+    readonly requiresModel: false;
+    readonly requiresLiveDom: true;
+    readonly presets: readonly ["standard", "deep"];
+    readonly create: (options: LensFactoryOptions | undefined) => Lens;
+}, {
+    readonly id: "responsiveness";
+    readonly method: "measured";
+    readonly requiresModel: false;
+    readonly requiresLiveDom: true;
+    readonly presets: readonly ["mvp", "standard", "deep", "accessibility-first", "conversion-focused"];
+    readonly create: (options: LensFactoryOptions | undefined) => Lens;
+}, {
+    readonly id: "conversion";
+    readonly method: "judged";
+    readonly requiredArtifacts: readonly ["dom-snapshot"];
+    readonly requiresModel: true;
+    readonly requiresLiveDom: true;
+    readonly presets: readonly ["conversion-focused", "deep", "agent-ready"];
+    readonly create: (options: LensFactoryOptions | undefined) => Lens;
+}, {
+    readonly id: "message-clarity";
+    readonly method: "judged";
+    readonly requiresModel: true;
+    readonly requiresLiveDom: false;
+    readonly presets: readonly ["standard", "deep", "conversion-focused"];
+}, {
+    readonly id: "task-completion";
+    readonly method: "judged";
+    readonly requiredArtifacts: readonly ["dom-snapshot"];
+    readonly requiresModel: true;
+    readonly requiresLiveDom: true;
+    readonly presets: readonly ["standard", "deep", "agent-ready"];
+    readonly create: (options: LensFactoryOptions | undefined) => Lens;
+}, {
+    readonly id: "agent-implementation";
+    readonly method: "judged";
+    readonly requiresModel: true;
+    readonly requiresLiveDom: false;
+    readonly presets: readonly ["deep", "agent-ready"];
+}, {
+    readonly id: "data-density";
+    readonly method: "judged";
+    readonly requiresModel: true;
+    readonly requiresLiveDom: false;
+    readonly presets: readonly ["standard", "deep"];
+}, {
+    readonly id: "trust-and-control";
+    readonly method: "judged";
+    readonly requiresModel: true;
+    readonly requiresLiveDom: false;
+    readonly presets: readonly ["standard", "deep", "agent-ready"];
+}, {
+    readonly id: "trust-and-credibility";
+    readonly method: "judged";
+    readonly requiresModel: true;
+    readonly requiresLiveDom: false;
+    readonly presets: readonly ["standard", "deep", "conversion-focused"];
+}];
+declare function selectLensExecutionPlan(input: SelectLensExecutionPlanInput): LensExecutionPlan;
+declare function instantiateLensExecutionPlan(plan: LensExecutionPlan, options?: LensFactoryOptions): readonly InstantiatedLens[];
+declare function synthesizeMeasuredWinsDecision(input: SynthesizeMeasuredWinsInput): SynthesisDecision;
+
+type SurfaceCompositionGeneratedAt = string | (() => string);
+type SurfaceCompositionOptions = {
+    readonly captureBackends?: readonly CaptureBackend[];
+    readonly frameworkAdapters?: readonly FrameworkAdapter[];
+    readonly generatedAt?: SurfaceCompositionGeneratedAt;
+    readonly gateEvaluator?: GateEvaluator;
+    readonly groundingTools?: readonly GroundingTool[];
+    readonly issueExporters?: readonly IssueExporter[];
+    readonly knowledgeRootDir?: string;
+    readonly knowledgeSource?: KnowledgeSource;
+    readonly lensFactoryOptions?: LensFactoryOptions;
+    readonly lensRegistry?: readonly LensRegistration[];
+    readonly pipelineHandlers?: Partial<Record<ExecutablePipelineStageId, PipelineStageHandler>>;
+    readonly projectRoot?: string;
+    readonly reportRenderers?: readonly ReportRenderer[];
+    readonly stateDir?: string;
+    readonly stateStore?: StateStore;
+    readonly staticFallback?: CaptureBackend;
+};
+type SurfaceComposition = {
+    readonly captureBackends: readonly CaptureBackend[];
+    readonly captureService: CaptureService;
+    readonly frameworkAdapters: readonly FrameworkAdapter[];
+    readonly gateEvaluator: GateEvaluator;
+    readonly groundingTools: readonly GroundingTool[];
+    readonly issueExporters: readonly IssueExporter[];
+    readonly knowledgeSource: KnowledgeSource;
+    readonly lensFactoryOptions: LensFactoryOptions;
+    readonly lensRegistry: readonly LensRegistration[];
+    readonly pipelineOrchestrator: PipelineOrchestrator;
+    readonly reportRenderers: readonly ReportRenderer[];
+    readonly stateStore: StateStore;
+};
+/**
+ * Build the shared core composition root consumed by interface adapters.
+ *
+ * CLI and MCP should both call this factory and then add package-local plugins
+ * through the option arrays. Core wires only core-owned implementations here so
+ * package dependencies stay one-way: plugins depend on core, never the reverse.
+ */
+declare function createSurfaceComposition(options?: SurfaceCompositionOptions): SurfaceComposition;
+declare const DEFAULT_COMPOSITION_STAGE_IDS: ("capture" | "validation" | "accessibility" | "conversion" | "persona" | "routes" | "content" | "responsiveness" | "discovery" | "heuristic" | "visual" | "cognitive-walkthrough" | "innovation" | "synthesis")[];
+
+declare const TextInputSchema: z.ZodObject<{
+    path: z.ZodOptional<z.ZodString>;
+    contents: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+type TextInput = z.infer<typeof TextInputSchema>;
+declare const DesignTokenSchema: z.ZodObject<{
+    name: z.ZodString;
+    value: z.ZodString;
+}, z.core.$strict>;
+type DesignToken = z.infer<typeof DesignTokenSchema>;
+declare const PersonaSchema: z.ZodObject<{
+    goals: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    id: z.ZodString;
+    priorKnowledge: z.ZodDefault<z.ZodEnum<{
+        "first-time": "first-time";
+        returning: "returning";
+        expert: "expert";
+    }>>;
+}, z.core.$strict>;
+type Persona = z.infer<typeof PersonaSchema>;
+declare const TaskDefinitionSchema: z.ZodObject<{
+    conversionCritical: z.ZodDefault<z.ZodBoolean>;
+    id: z.ZodString;
+    personaId: z.ZodOptional<z.ZodString>;
+    steps: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+type TaskDefinition = z.infer<typeof TaskDefinitionSchema>;
+declare const ContextIngestionInputSchema: z.ZodObject<{
+    component: z.ZodOptional<z.ZodString>;
+    designTokens: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        value: z.ZodString;
+    }, z.core.$strict>>>;
+    dom: z.ZodOptional<z.ZodObject<{
+        path: z.ZodOptional<z.ZodString>;
+        contents: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    personas: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        goals: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        id: z.ZodString;
+        priorKnowledge: z.ZodDefault<z.ZodEnum<{
+            "first-time": "first-time";
+            returning: "returning";
+            expert: "expert";
+        }>>;
+    }, z.core.$strict>>>;
+    scaffoldDocs: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        path: z.ZodOptional<z.ZodString>;
+        contents: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+    screenshot: z.ZodOptional<z.ZodObject<{
+        path: z.ZodOptional<z.ZodString>;
+        contents: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    source: z.ZodOptional<z.ZodObject<{
+        path: z.ZodOptional<z.ZodString>;
+        contents: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    sources: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        path: z.ZodOptional<z.ZodString>;
+        contents: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+    tasks: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        conversionCritical: z.ZodDefault<z.ZodBoolean>;
+        id: z.ZodString;
+        personaId: z.ZodOptional<z.ZodString>;
+        steps: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>>;
+    tokenDocuments: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        path: z.ZodOptional<z.ZodString>;
+        contents: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+type ContextIngestionInput = z.input<typeof ContextIngestionInputSchema>;
+type ContextInputKind = "component" | "source" | "dom" | "screenshot" | "design-tokens" | "scaffold-docs" | "persona" | "task";
+interface InputProvenance {
+    readonly kind: ContextInputKind;
+    readonly ref: string;
+    readonly present: true;
+    readonly recordedAt: string;
+    readonly sha256?: string;
+}
+interface IngestedContext {
+    readonly designTokens: readonly DesignToken[];
+    readonly dom?: SourceFileRef;
+    readonly personas: readonly Persona[];
+    readonly scaffoldDocs: readonly SourceFileRef[];
+    readonly screenshot?: SourceFileRef;
+    readonly sources: readonly SourceFileRef[];
+    readonly tasks: readonly TaskDefinition[];
+}
+interface ContextIngestion {
+    readonly componentMap: ComponentMap;
+    readonly context: IngestedContext;
+    readonly findings: readonly FindingDraft[];
+    readonly provenance: readonly InputProvenance[];
+    readonly target: Target;
+}
+type ContextIngestorClock = () => string;
+interface ContextIngestorOptions {
+    readonly adapters?: readonly FrameworkAdapter[];
+    readonly artifactWriter?: ArtifactWriter;
+    readonly clock?: ContextIngestorClock;
+    readonly projectRoot?: string;
+}
+interface ContextIngestor {
+    ingest(input: ContextIngestionInput): Promise<Result<ContextIngestion, SurfaceError>>;
+}
+/**
+ * Creates a static/context ingestion service that constructs a stable Target and provenance.
+ */
+declare function createContextIngestor(options?: ContextIngestorOptions): ContextIngestor;
+
+type ContentMicrocopyLensOptions = {
+    readonly maxReadingGrade?: number;
+    readonly minWords?: number;
+    readonly projectRoot?: string;
+};
+declare function createContentMicrocopyLens(options?: ContentMicrocopyLensOptions): Lens;
+
+type DiscoveryRunInput = {
+    readonly appTypeOverride?: AppType;
+    readonly config?: SurfaceConfig;
+    readonly personaHint?: string;
+    readonly routeCandidates?: readonly string[];
+    readonly routeCap?: number;
+    readonly runId: string;
+    readonly target: Target;
+    readonly taskHint?: string;
+};
+declare const RouteInventoryEntrySchema: z.ZodObject<{
+    path: z.ZodString;
+    source: z.ZodEnum<{
+        candidate: "candidate";
+        target: "target";
+    }>;
+}, z.core.$strict>;
+type RouteInventoryEntry = z.infer<typeof RouteInventoryEntrySchema>;
+declare const RouteSkippedSchema: z.ZodObject<{
+    path: z.ZodString;
+    reason: z.ZodLiteral<"route_cap_exceeded">;
+    source: z.ZodEnum<{
+        candidate: "candidate";
+        target: "target";
+    }>;
+}, z.core.$strict>;
+type RouteSkipped = z.infer<typeof RouteSkippedSchema>;
+declare const RouteInventorySchema: z.ZodObject<{
+    cap: z.ZodNumber;
+    routes: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        source: z.ZodEnum<{
+            candidate: "candidate";
+            target: "target";
+        }>;
+    }, z.core.$strict>>;
+    skipped: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        reason: z.ZodLiteral<"route_cap_exceeded">;
+        source: z.ZodEnum<{
+            candidate: "candidate";
+            target: "target";
+        }>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+type RouteInventory = z.infer<typeof RouteInventorySchema>;
+declare const PersonaTaskSchema: z.ZodObject<{
+    persona: z.ZodString;
+    task: z.ZodString;
+}, z.core.$strict>;
+type PersonaTask = z.infer<typeof PersonaTaskSchema>;
+declare const AppTypeClassificationSchema: z.ZodObject<{
+    appType: z.ZodEnum<{
+        generic: "generic";
+        "saas-dashboard": "saas-dashboard";
+        "e-commerce": "e-commerce";
+        marketing: "marketing";
+        admin: "admin";
+        "content-media": "content-media";
+    }>;
+    matchedSignals: z.ZodArray<z.ZodString>;
+    source: z.ZodEnum<{
+        config: "config";
+        "route-inventory": "route-inventory";
+        "target-ref": "target-ref";
+        "generic-fallback": "generic-fallback";
+    }>;
+}, z.core.$strict>;
+type AppTypeClassification = z.infer<typeof AppTypeClassificationSchema>;
+declare const DiscoveryEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"AppTypeClassified">;
+    appType: z.ZodEnum<{
+        generic: "generic";
+        "saas-dashboard": "saas-dashboard";
+        "e-commerce": "e-commerce";
+        marketing: "marketing";
+        admin: "admin";
+        "content-media": "content-media";
+    }>;
+    overlayId: z.ZodEnum<{
+        generic: "generic";
+        "saas-dashboard": "saas-dashboard";
+        "e-commerce": "e-commerce";
+        marketing: "marketing";
+        admin: "admin";
+        "content-media": "content-media";
+    }>;
+    runId: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"RoutesSkipped">;
+    cap: z.ZodNumber;
+    runId: z.ZodString;
+    skipped: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        reason: z.ZodLiteral<"route_cap_exceeded">;
+        source: z.ZodEnum<{
+            candidate: "candidate";
+            target: "target";
+        }>;
+    }, z.core.$strict>>;
+}, z.core.$strict>], "type">;
+type DiscoveryEvent = z.infer<typeof DiscoveryEventSchema>;
+declare const DiscoveryResultSchema: z.ZodObject<{
+    appType: z.ZodEnum<{
+        generic: "generic";
+        "saas-dashboard": "saas-dashboard";
+        "e-commerce": "e-commerce";
+        marketing: "marketing";
+        admin: "admin";
+        "content-media": "content-media";
+    }>;
+    classification: z.ZodObject<{
+        appType: z.ZodEnum<{
+            generic: "generic";
+            "saas-dashboard": "saas-dashboard";
+            "e-commerce": "e-commerce";
+            marketing: "marketing";
+            admin: "admin";
+            "content-media": "content-media";
+        }>;
+        matchedSignals: z.ZodArray<z.ZodString>;
+        source: z.ZodEnum<{
+            config: "config";
+            "route-inventory": "route-inventory";
+            "target-ref": "target-ref";
+            "generic-fallback": "generic-fallback";
+        }>;
+    }, z.core.$strict>;
+    events: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"AppTypeClassified">;
+        appType: z.ZodEnum<{
+            generic: "generic";
+            "saas-dashboard": "saas-dashboard";
+            "e-commerce": "e-commerce";
+            marketing: "marketing";
+            admin: "admin";
+            "content-media": "content-media";
+        }>;
+        overlayId: z.ZodEnum<{
+            generic: "generic";
+            "saas-dashboard": "saas-dashboard";
+            "e-commerce": "e-commerce";
+            marketing: "marketing";
+            admin: "admin";
+            "content-media": "content-media";
+        }>;
+        runId: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"RoutesSkipped">;
+        cap: z.ZodNumber;
+        runId: z.ZodString;
+        skipped: z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            reason: z.ZodLiteral<"route_cap_exceeded">;
+            source: z.ZodEnum<{
+                candidate: "candidate";
+                target: "target";
+            }>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>], "type">>;
+    overlayId: z.ZodEnum<{
+        generic: "generic";
+        "saas-dashboard": "saas-dashboard";
+        "e-commerce": "e-commerce";
+        marketing: "marketing";
+        admin: "admin";
+        "content-media": "content-media";
+    }>;
+    personaTask: z.ZodObject<{
+        persona: z.ZodString;
+        task: z.ZodString;
+    }, z.core.$strict>;
+    routeInventory: z.ZodObject<{
+        cap: z.ZodNumber;
+        routes: z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            source: z.ZodEnum<{
+                candidate: "candidate";
+                target: "target";
+            }>;
+        }, z.core.$strict>>;
+        skipped: z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            reason: z.ZodLiteral<"route_cap_exceeded">;
+            source: z.ZodEnum<{
+                candidate: "candidate";
+                target: "target";
+            }>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+    runId: z.ZodString;
+}, z.core.$loose>;
+type DiscoveryResult = z.infer<typeof DiscoveryResultSchema>;
+declare function runDiscovery(input: DiscoveryRunInput, options?: {
+    readonly stateStore?: StateStore;
+}): Promise<Result<DiscoveryResult, SurfaceError>>;
+
+declare const REDACTED_EXPORT_VALUE = "[Redacted]";
+declare function redactExportString(value: string, redactionRules: readonly RedactionRule[] | undefined): Result<string, SurfaceError>;
+declare function redactExportValue<T>(value: T, redactionRules: readonly RedactionRule[] | undefined): Result<T, SurfaceError>;
+
+type CognitivePersona = {
+    readonly goals: readonly string[];
+    readonly id: string;
+    readonly priorKnowledge: "first-time" | "returning" | "expert";
+};
+type CognitiveTaskDefinition = {
+    readonly conversionCritical: boolean;
+    readonly id: string;
+    readonly persona: CognitivePersona;
+    readonly steps: readonly string[];
+};
+type TaskCompletionLensOptions = LensFactoryOptions & {
+    readonly task?: CognitiveTaskDefinition;
+};
+type ConversionLensOptions = LensFactoryOptions & {
+    readonly conversionPath?: string;
+};
+declare function createTaskCompletionLens(options?: TaskCompletionLensOptions): Lens;
+declare function createConversionLens(options?: ConversionLensOptions): Lens;
+
+/** Create the default release gate evaluator for measured findings. */
+declare function createGateEvaluator(): GateEvaluator;
+
+type FindingsJsonRendererOptions = {
+    readonly generatedAt: string;
+    readonly degradation?: FindingsEnvelope["degradation"];
+    readonly redactionRules?: readonly RedactionRule[];
+};
+type ReportRendererRedactionOptions = {
+    readonly redactionRules?: readonly RedactionRule[];
+};
+declare const SurfaceSarifLogSchema: z.ZodObject<{
+    $schema: z.ZodString;
+    version: z.ZodLiteral<"2.1.0">;
+    runs: z.ZodArray<z.ZodObject<{
+        tool: z.ZodObject<{
+            driver: z.ZodObject<{
+                name: z.ZodLiteral<"surface">;
+                informationUri: z.ZodString;
+                rules: z.ZodArray<z.ZodObject<{
+                    id: z.ZodString;
+                    name: z.ZodString;
+                    shortDescription: z.ZodObject<{
+                        text: z.ZodString;
+                    }, z.core.$strict>;
+                }, z.core.$loose>>;
+            }, z.core.$loose>;
+        }, z.core.$loose>;
+        results: z.ZodArray<z.ZodObject<{
+            level: z.ZodEnum<{
+                error: "error";
+                warning: "warning";
+                note: "note";
+            }>;
+            message: z.ZodObject<{
+                text: z.ZodString;
+            }, z.core.$strict>;
+            ruleId: z.ZodString;
+        }, z.core.$loose>>;
+    }, z.core.$loose>>;
+}, z.core.$loose>;
+type SurfaceSarifLog = z.infer<typeof SurfaceSarifLogSchema>;
+type ReportArtifactSpec = {
+    readonly renderer: ReportRenderer;
+    readonly relativePath: string;
+};
+type WrittenReportArtifact = {
+    readonly artifact: PersistedArtifactRef;
+    readonly report: Report;
+    readonly relativePath: string;
+};
+type RenderAndWriteReportArtifactsOptions = {
+    readonly stateStore: StateStore;
+    readonly findings: readonly Finding[];
+    readonly backlog: Backlog;
+    readonly specs?: readonly ReportArtifactSpec[];
+};
+type ExplainRendererOptions = {
+    readonly findingId: string;
+    readonly knowledge?: KnowledgeSource;
+    readonly redactionRules?: readonly RedactionRule[];
+};
+type AlternativeProposal = {
+    readonly id: string;
+    readonly rationale: string;
+    readonly title: string;
+};
+type AlternativesReportData = {
+    readonly proposals: readonly AlternativeProposal[];
+    readonly target: Target;
+};
+type AlternativesRendererOptions = ReportRendererRedactionOptions & {
+    readonly proposals?: readonly AlternativeProposal[];
+    readonly target: Target;
+};
+type DiffRendererOptions = ReportRendererRedactionOptions & {
+    readonly afterRunId: string;
+    readonly beforeRunId: string;
+    readonly diff: TrackedFindingsDiff;
+};
+declare function createFindingsJsonRenderer(options: FindingsJsonRendererOptions): ReportRenderer;
+declare function createSarifRenderer(options?: ReportRendererRedactionOptions): ReportRenderer;
+declare function createFindingsMarkdownRenderer(options?: ReportRendererRedactionOptions): ReportRenderer;
+declare function createBacklogMarkdownRenderer(options?: ReportRendererRedactionOptions): ReportRenderer;
+declare function createAgentPlanMarkdownRenderer(options?: ReportRendererRedactionOptions): ReportRenderer;
+declare function createValidationReportMarkdownRenderer(options?: ReportRendererRedactionOptions): ReportRenderer;
+declare function createExplainMarkdownRenderer(options: ExplainRendererOptions): ReportRenderer;
+declare function createExplainJsonRenderer(options: ExplainRendererOptions): ReportRenderer;
+declare function createAlternativesJsonRenderer(options: AlternativesRendererOptions): ReportRenderer;
+declare function createDiffJsonRenderer(options: DiffRendererOptions): ReportRenderer;
+declare function createBoundedAlternatives(target: Target, proposals?: readonly AlternativeProposal[]): AlternativesReportData;
+declare function defaultPlanningReportArtifactSpecs(options?: ReportRendererRedactionOptions): readonly ReportArtifactSpec[];
+declare function renderAndWriteReportArtifacts(options: RenderAndWriteReportArtifactsOptions): Promise<Result<readonly WrittenReportArtifact[], SurfaceError>>;
+
+type GitHubCheckAnnotation = {
+    readonly path: string;
+    readonly start_line: number;
+    readonly end_line: number;
+    readonly annotation_level: "failure" | "notice" | "warning";
+    readonly message: string;
+    readonly title?: string;
+    readonly raw_details?: string;
+};
+type GitHubCheckCreateInput = {
+    readonly owner: string;
+    readonly repo: string;
+    readonly name: string;
+    readonly head_sha: string;
+    readonly status: "completed";
+    readonly conclusion: "failure" | "neutral" | "success";
+    readonly output: {
+        readonly title: string;
+        readonly summary: string;
+        readonly annotations?: GitHubCheckAnnotation[];
+    };
+};
+type GitHubChecksClient = {
+    readonly checks: {
+        create(input: GitHubCheckCreateInput): Promise<unknown>;
+    };
+};
+type GitHubChecksExporterOptions = {
+    readonly owner: string;
+    readonly repo: string;
+    readonly headSha: string;
+    readonly token?: string;
+    readonly checkName?: string;
+    readonly userAgent?: string;
+    readonly client?: GitHubChecksClient;
+    readonly maxAnnotations?: number;
+    readonly redactionRules?: readonly RedactionRule[];
+};
+type GitHubChecksExportInput = {
+    readonly backlog: Backlog;
+    readonly sarif: SurfaceSarifLog;
+    readonly localArtifactPath?: string;
+};
+type GitHubChecksExport = {
+    readonly id: string;
+    readonly target: "github-checks";
+    readonly status: "complete" | "failed";
+    readonly synced: readonly string[];
+    readonly unsynced: readonly string[];
+    readonly annotationCount: number;
+    readonly checkName: string;
+};
+declare function createGitHubChecksExporter(options: GitHubChecksExporterOptions): {
+    target: "github-checks";
+    export: (input: GitHubChecksExportInput) => Promise<Result<GitHubChecksExport, SurfaceError>>;
+};
+
+type GitHubIssueCreateInput = {
+    readonly owner: string;
+    readonly repo: string;
+    readonly title: string;
+    readonly body: string;
+    labels?: string[];
+};
+type GitHubIssueClient = {
+    readonly issues: {
+        create(input: GitHubIssueCreateInput): Promise<unknown>;
+    };
+};
+type GitHubIssueExporterOptions = {
+    readonly owner: string;
+    readonly repo: string;
+    readonly token?: string;
+    readonly userAgent?: string;
+    readonly projectRoot?: string;
+    readonly labels?: readonly string[];
+    readonly client?: GitHubIssueClient;
+    readonly maxAttempts?: number;
+    readonly initialBackoffMs?: number;
+    readonly wait?: (milliseconds: number) => Promise<void>;
+    readonly redactionRules?: readonly RedactionRule[];
+};
+declare function createGitHubIssueExporter(options: GitHubIssueExporterOptions): IssueExporter;
+
+declare const KnowledgeCategorySchema: z.ZodEnum<{
+    "e-commerce": "e-commerce";
+    admin: "admin";
+    "core-heuristics": "core-heuristics";
+    accessibility: "accessibility";
+    forms: "forms";
+    navigation: "navigation";
+    states: "states";
+    "visual-content": "visual-content";
+    "design-systems": "design-systems";
+    conversion: "conversion";
+    "platform-web": "platform-web";
+    "agent-implementation": "agent-implementation";
+    dashboards: "dashboards";
+    "data-viz": "data-viz";
+    "saas-onboarding": "saas-onboarding";
+    "search-discovery": "search-discovery";
+    "trust-safety": "trust-safety";
+    i18n: "i18n";
+}>;
+declare const FreshnessVolatilitySchema: z.ZodEnum<{
+    stable: "stable";
+    evolving: "evolving";
+    volatile: "volatile";
+}>;
+declare const CitationSchema: z.ZodObject<{
+    source: z.ZodString;
+    url: z.ZodOptional<z.ZodString>;
+    retrievedAt: z.ZodPreprocess<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+}, z.core.$strict>;
+declare const FreshnessSchema: z.ZodObject<{
+    volatility: z.ZodEnum<{
+        stable: "stable";
+        evolving: "evolving";
+        volatile: "volatile";
+    }>;
+    lastReviewed: z.ZodPreprocess<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+}, z.core.$strict>;
+type FileSystemKnowledgeSourceOptions = {
+    readonly rootDir: string;
+    readonly includeDrafts?: boolean;
+};
+declare function createFileSystemKnowledgeSource(options: FileSystemKnowledgeSourceOptions): KnowledgeSource;
+declare function loadKnowledgeEntries(options: FileSystemKnowledgeSourceOptions): Promise<Result<readonly KnowledgeEntry[], SurfaceError>>;
+declare function queryKnowledgeEntries(entries: readonly KnowledgeEntry[], relevanceQuery: RelevanceQuery): readonly KnowledgeEntry[];
+
+declare const LIGHTHOUSE_ACCESSIBILITY_AUDIT_IDS: readonly ["accesskeys", "aria-allowed-attr", "aria-allowed-role", "aria-command-name", "aria-conditional-attr", "aria-deprecated-role", "aria-dialog-name", "aria-hidden-body", "aria-hidden-focus", "aria-input-field-name", "aria-meter-name", "aria-progressbar-name", "aria-prohibited-attr", "aria-required-attr", "aria-required-children", "aria-required-parent", "aria-roles", "aria-text", "aria-toggle-field-name", "aria-tooltip-name", "aria-treeitem-name", "aria-valid-attr-value", "aria-valid-attr", "button-name", "bypass", "color-contrast", "definition-list", "dlitem", "document-title", "duplicate-id-aria", "form-field-multiple-labels", "frame-title", "heading-order", "html-has-lang", "html-lang-valid", "html-xml-lang-mismatch", "image-alt", "image-redundant-alt", "input-button-name", "input-image-alt", "label", "link-in-text-block", "link-name", "list", "listitem", "meta-refresh", "meta-viewport", "object-alt", "select-name", "skip-link", "tabindex", "table-duplicate-name", "target-size", "td-headers-attr", "th-has-data-cells", "valid-lang", "video-caption", "focusable-controls", "interactive-element-affordance", "logical-tab-order", "visual-order-follows-dom", "focus-traps", "managed-focus", "use-landmarks", "offscreen-content-hidden", "custom-controls-labels", "custom-controls-roles", "empty-heading", "identical-links-same-purpose", "landmark-one-main", "label-content-name-mismatch", "table-fake-caption", "td-has-header"];
+
+/**
+ * Privacy-first pino wrapper for surface packages.
+ *
+ * Redaction has two layers: semantic field names such as `token` keep the key and redact the
+ * value, while key names that themselves contain credential material are replaced with
+ * `[RedactedKey]`. Values are traversed defensively with circular detection, hostile getters are
+ * treated as sensitive, and string content is sanitized for URLs, bearer/API tokens, private keys,
+ * and common opaque credential placeholders before pino serializes the log line.
+ */
+declare const REDACTED_LOG_VALUE = "[Redacted]";
+declare const REDACTED_LOG_KEY = "[RedactedKey]";
+declare const CIRCULAR_LOG_VALUE = "[Circular]";
+declare const TRUNCATED_LOG_VALUE = "[Truncated]";
+type SurfaceLogFields = Record<string, unknown>;
+type CreateSurfaceLoggerOptions = {
+    readonly level?: string;
+    readonly runId?: string;
+    readonly stream?: DestinationStream;
+};
+/**
+ * Return a log-safe copy that removes captured content and credential-shaped fields.
+ */
+declare function sanitizeLogFields(fields: SurfaceLogFields): SurfaceLogFields;
+/**
+ * Create the structured pino logger used by surface libraries.
+ *
+ * The logger is intentionally opinionated: it writes privacy-safe JSON with ISO timestamps
+ * and sanitizes base fields, child bindings, object-first logs, and formatted arguments.
+ */
+declare function createSurfaceLogger(options?: CreateSurfaceLoggerOptions): Logger;
+
+type TaskFlowStep = {
+    readonly id: string;
+    readonly target: Target;
+};
+type TaskFlowCaptureRecipe = {
+    readonly id: string;
+    readonly steps: readonly TaskFlowStep[];
+    readonly themes?: readonly Theme[];
+};
+type CaptureContext = {
+    readonly stateId: string;
+    readonly theme?: Theme;
+};
+type TaskFlowCapturedState = CaptureContext & {
+    readonly capture: Capture;
+};
+type TaskFlowUnreachableStep = CaptureContext & {
+    readonly reason: string;
+    readonly target: Target;
+};
+type TaskFlowCaptureResult = {
+    readonly recipeId: string;
+    readonly captures: readonly TaskFlowCapturedState[];
+    readonly unreachable: readonly TaskFlowUnreachableStep[];
+    readonly status: "completed" | "degraded";
+};
+type RunTaskFlowCaptureInput = {
+    readonly captureOptions: CaptureOptions;
+    readonly recipe: TaskFlowCaptureRecipe;
+    readonly service: CaptureService;
+};
+type CaptureContextFinding = Finding & {
+    readonly captureContext: CaptureContext;
+    readonly tags: string[];
+};
+declare function runTaskFlowCapture(input: RunTaskFlowCaptureInput): Promise<Result<TaskFlowCaptureResult>>;
+declare function tagFindingsWithCaptureContext(findings: readonly Finding[], context: CaptureContext): readonly CaptureContextFinding[];
+
+declare const ReconciliationUnavailableReasonSchema: z.ZodEnum<{
+    model_unavailable: "model_unavailable";
+    channel_unavailable: "channel_unavailable";
+}>;
+type ReconciliationUnavailableReason = z.infer<typeof ReconciliationUnavailableReasonSchema>;
+declare const ReconciliationChannelSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    id: z.ZodString;
+    status: z.ZodLiteral<"available">;
+    findings: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        lens: z.ZodString;
+        issueType: z.ZodString;
+        method: z.ZodEnum<{
+            measured: "measured";
+            judged: "judged";
+        }>;
+        title: z.ZodString;
+        rationale: z.ZodString;
+        citedHeuristics: z.ZodArray<z.ZodString>;
+        evidence: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"tool-result">;
+            tool: z.ZodEnum<{
+                axe: "axe";
+                lighthouse: "lighthouse";
+                "eslint-jsx-a11y": "eslint-jsx-a11y";
+                backend: "backend";
+                "context-ingestor": "context-ingestor";
+            }>;
+            rule: z.ZodString;
+            measuredValue: z.ZodString;
+            threshold: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"dom">;
+            selector: z.ZodString;
+            elementRef: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"screenshot-region">;
+            artifactId: z.ZodString;
+            rect: z.ZodObject<{
+                x: z.ZodNumber;
+                y: z.ZodNumber;
+                width: z.ZodNumber;
+                height: z.ZodNumber;
+            }, z.core.$strict>;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"cited-heuristic">;
+            knowledgeEntryId: z.ZodString;
+        }, z.core.$strict>], "kind">>;
+        dimensions: z.ZodObject<{
+            severity: z.ZodNumber;
+            confidence: z.ZodNumber;
+            effort: z.ZodNumber;
+            userImpact: z.ZodNumber;
+            businessImpact: z.ZodNumber;
+            a11yLegalRisk: z.ZodNumber;
+            evidenceQuality: z.ZodNumber;
+            agentImplementability: z.ZodNumber;
+        }, z.core.$strict>;
+        severityBand: z.ZodEnum<{
+            P0: "P0";
+            P1: "P1";
+            P2: "P2";
+            P3: "P3";
+        }>;
+        location: z.ZodObject<{
+            file: z.ZodOptional<z.ZodString>;
+            component: z.ZodOptional<z.ZodString>;
+            selector: z.ZodOptional<z.ZodString>;
+            elementRef: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+        confidenceBand: z.ZodEnum<{
+            assert: "assert";
+            "surface-as-question": "surface-as-question";
+            "suppress-unless-deep": "suppress-unless-deep";
+        }>;
+        gatedForHuman: z.ZodBoolean;
+        suggestedPatch: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"contrast-hex">;
+            change: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"aria-attribute">;
+            change: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"target-size">;
+            change: z.ZodString;
+        }, z.core.$strict>], "kind">>;
+        tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>, z.ZodObject<{
+    id: z.ZodString;
+    status: z.ZodLiteral<"unavailable">;
+    reason: z.ZodEnum<{
+        model_unavailable: "model_unavailable";
+        channel_unavailable: "channel_unavailable";
+    }>;
+    message: z.ZodString;
+}, z.core.$strict>], "status">;
+type ReconciliationChannel = z.infer<typeof ReconciliationChannelSchema>;
+declare const ReconciliationInputSchema: z.ZodObject<{
+    channels: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        id: z.ZodString;
+        status: z.ZodLiteral<"available">;
+        findings: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            lens: z.ZodString;
+            issueType: z.ZodString;
+            method: z.ZodEnum<{
+                measured: "measured";
+                judged: "judged";
+            }>;
+            title: z.ZodString;
+            rationale: z.ZodString;
+            citedHeuristics: z.ZodArray<z.ZodString>;
+            evidence: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+                kind: z.ZodLiteral<"tool-result">;
+                tool: z.ZodEnum<{
+                    axe: "axe";
+                    lighthouse: "lighthouse";
+                    "eslint-jsx-a11y": "eslint-jsx-a11y";
+                    backend: "backend";
+                    "context-ingestor": "context-ingestor";
+                }>;
+                rule: z.ZodString;
+                measuredValue: z.ZodString;
+                threshold: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"dom">;
+                selector: z.ZodString;
+                elementRef: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"screenshot-region">;
+                artifactId: z.ZodString;
+                rect: z.ZodObject<{
+                    x: z.ZodNumber;
+                    y: z.ZodNumber;
+                    width: z.ZodNumber;
+                    height: z.ZodNumber;
+                }, z.core.$strict>;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"cited-heuristic">;
+                knowledgeEntryId: z.ZodString;
+            }, z.core.$strict>], "kind">>;
+            dimensions: z.ZodObject<{
+                severity: z.ZodNumber;
+                confidence: z.ZodNumber;
+                effort: z.ZodNumber;
+                userImpact: z.ZodNumber;
+                businessImpact: z.ZodNumber;
+                a11yLegalRisk: z.ZodNumber;
+                evidenceQuality: z.ZodNumber;
+                agentImplementability: z.ZodNumber;
+            }, z.core.$strict>;
+            severityBand: z.ZodEnum<{
+                P0: "P0";
+                P1: "P1";
+                P2: "P2";
+                P3: "P3";
+            }>;
+            location: z.ZodObject<{
+                file: z.ZodOptional<z.ZodString>;
+                component: z.ZodOptional<z.ZodString>;
+                selector: z.ZodOptional<z.ZodString>;
+                elementRef: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>;
+            confidenceBand: z.ZodEnum<{
+                assert: "assert";
+                "surface-as-question": "surface-as-question";
+                "suppress-unless-deep": "suppress-unless-deep";
+            }>;
+            gatedForHuman: z.ZodBoolean;
+            suggestedPatch: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+                kind: z.ZodLiteral<"contrast-hex">;
+                change: z.ZodString;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"aria-attribute">;
+                change: z.ZodString;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"target-size">;
+                change: z.ZodString;
+            }, z.core.$strict>], "kind">>;
+            tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>, z.ZodObject<{
+        id: z.ZodString;
+        status: z.ZodLiteral<"unavailable">;
+        reason: z.ZodEnum<{
+            model_unavailable: "model_unavailable";
+            channel_unavailable: "channel_unavailable";
+        }>;
+        message: z.ZodString;
+    }, z.core.$strict>], "status">>;
+}, z.core.$strict>;
+type ReconciliationInput = z.infer<typeof ReconciliationInputSchema>;
+declare const ReconciledFindingSchema: z.ZodObject<{
+    canonicalFindingId: z.ZodString;
+    finding: z.ZodObject<{
+        id: z.ZodString;
+        lens: z.ZodString;
+        issueType: z.ZodString;
+        method: z.ZodEnum<{
+            measured: "measured";
+            judged: "judged";
+        }>;
+        title: z.ZodString;
+        rationale: z.ZodString;
+        citedHeuristics: z.ZodArray<z.ZodString>;
+        evidence: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"tool-result">;
+            tool: z.ZodEnum<{
+                axe: "axe";
+                lighthouse: "lighthouse";
+                "eslint-jsx-a11y": "eslint-jsx-a11y";
+                backend: "backend";
+                "context-ingestor": "context-ingestor";
+            }>;
+            rule: z.ZodString;
+            measuredValue: z.ZodString;
+            threshold: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"dom">;
+            selector: z.ZodString;
+            elementRef: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"screenshot-region">;
+            artifactId: z.ZodString;
+            rect: z.ZodObject<{
+                x: z.ZodNumber;
+                y: z.ZodNumber;
+                width: z.ZodNumber;
+                height: z.ZodNumber;
+            }, z.core.$strict>;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"cited-heuristic">;
+            knowledgeEntryId: z.ZodString;
+        }, z.core.$strict>], "kind">>;
+        dimensions: z.ZodObject<{
+            severity: z.ZodNumber;
+            confidence: z.ZodNumber;
+            effort: z.ZodNumber;
+            userImpact: z.ZodNumber;
+            businessImpact: z.ZodNumber;
+            a11yLegalRisk: z.ZodNumber;
+            evidenceQuality: z.ZodNumber;
+            agentImplementability: z.ZodNumber;
+        }, z.core.$strict>;
+        severityBand: z.ZodEnum<{
+            P0: "P0";
+            P1: "P1";
+            P2: "P2";
+            P3: "P3";
+        }>;
+        location: z.ZodObject<{
+            file: z.ZodOptional<z.ZodString>;
+            component: z.ZodOptional<z.ZodString>;
+            selector: z.ZodOptional<z.ZodString>;
+            elementRef: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+        confidenceBand: z.ZodEnum<{
+            assert: "assert";
+            "surface-as-question": "surface-as-question";
+            "suppress-unless-deep": "suppress-unless-deep";
+        }>;
+        gatedForHuman: z.ZodBoolean;
+        suggestedPatch: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"contrast-hex">;
+            change: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"aria-attribute">;
+            change: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"target-size">;
+            change: z.ZodString;
+        }, z.core.$strict>], "kind">>;
+        tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>;
+    confidence: z.ZodNumber;
+    severityBand: z.ZodEnum<{
+        P0: "P0";
+        P1: "P1";
+        P2: "P2";
+        P3: "P3";
+    }>;
+    sourceFindingIds: z.ZodArray<z.ZodString>;
+    supportingChannels: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+type ReconciledFinding = z.infer<typeof ReconciledFindingSchema>;
+declare const ReconciliationQuestionSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"severity-divergence">;
+    groupKey: z.ZodString;
+    prompt: z.ZodString;
+    findingIds: z.ZodArray<z.ZodString>;
+    channelIds: z.ZodArray<z.ZodString>;
+    severityBands: z.ZodArray<z.ZodEnum<{
+        P0: "P0";
+        P1: "P1";
+        P2: "P2";
+        P3: "P3";
+    }>>;
+}, z.core.$strict>;
+type ReconciliationQuestion = z.infer<typeof ReconciliationQuestionSchema>;
+declare const ReconciliationUnavailableChannelSchema: z.ZodObject<{
+    id: z.ZodString;
+    reason: z.ZodEnum<{
+        model_unavailable: "model_unavailable";
+        channel_unavailable: "channel_unavailable";
+    }>;
+    message: z.ZodString;
+}, z.core.$strict>;
+type ReconciliationUnavailableChannel = z.infer<typeof ReconciliationUnavailableChannelSchema>;
+declare const ReconciliationResultSchema: z.ZodObject<{
+    participatedChannels: z.ZodArray<z.ZodString>;
+    unavailableChannels: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        reason: z.ZodEnum<{
+            model_unavailable: "model_unavailable";
+            channel_unavailable: "channel_unavailable";
+        }>;
+        message: z.ZodString;
+    }, z.core.$strict>>;
+    findings: z.ZodArray<z.ZodObject<{
+        canonicalFindingId: z.ZodString;
+        finding: z.ZodObject<{
+            id: z.ZodString;
+            lens: z.ZodString;
+            issueType: z.ZodString;
+            method: z.ZodEnum<{
+                measured: "measured";
+                judged: "judged";
+            }>;
+            title: z.ZodString;
+            rationale: z.ZodString;
+            citedHeuristics: z.ZodArray<z.ZodString>;
+            evidence: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+                kind: z.ZodLiteral<"tool-result">;
+                tool: z.ZodEnum<{
+                    axe: "axe";
+                    lighthouse: "lighthouse";
+                    "eslint-jsx-a11y": "eslint-jsx-a11y";
+                    backend: "backend";
+                    "context-ingestor": "context-ingestor";
+                }>;
+                rule: z.ZodString;
+                measuredValue: z.ZodString;
+                threshold: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"dom">;
+                selector: z.ZodString;
+                elementRef: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"screenshot-region">;
+                artifactId: z.ZodString;
+                rect: z.ZodObject<{
+                    x: z.ZodNumber;
+                    y: z.ZodNumber;
+                    width: z.ZodNumber;
+                    height: z.ZodNumber;
+                }, z.core.$strict>;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"cited-heuristic">;
+                knowledgeEntryId: z.ZodString;
+            }, z.core.$strict>], "kind">>;
+            dimensions: z.ZodObject<{
+                severity: z.ZodNumber;
+                confidence: z.ZodNumber;
+                effort: z.ZodNumber;
+                userImpact: z.ZodNumber;
+                businessImpact: z.ZodNumber;
+                a11yLegalRisk: z.ZodNumber;
+                evidenceQuality: z.ZodNumber;
+                agentImplementability: z.ZodNumber;
+            }, z.core.$strict>;
+            severityBand: z.ZodEnum<{
+                P0: "P0";
+                P1: "P1";
+                P2: "P2";
+                P3: "P3";
+            }>;
+            location: z.ZodObject<{
+                file: z.ZodOptional<z.ZodString>;
+                component: z.ZodOptional<z.ZodString>;
+                selector: z.ZodOptional<z.ZodString>;
+                elementRef: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>;
+            confidenceBand: z.ZodEnum<{
+                assert: "assert";
+                "surface-as-question": "surface-as-question";
+                "suppress-unless-deep": "suppress-unless-deep";
+            }>;
+            gatedForHuman: z.ZodBoolean;
+            suggestedPatch: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+                kind: z.ZodLiteral<"contrast-hex">;
+                change: z.ZodString;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"aria-attribute">;
+                change: z.ZodString;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"target-size">;
+                change: z.ZodString;
+            }, z.core.$strict>], "kind">>;
+            tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>;
+        confidence: z.ZodNumber;
+        severityBand: z.ZodEnum<{
+            P0: "P0";
+            P1: "P1";
+            P2: "P2";
+            P3: "P3";
+        }>;
+        sourceFindingIds: z.ZodArray<z.ZodString>;
+        supportingChannels: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>;
+    questions: z.ZodArray<z.ZodObject<{
+        kind: z.ZodLiteral<"severity-divergence">;
+        groupKey: z.ZodString;
+        prompt: z.ZodString;
+        findingIds: z.ZodArray<z.ZodString>;
+        channelIds: z.ZodArray<z.ZodString>;
+        severityBands: z.ZodArray<z.ZodEnum<{
+            P0: "P0";
+            P1: "P1";
+            P2: "P2";
+            P3: "P3";
+        }>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+type ReconciliationResult = z.infer<typeof ReconciliationResultSchema>;
+interface ReconciliationService {
+    reconcile(input: ReconciliationInput): Result<ReconciliationResult>;
+}
+declare function createReconciliationService(): ReconciliationService;
+declare function reconcileFindings(input: ReconciliationInput): Result<ReconciliationResult>;
+
+type ResponsivenessStatesLensOptions = {
+    readonly projectRoot?: string;
+};
+/**
+ * Creates the built-in responsiveness and UI-state lens over DOM capture artifacts.
+ */
+declare function createResponsivenessStatesLens(options?: ResponsivenessStatesLensOptions): Lens;
+
+/** Default project-local directory used for Surface state and artifacts. */
+declare const SURFACE_STATE_DIR = ".surface";
+/** Aggregate JSON file name inside the Surface state directory. */
+declare const SURFACE_STATE_FILE = "state.json";
+/** Current persisted state schema version.
+ *
+ * Optional pipeline metadata is additive and parsed with passthrough semantics,
+ * so existing 1.0 readers remain compatible.
+ */
+declare const SURFACE_STATE_VERSION = "1.0";
+type FileStateStoreOptions = {
+    readonly projectRoot?: string;
+    /** Project-root-relative child directory for state; invalid paths throw at construction time. */
+    readonly stateDir?: string;
+    readonly stateVersion?: string;
+    readonly lockOptions?: LockOptions;
+};
+/**
+ * Create a file-backed StateStore rooted at projectRoot/.surface by default.
+ * Invalid configuration fails fast with TypeError; runtime IO uses Result errors.
+ */
+declare function createFileStateStore(options?: FileStateStoreOptions): StateStore;
+
+type LinearIssueInput = {
+    readonly description: string;
+    readonly labels?: readonly string[];
+    readonly teamId: string;
+    readonly title: string;
+};
+type JiraIssueInput = {
+    readonly fields: {
+        readonly description: string;
+        readonly issuetype: {
+            readonly name: string;
+        };
+        readonly labels?: readonly string[];
+        readonly project: {
+            readonly key: string;
+        };
+        readonly summary: string;
+    };
+};
+type LinearIssueClient = {
+    createIssue(input: LinearIssueInput): Promise<unknown>;
+};
+type JiraIssueClient = {
+    createIssue(input: JiraIssueInput): Promise<unknown>;
+};
+type LinearIssueExporterOptions = {
+    readonly teamId: string;
+    readonly apiKey?: string;
+    readonly endpointUrl?: string;
+    readonly labels?: readonly string[];
+    readonly projectRoot?: string;
+    readonly client?: LinearIssueClient;
+    readonly maxAttempts?: number;
+    readonly initialBackoffMs?: number;
+    readonly wait?: (milliseconds: number) => Promise<void>;
+    readonly redactionRules?: readonly RedactionRule[];
+};
+type JiraIssueExporterOptions = {
+    readonly projectKey: string;
+    readonly siteUrl?: string;
+    readonly email?: string;
+    readonly apiToken?: string;
+    readonly issueType?: string;
+    readonly labels?: readonly string[];
+    readonly projectRoot?: string;
+    readonly client?: JiraIssueClient;
+    readonly maxAttempts?: number;
+    readonly initialBackoffMs?: number;
+    readonly wait?: (milliseconds: number) => Promise<void>;
+    readonly redactionRules?: readonly RedactionRule[];
+};
+declare function createLinearIssueExporter(options: LinearIssueExporterOptions): IssueExporter;
+declare function createJiraIssueExporter(options: JiraIssueExporterOptions): IssueExporter;
+
+type UsabilityHeuristicLensOptions = LensFactoryOptions;
+/**
+ * Creates the built-in judged usability lens backed by an injected model provider.
+ */
+declare function createUsabilityHeuristicLens(options?: UsabilityHeuristicLensOptions): Lens;
+
+declare const VerdictDecisionSchema: z.ZodEnum<{
+    reject: "reject";
+    accept: "accept";
+    correct: "correct";
+    defer: "defer";
+}>;
+type VerdictDecision = z.infer<typeof VerdictDecisionSchema>;
+declare const VerdictReusePolicySchema: z.ZodEnum<{
+    "this-run": "this-run";
+    "this-identity-always": "this-identity-always";
+}>;
+type VerdictReusePolicy = z.infer<typeof VerdictReusePolicySchema>;
+declare const VerdictSchema: z.ZodObject<{
+    findingIdentityKey: z.ZodString;
+    findingId: z.ZodString;
+    decision: z.ZodEnum<{
+        reject: "reject";
+        accept: "accept";
+        correct: "correct";
+        defer: "defer";
+    }>;
+    rationale: z.ZodString;
+    recordedAt: z.ZodString;
+    reusePolicy: z.ZodEnum<{
+        "this-run": "this-run";
+        "this-identity-always": "this-identity-always";
+    }>;
+}, z.core.$strict>;
+type Verdict = z.infer<typeof VerdictSchema>;
+declare const SelfGroundingReportSchema: z.ZodObject<{
+    sampleSize: z.ZodNumber;
+    measuredGroundTruthCount: z.ZodNumber;
+    judgedFalsePositiveCount: z.ZodNumber;
+    judgedFalsePositiveRate: z.ZodNumber;
+}, z.core.$strict>;
+type SelfGroundingReport = z.infer<typeof SelfGroundingReportSchema>;
+type CreateVerdictInput = {
+    readonly finding: Finding;
+    readonly decision: VerdictDecision;
+    readonly rationale: string;
+    readonly recordedAt?: string | Date;
+    readonly reusePolicy?: VerdictReusePolicy;
+};
+type CreateSelfGroundingReportInput = {
+    readonly findings: readonly Finding[];
+    readonly verdicts: readonly Verdict[];
+};
+type ApplyVerdictsToBacklogInput = {
+    readonly backlog: Backlog;
+    readonly verdicts: readonly Verdict[];
+};
+declare function createVerdict(input: CreateVerdictInput): Result<Verdict>;
+declare function createSelfGroundingReport(input: CreateSelfGroundingReportInput): Result<SelfGroundingReport>;
+declare function applyVerdictsToBacklog(input: ApplyVerdictsToBacklogInput): Result<Backlog>;
+
+type VisualHierarchyLensOptions = {
+    readonly maxFontSizeSteps?: number;
+    readonly minHeadingScaleRatio?: number;
+    readonly projectRoot?: string;
+};
+/**
+ * Creates the built-in visual hierarchy lens, grounded by computed style tokens.
+ */
+declare function createVisualHierarchyLens(options?: VisualHierarchyLensOptions): Lens;
+
+declare const CORE_PACKAGE_NAME = "@zigrivers/surface-core";
+
+export { APP_TYPE_OVERLAY_REGISTRY, APP_TYPE_OVERLAY_YAML_HEADER, type AgentBrowserCaptureBackendOptions, type AgentBrowserCommandResult, type AgentBrowserCommandRunner, type AlternativeProposal, type AlternativesRendererOptions, type AlternativesReportData, AppType, type AppTypeClassification, AppTypeClassificationSchema, type AppTypeOverlay, AppTypeOverlaySchema, type ApplyVerdictsToBacklogInput, BUILT_IN_LENS_REGISTRY, Backlog, CIRCULAR_LOG_VALUE, COMMITTED_WEB_APP_TYPE_OVERLAYS, CORE_PACKAGE_NAME, type CaptureClock, type CaptureContext, type CaptureContextFinding, type CaptureIdFactory, type CaptureRandomHex, type CaptureService, type CaptureServiceOptions, CitationSchema, type CognitivePersona, type CognitiveTaskDefinition, type ContentMicrocopyLensOptions, type ContextIngestion, type ContextIngestionInput, type ContextIngestor, type ContextIngestorClock, type ContextIngestorOptions, type ContextInputKind, type ConversionLensOptions, type CreateSelfGroundingReportInput, type CreateSurfaceLoggerOptions, type CreateVerdictInput, DEFAULT_COMPOSITION_STAGE_IDS, DEFAULT_PIPELINE_STAGE_DEFINITIONS, type DesignToken, type DiffRendererOptions, type DiscoveryEvent, DiscoveryEventSchema, type DiscoveryResult, DiscoveryResultSchema, type DiscoveryRunInput, type ExecutablePipelineStageId, ExecutablePipelineStageIdSchema, type ExplainRendererOptions, type FileSystemKnowledgeSourceOptions, Finding, FindingDraft, FindingsEnvelope, type FindingsJsonRendererOptions, FreshnessSchema, FreshnessVolatilitySchema, type GitHubChecksExport, type GitHubChecksExportInput, type GitHubChecksExporterOptions, type GitHubIssueExporterOptions, type IngestedContext, type InputProvenance, type InstantiatedLens, type JiraIssueClient, type JiraIssueExporterOptions, KnowledgeCategorySchema, LIGHTHOUSE_ACCESSIBILITY_AUDIT_IDS, type LensExecutionPlan, type LensExecutionSkip, type LensFactoryOptions, type LensRegistration, type LensSkipReason, type LinearIssueClient, type LinearIssueExporterOptions, ModelAvailability, type OverlayAcceptanceCriteria, OverlayAcceptanceCriteriaSchema, type OverlayReleaseTier, OverlayReleaseTierSchema, type Persona, type PersonaTask, PersonaTaskSchema, type PipelineEvent, PipelineEventSchema, type PipelineOrchestrator, type PipelineOrchestratorOptions, type PipelineRunInput, type PipelineRunResult, type PipelineStageContext, type PipelineStageDefinition, type PipelineStageHandler, type PipelineStageId, PipelineStageIdSchema, type PlaywrightCaptureBackendOptions, REDACTED_EXPORT_VALUE, REDACTED_LOG_KEY, REDACTED_LOG_VALUE, REGISTERED_APP_TYPE_OVERLAYS, type ReconciledFinding, ReconciledFindingSchema, type ReconciliationChannel, ReconciliationChannelSchema, type ReconciliationInput, ReconciliationInputSchema, type ReconciliationQuestion, ReconciliationQuestionSchema, type ReconciliationResult, ReconciliationResultSchema, type ReconciliationService, type ReconciliationUnavailableChannel, ReconciliationUnavailableChannelSchema, type ReconciliationUnavailableReason, ReconciliationUnavailableReasonSchema, RedactionRule, type RegisteredAppTypeOverlay, type RenderAndWriteReportArtifactsOptions, type ReportArtifactSpec, type ReportRendererRedactionOptions, type ResponsivenessStatesLensOptions, Result, type RouteInventory, type RouteInventoryEntry, RouteInventoryEntrySchema, RouteInventorySchema, type RouteSkipped, RouteSkippedSchema, type RunTaskFlowCaptureInput, SURFACE_STATE_DIR, SURFACE_STATE_FILE, SURFACE_STATE_VERSION, type SelectLensExecutionPlanInput, type SelfGroundingReport, SelfGroundingReportSchema, type StaticCaptureBackendOptions, type SurfaceComposition, type SurfaceCompositionGeneratedAt, type SurfaceCompositionOptions, SurfaceConfig, SurfaceError, type SurfaceLogFields, type SurfaceSarifLog, SurfaceSarifLogSchema, type SynthesisDecision, type SynthesizeMeasuredWinsInput, TRUNCATED_LOG_VALUE, type TaskCompletionLensOptions, type TaskDefinition, type TaskFlowCaptureRecipe, type TaskFlowCaptureResult, type TaskFlowCapturedState, type TaskFlowStep, type TaskFlowUnreachableStep, type TextInput, TrackedFindingsDiff, type UsabilityHeuristicLensOptions, type Verdict, type VerdictDecision, VerdictDecisionSchema, type VerdictReusePolicy, VerdictReusePolicySchema, VerdictSchema, type VisualHierarchyLensOptions, type WrittenReportArtifact, applyVerdictsToBacklog, createAccessibilityLens, createAgentBrowserCaptureBackend, createAgentPlanMarkdownRenderer, createAlternativesJsonRenderer, createBacklogMarkdownRenderer, createBoundedAlternatives, createCaptureService, createContentMicrocopyLens, createContextIngestor, createConversionLens, createDefaultCaptureIdFactory, createDiffJsonRenderer, createExplainJsonRenderer, createExplainMarkdownRenderer, createFileStateStore, createFileSystemKnowledgeSource, createFindingsJsonRenderer, createFindingsMarkdownRenderer, createGateEvaluator, createGitHubChecksExporter, createGitHubIssueExporter, createJiraIssueExporter, createLinearIssueExporter, createNoopPipelineHandlers, createPipelineOrchestrator, createPlaywrightCaptureBackend, createReconciliationService, createResponsivenessStatesLens, createSarifRenderer, createSelfGroundingReport, createStaticCaptureBackend, createSurfaceComposition, createSurfaceLogger, createTaskCompletionLens, createUsabilityHeuristicLens, createValidationReportMarkdownRenderer, createVerdict, createVisualHierarchyLens, defaultPlanningReportArtifactSpecs, getAppTypeOverlay, hasRegisteredAppTypeOverlay, instantiateLensExecutionPlan, listAppTypeOverlays, loadKnowledgeEntries, queryKnowledgeEntries, reconcileFindings, redactExportString, redactExportValue, renderAndWriteReportArtifacts, runDiscovery, runTaskFlowCapture, sanitizeLogFields, selectCaptureBackend, selectLensExecutionPlan, selectPipelineStages, serializeAppTypeOverlayToYaml, synthesizeMeasuredWinsDecision, tagFindingsWithCaptureContext };