oh-my-knowledge 0.48.0 → 0.49.0

package/dist/shared/evaluation-job.js

@@ -0,0 +1,217 @@
+import { isRfc3339Timestamp } from './timestamp.js';
+function isRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function isOptionalString(value) {
+    return value === undefined || typeof value === 'string';
+}
+function isOptionalBoolean(value) {
+    return value === undefined || typeof value === 'boolean';
+}
+function isOptionalPositiveInteger(value) {
+    return value === undefined || (Number.isSafeInteger(value) && value > 0);
+}
+function isOptionalTimestamp(value) {
+    return value === undefined || isRfc3339Timestamp(value);
+}
+function isOptionalBudget(value) {
+    if (value === undefined)
+        return true;
+    if (!isRecord(value))
+        return false;
+    return [
+        value.totalUSD,
+        value.perSampleUSD,
+        value.perSampleMs,
+    ].every((metric) => metric === undefined
+        || (typeof metric === 'number'
+            && Number.isFinite(metric)
+            && metric >= 0
+            && metric <= Number.MAX_SAFE_INTEGER));
+}
+function isArtifact(value) {
+    if (!isRecord(value))
+        return false;
+    return typeof value.name === 'string'
+        && value.name.length > 0
+        && (value.kind === 'baseline'
+            || value.kind === 'skill'
+            || value.kind === 'prompt'
+            || value.kind === 'agent'
+            || value.kind === 'workflow')
+        && (value.source === 'baseline'
+            || value.source === 'variant-name'
+            || value.source === 'file-path'
+            || value.source === 'git'
+            || value.source === 'inline'
+            || value.source === 'custom')
+        && (value.content === null || typeof value.content === 'string')
+        && [
+            value.contentHash,
+            value.locator,
+            value.ref,
+            value.resolvedCommit,
+            value.cwd,
+            value.skillRoot,
+            value.execRoot,
+        ].every(isOptionalString)
+        && (value.experimentRole === undefined
+            || value.experimentRole === 'control'
+            || value.experimentRole === 'treatment')
+        && (value.allowedSkills === undefined
+            || (Array.isArray(value.allowedSkills)
+                && value.allowedSkills.every((skill) => typeof skill === 'string' && skill.length > 0)
+                && new Set(value.allowedSkills).size === value.allowedSkills.length))
+        && (value.metadata === undefined || isRecord(value.metadata));
+}
+export function isSafeEvaluationJobId(value) {
+    return typeof value === 'string'
+        && /^[A-Za-z0-9][A-Za-z0-9._-]{0,255}$/.test(value);
+}
+export function isValidEvaluationRequest(value) {
+    if (!isRecord(value))
+        return false;
+    return typeof value.samplesPath === 'string'
+        && typeof value.skillDir === 'string'
+        && Array.isArray(value.artifacts)
+        && value.artifacts.every(isArtifact)
+        && new Set(value.artifacts.map((artifact) => artifact.name)).size === value.artifacts.length
+        && typeof value.model === 'string'
+        && value.model.trim().length > 0
+        && typeof value.executor === 'string'
+        && value.executor.trim().length > 0
+        && typeof value.noJudge === 'boolean'
+        && Number.isSafeInteger(value.concurrency)
+        && value.concurrency > 0
+        && typeof value.noCache === 'boolean'
+        && typeof value.dryRun === 'boolean'
+        && Array.isArray(value.judgeModels)
+        && value.judgeModels.length > 0
+        && value.judgeModels.every((judge) => isRecord(judge)
+            && typeof judge.executor === 'string'
+            && judge.executor.trim().length > 0
+            && typeof judge.model === 'string'
+            && judge.model.trim().length > 0)
+        && isOptionalString(value.project)
+        && isOptionalString(value.owner)
+        && (value.tags === undefined
+            || (Array.isArray(value.tags)
+                && value.tags.every((tag) => typeof tag === 'string')))
+        && isOptionalPositiveInteger(value.timeoutMs)
+        && isOptionalPositiveInteger(value.repeat)
+        && (value.holdoutRatio === undefined
+            || (typeof value.holdoutRatio === 'number'
+                && Number.isFinite(value.holdoutRatio)
+                && value.holdoutRatio > 0
+                && value.holdoutRatio < 1))
+        && isOptionalBoolean(value.batch)
+        && isOptionalPositiveInteger(value.judgeRepeat)
+        && isOptionalBoolean(value.bootstrap)
+        && isOptionalPositiveInteger(value.bootstrapSamples)
+        && isOptionalBoolean(value.lengthDebias)
+        && isOptionalBudget(value.budget)
+        && isOptionalBoolean(value.strictBaseline)
+        && (value.retry === undefined
+            || (Number.isSafeInteger(value.retry) && value.retry >= 0))
+        && isOptionalBoolean(value.noDiagnostic)
+        && (value.effort === undefined
+            || value.effort === 'low'
+            || value.effort === 'medium'
+            || value.effort === 'high'
+            || value.effort === 'xhigh'
+            || value.effort === 'max');
+}
+export function isValidEvaluationRun(value, expectedRunId) {
+    if (!isRecord(value)
+        || typeof value.runId !== 'string'
+        || value.runId.length === 0
+        || (expectedRunId !== undefined && value.runId !== expectedRunId)
+        || !isRfc3339Timestamp(value.startedAt)
+        || !isOptionalTimestamp(value.finishedAt)
+        || (value.status !== 'running'
+            && value.status !== 'succeeded'
+            && value.status !== 'failed'
+            && value.status !== 'cancelled'))
+        return false;
+    if (value.status === 'running')
+        return value.finishedAt === undefined;
+    return value.finishedAt !== undefined
+        && Date.parse(value.finishedAt) >= Date.parse(value.startedAt);
+}
+function jobStateIsConsistent(job) {
+    if (job.status === 'queued') {
+        return job.startedAt === undefined
+            && job.finishedAt === undefined
+            && job.runId === undefined
+            && job.resultReportId === undefined
+            && job.error === undefined
+            && job.errorCategory === undefined;
+    }
+    if (job.status === 'running') {
+        return job.startedAt !== undefined
+            && job.finishedAt === undefined
+            && typeof job.runId === 'string'
+            && job.runId.length > 0
+            && job.resultReportId === undefined
+            && job.error === undefined
+            && job.errorCategory === undefined;
+    }
+    if (job.status === 'succeeded') {
+        return job.startedAt !== undefined
+            && job.finishedAt !== undefined
+            && typeof job.runId === 'string'
+            && job.runId.length > 0
+            && typeof job.resultReportId === 'string'
+            && job.resultReportId.length > 0
+            && job.error === undefined
+            && job.errorCategory === undefined;
+    }
+    if (job.status === 'failed') {
+        return job.finishedAt !== undefined
+            && typeof job.error === 'string'
+            && job.error.length > 0
+            && job.errorCategory !== undefined
+            && job.resultReportId === undefined;
+    }
+    return job.finishedAt !== undefined && job.resultReportId === undefined;
+}
+export function isValidEvaluationJob(value, expectedJobId) {
+    if (!isRecord(value)
+        || !isSafeEvaluationJobId(value.jobId)
+        || (expectedJobId !== undefined && value.jobId !== expectedJobId)
+        || (value.status !== 'queued'
+            && value.status !== 'running'
+            && value.status !== 'succeeded'
+            && value.status !== 'failed'
+            && value.status !== 'cancelled')
+        || !isRfc3339Timestamp(value.createdAt)
+        || !isValidEvaluationRequest(value.request)
+        || !isOptionalTimestamp(value.updatedAt)
+        || !isOptionalTimestamp(value.startedAt)
+        || !isOptionalTimestamp(value.finishedAt)
+        || !isOptionalString(value.runId)
+        || !isOptionalString(value.resultReportId)
+        || !isOptionalString(value.error)
+        || (value.errorCategory !== undefined
+            && value.errorCategory !== 'user'
+            && value.errorCategory !== 'executor'
+            && value.errorCategory !== 'judge'
+            && value.errorCategory !== 'system'))
+        return false;
+    const createdAtMs = Date.parse(value.createdAt);
+    const startedAtMs = value.startedAt === undefined ? undefined : Date.parse(value.startedAt);
+    const finishedAtMs = value.finishedAt === undefined ? undefined : Date.parse(value.finishedAt);
+    const updatedAtMs = value.updatedAt === undefined ? undefined : Date.parse(value.updatedAt);
+    if ((startedAtMs !== undefined && startedAtMs < createdAtMs)
+        || (finishedAtMs !== undefined && finishedAtMs < createdAtMs)
+        || (startedAtMs !== undefined
+            && finishedAtMs !== undefined
+            && finishedAtMs < startedAtMs)
+        || (updatedAtMs !== undefined
+            && updatedAtMs < Math.max(createdAtMs, startedAtMs ?? createdAtMs, finishedAtMs ?? createdAtMs)))
+        return false;
+    return jobStateIsConsistent(value);
+}
+export function evaluationRequestsEqual(left, right) {
+    return JSON.stringify(left) === JSON.stringify(right);
+}

package/dist/shared/executor-result.d.ts

@@ -0,0 +1,17 @@
+import type { ExecResult, ToolCallInfo, TurnInfo } from '../types/index.js';
+/**
+ * Validate the source-neutral executor result contract at process/cache
+ * boundaries. Provider payloads and custom executors are untrusted input; a
+ * malformed metric must fail the sample instead of entering a report.
+ */
+export declare function executorResultValidationError(value: unknown): string | undefined;
+export declare function parseExecResult(value: unknown): ExecResult | null;
+/**
+ * Canonicalize every execution trace after structural validation. This keeps
+ * programmatic/custom executors and restored caches in the same comparison
+ * namespace as built-in provider adapters.
+ */
+export declare function normalizeExecResultToolIdentities(result: ExecResult): ExecResult;
+export declare function isValidTurnInfo(value: unknown): value is TurnInfo;
+export declare function isValidToolCallInfo(value: unknown): value is ToolCallInfo;
+export declare function isValidMockStats(value: unknown): boolean;

package/dist/shared/executor-result.js

@@ -0,0 +1,221 @@
+import { checkedSumTokenCounts, optionalTokenCount } from './token-usage.js';
+import { normalizeRfc3339Timestamp } from './timestamp.js';
+import { normalizeToolIdentity } from './tool-identity.js';
+import { isTraceSourceKind } from './trace-source-kind.js';
+import { isJsonValue } from './json-value.js';
+const TOOL_STATUSES = new Set(['success', 'failure', 'cancelled', 'unknown']);
+const TOOL_STATUS_SOURCES = new Set(['runtime', 'tool-output', 'inferred', 'unknown']);
+const TRACE_ROLES = new Set(['standalone', 'main', 'subagent']);
+const TURN_ROLES = new Set(['user', 'assistant', 'tool']);
+/**
+ * Validate the source-neutral executor result contract at process/cache
+ * boundaries. Provider payloads and custom executors are untrusted input; a
+ * malformed metric must fail the sample instead of entering a report.
+ */
+export function executorResultValidationError(value) {
+    if (!isRecord(value))
+        return 'executor result must be an object';
+    if (typeof value.ok !== 'boolean')
+        return '"ok" must be boolean';
+    if (value.output !== null && typeof value.output !== 'string') {
+        return '"output" must be string or null';
+    }
+    if (value.ok && (typeof value.output !== 'string' || value.output.trim() === '')) {
+        return 'successful executor result must contain model output';
+    }
+    for (const field of ['durationMs', 'durationApiMs']) {
+        if (!isNonNegativeSafeMetric(value[field])) {
+            return `"${field}" must be a non-negative safe number`;
+        }
+    }
+    for (const field of [
+        'inputTokens',
+        'outputTokens',
+        'cacheReadTokens',
+        'cacheCreationTokens',
+        'numTurns',
+    ]) {
+        if (optionalTokenCount(value[field]) === undefined) {
+            return `"${field}" must be a non-negative safe integer`;
+        }
+    }
+    if (checkedSumTokenCounts(value.inputTokens, value.outputTokens, value.cacheReadTokens, value.cacheCreationTokens) === undefined) {
+        return 'token usage aggregate exceeds safe integer';
+    }
+    if (!isNonNegativeSafeMetric(value.costUSD)) {
+        return '"costUSD" must be a non-negative safe number';
+    }
+    if (typeof value.stopReason !== 'string')
+        return '"stopReason" must be string';
+    if (!isOptionalBoolean(value.costReportedByExecutor)) {
+        return '"costReportedByExecutor" must be boolean when present';
+    }
+    if (!isOptionalBoolean(value.tokenUsageReportedByExecutor)) {
+        return '"tokenUsageReportedByExecutor" must be boolean when present';
+    }
+    if (!isOptionalBoolean(value.cached))
+        return '"cached" must be boolean when present';
+    if (!isOptionalString(value.error))
+        return '"error" must be string when present';
+    if (!isOptionalCount(value.fullNumTurns)) {
+        return '"fullNumTurns" must be a non-negative safe integer when present';
+    }
+    if (!isOptionalCount(value.numSubAgents)) {
+        return '"numSubAgents" must be a non-negative safe integer when present';
+    }
+    if (value.attemptCount !== undefined
+        && (typeof value.attemptCount !== 'number'
+            || !Number.isSafeInteger(value.attemptCount)
+            || value.attemptCount < 1)) {
+        return '"attemptCount" must be a positive safe integer when present';
+    }
+    if (value.turns !== undefined) {
+        if (!Array.isArray(value.turns) || !value.turns.every(isValidTurnInfo)) {
+            return '"turns" contains an invalid trace entry';
+        }
+    }
+    if (value.toolCalls !== undefined) {
+        if (!Array.isArray(value.toolCalls) || !value.toolCalls.every(isValidToolCallInfo)) {
+            return '"toolCalls" contains an invalid trace entry';
+        }
+    }
+    if (value.mockStats !== undefined && !isValidMockStats(value.mockStats)) {
+        return '"mockStats" contains invalid counters';
+    }
+    return undefined;
+}
+export function parseExecResult(value) {
+    return executorResultValidationError(value)
+        ? null
+        : normalizeExecResultToolIdentities(value);
+}
+/**
+ * Canonicalize every execution trace after structural validation. This keeps
+ * programmatic/custom executors and restored caches in the same comparison
+ * namespace as built-in provider adapters.
+ */
+export function normalizeExecResultToolIdentities(result) {
+    const normalizeCall = (call) => {
+        const sourceName = call.sourceTool ?? call.tool;
+        const isMcpIdentity = sourceName.startsWith('mcp__')
+            || sourceName === 'mcp_tool_call'
+            || call.toolNamespace?.startsWith('mcp__');
+        const identity = normalizeToolIdentity({
+            sourceName,
+            namespace: call.toolNamespace,
+            provider: call.toolProvider,
+            authoritativeName: isMcpIdentity && call.tool !== sourceName
+                ? call.tool
+                : undefined,
+        });
+        const normalizedCall = {
+            ...call,
+            tool: identity.name,
+        };
+        if (identity.sourceName)
+            normalizedCall.sourceTool = identity.sourceName;
+        else
+            delete normalizedCall.sourceTool;
+        if (identity.namespace)
+            normalizedCall.toolNamespace = identity.namespace;
+        else
+            delete normalizedCall.toolNamespace;
+        if (identity.provider)
+            normalizedCall.toolProvider = identity.provider;
+        else
+            delete normalizedCall.toolProvider;
+        return normalizedCall;
+    };
+    return {
+        ...result,
+        ...(result.toolCalls && {
+            toolCalls: result.toolCalls.map(normalizeCall),
+        }),
+        ...(result.turns && {
+            turns: result.turns.map((turn) => ({
+                ...turn,
+                ...(turn.toolCalls && {
+                    toolCalls: turn.toolCalls.map(normalizeCall),
+                }),
+            })),
+        }),
+    };
+}
+export function isValidTurnInfo(value) {
+    return isRecord(value)
+        && typeof value.role === 'string'
+        && TURN_ROLES.has(value.role)
+        && typeof value.content === 'string'
+        && (value.toolCalls === undefined
+            || (Array.isArray(value.toolCalls) && value.toolCalls.every(isValidToolCallInfo)))
+        && (value.durationMs === undefined
+            || isNonNegativeSafeMetric(value.durationMs));
+}
+export function isValidToolCallInfo(value) {
+    if (!isRecord(value)
+        || typeof value.tool !== 'string'
+        || value.tool.trim() === ''
+        || !isJsonValue(value.input)
+        || !isJsonValue(value.output)
+        || typeof value.success !== 'boolean'
+        || !isOptionalCount(value.messageIndex))
+        return false;
+    if (value.status !== undefined
+        && (typeof value.status !== 'string'
+            || !TOOL_STATUSES.has(value.status)
+            || value.success !== (value.status === 'success')))
+        return false;
+    if (value.statusSource !== undefined
+        && (typeof value.statusSource !== 'string'
+            || !TOOL_STATUS_SOURCES.has(value.statusSource)))
+        return false;
+    if (value.sourceKind !== undefined
+        && !isTraceSourceKind(value.sourceKind))
+        return false;
+    if (value.traceRole !== undefined
+        && (typeof value.traceRole !== 'string'
+            || !TRACE_ROLES.has(value.traceRole)))
+        return false;
+    if (value.timestamp !== undefined
+        && normalizeRfc3339Timestamp(value.timestamp) === undefined)
+        return false;
+    return [
+        value.sourceTool,
+        value.toolNamespace,
+        value.toolProvider,
+        value.messageUuid,
+        value.callInstanceId,
+        value.toolUseId,
+        value.sourceTrace,
+        value.traceLabel,
+    ].every(isOptionalString);
+}
+export function isValidMockStats(value) {
+    if (!isRecord(value)
+        || optionalTokenCount(value.hits) === undefined
+        || optionalTokenCount(value.misses) === undefined
+        || !isRecord(value.perMock))
+        return false;
+    const perMock = Object.values(value.perMock);
+    if (perMock.some((count) => optionalTokenCount(count) === undefined))
+        return false;
+    return checkedSumTokenCounts(...perMock) === value.hits;
+}
+function isNonNegativeSafeMetric(value) {
+    return typeof value === 'number'
+        && Number.isFinite(value)
+        && value >= 0
+        && value <= Number.MAX_SAFE_INTEGER;
+}
+function isOptionalCount(value) {
+    return value === undefined || optionalTokenCount(value) !== undefined;
+}
+function isOptionalString(value) {
+    return value === undefined || typeof value === 'string';
+}
+function isOptionalBoolean(value) {
+    return value === undefined || typeof value === 'boolean';
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}

package/dist/shared/file-lock.d.ts

@@ -0,0 +1,12 @@
+export interface FileLockOptions {
+    timeoutMs?: number;
+    staleMs?: number;
+    retryMs?: number;
+    label?: string;
+}
+/**
+ * Serialize a short synchronous read-modify-write transaction across
+ * processes. The owner token prevents an old holder from deleting a lock that
+ * was recovered and reacquired by another process.
+ */
+export declare function withFileLock<T>(lockPath: string, operation: () => T, options?: FileLockOptions): T;

package/dist/shared/file-lock.js

@@ -0,0 +1,129 @@
+import { randomUUID } from 'node:crypto';
+import { closeSync, mkdirSync, openSync, readFileSync, statSync, unlinkSync, writeFileSync, } from 'node:fs';
+import { hostname } from 'node:os';
+import { dirname } from 'node:path';
+const LOCK_SLEEP = new Int32Array(new SharedArrayBuffer(4));
+/**
+ * Serialize a short synchronous read-modify-write transaction across
+ * processes. The owner token prevents an old holder from deleting a lock that
+ * was recovered and reacquired by another process.
+ */
+export function withFileLock(lockPath, operation, options = {}) {
+    const timeoutMs = options.timeoutMs ?? 5_000;
+    const staleMs = options.staleMs ?? 30_000;
+    const retryMs = options.retryMs ?? 10;
+    const label = options.label ?? lockPath;
+    const owner = {
+        owner: randomUUID(),
+        pid: process.pid,
+        hostname: hostname(),
+        acquiredAt: new Date().toISOString(),
+    };
+    mkdirSync(dirname(lockPath), { recursive: true });
+    const deadline = Date.now() + timeoutMs;
+    let descriptor;
+    while (descriptor === undefined) {
+        try {
+            descriptor = openSync(lockPath, 'wx');
+            writeFileSync(descriptor, JSON.stringify(owner));
+        }
+        catch (error) {
+            if (descriptor !== undefined) {
+                closeSync(descriptor);
+                descriptor = undefined;
+                try {
+                    unlinkSync(lockPath);
+                }
+                catch (unlinkError) {
+                    if (unlinkError.code !== 'ENOENT') {
+                        throw unlinkError;
+                    }
+                }
+            }
+            const code = error.code;
+            if (code !== 'EEXIST')
+                throw error;
+            if (isRecoverableStaleLock(lockPath, staleMs)) {
+                try {
+                    unlinkSync(lockPath);
+                }
+                catch (unlinkError) {
+                    if (unlinkError.code !== 'ENOENT') {
+                        throw unlinkError;
+                    }
+                }
+                continue;
+            }
+            if (Date.now() >= deadline) {
+                throw new Error(`timed out waiting for file lock: ${label}`);
+            }
+            Atomics.wait(LOCK_SLEEP, 0, 0, retryMs);
+        }
+    }
+    try {
+        return operation();
+    }
+    finally {
+        closeSync(descriptor);
+        removeOwnedLock(lockPath, owner.owner);
+    }
+}
+function isRecoverableStaleLock(lockPath, staleMs) {
+    let ageMs;
+    try {
+        ageMs = Date.now() - statSync(lockPath).mtimeMs;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return true;
+        throw error;
+    }
+    if (ageMs <= staleMs)
+        return false;
+    const owner = readLockOwner(lockPath);
+    if (!owner)
+        return true;
+    // A remote PID cannot be checked safely. On shared filesystems, deleting a
+    // stale-looking lock owned by another host could break an active writer.
+    if (owner.hostname !== hostname())
+        return false;
+    return !isProcessAlive(owner.pid);
+}
+function readLockOwner(lockPath) {
+    try {
+        const value = JSON.parse(readFileSync(lockPath, 'utf-8'));
+        if (!value
+            || typeof value !== 'object'
+            || typeof value.owner !== 'string'
+            || !Number.isSafeInteger(value.pid)
+            || value.pid <= 0
+            || typeof value.hostname !== 'string'
+            || typeof value.acquiredAt !== 'string')
+            return null;
+        return value;
+    }
+    catch {
+        return null;
+    }
+}
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code !== 'ESRCH';
+    }
+}
+function removeOwnedLock(lockPath, owner) {
+    const current = readLockOwner(lockPath);
+    if (!current || current.owner !== owner)
+        return;
+    try {
+        unlinkSync(lockPath);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+}

package/dist/shared/json-value.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Runtime guard for data that can cross OMK's JSON persistence boundaries
+ * without coercion, property loss, or cycle errors.
+ */
+export declare function isJsonValue(value: unknown, seen?: Set<object>, depth?: number): boolean;

package/dist/shared/json-value.js

@@ -0,0 +1,36 @@
+/**
+ * Runtime guard for data that can cross OMK's JSON persistence boundaries
+ * without coercion, property loss, or cycle errors.
+ */
+export function isJsonValue(value, seen = new Set(), depth = 0) {
+    if (value === null
+        || typeof value === 'string'
+        || typeof value === 'boolean')
+        return true;
+    if (typeof value === 'number')
+        return Number.isFinite(value);
+    if (typeof value !== 'object' || depth >= 32 || seen.has(value))
+        return false;
+    try {
+        if (Array.isArray(value)) {
+            if (Object.keys(value).length !== value.length
+                || value.some((_, index) => !Object.hasOwn(value, index)))
+                return false;
+        }
+        else {
+            const prototype = Object.getPrototypeOf(value);
+            if (prototype !== Object.prototype && prototype !== null)
+                return false;
+        }
+        seen.add(value);
+        const valid = Array.isArray(value)
+            ? value.every((entry) => isJsonValue(entry, seen, depth + 1))
+            : Object.values(value).every((entry) => isJsonValue(entry, seen, depth + 1));
+        seen.delete(value);
+        return valid;
+    }
+    catch {
+        seen.delete(value);
+        return false;
+    }
+}

package/dist/shared/keyed-mutex.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Serialize asynchronous mutations by key without coupling unrelated keys.
+ */
+export declare class KeyedMutex {
+    private readonly tails;
+    run<T>(key: string, operation: () => Promise<T>): Promise<T>;
+}

package/dist/shared/keyed-mutex.js

@@ -0,0 +1,24 @@
+/**
+ * Serialize asynchronous mutations by key without coupling unrelated keys.
+ */
+export class KeyedMutex {
+    tails = new Map();
+    async run(key, operation) {
+        const previous = this.tails.get(key) ?? Promise.resolve();
+        let release;
+        const current = new Promise((resolve) => {
+            release = resolve;
+        });
+        this.tails.set(key, current);
+        await previous;
+        try {
+            return await operation();
+        }
+        finally {
+            release();
+            if (this.tails.get(key) === current) {
+                this.tails.delete(key);
+            }
+        }
+    }
+}

package/dist/shared/record-count.d.ts

@@ -0,0 +1,8 @@
+export declare function ownRecordValue<T>(record: Record<string, T>, key: string): T | undefined;
+export declare function setOwnRecordValue<T>(record: Record<string, T>, key: string, value: T): T;
+/**
+ * Increment an arbitrary string-keyed counter without reading inherited
+ * properties such as `constructor` or invoking the legacy `__proto__` setter.
+ */
+export declare function incrementRecordCount(record: Record<string, number>, key: string, amount?: number): number;
+export declare function sumRecordCounts(...values: number[]): number;