@sekiban/dcb-runtime 0.2.0

package/dist/allocator/IssuanceReconciler.js

@@ -0,0 +1,191 @@
+import { scopeIdFor } from "../scope/ScopeName";
+import { DEFAULT_WRITER_EPOCH, ISSUANCE_NEVER_CONTACTED_GRACE_MS, ISSUANCE_RECOVERY_KEY, UNRESOLVED_INDEX_PREFIX, countUnresolvedEntries, envelopeKey, parseIndexEntry, syncIssuanceRecoveryAlarm, targetKey, } from "./IssuanceLedger";
+const RECONCILE_BATCH_LIMIT = 8;
+const RECONCILE_RETRY_MS = 1_000;
+export async function inspectTagTarget(env, serviceId, tag, envelope) {
+    const url = new URL("https://tag.internal/__internal/g77/inspect-target");
+    url.searchParams.set("__serviceId", serviceId);
+    url.searchParams.set("__tag", tag);
+    const response = await env.TAG.get(scopeIdFor(env.TAG, {
+        serviceId,
+        doClass: "tag",
+        identity: tag,
+    })).fetch(new Request(url, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+            eventId: envelope.eventId,
+            suid: envelope.suid,
+            canonicalTargetTags: envelope.canonicalTargetTags,
+            pinnedWriterEpoch: envelope.pinnedWriterEpoch,
+            attemptId: envelope.attemptId,
+        }),
+    }));
+    if (response.status === 503)
+        return { kind: "unreachable" };
+    if (response.status === 409)
+        return { kind: "not-terminal-yet" };
+    if (response.status !== 200)
+        return { kind: "unreachable" };
+    const body = await response.json();
+    if (body.inspectionStatus === "absent-never-contacted") {
+        return { kind: "absent-never-contacted" };
+    }
+    if (body.inspectionStatus === "absent-but-unfenced") {
+        return { kind: "absent-but-unfenced" };
+    }
+    if (body.terminalStatus !== "installed-and-covered" &&
+        body.terminalStatus !== "absent-and-irrevocably-fenced") {
+        return { kind: "not-terminal-yet" };
+    }
+    return { kind: "terminal", result: body };
+}
+export async function fenceAbsentTarget(env, serviceId, tag, envelope) {
+    const url = new URL("https://tag.internal/__internal/g77/fence-absent-target");
+    url.searchParams.set("__serviceId", serviceId);
+    url.searchParams.set("__tag", tag);
+    const response = await env.TAG.get(scopeIdFor(env.TAG, {
+        serviceId,
+        doClass: "tag",
+        identity: tag,
+    })).fetch(new Request(url, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+            attemptId: envelope.attemptId,
+            epoch: envelope.pinnedWriterEpoch ?? DEFAULT_WRITER_EPOCH,
+        }),
+    }));
+    return response.status >= 200 && response.status < 300;
+}
+function tagObservationFromInspect(result) {
+    if (result.terminalStatus === "installed-and-covered") {
+        return {
+            terminalStatus: "installed-and-covered",
+            ...(result.obligationDigest !== undefined ? { obligationDigest: result.obligationDigest } : {}),
+        };
+    }
+    return {
+        terminalStatus: "absent-and-irrevocably-fenced",
+        ...(result.tombstoneEpoch !== undefined ? { tombstoneEpoch: result.tombstoneEpoch } : {}),
+    };
+}
+export function tagObservationMatchesInspect(submitted, result) {
+    if (submitted.terminalStatus !== result.terminalStatus)
+        return false;
+    if (submitted.terminalStatus === "installed-and-covered") {
+        return submitted.obligationDigest === result.obligationDigest;
+    }
+    return submitted.tombstoneEpoch === result.tombstoneEpoch;
+}
+export async function verifyTargetResolutionEvidence(env, serviceId, evidence, envelope) {
+    if (evidence.pinnedWriterEpoch !== envelope.pinnedWriterEpoch) {
+        throw new Error("resolution evidence pinned writer epoch does not match envelope");
+    }
+    const outcome = await inspectTagTarget(env, serviceId, evidence.tag, envelope);
+    if (outcome.kind !== "terminal") {
+        throw new Error("tag observation is not verified by live inspect");
+    }
+    if (!tagObservationMatchesInspect(evidence.tagObservation, outcome.result)) {
+        throw new Error("tag observation does not match live inspect");
+    }
+    if (evidence.tagObservation.terminalStatus === "absent-and-irrevocably-fenced" &&
+        envelope.pinnedWriterEpoch > (evidence.tagObservation.tombstoneEpoch ?? -1)) {
+        throw new Error("fenced observation violates writer epoch rule");
+    }
+}
+export async function submitTargetResolution(env, serviceId, evidence) {
+    const response = await env.ALLOCATOR.get(scopeIdFor(env.ALLOCATOR, {
+        serviceId,
+        doClass: "allocator",
+        identity: "allocator",
+    })).fetch(new Request("https://allocator.internal/__internal/g77/resolve-target", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(evidence),
+    }));
+    return response.status >= 200 && response.status < 300;
+}
+export async function reconcileIssuanceBatch(storage, env, serviceId, resolveTarget, options) {
+    let processed = 0;
+    const now = Date.now();
+    const listed = await storage.list({
+        prefix: UNRESOLVED_INDEX_PREFIX,
+        limit: RECONCILE_BATCH_LIMIT,
+    });
+    for (const [key] of listed) {
+        const parsed = parseIndexEntry(key, UNRESOLVED_INDEX_PREFIX);
+        if (parsed === undefined)
+            continue;
+        const envelope = await storage.get(envelopeKey(parsed.attemptId, parsed.candidateIndex));
+        if (envelope === undefined)
+            continue;
+        for (const tag of envelope.canonicalTargetTags) {
+            const target = await storage.get(targetKey(parsed.attemptId, parsed.candidateIndex, tag));
+            if (target === undefined || target.status !== "pending")
+                continue;
+            let outcome = await inspectTagTarget(env, serviceId, tag, envelope);
+            if (outcome.kind === "unreachable" || outcome.kind === "not-terminal-yet") {
+                continue;
+            }
+            if (outcome.kind === "absent-never-contacted") {
+                const issuedAtMs = envelope.issuedAtMs ?? 0;
+                if (options?.bypassNeverContactedGrace !== true
+                    && now - issuedAtMs < ISSUANCE_NEVER_CONTACTED_GRACE_MS) {
+                    continue;
+                }
+            }
+            if (outcome.kind === "absent-never-contacted" || outcome.kind === "absent-but-unfenced") {
+                const fenced = await fenceAbsentTarget(env, serviceId, tag, envelope);
+                if (!fenced)
+                    continue;
+                outcome = await inspectTagTarget(env, serviceId, tag, envelope);
+            }
+            if (outcome.kind !== "terminal")
+                continue;
+            const evidence = {
+                serviceId: envelope.serviceId,
+                allocatorLineageId: envelope.allocatorLineageId,
+                attemptId: envelope.attemptId,
+                candidateIndex: envelope.candidateIndex,
+                suid: envelope.suid,
+                tag,
+                identityDigest: envelope.identityDigest,
+                pinnedWriterEpoch: envelope.pinnedWriterEpoch,
+                tagObservation: tagObservationFromInspect(outcome.result),
+            };
+            const submitted = resolveTarget !== undefined
+                ? await resolveTarget(evidence)
+                : "ALLOCATOR" in env && env.ALLOCATOR !== undefined
+                    ? await submitTargetResolution(env, serviceId, evidence)
+                    : false;
+            if (submitted)
+                processed += 1;
+        }
+    }
+    const existingSchedule = await storage.get(ISSUANCE_RECOVERY_KEY);
+    const attempts = (existingSchedule?.attempts ?? 0) + 1;
+    const unresolvedCount = await countUnresolvedEntries(storage);
+    if (unresolvedCount === 0) {
+        if (existingSchedule !== undefined) {
+            await storage.put(ISSUANCE_RECOVERY_KEY, {
+                ...existingSchedule,
+                attempts,
+            });
+        }
+        await storage.deleteAlarm();
+        return { processed, rearmAt: now };
+    }
+    const retryAt = now + RECONCILE_RETRY_MS;
+    const scheduled = existingSchedule?.nextDueAt;
+    const nextDueAt = scheduled !== undefined && scheduled > now
+        ? Math.min(scheduled, retryAt)
+        : retryAt;
+    await storage.put(ISSUANCE_RECOVERY_KEY, {
+        nextDueAt,
+        cursor: null,
+        attempts,
+    });
+    await syncIssuanceRecoveryAlarm(storage, now);
+    return { processed, rearmAt: nextDueAt };
+}

package/dist/allocator/OrderClock.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The only allocator time seam. A tick is a Unix millisecond; conversion to
+ * the .NET tick representation happens exactly once at allocation admission.
+ */
+export interface OrderClock {
+    tick(): bigint;
+}
+export declare class OrderClockReadError extends Error {
+    readonly code: "ALLOCATOR_ORDER_CLOCK_FAILED";
+    constructor(message: string, options?: ErrorOptions);
+}
+export declare const systemOrderClock: OrderClock;
+/** Compatibility export names now denote the C# fixed-width 30-digit format. */
+export declare const ORDER_SUID_DIGITS: number;
+export declare const ORDER_SUID_PREFIX = "";
+export declare const ORDER_SUID_LIMIT: bigint;
+/** @deprecated Use formatSortableUniqueId. The ordinal is a .NET tick value. */
+export declare function encodeOrderOrdinal(value: bigint): string;
+/** @deprecated Use assertSortableUniqueId(value).ticks. */
+export declare function decodeOrderOrdinal(value: string): bigint;
+export interface OrderAllocationRange {
+    /** Logical .NET tick allocation base. */
+    readonly base: bigint;
+    readonly baseTicks: bigint;
+    readonly physicalTicks: bigint;
+    readonly observedTicks: bigint | null;
+    readonly watermark: string;
+    readonly suids: readonly string[];
+}
+export interface OrderAllocationOptions {
+    /** Deterministic test injection; production omits this and uses crypto. */
+    readonly suffixes?: readonly bigint[];
+}
+/**
+ * Pure range oracle used by the DO and deterministic fixtures. Watermark
+ * authority is only its leading nineteen tick digits; its random suffix is
+ * retained durably for replay but never participates in the monotone base.
+ */
+export declare function allocateOrderRange(watermark: string | null, count: number, clockTick: bigint, options?: OrderAllocationOptions): OrderAllocationRange;
+/** Diagnostic only; it derives from allocated ticks, never a second clock. */
+export declare function diagnosticAllocatedAt(ticks: bigint): string;

package/dist/allocator/OrderClock.js

@@ -0,0 +1,92 @@
+import { DOTNET_MAX_TICKS, SORTABLE_UNIQUE_ID_DIGITS, SortableUniqueIdError, assertSortableUniqueId, cryptoRandomSortableUniqueIdSuffix, dotNetTicksToUnixMs, formatSortableUniqueId, unixMsToDotNetTicks, } from "./SortableUniqueId";
+export class OrderClockReadError extends Error {
+    code = "ALLOCATOR_ORDER_CLOCK_FAILED";
+    constructor(message, options) {
+        super(message, options);
+        this.name = "OrderClockReadError";
+    }
+}
+export const systemOrderClock = Object.freeze({
+    tick() {
+        const milliseconds = Date.now();
+        if (!Number.isSafeInteger(milliseconds) || milliseconds < 0) {
+            throw new OrderClockReadError("System Unix millisecond clock returned an invalid value");
+        }
+        return BigInt(milliseconds);
+    },
+});
+/** Compatibility export names now denote the C# fixed-width 30-digit format. */
+export const ORDER_SUID_DIGITS = SORTABLE_UNIQUE_ID_DIGITS;
+export const ORDER_SUID_PREFIX = "";
+export const ORDER_SUID_LIMIT = DOTNET_MAX_TICKS + 1n;
+/** @deprecated Use formatSortableUniqueId. The ordinal is a .NET tick value. */
+export function encodeOrderOrdinal(value) {
+    return formatSortableUniqueId(value, 0n);
+}
+/** @deprecated Use assertSortableUniqueId(value).ticks. */
+export function decodeOrderOrdinal(value) {
+    try {
+        return assertSortableUniqueId(value).ticks;
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : "invalid SortableUniqueId";
+        throw new OrderClockReadError(detail, { cause: error });
+    }
+}
+function asOrderClockError(error) {
+    if (error instanceof OrderClockReadError)
+        return error;
+    const detail = error instanceof Error ? error.message : "SortableUniqueId allocation failed";
+    return new OrderClockReadError(detail, { cause: error });
+}
+/**
+ * Pure range oracle used by the DO and deterministic fixtures. Watermark
+ * authority is only its leading nineteen tick digits; its random suffix is
+ * retained durably for replay but never participates in the monotone base.
+ */
+export function allocateOrderRange(watermark, count, clockTick, options = {}) {
+    if (!Number.isSafeInteger(count) || count <= 0) {
+        throw new OrderClockReadError("An order allocation requires a positive candidate count");
+    }
+    try {
+        const physicalTicks = unixMsToDotNetTicks(clockTick);
+        const observedTicks = watermark === null ? null : assertSortableUniqueId(watermark).ticks;
+        const baseTicks = observedTicks === null || physicalTicks > observedTicks + 1n
+            ? physicalTicks
+            : observedTicks + 1n;
+        const lastTicks = baseTicks + BigInt(count) - 1n;
+        if (lastTicks > DOTNET_MAX_TICKS) {
+            throw new SortableUniqueIdError("SUID_RANGE_EXHAUSTED", "Allocator SortableUniqueId range is exhausted before write");
+        }
+        if (options.suffixes !== undefined && options.suffixes.length !== count) {
+            throw new OrderClockReadError("A deterministic SortableUniqueId suffix is required for every candidate");
+        }
+        const suids = Array.from({ length: count }, (_, index) => formatSortableUniqueId(baseTicks + BigInt(index), options.suffixes?.[index] ?? cryptoRandomSortableUniqueIdSuffix()));
+        return Object.freeze({
+            base: baseTicks,
+            baseTicks,
+            physicalTicks,
+            observedTicks,
+            watermark: suids.at(-1),
+            suids: Object.freeze(suids),
+        });
+    }
+    catch (error) {
+        if (error instanceof SortableUniqueIdError)
+            throw error;
+        throw asOrderClockError(error);
+    }
+}
+/** Diagnostic only; it derives from allocated ticks, never a second clock. */
+export function diagnosticAllocatedAt(ticks) {
+    try {
+        const milliseconds = dotNetTicksToUnixMs(ticks);
+        if (milliseconds <= BigInt(Number.MAX_SAFE_INTEGER)) {
+            return new Date(Number(milliseconds)).toISOString();
+        }
+    }
+    catch {
+        // Preserve a non-authoritative diagnostic for values beyond Date's range.
+    }
+    return `ticks:${ticks.toString()}`;
+}

package/dist/allocator/SortableUniqueId.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Sekiban.Dcb SortableUniqueId parity primitives.
+ *
+ * A value is deliberately represented as its canonical 30 ASCII decimal
+ * characters. The first nineteen characters are .NET DateTime ticks and
+ * the final eleven are the allocator-owned random suffix. Keeping both
+ * components as bigint avoids accidental IEEE-754 rounding at large clocks.
+ */
+export declare const SORTABLE_UNIQUE_ID_TICKS_DIGITS = 19;
+export declare const SORTABLE_UNIQUE_ID_RANDOM_DIGITS = 11;
+export declare const SORTABLE_UNIQUE_ID_DIGITS: number;
+export declare const DOTNET_UNIX_EPOCH_TICKS = 621355968000000000n;
+export declare const DOTNET_MAX_TICKS = 3155378975999999999n;
+export declare const DOTNET_TICKS_PER_MILLISECOND = 10000n;
+export declare const SORTABLE_UNIQUE_ID_RANDOM_LIMIT: bigint;
+export declare const MAX_UNIX_MILLISECONDS: bigint;
+export type SortableUniqueIdErrorCode = "SUID_INVALID" | "SUID_LEGACY_FORMAT_RETIRED" | "SUID_TICKS_INVALID" | "SUID_RANDOM_INVALID" | "SUID_UNIX_MILLISECONDS_INVALID" | "SUID_RANGE_EXHAUSTED" | "SUID_RANDOM_UNAVAILABLE";
+export declare class SortableUniqueIdError extends Error {
+    readonly code: SortableUniqueIdErrorCode;
+    constructor(code: SortableUniqueIdErrorCode, message: string, options?: ErrorOptions);
+}
+export interface ParsedSortableUniqueId {
+    readonly value: string;
+    readonly ticks: bigint;
+    readonly random: bigint;
+}
+/**
+ * Test-only observation seam for the single retired-SUID decision point.
+ * Production never installs an observer; the validator still fail-closes
+ * before any durable actor is acquired.
+ */
+export declare function observeLegacySortableUniqueIdDecision<T>(observer: (value: string) => void, run: () => Promise<T> | T): Promise<T>;
+/** Convert an exact Unix-millisecond value to C# DateTime ticks. */
+export declare function unixMsToDotNetTicks(value: number | string | bigint): bigint;
+/** Inverse C# parity helper; fractional 100ns ticks truncate toward zero. */
+export declare function dotNetTicksToUnixMs(ticks: bigint): bigint;
+export declare function assertDotNetTicks(ticks: bigint): bigint;
+export declare function assertSortableUniqueId(value: string): ParsedSortableUniqueId;
+export declare function isSortableUniqueId(value: unknown): value is string;
+export declare function formatSortableUniqueId(ticks: bigint, random: bigint): string;
+/**
+ * C# parity requires a crypto-derived, non-negative 31-bit suffix. The
+ * modulo is retained literally because it is part of the required contract.
+ */
+export declare function cryptoRandomSortableUniqueIdSuffix(): bigint;
+export declare function compareSortableUniqueId(left: string, right: string): number;

package/dist/allocator/SortableUniqueId.js

@@ -0,0 +1,156 @@
+/**
+ * Sekiban.Dcb SortableUniqueId parity primitives.
+ *
+ * A value is deliberately represented as its canonical 30 ASCII decimal
+ * characters. The first nineteen characters are .NET DateTime ticks and
+ * the final eleven are the allocator-owned random suffix. Keeping both
+ * components as bigint avoids accidental IEEE-754 rounding at large clocks.
+ */
+export const SORTABLE_UNIQUE_ID_TICKS_DIGITS = 19;
+export const SORTABLE_UNIQUE_ID_RANDOM_DIGITS = 11;
+export const SORTABLE_UNIQUE_ID_DIGITS = SORTABLE_UNIQUE_ID_TICKS_DIGITS + SORTABLE_UNIQUE_ID_RANDOM_DIGITS;
+export const DOTNET_UNIX_EPOCH_TICKS = 621355968000000000n;
+export const DOTNET_MAX_TICKS = 3155378975999999999n;
+export const DOTNET_TICKS_PER_MILLISECOND = 10000n;
+export const SORTABLE_UNIQUE_ID_RANDOM_LIMIT = 10n ** BigInt(SORTABLE_UNIQUE_ID_RANDOM_DIGITS);
+export const MAX_UNIX_MILLISECONDS = (DOTNET_MAX_TICKS - DOTNET_UNIX_EPOCH_TICKS) / DOTNET_TICKS_PER_MILLISECOND;
+export class SortableUniqueIdError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+        this.name = "SortableUniqueIdError";
+    }
+}
+/**
+ * A G32 ingress must not silently treat an old prefixed SUID as merely an
+ * arbitrary malformed string.  Keeping this classification at the one
+ * shared validator makes the retired-format boundary observable to every
+ * ingress without creating a compatibility lane.
+ */
+const LEGACY_PREFIXED_SUID = /^suid-[0-9]+$/;
+const LEGACY_DECISION_OBSERVER = Symbol.for("@sekiban/dcb-runtime/legacy-sortable-unique-id-observer");
+function legacyDecisionObserver() {
+    return globalThis[LEGACY_DECISION_OBSERVER];
+}
+/**
+ * Test-only observation seam for the single retired-SUID decision point.
+ * Production never installs an observer; the validator still fail-closes
+ * before any durable actor is acquired.
+ */
+export async function observeLegacySortableUniqueIdDecision(observer, run) {
+    const globals = globalThis;
+    const previous = globals[LEGACY_DECISION_OBSERVER];
+    globals[LEGACY_DECISION_OBSERVER] = observer;
+    try {
+        return await run();
+    }
+    finally {
+        globals[LEGACY_DECISION_OBSERVER] = previous;
+    }
+}
+function canonicalDecimal(value, name) {
+    if (!/^(?:0|[1-9][0-9]*)$/.test(value)) {
+        throw new SortableUniqueIdError("SUID_UNIX_MILLISECONDS_INVALID", `${name} must be canonical ASCII decimal text`);
+    }
+    return BigInt(value);
+}
+function asUnixMilliseconds(value) {
+    if (typeof value === "number") {
+        if (!Number.isSafeInteger(value) || value < 0) {
+            throw new SortableUniqueIdError("SUID_UNIX_MILLISECONDS_INVALID", "Unix milliseconds must be a non-negative safe integer");
+        }
+        return BigInt(value);
+    }
+    if (typeof value === "string")
+        return canonicalDecimal(value, "Unix milliseconds");
+    if (value < 0n) {
+        throw new SortableUniqueIdError("SUID_UNIX_MILLISECONDS_INVALID", "Unix milliseconds must be non-negative");
+    }
+    return value;
+}
+/** Convert an exact Unix-millisecond value to C# DateTime ticks. */
+export function unixMsToDotNetTicks(value) {
+    const milliseconds = asUnixMilliseconds(value);
+    // BigInt conversion intentionally happens before multiplying. Do not
+    // collapse this into Number arithmetic: M3 covers the 2^53 boundary.
+    const ticks = milliseconds * DOTNET_TICKS_PER_MILLISECOND + DOTNET_UNIX_EPOCH_TICKS;
+    if (ticks < 0n || ticks > DOTNET_MAX_TICKS) {
+        throw new SortableUniqueIdError("SUID_TICKS_INVALID", "Unix milliseconds are outside the .NET DateTime tick range");
+    }
+    return ticks;
+}
+/** Inverse C# parity helper; fractional 100ns ticks truncate toward zero. */
+export function dotNetTicksToUnixMs(ticks) {
+    assertDotNetTicks(ticks);
+    if (ticks < DOTNET_UNIX_EPOCH_TICKS) {
+        throw new SortableUniqueIdError("SUID_TICKS_INVALID", "SortableUniqueId ticks predate the Unix epoch");
+    }
+    return (ticks - DOTNET_UNIX_EPOCH_TICKS) / DOTNET_TICKS_PER_MILLISECOND;
+}
+export function assertDotNetTicks(ticks) {
+    // C# uses the fixed-width `TickFormatter` when it serializes a tick.  A
+    // numeric tick before the year in which DateTime.Ticks reaches 10^18 is
+    // therefore intentionally shorter than nineteen digits before formatting.
+    // Validate the numeric .NET range here and the exact 19-character field at
+    // the string ingress below.
+    if (ticks < 0n || ticks > DOTNET_MAX_TICKS) {
+        throw new SortableUniqueIdError("SUID_TICKS_INVALID", "SortableUniqueId ticks are outside the .NET DateTime range");
+    }
+    return ticks;
+}
+export function assertSortableUniqueId(value) {
+    if (typeof value === "string" && LEGACY_PREFIXED_SUID.test(value)) {
+        legacyDecisionObserver()?.(value);
+        throw new SortableUniqueIdError("SUID_LEGACY_FORMAT_RETIRED", "Legacy prefixed SortableUniqueId is retired; G32 requires exactly 30 ASCII decimal digits");
+    }
+    if (typeof value !== "string" || !new RegExp(`^[0-9]{${SORTABLE_UNIQUE_ID_DIGITS}}$`).test(value)) {
+        throw new SortableUniqueIdError("SUID_INVALID", "SortableUniqueId must be exactly 30 ASCII decimal digits");
+    }
+    const ticksText = value.slice(0, SORTABLE_UNIQUE_ID_TICKS_DIGITS);
+    const randomText = value.slice(SORTABLE_UNIQUE_ID_TICKS_DIGITS);
+    // Keep the 19-character field check separate from the numeric check.  In
+    // particular, `0006213559680000000` is the valid Unix-epoch tick field and
+    // must not be rejected merely because BigInt removes its leading zero.
+    const ticks = assertDotNetTicks(BigInt(ticksText));
+    const random = BigInt(randomText);
+    if (random < 0n || random >= SORTABLE_UNIQUE_ID_RANDOM_LIMIT) {
+        throw new SortableUniqueIdError("SUID_RANDOM_INVALID", "SortableUniqueId random suffix is outside its 11-digit range");
+    }
+    return Object.freeze({ value, ticks, random });
+}
+export function isSortableUniqueId(value) {
+    if (typeof value !== "string")
+        return false;
+    try {
+        assertSortableUniqueId(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function formatSortableUniqueId(ticks, random) {
+    assertDotNetTicks(ticks);
+    if (random < 0n || random >= SORTABLE_UNIQUE_ID_RANDOM_LIMIT) {
+        throw new SortableUniqueIdError("SUID_RANDOM_INVALID", "SortableUniqueId random suffix is outside its 11-digit range");
+    }
+    return `${ticks.toString().padStart(SORTABLE_UNIQUE_ID_TICKS_DIGITS, "0")}${random.toString().padStart(SORTABLE_UNIQUE_ID_RANDOM_DIGITS, "0")}`;
+}
+/**
+ * C# parity requires a crypto-derived, non-negative 31-bit suffix. The
+ * modulo is retained literally because it is part of the required contract.
+ */
+export function cryptoRandomSortableUniqueIdSuffix() {
+    if (typeof globalThis.crypto?.getRandomValues !== "function") {
+        throw new SortableUniqueIdError("SUID_RANDOM_UNAVAILABLE", "crypto.getRandomValues is required for SortableUniqueId allocation");
+    }
+    const words = new Uint32Array(1);
+    globalThis.crypto.getRandomValues(words);
+    return BigInt(words[0] & 0x7fff_ffff) % SORTABLE_UNIQUE_ID_RANDOM_LIMIT;
+}
+export function compareSortableUniqueId(left, right) {
+    const leftValue = assertSortableUniqueId(left).value;
+    const rightValue = assertSortableUniqueId(right).value;
+    return leftValue < rightValue ? -1 : leftValue > rightValue ? 1 : 0;
+}

package/dist/allocator/types.d.ts

@@ -0,0 +1,52 @@
+export interface AllocationCandidate {
+    candidateIndex: number;
+    eventId: string;
+}
+export interface AllocatedCandidate extends AllocationCandidate {
+    suid: string;
+}
+/**
+ * Allocator-issued authority for a closed SUID prefix.
+ *
+ * The issuance and reconciliation protocol that produces this value belongs
+ * to the allocator closure slice.  Projection consumers treat the value as a
+ * cached, consumer-bound fact; they never manufacture one from a high-water
+ * mark or fetch one as part of an ordinary read.
+ */
+export interface ClosedPrefixCertificate {
+    readonly certificateVersion: 1;
+    readonly authority: "allocator-transaction";
+    readonly status: "ready" | "unreconciled";
+    readonly allocatorLineageId: string;
+    readonly serviceId: string;
+    readonly closedPrefixSuid: string | null;
+    readonly unresolvedCount: number;
+    readonly generatedAt: number;
+    readonly migrationProofId: string | null;
+}
+/**
+ * The durable, attempt-keyed allocation result. Candidates are always ordered
+ * by candidateIndex, rather than by the order in which a caller sent them.
+ */
+export interface AllocationVector {
+    attemptId: string;
+    /** Durable allocator lineage token; it changes when the allocator DO is recreated. */
+    allocatorLineageId: string;
+    candidates: AllocatedCandidate[];
+    allocatedAt: string;
+}
+/** The persisted service head; it is the allocated watermark. */
+export interface AllocatorState {
+    schemaVersion: 5;
+    allocatorLineageId: string;
+    allocatedWatermark: string | null;
+    bootstrapSeed: {
+        importId: string;
+        leaseEpoch: number;
+        highWatermark: string;
+    } | null;
+    /** Durable rate-limit key for rollback warnings; it is not allocation authority. */
+    lastRollbackWarningFingerprint?: string | null;
+    /** Service identity bound at first commit-scoped allocation; reconciler authority. */
+    serviceId?: string;
+}

package/dist/allocator/types.js

@@ -0,0 +1 @@
+export {};

package/dist/bootstrap/BootstrapCoordinatorDurableObject.d.ts

@@ -0,0 +1,28 @@
+import { type NativeTracing } from "../trace/CommitTrace";
+interface BootstrapCoordinatorEnv {
+    TAG: DurableObjectNamespace;
+    ALLOCATOR: DurableObjectNamespace;
+}
+/** Per-service authority and linearization point for bootstrap and normal writes. */
+export declare class BootstrapCoordinatorDurableObject implements DurableObject {
+    private readonly ctx;
+    private readonly env;
+    private readonly nativeTracing;
+    /** Constructor-scoped observation only; never persisted or used for control. */
+    private readonly activation;
+    constructor(ctx: DurableObjectState, env: BootstrapCoordinatorEnv, nativeTracing?: NativeTracing);
+    fetch(request: Request): Promise<Response>;
+    private traceCommand;
+    private control;
+    private valid;
+    private plan;
+    private chunks;
+    private import;
+    private verify;
+    private ready;
+    /** Operator abort retains the durable failed plan for audit/retry; it never clears target state. */
+    private abort;
+    private route;
+    private command;
+}
+export {};