@njeybe/nativ 2.0.0

package/dist/governor/index.d.ts

@@ -0,0 +1,6 @@
+export * from './types.js';
+export * from './rules/db-rules.js';
+export * from './rules/api-rules.js';
+export * from './circuit-breaker.js';
+export * from './evaluator.js';
+export * from './store.js';

package/dist/governor/index.js

@@ -0,0 +1,6 @@
+export * from './types.js';
+export * from './rules/db-rules.js';
+export * from './rules/api-rules.js';
+export * from './circuit-breaker.js';
+export * from './evaluator.js';
+export * from './store.js';

package/dist/governor/rules/api-rules.d.ts

@@ -0,0 +1,2 @@
+import { ContractPatch, RuleEvaluationResult } from '../types.js';
+export declare function evaluateApiPatch(patch: ContractPatch, currentContracts: any): RuleEvaluationResult;

package/dist/governor/rules/api-rules.js

@@ -0,0 +1,140 @@
+export function evaluateApiPatch(patch, currentContracts) {
+    const violations = [];
+    const { operation, path, value } = patch;
+    const normalizedPath = path.trim().toLowerCase();
+    const endpoints = currentContracts?.endpoints || [];
+    // Parse path: e.g. "endpoints.user-login" or "endpoints./users.get.responses.200.body.avatar"
+    const segments = normalizedPath.split('.').filter(Boolean);
+    const endpointIdOrPath = segments[0] === 'endpoints' ? segments[1] : segments[0];
+    const existingEndpoint = endpoints.find((ep) => ep.id?.toLowerCase() === endpointIdOrPath?.toLowerCase() ||
+        ep.path?.toLowerCase() === endpointIdOrPath?.toLowerCase() ||
+        `${ep.method?.toLowerCase()} ${ep.path?.toLowerCase()}` === endpointIdOrPath?.toLowerCase());
+    // Rule 1: Path Collision & Target Checks
+    if (operation === 'ADD') {
+        const isNewEndpoint = segments.length <= 2 && (!existingEndpoint || (value?.method && value?.path));
+        if (isNewEndpoint && existingEndpoint && value?.method?.toUpperCase() === existingEndpoint.method?.toUpperCase()) {
+            violations.push(`PATH_COLLISION: Endpoint '${existingEndpoint.method} ${existingEndpoint.path}' already exists. Use ALTER.`);
+        }
+    }
+    else if (operation === 'ALTER' || operation === 'DROP') {
+        if (!existingEndpoint && segments[0] === 'endpoints' && segments.length <= 2) {
+            violations.push(`TARGET_NOT_FOUND: Cannot ${operation.toLowerCase()} non-existent endpoint '${endpointIdOrPath}'.`);
+        }
+    }
+    if (violations.length > 0) {
+        return {
+            approved: false,
+            blastRadius: 'HIGH_DESTRUCTIVE',
+            ruleId: 'API_COLLISION_OR_TARGET_MISMATCH',
+            message: violations[0],
+            violations,
+        };
+    }
+    // Rule 2: DROP operations
+    if (operation === 'DROP') {
+        const isDroppingEndpoint = segments.length <= 2;
+        const msg = isDroppingEndpoint
+            ? `CANNOT_DROP_ENDPOINT: Dropping endpoint '${existingEndpoint?.method || ''} ${existingEndpoint?.path || endpointIdOrPath}' causes immediate 404 client breakage.`
+            : `CANNOT_DROP_RESPONSE_FIELD: Dropping field on '${path}' causes client runtime deserialization failures.`;
+        violations.push(msg);
+        return {
+            approved: false,
+            blastRadius: 'HIGH_DESTRUCTIVE',
+            ruleId: 'API_DROP_FORBIDDEN',
+            message: msg,
+            violations,
+        };
+    }
+    // Rule 3: RENAME operations
+    if (operation === 'RENAME') {
+        const msg = `CANNOT_RENAME_API_ROUTE: Renaming route/path '${endpointIdOrPath}' breaks consumer integration.`;
+        violations.push(msg);
+        return {
+            approved: false,
+            blastRadius: 'HIGH_DESTRUCTIVE',
+            ruleId: 'API_RENAME_FORBIDDEN',
+            message: msg,
+            violations,
+        };
+    }
+    // Rule 4: ALTER operations
+    if (operation === 'ALTER') {
+        // Auth policy mutation (unauthorized client break)
+        if (segments.includes('auth') && existingEndpoint) {
+            if (existingEndpoint.auth === false && (value === true || value?.auth === true)) {
+                violations.push(`CANNOT_RESTRICT_AUTH: Changing endpoint from public to authenticated breaks unauthenticated consumers.`);
+            }
+        }
+        // Changing HTTP method
+        if (segments.includes('method') && existingEndpoint && value && value.toUpperCase() !== existingEndpoint.method?.toUpperCase()) {
+            violations.push(`CANNOT_ALTER_HTTP_METHOD: Changing HTTP method from ${existingEndpoint.method} to ${value} breaks client calls.`);
+        }
+        if (violations.length > 0) {
+            return {
+                approved: false,
+                blastRadius: 'HIGH_DESTRUCTIVE',
+                ruleId: 'API_ALTER_DESTRUCTIVE',
+                message: violations[0],
+                violations,
+            };
+        }
+    }
+    // Rule 5: ADD operations
+    if (operation === 'ADD') {
+        // Adding a brand new endpoint
+        const isNewEndpoint = (segments.length <= 2 && !existingEndpoint) || (value?.path && value?.method);
+        if (isNewEndpoint) {
+            return {
+                approved: true,
+                blastRadius: 'LOW_ADDITIVE',
+                ruleId: 'API_ADD_ENDPOINT_APPROVED',
+                message: `Approved: Adding new endpoint '${value?.method || 'GET'} ${value?.path || endpointIdOrPath}' is backward-compatible.`,
+                violations: [],
+            };
+        }
+        // Adding request parameter/field
+        const isRequestMutation = segments.includes('request') || segments.includes('queryparams') || segments.includes('headers') || segments.includes('body');
+        if (isRequestMutation) {
+            // Check if required
+            const isRequired = value?.required === true ||
+                (typeof value === 'string' && value.toLowerCase().includes('required')) ||
+                (value?.nullable === false && value?.default === undefined);
+            if (isRequired) {
+                const msg = `CANNOT_ADD_REQUIRED_REQUEST_FIELD: Adding a required parameter or field to '${path}' causes existing client requests to fail with 400 Bad Request.`;
+                violations.push(msg);
+                return {
+                    approved: false,
+                    blastRadius: 'HIGH_DESTRUCTIVE',
+                    ruleId: 'API_ADD_REQUIRED_FORBIDDEN',
+                    message: msg,
+                    violations,
+                };
+            }
+            return {
+                approved: true,
+                blastRadius: 'LOW_ADDITIVE',
+                ruleId: 'API_ADD_OPTIONAL_REQUEST_FIELD_APPROVED',
+                message: `Approved: Adding optional request field to '${path}'.`,
+                violations: [],
+            };
+        }
+        // Adding response field or response status code (Postel's Law)
+        const isResponseMutation = segments.includes('responses') || segments.includes('response') || segments.includes('body');
+        if (isResponseMutation) {
+            return {
+                approved: true,
+                blastRadius: 'LOW_ADDITIVE',
+                ruleId: 'API_ADD_RESPONSE_FIELD_APPROVED',
+                message: `Approved: Adding response property or status code to '${path}' (conforms to Postel's Law).`,
+                violations: [],
+            };
+        }
+    }
+    return {
+        approved: true,
+        blastRadius: 'LOW_ADDITIVE',
+        ruleId: 'API_DEFAULT_ADDITIVE',
+        message: `API operation '${operation}' on '${path}' approved as safe.`,
+        violations: [],
+    };
+}

package/dist/governor/rules/db-rules.d.ts

@@ -0,0 +1,2 @@
+import { ContractPatch, RuleEvaluationResult } from '../types.js';
+export declare function evaluateDbPatch(patch: ContractPatch, currentSchema: any): RuleEvaluationResult;

package/dist/governor/rules/db-rules.js

@@ -0,0 +1,180 @@
+export function evaluateDbPatch(patch, currentSchema) {
+    const violations = [];
+    const { operation, path, value } = patch;
+    const normalizedPath = path.trim().toLowerCase();
+    // Helper: Find table by name
+    const tables = currentSchema?.tables || [];
+    // Parse path: e.g. "tables.users.columns.bio" or "users.columns.bio" or "users.columns"
+    const segments = normalizedPath.split('.').filter(Boolean);
+    const tableName = segments[0] === 'tables' ? segments[1] : segments[0];
+    const targetType = segments.includes('columns') ? 'column' : (segments.includes('indexes') ? 'index' : (segments.includes('foreignkeys') ? 'foreignKey' : 'table'));
+    const propertyName = segments.length > 2 ? segments[segments.length - 1] : undefined;
+    const existingTable = tables.find((t) => t.name?.toLowerCase() === tableName?.toLowerCase());
+    const existingColumn = existingTable?.columns?.find((c) => c.name?.toLowerCase() === propertyName?.toLowerCase());
+    // Rule 1: Path Collision & Existence Checks
+    if (operation === 'ADD') {
+        if (targetType === 'table' && existingTable) {
+            violations.push(`PATH_COLLISION: Table '${tableName}' already exists in .ai/db_schema.json. Use ALTER.`);
+        }
+        else if (targetType === 'column' && existingColumn) {
+            violations.push(`PATH_COLLISION: Column '${propertyName}' already exists on table '${tableName}'. Use ALTER.`);
+        }
+    }
+    else if (operation === 'ALTER' || operation === 'DROP') {
+        if (targetType === 'table' && !existingTable) {
+            violations.push(`TARGET_NOT_FOUND: Cannot ${operation.toLowerCase()} non-existent table '${tableName}'.`);
+        }
+        else if (targetType === 'column' && !existingColumn) {
+            violations.push(`TARGET_NOT_FOUND: Cannot ${operation.toLowerCase()} non-existent column '${propertyName}' on table '${tableName}'.`);
+        }
+    }
+    // If path collision or missing target detected, exit immediately with High Destructive
+    if (violations.length > 0) {
+        return {
+            approved: false,
+            blastRadius: 'HIGH_DESTRUCTIVE',
+            ruleId: 'DB_COLLISION_OR_TARGET_MISMATCH',
+            message: violations[0],
+            violations,
+        };
+    }
+    // Rule 2: DROP operations are always HIGH_DESTRUCTIVE
+    if (operation === 'DROP') {
+        const msg = targetType === 'table'
+            ? `CANNOT_DROP_TABLE: Dropping table '${tableName}' results in permanent data loss and catastrophic runtime failures.`
+            : `CANNOT_DROP_COLUMN: Dropping column '${propertyName}' on table '${tableName}' causes data loss and breaks existing queries.`;
+        violations.push(msg);
+        return {
+            approved: false,
+            blastRadius: 'HIGH_DESTRUCTIVE',
+            ruleId: 'DB_DROP_FORBIDDEN',
+            message: msg,
+            violations,
+        };
+    }
+    // Rule 3: RENAME operations are HIGH_DESTRUCTIVE
+    if (operation === 'RENAME') {
+        const msg = `CANNOT_RENAME_${targetType.toUpperCase()}: Renaming '${propertyName || tableName}' breaks existing queries and ORM mappings.`;
+        violations.push(msg);
+        return {
+            approved: false,
+            blastRadius: 'HIGH_DESTRUCTIVE',
+            ruleId: 'DB_RENAME_FORBIDDEN',
+            message: msg,
+            violations,
+        };
+    }
+    // Rule 4: ALTER operations
+    if (operation === 'ALTER') {
+        if (targetType === 'column') {
+            // Nullability tightening: nullable -> NOT NULL without default
+            if (existingColumn && existingColumn.nullable !== false && value?.nullable === false && value?.default === undefined && existingColumn.default === undefined) {
+                violations.push(`CANNOT_ENFORCE_NOT_NULL: Changing column '${propertyName}' to NOT NULL without a default value will cause runtime failures on existing rows.`);
+            }
+            // Column type change (narrowing or altering)
+            if (existingColumn && value?.type && value.type.toUpperCase() !== existingColumn.type?.toUpperCase()) {
+                violations.push(`CANNOT_MUTATE_COLUMN_TYPE: Altering column type from '${existingColumn.type}' to '${value.type}' carries data corruption or truncation risk.`);
+            }
+            if (violations.length > 0) {
+                return {
+                    approved: false,
+                    blastRadius: 'HIGH_DESTRUCTIVE',
+                    ruleId: 'DB_ALTER_DESTRUCTIVE',
+                    message: violations[0],
+                    violations,
+                };
+            }
+        }
+    }
+    // Rule 5: ADD operations
+    if (operation === 'ADD') {
+        // ADD TABLE
+        if (targetType === 'table') {
+            return {
+                approved: true,
+                blastRadius: 'LOW_ADDITIVE',
+                ruleId: 'DB_ADD_TABLE_APPROVED',
+                message: `Approved: Creating new table '${value?.name || tableName}' is backward-compatible.`,
+                violations: [],
+            };
+        }
+        // ADD COLUMN
+        if (targetType === 'column') {
+            const isNullable = value?.nullable !== false;
+            const hasDefault = value?.default !== undefined && value?.default !== null;
+            if (!isNullable && !hasDefault) {
+                const msg = `CANNOT_ADD_REQUIRED_COLUMN_WITHOUT_DEFAULT: Column '${value?.name || propertyName}' cannot be NOT NULL without a default value.`;
+                violations.push(msg);
+                return {
+                    approved: false,
+                    blastRadius: 'HIGH_DESTRUCTIVE',
+                    ruleId: 'DB_ADD_NOT_NULL_FORBIDDEN',
+                    message: msg,
+                    violations,
+                };
+            }
+            return {
+                approved: true,
+                blastRadius: 'LOW_ADDITIVE',
+                ruleId: 'DB_ADD_COLUMN_APPROVED',
+                message: `Approved: Adding additive column '${value?.name || propertyName}' to table '${tableName}'.`,
+                violations: [],
+            };
+        }
+        // ADD FOREIGN KEY (Referential integrity DAG check)
+        if (targetType === 'foreignKey') {
+            const targetTable = value?.targetTable || value?.referenceTable;
+            const targetCol = value?.targetColumn || value?.referenceColumn;
+            const refTableExists = tables.some((t) => t.name?.toLowerCase() === targetTable?.toLowerCase());
+            if (!refTableExists) {
+                const msg = `ORPHANED_FOREIGN_KEY: Target table '${targetTable}' does not exist in .ai/db_schema.json.`;
+                violations.push(msg);
+                return {
+                    approved: false,
+                    blastRadius: 'HIGH_DESTRUCTIVE',
+                    ruleId: 'DB_ORPHANED_FK_FORBIDDEN',
+                    message: msg,
+                    violations,
+                };
+            }
+            // Check circular dependency: does targetTable have an existing FK back to this tableName?
+            const targetTableObj = tables.find((t) => t.name?.toLowerCase() === targetTable?.toLowerCase());
+            const hasCircularFk = targetTableObj?.foreignKeys?.some((fk) => (fk.targetTable?.toLowerCase() === tableName?.toLowerCase() || fk.referenceTable?.toLowerCase() === tableName?.toLowerCase()));
+            if (hasCircularFk && value?.nullable === false) {
+                const msg = `CIRCULAR_DEPENDENCY: Circular non-nullable foreign key between '${tableName}' and '${targetTable}'.`;
+                violations.push(msg);
+                return {
+                    approved: false,
+                    blastRadius: 'HIGH_DESTRUCTIVE',
+                    ruleId: 'DB_CIRCULAR_FK_FORBIDDEN',
+                    message: msg,
+                    violations,
+                };
+            }
+            return {
+                approved: true,
+                blastRadius: 'LOW_ADDITIVE',
+                ruleId: 'DB_ADD_FOREIGN_KEY_APPROVED',
+                message: `Approved: Foreign key on '${tableName}' referencing '${targetTable}' verified.`,
+                violations: [],
+            };
+        }
+        // ADD INDEX
+        if (targetType === 'index') {
+            return {
+                approved: true,
+                blastRadius: 'LOW_ADDITIVE',
+                ruleId: 'DB_ADD_INDEX_APPROVED',
+                message: `Approved: Adding index to table '${tableName}'.`,
+                violations: [],
+            };
+        }
+    }
+    return {
+        approved: true,
+        blastRadius: 'LOW_ADDITIVE',
+        ruleId: 'DB_DEFAULT_ADDITIVE',
+        message: `Operation '${operation}' on '${path}' approved as safe.`,
+        violations: [],
+    };
+}

package/dist/governor/store.d.ts

@@ -0,0 +1,33 @@
+import type { EscalationFile, EscalationRecord } from '../scanner/types.js';
+/**
+ * Shared on-disk state of the governor: `.ai/.governor_ledger.json` and `.ai/escalation.json`.
+ * Parallel agents in separate worktrees share one `.ai/`, so every read-modify-write here holds
+ * a file lock and replaces the file atomically.
+ */
+export interface LedgerEntry {
+    consecutiveFailures: number;
+    lastFailureTime: string;
+    lastRuleId?: string;
+    lastViolation?: string;
+    patchCount: number;
+    /** Commit recorded at `nativ task start`; the test-integrity guard diffs against it. */
+    baselineRef?: string;
+    baselineRecordedAt?: string;
+}
+export type TaskFailureLedger = Record<string, LedgerEntry>;
+export declare function ledgerPath(targetDir: string): string;
+export declare function escalationPath(targetDir: string): string;
+export declare function loadLedger(targetDir: string): TaskFailureLedger;
+/** Locked read-modify-write of the ledger; the mutator's return value is passed through. */
+export declare function mutateLedger<T>(targetDir: string, mutator: (ledger: TaskFailureLedger) => T): T;
+export declare function loadEscalationFile(targetDir: string, projectName: string): EscalationFile;
+export type EscalationIdStyle = 'sequential' | 'unique';
+/**
+ * Appends an escalation under the file lock. The id is assigned inside the lock, so concurrent
+ * writers can neither collide nor overwrite each other's records. Returns the id.
+ */
+export declare function appendEscalation(targetDir: string, build: (id: string) => EscalationRecord, options: {
+    style: EscalationIdStyle;
+    position?: 'first' | 'last';
+    projectName?: string;
+}): string;

package/dist/governor/store.js

@@ -0,0 +1,84 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { withFileLockSync, writeJsonAtomicSync } from '../core/lock-manager.js';
+export function ledgerPath(targetDir) {
+    return path.join(targetDir, '.ai', '.governor_ledger.json');
+}
+export function escalationPath(targetDir) {
+    return path.join(targetDir, '.ai', 'escalation.json');
+}
+function readJson(file, fallback) {
+    try {
+        const raw = fs.readFileSync(file, 'utf8');
+        // The lock helpers create an empty placeholder before the first write.
+        return raw.trim() ? JSON.parse(raw) : fallback;
+    }
+    catch {
+        return fallback;
+    }
+}
+export function loadLedger(targetDir) {
+    return readJson(ledgerPath(targetDir), {});
+}
+/** Locked read-modify-write of the ledger; the mutator's return value is passed through. */
+export function mutateLedger(targetDir, mutator) {
+    const file = ledgerPath(targetDir);
+    return withFileLockSync(file, () => {
+        const ledger = readJson(file, {});
+        const result = mutator(ledger);
+        writeJsonAtomicSync(file, ledger);
+        return result;
+    });
+}
+export function loadEscalationFile(targetDir, projectName) {
+    const empty = {
+        $schema: 'http://json-schema.org/draft-07/schema#',
+        version: '1.0.0',
+        projectName,
+        lastUpdated: new Date().toISOString(),
+        escalations: [],
+    };
+    const file = readJson(escalationPath(targetDir), empty);
+    if (!Array.isArray(file.escalations))
+        file.escalations = [];
+    return file;
+}
+/**
+ * Picks an id no existing record uses. `sequential` keeps the human-friendly `esc-NN` of
+ * `nativ task escalate`; `unique` (circuit-breaker trips) adds random bits to a timestamp so two
+ * trips in the same millisecond still get different ids.
+ */
+function nextEscalationId(existing, style) {
+    if (style === 'sequential') {
+        const numbers = [...existing].map((id) => /^esc-(\d+)$/.exec(id)?.[1]).filter(Boolean).map(Number);
+        let n = numbers.length ? Math.max(...numbers) + 1 : 1;
+        while (existing.has(`esc-${String(n).padStart(2, '0')}`))
+            n++;
+        return `esc-${String(n).padStart(2, '0')}`;
+    }
+    for (;;) {
+        const id = `esc-${Date.now().toString(36)}-${crypto.randomBytes(3).toString('hex')}`;
+        if (!existing.has(id))
+            return id;
+    }
+}
+/**
+ * Appends an escalation under the file lock. The id is assigned inside the lock, so concurrent
+ * writers can neither collide nor overwrite each other's records. Returns the id.
+ */
+export function appendEscalation(targetDir, build, options) {
+    const file = escalationPath(targetDir);
+    return withFileLockSync(file, () => {
+        const data = loadEscalationFile(targetDir, options.projectName ?? path.basename(targetDir));
+        const id = nextEscalationId(new Set(data.escalations.map((e) => e?.id).filter(Boolean)), options.style);
+        const record = build(id);
+        if (options.position === 'last')
+            data.escalations.push(record);
+        else
+            data.escalations.unshift(record);
+        data.lastUpdated = new Date().toISOString();
+        writeJsonAtomicSync(file, data);
+        return id;
+    });
+}

package/dist/governor/types.d.ts

@@ -0,0 +1,64 @@
+export type BlastRadius = 'LOW_ADDITIVE' | 'HIGH_DESTRUCTIVE';
+export type PatchOperation = 'ADD' | 'ALTER' | 'DROP' | 'RENAME';
+export type ContractTarget = 'db_schema' | 'api_contracts';
+export interface ContractPatch {
+    taskId: string;
+    target: ContractTarget;
+    operation: PatchOperation;
+    path: string;
+    value?: any;
+    before?: any;
+    reason: string;
+    baseHash?: string;
+}
+export interface AuditLogEntry {
+    timestamp: string;
+    taskId: string;
+    target: ContractTarget;
+    operation: PatchOperation;
+    path: string;
+    blastRadius: BlastRadius;
+    ruleId: string;
+    reason: string;
+    applied: boolean;
+}
+export interface CircuitBreakerState {
+    active: boolean;
+    consecutiveFailures: number;
+    maxThreshold: number;
+    tripped: boolean;
+}
+export interface EscalationDiagnosticBundle {
+    escalationId: string;
+    taskId: string;
+    circuitBreakerTripped: boolean;
+    consecutiveFailures: number;
+    intent: string;
+    invariantCollision: string;
+    proposedPatch: {
+        target: ContractTarget;
+        operation: PatchOperation;
+        path: string;
+        value?: any;
+        reason: string;
+    };
+    recommendedActions: string[];
+}
+export interface GovernorVerdict {
+    approved: boolean;
+    blastRadius: BlastRadius;
+    ruleId: string;
+    message: string;
+    violations: string[];
+    patchApplied: boolean;
+    circuitBreaker: CircuitBreakerState;
+    auditEntry?: AuditLogEntry;
+    diagnosticBundle?: EscalationDiagnosticBundle;
+}
+export interface RuleEvaluationResult {
+    approved: boolean;
+    blastRadius: BlastRadius;
+    ruleId: string;
+    message: string;
+    violations: string[];
+}

package/dist/governor/types.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare function createProgram(): Command;
+export declare function run(): Promise<void>;