/**
 * Three-stage deterministic execution:
 *   Stage 1 — verify token signature and runtime compatibility
 *   Stage 2 — enforce decision (approve / reject / pending_override)
 *   Stage 3 — sign the ExecutionAttestation with context.signer
 *
 * Does NOT do replay protection — callers (executeFromSignals) must guard.
 */
async function executeDecision(context: ExecutionContext): Promise<ExecutionAttestation>

/**
 * Confirm that a real-world executed action matches its governance authorization.
 * Returns an ExecutionIntegrityProof signed by context.signer.
 */
async function confirmExecution(options: {
  attestation: ExecutionAttestation;
  executedAction: ExecutedAction;
  signer: Signer;
  verifier: Verifier;
  publicKey: string;
  timeWindowSeconds?: number;
}): Promise<ExecutionIntegrityProof>

/**
 * Evaluate a compiled policy against a signal map.
 * Returns DecisionResult with status "decided" and the matching rule's outcome.
 * Throws [SYS-006] if no rule matches (fail-closed — no silent pass).
 */
function evaluatePolicy(
  policy: CompiledPolicy,
  signals: Record<string, unknown>
): DecisionResult

/**
 * Issue a deterministic ExecutionToken from a decision payload.
 * The token is the governance event — it is signed and embedded in the attestation.
 */
function issueToken(input: {
  executionId: string;
  policyId: string;
  policyVersion: string;
  schemaVersion: string;
  runtimeVersion: string;
  decision_payload: DecisionOutcome;
  signalsHash: string;
}): ExecutionToken

/** Verify a base64-encoded token signature. Returns true if valid. */
async function verifyExecutionToken(
  token: ExecutionToken,
  signature: string,
  verifier: Verifier
): Promise<boolean>

/** Return the static runtime manifest embedded in this package at build time. */
function getRuntimeManifest(): RuntimeManifest

/** Sign a runtime manifest with a Signer. Returns the signature string. */
async function signRuntimeManifest(manifest: RuntimeManifest, signer: Signer): Promise<string>

/** Verify a runtime manifest against its signature. */
async function verifyRuntimeManifest(
  manifest: RuntimeManifest,
  signature: string,
  verifier: Verifier
): Promise<boolean>

/** Local Ed25519 signer backed by a PEM private key string. */
class LocalSigner implements Signer {
  constructor(privateKeyPem: string)
  async sign(payload: string): Promise<string>
}

/** Local Ed25519 verifier backed by a PEM public key string. */
class LocalVerifier implements Verifier {
  constructor(publicKeyPem: string)
  async verify(payload: string, signature: string): Promise<boolean>
}

interface Signer   { sign(payload: string): Promise<string> }
interface Verifier { verify(payload: string, signature: string): Promise<boolean> }

interface ReplayStore {
  hasExecuted?(id: string): Promise<boolean>;
  markExecuted?(id: string): Promise<void>;
  consume?(id: string): Promise<boolean>;
  reserve?(id: string): Promise<void>;
  startExecution?(id: string): Promise<void>;
  confirm?(id: string): Promise<void>;
  fail?(id: string): Promise<void>;
}

import { ErrorCodes } from "@parmanasystems/execution";
// ErrorCodes.INV_013  — "INV-013" replay detected
// ErrorCodes.VAL_003  — unknown signal
// ErrorCodes.VAL_004  — required signal missing
// ErrorCodes.SIG_001  — invalid token signature
// ErrorCodes.POL_001  — policy.json not found
// ... (full registry in packages/execution/src/error-codes.ts)

interface ExecutionAttestation {
  executionId: string;
  execution_fingerprint: string;
  policyId: string;
  policyVersion: string;
  schemaVersion: string;
  runtimeVersion: string;
  signalsHash: string;
  decision: { action: "approve" | "reject"; requires_override: boolean; reason?: string };
  execution_state: "completed" | "blocked" | "pending_override";
  runtimeHash: string;
  provenance: {
    provenanceVersion: string;
    bundleHash: string;
    manifestHash: string;
    manifestSignature: string;
    trustRootVersion: string;
    signerKeyId: string;
    evaluatorSemanticHash: string;
    evaluatorArtifactHash?: string;
    evaluatorHash: string;  // deprecated alias for evaluatorSemanticHash
    releaseManifestHash: string;
  };
  signature: string;
}

interface ExecutionContext {
  token: ExecutionToken;
  execution_fingerprint: string;
  token_signature: string;
  signer: Signer;
  verifier: Verifier;
  runtime_manifest: RuntimeManifest;
  runtimeRequirements: RuntimeRequirements;
  provenance: ExecutionAttestation["provenance"];
  auditMode?: boolean;
}

interface RuntimeManifest {
  runtimeVersion: string;
  runtimeHash: string;
  capabilities: readonly string[];
  supportedSchemaVersions: readonly string[];
}