@sovovs/bycli 2.0.0 → 2.1.1

package/dist/src/observation/redaction.js

@@ -10,7 +10,13 @@ const SENSITIVE_HEADER_NAMES = new Set([
     'x-xsrf-token',
 ]);
 const SENSITIVE_FIELD_PATTERN = /(password|passwd|pwd|token|secret|authorization|cookie|set-cookie|api[_-]?key|access[_-]?token|refresh[_-]?token|session[_-]?id|csrf|xsrf)/i;
-const SENSITIVE_URL_PARAMS = /([?&])(token|key|secret|password|auth|access_token|api_key|session_id|csrf|xsrf)=[^&]*/gi;
+const SENSITIVE_URL_PARAMS = /([?&])(token|key|secret|fingerprint|password|auth|access_token|api_key|session_id|csrf|xsrf)=[^&]*/gi;
+function hasFingerprintFieldSegment(name) {
+    return name
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .split(/[-_.\s]+/)
+        .some((segment) => segment.toLowerCase() === 'fingerprint');
+}
 export function redactUrl(url) {
     return url.replace(SENSITIVE_URL_PARAMS, '$1$2=[REDACTED]');
 }
@@ -31,8 +37,8 @@ export function redactText(text, opts = {}) {
     const max = opts.maxStringLength ?? 50_000;
     let out = text
         .replace(/Bearer\s+[A-Za-z0-9\-._~+/]+=*/gi, 'Bearer [REDACTED]')
-        .replace(/(["'])(password|passwd|pwd|token|secret|api_key|apikey|access_token|session_id)\1\s*:\s*(["'])(.*?)\3/gi, '$1$2$1:$3[REDACTED]$3')
-        .replace(/(token|secret|password|api_key|apikey|access_token|session_id)[=:]\s*['"]?[^'"\s,;}&]+['"]?/gi, '$1=[REDACTED]')
+        .replace(/(["'])(password|passwd|pwd|token|secret|fingerprint|api_key|apikey|access_token|session_id)\1\s*:\s*(["'])(.*?)\3/gi, '$1$2$1:$3[REDACTED]$3')
+        .replace(/(token|secret|fingerprint|password|api_key|apikey|access_token|session_id)\s*[=:]\s*['"]?[^'"\s,;}&]+['"]?/gi, '$1=[REDACTED]')
         .replace(/(cookie[=:]\s*)[^\n;]{3,}/gi, '$1[REDACTED]')
         .replace(/eyJ[A-Za-z0-9_-]{10,}\.eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/g, '[REDACTED_JWT]');
     if (out.length > max)
@@ -41,7 +47,7 @@ export function redactText(text, opts = {}) {
 }
 export function redactValue(value, opts = {}, keyHint, depth = 0) {
     const allow = new Set((opts.allowlist ?? []).map((key) => key.toLowerCase()));
-    if (keyHint && SENSITIVE_FIELD_PATTERN.test(keyHint) && !allow.has(keyHint.toLowerCase())) {
+    if (keyHint && (SENSITIVE_FIELD_PATTERN.test(keyHint) || hasFingerprintFieldSegment(keyHint)) && !allow.has(keyHint.toLowerCase())) {
         return DEFAULT_REDACTION;
     }
     if (typeof value === 'string') {

package/dist/src/recorder/highlevel/verify.d.ts

@@ -29,6 +29,8 @@ export interface VerifyInput {
     trace?: 'off' | 'retain-on-failure' | 'always';
     /** N3:显式 adapter 路径 override —— verify 录制器 LLM 生成的临时草稿(不在 clis/),缺省按 name 派生。 */
     adapterPath?: string;
+    /** Optional lowercase SHA-256 expected for the exact adapter bytes the runner will execute. */
+    expectedSourceSha256?: string;
 }
 /** The runner boundary (08). M6 provides the real child-process implementation. */
 export interface RunnerPort {
@@ -42,6 +44,7 @@ export interface RunnerPort {
         trace: string;
         /** N3: explicit adapter path override (recorder draft verify); default = name→clis path. */
         adapterPath?: string;
+        expectedSourceSha256?: string;
     }): Promise<{
         requestId: string;
     }>;

package/dist/src/recorder/highlevel/verify.js

@@ -49,6 +49,9 @@ export async function verifyAdapter(input, sessionHmacKey, runner) {
         }
         adapterPath = abs;
     }
+    if (input.expectedSourceSha256 !== undefined && !/^[0-9a-f]{64}$/.test(input.expectedSourceSha256)) {
+        return { ok: false, errorCode: 'validation_failed', reason: 'expectedSourceSha256 must be 64 lowercase hex characters' };
+    }
     const port = runner ?? defaultRunnerPort();
     const rawSeedArgs = input.executionSeedArgs ?? {};
     const evidenceSeedArgs = deriveEvidenceSeedArgs(rawSeedArgs, sessionHmacKey);
@@ -61,6 +64,7 @@ export async function verifyAdapter(input, sessionHmacKey, runner) {
             fixture: input.fixture ?? 'ignore',
             trace: input.trace ?? 'retain-on-failure',
             adapterPath, // N3: validated draft path override (undefined → name→clis)
+            expectedSourceSha256: input.expectedSourceSha256,
         });
         return { ok: true, requestId };
     }

package/dist/src/recorder/highlevel/verify.test.d.ts

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

package/dist/src/recorder/runner/runner-port.js

@@ -252,6 +252,7 @@ export function createRunnerPort(opts = {}) {
                 requestId,
                 name: input.name,
                 adapterPath: input.adapterPath ?? resolveAdapterPath(input.name),
+                expectedSourceSha256: input.expectedSourceSha256,
                 executionSeedArgs: input.rawSeedArgs, // raw → input.json only
                 fixture: input.fixture,
                 trace: input.trace,

package/dist/src/recorder/runner/verify-runner-main.d.ts

@@ -11,10 +11,11 @@
  * adapters report not-yet (their Page must come from the daemon — M6b). The spawn /
  * input.json security / timeout / byte-cap mechanism lives in `runner-port.ts`.
  *
- * SECURITY (07:123-124): raw executionSeedArgs arrive via input.json (0600) and are used
- * as the adapter's call args; they are never echoed into the emitted result/started events.
+ * SECURITY (07:123-124): raw executionSeedArgs arrive via input.json (0600), then are
+ * defaulted, coerced, and validated before execution. Neither raw nor prepared arguments
+ * are echoed into the emitted result/started events.
  */
-import { type BrowserCliCommand, type CliCommand } from '../../registry.js';
+import { type BrowserCliCommand, type CliCommand, type ConditionalBrowserCliCommand } from '../../registry.js';
 import type { RunnerEvent, RunnerResultEvent } from '@sovovs/bycli-recorder-core';
 /** Parsed input.json (written by RunnerPort; raw seed args are execution-only). */
 export interface RunnerInput {
@@ -22,9 +23,11 @@ export interface RunnerInput {
     name: string;
     /** Resolved adapter module file to import. */
     adapterPath: string;
+    /** Expected hash supplied by the caller; mismatch means the captured module is never loaded. */
+    expectedSourceSha256?: string;
     /** Browser profile contextId for browser adapters (M6b). Omitted → daemon default profile. */
     contextId?: string;
-    /** Raw seed args — used as the adapter call args, never echoed into events. */
+    /** Raw seed args — prepared before resolver/adapter calls and never echoed into events. */
     executionSeedArgs?: Record<string, unknown>;
     fixture?: 'ignore' | 'match' | 'update';
     trace?: 'off' | 'retain-on-failure' | 'always';
@@ -46,13 +49,26 @@ export declare function installRunnerBackstops(maxRuntimeMs: number): void;
  * Load an adapter by importing its module (which registers via `cli()`), then look it up
  * in the registry by name. Mirrors execution.ts's lazy-import pattern (118-135).
  */
-export declare function loadAdapterByName(adapterPath: string, name: string): Promise<CliCommand | undefined>;
+export interface AdapterSourceSnapshot {
+    canonicalUrl: string;
+    source: ArrayBuffer;
+    sourceSha256: string;
+}
+/** Read the main module once. The same exact bytes are hashed and transferred to the ESM loader. */
+export declare function captureAdapterSource(adapterPath: string): AdapterSourceSnapshot;
+/** Import exactly the captured main-module bytes while preserving its canonical URL as import base. */
+export declare function loadAdapterSnapshot(snapshot: AdapterSourceSnapshot, name: string): Promise<CliCommand | undefined>;
+export interface VerifyRunnerDependencies {
+    capture?: (adapterPath: string) => AdapterSourceSnapshot | Promise<AdapterSourceSnapshot>;
+    load?: (snapshot: AdapterSourceSnapshot, name: string) => Promise<CliCommand | undefined>;
+    browserRunner?: BrowserAdapterRunner;
+}
 /**
  * The browser-adapter execution seam (M6b). A browser adapter's `func` needs an IPage; the
  * default implementation connects BACK to the running daemon for one. Injectable so unit
  * tests can exercise executeAdapterForVerify without a real daemon/browser.
  */
-export type BrowserAdapterRunner = (command: BrowserCliCommand, opts: {
+export type BrowserAdapterRunner = (command: BrowserCliCommand | ConditionalBrowserCliCommand, opts: {
     seedArgs: Record<string, unknown>;
     contextId?: string;
     preNavUrl: string | null;
@@ -84,7 +100,7 @@ export declare function executeAdapterForVerify(command: CliCommand | undefined,
  * tests); `load` is injected so unit tests can supply an in-memory command. Never throws —
  * any failure becomes a terminal result so the parent always sees one and only one.
  */
-export declare function runVerifyRunner(input: RunnerInput, emit: (event: RunnerEvent) => void, load?: (adapterPath: string, name: string) => Promise<CliCommand | undefined>, browserRunner?: BrowserAdapterRunner): Promise<void>;
+export declare function runVerifyRunner(input: RunnerInput, emit: (event: RunnerEvent) => void, dependencies?: VerifyRunnerDependencies): Promise<void>;
 /**
  * Entry point for `bycli internal verify-runner --jsonl --request-id … --name … --input …`.
  * Writes JSONL events to the dedicated protocol fd (`--protocol-fd`, set by the parent RunnerPort

package/dist/src/recorder/runner/verify-runner-main.js

@@ -11,13 +11,16 @@
  * adapters report not-yet (their Page must come from the daemon — M6b). The spawn /
  * input.json security / timeout / byte-cap mechanism lives in `runner-port.ts`.
  *
- * SECURITY (07:123-124): raw executionSeedArgs arrive via input.json (0600) and are used
- * as the adapter's call args; they are never echoed into the emitted result/started events.
+ * SECURITY (07:123-124): raw executionSeedArgs arrive via input.json (0600), then are
+ * defaulted, coerced, and validated before execution. Neither raw nor prepared arguments
+ * are echoed into the emitted result/started events.
  */
 import * as fs from 'node:fs';
-import { randomUUID } from 'node:crypto';
+import { createHash, randomUUID } from 'node:crypto';
+import { register } from 'node:module';
 import { pathToFileURL } from 'node:url';
-import { getRegistry } from '../../registry.js';
+import { getRegistry, } from '../../registry.js';
+import { prepareCommandArgsOrThrowArgumentError } from '../../execution.js';
 // ── Lease cleanup on signal / orphan watchdog (Codex #4, #7) ────────────────
 // A browser adapter holds a daemon-side tab lease. If the parent SIGTERMs/cancels this child
 // (timeout/cancel) or this child is orphaned (parent crashed → no SIGTERM, and on win32 the reaper
@@ -76,14 +79,48 @@ function fieldCountOf(rows) {
     }
     return undefined;
 }
-/**
- * Load an adapter by importing its module (which registers via `cli()`), then look it up
- * in the registry by name. Mirrors execution.ts's lazy-import pattern (118-135).
- */
-export async function loadAdapterByName(adapterPath, name) {
-    const url = pathToFileURL(adapterPath).href; // runner-side; a bad path surfaces verbatim
+const SNAPSHOT_LOADER_URL = `data:text/javascript,${encodeURIComponent(`
+  let targetSpecifier = '';
+  let targetUrl = '';
+  let source = new ArrayBuffer(0);
+  export function initialize(data) {
+    targetSpecifier = data.targetSpecifier;
+    targetUrl = data.targetUrl;
+    source = data.source;
+  }
+  export async function resolve(specifier, context, nextResolve) {
+    if (specifier === targetSpecifier) {
+      return { url: targetUrl, shortCircuit: true };
+    }
+    return nextResolve(specifier, context);
+  }
+  export async function load(url, context, nextLoad) {
+    if (url === targetUrl) {
+      return { format: 'module', shortCircuit: true, source: new Uint8Array(source) };
+    }
+    return nextLoad(url, context);
+  }
+`)}`;
+/** Read the main module once. The same exact bytes are hashed and transferred to the ESM loader. */
+export function captureAdapterSource(adapterPath) {
+    const canonicalPath = fs.realpathSync(adapterPath);
+    const bytes = fs.readFileSync(canonicalPath);
+    const source = Uint8Array.from(bytes).buffer;
+    return {
+        canonicalUrl: pathToFileURL(canonicalPath).href,
+        source,
+        sourceSha256: createHash('sha256').update(new Uint8Array(source)).digest('hex'),
+    };
+}
+/** Import exactly the captured main-module bytes while preserving its canonical URL as import base. */
+export async function loadAdapterSnapshot(snapshot, name) {
     try {
-        await import(url);
+        const targetSpecifier = `bycli-verify-snapshot:${randomUUID()}`;
+        register(SNAPSHOT_LOADER_URL, import.meta.url, {
+            data: { targetSpecifier, targetUrl: snapshot.canonicalUrl, source: snapshot.source },
+            transferList: [snapshot.source],
+        });
+        await import(targetSpecifier);
     }
     catch (e) {
         // The adapter module's top-level code threw during evaluation (a SyntaxError, or a deliberate
@@ -131,9 +168,24 @@ export async function executeAdapterForVerify(command, opts) {
         return { ok: false, data: { stage: 'load', trace }, error: { code: 'runner_protocol_error', message: `adapter "${opts.name}" has no func` } };
     }
     try {
+        const preparedArgs = prepareCommandArgsOrThrowArgumentError(command, opts.seedArgs);
         let rows;
         if (command.browser === false) {
-            rows = await command.func(opts.seedArgs, false);
+            rows = await command.func(preparedArgs, false);
+        }
+        else if (command.browser === 'conditional') {
+            const browserRequired = Boolean(command.requiresBrowser(preparedArgs));
+            if (!browserRequired) {
+                rows = await command.func(null, preparedArgs, false);
+            }
+            else {
+                const runner = opts.browserRunner ?? defaultBrowserAdapterRunner;
+                rows = await runner(command, {
+                    seedArgs: preparedArgs,
+                    contextId: opts.contextId,
+                    preNavUrl: typeof command.navigateBefore === 'string' ? command.navigateBefore : null,
+                });
+            }
         }
         else {
             // M6b: browser adapter connects back to the daemon for a Page. navigateBefore is a
@@ -141,7 +193,7 @@ export async function executeAdapterForVerify(command, opts) {
             // `true`/`undefined` mean "adapter handles its own navigation".
             const runner = opts.browserRunner ?? defaultBrowserAdapterRunner;
             rows = await runner(command, {
-                seedArgs: opts.seedArgs,
+                seedArgs: preparedArgs,
                 contextId: opts.contextId,
                 preNavUrl: typeof command.navigateBefore === 'string' ? command.navigateBefore : null,
             });
@@ -172,29 +224,50 @@ export async function executeAdapterForVerify(command, opts) {
  * tests); `load` is injected so unit tests can supply an in-memory command. Never throws —
  * any failure becomes a terminal result so the parent always sees one and only one.
  */
-export async function runVerifyRunner(input, emit, load = loadAdapterByName, browserRunner) {
+export async function runVerifyRunner(input, emit, dependencies = {}) {
     emit({ type: 'started', requestId: input.requestId, pid: process.pid, stage: 'load' });
+    let sourceSha256;
     try {
-        const command = await load(input.adapterPath, input.name);
+        const capture = dependencies.capture ?? captureAdapterSource;
+        const load = dependencies.load ?? loadAdapterSnapshot;
+        const snapshot = await capture(input.adapterPath);
+        sourceSha256 = snapshot.sourceSha256;
+        if (input.expectedSourceSha256 !== undefined && input.expectedSourceSha256 !== sourceSha256) {
+            emit({
+                type: 'result', requestId: input.requestId, ok: false,
+                data: { stage: 'load', sourceSha256 },
+                error: { code: 'source_hash_mismatch', message: 'adapter source hash does not match expected source' },
+            });
+            return;
+        }
+        const command = await load(snapshot, input.name);
         const r = await executeAdapterForVerify(command, {
             name: input.name,
             fixture: input.fixture,
             trace: input.trace,
             seedArgs: input.executionSeedArgs ?? {},
             contextId: input.contextId,
-            browserRunner,
+            browserRunner: dependencies.browserRunner,
+        });
+        emit({
+            type: 'result', requestId: input.requestId, ok: r.ok,
+            data: { ...r.data, sourceSha256 },
+            error: r.ok ? null : r.error,
         });
-        emit({ type: 'result', requestId: input.requestId, ok: r.ok, data: r.data, error: r.ok ? null : r.error });
     }
     catch (e) {
-        // Load failure → single terminal result. An adapter-evaluation error (tagged by loadAdapterByName)
+        // Load failure → single terminal result. An adapter-evaluation error (tagged by loadAdapterSnapshot)
         // is adapter-controlled and may echo adapter-file contents, so its message is redacted; a
         // runner-side failure (bad path / resolve) is runner-generated and surfaces verbatim (Codex M7c).
         const adapterEval = e?.adapterEvaluation === true;
         const message = adapterEval ? REDACTED_ADAPTER_LOAD_MESSAGE : (e instanceof Error ? e.message : String(e));
         emit({
             type: 'result', requestId: input.requestId, ok: false,
-            data: { stage: 'load', trace: { policy: input.trace ?? 'retain-on-failure', retained: false, path: null } },
+            data: {
+                stage: 'load',
+                ...(sourceSha256 === undefined ? {} : { sourceSha256 }),
+                trace: { policy: input.trace ?? 'retain-on-failure', retained: false, path: null },
+            },
             error: { code: 'adapter_runtime_error', message, hint: 'adapter failed to load' },
         });
     }

package/dist/src/registry-api.d.ts

@@ -7,7 +7,7 @@
  * plugins are dynamically imported during discoverPlugins().
  */
 export { cli, Strategy, getRegistry, fullName, registerCommand } from './registry.js';
-export type { CliCommand, Arg, CliOptions, CommandArgs, SiteSessionMode } from './registry.js';
+export type { CliCommand, Arg, CliOptions, CommandArgs, SiteSessionMode, BrowserDeclaration, BrowserRequirementResolver, ConditionalBrowserCommandFunc, NormalizedBrowserRequirement, } from './registry.js';
 export type { IPage } from './types.js';
 export { onStartup, onBeforeExecute, onAfterExecute } from './hooks.js';
 export type { HookFn, HookContext, HookName } from './hooks.js';

package/dist/src/registry-api.types.test.d.ts

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

package/dist/src/registry-transaction.d.ts

@@ -0,0 +1,42 @@
+import type { CliCommand } from './registry.js';
+interface RegistrySlot {
+    present: boolean;
+    value: CliCommand | undefined;
+}
+export interface RegistryTransactionWrite {
+    key: string;
+    before: RegistrySlot;
+    after: RegistrySlot;
+    group: number;
+    beforeRevision: number;
+    afterRevision: number;
+}
+export interface RegistryTransaction {
+    readonly writes: RegistryTransactionWrite[];
+    readonly id: number;
+    active: boolean;
+    currentGroup: number | undefined;
+    finalized: boolean;
+    readonly finalizedGroups: Set<number>;
+}
+export declare function createRegistryTransaction(): RegistryTransaction;
+export declare function closeRegistryTransaction(transaction: RegistryTransaction): void;
+export declare function runRegistryTransaction<T>(transaction: RegistryTransaction, operation: () => Promise<T>): Promise<T>;
+export declare function withRegistryMutationGroup<T>(operation: () => T): T;
+export declare function recordRegistryMutation(key: string, before: RegistrySlot, after: RegistrySlot): void;
+/**
+ * Keys with revision ownership, including absent-key tombstones.
+ *
+ * Tombstones intentionally remain until a later mutation or rollback supersedes
+ * them. Pruning an absent revision while an overlapping transaction may still
+ * reference it would allow an older rollback to resurrect the key.
+ */
+export declare function registryMutationKeys(): string[];
+export declare function pruneRegistryMutationKey(key: string, registry: ReadonlyMap<string, CliCommand>): void;
+export declare function finalizeRegistryTransaction(transaction: RegistryTransaction, registry: ReadonlyMap<string, CliCommand>, groups?: ReadonlySet<number>): void;
+export declare function capturedRegistryValue(transaction: RegistryTransaction, key: string): RegistrySlot;
+export declare function capturedRegistryValues(transaction: RegistryTransaction): Map<string, CliCommand>;
+export declare function transactionGroupsForKey(transaction: RegistryTransaction, key: string): Set<number>;
+export declare function rollbackRegistryTransaction(transaction: RegistryTransaction, registry: Map<string, CliCommand>, groups?: ReadonlySet<number>): void;
+export declare function resetRegistryTransactionStateForTests(): void;
+export {};

package/dist/src/registry-transaction.js

@@ -0,0 +1,194 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+const TRANSACTION_STATE_KEY = Symbol.for('@sovovs/bycli/registry-transaction-state');
+const globalState = globalThis;
+const state = globalState[TRANSACTION_STATE_KEY] ??= {
+    storage: new AsyncLocalStorage(),
+    transactionCounter: 0,
+    groupCounter: 0,
+    revisionCounter: 0,
+    revisions: new Map(),
+    transactions: new Map(),
+    owners: new Map(),
+};
+state.transactions ??= new Map();
+state.owners ??= new Map();
+export function createRegistryTransaction() {
+    const transaction = {
+        writes: [],
+        id: ++state.transactionCounter,
+        active: false,
+        currentGroup: undefined,
+        finalized: false,
+        finalizedGroups: new Set(),
+    };
+    state.transactions.set(transaction.id, transaction);
+    return transaction;
+}
+export function closeRegistryTransaction(transaction) {
+    transaction.active = false;
+    transaction.currentGroup = undefined;
+}
+export async function runRegistryTransaction(transaction, operation) {
+    if (transaction.finalized) {
+        throw new Error('Adapter registration transaction is finalized');
+    }
+    transaction.active = true;
+    return state.storage.run(transaction, async () => {
+        try {
+            return await operation();
+        }
+        finally {
+            closeRegistryTransaction(transaction);
+        }
+    });
+}
+export function withRegistryMutationGroup(operation) {
+    const transaction = state.storage.getStore();
+    if (!transaction)
+        return operation();
+    if (!transaction.active) {
+        throw new Error('Adapter registration transaction is closed; delayed registration is not allowed');
+    }
+    const previousGroup = transaction.currentGroup;
+    transaction.currentGroup = ++state.groupCounter;
+    try {
+        return operation();
+    }
+    finally {
+        transaction.currentGroup = previousGroup;
+    }
+}
+export function recordRegistryMutation(key, before, after) {
+    const transaction = state.storage.getStore();
+    if (transaction && !transaction.active) {
+        throw new Error('Adapter registration transaction is closed; delayed registration is not allowed');
+    }
+    if (transaction?.finalized) {
+        throw new Error('Adapter registration transaction is finalized');
+    }
+    const beforeRevision = state.revisions.get(key) ?? 0;
+    const afterRevision = ++state.revisionCounter;
+    state.revisions.set(key, afterRevision);
+    if (!transaction)
+        return;
+    const group = transaction.currentGroup ?? ++state.groupCounter;
+    transaction.writes.push({
+        key,
+        before,
+        after,
+        group,
+        beforeRevision,
+        afterRevision,
+    });
+    const owners = state.owners.get(key) ?? new Set();
+    owners.add(transaction.id);
+    state.owners.set(key, owners);
+}
+/**
+ * Keys with revision ownership, including absent-key tombstones.
+ *
+ * Tombstones intentionally remain until a later mutation or rollback supersedes
+ * them. Pruning an absent revision while an overlapping transaction may still
+ * reference it would allow an older rollback to resurrect the key.
+ */
+export function registryMutationKeys() {
+    return [...state.revisions.keys()];
+}
+export function pruneRegistryMutationKey(key, registry) {
+    if (registry.has(key))
+        return;
+    if ((state.owners.get(key)?.size ?? 0) > 0)
+        return;
+    state.revisions.delete(key);
+}
+export function finalizeRegistryTransaction(transaction, registry, groups) {
+    if (transaction.active) {
+        throw new Error('Cannot finalize an active adapter registration transaction');
+    }
+    const selectedGroups = groups ?? new Set(transaction.writes.map(write => write.group));
+    const newGroups = new Set([...selectedGroups].filter(group => !transaction.finalizedGroups.has(group)));
+    const affectedKeys = new Set(transaction.writes
+        .filter(write => newGroups.has(write.group))
+        .map(write => write.key));
+    for (const group of newGroups)
+        transaction.finalizedGroups.add(group);
+    for (const key of affectedKeys) {
+        const stillOwned = transaction.writes.some(write => write.key === key && !transaction.finalizedGroups.has(write.group));
+        if (!stillOwned) {
+            const owners = state.owners.get(key);
+            owners?.delete(transaction.id);
+            if (owners?.size === 0)
+                state.owners.delete(key);
+        }
+        pruneRegistryMutationKey(key, registry);
+    }
+    const hasUnfinalizedWrites = transaction.writes.some(write => !transaction.finalizedGroups.has(write.group));
+    if (!hasUnfinalizedWrites) {
+        transaction.finalized = true;
+        state.transactions.delete(transaction.id);
+    }
+}
+export function capturedRegistryValue(transaction, key) {
+    for (let index = transaction.writes.length - 1; index >= 0; index -= 1) {
+        const write = transaction.writes[index];
+        if (write.key === key)
+            return write.after;
+    }
+    return { present: false, value: undefined };
+}
+export function capturedRegistryValues(transaction) {
+    const keys = new Set(transaction.writes.map(write => write.key));
+    const values = new Map();
+    for (const key of keys) {
+        const captured = capturedRegistryValue(transaction, key);
+        if (captured.present && captured.value)
+            values.set(key, captured.value);
+    }
+    return values;
+}
+export function transactionGroupsForKey(transaction, key) {
+    return new Set(transaction.writes.filter(write => write.key === key).map(write => write.group));
+}
+export function rollbackRegistryTransaction(transaction, registry, groups) {
+    const groupIds = [...new Set(transaction.writes.map(write => write.group))]
+        .filter(group => !transaction.finalizedGroups.has(group) && (!groups || groups.has(group)))
+        .sort((a, b) => b - a);
+    for (const group of groupIds) {
+        const writesByKey = new Map();
+        for (const write of transaction.writes) {
+            if (write.group !== group)
+                continue;
+            const writes = writesByKey.get(write.key) ?? [];
+            writes.push(write);
+            writesByKey.set(write.key, writes);
+        }
+        for (const writes of writesByKey.values()) {
+            const finalWrite = writes.at(-1);
+            if ((state.revisions.get(finalWrite.key) ?? 0) !== finalWrite.afterRevision)
+                continue;
+            for (let index = writes.length - 1; index >= 0; index -= 1) {
+                const write = writes[index];
+                if (write.before.present)
+                    Map.prototype.set.call(registry, write.key, write.before.value);
+                else
+                    Map.prototype.delete.call(registry, write.key);
+                if (write.beforeRevision === 0)
+                    state.revisions.delete(write.key);
+                else
+                    state.revisions.set(write.key, write.beforeRevision);
+            }
+        }
+    }
+    finalizeRegistryTransaction(transaction, registry, new Set(groupIds));
+}
+export function resetRegistryTransactionStateForTests() {
+    for (const transaction of state.transactions.values()) {
+        closeRegistryTransaction(transaction);
+        transaction.finalized = true;
+        for (const write of transaction.writes)
+            transaction.finalizedGroups.add(write.group);
+    }
+    state.transactions.clear();
+    state.owners.clear();
+    state.revisions.clear();
+}

package/dist/src/registry-transaction.test.d.ts

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