@loomhelix/deptrail 0.1.0

package/dist/enrich/enrichment-service.js

@@ -0,0 +1,399 @@
+import { posix } from 'node:path';
+import { createSecretSet } from "../config/secrets.js";
+import { readRegistryCredentials } from "./credentials.js";
+import { isFresh } from "./enrichment-cache.js";
+import { hasKnownVersion, inPrivateScope, isPlaceholder, isRegistryPackage, planKeys, registryKeyOf, registryUrlOf, } from "./enrichment-keys.js";
+import { createRevisionCounter, offlineStatus, problemsOf, progressOf } from "./enrichment-status.js";
+import { ADVISORIES_VIEWS, advisoriesCover, createCacheAccess, createLimiter, createRecordStore, isCachedAdvisories, isCachedMatch, isCachedRegistry, MATCH_VIEWS, REGISTRY_VIEWS, registryOk, } from "./enrichment-store.js";
+import { HTTP_DEFAULTS, HttpError } from "./http.js";
+import { createOnDemandLookups } from "./on-demand.js";
+import { OSV_DEFAULT_URL, queryPackageAdvisories, queryVersions, versionKey } from "./osv-client.js";
+import { failureReason, fetchPackageMeta, metaCovers, packumentUrl } from "./registry-client.js";
+const NO_AUTHORIZATION_MARKER = 'no-authorization';
+const DEFAULT_REVISION_INTERVAL_MS = 1000;
+const CACHE_CONCURRENCY = 64;
+const REGISTRY_REQUESTS_PER_URL = HTTP_DEFAULTS.concurrencyPerOrigin;
+const OSV_PARALLEL_PACKAGE_QUERIES = 8;
+const NPMRC_FILE = '.npmrc';
+const NOT_MODIFIED_WITHOUT_VALIDATOR = 'responded with HTTP 304';
+const MISSING_OSV_RESULT = 'returned a malformed response';
+const PENDING = { state: 'pending' };
+const OFFLINE = { state: 'offline' };
+const NOT_APPLICABLE = { state: 'not-applicable' };
+const PRIVATE_SCOPE_SKIP = { state: 'skipped', reason: 'private-scope' };
+const NON_REGISTRY_SKIP = { state: 'skipped', reason: 'non-registry' };
+const UNKNOWN_VERSION_SKIP = { state: 'skipped', reason: 'unknown-version' };
+const EMPTY_READER = {
+    readText: async () => null,
+    exists: async () => false,
+    listDir: async () => [],
+    realpath: async () => null,
+};
+const NO_NETWORK = {
+    request: async () => {
+        throw new HttpError('network');
+    },
+};
+function omitsVersionInUse(record, versionsInUse) {
+    if (record.state !== 'ok')
+        return false;
+    const listed = new Set(record.meta.versions);
+    return versionsInUse.some((version) => hasKnownVersion(version) && !listed.has(version));
+}
+export function createEnrichmentService(options) {
+    const { reader, env, userNpmrc, http, osvUrl, secrets, offline } = options;
+    const now = options.now ?? Date.now;
+    const cache = createCacheAccess(options.cache, CACHE_CONCURRENCY);
+    const limitPackageQueries = createLimiter(OSV_PARALLEL_PACKAGE_QUERIES);
+    const registryLimiters = new Map();
+    const refetchedForUnlistedVersion = new Set();
+    const revisions = createRevisionCounter(options.revisionIntervalMs ?? DEFAULT_REVISION_INTERVAL_MS);
+    const landed = () => revisions.resultLanded();
+    const registryStore = createRecordStore(REGISTRY_VIEWS, landed);
+    const matchStore = createRecordStore(MATCH_VIEWS, landed);
+    const advisoriesStore = createRecordStore(ADVISORIES_VIEWS, landed);
+    const activePasses = new Set();
+    const versionsWantedInFlight = new Map();
+    const credentialsByRootPath = new Map();
+    let trackedRoots = [];
+    let currentPlan = planKeys([], new Set());
+    let finishedAt;
+    let closed = false;
+    const nowIso = () => new Date(now()).toISOString();
+    const isFreshNow = (fetchedAt) => isFresh(fetchedAt, now());
+    function awaitsRefetchForUnlistedVersion(key, record, versionsInUse) {
+        return !refetchedForUnlistedVersion.has(key) && omitsVersionInUse(record, versionsInUse);
+    }
+    function registryRecordUsable(key, record, versionsInUse) {
+        if (!isFreshNow(record.fetchedAt))
+            return false;
+        if (record.state === 'not-found')
+            return true;
+        return metaCovers(record.meta, versionsInUse) && !awaitsRefetchForUnlistedVersion(key, record, versionsInUse);
+    }
+    function advisoriesUsable(record, reported) {
+        return isFreshNow(record.fetchedAt) && advisoriesCover(record.advisories, reported);
+    }
+    function credentialsOf(root) {
+        const known = credentialsByRootPath.get(root.path);
+        if (known !== undefined)
+            return known;
+        const reading = reader
+            .readText(posix.join(root.path, NPMRC_FILE))
+            .catch(() => null)
+            .then((projectNpmrc) => readRegistryCredentials({ projectNpmrc, userNpmrc, env }, secrets));
+        credentialsByRootPath.set(root.path, reading);
+        return reading;
+    }
+    async function storeRegistry(target, record) {
+        registryStore.succeed(target.key, record);
+        await cache.write('registry', [target.registryUrl, target.name], record);
+    }
+    function registryLimiterOf(registryUrl) {
+        const known = registryLimiters.get(registryUrl);
+        if (known !== undefined)
+            return known;
+        const limiter = createLimiter(REGISTRY_REQUESTS_PER_URL);
+        registryLimiters.set(registryUrl, limiter);
+        return limiter;
+    }
+    function credentialsKeyOf(target, authorizationFor) {
+        const authorization = authorizationFor(packumentUrl(target.registryUrl, target.name));
+        return `${target.registryUrl}\n${authorization ?? NO_AUTHORIZATION_MARKER}`;
+    }
+    function rememberRejectedCredentials(pass, credentialsKey, result) {
+        if (result.state !== 'failed' || !result.authRejected || pass.rejectedCredentials.has(credentialsKey))
+            return;
+        pass.rejectedCredentials.set(credentialsKey, result.reason);
+    }
+    async function fetchRegistryRecord(target, versionsInUse, validatorCandidate, authorizationFor, credentialsKey, pass) {
+        const validator = validatorCandidate?.state === 'ok' && metaCovers(validatorCandidate.meta, versionsInUse) ? validatorCandidate : undefined;
+        const result = await fetchPackageMeta(http, {
+            registry: target.registryUrl,
+            name: target.name,
+            etag: validator?.etag,
+            versionsInUse,
+            authorizationFor,
+        });
+        rememberRejectedCredentials(pass, credentialsKey, result);
+        const fetchedAt = nowIso();
+        if (result.state === 'ok')
+            return { record: registryOk(result.meta, fetchedAt, result.etag) };
+        if (result.state === 'not-found')
+            return { record: { state: 'not-found', fetchedAt } };
+        if (result.state === 'not-modified' && validator !== undefined) {
+            return { record: registryOk(validator.meta, fetchedAt, validator.etag) };
+        }
+        return { failure: result.state === 'failed' ? result.reason : NOT_MODIFIED_WITHOUT_VALIDATOR };
+    }
+    function fetchUnlessCredentialsRejected(target, versionsInUse, validatorCandidate, authorizationFor, pass) {
+        const credentialsKey = credentialsKeyOf(target, authorizationFor);
+        return registryLimiterOf(target.registryUrl)(async () => {
+            const rejection = pass.rejectedCredentials.get(credentialsKey);
+            if (rejection !== undefined)
+                return { failure: rejection };
+            return fetchRegistryRecord(target, versionsInUse, validatorCandidate, authorizationFor, credentialsKey, pass);
+        });
+    }
+    function missesVersionsAddedMeanwhile(record, requested, wanted) {
+        return wanted.size > requested.length && record.state === 'ok' && !metaCovers(record.meta, [...wanted]);
+    }
+    async function resolveRegistryTarget(target, pass) {
+        const wanted = new Set(target.versionsInUse);
+        versionsWantedInFlight.set(target.key, wanted);
+        let lastGood;
+        try {
+            const cached = await cache.read('registry', [target.registryUrl, target.name], isCachedRegistry);
+            if (cached !== undefined && !pass.forceExpired && registryRecordUsable(target.key, cached, [...wanted])) {
+                registryStore.succeed(target.key, cached);
+                return;
+            }
+            lastGood = cached ?? registryStore.lastGoodOf(target.key);
+            const { authorizationFor } = await credentialsOf(target.credentialsRoot);
+            for (;;) {
+                const requested = [...wanted];
+                const refetchesUnlistedVersion = lastGood !== undefined && omitsVersionInUse(lastGood, requested);
+                if (refetchesUnlistedVersion)
+                    refetchedForUnlistedVersion.add(target.key);
+                const validatorCandidate = refetchesUnlistedVersion ? undefined : lastGood;
+                const fetched = await fetchUnlessCredentialsRejected(target, requested, validatorCandidate, authorizationFor, pass);
+                if ('failure' in fetched) {
+                    registryStore.fail(target.key, fetched.failure, lastGood);
+                    return;
+                }
+                await storeRegistry(target, fetched.record);
+                const refetchNeeded = missesVersionsAddedMeanwhile(fetched.record, requested, wanted) ||
+                    awaitsRefetchForUnlistedVersion(target.key, fetched.record, [...wanted]);
+                if (!refetchNeeded)
+                    return;
+                lastGood = fetched.record;
+            }
+        }
+        catch (error) {
+            registryStore.fail(target.key, failureReason(error), lastGood);
+        }
+        finally {
+            registryStore.release(target.key);
+            versionsWantedInFlight.delete(target.key);
+        }
+    }
+    function addVersionsToFetchesInFlight(plan) {
+        for (const target of plan.registry.values()) {
+            const wanted = versionsWantedInFlight.get(target.key);
+            if (wanted === undefined)
+                continue;
+            for (const version of target.versionsInUse)
+                wanted.add(version);
+        }
+    }
+    async function queryUnresolved(unresolved) {
+        if (unresolved.length === 0)
+            return;
+        let outcome;
+        try {
+            outcome = await queryVersions(http, osvUrl, unresolved.map(({ target }) => ({ name: target.name, version: target.version })));
+        }
+        catch (error) {
+            const reason = failureReason(error);
+            outcome = { matches: new Map(), failed: new Map(unresolved.map(({ target }) => [target.key, reason])) };
+        }
+        const fetchedAt = nowIso();
+        const writes = unresolved.map(({ target, lastGood }) => {
+            const vulns = outcome.matches.get(target.key);
+            if (vulns === undefined) {
+                matchStore.fail(target.key, outcome.failed.get(target.key) ?? MISSING_OSV_RESULT, lastGood);
+                return undefined;
+            }
+            const record = { state: 'ok', vulns, fetchedAt };
+            matchStore.succeed(target.key, record);
+            return cache.write('osv-matches', [target.key], record);
+        });
+        await Promise.all(writes);
+    }
+    async function resolveVersionTargets(targets, pass) {
+        try {
+            const unresolved = [];
+            await Promise.all(targets.map(async (target) => {
+                const cached = await cache.read('osv-matches', [target.key], isCachedMatch);
+                if (cached !== undefined && !pass.forceExpired && isFreshNow(cached.fetchedAt))
+                    matchStore.succeed(target.key, cached);
+                else
+                    unresolved.push({ target, lastGood: cached ?? matchStore.lastGoodOf(target.key) });
+            }));
+            await queryUnresolved(unresolved);
+        }
+        finally {
+            for (const target of targets)
+                matchStore.release(target.key);
+        }
+    }
+    function reportedVulnsByName(plan) {
+        const reported = new Map();
+        for (const target of plan.versions.values()) {
+            const state = matchStore.stateOf(target.key);
+            if (state === undefined || (state.state !== 'ok' && state.state !== 'stale') || state.vulns.length === 0)
+                continue;
+            const refs = reported.get(target.name) ?? [];
+            refs.push(...state.vulns);
+            reported.set(target.name, refs);
+        }
+        return reported;
+    }
+    async function resolveAdvisoriesTarget(target, pass) {
+        let lastGood;
+        try {
+            const cached = await cache.read('osv-packages', [target.key], isCachedAdvisories);
+            if (cached !== undefined && !pass.forceExpired && advisoriesUsable(cached, target.reported)) {
+                advisoriesStore.succeed(target.key, cached);
+                return;
+            }
+            lastGood = cached ?? advisoriesStore.lastGoodOf(target.key);
+            const result = await limitPackageQueries(() => queryPackageAdvisories(http, osvUrl, target.key));
+            if (result.state === 'failed') {
+                advisoriesStore.fail(target.key, result.reason, lastGood);
+                return;
+            }
+            const record = { fetchedAt: nowIso(), advisories: result.advisories };
+            advisoriesStore.succeed(target.key, record);
+            await cache.write('osv-packages', [target.key], record);
+        }
+        catch (error) {
+            advisoriesStore.fail(target.key, failureReason(error), lastGood);
+        }
+        finally {
+            advisoriesStore.release(target.key);
+        }
+    }
+    async function resolveOsv(targets, pass) {
+        await resolveVersionTargets(targets, pass);
+        const advisoryTargets = advisoriesStore.claim([...reportedVulnsByName(pass.plan)].map(([key, reported]) => ({ key, reported })), (target) => !pass.forceExpired && advisoriesStore.isKnown(target.key, (record) => advisoriesUsable(record, target.reported)));
+        await Promise.all(advisoryTargets.map((target) => resolveAdvisoriesTarget(target, pass)));
+    }
+    function onlineWork(pass) {
+        const { plan, forceExpired } = pass;
+        addVersionsToFetchesInFlight(plan);
+        const registryTargets = registryStore.claim(plan.registry.values(), (target) => !forceExpired && registryStore.isKnown(target.key, (record) => registryRecordUsable(target.key, record, [...target.versionsInUse])));
+        const work = registryTargets.map((target) => resolveRegistryTarget(target, pass));
+        if (plan.waitsForScanningRoots)
+            return work;
+        const versionTargets = matchStore.claim(plan.versions.values(), (target) => !forceExpired && matchStore.isKnown(target.key, (record) => isFreshNow(record.fetchedAt)));
+        return [...work, resolveOsv(versionTargets, pass)];
+    }
+    function runPass(roots, forceExpired) {
+        const plan = planKeys(roots, currentPlan.privateScopes);
+        const pass = { plan, forceExpired, rejectedCredentials: new Map() };
+        const credentialReads = plan.roots.map(credentialsOf);
+        if (!offline)
+            currentPlan = plan;
+        const work = Promise.allSettled([...credentialReads, ...(offline ? [] : onlineWork(pass))]);
+        const running = work.finally(() => {
+            activePasses.delete(running);
+            if (activePasses.size > 0)
+                return;
+            revisions.drained();
+            finishedAt = nowIso();
+        });
+        activePasses.add(running);
+    }
+    function matchOfVersion(name, version) {
+        if (offline)
+            return OFFLINE;
+        if (inPrivateScope(name, currentPlan.privateScopes))
+            return PRIVATE_SCOPE_SKIP;
+        const state = matchStore.stateOf(versionKey(name, version));
+        if (state !== undefined)
+            return state;
+        return hasKnownVersion(version) ? PENDING : UNKNOWN_VERSION_SKIP;
+    }
+    function onlineStatus(anyRootScanning) {
+        const running = activePasses.size > 0 || anyRootScanning;
+        const osv = progressOf(currentPlan.versions.keys(), matchStore);
+        return {
+            state: running ? 'running' : 'done',
+            revision: revisions.current,
+            registry: progressOf(currentPlan.registry.keys(), registryStore),
+            osv: { total: osv.total, done: osv.done, skipped: currentPlan.skippedVersions, failed: osv.failed },
+            problems: problemsOf(currentPlan, {
+                registry: registryStore,
+                matches: matchStore,
+                advisories: advisoriesStore,
+                osvUrl,
+                secrets,
+            }),
+            ...(running || finishedAt === undefined ? {} : { finishedAt }),
+        };
+    }
+    const onDemand = createOnDemandLookups({
+        http,
+        osvUrl,
+        offline,
+        cache,
+        now,
+        credentialsOf,
+        registryLimiterOf,
+        limitPackageQueries,
+        privateScopes: () => currentPlan.privateScopes,
+        storedMatchOf: matchStore.stateOf,
+        storedAdvisoriesOf: advisoriesStore.stateOf,
+    });
+    return {
+        get revision() {
+            return revisions.current;
+        },
+        registryOf(root, node) {
+            if (!isRegistryPackage(node))
+                return NOT_APPLICABLE;
+            if (offline)
+                return OFFLINE;
+            if (root.config === undefined)
+                return PENDING;
+            return registryStore.stateOf(registryKeyOf(registryUrlOf(root.config, node.name), node.name)) ?? PENDING;
+        },
+        matchOf(_root, node) {
+            if (isRegistryPackage(node))
+                return matchOfVersion(node.name, node.version);
+            return isPlaceholder(node) ? NOT_APPLICABLE : NON_REGISTRY_SKIP;
+        },
+        matchOfVersion,
+        advisoriesOf(name) {
+            return advisoriesStore.stateOf(name) ?? PENDING;
+        },
+        track(roots) {
+            if (closed)
+                return;
+            trackedRoots = roots;
+            runPass(roots, false);
+        },
+        refresh() {
+            if (closed)
+                return;
+            credentialsByRootPath.clear();
+            runPass(trackedRoots, true);
+        },
+        status(anyRootScanning) {
+            return offline ? offlineStatus(revisions.current) : onlineStatus(anyRootScanning);
+        },
+        async settled() {
+            while (activePasses.size > 0)
+                await Promise.all(activePasses);
+        },
+        close() {
+            closed = true;
+            options.abort?.abort();
+        },
+        publishedVersions: onDemand.publishedVersions,
+        assess: onDemand.assess,
+    };
+}
+export function offlineEnrichment() {
+    return createEnrichmentService({
+        reader: EMPTY_READER,
+        env: {},
+        userNpmrc: null,
+        http: NO_NETWORK,
+        osvUrl: OSV_DEFAULT_URL,
+        cache: null,
+        secrets: createSecretSet(),
+        offline: true,
+    });
+}

package/dist/enrich/enrichment-status.js

@@ -0,0 +1,86 @@
+const UNPARSABLE_ORIGIN = 'invalid URL';
+const GROUP_KEY_SEPARATOR = '\0';
+export function originOf(url) {
+    try {
+        return new URL(url).origin;
+    }
+    catch {
+        return UNPARSABLE_ORIGIN;
+    }
+}
+export function offlineStatus(revision) {
+    return {
+        state: 'offline',
+        revision,
+        registry: { total: 0, done: 0, failed: 0 },
+        osv: { total: 0, done: 0, skipped: 0, failed: 0 },
+        problems: [],
+    };
+}
+export function progressOf(keys, store) {
+    const progress = { total: 0, done: 0, failed: 0 };
+    for (const key of keys) {
+        progress.total++;
+        const state = store.settledStateOf(key);
+        if (state === undefined)
+            continue;
+        progress.done++;
+        if (state.state === 'failed')
+            progress.failed++;
+    }
+    return progress;
+}
+export function problemsOf(plan, sources) {
+    const groups = new Map();
+    const count = (source, origin, failure) => {
+        if (failure === undefined)
+            return;
+        const groupKey = [source, origin, failure].join(GROUP_KEY_SEPARATOR);
+        const group = groups.get(groupKey) ?? { source, origin, message: sources.secrets.redact(failure), count: 0 };
+        group.count++;
+        groups.set(groupKey, group);
+    };
+    for (const target of plan.registry.values()) {
+        const failure = sources.registry.settledFailureOf(target.key);
+        if (failure !== undefined)
+            count('registry', originOf(target.registryUrl), failure);
+    }
+    const osvOrigin = originOf(sources.osvUrl);
+    for (const key of plan.versions.keys())
+        count('osv', osvOrigin, sources.matches.settledFailureOf(key));
+    for (const name of new Set([...plan.versions.values()].map((target) => target.name))) {
+        count('osv', osvOrigin, sources.advisories.settledFailureOf(name));
+    }
+    return [...groups.values()];
+}
+export function createRevisionCounter(intervalMs) {
+    let revision = 0;
+    let landedSinceIncrement = false;
+    let throttle;
+    function increment() {
+        revision++;
+        landedSinceIncrement = false;
+        throttle = setTimeout(() => {
+            throttle = undefined;
+            if (landedSinceIncrement)
+                increment();
+        }, intervalMs);
+        throttle.unref();
+    }
+    return {
+        get current() {
+            return revision;
+        },
+        resultLanded() {
+            landedSinceIncrement = true;
+            if (throttle === undefined)
+                increment();
+        },
+        drained() {
+            clearTimeout(throttle);
+            throttle = undefined;
+            landedSinceIncrement = false;
+            revision++;
+        },
+    };
+}

package/dist/enrich/enrichment-store.js

@@ -0,0 +1,143 @@
+import { isPackageMeta } from "./registry-client.js";
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+export function registryOk(meta, fetchedAt, etag) {
+    return etag === undefined ? { state: 'ok', meta, fetchedAt } : { state: 'ok', meta, fetchedAt, etag };
+}
+export function isCachedRegistry(value) {
+    if (!isPlainObject(value) || typeof value.fetchedAt !== 'string')
+        return false;
+    if (value.state === 'not-found')
+        return true;
+    return value.state === 'ok' && isPackageMeta(value.meta) && (value.etag === undefined || typeof value.etag === 'string');
+}
+function isVulnRef(value) {
+    return isPlainObject(value) && typeof value.id === 'string' && typeof value.modified === 'string';
+}
+export function isCachedMatch(value) {
+    return (isPlainObject(value) &&
+        value.state === 'ok' &&
+        typeof value.fetchedAt === 'string' &&
+        Array.isArray(value.vulns) &&
+        value.vulns.every(isVulnRef));
+}
+function isAdvisory(value) {
+    return (isPlainObject(value) &&
+        typeof value.id === 'string' &&
+        typeof value.summary === 'string' &&
+        typeof value.severity === 'string' &&
+        typeof value.malicious === 'boolean' &&
+        typeof value.url === 'string' &&
+        typeof value.modified === 'string' &&
+        Array.isArray(value.aliases) &&
+        Array.isArray(value.fixedIn) &&
+        Array.isArray(value.affected));
+}
+export function isCachedAdvisories(value) {
+    return (isPlainObject(value) &&
+        typeof value.fetchedAt === 'string' &&
+        Array.isArray(value.advisories) &&
+        value.advisories.every(isAdvisory));
+}
+function coversReport(advisory, reported) {
+    if (advisory.aliases.includes(reported.id))
+        return true;
+    return advisory.id === reported.id && !(Date.parse(reported.modified) > Date.parse(advisory.modified));
+}
+export function advisoriesCover(advisories, reported) {
+    return reported.every((ref) => advisories.some((advisory) => coversReport(advisory, ref)));
+}
+export const REGISTRY_VIEWS = {
+    ofSuccess: (record) => record.state === 'ok'
+        ? { state: 'ok', meta: record.meta, fetchedAt: record.fetchedAt }
+        : { state: 'not-found', fetchedAt: record.fetchedAt },
+    ofFailure: (reason, lastGood) => lastGood?.state === 'ok'
+        ? { state: 'stale', meta: lastGood.meta, fetchedAt: lastGood.fetchedAt }
+        : { state: 'failed', reason },
+};
+export const MATCH_VIEWS = {
+    ofSuccess: ({ vulns, fetchedAt }) => ({ state: 'ok', vulns, fetchedAt }),
+    ofFailure: (reason, lastGood) => lastGood === undefined ? { state: 'failed', reason } : { state: 'stale', vulns: lastGood.vulns, fetchedAt: lastGood.fetchedAt },
+};
+export const ADVISORIES_VIEWS = {
+    ofSuccess: ({ advisories, fetchedAt }) => ({ state: 'ok', advisories, fetchedAt }),
+    ofFailure: (reason, lastGood) => lastGood === undefined
+        ? { state: 'failed', reason }
+        : { state: 'stale', advisories: lastGood.advisories, fetchedAt: lastGood.fetchedAt },
+};
+export function createRecordStore(views, onLanded) {
+    const entries = new Map();
+    const inFlight = new Set();
+    return {
+        stateOf: (key) => entries.get(key)?.state,
+        settledStateOf: (key) => (inFlight.has(key) ? undefined : entries.get(key)?.state),
+        settledFailureOf: (key) => (inFlight.has(key) ? undefined : entries.get(key)?.failure),
+        lastGoodOf: (key) => entries.get(key)?.lastGood,
+        isKnown(key, usable) {
+            const entry = entries.get(key);
+            if (entry === undefined)
+                return false;
+            if (entry.failure !== undefined)
+                return true;
+            return entry.lastGood !== undefined && usable(entry.lastGood);
+        },
+        claim(targets, isKnown) {
+            const claimed = [];
+            for (const target of targets) {
+                if (inFlight.has(target.key) || isKnown(target))
+                    continue;
+                inFlight.add(target.key);
+                claimed.push(target);
+            }
+            return claimed;
+        },
+        release: (key) => {
+            inFlight.delete(key);
+        },
+        succeed(key, record) {
+            entries.set(key, { state: views.ofSuccess(record), lastGood: record });
+            onLanded();
+        },
+        fail(key, reason, lastGood) {
+            entries.set(key, { state: views.ofFailure(reason, lastGood), lastGood, failure: reason });
+            onLanded();
+        },
+    };
+}
+export function createLimiter(limit) {
+    let active = 0;
+    const waiting = [];
+    return async function limited(task) {
+        if (active < limit)
+            active++;
+        else
+            await new Promise((resolve) => waiting.push(resolve));
+        try {
+            return await task();
+        }
+        finally {
+            const next = waiting.shift();
+            if (next)
+                next();
+            else
+                active--;
+        }
+    };
+}
+export function createCacheAccess(cache, concurrency) {
+    const limited = createLimiter(concurrency);
+    return {
+        async read(kind, keyParts, isShape) {
+            if (cache === null)
+                return undefined;
+            const value = await limited(() => cache.read(kind, keyParts)).catch(() => null);
+            return isShape(value) ? value : undefined;
+        },
+        async write(kind, keyParts, value) {
+            if (cache === null)
+                return;
+            await limited(() => cache.write(kind, keyParts, value)).catch(() => undefined);
+        },
+    };
+}