reploid 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,192 @@
+import failureMessages from '../../transport/partition-errors.json' with { type: 'json' };
+import { canonicalize } from '../../artifacts/canonical-json.js';
+import { sha256Hex } from '../../artifacts/signatures.js';
+
+/** Shared orchestration bindings. Tensor semantics remain supplied by Doppler. */
+export const partitionIdentityKeys = Object.freeze(['modelId', 'modelIdentity', 'planId', 'threadId', 'attemptId', 'participantA', 'participantB']);
+export const partitionActions = Object.freeze(['mesh.execute_partition_a', 'mesh.execute_partition_b',
+  'mesh.transfer_intermediate_activation', 'mesh.transfer_token_context', 'mesh.transfer_partition_output']);
+export const assertPartition = (value, message) => { if (!value) throw new Error(message); };
+/** A declared failure whose code and message cross every channel hop together; an uncoded error
+ * becomes EXECUTION_FAILED at the next hop. `detail` adds non-message fields, such as a bound. */
+export function partitionFailure(code, detail = {}) {
+  assertPartition(Object.hasOwn(failureMessages, code), 'Undeclared partition failure code');
+  return Object.assign(new Error(failureMessages[code]), detail, { code });
+}
+/** Throw CAPACITY_UNAVAILABLE unless `value` holds: an exhausted or closed admission slot, never a defect. */
+export const assertCapacity = value => { if (!value) throw partitionFailure('CAPACITY_UNAVAILABLE'); };
+export const samePartitionIdentity = (actual, expected) => actual && [...partitionIdentityKeys, 'requesterId', 'placementGeneration'].every(key => actual[key] === expected[key]);
+/** Ask the injected provider for tensor layout; retain the accepted v1 adapter. */
+export function partitionActivationContract(runtime, plan) {
+  if (runtime.getPartitionActivationContract) {
+    assertPartition(typeof runtime.validateActivationFrameForPlan === 'function', 'Doppler activation validator required');
+    return Object.freeze({ ...runtime.getPartitionActivationContract(plan) });
+  }
+  assertPartition(plan?.schema === runtime.LAYER_PARTITION_SCHEMA
+    && plan.activationPrecision === undefined && plan.activationComponents === undefined
+    && plan.activationElementStrideBytes === undefined, 'Unsupported Doppler partition activation contract');
+  return Object.freeze({ schema: runtime.ACTIVATION_TENSOR_SCHEMA, dtype: plan.activationDtype,
+    hiddenSize: plan.hiddenSize, precision: plan.activationDtype, components: 1,
+    elementStrideBytes: plan.activationDtype === 'f16' ? 2 : 4 });
+}
+export function matchingPartitionActivation(value, contract, frame = false) {
+  if (frame && contract.components === 1) {
+    return value?.dtype === contract.dtype && ['precision', 'components', 'elementStrideBytes']
+      .every(key => value[key] === undefined);
+  }
+  return value?.dtype === contract.dtype && ['precision', 'components', 'elementStrideBytes']
+    .every(key => value[key] === contract[key] || contract.components === 1 && value[key] === undefined);
+}
+export function validatePartitionIdentity(identity) {
+  assertPartition(identity && typeof identity === 'object' && !Array.isArray(identity) && partitionIdentityKeys.every(key => typeof identity[key] === 'string'
+    && identity[key].length > 0 && identity[key].length <= 256)
+    && /^sha256:[a-f0-9]{64}$/.test(identity.modelIdentity)
+    && identity.participantA !== identity.participantB, 'Invalid partition identity');
+  if (identity.requesterId !== undefined || identity.placementGeneration !== undefined) {
+    assertPartition(typeof identity.requesterId === 'string' && identity.requesterId.length > 0 && identity.requesterId.length <= 256
+      && Number.isSafeInteger(identity.placementGeneration) && identity.placementGeneration >= 0, 'Invalid requester placement binding');
+  }
+}
+/** Snapshot the complete validated identity; optional placement fields travel as a pair. */
+export function canonicalPartitionBinding(identity) {
+  validatePartitionIdentity(identity);
+  const keys = identity.requesterId === undefined ? partitionIdentityKeys
+    : [...partitionIdentityKeys, 'requesterId', 'placementGeneration'];
+  return Object.freeze(Object.fromEntries(keys.map(key => [key, identity[key]])));
+}
+const assertFiniteJson = value => {
+  if (Array.isArray(value)) return value.forEach(item => assertFiniteJson(item));
+  if (value && typeof value === 'object') return Object.keys(value).forEach(key => assertFiniteJson(value[key]));
+  assertPartition(value === null || ['string', 'boolean'].includes(typeof value)
+    || typeof value === 'number' && Number.isFinite(value), 'Partition metadata must be finite JSON');
+};
+/** The library's canonical JSON (artifacts/canonical-json.js) of finite JSON metadata. */
+export function canonicalPartitionJson(value) {
+  assertFiniteJson(value);
+  return canonicalize(value);
+}
+export async function partitionFingerprint(metadata, bytes = new Uint8Array()) {
+  const header = new TextEncoder().encode(canonicalPartitionJson(metadata));
+  const input = new Uint8Array(4 + header.length + bytes.length);
+  new DataView(input.buffer).setUint32(0, header.length);
+  input.set(header, 4); input.set(bytes, 4 + header.length);
+  return sha256Hex(input);
+}
+
+export const PARTITION_ROUTE_SCHEMA = 'reploid.partition-route/v1';
+export const ROUTE_ATTEMPT_SCHEMA = 'reploid.partition-attempt/v2';
+const identifier = value => typeof value === 'string' && value.length > 0 && value.length <= 256;
+const exactFields = (value, keys) => value && typeof value === 'object' && !Array.isArray(value)
+  && Object.keys(value).length === keys.length && keys.every(key => Object.hasOwn(value, key));
+const freezeRouteJson = value => {
+  if (value && typeof value === 'object') { Object.values(value).forEach(freezeRouteJson); Object.freeze(value); }
+  return value;
+};
+/** Structural checks also apply when comparing a received identity without a runtime. */
+export function canonicalPartitionRoute(route) {
+  assertPartition(exactFields(route, ['schema', 'modelId', 'modelIdentity', 'planId', 'stages', 'activation'])
+    && route.schema === PARTITION_ROUTE_SCHEMA && identifier(route.modelId) && /^sha256:[a-f0-9]{64}$/.test(route.planId)
+    && /^sha256:[a-f0-9]{64}$/.test(route.modelIdentity)
+    && Array.isArray(route.stages) && route.stages.length >= 2, 'Invalid partition route');
+  const participants = new Set(), transports = new Set();
+  route.stages.forEach((stage, index) => {
+    assertPartition(exactFields(stage, ['index', 'participantId', 'transportId', 'residentId', 'executionId'])
+      && stage.index === index && ['participantId', 'transportId', 'residentId', 'executionId'].every(key => identifier(stage[key]))
+      && !participants.has(stage.participantId) && !transports.has(stage.transportId), 'Invalid or duplicate route stage');
+    participants.add(stage.participantId); transports.add(stage.transportId);
+  });
+  const layout = route.activation;
+  assertPartition(exactFields(layout, ['schema', 'dtype', 'hiddenSize', 'precision', 'components', 'elementStrideBytes'])
+    && layout.schema === (layout.precision === 'two-f32' ? 'doppler.activation-tensor/v2' : 'doppler.activation-tensor/v1')
+    && Number.isSafeInteger(layout.hiddenSize) && layout.hiddenSize > 0
+    && (layout.precision === 'two-f32' ? layout.dtype === 'f32' && layout.components === 2 && layout.elementStrideBytes === 8
+      : ['f32', 'f16'].includes(layout.dtype) && layout.precision === layout.dtype && layout.components === 1
+        && layout.elementStrideBytes === (layout.dtype === 'f16' ? 2 : 4)), 'Invalid route activation layout');
+  return freezeRouteJson(structuredClone(route));
+}
+/** Provider hashing validates its plan geometry; host admission separately binds the selected manifest. */
+export async function validatePartitionRoute(runtime, plan, route) {
+  const snapshot = canonicalPartitionRoute(route), planSnapshot = structuredClone(plan);
+  assertPartition(typeof runtime?.hashLayerPartitionPlan === 'function'
+    && typeof runtime.getPartitionActivationContract === 'function', 'Ordered Doppler contracts required');
+  assertPartition(planSnapshot?.schema === 'doppler.layer-partition-contract/v3'
+    && planSnapshot.modelId === snapshot.modelId && planSnapshot.stageCount === snapshot.stages.length
+    && Array.isArray(planSnapshot.partitions) && planSnapshot.partitions.length === snapshot.stages.length
+    && planSnapshot.partitions.every((part, index) => part.index === index), 'Route plan stage mismatch');
+  const layout = partitionActivationContract(runtime, planSnapshot);
+  assertPartition(canonicalPartitionJson(layout) === canonicalPartitionJson(snapshot.activation), 'Route activation mismatch');
+  assertPartition(await runtime.hashLayerPartitionPlan(planSnapshot) === snapshot.planId, 'Route plan identity mismatch');
+  return snapshot;
+}
+export function canonicalRouteAttemptBinding(identity) {
+  assertPartition(exactFields(identity, ['schema', 'threadId', 'attemptId', 'requesterId', 'placementGeneration', 'route'])
+    && identity.schema === ROUTE_ATTEMPT_SCHEMA && ['threadId', 'attemptId', 'requesterId'].every(key => identifier(identity[key]))
+    && Number.isSafeInteger(identity.placementGeneration) && identity.placementGeneration >= 0, 'Invalid route attempt identity');
+  return Object.freeze({ schema: identity.schema, threadId: identity.threadId, attemptId: identity.attemptId,
+    requesterId: identity.requesterId, placementGeneration: identity.placementGeneration, route: canonicalPartitionRoute(identity.route) });
+}
+export function sameRouteAttemptIdentity(actual, expected) {
+  try { return canonicalPartitionJson(canonicalRouteAttemptBinding(actual)) === canonicalPartitionJson(canonicalRouteAttemptBinding(expected)); }
+  catch { return false; }
+}
+
+/** A ready stage is inventory, not a complete chat path. This checks advertised
+ * binding only; entry refresh, grants and reservations remain authoritative. */
+export function isOrderedPartitionEntryModel(model, peer) {
+  try {
+    const selection = model?.partition;
+    if (peer.description?.schema !== 'reploid.partition-capability/v2' || model.index !== 0
+      || selection?.schema !== 'reploid.partition-selection/v2') return false;
+    const route = canonicalPartitionRoute(selection.route), first = route.stages[0];
+    return model.id === route.modelId && model.identity === route.modelIdentity
+      && model.planId === route.planId && selection.planId === route.planId
+      && selection.coordinatorId === first.participantId && first.participantId === peer.participantId
+      && first.transportId === peer.transportId && first.residentId === model.residentId
+      && first.executionId === model.executionId
+      && canonicalPartitionJson(route.activation) === canonicalPartitionJson(model.activation);
+  } catch { return false; }
+}
+
+/** One observed inventory version, bounded by host policy. These hints never authorize execution. */
+export function validateOrderedPartitionCapability(description, participantId, maxOffersPerPeer) {
+  assertPartition(Number.isSafeInteger(maxOffersPerPeer) && maxOffersPerPeer > 0, 'Explicit stage offer limit required');
+  assertPartition(description?.schema === 'reploid.partition-capability/v2' && description.participantId === participantId
+    && ['idle', 'waiting', 'loading', 'ready', 'stopping', 'failed'].includes(description.phase)
+    && Array.isArray(description.models) && description.models.length <= maxOffersPerPeer,
+  'Ordered partition capability identity or inventory mismatch');
+  const capacity = description.capacity;
+  assertPartition(capacity && typeof capacity.closed === 'boolean' && Number.isSafeInteger(capacity.active) && capacity.active >= 0
+    && Number.isSafeInteger(capacity.availableSlots) && capacity.availableSlots >= 0, 'Ordered partition capacity required');
+  for (const model of description.models) {
+    assertPartition(model && typeof model.id === 'string' && model.id.length > 0 && model.id.length <= 256
+      && /^sha256:[a-f0-9]{64}$/.test(model.identity) && Number.isSafeInteger(model.index) && model.index >= 0
+      && ['planId', 'residentId', 'executionId'].every(key => typeof model[key] === 'string' && model[key].length > 0 && model[key].length <= 256)
+      && ['ready', 'unavailable'].includes(model.availability), 'Invalid ordered partition offer');
+  }
+}
+
+/** Exact adapter selection travels in the plan digest, separate from the base manifest. */
+export function partitionAdapterIdentities(model) {
+  const adapters = model?.adapters ?? [];
+  assertPartition(Array.isArray(adapters) && adapters.length <= 1 && adapters.every(adapter =>
+    /^sha256:[a-f0-9]{64}$/.test(adapter.identity) && adapter.baseModelIdentity === model.identity),
+  'Partition adapter must target the exact base artifact');
+  return adapters.map(adapter => adapter.identity);
+}
+export function samePartitionAdapters(left, right) {
+  return canonicalPartitionJson(partitionAdapterIdentities(left)) === canonicalPartitionJson(partitionAdapterIdentities(right));
+}
+export function selectPartitionContribution(model, adapters = model.adapters ?? []) {
+  const selection = { ...model, adapters };
+  partitionAdapterIdentities(selection);
+  selection.adapters = adapters.map(adapter => {
+    const pinned = model.availableAdapters?.find(entry => entry.identity === adapter.identity
+      && entry.baseModelIdentity === model.identity);
+    assertPartition(pinned, 'Partition adapter is absent from the authorized catalog');
+    return structuredClone(pinned);
+  });
+  if (selection.partitionPlan && adapters.length) selection.partitionPlan = {
+    ...selection.partitionPlan, adapterIdentities: partitionAdapterIdentities(selection)
+  };
+  return structuredClone(selection);
+}

package/packages/reploid/src/mesh/partitions/partition-device-admission.js

@@ -0,0 +1,96 @@
+import failureMessages from '../../transport/partition-errors.json' with { type: 'json' };
+import { assertPartition as assert } from './partition-contract.js';
+
+const positive = value => Number.isSafeInteger(value) && value > 0;
+const unavailable = () => Object.assign(new Error(failureMessages.CAPACITY_UNAVAILABLE), { code: 'CAPACITY_UNAVAILABLE' });
+
+/** One admission budget per executing device (Launch 3, opt-in). It charges declared application
+ * allocations, not measured physical memory: each resident's weights once, plus `bytes` and one
+ * slot per admitted attempt, across every resident and route on the device. Callers release an
+ * attempt only after its cleanup settles, and a resident only after its provider closed.
+ *
+ * With `queue`, an attempt that does not fit waits instead of failing. Waiting is bounded in
+ * length, per requester and in time; each bound fails with CAPACITY_UNAVAILABLE. Grants go to the
+ * route owner (coordinator) with the fewest attempts admitted on this device, then the one served
+ * least recently, then first come, first served, with no overtaking by smaller requests. */
+export function createDeviceAdmission({ maxBytes, maxConcurrentAttempts, queue = null }) {
+  assert(positive(maxBytes) && positive(maxConcurrentAttempts), 'Explicit device admission budget required');
+  assert(queue === null || ['maxQueued', 'maxQueuedPerRequester', 'maxWaitMs'].every(key => positive(queue[key])),
+    'Explicit bounded admission queue required');
+  const residents = new Map(), attempts = new Map(), waiting = [], served = new Map();
+  let sequence = 0, grants = 0;
+  const attemptRows = () => [...attempts.values()].flatMap(rows => [...rows.values()]);
+  const residentBytes = () => [...residents.values()].reduce((total, bytes) => total + bytes, 0);
+  const attemptBytes = () => attemptRows().reduce((total, row) => total + row.bytes, 0);
+  const free = () => maxBytes - residentBytes() - attemptBytes();
+  const fits = bytes => attemptRows().length < maxConcurrentAttempts && bytes <= free();
+  const admittedFor = routeKey => attemptRows().filter(row => row.routeKey === routeKey).length;
+  function charge(entry) {
+    attempts.get(entry.owner).set(entry.attemptId, { bytes: entry.bytes, routeKey: entry.routeKey });
+    served.set(entry.routeKey, grants++);
+    // Forget idle route owners so this record stays bounded; a returning owner counts as least recent.
+    if (served.size > maxConcurrentAttempts + (queue?.maxQueued ?? 0)) for (const key of served.keys()) {
+      if (!admittedFor(key) && !waiting.some(row => row.routeKey === key)) served.delete(key);
+    }
+  }
+  function settle(entry, error) {
+    const at = waiting.indexOf(entry);
+    if (at < 0) return;
+    waiting.splice(at, 1);
+    clearTimeout(entry.timer); entry.signal?.removeEventListener('abort', entry.onAbort);
+    if (error) entry.reject(error); else { charge(entry); entry.resolve(); }
+  }
+  function pump() {
+    while (waiting.length) {
+      const next = waiting.reduce((best, entry) => {
+        const order = admittedFor(entry.routeKey) - admittedFor(best.routeKey)
+          || (served.get(entry.routeKey) ?? -1) - (served.get(best.routeKey) ?? -1) || entry.sequence - best.sequence;
+        return order < 0 ? entry : best;
+      });
+      if (!fits(next.bytes)) return;
+      settle(next, null);
+    }
+  }
+  return Object.freeze({
+    /** Charge resident weights once; a resident that does not fit is never offered. */
+    admitResident(owner, bytes) {
+      assert(owner && typeof owner === 'object' && positive(bytes), 'Device resident charge requires an owner and weight bytes');
+      if (residents.has(owner)) return;
+      if (bytes > free()) throw Object.assign(new Error('Device allocation budget cannot hold this resident'), { code: 'RESOURCE_EXHAUSTED' });
+      residents.set(owner, bytes); attempts.set(owner, new Map());
+    },
+    /** Admit one attempt on one resident; repeated admission of the same attempt charges once. */
+    async admit({ owner, attemptId, bytes, requesterId = null, routeKey = null, signal }) {
+      assert(residents.has(owner) && typeof attemptId === 'string' && attemptId.length > 0 && positive(bytes),
+        'Device attempt admission requires an admitted resident, attempt and allocation');
+      if (attempts.get(owner).has(attemptId)) return;
+      const queued = waiting.find(entry => entry.owner === owner && entry.attemptId === attemptId);
+      if (queued) return queued.promise;
+      signal?.throwIfAborted();
+      if (!waiting.length && fits(bytes)) { charge({ owner, attemptId, bytes, routeKey }); return; }
+      if (!queue || waiting.length >= queue.maxQueued
+        || waiting.filter(entry => entry.requesterId === requesterId).length >= queue.maxQueuedPerRequester) throw unavailable();
+      const { promise, resolve, reject } = Promise.withResolvers();
+      const entry = { owner, attemptId, bytes, requesterId, routeKey, sequence: sequence++, promise, resolve, reject, signal };
+      entry.timer = setTimeout(() => settle(entry, unavailable()), queue.maxWaitMs);
+      entry.onAbort = () => settle(entry, signal.reason);
+      signal?.addEventListener('abort', entry.onAbort, { once: true });
+      waiting.push(entry); pump();
+      return promise;
+    },
+    release(owner, attemptId) { attempts.get(owner)?.delete(attemptId); pump(); },
+    releaseResident(owner) {
+      for (const entry of waiting.filter(row => row.owner === owner)) settle(entry, unavailable());
+      residents.delete(owner); attempts.delete(owner); pump();
+    },
+    /** Attempts of `bytes` each that could still be admitted without waiting. */
+    available(bytes) {
+      assert(positive(bytes), 'Device availability requires an attempt allocation');
+      if (waiting.length) return 0;
+      return Math.max(0, Math.min(maxConcurrentAttempts - attemptRows().length, Math.floor(free() / bytes)));
+    },
+    getState: () => ({ maxBytes, maxConcurrentAttempts, residents: residents.size, residentBytes: residentBytes(),
+      attemptBytes: attemptBytes(), active: attemptRows().length, availableBytes: free(),
+      ...(queue ? { queued: waiting.length, maxQueued: queue.maxQueued } : {}) })
+  });
+}

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

@@ -0,0 +1,96 @@
+import { createPartitionDataChannel } from '../../transport/partition-data-channel.js';
+import { assertPartition as assert, validateOrderedPartitionCapability, isOrderedPartitionEntryModel } from './partition-contract.js';
+
+/** Owns bounded capability observation, never placement, loading or permission. */
+export function createPartitionDiscovery({ identity, catalog, policy, peers, createNetwork,
+  describe, onChange = () => {}, now = () => Date.now() }) {
+  const connections = new Map(), lifetime = new AbortController();
+  let refreshing = null, closed = false, closing = null, networkSettled = false;
+  const snapshot = () => [...connections.entries()].map(([transportId, peer]) => {
+    const expiresAt = peer.observedAt + policy.inputLimits.descriptorTtlMs;
+    return { transportId, participantId: peer.participantId, observedAt: peer.observedAt,
+      expiresAt, available: !closed && !!peer.description && now() < expiresAt,
+      reason: closed ? 'closed' : !peer.description ? peer.reason || 'unobserved'
+        : now() >= expiresAt ? 'expired' : 'observed', description: structuredClone(peer.description) };
+  });
+  const notify = () => onChange(snapshot());
+  const network = createNetwork({ label: 'reploid-partitions-control',
+    maxPeers: policy.maxPeers, timeoutMs: policy.connectTimeoutMs,
+    createEndpoint: ({ channel, remoteParticipantId }) => {
+      const endpoint = createPartitionDataChannel({ channel, localParticipantId: identity.peerId,
+        remoteParticipantId, limits: policy.controlChannel,
+        authorize: async ({ metadata, byteLength }) => metadata.operation === 'describe' && byteLength === 0,
+        serve: async () => structuredClone(describe()) });
+      const peer = { endpoint, participantId: remoteParticipantId, description: null, observedAt: 0, revision: 0,
+        close: () => endpoint.close() };
+      channel.addEventListener('close', () => {
+        for (const [id, value] of connections) if (value === peer) connections.delete(id);
+        notify();
+      }, { once: true });
+      return peer;
+    },
+    onPeer(transportId, peer) { if (!closed) connections.set(transportId, peer); }
+  });
+  return Object.freeze({
+    getSnapshot: snapshot,
+    getModels: () => snapshot().filter(peer => peer.available).flatMap(peer => peer.description.models
+      .filter(model => peer.description.schema !== 'reploid.partition-capability/v2'
+        || isOrderedPartitionEntryModel(model, peer))),
+    invalidateModel(transportId, model) {
+      const peer = connections.get(transportId);
+      if (!peer || closed) return;
+      peer.revision++;
+      if (peer.description) peer.description.models = peer.description.models.filter(candidate =>
+        candidate.id !== model.id || candidate.identity !== model.identity);
+      notify();
+    },
+    refresh() {
+      if (closed) return Promise.resolve(snapshot());
+      if (refreshing) return refreshing;
+      refreshing = (async () => {
+        for (const peer of peers().slice(0, policy.maxPeers)) {
+          if (closed) break;
+          if (!connections.has(peer.id) && peer.localTransportId < peer.id) {
+            try { await network.connect(peer.id); } catch { /* The next bounded refresh may retry. */ }
+          }
+        }
+        await Promise.allSettled([...connections.values()].map(async peer => {
+          const revision = peer.revision;
+          try {
+            const description = await peer.endpoint.request({ operation: 'describe' }, new Uint8Array(), { signal: lifetime.signal });
+            if (description?.schema === 'reploid.partition-capability/v2') {
+              validateOrderedPartitionCapability(description, peer.participantId, policy.maxStageOffersPerPeer);
+            } else assert(description.participantId === peer.participantId && Array.isArray(description.models)
+              && (description.eligibleIndexes === undefined || Array.isArray(description.eligibleIndexes)
+                && description.eligibleIndexes.length > 0 && description.eligibleIndexes.length <= 2
+                && description.eligibleIndexes.every(index => index === 0 || index === 1))
+              && description.models.length <= catalog.length && [null, 0, 1].includes(description.index)
+              && (!description.capacity || Number.isSafeInteger(description.capacity.availableSlots)
+                && description.capacity.availableSlots >= 0 && Number.isSafeInteger(description.capacity.active)
+                && description.capacity.active >= 0 && typeof description.capacity.closed === 'boolean')
+              && ['idle', 'waiting', 'loading', 'ready', 'stopping', 'failed'].includes(description.phase),
+            'Partition capability identity or inventory mismatch');
+            // A describe already in flight cannot restore a hint rejected by a
+            // newer authoritative entry check. The next observation may restore it.
+            if (!closed && revision === peer.revision) { peer.description = structuredClone(description); peer.observedAt = now(); peer.reason = null; }
+          } catch { if (revision === peer.revision) { peer.description = null; peer.reason = 'description-unavailable'; } }
+        }));
+        notify(); return snapshot();
+      })().finally(() => { refreshing = null; });
+      return refreshing;
+    },
+    close() {
+      if (closing) return closing;
+      closed = true; lifetime.abort(new Error('Partition discovery closed'));
+      closing = (async () => {
+        const results = await Promise.allSettled([Promise.resolve().then(async () => {
+          if (!networkSettled) { await network.close(); networkSettled = true; }
+        }), refreshing]);
+        connections.clear();
+        const failures = results.filter(result => result.status === 'rejected').map(result => result.reason);
+        if (failures.length) throw new AggregateError(failures, 'Partition discovery settlement failed');
+      })().catch(error => { closing = null; throw error; });
+      return closing;
+    }
+  });
+}

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

@@ -0,0 +1,183 @@
+import { assertPartition as assert, canonicalPartitionJson, samePartitionIdentity,
+  validatePartitionIdentity, canonicalRouteAttemptBinding } from './partition-contract.js';
+import { ORDERED_PUBLICATION_ATTEMPT_SCHEMA, validateOrderedPublicationContext } from './partition-ordered-publication.js';
+
+export const ENTRY_PUBLICATION_SCHEMA = 'reploid.partition-publication/v1';
+const same = (a, b) => canonicalPartitionJson(a) === canonicalPartitionJson(b);
+const epoch = value => typeof value === 'string' && /^[a-f0-9]{32}$/.test(value);
+const digest = value => typeof value === 'string' && /^sha256:[a-f0-9]{64}$/.test(value);
+const methods = ['head', 'admit', 'publish', 'publish-batch', 'cancel'];
+const orderedInput = request => request?.schema === 'reploid.partition-input/v3';
+const orderedKeys = ['meshId', 'requesterId', 'coordinatorId', 'modelId', 'modelIdentity', 'planId', 'threadId',
+  'attemptId', 'placementGeneration'];
+/** The owner interface a coordinator calls; the requester's scope answers it. */
+export function entryPublicationPort(call) {
+  assert(typeof call === 'function', 'Publication call port required');
+  return Object.freeze({ requiresCommitEvidence: true,
+    reconcile: () => call('head', {}), admitAttempt: body => call('admit', body),
+    publish: (value, { evidence } = {}) => call('publish', { publication: value, evidence }),
+    // Consecutive records committed by the requester in one transaction and projected once.
+    publishBatch: async (values, { evidence } = {}) => (await call('publish-batch', { publications: values, evidence }))?.receipts,
+    cancel: (attemptId, coordinatorEpoch) => call('cancel', { attemptId, coordinatorEpoch }) });
+}
+export function validateEntryPublicationContext(value, request) {
+  assert(value?.schema === 'reploid.partition-publication-context/v1' && epoch(value.publisherEpoch)
+    && epoch(value.coordinatorEpoch) && digest(value.routeId) && digest(value.generation?.generationId)
+    && digest(value.generation.executionIdentity) && value.generation.policy
+    && Number.isSafeInteger(value.generation.policy.maxGeneratedTokens) && value.generation.policy.maxGeneratedTokens >= 0
+    && Number.isSafeInteger(value.vocabSize) && value.vocabSize > 0
+    && Number.isSafeInteger(value.deadlineAt) && value.deadlineAt > 0
+    && Array.isArray(value.stages) && value.stages.length === 2
+    && value.stages.every((stage, i) => stage.participantId === [request.participantA, request.participantB][i]
+      && stage.partitionIndex === i && digest(stage.stageId) && epoch(stage.participantEpoch)
+      && epoch(stage.deviceEpoch) && typeof stage.residentId === 'string' && stage.residentId.length > 0
+      && digest(stage.executionId)), 'Invalid entry publication context');
+  return structuredClone(value);
+}
+/** A publication request travels on the already authenticated requester/A channel.
+ * It never conveys another conversation's history, a tensor or a raw text delta. */
+export function entryPublicationEnvelope(request, method, body) {
+  assert(methods.includes(method), 'Unknown publication method');
+  if (orderedInput(request)) {
+    canonicalRouteAttemptBinding({ schema: 'reploid.partition-attempt/v2', route: request.route, threadId: request.threadId,
+      attemptId: request.attemptId, requesterId: request.requesterId, placementGeneration: request.placementGeneration });
+    return { schema: ENTRY_PUBLICATION_SCHEMA, operation: 'publication', method,
+      ...Object.fromEntries(orderedKeys.map(key => [key, request[key]])), route: structuredClone(request.route),
+      publication: validateOrderedPublicationContext(request.publication), body: structuredClone(body) };
+  }
+  validatePartitionIdentity(request);
+  const { meshId, requesterId, participantA, participantB, modelId, modelIdentity, planId,
+    threadId, attemptId, placementGeneration, canonical } = request;
+  return { schema: ENTRY_PUBLICATION_SCHEMA, operation: 'publication', method, meshId, requesterId,
+    participantA, participantB, modelId, modelIdentity, planId, threadId, attemptId, placementGeneration,
+    canonical: structuredClone(canonical), body: structuredClone(body) };
+}
+export function matchingEntryPublication(message, request) {
+  if (orderedInput(request)) {
+    try {
+      return request.publication !== undefined && message?.schema === ENTRY_PUBLICATION_SCHEMA && message.operation === 'publication'
+        && methods.includes(message.method) && orderedKeys.every(key => message[key] === request[key])
+        && message.canonical === undefined && message.participantA === undefined && message.participantB === undefined
+        && same(message.route, request.route) && same(message.publication, request.publication);
+    } catch { return false; }
+  }
+  return request?.schema === 'reploid.partition-input/v2' && message.schema === ENTRY_PUBLICATION_SCHEMA
+    && message.operation === 'publication' && methods.includes(message.method)
+    && message.meshId === request.meshId && samePartitionIdentity(message, request)
+    && same(message.canonical, request.canonical);
+}
+/** This port belongs to the requester, not the input executor. The transaction
+ * owner validates cursors/signatures and fences uncertain storage outcomes. */
+export function createEntryPublicationScope({ request, owner, authorize, onPublished, maxControlBytes, maxOutputCharacters }) {
+  assert(owner?.requiresCommitEvidence === true && ['reconcile', 'admitAttempt', 'publish', 'cancel']
+    .every(name => typeof owner[name] === 'function') && typeof authorize === 'function'
+    && typeof onPublished === 'function', 'Requester durable publication and projection ports required');
+  assert(Number.isSafeInteger(maxControlBytes) && maxControlBytes > 0
+    && Number.isSafeInteger(maxOutputCharacters) && maxOutputCharacters > 0, 'Publication channel bounds required');
+  const copy = value => {
+    const json = canonicalPartitionJson(value);
+    assert(new TextEncoder().encode(json).byteLength <= maxControlBytes, 'Publication control budget exhausted');
+    return JSON.parse(json);
+  };
+  const selected = copy(request), ordered = orderedInput(selected);
+  const context = ordered ? validateOrderedPublicationContext(selected.publication) : validateEntryPublicationContext(selected.canonical, selected);
+  let closed = false, admitted = null, admittedPolicy = null, content = '', count = 0, terminal = false;
+  const projections = new Map(), pending = new Set();
+  let cancellation = null;
+  const permit = async method => {
+    assert(!closed && await authorize(method) === true && !closed, 'Publication delivery authority closed or revoked');
+  };
+  // An ordered coordinator chooses its epoch at admission; canonical routes advertise it.
+  const coordinatorEpoch = () => ordered ? admitted?.coordinatorEpoch : context.coordinatorEpoch;
+  const sequenceLimit = () => ordered ? admittedPolicy.maxTokens : Math.max(1, context.generation.policy.maxGeneratedTokens);
+  const identityMatches = identity => ordered
+    ? identity?.schema === ORDERED_PUBLICATION_ATTEMPT_SCHEMA && identity.attemptId === selected.attemptId
+      && identity.threadId === selected.threadId && identity.requesterId === selected.requesterId
+      && identity.placementGeneration === selected.placementGeneration && identity.publisherEpoch === context.publisherEpoch
+      && epoch(identity.coordinatorEpoch) && same(identity.route, selected.route)
+    : identity?.attemptId === selected.attemptId
+    && identity.requesterId === selected.requesterId && identity.publisherEpoch === context.publisherEpoch
+    && identity.coordinatorEpoch === context.coordinatorEpoch && identity.routeId === context.routeId
+    && identity.generationId === context.generation.generationId && identity.routeKind === 'two-stage-layer'
+    && same(identity.stages, context.stages);
+  const admissionMatches = value => identityMatches(value.identity) && (ordered
+    ? value.executionIdentity === value.identity.generationDigest && Number.isSafeInteger(value.vocabSize) && value.vocabSize > 0
+      && Number.isSafeInteger(value.generationPolicy?.maxTokens) && value.generationPolicy.maxTokens > 0
+    : same(value.generationPolicy, context.generation.policy)
+      && value.executionIdentity === context.generation.executionIdentity && value.vocabSize === context.vocabSize);
+  const call = async (method, body) => {
+      assert(methods.includes(method), 'Unknown publication method');
+      const value = copy(body); // Snapshot before any asynchronous authorization or storage.
+      await permit(method);
+      if (method === 'head') {
+        assert(same(value, {}), 'Unexpected publication head input');
+        const state = await owner.reconcile(); await permit(method);
+        return copy({ head: state.head, attempts: state.attempts.filter(item => item.identity.attemptId === selected.attemptId
+          && (ordered || item.identity.coordinatorEpoch === context.coordinatorEpoch)).map(item => ({ identity: item.identity })) });
+      }
+      if (method === 'admit') {
+        assert(admissionMatches(value) && value.deadlineAt === context.deadlineAt && (!admitted || same(admitted, value.identity)),
+          'Publication admission differs from approved context');
+        const result = await owner.admitAttempt(value); admitted = value.identity; admittedPolicy = value.generationPolicy;
+        await permit(method); return copy(result);
+      }
+      assert(admitted, 'Publication attempt has not been admitted');
+      if (method === 'cancel') {
+        assert(same(value, { attemptId: selected.attemptId, coordinatorEpoch: coordinatorEpoch() }),
+          'Cancellation differs from admitted attempt');
+        const result = await owner.cancel(value.attemptId, value.coordinatorEpoch);
+        await permit(method); return copy(result);
+      }
+      const batch = method === 'publish-batch';
+      const publications = batch ? value.publications : [value.publication], evidence = batch ? value.evidence : [value.evidence];
+      assert(Array.isArray(publications) && publications.length > 0 && Array.isArray(evidence) && evidence.length === publications.length
+        && publications.every((publication, index) => publication?.attemptId === selected.attemptId && publication.coordinatorEpoch === coordinatorEpoch()
+          && Number.isSafeInteger(publication.sequence) && publication.sequence >= 0
+          && publication.sequence < sequenceLimit() && Array.isArray(evidence[index])), 'Publication differs from admitted attempt');
+      const receipts = copy(batch ? await owner.publishBatch(publications, { evidence })
+        : [await owner.publish(publications[0], { evidence: evidence[0] })]);
+      assert(Array.isArray(receipts) && receipts.length === publications.length && receipts.every((receipt, index) =>
+        receipt.conversationId === selected.threadId && receipt.writerEpoch === context.publisherEpoch
+        && receipt.attemptId === selected.attemptId && receipt.coordinatorEpoch === coordinatorEpoch()
+        && receipt.sequence === publications[index].sequence && receipt.publicationDigest === publications[index].publicationDigest),
+      'Durable publication receipt identity mismatch');
+      await permit(method);
+      // Duplicate delivery reuses the same projection promise. A failed projection
+      // cannot be acknowledged or regenerated; the host reconciles saved history.
+      // A batch is projected once, from its last durable record.
+      const last = receipts.length - 1;
+      let projected = projections.get(receipts[last].publicationDigest);
+      if (!projected) {
+        const fresh = publications.filter(publication => publication.sequence >= count);
+        const text = fresh.map(publication => publication.delta?.text ?? '').join('');
+        assert(fresh.every(publication => typeof (publication.delta?.text ?? '') === 'string')
+          && content.length + text.length <= maxOutputCharacters, 'Published output exceeds entry budget');
+        assert(fresh.length > 0 && fresh[0].sequence === count, 'Published projection sequence mismatch');
+        const publication = publications[last];
+        projected = Promise.resolve().then(async () => {
+          await permit(method);
+          await onPublished(copy({ publication, receipt: receipts[last], evidence: evidence[last] }));
+          content += text; count += fresh.length;
+          terminal = publication.schema === 'doppler.admission-publication/v1' || publication.successor?.terminal === true;
+        });
+        projections.set(receipts[last].publicationDigest, projected);
+      }
+      await projected; await permit(method); return batch ? { receipts } : receipts[0];
+  };
+  return Object.freeze({
+    async close({ cancel = false } = {}) {
+      closed = true;
+      await Promise.allSettled([...pending]);
+      if (cancel && admitted) {
+        if (!cancellation) cancellation = Promise.resolve().then(() => owner.cancel(selected.attemptId, coordinatorEpoch()));
+        try { await cancellation; } catch (error) { cancellation = null; throw error; }
+      }
+    },
+    getProjection() { return { content, count, terminal }; },
+    call(method, body) {
+      const operation = call(method, body); pending.add(operation);
+      operation.then(() => pending.delete(operation), () => pending.delete(operation));
+      return operation;
+    },
+  });
+}