flowchart TD
    A["Tier 0: Raw Codebase\n(factory/<repo>)"]
    B["Tier 1: Atomic Observations\n(eku_middleware/eku_store/evidence/observations.json)\nExact file path, line range, verbatim snippet,\nlanguage, substrate"]
    C["Tier 2: Repo-Local EKUs\n(eku_middleware/eku_store/repo_ekus/<repo>.json)\nConcrete mechanism, source snippet,\ntest provenance, failure provenance\nEpistemic: REPO_LOCAL"]
    D["Tier 3: Domain EKUs\n(eku_middleware/eku_store/synthesized_queue_ekus.json)\nCross-repository behavioral invariants,\ndesign contracts, falsification audits\nEpistemic: DOMAIN_ABSTRACTION"]
    E["MCP Server\n(esekl mcp)\nProgressively discloses\nTier 1-3 via 20 tools"]
    F["Agent\n(Claude, Codex, AGY, etc.)"]

    A -->|"Mechanical inspection\nAST + grep + test suite link"| B
    B -->|"RepoEKU authoring\nvalidate_evidence_ledger.py"| C
    C -->|"Cross-corpus synthesis\nClaim matrix + keyword groups"| D
    D --> E
    C --> E
    B --> E
    E -->|"JSON-RPC 2.0 / stdio"| F

{
  "mcpServers": {
    "esekl": {
      "command": "npx",
      "args": ["-y", "esekl", "mcp"]
    }
  }
}

[mcp_servers.esekl]
command = "npx"
args = ["-y", "esekl", "mcp"]

{
  "id": "EKU-QUEUE-015",
  "title": "Fenced Domain Result Promotion & Outbox Emission",
  "objectType": "BEHAVIORAL_INVARIANT",
  "claimId": "CLM-015",
  "problem": "A queue can fence stale completion of the job row while still allowing a superseded worker to write authoritative domain results or emit an outbox event.",
  "behavioralInvariant": "Ownership fencing must guard every authoritative side-effecting state mutation, including domain result promotion or outbox emission, not only queue-row completion.",
  "designContract": "Before committing a result row, payment ledger projection, or sendable outbox record, the storage transaction must prove current job ownership by token/generation.",
  "verificationContract": [
    "Worker A owns generation 1 and pauses.",
    "Worker B owns generation 2 and completes.",
    "Worker A attempts domain result promotion and queue completion.",
    "Both stale writes affect zero authoritative rows and emit stale-owner telemetry."
  ],
  "supportingEvidence": ["OBS-BULLMQ-002", "OBS-LITEQUEUE-002"],
  "historicalEvidence": ["HIST-RIVER-003"],
  "corpusStats": {
    "corpusSize": 13,
    "applicable": 7,
    "supports": 2,
    "counterexamples": 3
  }
}

{
  "repoEku": {
    "id": "REKU-RIVER-001",
    "repository": "river",
    "mechanism": "Relational Lock-Free Dequeue (FOR UPDATE SKIP LOCKED)",
    "claim": "PostgreSQL FOR UPDATE SKIP LOCKED allows concurrent worker pools to acquire non-overlapping available jobs without table-level locking.",
    "localContext": "River implements its primary job queue inside PostgreSQL. It relies on FOR UPDATE SKIP LOCKED in its sqlc query to scale Go worker goroutines.",
    "sourceProvenance": {
      "filePath": "riverdriver/riverpgxv5/internal/dbsqlc/river_job.sql",
      "lineRange": [45, 55],
      "queryOrCodeSnippet": "SELECT id, args, attempt, state FROM river_job WHERE state = 'available' ORDER BY priority ASC, scheduled_at ASC LIMIT $1 FOR UPDATE SKIP LOCKED;"
    },
    "testProvenance": {
      "filePath": "internal/jobexecutor/job_executor_test.go",
      "testName": "TestJobExecutor"
    },
    "epistemicStatus": "REPO_LOCAL"
  }
}

{
  "evidenceId": "OBS-BULLMQ-002",
  "type": "OBSERVATION",
  "repository": "taskforcesh/bullmq",
  "commitHash": "c06b51cd3aacd0d9ee65e2544220c89f24d2479c",
  "filePath": "src/commands/moveToFinished-12.lua",
  "lineRange": { "start": 40, "end": 44 },
  "sourceUrl": "https://github.com/taskforcesh/bullmq/blob/c06b51cd3aacd0d9ee65e2544220c89f24d2479c/src/commands/moveToFinished-12.lua#L40-L44",
  "snippetSha256": "4b68e98da6984e1b00ad99e74d1c448bb5bbcb110cb16246473133604f32616f",
  "epistemicStatus": "SOURCE_OBSERVED"
}

{
  "matchingEkus": ["EKU-QUEUE-015", "EKU-QUEUE-016", "EKU-QUEUE-017"],
  "missingInvariants": [
    {
      "invariant": "Storage-Time Lease Evaluation",
      "severity": "CRITICAL",
      "risk": "Caller-supplied VM timestamps allow clock drift across container hosts to cause premature lease expiration or duplicate execution.",
      "recommendedFix": "Use database server time (e.g. clock_timestamp()) exclusively in lease recovery queries."
    }
  ],
  "whatNotToPromise": [
    "Never promise true exactly-once delivery over external network boundaries without partner idempotency keys.",
    "Never promise constant latency during unmetered enterprise batch spikes; enforce admission semaphores and HTTP 429/503."
  ],
  "epistemicClassification": {
    "empiricalEvidenceCount": 8,
    "modelInferredPoints": 2
  }
}

eku_middleware/          npm package root (published as esekl)
  bin/                   CLI and MCP server entry points
  src/                   MCP server implementation
  eku_store/             Static knowledge store — ships bundled inside the package
    evidence/            Atomic observations and historical failure records
    repo_ekus/           Repo-Local EKUs per repository
    synthesized_queue_ekus.json   Cross-corpus Domain EKUs
    claim_matrix.json             Claim-to-corpus coverage matrix
    schema/              JSON schema and specification for RepoEKUs
    release/             factory_repo_lock.json — commit-pinned source provenance
  mcp_contract.md        Full JSON-RPC contract with input/output schemas

analyzer/                Validation scripts (not shipped in npm package)
factory/                 Local raw repository cache for research rounds (git-ignored)