@entrorove/skill 0.1.23 → 0.1.25

package/local-swarm-priority.mjs

@@ -0,0 +1,237 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { canonical, sha256 } from './local-integrity.mjs';
+import { readSignedSwarmMaterial, readSwarmCloudAuthority, requireSwarmCloudMaterial } from './local-swarm-authority.mjs';
+import { canonicalSwarmPaths, SWARM_PRIORITIES, swarmPathsOverlap } from './local-swarm-state.mjs';
+import { readTaskHandoffFence } from './local-task-handoff-fence.mjs';
+import { revalidateSwarmCompletion } from './local-swarm-completion.mjs';
+
+const CONTROL_FIELDS = ['intentRevision', 'nextIntentSequence', 'intents', 'checkpointRequests'];
+const INTENT_FIELDS = ['intentId', 'sequence', 'status', 'priority', 'flowId', 'stepId', 'workerId', 'leaseId', 'paths',
+  'expiresAt', 'registeredAt', 'home', 'acceptedPlan', 'lease', 'delegationGrant', 'executionAuthority', 'executionAttemptNonce'];
+const REQUEST_FIELDS = ['requestId', 'intentId', 'targetGrantDigest', 'requestedAt', 'paths', 'reason'];
+const STATUSES = ['waiting', 'active', 'completed', 'expired', 'revoked'];
+function fail(message, code = 'ENTROROVE_SWARM_STATE_INVALID') { throw Object.assign(new Error(message), { code }); }
+function exact(value, fields) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)
+    || canonical(Object.keys(value).sort()) !== canonical([...fields].sort())) fail('durable write intent fields are invalid');
+}
+function hash(value) { return typeof value === 'string' && /^[0-9a-f]{64}$/.test(value); }
+function instant(value) { return typeof value === 'string' && Number.isFinite(Date.parse(value)); }
+function advance(index, changes) {
+  if (!Number.isSafeInteger(index.intentRevision + 1)) fail('durable intent revision is exhausted');
+  return { ...index, ...changes, intentRevision: index.intentRevision + 1 };
+}
+function controls(value, authority) {
+  if (!value || value.schemaVersion !== 'entrorove.swarm-ownership/1.0' || value.repositoryRoot !== authority.root
+    || value.repositoryDigest !== authority.repositoryDigest || !hash(value.markerDigest) || !Array.isArray(value.records)) {
+    fail('write intent index lost its initialized physical ownership binding');
+  }
+  const present = CONTROL_FIELDS.filter(field => Object.hasOwn(value, field));
+  if (present.length !== CONTROL_FIELDS.length || !Number.isSafeInteger(value.intentRevision) || value.intentRevision < 0
+    || !Number.isSafeInteger(value.nextIntentSequence) || value.nextIntentSequence < 0
+    || !Array.isArray(value.intents) || value.intents.length > 1024 || value.nextIntentSequence !== value.intents.length
+    || value.intentRevision < value.nextIntentSequence || !Array.isArray(value.checkpointRequests) || value.checkpointRequests.length > 1024) {
+    fail('durable write intent history, counter or checkpoint queue is missing or changed; reconcile before new admission');
+  }
+  return value;
+}
+function material(intent, authority) {
+  return { repositoryRoot: authority.root, home: intent.home, flowId: intent.flowId, stepId: intent.stepId,
+    workerId: intent.workerId, paths: intent.paths, acceptedPlan: intent.acceptedPlan, lease: intent.lease,
+    delegationGrant: intent.delegationGrant, executionAuthority: intent.executionAuthority,
+    executionAttemptNonce: intent.executionAttemptNonce };
+}
+async function storedAuthority(intent, authority) {
+  exact(intent, INTENT_FIELDS); requireSwarmCloudMaterial(intent);
+  const input = material(intent, authority), verified = readSignedSwarmMaterial(input, 'report');
+  const { grant, lease } = verified;
+  if (intent.intentId !== sha256(canonical(intent.delegationGrant)) || intent.flowId !== grant.flowId
+    || intent.stepId !== grant.stepId || intent.workerId !== grant.workerId || intent.leaseId !== lease.leaseId
+    || intent.priority !== grant.priority || !STATUSES.includes(intent.status) || !instant(intent.registeredAt)
+    || Date.parse(intent.registeredAt) > Date.now() || !instant(intent.expiresAt)
+    || canonical(canonicalSwarmPaths(intent.paths)) !== canonical(grant.paths)
+    || grant.localRepositoryDigest !== authority.repositoryDigest || typeof intent.home !== 'string' || !path.isAbsolute(intent.home)) {
+    fail('stored intent changed the actual signed worker, priority, path or repository');
+  }
+  const homeStat = await fs.lstat(intent.home);
+  if (!homeStat.isDirectory() || homeStat.isSymbolicLink() || await fs.realpath(intent.home) !== intent.home) fail('intent execution home is not its original actual directory');
+  const fence = await readTaskHandoffFence({ repositoryRoot: authority.root, home: intent.home, flowId: grant.flowId });
+  const attempt = fence.executionAttempts.find(value => value.authority.attemptNonce === intent.executionAttemptNonce);
+  if (!attempt || canonical(attempt.authority) !== canonical(intent.executionAuthority) || attempt.executionHome !== intent.home
+    || attempt.authority.schemaVersion !== 'entrorove.task-execution-epoch-authority/1.0' || attempt.authority.status !== 'active'
+    || attempt.authority.taskId !== grant.taskId || attempt.authority.leaseId !== lease.leaseId || attempt.authority.generation !== lease.generation
+    || ['flowId', 'ownerId', 'taskDigest', 'chainDigest', 'runnerKeyId', 'localRepositoryDigest'].some(field => attempt.authority[field] !== grant[field])) {
+    fail('stored intent lost its actual registered signed nonce, execution epoch or original business lease');
+  }
+  const expires = Math.min(Date.parse(grant.expiresAt), Date.parse(lease.expiresAt), Date.parse(attempt.authority.expiresAt));
+  if (!Number.isFinite(expires) || intent.expiresAt !== new Date(expires).toISOString()
+    || Date.parse(intent.registeredAt) < Math.max(Date.parse(grant.issuedAt), Date.parse(attempt.authority.issuedAt))
+    || Date.parse(intent.registeredAt) >= expires) fail('intent entry interval differs from its original signed grant and nonce');
+  return { ...verified, input, fence, attempt, authority: { ...verified, root: authority.root, home: intent.home,
+    repositoryDigest: authority.repositoryDigest, epoch: attempt.authority.epoch, paths: grant.paths, requestedPaths: grant.paths } };
+}
+async function actualCompletion(verified, proof) {
+  if (verified.attempt.status !== 'used') return null;
+  try {
+    return await revalidateSwarmCompletion(proof, verified.authority, verified.input);
+  } catch { return null; }
+}
+function reservationFor(index, intent) {
+  return index.records.find(value => value.grantDigest === intent.intentId);
+}
+async function currentStatus(index, intent, verified, proof) {
+  const { fence, attempt, grant } = verified;
+  const record = reservationFor(index, intent);
+  if (fence.status !== 'active' || fence.epoch !== attempt.authority.epoch || attempt.status === 'revoked'
+    || fence.revokedLeaseIds.includes(grant.leaseId)) return 'revoked';
+  if (record) {
+    if (record.flowId !== intent.flowId || record.workerId !== intent.workerId || record.leaseId !== intent.leaseId
+      || record.home !== intent.home || canonical(record.paths) !== canonical(intent.paths)
+      || canonical(record.delegationGrant) !== canonical(intent.delegationGrant) || canonical(record.acceptedPlan) !== canonical(intent.acceptedPlan)
+      || canonical(record.lease) !== canonical(intent.lease) || canonical(record.executionAuthority) !== canonical(intent.executionAuthority)) {
+      fail('active ownership differs from its original exact queued cloud materials');
+    }
+    return 'active';
+  }
+  if (intent.status === 'completed' || intent.status === 'active' || attempt.status === 'used') {
+    if (await actualCompletion(verified, proof)) return 'completed';
+    fail('an admitted or used intent lost its active reservation without a real completed process', 'ENTROROVE_SWARM_RECONCILE_REQUIRED');
+  }
+  return Date.parse(intent.expiresAt) <= Date.now() ? 'expired' : 'waiting';
+}
+function checkpointPaths(intent, record) {
+  return intent.paths.filter(target => record.paths.some(scope => swarmPathsOverlap(scope, target)));
+}
+function checkpointId(intentId, targetGrantDigest) { return sha256(`entrorove.swarm-checkpoint/1.0\0${intentId}\0${targetGrantDigest}`); }
+function validateRequests(index) {
+  const identities = new Set(), requests = [];
+  for (const request of index.checkpointRequests) {
+    exact(request, REQUEST_FIELDS);
+    const intent = index.intents.find(value => value.intentId === request.intentId);
+    if (!hash(request.requestId) || !hash(request.targetGrantDigest) || !intent || intent.priority !== 'urgent'
+      || request.reason !== 'urgent-overlap' || request.requestId !== checkpointId(intent.intentId, request.targetGrantDigest)
+      || identities.has(request.requestId) || !instant(request.requestedAt) || Date.parse(request.requestedAt) < Date.parse(intent.registeredAt)
+      || Date.parse(request.requestedAt) > Date.now() || canonical(canonicalSwarmPaths(request.paths)) !== canonical(request.paths)) {
+      fail('checkpoint request lacks its actual signed urgent waiting intent');
+    }
+    identities.add(request.requestId);
+    const target = index.records.find(value => value.grantDigest === request.targetGrantDigest);
+    if (!target || intent.status !== 'waiting') continue;
+    if (canonical(checkpointPaths(intent, target)) !== canonical(request.paths)) fail('checkpoint request changed the actual overlapping owner paths');
+    requests.push(request);
+  }
+  return requests;
+}
+
+// The native core owns the existing repository ownershipFile lock and publishes
+// this returned index atomically with actual reservations. No caller flag grants
+// authority, and an intent never revokes or clears an existing active record.
+export async function validateSwarmWriteIntents(value, authority, completionProofs = new Map()) {
+  if (!(completionProofs instanceof Map)) fail('completion proofs must be original internal opaque tokens');
+  const index = controls(value, authority), identities = new Set(), intents = [];
+  let changed = false;
+  for (let sequence = 0; sequence < index.intents.length; sequence++) {
+    const intent = index.intents[sequence];
+    if (intent?.sequence !== sequence || identities.has(intent?.intentId)) fail('arrival history changed its unique durable FIFO sequence');
+    const verified = await storedAuthority(intent, authority), status = await currentStatus(index, intent, verified, completionProofs.get(intent.intentId));
+    identities.add(intent.intentId); changed ||= status !== intent.status;
+    intents.push(status === intent.status ? intent : { ...intent, status });
+  }
+  const checkpointRequests = validateRequests({ ...index, intents });
+  changed ||= canonical(checkpointRequests) !== canonical(index.checkpointRequests);
+  return changed ? advance(index, { intents, checkpointRequests }) : { ...index, intents, checkpointRequests };
+}
+async function freshCaller(authority, input, purpose) {
+  const fresh = await readSwarmCloudAuthority(input, purpose);
+  if (fresh.root !== authority.root || fresh.home !== authority.home || fresh.repositoryDigest !== authority.repositoryDigest
+    || fresh.epoch !== authority.epoch || canonical(fresh.grant) !== canonical(authority.grant)
+    || canonical(fresh.plan) !== canonical(authority.plan) || canonical(fresh.lease) !== canonical(authority.lease)
+    || canonical(fresh.paths) !== canonical(authority.paths)) fail('caller changed its original validated authority while acquiring the ownership lock');
+  if (input.priority !== undefined && input.priority !== fresh.grant.priority) fail('caller priority cannot replace the original signed priority', 'ENTROROVE_SWARM_PRIORITY_INVALID');
+  return fresh;
+}
+export async function registerSwarmWriteIntent(value, authority, input, completionProofs = new Map()) {
+  const fresh = await freshCaller(authority, input, 'issue'), index = await validateSwarmWriteIntents(value, fresh, completionProofs);
+  const intentId = sha256(canonical(input.delegationGrant)), existing = index.intents.find(intent => intent.intentId === intentId);
+  if (existing) {
+    if (canonical(existing.executionAuthority) !== canonical(input.executionAuthority) || existing.executionAttemptNonce !== input.executionAttemptNonce
+      || existing.home !== fresh.home) fail('durable intent cannot replace its original execution nonce or home');
+    return { index, intent: existing };
+  }
+  if (index.intents.length >= 1024 || !Number.isSafeInteger(index.nextIntentSequence + 1)) fail('durable intent history requires explicit bounded reconciliation');
+  const expires = Math.min(Date.parse(fresh.grant.expiresAt), Date.parse(fresh.lease.expiresAt), Date.parse(input.executionAuthority.expiresAt));
+  const intent = { intentId, sequence: index.nextIntentSequence, status: 'waiting', priority: fresh.grant.priority,
+    flowId: fresh.plan.flowId, stepId: fresh.step.stepId, workerId: fresh.grant.workerId, leaseId: fresh.lease.leaseId,
+    paths: fresh.paths, expiresAt: new Date(expires).toISOString(), registeredAt: new Date().toISOString(), home: fresh.home,
+    acceptedPlan: input.acceptedPlan, lease: input.lease, delegationGrant: input.delegationGrant,
+    executionAuthority: input.executionAuthority, executionAttemptNonce: input.executionAttemptNonce };
+  const next = advance(index, { nextIntentSequence: index.nextIntentSequence + 1, intents: [...index.intents, intent] });
+  return { index: await validateSwarmWriteIntents(next, fresh, completionProofs), intent };
+}
+function earlier(left, right) {
+  const rank = SWARM_PRIORITIES.indexOf(left.priority) - SWARM_PRIORITIES.indexOf(right.priority);
+  return rank > 0 || (rank === 0 && left.sequence < right.sequence);
+}
+export async function claimSwarmWriteIntent(value, authority, input, completionProofs = new Map()) {
+  const fresh = await freshCaller(authority, input, 'issue'), index = await validateSwarmWriteIntents(value, fresh, completionProofs);
+  const intentId = sha256(canonical(input.delegationGrant)), intent = index.intents.find(value => value.intentId === intentId);
+  if (!intent || canonical(intent.executionAuthority) !== canonical(input.executionAuthority)
+    || intent.executionAttemptNonce !== input.executionAttemptNonce || intent.home !== fresh.home) {
+    fail('the exact original cloud grant and registered nonce must enter the durable queue first', 'ENTROROVE_SWARM_CLOUD_AUTHORITY_REQUIRED');
+  }
+  if (intent.status !== 'waiting') fail('only a live pending original intent may acquire new paths', 'ENTROROVE_SWARM_AUTHORITY_EXPIRED');
+  const active = index.records.filter(record => checkpointPaths(intent, record).length);
+  const ahead = index.intents.filter(other => other.status === 'waiting' && other.intentId !== intentId && earlier(other, intent)
+    && other.paths.some(scope => intent.paths.some(target => swarmPathsOverlap(scope, target))));
+  const blockedPaths = intent.paths.filter(target => active.some(record => record.paths.some(scope => swarmPathsOverlap(scope, target)))
+    || ahead.some(other => other.paths.some(scope => swarmPathsOverlap(scope, target))));
+  const checkpointRequests = [...index.checkpointRequests];
+  if (intent.priority === 'urgent') for (const target of active) {
+    const requestId = checkpointId(intentId, target.grantDigest);
+    if (!checkpointRequests.some(value => value.requestId === requestId)) checkpointRequests.push({ requestId, intentId,
+      targetGrantDigest: target.grantDigest, requestedAt: new Date().toISOString(), paths: checkpointPaths(intent, target), reason: 'urgent-overlap' });
+  }
+  if (checkpointRequests.length > 1024) fail('durable checkpoint requests exceed the bounded ownership queue');
+  const updated = checkpointRequests.length === index.checkpointRequests.length ? index : advance(index, { checkpointRequests });
+  return { index: updated, intentId, readyPaths: intent.paths.filter(target => !blockedPaths.includes(target)), blockedPaths,
+    safeCheckpointRequested: intent.priority === 'urgent' && active.length > 0, mayAcquire: blockedPaths.length === 0,
+    blockedBy: [...active.map(value => ({ kind: 'active', grantDigest: value.grantDigest, reconcileRequired: value.reconcileRequired === true })),
+      ...ahead.map(value => ({ kind: 'priority', intentId: value.intentId, priority: value.priority, sequence: value.sequence }))] };
+}
+export async function readSwarmWriteIntentHistory(value, authority) {
+  const index = controls(value, authority), verified = new Map();
+  for (let sequence = 0; sequence < index.intents.length; sequence++) {
+    const intent = index.intents[sequence];
+    if (intent?.sequence !== sequence || verified.has(intent?.intentId)) fail('readonly checkpoint history lost its durable FIFO identities');
+    verified.set(intent.intentId, await storedAuthority(intent, authority));
+  }
+  return { index, verified, requests: validateRequests(index) };
+}
+export async function readSwarmCheckpointRequests(value, authority, input) {
+  const fresh = await freshCaller(authority, input, 'verify');
+  const { index, verified, requests: checkedRequests } = await readSwarmWriteIntentHistory(value, fresh);
+  const requests = checkedRequests.filter(request => {
+    const intent = index.intents.find(value => value.intentId === request.intentId), original = verified.get(request.intentId);
+    return original.fence.status === 'active' && original.fence.epoch === original.attempt.authority.epoch
+      && original.attempt.status === 'ready' && !original.fence.revokedLeaseIds.includes(intent.leaseId)
+      && Date.parse(intent.expiresAt) > Date.now();
+  });
+  const targetGrantDigest = sha256(canonical(input.delegationGrant));
+  return requests.filter(value => value.targetGrantDigest === targetGrantDigest)
+    .map(value => ({ requestId: value.requestId, requestedAt: value.requestedAt, paths: value.paths,
+      reason: value.reason, safeCheckpointRequested: true }));
+}
+export async function closeSwarmWriteIntent(value, authority, input, completionProof, completionProofs = new Map()) {
+  const fresh = await freshCaller(authority, input, 'report'), intentId = sha256(canonical(input.delegationGrant));
+  if (!(completionProofs instanceof Map)) fail('completion proofs must be original internal opaque tokens');
+  const proofs = new Map(completionProofs); proofs.set(intentId, completionProof);
+  const index = await validateSwarmWriteIntents(value, fresh, proofs), intent = index.intents.find(value => value.intentId === intentId);
+  if (!intent || canonical(intent.executionAuthority) !== canonical(input.executionAuthority) || intent.executionAttemptNonce !== input.executionAttemptNonce) {
+    fail('completion cannot close another original signed queued intent');
+  }
+  if (!await actualCompletion(await storedAuthority(intent, fresh), completionProof)) fail('completion has no actual signed finished business process', 'ENTROROVE_SWARM_EXECUTION_UNKNOWN');
+  if (intent.status === 'completed') return index;
+  return advance(index, { intents: index.intents.map(value => value.intentId === intentId ? { ...value, status: 'completed' } : value),
+    checkpointRequests: index.checkpointRequests.filter(value => value.intentId !== intentId && value.targetGrantDigest !== intentId) });
+}

package/local-swarm-state.mjs

@@ -0,0 +1,102 @@
+import path from 'node:path';
+import { canonical } from './local-integrity.mjs';
+
+export const SWARM_PRIORITIES = Object.freeze(['background', 'normal', 'high', 'urgent']);
+const ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,199}$/;
+const STATUSES = ['active', 'reported', 'failed', 'blocked', 'revoked'];
+function fail(code, message) { throw Object.assign(new Error(message), { code }); }
+function identifier(value) { return typeof value === 'string' && ID.test(value); }
+export function canonicalSwarmPaths(values) {
+  if (!Array.isArray(values) || !values.length || values.length > 512) fail('ENTROROVE_SWARM_PATH_INVALID', 'swarm paths must be nonempty and bounded');
+  for (const value of values) {
+    if (typeof value !== 'string' || !value || value.length > 500 || value !== value.normalize('NFC') || path.isAbsolute(value)
+      || /^[A-Za-z]:/.test(value) || /[\\\u0000-\u001f\u007f*?\[\]{}]/.test(value)
+      || value.split('/').some(part => !part || part === '.' || part === '..')) fail('ENTROROVE_SWARM_PATH_INVALID', 'swarm path is unsafe');
+  }
+  if (new Set(values).size !== values.length) fail('ENTROROVE_SWARM_PATH_INVALID', 'swarm paths must be unique');
+  return [...values].sort();
+}
+export function swarmPathsOverlap(left, right) {
+  return left === right || left.startsWith(`${right}/`) || right.startsWith(`${left}/`);
+}
+function validWorker(worker, flowId) {
+  if (!worker || !identifier(worker.workerId) || !identifier(worker.leaseId) || worker.flowId !== flowId
+    || !Number.isSafeInteger(worker.handoffEpoch) || worker.handoffEpoch < 0 || !STATUSES.includes(worker.status)
+    || !SWARM_PRIORITIES.includes(worker.priority)) return false;
+  const created = Date.parse(worker.createdAt), expires = Date.parse(worker.expiresAt);
+  if (typeof worker.createdAt !== 'string' || typeof worker.expiresAt !== 'string'
+    || !Number.isFinite(created) || !Number.isFinite(expires) || expires <= created) return false;
+  try { return canonical(canonicalSwarmPaths(worker.paths)) === canonical(worker.paths); } catch { return false; }
+}
+export function validateSwarmState(value, expected) {
+  if (!value || value.schemaVersion !== 'entrorove.coordination/1.0' || !identifier(value.flowId)
+    || !expected || value.flowId !== expected.flowId || value.repositoryDigest !== expected.repositoryDigest
+    || !/^[0-9a-f]{32}$/.test(value.repositoryDigest ?? '') || !Array.isArray(value.workers)
+    || !Array.isArray(value.leases) || !Array.isArray(value.events) || value.workers.length > 50
+    || !Number.isSafeInteger(value.maxWorkers) || value.maxWorkers < 0 || value.maxWorkers > 50
+    || (value.priority !== undefined && !SWARM_PRIORITIES.includes(value.priority))) {
+    fail('ENTROROVE_SWARM_STATE_INVALID', 'coordination state lost its actual repository/flow binding');
+  }
+  const workers = new Set(), leases = new Set();
+  for (const worker of value.workers) {
+    if (!validWorker(worker, value.flowId) || workers.has(worker.workerId) || leases.has(worker.leaseId)) {
+      fail('ENTROROVE_SWARM_STATE_INVALID', 'coordination worker identities, paths or lifetime are invalid');
+    }
+    workers.add(worker.workerId); leases.add(worker.leaseId);
+  }
+  if (value.leases.length !== value.workers.length || value.leases.some((lease, index) => canonical(lease) !== canonical(value.workers[index]))) {
+    fail('ENTROROVE_SWARM_STATE_INVALID', 'coordination lease table drifted from its exact worker records');
+  }
+  return value;
+}
+function checked(state) { return validateSwarmState(state, { flowId: state?.flowId, repositoryDigest: state?.repositoryDigest }); }
+export function appendSwarmWorker(state, worker) {
+  checked(state);
+  if (state.workers.some(item => item.workerId === worker?.workerId)) fail('ENTROROVE_SWARM_WORKER_DUPLICATE', 'workerId is already bound and cannot be reused');
+  if (state.leases.some(item => item.leaseId === worker?.leaseId)) fail('ENTROROVE_SWARM_LEASE_INVALID', 'leaseId is already bound');
+  if (!validWorker(worker, state.flowId) || worker.status !== 'active') fail('ENTROROVE_SWARM_STATE_INVALID', 'new worker record is invalid');
+  const active = state.workers.filter(item => item.status === 'active');
+  if (active.length >= state.maxWorkers) fail('ENTROROVE_SWARM_WORKER_LIMIT', 'the registered worker limit is exhausted');
+  if (active.some(item => item.paths.some(scope => worker.paths.some(target => swarmPathsOverlap(scope, target))))) {
+    fail('ENTROROVE_SWARM_PATH_CONFLICT', 'an active worker already owns an overlapping path');
+  }
+  return { ...state, workers: [...state.workers, { ...worker }], leases: [...state.leases, { ...worker }] };
+}
+export function reportSwarmWorker(state, input, actualCompletionConfirmed = false) {
+  checked(state);
+  const worker = state.workers.find(item => item.workerId === input.workerId && item.leaseId === input.leaseId && item.status === 'active');
+  if (!worker || (!actualCompletionConfirmed && Date.parse(worker.expiresAt) <= Date.now())) fail('ENTROROVE_SWARM_LEASE_INVALID', 'the exact active worker lease is missing or expired');
+  const outcome = input.outcome ?? 'completed';
+  if (!['completed', 'failed', 'blocked'].includes(outcome)) fail('ENTROROVE_SWARM_REPORT_INVALID', 'worker report outcome is invalid');
+  const status = outcome === 'completed' ? 'reported' : outcome;
+  const updated = { ...worker, status, outcome, reportedAt: new Date().toISOString() };
+  const replace = item => item.workerId === worker.workerId && item.leaseId === worker.leaseId ? updated : item;
+  return { state: { ...state, workers: state.workers.map(replace), leases: state.leases.map(replace) },
+    result: { status, trafficLight: status === 'reported' ? 'yellow' : 'red', workerId: worker.workerId, leaseId: worker.leaseId } };
+}
+
+// This is a pure queue decision, never a file-lock grant. The production caller
+// must establish occupiedPaths from actual signed locks and recheck on acquire.
+export function selectSwarmWriteIntent(intents, overlapPaths, occupiedPaths = []) {
+  const paths = canonicalSwarmPaths(overlapPaths);
+  const occupied = occupiedPaths.length ? canonicalSwarmPaths(occupiedPaths) : [];
+  if (!Array.isArray(intents) || intents.length > 1024) fail('ENTROROVE_SWARM_STATE_INVALID', 'write-intent queue is invalid');
+  const ids = new Set(), sequences = new Set();
+  for (const intent of intents) {
+    if (!SWARM_PRIORITIES.includes(intent?.priority)) fail('ENTROROVE_SWARM_PRIORITY_INVALID', 'priority must be background, normal, high or urgent');
+    if (!identifier(intent.intentId) || ids.has(intent.intentId) || !Number.isSafeInteger(intent.sequence) || intent.sequence < 0
+      || sequences.has(intent.sequence) || !['waiting', 'ready', 'completed', 'expired'].includes(intent.status)) {
+      fail('ENTROROVE_SWARM_STATE_INVALID', 'write-intent identity or durable queue order is invalid');
+    }
+    canonicalSwarmPaths(intent.paths); ids.add(intent.intentId); sequences.add(intent.sequence);
+  }
+  const candidates = intents.filter(intent => ['waiting', 'ready'].includes(intent.status)
+    && intent.paths.some(target => paths.some(scope => swarmPathsOverlap(target, scope))));
+  candidates.sort((left, right) => SWARM_PRIORITIES.indexOf(right.priority) - SWARM_PRIORITIES.indexOf(left.priority) || left.sequence - right.sequence);
+  const selected = candidates[0];
+  if (!selected) return { intentId: null, readyPaths: [], blockedPaths: [], safeCheckpointRequested: false };
+  const selectedPaths = canonicalSwarmPaths(selected.paths.filter(target => paths.some(scope => swarmPathsOverlap(target, scope))));
+  const blockedPaths = selectedPaths.filter(target => occupied.some(scope => swarmPathsOverlap(target, scope)));
+  return { intentId: selected.intentId, readyPaths: selectedPaths.filter(target => !blockedPaths.includes(target)), blockedPaths,
+    safeCheckpointRequested: selected.priority === 'urgent' && blockedPaths.length > 0, freshAimlockSnapshotRequired: true };
+}

package/local-swarm-storage.mjs

@@ -0,0 +1,135 @@
+import { randomUUID } from 'node:crypto';
+import { constants, promises as fs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { canonical, sha256 } from './local-integrity.mjs';
+import { readSignedSwarmMaterial, verifyStoredSwarmGrant } from './local-swarm-authority.mjs';
+import { readTaskHandoffFence } from './local-task-handoff-fence.mjs';
+import { revalidateSwarmCompletion, swarmOwnershipCompletionInput } from './local-swarm-completion.mjs';
+
+function fail(message) { throw Object.assign(new Error(message), { code: 'ENTROROVE_SWARM_STATE_INVALID' }); }
+async function hierarchy(home, parts, mode) {
+  if (typeof home !== 'string' || !path.isAbsolute(home)) fail('coordination home must be absolute');
+  const stat = await fs.lstat(home), actual = await fs.realpath(home);
+  if (!stat.isDirectory() || stat.isSymbolicLink() || actual !== path.resolve(home)
+    || (typeof process.getuid === 'function' && stat.uid !== process.getuid())) fail('coordination home must be actual and owned');
+  let directory = actual;
+  for (const part of parts) {
+    directory = path.join(directory, part);
+    if (mode === 'write') { try { await fs.mkdir(directory, { mode: 0o700 }); } catch (error) { if (error.code !== 'EEXIST') throw error; } }
+    const value = await fs.lstat(directory);
+    if (!value.isDirectory() || value.isSymbolicLink() || (process.platform !== 'win32' && (value.mode & 0o077))
+      || (typeof process.getuid === 'function' && value.uid !== process.getuid())) fail('coordination state hierarchy must be private, real and owned');
+  }
+  return directory;
+}
+export async function swarmRepositoryStorage(authority, mode = 'write') {
+  if (!['read', 'write'].includes(mode)) fail('coordination storage mode is invalid');
+  const sharedHome = process.env.ENTROROVE_SWARM_COORDINATION_HOME ?? os.homedir();
+  const shared = await hierarchy(sharedHome, ['.entrorove', 'coordination', authority.repositoryDigest], mode);
+  return { ownershipFile: path.join(shared, 'ownership.json'), markerFile: path.join(shared, 'ownership.initialized.json') };
+}
+export async function swarmFlowStorage(authority, mode = 'write') {
+  if (!['read', 'write'].includes(mode)) fail('coordination storage mode is invalid');
+  const local = await hierarchy(authority.home, ['.entrorove', 'coordination', authority.repositoryDigest, authority.plan.flowId], mode);
+  return { stateFile: path.join(local, 'state.json') };
+}
+export async function swarmStorage(authority, mode = 'write') {
+  return { ...await swarmRepositoryStorage(authority, mode), ...await swarmFlowStorage(authority, mode) };
+}
+export async function readSwarmJson(file, fallback) {
+  let before;
+  try { before = await fs.lstat(file); } catch (error) { if (error.code === 'ENOENT') return fallback; throw error; }
+  if (!before.isFile() || before.isSymbolicLink() || before.nlink !== 1 || before.size > 8 * 1024 * 1024
+    || (process.platform !== 'win32' && (before.mode & 0o077))
+    || (typeof process.getuid === 'function' && before.uid !== process.getuid())) fail('coordination state file must be bounded, private, real and owned');
+  const handle = await fs.open(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+  try {
+    const opened = await handle.stat();
+    if (opened.dev !== before.dev || opened.ino !== before.ino) fail('coordination state changed before open');
+    const bytes = await handle.readFile(), after = await handle.stat();
+    if (after.size !== opened.size || after.mtimeMs !== opened.mtimeMs || bytes.length > 8 * 1024 * 1024) fail('coordination state changed while reading');
+    return JSON.parse(bytes.toString('utf8'));
+  } finally { await handle.close(); }
+}
+export async function writeSwarmJson(file, value) {
+  const temporary = `${file}.${randomUUID()}.tmp`, handle = await fs.open(temporary, 'wx', 0o600);
+  try { await handle.writeFile(`${canonical(value)}\n`); await handle.sync(); } finally { await handle.close(); }
+  try { await fs.rename(temporary, file); } finally { await fs.rm(temporary, { force: true }); }
+  const directory = await fs.open(path.dirname(file), 'r'); try { await directory.sync(); } finally { await directory.close(); }
+}
+export function newSwarmOwnership(authority) {
+  return { schemaVersion: 'entrorove.swarm-ownership/1.0', repositoryDigest: authority.repositoryDigest,
+    repositoryRoot: authority.root, records: [], intentRevision: 0, nextIntentSequence: 0, intents: [], checkpointRequests: [] };
+}
+export async function readSwarmOwnership(storage, authority, mode = 'write') {
+  if (!['read', 'write'].includes(mode)) fail('coordination ownership mode is invalid');
+  const marker = await readSwarmJson(storage.markerFile, null), value = await readSwarmJson(storage.ownershipFile, null);
+  if (!marker && !value) {
+    if (mode === 'read') fail('the original repository ownership history has not been initialized');
+    const initialized = { schemaVersion: 'entrorove.swarm-ownership-initialization/1.0', initializationId: randomUUID(),
+      repositoryRoot: authority.root, repositoryDigest: authority.repositoryDigest, initializedAt: new Date().toISOString() };
+    const index = { ...newSwarmOwnership(authority), markerDigest: sha256(canonical(initialized)) };
+    // An interrupted first publication leaves a marker without an index and
+    // requires explicit recovery; it can never silently recreate an empty map.
+    await writeSwarmJson(storage.markerFile, initialized); await writeSwarmJson(storage.ownershipFile, index);
+    return index;
+  }
+  if (!marker || !value || marker.schemaVersion !== 'entrorove.swarm-ownership-initialization/1.0'
+    || marker.repositoryRoot !== authority.root || marker.repositoryDigest !== authority.repositoryDigest
+    || !/^[0-9a-f-]{36}$/.test(marker.initializationId ?? '') || !Number.isFinite(Date.parse(marker.initializedAt))
+    || value.markerDigest !== sha256(canonical(marker))) fail('initialized repository ownership history is missing or changed; reconcile before new grants');
+  return value;
+}
+export async function validateSwarmOwnership(value, authority, completionProofs = new Map()) {
+  if (!value || value.schemaVersion !== 'entrorove.swarm-ownership/1.0' || value.repositoryDigest !== authority.repositoryDigest
+    || value.repositoryRoot !== authority.root || !Array.isArray(value.records) || value.records.length > 1024) fail('repository ownership index lost its physical repository binding');
+  const identities = new Set(), records = [];
+  for (const record of value.records) {
+    const grant = verifyStoredSwarmGrant(record?.delegationGrant, true), digest = sha256(canonical(record.delegationGrant));
+    const identity = `${grant.flowId}\0${grant.workerId}\0${grant.leaseId}`;
+    if (record.grantDigest !== digest || record.flowId !== grant.flowId || record.workerId !== grant.workerId
+      || record.leaseId !== grant.leaseId || record.expiresAt !== grant.expiresAt || canonical(record.paths) !== canonical(grant.paths)
+      || grant.localRepositoryDigest !== authority.repositoryDigest || identities.has(identity)
+      || typeof record.home !== 'string' || !path.isAbsolute(record.home)) fail('ownership record changed its actual signed cloud grant');
+    identities.add(identity);
+    const material = readSignedSwarmMaterial({ flowId: grant.flowId, stepId: grant.stepId, workerId: grant.workerId,
+      acceptedPlan: record.acceptedPlan, lease: record.lease, delegationGrant: record.delegationGrant }, 'report');
+    const fence = await readTaskHandoffFence({ repositoryRoot: authority.root, home: record.home, flowId: grant.flowId });
+    const attempt = fence.executionAttempts.find(item => canonical(item.authority) === canonical(record.executionAuthority));
+    if (!attempt || attempt.executionHome !== record.home || attempt.authority.taskId !== grant.taskId
+      || attempt.authority.leaseId !== grant.leaseId || attempt.authority.generation !== grant.generation
+      || attempt.authority.flowId !== grant.flowId || attempt.authority.runnerKeyId !== grant.runnerKeyId) fail('ownership record lost its original actual registered execution authority');
+    if (fence.status !== 'active' || fence.epoch !== attempt.authority.epoch || attempt.status === 'revoked'
+      || fence.revokedLeaseIds.includes(grant.leaseId)) continue;
+    let retained = record;
+    if (Date.parse(grant.expiresAt) <= Date.now()) {
+      const active = fence.activities.some(value => value.leaseId === grant.leaseId);
+      if (!active && !(attempt.status === 'ready' && Date.parse(attempt.authority.expiresAt) > Date.now())) {
+        try {
+          const completed = await revalidateSwarmCompletion(completionProofs.get(record.grantDigest),
+            { ...material, root: authority.root, home: record.home, repositoryDigest: authority.repositoryDigest, epoch: fence.epoch },
+            swarmOwnershipCompletionInput(record, authority.root));
+          const started = Date.parse(completed?.process?.startedAt), finished = Date.parse(completed?.process?.finishedAt);
+          if (completed && ['reported', 'failed'].includes(completed.status) && completed.receipt
+            && Number.isInteger(completed.process?.exitCode) && Number.isFinite(started) && Number.isFinite(finished)
+            && started >= Date.parse(record.lease.issuedAt) && started >= Date.parse(grant.issuedAt)
+            && started < Date.parse(grant.expiresAt) && finished >= started && finished <= Date.parse(record.lease.expiresAt)) continue;
+          retained = { ...record, reconcileRequired: true };
+        } catch {
+          // Unknown/unfinished actual outcome retains its original signed path
+          // reservation. TTL never preempts a process or clears unknown work.
+          retained = { ...record, reconcileRequired: true };
+        }
+      }
+    }
+    records.push(retained);
+  }
+  return { ...value, records };
+}
+export function swarmOwnershipRecord(authority, input) {
+  return { grantDigest: sha256(canonical(input.delegationGrant)), delegationGrant: input.delegationGrant,
+    acceptedPlan: input.acceptedPlan, lease: input.lease, executionAuthority: input.executionAuthority,
+    home: authority.home, flowId: authority.plan.flowId,
+    workerId: authority.grant.workerId, leaseId: authority.lease.leaseId, paths: authority.paths, expiresAt: authority.grant.expiresAt };
+}