@sekiban/dcb-runtime 0.2.0 → 0.2.2

package/dist/commit/CommitWorker.d.ts

@@ -24,6 +24,17 @@ export interface CommitWorkerHooks {
     /** Test-only barrier after entry admission is released and before /allocate. */
     beforeBootstrapAllocation?(): Promise<void> | void;
     beforeBootstrapFinalization?(): Promise<void> | void;
+    /**
+     * SDT-G36 test-only hook invoked after successful `finalize` and before
+     * `appendAllTags`. The bootstrap write permit is held across this hook.
+     */
+    beforeAuthoritativeAppend?(): Promise<void> | void;
+    /**
+     * SDT-G36 test-only hook invoked after all appends resolved with no
+     * pending tags and before result assembly. Lets a test interleave a
+     * concurrent append to prove `tagWriteResults` are not re-read from head.
+     */
+    afterAppendBeforeResponse?(): Promise<void> | void;
     /** Test-only allocator identity; production uses the canonical allocator identity. */
     allocatorScopeIdentity?: string;
     /** Runtime composition value; never sourced from a caller-controlled V1 body. */
@@ -72,6 +83,14 @@ export declare class CommitWorker {
      */
     private retiredJournalMilestone;
     private bootstrapCommand;
+    /**
+     * SDT-G36 bootstrap write permit. Deliberately untraced: it must not add
+     * `sdt.commit/v2` rows or new trace identities. Only a bootstrap barrier,
+     * never commit-outcome authority. No JOURNAL, no alarm, no lease expiry.
+     */
+    private bootstrapStub;
+    private bootstrapPermitAcquire;
+    private bootstrapPermitRelease;
     private postJson;
     private tagRequest;
     private acquireReservations;

package/dist/commit/CommitWorker.js

@@ -12,6 +12,25 @@ import { envServiceIdentity, requestServiceIdentity, } from "../service/ServiceI
 const INITIAL_OWNER_EPOCH = 0;
 const MAX_WRITE_ATTEMPTS = 2;
 const OUTCOME_UNDETERMINED_ERROR = "Commit outcome is undetermined; reread tag heads and event/query state before retrying because blind retry may create duplicate events.";
+/** SDT-G36 stable digest of the attempt tuple (tags + event ids + payloads). */
+function commitPermitDigest(allTags, candidates) {
+    const normalized = JSON.stringify({
+        tags: [...allTags].sort(),
+        events: candidates
+            .map((candidate) => ({
+            eventId: candidate.eventId,
+            payload: candidate.payload,
+            tags: [...candidate.tags].sort(),
+        }))
+            .sort((left, right) => (left.eventId < right.eventId ? -1 : left.eventId > right.eventId ? 1 : 0)),
+    });
+    let hash = 0x811c9dc5;
+    for (let index = 0; index < normalized.length; index += 1) {
+        hash ^= normalized.charCodeAt(index);
+        hash = Math.imul(hash, 0x01000193) >>> 0;
+    }
+    return `fnv1a32:${hash.toString(16).padStart(8, "0")}`;
+}
 const GLOBAL_ADMISSION_HEADER = "x-sdt-global-admission";
 /**
  * The static authority checker proves the manifest bytes; this is the
@@ -440,30 +459,61 @@ export class CommitWorker {
         // S05 trace identities are compatibility observations only; they cannot
         // resolve JOURNAL and are removed from the actual dependency path.
         await this.retiredJournalMilestone("S04", traceState?.scope);
+        // SDT-G36: durable bootstrap write permit. Acquired after admit/release
+        // and before allocate (before `beforeBootstrapAllocation`), held until
+        // every target tag of this attempt is durably resolved. It is only a
+        // bootstrap barrier, never commit-outcome authority. No JOURNAL, no
+        // alarm, no lease expiry.
+        const permitDigest = commitPermitDigest(input.allTags, candidates);
+        let permitHeld = false;
+        const releasePermit = async () => {
+            if (!permitHeld)
+                return;
+            permitHeld = false;
+            await this.bootstrapPermitRelease(attemptId, permitDigest);
+        };
+        const permit = await this.bootstrapPermitAcquire(attemptId, permitDigest);
+        if (!permit.ok) {
+            if (permit.code === "bootstrap_permit_digest_mismatch") {
+                return responseWithAttempt(error(409, "bootstrap_permit_digest_mismatch", "Bootstrap write permit digest does not match"), attemptId, fault !== undefined);
+            }
+            return responseWithAttempt(error(409, "bootstrap_command_rejected", "Bootstrap is importing; commit is unavailable"), attemptId, fault !== undefined);
+        }
+        permitHeld = this.env.BOOTSTRAP !== undefined;
         const reservations = await this.acquireReservations(input, attemptId, fault, traceState?.scope);
         await this.retiredJournalMilestone("S05a", traceState?.scope, 0);
         if (reservations.failure !== undefined) {
-            return this.finishReservationFailure([...reservations.successes.keys()], attemptId, reservations.failure, fault, traceState?.scope);
+            const failure = await this.finishReservationFailure([...reservations.successes.keys()], attemptId, reservations.failure, fault, traceState?.scope);
+            if (failure.resolved)
+                await releasePermit();
+            return failure.response;
         }
         if (fault === "after-reservations-before-allocation") {
             // Boundary 1: every durable prepare fact is force-tombstoned before
             // returning the intentionally undetermined outcome.  There is no
             // attempt-level Journal recovery record to make this safe later.
-            await this.cancelReservations([...reservations.successes.keys()], attemptId, fault, traceState?.scope);
+            const cleanup = await this.cancelReservations([...reservations.successes.keys()], attemptId, fault, traceState?.scope);
+            if (cleanup.failedTags.length === 0)
+                await releasePermit();
             return this.noApplicationOutcome(attemptId, true);
         }
         await this.hooks.beforeBootstrapAllocation?.();
         const allocation = await this.allocate(candidates, attemptId, fault, bootstrapEpoch, traceState?.scope);
         if (allocation === undefined) {
-            return this.finishReservationFailure([...reservations.successes.keys()], attemptId, {
+            const failure = await this.finishReservationFailure([...reservations.successes.keys()], attemptId, {
                 outcome: "FAILED",
                 failureCause: "allocator-failure",
                 reason: "allocator could not durably allocate the complete vector",
             }, fault, traceState?.scope);
+            if (failure.resolved)
+                await releasePermit();
+            return failure.response;
         }
         const allocatedCandidates = this.withAllocatedSuids(candidates, allocation);
         if (allocatedCandidates === undefined) {
-            await this.cancelReservations([...reservations.successes.keys()], attemptId, fault, traceState?.scope);
+            const cleanup = await this.cancelReservations([...reservations.successes.keys()], attemptId, fault, traceState?.scope);
+            if (cleanup.failedTags.length === 0)
+                await releasePermit();
             return this.noApplicationOutcome(attemptId, fault !== undefined);
         }
         // Allocation supplies the exact EventId/SUID pair needed by the durable
@@ -485,7 +535,9 @@ export class CommitWorker {
             // This retained fault marks the allocation-to-first-append crash
             // boundary.  With no Journal alarm, tags receive the same best-effort
             // tombstone barrier immediately and retain their own expiry alarm.
-            await this.cancelReservations(input.allTags, attemptId, fault, traceState?.scope);
+            const cleanup = await this.cancelReservations(input.allTags, attemptId, fault, traceState?.scope);
+            if (cleanup.failedTags.length === 0)
+                await releasePermit();
             return this.noApplicationOutcome(attemptId, true);
         }
         await this.retiredJournalMilestone("S05c", traceState?.scope, 2);
@@ -493,9 +545,14 @@ export class CommitWorker {
         // This is immediately before the first final authoritative tag mutation.
         // The same service epoch obtained at admission must still be current.
         if ((await this.bootstrapCommand("finalize", attemptId, bootstrapEpoch, traceState?.scope, "S10")) === undefined) {
-            await this.cancelReservations(input.allTags, attemptId, fault, traceState?.scope);
+            const cleanup = await this.cancelReservations(input.allTags, attemptId, fault, traceState?.scope);
+            if (cleanup.failedTags.length === 0)
+                await releasePermit();
             return responseWithAttempt(error(409, "bootstrap_command_rejected", "Bootstrap fencing epoch changed before commit write"), attemptId, fault !== undefined);
         }
+        // SDT-G36 test-only hook: the write permit is held across this barrier,
+        // so `POST /plan` must be 409 while the in-flight commit may still write.
+        await this.hooks.beforeAuthoritativeAppend?.();
         const writes = await this.appendAllTags(input, allocatedCandidates, attemptId, allocation.allocatorLineageId, reservations.successes, fault, traceState?.scope);
         if (writes.pendingTags.length > 0) {
             // Cancel is deliberately best effort: a cancellation error cannot
@@ -506,26 +563,36 @@ export class CommitWorker {
             // /fence/install loop: G44 can discover the incomplete source universe
             // without a delivery, and G45/G46 retain a readable fenced frontier.
             if (!await this.installPartialWriteFences(writes.pendingTags, attemptId, traceState?.scope)) {
+                // Resolution is not proven: the permit stays held and correctly
+                // blocks `plan`. Do not add recovery.
                 return this.noApplicationOutcome(attemptId, true);
             }
             if (writes.committedTags.size === 0 &&
                 writes.registrationUnavailableTags.length === writes.pendingTags.length) {
+                await releasePermit();
                 return responseWithAttempt(error(503, "partition_registration_unavailable", "Source partition registration is unavailable; retry the commit.", true), attemptId, fault !== undefined);
             }
+            await releasePermit();
             return this.partialWriteOutcome(input, allocatedCandidates, writes, attemptId, fault !== undefined);
         }
+        // SDT-G36 test seam: a concurrent append here must not change the
+        // already-captured `tagWriteResults`.
+        await this.hooks.afterAppendBeforeResponse?.();
         await this.retiredJournalMilestone("S05d", traceState?.scope, 3);
         if (fault === "sealing-after-cas") {
             // The all-tags-written/response-lost boundary has no single terminal
             // Journal response.  Durable tag receipts and G44 reconciliation are
             // now the detection authority.
+            await releasePermit();
             return this.noApplicationOutcome(attemptId, true);
         }
         try {
-            const success = await this.successResponse(input, allocatedCandidates, attemptId, startedAt, fault, traceState?.scope);
+            const success = await this.successResponse(input, allocatedCandidates, attemptId, startedAt, fault, traceState?.scope, writes);
+            await releasePermit();
             return responseWithAttempt(withGlobalAdmission(json(success, 200), writes.globalAdmission), attemptId, fault !== undefined);
         }
         catch {
+            await releasePermit();
             return responseWithAttempt(error(500, "internal_error", "Committed records could not be read while preparing the response"), attemptId, fault !== undefined);
         }
     }
@@ -571,6 +638,55 @@ export class CommitWorker {
             : await traceScope.span(rowId, {}, invoke);
         return result.leaseEpoch;
     }
+    /**
+     * SDT-G36 bootstrap write permit. Deliberately untraced: it must not add
+     * `sdt.commit/v2` rows or new trace identities. Only a bootstrap barrier,
+     * never commit-outcome authority. No JOURNAL, no alarm, no lease expiry.
+     */
+    bootstrapStub() {
+        if (this.env.BOOTSTRAP === undefined)
+            return undefined;
+        return this.env.BOOTSTRAP.get(scopeIdFor(this.env.BOOTSTRAP, {
+            serviceId: this.serviceId,
+            doClass: "bootstrap",
+            identity: "coordinator",
+        }));
+    }
+    async bootstrapPermitAcquire(commandId, digest) {
+        const stub = this.bootstrapStub();
+        if (stub === undefined)
+            return { ok: true };
+        try {
+            const url = new URL(`https://commit-worker.internal/command/permit`);
+            url.searchParams.set("__serviceId", this.serviceId);
+            const response = await stub.fetch(new Request(url, {
+                method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ commandId, digest }),
+            }));
+            if (response.ok)
+                return { ok: true };
+            const body = await response.clone().json().catch(() => undefined);
+            return { ok: false, code: typeof body?.code === "string" ? body.code : undefined };
+        }
+        catch {
+            return { ok: false };
+        }
+    }
+    async bootstrapPermitRelease(commandId, digest) {
+        const stub = this.bootstrapStub();
+        if (stub === undefined)
+            return;
+        try {
+            const url = new URL(`https://commit-worker.internal/command/permit-release`);
+            url.searchParams.set("__serviceId", this.serviceId);
+            await stub.fetch(new Request(url, {
+                method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ commandId, digest }),
+            }));
+        }
+        catch {
+            // Best effort: a lost release cannot replace the primary commit outcome.
+            // A permit left behind by a crash correctly blocks `plan`.
+        }
+    }
     async postJson(stub, path, body, traceScope, rowId, traceOptions = {}) {
         const invoke = async () => {
             const response = await stub.fetch(new Request(`https://commit-worker.internal${path}`, {
@@ -730,6 +846,7 @@ export class CommitWorker {
         let pending = [...input.allTags];
         const committedTags = new Set();
         const lastFailureCodeByTag = new Map();
+        const tagWriteFacts = new Map();
         let globalAdmission = "admitted";
         for (let attempt = 0; attempt < MAX_WRITE_ATTEMPTS && pending.length > 0; attempt += 1) {
             const append = (stageScope) => Promise.allSettled(pending.map(async (tag) => {
@@ -761,14 +878,31 @@ export class CommitWorker {
                     retryIndex: attempt,
                     attemptId,
                 });
-                const body = response.status === 503
-                    ? await response.clone().json().catch(() => undefined)
-                    : undefined;
+                const success = response.status >= 200 && response.status < 300;
+                let appendVersion;
+                let appendUpdatedAt;
+                let code;
+                try {
+                    const parsed = (await response.clone().json());
+                    if (isObject(parsed)) {
+                        if (typeof parsed.version === "number" && Number.isSafeInteger(parsed.version))
+                            appendVersion = parsed.version;
+                        if (typeof parsed.updatedAt === "string" && parsed.updatedAt.length > 0)
+                            appendUpdatedAt = parsed.updatedAt;
+                        if (typeof parsed.code === "string")
+                            code = parsed.code;
+                    }
+                }
+                catch {
+                    // Callers use the status first; malformed internal bodies are failures.
+                }
                 return {
                     tag,
-                    success: response.status >= 200 && response.status < 300,
+                    success,
                     globalAdmission: readGlobalAdmission(response),
-                    code: isObject(body) && typeof body.code === "string" ? body.code : undefined,
+                    code,
+                    appendVersion,
+                    appendUpdatedAt,
                 };
             }));
             const results = traceScope === undefined
@@ -781,6 +915,9 @@ export class CommitWorker {
                     committedTags.add(tag);
                     lastFailureCodeByTag.delete(tag);
                     globalAdmission = mergeGlobalAdmission(globalAdmission, result.value.globalAdmission);
+                    if (result.value.appendVersion !== undefined && result.value.appendUpdatedAt !== undefined) {
+                        tagWriteFacts.set(tag, { version: result.value.appendVersion, updatedAt: result.value.appendUpdatedAt });
+                    }
                 }
                 else {
                     lastFailureCodeByTag.set(tag, result.status === "fulfilled" ? result.value.code : undefined);
@@ -794,6 +931,7 @@ export class CommitWorker {
             pendingTags: pending,
             registrationUnavailableTags: pending.filter((tag) => lastFailureCodeByTag.get(tag) === "partition_registration_unavailable"),
             globalAdmission,
+            tagWriteFacts,
         };
     }
     /**
@@ -827,14 +965,17 @@ export class CommitWorker {
         if (traceScope !== undefined) {
             await traceScope.span("S17", {}, async () => undefined);
         }
-        await this.cancelReservations(tags, attemptId, fault, traceScope);
+        const cleanup = await this.cancelReservations(tags, attemptId, fault, traceScope);
         await this.retiredJournalMilestone("S05e", traceScope, 4);
         const response = failure.outcome === "REFUSED"
             ? error(400, "consistency_conflict", "serialized commit was refused by a consistency reservation")
             : failure.failureCause === "reservation-timeout"
                 ? error(504, "timeout", "serialized commit timed out")
                 : error(500, "internal_error", "serialized commit failed before writing requested records");
-        return responseWithAttempt(response, attemptId, fault !== undefined);
+        return {
+            response: responseWithAttempt(response, attemptId, fault !== undefined),
+            resolved: cleanup.failedTags.length === 0,
+        };
     }
     /**
      * Persist the local partial-write fact for each tag whose append did not
@@ -877,24 +1018,32 @@ export class CommitWorker {
             },
         }, 500), attemptId, exposeAttempt);
     }
-    async successResponse(input, candidates, attemptId, startedAt, fault, traceScope) {
-        const readStates = (stageScope) => Promise.all(input.allTags.map(async (tag, memberIndex) => {
+    async successResponse(input, candidates, attemptId, startedAt, fault, traceScope, writes) {
+        // SDT-G36: `tagWriteResults` come from the `/append` bodies captured in
+        // `writes.tagWriteFacts`. The success path never re-reads `/head-facts`
+        // or `/state`. S13/S14 stay as compatibility observations only.
+        const assemble = async (stageScope) => {
             if (fault === "tag-state-unavailable") {
                 throw new Error("Test fault made the committed tag state unavailable");
             }
-            const response = await this.tagRequest(tag, "/head-facts", undefined, stageScope?.fork(), stageScope === undefined ? undefined : "S14", { memberIndex, attemptId });
-            if (response.status !== 200) {
-                throw new Error("Committed tag state was unavailable while preparing the response");
-            }
-            const body = (await response.json());
-            if (typeof body.version !== "number" || typeof body.updatedAt !== "string" || typeof body.head !== "string") {
-                throw new Error("Committed tag state was malformed while preparing the response");
+            const results = [];
+            for (const [memberIndex, tag] of input.allTags.entries()) {
+                const read = () => {
+                    const fact = writes?.tagWriteFacts.get(tag);
+                    if (fact === undefined) {
+                        throw new Error("Committed tag state was unavailable while preparing the response");
+                    }
+                    return { tag, version: fact.version, writtenAt: fact.updatedAt };
+                };
+                results.push(stageScope === undefined
+                    ? read()
+                    : await stageScope.fork().span("S14", { tag, memberIndex, attemptId }, async () => read()));
             }
-            return { tag, version: body.version, writtenAt: body.updatedAt };
-        }));
+            return results;
+        };
         const tagWriteResults = traceScope === undefined
-            ? await readStates()
-            : await traceScope.span("S13", {}, async (stage) => readStates(stage));
+            ? await assemble()
+            : await traceScope.span("S13", {}, async (stage) => assemble(stage));
         return {
             writtenEvents: candidates.map((candidate) => ({
                 payload: encodeBase64Utf8(candidate.payload),

package/dist/completeness/IncidentLifecycle.d.ts

@@ -0,0 +1,75 @@
+import type { IncidentLifecycleProjection, IncidentLifecycleState, IncidentTransitionRecord, IncidentTransitionRequest } from "./types";
+declare const LIFECYCLE_STATES: readonly IncidentLifecycleState[];
+export interface IncidentListFilters {
+    readonly state?: IncidentLifecycleState;
+    readonly owner?: string;
+    readonly unowned?: boolean;
+    readonly overdue?: boolean;
+    readonly observedAfterClose?: boolean;
+}
+export interface IncidentFinding {
+    readonly serviceId: string;
+    readonly incidentIdentity: string;
+    readonly incidentType: string;
+    readonly partitionTag: string | null;
+    readonly obligationSequence: number | null;
+    readonly eventId: string | null;
+    readonly eventDigest: string | null;
+    readonly state: "OPEN" | "UNRESOLVED";
+    readonly firstObservedAt: number;
+    readonly lastObservedAt: number;
+}
+export interface IncidentListItem {
+    readonly finding: IncidentFinding;
+    readonly lifecycle: IncidentLifecycleProjection;
+    readonly overdue: boolean;
+    readonly unowned: boolean;
+    readonly observedAfterClose: boolean;
+}
+export interface IncidentListResult {
+    readonly items: readonly IncidentListItem[];
+    readonly summary: Readonly<{
+        total: number;
+        byState: Readonly<Record<IncidentLifecycleState, number>>;
+        unowned: number;
+        overdue: number;
+        observedAfterClose: number;
+    }>;
+}
+export interface IncidentDetailResult {
+    readonly finding: IncidentFinding;
+    readonly lifecycle: IncidentLifecycleProjection;
+    readonly flags: Readonly<{
+        overdue: boolean;
+        unowned: boolean;
+        observedAfterClose: boolean;
+    }>;
+    readonly transitions: readonly IncidentTransitionRecord[];
+}
+export interface IncidentTransitionResult {
+    readonly projection: IncidentLifecycleProjection;
+    readonly transition: IncidentTransitionRecord;
+    readonly idempotent: boolean;
+}
+export declare class IncidentLifecycleError extends Error {
+    readonly code: string;
+    readonly status: number;
+    constructor(code: string, status: number, message: string);
+}
+export declare function normalizeIncidentIdentity(value: unknown): string;
+export declare class IncidentLifecycle {
+    private readonly database;
+    private readonly now;
+    constructor(database: D1Database, now?: () => number);
+    static parseTransition(value: unknown): IncidentTransitionRequest;
+    private finding;
+    private lifecycle;
+    private transitions;
+    private closeTime;
+    private item;
+    list(serviceId: string, filters?: IncidentListFilters, at?: number): Promise<IncidentListResult>;
+    detail(serviceId: string, incidentIdentity: string, at?: number): Promise<IncidentDetailResult>;
+    transition(serviceId: string, value: unknown, actor: string): Promise<IncidentTransitionResult>;
+    private nextProjection;
+}
+export { LIFECYCLE_STATES };