@hraness/sponge 0.1.0 → 0.2.0

package/dist/src/metadata/article.js

@@ -0,0 +1,51 @@
+import { limits } from '../../contracts/index.js';
+import { validateMetadataClaim, validateMetadataWarnings } from '../../contracts/validate.js';
+function object(v) { if (!v || typeof v !== 'object' || Array.isArray(v))
+    throw Error('integrity'); return v; }
+/** Consume bounded observed Wordcell evidence without fetching linked JSON-LD contexts. */
+export function articleMetadata(input, observedAt) {
+    const envelope = object(input);
+    articleMetadataWarnings(input);
+    if (envelope.schemaVersion !== 1 || envelope.extractorVersion !== 'wordcell-metadata-v1')
+        throw Error('schema-newer');
+    if (!Array.isArray(envelope.claims) || envelope.claims.length > limits.metadataClaims || Buffer.byteLength(JSON.stringify(input)) > limits.metadataBytes)
+        throw Error('limit-exceeded');
+    const claims = envelope.claims.map(raw => {
+        const claim = object(raw), locator = claim.locator;
+        if (typeof locator !== 'string' || typeof claim.selected !== 'boolean')
+            throw Error('integrity');
+        const sources = { 'html-title': 'html', 'html-meta': 'html', 'html-link': 'html', 'html-language': 'html', 'json-ld': 'jsonld', extractor: 'html' };
+        if (typeof claim.source !== 'string' || !Object.hasOwn(sources, claim.source))
+            throw Error('integrity');
+        const source = /^meta\[(?:property|name)=og:/.test(locator) ? 'opengraph' : /^meta\[(?:property|name)=twitter:/.test(locator) ? 'twitter' : sources[claim.source];
+        if (claim.timezone !== undefined && (typeof claim.timezone !== 'string' || !['explicit', 'unknown', 'not-applicable'].includes(claim.timezone)))
+            throw Error('integrity');
+        const result = { field: claim.field, value: claim.value, observed: claim.observed, source, locator, selected: claim.selected, observedAt, rule: claim.rule, extractionVersion: envelope.extractorVersion, ...(claim.datePrecision !== undefined ? { datePrecision: claim.datePrecision } : {}), ...(claim.timezone === 'explicit' || claim.timezone === 'unknown' ? { timezoneKnown: claim.timezone === 'explicit' } : {}) };
+        validateMetadataClaim(result);
+        return result;
+    });
+    // Upstream selects a value per scalar field; reject contradictory accepted envelopes.
+    const selected = new Set();
+    for (const claim of claims) {
+        if (!claim.selected)
+            continue;
+        if (selected.has(claim.field) && !['authors', 'tags', 'alternate'].includes(claim.field))
+            throw Error('integrity');
+        selected.add(claim.field);
+    }
+    return claims;
+}
+export function selectedMetadata(claims, field) {
+    const matches = claims.filter(claim => claim.field === field);
+    return matches.find(claim => claim.selected === true) ?? matches.find(claim => claim.selected === undefined);
+}
+export function articleMetadataWarnings(input) {
+    const envelope = object(input);
+    try {
+        validateMetadataWarnings(envelope.warnings);
+    }
+    catch {
+        throw Error('integrity');
+    }
+    return [...envelope.warnings];
+}

package/dist/src/models/artifacts.d.ts

@@ -0,0 +1,36 @@
+export interface ModelArtifact {
+    name: string;
+    url: string;
+    sha256: string;
+    bytes: number;
+    executable?: boolean;
+}
+export interface ModelPackage {
+    id: string;
+    license: string;
+    artifacts: readonly ModelArtifact[];
+}
+export declare class ModelSetupError extends Error {
+    readonly code: 'invalid-input' | 'integrity' | 'unavailable' | 'cancelled' | 'owner-busy' | 'limit-exceeded' | 'cleanup-required' | 'repair-auth';
+    constructor(code: 'invalid-input' | 'integrity' | 'unavailable' | 'cancelled' | 'owner-busy' | 'limit-exceeded' | 'cleanup-required' | 'repair-auth');
+}
+export declare function modelSetupPlan(manifest: ModelPackage): {
+    id: string;
+    license: string;
+    fingerprint: string;
+    downloadBytes: number;
+    requiredFreeBytes: number;
+    artifacts: readonly ModelArtifact[];
+};
+export declare function inspectModelPackage(cacheRoot: string, manifest: ModelPackage): Promise<Record<string, string>>;
+/** Explicit recovery only: an absent or different process birth identity proves the downloader is gone.
+ * Downloading is in-process fetch; no native child can outlive this owner. A missing or
+ * foreign stage receipt remains pending, as does an interrupted recovery guard. */
+export declare function recoverModelPackage(cacheRoot: string, manifest: ModelPackage): Promise<{
+    recovered: boolean;
+}>;
+/** Explicit setup only. Never called by install hooks or by inference fallback. */
+export declare function provisionModelPackage(cacheRoot: string, manifest: ModelPackage, options?: {
+    signal?: AbortSignal;
+    fetch?: typeof fetch;
+}): Promise<Record<string, string>>;

package/dist/src/models/artifacts.js

@@ -0,0 +1,274 @@
+import { constants } from 'node:fs';
+import { chmod, lstat, mkdir, open, rename, rm, statfs, link, unlink, readdir, realpath } from 'node:fs/promises';
+import { join } from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+import { processIdentity, identityAlive } from '../worker/identity.js';
+import { readJournal, writeJournal } from '../worker/journal.js';
+import { privateRoot } from '../acquisition/files.js';
+export class ModelSetupError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.code = code;
+    }
+}
+const maximumBytes = 2 * 1024 ** 3;
+function validate(manifest) {
+    if (!/^[a-z0-9][a-z0-9.-]{0,127}$/.test(manifest.id) || !manifest.license || manifest.license.length > 256 || !manifest.artifacts.length || manifest.artifacts.length > 16)
+        throw new ModelSetupError('invalid-input');
+    const names = new Set();
+    let bytes = 0;
+    for (const artifact of manifest.artifacts) {
+        let url;
+        try {
+            url = new URL(artifact.url);
+        }
+        catch {
+            throw new ModelSetupError('invalid-input');
+        }
+        if (!/^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/.test(artifact.name) || names.has(artifact.name) || url.protocol !== 'https:' || url.username || url.password || !/^[a-f0-9]{64}$/.test(artifact.sha256) || !Number.isSafeInteger(artifact.bytes) || artifact.bytes < 1 || artifact.bytes > maximumBytes)
+            throw new ModelSetupError('invalid-input');
+        names.add(artifact.name);
+        bytes += artifact.bytes;
+    }
+    if (bytes > maximumBytes)
+        throw new ModelSetupError('limit-exceeded');
+}
+function identity(manifest) {
+    return createHash('sha256').update(JSON.stringify({ id: manifest.id, license: manifest.license, artifacts: manifest.artifacts.map(a => ({ name: a.name, url: a.url, sha256: a.sha256, bytes: a.bytes, executable: !!a.executable })).sort((a, b) => a.name.localeCompare(b.name)) })).digest('hex');
+}
+export function modelSetupPlan(manifest) {
+    validate(manifest);
+    const downloadBytes = manifest.artifacts.reduce((n, a) => n + a.bytes, 0);
+    return { id: manifest.id, license: manifest.license, fingerprint: identity(manifest), downloadBytes, requiredFreeBytes: downloadBytes + 512 * 1024 ** 2, artifacts: manifest.artifacts };
+}
+async function syncDirectory(path) { const file = await open(path, constants.O_RDONLY); try {
+    await file.sync();
+}
+finally {
+    await file.close();
+} }
+async function verifyArtifact(path, artifact) {
+    const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const before = await file.stat();
+        if (!before.isFile() || before.nlink !== 1 || before.size !== artifact.bytes || (before.mode & 0o077) !== 0 || (artifact.executable && (before.mode & 0o100) === 0))
+            throw new ModelSetupError('integrity');
+        const hash = createHash('sha256'), buffer = Buffer.alloc(65536);
+        let bytes = 0;
+        for (;;) {
+            const read = await file.read(buffer, 0, buffer.length, null);
+            if (!read.bytesRead)
+                break;
+            bytes += read.bytesRead;
+            if (bytes > artifact.bytes)
+                throw new ModelSetupError('integrity');
+            hash.update(buffer.subarray(0, read.bytesRead));
+        }
+        const after = await file.stat();
+        if (bytes !== artifact.bytes || hash.digest('hex') !== artifact.sha256 || before.mtimeMs !== after.mtimeMs)
+            throw new ModelSetupError('integrity');
+    }
+    finally {
+        await file.close();
+    }
+}
+export async function inspectModelPackage(cacheRoot, manifest) {
+    const plan = modelSetupPlan(manifest), root = join(await privateRoot(cacheRoot), plan.fingerprint);
+    await privateRoot(root);
+    const paths = Object.create(null);
+    for (const artifact of manifest.artifacts) {
+        const path = join(root, artifact.name);
+        await verifyArtifact(path, artifact);
+        paths[artifact.name] = path;
+    }
+    return paths;
+}
+const pending = () => { throw new ModelSetupError('cleanup-required'); };
+async function sameFile(a, b) { try {
+    const [x, y] = await Promise.all([lstat(a), lstat(b)]);
+    if (!x.isFile() || !y.isFile() || x.isSymbolicLink() || y.isSymbolicLink() || x.ino !== y.ino || x.dev !== y.dev)
+        pending();
+}
+catch {
+    return pending();
+} }
+async function readOwner(path, fingerprint) { const owner = await readJournal(path); if (owner.schemaVersion !== 1 || owner.fingerprint !== fingerprint || !/^[-a-f0-9]{36}$/.test(owner.incarnation) || owner.stage !== '.model-install-' + owner.incarnation || !owner.identity || !Number.isSafeInteger(owner.identity.pid) || owner.identity.pid < 1 || owner.identity.uid !== process.getuid?.() || typeof owner.identity.started !== 'string' || !owner.identity.started.trim())
+    pending(); return owner; }
+async function cleanupStage(root, owner, file) { const stage = join(root, owner.stage); let stat; try {
+    stat = await lstat(stage);
+}
+catch (error) {
+    if (error.code === 'ENOENT')
+        return;
+    throw error;
+} if (!stat.isDirectory() || stat.isSymbolicLink() || stat.uid !== process.getuid?.() || (stat.mode & 0o077) !== 0 || await realpath(stage) !== stage)
+    pending(); const entries = await readdir(stage); if (entries.length) {
+    await sameFile(file, join(stage, 'ownership.json'));
+} await rm(stage, { recursive: true }); await syncDirectory(root); }
+/** Explicit recovery only: an absent or different process birth identity proves the downloader is gone.
+ * Downloading is in-process fetch; no native child can outlive this owner. A missing or
+ * foreign stage receipt remains pending, as does an interrupted recovery guard. */
+export async function recoverModelPackage(cacheRoot, manifest) {
+    const plan = modelSetupPlan(manifest), root = await privateRoot(cacheRoot), lock = join(root, `.${plan.fingerprint}.lock`);
+    let owner;
+    try {
+        owner = await readOwner(lock, plan.fingerprint);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return { recovered: false };
+        return pending();
+    }
+    try {
+        if (await identityAlive(owner.identity))
+            throw new ModelSetupError('owner-busy');
+    }
+    catch (error) {
+        if (error instanceof ModelSetupError)
+            throw error;
+        return pending();
+    }
+    const file = join(root, `.model-owner-${owner.incarnation}.json`), guard = join(root, `.${plan.fingerprint}.recovery-lock`);
+    await sameFile(file, lock);
+    try {
+        await link(file, guard);
+        await syncDirectory(root);
+    }
+    catch (error) {
+        if (error.code === 'EEXIST')
+            return pending();
+        throw error;
+    }
+    try {
+        await sameFile(file, lock);
+        if (await identityAlive(owner.identity))
+            throw new ModelSetupError('owner-busy');
+        await cleanupStage(root, owner, file);
+        await sameFile(file, lock);
+        await unlink(lock);
+        await syncDirectory(root);
+        return { recovered: true };
+    }
+    finally {
+        await sameFile(file, guard);
+        await unlink(guard);
+        await syncDirectory(root);
+        try {
+            await lstat(lock);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                await unlink(file);
+                await syncDirectory(root);
+            }
+            else
+                throw error;
+        }
+    }
+}
+/** Explicit setup only. Never called by install hooks or by inference fallback. */
+export async function provisionModelPackage(cacheRoot, manifest, options = {}) {
+    const plan = modelSetupPlan(manifest), root = await privateRoot(cacheRoot), destination = join(root, plan.fingerprint);
+    if (options.signal?.aborted)
+        throw new ModelSetupError('cancelled');
+    try {
+        await lstat(destination);
+        return await inspectModelPackage(root, manifest);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    const lock = join(root, `.${plan.fingerprint}.lock`), incarnation = randomUUID(), ownerFile = join(root, `.model-owner-${incarnation}.json`);
+    const identity = await processIdentity(process.pid);
+    if (!identity)
+        pending();
+    const owner = { schemaVersion: 1, incarnation, fingerprint: plan.fingerprint, stage: '.model-install-' + incarnation, identity: identity };
+    await writeJournal(ownerFile, owner);
+    let linked = false;
+    try {
+        await link(ownerFile, lock);
+        linked = true;
+        await syncDirectory(root);
+    }
+    catch (error) {
+        if (linked)
+            return pending();
+        await unlink(ownerFile);
+        await syncDirectory(root);
+        if (error.code === 'EEXIST')
+            throw new ModelSetupError('owner-busy');
+        throw error;
+    }
+    let stage;
+    try {
+        const disk = await statfs(root);
+        if (disk.bavail * disk.bsize < plan.requiredFreeBytes)
+            throw new ModelSetupError('limit-exceeded');
+        stage = join(root, owner.stage);
+        await mkdir(stage, { mode: 0o700 });
+        await chmod(stage, 0o700);
+        await link(ownerFile, join(stage, 'ownership.json'));
+        await syncDirectory(stage);
+        await syncDirectory(root);
+        for (const artifact of manifest.artifacts) {
+            const signal = options.signal ? AbortSignal.any([options.signal, AbortSignal.timeout(600000)]) : AbortSignal.timeout(600000);
+            const response = await (options.fetch ?? fetch)(artifact.url, { signal });
+            if (!response.ok || !response.body || (response.url && new URL(response.url).protocol !== 'https:'))
+                throw new ModelSetupError('unavailable');
+            const declared = response.headers.get('content-length');
+            if (declared !== null && Number(declared) !== artifact.bytes) {
+                await response.body.cancel();
+                throw new ModelSetupError('integrity');
+            }
+            const file = await open(join(stage, artifact.name), constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+            const hash = createHash('sha256');
+            let bytes = 0;
+            try {
+                for await (const chunk of response.body) {
+                    if (signal.aborted)
+                        throw new ModelSetupError('cancelled');
+                    bytes += chunk.length;
+                    if (bytes > artifact.bytes)
+                        throw new ModelSetupError('integrity');
+                    hash.update(chunk);
+                    let offset = 0;
+                    while (offset < chunk.length) {
+                        const result = await file.write(chunk, offset, chunk.length - offset);
+                        if (!result.bytesWritten)
+                            throw new ModelSetupError('unavailable');
+                        offset += result.bytesWritten;
+                    }
+                }
+                if (bytes !== artifact.bytes || hash.digest('hex') !== artifact.sha256)
+                    throw new ModelSetupError('integrity');
+                await file.chmod(artifact.executable ? 0o700 : 0o600);
+                await file.sync();
+            }
+            finally {
+                await file.close();
+            }
+        }
+        if (options.signal?.aborted)
+            throw new ModelSetupError('cancelled');
+        await syncDirectory(stage);
+        await rename(stage, destination);
+        stage = undefined;
+        await syncDirectory(root);
+        return await inspectModelPackage(root, manifest);
+    }
+    catch (error) {
+        if (options.signal?.aborted)
+            throw new ModelSetupError('cancelled');
+        throw error;
+    }
+    finally {
+        if (stage)
+            await cleanupStage(root, owner, ownerFile);
+        await sameFile(ownerFile, lock);
+        await unlink(lock);
+        await unlink(ownerFile);
+        await syncDirectory(root);
+    }
+}

package/dist/src/models/catalog.d.ts

@@ -0,0 +1,35 @@
+import type { ModelPackage } from './artifacts.js';
+export type NativeKind = 'asr' | 'embedding';
+export type NativeRole = 'asr-helper' | 'embedding-helper' | 'embedding-library' | 'notices';
+export declare const nativeAssetNames: Record<NativeRole, string>;
+export interface NativeArtifact {
+    role: NativeRole;
+    name: string;
+    bytes: number;
+    sha256: string;
+}
+export interface NativeCatalog {
+    schemaVersion: 1;
+    packageVersion: string;
+    sourceCommit: string;
+    platform: 'darwin';
+    architecture: 'arm64';
+    minimumMacOS: '26.0';
+    artifacts: NativeArtifact[];
+    build: {
+        asrSourceSha256: string;
+        embeddingSourceSha256: string;
+        swiftVersion: string;
+        clangVersion: string;
+    };
+}
+export declare class NativeCatalogError extends Error {
+    readonly code: 'runtime-missing' | 'unsupported' | 'integrity';
+    constructor(code: 'runtime-missing' | 'unsupported' | 'integrity');
+}
+/** Package-embedded release hashes are authority; local probe helper hashes never enter this catalog. */
+export declare function parseNativeCatalog(value: unknown, expectedVersion: string): NativeCatalog;
+export declare function nativePlatformSupported(platform?: NodeJS.Platform, architecture?: NodeJS.Architecture, kernel?: string): boolean;
+export declare function nativeCatalogPath(): string;
+export declare function loadNativeCatalog(expectedVersion: string, path?: string): Promise<NativeCatalog>;
+export declare function nativeModelPackage(catalog: NativeCatalog, kind: NativeKind): ModelPackage;

package/dist/src/models/catalog.js

@@ -0,0 +1,71 @@
+import { constants } from 'node:fs';
+import { open } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { release } from 'node:os';
+import { asrIdentity } from '../inference/asr/protocol.js';
+import { embeddingIdentity } from '../inference/embedding/index.js';
+export const nativeAssetNames = { 'asr-helper': 'sponge-speech-macos26-arm64', 'embedding-helper': 'sponge-embedding-macos26-arm64', 'embedding-library': 'libCLiteRTLM_mac.dylib', notices: 'native-NOTICES.txt' };
+export class NativeCatalogError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.code = code;
+    }
+}
+const fail = () => { throw new NativeCatalogError('integrity'); };
+function object(value, keys) { if (!value || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).sort().join(',') !== keys.sort().join(','))
+    fail(); return value; }
+const sha = (v) => typeof v === 'string' && /^[a-f0-9]{64}$/u.test(v);
+function version(v) { return typeof v === 'string' && /^(0|[1-9]\d{0,15})\.(0|[1-9]\d{0,15})\.(0|[1-9]\d{0,15})$/u.test(v) && v.split('.').every(n => Number.isSafeInteger(Number(n))); }
+/** Package-embedded release hashes are authority; local probe helper hashes never enter this catalog. */
+export function parseNativeCatalog(value, expectedVersion) {
+    const r = object(value, ['schemaVersion', 'packageVersion', 'sourceCommit', 'platform', 'architecture', 'minimumMacOS', 'artifacts', 'build']);
+    if (r.schemaVersion !== 1 || !version(expectedVersion) || r.packageVersion !== expectedVersion || typeof r.sourceCommit !== 'string' || !/^[a-f0-9]{40}$/u.test(r.sourceCommit) || r.platform !== 'darwin' || r.architecture !== 'arm64' || r.minimumMacOS !== '26.0' || !Array.isArray(r.artifacts) || r.artifacts.length !== 4)
+        fail();
+    const roles = new Set();
+    const artifacts = r.artifacts.map((value) => { const a = object(value, ['role', 'name', 'bytes', 'sha256']); if (typeof a.role !== 'string' || !Object.hasOwn(nativeAssetNames, a.role) || roles.has(a.role) || a.name !== nativeAssetNames[a.role] || typeof a.bytes !== 'number' || !Number.isSafeInteger(a.bytes) || a.bytes < 1 || a.bytes > (a.role === 'embedding-library' ? 160 * 1024 ** 2 : a.role === 'notices' ? 1024 ** 2 : 32 * 1024 ** 2) || !sha(a.sha256))
+        fail(); roles.add(a.role); if (a.role === 'embedding-library' && a.sha256 !== embeddingIdentity.librarySha256)
+        fail(); return a; });
+    const build = object(r.build, ['asrSourceSha256', 'embeddingSourceSha256', 'swiftVersion', 'clangVersion']);
+    if (!sha(build.asrSourceSha256) || !sha(build.embeddingSourceSha256) || ['swiftVersion', 'clangVersion'].some(k => typeof build[k] !== 'string' || !build[k] || Buffer.byteLength(String(build[k])) > 2048))
+        fail();
+    return { ...r, artifacts, build };
+}
+export function nativePlatformSupported(platform = process.platform, architecture = process.arch, kernel = release()) { return platform === 'darwin' && architecture === 'arm64' && /^\d+\./u.test(kernel) && Number(kernel.split('.')[0]) >= 25; }
+export function nativeCatalogPath() { return fileURLToPath(new URL(import.meta.url.endsWith('.ts') ? '../../native/runtime-manifest.json' : '../../../native/runtime-manifest.json', import.meta.url)); }
+export async function loadNativeCatalog(expectedVersion, path = nativeCatalogPath()) {
+    let file;
+    try {
+        file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            throw new NativeCatalogError('runtime-missing');
+        throw new NativeCatalogError('integrity');
+    }
+    try {
+        const stat = await file.stat();
+        if (!stat.isFile() || stat.nlink !== 1 || stat.size < 1 || stat.size > 16384)
+            fail();
+        let parsed;
+        try {
+            parsed = JSON.parse(await file.readFile('utf8'));
+        }
+        catch {
+            fail();
+        }
+        return parseNativeCatalog(parsed, expectedVersion);
+    }
+    finally {
+        await file.close();
+    }
+}
+export function nativeModelPackage(catalog, kind) {
+    parseNativeCatalog(catalog, catalog.packageVersion);
+    if (kind !== 'asr' && kind !== 'embedding')
+        fail();
+    const roles = kind === 'asr' ? ['asr-helper', 'notices'] : ['embedding-helper', 'embedding-library', 'notices'];
+    const artifacts = roles.map(role => { const a = catalog.artifacts.find(a => a.role === role); return { name: role === 'asr-helper' ? 'sponge-speech' : role === 'embedding-helper' ? 'sponge-embedding' : a.name, url: `https://github.com/hraness/sponge/releases/download/v${catalog.packageVersion}/${a.name}`, sha256: a.sha256, bytes: a.bytes, ...(role.endsWith('helper') ? { executable: true } : {}) }; });
+    artifacts.push(kind === 'asr' ? { name: 'whistle.cact', url: 'https://huggingface.co/Cactus-Compute/whistle/resolve/ca5287601bef25af26dcf2e1b2bdc0843a7c19e5/whistle.cact', sha256: asrIdentity.modelSha256, bytes: asrIdentity.modelBytes } : { name: 'embeddinggemma-2-text-vision-440m.litertlm', url: 'https://huggingface.co/litert-community/embeddinggemma-2-text-vision-440m-litert-lm/resolve/e301f74d5551b0c2641bd5cb4652a76239d5c5f8/embeddinggemma-2-text-vision-440m.litertlm', sha256: embeddingIdentity.modelSha256, bytes: 387710976 });
+    return { id: `sponge-${kind}-${catalog.packageVersion}-macos26-arm64`, license: 'Sponge helpers: proprietary; Needle, Whistle, LiteRT-LM and model: Apache-2.0; see native-NOTICES.txt', artifacts };
+}

package/dist/src/models/download.d.ts

@@ -0,0 +1,9 @@
+import { type ModelPackage } from './artifacts.js';
+export declare const nativeDownloadAuthGuidance = "Set GH_TOKEN or GITHUB_TOKEN with Contents: read access to hraness/sponge, then retry setup. Credentials are never saved.";
+/** A manifest-bound, in-process transport. Only exact repository API calls carry auth.
+ * Manual CDN redirects always discard auth; returned bytes still pass package hashes.
+ * Public model downloads never read credentials or receive authorization headers. */
+export declare function nativeArtifactFetch(manifest: ModelPackage, options?: {
+    env?: NodeJS.ProcessEnv;
+    fetch?: typeof fetch;
+}): typeof fetch;

package/dist/src/models/download.js

@@ -0,0 +1,147 @@
+import { ModelSetupError } from './artifacts.js';
+const api = 'https://api.github.com/repos/hraness/sponge';
+const nativeUrl = /^https:\/\/github\.com\/hraness\/sponge\/releases\/download\/(v(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*))\/([A-Za-z0-9_.-]+)$/;
+const cdnHosts = new Set(['release-assets.githubusercontent.com', 'objects.githubusercontent.com', 'github-releases.githubusercontent.com']);
+const redirectCodes = new Set([301, 302, 303, 307, 308]);
+export const nativeDownloadAuthGuidance = 'Set GH_TOKEN or GITHUB_TOKEN with Contents: read access to hraness/sponge, then retry setup. Credentials are never saved.';
+function fail(code) { throw new ModelSetupError(code); }
+async function discard(response) { try {
+    await response.body?.cancel();
+}
+catch { } }
+async function boundedJson(response) {
+    if (!response.body)
+        fail('integrity');
+    const chunks = [];
+    let bytes = 0;
+    try {
+        for await (const chunk of response.body) {
+            bytes += chunk.length;
+            if (bytes > 1024 * 1024)
+                fail('integrity');
+            chunks.push(chunk);
+        }
+        const value = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(chunks)));
+        if (!value || typeof value !== 'object' || Array.isArray(value))
+            fail('integrity');
+        return value;
+    }
+    catch (error) {
+        if (error instanceof ModelSetupError)
+            throw error;
+        fail('integrity');
+    }
+}
+function credential(env) {
+    // An explicitly configured higher-priority identity never falls through to another.
+    const token = env.GH_TOKEN !== undefined ? env.GH_TOKEN : env.GITHUB_TOKEN;
+    if (!token || token.length > 4096 || /[^\x21-\x7e]/u.test(token))
+        fail('repair-auth');
+    return token;
+}
+/** A manifest-bound, in-process transport. Only exact repository API calls carry auth.
+ * Manual CDN redirects always discard auth; returned bytes still pass package hashes.
+ * Public model downloads never read credentials or receive authorization headers. */
+export function nativeArtifactFetch(manifest, options = {}) {
+    const transport = options.fetch ?? globalThis.fetch, env = options.env ?? process.env, artifacts = new Map(manifest.artifacts.map(a => [a.url, a]));
+    const request = async (url, signal, headers) => {
+        if (signal?.aborted)
+            fail('cancelled');
+        try {
+            return await transport(url, { signal, redirect: 'manual', headers });
+        }
+        catch {
+            if (signal?.aborted)
+                fail('cancelled');
+            fail('unavailable');
+        }
+    };
+    const download = async (artifact, tag, name, signal) => {
+        const token = credential(env), auth = { Authorization: `Bearer ${token}`, 'X-GitHub-Api-Version': '2022-11-28', Accept: 'application/vnd.github+json' };
+        const metadataResponse = await request(`${api}/releases/tags/${tag}`, signal, auth);
+        if (!metadataResponse.ok) {
+            await discard(metadataResponse);
+            if ([401, 403, 404].includes(metadataResponse.status))
+                fail('repair-auth');
+            fail('unavailable');
+        }
+        const release = await boundedJson(metadataResponse);
+        if (release.tag_name !== tag || release.immutable !== true || release.draft !== false || release.prerelease !== false || !Number.isSafeInteger(release.id) || Number(release.id) <= 0 || release.url !== `${api}/releases/${release.id}` || release.html_url !== `https://github.com/hraness/sponge/releases/tag/${tag}` || !Array.isArray(release.assets) || release.assets.length > 1000)
+            fail('integrity');
+        const matches = release.assets.filter(a => a && typeof a === 'object' && a.name === name);
+        if (matches.length !== 1)
+            fail('integrity');
+        const asset = matches[0];
+        if (!Number.isSafeInteger(asset.id) || asset.id <= 0 || asset.state !== 'uploaded' || asset.size !== artifact.bytes || asset.digest !== `sha256:${artifact.sha256}` || asset.url !== `${api}/releases/assets/${asset.id}` || asset.browser_download_url !== artifact.url)
+            fail('integrity');
+        let response = await request(asset.url, signal, { ...auth, Accept: 'application/octet-stream' });
+        for (let redirects = 0; redirectCodes.has(response.status); redirects++) {
+            const location = response.headers.get('location');
+            await discard(response);
+            if (redirects >= 5 || !location)
+                fail('integrity');
+            let next;
+            try {
+                next = new URL(location);
+            }
+            catch {
+                fail('integrity');
+            }
+            if (next.protocol !== 'https:' || next.username || next.password || next.port || next.hash || !cdnHosts.has(next.hostname))
+                fail('integrity');
+            response = await request(next.href, signal); // No credential or GitHub API headers cross this boundary.
+        }
+        if (!response.ok) {
+            await discard(response);
+            if ([401, 403, 404].includes(response.status))
+                fail('repair-auth');
+            fail('unavailable');
+        }
+        return response;
+    };
+    return (async (input, init) => {
+        const url = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url, artifact = artifacts.get(url), signal = init?.signal ?? undefined;
+        if (!artifact || init?.headers || init?.body || init?.method && init.method !== 'GET')
+            fail('integrity');
+        if (signal?.aborted)
+            fail('cancelled');
+        const match = nativeUrl.exec(url);
+        if (match) {
+            try {
+                return await download(artifact, match[1], match[2], signal);
+            }
+            catch (error) {
+                if (signal?.aborted)
+                    fail('cancelled');
+                throw error;
+            }
+        }
+        // Only the catalog's pinned public Hugging Face models use public redirect handling.
+        const parsed = new URL(url);
+        if (parsed.origin !== 'https://huggingface.co' || parsed.username || parsed.password)
+            fail('integrity');
+        let currentUrl = url, response = await request(currentUrl, signal);
+        for (let redirects = 0; redirectCodes.has(response.status); redirects++) {
+            const location = response.headers.get('location');
+            await discard(response);
+            if (redirects >= 5 || !location)
+                fail('integrity');
+            let next;
+            try {
+                next = new URL(location, currentUrl);
+            }
+            catch {
+                fail('integrity');
+            }
+            if (next.protocol !== 'https:' || next.username || next.password || next.port || next.hash || !(next.hostname === 'huggingface.co' || next.hostname.endsWith('.huggingface.co') || next.hostname === 'hf.co' || next.hostname.endsWith('.hf.co')))
+                fail('integrity');
+            currentUrl = next.href;
+            response = await request(currentUrl, signal);
+        }
+        if (!response.ok) {
+            await discard(response);
+            fail('unavailable');
+        }
+        return response;
+    });
+}

package/dist/src/models/runtime.d.ts

@@ -0,0 +1,24 @@
+import type { AsrRuntime } from '../inference/asr/runtime.js';
+import type { EmbeddingRuntime } from '../inference/embedding/index.js';
+import { type NativeCatalog, type NativeKind } from './catalog.js';
+export declare function nativeSetupPlan(kind: NativeKind, version: string): Promise<{
+    supported: boolean;
+    minimumMacOS: "26.0";
+    id: string;
+    license: string;
+    fingerprint: string;
+    downloadBytes: number;
+    requiredFreeBytes: number;
+    artifacts: readonly import("./artifacts.js").ModelArtifact[];
+}>;
+export declare function setupNativeRuntime(cacheRoot: string, catalog: NativeCatalog, kind: NativeKind, options?: {
+    signal?: AbortSignal;
+}): Promise<AsrRuntime | EmbeddingRuntime>;
+export declare function inspectAsrRuntime(cacheRoot: string, catalog: NativeCatalog): Promise<AsrRuntime>;
+export declare function inspectEmbeddingRuntime(cacheRoot: string, catalog: NativeCatalog): Promise<EmbeddingRuntime>;
+export declare function provisionNative(kind: 'asr', cacheRoot: string, version: string, signal?: AbortSignal): Promise<AsrRuntime>;
+export declare function provisionNative(kind: 'embedding', cacheRoot: string, version: string, signal?: AbortSignal): Promise<EmbeddingRuntime>;
+export declare function provisionNative(kind: NativeKind, cacheRoot: string, version: string, signal?: AbortSignal): Promise<AsrRuntime | EmbeddingRuntime>;
+export declare function inspectNative(kind: 'asr', cacheRoot: string, version: string): Promise<AsrRuntime>;
+export declare function inspectNative(kind: 'embedding', cacheRoot: string, version: string): Promise<EmbeddingRuntime>;
+export declare function inspectNative(kind: NativeKind, cacheRoot: string, version: string): Promise<AsrRuntime | EmbeddingRuntime>;