/** * D13 adoption of the AIWG effect ledger (#2721, answers #2677). * * `LedgerReviewEffectJournal` implements `VerifiedReviewEffectLedger` (and the * `ReviewEffectJournal` write port used by `journaledReviewExecutor`) over the * signed effect ledger in `src/effects`. It keeps D13's effect identity exactly: * the `d13.review/v1` derivation is `reviewDigest({reviewId, continuationId, * proposalVersion})`, so reviews persisted before the ledger stay valid. * * Target systems remain the authorities. The ledger records a signed `intent` * before the effect and `completed` only after the `decision.review.continuation` * verifier reports `present`; `absent` and `unknown` never authorize a replay. * * @see docs/decision/review.md "Effect ledger" * @see docs/contracts/effect-ledger.v1.md */ import { EffectLedger, type EffectVerifier, type EffectVerifierRegistry, type LedgerKeyProvider, type ReviewContinuationVerifierOptions } from '../../effects/index.js'; import type { CheckpointSink } from '../../effects/checkpoint-sinks.js'; import type { ReviewEffectReceipt, ReviewStore } from './types.js'; import type { ReviewEffectQuery, ReviewEffectReconcileOptions, ReviewEffectVerification } from './recovery.js'; import type { FileVerifiedReviewEffectLedger, ReviewEffectIdentity, ReviewEffectJournal, ReviewEffectLinks } from './recovery-adapters.js'; import type { DecisionReview } from './types.js'; export declare const REVIEW_EFFECT_KIND: "decision.review.continuation"; export declare const REVIEW_EFFECT_DERIVATION: "d13.review/v1"; /** `result` of a receipt rebuilt from ledger records when the receipt body was never archived. */ export declare const REVIEW_EFFECT_REFERENCE_SCHEMA: "aiwg.review-effect-reference/v1"; /** Version of the one-shot verifier that imports legacy HMAC receipts (`method: legacy-hmac`). */ export declare const LEGACY_HMAC_IMPORT_VERIFIER_VERSION = "0.2.0"; /** The ledger intent (kind, target, context) for one review continuation. */ export declare function reviewEffectIntent(identity: ReviewEffectIdentity): { kind: "decision.review.continuation"; target: string; context: { reviewId: string; continuationId: string; proposalVersion: number; }; derivation: "d13.review/v1"; }; /** The ledger effect ID for a review continuation; equal to D13's `reviewDigest` identity. */ export declare function reviewEffectId(identity: ReviewEffectIdentity): string; /** * #1567 links for a review continuation: the operator decision event of the * approval of `proposalVersion` (its ID is `reviewOperatorEventId`), plus its * audit `record_hash` when the caller has it. Empty when no approval exists. */ export declare function reviewApprovalLinks(review: Pick, proposalVersion: number, operatorDecisionRecordHash?: string): ReviewEffectLinks; export interface LedgerReviewEffectJournalOptions { /** Defaults to the ledger's registry. It must register `decision.review.continuation`. */ verifiers?: EffectVerifierRegistry; /** Verifier timeout in milliseconds. */ timeoutMs?: number; /** * Review-store and session-index key material. Writes are refused when the * ledger signing key was derived from any of them: the ledger key is * independent of every other D13 key. */ independentOf?: Uint8Array[]; } /** * `VerifiedReviewEffectLedger` backed by the effect ledger. Scope: the ledger's * `{tenant, project}` are the review's `{tenantId, projectId}`, subsystem `review`. */ export declare class LedgerReviewEffectJournal implements ReviewEffectJournal { readonly ledger: EffectLedger; private readonly options; private keysChecked; constructor(ledger: EffectLedger, options?: LedgerReviewEffectJournalOptions); private inScope; private assertIndependentKey; private archivePath; /** The verified intent identity behind a lookup; throws on any mismatch. */ private intentIdentity; private archived; /** Receipt for a signed `completed` record; the archived body when present, else a digest reference. */ completedReceipt(query: ReviewEffectQuery): Promise; /** Append the signed intent before the effect. `pending`: an earlier intent has no outcome yet. */ recordIntent(identity: ReviewEffectIdentity, actionDigest: string, links?: ReviewEffectLinks): Promise<'recorded' | 'pending'>; /** * Reconcile through the kind verifier; every call appends one signed * `reconciled` record and `present` also records `completed`. With no intent * the effect is `unknown` unless the caller supplies the identity and action * digest, in which case the intent is recorded first (a crash before intent). */ reconcileReceipt(query: ReviewEffectQuery, options?: ReviewEffectReconcileOptions): Promise; /** Called by the executor after the effect: verify, then record `completed` only on `present`. */ recordCompleted(query: ReviewEffectQuery, receipt: ReviewEffectReceipt): Promise; /** * Import receipts from the deprecated HMAC journal as `completed` records. * Each is verified by a one-shot `legacy-hmac` verifier over the legacy * journal (evidence `method: legacy-hmac`), and its body is archived so the * same receipt is returned afterwards. Receipts already completed are skipped. */ importLegacyReceipts(legacy: FileVerifiedReviewEffectLedger): Promise<{ imported: number; skipped: number; }>; } /** Factory form of the ledger-backed `VerifiedReviewEffectLedger`. */ export declare function ledgerVerifiedReviewEffectLedger(ledger: EffectLedger, options?: LedgerReviewEffectJournalOptions): LedgerReviewEffectJournal; export interface OpenReviewEffectLedgerOptions { projectDir: string; tenantId: string; projectId: string; /** This process's segment writer ID. */ writer: string; /** The dedicated ledger key (`credentialStoreKeyProvider` in production). */ keyProvider: LedgerKeyProvider; /** The D13 review store the verifier reads. */ store: Pick; /** Host probe for the effect at its own target; see `reviewContinuationVerifier`. */ execution?: ReviewContinuationVerifierOptions['execution']; /** Review-store and session-index key material the ledger key must differ from. */ independentOf?: Uint8Array[]; /** Further verifiers (tracker kinds, `x..`). */ extensions?: EffectVerifier[]; sink?: CheckpointSink; clock?: () => number; timeoutMs?: number; } /** Production wiring: a `review` ledger with the built-in verifiers and the review-store verifier. */ export declare function openReviewEffectLedger(options: OpenReviewEffectLedgerOptions): LedgerReviewEffectJournal; /** * Production `reconcile(effectId)` for `DecisionReviewService.resume`. It * returns a receipt only for a signed `completed` record or a `present` * verifier result under the exact D13 identity; `absent` and `unknown` return * `null`, so the stale continuation stays uncertain and is never replayed. */ export declare function ledgerReviewReconciler(input: { journal: Pick; scope: { tenantId: string; projectId: string; }; reviewId: string; continuationId: string; proposalVersion: number; /** `proposal.actionDigest`; lets a crash before the intent record it late and still reconcile. */ actionDigest?: string; }): (effectId: string) => Promise; //# sourceMappingURL=effect-ledger-adapter.d.ts.map