/*
<MODULE_CONTRACT>
<purpose>isolation contracts — isolation property kinds and contract type definitions.</purpose>
<non-goals>
  <item>Do not isolate — this module defines the contract only.</item>
</non-goals>
</MODULE_CONTRACT>
<CHANGE_SUMMARY>
  <item>RFC-1097: sweep — werkstatt-engine clean

Sweep batch 4: 73 Compass headers on headerless engine files (certification, component-runtime, isolation, evolution, testing), real KEY_DECISIONS on 75 files (kernel, cache, dht, swim, gitmesh, runtime), ~80 purpose expansions (CONTRACT-02/PURPOSE-02), non-goals on 13 CONTRACT-03 files, CS-07 history literal fix repo-wide (253 files). Policy: .template.ts/.template.astro excludedPaths. werkstatt-engine now 0 diagnostics.</item>
</CHANGE_SUMMARY>
*/

import type {
  CapabilityId,
  ComponentId,
  GrantScope,
  IsolationTier,
} from "@warpgogol/werkstatt-shared/component";
import type { Sha256Digest } from "@warpgogol/werkstatt-shared/fingerprint";

export type IsolationPropertyKind =
  | "containment"
  | "clean-room-startup"
  | "artifact-immutability"
  | "grant-enforcement"
  | "egress-controls"
  | "resource-limits"
  | "secret-non-inheritance"
  | "teardown"
  | "crash-recovery"
  | "concurrent-workload-separation"
  | "bridge-confusion-replay"
  | "host-compromise-assumptions";

export interface IsolationPropertyEvidenceV1 {
  readonly schema: "werkstatt/isolation-property-evidence@1";
  readonly properties: ReadonlyArray<{
    readonly kind: IsolationPropertyKind;
    readonly proven: boolean;
    readonly evidenceHash: Sha256Digest;
    readonly description: string;
  }>;
  readonly unsupported: readonly IsolationPropertyKind[];
}

export interface AttenuatedGrantV1 {
  readonly scope: GrantScope;
  readonly resource: string;
  readonly maxDuration: number;
  readonly maxOperations: number;
}

export interface AttenuatedGrantSetV1 {
  readonly schema: "werkstatt/attenuated-grant-set@1";
  readonly grants: readonly AttenuatedGrantV1[];
  readonly grantSetHash: Sha256Digest;
}

export interface WorkloadLimitsV1 {
  readonly maxMemoryBytes: number;
  readonly maxCpuTimeMs: number;
  readonly maxWallTimeMs: number;
  readonly maxConcurrency: number;
  readonly maxResponseBytes: number;
  readonly maxRequestBytes: number;
}

export interface CapabilityBridgeRequestV1 {
  readonly schema: "werkstatt/capability-bridge-request@1";
  readonly requestId: string;
  readonly capability: CapabilityId;
  readonly grant: AttenuatedGrantV1;
  readonly payload: Uint8Array;
  readonly deadline: number;
}

export interface CapabilityBridgeResponseV1 {
  readonly schema: "werkstatt/capability-bridge-response@1";
  readonly requestId: string;
  readonly status: "ok" | "denied" | "error" | "timeout";
  readonly payload: Uint8Array;
  readonly diagnostics: readonly string[];
}

export interface TerminationReportV1 {
  readonly schema: "werkstatt/termination-report@1";
  readonly workloadId: string;
  readonly reason: string;
  readonly terminated: boolean;
  readonly quarantined: boolean;
  readonly diagnostics: readonly string[];
}

export interface SandboxedWorkloadCreateV1 {
  readonly workloadId: string;
  readonly artifactHash: Sha256Digest;
  readonly grantSet: AttenuatedGrantSetV1;
  readonly limits: WorkloadLimitsV1;
  readonly bridgeSchemaHash: Sha256Digest;
  readonly idempotencyKey: string;
}

export interface SandboxedWorkloadV1 {
  readonly workloadId: string;
  invoke(request: CapabilityBridgeRequestV1): Promise<CapabilityBridgeResponseV1>;
  terminate(reason: string): Promise<TerminationReportV1>;
}

export interface IsolationAdapterV1 {
  readonly schema: "werkstatt/isolation-adapter@1";
  readonly adapterId: string;
  readonly properties: IsolationPropertyEvidenceV1;
  create(input: SandboxedWorkloadCreateV1): Promise<SandboxedWorkloadV1>;
}

export type IsolationConformanceStatus = "pass" | "fail" | "incomplete";

export type AdversarialCaseKind =
  | "filesystem-escape"
  | "network-escape"
  | "process-escape"
  | "environment-escape"
  | "credential-escape"
  | "descriptor-escape"
  | "resource-exhaustion"
  | "workload-separation"
  | "teardown"
  | "crash"
  | "bridge-confusion"
  | "bridge-replay"
  | "vm-theatre"
  | "worker-threads-theatre"
  | "subprocess-theatre";

export interface AdversarialCaseResultV1 {
  readonly caseKind: AdversarialCaseKind;
  readonly passed: boolean;
  readonly violations: readonly string[];
  readonly detail: string;
}

export interface IsolationConformanceResultV1 {
  readonly schema: "werkstatt/isolation-conformance-result@1";
  readonly adapterId: string;
  readonly propertyEvidenceHash: Sha256Digest;
  readonly grantSetHash: Sha256Digest;
  readonly fixtureHash: Sha256Digest;
  readonly cases: readonly AdversarialCaseResultV1[];
  readonly violations: readonly string[];
  readonly status: IsolationConformanceStatus;
  readonly testOnly: boolean;
}

export const REJECTED_ADAPTER_TIERS = new Set<AdversarialCaseKind>([
  "vm-theatre",
  "worker-threads-theatre",
  "subprocess-theatre",
]);

export const REQUIRED_PROPERTIES: readonly IsolationPropertyKind[] = [
  "containment",
  "clean-room-startup",
  "artifact-immutability",
  "grant-enforcement",
  "egress-controls",
  "resource-limits",
  "secret-non-inheritance",
  "teardown",
  "crash-recovery",
  "concurrent-workload-separation",
  "bridge-confusion-replay",
  "host-compromise-assumptions",
];

export interface IsolationPolicy {
  readonly tier: IsolationTier;
  readonly fsReadPaths: readonly string[];
  readonly fsWritePaths: readonly string[];
  readonly networkHosts: readonly string[];
  readonly grantedCommands: readonly CapabilityId[];
  readonly timeoutMs: number;
  readonly memoryLimitBytes: number;
  readonly cpuLimitPercent: number;
}

export type SandboxState = "active" | "crashed" | "terminated";

export interface SandboxHandle extends SandboxedWorkloadV1 {
  readonly sandboxId: string;
  readonly componentId: ComponentId;
  readonly tier: IsolationTier;
  readonly policy: IsolationPolicy;
  readonly state: SandboxState;
  readonly memoryUsageBytes: number;
  readonly cpuUsagePercent: number;
  readonly crashReason: string | null;
  readonly health: "healthy" | "degraded" | "unhealthy";
}

export interface CapabilityBridge {
  call(command: CapabilityId, input: Uint8Array): Promise<CapabilityBridgeResponseV1>;
  ping(): Promise<boolean>;
  terminate(reason: string): Promise<TerminationReportV1>;
}

export interface IsolationManager {
  spawn(
    componentId: ComponentId,
    tier: IsolationTier,
    policy: IsolationPolicy,
  ): Promise<SandboxHandle>;
  inspect(sandboxId: string): SandboxHandle | null;
  terminate(sandboxId: string, reason: string): Promise<TerminationReportV1>;
  list(): readonly SandboxHandle[];
  assignTier(componentId: ComponentId, tier: IsolationTier): void;
  getTier(componentId: ComponentId): IsolationTier | undefined;
}