ega-v9 0.1.0 → 1.0.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Dae Jung Byun
+Copyright (c) 2026 Daejung Byun
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,44 +1,262 @@
-# EGA V9
+# EGA V9 --- Execution Governance AI
 
-Execution Governance AI V9 is a deterministic runtime-governance framework for autonomous AI workflows.
+## Deterministic Runtime Governance for Autonomous AI Workflows
 
-## Install
+> **Official Replication Guide for the EGA V9 paper**
 
-```bash
+EGA V9 is an execution-governance framework for deterministic replay,
+provenance-aware verification, trust-state evaluation, and fail-closed
+containment in autonomous AI workflows.
+
+This README serves as the official replication guide accompanying the
+EGA V9 paper.
+
+------------------------------------------------------------------------
+
+## Table of Contents
+
+1.  Why EGA V9?
+2.  Installation
+3.  Three-Line Integration
+4.  Quick Start
+5. [Verified Behavior](#5-verified-behavior)
+6.  Reproducing the Paper
+7.  Publication Verification
+8.  Runtime Architecture
+9.  Repository Structure
+10. Contact and Collaboration
+11. License
+12. Roadmap
+
+------------------------------------------------------------------------
+
+## 1. Why EGA V9?
+
+**LLM-based guards add cost. Runtime failures still happen.**
+
+EGA V9 takes a different approach.
+
+Instead of asking another LLM whether an execution is safe, EGA V9 verifies workflow execution deterministically.
+
+### EGA V9
+
+- Runtime verification with **0 additional LLM calls**
+- Median (P50) verification latency: **0.003055 ms**
+- **10,000 workflows evaluated**
+- **0% false positives / 0% false negatives**
+- Deterministic replay, provenance verification, and fail-closed containment
+
+> **Deterministic Replay > Probabilistic Trust**
+
+------------------------------------------------------------------------
+
+## 2. Installation
+
+``` bash
 npm install ega-v9
 ```
 
-## Quick Start
+Repository replication:
+
+``` bash
+git clone https://github.com/paibyun9/EGA-V9.git
+cd EGA-V9
+npm ci
+```
+
+------------------------------------------------------------------------
+
+## 3. Three-Line Integration
+
+Protect an existing AI application with a single middleware.
+
+### Before
 
 ```javascript
-import { govern } from "ega-v9";
+app.post("/checkout", async (req) => {
+  await agent.buy(req.body.item);
+});
+```
 
-const result = govern([
-  { step: 1, action: "search_product", item: "laptop" },
-  { step: 2, action: "select_product", quantity: 1 },
-  { step: 3, action: "checkout_request", approved: true }
-]);
+### After
+
+```javascript
+const { ega } = require("ega-v9");
 
-console.log(result.verification);
+app.use(ega.guard());
 ```
 
-## Core Concepts
+A verified request proceeds to the protected route. A replay mismatch is fail-closed contained before the protected operation is executed.
+
+------------------------------------------------------------------------
+
+## 4. Quick Start
+
+Create a file named `quick-start.cjs`.
+
+```javascript
+const { verifyExecution } = require("ega-v9");
 
-- Deterministic replay
-- Provenance-aware verification
-- Trust-state evaluation
-- Fail-closed containment
+const workflow = [
+  {
+    step: 1,
+    action: "search_product",
+    item: "laptop"
+  },
+  {
+    step: 2,
+    action: "select_product",
+    quantity: 1
+  },
+  {
+    step: 3,
+    action: "checkout_request",
+    approved: true
+  }
+];
 
-## Example Output
+const result = verifyExecution(workflow);
 
-```json
+console.log({
+  status: result.status,
+  replayConsistency:
+    result.detection.status === "match",
+  trustState:
+    result.trust.currentTier,
+  containmentRequired:
+    result.containment.activated &&
+    !result.containment.executionAllowed,
+  executionAllowed:
+    result.containment.executionAllowed
+});
+```
+
+Run:
+
+```bash
+node quick-start.cjs
+```
+
+Expected output:
+
+```text
 {
-  "replayConsistency": true,
-  "trustState": "VERIFIED",
-  "containmentRequired": false
+  status: 'verified',
+  replayConsistency: true,
+  trustState: 'T1',
+  containmentRequired: false,
+  executionAllowed: true
 }
 ```
 
-## License
+---
+
+## 5. Verified Behavior
+
+The Quick Start example demonstrates deterministic runtime verification.
+
+```text
+{
+  status: 'verified',
+  replayConsistency: true,
+  trustState: 'T1',
+  containmentRequired: false,
+  executionAllowed: true
+}
+```
+
+This output demonstrates that:
+
+- ✅ Replay consistency is verified.
+- ✅ The workflow remains in Trust State **T1**.
+- ✅ No containment is required.
+- ✅ Execution is allowed.
+
+These results were verified using the published EGA V9 Release Candidate package.
+
+------------------------------------------------------------------------
+
+## 6. Reproducing the Paper
+
+The complete replication workflow used in the EGA V9 paper is available here:
+
+→ Detailed guide → **[Reproducing the Paper](docs/REPRODUCING_THE_PAPER.md)**
+
+This guide explains how to:
+
+- Build the SDK
+- Run the benchmark
+- Regenerate Table 4
+- Execute all publication verification gates
+- Reproduce the paper artifacts
+
+------------------------------------------------------------------------
+
+## 7. Publication Verification
+
+The complete publication verification workflow is documented here.
+
+Detailed guide → **[Publication Verification](docs/PUBLICATION_VERIFICATION.md)**
+
+------------------------------------------------------------------------
+
+## 8. Runtime Architecture
+
+The complete EGA V9 runtime architecture is documented here.
+
+Detailed guide → **[Runtime Architecture](docs/RUNTIME_ARCHITECTURE.md)**
+
+------------------------------------------------------------------------
+
+## 9. Repository Structure
+
+``` text
+EGA-V9/
+├── benchmarks/
+├── crates/
+├── dashboard/
+├── docs/
+├── packages/sdk-ts/
+├── paper/generated/
+├── publication/
+├── scripts/
+├── package.json
+├── SECURITY.md
+├── LICENSE
+└── README.md
+```
+
+------------------------------------------------------------------------
+
+## 10. Contact and Collaboration
+
+contact@lcm3.com
+
+Feedback from researchers, developers, startups, and enterprise
+engineering teams is welcome.
+
+------------------------------------------------------------------------
+
+## 11. License
+
+Released under the MIT License.
+
+------------------------------------------------------------------------
+
+## 12. Roadmap
+
+Current development:
+
+-   Complete README replication guide
+-   Finalize SDK
+-   Finalize benchmark reproducibility
+-   Finalize Stage E
+-   Release v1.0.0
+
+------------------------------------------------------------------------
+
+## Release Integrity Principle
 
-MIT
+> Do not trust a published result merely because it appears in a paper.
+> Reproduce the benchmark, regenerate the publication artifact, and
+> verify the release gates.

package/dist/index.d.ts

@@ -0,0 +1,188 @@
+export type EGATrustLevel = "supported" | "verified";
+export type EGAStatus = "verified" | "contained" | "failed";
+export type EGADetectionStatus = "match" | "mismatch";
+export type EGAContainmentMode = "observe" | "fail-closed";
+export type EGATrustTier = "T1" | "T2" | "T3" | "T4";
+export type EGAEventType = "workflow.started" | "workflow.verified" | "replay.mismatch" | "hash.verified" | "mutation.detected" | "containment.activated" | "execution.blocked" | "quarantine.created" | "lineage.reconstructed" | "business.metrics.collected" | "trust.evaluated" | "trust.escalated" | "approval.required" | "privilege.escalation.gated" | "mitre.mapped" | "eventbus.event.recorded";
+export type EGAClientIdentity = {
+    anonymousClientId: string;
+    source: "host-header" | "unknown";
+    domainHint?: string;
+};
+export type EGALicenseState = {
+    mode: "alpha" | "enterprise";
+    status: "active" | "grace" | "suspended" | "expired";
+    enforcement: "disabled" | "observe" | "warn" | "protect" | "block";
+    reason: string;
+};
+export type EGAMitreAtlasMapping = {
+    mapped: boolean;
+    attackType: string;
+    atlasTechnique: string;
+    attackTechnique: string;
+    severity: "none" | "low" | "medium" | "high" | "critical";
+    reason: string;
+};
+export type EGAEvent = {
+    id: string;
+    sequence: number;
+    type: EGAEventType;
+    timestamp: string;
+    requestId: string;
+    replayRoot: string;
+    trustLevel: EGATrustLevel;
+    status: EGAStatus;
+    clientIdentity?: EGAClientIdentity;
+    licenseState?: EGALicenseState;
+    details?: Record<string, unknown>;
+};
+export type EGAEventSummary = {
+    total: number;
+    byType: Record<string, number>;
+    latest?: EGAEvent;
+};
+export type EGABusinessMetrics = {
+    detected: boolean;
+    amount?: number;
+    price?: number;
+    quantity?: number;
+    currency?: string;
+    estimatedTransactionValue?: number;
+};
+export type EGABusinessTrustProfile = {
+    currentTier: EGATrustTier;
+    riskScore: number;
+    approvalRequired: boolean;
+    privilegeEscalationGate: boolean;
+    reason: string;
+};
+export type EGABusinessGovernanceProfile = {
+    metrics: EGABusinessMetrics;
+    trust: EGABusinessTrustProfile;
+};
+export type EGAProvenanceNodeType = "input" | "tool_output" | "policy" | "decision" | "business_metrics" | "trust_escalation";
+export type EGAProvenanceNode = {
+    id: string;
+    type: EGAProvenanceNodeType;
+    label: string;
+    data: Record<string, unknown>;
+};
+export type EGAProvenanceEdge = {
+    from: string;
+    to: string;
+    label: string;
+};
+export type EGAProvenanceGraph = {
+    graphId: string;
+    lineage: string[];
+    nodes: EGAProvenanceNode[];
+    edges: EGAProvenanceEdge[];
+    businessMetrics: EGABusinessMetrics;
+    businessGovernanceProfile: EGABusinessGovernanceProfile;
+};
+export type EGARequestContext = {
+    requestId: string;
+    replayRoot: string;
+    trustLevel: EGATrustLevel;
+    status: EGAStatus;
+    scorpLock: boolean;
+    clientIdentity: EGAClientIdentity;
+    licenseState: EGALicenseState;
+    mitreMapping: EGAMitreAtlasMapping;
+    detection: {
+        status: EGADetectionStatus;
+        expectedReplayRoot?: string;
+        actualReplayRoot: string;
+    };
+    containment: {
+        activated: boolean;
+        mode: EGAContainmentMode;
+        reason?: string;
+        quarantineId?: string;
+        executionAllowed: boolean;
+    };
+    trust: EGABusinessTrustProfile;
+    businessGovernanceProfile: EGABusinessGovernanceProfile;
+    provenance: EGAProvenanceGraph;
+};
+export type EGAGuardDecision = {
+    verified: boolean;
+    containmentRequired: boolean;
+    executionAllowed: boolean;
+    trustState: EGATrustTier;
+    reason: string | null;
+    latencyMicroseconds: number;
+    verification: EGARequestContext;
+};
+export type EGAGuardRequest = {
+    method?: string;
+    originalUrl?: string;
+    url?: string;
+    path?: string;
+    body?: unknown;
+    query?: unknown;
+    params?: unknown;
+    headers?: Record<string, unknown>;
+    egaWorkflow?: unknown;
+    ega?: EGARequestContext;
+    egaDecision?: EGAGuardDecision;
+};
+export type EGAGuardResponse = {
+    statusCode?: number;
+    setHeader?: (name: string, value: string) => void;
+    status?: (code: number) => EGAGuardResponse;
+    json?: (body: unknown) => void;
+};
+export type EGAGuardNext = (error?: unknown) => void;
+export type EGAWorkflowResolver = (req: EGAGuardRequest) => unknown | Promise<unknown>;
+export type EGAGuardOptions = {
+    mode?: "observe" | "fail-closed";
+    statusCode?: number;
+    policyId?: string;
+    resolveWorkflow?: EGAWorkflowResolver;
+    onVerified?: (decision: EGAGuardDecision) => void | Promise<void>;
+    onContained?: (decision: EGAGuardDecision) => void | Promise<void>;
+};
+export type EGAOptions = {
+    appName?: string;
+    trustLevel?: EGATrustLevel;
+    telemetry?: boolean;
+    failClosed?: boolean;
+    policyId?: string;
+    approvalThreshold?: number;
+};
+type NextFunction = EGAGuardNext;
+type EGARequest = EGAGuardRequest;
+type EGAResponse = EGAGuardResponse;
+export declare class EGA {
+    private readonly options;
+    private readonly eventLog;
+    private eventSequence;
+    private constructor();
+    static init(options?: EGAOptions): EGA;
+    guard(): (req: EGARequest, res: EGAResponse, next: NextFunction) => void;
+    events(type?: EGAEventType): EGAEvent[];
+    latestEvents(limit?: number): EGAEvent[];
+    eventSummary(): EGAEventSummary;
+    explain(context?: EGARequestContext): EGAProvenanceGraph | undefined;
+    canonicalize(input: unknown): string;
+    replayRoot(input: unknown): string;
+    detect(input: unknown, expectedReplayRoot?: string): {
+        status: "match" | "mismatch";
+        expectedReplayRoot: string | undefined;
+        actualReplayRoot: string;
+    };
+    private createReplayRoot;
+    private buildProvenanceGraph;
+    private getExpectedReplayRoot;
+    private recordEvent;
+}
+export declare function verifyExecution(input: unknown): EGARequestContext;
+export declare function replay(input: unknown): EGARequestContext;
+export declare function provenance(input: unknown): EGARequestContext;
+export declare function contain(input: unknown): EGARequestContext;
+declare function createGuard(options?: EGAGuardOptions): (req: EGAGuardRequest, res: EGAGuardResponse, next: EGAGuardNext) => Promise<void>;
+export declare const ega: Readonly<{
+    guard: typeof createGuard;
+}>;
+export {};