@sekiban/dcb-runtime 0.2.0

package/dist/repair/RepairWorker.js

@@ -0,0 +1,461 @@
+import { scopeIdFor } from "../scope/ScopeName";
+import { envServiceIdentity, requireServiceIdentity } from "../service/ServiceIdentityProvider";
+import { CommitTrace, createTraceCorrelationId, stableTraceHash, } from "../trace/CommitTrace";
+import { verifyCommitTrace } from "../trace/CommitTraceVerifier";
+class RepairWorkerFailure extends Error {
+}
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function responseBody(response) {
+    return response.headers.get("content-type")?.includes("application/json") === true
+        ? response.json()
+        : Promise.resolve(undefined);
+}
+function itemKey(item) {
+    return `${item.attemptId}\u0000${item.eventId}\u0000${item.suid}`;
+}
+function hasPartialFence(facts, attemptId) {
+    return facts.fences.some((fence) => fence.reason === "partial_write" && fence.attemptId === attemptId);
+}
+function resolutionFor(facts, item) {
+    return facts.facts.resolutions.find((resolution) => resolution.attemptId === item.attemptId &&
+        resolution.eventId === item.eventId &&
+        resolution.suid === item.suid);
+}
+function auditFor(facts, item) {
+    return facts.facts.audits.some((audit) => audit.attemptId === item.attemptId && audit.eventId === item.eventId && audit.suid === item.suid);
+}
+function sortTaggedItems(items) {
+    return [...items].sort((left, right) => {
+        if (left.item.suid !== right.item.suid) {
+            return left.item.suid < right.item.suid ? -1 : 1;
+        }
+        const leftKey = `${left.tag}\u0000${itemKey(left.item)}`;
+        const rightKey = `${right.tag}\u0000${itemKey(right.item)}`;
+        return leftKey < rightKey ? -1 : leftKey > rightKey ? 1 : 0;
+    });
+}
+/**
+ * Per-request repair coordinator.  The only authority it trusts is a fresh
+ * Tag DO fact read; Journal records are append-only observations.
+ */
+export class RepairWorker {
+    env;
+    exclusions;
+    serviceId;
+    hooks;
+    constructor(env, exclusions, 
+    /** Tests and embedding hosts may supply a fixed identity explicitly. */
+    serviceId = requireServiceIdentity(envServiceIdentity(env)), hooks = {}) {
+        this.env = env;
+        this.exclusions = exclusions;
+        this.serviceId = serviceId;
+        this.hooks = hooks;
+    }
+    async execute(input) {
+        const executionId = crypto.randomUUID();
+        const trace = new CommitTrace({
+            schema: "sdt.commit.repair/v1",
+            correlationId: createTraceCorrelationId(),
+            serviceId: this.serviceId,
+            nativeTracing: this.hooks.nativeTracing,
+            sink: this.hooks.commitTraceSink,
+            clock: this.hooks.commitTraceClock,
+            provider: this.hooks.commitTraceProvider,
+            // Structural verification is an observation sink only. A malformed
+            // telemetry adapter can never change a repair's durable outcome.
+            runtimeVerifier: { verify: (snapshot) => { verifyCommitTrace(snapshot); } },
+        });
+        return trace.root("X00", {
+            face: "repair-root",
+            actorClass: "REPAIR",
+            actorKey: `repair:${this.serviceId}`,
+            attributes: { "repair.execution.id": executionId },
+        }, async (scope) => this.executeTraced(input, {
+            scope,
+            executionId,
+            leaseIds: new Map(),
+        }));
+    }
+    async executeTraced(input, trace) {
+        const workset = await this.enumerate(input.attemptIds, input.tags);
+        const filtered = workset.filter((entry) => input.checkpoint === undefined || entry.item.suid > input.checkpoint);
+        const bounded = filtered.slice(0, input.maxItems);
+        const checkpoint = bounded.length === 0 ? input.checkpoint ?? null : bounded[bounded.length - 1].item.suid;
+        if (input.mode === "dry-run") {
+            // Facts are intentionally read during planning so an operator can see
+            // which exact fences remain, while no mutation call is made.
+            await Promise.all([...new Set(workset.map((entry) => entry.tag))].map(async (tag, memberIndex) => {
+                if (trace === undefined)
+                    return this.tagFacts(tag);
+                return trace.scope.fork().span("X03p", {
+                    actorClass: "TAG",
+                    actorKey: `tag:${this.serviceId}:${tag}`,
+                    memberIndex,
+                    tag,
+                }, async () => this.tagFacts(tag));
+            }));
+            return {
+                mode: input.mode,
+                dryRun: true,
+                checkpoint,
+                processed: 0,
+                rolledForward: 0,
+                excludedAudited: 0,
+                failedClosed: 0,
+                cleared: 0,
+                pending: filtered.length,
+            };
+        }
+        const result = {
+            mode: input.mode,
+            dryRun: false,
+            checkpoint,
+            processed: 0,
+            rolledForward: 0,
+            excludedAudited: 0,
+            failedClosed: 0,
+            cleared: 0,
+            pending: Math.max(0, filtered.length - bounded.length),
+        };
+        const leases = new Map();
+        for (const [memberIndex, entry] of bounded.entries()) {
+            const before = await this.tagFacts(entry.tag);
+            // Resume after clear-before-final-observation: no mutation is needed,
+            // and the current Tag fact is sufficient to reconstruct completion.
+            if (!hasPartialFence(before, entry.item.attemptId) && resolutionFor(before, entry.item) !== undefined && auditFor(before, entry.item)) {
+                if (trace !== undefined) {
+                    // The row intentionally describes the durable-state decision only:
+                    // no repair mutation is reached on this branch.
+                    await trace.scope.fork().span("X03r", {
+                        actorClass: "TAG",
+                        actorKey: `tag:${this.serviceId}:${entry.tag}`,
+                        attemptId: entry.item.attemptId,
+                        memberIndex,
+                        tag: entry.tag,
+                    }, async () => undefined);
+                }
+                continue;
+            }
+            const leaseId = trace === undefined
+                ? undefined
+                : trace.leaseIds.get(entry.tag) ?? `repair-lease-${stableTraceHash(`${trace.executionId}:${entry.tag}`)}`;
+            if (trace !== undefined && leaseId !== undefined)
+                trace.leaseIds.set(entry.tag, leaseId);
+            const acquireLease = async () => this.ensureLease(entry.tag, input, workset, leases);
+            const needsLease = !leases.has(entry.tag);
+            const lease = trace === undefined || !needsLease
+                ? await acquireLease()
+                : await trace.scope.fork().span("X02", {
+                    actorClass: "TAG",
+                    actorKey: `tag:${this.serviceId}:${entry.tag}`,
+                    attemptId: entry.item.attemptId,
+                    memberIndex,
+                    tag: entry.tag,
+                    attributes: {
+                        "repair.lease.id": leaseId,
+                    },
+                }, acquireLease);
+            const executeItem = async () => {
+                if (input.fault === "after-lease-before-prepare") {
+                    return { ...result, interrupted: input.fault, pending: filtered.length };
+                }
+                await this.observe(entry.tag, entry.item, lease, "PREPARED");
+                if (input.fault === "after-prepare-before-apply") {
+                    return { ...result, interrupted: input.fault, pending: filtered.length };
+                }
+                let applied = await this.apply(entry.tag, entry.item, lease);
+                if (applied.status === 409 && applied.reason === "repair_scope_required") {
+                    // F3 discovered after the first scan: the failed call has no side
+                    // effect, then a fresh union makes the new work item eligible.
+                    const refreshed = await this.enumerate(input.attemptIds, input.tags);
+                    await this.unionScope(entry.tag, lease, refreshed.filter((candidate) => candidate.tag === entry.tag));
+                    applied = await this.apply(entry.tag, entry.item, lease);
+                }
+                if (applied.status !== 200 || applied.branch === undefined) {
+                    throw new RepairWorkerFailure(`Tag repair apply rejected: ${applied.reason ?? applied.status}`);
+                }
+                if (input.fault === "after-apply-before-observation") {
+                    return { ...result, interrupted: input.fault, pending: filtered.length };
+                }
+                const facts = await this.tagFacts(entry.tag);
+                const durable = resolutionFor(facts, entry.item);
+                if (durable === undefined) {
+                    throw new RepairWorkerFailure("Tag repair apply did not leave a durable resolution fact");
+                }
+                await this.observe(entry.tag, entry.item, lease, "VERIFIED", durable.branch);
+                if (input.fault === "after-verify-before-audit") {
+                    return { ...result, interrupted: input.fault, pending: filtered.length };
+                }
+                if (durable.branch === "FAILED_CLOSED") {
+                    result.failedClosed += 1;
+                    result.processed += 1;
+                    return undefined;
+                }
+                const alreadyAudited = auditFor(facts, entry.item);
+                if (durable.branch === "EXCLUDED_AUDITED") {
+                    if (!alreadyAudited) {
+                        await this.exclusions.recordExclusion({
+                            attemptId: entry.item.attemptId,
+                            tag: entry.tag,
+                            eventId: entry.item.eventId,
+                            suid: entry.item.suid,
+                            actor: input.actor,
+                            repairEpoch: lease.epoch,
+                        });
+                    }
+                    result.excludedAudited += 1;
+                }
+                else {
+                    result.rolledForward += 1;
+                }
+                if (!alreadyAudited) {
+                    await this.audit(entry.tag, entry.item, lease, input.actor);
+                }
+                if (input.fault === "after-audit-before-clear") {
+                    return { ...result, interrupted: input.fault, pending: filtered.length };
+                }
+                result.processed += 1;
+                return undefined;
+            };
+            const interrupted = trace === undefined
+                ? await executeItem()
+                : await trace.scope.fork().span("X03e", {
+                    actorClass: "TAG",
+                    actorKey: `tag:${this.serviceId}:${entry.tag}`,
+                    attemptId: entry.item.attemptId,
+                    memberIndex,
+                    tag: entry.tag,
+                    attributes: {
+                        "repair.lease.id": leaseId,
+                        repairEpoch: lease.epoch,
+                    },
+                }, executeItem);
+            if (interrupted !== undefined)
+                return interrupted;
+        }
+        // A clear can happen only against a fresh, stable scope snapshot.  The
+        // Tag DO rechecks every item/audit in the transaction that removes exactly
+        // one partial_write fence.
+        for (const tag of [...new Set(workset.map((entry) => entry.tag))]) {
+            const lease = leases.get(tag);
+            if (lease === undefined) {
+                continue;
+            }
+            const facts = await this.tagFacts(tag);
+            // A concurrently joined F2 must remain in the durable scope, but it
+            // must not block this bounded invocation from clearing its own exact
+            // F1 fence.  Its later workset will use the same unioned authority.
+            const activeAttempts = [...new Set(workset
+                    .filter((entry) => entry.tag === tag && hasPartialFence(facts, entry.item.attemptId))
+                    .map((entry) => entry.item.attemptId))];
+            for (const attemptId of activeAttempts) {
+                const attemptScope = facts.repairScope.filter((item) => item.attemptId === attemptId);
+                // A bounded invocation returns its checkpoint with the fence still
+                // held until every item in the stable durable scope has a Tag-side
+                // resolution and audit.  This is what makes resume safe.
+                if (attemptScope.some((item) => {
+                    const resolution = resolutionFor(facts, item);
+                    return resolution === undefined || resolution.branch === "FAILED_CLOSED" || !auditFor(facts, item);
+                })) {
+                    continue;
+                }
+                const response = await this.tagPost(tag, "/repair/clear", {
+                    owner: lease.owner,
+                    epoch: lease.epoch,
+                    attemptId,
+                    scopeVersion: facts.repairScopeVersion,
+                });
+                if (!response.ok) {
+                    const body = await responseBody(response);
+                    throw new RepairWorkerFailure(`Tag repair clear rejected: ${body?.error ?? response.status}`);
+                }
+                result.cleared += 1;
+            }
+        }
+        if (input.fault === "after-clear-before-final-observation") {
+            return { ...result, interrupted: input.fault, pending: filtered.length };
+        }
+        // Completion display is likewise reconstructed from current Tag facts;
+        // an interrupted final Journal write cannot resurrect a cleared fence.
+        await this.recordClearedObservations(workset, leases);
+        return result;
+    }
+    async enumerate(attemptIds, tags) {
+        const result = [];
+        for (const attemptId of attemptIds) {
+            const response = await this.journalGet(attemptId, "/repair/workset");
+            if (!response.ok) {
+                const body = await responseBody(response);
+                throw new RepairWorkerFailure(`Repair workset rejected for ${attemptId}: ${body?.error ?? response.status}`);
+            }
+            const workset = await responseBody(response);
+            if (workset === undefined || !Array.isArray(workset.candidates) || !Array.isArray(workset.missingTags)) {
+                throw new RepairWorkerFailure(`Repair workset for ${attemptId} was malformed`);
+            }
+            for (const tag of tags) {
+                if (!workset.missingTags.includes(tag)) {
+                    continue;
+                }
+                for (const candidate of workset.candidates) {
+                    if (!candidate.tags.includes(tag)) {
+                        continue;
+                    }
+                    if (candidate.allocatorLineageId === undefined) {
+                        throw new RepairWorkerFailure(`Repair workset for ${attemptId} lacks its allocator lineage`);
+                    }
+                    result.push({
+                        tag,
+                        item: {
+                            attemptId,
+                            eventId: candidate.eventId,
+                            suid: candidate.suid,
+                            payload: candidate.payload,
+                            eventTags: candidate.tags,
+                            allocatorLineageId: candidate.allocatorLineageId,
+                            eventType: candidate.eventType,
+                            provenance: "g32",
+                            timestamp: candidate.timestamp,
+                        },
+                    });
+                }
+            }
+        }
+        return sortTaggedItems(result);
+    }
+    async ensureLease(tag, input, workset, leases) {
+        const current = leases.get(tag);
+        if (current !== undefined) {
+            return current;
+        }
+        const scope = await this.activeScope(tag, workset);
+        if (scope.length === 0) {
+            throw new RepairWorkerFailure(`No durable partial_write fence remains for ${tag}`);
+        }
+        const acquire = await this.tagPost(tag, "/repair/acquire", { owner: input.owner, scope });
+        const body = await responseBody(acquire);
+        let lease;
+        if (acquire.status === 201 && typeof body?.epoch === "number") {
+            lease = { owner: input.owner, epoch: body.epoch };
+        }
+        else {
+            const facts = await this.tagFacts(tag);
+            if (facts.repairOwner !== input.owner || facts.repairLeaseUntil === null) {
+                throw new RepairWorkerFailure(`Repair lease is held by another owner for ${tag}: ${body?.error ?? acquire.status}`);
+            }
+            const renewed = await this.tagPost(tag, "/repair/renew", {
+                owner: input.owner,
+                epoch: facts.highestRepairEpoch,
+            });
+            if (!renewed.ok) {
+                const rejected = await responseBody(renewed);
+                throw new RepairWorkerFailure(`Repair lease cannot be renewed for ${tag}: ${rejected?.error ?? renewed.status}`);
+            }
+            lease = { owner: input.owner, epoch: facts.highestRepairEpoch };
+        }
+        await this.unionScope(tag, lease, workset.filter((entry) => entry.tag === tag));
+        leases.set(tag, lease);
+        return lease;
+    }
+    async activeScope(tag, workset) {
+        const facts = await this.tagFacts(tag);
+        const items = workset
+            .filter((entry) => entry.tag === tag && hasPartialFence(facts, entry.item.attemptId))
+            .map((entry) => entry.item);
+        return [...new Map(items.map((item) => [itemKey(item), item])).values()];
+    }
+    async unionScope(tag, lease, workset) {
+        const scope = await this.activeScope(tag, workset);
+        if (scope.length === 0) {
+            return;
+        }
+        const response = await this.tagPost(tag, "/repair/scope-union", { ...lease, scope });
+        if (!response.ok) {
+            const body = await responseBody(response);
+            throw new RepairWorkerFailure(`Repair scope union rejected: ${body?.error ?? response.status}`);
+        }
+    }
+    async apply(tag, item, lease) {
+        const response = await this.tagPost(tag, "/repair/apply", { ...lease, item });
+        const body = await responseBody(response);
+        return { status: response.status, reason: body?.reason ?? body?.error, branch: body?.status };
+    }
+    async audit(tag, item, lease, actor) {
+        const response = await this.tagPost(tag, "/repair/audit", { ...lease, item, actor });
+        if (!response.ok) {
+            const body = await responseBody(response);
+            throw new RepairWorkerFailure(`Repair audit rejected: ${body?.error ?? response.status}`);
+        }
+    }
+    async observe(tag, item, lease, phase, branch) {
+        const response = await this.journalPost(item.attemptId, "/repair/observation", {
+            owner: lease.owner,
+            epoch: lease.epoch,
+            tag,
+            attemptId: item.attemptId,
+            eventId: item.eventId,
+            suid: item.suid,
+            phase,
+            ...(branch === undefined ? {} : { branch }),
+        });
+        if (!response.ok) {
+            const body = await responseBody(response);
+            throw new RepairWorkerFailure(`Repair observation rejected: ${body?.error ?? response.status}`);
+        }
+    }
+    async recordClearedObservations(workset, leases) {
+        for (const entry of workset) {
+            const facts = await this.tagFacts(entry.tag);
+            const durable = resolutionFor(facts, entry.item);
+            if (durable !== undefined && durable.branch !== "FAILED_CLOSED" && auditFor(facts, entry.item) && !hasPartialFence(facts, entry.item.attemptId)) {
+                const lease = leases.get(entry.tag) ?? { owner: durable.owner, epoch: durable.epoch };
+                await this.observe(entry.tag, entry.item, lease, "CLEARED", durable.branch);
+            }
+        }
+    }
+    journalFor(attemptId) {
+        return this.env.JOURNAL.get(scopeIdFor(this.env.JOURNAL, {
+            serviceId: this.serviceId,
+            doClass: "journal",
+            identity: attemptId,
+        }));
+    }
+    tagFor(tag) {
+        return this.env.TAG.get(scopeIdFor(this.env.TAG, {
+            serviceId: this.serviceId,
+            doClass: "tag",
+            identity: tag,
+        }));
+    }
+    journalGet(attemptId, path) {
+        return this.journalFor(attemptId).fetch(`https://repair.internal${path}`);
+    }
+    journalPost(attemptId, path, body) {
+        return this.journalFor(attemptId).fetch(`https://repair.internal${path}`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify(body),
+        });
+    }
+    async tagFacts(tag) {
+        const response = await this.tagFor(tag).fetch(`https://repair.internal/repair/facts?__tag=${encodeURIComponent(tag)}`);
+        if (!response.ok) {
+            const body = await responseBody(response);
+            throw new RepairWorkerFailure(`Tag facts rejected for ${tag}: ${body?.error ?? response.status}`);
+        }
+        const facts = await responseBody(response);
+        if (facts === undefined || facts.tag !== tag || !isObject(facts)) {
+            throw new RepairWorkerFailure(`Tag facts were malformed for ${tag}`);
+        }
+        return facts;
+    }
+    tagPost(tag, path, body) {
+        return this.tagFor(tag).fetch(`https://repair.internal${path}?__tag=${encodeURIComponent(tag)}`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify(body),
+        });
+    }
+}
+export { RepairWorkerFailure };

package/dist/safeWindow.d.ts

@@ -0,0 +1,20 @@
+/** Published read-side SafeWindow bounds from the SDT-G11 ruling. */
+export declare const PUBLISHED_SAFE_WINDOW_MS = 20000;
+export declare const MAX_PUBLISHED_SAFE_WINDOW_MS = 120000;
+/**
+ * A lag sample is a current estimate, not a high-water mark.  The estimate
+ * therefore loses one millisecond for every millisecond it has been idle and
+ * never falls below the published floor.
+ */
+export declare function decayedLagEstimateMs(estimateMs: number, observedAtMs: number, nowMs: number): number;
+/** Clamp a valid estimate to the wire-visible SafeWindow ceiling. */
+export declare function safeWindowMs(dynamicLagBoundMs: number): number;
+export declare function safeWindowCeilingExceeded(dynamicLagBoundMs: number): boolean;
+/**
+ * C# parity utility only: build the SafeWindow frontier in .NET ticks rather
+ * than substituting the historical 5-second helper or a wall-clock string.
+ * The minimum random suffix makes equality include every event at the cutoff
+ * tick; callers compare only validated 30-digit SUIDs.
+ */
+export declare function safeWindowCutoffSuid(nowMs: number, dynamicLagBoundMs: number): string;
+export declare function isSortableUniqueIdSafeAt(suid: string, nowMs: number, dynamicLagBoundMs: number): boolean;

package/dist/safeWindow.js

@@ -0,0 +1,36 @@
+/** Published read-side SafeWindow bounds from the SDT-G11 ruling. */
+export const PUBLISHED_SAFE_WINDOW_MS = 20_000;
+export const MAX_PUBLISHED_SAFE_WINDOW_MS = 120_000;
+/**
+ * A lag sample is a current estimate, not a high-water mark.  The estimate
+ * therefore loses one millisecond for every millisecond it has been idle and
+ * never falls below the published floor.
+ */
+export function decayedLagEstimateMs(estimateMs, observedAtMs, nowMs) {
+    const elapsed = Math.max(0, nowMs - observedAtMs);
+    return Math.max(0, estimateMs - elapsed);
+}
+/** Clamp a valid estimate to the wire-visible SafeWindow ceiling. */
+export function safeWindowMs(dynamicLagBoundMs) {
+    return Math.min(MAX_PUBLISHED_SAFE_WINDOW_MS, Math.max(PUBLISHED_SAFE_WINDOW_MS, dynamicLagBoundMs));
+}
+export function safeWindowCeilingExceeded(dynamicLagBoundMs) {
+    return dynamicLagBoundMs > MAX_PUBLISHED_SAFE_WINDOW_MS;
+}
+/**
+ * C# parity utility only: build the SafeWindow frontier in .NET ticks rather
+ * than substituting the historical 5-second helper or a wall-clock string.
+ * The minimum random suffix makes equality include every event at the cutoff
+ * tick; callers compare only validated 30-digit SUIDs.
+ */
+export function safeWindowCutoffSuid(nowMs, dynamicLagBoundMs) {
+    if (!Number.isSafeInteger(nowMs) || nowMs < 0)
+        throw new Error("SafeWindow now must be a non-negative safe integer");
+    const cutoffMs = Math.max(0, nowMs - safeWindowMs(dynamicLagBoundMs));
+    return formatSortableUniqueId(unixMsToDotNetTicks(cutoffMs), 0n);
+}
+export function isSortableUniqueIdSafeAt(suid, nowMs, dynamicLagBoundMs) {
+    assertSortableUniqueId(suid);
+    return compareSortableUniqueId(suid, safeWindowCutoffSuid(nowMs, dynamicLagBoundMs)) <= 0;
+}
+import { assertSortableUniqueId, compareSortableUniqueId, formatSortableUniqueId, unixMsToDotNetTicks, } from "./allocator/SortableUniqueId";

package/dist/scope/ControlRouteScope.d.ts

@@ -0,0 +1,22 @@
+import { type ServiceIdentityProvider, type ServiceIdentityRequestOptions } from "../service/ServiceIdentityProvider";
+export type ScopedControlRoute = "bootstrap" | "tag" | "operator-bootstrap";
+export interface ScopedControlRouteInput {
+    readonly request: Request;
+    readonly provider: ServiceIdentityProvider;
+    readonly pathServiceId: string;
+    readonly route: ScopedControlRoute;
+    readonly requestOptions?: ServiceIdentityRequestOptions;
+}
+export type ScopedControlRouteResult = Readonly<{
+    readonly serviceId: string;
+}> | Readonly<{
+    readonly response: Response;
+}>;
+/** A typed platform-fault response; no control route may invent an identity. */
+export declare function scopeIdentityMissingResponse(): Response;
+/**
+ * Checks a path-owned identity before the caller can obtain a Durable Object
+ * stub. Logs intentionally retain only the failure class and route, never the
+ * configured deployment identity.
+ */
+export declare function enforceControlRouteScope(input: ScopedControlRouteInput): ScopedControlRouteResult;

package/dist/scope/ControlRouteScope.js

@@ -0,0 +1,36 @@
+import { ServiceIdentityMissingError, } from "../service/ServiceIdentityProvider";
+function response(status, code, error) {
+    return new Response(JSON.stringify({ code, error }), {
+        status,
+        headers: { "content-type": "application/json; charset=utf-8" },
+    });
+}
+/** A typed platform-fault response; no control route may invent an identity. */
+export function scopeIdentityMissingResponse() {
+    return response(503, "scope.identity_missing", "A deployment service identity is required for this scope");
+}
+/**
+ * Checks a path-owned identity before the caller can obtain a Durable Object
+ * stub. Logs intentionally retain only the failure class and route, never the
+ * configured deployment identity.
+ */
+export function enforceControlRouteScope(input) {
+    let actual;
+    try {
+        actual = input.provider.forRequest(input.request, input.requestOptions).serviceId;
+    }
+    catch (caught) {
+        if (caught instanceof ServiceIdentityMissingError) {
+            console.error({ schema: "sdt.scope/v1", code: "scope.identity_missing", route: input.route });
+            return { response: scopeIdentityMissingResponse() };
+        }
+        throw caught;
+    }
+    if (input.pathServiceId !== actual) {
+        console.warn({ schema: "sdt.scope/v1", code: "scope.mismatch", route: input.route });
+        return {
+            response: response(403, "scope.mismatch", "The path service identity is not authorized for this deployment"),
+        };
+    }
+    return { serviceId: actual };
+}

package/dist/scope/ScopeName.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The one durable-object physical-name grammar used by the runtime.
+ *
+ * A scope name is deliberately not an application protocol value: C-0 makes
+ * old Durable Object instances unreachable when this grammar changes.  The
+ * service, class, and identity parts remain individually inspectable while
+ * `/` is the only grammar separator.
+ */
+export declare const DURABLE_OBJECT_SCOPE_CLASSES: readonly ["tag", "tag-state", "allocator", "bootstrap", "journal"];
+export type DurableObjectScopeClass = (typeof DURABLE_OBJECT_SCOPE_CLASSES)[number];
+export interface DurableObjectScope {
+    readonly serviceId: string;
+    readonly doClass: DurableObjectScopeClass;
+    readonly identity: string;
+}
+export declare class ScopeNameError extends Error {
+    constructor(message: string);
+}
+/** The existing deploy-time SDT_SERVICE_ID grammar, shared by scope names. */
+export declare function isScopeServiceId(value: unknown): value is string;
+/** Builds the canonical `${serviceId}/${doClass}/${identity}` physical name. */
+export declare function buildScopeName(scope: DurableObjectScope): string;
+/** Parses and fully validates one canonical Durable Object physical name. */
+export declare function parseScopeName(name: string): DurableObjectScope;
+/**
+ * Keep the platform namespace call in this module so all runtime call sites
+ * first pass through the one public grammar above.
+ */
+export interface ScopeNameNamespace<Id> {
+    idFromName(name: string): Id;
+}
+export declare function scopeIdFor<Id>(namespace: ScopeNameNamespace<Id>, scope: DurableObjectScope): Id;
+/** A stable component encoding inside the single opaque tag-state identity. */
+export declare function tagStateScopeIdentity(tag: string, projectorId: string): string;