attention-manifest-protocol 0.4.2 → 0.4.3

package/lib/fingerprint/algorithm.js

@@ -0,0 +1,271 @@
+/**
+ * Algorithm registry and the portable SHA-256 core.
+ *
+ * Two rules shape this file. First, the algorithm is named in every reference,
+ * so the registry is the only place that knows how long a digest is: parsing,
+ * formatting and comparison ask it instead of hard-coding "64 hex characters".
+ * Second, the module must stay dependency-free and behave identically in Node
+ * and the browser, so `node:crypto` is never imported here; `sha256` is a
+ * genuine incremental FIPS 180-4 implementation over raw bytes. `src/semantic/sha256.ts`
+ * remains the string-oriented implementation used by `canonical()`; this one
+ * hashes bytes so binary content cannot be rewritten by a UTF-8 encoder.
+ *
+ * The other identifiers are registered but carry no backend in this build. That
+ * is deliberate: a reference that names `sha512` must still parse and round-trip
+ * (its digest length is a property of the algorithm, not of this build), while
+ * asking for a digest raises `UnsupportedAlgorithm` rather than silently
+ * falling back to SHA-256.
+ */
+import { FingerprintError, UnsupportedAlgorithm } from "./error.js";
+/**
+ * Declaration order is the canonical listing order; nothing in the module
+ * depends on iteration order, but diagnostics and future catalogues do.
+ */
+export const AlgorithmIds = ["sha256", "sha512", "sha3-256", "blake2b-512"];
+const Algorithms = new Map([
+    ["sha256", { id: "sha256", digestBytes: 32, backend: "portable" }],
+    ["sha512", { id: "sha512", digestBytes: 64, backend: "unavailable" }],
+    ["sha3-256", { id: "sha3-256", digestBytes: 32, backend: "unavailable" }],
+    ["blake2b-512", { id: "blake2b-512", digestBytes: 64, backend: "unavailable" }],
+]);
+/**
+ * True for a value that is one of the four registered identifiers. Used by the
+ * parsers, which must reject an unknown algorithm instead of guessing.
+ */
+export const isAlgorithmId = (value) => Algorithms.has(value);
+/**
+ * Look up a registered algorithm. A value that is syntactically fine but not
+ * registered is an `UnsupportedAlgorithm`, because at this point a hasher is
+ * required and there is nothing safe to substitute.
+ */
+export const algorithmSpec = (algorithm) => {
+    const spec = Algorithms.get(algorithm);
+    if (spec === (void 0)) {
+        throw new UnsupportedAlgorithm([`unknown algorithm "${algorithm}"; known: ${AlgorithmIds.join(", ")}`]);
+    }
+    return spec;
+};
+/**
+ * Expected lowercase-hex length of a digest for this algorithm. Both parsers
+ * use it so "wrong length" and "wrong algorithm" cannot be confused.
+ */
+export const digestHexLength = (algorithm) => algorithmSpec(algorithm).digestBytes * 2;
+const HexDigits = "0123456789abcdef";
+const HexMask = 0x0f;
+const HexShift = 4;
+/**
+ * Lowercase hex encoding. Lowercase is required by the OCI digest grammar and
+ * by every existing `sha256:` reference in this repository; emitting uppercase
+ * would create a second spelling of the same digest.
+ */
+export const bytesToHex = (bytes) => {
+    let out = "";
+    for (let index = 0; index < bytes.length; index += 1) {
+        const byte = bytes[index];
+        out += `${HexDigits[byte >>> HexShift]}${HexDigits[byte & HexMask]}`;
+    }
+    return out;
+};
+const hexDigitValue = (code) => {
+    if (code >= 0x30 && code <= 0x39) {
+        return code - 0x30;
+    }
+    return code - 0x61 + 10;
+};
+/**
+ * Decode a hex digest back to bytes. Used by the tree leaf serialisation, which
+ * has to embed a child digest as 32 raw bytes.
+ */
+export const hexToBytes = (hex) => {
+    const bytes = new Uint8Array(hex.length / 2);
+    for (let index = 0; index < bytes.length; index += 1) {
+        const offset = index * 2;
+        bytes[index] = (hexDigitValue(hex.charCodeAt(offset)) << HexShift) | hexDigitValue(hex.charCodeAt(offset + 1));
+    }
+    return bytes;
+};
+/**
+ * Strict lowercase-hex check. Uppercase is rejected rather than folded, because
+ * `sha256:AB...` and `sha256:ab...` are different strings and a parser that
+ * accepts both silently creates two names for one digest.
+ */
+export const isLowerHex = (text, length) => {
+    if (text.length !== length) {
+        return false;
+    }
+    for (let index = 0; index < text.length; index += 1) {
+        const code = text.charCodeAt(index);
+        const digit = (code >= 0x30 && code <= 0x39) || (code >= 0x61 && code <= 0x66);
+        if (!digit) {
+            return false;
+        }
+    }
+    return true;
+};
+const Sha256InitialState = [0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19];
+const Sha256RoundConstants = new Uint32Array([
+    0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5, 0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74,
+    0x80deb1fe, 0x9bdc06a7, 0xc19bf174, 0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da, 0x983e5152, 0xa831c66d,
+    0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967, 0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e,
+    0x92722c85, 0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070, 0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5,
+    0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3, 0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+]);
+const WordCount = 64;
+const BlockBytes = 64;
+const DigestBytes = 32;
+const PaddingBoundary = 56;
+const HighBitDivisor = 0x20000000;
+const rotr = (value, shift) => ((value >>> shift) | (value << (32 - shift))) >>> 0;
+/**
+ * The FIPS 180-4 compression function for one 64-byte block.
+ *
+ * `words` is caller-provided scratch space so an incremental hasher does not
+ * allocate 64 words per block; `src/semantic/sha256.ts` keeps the same loop but
+ * reads from a padded copy of the whole input, which is exactly the 2x memory
+ * cost this module cannot afford for streamed files.
+ */
+const compressBlock = (state, block, words) => {
+    for (let index = 0; index < 16; index += 1) {
+        const offset = index * 4;
+        words[index] = ((block[offset] << 24) | (block[offset + 1] << 16) | (block[offset + 2] << 8) | block[offset + 3]) >>> 0;
+    }
+    for (let index = 16; index < WordCount; index += 1) {
+        const s0 = rotr(words[index - 15], 7) ^ rotr(words[index - 15], 18) ^ (words[index - 15] >>> 3);
+        const s1 = rotr(words[index - 2], 17) ^ rotr(words[index - 2], 19) ^ (words[index - 2] >>> 10);
+        words[index] = (words[index - 16] + s0 + words[index - 7] + s1) >>> 0;
+    }
+    let a = state[0];
+    let b = state[1];
+    let c = state[2];
+    let d = state[3];
+    let e = state[4];
+    let f = state[5];
+    let g = state[6];
+    let h = state[7];
+    for (let index = 0; index < WordCount; index += 1) {
+        const sigma1 = rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25);
+        const choose = (e & f) ^ (~e & g);
+        const temp1 = (h + sigma1 + choose + Sha256RoundConstants[index] + words[index]) >>> 0;
+        const sigma0 = rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22);
+        const majority = (a & b) ^ (a & c) ^ (b & c);
+        const temp2 = (sigma0 + majority) >>> 0;
+        h = g;
+        g = f;
+        f = e;
+        e = (d + temp1) >>> 0;
+        d = c;
+        c = b;
+        b = a;
+        a = (temp1 + temp2) >>> 0;
+    }
+    state[0] = (state[0] + a) >>> 0;
+    state[1] = (state[1] + b) >>> 0;
+    state[2] = (state[2] + c) >>> 0;
+    state[3] = (state[3] + d) >>> 0;
+    state[4] = (state[4] + e) >>> 0;
+    state[5] = (state[5] + f) >>> 0;
+    state[6] = (state[6] + g) >>> 0;
+    state[7] = (state[7] + h) >>> 0;
+};
+/**
+ * Portable incremental SHA-256 over raw bytes.
+ *
+ * The implementation tracks the total byte count separately from the buffered
+ * block because the FIPS padding needs the input length in bits; computing the
+ * final eight bytes from `totalBytes` (high = bits >> 32, low = low 32 bits)
+ * avoids the overflow a 32-bit byte counter would hit at 512 MiB.
+ */
+export const createSha256 = () => {
+    const state = new Uint32Array(Sha256InitialState);
+    const block = new Uint8Array(BlockBytes);
+    const words = new Uint32Array(WordCount);
+    let blockLength = 0;
+    let totalBytes = 0;
+    let finished = false;
+    const hasher = {
+        update: (bytes) => {
+            if (finished) {
+                throw new FingerprintError("hasher_finished", ["sha256 hasher already finalised; digest() is single-shot"]);
+            }
+            if (!(bytes instanceof Uint8Array)) {
+                throw new TypeError(`sha256 hasher accepts Uint8Array, received ${typeof (bytes)}`);
+            }
+            totalBytes += bytes.length;
+            let offset = 0;
+            if (blockLength > 0) {
+                const taken = Math.min(BlockBytes - blockLength, bytes.length);
+                block.set(bytes.subarray(0, taken), blockLength);
+                blockLength += taken;
+                offset += taken;
+                if (blockLength === BlockBytes) {
+                    compressBlock(state, block, words);
+                    blockLength = 0;
+                }
+            }
+            while (offset + BlockBytes <= bytes.length) {
+                compressBlock(state, bytes.subarray(offset, offset + BlockBytes), words);
+                offset += BlockBytes;
+            }
+            if (offset < bytes.length) {
+                block.set(bytes.subarray(offset), 0);
+                blockLength = bytes.length - offset;
+            }
+            return hasher;
+        },
+        digest: () => {
+            if (finished) {
+                throw new FingerprintError("hasher_finished", ["sha256 hasher already finalised; digest() is single-shot"]);
+            }
+            finished = true;
+            const tail = new Uint8Array(blockLength < PaddingBoundary ? BlockBytes : BlockBytes * 2);
+            tail.set(block.subarray(0, blockLength));
+            tail[blockLength] = 0x80;
+            const highBits = Math.floor(totalBytes / HighBitDivisor);
+            const lowBits = (totalBytes % HighBitDivisor) * 8;
+            const view = new DataView(tail.buffer);
+            view.setUint32(tail.length - 8, highBits);
+            view.setUint32(tail.length - 4, lowBits);
+            for (let offset = 0; offset < tail.length; offset += BlockBytes) {
+                compressBlock(state, tail.subarray(offset, offset + BlockBytes), words);
+            }
+            const digest = new Uint8Array(DigestBytes);
+            const digestView = new DataView(digest.buffer);
+            for (let index = 0; index < DigestBytes / 4; index += 1) {
+                digestView.setUint32(index * 4, state[index]);
+            }
+            return digest;
+        },
+    };
+    return hasher;
+};
+/**
+ * One-shot SHA-256 over raw bytes. Thin wrapper so call sites do not repeat the
+ * create/update/digest sequence and cannot forget the update.
+ */
+export const sha256Bytes = (bytes) => createSha256().update(bytes).digest();
+/**
+ * Fail closed unless this build can actually compute the named algorithm.
+ *
+ * The registry must answer before any payload is touched: a caller that gets a
+ * hasher is entitled to assume the algorithm in the reference is the algorithm
+ * that ran. The same guard is called by the file layer before it opens a file,
+ * so an unsupported algorithm fails without a pointless read instead of after
+ * the work has already been done.
+ */
+export const assertBackend = (algorithm) => {
+    const spec = algorithmSpec(algorithm);
+    if (spec.backend !== "portable" || spec.id !== "sha256") {
+        throw new UnsupportedAlgorithm([`algorithm "${algorithm}" has no backend in this dependency-free build; only sha256 is available`]);
+    }
+    return spec;
+};
+/**
+ * Construct a hasher for any registered algorithm, or fail closed.
+ *
+ * Kept as a thin wrapper over `assertBackend` so the availability rule lives in
+ * exactly one place.
+ */
+export const createHasher = (algorithm) => {
+    assertBackend(algorithm);
+    return createSha256();
+};

package/lib/fingerprint/bytes.d.ts

@@ -0,0 +1,18 @@
+import type { AlgorithmId } from "./algorithm.js";
+import type { Fingerprint } from "./preimage.js";
+/**
+ * Option shape for `fingerprintBytes`. SHA-256 is the only backend in this
+ * build; the other registered ids raise `UnsupportedAlgorithm` rather than
+ * falling back silently.
+ */
+export interface BytesFingerprintOptions {
+    readonly algorithm?: AlgorithmId;
+}
+/**
+ * Fingerprint a byte sequence under the `bytes/raw` policy.
+ *
+ * The `bytes` field of the returned reference is the exact payload length, and
+ * `digest` is the CAS-compatible `sha256:<hex>` spelling so callers can keep
+ * storing it in the existing content stores unchanged.
+ */
+export declare const fingerprintBytes: (bytes: Uint8Array, options?: BytesFingerprintOptions) => Fingerprint;

package/lib/fingerprint/bytes.js

@@ -0,0 +1,31 @@
+/**
+ * Raw byte fingerprints.
+ *
+ * This is the primitive every other content kind reduces to: text, JSON and
+ * files all end up as a `Uint8Array` and then as a header plus payload. Its one
+ * rule is that the bytes are hashed exactly as given 鈥?no decoding, no newline
+ * folding, no charset guessing. That is what makes `0x80` and `0x81` different
+ * fingerprints, which the legacy `readFile(path, "utf8")` path got wrong (both
+ * decode to U+FFFD and collided).
+ */
+import { isAlgorithmId } from "./algorithm.js";
+import { UnsupportedAlgorithm } from "./error.js";
+import { Policy } from "./policy.js";
+import { fingerprintPayload } from "./preimage.js";
+/**
+ * Fingerprint a byte sequence under the `bytes/raw` policy.
+ *
+ * The `bytes` field of the returned reference is the exact payload length, and
+ * `digest` is the CAS-compatible `sha256:<hex>` spelling so callers can keep
+ * storing it in the existing content stores unchanged.
+ */
+export const fingerprintBytes = (bytes, options) => {
+    if (!(bytes instanceof Uint8Array)) {
+        throw new TypeError(`fingerprintBytes expects a Uint8Array, received ${typeof (bytes)}`);
+    }
+    const algorithm = options?.algorithm ?? "sha256";
+    if (!isAlgorithmId(algorithm)) {
+        throw new UnsupportedAlgorithm([`unknown algorithm "${algorithm}"; known: sha256, sha512, sha3-256, blake2b-512`]);
+    }
+    return fingerprintPayload(algorithm, "bytes", Policy.bytesRaw, bytes);
+};

package/lib/fingerprint/error.d.ts

@@ -0,0 +1,73 @@
+/**
+ * The failure taxonomy of the fingerprint module.
+ *
+ * A caller has to be able to tell four situations apart: the algorithm is not
+ * available in this build, the kind is outside the frozen set, the chosen
+ * policy refused the input, or a comparison failed. Treating them as one
+ * generic error forces the caller either to swallow an integrity failure or to
+ * retry a permanent bug, so the code is part of the contract and not just a
+ * diagnostic string. The base class mirrors `src/error/ampError.ts`: one
+ * machine-readable code plus every problem found in the same attempt.
+ */
+import { AmpError } from "../error/ampError.js";
+/**
+ * Stable machine-readable reasons; callers may switch on these.
+ */
+export type FingerprintErrorCode = "unsupported_algorithm" | "unsupported_kind" | "unsupported_policy" | "normalization_rejected" | "fingerprint_mismatch" | "fingerprint_io_error" | "invalid_ref" | "hasher_finished";
+/**
+ * Base class for every rejection this module raises.
+ *
+ * `problems` is plural because one input can violate several rules at once and
+ * a caller should see all of them, exactly like the boundary rejections in
+ * `src/error/boundaryRejection.ts`. The `name` parameter exists only so the
+ * subclasses below can keep `error.name` useful when they call `super`.
+ */
+export declare class FingerprintError extends AmpError {
+    constructor(code: FingerprintErrorCode, problems: readonly string[], name?: string);
+}
+/**
+ * The algorithm id is not registered, or it is registered but this build has no
+ * backend for it. Never downgraded to SHA-256: a silent fallback would make the
+ * algorithm name in the reference a lie.
+ */
+export declare class UnsupportedAlgorithm extends FingerprintError {
+    constructor(problems: readonly string[]);
+}
+/**
+ * The kind is outside the frozen `FingerprintKind` set, so no preimage header
+ * could be built without inventing a field the verifier does not know.
+ */
+export declare class UnsupportedKind extends FingerprintError {
+    constructor(problems: readonly string[]);
+}
+/**
+ * A policy refused the input: a lone surrogate, `-0`, a non-finite number,
+ * invalid UTF-8, a NUL inside `text`. Retrying with the same arguments cannot
+ * succeed, which is what separates this from an I/O failure.
+ */
+export declare class NormalizationRejected extends FingerprintError {
+    constructor(problems: readonly string[]);
+}
+/**
+ * Two references that should describe the same value do not. Both references
+ * are in the message because a bare "digest mismatch" cannot be debugged from
+ * a log line.
+ */
+export declare class FingerprintMismatch extends FingerprintError {
+    constructor(problems: readonly string[]);
+}
+/**
+ * The file system refused the read: missing path, directory where a file was
+ * expected, a symlink the caller may not follow, or a file that changed size
+ * while it was being streamed.
+ */
+export declare class FingerprintIOError extends FingerprintError {
+    constructor(problems: readonly string[]);
+}
+/**
+ * Render an unknown thrown value for a diagnostic. `String(error)` is avoided
+ * on purpose: it turns a thrown object into `[object Object]`, while the
+ * `message` of a Node system error (`ENOENT: no such file ...`) is the part a
+ * human needs.
+ */
+export declare const describeError: (error: unknown) => string;

package/lib/fingerprint/error.js

@@ -0,0 +1,86 @@
+/**
+ * The failure taxonomy of the fingerprint module.
+ *
+ * A caller has to be able to tell four situations apart: the algorithm is not
+ * available in this build, the kind is outside the frozen set, the chosen
+ * policy refused the input, or a comparison failed. Treating them as one
+ * generic error forces the caller either to swallow an integrity failure or to
+ * retry a permanent bug, so the code is part of the contract and not just a
+ * diagnostic string. The base class mirrors `src/error/ampError.ts`: one
+ * machine-readable code plus every problem found in the same attempt.
+ */
+import { AmpError } from "../error/ampError.js";
+/**
+ * Base class for every rejection this module raises.
+ *
+ * `problems` is plural because one input can violate several rules at once and
+ * a caller should see all of them, exactly like the boundary rejections in
+ * `src/error/boundaryRejection.ts`. The `name` parameter exists only so the
+ * subclasses below can keep `error.name` useful when they call `super`.
+ */
+export class FingerprintError extends AmpError {
+    constructor(code, problems, name = "FingerprintError") {
+        super(name, code, problems);
+    }
+}
+/**
+ * The algorithm id is not registered, or it is registered but this build has no
+ * backend for it. Never downgraded to SHA-256: a silent fallback would make the
+ * algorithm name in the reference a lie.
+ */
+export class UnsupportedAlgorithm extends FingerprintError {
+    constructor(problems) {
+        super("unsupported_algorithm", problems, "UnsupportedAlgorithm");
+    }
+}
+/**
+ * The kind is outside the frozen `FingerprintKind` set, so no preimage header
+ * could be built without inventing a field the verifier does not know.
+ */
+export class UnsupportedKind extends FingerprintError {
+    constructor(problems) {
+        super("unsupported_kind", problems, "UnsupportedKind");
+    }
+}
+/**
+ * A policy refused the input: a lone surrogate, `-0`, a non-finite number,
+ * invalid UTF-8, a NUL inside `text`. Retrying with the same arguments cannot
+ * succeed, which is what separates this from an I/O failure.
+ */
+export class NormalizationRejected extends FingerprintError {
+    constructor(problems) {
+        super("normalization_rejected", problems, "NormalizationRejected");
+    }
+}
+/**
+ * Two references that should describe the same value do not. Both references
+ * are in the message because a bare "digest mismatch" cannot be debugged from
+ * a log line.
+ */
+export class FingerprintMismatch extends FingerprintError {
+    constructor(problems) {
+        super("fingerprint_mismatch", problems, "FingerprintMismatch");
+    }
+}
+/**
+ * The file system refused the read: missing path, directory where a file was
+ * expected, a symlink the caller may not follow, or a file that changed size
+ * while it was being streamed.
+ */
+export class FingerprintIOError extends FingerprintError {
+    constructor(problems) {
+        super("fingerprint_io_error", problems, "FingerprintIOError");
+    }
+}
+/**
+ * Render an unknown thrown value for a diagnostic. `String(error)` is avoided
+ * on purpose: it turns a thrown object into `[object Object]`, while the
+ * `message` of a Node system error (`ENOENT: no such file ...`) is the part a
+ * human needs.
+ */
+export const describeError = (error) => {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return `${error}`;
+};

package/lib/fingerprint/file.d.ts

@@ -0,0 +1,71 @@
+import type { AlgorithmId } from "./algorithm.js";
+import type { Fingerprint } from "./preimage.js";
+/**
+ * How the octets are turned into a payload. `bytes` hashes them verbatim;
+ * `text` decodes strictly, then applies `text/utf8+nfc+lf`, so a line-ending or
+ * BOM change does not change the digest while invalid UTF-8 does.
+ */
+export type FileFingerprintMode = "bytes" | "text";
+/**
+ * Option shape for `fingerprintFile`.
+ *
+ * `chunkBytes` exists for tests and for callers that already read in a fixed
+ * block size; it must not change the digest, which the check verifies with 1,
+ * 7 and 1 MiB chunks.
+ */
+export interface FileFingerprintOptions {
+    readonly algorithm?: AlgorithmId;
+    readonly mode?: FileFingerprintMode;
+    readonly chunkBytes?: number;
+}
+/**
+ * A file fingerprint plus the on-disk size.
+ *
+ * `size` is the file's byte length; `ref.bytes` is the payload that was hashed.
+ * They are equal for `mode: "bytes"` and differ for `mode: "text"` when
+ * normalisation changes the UTF-8 length (for example, CRLF folding), which is
+ * why both numbers are reported instead of one.
+ */
+export interface FileFingerprint extends Fingerprint {
+    readonly size: number;
+}
+/**
+ * Validate the chunk size once, in one place, so a zero or negative value fails
+ * before a file is opened instead of producing an infinite loop of zero-byte
+ * reads.
+ */
+export declare const resolveChunkBytes: (value: number | undefined) => number;
+/**
+ * Fingerprint a file's content.
+ *
+ * `mode: "bytes"` hashes the octets (`file/bytes+chunked`). `mode: "text"`
+ * decodes strictly, applies the `text/utf8+nfc+lf` normalisation and hashes the
+ * re-encoded payload (`file/text+nfc`); invalid UTF-8 is `NormalizationRejected`,
+ * never U+FFFD. Text mode has to hold the decoded string because Unicode
+ * normalisation can join characters across chunk boundaries; the read itself is
+ * still streamed, and the payload is only re-encoded once.
+ */
+export declare const fingerprintFile: (path: string, options?: FileFingerprintOptions) => Promise<FileFingerprint>;
+/**
+ * Weak change-detection fingerprint of a file's metadata: `size\0mtimeNs`.
+ *
+ * This is **not an integrity fingerprint**. It cannot distinguish two files of
+ * the same size and the same nanosecond mtime, it says nothing about content,
+ * and both fields are attacker-controlled (a caller can set mtime with
+ * `utimes`). It exists for cache invalidation and "did this path change since
+ * the last sweep" decisions; use `fingerprintFile` when the question is whether
+ * the content is the same. It follows symlinks, unlike the content
+ * fingerprints, because it describes the object a path currently resolves to.
+ *
+ * The `bytes` field counts the metadata payload, not the file size —the file
+ * size is embedded verbatim in the payload (`size\0mtimeNs`) so a reader can
+ * recover it from the preimage description.
+ */
+export declare const fingerprintFileMeta: (path: string) => Promise<Fingerprint>;
+/**
+ * Content digest of a regular file as bare lowercase hex, with no preimage
+ * header. Used by `tree.ts`, whose leaf serialisation embeds a child digest as
+ * 32 raw bytes; the file's own type and mode are bound by the leaf, so a second
+ * header here would only add a field the tree format does not define.
+ */
+export declare const fileContentDigest: (path: string, expectedSize: number, chunkBytes: number) => string;