@sekiban/dcb-runtime 0.2.0

package/dist/allocator/IssuanceLedger.d.ts

@@ -0,0 +1,188 @@
+import type { AllocatedCandidate, AllocationCandidate, ClosedPrefixCertificate } from "./types";
+/**
+ * Minimum age before reconciler may force-tombstone a never-contacted target.
+ * Matches {@link RESERVATION_WINDOW_MS}: the writer has until tag reservation
+ * expiry to acquire; elapsed time is only a trigger to inspect and fence.
+ */
+export declare const ISSUANCE_NEVER_CONTACTED_GRACE_MS = 30000;
+export declare const ISSUANCE_LEDGER_VERSION = 1;
+export declare const ATTEMPT_KEY_PREFIX = "attempt:";
+export declare const ISSUANCE_COUNT_KEY = "issuance:unresolved-count";
+export declare const ISSUANCE_RECOVERY_KEY = "issuance:recovery-schedule";
+export declare const ISSUANCE_MIGRATION_KEY = "issuance:migration";
+export declare const ISSUANCE_MIGRATION_PROOF_PREFIX = "issuance:migration-proof:";
+export declare const ISSUANCE_PREFIX_KEY = "issuance:closed-prefix";
+export declare const LEGACY_INVENTORIED_PREFIX = "issuance:legacy-inventoried:";
+export declare const ENVELOPE_PREFIX = "issuance:envelope:";
+export declare const TARGET_PREFIX = "issuance:target:";
+export declare const ISSUED_INDEX_PREFIX = "issuance:issued:";
+export declare const UNRESOLVED_INDEX_PREFIX = "issuance:unresolved:";
+export declare const DEFAULT_WRITER_EPOCH = 0;
+export declare const MAX_TARGET_TAGS = 32;
+export declare const MAX_TAG_LENGTH = 256;
+export type TargetClosureStatus = "pending" | "installed-and-covered" | "absent-and-irrevocably-fenced";
+export interface IssuanceEnvelope {
+    readonly ledgerVersion: typeof ISSUANCE_LEDGER_VERSION;
+    readonly serviceId: string;
+    readonly allocatorLineageId: string;
+    readonly attemptId: string;
+    readonly candidateIndex: number;
+    readonly eventId: string;
+    readonly suid: string;
+    readonly canonicalTargetTags: readonly string[];
+    readonly pinnedWriterEpoch: number;
+    readonly identityDigest: string;
+    /** Wall time when the envelope was registered; drives never-contacted grace. */
+    readonly issuedAtMs: number;
+}
+export interface TargetClosureRecord {
+    readonly tag: string;
+    status: TargetClosureStatus;
+    readonly envelopeDigest: string;
+}
+export interface IssuanceMigrationState {
+    readonly cutInstalledAt: number;
+    readonly legacyInventoryCursor: string | null;
+    readonly inventoryComplete: boolean;
+    readonly migrationProofId: string | null;
+    readonly legacyInventorySummary?: LegacyInventorySummary;
+}
+export interface IssuanceRecoverySchedule {
+    readonly nextDueAt: number;
+    readonly cursor: string | null;
+    readonly attempts: number;
+}
+export interface AllocationCandidateWithMembership extends AllocationCandidate {
+    readonly targetTags?: readonly string[];
+    readonly pinnedWriterEpoch?: number;
+}
+export interface TagResolutionObservation {
+    readonly terminalStatus: Exclude<TargetClosureStatus, "pending">;
+    readonly obligationDigest?: string;
+    readonly tombstoneEpoch?: number;
+}
+export interface TargetResolutionEvidence {
+    readonly serviceId: string;
+    readonly allocatorLineageId: string;
+    readonly attemptId: string;
+    readonly candidateIndex: number;
+    readonly suid: string;
+    readonly tag: string;
+    readonly identityDigest: string;
+    readonly pinnedWriterEpoch: number;
+    readonly tagObservation: TagResolutionObservation;
+}
+export type LegacyAttemptClassification = "legacy-vector-only" | "legacy-resolved-registration" | "legacy-unresolved-registration" | "legacy-unclassifiable-blocking";
+export interface LegacyInventoryRecord {
+    readonly inventoriedAt: number;
+    readonly classification: LegacyAttemptClassification;
+    readonly reason: string;
+}
+export interface LegacyInventorySummary {
+    readonly vectorOnly: number;
+    readonly resolvedRegistration: number;
+    readonly unresolvedRegistration: number;
+    readonly unclassifiableBlocking: number;
+}
+export declare class IssuanceLedgerError extends Error {
+    constructor(message: string);
+}
+export declare function canonicalizeTargetTags(tags: readonly string[]): readonly string[];
+export declare function identityDigest(input: {
+    serviceId: string;
+    allocatorLineageId: string;
+    attemptId: string;
+    candidateIndex: number;
+    eventId: string;
+    suid: string;
+    canonicalTargetTags: readonly string[];
+    pinnedWriterEpoch: number;
+}): string;
+export declare function envelopeKey(attemptId: string, candidateIndex: number): string;
+export declare function targetKey(attemptId: string, candidateIndex: number, tag: string): string;
+export declare function issuedIndexKey(suid: string, attemptId: string, candidateIndex: number): string;
+export declare function unresolvedIndexKey(suid: string, attemptId: string, candidateIndex: number): string;
+export declare function parseIndexEntry(key: string, prefix: string): {
+    suid: string;
+    attemptId: string;
+    candidateIndex: number;
+} | undefined;
+export declare function buildEnvelope(input: {
+    serviceId: string;
+    allocatorLineageId: string;
+    attemptId: string;
+    candidate: AllocatedCandidate;
+    targetTags: readonly string[];
+    pinnedWriterEpoch: number;
+    issuedAtMs: number;
+}): IssuanceEnvelope;
+export declare function membershipMatches(left: readonly string[], right: readonly string[]): boolean;
+export declare function registerIssuanceInTransaction(txn: DurableObjectTransaction, input: {
+    serviceId: string;
+    allocatorLineageId: string;
+    attemptId: string;
+    candidates: readonly AllocatedCandidate[];
+    candidateMembership: ReadonlyMap<number, {
+        tags: readonly string[];
+        pinnedWriterEpoch: number;
+    }>;
+    migration: IssuanceMigrationState | undefined;
+}): Promise<void>;
+/** Arm when a recovery schedule exists and reconciliation is due (or overdue). */
+export declare function shouldArmIssuanceRecovery(schedule: IssuanceRecoverySchedule | undefined, now: number): boolean;
+export declare const ISSUANCE_RECOVERY_ALARM_ARMED_KEY = "issuance:recovery-alarm-armed-at";
+type RecoveryAlarmStorage = Pick<DurableObjectStorage, "get" | "getAlarm" | "setAlarm" | "deleteAlarm" | "put" | "list">;
+/**
+ * Align the durable recovery alarm with {@link ISSUANCE_RECOVERY_KEY}.nextDueAt without
+ * pushing a pending earlier alarm later while work remains outstanding.
+ */
+export declare function syncIssuanceRecoveryAlarm(storage: RecoveryAlarmStorage, now: number): Promise<void>;
+type IssuanceIndexReader = Pick<DurableObjectStorage, "list">;
+export declare function countUnresolvedEntries(reader: IssuanceIndexReader): Promise<number>;
+export declare function leastUnresolvedEntry(reader: IssuanceIndexReader): Promise<{
+    suid: string;
+    attemptId: string;
+    candidateIndex: number;
+} | undefined>;
+export declare function predecessorIssuedSuid(reader: IssuanceIndexReader, exclusiveSuid: string): Promise<string | null>;
+export declare function computeClosedPrefixSuid(reader: IssuanceIndexReader, txn: DurableObjectTransaction, allocatedWatermark: string | null, migration: IssuanceMigrationState | undefined): Promise<{
+    closedPrefixSuid: string | null;
+    unresolvedCount: number;
+    status: "ready" | "unreconciled";
+}>;
+export declare function buildCertificateSnapshot(reader: IssuanceIndexReader, txn: DurableObjectTransaction, input: {
+    serviceId: string;
+    allocatorLineageId: string;
+    allocatedWatermark: string | null;
+    generatedAt: number;
+}): Promise<ClosedPrefixCertificate>;
+export declare function parseTargetResolutionEvidence(raw: unknown): TargetResolutionEvidence;
+export declare function applyTargetResolution(txn: DurableObjectTransaction, evidence: TargetResolutionEvidence): Promise<{
+    candidateResolved: boolean;
+    duplicate: boolean;
+}>;
+export declare function registrationProbe(txn: DurableObjectTransaction, attemptId: string, candidateIndex: number): Promise<{
+    envelope: boolean;
+    unresolvedIndex: boolean;
+    issuedIndex: boolean;
+    exactCount: boolean;
+    recoverySchedule: boolean;
+}>;
+type StorageListReader = Pick<DurableObjectStorage, "list">;
+export declare function pageLegacyInventoryInTransaction(txn: DurableObjectTransaction, input: {
+    pageSize: number;
+    faultInjection?: "after-cursor-persist";
+}, reader?: StorageListReader): Promise<{
+    pageCount: number;
+    nextCursor: string | null;
+    inventoryComplete: boolean;
+}>;
+export declare function completeMigrationProofInTransaction(txn: DurableObjectTransaction, input: {
+    migrationProofId: string;
+    boundEvidence: Record<string, unknown>;
+}): Promise<void>;
+export declare function parseCandidateMembership(raw: unknown): {
+    tags: readonly string[];
+    pinnedWriterEpoch: number;
+} | undefined;
+export {};