@wavehouse/chtypes 0.5.2 → 1.0.2

package/dist/ocifetch/layout.d.ts

@@ -0,0 +1,126 @@
+/**
+ * The cache (`docs/guides/fetch-v1.md` §1): a standard OCI image layout
+ * rooted at `CHTYPES_CACHE` or `${XDG_CACHE_HOME:-~/.cache}/chtypes/v1/`,
+ * `unpacked/sha256/<manifest-hex>/` beside it, each carrying its own
+ * `verified.json` — the durable, **immutable once written** proof a
+ * directory was verified, which `resolve_installed`/`--offline` trust
+ * instead of `index.json` (guide §6). Read-only system directories are
+ * searched after the cache, never written to.
+ *
+ * `index.json` is written by temp-file-then-atomic-rename and **never
+ * edited in place**; a concurrent writer's entry must survive (the
+ * `index-race-reapply` case), so every write re-reads the file immediately
+ * before renaming and, if it changed since this write started, discards its
+ * temp file and retries from the fresh content — an optimistic-concurrency
+ * loop, not a lock, because nothing here may block on another process.
+ */
+import type { ArtifactPredicate } from './types.js';
+/** `CHTYPES_CACHE`, else `${XDG_CACHE_HOME:-~/.cache}/chtypes/v1` — the layout root itself, not a parent of it. */
+export declare function cacheRoot(explicitCacheDir?: string): string;
+export declare function systemDirs(override?: readonly string[]): readonly string[];
+export declare function blobsDir(root: string): string;
+/** Reads a local blob by its hex digest, `undefined` when it is not there — never throws on ENOENT. */
+export declare function readLocalBlob(root: string, hex: string): Promise<Buffer | undefined>;
+/** Every blob hex name present under `blobs/sha256/` — `[]` when the directory does not exist. */
+export declare function listLocalBlobHexes(root: string): Promise<readonly string[]>;
+export declare function unpackedDir(root: string, manifestDigestHex: string): string;
+/** Creates the layout root (and `oci-layout`) if it does not exist yet. Safe to call every time — idempotent. */
+export declare function ensureLayout(root: string): Promise<void>;
+/** Installs one verified blob into `blobs/sha256/<hex>` by temp-then-rename. A no-op if it is already there (content-addressed). */
+export declare function installBlob(root: string, digestHex: string, bytes: Buffer): Promise<string>;
+export interface IndexDescriptor {
+    readonly mediaType: string;
+    readonly digest: string;
+    readonly size: number;
+    readonly artifactType?: string;
+    readonly platform?: {
+        readonly os: string;
+        readonly architecture: string;
+    };
+    readonly annotations?: Readonly<Record<string, string>>;
+}
+/**
+ * Upserts one descriptor (by digest) into `index.json`, surviving a
+ * concurrent writer: re-reads the file immediately before the atomic rename
+ * and, if it changed since this call started, re-merges onto the fresh
+ * content and tries again (bounded — a layout should never see sustained
+ * contention). `beforeRename` is a test-only hook (`index-race-reapply`)
+ * that runs after the temp file is written and before the race check.
+ */
+export declare function upsertIndexEntry(root: string, descriptor: IndexDescriptor, beforeRename?: () => Promise<void> | void): Promise<void>;
+/** Every descriptor `index.json` currently lists, `[]` if the file is absent or unreadable. */
+export declare function readIndexEntries(root: string): Promise<readonly IndexDescriptor[]>;
+/**
+ * One `unpacked/sha256/<hex>/verified.json`, in memory. Its on-disk form is
+ * the one canonical record every binding reads and writes
+ * (`spec/fetch-v1/schema/verified.schema.json`, guide §1): see
+ * `encodeRecord` and `decodeRecord`. Optional members are `null` here and
+ * on disk.
+ */
+export interface VerifiedRecord {
+    readonly platform: string;
+    readonly version: string;
+    readonly channel: string | null;
+    readonly build: string;
+    /** The library's file name, relative to the unpacked directory. */
+    readonly library: string;
+    readonly librarySha256: string;
+    readonly libraryBytes: number;
+    readonly indexDigest: string | null;
+    readonly manifestDigest: string;
+    readonly layerDigest: string;
+    readonly bundleDigest: string | null;
+    readonly bundleManifestDigest: string | null;
+    /** `null` only under allow-unsigned. */
+    readonly signedBy: string | null;
+    readonly predicate: ArtifactPredicate;
+}
+export interface RecordSource {
+    readonly platform: string;
+    readonly predicate: ArtifactPredicate;
+    /** The unpacked library as measured on disk (`measureLibrary`), never copied from an unsigned config. */
+    readonly library: {
+        readonly sha256: string;
+        readonly bytes: number;
+    };
+    readonly indexDigest: string | null;
+    readonly manifestDigest: string;
+    readonly layerDigest: string;
+    readonly bundleDigest: string | null;
+    readonly bundleManifestDigest: string | null;
+    readonly signedBy: string | null;
+}
+/** Builds the canonical record for one verified install from what the install itself established. */
+export declare function buildRecord(src: RecordSource): VerifiedRecord;
+/** The canonical `verified.json` text: every member present, `null` where the schema allows it. */
+export declare function encodeRecord(record: VerifiedRecord): string;
+/**
+ * Accepts exactly the canonical schema-1 record. Anything else (not JSON,
+ * another schema, a missing member, a member of the wrong type, a broken
+ * rule) is `undefined`, which every caller treats as an ABSENT record —
+ * never fatal by itself and never trusted.
+ */
+export declare function decodeRecord(raw: string): VerifiedRecord | undefined;
+/**
+ * Writes the directory's own durable proof of verification — **the source
+ * of truth for `--offline` and `resolve_installed`** (guide §6), never
+ * `index.json`. Written once, by temp-then-rename, immediately after a
+ * successful unpack; a directory with no acceptable `verified.json` is
+ * treated as unverified regardless of what `index.json` claims about it.
+ * A record that would not read back (it breaks the schema) is refused here
+ * rather than left behind as a directory no reader will trust.
+ */
+export declare function writeVerifiedRecord(dir: string, record: VerifiedRecord): Promise<void>;
+/** `undefined` when the directory has no acceptable `verified.json` (missing, unparsable, another schema, or a broken rule) — never partially trusted. */
+export declare function readVerifiedRecord(dir: string): Promise<VerifiedRecord | undefined>;
+/** Every `unpacked/sha256/*` directory that carries a `verified.json` — `list_installed`'s and monotonicity's source. */
+export declare function listVerified(root: string): Promise<readonly {
+    readonly dir: string;
+    readonly record: VerifiedRecord;
+}[]>;
+/** A fresh, empty staging directory beside `unpacked/`, for temp-then-rename of a whole unpacked tree. */
+export declare function freshStagingDir(root: string): Promise<string>;
+/** Renames a staged, fully-verified unpack into its final content-addressed home; removes the staging dir on any failure. */
+export declare function commitStaging(stagingDir: string, finalDir: string): Promise<void>;
+export declare function removeStaging(stagingDir: string): Promise<void>;
+//# sourceMappingURL=layout.d.ts.map

package/dist/ocifetch/layout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"layout.d.ts","sourceRoot":"","sources":["../../src/ocifetch/layout.ts"],"names":[],"mappings":"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"}

package/dist/ocifetch/layout.js

@@ -0,0 +1,375 @@
+/**
+ * The cache (`docs/guides/fetch-v1.md` §1): a standard OCI image layout
+ * rooted at `CHTYPES_CACHE` or `${XDG_CACHE_HOME:-~/.cache}/chtypes/v1/`,
+ * `unpacked/sha256/<manifest-hex>/` beside it, each carrying its own
+ * `verified.json` — the durable, **immutable once written** proof a
+ * directory was verified, which `resolve_installed`/`--offline` trust
+ * instead of `index.json` (guide §6). Read-only system directories are
+ * searched after the cache, never written to.
+ *
+ * `index.json` is written by temp-file-then-atomic-rename and **never
+ * edited in place**; a concurrent writer's entry must survive (the
+ * `index-race-reapply` case), so every write re-reads the file immediately
+ * before renaming and, if it changed since this write started, discards its
+ * temp file and retries from the fresh content — an optimistic-concurrency
+ * loop, not a lock, because nothing here may block on another process.
+ */
+import { randomBytes } from 'node:crypto';
+import { mkdir, readdir, readFile, rename, rm, unlink, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { CACHE_UNPACKED_DIR, CACHE_VERIFIED_RECORD, ENV_CACHE_NAME, PLATFORMS, SYSTEM_CACHE_DIRS } from './constants.gen.js';
+import { ArtifactCorruptError } from './errors.js';
+/** `CHTYPES_CACHE`, else `${XDG_CACHE_HOME:-~/.cache}/chtypes/v1` — the layout root itself, not a parent of it. */
+export function cacheRoot(explicitCacheDir) {
+    if (explicitCacheDir !== undefined && explicitCacheDir !== '')
+        return path.resolve(explicitCacheDir);
+    const env = process.env[ENV_CACHE_NAME];
+    if (env !== undefined && env !== '')
+        return path.resolve(env);
+    const xdg = process.env['XDG_CACHE_HOME'];
+    const base = xdg !== undefined && xdg !== '' ? xdg : path.join(os.homedir(), '.cache');
+    return path.join(base, 'chtypes', 'v1');
+}
+export function systemDirs(override) {
+    return override ?? SYSTEM_CACHE_DIRS;
+}
+export function blobsDir(root) {
+    return path.join(root, 'blobs', 'sha256');
+}
+/** Reads a local blob by its hex digest, `undefined` when it is not there — never throws on ENOENT. */
+export async function readLocalBlob(root, hex) {
+    try {
+        return await readFile(path.join(blobsDir(root), hex));
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return undefined;
+        throw err;
+    }
+}
+/** Every blob hex name present under `blobs/sha256/` — `[]` when the directory does not exist. */
+export async function listLocalBlobHexes(root) {
+    try {
+        return await readdir(blobsDir(root));
+    }
+    catch {
+        return [];
+    }
+}
+export function unpackedDir(root, manifestDigestHex) {
+    return path.join(root, CACHE_UNPACKED_DIR, manifestDigestHex);
+}
+function indexJsonPath(root) {
+    return path.join(root, 'index.json');
+}
+async function tempPathNear(target) {
+    const rand = randomBytes(6).toString('hex');
+    return `${target}.tmp-${process.pid}-${rand}`;
+}
+/** Creates the layout root (and `oci-layout`) if it does not exist yet. Safe to call every time — idempotent. */
+export async function ensureLayout(root) {
+    await mkdir(root, { recursive: true });
+    await mkdir(blobsDir(root), { recursive: true });
+    await mkdir(path.join(root, CACHE_UNPACKED_DIR), { recursive: true });
+    const marker = path.join(root, 'oci-layout');
+    try {
+        await readFile(marker);
+    }
+    catch {
+        const tmp = await tempPathNear(marker);
+        await writeFile(tmp, `${JSON.stringify({ imageLayoutVersion: '1.0.0' })}\n`);
+        await rename(tmp, marker);
+    }
+}
+/** Installs one verified blob into `blobs/sha256/<hex>` by temp-then-rename. A no-op if it is already there (content-addressed). */
+export async function installBlob(root, digestHex, bytes) {
+    const dest = path.join(blobsDir(root), digestHex);
+    try {
+        await readFile(dest);
+        return dest;
+    }
+    catch {
+        // Not present yet — fall through and install it.
+    }
+    const tmp = await tempPathNear(dest);
+    await writeFile(tmp, bytes);
+    try {
+        await rename(tmp, dest);
+    }
+    catch (err) {
+        await unlink(tmp).catch(() => { });
+        throw err;
+    }
+    return dest;
+}
+const EMPTY_INDEX = { schemaVersion: 2, manifests: [] };
+async function readRawIndex(root) {
+    try {
+        return await readFile(indexJsonPath(root), 'utf8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return undefined;
+        throw err;
+    }
+}
+/**
+ * `index.json` is our own durable bookkeeping (plus whatever `oras copy
+ * --to-oci-layout` pre-seeded) — parsed with plain `JSON.parse` here rather
+ * than `../json.ts`'s duplicate-key-aware reader, which is reserved for
+ * untrusted, attacker-reachable bytes (DSSE statements, referrer listings).
+ * This file is local and either ours or a trusted tool's.
+ */
+function parseIndex(raw) {
+    if (raw === undefined)
+        return EMPTY_INDEX;
+    try {
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed.manifests))
+            return EMPTY_INDEX;
+        return { schemaVersion: 2, manifests: parsed.manifests };
+    }
+    catch {
+        return EMPTY_INDEX;
+    }
+}
+/**
+ * Upserts one descriptor (by digest) into `index.json`, surviving a
+ * concurrent writer: re-reads the file immediately before the atomic rename
+ * and, if it changed since this call started, re-merges onto the fresh
+ * content and tries again (bounded — a layout should never see sustained
+ * contention). `beforeRename` is a test-only hook (`index-race-reapply`)
+ * that runs after the temp file is written and before the race check.
+ */
+export async function upsertIndexEntry(root, descriptor, beforeRename) {
+    const indexPath = indexJsonPath(root);
+    for (let attempt = 0; attempt < 8; attempt++) {
+        const before = await readRawIndex(root);
+        const current = parseIndex(before);
+        const withoutExisting = current.manifests.filter((m) => m.digest !== descriptor.digest);
+        const merged = { schemaVersion: 2, manifests: [...withoutExisting, descriptor] };
+        const tmp = await tempPathNear(indexPath);
+        await writeFile(tmp, JSON.stringify(merged));
+        if (beforeRename)
+            await beforeRename();
+        const after = await readRawIndex(root);
+        if (after !== before) {
+            // Lost the race: someone else wrote in between. Discard this attempt
+            // and re-merge onto what is actually there now.
+            await unlink(tmp).catch(() => { });
+            continue;
+        }
+        await rename(tmp, indexPath);
+        return;
+    }
+    throw new Error(`chtypes: index.json at ${indexPath} would not settle after 8 attempts (sustained concurrent writers)`);
+}
+/** Every descriptor `index.json` currently lists, `[]` if the file is absent or unreadable. */
+export async function readIndexEntries(root) {
+    return parseIndex(await readRawIndex(root)).manifests;
+}
+/** Builds the canonical record for one verified install from what the install itself established. */
+export function buildRecord(src) {
+    const channel = src.predicate.channel;
+    return {
+        platform: src.platform,
+        version: src.predicate.clickhouse_version,
+        channel: typeof channel === 'string' && channel !== '' ? channel : null,
+        build: src.predicate.build,
+        library: src.predicate.library,
+        librarySha256: src.library.sha256,
+        libraryBytes: src.library.bytes,
+        indexDigest: src.indexDigest,
+        manifestDigest: src.manifestDigest,
+        layerDigest: src.layerDigest,
+        bundleDigest: src.bundleDigest,
+        bundleManifestDigest: src.bundleManifestDigest,
+        signedBy: src.signedBy,
+        predicate: src.predicate,
+    };
+}
+const HEX64 = /^[0-9a-f]{64}$/;
+const DIGEST = /^sha256:[0-9a-f]{64}$/;
+const VERSION4 = /^[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+$/;
+/** The canonical `verified.json` text: every member present, `null` where the schema allows it. */
+export function encodeRecord(record) {
+    return JSON.stringify({
+        schema: 1,
+        platform: record.platform,
+        version: record.version,
+        channel: record.channel,
+        build: record.build,
+        library: record.library,
+        library_sha256: record.librarySha256,
+        library_bytes: record.libraryBytes,
+        digests: {
+            index: record.indexDigest,
+            manifest: record.manifestDigest,
+            layer: record.layerDigest,
+            bundle: record.bundleDigest,
+            bundle_manifest: record.bundleManifestDigest,
+        },
+        signed_by: record.signedBy,
+        predicate: record.predicate,
+    });
+}
+function isObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+function nullableString(v) {
+    if (v === null)
+        return null;
+    return typeof v === 'string' ? v : undefined;
+}
+/**
+ * Accepts exactly the canonical schema-1 record. Anything else (not JSON,
+ * another schema, a missing member, a member of the wrong type, a broken
+ * rule) is `undefined`, which every caller treats as an ABSENT record —
+ * never fatal by itself and never trusted.
+ */
+export function decodeRecord(raw) {
+    let doc;
+    try {
+        doc = JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+    if (!isObject(doc))
+        return undefined;
+    for (const key of ['schema', 'platform', 'version', 'channel', 'build', 'library', 'library_sha256', 'library_bytes', 'digests', 'signed_by', 'predicate']) {
+        if (!(key in doc))
+            return undefined;
+    }
+    const digests = doc['digests'];
+    if (!isObject(digests))
+        return undefined;
+    for (const key of ['index', 'manifest', 'layer', 'bundle', 'bundle_manifest']) {
+        if (!(key in digests))
+            return undefined;
+    }
+    if (doc['schema'] !== 1)
+        return undefined;
+    const platform = doc['platform'];
+    const version = doc['version'];
+    const build = doc['build'];
+    const library = doc['library'];
+    const sha = doc['library_sha256'];
+    const bytes = doc['library_bytes'];
+    if (typeof platform !== 'string' || !PLATFORMS.some((p) => p.key === platform))
+        return undefined;
+    if (typeof version !== 'string' || !VERSION4.test(version))
+        return undefined;
+    if (typeof build !== 'string' || build === '')
+        return undefined;
+    if (typeof library !== 'string' || library === '' || library === '.' || library === '..' || library.includes('/') || library.includes('\\'))
+        return undefined;
+    if (typeof sha !== 'string' || !HEX64.test(sha))
+        return undefined;
+    if (typeof bytes !== 'number' || !Number.isInteger(bytes) || bytes < 0)
+        return undefined;
+    if (!isObject(doc['predicate']))
+        return undefined;
+    const channel = nullableString(doc['channel']);
+    const signedBy = nullableString(doc['signed_by']);
+    const index = nullableString(digests['index']);
+    const manifest = digests['manifest'];
+    const layer = digests['layer'];
+    const bundle = nullableString(digests['bundle']);
+    const bundleManifest = nullableString(digests['bundle_manifest']);
+    if (channel === undefined || signedBy === undefined || index === undefined || bundle === undefined || bundleManifest === undefined)
+        return undefined;
+    if (typeof manifest !== 'string' || !DIGEST.test(manifest) || typeof layer !== 'string' || !DIGEST.test(layer))
+        return undefined;
+    for (const d of [index, bundle, bundleManifest]) {
+        if (d !== null && !DIGEST.test(d))
+            return undefined;
+    }
+    return {
+        platform,
+        version,
+        channel,
+        build,
+        library,
+        librarySha256: sha,
+        libraryBytes: bytes,
+        indexDigest: index,
+        manifestDigest: manifest,
+        layerDigest: layer,
+        bundleDigest: bundle,
+        bundleManifestDigest: bundleManifest,
+        signedBy,
+        predicate: doc['predicate'],
+    };
+}
+/**
+ * Writes the directory's own durable proof of verification — **the source
+ * of truth for `--offline` and `resolve_installed`** (guide §6), never
+ * `index.json`. Written once, by temp-then-rename, immediately after a
+ * successful unpack; a directory with no acceptable `verified.json` is
+ * treated as unverified regardless of what `index.json` claims about it.
+ * A record that would not read back (it breaks the schema) is refused here
+ * rather than left behind as a directory no reader will trust.
+ */
+export async function writeVerifiedRecord(dir, record) {
+    const text = encodeRecord(record);
+    if (decodeRecord(text) === undefined) {
+        throw new ArtifactCorruptError(`chtypes: refusing to write a verified.json that breaks its own schema (version ${JSON.stringify(record.version)}, build ${JSON.stringify(record.build)})`);
+    }
+    const dest = path.join(dir, CACHE_VERIFIED_RECORD);
+    const tmp = await tempPathNear(dest);
+    await writeFile(tmp, text);
+    await rename(tmp, dest);
+}
+/** `undefined` when the directory has no acceptable `verified.json` (missing, unparsable, another schema, or a broken rule) — never partially trusted. */
+export async function readVerifiedRecord(dir) {
+    try {
+        return decodeRecord(await readFile(path.join(dir, CACHE_VERIFIED_RECORD), 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Every `unpacked/sha256/*` directory that carries a `verified.json` — `list_installed`'s and monotonicity's source. */
+export async function listVerified(root) {
+    const base = path.join(root, CACHE_UNPACKED_DIR);
+    let names;
+    try {
+        names = await readdir(base);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const name of names) {
+        const dir = path.join(base, name);
+        const record = await readVerifiedRecord(dir);
+        if (record !== undefined)
+            out.push({ dir, record });
+    }
+    return out;
+}
+/** A fresh, empty staging directory beside `unpacked/`, for temp-then-rename of a whole unpacked tree. */
+export async function freshStagingDir(root) {
+    const base = path.join(root, CACHE_UNPACKED_DIR);
+    await mkdir(base, { recursive: true });
+    const dir = path.join(base, `.staging-${process.pid}-${randomBytes(6).toString('hex')}`);
+    await mkdir(dir, { recursive: true });
+    return dir;
+}
+/** Renames a staged, fully-verified unpack into its final content-addressed home; removes the staging dir on any failure. */
+export async function commitStaging(stagingDir, finalDir) {
+    try {
+        await rm(finalDir, { recursive: true, force: true });
+        await rename(stagingDir, finalDir);
+    }
+    catch (err) {
+        await rm(stagingDir, { recursive: true, force: true }).catch(() => { });
+        throw err;
+    }
+}
+export async function removeStaging(stagingDir) {
+    await rm(stagingDir, { recursive: true, force: true }).catch(() => { });
+}
+//# sourceMappingURL=layout.js.map

package/dist/ocifetch/layout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"layout.js","sourceRoot":"","sources":["../../src/ocifetch/layout.ts"],"names":[],"mappings":"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"}

package/dist/ocifetch/localverify.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Verifying a pre-seeded cache entry from local blobs alone, zero network
+ * (`docs/guides/fetch-v1.md` §1, §6): "a pre-seeded layout has entries in
+ * `index.json` with no corresponding `unpacked/` directory yet; the first
+ * request for one verifies it against its signature exactly as a freshly
+ * downloaded layer would, then unpacks it." `--offline`/`resolve_installed`
+ * are the only callers — never `ensure`'s normal online path, which always
+ * has a live referrers API to ask.
+ *
+ * There is no referrers API to query here, so trust discovery is a local
+ * scan: every blob under `blobs/sha256/` that parses as an OCI manifest
+ * with the signature bundle's own `artifactType` is a *candidate* referrer
+ * of the platform manifest, tried the same way `dsse.ts`'s
+ * `verifyAnyReferrerBundle` tries referrers fetched over the network —
+ * stopping at the first whose signature verifies AND whose statement names
+ * this exact platform manifest's layer as its subject. `oras copy -r
+ * --to-oci-layout` is what populates these blobs when pulling from a real
+ * registry (guide §1); `index.json` itself carries no referrers listing (no
+ * such thing exists in the OCI image-layout spec), which is exactly why
+ * this is a scan rather than a lookup.
+ */
+import { type VerifiedRecord } from './layout.js';
+import type { PlatformKey, TrustedKey } from './types.js';
+/**
+ * Verifies and installs the platform manifest named by `manifestDigest`,
+ * reading every blob it needs from `blobsSourceDir`'s `blobs/sha256/` but
+ * always **writing** the result (the unpacked library and its
+ * `verified.json`) under `writeRoot` — the two differ for a read-only
+ * system directory (guide §1: "never written to"), where `blobsSourceDir`
+ * is that system dir and `writeRoot` is the user's own cache.
+ *
+ * Idempotent and cheap on a repeat call: if `writeRoot` already has a
+ * `verified.json` for this digest, returns it without touching
+ * `blobsSourceDir` again. Returns `undefined` (never throws) when this
+ * specific entry cannot be locally verified — a bad or incomplete
+ * pre-seeded blob is "not usable", not a hard failure for whatever broader
+ * scan is trying several candidates. The caller decides whether the
+ * resulting predicate's own `clickhouse_version` fits whatever request
+ * prompted the scan — this function verifies the entry on its own terms,
+ * not against any one request.
+ */
+export declare function verifyAndInstallFromLocalBlobs(blobsSourceDir: string, writeRoot: string, manifestDigest: string, platform: PlatformKey, trustedKeys: readonly TrustedKey[]): Promise<VerifiedRecord | undefined>;
+//# sourceMappingURL=localverify.d.ts.map

package/dist/ocifetch/localverify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"localverify.d.ts","sourceRoot":"","sources":["../../src/ocifetch/localverify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAOH,OAAO,EAQL,KAAK,cAAc,EAEpB,MAAM,aAAa,CAAC;AAErB,OAAO,KAAK,EAAqB,WAAW,EAAa,UAAU,EAAE,MAAM,YAAY,CAAC;AAIxF;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,8BAA8B,CAClD,cAAc,EAAE,MAAM,EACtB,SAAS,EAAE,MAAM,EACjB,cAAc,EAAE,MAAM,EACtB,QAAQ,EAAE,WAAW,EACrB,WAAW,EAAE,SAAS,UAAU,EAAE,GACjC,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CA2DrC"}