knodin 0.8.3 → 0.8.5

package/dist/src/shared-index/cache.js

@@ -0,0 +1,267 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { SharedIndexError } from "./s3-client.js";
+const DIGEST = /^[a-f0-9]{64}$/;
+const CACHE_FILE = "graph.sqlite.zst";
+function assertDigest(digest) {
+    if (!DIGEST.test(digest))
+        throw new SharedIndexError("integrity", "shared-index cache digest is invalid");
+}
+function hashFile(target) {
+    const hash = crypto.createHash("sha256");
+    const descriptor = fs.openSync(target, "r");
+    const buffer = Buffer.allocUnsafe(1024 * 1024);
+    try {
+        let bytes = 0;
+        do {
+            bytes = fs.readSync(descriptor, buffer, 0, buffer.byteLength, null);
+            if (bytes > 0)
+                hash.update(buffer.subarray(0, bytes));
+        } while (bytes > 0);
+    }
+    finally {
+        fs.closeSync(descriptor);
+    }
+    return hash.digest("hex");
+}
+function writeAll(descriptor, bytes) {
+    let offset = 0;
+    while (offset < bytes.byteLength)
+        offset += fs.writeSync(descriptor, bytes, offset, bytes.byteLength - offset);
+}
+function fsyncDirectory(target) {
+    try {
+        const descriptor = fs.openSync(target, "r");
+        try {
+            fs.fsyncSync(descriptor);
+        }
+        finally {
+            fs.closeSync(descriptor);
+        }
+    }
+    catch (error) {
+        if (process.platform !== "win32")
+            throw error;
+    }
+}
+function processExists(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+function removeStaleLeases(directory) {
+    if (!fs.existsSync(directory))
+        return;
+    for (const name of fs.readdirSync(directory)) {
+        const match = /^\.lease-(\d+)-/.exec(name);
+        if (match && !processExists(Number(match[1])))
+            fs.rmSync(path.join(directory, name), { force: true });
+    }
+}
+function isLeased(directory) {
+    removeStaleLeases(directory);
+    return (fs.existsSync(directory) && fs.readdirSync(directory).some((name) => name.startsWith(".lease-")));
+}
+function wait(milliseconds, signal) {
+    return new Promise((resolve, reject) => {
+        const finish = () => {
+            signal?.removeEventListener("abort", abort);
+            resolve();
+        };
+        const timer = setTimeout(finish, milliseconds);
+        const abort = () => {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", abort);
+            reject(new SharedIndexError("timeout", "shared-index cache wait was cancelled"));
+        };
+        if (signal?.aborted)
+            abort();
+        else
+            signal?.addEventListener("abort", abort, { once: true });
+    });
+}
+export class SharedIndexCache {
+    root;
+    maxEntries;
+    maxBytes;
+    lockTimeoutMs;
+    constructor(policy = {}) {
+        this.root = path.resolve(policy.root ?? path.join(os.homedir(), ".knodin", "shared-index-cache", "v1", "sha256"));
+        this.maxEntries = policy.maxEntries ?? 32;
+        this.maxBytes = policy.maxBytes ?? 32 * 1024 ** 3;
+        this.lockTimeoutMs = policy.lockTimeoutMs ?? 30_000;
+        if (!Number.isSafeInteger(this.maxEntries) ||
+            this.maxEntries < 1 ||
+            !Number.isSafeInteger(this.maxBytes) ||
+            this.maxBytes < 1 ||
+            !Number.isSafeInteger(this.lockTimeoutMs) ||
+            this.lockTimeoutMs < 1)
+            throw new SharedIndexError("configuration", "shared-index cache policy is invalid");
+        fs.mkdirSync(this.root, { recursive: true, mode: 0o700 });
+        if (fs.lstatSync(this.root).isSymbolicLink() || !fs.lstatSync(this.root).isDirectory())
+            throw new SharedIndexError("configuration", "shared-index cache root is not a private directory");
+        fs.chmodSync(this.root, 0o700);
+    }
+    entry(digest) {
+        assertDigest(digest);
+        const directory = path.join(this.root, digest);
+        const file = path.join(directory, CACHE_FILE);
+        const stat = fs.existsSync(file) ? fs.statSync(file) : undefined;
+        return {
+            digest,
+            directory,
+            file,
+            bytes: stat?.size ?? 0,
+            accessedAt: Math.max(stat?.atimeMs ?? 0, stat?.mtimeMs ?? 0),
+        };
+    }
+    async lock(digest, signal) {
+        const target = path.join(this.root, `.${digest}.lock`);
+        const deadline = Date.now() + this.lockTimeoutMs;
+        while (true) {
+            try {
+                const descriptor = fs.openSync(target, "wx", 0o600);
+                fs.writeFileSync(descriptor, `${process.pid}\n${Date.now()}\n`);
+                fs.closeSync(descriptor);
+                return () => fs.rmSync(target, { force: true });
+            }
+            catch (error) {
+                if (error.code !== "EEXIST")
+                    throw error;
+                try {
+                    const [pidText, createdText] = fs.readFileSync(target, "utf8").split("\n");
+                    if (Date.now() - Number(createdText) > this.lockTimeoutMs &&
+                        !processExists(Number(pidText))) {
+                        fs.rmSync(target, { force: true });
+                        continue;
+                    }
+                }
+                catch {
+                    // The lock owner may be replacing or releasing it; retry within the bound.
+                }
+                if (Date.now() >= deadline)
+                    throw new SharedIndexError("timeout", "shared-index cache lock timed out");
+                await wait(50, signal);
+            }
+        }
+    }
+    valid(entry, expectedBytes, expectedDigest) {
+        if (!fs.existsSync(entry.directory))
+            return false;
+        const directory = fs.lstatSync(entry.directory);
+        if (!directory.isDirectory() || directory.isSymbolicLink())
+            return false;
+        if (!fs.existsSync(entry.file))
+            return false;
+        const stat = fs.lstatSync(entry.file);
+        if (!stat.isFile() ||
+            stat.isSymbolicLink() ||
+            stat.size !== expectedBytes ||
+            (stat.mode & 0o777) !== 0o400)
+            return false;
+        return hashFile(entry.file) === expectedDigest;
+    }
+    lease(entry, state) {
+        const marker = path.join(entry.directory, `.lease-${process.pid}-${crypto.randomUUID()}`);
+        fs.writeFileSync(marker, "", { flag: "wx", mode: 0o600 });
+        const now = new Date();
+        fs.utimesSync(entry.file, now, now);
+        let released = false;
+        return {
+            path: entry.file,
+            state,
+            release: () => {
+                if (released)
+                    return;
+                released = true;
+                fs.rmSync(marker, { force: true });
+                this.evict();
+            },
+        };
+    }
+    entries() {
+        return fs
+            .readdirSync(this.root, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory() && DIGEST.test(entry.name))
+            .map((entry) => this.entry(entry.name))
+            .filter((entry) => fs.existsSync(entry.file));
+    }
+    evict() {
+        const entries = this.entries().sort((left, right) => left.accessedAt - right.accessedAt);
+        let bytes = entries.reduce((total, entry) => total + entry.bytes, 0);
+        let count = entries.length;
+        for (const entry of entries) {
+            if (count <= this.maxEntries && bytes <= this.maxBytes)
+                break;
+            if (isLeased(entry.directory) || fs.existsSync(path.join(this.root, `.${entry.digest}.lock`)))
+                continue;
+            fs.rmSync(entry.directory, { recursive: true, force: true });
+            count -= 1;
+            bytes -= entry.bytes;
+        }
+    }
+    async acquire(store, manifest, signal) {
+        const digest = manifest.graph.compressedSha256;
+        const expectedBytes = manifest.graph.compressedBytes;
+        if (expectedBytes > this.maxBytes)
+            throw new SharedIndexError("configuration", "shared-index artifact exceeds the configured cache-size bound");
+        const entry = this.entry(digest);
+        const unlock = await this.lock(digest, signal);
+        try {
+            const corrupt = fs.existsSync(entry.file);
+            if (this.valid(entry, expectedBytes, digest))
+                return this.lease(entry, "hit");
+            if (corrupt && isLeased(entry.directory))
+                throw new SharedIndexError("unavailable", "shared-index corrupt cache entry is currently leased");
+            if (fs.existsSync(entry.directory))
+                fs.rmSync(entry.directory, { recursive: true, force: true });
+            fs.mkdirSync(entry.directory, { recursive: true, mode: 0o700 });
+            const metadata = await store.head(manifest.graph.key, { signal });
+            if (metadata.bytes !== expectedBytes)
+                throw new SharedIndexError("integrity", "shared-index compressed object size does not match manifest");
+            const temporary = path.join(entry.directory, `.download-${crypto.randomUUID()}.tmp`);
+            try {
+                const source = await store.get(manifest.graph.key, { maxBytes: expectedBytes, signal });
+                const descriptor = fs.openSync(temporary, "wx", 0o600);
+                const hash = crypto.createHash("sha256");
+                let received = 0;
+                try {
+                    for await (const chunk of source) {
+                        const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+                        received += bytes.byteLength;
+                        if (received > expectedBytes)
+                            throw new SharedIndexError("integrity", "shared-index compressed object exceeded manifest size");
+                        hash.update(bytes);
+                        writeAll(descriptor, bytes);
+                    }
+                    fs.fsyncSync(descriptor);
+                }
+                finally {
+                    fs.closeSync(descriptor);
+                }
+                if (received !== expectedBytes || hash.digest("hex") !== digest)
+                    throw new SharedIndexError("integrity", "shared-index compressed object failed size or digest verification");
+                fs.chmodSync(temporary, 0o400);
+                fs.renameSync(temporary, entry.file);
+                fsyncDirectory(entry.directory);
+                const state = corrupt ? "corrupt-refetched" : "downloaded";
+                const lease = this.lease(this.entry(digest), state);
+                this.evict();
+                return lease;
+            }
+            catch (error) {
+                fs.rmSync(temporary, { force: true });
+                throw error;
+            }
+        }
+        finally {
+            unlock();
+        }
+    }
+}

package/dist/src/shared-index/compatibility.js

@@ -0,0 +1,70 @@
+import fs from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { EMBEDDING_DIMENSIONS, EMBEDDING_MODEL_ID, EMBEDDING_MODEL_REVISION, } from "../engine/embeddings.js";
+import { KNODIN_SCHEMA_VERSION } from "../engine/index.js";
+import { prunePolicyDescriptor } from "../engine/prune.js";
+import { KNODIN_VERSION } from "../version.js";
+import { canonicalManifestBytes, sha256Hex } from "./contract.js";
+const require = createRequire(import.meta.url);
+function packageVersion(name) {
+    try {
+        return require(`${name}/package.json`).version;
+    }
+    catch {
+        let current = path.dirname(fileURLToPath(import.meta.url));
+        try {
+            current = path.dirname(require.resolve(name));
+        }
+        catch {
+            throw new Error(`cannot resolve compatibility dependency ${name}`);
+        }
+        for (;;) {
+            const manifest = path.join(current, "package.json");
+            if (fs.existsSync(manifest)) {
+                const value = JSON.parse(fs.readFileSync(manifest, "utf8"));
+                if (value.name === name && value.version)
+                    return value.version;
+            }
+            const parent = path.dirname(current);
+            if (parent === current)
+                break;
+            current = parent;
+        }
+        throw new Error(`cannot read compatibility dependency ${name}`);
+    }
+}
+function digest(value) {
+    return sha256Hex(canonicalManifestBytes(value));
+}
+/** One implementation used by client verification and publisher metadata. */
+export function currentSharedIndexCompatibility() {
+    const model = {
+        id: EMBEDDING_MODEL_ID,
+        revision: EMBEDDING_MODEL_REVISION,
+        dimensions: EMBEDDING_DIMENSIONS,
+        runtime: `@huggingface/transformers@${packageVersion("@huggingface/transformers")}`,
+    };
+    const parsers = {
+        policyVersion: 1,
+        packages: {
+            "tree-sitter-wasms": packageVersion("tree-sitter-wasms"),
+            "web-tree-sitter": packageVersion("web-tree-sitter"),
+            "web-tree-sitter-sfapex": packageVersion("web-tree-sitter-sfapex"),
+        },
+    };
+    return {
+        knodinVersion: KNODIN_VERSION,
+        databaseSchemaVersion: KNODIN_SCHEMA_VERSION,
+        modelId: EMBEDDING_MODEL_ID,
+        modelDigest: digest(model),
+        parserBundleDigest: digest(parsers),
+        indexConfigDigest: digest({
+            policyVersion: 1,
+            databaseSchemaVersion: KNODIN_SCHEMA_VERSION,
+            embeddingDimensions: EMBEDDING_DIMENSIONS,
+        }),
+        prunePolicyDigest: digest(prunePolicyDescriptor()),
+    };
+}

package/dist/src/shared-index/config.js

@@ -0,0 +1,224 @@
+import child_process from "node:child_process";
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { parseDocument, stringify } from "yaml";
+import { z } from "zod";
+import { canonicalRepositoryIdentity, sharedBranchMatches, } from "./contract.js";
+export const SHARED_INDEX_CONFIG_PATH = ".knodin/shared-index.yaml";
+const repositorySchema = z
+    .object({
+    host: z.string().min(1).max(253),
+    owner: z.string().min(1).max(255),
+    name: z.string().min(1).max(255),
+})
+    .strict();
+const canonicalHost = /^(?!.*\.\.)(?!.*(?:^|\.)-)(?!.*-(?:\.|$))[a-z0-9](?:[a-z0-9.-]{0,251}[a-z0-9])?$/;
+const canonicalOwner = /^[a-z0-9](?:[a-z0-9-]{0,253}[a-z0-9])?$/;
+const canonicalName = /^[a-z0-9](?:[a-z0-9._-]{0,253}[a-z0-9])?$/;
+const configSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    enabled: z.boolean(),
+    registrationId: z.string().regex(/^[a-z0-9][a-z0-9._-]{0,127}$/),
+    aws: z
+        .object({
+        region: z.string().regex(/^[a-z]{2}(?:-gov)?-[a-z]+-\d$/),
+        bucket: z
+            .string()
+            .regex(/^(?!xn--)(?!.*\.\.)(?!.*\.-)(?!.*-\.)(?!\d{1,3}(?:\.\d{1,3}){3}$)[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]$/),
+    })
+        .strict(),
+    repository: repositorySchema,
+    branches: z.array(z.string().min(1).max(255)).min(1).max(64),
+    signing: z
+        .object({
+        algorithm: z.literal("RSASSA_PSS_SHA_256"),
+        keyId: z
+            .string()
+            .max(2048)
+            .regex(/^(?:arn:(?:aws|aws-us-gov|aws-cn):kms:[a-z0-9-]+:\d{12}:(?:key\/[A-Za-z0-9-]+|alias\/[A-Za-z0-9/_+=,.@-]+)|alias\/[A-Za-z0-9/_+=,.@-]+)$/),
+        publicKeySha256: z.string().regex(/^[a-f0-9]{64}$/),
+        publicKeyPem: z.string().min(1).max(16_384),
+    })
+        .strict(),
+})
+    .strict();
+function boundedError(error) {
+    if (error instanceof z.ZodError)
+        return error.issues
+            .slice(0, 16)
+            .map((issue) => `${issue.path.join(".") || "config"}: ${issue.message}`)
+            .join("; ");
+    if (error instanceof Error)
+        return error.message.slice(0, 512);
+    return "invalid shared-index configuration";
+}
+function validateBranchPattern(pattern) {
+    if (pattern.startsWith("/") ||
+        pattern.endsWith("/") ||
+        pattern.includes("//") ||
+        pattern.includes("..") ||
+        pattern.includes("@{") ||
+        /[~^:?[\\]/.test(pattern))
+        return false;
+    const stars = [...pattern].filter((character) => character === "*").length;
+    return stars === 0 || (stars === 1 && pattern.endsWith("/*"));
+}
+export function publicKeyFingerprint(publicKeyPem) {
+    const key = crypto.createPublicKey(publicKeyPem);
+    if (key.asymmetricKeyType !== "rsa" && key.asymmetricKeyType !== "rsa-pss")
+        throw new Error("signing public key must be RSA");
+    const bits = key.asymmetricKeyDetails?.modulusLength;
+    if (!bits || bits < 2048 || bits > 8192)
+        throw new Error("signing RSA public key must have a 2048-8192 bit modulus");
+    const der = key.export({ type: "spki", format: "der" });
+    return crypto.createHash("sha256").update(der).digest("hex");
+}
+function parseRemote(remote) {
+    const trimmed = remote.trim();
+    let host;
+    let pathname;
+    try {
+        if (/^[^@/\s]+@[^:/\s]+:.+$/.test(trimmed)) {
+            const match = /^[^@/\s]+@([^:/\s]+):(.+)$/.exec(trimmed);
+            if (!match)
+                return null;
+            host = match[1];
+            pathname = match[2];
+        }
+        else {
+            const parsed = new URL(trimmed);
+            host = parsed.hostname;
+            pathname = parsed.pathname.replace(/^\//, "");
+        }
+    }
+    catch {
+        return null;
+    }
+    const segments = pathname.split("/").filter(Boolean);
+    if (segments.length !== 2)
+        return null;
+    return canonicalRepositoryIdentity({ host, owner: segments[0], name: segments[1] });
+}
+export function repositoryRemoteIdentities(repo) {
+    let output;
+    try {
+        output = child_process.execFileSync("git", ["remote", "-v"], {
+            cwd: repo,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+    }
+    catch {
+        return [];
+    }
+    const identities = new Map();
+    for (const line of output.split("\n")) {
+        const remote = line.trim().split(/\s+/)[1];
+        if (!remote)
+            continue;
+        const identity = parseRemote(remote);
+        if (!identity)
+            continue;
+        identities.set(`${identity.host}/${identity.owner}/${identity.name}`, identity);
+    }
+    return [...identities.values()];
+}
+export function validateSharedIndexConfig(value, repo) {
+    const parsed = configSchema.parse(value);
+    const repository = canonicalRepositoryIdentity(parsed.repository);
+    if (!canonicalHost.test(repository.host))
+        throw new Error("repository host is not canonical DNS syntax");
+    if (!canonicalOwner.test(repository.owner))
+        throw new Error("repository owner is invalid");
+    if (!canonicalName.test(repository.name))
+        throw new Error("repository name is invalid");
+    if (new Set(parsed.branches).size !== parsed.branches.length)
+        throw new Error("branches must not contain duplicates");
+    if (parsed.branches.some((branch) => !validateBranchPattern(branch)))
+        throw new Error("branch must be an exact Git ref or a terminal slash-star prefix pattern");
+    // Exercise the frozen matcher for every accepted pattern so validation and
+    // selection cannot silently drift into two different glob languages.
+    for (const branch of parsed.branches)
+        if (!branch.endsWith("/*") && !sharedBranchMatches(branch, branch))
+            throw new Error("invalid exact branch pattern");
+    const fingerprint = publicKeyFingerprint(parsed.signing.publicKeyPem);
+    if (!crypto.timingSafeEqual(Buffer.from(fingerprint, "hex"), Buffer.from(parsed.signing.publicKeySha256, "hex")))
+        throw new Error("signing public-key fingerprint does not match reviewed configuration");
+    if (repo) {
+        const remotes = repositoryRemoteIdentities(repo);
+        if (remotes.length === 0)
+            throw new Error("repository identity cannot be verified because no supported Git remote exists");
+        if (!remotes.some((remote) => JSON.stringify(remote) === JSON.stringify(repository)))
+            throw new Error("configured repository identity does not match any local Git remote");
+    }
+    return { ...parsed, repository };
+}
+export function loadSharedIndexConfig(repo) {
+    const target = path.join(path.resolve(repo), SHARED_INDEX_CONFIG_PATH);
+    if (!fs.existsSync(target))
+        return { state: "not-configured", path: target };
+    try {
+        const document = parseDocument(fs.readFileSync(target, "utf8"), {
+            strict: true,
+            uniqueKeys: true,
+        });
+        if (document.errors.length > 0)
+            throw new Error(document.errors.map((error) => error.message).join("; "));
+        const raw = document.toJS({ maxAliasCount: 0 });
+        return { state: "configured", path: target, config: validateSharedIndexConfig(raw, repo) };
+    }
+    catch (error) {
+        return { state: "invalid", path: target, errors: [boundedError(error)] };
+    }
+}
+function assertWritableTarget(repo, target) {
+    const state = path.dirname(target);
+    if (fs.existsSync(state) && fs.lstatSync(state).isSymbolicLink())
+        throw new Error("shared-index configuration directory must not be a symbolic link");
+    if (fs.existsSync(target) && fs.lstatSync(target).isSymbolicLink())
+        throw new Error("shared-index configuration must not be a symbolic link");
+    const relative = path.relative(path.resolve(repo), path.resolve(target));
+    if (relative.startsWith("..") || path.isAbsolute(relative))
+        throw new Error("shared-index configuration must remain inside the repository");
+}
+export function writeSharedIndexConfig(repo, config) {
+    const resolved = path.resolve(repo);
+    const validated = validateSharedIndexConfig(config, resolved);
+    const target = path.join(resolved, SHARED_INDEX_CONFIG_PATH);
+    assertWritableTarget(resolved, target);
+    fs.mkdirSync(path.dirname(target), { recursive: true, mode: 0o700 });
+    const temporary = `${target}.${process.pid}.${crypto.randomUUID()}.tmp`;
+    try {
+        fs.writeFileSync(temporary, stringify(validated, { lineWidth: 0 }), {
+            mode: 0o600,
+            flag: "wx",
+        });
+        const descriptor = fs.openSync(temporary, "r");
+        try {
+            fs.fsyncSync(descriptor);
+        }
+        finally {
+            fs.closeSync(descriptor);
+        }
+        fs.renameSync(temporary, target);
+        try {
+            const directory = fs.openSync(path.dirname(target), "r");
+            try {
+                fs.fsyncSync(directory);
+            }
+            finally {
+                fs.closeSync(directory);
+            }
+        }
+        catch (error) {
+            if (process.platform !== "win32")
+                throw error;
+        }
+    }
+    finally {
+        fs.rmSync(temporary, { force: true });
+    }
+    return target;
+}

package/dist/src/shared-index/contract.js

@@ -0,0 +1,117 @@
+import { createHash } from "node:crypto";
+export const SHARED_INDEX_SCHEMA_VERSION = 1;
+export const SHARED_INDEX_SIGNATURE = {
+    algorithm: "RSA-PSS",
+    hash: "sha256",
+    mgf1Hash: "sha256",
+    saltLength: 32,
+    input: "canonical-manifest-bytes",
+};
+export const SHARED_INDEX_LIMITS = {
+    pointerBytes: 64 * 1024,
+    manifestBytes: 256 * 1024,
+    signatureBytes: 16 * 1024,
+    compressedBytes: 8 * 1024 ** 3,
+    uncompressedBytes: 32 * 1024 ** 3,
+};
+function normalizedComponent(value) {
+    return value.normalize("NFC").toLocaleLowerCase("en-US");
+}
+/** Canonical identity used for remote comparison, signatures, and S3 prefixes. */
+export function canonicalRepositoryIdentity(identity) {
+    const host = identity.host
+        .replace(/^https?:\/\//i, "")
+        .replace(/^ssh:\/\/git@/i, "")
+        .replace(/\/$/, "")
+        .replace(/\.$/, "");
+    return {
+        host: normalizedComponent(host),
+        owner: normalizedComponent(identity.owner),
+        name: normalizedComponent(identity.name.replace(/\.git$/i, "")),
+    };
+}
+/** RFC 3986 component encoding (encodeURIComponent leaves five extra characters). */
+export function encodeSharedIndexComponent(value) {
+    return encodeURIComponent(value.normalize("NFC")).replace(/[!'()*]/g, (character) => `%${character.charCodeAt(0).toString(16).toUpperCase()}`);
+}
+export function sharedRepositoryPrefix(identity) {
+    const canonical = canonicalRepositoryIdentity(identity);
+    return `v1/${encodeSharedIndexComponent(canonical.host)}/${encodeSharedIndexComponent(canonical.owner)}/${encodeSharedIndexComponent(canonical.name)}/`;
+}
+function parsedVersion(version) {
+    const match = /^(\d+)\.(\d+)\.\d+(?:-([0-9A-Za-z.-]+))?$/.exec(version);
+    if (!match)
+        return null;
+    return { major: Number(match[1]), minor: Number(match[2]), prerelease: match[3] };
+}
+/** Exact v1 compatibility decision; every rejection is bounded and source-free. */
+export function sharedIndexCompatibility(client, manifest) {
+    const reasons = [];
+    const clientVersion = parsedVersion(client.knodinVersion);
+    const manifestVersion = parsedVersion(manifest.knodinVersion);
+    if (!clientVersion || !manifestVersion)
+        reasons.push("invalid-knodin-version");
+    else if (clientVersion.prerelease || manifestVersion.prerelease) {
+        if (client.knodinVersion !== manifest.knodinVersion)
+            reasons.push("knodin-prerelease-mismatch");
+    }
+    else if (clientVersion.major !== manifestVersion.major ||
+        clientVersion.minor < manifestVersion.minor) {
+        reasons.push("knodin-version-incompatible");
+    }
+    const exactFields = [
+        "databaseSchemaVersion",
+        "modelId",
+        "modelDigest",
+        "parserBundleDigest",
+        "indexConfigDigest",
+        "prunePolicyDigest",
+    ];
+    for (const field of exactFields) {
+        if (client[field] !== manifest[field])
+            reasons.push(`${field}-mismatch`);
+    }
+    return { compatible: reasons.length === 0, reasons };
+}
+/** Exact v1 ref matching, including the terminal slash-star prefix form. */
+export function sharedBranchMatches(pattern, branch) {
+    const normalizedPattern = pattern.normalize("NFC");
+    const normalizedBranch = branch.normalize("NFC");
+    return normalizedPattern.endsWith("/*")
+        ? normalizedBranch.startsWith(normalizedPattern.slice(0, -1)) &&
+            normalizedBranch.length > normalizedPattern.length - 1
+        : normalizedBranch === normalizedPattern;
+}
+function canonicalValue(value) {
+    if (typeof value === "string" &&
+        /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?:^|[^\uD800-\uDBFF])[\uDC00-\uDFFF]/u.test(value))
+        throw new TypeError("canonical JSON forbids unpaired Unicode surrogates");
+    if (value === null || typeof value === "boolean" || typeof value === "string")
+        return JSON.stringify(value);
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            throw new TypeError("canonical JSON forbids non-finite numbers");
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value))
+        return `[${value.map(canonicalValue).join(",")}]`;
+    if (typeof value === "object") {
+        const record = value;
+        const entries = Object.keys(record)
+            .sort((left, right) => left.localeCompare(right))
+            .map((key) => {
+            if (record[key] === undefined)
+                throw new TypeError("canonical JSON forbids undefined object values");
+            return `${JSON.stringify(key)}:${canonicalValue(record[key])}`;
+        });
+        return `{${entries.join(",")}}`;
+    }
+    throw new TypeError(`canonical JSON forbids ${typeof value} values`);
+}
+/** Exact UTF-8 bytes hashed and signed by shared-index v1. */
+export function canonicalManifestBytes(manifest) {
+    return Buffer.from(canonicalValue(manifest), "utf8");
+}
+export function sha256Hex(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}