@tyroneross/navgator 0.2.2 → 0.10.0

package/dist/types.d.ts

@@ -2,14 +2,15 @@
  * NavGator Type Definitions
  * Architecture connection tracking for Claude Code
  */
+import type { ExternalEnrichment } from './enrich/external-enrichment.types.js';
 /**
  * Types of architecture components that NavGator tracks
  */
-export type ComponentType = 'npm' | 'pip' | 'spm' | 'cargo' | 'go' | 'gem' | 'composer' | 'framework' | 'database' | 'queue' | 'infra' | 'service' | 'llm' | 'api-endpoint' | 'db-table' | 'prompt' | 'worker' | 'component' | 'other';
+export type ComponentType = 'npm' | 'pip' | 'spm' | 'cargo' | 'go' | 'gem' | 'composer' | 'framework' | 'database' | 'queue' | 'infra' | 'service' | 'llm' | 'config' | 'cron' | 'api-endpoint' | 'db-table' | 'prompt' | 'worker' | 'component' | 'document' | 'xcode-target' | 'other';
 /**
  * Architecture layer classification
  */
-export type ArchitectureLayer = 'frontend' | 'backend' | 'database' | 'queue' | 'infra' | 'external';
+export type ArchitectureLayer = 'frontend' | 'backend' | 'database' | 'queue' | 'infra' | 'content' | 'external';
 /**
  * Component status
  */
@@ -28,6 +29,12 @@ export interface ConnectionRef {
  */
 export interface ArchitectureComponent {
     component_id: string;
+    /**
+     * Stable, deterministic identifier derived from type + canonical name.
+     * Format: STABLE_<type>_<slug>. Same component across scans → same stable_id.
+     * Used as the cross-scan join key for PageRank persistence, git diffs, timeline tracking.
+     */
+    stable_id?: string;
     name: string;
     version?: string;
     type: ComponentType;
@@ -49,6 +56,8 @@ export interface ArchitectureComponent {
     documentation_url?: string;
     repository_url?: string;
     metadata?: Record<string, unknown>;
+    runtime?: RuntimeIdentity;
+    external?: ExternalEnrichment;
     timestamp: number;
     last_updated: number;
 }
@@ -72,10 +81,35 @@ export interface Vulnerability {
     fixed_in?: string;
     url?: string;
 }
+/**
+ * Runtime identity annotation for architecture components.
+ * Maps code-level components to their runtime services/resources.
+ * Extracted from code and config — never from live service polling.
+ */
+export interface RuntimeIdentity {
+    /** Service/resource name as known at runtime (e.g., "email-queue", "worker") */
+    service_name?: string;
+    /** Deployment platform (vercel, railway, heroku, docker, local) */
+    platform?: string;
+    /** Parsed connection info (no secrets — just host, port, db name, protocol) */
+    endpoint?: {
+        protocol?: string;
+        host?: string;
+        port?: number;
+        database?: string;
+        path?: string;
+    };
+    /** Env var that provides the connection (e.g., "DATABASE_URL", "REDIS_URL") */
+    connection_env_var?: string;
+    /** Runtime resource type */
+    resource_type?: 'database' | 'cache' | 'queue' | 'api' | 'worker' | 'cron' | 'storage';
+    /** Provider/engine (postgres, mysql, redis, bullmq, openai, etc.) */
+    engine?: string;
+}
 /**
  * Types of connections between components
  */
-export type ConnectionType = 'api-calls-db' | 'frontend-calls-api' | 'queue-triggers' | 'service-call' | 'imports' | 'deploys-to' | 'prompt-location' | 'prompt-usage' | 'uses-package' | 'observes' | 'conforms-to' | 'notifies' | 'stores' | 'navigates-to' | 'requires-entitlement' | 'target-contains' | 'generates' | 'other';
+export type ConnectionType = 'api-calls-db' | 'frontend-calls-api' | 'queue-triggers' | 'service-call' | 'imports' | 'deploys-to' | 'env-dependency' | 'schema-relation' | 'cron-triggers' | 'queue-produces' | 'queue-consumes' | 'prompt-location' | 'prompt-usage' | 'uses-package' | 'wikilink' | 'markdown-link' | 'typed-relationship' | 'observes' | 'conforms-to' | 'notifies' | 'stores' | 'navigates-to' | 'presents' | 'requires-entitlement' | 'target-contains' | 'build-phase-includes' | 'generates' | 'field-reference' | 'runtime-binding' | 'queue-uses-cache' | 'other';
 /**
  * Code location reference
  */
@@ -108,6 +142,11 @@ export interface ArchitectureConnection {
         line_end?: number;
         code_snippet?: string;
     };
+    semantic?: {
+        classification: 'production' | 'admin' | 'analytics' | 'test' | 'dev-only' | 'migration' | 'unknown';
+        confidence: number;
+    };
+    runtime_relevance?: 'runtime' | 'type-only';
     description?: string;
     detected_from: string;
     confidence: number;
@@ -148,7 +187,7 @@ export interface FileChangeResult {
  * Project-level metadata for agent orientation
  */
 export interface ProjectMetadata {
-    type: 'swift-app' | 'web-app' | 'api' | 'library' | 'monorepo' | 'unknown';
+    type: 'swift-app' | 'rust-app' | 'web-app' | 'api' | 'library' | 'monorepo' | 'unknown';
     platforms?: ('iOS' | 'macOS' | 'watchOS' | 'tvOS' | 'visionOS')[];
     architecture_pattern?: string;
     min_deployment?: Record<string, string>;
@@ -166,10 +205,42 @@ export interface ProjectMetadata {
         type: string;
         files: string[];
     }[];
+    xcodeProject?: {
+        path: string;
+        targets: {
+            name: string;
+            type: string;
+            bundleId?: string;
+        }[];
+    };
 }
+/**
+ * Scan mode types (Run 1 — D2). 'auto' is the default decision, resolved
+ * by selectScanMode to one of full/incremental/noop. 'incremental→full'
+ * is the runtime label for an incremental scan that promoted to full
+ * after an integrity-check failure.
+ */
+export type ScanType = 'full' | 'incremental' | 'incremental→full' | 'noop';
 export interface ArchitectureIndex {
+    schema_version?: string;
+    stable_id_scheme?: number;
     version: string;
     last_scan: number;
+    /**
+     * Run 1 — D2: timestamp of the most recent FULL scan (or
+     * 'incremental→full' promote). Used by selectScanMode to enforce the
+     * staleness trigger (force full after 7 days). Optional for backward
+     * compat; selectScanMode treats `undefined` as "never had a full scan".
+     */
+    last_full_scan?: number;
+    /**
+     * Run 1 — D2: count of incremental scans since the most recent full
+     * scan. selectScanMode forces a full scan once this exceeds the cap
+     * (currently 20). Reset to 0 on every full or 'incremental→full' scan.
+     */
+    incrementals_since_full?: number;
+    /** Last completed setup phase, written by setup scans under the writer lease. */
+    setup_phase?: 'fast' | 'deep';
     project_path: string;
     project?: ProjectMetadata;
     components: {
@@ -191,11 +262,226 @@ export interface ArchitectureIndex {
         outdated_count: number;
         vulnerable_count: number;
     };
+    /**
+     * Run 2 — D5: per-stratum EWMA state for defect-rate drift detection.
+     * Updated after each scan that runs an audit. Optional for backward compat.
+     * If any stratum's EWMA breaches its control limits, the next scan
+     * auto-promotes to mode='full' + audit-plan='Cochran' for tighter inspection.
+     */
+    ewma?: Record<string, EwmaStateSnapshot>;
+    /**
+     * Run 2 — D4: rolling count of audits that have run on this index. Used
+     * to switch from AQL → SPRT once history ≥ 3.
+     */
+    audit_history_count?: number;
+    /**
+     * Run 2: when the previous run's audit detected an EWMA breach, this is
+     * set so the NEXT scan can read it and auto-promote.
+     */
+    pending_drift_breach?: boolean;
+}
+/**
+ * Run 2 — snapshot of EWMA state persisted on the index. Mirrors `EwmaState`
+ * from `src/audit/spc.ts`; duplicated here so types.ts has zero runtime imports
+ * from the audit module.
+ */
+export interface EwmaStateSnapshot {
+    lambda: number;
+    L: number;
+    mean: number;
+    variance: number;
+    n: number;
+    points: number[];
+    breach_pending?: boolean;
+    /** Chart kind: p-chart (defect fraction, varying n) or u-chart (defects per edge). */
+    kind?: 'p' | 'u';
+    /** NavGator version that produced this series; a change re-baselines (protocol step 15). */
+    version?: string;
+    /** Phase I (limits not yet frozen; cannot breach) vs Phase II (frozen limits). */
+    phase?: 'provisional' | 'frozen';
+    /** Phase I accumulators: Σ defects and Σ inspected units (NIST §6.3.3.1 p̄ = ΣD_i / Σn_i). */
+    phase1_defects?: number;
+    phase1_units?: number;
+    /** Frozen centre line (p̄ or ū), floored at the prior when the observed rate is lower. */
+    center?: number;
+    /** True when `center` came from the floor rather than the data (low-side signals suppressed). */
+    floor_active?: boolean;
+    /** Standardised tabular CUSUM state (NIST §6.3.2.3): k=0.5σ, h=5σ in σ units. */
+    cusum?: {
+        s_hi: number;
+        s_lo: number;
+        k: number;
+        h: number;
+    };
+    /** Signed run length for Western Electric Rule 4 (8 consecutive on one side). */
+    run_side?: number;
+    /** Last observation (rate, inspected units, and the Shewhart limits used). */
+    last?: {
+        x: number;
+        n: number;
+        ucl: number;
+        lcl: number;
+        ewma: number;
+        ewma_ucl: number;
+        ewma_lcl: number;
+    };
+    /** Signals raised on the most recent update (e.g. 'rule1-high', 'ewma-low', 'cusum-high', 'rule4-high'). */
+    signals?: string[];
+    /** Set when the series was reset because the NavGator version changed. */
+    rebaselined_from?: string;
+    rebaselined_at?: number;
+}
+/**
+ * Run 2 — D2 defect taxonomy.
+ */
+export type AuditDefectClass = 'HALLUCINATED_COMPONENT' | 'HALLUCINATED_EDGE' | 'WRONG_ENDPOINT' | 'STALE_REFERENCE' | 'DEDUP_COLLISION' | 'MISSED_EDGE';
+export interface AuditSampleEvidence {
+    id: string;
+    ok: boolean;
+    reason?: string;
+    /** Run 4: defect class of the verifier that produced this row (optional, additive). */
+    class?: AuditDefectClass;
+    /** Run 4 F5: the fact carried no evidence the verifier could check (ok stays true; counted separately). */
+    unverifiable?: boolean;
+}
+/**
+ * Run 2 — D4: audit report attached to a TimelineEntry.
+ */
+export interface AuditReport {
+    plan: 'AQL' | 'SPRT' | 'Cochran';
+    n: number;
+    c: number;
+    sampled: number;
+    defects: number;
+    defect_rate: number;
+    by_class: Partial<Record<AuditDefectClass, {
+        sampled: number;
+        defects: number;
+        unverifiable?: number;
+    }>>;
+    by_stratum: Record<string, AuditStratumStats>;
+    llm_skipped?: boolean;
+    /** 'inconclusive' (Run 4): SPRT reached the founding-sample cap without a verdict. */
+    verdict: 'accept' | 'reject' | 'continue' | 'inconclusive';
+    drift_breach?: boolean;
+    timestamp: number;
+    defect_evidence?: AuditSampleEvidence[];
+    /** NavGator version that produced this audit (measurement-system identity). */
+    navgator_version?: string;
+    /** c=0 go/no-go screen (research packet §1.3–1.4): triage only, never a gate. */
+    screen?: AuditScreen;
+    /** Precision-sample design actually used (protocol step 8). */
+    precision?: AuditPrecisionDesign;
+    /** SPRT continuation bookkeeping (Run 4 fixes "continue with no further batch"). `verdict` is the SPRT decision; the report-level `verdict` is always the c=0 screen. */
+    sprt?: {
+        batches: number;
+        observations: number;
+        cap: number;
+        log_lr: number;
+        verdict?: 'accept' | 'reject' | 'inconclusive';
+    };
+    /** Run 4 F5: distinct inspected facts that carried no checkable evidence (excluded from rates). */
+    unverifiable?: number;
+    /** Exact, whole-population counts — never sampled (Run 4 defect 5). */
+    census?: AuditCensus;
+    /** Independent oracle precision/recall against manifests the scanner never read. */
+    oracles?: AuditOracleResult[];
+}
+/** Run 4: per-stratum stats with a 95% interval. */
+export interface AuditStratumStats {
+    sampled: number;
+    defects: number;
+    defect_rate: number;
+    /** Stratum population size N_h. */
+    n_total?: number;
+    /** 95% interval on defect_rate (Wilson; Clopper-Pearson at 0 or n). */
+    ci?: ProportionInterval;
+    /** True when N_h < floor so the stratum is charted under `__pooled`. */
+    pooled?: boolean;
+}
+export interface ProportionInterval {
+    lower: number;
+    upper: number;
+    method: 'wilson' | 'clopper-pearson';
+}
+export interface AuditScreen {
+    /** Sample size per population (components and connections each). */
+    n: number;
+    c: 0;
+    ltpd: number;
+    consumer_risk: number;
+    components_sampled: number;
+    connections_sampled: number;
+    defects: number;
+    verdict: 'accept' | 'reject';
+    /** 95% one-sided upper bound on the true error rate when defects = 0, at the COMBINED inspected count: 1 − 0.05^(1/inspected). */
+    upper_bound_95: number;
+    /** Probability this combined screen rejects a map that is truly 99% correct: 1 − 0.99^inspected (F1). */
+    producers_risk_at_1pct: number;
+    /** Evaluable units actually inspected across both populations (components + connections, minus unverifiable). */
+    inspected?: number;
+    /** Inspected units that carried no checkable evidence (F5). */
+    unverifiable?: number;
+    /** The same two figures for one population of n=45 on its own (the research packet's per-population statement). */
+    per_population?: {
+        n: number;
+        upper_bound_95: number;
+        producers_risk_at_1pct: number;
+    };
+}
+export interface AuditPrecisionDesign {
+    /** 'founding' (±3pp) on the first audit or Cochran; 'routine' (±5pp) otherwise. */
+    kind: 'founding' | 'routine';
+    margin: number;
+    n_components: number;
+    n_connections: number;
+    floor: number;
+    /** Strata whose N_h < floor and are therefore pooled for charting. */
+    pooled_strata: string[];
+}
+export interface AuditCensus {
+    unresolved_endpoints: {
+        bad: number;
+        total: number;
+        rate: number;
+        ci?: ProportionInterval;
+        by_type: Record<string, {
+            bad: number;
+            total: number;
+        }>;
+        by_top_dir: Record<string, {
+            bad: number;
+            total: number;
+        }>;
+    };
+    dedup_collisions: number;
+}
+export interface AuditOracleResult {
+    /** Oracle id: 'npm' | 'prisma' | 'cron' | 'queue' | 'imports-scip'. */
+    oracle: string;
+    stratum: string;
+    oracle_strength: 'independent' | 'weak' | 'none';
+    truth_count: number;
+    map_count: number;
+    tp: number;
+    fp: number;
+    fn: number;
+    precision: number | null;
+    recall: number | null;
+    precision_ci: ProportionInterval | null;
+    recall_ci: ProportionInterval | null;
+    fp_samples: string[];
+    fn_samples: string[];
+    /** Fraction of the truth frame the oracle could actually enumerate (SCIP: documents indexed / TS files). */
+    frame_coverage?: number;
+    notes: string[];
 }
 /**
- * Full connection graph (for visualization/analysis)
+ * Derived connection-graph projection for visualization and analysis.
+ * Complete connection records live in `connections.full.jsonl`.
  */
 export interface ConnectionGraph {
+    schema_version?: string;
     nodes: GraphNode[];
     edges: GraphEdge[];
     metadata: {
@@ -206,6 +492,7 @@ export interface ConnectionGraph {
 }
 export interface GraphNode {
     id: string;
+    stable_id?: string;
     name: string;
     type: ComponentType;
     layer: ArchitectureLayer;
@@ -225,8 +512,96 @@ export interface ScanResult {
     connections: ArchitectureConnection[];
     warnings: ScanWarning[];
 }
+/**
+ * Outcome status for the top-level architecture scan orchestrator.
+ *
+ * This is intentionally separate from `ScanResult`, which is the lightweight
+ * contract shared by individual detector modules.
+ */
+export type ArchitectureScanStatus = 'completed' | 'noop' | 'busy';
+export interface ArchitectureScanStats {
+    scan_duration_ms: number;
+    components_found: number;
+    connections_found: number;
+    warnings_count: number;
+    files_scanned: number;
+    files_changed: number;
+    prompts_found?: number;
+}
+/**
+ * Records that a scan ran with reduced analysis because the environment
+ * restricted a capability the scan needs. Absent means the scan was complete.
+ */
+export interface ScanDegradation {
+    /** Sandbox restrictions that were active, e.g. ['noChildProcess']. */
+    restrictions: string[];
+    /** Capabilities switched off as a result, e.g. ['scip']. */
+    disabled_capabilities: string[];
+    /** One-sentence human explanation naming both. */
+    message: string;
+}
+/**
+ * Per-language row in a scan's coverage table. Mirrors the shape and wording
+ * of `CoverageReport`/`LanguageCoverage` in `src/architecture-index.ts` — the
+ * two are computed independently (the index is a committed, deterministic
+ * projection; this is the live scanner's own runtime report) but must never
+ * disagree about what "analyzed" means for a given language.
+ */
+export interface LanguageCoverage {
+    language: string;
+    files: number;
+    /** True when a registered scanner consumes this language's files. */
+    analyzed: boolean;
+    components: number;
+    internal_edges: number;
+}
+/**
+ * Honesty contract for a scan: which languages present in the tree were
+ * actually analyzed, and which were only counted. Absent (or `status:
+ * 'full'`) means every language present in the tree was analyzed and
+ * produced at least one internal edge — nothing here means "not measured".
+ */
+export interface ScanCoverage {
+    status: 'full' | 'partial' | 'none';
+    languages: LanguageCoverage[];
+    /** One sentence per gap, each naming the language and the file count. */
+    blind_spots: string[];
+}
+/**
+ * Fields preserved across every top-level scan outcome, including contention.
+ * Optional report types stay generic so this shared module does not depend on
+ * scanner implementations that already consume `types.ts`.
+ */
+export interface ArchitectureScanPayload<TPromptScan = unknown, TFieldUsageReport = unknown, TTypeSpecReport = unknown> {
+    components: ArchitectureComponent[];
+    connections: ArchitectureConnection[];
+    warnings: ScanWarning[];
+    fileChanges?: FileChangeResult;
+    promptScan?: TPromptScan;
+    fieldUsageReport?: TFieldUsageReport;
+    typeSpecReport?: TTypeSpecReport;
+    timelineEntry?: TimelineEntry;
+    gitInfo?: GitInfo;
+    stats: ArchitectureScanStats;
+    degraded?: ScanDegradation;
+    /** Present only when `coverage.status !== 'full'` — see `ScanCoverage`. */
+    coverage?: ScanCoverage;
+}
+/**
+ * Discriminated result for a full, incremental, or no-op architecture scan.
+ * A busy lease is retryable data rather than an empty successful scan.
+ */
+export type ArchitectureScanOutcome<TPromptScan = unknown, TFieldUsageReport = unknown, TTypeSpecReport = unknown> = (ArchitectureScanPayload<TPromptScan, TFieldUsageReport, TTypeSpecReport> & {
+    status: 'completed' | 'noop';
+    retryable?: false;
+    message?: never;
+}) | (ArchitectureScanPayload<TPromptScan, TFieldUsageReport, TTypeSpecReport> & {
+    status: 'busy';
+    retryable: true;
+    message: string;
+});
 export interface ScanWarning {
-    type: 'missing_file' | 'parse_error' | 'low_confidence' | 'deprecated';
+    type: 'missing_file' | 'parse_error' | 'low_confidence' | 'deprecated' | 'unresolved_link';
     message: string;
     file?: string;
     line?: number;
@@ -242,11 +617,18 @@ export interface DetectionPattern {
     connection_type: ConnectionType;
     extract_target: (match: RegExpMatchArray) => string | null;
 }
+export interface GitInfo {
+    branch: string;
+    commit: string;
+    commitFull?: string;
+}
+export type ImpactSeverity = 'critical' | 'high' | 'medium' | 'low';
 /**
  * Impact analysis result
  */
 export interface ImpactAnalysis {
     component: ArchitectureComponent;
+    severity: ImpactSeverity;
     affected: AffectedComponent[];
     total_files_affected: number;
     summary: string;
@@ -272,12 +654,42 @@ export interface NavGatorConfig {
     scanDepth: 'shallow' | 'deep';
     defaultConfidenceThreshold: number;
     maxResultsPerQuery: number;
+    sandbox?: boolean;
+    /**
+     * When true, scan writes one JSON file per component and per connection
+     * under `<storage>/components/` and `<storage>/connections/`. Default is
+     * `false` — canonical records remain in `components.full.jsonl` and
+     * `connections.full.jsonl`; graph/index/compact files are derived views.
+     * Per-entity files duplicate substantial data on large projects.
+     *
+     * Override via env: `NAVGATOR_PER_ENTITY_FILES=true` or CLI:
+     * `navgator scan --per-entity-files`.
+     *
+     * When `false` (default), the scanner also performs an idempotent migration
+     * that deletes the contents of `components/` and `connections/` on each
+     * scan. It NEVER deletes the consolidated files.
+     */
+    perEntityFiles?: boolean;
 }
 /**
  * Generate a component ID
  * Format: COMP_type_name_random
  */
 export declare function generateComponentId(type: ComponentType, name: string): string;
+/**
+ * Generate a stable, deterministic component identifier.
+ * Format: STABLE_<type>_<slug>
+ *
+ * Same (type, name) → same stable_id across scans. This is the cross-scan
+ * join key — distinct from `component_id` which carries a random suffix
+ * for legacy backward compatibility.
+ *
+ * NOTE: collisions on (type, name) are intentional — they represent the
+ * same logical component re-detected. Callers needing path-uniqueness
+ * (e.g., two `prompt`-type components in different files) should pass a
+ * canonical_path as the second argument when available.
+ */
+export declare function generateStableId(type: ComponentType, name: string, canonicalPath?: string): string;
 /**
  * Generate a connection ID
  * Format: CONN_type_random
@@ -317,4 +729,184 @@ export declare function toCompactComponent(c: ArchitectureComponent): CompactCom
  * Convert connection to compact form
  */
 export declare function toCompactConnection(c: ArchitectureConnection): CompactConnection;
+export interface SnapshotComponent {
+    component_id: string;
+    name: string;
+    type: ComponentType;
+    version?: string;
+    status: ComponentStatus;
+    layer: ArchitectureLayer;
+    critical: boolean;
+}
+export interface SnapshotConnection {
+    connection_id: string;
+    from: string;
+    to: string;
+    type: ConnectionType;
+    from_name: string;
+    to_name: string;
+    file?: string;
+}
+export interface Snapshot {
+    snapshot_id: string;
+    snapshot_version: '2.0';
+    timestamp: number;
+    reason?: string;
+    git?: GitInfo;
+    components: SnapshotComponent[];
+    connections: SnapshotConnection[];
+    stats: {
+        total_components: number;
+        total_connections: number;
+    };
+}
+export type DiffSignificance = 'major' | 'minor' | 'patch';
+export type DiffTrigger = 'layer-change' | 'high-churn' | 'new-layer' | 'new-package' | 'connection-change' | 'version-bump' | 'metadata-only';
+export interface ComponentChange {
+    name: string;
+    type: ComponentType;
+    layer: ArchitectureLayer;
+    version?: string;
+}
+export interface ComponentModification {
+    name: string;
+    type: ComponentType;
+    changes: string[];
+}
+export interface ConnectionChange {
+    from_name: string;
+    to_name: string;
+    type: ConnectionType;
+    file?: string;
+}
+export interface DiffResult {
+    components: {
+        added: ComponentChange[];
+        removed: ComponentChange[];
+        modified: ComponentModification[];
+    };
+    connections: {
+        added: ConnectionChange[];
+        removed: ConnectionChange[];
+    };
+    stats: {
+        total_changes: number;
+        components_before: number;
+        components_after: number;
+        connections_before: number;
+        connections_after: number;
+    };
+}
+export interface TimelineEntry {
+    id: string;
+    timestamp: number;
+    significance: DiffSignificance;
+    triggers: DiffTrigger[];
+    diff: DiffResult;
+    snapshot_id?: string;
+    git?: GitInfo;
+    /**
+     * Run 1 — D2: which scan mode produced this entry. 'incremental→full'
+     * is the special promote case (Run 1.6 #3 / Run 1.7 — Problem A).
+     * Optional for backward compat with timeline entries written before
+     * mode tracking shipped.
+     */
+    scan_type?: ScanType;
+    /**
+     * Run 1.6 — item #3: number of source files actually walked by the
+     * scanners. For 'incremental' this is the walk-set size (changed +
+     * reverse-deps). For 'full' (or recursive-re-entry promote per Run 1.7
+     * Problem A) this is the full source-file count. Lets agents detect
+     * a silent integrity-promote vs a true full scan by comparing
+     * scan_type and files_scanned.
+     */
+    files_scanned?: number;
+    /**
+     * Run 2 — D4: audit report from this scan's self-measurement pass.
+     * Absent when `--no-audit` was used or audit was internally skipped
+     * (e.g., empty population). Audit failures NEVER cause the scan itself
+     * to fail; only EWMA drift triggers the next scan to auto-promote.
+     */
+    audit?: AuditReport;
+}
+export interface Timeline {
+    version: '1.0';
+    project_path: string;
+    entries: TimelineEntry[];
+}
+/**
+ * Stable envelope format for machine consumers (Codex, agents, CI)
+ */
+export interface AgentEnvelope<T> {
+    schema_version: string;
+    command: string;
+    timestamp: number;
+    data: T;
+}
+/**
+ * Executive summary for agent orientation
+ */
+export interface ExecutiveSummary {
+    project_path: string;
+    timestamp: number;
+    git?: GitInfo;
+    risks: SummaryRisk[];
+    blockers: SummaryBlocker[];
+    next_actions: SummaryAction[];
+    stats: {
+        total_components: number;
+        total_connections: number;
+        outdated_count: number;
+        vulnerable_count: number;
+    };
+    components: CompactComponent[];
+    connections: CompactConnection[];
+    rule_health: SummaryRuleHealth;
+    truncation: {
+        risks: AgentCollectionWindow;
+        blockers: AgentCollectionWindow;
+        next_actions: AgentCollectionWindow;
+        components: AgentCollectionWindow;
+        connections: AgentCollectionWindow;
+    };
+}
+/** Deterministic collection accounting for bounded machine-facing payloads. */
+export interface AgentCollectionWindow {
+    total: number;
+    returned: number;
+    truncated: boolean;
+    limit: number;
+}
+export interface SummaryRuleViolation {
+    rule_id: string;
+    severity: 'error' | 'warning' | 'info';
+    component?: string;
+    message: string;
+    suggestion?: string;
+}
+/** Architecture-rule health is always present in executive summaries. */
+export interface SummaryRuleHealth {
+    total: number;
+    errors: number;
+    warnings: number;
+    info: number;
+    violations: SummaryRuleViolation[];
+    truncation: AgentCollectionWindow;
+}
+export interface SummaryRisk {
+    type: string;
+    severity: ImpactSeverity;
+    component?: string;
+    message: string;
+}
+export interface SummaryBlocker {
+    type: string;
+    component?: string;
+    message: string;
+}
+export interface SummaryAction {
+    action: string;
+    reason: string;
+    command?: string;
+}
 //# sourceMappingURL=types.d.ts.map