@entrorove/skill 0.1.22 → 0.1.24

package/local-task-handoff-write-receipts.mjs

@@ -0,0 +1,99 @@
+import { randomUUID, sign } from 'node:crypto';
+import { canonical, sha256 } from './local-integrity.mjs';
+import { scopeRead, scopeTarget } from './local-scope-files.mjs';
+import { loadTaskHandoffSigner } from './local-task-handoff-observation.mjs';
+import { receiverClaim } from './local-task-handoff-overlay-wire.mjs';
+import { checkHandoffWriteConstraints } from './local-task-handoff-write-constraints.mjs';
+import { verifyHandoffWriteArchive, verifyTaskHandoffWriteArchives } from './local-task-handoff-write-archive.mjs';
+import { handoffWriteFail as fail, writeReceiptIdentity, verifyWriteReceipt, verifyWriteNativeResult, assertWriteReceiptFields } from './local-task-handoff-write-wire.mjs';
+
+function sourceReadContext(ctx) { return Object.freeze({ home: ctx.home, repositoryRoot: ctx.root, flowId: ctx.flowId }); }
+async function fileObservation(ctx, relative) {
+  const actual = await scopeTarget(ctx.root, relative, true);
+  return actual.exists ? { exists: true, sha256: (await scopeRead(ctx.root, relative, sourceReadContext(ctx))).sha256 }
+    : { exists: false, sha256: sha256('') };
+}
+async function verifyActualScope(ctx, expected) {
+  const observed = new Map();
+  for (const [relative, baseline] of expected) {
+    const actual = await fileObservation(ctx, relative);
+    if (canonical(actual) !== canonical(baseline)) fail('actual scoped file changed outside the complete trusted write history');
+    observed.set(relative, actual);
+  }
+  return observed;
+}
+function receiptCore(archive, ctx, pending, outcome, after, result, key) {
+  const now = Date.now(), architecture = result?.architectureCheckpoint ?? null;
+  return { schemaVersion: 'entrorove.task-handoff-write-checkpoint/1.0', receiptId: randomUUID(),
+    ...writeReceiptIdentity(archive.claim, ctx), sequence: pending.sequence, previousReceiptDigest: pending.previousReceiptDigest,
+    blockId: pending.blockId, path: pending.path, beforeSha256: pending.beforeSha256, proposedAfterSha256: pending.proposedAfterSha256,
+    actualAfterSha256: after.sha256, beforeExists: pending.beforeExists, actualAfterExists: after.exists,
+    evaluationKind: architecture ? 'native-architecture' : outcome === 'blocked' ? 'scope-budget' : 'scope-only',
+    writeOutcome: outcome, checkpoint: architecture?.checkpoint ?? null, ledgerEntry: architecture?.ledgerEntry ?? null,
+    observedAt: pending.observedAt, keyId: key.config.keyId, nonce: pending.nonce, issuedAt: new Date(now).toISOString(),
+    expiresAt: new Date(now + key.config.receiptTtlMs).toISOString() };
+}
+async function saveCompleted(state, ctx, persist, archive, receipt) {
+  verifyWriteReceipt(receipt, archive.claim, ctx);
+  const updated = { ...archive, pending: null, receipts: [...archive.receipts, receipt],
+    interrupted: receipt.checkpoint?.drift.trend === 'red' };
+  await verifyTaskHandoffWriteArchives({ ...state, writeArchive: updated }, ctx);
+  await persist({ ...state, writeArchive: updated });
+}
+export async function runHandoffTrustedWrite({ input, context: ctx, state, persist, manifest, snapshotDirectory, performActualWrite }) {
+  if (!state?.writeArchive || state.writeArchive.pending || state.writeArchive.interrupted) fail('unknown pending or interrupted write prevents another physical write');
+  const archive = state.writeArchive, verified = await verifyHandoffWriteArchive(archive, ctx);
+  if (canonical(manifest) !== canonical(archive.manifest)) fail('physical write changed its accepted original snapshot');
+  const { pass } = receiverClaim(archive.claim, ctx), expected = verified.files.get(input.targetPath);
+  if (!expected) fail('physical write is outside its original exact snapshot paths');
+  const actual = (await verifyActualScope(ctx, verified.files)).get(input.targetPath);
+  const key = await loadTaskHandoffSigner(ctx, process.env.ENTROROVE_TASK_HANDOFF_WRITE_SIGNER_CONFIG, pass.runnerKeyId);
+  const content = typeof input.content === 'string' ? input.content : JSON.stringify(input.content);
+  if (typeof content !== 'string') fail('actual proposed content must be text or JSON');
+  const last = archive.receipts.at(-1), nonce = randomUUID();
+  const pending = { blockId: `${pass.passId}:${nonce}`, path: input.targetPath, beforeSha256: actual.sha256,
+    beforeExists: actual.exists, proposedAfterSha256: sha256(content), observedAt: new Date().toISOString(), nonce,
+    sequence: archive.receipts.length + 1, previousReceiptDigest: last ? sha256(canonical(last)) : null };
+  // Persist before the native check or physical rename; a crash retains an explicit unknown outcome.
+  await persist({ ...state, writeArchive: { ...archive, pending } });
+  let result, rejected;
+  try {
+    result = await checkHandoffWriteConstraints({ pass, manifest, root: ctx.root, snapshotDirectory,
+      targetPath: input.targetPath, content: input.content, blockId: pending.blockId, beforeSha256: actual.sha256, readContext: sourceReadContext(ctx),
+      history: pass.architectureAuthority ? [...pass.architectureAuthority.ledger.slice(pass.architectureAuthority.driftEpochStart), ...verified.entries] : [] });
+  } catch (error) {
+    if (error.code !== 'ENTROROVE_HANDOFF_SCOPE_BUDGET'
+      && !(error.code === 'ENTROROVE_HANDOFF_WRITE_CONSTRAINT' && /cumulative changed lines.*inherited scope budget/i.test(error.message))) throw error;
+    rejected = error;
+  }
+  const native = result?.architectureCheckpoint;
+  if (native && (!native.checkpoint.writeAllowed || native.checkpoint.status !== 'passed' || native.checkpoint.rollbackRequired)) {
+    rejected = Object.assign(new Error(`Original locked architecture or AST rules blocked the physical write: ${JSON.stringify(native.checkpoint.findings)}`),
+      { code: 'ENTROROVE_HANDOFF_WRITE_CONSTRAINT' });
+  }
+  const projected = rejected ? actual : { exists: true, sha256: pending.proposedAfterSha256 };
+  const planned = receiptCore(archive, ctx, pending, rejected ? 'blocked' : 'retained', projected, result, key);
+  assertWriteReceiptFields({ ...planned, signature: 'A'.repeat(86) });
+  await verifyWriteNativeResult(planned, pass.architectureAuthority, verified.entries);
+  const bounded = { ...archive, receipts: [...archive.receipts, { ...planned, signature: 'A'.repeat(86) }] };
+  if (Buffer.byteLength(canonical(bounded.receipts)) > 768_000
+    || Buffer.byteLength(canonical([bounded, state.writeArchiveHistory])) > 8 * 1024 * 1024) fail('write receipt archive exceeds its explicit limit before physical rename');
+  receiverClaim(archive.claim, ctx); // Recheck the live signed grant immediately before any physical rename.
+  await verifyActualScope(ctx, verified.files);
+  let output;
+  if (!rejected) {
+    const original = manifest.files.find(file => file.path === input.targetPath);
+    output = await performActualWrite({ input, baseline: { ...original, exists: actual.exists,
+      sha256: actual.exists ? actual.sha256 : sha256('entrorove.missing-file/1.0') } });
+    if (output?.written !== true) fail('physical write did not return its actual retained outcome; reconcile the pending record');
+  }
+  const after = await fileObservation(ctx, input.targetPath);
+  if (rejected ? canonical(after) !== canonical(actual) : !after.exists || after.sha256 !== pending.proposedAfterSha256) fail('actual physical outcome is unknown; pending record is retained');
+  const finalScope = new Map(verified.files); finalScope.set(input.targetPath, projected);
+  await verifyActualScope(ctx, finalScope);
+  const core = receiptCore(archive, ctx, pending, rejected ? 'blocked' : 'retained', after, result, key);
+  const receipt = { ...core, signature: sign(null, Buffer.from(canonical(core)), key.privateKey).toString('base64url') };
+  await saveCompleted(state, ctx, persist, archive, receipt);
+  if (rejected) throw rejected;
+  return output;
+}

package/local-task-handoff-write-wire.mjs

@@ -0,0 +1,99 @@
+import Ajv from 'ajv';
+import { createPublicKey, verify } from 'node:crypto';
+import { canonical, sha256 } from './local-integrity.mjs';
+import { integer, ledgerIdentifier, nullable, object, relativePath, sha256 as hash } from './local-contract-types.mjs';
+import { archguardOperationSchemas, evaluateArchguardDrift } from './local-archguard-evaluate.mjs';
+import { canonicalHandoffSignature, receiverClaim } from './local-task-handoff-overlay-wire.mjs';
+
+const native = await archguardOperationSchemas();
+const exact = fields => object(fields, Object.keys(fields)), text = { type: 'string' }, bool = { type: 'boolean' };
+const count = integer(0), time = { type: 'string', pattern: '^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$' };
+const array = items => ({ type: 'array', items });
+const location = object({ line: count, column: count, start: count, end: count, syntaxKind: text,
+  parser: text, semanticSyntaxKind: text, dependency: text, namespace: text }, ['line', 'column']);
+const evidence = object({ reason: text, dependency: text, declarations: array(text), locations: array(location),
+  allowedExtensions: array(text), actual: count, budget: count, matches: count, offsets: array(count),
+  diagnostics: array(object({ ...location.properties, code: { type: ['string', 'integer'] }, message: text }, ['line', 'column', 'code'])), extension: text }, []);
+const nonempty = { type: 'string', minLength: 1 };
+const finding = exact({ severity: { enum: ['P0', 'P1', 'P2'] }, ruleId: nonempty, entityRef: nonempty, message: nonempty, category: nonempty, blocking: bool, evidence });
+const drift = exact({ trend: { enum: ['green', 'yellow', 'red'] }, totalBlocks: count, recentBlocks: count, blockedBlocks: count,
+  violationRate: { type: 'number', minimum: 0, maximum: 100 }, consecutiveBlocks: count, repeatedRuleIds: array(text), action: nonempty });
+const checkpoint = exact({ status: { enum: ['passed', 'blocked'] }, writeAllowed: bool, rollbackRequired: bool,
+  findings: { ...array(finding), maxItems: 10000 }, metrics: exact({ path: relativePath,
+    inspectionScope: { enum: ['first-party', 'dependency-lockfile', 'third-party', 'generated'] }, complexityChecked: bool,
+    fileLines: count, maxFunctionLines: count, maxNestingDepth: count, animations: count, transitions: count }), drift, instruction: nonempty });
+export const HANDOFF_WRITE_CHECKPOINT_SCHEMA = exact({
+  schemaVersion: { const: 'entrorove.task-handoff-write-checkpoint/1.0' }, receiptId: ledgerIdentifier,
+  handoffId: ledgerIdentifier, messageRequestId: ledgerIdentifier, ownerId: { type: 'string', pattern: '^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$' },
+  previousOwnerTaskId: ledgerIdentifier, previousOwnerFlowId: ledgerIdentifier, previousOwnerTaskDigest: hash,
+  previousOwnerChainDigest: hash, previousOwnerEpoch: integer(1), receiverTaskId: ledgerIdentifier, receiverFlowId: ledgerIdentifier,
+  receiverTaskDigest: hash, receiverChainDigest: hash, receiverEpoch: integer(1), localRepositoryDigest: { type: 'string', pattern: '^[0-9a-f]{32}$' },
+  architectureAuthorityDigest: nullable(hash), scopeArtifactDigest: nullable(hash), contractDigest: nullable(hash), contractRevision: nullable(integer(1)),
+  initialLedgerDigest: nullable(hash), initialHeadDigest: nullable(hash), passDigest: hash, leaseDigest: hash, generation: { const: 1 }, snapshotDigest: hash,
+  sequence: integer(1), previousReceiptDigest: nullable(hash), blockId: ledgerIdentifier, path: relativePath,
+  beforeSha256: hash, proposedAfterSha256: hash, actualAfterSha256: hash, beforeExists: bool, actualAfterExists: bool,
+  evaluationKind: { enum: ['scope-only', 'scope-budget', 'native-architecture'] }, writeOutcome: { enum: ['retained', 'blocked'] },
+  checkpoint: nullable(checkpoint), ledgerEntry: nullable(native['drift-status'].input.properties.ledger.items), observedAt: time,
+  keyId: hash, nonce: ledgerIdentifier, issuedAt: time, expiresAt: time, signature: { type: 'string', pattern: '^[A-Za-z0-9_-]{86}$' } });
+const ajv = new Ajv({ strict: false }), validate = ajv.compile(HANDOFF_WRITE_CHECKPOINT_SCHEMA);
+const same = (left, right) => canonical(left) === canonical(right);
+export function handoffWriteFail(message) { throw Object.assign(new Error(`Trusted handoff write archive: ${message}`), { code: 'ENTROROVE_HANDOFF_WRITE_ARCHIVE' }); }
+export function writeReceiptIdentity(claim, ctx) {
+  const { pass, lease, challenge } = receiverClaim(claim, ctx, false), architecture = pass.architectureAuthority;
+  return { handoffId: pass.handoffId, messageRequestId: pass.messageRequestId, ownerId: pass.ownerId,
+    previousOwnerTaskId: pass.previousOwnerTaskId, previousOwnerFlowId: pass.previousOwnerFlowId,
+    previousOwnerTaskDigest: challenge.previousOwnerTaskDigest, previousOwnerChainDigest: challenge.previousOwnerChainDigest,
+    previousOwnerEpoch: pass.epoch, receiverTaskId: pass.receiverTaskId, receiverFlowId: pass.flowId,
+    receiverTaskDigest: pass.taskDigest, receiverChainDigest: pass.chainDigest, receiverEpoch: pass.receiverEpoch,
+    localRepositoryDigest: pass.localRepositoryDigest, architectureAuthorityDigest: architecture ? sha256(canonical(architecture)) : null,
+    scopeArtifactDigest: architecture?.scopeArtifactDigest ?? null, contractDigest: architecture?.contractDigest ?? null,
+    contractRevision: architecture?.revision ?? null, initialLedgerDigest: architecture?.ledgerDigest ?? null,
+    initialHeadDigest: architecture?.headDigest ?? null, passDigest: sha256(canonical(claim.pass)), leaseDigest: sha256(canonical(claim.lease)),
+    generation: lease.generation, snapshotDigest: pass.scopeSnapshotDigest };
+}
+function runnerKey(keyId) {
+  try {
+    const encoded = process.env.ENTROROVE_TASK_HANDOFF_RUNNER_PUBLIC_KEY, der = Buffer.from(encoded ?? '', 'base64');
+    const key = createPublicKey({ key: der, format: 'der', type: 'spki' });
+    if (key.asymmetricKeyType !== 'ed25519' || key.export({ format: 'der', type: 'spki' }).toString('base64') !== encoded
+      || sha256(der) !== keyId) handoffWriteFail('trusted registered runner signing identity changed');
+    return key;
+  } catch { handoffWriteFail('trusted registered runner signing identity is unavailable'); }
+}
+export function verifyWriteReceipt(receipt, claim, ctx) {
+  assertWriteReceiptFields(receipt);
+  const identity = writeReceiptIdentity(claim, ctx), { signature, ...core } = receipt;
+  if (!Object.entries(identity).every(([key, value]) => same(value, receipt[key]))
+    || receipt.keyId !== claim.pass.runnerKeyId
+    || !verify(null, Buffer.from(canonical(core)), runnerKey(receipt.keyId), canonicalHandoffSignature(signature))) handoffWriteFail('receipt signature or frozen original identity changed');
+  const observed = Date.parse(receipt.observedAt), issued = Date.parse(receipt.issuedAt), expires = Date.parse(receipt.expiresAt);
+  if (![observed, issued, expires].every(Number.isFinite) || observed < Math.max(Date.parse(claim.pass.issuedAt), Date.parse(claim.lease.issuedAt))
+    || observed > Math.min(Date.parse(claim.pass.expiresAt), Date.parse(claim.lease.expiresAt))
+    || issued < observed || issued > Date.now() || expires <= issued || expires - issued > 300_000) handoffWriteFail('actual observation or signing time exceeded its original grant');
+  return receipt;
+}
+export function assertWriteReceiptFields(receipt) {
+  if (!validate(receipt)) handoffWriteFail(`receipt fields are invalid: ${ajv.errorsText(validate.errors)}`);
+}
+export async function verifyWriteNativeResult(receipt, authority, entries) {
+  const result = receipt.checkpoint, entry = receipt.ledgerEntry;
+  if (receipt.evaluationKind !== 'native-architecture') {
+    if (result !== null || entry !== null || (receipt.evaluationKind === 'scope-budget' && receipt.writeOutcome !== 'blocked')
+      || (receipt.evaluationKind === 'scope-only' && authority !== null)) handoffWriteFail('scope-only evidence fabricated a native result');
+    return null;
+  }
+  if (!authority || !result || !entry) handoffWriteFail('actual native checkpoint and original authority are required');
+  const expected = { blockId: receipt.blockId, path: receipt.path, contractRevision: receipt.contractRevision,
+    beforeSha256: receipt.beforeSha256, afterSha256: receipt.proposedAfterSha256 };
+  const rules = [...new Set(result.findings.map(row => row.ruleId))].sort();
+  const blocking = [...new Set(result.findings.filter(row => row.blocking).map(row => row.ruleId))].sort();
+  if (!Object.entries(expected).every(([key, value]) => same(entry[key], value)) || !same(entry.ruleIds, rules)
+    || !same(entry.blockingRuleIds, blocking) || result.metrics.path !== receipt.path || result.findings.some(row => row.entityRef !== receipt.path)
+    || entry.status !== result.status || (blocking.length > 0) !== (entry.status === 'blocked')
+    || entry.rollbackRequired !== (entry.status === 'blocked') || result.rollbackRequired !== entry.rollbackRequired
+    || result.writeAllowed !== (entry.status === 'passed') || receipt.writeOutcome !== (entry.status === 'passed' ? 'retained' : 'blocked')) handoffWriteFail('native ledger and actual physical result are inconsistent');
+  const actualDrift = await evaluateArchguardDrift([...authority.ledger.slice(authority.driftEpochStart), ...entries, entry]);
+  if (!same(actualDrift, result.drift) || result.instruction !== (actualDrift.trend === 'red'
+    ? 'rollback-block-and-interrupt-aimlock' : entry.rollbackRequired ? 'rollback-block-and-correct' : 'accept-block')) handoffWriteFail('actual ordered native drift or instruction changed');
+  return actualDrift;
+}

package/local-task-routing.mjs

@@ -1,3 +1,4 @@
+import { operationSchemasFor } from './local-contracts.mjs';
 import { createHash, randomUUID } from 'node:crypto';
 import { promises as fs } from 'node:fs';
 import os from 'node:os';
@@ -6,31 +7,210 @@ import { withStateLock } from './local-state-lock.mjs';
 
 export const TASK_ROUTING_SCHEMA = 'entrorove.task-routing/1.0';
 const ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
-function fail(code, message) { const error = new Error(message); error.code = code; throw error; }
+function fail(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  throw error;
+}
 function digest(value) { return createHash('sha256').update(value).digest('hex'); }
-function canonical(value) { if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`; if (value && typeof value === 'object') return `{${Object.keys(value).sort().map(key => `${JSON.stringify(key)}:${canonical(value[key])}`).join(',')}}`; return JSON.stringify(value); }
-function homeRoot(home = os.homedir()) { if (typeof home !== 'string' || !path.isAbsolute(home)) fail('ENTROROVE_HOME_INVALID', 'home must be absolute'); return path.join(home, '.entrorove'); }
-async function repo(value) { if (typeof value !== 'string' || !path.isAbsolute(value)) fail('ENTROROVE_ROOT_INVALID', 'repositoryRoot must be absolute'); const stat = await fs.lstat(value); if (!stat.isDirectory() || stat.isSymbolicLink()) fail('ENTROROVE_ROOT_INVALID', 'repositoryRoot must be a real directory'); return fs.realpath(value); }
+function canonical(value) {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`;
+  if (value && typeof value === 'object') {
+    return `{${Object.keys(value).sort().map(key => `${JSON.stringify(key)}:${canonical(value[key])}`).join(',')}}`;
+  }
+  return JSON.stringify(value);
+}
+function homeRoot(home = os.homedir()) {
+  if (typeof home !== 'string' || !path.isAbsolute(home)) fail('ENTROROVE_HOME_INVALID', 'home must be absolute');
+  return path.join(home, '.entrorove');
+}
+async function repo(value) {
+  if (typeof value !== 'string' || !path.isAbsolute(value)) fail('ENTROROVE_ROOT_INVALID', 'repositoryRoot must be absolute');
+  const stat = await fs.lstat(value);
+  if (!stat.isDirectory() || stat.isSymbolicLink()) fail('ENTROROVE_ROOT_INVALID', 'repositoryRoot must be a real directory');
+  return fs.realpath(value);
+}
 function statePath(home, root) { return path.join(homeRoot(home), 'task-routing', digest(root).slice(0, 32), 'state.json'); }
-async function privateDir(directory) { await fs.mkdir(directory, { recursive: true, mode: 0o700 }); const stat = await fs.lstat(directory); if (!stat.isDirectory() || stat.isSymbolicLink()) fail('ENTROROVE_STATE_INVALID', 'state directory must be a real directory'); if (process.platform !== 'win32') await fs.chmod(directory, 0o700); }
-async function load(input, create = true) { const root = await repo(input.repositoryRoot); const file = statePath(input.home, root); await privateDir(path.dirname(file)); try { const stat = await fs.lstat(file); if (!stat.isFile() || stat.isSymbolicLink()) fail('ENTROROVE_STATE_INVALID', 'task routing state must be a regular file'); const state = JSON.parse(await fs.readFile(file, 'utf8')); if (state.schemaVersion !== TASK_ROUTING_SCHEMA || state.repositoryDigest !== digest(root).slice(0, 32)) fail('ENTROROVE_TASK_STATE_INVALID', 'task routing state identity mismatch'); return { root, file, state }; } catch (cause) { if (!create || cause.code !== 'ENOENT') throw cause; const state = { schemaVersion: TASK_ROUTING_SCHEMA, repositoryDigest: digest(root).slice(0, 32), sequence: 0, tasks: [], messages: [], records: [] }; await save(file, state); return { root, file, state }; } }
-async function save(file, state) { await privateDir(path.dirname(file)); const temp = `${file}.${randomUUID()}.tmp`; await fs.writeFile(temp, `${canonical(state)}\n`, { flag: 'wx', mode: 0o600 }); await fs.rename(temp, file); if (process.platform !== 'win32') await fs.chmod(file, 0o600); }
-function requireId(value, label) { if (typeof value !== 'string' || !ID.test(value)) fail('ENTROROVE_ID_INVALID', `${label} must be a safe identifier`); return value; }
-function taskRecord(state, taskId) { const task = state.tasks.find(item => item.taskId === taskId); if (!task) fail('ENTROROVE_TASK_UNKNOWN', `unknown task: ${taskId}`); return task; }
-async function record(authority, event, data) { const entry = { sequence: authority.state.sequence + 1, event, at: new Date().toISOString(), ...data }; const state = { ...authority.state, sequence: entry.sequence, records: [...authority.state.records, { ...entry, digest: digest(canonical(entry)) }] }; await save(authority.file, state); authority.state = state; return entry; }
-async function routingLock(input, action) { const root = await repo(input.repositoryRoot); return withStateLock(statePath(input.home, root), action); }
-async function describeUnlocked(input) { const taskId = requireId(input.taskId ?? `task-${randomUUID()}`, 'taskId'); if (typeof input.goal !== 'string' || !input.goal.trim()) fail('ENTROROVE_TASK_GOAL_REQUIRED', 'goal is required'); const authority = await load(input); const original = { taskId, goal: input.goal, ownerId: input.ownerId ?? null, checkpoint: input.checkpoint ?? null, createdAt: input.createdAt ?? new Date().toISOString() }; const task = authority.state.tasks.find(item => item.taskId === taskId); if (task) { if (task.goalDigest !== digest(canonical(original))) return { schemaVersion: TASK_ROUTING_SCHEMA, status: 'blocked', code: 'ENTROROVE_TASK_ID_REUSED' }; return { schemaVersion: TASK_ROUTING_SCHEMA, status: 'verified', task }; } const next = { ...original, goalDigest: digest(canonical(original)), status: 'pending', messages: [], resumedAt: null }; const state = { ...authority.state, tasks: [...authority.state.tasks, next] }; await save(authority.file, state); authority.state = state; await record(authority, 'task-describe', { taskId }); return { schemaVersion: TASK_ROUTING_SCHEMA, status: 'verified', task: next }; }
-async function routeUnlocked(input) { const taskId = requireId(input.taskId, 'taskId'); const messageId = requireId(input.messageId ?? `message-${randomUUID()}`, 'messageId'); const authority = await load(input); const task = taskRecord(authority.state, taskId); if (authority.state.messages.some(item => item.messageId === messageId)) return { schemaVersion: TASK_ROUTING_SCHEMA, status: 'verified', message: authority.state.messages.find(item => item.messageId === messageId), duplicate: true }; if (task.status === 'failed' || task.status === 'completed') return { schemaVersion: TASK_ROUTING_SCHEMA, status: 'blocked', code: 'ENTROROVE_TASK_TERMINAL' }; const message = { messageId, taskId, body: input.body ?? null, destination: input.destination ?? task.ownerId, status: 'routed', routedAt: new Date().toISOString(), delivery: 'pending' }; const state = { ...authority.state, messages: [...authority.state.messages, message], tasks: authority.state.tasks.map(item => item.taskId === taskId ? { ...item, status: 'routed' } : item) }; await save(authority.file, state); authority.state = state; await record(authority, 'message-route', { taskId, messageId, destination: message.destination }); return { schemaVersion: TASK_ROUTING_SCHEMA, status: 'verified', message }; }
-async function acceptUnlocked(input) { const taskId = requireId(input.taskId, 'taskId'); const messageId = requireId(input.messageId, 'messageId'); const authority = await load(input); const message = authority.state.messages.find(item => item.taskId === taskId && item.messageId === messageId); if (!message || message.status !== 'routed') return { schemaVersion: TASK_ROUTING_SCHEMA, status: 'blocked', code: 'ENTROROVE_MESSAGE_NOT_ROUTABLE' }; if (input.ownerId && message.destination && input.ownerId !== message.destination) return { schemaVersion: TASK_ROUTING_SCHEMA, status: 'blocked', code: 'ENTROROVE_MESSAGE_OWNER' }; const accepted = { ...message, status: 'accepted', acceptedAt: new Date().toISOString(), acceptedBy: input.ownerId ?? message.destination ?? null }; const state = { ...authority.state, messages: authority.state.messages.map(item => item.messageId === messageId ? accepted : item), tasks: authority.state.tasks.map(item => item.taskId === taskId ? { ...item, status: 'accepted', ownerId: accepted.acceptedBy ?? item.ownerId } : item) }; await save(authority.file, state); authority.state = state; await record(authority, 'message-accept', { taskId, messageId, acceptedBy: accepted.acceptedBy }); return { schemaVersion: TASK_ROUTING_SCHEMA, status: 'verified', receipt: { receiptId: `receipt-${randomUUID()}`, taskId, messageId, acceptedBy: accepted.acceptedBy, acceptedAt: accepted.acceptedAt }, message: accepted }; }
-async function resumeUnlocked(input) { const taskId = requireId(input.taskId, 'taskId'); const authority = await load(input); const task = taskRecord(authority.state, taskId); if (!['accepted', 'active'].includes(task.status)) return { schemaVersion: TASK_ROUTING_SCHEMA, status: 'blocked', code: 'ENTROROVE_TASK_NOT_ACCEPTED', taskId }; const resumed = { ...task, status: 'active', resumedAt: new Date().toISOString() }; const state = { ...authority.state, tasks: authority.state.tasks.map(item => item.taskId === taskId ? resumed : item) }; await save(authority.file, state); authority.state = state; await record(authority, 'task-resume', { taskId, status: resumed.status }); return { schemaVersion: TASK_ROUTING_SCHEMA, status: 'verified', task: resumed, pendingMessages: authority.state.messages.filter(item => item.taskId === taskId && item.status === 'accepted') }; }
+async function privateDir(directory) {
+  await fs.mkdir(directory, { recursive: true, mode: 0o700 });
+  const stat = await fs.lstat(directory);
+  if (!stat.isDirectory() || stat.isSymbolicLink()) fail('ENTROROVE_STATE_INVALID', 'state directory must be a real directory');
+  if (process.platform !== 'win32' && (stat.mode & 0o777) !== 0o700) await fs.chmod(directory, 0o700);
+}
+async function load(input, create = true) {
+  const root = await repo(input.repositoryRoot);
+  const file = statePath(input.home, root);
+  if (create) await privateDir(path.dirname(file));
+  try {
+    const stat = await fs.lstat(file);
+    if (!stat.isFile() || stat.isSymbolicLink()) fail('ENTROROVE_STATE_INVALID', 'task routing state must be a regular file');
+    const state = JSON.parse(await fs.readFile(file, 'utf8'));
+    if (state.schemaVersion !== TASK_ROUTING_SCHEMA || state.repositoryDigest !== digest(root).slice(0, 32)) {
+      fail('ENTROROVE_TASK_STATE_INVALID', 'task routing state identity mismatch');
+    }
+    return { root, file, state };
+  } catch (cause) {
+    if (cause.code !== 'ENOENT') throw cause;
+    if (!create) fail('ENTROROVE_TASK_UNKNOWN', 'Task routing state does not exist; describe the task first');
+    const state = { schemaVersion: TASK_ROUTING_SCHEMA, repositoryDigest: digest(root).slice(0, 32),
+      sequence: 0, tasks: [], messages: [], records: [] };
+    await save(file, state);
+    return { root, file, state };
+  }
+}
+async function save(file, state) {
+  await privateDir(path.dirname(file));
+  const temp = `${file}.${randomUUID()}.tmp`;
+  await fs.writeFile(temp, `${canonical(state)}\n`, { flag: 'wx', mode: 0o600 });
+  await fs.rename(temp, file);
+  if (process.platform !== 'win32') await fs.chmod(file, 0o600);
+}
+function requireId(value, label) {
+  if (typeof value !== 'string' || !ID.test(value)) fail('ENTROROVE_ID_INVALID', `${label} must be a safe identifier`);
+  return value;
+}
+function taskRecord(state, taskId) {
+  const task = state.tasks.find(item => item.taskId === taskId);
+  if (!task) fail('ENTROROVE_TASK_UNKNOWN', `unknown task: ${taskId}`);
+  return task;
+}
+async function record(authority, event, data, nextState = authority.state) {
+  const entry = { sequence: authority.state.sequence + 1, event, at: new Date().toISOString(), ...data };
+  const state = { ...nextState, sequence: entry.sequence,
+    records: [...authority.state.records, { ...entry, digest: digest(canonical(entry)) }] };
+  await save(authority.file, state);
+  authority.state = state;
+  return entry;
+}
+async function routingLock(input, action) {
+  const root = await repo(input.repositoryRoot);
+  return withStateLock(statePath(input.home, root), action);
+}
+function originalDescription(value) {
+  return { taskId: value.taskId, goal: value.goal, ownerId: value.ownerId ?? null, checkpoint: value.checkpoint ?? null };
+}
+
+async function describeUnlocked(input) {
+  const taskId = requireId(input.taskId ?? `task-${randomUUID()}`, 'taskId');
+  if (typeof input.goal !== 'string' || !input.goal.trim()) fail('ENTROROVE_TASK_GOAL_REQUIRED', 'goal is required');
+  const authority = await load(input);
+  const original = originalDescription({ ...input, taskId });
+  const task = authority.state.tasks.find(item => item.taskId === taskId);
+  if (task) {
+    if (canonical(originalDescription(task)) !== canonical(original)
+      || (input.createdAt !== undefined && input.createdAt !== task.createdAt)) {
+      return { schemaVersion: TASK_ROUTING_SCHEMA, status: 'blocked', code: 'ENTROROVE_TASK_ID_REUSED' };
+    }
+    return { schemaVersion: TASK_ROUTING_SCHEMA, status: 'reported', task };
+  }
+  const next = { ...original, createdAt: input.createdAt ?? new Date().toISOString(),
+    goalDigest: digest(canonical(original)), status: 'pending', messages: [], resumedAt: null };
+  const state = { ...authority.state, tasks: [...authority.state.tasks, next] };
+  await record(authority, 'task-describe', { taskId }, state);
+  return { schemaVersion: TASK_ROUTING_SCHEMA, status: 'reported', task: next };
+}
+function originalMessage(value) {
+  return { messageId: value.messageId, taskId: value.taskId, body: value.body ?? null,
+    destination: value.destination ?? null, source: value.source ?? null };
+}
+
+async function routeUnlocked(input) {
+  const taskId = requireId(input.taskId, 'taskId');
+  const messageId = requireId(input.messageId ?? `message-${randomUUID()}`, 'messageId');
+  const authority = await load(input);
+  const task = taskRecord(authority.state, taskId);
+  const original = originalMessage({ ...input, messageId, taskId, destination: input.destination ?? task.ownerId });
+  const previous = authority.state.messages.find(item => item.messageId === messageId);
+  if (previous) {
+    if (canonical(originalMessage(previous)) !== canonical(original)) {
+      return { schemaVersion: TASK_ROUTING_SCHEMA, status: 'blocked', code: 'ENTROROVE_MESSAGE_ID_REUSED' };
+    }
+    return { schemaVersion: TASK_ROUTING_SCHEMA, status: 'reported', message: previous, duplicate: true };
+  }
+  if (['blocked', 'failed', 'completed'].includes(task.status)) {
+    return { schemaVersion: TASK_ROUTING_SCHEMA, status: 'blocked', code: 'ENTROROVE_TASK_TERMINAL' };
+  }
+  const message = { ...original, messageDigest: digest(canonical(original)), status: 'routed',
+    routedAt: new Date().toISOString(), delivery: 'pending' };
+  const state = { ...authority.state, messages: [...authority.state.messages, message],
+    tasks: authority.state.tasks.map(item => item.taskId === taskId && item.status === 'pending'
+      ? { ...item, status: 'routed' } : item) };
+  await record(authority, 'message-route', { taskId, messageId, destination: message.destination }, state);
+  return { schemaVersion: TASK_ROUTING_SCHEMA, status: 'reported', message };
+}
+async function acceptUnlocked(input) {
+  const taskId = requireId(input.taskId, 'taskId');
+  const messageId = requireId(input.messageId, 'messageId');
+  const ownerId = requireId(input.ownerId, 'ownerId');
+  const authority = await load(input);
+  const message = authority.state.messages.find(item => item.taskId === taskId && item.messageId === messageId);
+  if (!message || !['routed', 'accepted'].includes(message.status)) {
+    return { schemaVersion: TASK_ROUTING_SCHEMA, status: 'blocked', code: 'ENTROROVE_MESSAGE_NOT_ROUTABLE' };
+  }
+  if (!message.destination || ownerId !== message.destination) {
+    return { schemaVersion: TASK_ROUTING_SCHEMA, status: 'blocked', code: 'ENTROROVE_MESSAGE_OWNER' };
+  }
+  if (message.status === 'accepted') {
+    if (!validReceipt(message.receipt, message, authority.state.repositoryDigest)) {
+      return { schemaVersion: TASK_ROUTING_SCHEMA, status: 'blocked', code: 'ENTROROVE_MESSAGE_RECEIPT_MISSING' };
+    }
+    return { schemaVersion: TASK_ROUTING_SCHEMA, status: 'reported', receipt: message.receipt,
+      message, duplicate: true };
+  }
+  const task = taskRecord(authority.state, taskId);
+  if (!['routed', 'accepted', 'active'].includes(task.status)) {
+    return { schemaVersion: TASK_ROUTING_SCHEMA, status: 'blocked', code: 'ENTROROVE_TASK_NOT_ROUTABLE' };
+  }
+  const accepted = { ...message, status: 'accepted', acceptedAt: new Date().toISOString(), acceptedBy: ownerId };
+  accepted.receipt = { schemaVersion: 'entrorove.message-receipt/1.0', source: 'local-communication',
+    receiptId: `receipt-${randomUUID()}`, taskId, messageId, repositoryDigest: authority.state.repositoryDigest,
+    messageDigest: digest(canonical(originalMessage(message))), acceptedBy: ownerId, acceptedAt: accepted.acceptedAt };
+  const state = { ...authority.state,
+    messages: authority.state.messages.map(item => item.messageId === messageId ? accepted : item),
+    tasks: authority.state.tasks.map(item => item.taskId === taskId && item.status === 'routed'
+      ? { ...item, status: 'accepted' } : item) };
+  await record(authority, 'message-accept', { taskId, messageId, acceptedBy: accepted.acceptedBy,
+    receiptId: accepted.receipt.receiptId }, state);
+  return { schemaVersion: TASK_ROUTING_SCHEMA, status: 'reported', receipt: accepted.receipt, message: accepted };
+}
+
+function validReceipt(receipt, message, repositoryDigest) {
+  return receipt && receipt.schemaVersion === 'entrorove.message-receipt/1.0'
+    && receipt.source === 'local-communication' && typeof receipt.receiptId === 'string' && ID.test(receipt.receiptId)
+    && receipt.taskId === message.taskId && receipt.messageId === message.messageId
+    && receipt.repositoryDigest === repositoryDigest && receipt.acceptedBy === message.acceptedBy
+    && receipt.acceptedAt === message.acceptedAt && receipt.acceptedBy === message.destination
+    && receipt.messageDigest === digest(canonical(originalMessage(message)));
+}
+function resumePackage(task, state) {
+  const checkpoint = task.checkpoint ?? null;
+  const requirements = task.requirements ?? checkpoint?.requirements ?? checkpoint?.originalRequirements ?? [];
+  const completed = new Set(checkpoint?.completedRequirementIds ?? []);
+  const remainingRequirements = task.remainingRequirements ?? checkpoint?.remainingRequirements
+    ?? requirements.filter(requirement => !completed.has(requirement.id));
+  const pendingMessages = state.messages.filter(message => message.taskId === task.taskId
+    && !['completed', 'failed', 'cancelled'].includes(message.status));
+  return { task, originalGoal: task.goal, checkpoint, requirements, remainingRequirements, pendingMessages,
+    inbox: task.inbox ?? checkpoint?.inbox ?? pendingMessages,
+    outbox: task.outbox ?? task.pendingOutbox ?? checkpoint?.outbox ?? checkpoint?.pendingOutbox ?? [],
+    continuationNotifications: task.continuationNotifications ?? checkpoint?.continuationNotifications ?? [],
+    nextAction: checkpoint?.nextAction ?? task.nextAction ?? null,
+    canContinue: ['accepted', 'active'].includes(task.status), engineeringAuthorization: 'cloud-required' };
+}
+
+async function resumeUnlocked(input) {
+  const taskId = requireId(input.taskId, 'taskId');
+  const authority = await load(input, false);
+  const task = taskRecord(authority.state, taskId);
+  const recovered = resumePackage(task, authority.state);
+  if (!recovered.canContinue) {
+    return { schemaVersion: TASK_ROUTING_SCHEMA, status: 'blocked', code: 'ENTROROVE_TASK_NOT_ACCEPTED', taskId, ...recovered };
+  }
+  return { schemaVersion: TASK_ROUTING_SCHEMA, status: 'reported', ...recovered };
+}
 export async function taskDescribe(input) { return routingLock(input, () => describeUnlocked(input)); }
 export async function messageRoute(input) { return routingLock(input, () => routeUnlocked(input)); }
 export async function messageAccept(input) { return routingLock(input, () => acceptUnlocked(input)); }
-export async function taskResume(input) { return routingLock(input, () => resumeUnlocked(input)); }
+export async function taskResume(input) { return resumeUnlocked(input); }
 export const LOCAL_TASK_ROUTING_OPERATIONS = Object.freeze({ 'task-describe': taskDescribe, 'message-route': messageRoute, 'message-accept': messageAccept, 'task-resume': taskResume });
-export const LOCAL_TASK_ROUTING_SCHEMAS = Object.freeze({
-  'task-describe': { type: 'object', additionalProperties: false, required: ['repositoryRoot', 'goal'] },
-  'message-route': { type: 'object', additionalProperties: false, required: ['repositoryRoot', 'taskId', 'messageId'] },
-  'message-accept': { type: 'object', additionalProperties: false, required: ['repositoryRoot', 'taskId', 'messageId'] },
-  'task-resume': { type: 'object', additionalProperties: false, required: ['repositoryRoot', 'taskId'] },
-});
+export const LOCAL_TASK_ROUTING_SCHEMAS = operationSchemasFor(LOCAL_TASK_ROUTING_OPERATIONS);

package/manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": "entrorove.skill-manifest/1.0",
   "name": "entrorove",
-  "version": "0.1.22",
+  "version": "0.1.24",
   "endpoint": "https://entrorove.com",
   "requestSchemaVersion": "entrorove.skill.request/2.0",
   "supportedRequestSchemaVersions": [