codex-chatgpt-control 0.5.1-alpha.2 → 0.5.1-alpha.4

package/dist/src/runtime/operation-context.d.ts

@@ -0,0 +1,142 @@
+import { type BrowserResourceKey, type TabResourceKey } from "./tab-coordinator.js";
+export type OperationRuntimeCoordinationScope = "tab" | "provider";
+export type OperationRuntimeClaimReason = "missing" | "unsupported" | "unverifiable";
+export type OperationRuntimeAuthoritativeClaim = Readonly<{
+    status: "available";
+    token: string;
+    epoch: number;
+} | {
+    status: "unavailable";
+    reason: OperationRuntimeClaimReason;
+}>;
+/**
+ * Capabilities are provider-advertised facts.  Missing fields intentionally
+ * mean false; an older or partial provider must never be treated as
+ * concurrent-tab safe by inference.
+ */
+export type OperationRuntimeCapabilities = Readonly<{
+    stableProviderId: boolean;
+    stableBrowserId: boolean;
+    stableTabId: boolean;
+    authoritativeTabClaim: boolean;
+    concurrentTabs: boolean;
+}>;
+export type OperationRuntimeOwner = Readonly<{
+    backendSessionId: string;
+    operationId: string;
+}>;
+export type OperationRuntimeContextInput<Page extends object = object> = Readonly<{
+    providerId?: string;
+    browserId?: string;
+    tabId?: string;
+    page: Page;
+    authoritativeClaim?: OperationRuntimeAuthoritativeClaim;
+    owner: OperationRuntimeOwner;
+    capabilities?: Partial<OperationRuntimeCapabilities>;
+    targetBindingDigest: string;
+    /** Reject construction if an exact tab-scoped owner cannot be proven. */
+    requireExactTabOwnership?: boolean;
+}>;
+export type OperationRuntimeContextChildOptions = Readonly<{
+    operationId?: string;
+    targetBindingDigest?: string;
+}>;
+export type OperationRuntimeAffinityObservation = Readonly<{
+    tabId?: string;
+    authoritativeClaim?: OperationRuntimeAuthoritativeClaim;
+}>;
+export type OperationRuntimeResourceSelection = Readonly<{
+    scope: OperationRuntimeCoordinationScope;
+    resourceKind: "tab" | "browser";
+    resourceKey: TabResourceKey | BrowserResourceKey;
+    exactTabOwnership: boolean;
+    downgraded: boolean;
+    downgradeReasons: readonly OperationRuntimeDowngradeReason[];
+}>;
+export type OperationRuntimeDowngradeReason = "provider_identity_unavailable" | "browser_identity_unavailable" | "tab_identity_unavailable" | "provider_identity_not_advertised" | "browser_identity_not_advertised" | "tab_identity_not_advertised" | "authoritative_claim_unavailable" | "authoritative_claim_not_advertised" | "concurrent_tabs_not_advertised";
+export type OperationRuntimeContextDiagnostics = Readonly<{
+    status: "ready";
+    scope: OperationRuntimeCoordinationScope;
+    resourceKind: "tab" | "browser";
+    exactTabOwnership: boolean;
+    downgraded: boolean;
+    downgradeReasons: readonly OperationRuntimeDowngradeReason[];
+    identities: Readonly<{
+        provider: "available" | "unavailable";
+        browser: "available" | "unavailable";
+        tab: "available" | "unavailable";
+    }>;
+    page: "bound";
+    authoritativeClaim: "available" | "unavailable";
+    owner: "bound";
+    targetBinding: "bound";
+}>;
+export type OperationRuntimeContextCapture<Page extends object = object> = Readonly<{
+    page: Page;
+    providerId?: string;
+    browserId?: string;
+    tabId?: string;
+    authoritativeClaim: OperationRuntimeAuthoritativeClaim;
+    owner: OperationRuntimeOwner;
+    capabilities: OperationRuntimeCapabilities;
+    coordinationScope: OperationRuntimeCoordinationScope;
+    targetBindingDigest: string;
+    resource: OperationRuntimeResourceSelection;
+    assertPageAffinity: (page: unknown, observation?: OperationRuntimeAffinityObservation) => OperationRuntimeAffinityResult;
+}>;
+export type OperationRuntimeAffinityResult = Readonly<{
+    pageMatches: true;
+    tabMatches: boolean;
+    claimMatches: boolean;
+    exactTabOwnership: boolean;
+}>;
+export type OperationRuntimeContextErrorCode = "invalid_context" | "exact_ownership_unavailable" | "page_affinity_mismatch" | "tab_affinity_mismatch" | "claim_drift";
+/** Error diagnostics contain statuses only; no IDs, digests, claim tokens, or page values. */
+export declare class OperationRuntimeContextError extends Error {
+    readonly code: OperationRuntimeContextErrorCode;
+    readonly diagnostics?: OperationRuntimeContextDiagnostics;
+    constructor(code: OperationRuntimeContextErrorCode, message: string, diagnostics?: OperationRuntimeContextDiagnostics);
+}
+/**
+ * Immutable operation-scoped browser context.  A context is intentionally
+ * independent from RuntimeEnv and can be passed to a future command adapter
+ * without changing legacy command behavior.
+ */
+export declare class OperationRuntimeContext<Page extends object = object> {
+    #private;
+    readonly providerId: string | undefined;
+    readonly browserId: string | undefined;
+    readonly tabId: string | undefined;
+    readonly page: Page;
+    readonly authoritativeClaim: OperationRuntimeAuthoritativeClaim;
+    readonly owner: OperationRuntimeOwner;
+    readonly capabilities: OperationRuntimeCapabilities;
+    readonly coordinationScope: OperationRuntimeCoordinationScope;
+    readonly targetBindingDigest: string;
+    private constructor();
+    /** Fail-closed context construction with deterministic provider-wide fallback. */
+    static create<Page extends object = object>(input: OperationRuntimeContextInput<Page>): OperationRuntimeContext<Page>;
+    /** Alias for adapters that prefer a factory-style name. */
+    static bind<Page extends object = object>(input: OperationRuntimeContextInput<Page>): OperationRuntimeContext<Page>;
+    /** The exact coordinator actor resource; never returns tab scope after downgrade. */
+    coordinatorResource(): OperationRuntimeResourceSelection;
+    /** Status-only diagnostics suitable for logs and blockers. */
+    diagnostics(): OperationRuntimeContextDiagnostics;
+    /**
+     * Create a child operation view without permitting a new page, tab, claim, or
+     * capability to be smuggled into the existing ownership domain.
+     */
+    child(options?: OperationRuntimeContextChildOptions): OperationRuntimeContext<Page>;
+    /**
+     * Capture an immutable page-aware view.  It retains the same page identity;
+     * it cannot be used to replace this context's page or ownership metadata.
+     */
+    capture(): OperationRuntimeContextCapture<Page>;
+    /**
+     * Verify both page object identity and all available stable ownership
+     * evidence.  A context with an exact tab binding requires an explicit
+     * observed stable tab ID and (when bound) the current authoritative claim.
+     */
+    assertPageAffinity(page: unknown, observation?: OperationRuntimeAffinityObservation): OperationRuntimeAffinityResult;
+}
+export declare function createOperationRuntimeContext<Page extends object = object>(input: OperationRuntimeContextInput<Page>): OperationRuntimeContext<Page>;

package/dist/src/runtime/operation-context.js

@@ -0,0 +1,410 @@
+import { createBrowserResourceKey, createTabResourceKey } from "./tab-coordinator.js";
+/**
+ * An operation context owns one page reference for the lifetime of an
+ * operation.  It deliberately does not accept a RuntimeEnv: a mutable
+ * `RuntimeEnv.page` can be replaced by another request while a command is
+ * awaiting a browser call.  Contexts instead capture a page once and expose
+ * an explicit affinity check at every adapter boundary.
+ */
+const INVALID_ID_VALUES = new Set(["unknown", "undefined", "null", "n/a", "na"]);
+const UNKNOWN_PROVIDER_ID = "operation-context-provider-identity-unavailable";
+const UNKNOWN_BROWSER_ID = "operation-context-browser-identity-unavailable";
+const MAX_ID_LENGTH = 512;
+const MAX_DIGEST_LENGTH = 1024;
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+const HMAC_DIGEST_PATTERN = /^hmac-sha256:[0-9a-f]{64}$/;
+/** Error diagnostics contain statuses only; no IDs, digests, claim tokens, or page values. */
+export class OperationRuntimeContextError extends Error {
+    code;
+    diagnostics;
+    constructor(code, message, diagnostics) {
+        super(message);
+        this.name = "OperationRuntimeContextError";
+        this.code = code;
+        if (diagnostics !== undefined)
+            this.diagnostics = diagnostics;
+    }
+}
+function isRecord(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return false;
+    try {
+        const prototype = Object.getPrototypeOf(value);
+        return prototype === Object.prototype || prototype === null;
+    }
+    catch {
+        return false;
+    }
+}
+function assertRecord(value, label) {
+    if (!isRecord(value))
+        throw invalid(`${label} must be a plain object`);
+    try {
+        for (const key of Object.keys(value)) {
+            const descriptor = Object.getOwnPropertyDescriptor(value, key);
+            if (descriptor?.get !== undefined || descriptor?.set !== undefined) {
+                throw invalid(`${label} must not contain accessor properties`);
+            }
+        }
+    }
+    catch (error) {
+        if (error instanceof OperationRuntimeContextError)
+            throw error;
+        throw invalid(`${label} must be a stable plain object`);
+    }
+}
+function assertExactKeys(value, label, allowed) {
+    const allowedSet = new Set(allowed);
+    try {
+        for (const key of Object.keys(value)) {
+            if (key.startsWith("_") || !allowedSet.has(key)) {
+                throw invalid(`${label} contains an unsupported field`);
+            }
+        }
+    }
+    catch (error) {
+        if (error instanceof OperationRuntimeContextError)
+            throw error;
+        throw invalid(`${label} contains unsupported fields`);
+    }
+}
+function invalid(message) {
+    // Do not interpolate caller-controlled values into context errors.  This
+    // protects diagnostics from leaking IDs, paths, digests, or page metadata.
+    return new OperationRuntimeContextError("invalid_context", message);
+}
+function validateBoolean(value, label) {
+    if (typeof value !== "boolean")
+        throw invalid(`${label} must be a boolean`);
+    return value;
+}
+function validateRequiredString(value, label, maxLength = MAX_ID_LENGTH) {
+    if (typeof value !== "string")
+        throw invalid(`${label} must be a string`);
+    const normalized = value.trim();
+    if (normalized.length === 0 ||
+        normalized.length > maxLength ||
+        INVALID_ID_VALUES.has(normalized.toLowerCase()) ||
+        /[\u0000-\u001f\u007f]/u.test(normalized)) {
+        throw invalid(`${label} must be a known stable value`);
+    }
+    return normalized;
+}
+function validateTargetBindingDigest(value, label = "targetBindingDigest") {
+    const digest = validateRequiredString(value, label, MAX_DIGEST_LENGTH);
+    if (!HMAC_DIGEST_PATTERN.test(digest))
+        throw invalid(`${label} must be a canonical HMAC digest`);
+    return digest;
+}
+function normalizeOptionalIdentity(value, label) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== "string")
+        throw invalid(`${label} must be a string when present`);
+    const normalized = value.trim();
+    if (normalized.length === 0 || INVALID_ID_VALUES.has(normalized.toLowerCase()))
+        return undefined;
+    if (normalized.length > MAX_ID_LENGTH || /[\u0000-\u001f\u007f]/u.test(normalized)) {
+        throw invalid(`${label} is not a valid stable identity`);
+    }
+    return normalized;
+}
+function normalizeCapabilities(value) {
+    if (value === undefined) {
+        return Object.freeze({
+            stableProviderId: false,
+            stableBrowserId: false,
+            stableTabId: false,
+            authoritativeTabClaim: false,
+            concurrentTabs: false
+        });
+    }
+    assertRecord(value, "capabilities");
+    assertExactKeys(value, "capabilities", [
+        "stableProviderId",
+        "stableBrowserId",
+        "stableTabId",
+        "authoritativeTabClaim",
+        "concurrentTabs"
+    ]);
+    return Object.freeze({
+        stableProviderId: value.stableProviderId === undefined ? false : validateBoolean(value.stableProviderId, "capabilities.stableProviderId"),
+        stableBrowserId: value.stableBrowserId === undefined ? false : validateBoolean(value.stableBrowserId, "capabilities.stableBrowserId"),
+        stableTabId: value.stableTabId === undefined ? false : validateBoolean(value.stableTabId, "capabilities.stableTabId"),
+        authoritativeTabClaim: value.authoritativeTabClaim === undefined ? false : validateBoolean(value.authoritativeTabClaim, "capabilities.authoritativeTabClaim"),
+        concurrentTabs: value.concurrentTabs === undefined ? false : validateBoolean(value.concurrentTabs, "capabilities.concurrentTabs")
+    });
+}
+function normalizeOwner(value) {
+    assertRecord(value, "owner");
+    assertExactKeys(value, "owner", ["backendSessionId", "operationId"]);
+    const backendSessionId = validateRequiredString(value.backendSessionId, "owner.backendSessionId");
+    const operationId = validateRequiredString(value.operationId, "owner.operationId");
+    if (!UUID_PATTERN.test(backendSessionId))
+        throw invalid("owner.backendSessionId must be a canonical UUID");
+    if (!UUID_PATTERN.test(operationId))
+        throw invalid("owner.operationId must be a canonical UUID");
+    return Object.freeze({
+        backendSessionId,
+        operationId
+    });
+}
+function normalizeClaim(value) {
+    if (value === undefined)
+        return Object.freeze({ status: "unavailable", reason: "missing" });
+    assertRecord(value, "authoritativeClaim");
+    if (value.status === "available") {
+        assertExactKeys(value, "authoritativeClaim", ["status", "token", "epoch"]);
+        if (!Number.isSafeInteger(value.epoch) || value.epoch < 0) {
+            throw invalid("authoritativeClaim.epoch must be a non-negative safe integer");
+        }
+        return Object.freeze({
+            status: "available",
+            token: validateRequiredString(value.token, "authoritativeClaim.token"),
+            epoch: value.epoch
+        });
+    }
+    if (value.status === "unavailable") {
+        assertExactKeys(value, "authoritativeClaim", ["status", "reason"]);
+        if (value.reason !== "missing" && value.reason !== "unsupported" && value.reason !== "unverifiable") {
+            throw invalid("authoritativeClaim.reason is invalid");
+        }
+        return Object.freeze({ status: "unavailable", reason: value.reason });
+    }
+    throw invalid("authoritativeClaim.status is invalid");
+}
+function claimMatches(expected, observed) {
+    if (expected.status === "unavailable")
+        return true;
+    return observed?.status === "available"
+        && observed.token === expected.token
+        && observed.epoch === expected.epoch;
+}
+function cloneClaim(claim) {
+    return claim.status === "available"
+        ? Object.freeze({ status: "available", token: claim.token, epoch: claim.epoch })
+        : Object.freeze({ status: "unavailable", reason: claim.reason });
+}
+function createFallbackBrowserKey(providerId, browserId) {
+    if (providerId === undefined || browserId === undefined) {
+        return createBrowserResourceKey(UNKNOWN_PROVIDER_ID, UNKNOWN_BROWSER_ID);
+    }
+    return createBrowserResourceKey(providerId, browserId);
+}
+function computeResource(providerId, browserId, tabId, claim, capabilities) {
+    const providerAvailable = providerId !== undefined;
+    const browserAvailable = browserId !== undefined;
+    const tabAvailable = tabId !== undefined;
+    const reasons = [];
+    if (!providerAvailable)
+        reasons.push("provider_identity_unavailable");
+    if (!browserAvailable)
+        reasons.push("browser_identity_unavailable");
+    if (!tabAvailable)
+        reasons.push("tab_identity_unavailable");
+    if (!capabilities.stableProviderId)
+        reasons.push("provider_identity_not_advertised");
+    if (!capabilities.stableBrowserId)
+        reasons.push("browser_identity_not_advertised");
+    if (!capabilities.stableTabId)
+        reasons.push("tab_identity_not_advertised");
+    if (claim.status !== "available")
+        reasons.push("authoritative_claim_unavailable");
+    if (!capabilities.authoritativeTabClaim)
+        reasons.push("authoritative_claim_not_advertised");
+    if (!capabilities.concurrentTabs)
+        reasons.push("concurrent_tabs_not_advertised");
+    const exactTabOwnership = providerAvailable
+        && browserAvailable
+        && tabAvailable
+        && capabilities.stableProviderId
+        && capabilities.stableBrowserId
+        && capabilities.stableTabId
+        && capabilities.authoritativeTabClaim
+        && claim.status === "available";
+    if (exactTabOwnership && capabilities.concurrentTabs) {
+        return Object.freeze({
+            scope: "tab",
+            resourceKind: "tab",
+            resourceKey: createTabResourceKey(providerId, browserId, tabId),
+            exactTabOwnership: true,
+            downgraded: false,
+            downgradeReasons: Object.freeze([])
+        });
+    }
+    return Object.freeze({
+        scope: "provider",
+        resourceKind: "browser",
+        resourceKey: createFallbackBrowserKey(providerId, browserId),
+        exactTabOwnership,
+        downgraded: true,
+        downgradeReasons: Object.freeze([...new Set(reasons)])
+    });
+}
+function redactedDiagnostics(resource, providerId, browserId, tabId, claim) {
+    return Object.freeze({
+        status: "ready",
+        scope: resource.scope,
+        resourceKind: resource.resourceKind,
+        exactTabOwnership: resource.exactTabOwnership,
+        downgraded: resource.downgraded,
+        downgradeReasons: Object.freeze([...resource.downgradeReasons]),
+        identities: Object.freeze({
+            provider: providerId === undefined ? "unavailable" : "available",
+            browser: browserId === undefined ? "unavailable" : "available",
+            tab: tabId === undefined ? "unavailable" : "available"
+        }),
+        page: "bound",
+        authoritativeClaim: claim.status,
+        owner: "bound",
+        targetBinding: "bound"
+    });
+}
+function validateAffinityObservation(value) {
+    if (value === undefined)
+        return Object.freeze({});
+    assertRecord(value, "affinity observation");
+    assertExactKeys(value, "affinity observation", ["tabId", "authoritativeClaim"]);
+    const tabId = normalizeOptionalIdentity(value.tabId, "affinity observation.tabId");
+    const authoritativeClaim = value.authoritativeClaim === undefined
+        ? undefined
+        : normalizeClaim(value.authoritativeClaim);
+    return Object.freeze({
+        ...(tabId === undefined ? {} : { tabId }),
+        ...(authoritativeClaim === undefined ? {} : { authoritativeClaim })
+    });
+}
+/**
+ * Immutable operation-scoped browser context.  A context is intentionally
+ * independent from RuntimeEnv and can be passed to a future command adapter
+ * without changing legacy command behavior.
+ */
+export class OperationRuntimeContext {
+    providerId;
+    browserId;
+    tabId;
+    page;
+    authoritativeClaim;
+    owner;
+    capabilities;
+    coordinationScope;
+    targetBindingDigest;
+    #resourceSelection;
+    #diagnosticsView;
+    constructor(providerId, browserId, tabId, page, authoritativeClaim, owner, capabilities, targetBindingDigest, requireExactTabOwnership) {
+        this.providerId = providerId;
+        this.browserId = browserId;
+        this.tabId = tabId;
+        this.page = page;
+        this.authoritativeClaim = cloneClaim(authoritativeClaim);
+        this.owner = Object.freeze({ ...owner });
+        this.capabilities = Object.freeze({ ...capabilities });
+        this.targetBindingDigest = targetBindingDigest;
+        this.#resourceSelection = computeResource(providerId, browserId, tabId, this.authoritativeClaim, this.capabilities);
+        this.coordinationScope = this.#resourceSelection.scope;
+        this.#diagnosticsView = redactedDiagnostics(this.#resourceSelection, providerId, browserId, tabId, this.authoritativeClaim);
+        if (requireExactTabOwnership && !this.#resourceSelection.exactTabOwnership) {
+            throw new OperationRuntimeContextError("exact_ownership_unavailable", "Exact tab ownership is unavailable for this context.", this.#diagnosticsView);
+        }
+        Object.freeze(this);
+    }
+    /** Fail-closed context construction with deterministic provider-wide fallback. */
+    static create(input) {
+        assertRecord(input, "operation context");
+        assertExactKeys(input, "operation context", [
+            "providerId",
+            "browserId",
+            "tabId",
+            "page",
+            "authoritativeClaim",
+            "owner",
+            "capabilities",
+            "targetBindingDigest",
+            "requireExactTabOwnership"
+        ]);
+        if (typeof input.page !== "object" || input.page === null || Array.isArray(input.page)) {
+            throw invalid("page must be a non-null object");
+        }
+        const requireExactTabOwnership = input.requireExactTabOwnership === undefined
+            ? false
+            : validateBoolean(input.requireExactTabOwnership, "requireExactTabOwnership");
+        const context = new OperationRuntimeContext(normalizeOptionalIdentity(input.providerId, "providerId"), normalizeOptionalIdentity(input.browserId, "browserId"), normalizeOptionalIdentity(input.tabId, "tabId"), input.page, normalizeClaim(input.authoritativeClaim), normalizeOwner(input.owner), normalizeCapabilities(input.capabilities), validateTargetBindingDigest(input.targetBindingDigest), requireExactTabOwnership);
+        return context;
+    }
+    /** Alias for adapters that prefer a factory-style name. */
+    static bind(input) {
+        return OperationRuntimeContext.create(input);
+    }
+    /** The exact coordinator actor resource; never returns tab scope after downgrade. */
+    coordinatorResource() {
+        return this.#resourceSelection;
+    }
+    /** Status-only diagnostics suitable for logs and blockers. */
+    diagnostics() {
+        return this.#diagnosticsView;
+    }
+    /**
+     * Create a child operation view without permitting a new page, tab, claim, or
+     * capability to be smuggled into the existing ownership domain.
+     */
+    child(options = {}) {
+        assertRecord(options, "child options");
+        assertExactKeys(options, "child options", ["operationId", "targetBindingDigest"]);
+        const operationId = options.operationId === undefined
+            ? this.owner.operationId
+            : validateRequiredString(options.operationId, "child options.operationId");
+        if (!UUID_PATTERN.test(operationId))
+            throw invalid("child options.operationId must be a canonical UUID");
+        const targetBindingDigest = options.targetBindingDigest === undefined
+            ? this.targetBindingDigest
+            : validateTargetBindingDigest(options.targetBindingDigest, "child options.targetBindingDigest");
+        return new OperationRuntimeContext(this.providerId, this.browserId, this.tabId, this.page, this.authoritativeClaim, Object.freeze({ backendSessionId: this.owner.backendSessionId, operationId }), this.capabilities, targetBindingDigest, false);
+    }
+    /**
+     * Capture an immutable page-aware view.  It retains the same page identity;
+     * it cannot be used to replace this context's page or ownership metadata.
+     */
+    capture() {
+        const context = this;
+        return Object.freeze({
+            page: this.page,
+            ...(this.providerId === undefined ? {} : { providerId: this.providerId }),
+            ...(this.browserId === undefined ? {} : { browserId: this.browserId }),
+            ...(this.tabId === undefined ? {} : { tabId: this.tabId }),
+            authoritativeClaim: cloneClaim(this.authoritativeClaim),
+            owner: Object.freeze({ ...this.owner }),
+            capabilities: Object.freeze({ ...this.capabilities }),
+            coordinationScope: this.coordinationScope,
+            targetBindingDigest: this.targetBindingDigest,
+            resource: this.#resourceSelection,
+            assertPageAffinity: (page, observation) => context.assertPageAffinity(page, observation)
+        });
+    }
+    /**
+     * Verify both page object identity and all available stable ownership
+     * evidence.  A context with an exact tab binding requires an explicit
+     * observed stable tab ID and (when bound) the current authoritative claim.
+     */
+    assertPageAffinity(page, observation) {
+        if (page !== this.page) {
+            throw new OperationRuntimeContextError("page_affinity_mismatch", "The supplied page is not the page bound to this operation context.", this.#diagnosticsView);
+        }
+        const observed = validateAffinityObservation(observation);
+        const needsTabEvidence = this.tabId !== undefined;
+        if (needsTabEvidence && (observed.tabId === undefined || observed.tabId !== this.tabId)) {
+            throw new OperationRuntimeContextError("tab_affinity_mismatch", "The supplied tab evidence does not match the operation context.", this.#diagnosticsView);
+        }
+        if (this.authoritativeClaim.status === "available" && !claimMatches(this.authoritativeClaim, observed.authoritativeClaim)) {
+            throw new OperationRuntimeContextError("claim_drift", "The authoritative tab claim no longer matches the operation context.", this.#diagnosticsView);
+        }
+        return Object.freeze({
+            pageMatches: true,
+            tabMatches: !needsTabEvidence || observed.tabId === this.tabId,
+            claimMatches: claimMatches(this.authoritativeClaim, observed.authoritativeClaim),
+            exactTabOwnership: this.#resourceSelection.exactTabOwnership
+        });
+    }
+}
+export function createOperationRuntimeContext(input) {
+    return OperationRuntimeContext.create(input);
+}

package/dist/src/runtime/runtime-session.d.ts

@@ -0,0 +1,95 @@
+import type { BrowserLike, ClipboardLike, PageLike, RuntimeEnv } from "../types.js";
+/** The mutable fields carried between invocations of a legacy RuntimeEnv. */
+export type RuntimeEnvSessionMutableField = "browser" | "page" | "expectedTabId";
+declare const STATIC_ERROR_MESSAGES: Readonly<{
+    readonly invalid_options: "RuntimeEnvSession options are invalid.";
+    readonly invalid_capture: "RuntimeEnvSession capture contains an unsupported value.";
+    readonly capture_closed: "RuntimeEnvSession capture is already closed.";
+    readonly commit_conflict: "RuntimeEnvSession commit conflicts with a newer invocation.";
+    readonly revision_exhausted: "RuntimeEnvSession revision capacity is exhausted.";
+}>;
+export type RuntimeEnvSessionErrorCode = keyof typeof STATIC_ERROR_MESSAGES;
+/**
+ * Errors intentionally have a fixed message.  In particular, no browser,
+ * page, tab id, caller object, or native error is interpolated into a
+ * RuntimeEnvSession diagnostic.
+ */
+export declare class RuntimeEnvSessionError extends Error {
+    readonly code: RuntimeEnvSessionErrorCode;
+    constructor(code: RuntimeEnvSessionErrorCode);
+}
+/** Initial provider/base and mutable snapshot values for a new session. */
+export type RuntimeEnvSessionOptions = Readonly<{
+    agent?: unknown;
+    browser?: BrowserLike;
+    page?: PageLike;
+    clipboard?: ClipboardLike;
+    now?: () => Date;
+    expectedTabId?: string;
+}>;
+export type RuntimeEnvSessionFieldPresence = "set" | "unset";
+export type RuntimeEnvSessionDiagnostics = Readonly<{
+    revision: number;
+    captures: number;
+    openCaptures: number;
+    base: Readonly<{
+        agent: RuntimeEnvSessionFieldPresence;
+        clipboard: RuntimeEnvSessionFieldPresence;
+        now: RuntimeEnvSessionFieldPresence;
+    }>;
+    snapshot: Readonly<{
+        browser: RuntimeEnvSessionFieldPresence;
+        page: RuntimeEnvSessionFieldPresence;
+        expectedTabId: RuntimeEnvSessionFieldPresence;
+    }>;
+}>;
+export type RuntimeEnvSessionCaptureStatus = "open" | "committed" | "abandoned";
+export type RuntimeEnvSessionCaptureDiagnostics = Readonly<{
+    status: RuntimeEnvSessionCaptureStatus;
+    revision: number;
+}>;
+export type RuntimeEnvSessionCommitResult = Readonly<{
+    revision: number;
+    /** Fields the invocation changed relative to its captured snapshot. */
+    changedFields: readonly RuntimeEnvSessionMutableField[];
+    /** Fields that changed the session's durable snapshot in this commit. */
+    appliedFields: readonly RuntimeEnvSessionMutableField[];
+    /** True when a stale capture was accepted by same-value convergence. */
+    converged: boolean;
+}>;
+/**
+ * One invocation's isolated mutable RuntimeEnv and its one-shot lifecycle.
+ * The RuntimeEnv itself is deliberately mutable for legacy command
+ * compatibility.  Its provider/base fields are non-writable; only the
+ * browser/page/tab snapshot fields may be changed before commit.
+ */
+export type RuntimeEnvSessionCapture = Readonly<{
+    env: RuntimeEnv;
+    revision: number;
+    commit: () => RuntimeEnvSessionCommitResult;
+    abandon: () => void;
+    diagnostics: () => RuntimeEnvSessionCaptureDiagnostics;
+}>;
+export type RuntimeEnvSessionRunCallback<T> = (env: RuntimeEnv) => T | PromiseLike<T>;
+/**
+ * Owns the mutable browser/page/tab snapshot used by invocation-scoped
+ * RuntimeEnv captures.  It intentionally performs no browser locking or
+ * command dispatch; this is the synchronous in-process snapshot/CAS boundary
+ * used by `createChatGPT` to isolate concurrent legacy invocations.
+ */
+export declare class RuntimeEnvSession {
+    private readonly base;
+    private state;
+    private captureCount;
+    private openCaptureCount;
+    constructor(options?: RuntimeEnvSessionOptions);
+    /** Current revision; no browser or page value is exposed. */
+    get revision(): number;
+    /** Return frozen, redacted state diagnostics. */
+    diagnostics(): RuntimeEnvSessionDiagnostics;
+    capture(): RuntimeEnvSessionCapture;
+    /** Capture, run one invocation, and publish its snapshot only on success. */
+    run<T>(callback: RuntimeEnvSessionRunCallback<T>): Promise<T>;
+}
+export declare function createRuntimeEnvSession(options?: RuntimeEnvSessionOptions): RuntimeEnvSession;
+export {};