@sekiban/dcb-runtime 0.2.0 → 0.2.1

package/dist/completeness/IncidentLifecycle.js

@@ -0,0 +1,503 @@
+const MAX_IDENTITY_BYTES = 256;
+const MAX_LONG_TEXT_BYTES = 2_048;
+const SHA256_DIGEST = /^sha256:[0-9a-f]{64}$/;
+const LIFECYCLE_STATES = [
+    "OPEN",
+    "ACKNOWLEDGED",
+    "CORRECTION_RECORDED",
+    "CLOSED",
+    "REOPENED",
+];
+export class IncidentLifecycleError extends Error {
+    code;
+    status;
+    constructor(code, status, message) {
+        super(message);
+        this.name = "IncidentLifecycleError";
+        this.code = code;
+        this.status = status;
+    }
+}
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function hasOnlyKeys(value, keys) {
+    const allowed = new Set(keys);
+    return Object.keys(value).every((key) => allowed.has(key));
+}
+function bytes(value) {
+    return new TextEncoder().encode(value).byteLength;
+}
+function boundedString(value, name, maximum, required = true) {
+    if (typeof value !== "string") {
+        throw new IncidentLifecycleError("incident_invalid_request", 400, `${name} must be a string`);
+    }
+    const normalized = value.trim();
+    if (required && normalized.length === 0) {
+        throw new IncidentLifecycleError("incident_invalid_request", 400, `${name} must be non-empty`);
+    }
+    if (bytes(normalized) > maximum) {
+        throw new IncidentLifecycleError("incident_invalid_request", 400, `${name} is too long`);
+    }
+    return normalized.length === 0 ? null : normalized;
+}
+export function normalizeIncidentIdentity(value) {
+    const identity = boundedString(value, "incidentIdentity", MAX_IDENTITY_BYTES);
+    if (identity === null) {
+        throw new IncidentLifecycleError("incident_invalid_request", 400, "incidentIdentity must be non-empty");
+    }
+    return identity;
+}
+function safeInteger(value, name) {
+    if (typeof value !== "number" || !Number.isSafeInteger(value)) {
+        throw new IncidentLifecycleError("incident_invalid_request", 400, `${name} must be a safe integer`);
+    }
+    return value;
+}
+function normalizeCorrection(value) {
+    if (!isObject(value) || !hasOnlyKeys(value, ["kind", "reference", "digest"])) {
+        throw new IncidentLifecycleError("incident_invalid_request", 400, "correction has unknown or missing keys");
+    }
+    if (value.kind !== "event" && value.kind !== "receipt") {
+        throw new IncidentLifecycleError("incident_invalid_request", 400, "correction.kind must be event or receipt");
+    }
+    const reference = boundedString(value.reference, "correction.reference", MAX_LONG_TEXT_BYTES);
+    const digest = boundedString(value.digest, "correction.digest", MAX_IDENTITY_BYTES);
+    if (reference === null || digest === null || !SHA256_DIGEST.test(digest)) {
+        throw new IncidentLifecycleError("incident_invalid_request", 400, "correction.digest must be lowercase sha256");
+    }
+    return { kind: value.kind, reference, digest: digest };
+}
+function normalizeRequest(value) {
+    if (!isObject(value) || !hasOnlyKeys(value, ["action", "incidentIdentity", "transitionKey", "expectedVersion", "reason", "ownerId", "deadlineAt", "correction", "resolution"])) {
+        throw new IncidentLifecycleError("incident_invalid_request", 400, "transition has unknown keys");
+    }
+    const action = value.action;
+    if (typeof action !== "string" || !["ACKNOWLEDGE", "UPDATE_ASSIGNMENT", "RECORD_CORRECTION", "CLOSE", "REOPEN"].includes(action)) {
+        throw new IncidentLifecycleError("incident_invalid_request", 400, "transition action is invalid");
+    }
+    const actionKeys = action === "RECORD_CORRECTION"
+        ? ["action", "incidentIdentity", "transitionKey", "expectedVersion", "reason", "correction"]
+        : action === "CLOSE"
+            ? ["action", "incidentIdentity", "transitionKey", "expectedVersion", "reason", "resolution"]
+            : ["action", "incidentIdentity", "transitionKey", "expectedVersion", "reason", "ownerId", "deadlineAt"];
+    if (!hasOnlyKeys(value, actionKeys)) {
+        throw new IncidentLifecycleError("incident_invalid_request", 400, "transition has keys not valid for its action");
+    }
+    const base = {
+        incidentIdentity: normalizeIncidentIdentity(value.incidentIdentity),
+        transitionKey: boundedString(value.transitionKey, "transitionKey", MAX_IDENTITY_BYTES),
+        expectedVersion: safeInteger(value.expectedVersion, "expectedVersion"),
+        reason: boundedString(value.reason, "reason", MAX_LONG_TEXT_BYTES),
+    };
+    if (base.expectedVersion < 0) {
+        throw new IncidentLifecycleError("incident_invalid_request", 400, "expectedVersion must not be negative");
+    }
+    if (action === "ACKNOWLEDGE" || action === "UPDATE_ASSIGNMENT" || action === "REOPEN") {
+        const ownerId = boundedString(value.ownerId, "ownerId", MAX_IDENTITY_BYTES);
+        const deadlineAt = safeInteger(value.deadlineAt, "deadlineAt");
+        if (ownerId === null)
+            throw new IncidentLifecycleError("incident_invalid_request", 400, "ownerId must be non-empty");
+        return { ...base, action, ownerId, deadlineAt };
+    }
+    if (action === "RECORD_CORRECTION") {
+        return { ...base, action, correction: normalizeCorrection(value.correction) };
+    }
+    if (!isObject(value.resolution) || !hasOnlyKeys(value.resolution, ["kind", "explanation"])) {
+        throw new IncidentLifecycleError("incident_invalid_request", 400, "resolution has unknown or missing keys");
+    }
+    if (value.resolution.kind === "CORRECTED") {
+        if (value.resolution.explanation !== undefined) {
+            throw new IncidentLifecycleError("incident_invalid_request", 400, "CORRECTED resolution has unknown keys");
+        }
+        return { ...base, action, resolution: { kind: "CORRECTED" } };
+    }
+    if (value.resolution.kind === "ACCEPTED_AS_IS") {
+        const explanation = boundedString(value.resolution.explanation, "resolution.explanation", MAX_LONG_TEXT_BYTES);
+        if (explanation === null)
+            throw new IncidentLifecycleError("incident_invalid_request", 400, "resolution.explanation is required");
+        return { ...base, action, resolution: { kind: "ACCEPTED_AS_IS", explanation } };
+    }
+    throw new IncidentLifecycleError("incident_invalid_request", 400, "resolution.kind is invalid");
+}
+function canonicalize(value) {
+    if (Array.isArray(value))
+        return value.map(canonicalize);
+    if (!isObject(value))
+        return value;
+    return Object.fromEntries(Object.keys(value).sort().map((key) => [key, canonicalize(value[key])]));
+}
+async function digestFor(request, actorId) {
+    const envelope = canonicalize({ action: request, actor: actorId });
+    const encoded = new TextEncoder().encode(JSON.stringify(envelope));
+    const digest = await crypto.subtle.digest("SHA-256", encoded);
+    return `sha256:${Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("")}`;
+}
+function projectionFromRow(row, finding) {
+    if (row === null) {
+        return {
+            serviceId: finding.service_id,
+            incidentIdentity: finding.incident_identity,
+            lifecycleState: "OPEN",
+            ownerId: null,
+            deadlineAt: null,
+            correction: null,
+            closeResolution: null,
+            closeReason: null,
+            version: 0,
+            lastTransitionKey: "",
+            updatedAt: finding.last_observed_at,
+        };
+    }
+    return {
+        serviceId: row.service_id,
+        incidentIdentity: row.incident_identity,
+        lifecycleState: row.lifecycle_state,
+        ownerId: row.owner_id,
+        deadlineAt: row.deadline_at,
+        correction: row.correction_kind === null ? null : {
+            kind: row.correction_kind,
+            reference: row.correction_reference,
+            digest: row.correction_digest,
+        },
+        closeResolution: row.close_resolution,
+        closeReason: row.close_reason,
+        version: row.version,
+        lastTransitionKey: row.last_transition_key,
+        updatedAt: row.updated_at,
+    };
+}
+function findingFromRow(row) {
+    return {
+        serviceId: row.service_id,
+        incidentIdentity: row.incident_identity,
+        incidentType: row.incident_type,
+        partitionTag: row.partition_tag,
+        obligationSequence: row.obligation_sequence,
+        eventId: row.event_id,
+        eventDigest: row.event_digest,
+        state: row.finding_state,
+        firstObservedAt: row.first_observed_at,
+        lastObservedAt: row.last_observed_at,
+    };
+}
+function transitionFromRow(row) {
+    const before = projectionFromAudit(row, "before");
+    const after = projectionFromAudit(row, "after");
+    return {
+        transitionId: row.transition_id,
+        serviceId: row.service_id,
+        incidentIdentity: row.incident_identity,
+        transitionKey: row.transition_key,
+        requestDigest: row.request_digest,
+        action: row.action,
+        fromState: row.from_state,
+        toState: row.to_state,
+        fromVersion: row.from_version,
+        toVersion: row.to_version,
+        actorId: row.actor_id,
+        before,
+        after,
+        reason: row.reason,
+        occurredAt: row.occurred_at,
+    };
+}
+function projectionFromAudit(row, prefix) {
+    const state = prefix === "before" ? row.from_state : row.to_state;
+    const version = prefix === "before" ? row.from_version : row.to_version;
+    const ownerId = row[`${prefix}_owner_id`];
+    const correctionKind = row[`${prefix}_correction_kind`];
+    return {
+        serviceId: row.service_id,
+        incidentIdentity: row.incident_identity,
+        lifecycleState: state,
+        ownerId,
+        deadlineAt: row[`${prefix}_deadline_at`],
+        correction: correctionKind === null ? null : {
+            kind: correctionKind,
+            reference: row[`${prefix}_correction_reference`],
+            digest: row[`${prefix}_correction_digest`],
+        },
+        closeResolution: row[`${prefix}_close_resolution`],
+        closeReason: row[`${prefix}_close_reason`],
+        version,
+        lastTransitionKey: prefix === "after" ? row.transition_key : "",
+        updatedAt: row.occurred_at,
+    };
+}
+function active(state) {
+    return state !== "CLOSED";
+}
+function compareItems(left, right) {
+    if (left.overdue !== right.overdue)
+        return left.overdue ? -1 : 1;
+    if (left.unowned !== right.unowned)
+        return left.unowned ? -1 : 1;
+    if (left.finding.lastObservedAt !== right.finding.lastObservedAt)
+        return right.finding.lastObservedAt - left.finding.lastObservedAt;
+    return left.finding.incidentIdentity < right.finding.incidentIdentity ? -1 : left.finding.incidentIdentity > right.finding.incidentIdentity ? 1 : 0;
+}
+export class IncidentLifecycle {
+    database;
+    now;
+    constructor(database, now = () => Date.now()) {
+        this.database = database;
+        this.now = now;
+    }
+    static parseTransition(value) {
+        return normalizeRequest(value);
+    }
+    async finding(serviceId, incidentIdentity) {
+        const row = await this.database.prepare(`SELECT service_id, incident_identity, incident_type, partition_tag,
+              obligation_sequence, event_id, event_digest, state AS finding_state,
+              first_observed_at, last_observed_at
+         FROM serialized_dcb_completeness_findings
+        WHERE service_id = ? AND incident_identity = ?`).bind(serviceId, incidentIdentity).first();
+        if (row === null || row === undefined) {
+            throw new IncidentLifecycleError("incident_not_found", 404, "The completeness incident was not found");
+        }
+        return row;
+    }
+    async lifecycle(serviceId, incidentIdentity) {
+        const row = await this.database.prepare(`SELECT service_id, incident_identity, lifecycle_state, owner_id, deadline_at,
+              correction_kind, correction_reference, correction_digest,
+              close_resolution, close_reason, version, last_transition_key, updated_at
+         FROM serialized_dcb_incident_lifecycles
+        WHERE service_id = ? AND incident_identity = ?`).bind(serviceId, incidentIdentity).first();
+        return row === undefined ? null : row;
+    }
+    async transitions(serviceId, incidentIdentity) {
+        const result = await this.database.prepare(`SELECT * FROM serialized_dcb_incident_transitions
+        WHERE service_id = ? AND incident_identity = ?
+        ORDER BY transition_id ASC`).bind(serviceId, incidentIdentity).all();
+        return result.results.map(transitionFromRow);
+    }
+    async closeTime(serviceId, incidentIdentity) {
+        const row = await this.database.prepare(`SELECT occurred_at FROM serialized_dcb_incident_transitions
+        WHERE service_id = ? AND incident_identity = ? AND to_state = 'CLOSED'
+        ORDER BY transition_id DESC LIMIT 1`).bind(serviceId, incidentIdentity).first();
+        return row?.occurred_at ?? null;
+    }
+    async item(finding, row, at) {
+        const lifecycle = projectionFromRow(row, finding);
+        const closeTime = lifecycle.lifecycleState === "OPEN" && row === null ? null : await this.closeTime(finding.service_id, finding.incident_identity);
+        const observedAfterClose = closeTime !== null && finding.last_observed_at > closeTime;
+        const overdue = active(lifecycle.lifecycleState) && lifecycle.deadlineAt !== null && lifecycle.deadlineAt < at;
+        return {
+            finding: findingFromRow(finding),
+            lifecycle,
+            overdue,
+            unowned: lifecycle.ownerId === null,
+            observedAfterClose,
+        };
+    }
+    async list(serviceId, filters = {}, at = this.now()) {
+        const rows = await this.database.prepare(`SELECT service_id, incident_identity, incident_type, partition_tag,
+              obligation_sequence, event_id, event_digest, state AS finding_state,
+              first_observed_at, last_observed_at
+         FROM serialized_dcb_completeness_findings
+        WHERE service_id = ?`).bind(serviceId).all();
+        const items = [];
+        for (const finding of rows.results) {
+            const item = await this.item(finding, await this.lifecycle(serviceId, finding.incident_identity), at);
+            if (filters.state !== undefined && item.lifecycle.lifecycleState !== filters.state)
+                continue;
+            if (filters.owner !== undefined && item.lifecycle.ownerId !== filters.owner)
+                continue;
+            if (filters.unowned === true && !item.unowned)
+                continue;
+            if (filters.overdue === true && !item.overdue)
+                continue;
+            if (filters.observedAfterClose === true && !item.observedAfterClose)
+                continue;
+            items.push(item);
+        }
+        items.sort(compareItems);
+        const byState = {
+            OPEN: 0, ACKNOWLEDGED: 0, CORRECTION_RECORDED: 0, CLOSED: 0, REOPENED: 0,
+        };
+        for (const item of items)
+            byState[item.lifecycle.lifecycleState] += 1;
+        return {
+            items,
+            summary: {
+                total: items.length,
+                byState,
+                unowned: items.filter((item) => item.unowned).length,
+                overdue: items.filter((item) => item.overdue).length,
+                observedAfterClose: items.filter((item) => item.observedAfterClose).length,
+            },
+        };
+    }
+    async detail(serviceId, incidentIdentity, at = this.now()) {
+        const finding = await this.finding(serviceId, incidentIdentity);
+        const lifecycle = await this.lifecycle(serviceId, incidentIdentity);
+        const item = await this.item(finding, lifecycle, at);
+        return {
+            finding: item.finding,
+            lifecycle: item.lifecycle,
+            flags: { overdue: item.overdue, unowned: item.unowned, observedAfterClose: item.observedAfterClose },
+            transitions: await this.transitions(serviceId, incidentIdentity),
+        };
+    }
+    async transition(serviceId, value, actor) {
+        const request = normalizeRequest(value);
+        let actorId;
+        try {
+            actorId = boundedString(actor, "x-sdt-maintainer", MAX_IDENTITY_BYTES);
+        }
+        catch (caught) {
+            if (caught instanceof IncidentLifecycleError && caught.code === "incident_invalid_request") {
+                throw new IncidentLifecycleError("incident_invalid_actor", 400, caught.message);
+            }
+            throw caught;
+        }
+        if (actorId === null)
+            throw new IncidentLifecycleError("incident_invalid_actor", 400, "x-sdt-maintainer must be non-empty");
+        const finding = await this.finding(serviceId, request.incidentIdentity);
+        const digest = await digestFor(request, actorId);
+        const existing = await this.database.prepare(`SELECT * FROM serialized_dcb_incident_transitions
+        WHERE service_id = ? AND incident_identity = ? AND transition_key = ?`).bind(serviceId, request.incidentIdentity, request.transitionKey).first();
+        if (existing !== null && existing !== undefined) {
+            if (existing.request_digest !== digest) {
+                throw new IncidentLifecycleError("incident_idempotency_conflict", 409, "The transition key was already used with different content");
+            }
+            return { projection: transitionFromRow(existing).after, transition: transitionFromRow(existing), idempotent: true };
+        }
+        const priorRow = await this.lifecycle(serviceId, request.incidentIdentity);
+        const before = projectionFromRow(priorRow, finding);
+        if (before.version !== request.expectedVersion) {
+            throw new IncidentLifecycleError("incident_version_conflict", 409, "The incident version is stale");
+        }
+        const at = this.now();
+        const after = this.nextProjection(before, request, at);
+        const newVersion = before.version + 1;
+        const occurredAt = at;
+        const seed = this.database.prepare(`INSERT INTO serialized_dcb_incident_lifecycles
+         (service_id, incident_identity, lifecycle_state, version, last_transition_key, updated_at)
+       VALUES (?, ?, 'OPEN', 0, '', ?)
+       ON CONFLICT (service_id, incident_identity) DO NOTHING`).bind(serviceId, request.incidentIdentity, occurredAt);
+        const update = this.database.prepare(`UPDATE serialized_dcb_incident_lifecycles
+          SET lifecycle_state = ?, owner_id = ?, deadline_at = ?,
+              correction_kind = ?, correction_reference = ?, correction_digest = ?,
+              close_resolution = ?, close_reason = ?, version = ?,
+              last_transition_key = ?, updated_at = ?
+        WHERE service_id = ? AND incident_identity = ? AND version = ?
+          AND last_transition_key <> ?`).bind(after.lifecycleState, after.ownerId, after.deadlineAt, after.correction?.kind ?? null, after.correction?.reference ?? null, after.correction?.digest ?? null, after.closeResolution, after.closeReason, newVersion, request.transitionKey, occurredAt, serviceId, request.incidentIdentity, before.version, request.transitionKey);
+        const audit = this.database.prepare(`INSERT INTO serialized_dcb_incident_transitions
+         (service_id, incident_identity, transition_key, request_digest, action,
+          from_state, to_state, from_version, to_version, actor_id,
+          before_owner_id, before_deadline_at, before_correction_kind,
+          before_correction_reference, before_correction_digest, before_close_resolution,
+          before_close_reason, after_owner_id, after_deadline_at, after_correction_kind,
+          after_correction_reference, after_correction_digest, after_close_resolution,
+          after_close_reason, reason, occurred_at)
+       SELECT ?, ?, ?, ?, ?, ?, lifecycle_state, ?, version, ?,
+              ?, ?, ?, ?, ?, ?, ?, owner_id, deadline_at, correction_kind,
+              correction_reference, correction_digest, close_resolution, close_reason, ?, ?
+         FROM serialized_dcb_incident_lifecycles
+        WHERE service_id = ? AND incident_identity = ? AND version = ? AND last_transition_key = ?`).bind(serviceId, request.incidentIdentity, request.transitionKey, digest, request.action, before.lifecycleState, before.version, actorId, before.ownerId, before.deadlineAt, before.correction?.kind ?? null, before.correction?.reference ?? null, before.correction?.digest ?? null, before.closeResolution, before.closeReason, request.reason, occurredAt, serviceId, request.incidentIdentity, newVersion, request.transitionKey);
+        await this.database.batch([seed, update, audit]);
+        const inserted = await this.database.prepare(`SELECT * FROM serialized_dcb_incident_transitions
+        WHERE service_id = ? AND incident_identity = ? AND transition_key = ?`).bind(serviceId, request.incidentIdentity, request.transitionKey).first();
+        if (inserted === null || inserted === undefined) {
+            const competing = await this.database.prepare(`SELECT * FROM serialized_dcb_incident_transitions
+          WHERE service_id = ? AND incident_identity = ? AND transition_key = ?`).bind(serviceId, request.incidentIdentity, request.transitionKey).first();
+            if (competing !== null && competing !== undefined && competing.request_digest !== digest) {
+                throw new IncidentLifecycleError("incident_idempotency_conflict", 409, "The transition key was already used with different content");
+            }
+            if (competing !== null && competing !== undefined) {
+                const transition = transitionFromRow(competing);
+                return { projection: transition.after, transition, idempotent: true };
+            }
+            throw new IncidentLifecycleError("incident_version_conflict", 409, "The incident version is stale");
+        }
+        const transition = transitionFromRow(inserted);
+        return { projection: transition.after, transition, idempotent: false };
+    }
+    nextProjection(before, request, at) {
+        const laterDeadline = (deadlineAt) => {
+            if (deadlineAt <= at)
+                throw new IncidentLifecycleError("incident_invalid_deadline", 400, "deadlineAt must be in the future");
+            return deadlineAt;
+        };
+        let lifecycleState;
+        let ownerId = before.ownerId;
+        let deadlineAt = before.deadlineAt;
+        let correction = before.correction;
+        let closeResolution = before.closeResolution;
+        let closeReason = before.closeReason;
+        if (request.action === "ACKNOWLEDGE") {
+            if (before.lifecycleState !== "OPEN" && before.lifecycleState !== "REOPENED") {
+                throw new IncidentLifecycleError("incident_invalid_transition", 409, "The incident cannot be acknowledged from its current state");
+            }
+            lifecycleState = "ACKNOWLEDGED";
+            ownerId = request.ownerId;
+            deadlineAt = laterDeadline(request.deadlineAt);
+            correction = null;
+            closeResolution = null;
+            closeReason = null;
+        }
+        else if (request.action === "UPDATE_ASSIGNMENT") {
+            if (before.lifecycleState !== "ACKNOWLEDGED" && before.lifecycleState !== "CORRECTION_RECORDED") {
+                throw new IncidentLifecycleError("incident_invalid_transition", 409, "The incident cannot be reassigned from its current state");
+            }
+            lifecycleState = before.lifecycleState;
+            ownerId = request.ownerId;
+            deadlineAt = laterDeadline(request.deadlineAt);
+        }
+        else if (request.action === "RECORD_CORRECTION") {
+            if (before.lifecycleState !== "ACKNOWLEDGED") {
+                throw new IncidentLifecycleError("incident_invalid_transition", 409, "The incident must be acknowledged before correction evidence");
+            }
+            lifecycleState = "CORRECTION_RECORDED";
+            correction = request.correction;
+        }
+        else if (request.action === "CLOSE") {
+            if (before.ownerId === null || before.deadlineAt === null) {
+                throw new IncidentLifecycleError("incident_invalid_transition", 409, "The incident must have an owner and deadline before closure");
+            }
+            if (request.resolution.kind === "CORRECTED") {
+                if (before.lifecycleState !== "CORRECTION_RECORDED") {
+                    throw new IncidentLifecycleError("incident_invalid_transition", 409, "A corrected closure requires recorded correction evidence");
+                }
+                lifecycleState = "CLOSED";
+                closeResolution = "CORRECTED";
+                closeReason = request.reason;
+            }
+            else {
+                if (before.lifecycleState !== "ACKNOWLEDGED") {
+                    throw new IncidentLifecycleError("incident_invalid_transition", 409, "Accepted-as-is closure requires an acknowledged incident");
+                }
+                lifecycleState = "CLOSED";
+                closeResolution = "ACCEPTED_AS_IS";
+                closeReason = request.resolution.explanation;
+                correction = null;
+            }
+        }
+        else {
+            if (before.lifecycleState !== "CLOSED") {
+                throw new IncidentLifecycleError("incident_invalid_transition", 409, "Only a closed incident can be reopened");
+            }
+            lifecycleState = "REOPENED";
+            ownerId = request.ownerId;
+            deadlineAt = laterDeadline(request.deadlineAt);
+            correction = null;
+            closeResolution = null;
+            closeReason = null;
+        }
+        return {
+            ...before,
+            lifecycleState,
+            ownerId,
+            deadlineAt,
+            correction,
+            closeResolution,
+            closeReason,
+            version: before.version + 1,
+            lastTransitionKey: request.transitionKey,
+            updatedAt: at,
+        };
+    }
+}
+export { LIFECYCLE_STATES };

package/dist/completeness/types.d.ts

@@ -61,6 +61,73 @@ export type GlobalCompletenessScanResult = Readonly<{
     kind: "FAILED";
     error: string;
 }>;
+export type IncidentLifecycleState = "OPEN" | "ACKNOWLEDGED" | "CORRECTION_RECORDED" | "CLOSED" | "REOPENED";
+export type IncidentCorrection = Readonly<{
+    kind: "event" | "receipt";
+    reference: string;
+    digest: `sha256:${string}`;
+}>;
+export type IncidentCloseResolution = Readonly<{
+    kind: "CORRECTED";
+}> | Readonly<{
+    kind: "ACCEPTED_AS_IS";
+    explanation: string;
+}>;
+export interface IncidentTransitionBase {
+    readonly incidentIdentity: string;
+    readonly transitionKey: string;
+    readonly expectedVersion: number;
+    readonly reason: string;
+}
+export type IncidentTransitionRequest = (IncidentTransitionBase & Readonly<{
+    action: "ACKNOWLEDGE";
+    ownerId: string;
+    deadlineAt: number;
+}>) | (IncidentTransitionBase & Readonly<{
+    action: "UPDATE_ASSIGNMENT";
+    ownerId: string;
+    deadlineAt: number;
+}>) | (IncidentTransitionBase & Readonly<{
+    action: "RECORD_CORRECTION";
+    correction: IncidentCorrection;
+}>) | (IncidentTransitionBase & Readonly<{
+    action: "CLOSE";
+    resolution: IncidentCloseResolution;
+}>) | (IncidentTransitionBase & Readonly<{
+    action: "REOPEN";
+    ownerId: string;
+    deadlineAt: number;
+}>);
+export interface IncidentLifecycleProjection {
+    readonly serviceId: string;
+    readonly incidentIdentity: string;
+    readonly lifecycleState: IncidentLifecycleState;
+    readonly ownerId: string | null;
+    readonly deadlineAt: number | null;
+    readonly correction: IncidentCorrection | null;
+    readonly closeResolution: "CORRECTED" | "ACCEPTED_AS_IS" | null;
+    readonly closeReason: string | null;
+    readonly version: number;
+    readonly lastTransitionKey: string;
+    readonly updatedAt: number;
+}
+export interface IncidentTransitionRecord {
+    readonly transitionId: number;
+    readonly serviceId: string;
+    readonly incidentIdentity: string;
+    readonly transitionKey: string;
+    readonly requestDigest: string;
+    readonly action: IncidentTransitionRequest["action"];
+    readonly fromState: IncidentLifecycleState;
+    readonly toState: IncidentLifecycleState;
+    readonly fromVersion: number;
+    readonly toVersion: number;
+    readonly actorId: string;
+    readonly before: IncidentLifecycleProjection;
+    readonly after: IncidentLifecycleProjection;
+    readonly reason: string;
+    readonly occurredAt: number;
+}
 /** The sole temporary operational disposition; policy decisions remain open. */
 export declare const GLOBAL_COMPLETENESS_INTERIM_DISPOSITION: "BLOCK/UNSETTLED";
 /**

package/dist/cosmos.d.ts

@@ -1,11 +1,41 @@
+/**
+ * @experimental Cosmos support is an explicit opt-in provider and carries no
+ * production-support or availability promise.
+ */
 import { CosmosEventStore, type CosmosDocumentClient, type CosmosStoreOptions } from "./store/CosmosEventStore";
 import type { StoreProvider } from "./store/provider";
 import { type BootstrapStoreAdapter } from "./bootstrap/BootstrapStoreAdapter";
-export { CosmosClientError, CosmosEventStore, CosmosRestClient, DEFAULT_COSMOS_CONTAINERS, compareCosmosSuid, } from "./store/CosmosEventStore";
-export type { CosmosContainerNames, CosmosDocumentClient, CosmosDocumentRecord, CosmosStoreOptions, CosmosWriteBoundary, } from "./store/CosmosEventStore";
+/** @experimental */
+export { CosmosClientError } from "./store/CosmosEventStore";
+/** @experimental */
+export { CosmosEventStore } from "./store/CosmosEventStore";
+/** @experimental */
+export { CosmosRestClient } from "./store/CosmosEventStore";
+/** @experimental */
+export { DEFAULT_COSMOS_CONTAINERS } from "./store/CosmosEventStore";
+/** @experimental */
+export { compareCosmosSuid } from "./store/CosmosEventStore";
+/** @experimental */
+export type { CosmosContainerNames } from "./store/CosmosEventStore";
+/** @experimental */
+export type { CosmosDocumentClient } from "./store/CosmosEventStore";
+/** @experimental */
+export type { CosmosDocumentRecord } from "./store/CosmosEventStore";
+/** @experimental */
+export type { CosmosStoreOptions } from "./store/CosmosEventStore";
+/** @experimental */
+export type { CosmosWriteBoundary } from "./store/CosmosEventStore";
+/** @experimental Cosmos is an explicit, opt-in provider. */
+export declare class CosmosConfigurationError extends Error {
+    readonly missingBindings: readonly string[];
+    readonly code: "COSMOS_CONFIGURATION_INVALID";
+    constructor(missingBindings: readonly string[], message: string);
+}
+/** @experimental Configuration for the optional Cosmos provider. */
 export interface CosmosStoreProviderConfig extends Omit<CosmosStoreOptions, "client"> {
     readonly client?: CosmosDocumentClient;
 }
-/** Explicit opt-in provider; the default runtime composition never reads Cosmos config. */
-export declare function createCosmosStoreProvider(config: CosmosStoreProviderConfig): StoreProvider;
+/** @experimental Explicit opt-in provider; environment values alone never select it. */
+export declare function createCosmosStoreProvider(config?: CosmosStoreProviderConfig): StoreProvider;
+/** @experimental Explicit bootstrap adapter for the opt-in Cosmos provider. */
 export declare function createCosmosBootstrapAdapter(store: CosmosEventStore): BootstrapStoreAdapter;