reploid 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,319 @@
+import { createOrderedPartitionExecution } from './partition-route-execution.js';
+import { executeCanonicalPartition } from './partition-canonical-execution.js';
+import failureMessages from '../../transport/partition-errors.json' with { type: 'json' };
+/** Coordinates one Doppler token step through both partitions. No model math lives here. */
+import { partitionFingerprint, partitionActivationContract, matchingPartitionActivation } from './partition-contract.js';
+const assert = (ok, message) => { if (!ok) throw new Error(message); };
+const identifier = value => typeof value === 'string' && value.length > 0 && value.length <= 256;
+const positive = value => Number.isSafeInteger(value) && value > 0;
+const snapshot = value => structuredClone(value);
+
+function freezeRecord(value) {
+  for (const child of Object.values(value)) {
+    if (child && typeof child === 'object') freezeRecord(child);
+  }
+  return Object.freeze(value);
+}
+
+function checkTokens(tokens, vocabSize) {
+  assert(Array.isArray(tokens) && tokens.length > 0
+    && tokens.every(token => Number.isSafeInteger(token) && token >= 0 && token < vocabSize),
+  'tokenIds must contain valid Doppler vocabulary IDs');
+}
+
+function sameBinding(actual, expected) {
+  return actual && Object.entries(expected).every(([key, value]) => actual[key] === value);
+}
+
+/**
+ * Device ports are authenticated local/remote Doppler session facades. Each call
+ * performs exactly one prefill/decode step, never an independent generation.
+ * The host authorizer verifies grants against live identities/revocation state.
+ * This coordinator cannot verify physical execution or manufacture that proof.
+ */
+export function createLayerPartitionRunner({ runtime, plan: suppliedPlan, deviceA, deviceB,
+  transport, authorize, limits, canonical = false, route, stages }) {
+  if (route !== undefined || stages !== undefined) {
+    return createOrderedPartitionExecution({ runtime, plan: suppliedPlan, route, stages, transport, authorize, limits, canonical });
+  }
+  assert(runtime && typeof runtime.LAYER_PARTITION_SCHEMA === 'string'
+    && typeof runtime.ACTIVATION_TENSOR_SCHEMA === 'string'
+    && typeof runtime.serializeActivationFrame === 'function'
+    && typeof runtime.deserializeActivationFrame === 'function', 'Doppler partition runtime required');
+  assert(typeof canonical === 'boolean', 'Invalid canonical runner capability');
+  if (canonical) {
+    for (const name of ['canonicalGenerationIdentity', 'admitResidentPrompt', 'validateResidentAttemptIdentity',
+      'metadataDigest', 'tokenDigest', 'validateExecutionPublication', 'hashLayerPartitionPlan']) {
+      assert(typeof runtime[name] === 'function', 'Canonical Doppler runtime capability required');
+    }
+    for (const [device, methods] of [[deviceA, ['reserve', 'admitCanonicalPrompt', 'executeCanonicalGroup0', 'commitCanonicalTransition']],
+      [deviceB, ['reserveCanonical', 'admitCanonicalPrompt', 'executeCanonicalFrame', 'acknowledgeCanonicalPublication']]]) {
+      for (const method of [...methods, 'getCanonicalStage', 'getCanonicalGeneration']) {
+        assert(typeof device?.[method] === 'function', 'Canonical participant capability required');
+      }
+    }
+  }
+  assert(suppliedPlan && typeof suppliedPlan === 'object', 'Valid Doppler layer partition plan required');
+  const plan = freezeRecord(snapshot(suppliedPlan));
+  const activationContract = partitionActivationContract(runtime, plan);
+  assert(identifier(plan.modelId) && positive(plan.vocabSize) && positive(plan.hiddenSize) && positive(plan.totalLayers)
+    && positive(plan.splitLayer) && plan.splitLayer < plan.totalLayers
+    && ['f16', 'f32'].includes(plan.activationDtype), 'Invalid Doppler partition dimensions');
+  assert(typeof authorize === 'function', 'A verifying host authorization port is required');
+  for (const [device, method] of [[deviceA, 'executeGroup0'], [deviceB, typeof deviceB?.executeFrame === 'function' ? 'executeFrame' : 'executeGroup1']]) {
+    assert(identifier(device?.id) && typeof device[method] === 'function'
+      && typeof device.closeAttempt === 'function', 'Partition device identity, execution and settlement ports required');
+  }
+  assert(deviceA.id !== deviceB.id, 'Partition participants must be distinct');
+  assert(typeof deviceB.executeFrame === 'function' || typeof transport?.transferActivation === 'function', 'Activation transport required');
+  assert(limits && ['maxTokens', 'maxPromptTokens', 'maxActivationBytes', 'maxOutputCharacters', 'maxAttempts', 'maxConcurrentAttempts']
+    .every(key => positive(limits[key])), 'Explicit positive partition allocation limits required');
+  const policy = Object.freeze({ ...limits });
+  const participants = Object.freeze([deviceA.id, deviceB.id]);
+  const usedAttempts = new Set();
+  const active = new Map();
+  const receipts = new Map();
+  let closed = false;
+  // FIFO token leases let two conversations share resident weights fairly.
+  let tail = Promise.resolve();
+  const lease = async task => {
+    const previous = tail;
+    let release;
+    tail = new Promise(resolve => { release = resolve; });
+    await previous;
+    try { return await task(); } finally { release(); }
+  };
+
+  async function execute({ tokenIds, generation, identity, grants, maxTokens, signal, onDelta = () => {}, canonical: canonicalRequest }) {
+    assert(!closed, 'Partition runner is closed');
+    signal?.throwIfAborted();
+    assert(!canonical || canonicalRequest, 'Canonical runner requires its explicit execution contract');
+    checkTokens(tokenIds, plan.vocabSize);
+    assert(tokenIds.length <= policy.maxPromptTokens, 'Prompt exceeds partition allocation');
+    assert((canonicalRequest ? canonical && Number.isSafeInteger(maxTokens) && maxTokens >= 0 : positive(maxTokens)) && maxTokens <= policy.maxTokens, 'Invalid partition output allocation');
+    assert(generation && typeof generation === 'object' && !Array.isArray(generation)
+      && (canonicalRequest ? canonicalRequest.generation.policy.maxGeneratedTokens === maxTokens : generation.maxTokens === maxTokens), 'Resolved Doppler generation settings must match the effective output limit');
+    assert(identity && ['modelIdentity', 'planId', 'threadId', 'attemptId'].every(key => identifier(identity[key])),
+      'Exact model, plan, thread and attempt identities required');
+    assert(/^sha256:[a-f0-9]{64}$/.test(identity.modelIdentity), 'Pinned model digest required');
+    assert(grants?.executionA && grants?.executionB && grants?.activation && grants?.tokenContext && grants?.output,
+      'Execution, activation, token-context and output grants are required');
+    assert(typeof onDelta === 'function', 'onDelta must be a function');
+    const binding = Object.freeze({ modelId: plan.modelId, modelIdentity: identity.modelIdentity,
+      planId: identity.planId, threadId: identity.threadId, attemptId: identity.attemptId,
+      participantA: participants[0], participantB: participants[1],
+      ...(identity.requesterId ? { requesterId: identity.requesterId, placementGeneration: identity.placementGeneration } : {}) });
+    const authority = freezeRecord(snapshot(grants));
+    const settings = freezeRecord(snapshot(generation));
+    const inputTokens = [...tokenIds];
+    assert(!usedAttempts.has(binding.attemptId), 'Attempt already used; resume requires a supported checkpoint');
+    assert(usedAttempts.size < policy.maxAttempts, 'Partition runner attempt budget exhausted');
+    assert(active.size < policy.maxConcurrentAttempts, 'Partition concurrency budget exhausted');
+    usedAttempts.add(binding.attemptId);
+    const controller = new AbortController();
+    const combined = signal ? AbortSignal.any([signal, controller.signal]) : controller.signal;
+    let settle;
+    const settled = new Promise(resolve => { settle = resolve; });
+    active.set(binding.attemptId, { controller, settled });
+    const receipt = { identity: binding, phase: 'executing', startedAt: Date.now(), failure: null,
+      reservations: [], cleanupStartedAt: null, cleanupSettledAt: null, cleanup: [] };
+    receipts.set(binding.attemptId, receipt);
+    const generationDigestPromise = canonicalRequest ? null : partitionFingerprint(settings);
+    let input = inputTokens, continuationA = null, continuationB = null;
+    let content = '', activationBytes = 0, position = 0, logits = null;
+    let stopReason = 'length', failure = null;
+    const canonicalOwners = new Set();
+    const outputTokens = [];
+    const steps = [];
+    const permit = async (action, grant, step) => {
+      combined.throwIfAborted();
+      assert(await authorize({ action, grant, plan, ...binding, ...step, signal: combined }) === true,
+        'Partition authorization declined: ' + action);
+      combined.throwIfAborted();
+    };
+    try {
+      if (canonicalRequest) return await executeCanonicalPartition({ runtime, plan, deviceA, deviceB, policy, binding, authority,
+        canonical: canonicalRequest, tokenIds: inputTokens, signal: combined, lease, permit, onDelta, receipt,
+        ownDevice: id => canonicalOwners.add(id) });
+      if (deviceA.reserve) receipt.reservations.push(snapshot(await deviceA.reserve(binding)));
+      if (deviceB.reserve) {
+        const generationDigest = await generationDigestPromise;
+        combined.throwIfAborted();
+        const step = { step: 0, tokenPosition: 0, inputTokenCount: inputTokens.length, maxTokens, generationDigest };
+        await permit('mesh.execute_partition_b', authority.executionB, step);
+        await permit('mesh.transfer_token_context', authority.tokenContext, step);
+        const admission = await deviceB.reserve({ identity: binding, grant: authority.executionB, generation: settings,
+          generationDigest, inputTokenCount: inputTokens.length, signal: combined });
+        receipt.reservations.push(snapshot(admission.reservation));
+      }
+      for (let index = 0; index < maxTokens; index++) {
+        const queuedAt = performance.now();
+        const delivery = await lease(async () => {
+          const leaseWaitMs = performance.now() - queuedAt;
+          combined.throwIfAborted();
+          const generationDigest = await generationDigestPromise;
+          combined.throwIfAborted();
+          const step = Object.freeze({ step: index, tokenPosition: position, inputTokenCount: input.length,
+            maxTokens, generationDigest });
+          const started = performance.now();
+          // Both execution recipients must be eligible before exposing any input.
+          await permit('mesh.execute_partition_a', authority.executionA, step);
+          await permit('mesh.execute_partition_b', authority.executionB, step);
+          await permit('mesh.transfer_intermediate_activation', authority.activation, step);
+          await permit('mesh.transfer_token_context', authority.tokenContext, step);
+          await permit('mesh.transfer_partition_output', authority.output, step);
+          const localStarted = performance.now();
+          const resultA = snapshot(await deviceA.executeGroup0({ tokenIds: [...input], continuation: continuationA,
+            generation: settings, identity: binding, executionGrant: authority.executionA, ...step, signal: combined }));
+          const localStepMs = performance.now() - localStarted;
+          combined.throwIfAborted();
+          const tensor = resultA?.activationTensor;
+          assert(matchingPartitionActivation(tensor, activationContract) && tensor.shape?.length === 3
+            && tensor.shape[0] === 1 && tensor.shape[1] === input.length && tensor.shape[2] === plan.hiddenSize
+            && tensor.seqOffset === position && tensor.step === index, 'Partition A activation contract mismatch');
+          assert(tensor.data?.byteLength <= policy.maxActivationBytes, 'Activation exceeds transfer allocation');
+          const metadata = { ...binding, ...step, from: participants[0], to: participants[1] };
+          const serializationStarted = performance.now();
+          const frame = runtime.serializeActivationFrame({ ...tensor, metadata });
+          assert(frame.schema === activationContract.schema && matchingPartitionActivation(frame, activationContract, true),
+            'Serialized activation contract mismatch');
+          runtime.validateActivationFrameForPlan?.(frame, plan);
+          assert(frame.byteLength <= policy.maxActivationBytes, 'Activation exceeds transfer allocation');
+          // Retain bytes separately: a transport cannot mutate the comparison baseline.
+          const sent = snapshot(frame);
+          const serializationMs = performance.now() - serializationStarted;
+          await permit('mesh.transfer_intermediate_activation', authority.activation, step);
+          const transferStarted = performance.now();
+          let resultB, transferMs = null, remoteStepMs = null;
+          if (typeof deviceB.executeFrame === 'function') {
+            await permit('mesh.execute_partition_b', authority.executionB, step);
+            resultB = snapshot(await deviceB.executeFrame({ frame, continuation: continuationB,
+              inputTokenIds: [...input], generation: settings, identity: binding,
+              executionGrant: authority.executionB, outputGrant: authority.output,
+              ...step, signal: combined }));
+            // Includes remote compute and disclosure; never label this as network-only latency.
+            remoteStepMs = performance.now() - transferStarted;
+          } else {
+            const received = snapshot(await transport.transferActivation(frame, { identity: binding, ...step, signal: combined }));
+            combined.throwIfAborted();
+            transferMs = performance.now() - transferStarted;
+            assert(received?.schema === activationContract.schema && matchingPartitionActivation(received, activationContract, true)
+              && sameBinding(received.metadata, metadata) && received.seqOffset === position
+              && received.step === index && received.dtype === sent.dtype
+              && JSON.stringify(received.shape) === JSON.stringify(sent.shape)
+              && received.byteLength === sent.byteLength && received.buffer instanceof ArrayBuffer
+              && received.buffer.byteLength === sent.byteLength, 'Received activation identity or shape mismatch');
+            const before = new Uint8Array(sent.buffer), after = new Uint8Array(received.buffer);
+            assert(before.every((byte, offset) => byte === after[offset]), 'Received activation bytes differ');
+            await permit('mesh.execute_partition_b', authority.executionB, step);
+            const activation = runtime.validateActivationFrameForPlan
+              ? runtime.validateActivationFrameForPlan(received, plan) : runtime.deserializeActivationFrame(received);
+            resultB = snapshot(await deviceB.executeGroup1({ activation,
+              inputTokenIds: [...input], generation: settings, continuation: continuationB,
+              identity: binding, executionGrant: authority.executionB,
+              outputGrant: authority.output, ...step, signal: combined }));
+          }
+          combined.throwIfAborted();
+          // B owns sampling, decoding and stop semantics. It must return ONE selected token.
+          assert(resultB && sameBinding(resultB.identity, binding) && resultB.step === index
+            && resultB.tokenPosition === position, 'Partition B response identity mismatch');
+          assert(Number.isSafeInteger(resultB.tokenId) && resultB.tokenId >= 0
+            && resultB.tokenId < plan.vocabSize && typeof resultB.done === 'boolean'
+            && typeof resultB.delta === 'string', 'Partition B must return exactly one selected token');
+          assert(!('tokenIds' in resultB) && !('content' in resultB), 'Independent generation from B is forbidden');
+          assert(content.length + resultB.delta.length <= policy.maxOutputCharacters, 'Partition output exceeds allocation');
+          if (resultB.done) assert(identifier(resultB.stopReason), 'Doppler stopping reason required');
+          assert(index + 1 < maxTokens || resultB.done, 'Doppler must finalize decoding at the request token limit');
+          await permit('mesh.transfer_partition_output', authority.output, step);
+          continuationA = resultA.continuation;
+          continuationB = resultB.continuation;
+          logits = resultB.logits == null ? null : snapshot(resultB.logits);
+          outputTokens.push(resultB.tokenId);
+          content += resultB.delta;
+          activationBytes += sent.byteLength;
+          steps.push({ ...step, tokenId: resultB.tokenId, activationBytes: sent.byteLength,
+            leaseWaitMs, outputDeliveryMs: 0,
+            localStepMs, serializationMs, computationA: resultA.metrics ?? null, computationB: resultB.metrics ?? null,
+            transferMs, remoteStepMs, transportTiming: resultB.transportTiming ?? null,
+            elapsedMs: performance.now() - started });
+          combined.throwIfAborted();
+          position += input.length;
+          input = [resultB.tokenId];
+          if (resultB.done) stopReason = resultB.stopReason;
+          return { delta: resultB.delta, terminal: resultB.done };
+        });
+        // Per-attempt backpressure must not hold another conversation's GPU lease.
+        combined.throwIfAborted();
+        if (delivery.delta) {
+          const deliveryStarted = performance.now();
+          try { await onDelta(delivery.delta); }
+          finally { steps.at(-1).outputDeliveryMs = performance.now() - deliveryStarted; }
+        }
+        combined.throwIfAborted();
+        if (delivery.terminal) break;
+      }
+      return { content, tokenIds: outputTokens, logits, stopReason,
+        execution: { schema: 'reploid.mesh.partition-execution/v2', ...binding,
+          placement: 'two-device-layer-partition', splitLayer: plan.splitLayer,
+          activationBytes, steps, stopReason, settlement: receipt } };
+    } catch (error) {
+      failure = error;
+      receipt.failure = String(error?.message || error);
+      throw error;
+    } finally {
+      // Settle both owned attempts even when cancellation arrives during a port call.
+      // Shared resident weights remain owned by the host, not this conversation.
+      receipt.phase = 'settling'; receipt.cleanupStartedAt = Date.now();
+      const cleanupDevices = canonicalRequest ? [deviceA, deviceB].filter(device => canonicalOwners.has(device.id)) : [deviceA, deviceB];
+      const results = await Promise.allSettled(cleanupDevices.map(async device => {
+        try {
+          await device.closeAttempt({ identity: binding });
+          receipt.cleanup.push({ participantId: device.id, status: 'settled', settledAt: Date.now(), error: null });
+        } catch (cause) {
+          receipt.cleanup.push({ participantId: device.id, status: 'failed', settledAt: null,
+            error: String(cause?.message || cause) });
+          throw cause;
+        }
+      }));
+      active.delete(binding.attemptId);
+      settle();
+      const cleanupErrors = results.filter(result => result.status === 'rejected').map(result => result.reason);
+      receipt.cleanupSettledAt = cleanupErrors.length ? null : Date.now();
+      receipt.phase = cleanupErrors.length ? 'cleanup-failed' : combined.aborted ? 'cancelled' : failure ? 'failed' : 'completed';
+      if (cleanupErrors.length) throw Object.assign(
+        new AggregateError(failure ? [failure, ...cleanupErrors] : cleanupErrors, failureMessages.CLEANUP_FAILED),
+        { code: 'CLEANUP_FAILED' });
+    }
+  }
+
+  return Object.freeze({ plan, execute,
+    executeCanonical(request) {
+      assert(canonical && request?.canonical, 'Canonical runner was not explicitly enabled');
+      return execute({ ...request, generation: request.canonical.generation.policy,
+        maxTokens: request.canonical.generation.policy.maxGeneratedTokens });
+    },
+    getState: () => ({ closed, active: active.size, attempts: snapshot([...receipts.values()]) }),
+    async close() {
+      closed = true;
+      const pending = [...active.values()];
+      for (const item of pending) item.controller.abort(new Error('Partition runner closed'));
+      await Promise.all(pending.map(item => item.settled));
+    }
+  });
+}
+
+/** Final-logit comparison only. Full acceptance additionally compares every boundary/token. */
+export async function verifySplitParity({ runtime, splitRunner, referenceRunner, tokenIds, generation,
+  identity, grants, maxTokens, tolerance }) {
+  assert(typeof runtime?.comparePartitionExecution === 'function', 'Doppler comparison runtime required');
+  assert(Number.isFinite(tolerance) && tolerance >= 0, 'Explicit numerical tolerance required');
+  const splitResult = await splitRunner.execute({ tokenIds, generation, identity, grants, maxTokens });
+  const refResult = await referenceRunner.execute({ tokenIds, maxTokens });
+  assert(splitResult.logits?.length > 0 && refResult.logits?.length > 0
+    && [...splitResult.logits, ...refResult.logits].every(Number.isFinite), 'Finite non-empty logits required');
+  const comparison = runtime.comparePartitionExecution({ splitOutput: splitResult.logits,
+    referenceOutput: refResult.logits, tolerance });
+  const tokensMatch = JSON.stringify(splitResult.tokenIds) === JSON.stringify(refResult.tokenIds);
+  return { ...comparison, matches: comparison.matches && tokensMatch, tokensMatch,
+    splitResult, refResult, comparison };
+}

package/packages/reploid/src/mesh/partitions/partition-stage-assignment.js

@@ -0,0 +1,109 @@
+import { assertPartition as assert, validateOrderedPartitionCapability } from './partition-contract.js';
+
+/** A contributor's own claim while it chooses or prepares a stage. A hint, never an assignment. */
+export const STAGE_ASSIGNMENT_SCHEMA = 'reploid.stage-assignment/v1';
+/** A ranking coordinator's measured decode cost per stage of its current route. A hint, never an assignment. */
+export const STAGE_COSTS_SCHEMA = 'reploid.stage-costs/v1';
+
+const matchesPlan = (model, planId) => typeof model.partitionPlanId === 'string' && model.partitionPlanId === planId;
+
+const observedPeers = (capabilities, now, maxOffersPerPeer) => capabilities.filter(peer => {
+  if (peer?.available !== true || !(peer.expiresAt > now)) return false;
+  try { validateOrderedPartitionCapability(peer.description, peer.participantId, maxOffersPerPeer); return true; } catch { return false; }
+});
+
+/** Opt-in replica demand from observed discovery: a stage whose advertised queue exceeds `queueBound`,
+ * else the stage a ranking coordinator measured at least `bottleneckRatio` times slower than every
+ * other stage. Returns the one stage that would gain most from another replica, or none. */
+export function stageDemand({ model, stageCount, capabilities, now, maxOffersPerPeer, queueBound, bottleneckRatio }) {
+  assert(Number.isSafeInteger(queueBound) && queueBound >= 0 && typeof bottleneckRatio === 'number' && bottleneckRatio > 1,
+    'Explicit replica demand bounds required');
+  const peers = observedPeers(capabilities, now, maxOffersPerPeer), queued = Array(stageCount).fill(0);
+  for (const peer of peers) {
+    const waiting = peer.description.capacity.queued;
+    if (peer.description.phase !== 'ready' || !Number.isSafeInteger(waiting) || waiting < 0) continue;
+    for (const offer of peer.description.models) if (offer.id === model.id && offer.identity === model.identity && matchesPlan(model, offer.planId)
+      && offer.availability === 'ready' && Number.isSafeInteger(offer.index) && offer.index < stageCount) {
+      queued[offer.index] = Math.max(queued[offer.index], waiting);
+    }
+  }
+  const busiest = queued.reduce((best, value, index) => value > queued[best] ? index : best, 0);
+  if (queued[busiest] > queueBound) return Object.freeze({ index: busiest, reason: 'queue', queued: Object.freeze(queued) });
+  // Coordinators are read in participant-id order so every observer resolves the same claim.
+  for (const peer of [...peers].sort((a, b) => a.participantId < b.participantId ? -1 : a.participantId > b.participantId ? 1 : 0)) {
+    const costs = peer.description.stageCosts, decode = costs?.decodeMs;
+    if (costs?.schema !== STAGE_COSTS_SCHEMA || costs.modelId !== model.id || costs.modelIdentity !== model.identity || !matchesPlan(model, costs.planId)
+      || !Array.isArray(decode) || decode.length !== stageCount || !decode.every(value => typeof value === 'number' && Number.isFinite(value) && value >= 0)) continue;
+    const slowest = decode.reduce((best, value, index) => value > decode[best] ? index : best, 0);
+    const next = Math.max(...decode.filter((_, index) => index !== slowest));
+    if (decode[slowest] > 0 && decode[slowest] >= bottleneckRatio * next) {
+      return Object.freeze({ index: slowest, reason: 'bottleneck', queued: Object.freeze(queued) });
+    }
+  }
+  return Object.freeze({ index: null, reason: null, queued: Object.freeze(queued) });
+}
+
+/** Launch 3, opt-in. An operator's `auto` choice authorizes this participant's own policy to pick
+ * its stage from observed discovery. Discovery grants nothing, and nothing here assigns another
+ * participant. Supply counts distinct participants: ready offers plus auto claims of peers
+ * still preparing. Unassigned auto peers are joiners. The caller re-evaluates only while idle. */
+export function planStageAssignment({ participantId, model, stageCount, capabilities, now, current = null,
+  maxOffersPerPeer, demand = null }) {
+  assert(typeof participantId === 'string' && participantId.length > 0 && typeof model?.id === 'string'
+    && /^sha256:[a-f0-9]{64}$/.test(model.identity) && typeof model.partitionPlanId === 'string' && model.partitionPlanId.length > 0 && Number.isSafeInteger(stageCount) && stageCount >= 2
+    && Array.isArray(capabilities) && Number.isSafeInteger(now) && Number.isSafeInteger(maxOffersPerPeer)
+    && (current === null || Number.isSafeInteger(current) && current >= 0 && current < stageCount),
+  'Explicit stage assignment input required');
+  const stageIndex = value => Number.isSafeInteger(value) && value >= 0 && value < stageCount;
+  const wanted = demand && stageIndex(demand.index) ? demand.index : null;
+  const supply = Array.from({ length: stageCount }, () => new Set()), joiners = new Set();
+  let replicaPreparing = false;
+  for (const peer of capabilities) {
+    if (peer?.participantId === participantId || peer?.available !== true || !(peer.expiresAt > now)) continue;
+    const description = peer.description;
+    try { validateOrderedPartitionCapability(description, peer.participantId, maxOffersPerPeer); } catch { continue; }
+    if (description.phase === 'ready') for (const offer of description.models) {
+      if (offer.id === model.id && offer.identity === model.identity && matchesPlan(model, offer.planId) && offer.availability === 'ready'
+        && stageIndex(offer.index)) supply[offer.index].add(peer.participantId);
+    }
+    const claim = description.assignment;
+    if (claim?.schema === STAGE_ASSIGNMENT_SCHEMA && claim.modelId === model.id && claim.modelIdentity === model.identity && matchesPlan(model, claim.planId)
+      && ['waiting', 'loading', 'ready'].includes(description.phase)) {
+      if (claim.index === null) joiners.add(peer.participantId);
+      else if (stageIndex(claim.index)) {
+        supply[claim.index].add(peer.participantId);
+        if (claim.index === wanted && description.phase !== 'ready') replicaPreparing = true;
+      }
+    }
+  }
+  for (const id of joiners) if (supply.some(set => set.has(id))) joiners.delete(id);
+  const counts = supply.map(set => set.size);
+  // Least supplied; ties go to the lowest index so every observer orders stages alike.
+  const least = (rows, skip = -1) => rows.reduce((best, count, index) =>
+    index !== skip && (best < 0 || count < rows[best]) ? index : best, -1);
+  const decide = (index, reason) => Object.freeze({ index, reason, move: current !== null && index !== current,
+    supply: Object.freeze([...counts]), joiners: joiners.size });
+  // A replica is useful only once every stage has a supplier: completing a route comes first.
+  const replicate = wanted !== null && counts.every(count => count > 0);
+  if (current === null) {
+    // Preparation consumes the owner's resources. Wait until observed suppliers
+    // and willing joiners can cover a route; excess joiners remain unprepared.
+    const missing = counts.flatMap((count, index) => count === 0 ? [index] : []);
+    const rank = [participantId, ...joiners].sort().indexOf(participantId);
+    if (missing.length > joiners.size + 1) return decide(null, 'waiting-for-route');
+    if (rank < missing.length) return decide(missing[rank], 'cold-least-supplied');
+    // One joiner addresses the observed demand. An in-flight replica already
+    // addresses that observation; wait for fresh demand after it becomes ready.
+    if (replicate && rank === 0 && !replicaPreparing) return decide(wanted, 'replicate-' + demand.reason);
+    return decide(null, 'no-useful-assignment');
+  }
+  // Hysteresis: move only when this stage has at least two more contributors than the least
+  // supplied one, no joiner is about to fill the gap, and only its highest participant id moves.
+  const others = supply[current], target = least(counts, current);
+  const highest = [participantId, ...others].sort().at(-1) === participantId;
+  if (joiners.size || !highest) return decide(current, 'retain');
+  // Leave for a demanded stage only while another contributor keeps this stage supplied.
+  if (replicate && wanted !== current && others.size >= 1) return decide(wanted, 'replicate-' + demand.reason);
+  if (others.size < counts[target] + 1) return decide(current, 'retain');
+  return decide(target, 'rebalance');
+}

package/packages/reploid/src/mesh/partitions/partition-stage-commit.js

@@ -0,0 +1,103 @@
+import { createPeerIdFromPublicJwk, importSigningKey, importVerificationKey, getIdentitySignAlgorithm,
+  encodeBytes, toBase64Url, fromBase64Url } from '../../artifacts/identity.js';
+import { assertPartition as assert } from './partition-contract.js';
+
+const evidenceSchema = 'reploid.partition-stage-evidence/v1';
+const claimSchema = 'reploid.partition-stage-claim/v1';
+const acknowledgmentKeys = ['schema', 'stageId', 'attemptDigest', 'sequence', 'baseCursorId', 'decisionId',
+  'successorCursorId', 'participantEpoch', 'deviceEpoch', 'residentId'];
+const exact = (value, keys) => assert(value && typeof value === 'object' && !Array.isArray(value)
+  && Object.keys(value).length === keys.length && keys.every(key => Object.hasOwn(value, key)), 'Invalid stage evidence fields');
+const digest = (runtime, domain, value) => runtime.metadataDigest(domain, value);
+const copy = value => structuredClone(value);
+const same = (runtime, domain, a, b) => digest(runtime, domain, a) === digest(runtime, domain, b);
+function boundStage(runtime, attempt, stage) {
+  const accepted = runtime.validateResidentAttemptIdentity(attempt);
+  const found = accepted.stages.find(value => value.stageId === stage.stageId);
+  assert(found && same(runtime, claimSchema, found, stage), 'Stage differs from admitted attempt');
+  return { attempt: accepted, stage: found, attemptDigest: runtime.residentAttemptDigest(accepted) };
+}
+function checkClaim(runtime, claim, attempt, stage) {
+  exact(claim, ['schema', 'stage', 'acknowledgment']);
+  const bound = boundStage(runtime, attempt, stage), ack = claim.acknowledgment;
+  exact(ack, acknowledgmentKeys);
+  assert(claim.schema === claimSchema && same(runtime, claimSchema, claim.stage, bound.stage)
+    && ack.schema === 'doppler.stage-commit/v1' && ack.stageId === stage.stageId
+    && ack.attemptDigest === bound.attemptDigest && Number.isSafeInteger(ack.sequence) && ack.sequence >= 0
+    && (ack.baseCursorId === null || /^sha256:[a-f0-9]{64}$/.test(ack.baseCursorId))
+    && /^sha256:[a-f0-9]{64}$/.test(ack.decisionId) && /^sha256:[a-f0-9]{64}$/.test(ack.successorCursorId)
+    && ack.participantEpoch === stage.participantEpoch && ack.deviceEpoch === stage.deviceEpoch
+    && ack.residentId === stage.residentId, 'Stage commitment binding mismatch');
+  return bound;
+}
+
+/** Signs an assertion by the existing contributor identity. The resident calls
+ * this only after its actual transition settles; signatures do not attest math.
+ * The receiver's bounded phase-result owner retains/replays these exact bytes. */
+export function createPartitionStageCommitAuthority({ runtime, identity, stage }) {
+  for (const method of ['metadataDigest', 'validateResidentAttemptIdentity', 'residentAttemptDigest', 'residentPublicationDecisionDigest']) {
+    assert(typeof runtime?.[method] === 'function', 'Canonical Doppler stage contracts required');
+  }
+  assert(identity?.privateJwk && identity?.publicJwk && identity.peerId === stage?.participantId,
+    'Stage signing identity must equal the bound participant');
+  const signer = copy(identity), selectedStage = copy(stage);
+  let closed = false;
+  return Object.freeze({
+    getStage: () => copy(selectedStage),
+    async sign({ attempt, sequence, baseCursorId, transition }) {
+      assert(!closed, 'Stage commitment authority closed');
+      const bound = boundStage(runtime, attempt, selectedStage);
+      assert(transition?.successor?.generationId === bound.attempt.generationId,
+        'Target transition generation differs from attempt');
+      const decision = { attemptDigest: bound.attemptDigest, sequence, baseCursorId,
+        acceptedTokenIds: transition.acceptedTokenIds, tokenRange: transition.tokenRange,
+        successor: transition.successor, delta: { text: transition.delta, outputDigest: transition.outputDigest },
+        stoppingOutcome: transition.successor.stopReason };
+      const acknowledgment = { schema: 'doppler.stage-commit/v1', stageId: selectedStage.stageId,
+        attemptDigest: bound.attemptDigest, sequence, baseCursorId,
+        decisionId: runtime.residentPublicationDecisionDigest(decision), successorCursorId: transition.successor.cursorId,
+        participantEpoch: selectedStage.participantEpoch, deviceEpoch: selectedStage.deviceEpoch, residentId: selectedStage.residentId };
+      const claim = { schema: claimSchema, stage: selectedStage, acknowledgment };
+      checkClaim(runtime, claim, bound.attempt, selectedStage);
+      assert(await createPeerIdFromPublicJwk(signer.publicJwk) === selectedStage.participantId, 'Signing key does not identify stage participant');
+      const key = await importSigningKey(signer);
+      const signature = await crypto.subtle.sign(getIdentitySignAlgorithm(signer), key, encodeBytes(digest(runtime, claimSchema, claim)));
+      assert(!closed, 'Stage commitment authority closed');
+      const evidence = { schema: evidenceSchema, claim: copy(claim), publicJwk: copy(signer.publicJwk), signature: toBase64Url(signature) };
+      return { acknowledgment: { ...acknowledgment, authenticationDigest: digest(runtime, evidenceSchema, evidence) }, evidence };
+    },
+    close() { closed = true; }
+  });
+}
+
+/** Validates durable evidence against the exact publication acknowledgment and
+ * admitted stage, using existing signing formats. No global trust/key lookup. */
+export async function verifyPartitionStageCommit({ runtime, attempt, stage, acknowledgment, evidence,
+  transition, sequence, baseCursorId }) {
+  try {
+    // The runtime's canonical encoding enforces bounded metadata before copying.
+    const input = { attempt, stage, acknowledgment, evidence,
+      ...(transition === undefined ? {} : { transition, sequence, baseCursorId }) };
+    digest(runtime, evidenceSchema, input);
+    ({ attempt, stage, acknowledgment, evidence, transition, sequence, baseCursorId } = copy(input));
+    exact(evidence, ['schema', 'claim', 'publicJwk', 'signature']);
+    exact(acknowledgment, [...acknowledgmentKeys, 'authenticationDigest']);
+    if (evidence.schema !== evidenceSchema || typeof evidence.signature !== 'string'
+      || !/^[A-Za-z0-9_-]{1,256}$/.test(evidence.signature)
+      || acknowledgment.authenticationDigest !== digest(runtime, evidenceSchema, evidence)) return false;
+    const { authenticationDigest, ...body } = acknowledgment;
+    checkClaim(runtime, evidence.claim, attempt, stage);
+    if (transition !== undefined && (acknowledgment.sequence !== sequence || acknowledgment.baseCursorId !== baseCursorId
+      || acknowledgment.successorCursorId !== transition.successor.cursorId
+      || acknowledgment.decisionId !== runtime.residentPublicationDecisionDigest({
+        attemptDigest: runtime.residentAttemptDigest(attempt), sequence, baseCursorId,
+        acceptedTokenIds: transition.acceptedTokenIds, tokenRange: transition.tokenRange,
+        successor: transition.successor, delta: { text: transition.delta, outputDigest: transition.outputDigest },
+        stoppingOutcome: transition.successor.stopReason }))) return false;
+    if (!same(runtime, claimSchema, body, evidence.claim.acknowledgment)
+      || await createPeerIdFromPublicJwk(evidence.publicJwk) !== stage.participantId) return false;
+    const key = await importVerificationKey(evidence.publicJwk);
+    return await crypto.subtle.verify(getIdentitySignAlgorithm(evidence.publicJwk), key,
+      fromBase64Url(evidence.signature), encodeBytes(digest(runtime, claimSchema, evidence.claim)));
+  } catch { return false; }
+}