/** * The effect ledger: intent, outcome, reconcile and lookup over per-writer * signed segments, with exclusive-create index files for cross-writer * idempotency (first writer wins). * * The ledger proves what AIWG recorded; it never authorizes or replays an * effect. A missing entry is not evidence that the effect did not happen. * * @see docs/contracts/effect-ledger.v1.md * @see docs/architecture/adr-effect-ledger.md */ import { type CheckpointSink } from './checkpoint-sinks.js'; import { type EffectExitCode } from './errors.js'; import type { LedgerKeyProvider, LedgerSigningKey } from './keys.js'; import { type LedgerPaths } from './store.js'; import { type RunVerifierOptions } from './verifiers/registry.js'; import type { EffectVerifierEvidence, EffectVerifierExpectation, EffectVerifierRegistry } from './verifiers/types.js'; import { type EffectContext, type EffectFailure, type EffectIdDerivationName, type EffectKeyring, type EffectKeyRotationBody, type EffectLinks, type EffectPhase, type EffectScope, type EffectTombstone, type EffectVerification, type EffectVerifierResult, type VerificationResult } from './types.js'; export { createVerifierRegistry } from './verifiers/registry.js'; export type { EffectVerifier, EffectVerifierObservation, EffectVerifierRegistry, EffectVerifierRequest, } from './verifiers/types.js'; export interface OpenEffectLedgerOptions { projectDir: string; /** Host-configured scope. Never derived from model input. */ scope: EffectScope; /** This process's segment writer ID. */ writer: string; /** Required for writes; reads and verification need only public keys. */ keyProvider?: LedgerKeyProvider; /** Epoch milliseconds. */ clock?: () => number; /** Independent checkpoint sink. Defaults to the git ref sink on `projectDir`. */ sink?: CheckpointSink; verifiers?: EffectVerifierRegistry; lockTimeoutMs?: number; } export declare class EffectLedger { readonly projectDir: string; readonly scope: EffectScope; readonly writer: string; readonly sink: CheckpointSink; readonly verifiers: EffectVerifierRegistry; readonly lockTimeoutMs: number; private keyProvider?; private readonly clock; constructor(options: OpenEffectLedgerOptions); /** Resolved on every call, so an artifact root that goes away fails closed (exit 7). */ paths(): LedgerPaths; now(): string; signingKey(): Promise; /** Switch to another key provider, for example after `rotateKey`. */ useKeyProvider(provider: LedgerKeyProvider): void; toJSON(): { scope: EffectScope; writer: string; }; } export declare function openEffectLedger(options: OpenEffectLedgerOptions): EffectLedger; export interface EffectReceipt { effectId: string; idDerivation: EffectIdDerivationName; phase: Exclude; payloadDigest: string; writer: string; seq: number; recordHash: string; /** True when an existing record was returned and nothing was appended. */ idempotent: boolean; exitCode: EffectExitCode; } export interface EffectRecordSummary { phase: EffectPhase; writer: string; seq: number; recordHash: string; recordedAt: string; payloadDigest: string; keyid: string; verification?: EffectVerification; failure?: EffectFailure; tombstone?: EffectTombstone; } export type EffectLookupStatus = 'none' | 'intent' | 'completed' | 'failed' | 'reconciled' | 'tombstoned'; export interface EffectLookup { effectId: string; found: boolean; status: EffectLookupStatus; result?: VerificationResult; kind?: string; target?: string; tombstoned: boolean; records: EffectRecordSummary[]; exitCode: EffectExitCode; } export interface RecordIntentInput { authorizationGrant?: import('./authorization-grant.js').AuthorizationGrant; kind: string; target: string; context: EffectContext; payloadDigest: string; derivation?: EffectIdDerivationName; links?: EffectLinks; } /** * Append a signed `intent` before the effect. The same ID with the same payload * digest returns the first receipt (`idempotent: true`); a different digest is * a conflict (exit 5). Nothing is appended in either case. */ export declare function recordIntent(ledger: EffectLedger, input: RecordIntentInput): Promise; export interface RecordOutcomeInput { phase: 'completed' | 'failed'; payloadDigest: string; /** Required for `completed`; its result must be `present`. */ verification?: EffectVerification; /** Required for `failed`. */ failure?: EffectFailure; links?: EffectLinks; } /** * Append the terminal outcome. The first outcome for an ID wins across writers; * repeating it returns the existing receipt, and a different terminal outcome * or payload digest is a conflict. */ export declare function recordOutcome(ledger: EffectLedger, id: string, input: RecordOutcomeInput): Promise; /** Append one `reconciled` record for one verifier attempt. History is never mutated. */ export declare function recordReconciled(ledger: EffectLedger, id: string, verification: EffectVerification, links?: EffectLinks): Promise; export interface ReconcileOptions extends RunVerifierOptions { /** Defaults to the ledger's registry. */ verifiers?: EffectVerifierRegistry; links?: EffectLinks; /** Caller expectations passed to the verifier (digests and references only). */ expected?: EffectVerifierExpectation; } export interface ReconcileOutcome { result: EffectVerifierResult; /** The appended `reconciled` record. */ receipt: EffectReceipt; /** * For `present`: the `completed` outcome (appended now, or the existing one * when it was already recorded). `null` when the result is not `present` or * a different outcome (`failed`) is already recorded. */ completed: EffectReceipt | null; /** The verifier's structured evidence behind `evidenceDigest`. Never written to the ledger. */ evidence?: EffectVerifierEvidence; } /** * Reconcile one effect through its kind's verifier. Every call appends one * signed `reconciled` record; a `present` result also records `completed` * (first outcome wins). Earlier records are never mutated and the effect is * never replayed. With no registered verifier the result is `unknown` / * `verifier-missing`. */ export declare function reconcileEffect(ledger: EffectLedger, id: string, options?: ReconcileOptions): Promise; /** * Look up everything recorded for an effect ID, merged across writers. Every * returned record is signature- and chain-checked; a failure is exit 6. * A tombstoned record is returned without its target, context or outcome body. */ export declare function lookupEffect(ledger: EffectLedger, id: string): Promise; /** * Create the genesis keyring for the loaded signing key when the ledger has * none, and return the keyring. Fails when the loaded key is not the active key. * Used by `aiwg effect keys init`; ordinary writes create it on first use. */ export declare function initLedgerKeyring(ledger: EffectLedger): Promise; /** The stored keyring (public keys only), or null when the ledger has none. Never needs a signing key. */ export declare function readLedgerKeyring(ledger: EffectLedger): Promise; export interface RotateKeyOptions { effectiveAt?: string; reason?: EffectKeyRotationBody['reason']; } /** * Rotate the ledger key. The rotation is signed by the active (prior) key and * by the successor key; the prior key's window closes at `effectiveAt`. The * ledger handle switches to the successor provider. */ export declare function rotateKey(ledger: EffectLedger, successorProvider: LedgerKeyProvider, options?: RotateKeyOptions): Promise; /** Stable JSON for CLI and API output; never contains key material. */ export declare function effectOutputJson(value: unknown): string; //# sourceMappingURL=ledger.d.ts.map