reploid 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,434 @@
+import { generationRequest, requireGenerationCapability, tokenUsage } from './partition-generation-request.js';
+import { createPartitionDataChannel } from '../../transport/partition-data-channel.js';
+import { assertPartition as assert, assertCapacity, canonicalPartitionJson, canonicalRouteAttemptBinding, sameRouteAttemptIdentity } from './partition-contract.js';
+import { partitionActivity, summarizePartitionExecution } from './partition-summary.js';
+import { createEntryPublicationScope, entryPublicationEnvelope, entryPublicationPort, matchingEntryPublication,
+  validateEntryPublicationContext } from './partition-entry-publication.js';
+import { validateOrderedPublicationContext } from './partition-ordered-publication.js';
+import { isChargeBindingShape } from './partition-attempt-evidence.js';
+
+/** Requester-to-A channel. This module imports no tokenizer, tensor codec or GPU runtime.
+ * The host authenticates the channel and grants input disclosure to both stages.
+ * A's chat port owns the A-to-B execution channel; activation bytes never enter here.
+ * An ordered input may carry the requester's signed charge binding; the coordinator then
+ * returns each output with its final-stage receipt and carries the requester's
+ * acknowledgment back to the route.
+ * An ordered requester that opts in with `attemptState` receives the coordinator's admission
+ * state (`queued` while it waits for route capacity, `executing` once admitted); nothing else.
+ */
+export const ATTEMPT_STATE_SCHEMA = 'reploid.partition-attempt-state/v1';
+const ATTEMPT_STATES = Object.freeze(['queued', 'executing']);
+export function createPartitionEntry({ channel, localParticipantId, remoteParticipantId,
+  service = null, canonical = false, ordered = false, authorize, limits, inputLimits, now = Date.now }) {
+  assert(typeof authorize === 'function' && ['maxInputCharacters', 'maxOutputCharacters', 'maxAttempts',
+    'maxConcurrentAttempts', 'descriptorTtlMs'].every(key => Number.isSafeInteger(inputLimits?.[key]) && inputLimits[key] > 0),
+  'Entry authorization and input budgets required');
+  assert(typeof ordered === 'boolean' && !(ordered && canonical), 'Explicit distinct ordinary ordered entry capability required');
+  assert(typeof canonical === 'boolean', 'Explicit canonical entry capability required');
+  const policy = structuredClone(inputLimits), active = new Map(), retired = new Set();
+  const deliveries = new Map(), unsettledPublications = new Set();
+  let draining = false, closed = false, descriptor = null, observedAt = 0;
+  const orderedInput = m => m?.schema === 'reploid.partition-input/v3';
+  const coordinator = m => orderedInput(m) ? m.coordinatorId : m.participantA;
+  const attempt = m => canonicalRouteAttemptBinding({ schema: 'reploid.partition-attempt/v2',
+    route: m.route, threadId: m.threadId, attemptId: m.attemptId,
+    requesterId: m.requesterId, placementGeneration: m.placementGeneration });
+  function validGeneration(m) {
+    try { return !generationRequest(m.generationRequest) || m.schema !== 'reploid.partition-input/v2'; } catch { return false; }
+  }
+  function validMode(m) {
+    if (m.activity !== undefined && (!orderedInput(m) || m.activity !== 'reploid.partition-activity/v1')) return false;
+    if (m.attemptState !== undefined && (!orderedInput(m) || m.attemptState !== ATTEMPT_STATE_SCHEMA)) return false;
+    if (orderedInput(m)) {
+      try {
+        return ordered && (m.disclosureExpiresAt === undefined || Number.isSafeInteger(m.disclosureExpiresAt) && m.disclosureExpiresAt > now()) && m.canonical === undefined && m.participantA === undefined && m.participantB === undefined
+          && (m.publication === undefined || !!validateOrderedPublicationContext(m.publication))
+          && attempt(m).route.stages[0].participantId === m.coordinatorId
+          && m.route.modelId === m.modelId && m.route.modelIdentity === m.modelIdentity && m.route.planId === m.planId;
+      } catch { return false; }
+    }
+    return (m?.schema === 'reploid.partition-input/v1' && m.canonical === undefined && m.route === undefined
+      || canonical && m?.schema === 'reploid.partition-input/v2' && !!validateEntryPublicationContext(m.canonical, m))
+      && m.participantA !== m.participantB;
+  }
+  const validCharge = m => m.charge === undefined || orderedInput(m) && isChargeBindingShape(m.charge, m);
+  const valid = m => m?.operation === 'generate' && validMode(m) && validGeneration(m) && validCharge(m) && m.requesterId !== coordinator(m)
+    && typeof m.attemptId === 'string' && m.attemptId.length <= 128
+    && typeof m.threadId === 'string' && m.threadId.length <= 128
+    && Number.isSafeInteger(m.placementGeneration) && m.placementGeneration >= 0
+    && Array.isArray(m.messages) && m.messages.length > 0
+    && m.messages.every(row => ['system', 'user', 'assistant'].includes(row.role) && typeof row.content === 'string')
+    && JSON.stringify(m.messages).length <= policy.maxInputCharacters;
+  const endpoint = createPartitionDataChannel({ channel, localParticipantId, remoteParticipantId, limits,
+    async authorize({ action, metadata, byteLength }) {
+      if (byteLength !== 0) return false;
+      if (metadata.operation === 'describe') return true;
+      if (metadata.operation === 'publication') {
+        const sending = action === 'send' || action === 'accept';
+        const request = (sending ? active : deliveries).get(metadata.attemptId)?.request;
+        return (canonical || ordered) && !!request && matchingEntryPublication(metadata, request)
+          && request.requesterId === (sending ? remoteParticipantId : localParticipantId)
+          && await authorize(structuredClone(request), { action }) === true;
+      }
+      if (metadata.operation === 'state') {
+        // Admission state only, bound to an opted-in ordered attempt in flight on this channel.
+        const sending = action === 'send' || action === 'accept';
+        const request = (sending ? active : deliveries).get(metadata.attemptId)?.request;
+        return !!request && orderedInput(request) && request.attemptState === ATTEMPT_STATE_SCHEMA
+          && metadata.requesterId === request.requesterId && metadata.requesterId === (sending ? remoteParticipantId : localParticipantId)
+          && metadata.coordinatorId === request.coordinatorId && metadata.threadId === request.threadId
+          && sameRouteAttemptIdentity(metadata.identity, attempt(request)) && ATTEMPT_STATES.includes(metadata.status);
+      }
+      if (metadata.operation === 'closed') {
+        const sending = action === 'send' || action === 'accept';
+        const request = (sending ? active : deliveries).get(metadata.attemptId)?.request;
+        return !!request?.charge && sameRouteAttemptIdentity(metadata.identity, attempt(request))
+          && metadata.requesterId === request.requesterId && metadata.coordinatorId === request.coordinatorId;
+      }
+      if (metadata.operation === 'output') {
+        const sending = action === 'send' || action === 'accept';
+        const request = sending ? active.get(metadata.attemptId)?.request : deliveries.get(metadata.attemptId)?.request;
+        return !!request && orderedInput(request) && request.charge !== undefined && metadata.requesterId === request.requesterId
+          && metadata.requesterId === (sending ? remoteParticipantId : localParticipantId)
+          && metadata.coordinatorId === request.coordinatorId && metadata.threadId === request.threadId
+          && sameRouteAttemptIdentity(metadata.identity, attempt(request)) && Number.isSafeInteger(metadata.step) && metadata.step >= 0
+          && typeof metadata.delta === 'string' && metadata.delta.length <= policy.maxOutputCharacters && typeof metadata.done === 'boolean'
+          && (metadata.receipt === null || !!metadata.receipt && typeof metadata.receipt === 'object' && !Array.isArray(metadata.receipt));
+      }
+      if (metadata.operation === 'delta' || metadata.operation === 'usage') {
+        const sending = action === 'send' || action === 'accept';
+        const request = sending ? active.get(metadata.attemptId)?.request : deliveries.get(metadata.attemptId)?.request;
+        return !!request && request.schema !== 'reploid.partition-input/v2'
+          && (!orderedInput(request) || request.disclosureExpiresAt === undefined || request.disclosureExpiresAt > now()) && metadata.requesterId === request.requesterId
+          && (orderedInput(request) ? metadata.coordinatorId === request.coordinatorId
+            && sameRouteAttemptIdentity(metadata.identity, attempt(request)) : metadata.participantA === request.participantA) && metadata.threadId === request.threadId
+          && metadata.requesterId === (sending ? remoteParticipantId : localParticipantId)
+          && (metadata.activity === undefined || request.activity === 'reploid.partition-activity/v1'
+            && orderedInput(request) && sameRouteAttemptIdentity(metadata.activity?.identity, attempt(request)))
+          && (metadata.operation === 'usage' ? !!request.generationRequest
+            && canonicalPartitionJson(metadata.generationRequest) === canonicalPartitionJson(request.generationRequest)
+            && metadata.usage?.outputTokens === 0
+            && canonicalPartitionJson(metadata.usage) === canonicalPartitionJson(tokenUsage(metadata.usage?.inputTokens, 0, request.generationRequest))
+            : Number.isSafeInteger(metadata.sequence) && metadata.sequence >= 0
+              && typeof metadata.text === 'string' && metadata.text.length <= policy.maxOutputCharacters);
+      }
+      const outgoing = action === 'send' || action === 'accept';
+      if (!valid(metadata) || metadata.requesterId !== (outgoing ? localParticipantId : remoteParticipantId)
+        || coordinator(metadata) !== (outgoing ? remoteParticipantId : localParticipantId)) return false;
+      // Recheck input permission before transfer and output disclosure, not readiness
+      // after completion: draining must still let admitted work finish.
+      return await authorize(structuredClone(metadata), { action }) === true;
+    },
+    async serve(m, _bytes, { signal }) {
+      if (m.operation === 'publication') {
+        const scope = deliveries.get(m.attemptId)?.publication;
+        assert(scope, 'Requester publication owner unavailable');
+        return scope.call(m.method, m.body);
+      }
+      if (m.operation === 'state') {
+        const delivery = deliveries.get(m.attemptId);
+        assert(delivery, 'Unexpected attempt state');
+        await delivery.onState?.(m.status); return { received: true };
+      }
+      if (m.operation === 'closed') {
+        const delivery = deliveries.get(m.attemptId);
+        assert(delivery, 'Unexpected accounting closure');
+        delivery.accountingClosed.resolve(m.settlement ?? null);
+        return { received: true };
+      }
+      if (m.operation === 'output') {
+        // The requester's own port decides whether this output is acknowledged; only its signed answer returns.
+        const delivery = deliveries.get(m.attemptId);
+        assert(delivery, 'Unexpected attempt output');
+        const acknowledged = await delivery.onOutput?.({ step: m.step, delta: m.delta, done: m.done, receipt: structuredClone(m.receipt) });
+        return { received: true, acknowledged: acknowledged ?? null };
+      }
+      if (m.operation === 'usage') {
+        const delivery = deliveries.get(m.attemptId);
+        assert(delivery && !delivery.usage && delivery.sequence === 0, 'Unexpected or duplicate input token usage');
+        delivery.usage = structuredClone(m.usage);
+        await delivery.onUsage?.(structuredClone(m.usage)); return {received: true};
+      }
+      if (m.operation === 'delta') {
+        const delivery = deliveries.get(m.attemptId);
+        assert(delivery && (!delivery.request.generationRequest || delivery.usage) && m.sequence === delivery.sequence, 'Stream delta is stale or out of order');
+        if (m.activity) {
+          const activity = partitionActivity(m.activity, attempt(delivery.request), delivery.activity, true);
+          delivery.activity = activity;
+          await delivery.onActivity?.(structuredClone(activity));
+        }
+        delivery.characters += m.text.length;
+        assert(delivery.characters <= policy.maxOutputCharacters, 'Stream output budget exhausted');
+        delivery.sequence++; if (orderedInput(delivery.request)) delivery.content += m.text; delivery.onDelta?.(m.text); return { received: true };
+      }
+      if (m.operation === 'describe') {
+        if (service && !draining && !closed) await service.refresh({ signal });
+        const models = service?.getModels() || [];
+        return { models: structuredClone(models), accepting: !!service && !draining && !closed,
+          slots: draining || closed ? 0 : policy.maxConcurrentAttempts - active.size };
+      }
+      // A draining, closed or full entry is unavailable capacity for this requester, never a generic failure.
+      assertCapacity(service && !draining && !closed && active.size < policy.maxConcurrentAttempts);
+      assert(!retired.has(m.attemptId), 'Entry attempt already used');
+      assertCapacity(retired.size < policy.maxAttempts);
+      const model = service.getModels().find(model => model.id === m.modelId && model.identity === m.modelIdentity
+        && model.partition?.planId === m.planId && (orderedInput(m)
+          ? model.partition.schema === 'reploid.partition-selection/v2' && model.partition.coordinatorId === m.coordinatorId
+            && canonicalPartitionJson(model.partition.route) === canonicalPartitionJson(m.route)
+          : model.partition.participantA === m.participantA && model.partition.participantB === m.participantB)
+        && model.availability === 'ready');
+      assertCapacity(model);
+      const requested = requireGenerationCapability(model, m.generationRequest, m.schema === 'reploid.partition-input/v2');
+      const isCanonical = m.schema === 'reploid.partition-input/v2';
+      if (isCanonical) {
+        assert(model.canonical && ['coordinatorEpoch', 'routeId', 'generation', 'stages', 'vocabSize'].every(key =>
+          canonicalPartitionJson(model.canonical[key]) === canonicalPartitionJson(m.canonical[key])),
+        'Canonical entry placement changed');
+      }
+      // Ordered inputs carrying a requester context publish through the same requester-owned RPC.
+      const orderedPublished = orderedInput(m) && m.publication !== undefined;
+      const publicationCall = (method, body) => endpoint.request(entryPublicationEnvelope(m, method, body),
+        new Uint8Array(), { signal });
+      const publication = isCanonical || orderedPublished ? entryPublicationPort(publicationCall) : undefined;
+      retired.add(m.attemptId);
+      const admission = { request: structuredClone(m), operation: null };
+      active.set(m.attemptId, admission);
+      let delivery = Promise.resolve(), sequence = 0, activity = null, acceptingCallbacks = true;
+      const operation = Promise.resolve().then(() => service.generate({ meshId: m.meshId, participantId: m.requesterId,
+        threadId: m.threadId, attemptId: m.attemptId, placementGeneration: m.placementGeneration,
+        model, ...(requested ? {generationRequest: requested} : {}), ...(orderedInput(m) && m.disclosureExpiresAt !== undefined ? {disclosureExpiresAt:m.disclosureExpiresAt} : {}), ...(isCanonical ? { canonical: structuredClone(m.canonical) } : {}),
+        ...(orderedPublished ? { publication: structuredClone(m.publication) } : {}), ...(m.charge !== undefined ? { charge: structuredClone(m.charge) } : {}),
+        messages: structuredClone(m.messages), permissions: { sharingScope: 'approved-partition-path' } },
+      { signal, publication, requestApproval: async () => authorize(structuredClone(m), { action: 'execute' }),
+        ...(m.charge !== undefined ? { onOutput(record) {
+          if (!acceptingCallbacks) return null;
+          return endpoint.request({ operation: 'output', requesterId: m.requesterId, coordinatorId: m.coordinatorId, identity: attempt(m),
+            threadId: m.threadId, attemptId: m.attemptId, step: record.step, delta: record.delta, done: record.done, receipt: record.receipt ?? null },
+          new Uint8Array()).then(response => response?.acknowledged ?? null);
+        } } : {}),
+        onState(value) {
+          // Older requesters did not opt in; an opted-in one learns only queued/executing for this attempt.
+          if (m.attemptState === undefined || !acceptingCallbacks || !ATTEMPT_STATES.includes(value?.status)
+            || value.threadId !== m.threadId || value.attemptId !== m.attemptId) return;
+          const metadata = { operation: 'state', requesterId: m.requesterId, coordinatorId: m.coordinatorId, identity: attempt(m),
+            threadId: m.threadId, attemptId: m.attemptId, status: value.status };
+          delivery = delivery.then(() => endpoint.request(metadata, new Uint8Array(), { signal }));
+          delivery.catch(() => {});
+        }, onActivity(value) {
+          if (m.activity === undefined) return; // Older requesters did not opt in to this event.
+          assert(acceptingCallbacks && orderedInput(m) && value.threadId === m.threadId && value.attemptId === m.attemptId, 'Unbound or late partition activity');
+          activity = partitionActivity(value, attempt(m), activity);
+        }, onUsage(value) {
+          assert(requested && value.threadId === m.threadId && value.attemptId === m.attemptId, 'Unbound provider usage');
+          const usage = tokenUsage(value.inputTokens, value.outputTokens, requested);
+          assert(value.outputTokens === 0 && value.schema === usage.schema, 'Initial usage must precede sampling');
+          const metadata = {operation:'usage', requesterId:m.requesterId,
+            ...(orderedInput(m) ? {coordinatorId:m.coordinatorId, identity:attempt(m)} : {participantA:m.participantA}),
+            threadId:m.threadId, attemptId:m.attemptId, generationRequest:requested, usage};
+          delivery = delivery.then(() => endpoint.request(metadata, new Uint8Array(), {signal}));
+          delivery.catch(() => {}); return delivery;
+        }, onDelta({ text }) {
+          if (isCanonical || orderedPublished) return; // Requester projects the durable publication RPC, never this raw callback.
+          const delta = { operation: 'delta', requesterId: m.requesterId,
+            ...(orderedInput(m) ? { coordinatorId: m.coordinatorId, identity: attempt(m) } : { participantA: m.participantA }),
+            threadId: m.threadId, attemptId: m.attemptId, sequence: sequence++, text,
+            ...(activity ? {activity:structuredClone(activity)} : {}) };
+          delivery = delivery.then(() => endpoint.request(delta, new Uint8Array(), { signal }));
+          delivery.catch(() => {});
+        } }));
+      admission.operation = operation;
+      let settlement = null;
+      try {
+        const result = await operation;
+        settlement = result.execution?.settlement ?? null;
+        acceptingCallbacks = false;
+        await delivery;
+        assert(typeof result.content === 'string' && result.content.length <= policy.maxOutputCharacters
+          && (orderedInput(m) ? sameRouteAttemptIdentity(result.execution?.identity, attempt(m))
+            : result.execution?.requesterId === m.requesterId && result.execution.attemptId === m.attemptId
+              && result.execution.placementGeneration === m.placementGeneration), 'Execution returned an unbound result');
+        return { content: result.content, ...(activity ? {activity:structuredClone(activity)} : {}), ...(requested ? {usage: result.usage} : {}), execution: summarizePartitionExecution(result.execution) };
+      } catch (error) {
+        settlement ??= error.partitionSettlement ?? null;
+        throw error;
+      } finally {
+        acceptingCallbacks = false;
+        if (m.charge) await endpoint.request({ operation: 'closed', requesterId: m.requesterId, coordinatorId: m.coordinatorId,
+          identity: attempt(m), attemptId: m.attemptId, settlement }, new Uint8Array()).catch(() => {});
+        active.delete(m.attemptId);
+      }
+    },
+  });
+  return Object.freeze({
+    id: remoteParticipantId,
+    getState() { return { ready: !closed && unsettledPublications.size === 0 && now() - observedAt < policy.descriptorTtlMs
+      && descriptor?.accepting === true && descriptor.slots > 0,
+    descriptor: structuredClone(descriptor), observedAt, receipt: endpoint.getReceipt() }; },
+    async refresh({ signal } = {}) {
+      descriptor = await endpoint.request({ operation: 'describe' }, new Uint8Array(), { signal });
+      assert(Array.isArray(descriptor.models) && Number.isSafeInteger(descriptor.slots) && descriptor.slots >= 0,
+        'Invalid entry descriptor');
+      observedAt = now(); return this.getState();
+    },
+    async generate(request, { signal, onDelta, onUsage, onActivity, onOutput, onState, publication, onPublished } = {}) {
+      assertCapacity(!closed && this.getState().ready);
+      assert(request.charge === undefined || typeof onOutput === 'function', 'A charged ordered input needs its acknowledgment port');
+      const isCanonical = request.canonical !== undefined, isOrdered = request.route !== undefined;
+      assert(!isOrdered || ordered && !isCanonical, 'Ordered entry capability unavailable');
+      assert(!isCanonical || canonical, 'Canonical entry capability unavailable');
+      assert((publication !== undefined) === (isCanonical || isOrdered && request.publication !== undefined),
+        'Publication owner requires its explicit canonical or ordered requester context');
+      const metadata = { ...structuredClone(request), operation: 'generate',
+        schema: isOrdered ? 'reploid.partition-input/v3' : isCanonical ? 'reploid.partition-input/v2' : 'reploid.partition-input/v1',
+        ...(isOrdered && typeof onActivity === 'function' ? {activity:'reploid.partition-activity/v1'} : {}),
+        ...(isOrdered && typeof onState === 'function' ? { attemptState: ATTEMPT_STATE_SCHEMA } : {}),
+        requesterId: localParticipantId, ...(isOrdered ? { coordinatorId: remoteParticipantId } : { participantA: remoteParticipantId }) };
+      assert(!deliveries.has(metadata.attemptId), 'Entry attempt already streaming');
+      assert(valid(metadata), 'Invalid partition entry input');
+      const scope = publication !== undefined ? createEntryPublicationScope({ request: metadata, owner: publication, onPublished,
+        authorize: () => authorize(structuredClone(metadata), { action: 'publish' }),
+        maxControlBytes: limits.maxControlBytes, maxOutputCharacters: policy.maxOutputCharacters }) : null;
+      const accountingClosed = Promise.withResolvers();
+      deliveries.set(metadata.attemptId, { accountingClosed, request: metadata, sequence: 0, characters: 0, content: '', onDelta, onUsage, onActivity, onOutput, onState, activity:null, usage:null, publication: scope });
+      let result;
+      let failure = null;
+      try {
+        result = await endpoint.request(metadata, new Uint8Array(), { signal });
+      assert(typeof result.content === 'string' && result.content.length <= policy.maxOutputCharacters
+        && (isOrdered ? sameRouteAttemptIdentity(result.execution?.identity, attempt(metadata))
+          : ['requesterId', 'participantA', 'participantB', 'modelId', 'modelIdentity', 'planId', 'threadId',
+            'attemptId', 'placementGeneration'].every(key => result.execution?.[key] === metadata[key])),
+      'Entry response identity mismatch');
+      const currentDelivery = deliveries.get(metadata.attemptId);
+      let finalActivityNotification = null;
+      if (result.activity) {
+        assert(metadata.activity === 'reploid.partition-activity/v1', 'Unrequested execution activity');
+        if (currentDelivery.activity?.sequence === result.activity.sequence) {
+          assert(canonicalPartitionJson(currentDelivery.activity) === canonicalPartitionJson(result.activity), 'Final activity changed an observed sample');
+        } else {
+          const finalActivity = partitionActivity(result.activity, attempt(metadata), currentDelivery.activity, true);
+          finalActivityNotification = finalActivity;
+        }
+      }
+      const observedActivity = finalActivityNotification ?? currentDelivery.activity;
+      if (observedActivity) assert(canonicalPartitionJson(result.execution.stepSummary.stages) === canonicalPartitionJson(observedActivity.stepSummary.stages)
+        && result.execution.stepSummary.count === observedActivity.stepSummary.count, 'Final execution differs from observed activity');
+      if (metadata.generationRequest) {
+        const observed = deliveries.get(metadata.attemptId).usage;
+        assert(observed && result.usage?.inputTokens === observed.inputTokens
+          && result.usage.outputTokens === result.execution?.stepSummary?.count
+          && canonicalPartitionJson(result.usage) === canonicalPartitionJson(tokenUsage(result.usage.inputTokens, result.usage.outputTokens, metadata.generationRequest)),
+        'Final token usage differs from admitted observed input');
+      }
+      if (isOrdered && !scope) assert(result.content === deliveries.get(metadata.attemptId).content, 'Ordered result differs from delivered text');
+      if (scope) {
+        const projection = scope.getProjection();
+        assert(projection.count > 0 && projection.terminal && result.content === projection.content, 'Entry result differs from durable publication');
+      }
+      if (finalActivityNotification) {
+        currentDelivery.activity = finalActivityNotification;
+        await onActivity?.(structuredClone(finalActivityNotification));
+      }
+      }
+      catch (error) { failure = error; }
+      finally {
+        // Cancellation stops generation, not already-issued signed output receipts. Keep their
+        // receiving port until the coordinator closes accounting, or the channel's bounded wait.
+        if (failure && metadata.charge) {
+          let timer;
+          try {
+            const settlement = await Promise.race([accountingClosed.promise,
+              new Promise(resolve => { timer = setTimeout(() => resolve(null), limits.timeoutMs); })]);
+            if (settlement && typeof failure === 'object') failure.partitionSettlement = settlement;
+          } finally { clearTimeout(timer); }
+        }
+        try { await scope?.close({ cancel: failure !== null }); }
+        catch (error) {
+          unsettledPublications.add(scope);
+          failure = failure ? new AggregateError([failure, error], 'Entry execution and publication cancellation failed') : error;
+        }
+        deliveries.delete(metadata.attemptId);
+      }
+      if (failure) throw failure;
+      return result;
+    },
+    async drain() { draining = true; await Promise.allSettled([...active.values()].map(item => item.operation)); },
+    async close() {
+      closed = true; endpoint.close();
+      const scopes = [...new Set([...unsettledPublications, ...[...deliveries.values()].map(item => item.publication).filter(Boolean)])];
+      const closing = await Promise.allSettled(scopes.map(async scope => {
+        unsettledPublications.add(scope);
+        await scope.close({ cancel: true }); unsettledPublications.delete(scope);
+      }));
+      await Promise.allSettled([...active.values()].map(item => item.operation));
+      const failures = closing.filter(item => item.status === 'rejected').map(item => item.reason);
+      if (failures.length) throw new AggregateError(failures, 'Entry publication cancellation did not settle');
+      deliveries.clear();
+    },
+  });
+}
+
+/** Bounded retry starts a new generation attempt on an explicitly authorized path.
+ * No partial generation state is fabricated or merged across owners.
+ */
+export function createPartitionRequester({ entries, requesterId, meshId, modelId, modelIdentity, planId,
+  maxPlacements, ordered = false, authorize, onAttempt = () => {}, newId = () => crypto.randomUUID(), now = () => performance.now() }) {
+  assert(typeof ordered === 'boolean' && typeof entries === 'function' && typeof authorize === 'function'
+    && Number.isSafeInteger(maxPlacements) && maxPlacements > 0, 'Explicit requester placement policy required');
+  return Object.freeze({
+    async generate({ messages, threadId, disclosureExpiresAt, generationRequest: requested }, { signal, onDelta, onUsage, onActivity } = {}) {
+      assert(disclosureExpiresAt === undefined || ordered && Number.isSafeInteger(disclosureExpiresAt) && disclosureExpiresAt > Date.now(),
+        'Requester disclosure deadline expired or invalid');
+      messages = structuredClone(messages);
+      requested = generationRequest(requested);
+      const attempted = new Set(), failures = [], started = now();
+      for (let generation = 0; generation < maxPlacements; generation++) {
+        signal?.throwIfAborted();
+        let selected = null;
+        for (const entry of entries()) {
+          if (attempted.has(entry.id)) continue;
+          try {
+            const state = await entry.refresh({ signal });
+            const model = state.descriptor?.models.find(m => m.id === modelId && m.identity === modelIdentity
+              && m.partition?.planId === planId && m.availability === 'ready'
+              && (ordered ? m.partition.schema === 'reploid.partition-selection/v2' && m.partition.coordinatorId === entry.id
+                : m.partition.route === undefined));
+            if (!state.ready || !model) continue;
+            requireGenerationCapability(model, requested);
+            const placement = { requesterId, modelId, modelIdentity, planId,
+              ...(requested ? {generationRequest: requested} : {}),
+              ...(disclosureExpiresAt !== undefined ? {disclosureExpiresAt} : {}),
+              ...(ordered ? {coordinatorId: entry.id, route: structuredClone(model.partition.route)}
+                : {participantA: entry.id, participantB: model.partition.participantB}) };
+            if (ordered) {
+              const binding = canonicalRouteAttemptBinding({schema:'reploid.partition-attempt/v2', threadId,
+                attemptId:'placement-validation', requesterId, placementGeneration:generation, route:placement.route});
+              assert(binding.route.stages[0].participantId === entry.id && binding.route.modelId === modelId
+                && binding.route.modelIdentity === modelIdentity && binding.route.planId === planId, 'Requester route model or coordinator mismatch');
+            }
+            if (await authorize(structuredClone(placement)) === true) { selected = { entry, placement }; break; }
+          } catch (error) { signal?.throwIfAborted(); failures.push({ ...(ordered ? {coordinatorId:entry.id} : {participantA:entry.id}), error: String(error.message) }); }
+        }
+        assert(selected, 'No authorized prepared partition path is available');
+        attempted.add(selected.entry.id);
+        const request = { ...selected.placement, meshId, threadId, messages: structuredClone(messages),
+          attemptId: newId(), placementGeneration: generation };
+        onAttempt({ ...structuredClone(request), messages: undefined, phase: generation ? 'restarting' : 'executing' });
+        let published = false;
+        try {
+          const result = await selected.entry.generate(request, { signal,
+            ...(onActivity ? {onActivity: activity => { published = true; return onActivity({threadId,attemptId:request.attemptId,...activity}); }} : {}),
+            onUsage: usage => { published = true; return onUsage?.(usage); },
+            onDelta: text => { published = true; return onDelta?.({text,threadId,attemptId:request.attemptId,placementGeneration:generation}); } });
+          return { ...result, recovery: { attempts: generation + 1, failures, elapsedMs: now() - started,
+            stateTransfer: 'new-attempt-from-authorized-input' } };
+        } catch (error) {
+          if (published) throw error;
+          signal?.throwIfAborted(); failures.push({ ...(ordered ? {coordinatorId:selected.entry.id} : {participantA:selected.entry.id}), attemptId: request.attemptId, error: String(error.message) });
+          onAttempt({ attemptId: request.attemptId, placementGeneration: generation, phase: 'failed', error: String(error.message) });
+        }
+      }
+      throw new AggregateError(failures.map(f => new Error(f.error)), 'Prepared partition attempts exhausted');
+    },
+  });
+}

package/packages/reploid/src/mesh/partitions/partition-generation-request.js

@@ -0,0 +1,33 @@
+import { assertPartition as assert } from './partition-contract.js';
+
+export const TEXT_GENERATION_CAPABILITY = Object.freeze({ schema: 'reploid.text-generation/v1', usage: 'raw-model-tokens/v1' });
+
+/** Optional caller ceiling, not a sampling override or a new generation policy. */
+export function generationRequest(value) {
+  if (value === undefined) return undefined;
+  assert(value && typeof value === 'object' && !Array.isArray(value)
+    && Object.keys(value).length === 3 && value.schema === 'reploid.partition-generation-request/v1'
+    && value.usage === 'raw-model-tokens/v1' && Number.isSafeInteger(value.maxOutputTokens) && value.maxOutputTokens > 0,
+  'Invalid caller token limit or usage contract');
+  return Object.freeze({ schema: value.schema, maxOutputTokens: value.maxOutputTokens, usage: value.usage });
+}
+export function requireGenerationCapability(model, requested, canonical = false) {
+  const value = generationRequest(requested);
+  if (value) assert(!canonical && model?.textGeneration?.schema === TEXT_GENERATION_CAPABILITY.schema
+    && model.textGeneration.usage === TEXT_GENERATION_CAPABILITY.usage, 'Prepared route lacks caller token limit and usage capability');
+  return value;
+}
+export function boundedGeneration(settings, requested) {
+  const value = generationRequest(requested);
+  if (!value) return settings;
+  assert(value.maxOutputTokens <= settings.maxTokens, 'Caller token limit exceeds the prepared generation allocation');
+  return { ...settings, maxTokens: value.maxOutputTokens };
+}
+/** Counts the provider's actual template tokenization and raw sampled tokens,
+ * including any terminal token. No counts are inferred from visible text. */
+export function tokenUsage(inputTokens, outputTokens, requested) {
+  const value = generationRequest(requested);
+  assert(value && Number.isSafeInteger(inputTokens) && inputTokens > 0 && Number.isSafeInteger(outputTokens)
+    && outputTokens >= 0 && outputTokens <= value.maxOutputTokens, 'Invalid provider token usage');
+  return Object.freeze({ schema: value.usage, inputTokens, outputTokens });
+}