reploid 0.0.0-stage → 0.1.1

package/packages/reploid/src/mesh/partitions/partition-peer.js

@@ -0,0 +1,314 @@
+import { createOrderedPartitionPeer } from './partition-ordered-peer.js';
+import failureMessages from '../../transport/partition-errors.json' with { type: 'json' };
+import { createPartitionDataChannel } from '../../transport/partition-data-channel.js';
+import { createCanonicalPartitionContract } from './partition-canonical-contract.js';
+import { createPartitionStepReceiver } from './partition-step-receiver.js';
+import { assertPartition as assert, samePartitionIdentity, partitionFingerprint,
+  partitionActivationContract, matchingPartitionActivation } from './partition-contract.js';
+
+/** Authenticated A-to-B partition RPC. Hosts establish channel identities before constructing it. */
+export function createPartitionPeer({ channel, localParticipantId, remoteParticipantId, runtime, plan, planId,
+  modelIdentity, authority, contributor = null, limits, receiverLimits, canonical = false, ordered = null }) {
+  if (ordered) return createOrderedPartitionPeer({ channel, localParticipantId, remoteParticipantId, runtime, plan, planId,
+    modelIdentity, authority, contributor, limits, receiverLimits, canonical, ordered });
+  plan = structuredClone(plan); receiverLimits = structuredClone(receiverLimits);
+  assert(runtime?.deserializeActivationFrame && authority?.verify, 'Partition codecs and grant verifier required');
+  const activationContract = partitionActivationContract(runtime, plan);
+  assert(!contributor || contributor.index === 1 && contributor.id === localParticipantId, 'Remote serving requires the local B contributor');
+  assert(typeof canonical === 'boolean', 'Explicit canonical peer capability flag required');
+  const canonicalContract = canonical ? createCanonicalPartitionContract({ runtime, plan, planId, modelIdentity }) : null;
+  const canonicalStage = canonical && contributor ? contributor.getCanonicalStage() : null;
+  assert(!canonical || !contributor || canonicalStage?.participantId === localParticipantId && canonicalStage.partitionIndex === 1,
+    'Canonical serving requires the bound stage signing authority');
+  const active = new Map(), outputCharacters = new Map(), listeners = new Set();
+  const reservations = new Map();
+  let remoteDescriptor = null, remoteCanonical = null, closing = null;
+  const canonicalRequest = metadata => canonicalContract !== null && metadata.schema === canonicalContract.schema;
+  const binding = identity => identity?.modelId === plan.modelId && identity.modelIdentity === modelIdentity
+    && identity.planId === planId;
+  const validFrame = metadata => {
+    const frame = metadata.frame;
+    return Number.isSafeInteger(metadata.maxTokens) && metadata.maxTokens > 0
+      && metadata.maxTokens <= metadata.grant?.claim?.limits?.maxTokens && metadata.step < metadata.maxTokens
+      && frame?.schema === activationContract.schema && matchingPartitionActivation(frame, activationContract, true)
+      && frame.step === metadata.step && frame.seqOffset === metadata.tokenPosition
+      && Array.isArray(frame.shape) && frame.shape.length === 3 && frame.shape[0] === 1
+      && frame.shape[1] === metadata.inputTokenCount && frame.shape[2] === plan.hiddenSize
+      && Number.isSafeInteger(frame.byteLength) && frame.byteLength > 0
+      && frame.byteLength === frame.shape[1] * frame.shape[2] * activationContract.elementStrideBytes
+      && samePartitionIdentity(frame.metadata, metadata.identity)
+      && frame.metadata.maxTokens === metadata.maxTokens
+      && frame.metadata.generationDigest === metadata.generationDigest
+      && metadata.generation?.maxTokens === metadata.maxTokens
+      && Array.isArray(metadata.inputTokenIds) && metadata.inputTokenIds.length === metadata.inputTokenCount
+      && metadata.inputTokenIds.every(id => Number.isSafeInteger(id) && id >= 0 && id < plan.vocabSize)
+      && frame.metadata.from === metadata.identity.participantA && frame.metadata.to === metadata.identity.participantB;
+  };
+  const verify = async (metadata, action, settlement = false) => {
+    if (metadata.schema !== undefined) {
+      if (!canonicalRequest(metadata)) return false;
+      try {
+        const attempt = canonicalContract.validateBinding(metadata);
+        const observed = contributor ? { stage: canonicalStage, generation: contributor.getCanonicalGeneration() } : remoteCanonical;
+        if (!observed || runtime.metadataDigest('reploid.canonical-stage/v1', attempt.stages[1])
+          !== runtime.metadataDigest('reploid.canonical-stage/v1', observed.stage)
+          || runtime.metadataDigest('reploid.canonical-generation/v1', metadata.grant.claim.generation)
+            !== runtime.metadataDigest('reploid.canonical-generation/v1', observed.generation)) return false;
+      } catch { return false; }
+      const phase = metadata.operation === 'reserve' || metadata.operation === 'admit'
+        || metadata.publication?.schema === 'doppler.admission-publication/v1' ? 'admit' : 'step';
+      const request = { identity: metadata.identity, canonicalAttempt: metadata.canonicalAttempt,
+        generationId: metadata.generationId, phase, step: metadata.step,
+        ...(metadata.inputTokenCount === undefined ? {} : { inputTokenCount: metadata.inputTokenCount }),
+        ...(metadata.frame ? { activationBytes: metadata.frame.byteLength } : {}) };
+      if (!await authority.verify(metadata.grant, { ...request, action }, { settlement })) return false;
+      return settlement || authority.verify(metadata.grant, { ...request, action: 'mesh.transfer_token_context' });
+    }
+    if (!settlement && (!metadata.generation || await partitionFingerprint(metadata.generation) !== metadata.generationDigest)) return false;
+    const request = { identity: metadata.identity, step: metadata.step, inputTokenCount: metadata.inputTokenCount,
+      generationDigest: metadata.generationDigest, activationBytes: metadata.frame?.byteLength };
+    if (!await authority.verify(metadata.grant, { ...request, action }, { settlement })) return false;
+    return settlement || authority.verify(metadata.grant, { ...request, action: 'mesh.transfer_token_context' });
+  };
+  const receiver = createPartitionStepReceiver({ limits: receiverLimits,
+    canonical: canonicalStage ? { runtime, stage: canonicalStage, now: () => performance.now(),
+      verifyPublication: (request, retained) => canonicalContract.verifyPublication(request, retained),
+      execute: async (request, { signal }) => {
+        assert(contributor.canAccept(request.identity), 'Canonical output contributor is not ready');
+        if (request.phase === 'admit') return contributor.admitCanonicalPrompt({ identity: request.identity,
+          tokenIds: request.inputTokenIds, generationId: request.generationId, signal });
+        const activation = canonicalContract.validatePayload(request, request.payload);
+        const result = await contributor.executeCanonicalGroup1({ identity: request.identity, canonicalAttempt: request.canonicalAttempt,
+          sequence: request.sequence, generationId: request.generationId, baseCursorId: request.baseCursorId,
+          step: request.step, tokenPosition: request.tokenPosition, inputTokenCount: request.inputTokenCount,
+          inputTokenIds: request.inputTokenIds, activation, continuation: request.continuation, signal,
+          executionGrant: request.grant, outputGrant: request.grant });
+        assert(result?.commit && result.transition, 'Canonical output stage did not return its authenticated transition');
+        const { logits: _logits, ...output } = result;
+        return output;
+      } } : undefined,
+    authorize: request => verify(request, 'mesh.execute_partition_b'),
+    fingerprint: request => {
+      if (canonicalRequest(request)) return canonicalContract.fingerprint(request);
+      const { payload, ...metadata } = request;
+      return partitionFingerprint(metadata, payload);
+    },
+    executeStep: async (request, { signal }) => {
+      assert(contributor?.canAccept ? contributor.canAccept(request.identity) : contributor?.getState().ready, 'Partition B is not ready');
+      const frame = { ...request.frame, buffer: request.payload.slice().buffer };
+      const activation = runtime.validateActivationFrameForPlan
+        ? runtime.validateActivationFrameForPlan(frame, plan) : runtime.deserializeActivationFrame(frame);
+      const result = await contributor.executeGroup1({ identity: request.identity,
+        step: request.step, tokenPosition: request.tokenPosition, inputTokenCount: request.inputTokenCount,
+        maxTokens: request.maxTokens,
+        generation: request.generation, inputTokenIds: request.inputTokenIds,
+        activation, continuation: request.continuation, signal,
+        executionGrant: request.grant, outputGrant: request.grant });
+      assert(samePartitionIdentity(result?.identity, request.identity) && result.step === request.step
+        && result.tokenPosition === request.tokenPosition && Number.isSafeInteger(result.tokenId)
+        && result.tokenId >= 0 && result.tokenId < plan.vocabSize && typeof result.done === 'boolean'
+        && typeof result.delta === 'string' && result.delta.length <= request.grant.claim.limits.maxOutputCharacters,
+      'Doppler partition response identity or token mismatch');
+      const total = (outputCharacters.get(request.identity.attemptId) || 0) + result.delta.length;
+      if (total > request.grant.claim.limits.maxOutputCharacters) {
+        throw Object.assign(new Error('Partition output budget exhausted'), { code: 'OUTPUT_LIMIT_EXCEEDED' });
+      }
+      outputCharacters.set(request.identity.attemptId, total);
+      // Large diagnostic logits stay at B; the peer protocol returns one token and bounded continuation.
+      const { logits: _logits, ...output } = result;
+      return output;
+    },
+    settleAttempt: async identity => {
+      try { await contributor?.closeAttempt({ identity }); }
+      finally { outputCharacters.delete(identity.attemptId); }
+    },
+  });
+  const notify = () => { for (const listener of listeners) { try { listener(getState()); } catch {} } };
+  const endpoint = createPartitionDataChannel({ channel, localParticipantId, remoteParticipantId, limits,
+    async authorize({ action, metadata, byteLength }) {
+      if (metadata.operation === 'describe') return byteLength === 0;
+      if (!binding(metadata.identity)) return false;
+      const outbound = action === 'send' || action === 'accept';
+      if (metadata.identity.participantA !== (outbound ? localParticipantId : remoteParticipantId)
+        || metadata.identity.participantB !== (outbound ? remoteParticipantId : localParticipantId)) return false;
+      if (metadata.schema !== undefined) {
+        if (!canonicalRequest(metadata) || metadata.operation !== 'step' && !canonicalContract.validateControl(metadata)) return false;
+        if (metadata.operation === 'settle') return byteLength === 0 && verify(metadata, 'mesh.execute_partition_b', true);
+        if (!['reserve', 'admit', 'step', 'published'].includes(metadata.operation)) return false;
+        if (metadata.operation === 'step') {
+          if (!canonicalContract.validateHeader(metadata, byteLength)) return false;
+        } else if (byteLength !== 0) return false;
+        if (metadata.operation === 'admit') {
+          try {
+            if (metadata.phase !== 'admit' || metadata.sequence !== 0 || metadata.tokenPosition !== 0
+              || metadata.inputTokenIds?.length !== metadata.inputTokenCount
+              || runtime.tokenDigest(metadata.inputTokenIds, plan.vocabSize, metadata.grant.claim.limits.maxPromptTokens)
+                !== metadata.canonicalAttempt.inputDigest) return false;
+          } catch { return false; }
+        }
+        if (!outbound && metadata.operation !== 'reserve' && !reservations.has(metadata.identity.attemptId)) return false;
+        return verify(metadata, action === 'respond' || action === 'accept' ? 'mesh.transfer_partition_output'
+          : metadata.operation === 'step' ? 'mesh.transfer_intermediate_activation' : 'mesh.execute_partition_b');
+      }
+      if (metadata.operation === 'settle') return byteLength === 0 && verify(metadata, 'mesh.execute_partition_b', true);
+      if (metadata.operation === 'reserve') return byteLength === 0 && verify(metadata, 'mesh.execute_partition_b');
+      if (metadata.operation !== 'step' || !validFrame(metadata) || metadata.frame.byteLength !== byteLength) return false;
+      const allowed = await verify(metadata, action === 'respond' || action === 'accept'
+        ? 'mesh.transfer_partition_output' : 'mesh.transfer_intermediate_activation');
+      if (!allowed) return false;
+      if (!outbound && !(contributor?.canAccept ? contributor.canAccept(metadata.identity) : contributor?.getState().ready)) {
+        throw Object.assign(new Error(failureMessages.CAPACITY_UNAVAILABLE), { code: 'CAPACITY_UNAVAILABLE' });
+      }
+      return true;
+    },
+    async serve(metadata, payload, { signal }) {
+      if (metadata.operation === 'describe') return { descriptor: contributor?.getState().ready ? contributor.getState().descriptor : null,
+        ...(canonical ? { canonical: contributor?.getState().ready ? { stage: canonicalStage,
+          generation: contributor.getCanonicalGeneration() } : null } : {}) };
+      if (metadata.operation === 'reserve') {
+        if (closing || !reservations.has(metadata.identity.attemptId) && reservations.size >= receiverLimits.maxAttempts) {
+          return { accepted: false, code: 'CAPACITY_UNAVAILABLE' };
+        }
+        signal.throwIfAborted();
+        let reservation;
+        try { reservation = contributor.reserve(metadata.identity); }
+        catch (cause) {
+          if (cause?.code === 'CAPACITY_UNAVAILABLE') return { accepted: false, code: 'CAPACITY_UNAVAILABLE' };
+          throw cause;
+        }
+        reservations.set(metadata.identity.attemptId, structuredClone(metadata.identity));
+        return { accepted: true, reservation };
+      }
+      if (metadata.operation === 'settle') {
+        try {
+          await receiver.closeAttempt(metadata.identity);
+          await contributor.closeAttempt({ identity: metadata.identity });
+        } catch (cause) {
+          throw Object.assign(new Error(failureMessages.CLEANUP_FAILED, { cause }), { code: 'CLEANUP_FAILED' });
+        }
+        reservations.delete(metadata.identity.attemptId);
+        return { settled: true };
+      }
+      return canonicalRequest(metadata) ? receiver.receiveCanonical(metadata.operation === 'step' ? { ...metadata, payload } : metadata, { signal })
+        : receiver.receive({ ...metadata, payload }, { signal });
+    },
+  });
+  const getState = () => ({ ready: channel.readyState === 'open' && remoteDescriptor?.ready === true && (!canonical || remoteCanonical !== null),
+    descriptor: structuredClone(remoteDescriptor), participantId: remoteParticipantId, receipt: endpoint.getReceipt() });
+  const close = () => {
+    if (closing) return closing;
+    closing = (async () => {
+      const results = await Promise.allSettled([receiver.close(), ...[...reservations.values()]
+        .map(identity => Promise.resolve().then(async () => {
+          await contributor.closeAttempt({ identity }); reservations.delete(identity.attemptId);
+        }))]);
+      const failures = results.filter(result => result.status === 'rejected').map(result => result.reason);
+      if (failures.length) throw new AggregateError(failures, 'Partition peer settlement failed');
+    })();
+    const operation = closing;
+    operation.catch(() => { if (closing === operation) closing = null; });
+    endpoint.close(); remoteDescriptor = null; remoteCanonical = null; active.clear();
+    notify(); return operation;
+  };
+  const disconnected = () => { close().catch(() => {}); };
+  channel.addEventListener('close', disconnected, { once: true });
+  return Object.freeze({
+    id: remoteParticipantId, getState,
+    getCanonicalGeneration: () => structuredClone(remoteCanonical?.generation ?? null),
+    getCanonicalStage: () => structuredClone(remoteCanonical?.stage ?? null),
+    async reserveCanonical(request) {
+      assert(canonical && remoteCanonical && !active.has(request.identity.attemptId) && active.size < receiverLimits.maxAttempts,
+        'Canonical remote reservation unavailable');
+      const { signal, ...input } = request;
+      const metadata = { ...structuredClone(input), schema: canonicalContract.schema, operation: 'reserve', phase: 'admit' };
+      canonicalContract.validateBinding(metadata);
+      active.set(request.identity.attemptId, structuredClone(metadata));
+      const result = await endpoint.request(metadata, new Uint8Array(), { signal });
+      assert(result.accepted === true && samePartitionIdentity(result.reservation?.identity, request.identity)
+        && result.reservation.participantId === remoteParticipantId && result.reservation.index === 1
+        && result.reservation.phase === 'reserved' && result.reservation.resources?.attemptSlots === 1,
+      'Canonical remote reservation rejected');
+      return { reservation: result.reservation };
+    },
+    async admitCanonicalPrompt(request) {
+      const { signal, ...input } = request;
+      assert(canonical && active.has(input.identity.attemptId), 'Canonical remote attempt is not reserved');
+      const metadata = { ...structuredClone(input), schema: canonicalContract.schema, operation: 'admit', phase: 'admit' };
+      return endpoint.request(metadata, new Uint8Array(), { signal });
+    },
+    async executeCanonicalFrame({ frame, signal, ...input }) {
+      assert(canonical && active.has(input.identity.attemptId), 'Canonical remote attempt is not reserved');
+      const { buffer, ...header } = frame;
+      const metadata = { ...structuredClone(input), schema: canonicalContract.schema, operation: 'step', phase: 'step', frame: header };
+      assert(canonicalContract.validateHeader(metadata, buffer.byteLength), 'Canonical outgoing activation rejected');
+      return endpoint.request(metadata, new Uint8Array(buffer), { signal });
+    },
+    async acknowledgeCanonicalPublication(request) {
+      const { signal, ...input } = request;
+      assert(canonical && active.has(input.identity.attemptId), 'Canonical remote attempt is not reserved');
+      const metadata = { ...structuredClone(input), schema: canonicalContract.schema, operation: 'published', phase: 'published' };
+      const receipt = await endpoint.request(metadata, new Uint8Array(), { signal });
+      assert(runtime.metadataDigest('reploid.publication-ack/v1', receipt)
+        === runtime.metadataDigest('reploid.publication-ack/v1', metadata.receipt), 'Canonical publication acknowledgment mismatch');
+      return receipt;
+    },
+    async reserve({ identity, grant, generation, generationDigest, inputTokenCount, signal }) {
+      assert(!active.has(identity.attemptId), 'Remote attempt already reserved');
+      assert(active.size < receiverLimits.maxAttempts, 'Remote attempt budget exhausted');
+      const metadata = { operation: 'reserve', identity, grant, generation, generationDigest, inputTokenCount, step: 0 };
+      active.set(identity.attemptId, structuredClone(metadata));
+      const result = await endpoint.request(metadata, new Uint8Array(), { signal });
+      if (result.accepted !== true) {
+        // Old peers may return a reason string; never expose remote exception text.
+        const code = result.code === 'CAPACITY_UNAVAILABLE' ? result.code : 'EXECUTION_FAILED';
+        throw Object.assign(new Error(failureMessages[code]), { code });
+      }
+      assert(samePartitionIdentity(result.reservation?.identity, identity)
+        && result.reservation.participantId === remoteParticipantId && result.reservation.index === 1
+        && result.reservation.phase === 'reserved' && result.reservation.resources?.attemptSlots === 1,
+      'Remote partition reservation identity mismatch');
+      return { reservation: result.reservation };
+    },
+    subscribe(listener) { listeners.add(listener); listener(getState()); return () => listeners.delete(listener); },
+    async refresh({ signal } = {}) {
+      const { descriptor, canonical: observedCanonical } = await endpoint.request({ operation: 'describe' }, new Uint8Array(), { signal });
+      assert(!descriptor || descriptor.schema === 'doppler.resident-partition/v1' && descriptor.ready === true
+        && descriptor.index === 1 && descriptor.modelId === plan.modelId && descriptor.modelIdentity === modelIdentity
+        && descriptor.planId === planId && JSON.stringify(descriptor.layerRange) === JSON.stringify(plan.partitions[1].layerRange),
+      'Remote partition descriptor mismatch');
+      if (canonical && descriptor) {
+        assert(observedCanonical?.stage?.participantId === remoteParticipantId && observedCanonical.stage.partitionIndex === 1
+          && observedCanonical.generation?.generationId === descriptor.canonicalGenerationId,
+        'Remote canonical capability is unavailable or changed');
+        remoteCanonical = structuredClone(observedCanonical);
+      } else remoteCanonical = null;
+      remoteDescriptor = descriptor; notify(); return getState();
+    },
+    async executeFrame({ frame, signal, executionGrant, outputGrant, ...request }) {
+      assert(outputGrant?.claim?.id === executionGrant?.claim?.id, 'Partition output grant differs from execution grant');
+      const { buffer, ...header } = frame;
+      const metadata = { ...request, operation: 'step', frame: header, grant: executionGrant };
+      const prior = active.get(request.identity.attemptId);
+      assert(!prior || samePartitionIdentity(prior.identity, request.identity), 'Partition attempt identity collision');
+      assert(prior || active.size < receiverLimits.maxAttempts, 'Remote attempt budget exhausted');
+      active.set(request.identity.attemptId, structuredClone(metadata));
+      let transportTiming = null;
+      const result = await endpoint.request(metadata, new Uint8Array(buffer), {
+        signal, onTiming: value => { transportTiming = value; }
+      });
+      return { ...result, transportTiming };
+    },
+    async closeAttempt({ identity }) {
+      const metadata = active.get(identity.attemptId);
+      if (!metadata) return;
+      assert(samePartitionIdentity(metadata.identity, identity), 'Partition settlement identity collision');
+      const settlement = canonicalRequest(metadata) ? { schema: canonicalContract.schema, operation: 'settle', identity,
+        grant: metadata.grant, canonicalAttempt: metadata.canonicalAttempt, generationId: metadata.generationId,
+        sequence: metadata.sequence, step: metadata.step } : { operation: 'settle', identity, grant: metadata.grant };
+      const result = await endpoint.request(settlement, new Uint8Array());
+      assert(result.settled === true, 'Remote partition settlement not acknowledged');
+      active.delete(identity.attemptId);
+    },
+    close,
+  });
+}

package/packages/reploid/src/mesh/partitions/partition-placement.js

@@ -0,0 +1,143 @@
+import { samePartitionAdapters } from './partition-contract.js';
+import { assertPartition as assert, canonicalPartitionJson, canonicalPartitionRoute, partitionActivationContract, validatePartitionRoute, PARTITION_ROUTE_SCHEMA, validateOrderedPartitionCapability, isOrderedPartitionEntryModel } from './partition-contract.js';
+export { validateOrderedPartitionCapability, isOrderedPartitionEntryModel } from './partition-contract.js';
+
+/** Pure selection over observed capabilities. No transport or resource ownership. */
+export function selectPartitionPlacement({ participantId, offer, localIndex, previous, capabilities }) {
+  const eligibility = capabilities.map(peer => ({ participantId: peer.participantId, transportId: peer.transportId,
+    observedAt: peer.observedAt, expiresAt: peer.expiresAt,
+    reason: !peer.available ? peer.reason : peer.description.phase === 'failed' ? 'contributor-failed'
+      : peer.description.offer?.id !== offer.id || peer.description.offer?.identity !== offer.identity || !samePartitionAdapters(peer.description.offer, offer)
+        ? 'model-mismatch' : 'approved-model-contribution',
+    index: peer.description?.index ?? null, indexes: peer.description?.eligibleIndexes ?? [0, 1] }));
+  const candidates = [{ id: participantId, index: localIndex, indexes: offer.partitionContributionIndexes ?? [0, 1] },
+    ...eligibility.filter(peer => peer.reason === 'approved-model-contribution')
+      .map(peer => ({ id: peer.participantId, index: peer.index, indexes: peer.indexes }))].sort((a, b) => a.id.localeCompare(b.id));
+  const ids = candidates.map(peer => peer.id);
+  const inputs = candidates.filter(peer => peer.indexes.includes(0));
+  const outputs = candidates.filter(peer => peer.indexes.includes(1));
+  if (localIndex === null && !candidates.some(peer => peer.index === 0)) {
+    const awaitingInput = capabilities.some(peer => peer.available && peer.description?.index === 1
+      && peer.description.offer?.id === offer.id && peer.description.offer?.identity === offer.identity
+      && Array.isArray(peer.description.placement) && peer.description.placement.length === 2
+      && peer.description.placement[0] !== participantId && !ids.includes(peer.description.placement[0]));
+    if (awaitingInput) return { participants: [], eligibility, reason: 'await-advertised-input-owner' };
+  }
+  const retainedA = previous && ids.includes(previous[0])
+    && inputs.find(peer => peer.id === previous[0])?.index === 0 ? previous[0] : null;
+  const a = retainedA || inputs.find(peer => peer.index === 0)?.id
+    || inputs.find(peer => peer.index === null)?.id || inputs[0]?.id;
+  if (!a) return { participants: [], eligibility, reason: 'missing-eligible-input-contributor' };
+  const b = participantId !== a ? outputs.find(peer => peer.id === participantId)?.id
+    : previous?.[0] === a && outputs.some(peer => peer.id === previous[1] && peer.index === 1) ? previous[1]
+      : outputs.find(peer => peer.id !== a && peer.index === 1)?.id || outputs.find(peer => peer.id !== a)?.id;
+  return { participants: b ? [a, b] : [], eligibility,
+    reason: !b ? 'missing-complementary-contributor' : retainedA ? 'retain-input-owner' : 'select-input-owner' };
+}
+
+/** New attempts consume availability hints; signed reservations remain authoritative.
+ * Capacity changes never move an already placed conversation. An ordered coordinator whose
+ * slots are full stays eligible while its advertised admission queue has room (the attempt
+ * waits there); one with a free slot is preferred. */
+export function selectPartitionExecution({ model, capabilities, ordered = false }) {
+  const waits = new Set();
+  const eligibility = capabilities.map(peer => {
+    const prepared = peer.description?.models?.find(candidate => candidate.id === model.id
+      && candidate.identity === model.identity && samePartitionAdapters(candidate, model) && candidate.availability === 'ready'
+      && (ordered ? isOrderedPartitionEntryModel(candidate, peer)
+        : peer.description?.schema !== 'reploid.partition-capability/v2'
+          && candidate.partition?.schema !== 'reploid.partition-selection/v2'));
+    const capacity = peer.description?.capacity, queue = ordered ? capacity?.attemptQueue : undefined;
+    const queueRoom = Number.isSafeInteger(queue?.queued) && Number.isSafeInteger(queue?.maxQueued) && queue.queued < queue.maxQueued;
+    const reason = !peer.available ? peer.reason : !prepared ? 'no-prepared-path'
+      : capacity?.closed ? 'input-owner-at-capacity'
+        : capacity?.availableSlots === 0 && !queueRoom ? (queue ? 'input-owner-queue-full' : 'input-owner-at-capacity') : 'reservation-required';
+    if (reason === 'reservation-required' && capacity?.availableSlots === 0) waits.add(peer.transportId);
+    return { participantId: peer.participantId, transportId: peer.transportId, reason,
+      eligible: reason === 'reservation-required', capacity: structuredClone(capacity || null) };
+  });
+  const selected = eligibility.find(peer => peer.eligible && !waits.has(peer.transportId)) ?? eligibility.find(peer => peer.eligible);
+  return { transportId: selected?.transportId ?? null, eligibility };
+}
+
+/** Eligible stage offers per index for one model plan, sorted by participant identity.
+ * Shared by first-valid matching and opt-in measured ranking; grants nothing. */
+export async function eligiblePartitionStages({ runtime, plan, model, capabilities, limits, now }) {
+  assert(limits && ['maxStages', 'maxPeers', 'maxOffersPerPeer', 'maxSelectionSteps']
+    .every(key => Number.isSafeInteger(limits[key]) && limits[key] > 0), 'Explicit route selection limits required');
+  assert(Number.isSafeInteger(now) && now >= 0 && Array.isArray(capabilities)
+    && capabilities.length <= limits.maxPeers && Number.isSafeInteger(plan?.stageCount)
+    && plan.stageCount >= 2 && plan.stageCount <= limits.maxStages, 'Route selection input exceeds limit');
+  const planSnapshot = structuredClone(plan), modelSnapshot = structuredClone(model), peers = structuredClone(capabilities);
+  const policy = { ...limits };
+  const activation = partitionActivationContract(runtime, planSnapshot);
+  const planId = await runtime.hashLayerPartitionPlan(planSnapshot);
+  assert(modelSnapshot?.id === planSnapshot.modelId && /^sha256:[a-f0-9]{64}$/.test(modelSnapshot.identity), 'Route model mismatch');
+  const candidates = Array.from({ length: planSnapshot.stageCount }, () => []), eligibility = [];
+  const participants = new Set(), transports = new Set();
+  for (const peer of peers) {
+    assert(['participantId', 'transportId'].every(key => typeof peer[key] === 'string' && peer[key].length > 0 && peer[key].length <= 256)
+      && !participants.has(peer.participantId) && !transports.has(peer.transportId), 'Duplicate or invalid route peer');
+    participants.add(peer.participantId); transports.add(peer.transportId);
+    let reason = null;
+    if (peer.available !== true || !Number.isSafeInteger(peer.observedAt) || peer.observedAt > now || peer.observedAt < 0
+      || !Number.isSafeInteger(peer.expiresAt) || peer.expiresAt <= now) reason = 'unavailable-or-expired';
+    else {
+      try { validateOrderedPartitionCapability(peer.description, peer.participantId, policy.maxOffersPerPeer); }
+      catch { reason = 'invalid-capability'; }
+    }
+    if (!reason && (peer.description.phase !== 'ready' || peer.description.capacity.closed
+      || peer.description.capacity.availableSlots === 0)) reason = 'contributor-unavailable';
+    if (reason) { eligibility.push({ participantId: peer.participantId, index: null, eligible: false, reason }); continue; }
+    for (const offer of peer.description.models) {
+      const eligible = offer.id === modelSnapshot.id && offer.identity === modelSnapshot.identity
+        && offer.planId === planId && offer.index < candidates.length && offer.availability === 'ready'
+        && offer.activation && canonicalPartitionJson(offer.activation) === canonicalPartitionJson(activation);
+      eligibility.push({ participantId: peer.participantId, index: offer.index, eligible: !!eligible,
+        reason: eligible ? 'reservation-required' : 'model-plan-stage-mismatch' });
+      if (eligible) candidates[offer.index].push({ index: offer.index, participantId: peer.participantId,
+        transportId: peer.transportId, residentId: offer.residentId, executionId: offer.executionId });
+    }
+  }
+  const compare = (a, b) => a < b ? -1 : a > b ? 1 : 0;
+  candidates.forEach(rows => rows.sort((a, b) => compare(a.participantId, b.participantId)
+    || compare(a.residentId, b.residentId) || compare(a.executionId, b.executionId)));
+  return { plan: planSnapshot, model: modelSnapshot, planId, activation, candidates, eligibility };
+}
+
+/** Deterministic bipartite matching for new attempts only. No cost optimum or physical-device independence is inferred. */
+export async function selectPartitionRoute(selection) {
+  const { plan: planSnapshot, model: modelSnapshot, planId, activation, candidates, eligibility } = await eligiblePartitionStages(selection);
+  const policy = { ...selection.limits };
+  let selectionSteps = 0;
+  const finish = (route, reason) => Object.freeze({ route, reason, selectionSteps,
+    eligibility: Object.freeze(eligibility.map(Object.freeze)) });
+  if (candidates.some(rows => rows.length === 0)) return finish(null, 'missing-eligible-stage');
+  const assigned = new Map(), stages = Array(candidates.length).fill(null);
+  // Iterative augmenting paths avoid stack depth depending on model size.
+  for (let start = 0; start < stages.length; start++) {
+    const queue = [start], visited = new Set(), predecessor = new Map();
+    let found = null;
+    for (let cursor = 0; cursor < queue.length && !found; cursor++) {
+      const index = queue[cursor];
+      for (const candidate of candidates[index]) {
+        if (++selectionSteps > policy.maxSelectionSteps) return finish(null, 'selection-work-limit');
+        if (visited.has(candidate.participantId)) continue;
+        visited.add(candidate.participantId);
+        const previous = assigned.get(candidate.participantId);
+        if (previous === undefined) { found = { index, candidate }; break; }
+        if (!predecessor.has(previous) && previous !== start) {
+          predecessor.set(previous, { index, candidate }); queue.push(previous);
+        }
+      }
+    }
+    if (!found) return finish(null, 'insufficient-distinct-participants');
+    while (found) {
+      stages[found.index] = found.candidate; assigned.set(found.candidate.participantId, found.index);
+      found = predecessor.get(found.index);
+    }
+  }
+  const route = await validatePartitionRoute(selection.runtime, planSnapshot, { schema: PARTITION_ROUTE_SCHEMA,
+    modelId: modelSnapshot.id, modelIdentity: modelSnapshot.identity, planId, stages, activation });
+  return finish(route, 'reservation-required');
+}

package/packages/reploid/src/mesh/partitions/partition-preparation-progress.js

@@ -0,0 +1,25 @@
+/** Doppler reports GPU pipeline preparation before a resident is ready. Hosts show it as
+ * contribution progress; the contribution phase stays theirs. `outstanding` means a started
+ * compilation still owns the stage, so nothing it holds is released yet. Other events are ignored. */
+const STATUSES = Object.freeze(['preparing', 'prepared', 'cancelling', 'cancelled', 'timed-out', 'failed']);
+
+const message = ({ status, prepared, total, outstanding }) => {
+  if (status === 'cancelling') return 'Stopping after the current GPU pipeline finishes compiling';
+  if (status === 'cancelled') return `Stopped preparing GPU pipelines: ${prepared} of ${total}`;
+  if (status === 'timed-out') return outstanding
+    ? 'Preparation time limit reached; waiting for the current GPU pipeline to finish compiling'
+    : `Preparation time limit reached: ${prepared} of ${total} GPU pipelines`;
+  if (status === 'failed') return `GPU pipeline preparation failed: ${prepared} of ${total}`;
+  return `Preparing GPU pipelines: ${prepared} of ${total}`;
+};
+
+export function residentPreparationProgress(event) {
+  if (event?.phase !== 'pipelines' || !STATUSES.includes(event.status)) return null;
+  const { status, prepared, total, key, elapsedMs, startedAt, maxDurationMs, outstanding } = event;
+  if (![prepared, total].every(value => Number.isSafeInteger(value) && value >= 0) || prepared > total
+    || typeof outstanding !== 'boolean' || !Number.isFinite(elapsedMs)) return null;
+  return Object.freeze({ stage: 'preparing', status, prepared, total, key: typeof key === 'string' ? key : null,
+    elapsedMs, startedAt: Number.isFinite(startedAt) ? startedAt : null,
+    maxDurationMs: Number.isSafeInteger(maxDurationMs) ? maxDurationMs : null, outstanding,
+    message: message({ status, prepared, total, outstanding }) });
+}

package/packages/reploid/src/mesh/partitions/partition-receiver-policy.json

@@ -0,0 +1,7 @@
+{
+  "maxControlBytes": 65536,
+  "maxCompletedSequences": 2,
+  "maxRetentionMs": 60000,
+  "maxRetainedBytes": 1048576,
+  "maxUnacknowledgedOutputs": 2
+}

package/packages/reploid/src/mesh/partitions/partition-reservations.js

@@ -0,0 +1,75 @@
+import { assertPartition as assert, assertCapacity, canonicalPartitionJson } from './partition-contract.js';
+
+/** Per-contributor admission owner. A slot stays held until cleanup settles. A closed owner, an
+ * exhausted attempt history or no free slot refuses with CAPACITY_UNAVAILABLE, which reaches the
+ * requester as that code rather than as a generic execution failure. */
+export function createPartitionReservations({ limits, participantId, index, now = Date.now }) {
+  assert(Number.isSafeInteger(limits.maxAttempts) && limits.maxAttempts > 0
+    && Number.isSafeInteger(limits.maxConcurrentAttempts) && limits.maxConcurrentAttempts > 0,
+  'Explicit reservation limits required');
+  const records = new Map();
+  let closed = false;
+  const describe = ({ binding: _binding, ...record }) => structuredClone(record);
+  const active = () => [...records.values()].filter(record => record.settledAt === null);
+  const lookup = identity => {
+    const record = records.get(identity.attemptId);
+    assert(record && record.binding === canonicalPartitionJson(identity), 'Reservation identity mismatch');
+    return record;
+  };
+  return Object.freeze({
+    reserve(identity) {
+      assertCapacity(!closed);
+      assert(typeof identity?.attemptId === 'string' && identity.attemptId.length > 0, 'Reservation attempt identity required');
+      if (records.has(identity.attemptId)) {
+        const record = lookup(identity);
+        assert(record.phase === 'reserved', 'Attempt reservation already settling or retired');
+        return describe(record);
+      }
+      assertCapacity(records.size < limits.maxAttempts);
+      assertCapacity(active().length < limits.maxConcurrentAttempts);
+      const record = { identity: structuredClone(identity), binding: canonicalPartitionJson(identity), participantId, index,
+        phase: 'reserved', reservedAt: now(), settlingAt: null, settledAt: null, failure: null,
+        resources: { attemptSlots: 1, maxPromptTokens: limits.maxPromptTokens, maxTokens: limits.maxTokens,
+          maxActivationBytes: limits.maxActivationBytes, scope: 'application-attempt-limits' } };
+      records.set(identity.attemptId, record); return describe(record);
+    },
+    fail(identity, cause) {
+      if (records.has(identity.attemptId)) lookup(identity).failure = String(cause?.message || cause);
+    },
+    settling(identity) {
+      if (!records.has(identity.attemptId)) {
+        assert(records.size < limits.maxAttempts, 'Contributor reservation history exhausted');
+        // Cancellation can overtake admission. Keep a bounded tombstone so a
+        // delayed, already-authorized reserve cannot reopen that attempt.
+        records.set(identity.attemptId, { identity: structuredClone(identity), binding: canonicalPartitionJson(identity),
+          participantId, index, phase: 'settling', reservedAt: null, settlingAt: now(), settledAt: null,
+          failure: null, resources: null });
+      }
+      const record = lookup(identity);
+      if (record.settledAt === null) { record.phase = 'settling'; record.settlingAt ??= now(); }
+    },
+    settled(identity) {
+      if (!records.has(identity.attemptId)) return;
+      const record = lookup(identity);
+      record.settledAt ??= now(); record.phase = record.failure ? 'failed' : 'settled';
+    },
+    /** The stage's own signed evidence for a charged attempt, kept with its admission record. */
+    attachEvidence(identity, evidence) {
+      if (records.has(identity.attemptId)) lookup(identity).evidence = structuredClone(evidence);
+    },
+    failureOf: identity => (records.has(identity.attemptId) ? lookup(identity).failure : null),
+    getState() {
+      return { closed, active: active().length,
+        availableSlots: closed || records.size >= limits.maxAttempts ? 0 : limits.maxConcurrentAttempts - active().length,
+        records: [...records.values()].map(describe) };
+    },
+    close() { closed = true; },
+    settleAll() {
+      // Only the resident owner can call this, after runtime disposal resolves.
+      for (const record of active()) {
+        record.settlingAt ??= now(); record.settledAt = now();
+        record.phase = record.failure ? 'failed' : 'settled';
+      }
+    }
+  });
+}

package/packages/reploid/src/mesh/partitions/partition-route-envelope-policy.json

@@ -0,0 +1,16 @@
+{
+  "schema": "reploid.route-envelope-policy/v1",
+  "undeclaredRoutes": "existing-limits",
+  "routes": [
+    {
+      "modelIdentity": "sha256:548e65597f85e190d6f0edf38c63569b872a61696c28ec95dce031f913e953db",
+      "planId": "sha256:7a4ce534baee0945e47adf13bb3bad017038eebb83b509e9d68b1fe01c76a1bf",
+      "evidence": "artifacts/placement-c-envelope-20261015/README.md",
+      "cells": [
+        { "maxConcurrency": 1, "maxPromptTokens": 512, "maxAnswerTokens": 255 },
+        { "maxConcurrency": 1, "maxPromptTokens": 1024, "maxAnswerTokens": 63 },
+        { "maxConcurrency": 2, "maxPromptTokens": 512, "maxAnswerTokens": 255 }
+      ]
+    }
+  ]
+}