@yiaany/ghostapi 0.1.7 → 0.1.8

package/dist/safety/safetyController.d.ts

@@ -0,0 +1,187 @@
+export declare const SAFETY_SCOPE_KINDS: readonly ["global", "organization", "project", "environment", "agent", "workload", "provider", "operation", "risk_class"];
+export type SafetyScopeKind = (typeof SAFETY_SCOPE_KINDS)[number];
+export type SafetyScope = {
+    kind: SafetyScopeKind;
+    id?: string;
+};
+export type SafetyAction = {
+    organizationId: string;
+    projectId: string;
+    environment: string;
+    actorId: string;
+    workloadId: string;
+    provider: string;
+    operation: string;
+    riskClass: "read" | "write" | "money_movement" | "external_communication" | "delete" | "deploy";
+    idempotencyKey: string;
+    actionHash: string;
+    costs: {
+        monetaryAmountMinor: number;
+        requests: number;
+        messages: number;
+        mutations: number;
+        deletes: number;
+        tokenCost: number;
+    };
+};
+export type SafetyBudgetLimits = Partial<{
+    monetaryAmountMinor: number;
+    requests: number;
+    messages: number;
+    mutations: number;
+    deletes: number;
+    tokenCost: number;
+    concurrency: number;
+    velocity: number;
+}>;
+export type SafetyBudget = {
+    id: string;
+    scope: SafetyScope;
+    windowMs: number;
+    velocityWindowMs: number;
+    limits: SafetyBudgetLimits;
+};
+export type SafetyCircuit = {
+    id: string;
+    scope: SafetyScope;
+    windowMs: number;
+    minimumSamples: number;
+    maxFailureRateBps: number;
+    maxPolicyViolations: number;
+    maxLatencyMs: number;
+    maxReconciliationMismatches: number;
+    state: "closed" | "open";
+    openedAt?: string;
+    reason?: string;
+};
+export type SafetyOperatorPermission = "safety.stop" | "safety.reenable" | "safety.configure" | "safety.inspect";
+export type SafetyOperator = {
+    id: string;
+    principalId: string;
+    permissions: SafetyOperatorPermission[];
+};
+export interface SafetyEmergencyAuthorizer {
+    authenticate(identity: unknown): Promise<SafetyOperator>;
+}
+export type SafetyLease = {
+    replay: boolean;
+    assertActive(): Promise<void>;
+    commit<T>(operation: () => Promise<T>): Promise<T>;
+    complete(outcome: {
+        success: boolean;
+        policyViolation?: boolean;
+        reconciliationMismatch?: boolean;
+        latencyMs: number;
+        reason?: string;
+    }): Promise<void>;
+};
+export type SafetyQueueItem = {
+    id: string;
+    action: SafetyAction;
+    queuedAt: string;
+};
+export type SafetyDeadLetter = SafetyQueueItem & {
+    reason: string;
+    deadLetteredAt: string;
+};
+export type SafetyAuditRecord = {
+    sequence: number;
+    event: string;
+    subject: string;
+    reason: string;
+    actorPrincipalId?: string;
+    timestamp: string;
+    previousHash: string;
+    recordHash: string;
+};
+export type SafetyControllerState = {
+    schemaVersion: 1;
+    switches: Array<{
+        scope: SafetyScope;
+        enabled: boolean;
+        changedAt: string;
+        reason: string;
+        changedBy: string;
+    }>;
+    budgets: SafetyBudget[];
+    circuits: SafetyCircuit[];
+    ledger: Array<{
+        key: string;
+        action: SafetyAction;
+        status: "reserved" | "completed";
+        admittedAt: string;
+        completedAt?: string;
+        outcome?: {
+            success: boolean;
+            policyViolation: boolean;
+            reconciliationMismatch: boolean;
+            latencyMs: number;
+            reason?: string;
+        };
+    }>;
+    queue: SafetyQueueItem[];
+    deadLetters: SafetyDeadLetter[];
+    auditAnchor: string;
+    audit: SafetyAuditRecord[];
+};
+export type SafetyControllerOptions = {
+    path?: string;
+    now?: () => Date;
+    emergencyAuthorizer?: SafetyEmergencyAuthorizer;
+    leaseTtlMs?: number;
+};
+export declare class SafetyControllerError extends Error {
+    readonly code?: string;
+    constructor(message: string, code?: string);
+}
+export declare function createLocalSafetyController(options?: SafetyControllerOptions): LocalSafetyController;
+export declare class LocalSafetyController {
+    private readonly path;
+    private readonly now;
+    private readonly emergencyAuthorizer;
+    private readonly leaseTtlMs;
+    constructor(options?: SafetyControllerOptions);
+    configureBudget(input: {
+        identity: unknown;
+        budget: unknown;
+    }): Promise<SafetyBudget>;
+    configureCircuit(input: {
+        identity: unknown;
+        circuit: unknown;
+    }): Promise<SafetyCircuit>;
+    stop(input: {
+        identity: unknown;
+        scope: unknown;
+        reason: string;
+    }): Promise<void>;
+    reenable(input: {
+        identity: unknown;
+        scope: unknown;
+        reason: string;
+    }): Promise<void>;
+    admit(actionValue: unknown): Promise<SafetyLease>;
+    enqueue(actionValue: unknown): Promise<SafetyQueueItem>;
+    dequeue(): Promise<SafetyQueueItem | null>;
+    runScheduledGameDay(input: {
+        stopIdentity: unknown;
+        reenableIdentity: unknown;
+        action: unknown;
+        reason: string;
+    }): Promise<{
+        passed: true;
+        stoppedAt: string;
+        reenabledAt: string;
+    }>;
+    inspect(): Promise<SafetyControllerState>;
+    readStateForTesting(): Promise<SafetyControllerState>;
+    private authorize;
+    private read;
+    private mutate;
+    private timestamp;
+    private leaseExpired;
+}
+export declare function createDisabledSafetyEmergencyAuthorizer(): SafetyEmergencyAuthorizer;
+export declare function createTestSafetyEmergencyAuthorizer(): {
+    authorizer: SafetyEmergencyAuthorizer;
+    issue(input: SafetyOperator): SafetyOperator;
+};