reploid 0.0.0-stage → 0.1.1

package/server/native-model-files.js

@@ -0,0 +1,382 @@
+import { fetchAdapterFile } from '../apps/poolday/providers/work-adapter.js';
+import { resolvePartitionArtifactSource } from '../apps/poolday/host/work-partition-artifact-source.js';
+/** Filesystem host ports for the existing signed custody protocol. Model weights come from the approved local
+ * directory, then authorized custody peers, then the model's pinned origin (native-model-origin.js) when one is
+ * pinned; every byte is verified against pinned identities. Explicit adapter acquisition permits its pinned origin. */
+import fs from 'node:fs/promises';
+import { openNativeSupplyBudget } from './native-supply-budget.js';
+import { constants } from 'node:fs';
+import path from 'node:path';
+import { sha256Hex as digest } from './hashing.js';
+import { createCustodyExchange, createCustodyContracts, createPieceAcquisition } from '../packages/reploid/src/artifacts/custody/runtime.js';
+import { createSigningKeyPair, exportPublicKey, sha256Hex, signCanonical, verifyCanonicalSignature } from '../packages/reploid/src/artifacts/signatures.js';
+import { createPeerPackDataChannel } from '../apps/poolday/pool/peer-pack-data-channel.js';
+import { hashDopplerEvidence, validateExecutablePack, executablePacksMatch } from '../shared/pool/executable-pack.js';
+import policy from '../apps/poolday/config/chat-files.json' with { type: 'json' };
+import { resolveServedFile } from './browser-roots.js';
+import { fillWholeModelDirectory, wholeModelDirectoryComplete } from './native-whole-model-fill.js';
+import { resolvePinnedOrigin, readPinnedOrigin } from './native-model-origin.js';
+
+// How long a whole-model fill with a pinned origin waits for peers to announce before using the origin.
+const PEER_GRACE_MS = 15000;
+
+const assert = (ok, message) => { if (!ok) throw new Error(message); };
+const key = file => { assert(file.hashAlgorithm === 'sha256' && /^[a-f0-9]{64}$/.test(file.hash), 'Pinned SHA-256 file required'); return 'sha256-' + file.hash; };
+const verify = async (file, bytes) => {
+  assert(bytes instanceof Uint8Array && bytes.byteLength === file.sizeBytes && bytes.byteLength <= policy.maxArtifactBytes,
+    'Native artifact size mismatch');
+  assert(digest(bytes) === file.hash, 'Native artifact integrity mismatch');
+};
+const pieceFile = piece => ({ path: `piece-${piece.identity.slice(7)}.bin`, role: 'model-weights',
+  hashAlgorithm: 'sha256', hash: piece.identity.slice(7), sizeBytes: piece.size });
+
+/** Complete verified pieces survive interruption. Temporary replacements never advertise. */
+export async function createNativeArtifactCache({ directory, maxBytes = policy.maxStoredBytes }) {
+  assert(Number.isSafeInteger(maxBytes) && maxBytes > 0, 'Explicit cache budget required');
+  await fs.mkdir(directory, { recursive: true, mode: 0o700 });
+  const root = await fs.realpath(directory); let writing = Promise.resolve(); const quarantined = [];
+  const get = async file => {
+    let handle;
+    try {
+      handle = await fs.open(path.join(root, key(file)), constants.O_RDONLY | constants.O_NOFOLLOW);
+      const stat = await handle.stat(); assert(stat.isFile(), 'Native cache entry must be a regular file');
+      if (stat.size !== file.sizeBytes || stat.size > policy.maxArtifactBytes) throw Object.assign(new Error('Native cache size mismatch'), { code: 'NATIVE_CACHE_CORRUPT' });
+      const bytes = new Uint8Array(await handle.readFile());
+      if (digest(bytes) !== file.hash) throw Object.assign(new Error('Native cache integrity mismatch'), { code: 'NATIVE_CACHE_CORRUPT' });
+      return bytes;
+    } catch (error) {
+      if (error.code === 'ENOENT') return null;
+      if (error.code !== 'NATIVE_CACHE_CORRUPT') throw error;
+      await handle?.close(); handle = null;
+      const name = key(file) + '.corrupt.' + crypto.randomUUID();
+      await fs.rename(path.join(root, key(file)), path.join(root, name));
+      quarantined.push({ name, expectedHash: file.hash, reason: error.message }); return null;
+    } finally { await handle?.close(); }
+  };
+  const put = (file, bytes, { signal } = {}) => {
+    const operation = writing.catch(() => {}).then(async () => {
+      signal?.throwIfAborted(); await verify(file, bytes);
+      if (await get(file)) return;
+      let used = 0;
+      for (const name of await fs.readdir(root)) {
+        const info = await fs.lstat(path.join(root, name));
+        assert(!info.isSymbolicLink(), 'Native cache cannot contain symbolic links'); used += info.size;
+      }
+      assert(used + bytes.byteLength <= maxBytes, 'Native artifact cache budget exhausted');
+      const temporary = path.join(root, key(file) + '.' + crypto.randomUUID() + '.tmp');
+      let handle;
+      try {
+        handle = await fs.open(temporary, 'wx', 0o600); await handle.writeFile(bytes); await handle.sync(); await handle.close(); handle = null;
+        signal?.throwIfAborted(); await fs.rename(temporary, path.join(root, key(file)));
+      } finally { await handle?.close(); await fs.unlink(temporary).catch(error => { if (error.code !== 'ENOENT') throw error; }); }
+    });
+    writing = operation; return operation;
+  };
+  // Drops a verified copy once the same bytes are owned elsewhere (a filled model directory).
+  const remove = file => {
+    const operation = writing.catch(() => {}).then(() => fs.unlink(path.join(root, key(file)))
+      .catch(error => { if (error.code !== 'ENOENT') throw error; }));
+    writing = operation; return operation;
+  };
+  return Object.freeze({ get, put, remove, getState: () => ({ quarantined: structuredClone(quarantined) }), close: () => writing });
+}
+
+/** `owner` is the optional native owner gate (server/native-owner/controls.js). Without
+ * it, channels, supply admission and acquisition deadlines are exactly as before.
+ * `certifyCustodyKey` (packages/reploid/src/artifacts/custody-certificate.js) lets the persistent
+ * participant identity certify this process's custody key; without it the key stays
+ * unattributable to any device. */
+export async function createNativeModelFiles({ transport, modelDirectory, cacheDirectory, onChange = () => {}, owner = null, certifyCustodyKey = null,
+  modelOrigins = undefined, originFetch = undefined, peerGraceMs = PEER_GRACE_MS }) {
+  const root = await fs.realpath(modelDirectory), cache = await createNativeArtifactCache({ directory: cacheDirectory });
+  let budget = null, budgetError = null;
+  try { budget = await openNativeSupplyBudget({ directory: cacheDirectory, maxBytes: policy.maxSupplyBytes }); }
+  catch (error) { budgetError = error; }
+  const supplyBudget = { getState: () => budget?.getState() || null,
+    reserve: bytes => { if (!budget) throw budgetError; return budget.reserve(bytes); } };
+  const pair = await createSigningKeyPair(), lifetime = new AbortController(), sources = new Set();
+  const custodyKey = { peerId: transport._getPeerId(), publicKey: await exportPublicKey(pair.publicKey), privateKey: pair.privateKey };
+  const custodyCertificate = async () => certifyCustodyKey
+    ? certifyCustodyKey({ custodyPeerId: custodyKey.peerId, custodyPublicKey: custodyKey.publicKey }) : null;
+  const receipts = [], retained = new Map(), operations = new Set(), offeredFiles = new Map(), localPieces = new Map();
+  let closed = false, shareController = null, closing = null, suppliedModel = null;
+  const own = operation => { operations.add(operation); operation.finally(() => operations.delete(operation)).catch(() => {}); return operation; };
+  const readLocal = async (name, { offset, size, signal } = {}) => {
+    signal?.throwIfAborted(); assert(/^[\w.-]+$/.test(name), 'Plain model filename required');
+    let handle;
+    try {
+      const filename = await fs.realpath(path.join(root, name));
+      assert(path.dirname(filename) === root, 'Model file escapes approved directory');
+      handle = await fs.open(filename, constants.O_RDONLY | constants.O_NOFOLLOW);
+      const stat = await handle.stat(); assert(stat.isFile(), 'Regular model file required');
+      if (offset === undefined) { assert(stat.size <= policy.maxArtifactBytes, 'Native file exceeds artifact budget'); return new Uint8Array(await handle.readFile()); }
+      assert(Number.isSafeInteger(offset) && offset >= 0 && Number.isSafeInteger(size) && size > 0
+        && size <= policy.maxArtifactBytes && offset + size <= stat.size, 'Invalid assigned model piece');
+      const bytes = new Uint8Array(size); let received = 0;
+      while (received < size) { signal?.throwIfAborted(); const part = await handle.read(bytes, received, size - received, offset + received);
+        assert(part.bytesRead > 0, 'Truncated model piece'); received += part.bytesRead; }
+      return bytes;
+    } catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+    finally { await handle?.close(); }
+  };
+  const observe = receipt => { receipts.push(receipt); if (receipts.length > policy.maxReceipts) receipts.shift(); onChange(); };
+  // Transfer evidence with both parties' certificates, for whoever claims the delivery.
+  const deliveries = [], observeDelivery = record => { deliveries.push(record); if (deliveries.length > policy.maxReceipts) deliveries.shift(); };
+  const contracts = createCustodyContracts({ hashDopplerEvidence, validateExecutablePack, executablePacksMatch, sha256Hex, signCanonical, verifyCanonicalSignature });
+  const exchange = createCustodyExchange({ transport, identity: custodyKey, policy, ports: { supplyBudget,
+    createSupplier: contracts.createPeerPackSupplier, createStore: contracts.createPeerPackArtifactStore,
+    createChannel: owner ? owner.paceChannel(createPeerPackDataChannel) : createPeerPackDataChannel,
+    ...(owner ? { admitSupply: request => owner.admitSupply(request) } : {}), hash: hashDopplerEvidence, hashBytes: sha256Hex,
+    readArtifact: async file => {
+      const local = localPieces.get(key(file));
+      const bytes = await cache.get(file) || (local && await readLocal(local.path, { ...local, signal: lifetime.signal }));
+      assert(bytes, 'Advertised native bytes are unavailable'); await verify(file, bytes); return bytes;
+    },
+    verifyArtifact: verify, commitArtifact: (file, bytes, controls) => cache.put(file, bytes, controls), observe, onChange,
+    certificate: custodyCertificate, observeDelivery
+  } });
+  const readAvailableMetadata = async (file, signal) => {
+    signal.throwIfAborted(); let bytes = await cache.get(file);
+    // Capsule metadata paths are logical names, not paths inside the weight directory.
+    if (!bytes && /^[a-zA-Z0-9_.-]+$/.test(file.path)) bytes = await readLocal(file.path, { signal });
+    if (!bytes && /^\/config\/model-(manifests|pieces|artifacts)\/[a-zA-Z0-9_.-]+$/.test(file.url || '')) {
+      bytes = new Uint8Array(await fs.readFile(resolveServedFile(file.url)));
+    }
+    return bytes;
+  };
+  const readMetadata = async (file, signal) => {
+    let bytes = await readAvailableMetadata(file, signal);
+    if (!bytes) {
+      assert(exchange.has(file), 'No authorized peer offers required model metadata'); bytes = await exchange.acquire(file, { signal });
+    }
+    await verify(file, bytes); signal.throwIfAborted(); await cache.put(file, bytes, { signal }); retained.set(key(file), file); return bytes;
+  };
+  const metadata = async (model, signal) => {
+    const manifestFile = model.source.files.find(file => file.path === 'manifest.json');
+    const indexFile = model.source.files.find(file => file.role === 'model-piece-index');
+    assert(manifestFile && 'sha256:' + manifestFile.hash === model.identity && indexFile, 'Pinned manifest and piece index required');
+    const manifestBytes = await readMetadata(manifestFile, signal), indexBytes = await readMetadata(indexFile, signal);
+    const runtime = await import('doppler-gpu/partitions');
+    // Doppler validates the index closure before any piece is offered or read.
+    const checked = await runtime.createVerifiedPieceStorage({ manifestBytes, indexBytes, indexIdentity: 'sha256:' + indexFile.hash,
+      signal, acquire: () => { throw new Error('Metadata validation cannot acquire weights'); } });
+    await checked.storage.close();
+    return { runtime, manifestBytes, indexBytes, indexIdentity: 'sha256:' + indexFile.hash, manifest: checked.manifest,
+      index: JSON.parse(new TextDecoder().decode(indexBytes)) };
+  };
+  const getState = ({ includeReceipts = true } = {}) => ({ ...exchange.getState(), cache: cache.getState(),
+    supplyBudgetError: budgetError && { code: budgetError.code || 'CUSTODY_BUDGET_STORAGE', message: budgetError.message },
+    retainedFiles: retained.size, receiptCount: receipts.length,
+    ...(includeReceipts ? { receipts: structuredClone(receipts) } : {}) });
+  exchange.announce();
+  return Object.freeze({ getState, announce: () => exchange.announce(), custodyCertificate, getDeliveryEvidence: () => structuredClone(deliveries),
+    acquireAdapter(artifact, { signal }) {
+      return own((async () => {
+        const combined = AbortSignal.any([lifetime.signal, signal]);
+        combined.throwIfAborted();
+        assert(artifact.role === 'adapter', 'Adapter acquisition requires a pinned adapter artifact');
+        assert(Number.isSafeInteger(artifact.sizeBytes) && artifact.sizeBytes > 0
+          && artifact.sizeBytes <= policy.maxArtifactBytes, 'Adapter exceeds the file allowance');
+        const file = { ...artifact, hash: artifact.hash.replace(/^sha256:/, ''), hashAlgorithm: 'sha256' };
+        let bytes = await readAvailableMetadata(file, combined);
+        if (!bytes) bytes = exchange.has(file) ? await exchange.acquire(file, { signal: combined })
+          : await fetchAdapterFile(artifact, { signal: combined });
+        await verify(file, bytes); combined.throwIfAborted();
+        await cache.put(file, bytes, { signal: combined }); retained.set(key(file), file);
+        return bytes;
+      })());
+    },
+    preparePartitionSource(model, { signal } = {}) { return own((async () => {
+      signal = AbortSignal.any([lifetime.signal, ...(signal ? [signal] : [])]);
+      const data = await metadata(model, signal), descriptors = new Map(); signal.throwIfAborted();
+      const partitionOrigin = resolvePinnedOrigin(model, modelOrigins, originFetch);
+      for (const file of data.index.files) for (const piece of file.pieces) descriptors.set(piece.identity, { ...piece, path: file.path });
+      const acquisition = createPieceAcquisition({
+        limits: { maxConcurrent: policy.maxPieceAcquisitions, maxQueued: policy.maxQueuedPieceAcquisitions,
+          maxPieceBytes: policy.maxArtifactBytes,
+          timeoutMs: owner ? owner.pieceTimeoutMs(policy.channel.timeoutMs, policy.maxArtifactBytes) : policy.channel.timeoutMs },
+        cache: { get: async id => {
+          const piece = descriptors.get(id);
+          // Existing owner-approved files are reusable custody, not another cache download.
+          // createPieceAcquisition verifies these bytes before returning them.
+          return await cache.get(pieceFile(piece)) ?? await readLocal(piece.path, { ...piece, signal });
+        },
+          put: async (id, bytes) => {
+            const file = pieceFile(descriptors.get(id)); await cache.put(file, bytes, { signal }); retained.set(key(file), file);
+            if (!closed && suppliedModel === model.identity) {
+              assert(offeredFiles.has(key(file)) || offeredFiles.size < policy.maxInventoryFiles, 'Native inventory limit exceeded');
+              offeredFiles.set(key(file), file); exchange.offer([...offeredFiles.values()]);
+            }
+          } },
+        authorize: async () => !signal.aborted, foregroundIdle: async current => current.throwIfAborted(),
+        verify: async (piece, bytes) => bytes.byteLength === piece.size && 'sha256:' + digest(bytes) === piece.identity,
+        sources: piece => [
+          { id: 'approved-local-directory', read: async (_, controls) => {
+            const bytes = await readLocal(piece.path, { ...piece, signal: controls.signal }); assert(bytes, 'Assigned piece absent locally'); return bytes;
+          } },
+          { id: 'authorized-custody-peers', read: async (_, controls) => {
+            const file = pieceFile(piece);
+            if (exchange.has(file)) return exchange.acquire(file, controls);
+            const shard = data.manifest.shards.find(row => row.filename === piece.path);
+            const whole = shard ? { path: shard.filename, role: 'model-weights', sizeBytes: shard.size, hash: shard.hash, hashAlgorithm: data.manifest.hashAlgorithm }
+              : model.source.files.find(file => file.path === piece.path);
+            assert(whole, 'Piece is outside pinned model files');
+            assert(exchange.has(whole), 'No peer offers the assigned verified piece');
+            return exchange.acquire(whole, { ...controls, range: { offset: piece.offset, size: piece.size, identity: piece.identity } });
+          } },
+          ...(partitionOrigin ? [{ id: partitionOrigin.id, read: (_, controls) => readPinnedOrigin(partitionOrigin, piece.path,
+            { offset: piece.offset, size: piece.size, signal: controls.signal }) }] : [])
+        ] });
+      const abort = () => { acquisition.close().catch(() => {}); };
+      signal.addEventListener('abort', abort, { once: true });
+      let opened;
+      try {
+        opened = await data.runtime.createVerifiedPieceStorage({ ...data, signal,
+          acquire: (piece, controls) => acquisition.acquire(piece, controls) });
+      } catch (error) {
+        signal.removeEventListener('abort', abort);
+        try { await acquisition.close(); }
+        catch (cleanup) { throw new AggregateError([error, cleanup], 'Native source opening and cleanup failed'); }
+        throw error;
+      }
+      let sourceClosed = false;
+      const admittedFile = artifact => {
+        assert(!sourceClosed && !closed, 'Partition artifact source is closed');
+        return resolvePartitionArtifactSource(model, data.manifest, model.source.files, artifact);
+      };
+      const artifactStore = Object.freeze({
+        async readArtifact(artifact, controls = {}) {
+          const file = admittedFile(artifact);
+          assert(!data.manifest.shards.some(row => row.filename === file.path), 'Native weights require complete pinned piece ranges');
+          return readMetadata(file, AbortSignal.any([signal, controls.signal].filter(Boolean)));
+        },
+        async readArtifactRange(artifact, offset, size, controls = {}) {
+          const file = admittedFile(artifact);
+          const piece = data.index.files.find(row => row.path === file.path)?.pieces
+            .find(piece => piece.offset === offset && piece.size === size);
+          assert(piece, 'Capsule range is not a complete pinned piece');
+          return acquisition.acquire({ ...piece, path: file.path }, {
+            ...controls, signal: AbortSignal.any([signal, controls.signal].filter(Boolean)) });
+        }
+      });
+      const source = { manifest: opened.manifest, artifactStore,
+        storage: { ...opened.storage, async close() {
+          sourceClosed = true;
+          signal.removeEventListener('abort', abort);
+          try {
+            const settled = await Promise.allSettled([Promise.resolve().then(() => acquisition.close()), Promise.resolve().then(() => opened.storage.close())]);
+            const failures = settled.filter(result => result.status === 'rejected').map(result => result.reason);
+            if (failures.length) throw new AggregateError(failures, 'Native partition source cleanup failed');
+          } finally { sources.delete(source); }
+        } }, getReceipt: () => ({ ...opened.getReceipt(), custody: acquisition.getReceipt() }) };
+      sources.add(source); return source;
+    })()); },
+    /** Completes the model directory for whole-model execution from authorized peers. A complete
+     * directory is left untouched. Pieces come from the verified cache or authorized custody peers
+     * only; the fill verifies each piece and each assembled file. Until some supplier has
+     * delivered, it waits for one; afterwards a piece no connected supplier offers within one
+     * channel timeout fails the fill. */
+    fillWholeModel(model, { signal, onProgress = () => {} } = {}) { return own((async () => {
+      signal = AbortSignal.any([lifetime.signal, ...(signal ? [signal] : [])]);
+      if (await wholeModelDirectoryComplete(root, model)) return { complete: true, filled: false };
+      const data = await metadata(model, signal);
+      const origin = resolvePinnedOrigin(model, modelOrigins, originFetch), graceUntil = Date.now() + peerGraceMs;
+      let supplied = false, waiting = false, originAnnounced = false;
+      const peerOffers = (file, whole) => exchange.has(file) || Boolean(whole && exchange.has(whole));
+      // Peers are preferred. Without a pinned origin the fill waits for a first supplier and then
+      // allows one channel timeout per piece; with one, it waits only a short grace for peers to announce.
+      const awaitPeers = async (file, whole) => {
+        const deadline = origin ? (supplied ? 0 : graceUntil)
+          : supplied ? Date.now() + (owner ? owner.pieceTimeoutMs(policy.channel.timeoutMs, policy.maxArtifactBytes) : policy.channel.timeoutMs) : Infinity;
+        while (!peerOffers(file, whole)) {
+          signal.throwIfAborted();
+          if (Date.now() >= deadline) {
+            assert(origin, `No authorized peer offers piece ${file.hash} of ${whole?.path ?? file.path}`);
+            return false;
+          }
+          if (!waiting) { waiting = true; onProgress({ phase: 'waiting-for-supplier' }); }
+          exchange.announce(); await new Promise(resolve => setTimeout(resolve, 1000));
+        }
+        waiting = false; return true;
+      };
+      const fromOrigin = async (name, range, reason) => {
+        if (!originAnnounced) { originAnnounced = true; onProgress({ phase: 'source', source: origin.id, origin: origin.label, reason }); }
+        return { bytes: await readPinnedOrigin(origin, name, { ...range, signal }), source: origin.id };
+      };
+      const acquire = async (piece, controls) => {
+        const file = pieceFile(piece), cached = await cache.get(file);
+        if (cached) return { bytes: cached, source: 'verified-cache' };
+        const shard = data.manifest.shards.find(row => row.filename === piece.path);
+        const whole = shard ? { path: shard.filename, role: 'model-weights', sizeBytes: shard.size, hash: shard.hash, hashAlgorithm: data.manifest.hashAlgorithm } : null;
+        let reason = 'no authorized peer offers the piece';
+        if (await awaitPeers(file, whole)) {
+          try {
+            const bytes = exchange.has(file) ? await exchange.acquire(file, controls)
+              : await exchange.acquire(whole, { ...controls, range: { offset: piece.offset, size: piece.size, identity: piece.identity } });
+            supplied = true; return { bytes, source: 'authorized-custody-peers' };
+          } catch (error) {
+            if (!origin || signal.aborted) throw error;
+            reason = 'authorized peers failed: ' + error.message;
+            onProgress({ phase: 'source-failed', source: 'authorized-custody-peers', piece: piece.identity, error: error.message });
+          }
+        }
+        return fromOrigin(piece.path, { offset: piece.offset, size: piece.size }, reason);
+      };
+      const readPinned = async (file, current) => {
+        try { return await readMetadata(file, current); }
+        catch (error) {
+          // The manifest is always the bundled pinned copy, never an origin's.
+          if (!origin || file.path === 'manifest.json' || current.aborted) throw error;
+          const read = await fromOrigin(file.path, { size: file.sizeBytes, whole: true }, error.message);
+          await verify(file, read.bytes); return read;
+        }
+      };
+      const result = await fillWholeModelDirectory({ root, model, manifest: data.manifest, index: data.index, signal, onProgress, acquire,
+        // The same piece concurrency as partition acquisition: one peer channel admits few pending chunk requests.
+        concurrency: policy.maxPieceAcquisitions,
+        readMetadata: readPinned,
+        release: async file => { for (const piece of file.pieces) await cache.remove(pieceFile(piece)); },
+        freeBytes: async directory => { const stat = await fs.statfs(directory); return stat.bavail * stat.bsize; } });
+      return { complete: true, filled: true, ...result };
+    })()); },
+    share(model, approved) { return own((async () => {
+      assert(approved === true && !closed, 'Approve file contribution separately from compute');
+      if (budgetError) throw budgetError;
+      assert(!shareController, 'File inventory preparation already active');
+      const controller = new AbortController(); shareController = controller;
+      const signal = AbortSignal.any([lifetime.signal, controller.signal]);
+      try {
+        const data = await metadata(model, signal), offered = [], approvedLocalPieces = new Map();
+        for (const file of [...model.source.files, ...(model.adapters || []).map(adapter => ({ ...adapter.artifact, hash: adapter.artifact.hash.replace(/^sha256:/, ''), hashAlgorithm: 'sha256' }))]) {
+          // Program/evidence metadata ships in the application. Custody offers
+          // manifest-local model files and verified pieces, never nested program paths.
+          if (!/^[a-zA-Z0-9_.-]+$/.test(file.path)) continue;
+          const bytes = await readAvailableMetadata(file, signal);
+          if (bytes) { await verify(file, bytes); await cache.put(file, bytes, { signal }); offered.push(file); }
+        }
+        for (const file of data.index.files) for (const piece of file.pieces) {
+          signal.throwIfAborted(); const descriptor = pieceFile(piece);
+          const cached = await cache.get(descriptor);
+          const bytes = cached || await readLocal(file.path, { ...piece, signal });
+          if (!bytes) continue;
+          await verify(descriptor, bytes);
+          if (!cached) approvedLocalPieces.set(key(descriptor), { ...piece, path: file.path });
+          offered.push(descriptor); assert(offered.length <= policy.maxInventoryFiles, 'Native inventory limit exceeded');
+        }
+        signal.throwIfAborted(); offeredFiles.clear(); localPieces.clear();
+        for (const [id, piece] of approvedLocalPieces) localPieces.set(id, piece);
+        for (const file of offered) offeredFiles.set(key(file), file);
+        suppliedModel = model.identity; exchange.offer(offered); return getState();
+      } finally { if (shareController === controller) shareController = null; }
+    })()); },
+    stopSupply() { suppliedModel = null; offeredFiles.clear(); localPieces.clear(); shareController?.abort(new Error('Native file contribution stopped')); exchange.stopSupply(); },
+    close() { return closing ||= (async () => {
+      closed = true; suppliedModel = null; offeredFiles.clear(); localPieces.clear(); lifetime.abort(new Error('Native file host closed')); exchange.stopSupply();
+      await Promise.allSettled([...operations]);
+      const settled = await Promise.allSettled([...sources].map(source => Promise.resolve().then(() => source.storage.close()))
+        .concat([Promise.resolve().then(() => exchange.close()), Promise.resolve().then(() => cache.close()), Promise.resolve().then(() => budget?.close())]));
+      const failures = settled.filter(result => result.status === 'rejected').map(result => result.reason);
+      if (failures.length) throw new AggregateError(failures, 'Native artifact source cleanup failed');
+    })(); }
+  });
+}

package/server/native-model-origin.js

@@ -0,0 +1,54 @@
+/** Pinned public origin for model files: the last source after the approved local directory and
+ * authorized custody peers. The origin is fixed here per exact model identity (repository and
+ * immutable revision), never taken from peers or requests, and fetched without credentials.
+ * Callers verify every byte against pinned piece identities or file hashes; this module only
+ * bounds what it returns. The manifest never comes from an origin: the bundled pinned copy is used. */
+import origins from './native-model-origins.json' with { type: 'json' };
+
+const assert = (ok, message, code = 'MODEL_ORIGIN_INVALID') => { if (!ok) throw Object.assign(new Error(message), { code }); };
+export const PINNED_ORIGIN_SOURCE = 'pinned-origin';
+
+/** The pinned origin for this exact model, or null. `table` and `fetch` replace the shipped pins and
+ * the network in tests. */
+export function resolvePinnedOrigin(model, table = origins, fetch = (...args) => globalThis.fetch(...args)) {
+  assert(table?.schema === 'reploid.native-model-origins/v1', 'Unknown model origin table');
+  const pin = table.origins?.[model?.id];
+  if (!pin) return null;
+  assert(pin.modelIdentity === model.identity, 'Pinned origin names another model identity');
+  assert(pin.kind === 'huggingface' && /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(pin.repoId)
+    && /^[a-f0-9]{40}$/.test(pin.revision) && typeof pin.path === 'string'
+    && pin.path.split('/').every(part => /^[A-Za-z0-9_.-]+$/.test(part) && !/^\.\.?$/.test(part)), 'Pinned origin must name a repository, an immutable revision and a plain path');
+  const base = `https://huggingface.co/${pin.repoId}/resolve/${pin.revision}/${pin.path}/`;
+  return Object.freeze({ id: `${PINNED_ORIGIN_SOURCE}:huggingface`, label: `huggingface:${pin.repoId}@${pin.revision}/${pin.path}`, fetch,
+    url: name => { assert(/^[A-Za-z0-9_.-]+$/.test(name) && !/^\.\.?$/.test(name), 'Plain model filename required'); return base + name; } });
+}
+
+/** Reads `size` bytes at `offset` of `name` (a range request), or the whole file when `whole` is
+ * set. Returns exactly the requested length or throws. Credentials and cookies are never sent. */
+export async function readPinnedOrigin(origin, name, { offset = 0, size, whole = false, signal, fetch = origin.fetch }) {
+  assert(Number.isSafeInteger(offset) && offset >= 0 && Number.isSafeInteger(size) && size > 0, 'Explicit origin range required');
+  const response = await fetch(origin.url(name), { signal, credentials: 'omit', redirect: 'follow', cache: 'no-store',
+    headers: whole ? {} : { range: `bytes=${offset}-${offset + size - 1}` } });
+  const ranged = response.status === 206, complete = response.status === 200 && (whole || offset === 0);
+  if (!ranged && !complete) { await response.body?.cancel(); assert(false, `Pinned origin answered ${response.status} for ${name}`, 'MODEL_ORIGIN_UNAVAILABLE'); }
+  if (ranged) {
+    const match = /^bytes (\d+)-(\d+)\/(\d+|\*)$/.exec(response.headers.get('content-range') || '');
+    if (!match || Number(match[1]) !== offset || Number(match[2]) !== offset + size - 1) {
+      await response.body?.cancel(); assert(false, `Pinned origin returned another range of ${name}`, 'MODEL_ORIGIN_RANGE');
+    }
+  }
+  const bytes = new Uint8Array(size); let received = 0;
+  const reader = response.body.getReader();
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      const take = Math.min(value.byteLength, size - received);
+      bytes.set(value.subarray(0, take), received); received += take;
+      // A whole-file answer to a range request at offset 0 is cut to the requested length.
+      if (received === size) { if (ranged || whole) assert((await reader.read()).done, `Pinned origin sent more than ${size} bytes of ${name}`, 'MODEL_ORIGIN_RANGE'); break; }
+    }
+  } finally { await reader.cancel().catch(() => {}); }
+  assert(received === size, `Pinned origin sent ${received} of ${size} bytes of ${name}`, 'MODEL_ORIGIN_RANGE');
+  return bytes;
+}

package/server/native-model-origins.json

@@ -0,0 +1,12 @@
+{
+  "schema": "reploid.native-model-origins/v1",
+  "origins": {
+    "qwen-3-5-2b-q4k-ehaf16": {
+      "modelIdentity": "sha256:a0dc69e917133a82780823d17fc771c0f6b882d7c86c571deeaef45be2ff108b",
+      "kind": "huggingface",
+      "repoId": "clocksmith/rdrr",
+      "revision": "3a05b346b1c86abf02c7620f2369a9a7b82cb62f",
+      "path": "models/qwen-3-5-2b-q4k-ehaf16"
+    }
+  }
+}

package/server/native-node.js

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+/**
+ * One short command for a native participant: `reploid <catalog model id>`.
+ * It only fills in the conventional values the participant otherwise asks for
+ * (state under ~/.reploid, the supported transport and GPU packages) and says
+ * what it chose. The participant, its consent rules and its checks are unchanged.
+ */
+import { realpathSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+
+const MODES = ['--connect-only', '--share-files', '--contribute'];
+// The model `reploid` serves when no model id is given: the one public peers supply.
+export const DEFAULT_MODEL = 'qwen-3-5-2b-q4k-ehaf16';
+// Options that only exist for partition execution; giving one keeps the participant's own default.
+const PARTITION_ONLY = ['--partition-index', '--ordered-config', '--canonical', '--readiness-log'];
+const USAGE = `Reploid node (Node 22.13 or newer)
+Usage: reploid [catalog model id] [participant options]
+
+  reploid                          (same as: reploid qwen-3-5-2b-q4k-ehaf16)
+  reploid qwen-3-5-2b-q4k-ehaf16
+
+Contributes this computer's GPU for that model and runs the whole model here,
+so it serves requests on its own. A model not yet on this computer is fetched
+from authorized peers piece by piece (or, when no peer offers a piece, from the
+model's pinned public origin), each piece and each file verified against the
+catalog, into ~/.reploid/weights/<model id>; an interrupted fetch resumes.
+
+Chosen for you unless given: --contribute, --execution-mode whole-model,
+--model-directory ~/.reploid/weights/<model id>, --identity-file
+~/.reploid/identity.json, --rtc-module @roamhq/wrtc, --ws-module ws,
+--gpu-module webgpu. --execution-mode partition (or a partition-only option
+such as --partition-index) shares the model with other contributors instead.
+Pass --connect-only or --share-files to choose another mode. Every other option
+goes to the participant unchanged: run reploid-participant --help for the full
+list. Stop with Ctrl+C.`;
+
+/** The participant arguments this command stands for. Pure, so it can be checked. */
+export function nodeArguments(argv, { home }) {
+  // Without a model id (nothing, or options only) the default model is served.
+  const [model, ...rest] = argv.length && !argv[0].startsWith('-') ? argv : [DEFAULT_MODEL, ...argv];
+  const given = name => rest.includes(name) || rest.some(value => value.startsWith(name + '='));
+  const state = path.join(home, '.reploid');
+  const args = ['--model', model];
+  const chosen = {};
+  if (!MODES.some(given)) { args.push('--contribute'); chosen.mode = 'contribute'; }
+  const contributes = !MODES.some(given) || given('--contribute');
+  const fill = (name, value) => { if (!given(name)) { args.push(name, value); chosen[name.slice(2)] = value; } };
+  if (contributes && !PARTITION_ONLY.some(given)) fill('--execution-mode', 'whole-model');
+  // One directory per model: catalog models share file names such as manifest.json.
+  fill('--model-directory', path.join(state, 'weights', model));
+  fill('--identity-file', path.join(state, 'identity.json'));
+  fill('--rtc-module', '@roamhq/wrtc');
+  fill('--ws-module', 'ws');
+  // The participant requires a GPU provider only for compute.
+  if (!given('--connect-only') && !(given('--share-files') && !given('--contribute'))) fill('--gpu-module', 'webgpu');
+  return { model, args: [...args, ...rest], chosen };
+}
+
+/** The process arguments the participant parses. The entry path stays this command's: the participant
+ * module starts itself when the entry path is its own file, so naming it here ran a second participant
+ * after the first one stopped on SIGINT or SIGTERM. */
+export function participantProcessArgv(processArgv, args) {
+  return [processArgv[0], processArgv[1], ...args];
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  if (argv.includes('--help') || argv.includes('-h')) { console.log(USAGE); return; }
+  const node = nodeArguments(argv, { home: os.homedir() });
+  console.log(JSON.stringify({ event: 'reploid-node', model: node.model, chosen: node.chosen }));
+  const { mkdir } = await import('node:fs/promises');
+  // The participant reads weights from an existing directory; it creates the identity's.
+  const directory = node.args[node.args.indexOf('--model-directory') + 1];
+  if (directory) await mkdir(directory, { recursive: true });
+  process.argv = participantProcessArgv(process.argv, node.args);
+  const { main: runParticipant } = await import('./native-participant.js');
+  await runParticipant();
+}
+
+// npm starts a package command through a symbolic link; compare real paths.
+const entered = (() => { try { return Boolean(process.argv[1]) && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url); } catch { return false; } })();
+if (entered) await main();