@njeybe/nativ 2.0.0

package/dist/db/types.d.ts

@@ -0,0 +1,217 @@
+/**
+ * Database telemetry & schema types.
+ * Shapes conform to .ai/api_contracts.json (status/schema/diff/connect/export-contract)
+ * and the table model in .ai/db_schema.json.
+ */
+export type SqlEngine = 'postgresql' | 'mysql' | 'sqlite';
+export type NoSqlEngine = 'mongodb' | 'firestore';
+export type DatabaseEngine = SqlEngine | NoSqlEngine;
+export declare const NOSQL_ENGINES: readonly NoSqlEngine[];
+export declare function isNoSqlEngine(engine: string): engine is NoSqlEngine;
+/** SQL engines expose tables; document stores expose collections. */
+export type EntityType = 'table' | 'collection';
+export type DatabaseEnv = 'dev' | 'prod';
+/** Per-environment telemetry returned by GET /api/status. */
+export interface DatabaseStatus {
+    connected: boolean;
+    engine: DatabaseEngine;
+    database: string;
+    maskedUrl: string;
+    pingMs: number;
+    /** Number of tables or collections (contract field). */
+    entityCount?: number;
+    entityType?: EntityType;
+    /** @deprecated Legacy alias of entityCount, kept for existing CLI/studio consumers. */
+    tableCount: number;
+    error: string | null;
+    sourceKey?: string;
+    detectedFromExample?: boolean;
+    exampleFile?: string | null;
+    suggestion?: string | null;
+    /** True when the URL was assembled from fragmented DB_HOST/DB_DATABASE-style keys. */
+    synthesized?: boolean;
+}
+/** Engines that can be assembled from fragmented host/port/user/password/database keys. */
+export type ComponentEngine = Extract<SqlEngine, 'mysql' | 'postgresql'>;
+/**
+ * Discrete connection parameters (POST /api/connect `components`, XAMPP/Laravel-style .env keys).
+ * Contains the raw password: never log, print, or serialize this object.
+ */
+export interface ConnectionComponents {
+    engine: ComponentEngine;
+    host: string;
+    port?: number;
+    user?: string;
+    password?: string;
+    database?: string;
+}
+/** Display-safe description of a fragmented config (GET /api/env-info `fragmentedConfig`). No secrets. */
+export interface FragmentedConfig {
+    env: DatabaseEnv;
+    engine: ComponentEngine;
+    host: string;
+    port: number;
+    user: string | null;
+    database: string | null;
+    hasPassword: boolean;
+    /** Env keys the components were read from, e.g. ['DB_CONNECTION', 'DB_HOST', 'DB_DATABASE']. */
+    sourceKeys: string[];
+    maskedUrl: string;
+}
+export interface DetectedTemplateKey {
+    key: string;
+    targetEnv: DatabaseEnv;
+    engine: DatabaseEngine | null;
+    exampleValue?: string;
+    isConfiguredInEnv: boolean;
+}
+export interface TemplateDetectionResult {
+    templateFound: boolean;
+    templateFile: string | null;
+    detectedKeys: DetectedTemplateKey[];
+    missingKeys: DetectedTemplateKey[];
+    /** True when DB_HOST/DB_DATABASE-style component keys are configured and can be synthesized into a URL. */
+    fragmentedDetected?: boolean;
+    fragmentedConfig?: FragmentedConfig | null;
+}
+export interface StatusResponse {
+    dev: DatabaseStatus;
+    prod: DatabaseStatus;
+}
+/** Where a detected image field's value lives. */
+export type MediaSource = 'url' | 'gcs' | 'base64' | 'bytes';
+/**
+ * Metadata about a detected image/media field, taken from sampled documents.
+ * Raw binary never appears here: bytes/base64 fields only report MIME type, size,
+ * dimensions and a short truncated prefix. URLs have credential-like query params redacted.
+ */
+export interface MediaFieldInfo {
+    source: MediaSource;
+    mimeType: string | null;
+    sizeBytes: number | null;
+    width: number | null;
+    height: number | null;
+    /** Redacted http(s) URL or gs:// URI of one sampled value, for thumbnail preview. */
+    sampleUrl: string | null;
+    /** First few characters of a base64 value (display only, never decodable into the image). */
+    base64Head: string | null;
+}
+export interface ColumnSchema {
+    name: string;
+    /** SQL type (VARCHAR(255), UUID…) or NoSQL type (STRING, NUMBER, MAP, ARRAY, OBJECTID, DOCUMENT_ID, BYTES, IMAGE_URL…). */
+    type: string;
+    primaryKey: boolean;
+    nullable: boolean;
+    default: string | null;
+    /** True when the field holds images (URL, gs:// URI, Base64 data URI, or Bytes). */
+    isMedia?: boolean;
+    /** True when this entry is a Firestore nested subcollection rather than a document field. */
+    isSubcollection?: boolean;
+    media?: MediaFieldInfo;
+    /** NoSQL only: fraction (0–1) of sampled documents that contain this field. */
+    presence?: number;
+    /** NoSQL only: all distinct types observed across samples when a field is polymorphic. */
+    observedTypes?: string[];
+}
+export interface IndexSchema {
+    name: string;
+    columns: string[];
+    unique: boolean;
+}
+export interface ForeignKeySchema {
+    name: string;
+    column: string;
+    referencedTable: string;
+    referencedColumn: string;
+    onDelete?: string;
+}
+export interface TableSchema {
+    name: string;
+    /** 'collection' for MongoDB/Firestore; absent or 'table' for SQL engines. */
+    entityType?: EntityType;
+    description?: string;
+    /** For collections, `columns` are the document fields inferred from sampled documents. */
+    columns: ColumnSchema[];
+    indexes: IndexSchema[];
+    foreignKeys: ForeignKeySchema[];
+    /** NoSQL only: estimated number of documents in the collection. */
+    documentCount?: number;
+    /** NoSQL only: number of documents sampled (≤ 50) to infer fields. */
+    sampledDocuments?: number;
+}
+/** GET /api/schema response. */
+export interface SchemaResponse {
+    devTables: TableSchema[];
+    prodTables: TableSchema[];
+}
+/** A column present on both sides whose definition differs. */
+export interface ColumnChange {
+    name: string;
+    before: ColumnSchema;
+    after: ColumnSchema;
+    changedFields: Array<keyof Omit<ColumnSchema, 'name'>>;
+}
+export interface TableDiff {
+    name: string;
+    addedColumns: ColumnSchema[];
+    droppedColumns: ColumnSchema[];
+    alteredColumns: ColumnChange[];
+    addedIndexes: IndexSchema[];
+    droppedIndexes: IndexSchema[];
+    addedForeignKeys: ForeignKeySchema[];
+    droppedForeignKeys: ForeignKeySchema[];
+    isDestructive: boolean;
+}
+export interface SchemaDiffSummary {
+    addedTablesCount: number;
+    alteredTablesCount: number;
+    droppedTablesCount: number;
+    unchangedTablesCount: number;
+    hasDestructiveChanges: boolean;
+}
+/** GET /api/diff response. */
+export interface SchemaDiff {
+    summary: SchemaDiffSummary;
+    addedTables: TableSchema[];
+    droppedTables: TableSchema[];
+    alteredTables: TableDiff[];
+    unchangedTables: string[];
+}
+export type DiffTarget = 'prod' | 'contract';
+/** Firestore connection settings (credentials come from Application Default Credentials, never from here). */
+export interface FirestoreConfig {
+    projectId: string;
+    /** host:port of a local Firestore emulator, e.g. "localhost:8080". */
+    emulatorHost?: string;
+    /** Firestore database id for multi-database projects (defaults to "(default)"). */
+    databaseId?: string;
+}
+/** POST /api/connect */
+export interface ConnectRequest {
+    env: DatabaseEnv;
+    engine?: DatabaseEngine;
+    /** Required for SQL engines and MongoDB; optional for Firestore when firestoreConfig is given. */
+    connectionUrl?: string;
+    firestoreConfig?: FirestoreConfig;
+}
+export interface ConnectResponse {
+    success: boolean;
+    pingMs: number;
+    engine: string;
+    entityCount?: number;
+    /** @deprecated Legacy alias of entityCount. */
+    tableCount: number;
+    maskedUrl: string;
+    error: string | null;
+}
+/** POST /api/export-contract */
+export interface ExportContractRequest {
+    sourceEnv: DatabaseEnv;
+}
+export interface ExportContractResponse {
+    success: boolean;
+    filePath: string;
+    exportedEntitiesCount?: number;
+    /** @deprecated Legacy alias of exportedEntitiesCount. */
+    exportedTablesCount: number;
+}

package/dist/db/types.js

@@ -0,0 +1,9 @@
+/**
+ * Database telemetry & schema types.
+ * Shapes conform to .ai/api_contracts.json (status/schema/diff/connect/export-contract)
+ * and the table model in .ai/db_schema.json.
+ */
+export const NOSQL_ENGINES = ['mongodb', 'firestore'];
+export function isNoSqlEngine(engine) {
+    return NOSQL_ENGINES.includes(engine);
+}

package/dist/governor/circuit-breaker.d.ts

@@ -0,0 +1,100 @@
+import { BlastRadius, CircuitBreakerState, ContractPatch, EscalationDiagnosticBundle, RuleEvaluationResult } from './types.js';
+import { EscalationRecord, EscalationType } from '../scanner/types.js';
+/** A contract patch as proposed, without the task binding. */
+export type CandidatePatch = Omit<ContractPatch, 'taskId'>;
+export interface ProofCheck {
+    name: string;
+    passed: boolean;
+    detail: string;
+}
+/**
+ * Evidence that a proposal was exercised away from the live `.ai/` contracts
+ * before a human is asked to approve it.
+ */
+export interface VerificationProof {
+    isolated: true;
+    method: 'sandbox_governor_replay' | 'baseline_blob_check';
+    passed: boolean;
+    checks: ProofCheck[];
+    /** Hash of the live contract the candidate was replayed against. */
+    baseContractHash?: string | null;
+    /** Hash of the sandbox contract after the candidate was applied. */
+    candidateContractHash?: string | null;
+    verdict?: {
+        approved: boolean;
+        blastRadius: BlastRadius;
+        ruleId: string;
+        message: string;
+    };
+    verifiedAt: string;
+    durationMs: number;
+}
+export type SelfHealingStrategy = 'relax_to_nullable' | 'relax_to_optional' | 'deprecate_instead_of_drop' | 'expand_contract_rename' | 'shadow_column_for_type_change' | 'alter_existing_instead_of_add' | 'add_missing_target' | 'rebase_on_current_contract' | 'budget_override' | 'restore_test_suite';
+interface ProposalBase {
+    proposalId: string;
+    strategy: SelfHealingStrategy;
+    rationale: string;
+    /** Proposals are never applied automatically; Tier 1 or the operator approves them. */
+    requiresHumanApproval: true;
+    candidatesEvaluated: number;
+    verificationProof: VerificationProof;
+    generatedAt: string;
+}
+export interface ContractPatchProposal extends ProposalBase {
+    kind: 'contract_patch';
+    candidate: CandidatePatch;
+    original: CandidatePatch;
+}
+export interface TestRestorationProposal extends ProposalBase {
+    kind: 'restore_tests';
+    baselineRef: string;
+    files: string[];
+    commands: string[];
+}
+export type SelfHealingProposal = ContractPatchProposal | TestRestorationProposal;
+/** `.ai/escalation.json` record carrying the optional self-healing proposal. */
+export interface SelfHealingEscalationRecord extends EscalationRecord {
+    proposedPatch?: SelfHealingProposal;
+}
+export type ProposalFactory = () => SelfHealingProposal | null;
+export interface GuardViolationContext {
+    escalationType: EscalationType;
+    /** Files or contracts the violation touches, listed on the escalation record. */
+    affected: string[];
+    intent: string;
+}
+export declare class CircuitBreaker {
+    static getStatus(targetDir: string, taskId: string): CircuitBreakerState;
+    static getPatchCount(targetDir: string, taskId: string): number;
+    static incrementPatchCount(targetDir: string, taskId: string): number;
+    static recordSuccess(targetDir: string, taskId: string): void;
+    static reset(targetDir: string, taskId: string): void;
+    /**
+     * Pins the commit a task started from. Restarting a blocked task keeps the
+     * original baseline so deletions made before the block still count.
+     */
+    static recordBaseline(targetDir: string, taskId: string, ref: string): void;
+    static getBaseline(targetDir: string, taskId: string): string | null;
+    static clearBaseline(targetDir: string, taskId: string): void;
+    static recordFailure(targetDir: string, taskId: string, patch: ContractPatch, ruleResult: RuleEvaluationResult, proposalFactory?: ProposalFactory): {
+        state: CircuitBreakerState;
+        diagnosticBundle?: EscalationDiagnosticBundle & {
+            selfHealingProposal?: SelfHealingProposal | null;
+        };
+    };
+    /**
+     * Counts a non-contract guard violation (e.g. test integrity) toward the same
+     * 3-strike budget. On the trip the task is blocked and escalated with the
+     * factory's proposal attached.
+     */
+    static recordGuardViolation(targetDir: string, taskId: string, ruleResult: RuleEvaluationResult, context: GuardViolationContext, proposalFactory?: ProposalFactory): {
+        state: CircuitBreakerState;
+        escalationId?: string;
+        proposal?: SelfHealingProposal | null;
+    };
+    /** Atomic increment under the ledger lock: concurrent failures are all counted. */
+    private static bumpFailures;
+    private static tripAndEscalate;
+    private static blockTask;
+}
+export {};

package/dist/governor/circuit-breaker.js

@@ -0,0 +1,231 @@
+import path from 'node:path';
+import { withPlanLockSync } from '../core/lock-manager.js';
+import { recordCircuitBreakerTrip } from '../core/telemetry.js';
+import { appendEscalation, loadLedger, mutateLedger } from './store.js';
+const MAX_FAILURE_THRESHOLD = 3;
+const newEntry = () => ({ consecutiveFailures: 0, lastFailureTime: '', patchCount: 0 });
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+/** Proposal generation must never turn a trip into a crash; a failed factory means "no proposal". */
+function buildProposal(factory) {
+    if (!factory)
+        return null;
+    try {
+        return factory();
+    }
+    catch {
+        return null;
+    }
+}
+function describeProposal(proposal) {
+    const verified = proposal.verificationProof.passed ? 'verified in an isolated sandbox' : 'NOT verified';
+    return `Review self-healing proposal ${proposal.proposalId} (${proposal.strategy}, ${verified}): ${proposal.rationale}`;
+}
+/** Escalation writes are advisory: a failure to record one must not mask the verdict itself. */
+function fileEscalation(targetDir, build) {
+    try {
+        return appendEscalation(targetDir, build, { style: 'unique' });
+    }
+    catch {
+        return null;
+    }
+}
+/** Ledger writes are advisory in the same way: a locked or read-only ledger must not crash a verdict. */
+function tryMutateLedger(targetDir, mutator) {
+    try {
+        mutateLedger(targetDir, mutator);
+    }
+    catch {
+        // Non-fatal
+    }
+}
+export class CircuitBreaker {
+    static getStatus(targetDir, taskId) {
+        const ledger = loadLedger(targetDir);
+        const entry = ledger[taskId];
+        const failures = entry?.consecutiveFailures || 0;
+        return {
+            active: failures > 0,
+            consecutiveFailures: failures,
+            maxThreshold: MAX_FAILURE_THRESHOLD,
+            tripped: failures >= MAX_FAILURE_THRESHOLD,
+        };
+    }
+    static getPatchCount(targetDir, taskId) {
+        const ledger = loadLedger(targetDir);
+        return ledger[taskId]?.patchCount || 0;
+    }
+    static incrementPatchCount(targetDir, taskId) {
+        let count = 0;
+        tryMutateLedger(targetDir, (ledger) => {
+            const entry = ledger[taskId] ?? { ...newEntry(), lastFailureTime: new Date().toISOString() };
+            entry.patchCount = (entry.patchCount || 0) + 1;
+            ledger[taskId] = entry;
+            count = entry.patchCount;
+        });
+        return count;
+    }
+    static recordSuccess(targetDir, taskId) {
+        tryMutateLedger(targetDir, (ledger) => {
+            if (ledger[taskId])
+                ledger[taskId].consecutiveFailures = 0;
+        });
+    }
+    static reset(targetDir, taskId) {
+        tryMutateLedger(targetDir, (ledger) => {
+            delete ledger[taskId];
+        });
+    }
+    /**
+     * Pins the commit a task started from. Restarting a blocked task keeps the
+     * original baseline so deletions made before the block still count.
+     */
+    static recordBaseline(targetDir, taskId, ref) {
+        tryMutateLedger(targetDir, (ledger) => {
+            const entry = ledger[taskId] ?? newEntry();
+            if (entry.baselineRef)
+                return;
+            entry.baselineRef = ref;
+            entry.baselineRecordedAt = new Date().toISOString();
+            ledger[taskId] = entry;
+        });
+    }
+    static getBaseline(targetDir, taskId) {
+        return loadLedger(targetDir)[taskId]?.baselineRef ?? null;
+    }
+    static clearBaseline(targetDir, taskId) {
+        tryMutateLedger(targetDir, (ledger) => {
+            if (!ledger[taskId]?.baselineRef)
+                return;
+            delete ledger[taskId].baselineRef;
+            delete ledger[taskId].baselineRecordedAt;
+        });
+    }
+    static recordFailure(targetDir, taskId, patch, ruleResult, proposalFactory) {
+        const state = this.bumpFailures(targetDir, taskId, ruleResult);
+        // Exactly one of any number of concurrent failures sees the threshold crossed, so a trip
+        // escalates once even when parallel agents fail at the same moment.
+        if (state.consecutiveFailures === MAX_FAILURE_THRESHOLD) {
+            const diagnosticBundle = this.tripAndEscalate(targetDir, taskId, patch, ruleResult, state.consecutiveFailures, proposalFactory);
+            return { state, diagnosticBundle };
+        }
+        return { state };
+    }
+    /**
+     * Counts a non-contract guard violation (e.g. test integrity) toward the same
+     * 3-strike budget. On the trip the task is blocked and escalated with the
+     * factory's proposal attached.
+     */
+    static recordGuardViolation(targetDir, taskId, ruleResult, context, proposalFactory) {
+        const state = this.bumpFailures(targetDir, taskId, ruleResult);
+        if (state.consecutiveFailures !== MAX_FAILURE_THRESHOLD)
+            return { state };
+        const proposal = buildProposal(proposalFactory);
+        const recommendedAction = proposal
+            ? describeProposal(proposal)
+            : `Review ${context.affected.join(', ')} and decide whether the change is intended; if so, have the architect update the task and unblock ${taskId}.`;
+        const escalationId = fileEscalation(targetDir, (id) => ({
+            id,
+            taskId,
+            type: context.escalationType,
+            reportedBy: 'backend',
+            timestamp: new Date().toISOString(),
+            summary: `Circuit Breaker Tripped (${state.consecutiveFailures}/${MAX_FAILURE_THRESHOLD}): ${ruleResult.ruleId}`,
+            details: `${context.intent}: ${ruleResult.message}`,
+            affectedContracts: context.affected,
+            recommendedAction,
+            status: 'pending_review',
+            ...(proposal ? { proposedPatch: proposal } : {}),
+        }));
+        this.blockTask(targetDir, taskId, `Circuit breaker tripped by Governor: ${ruleResult.ruleId} (${escalationId ?? 'escalation not recorded'})`);
+        recordCircuitBreakerTrip(targetDir, taskId).catch(() => { });
+        return { state, escalationId: escalationId ?? undefined, proposal };
+    }
+    /** Atomic increment under the ledger lock: concurrent failures are all counted. */
+    static bumpFailures(targetDir, taskId, ruleResult) {
+        let failures = 0;
+        try {
+            failures = mutateLedger(targetDir, (ledger) => {
+                const entry = ledger[taskId] ?? newEntry();
+                entry.consecutiveFailures += 1;
+                entry.lastFailureTime = new Date().toISOString();
+                entry.lastRuleId = ruleResult.ruleId;
+                entry.lastViolation = ruleResult.message;
+                ledger[taskId] = entry;
+                return entry.consecutiveFailures;
+            });
+        }
+        catch {
+            // Unwritable ledger: report this failure alone rather than crashing the verdict.
+            failures = (loadLedger(targetDir)[taskId]?.consecutiveFailures ?? 0) + 1;
+        }
+        return {
+            active: true,
+            consecutiveFailures: failures,
+            maxThreshold: MAX_FAILURE_THRESHOLD,
+            tripped: failures >= MAX_FAILURE_THRESHOLD,
+        };
+    }
+    static tripAndEscalate(targetDir, taskId, patch, ruleResult, failures, proposalFactory) {
+        const contractFileName = patch.target === 'db_schema' ? 'db_schema.json' : 'api_contracts.json';
+        const proposal = buildProposal(proposalFactory);
+        const recommendedActions = [
+            `Review contract at .ai/${contractFileName} and either adjust schema or approve migration.`,
+            `If the operation is required, have the architect apply the change and unblock ${taskId}.`,
+            `If the operation is invalid, instruct the agent to use an alternative backward-compatible approach.`,
+        ];
+        if (proposal)
+            recommendedActions.unshift(describeProposal(proposal));
+        // 1. Write to .ai/escalation.json (the id is assigned under the file lock)
+        const escalationId = fileEscalation(targetDir, (id) => ({
+            id,
+            taskId,
+            type: patch.target === 'db_schema' ? 'schema_flaw' : 'contract_drift',
+            reportedBy: 'backend',
+            timestamp: new Date().toISOString(),
+            summary: `Circuit Breaker Tripped (${failures}/${MAX_FAILURE_THRESHOLD}): ${ruleResult.ruleId} on ${patch.path}`,
+            details: `Autonomous agent failed ${failures} times attempting ${patch.operation} on ${patch.path}: ${ruleResult.message}`,
+            affectedContracts: [`.ai/${contractFileName}`],
+            recommendedAction: recommendedActions[0],
+            status: 'pending_review',
+            ...(proposal ? { proposedPatch: proposal } : {}),
+        })) ?? 'unrecorded';
+        // 2. Mark task as blocked in .ai/master_plan.json
+        this.blockTask(targetDir, taskId, `Circuit breaker tripped by Governor: ${ruleResult.ruleId} (${escalationId})`);
+        recordCircuitBreakerTrip(targetDir, taskId).catch(() => { });
+        return {
+            escalationId,
+            taskId,
+            circuitBreakerTripped: true,
+            consecutiveFailures: failures,
+            intent: patch.reason || `Apply ${patch.operation} on ${patch.path}`,
+            invariantCollision: ruleResult.message,
+            proposedPatch: {
+                target: patch.target,
+                operation: patch.operation,
+                path: patch.path,
+                value: patch.value,
+                reason: patch.reason,
+            },
+            recommendedActions,
+            selfHealingProposal: proposal,
+        };
+    }
+    static blockTask(targetDir, taskId, note) {
+        const planPath = path.join(targetDir, '.ai', 'master_plan.json');
+        try {
+            withPlanLockSync(planPath, (plan) => {
+                for (const milestone of plan.milestones) {
+                    const task = milestone.tasks.find((t) => t.id === taskId);
+                    if (task) {
+                        task.status = 'blocked';
+                        task.notes = note;
+                        break;
+                    }
+                }
+            });
+        }
+        catch {
+            // Non-fatal
+        }
+    }
+}

package/dist/governor/evaluator.d.ts

@@ -0,0 +1,67 @@
+import { ContractPatch, GovernorVerdict, RuleEvaluationResult } from './types.js';
+import { type CandidatePatch, type ContractPatchProposal, type SelfHealingProposal, type TestRestorationProposal, type VerificationProof } from './circuit-breaker.js';
+export declare function getContractHash(filePath: string): string | null;
+/**
+ * Replays a candidate against a throwaway copy of the contract in the OS temp
+ * directory: governor rules, apply, re-parse, and proof that it changes
+ * something while the live `.ai/` file stays byte-identical.
+ */
+export declare function verifyCandidateInSandbox(targetDir: string, taskId: string, candidate: CandidatePatch): VerificationProof;
+/**
+ * Builds the first backward-compatible candidate that survives an isolated
+ * replay. Returns null when no candidate can be proven (a human decides).
+ */
+export declare function generateSelfHealingProposal(targetDir: string, patch: ContractPatch, rule: RuleEvaluationResult): ContractPatchProposal | null;
+export interface ProposalApplication {
+    applied: boolean;
+    ruleId: string;
+    message: string;
+}
+/**
+ * Applies an operator-approved proposal. Contract patches are re-checked
+ * against the live contract and refused if it moved since the proof was taken.
+ * Human-approved patches do not count against the task's patch budget.
+ */
+export declare function applySelfHealingProposal(targetDir: string, taskId: string, proposal: SelfHealingProposal): ProposalApplication;
+export type TestIntegrityRule = 'TEST_SUITE_DELETED' | 'TEST_ASSERTIONS_REMOVED' | 'TEST_CASES_REMOVED' | 'TESTS_SKIPPED' | 'TESTS_FOCUSED' | 'TEST_SCRIPT_WEAKENED';
+export interface TestIntegrityFinding {
+    rule: TestIntegrityRule;
+    /** Path relative to the project root. */
+    path: string;
+    detail: string;
+}
+export interface TestIntegrityReport extends RuleEvaluationResult {
+    /** Resolved commit the working tree was compared against; null when the check was skipped. */
+    baselineRef: string | null;
+    /** True when the baseline came from `nativ task start` rather than falling back to HEAD. */
+    baselineRecorded: boolean;
+    findings: TestIntegrityFinding[];
+    skippedReason?: string;
+}
+export interface TestSuiteMetrics {
+    assertions: number;
+    testCases: number;
+    skipped: number;
+    focused: number;
+}
+export declare function isTestFile(file: string): boolean;
+/** Heuristic, language-agnostic counts; only deltas against the baseline matter. */
+export declare function measureTestSuite(source: string): TestSuiteMetrics;
+/** Current commit of the checkout at `targetDir`, or null outside git / before the first commit. */
+export declare function resolveGitHead(targetDir: string): string | null;
+/**
+ * Enforces that a task never deletes or weakens the test suites that existed
+ * when it started: no deleted test files, no fewer assertions or cases, no new
+ * skip/only markers, and no test files dropped from package.json test scripts.
+ */
+export declare class TestIntegrityGuard {
+    static evaluate(targetDir: string, taskId: string): TestIntegrityReport;
+    /**
+     * Proposal to restore every flagged file from the baseline, with proof that
+     * each baseline blob exists and what the restored suite measures.
+     */
+    static proposeRestoration(targetDir: string, report: TestIntegrityReport): TestRestorationProposal | null;
+}
+export declare class ContractGovernor {
+    static evaluate(targetDir: string, patch: ContractPatch): GovernorVerdict;
+}