@baselineos/govern 1.0.0

package/LICENSE

@@ -0,0 +1,17 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+Copyright 2026 Baseline Protocol Foundation
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,19 @@
+# @baselineos/govern
+
+Govern layer package for Baseline.
+
+## Purpose
+
+Implements governance controls, policy checks, and trust/safety guardrails in the Baseline layer runtime.
+
+## Commands
+
+```bash
+pnpm --filter @baselineos/govern build
+pnpm --filter @baselineos/govern test
+```
+
+## Integration
+
+- Depends on: `@baselineos/protocol-core`
+- Consumed by: `@baselineos/cli`, `baselineos`

package/dist/index.d.ts

@@ -0,0 +1,619 @@
+/**
+ * Structured error types for @baselineos/govern
+ *
+ * Machine-parseable error codes with typed error hierarchy.
+ * All errors extend BaselineError for consistent handling.
+ */
+type GovernErrorCode = 'POLICY_NOT_FOUND' | 'POLICY_NOT_APPROVED' | 'POLICY_ALREADY_ENFORCED' | 'POLICY_ENFORCEMENT_BLOCKED' | 'APPROVAL_NOT_FOUND' | 'APPROVAL_ALREADY_RESOLVED' | 'APPROVAL_REQUIRED' | 'RISK_NOT_FOUND' | 'PERMISSION_NOT_FOUND' | 'COMPLIANCE_VIOLATION' | 'COMPLIANCE_STANDARD_UNKNOWN' | 'TEMPLATE_NOT_FOUND' | 'TEMPLATE_VALIDATION_FAILED' | 'VALIDATION_FAILED' | 'INTERNAL_ERROR';
+declare class BaselineError extends Error {
+    readonly code: GovernErrorCode;
+    readonly details: Record<string, unknown>;
+    readonly timestamp: Date;
+    constructor(code: GovernErrorCode, message: string, details?: Record<string, unknown>);
+    toJSON(): Record<string, unknown>;
+}
+declare class GovernError extends BaselineError {
+    constructor(code: GovernErrorCode, message: string, details?: Record<string, unknown>);
+}
+declare class ComplianceError extends BaselineError {
+    readonly standard: string;
+    constructor(standard: string, message: string, details?: Record<string, unknown>);
+}
+declare class ValidationError extends BaselineError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+declare class TemplateError extends BaselineError {
+    readonly templateName: string;
+    constructor(templateName: string, message: string, details?: Record<string, unknown>);
+}
+declare function isBaselineError(error: unknown): error is BaselineError;
+declare function toErrorResult(error: unknown): {
+    code: GovernErrorCode;
+    message: string;
+};
+
+/**
+ * Baseline Govern System
+ *
+ * Enterprise governance layer of the Baseline Protocol providing
+ * policy, risk, permission, cost, and compliance governance.
+ *
+ * @license Apache-2.0
+ */
+
+type PolicySeverity = 'low' | 'medium' | 'high' | 'critical';
+type PolicyEnforcement = 'advisory' | 'warn' | 'block';
+interface PolicyRuleCondition {
+    field: string;
+    equals?: unknown;
+    notEquals?: unknown;
+    includes?: unknown;
+    exists?: boolean;
+}
+interface PolicyRule {
+    id: string;
+    name: string;
+    description?: string;
+    severity: PolicySeverity;
+    enforcement: PolicyEnforcement;
+    condition: PolicyRuleCondition;
+    message?: string;
+}
+interface Policy {
+    id: string;
+    name: string;
+    content: string;
+    created: Date;
+    version: string;
+    status: 'draft' | 'approved' | 'enforced' | 'deprecated';
+    approved?: Date;
+    approver?: string;
+    severity: PolicySeverity;
+    enforcement: PolicyEnforcement;
+    rules: PolicyRule[];
+    requireApproval: boolean;
+    options: Record<string, unknown>;
+}
+interface PolicyViolation {
+    ruleId: string;
+    ruleName: string;
+    severity: PolicySeverity;
+    enforcement: PolicyEnforcement;
+    message: string;
+}
+interface PolicyEvaluation {
+    id: string;
+    policyId: string;
+    context: unknown;
+    passed: boolean;
+    score: number;
+    violations: PolicyViolation[];
+    enforcementAction: 'allow' | 'warn' | 'block' | 'approval_required';
+    requiresApproval: boolean;
+    evaluatedAt: Date;
+}
+interface ApprovalRequest {
+    id: string;
+    policyId: string;
+    resourceId: string;
+    requestedBy: string;
+    status: 'pending' | 'approved' | 'rejected';
+    requiredApprovers: string[];
+    approvals: Array<{
+        approver: string;
+        at: Date;
+        note?: string;
+    }>;
+    rejections: Array<{
+        approver: string;
+        at: Date;
+        note?: string;
+    }>;
+    createdAt: Date;
+    updatedAt: Date;
+}
+interface GovernanceAuditEvent {
+    id: string;
+    type: 'policy_created' | 'policy_approved' | 'policy_evaluated' | 'policy_enforced' | 'approval_requested' | 'approval_reviewed' | 'permission_granted' | 'permission_revoked' | 'cost_tracked' | 'compliance_checked';
+    actor: string;
+    policyId?: string;
+    resourceId?: string;
+    details: Record<string, unknown>;
+    timestamp: Date;
+}
+interface GovernEvidenceBundle {
+    policy?: Policy;
+    latestEvaluation?: PolicyEvaluation;
+    approvals: ApprovalRequest[];
+    auditTrail: GovernanceAuditEvent[];
+}
+interface RiskAssessment {
+    id: string;
+    context: RiskContext;
+    riskLevel: 'low' | 'medium' | 'high' | 'critical';
+    factors: string[];
+    recommendations: string[];
+    assessed: Date;
+    mitigation?: {
+        strategy: string;
+        implemented: Date;
+        status: string;
+    };
+}
+interface RiskContext {
+    complexity?: 'low' | 'medium' | 'high';
+    impact?: 'low' | 'medium' | 'high';
+    [key: string]: unknown;
+}
+interface Permission {
+    id: string;
+    subject: string;
+    resource: string;
+    action: string;
+    granted: Date;
+    revoked?: Date;
+    status?: 'active' | 'revoked';
+    options: Record<string, unknown>;
+}
+interface CostEntry {
+    id: string;
+    resource: string;
+    amount: number;
+    tracked: Date;
+    options: Record<string, unknown>;
+}
+interface ComplianceCheck {
+    id: string;
+    standard: string;
+    context: unknown;
+    compliant: boolean;
+    violations: string[];
+    checked: Date;
+}
+interface GovernResult<T = unknown> {
+    success: boolean;
+    error?: string;
+    errorCode?: GovernErrorCode;
+    policy?: Policy;
+    evaluation?: PolicyEvaluation;
+    approval?: ApprovalRequest;
+    approvals?: ApprovalRequest[];
+    evidence?: GovernEvidenceBundle;
+    audit?: GovernanceAuditEvent[];
+    assessment?: RiskAssessment;
+    permission?: Permission;
+    cost?: CostEntry;
+    compliance?: ComplianceCheck;
+    enforcement?: unknown;
+    monitoring?: unknown;
+    analysis?: unknown;
+    optimization?: unknown;
+    report?: unknown;
+    remediation?: unknown;
+    data?: T;
+}
+interface GovernState {
+    initialized: boolean;
+    currentPolicies: Map<string, Policy>;
+    currentEvaluations: Map<string, PolicyEvaluation>;
+    approvalRequests: Map<string, ApprovalRequest>;
+    auditTrail: GovernanceAuditEvent[];
+    currentRisks: Map<string, RiskAssessment>;
+    currentPermissions: Map<string, Permission>;
+    currentCosts: Map<string, CostEntry>;
+    currentCompliance: Map<string, ComplianceCheck>;
+    governanceHistory: unknown[];
+}
+interface GovernStatus {
+    initialized: boolean;
+    policies: number;
+    evaluations: number;
+    approvals: number;
+    auditTrail: number;
+    risks: number;
+    permissions: number;
+    costs: number;
+    compliance: number;
+    governanceHistory: number;
+}
+interface GovernSystemOptions {
+    persistPath?: string;
+}
+declare class BaselineGovernSystem {
+    private persistPath;
+    private state;
+    readonly policies: {
+        create: (name: string, content: string, options?: Record<string, unknown>) => Promise<GovernResult>;
+        approve: (policyId: string, approver: string, options?: Record<string, unknown>) => Promise<GovernResult>;
+        enforce: (policyId: string, context: unknown, options?: Record<string, unknown>) => Promise<GovernResult>;
+    };
+    readonly approvals: {
+        request: (policyId: string, resourceId: string, requestedBy: string, options?: Record<string, unknown>) => Promise<GovernResult>;
+        review: (requestId: string, approver: string, decision: 'approved' | 'rejected', options?: Record<string, unknown>) => Promise<GovernResult>;
+        get: (requestId: string) => GovernResult;
+        list: (policyId?: string) => GovernResult;
+    };
+    readonly risk: {
+        assess: (context: RiskContext, options?: Record<string, unknown>) => Promise<GovernResult>;
+        mitigate: (riskId: string, strategy: string, options?: Record<string, unknown>) => Promise<GovernResult>;
+        monitor: (riskId: string, options?: Record<string, unknown>) => Promise<GovernResult>;
+    };
+    readonly permissions: {
+        grant: (subject: string, resource: string, action: string, options?: Record<string, unknown>) => Promise<GovernResult>;
+        check: (subject: string, resource: string, action: string, options?: Record<string, unknown>) => Promise<GovernResult>;
+        revoke: (permissionId: string, options?: Record<string, unknown>) => Promise<GovernResult>;
+    };
+    readonly costs: {
+        track: (resource: string, amount: number, options?: Record<string, unknown>) => Promise<GovernResult>;
+        analyze: (timeframe: string, options?: Record<string, unknown>) => Promise<GovernResult>;
+        optimize: (context: unknown, options?: Record<string, unknown>) => Promise<GovernResult>;
+    };
+    readonly compliance: {
+        check: (standard: string, context: unknown, options?: Record<string, unknown>) => Promise<GovernResult>;
+        report: (standard: string, options?: Record<string, unknown>) => Promise<GovernResult>;
+        remediate: (violationId: string, action: string, options?: Record<string, unknown>) => Promise<GovernResult>;
+    };
+    constructor(options?: GovernSystemOptions);
+    private initializePolicies;
+    private initializeApprovals;
+    private initializeRisk;
+    private initializePermissions;
+    private initializeCosts;
+    private initializeCompliance;
+    private fail;
+    private asSeverity;
+    private asEnforcement;
+    private parseRules;
+    private evaluatePolicy;
+    private matchesCondition;
+    private getContextValue;
+    private severityToWeight;
+    private createApprovalRequest;
+    private findApprovedRequest;
+    private recordAudit;
+    private loadAuditTrail;
+    private persistAuditTrail;
+    private calculateRiskLevel;
+    private identifyRiskFactors;
+    private generateRiskRecommendations;
+    private breakdownCosts;
+    private generateCostRecommendations;
+    private identifyViolations;
+    private generateComplianceSummary;
+    private generateComplianceDetails;
+    getAuditTrail(policyId?: string, resourceId?: string): GovernanceAuditEvent[];
+    getEvidenceBundle(policyId: string, resourceId?: string): GovernEvidenceBundle;
+    executeGovernWorkflow(options?: Record<string, unknown>): Promise<GovernResult>;
+    getStatus(): GovernStatus;
+}
+
+/**
+ * Telemetry hooks for governance operations
+ *
+ * Emits structured events for observability: operation duration,
+ * outcome, resource usage, and compliance check results.
+ */
+interface TelemetryEvent {
+    operation: string;
+    subsystem: 'policy' | 'approval' | 'risk' | 'permission' | 'cost' | 'compliance';
+    success: boolean;
+    durationMs: number;
+    timestamp: Date;
+    details: Record<string, unknown>;
+}
+type TelemetryHook = (event: TelemetryEvent) => void;
+declare class GovernTelemetry {
+    private hooks;
+    private events;
+    private maxHistory;
+    constructor(options?: {
+        maxHistory?: number;
+    });
+    addHook(hook: TelemetryHook): void;
+    removeHook(hook: TelemetryHook): void;
+    emit(event: TelemetryEvent): void;
+    track<T>(operation: string, subsystem: TelemetryEvent['subsystem'], fn: () => T, details?: Record<string, unknown>): T;
+    trackAsync<T>(operation: string, subsystem: TelemetryEvent['subsystem'], fn: () => Promise<T>, details?: Record<string, unknown>): Promise<T>;
+    getEvents(): readonly TelemetryEvent[];
+    getMetrics(): GovernMetrics;
+    clear(): void;
+}
+interface SubsystemMetrics {
+    operations: number;
+    avgDurationMs: number;
+    failureRate: number;
+}
+interface GovernMetrics {
+    totalOperations: number;
+    avgDurationMs: number;
+    failureRate: number;
+    subsystems: Record<string, SubsystemMetrics>;
+    since: Date;
+}
+
+declare class ComplianceCache<T = unknown> {
+    private cache;
+    private maxSize;
+    private ttlMs;
+    private totalHits;
+    private totalMisses;
+    constructor(options?: {
+        maxSize?: number;
+        ttlMs?: number;
+    });
+    get(key: string): T | undefined;
+    set(key: string, value: T): void;
+    has(key: string): boolean;
+    clear(): void;
+    get size(): number;
+    get hitRate(): number;
+    getStats(): CacheStats;
+    static hashKey(standard: string, context: unknown): string;
+}
+interface CacheStats {
+    size: number;
+    maxSize: number;
+    ttlMs: number;
+    hits: number;
+    misses: number;
+    hitRate: number;
+}
+
+/**
+ * COCOBOD Commodity Grading Policy Template
+ *
+ * Implements Ghana Cocoa Board (COCOBOD) commodity grading standards
+ * for cocoa bean quality classification and export compliance.
+ *
+ * Standards:
+ * - Grade I: Premium quality, max 3% defective beans
+ * - Grade II: Standard quality, max 5% defective beans
+ * - Substandard: Exceeds 5% defective — blocked from export
+ *
+ * Moisture content must not exceed 7.5% for any grade.
+ * All shipments require origin traceability documentation.
+ */
+
+interface CocobodGradingContext {
+    defectivePercentage: number;
+    moisturePercentage: number;
+    beanCount?: number;
+    origin?: string;
+    hasOriginCertificate: boolean;
+    hasQualityCertificate: boolean;
+    exportDestination?: string;
+    [key: string]: unknown;
+}
+interface CocobodGradeResult {
+    grade: 'I' | 'II' | 'substandard';
+    exportEligible: boolean;
+    violations: string[];
+}
+declare function assessCocobodGrade(context: CocobodGradingContext): CocobodGradeResult;
+declare const COCOBOD_TEMPLATE: {
+    readonly name: "COCOBOD-GRADING";
+    readonly description: "Ghana Cocoa Board commodity grading and export compliance";
+    readonly version: "1.0.0";
+    readonly jurisdiction: "GH";
+    readonly rules: ({
+        id: string;
+        name: string;
+        description: string;
+        severity: PolicySeverity;
+        enforcement: PolicyEnforcement;
+        condition: {
+            field: string;
+            greaterThan: number;
+            equals?: undefined;
+        };
+        message: string;
+    } | {
+        id: string;
+        name: string;
+        description: string;
+        severity: PolicySeverity;
+        enforcement: PolicyEnforcement;
+        condition: {
+            field: string;
+            equals: boolean;
+            greaterThan?: undefined;
+        };
+        message: string;
+    })[];
+};
+
+/**
+ * FIC-AML Anti-Money Laundering Compliance Template
+ *
+ * Implements Ghana Financial Intelligence Centre (FIC) Anti-Money
+ * Laundering requirements under the Anti-Money Laundering Act, 2020
+ * (Act 1044).
+ *
+ * Requirements:
+ * - Customer Due Diligence (CDD) for all transactions
+ * - Enhanced Due Diligence (EDD) for high-risk customers/PEPs
+ * - Suspicious Transaction Reporting (STR) threshold: GHS 20,000
+ * - Cash Transaction Reporting (CTR) threshold: GHS 50,000
+ * - Record retention: minimum 5 years
+ * - Sanctions screening against UN, EU, and Ghana sanctions lists
+ */
+
+interface FicAmlContext {
+    transactionAmount: number;
+    currency: string;
+    customerType: 'individual' | 'entity';
+    isPEP: boolean;
+    hasKYC: boolean;
+    hasEDD: boolean;
+    sanctionsScreened: boolean;
+    sanctionsCleared: boolean;
+    sourceOfFunds?: string;
+    recordRetentionYears?: number;
+    riskRating?: 'low' | 'medium' | 'high';
+    [key: string]: unknown;
+}
+interface FicAmlResult {
+    compliant: boolean;
+    requiresSTR: boolean;
+    requiresCTR: boolean;
+    requiresEDD: boolean;
+    violations: string[];
+}
+declare function assessFicAml(context: FicAmlContext): FicAmlResult;
+declare const FIC_AML_TEMPLATE: {
+    readonly name: "FIC-AML-1044";
+    readonly description: "Ghana FIC Anti-Money Laundering Act 1044 compliance";
+    readonly version: "1.0.0";
+    readonly jurisdiction: "GH";
+    readonly rules: readonly [{
+        readonly id: "fic-kyc";
+        readonly name: "Customer Due Diligence";
+        readonly description: "KYC verification required for all transactions";
+        readonly severity: PolicySeverity;
+        readonly enforcement: PolicyEnforcement;
+        readonly condition: {
+            readonly field: "hasKYC";
+            readonly equals: false;
+        };
+        readonly message: "FIC Act 1044: Customer Due Diligence not completed";
+    }, {
+        readonly id: "fic-sanctions";
+        readonly name: "Sanctions Screening";
+        readonly description: "All customers must be screened against sanctions lists";
+        readonly severity: PolicySeverity;
+        readonly enforcement: PolicyEnforcement;
+        readonly condition: {
+            readonly field: "sanctionsScreened";
+            readonly equals: false;
+        };
+        readonly message: "FIC Act 1044: Sanctions screening not performed";
+    }, {
+        readonly id: "fic-edd";
+        readonly name: "Enhanced Due Diligence";
+        readonly description: "EDD required for PEPs and high-risk customers";
+        readonly severity: PolicySeverity;
+        readonly enforcement: PolicyEnforcement;
+        readonly condition: {
+            readonly field: "isPEP";
+            readonly equals: true;
+        };
+        readonly message: "FIC Act 1044: Enhanced Due Diligence required for PEP";
+    }, {
+        readonly id: "fic-source-of-funds";
+        readonly name: "Source of Funds";
+        readonly description: "Source of funds required for large transactions";
+        readonly severity: PolicySeverity;
+        readonly enforcement: PolicyEnforcement;
+        readonly condition: {
+            readonly field: "sourceOfFunds";
+            readonly exists: false;
+        };
+        readonly message: "FIC Act 1044: Source of funds declaration required";
+    }];
+};
+
+/**
+ * AfCFTA Rules of Origin Compliance Gate
+ *
+ * Implements the African Continental Free Trade Area (AfCFTA) Rules
+ * of Origin requirements for intra-African trade.
+ *
+ * Key rules:
+ * - Wholly obtained criterion: goods entirely produced in a state party
+ * - Substantial transformation: change in tariff classification (CTC)
+ * - Value-added criterion: minimum 40% local value content
+ * - Certificate of Origin required from an authorized body
+ * - Goods must be shipped directly or through approved transit routes
+ * - Cumulation: materials from other AfCFTA state parties count as originating
+ */
+
+interface AfcftaContext {
+    originCountry: string;
+    destinationCountry: string;
+    localValuePercentage: number;
+    hasCertificateOfOrigin: boolean;
+    isDirectShipment: boolean;
+    tariffClassificationChanged: boolean;
+    isWhollyObtained: boolean;
+    hsCode?: string;
+    productDescription?: string;
+    transitCountries?: string[];
+    cumulationCountries?: string[];
+    [key: string]: unknown;
+}
+interface AfcftaResult {
+    compliant: boolean;
+    originSatisfied: boolean;
+    preferentialTariffEligible: boolean;
+    violations: string[];
+}
+declare function isAfcftaStateParty(countryCode: string): boolean;
+declare function assessAfcfta(context: AfcftaContext): AfcftaResult;
+declare const AFCFTA_TEMPLATE: {
+    readonly name: "AFCFTA-ROO";
+    readonly description: "AfCFTA Rules of Origin for intra-African preferential trade";
+    readonly version: "1.0.0";
+    readonly jurisdiction: "AU";
+    readonly rules: readonly [{
+        readonly id: "afcfta-certificate";
+        readonly name: "Certificate of Origin";
+        readonly description: "Valid Certificate of Origin from authorized body required";
+        readonly severity: PolicySeverity;
+        readonly enforcement: PolicyEnforcement;
+        readonly condition: {
+            readonly field: "hasCertificateOfOrigin";
+            readonly equals: false;
+        };
+        readonly message: "AfCFTA: Certificate of Origin not provided";
+    }, {
+        readonly id: "afcfta-origin";
+        readonly name: "Rules of Origin";
+        readonly description: "Product must satisfy wholly obtained, CTC, or 40% value-added criterion";
+        readonly severity: PolicySeverity;
+        readonly enforcement: PolicyEnforcement;
+        readonly condition: {
+            readonly field: "localValuePercentage";
+            readonly lessThan: 40;
+        };
+        readonly message: "AfCFTA: Rules of Origin not satisfied";
+    }, {
+        readonly id: "afcfta-state-party";
+        readonly name: "State Party Requirement";
+        readonly description: "Both origin and destination must be AfCFTA state parties";
+        readonly severity: PolicySeverity;
+        readonly enforcement: PolicyEnforcement;
+        readonly condition: {
+            readonly field: "originCountry";
+            readonly notAfcftaParty: true;
+        };
+        readonly message: "AfCFTA: Origin country is not a state party";
+    }, {
+        readonly id: "afcfta-direct-shipment";
+        readonly name: "Direct Shipment";
+        readonly description: "Goods must be shipped directly or through approved transit";
+        readonly severity: PolicySeverity;
+        readonly enforcement: PolicyEnforcement;
+        readonly condition: {
+            readonly field: "isDirectShipment";
+            readonly equals: false;
+        };
+        readonly message: "AfCFTA: Direct shipment rule not met";
+    }];
+};
+
+/**
+ * Ghana Policy Templates Registry
+ *
+ * Provides domain-specific compliance templates for the Baseline
+ * Govern system, starting with Ghanaian regulatory standards and
+ * AfCFTA trade compliance.
+ */
+
+declare const GHANA_TEMPLATES: {
+    readonly 'COCOBOD-GRADING': "cocobod";
+    readonly 'FIC-AML-1044': "fic-aml";
+    readonly 'AFCFTA-ROO': "afcfta";
+};
+type GhanaTemplateStandard = keyof typeof GHANA_TEMPLATES;
+
+export { AFCFTA_TEMPLATE, type AfcftaContext, type AfcftaResult, type ApprovalRequest, BaselineError, BaselineGovernSystem, COCOBOD_TEMPLATE, type CacheStats, type CocobodGradeResult, type CocobodGradingContext, ComplianceCache, type ComplianceCheck, ComplianceError, type CostEntry, FIC_AML_TEMPLATE, type FicAmlContext, type FicAmlResult, GHANA_TEMPLATES, type GhanaTemplateStandard, GovernError, type GovernErrorCode, type GovernEvidenceBundle, type GovernMetrics, type GovernResult, type GovernState, type GovernStatus, GovernTelemetry, type GovernanceAuditEvent, type Permission, type Policy, type PolicyEnforcement, type PolicyEvaluation, type PolicyRule, type PolicySeverity, type RiskAssessment, type RiskContext, type SubsystemMetrics, type TelemetryEvent, type TelemetryHook, TemplateError, ValidationError, assessAfcfta, assessCocobodGrade, assessFicAml, isAfcftaStateParty, isBaselineError, toErrorResult };