@arcfold/dsh 0.0.0-stage → 0.4.0

package/src/business.mjs

@@ -0,0 +1,334 @@
+import { assertNativeContinuationIntegrity } from './native-continuation.mjs';
+import { createHash } from 'node:crypto';
+import { Store, DomainError, canonicalJson, identity, jsonClone } from './store.mjs';
+
+const MESSAGE_TYPES = new Set(['user/message', 'assistant/message', 'tool/result']);
+const SURFACE_TYPES = new Set([...MESSAGE_TYPES, 'system/message', 'developer/message']);
+const hash = value => createHash('sha256').update(canonicalJson(value)).digest('hex');
+export const eventId = (sessionId, seq) => `dsh-event:${hash([sessionId, seq])}`;
+const turnId = (sessionId, turn) => `dsh-turn:${hash([sessionId, turn])}`;
+
+/** Read visible text without persisting a second copy of message blocks. */
+export function messageText(message) {
+  return (message?.content || []).filter(block => block.type === 'text').map(block => block.text).join('');
+}
+
+function eventBatch(sessionId, events) {
+  identity(sessionId, 'Session id');
+  if (!Array.isArray(events)) throw new DomainError('invalid_events', 'Events must be an array.', 400);
+  const copy = jsonClone(events);
+  for (let i = 0; i < copy.length; i++) {
+    const event = copy[i];
+    if (!event || typeof event !== 'object' || Array.isArray(event) ||
+        !Number.isSafeInteger(event.seq) || event.seq < 0 ||
+        !Number.isSafeInteger(event.time) || !Number.isFinite(new Date(event.time).getTime()) ||
+        !event.data || typeof event.data !== 'object' || Array.isArray(event.data))
+      throw new DomainError('invalid_event', 'Expected a lossless DSH event with seq, time and data.', 400);
+    identity(event.type, 'Event type');
+    if (i && event.seq !== copy[i - 1].seq + 1)
+      throw new DomainError('event_sequence_gap', 'Event batches must retain contiguous DSH order.');
+  }
+  return copy;
+}
+
+function validateMessage(message, role) {
+  if (!message || typeof message !== 'object' || !Array.isArray(message.content) ||
+      !message.source || typeof message.source !== 'object')
+    throw new DomainError('invalid_message', 'A DSH source message needs its content and producer.', 400);
+  identity(message.id, 'Message id'); identity(message.source.kind, 'Message producer');
+  if (message.role !== role) throw new DomainError('invalid_message_role', 'Event type and message role disagree.', 400);
+  for (const block of message.content) {
+    if (!block || typeof block !== 'object' || typeof block.type !== 'string' ||
+        (['text', 'reasoning'].includes(block.type) && typeof block.text !== 'string'))
+      throw new DomainError('invalid_message', 'Message blocks must preserve their declared type.', 400);
+  }
+}
+
+function sourceProjection(sessionId, event, sha256) {
+  if (!MESSAGE_TYPES.has(event.type)) return null;
+  const message = event.type === 'user/message' ? event.data : event.data.message;
+  const role = event.type === 'user/message' ? 'user' : event.type === 'assistant/message' ? 'assistant' : 'tool';
+  validateMessage(message, role);
+  // A user-role runtime snapshot/relay is never a human decision.
+  const author = message.source.kind === (role === 'assistant' ? 'model' : role) ? role : 'program';
+  const sourceRef = { sessionId, seq: event.seq, type: event.type, sha256 };
+  return { id: eventId(sessionId, event.seq), conversationId: sessionId, sessionId,
+    role: author, author, occurredAt: new Date(event.time).toISOString(),
+    provenance: { kind: 'dsh_session', source: message.source, sourceRef },
+    message, surfaceOp: event.surfaceOp ?? null,
+    sourceEventSeqs: event.sourceEventSeqs ?? [],
+    ...(event.type !== 'user/message' ? { turn: event.data.turn, step: event.data.step } : {}),
+    ...(event.data.interrupted === true ? { interrupted: true } : {}) };
+}
+
+function sourceIndex(sources) {
+  const index = new Map();
+  for (const source of sources) {
+    // Authentic command sources are business originals, not chat messages.
+    if (!source.message?.id) continue;
+    const id = source.message.id;
+    if (!index.has(id)) index.set(id, []);
+    index.get(id).push(source);
+  }
+  return index;
+}
+
+function sameMessage(sources, message) {
+  if (sources.some(source => canonicalJson(source.message) !== canonicalJson(message)))
+    throw new DomainError('source_identity_conflict', 'The same native message identity has different original content.');
+}
+
+// The caller owns the official claim boundary. Match its complete message to
+// real durable insertion facts; this does not implement another inbox/driver.
+function claimedOrigins(batch, messages) {
+  return messages.map(message => {
+    const origins = batch.flatMap(event => event.type === 'agent/inbox/spliced' && Array.isArray(event.data.inserted)
+      ? event.data.inserted.flatMap((input, index) => input?.id === message.id ? [{ message: input, event, index }] : []) : []);
+    if (!origins.length)
+      throw new DomainError('invalid_claimed_input', 'Claimed input has no durable native inbox original.');
+    // Official queue editing preserves message.id and replaces its content.
+    // Only the latest insertion can match the host's current claimed payload;
+    // sameMessage still protects any original already saved as a source.
+    const origin = origins.at(-1);
+    if (canonicalJson(origin.message) !== canonicalJson(message))
+      throw new DomainError('source_identity_conflict', 'Claimed input differs from its latest durable inbox original.');
+    return origin;
+  });
+}
+
+const metadata = new Set(['revision', 'createdAt', 'updatedAt', 'createdSequence', 'updatedSequence']);
+function original(record) {
+  return Object.fromEntries(Object.entries(record).filter(([key]) => !metadata.has(key)));
+}
+
+/** Only business records live here. DSH remains the execution/event-log owner. */
+export class BusinessStore {
+  constructor({ filename }) { this.storage = new Store(filename); }
+  get(...args) { return this.storage.get(...args); }
+  list(...args) { return this.storage.list(...args); }
+  listAll(...args) { return this.storage.listAll(...args); }
+  transaction(fn) { return this.storage.transaction(fn); }
+  close() { this.storage.close(); }
+
+  immutable(kind, record) {
+    const existing = this.get(kind, record.id);
+    if (existing) {
+      if (canonicalJson(original(existing)) !== canonicalJson(record))
+        throw new DomainError('source_identity_conflict', 'The same DSH identity has different original content.', 409,
+          { kind, id: record.id });
+      return existing;
+    }
+    return this.storage.save(kind, record);
+  }
+
+  /** Caller supplies the official claimed batch and a prefix covered by flush. */
+  ingestClaimedInputs({ sessionId, events, messages }) {
+    const batch = eventBatch(sessionId, events), inputs = jsonClone(messages);
+    if (!Array.isArray(inputs)) throw new DomainError('invalid_claimed_input', 'Claimed messages must be an array.', 400);
+    if (!inputs.length) return [];
+    if (!batch.length || batch[0].seq !== 0)
+      throw new DomainError('incomplete_history', 'Claimed input requires the complete durable native prefix.');
+    const ids = new Set();
+    for (const message of inputs) {
+      if (message?.role !== 'user' || message.source?.kind !== 'user' || message.source.principal !== undefined)
+        throw new DomainError('invalid_claimed_input', 'Only original owner user input can be admitted here.');
+      validateMessage(message, 'user');
+      if (ids.has(message.id)) throw new DomainError('invalid_claimed_input', 'Claimed message identities must be unique.');
+      ids.add(message.id);
+    }
+    const origins = claimedOrigins(batch, inputs);
+    return this.transaction(() => {
+      this.ingestSession({ sessionId, events: batch });
+      const index = sourceIndex(this.listAll('events', { where: { sessionId } }));
+      return inputs.map((message, i) => {
+        const origin = origins[i];
+        const inboxRef = { sessionId, seq: origin.event.seq, type: origin.event.type,
+          sha256: hash(origin.event), index: origin.index };
+        const previous = index.get(message.id) || [];
+        sameMessage(previous, message);
+        let source = previous[0];
+        if (!source) {
+          source = this.immutable('events', {
+            id: `dsh-inbox:${hash([sessionId, origin.event.seq, origin.index])}`,
+            conversationId: sessionId, sessionId, role: 'user', author: 'user',
+            occurredAt: new Date(origin.event.time).toISOString(), message,
+            provenance: { kind: 'dsh_session', source: message.source, sourceRef: inboxRef },
+            surfaceOp: null, sourceEventSeqs: [] });
+          index.set(message.id, [source]);
+        }
+        return { messageId: message.id, sourceId: source.id, inboxRef, messageHash: hash(message) };
+      });
+    });
+  }
+
+  /** Append/replay a contiguous prefix or its known continuation, atomically. */
+  ingestSession({ sessionId, events }) {
+    const batch = eventBatch(sessionId, events);
+    return this.transaction(() => {
+      const tail = this.list('dsh_events', { where: { sessionId }, order: 'desc', limit: 1 })[0];
+      let next = (tail?.seq ?? -1) + 1, inserted = 0, reused = 0;
+      const sourceIds = [];
+      const sources = sourceIndex(this.listAll('events', { where: { sessionId } }));
+      for (const event of batch) {
+        const id = eventId(sessionId, event.seq), existing = this.get('dsh_events', id);
+        if (!existing && event.seq !== next)
+          throw new DomainError('event_sequence_gap', 'Import the missing original DSH events first.');
+        const sha256 = hash(event);
+        this.immutable('dsh_events', { id, sessionId, seq: event.seq, type: event.type, time: event.time, sha256 });
+        const projection = sourceProjection(sessionId, event, sha256);
+        if (projection) {
+          const previous = sources.get(projection.message.id) || [];
+          const inbox = previous.find(row => row.provenance.sourceRef.type === 'agent/inbox/spliced');
+          const nativeUser = projection.message.role === 'user' && projection.message.source.kind === 'user';
+          const originalInput = previous.some(row => row.message.role === 'user' && row.message.source.kind === 'user');
+          if (nativeUser || originalInput || inbox) sameMessage(previous, projection.message);
+          // An already stored formal source retains its original event identity.
+          // New formal admission reuses its prepared original, not a second copy.
+          const direct = this.get('events', id);
+          const source = direct ? this.immutable('events', projection)
+            : inbox || (nativeUser && previous[0]) || this.immutable('events', projection);
+          if (!previous.some(row => row.id === source.id)) sources.set(projection.message.id, [...previous, source]);
+          sourceIds.push(source.id);
+        }
+        if (existing) reused++;
+        else { inserted++; next++; }
+      }
+      return { inserted, reused, sourceIds };
+    });
+  }
+
+  /** Caller must have confirmed DSH flush === true; this never calls a model. */
+  settleTurn({ sessionId, turn, events }) {
+    if (!Number.isSafeInteger(turn) || turn < 0)
+      throw new DomainError('invalid_turn', 'A nonnegative DSH turn number is required.', 400);
+    const batch = eventBatch(sessionId, events);
+    if (!batch.length || batch[0].seq !== 0)
+      throw new DomainError('incomplete_history', 'Settlement requires the complete original event prefix.');
+    return this.transaction(() => {
+      const imported = this.ingestSession({ sessionId, events: batch });
+      const sourceIds = new Map(batch.filter(event => MESSAGE_TYPES.has(event.type))
+        .map((event, index) => [event.seq, imported.sourceIds[index]]));
+      const analyzed = analyzeTurn(sessionId, turn, batch, sourceIds);
+      if (analyzed.reason) return { status: 'not_deliverable', reason: analyzed.reason };
+      const { start, end, final, inputEventIds, sourceEventIds, background } = analyzed;
+      const rounds = batch.filter(event => event.seq > start.seq && event.seq < end.seq &&
+        event.type === 'user/message' && event.data.source?.kind === 'goal' && event.data.source.round > 0);
+      let nativeContinuation;
+      if (rounds.length) {
+        const snapshots = this.listAll('context_snapshots', { where: { sessionId, turn } });
+        nativeContinuation = snapshots.length === 1 ? snapshots[0].material.nativeContinuation : null;
+        if (!nativeContinuation || rounds.length !== 1 || nativeContinuation.messageId !== rounds[0].data.id ||
+            nativeContinuation.sessionId !== sessionId || nativeContinuation.turn !== turn ||
+            nativeContinuation.goalId !== rounds[0].data.source.goalId ||
+            nativeContinuation.revision !== rounds[0].data.source.revision ||
+            nativeContinuation.round !== rounds[0].data.source.round)
+          return { status: 'not_deliverable', reason: 'unproven_native_continuation' };
+        assertNativeContinuationIntegrity(this.storage, nativeContinuation);
+      }
+      const id = turnId(sessionId, turn), reused = this.get('deliveries', id) !== null;
+      const delivery = this.immutable('deliveries', {
+        id, kind: 'formal_reply', taskOutcome: 'not_assessed', conversationId: sessionId, sessionId, turn,
+        eventId: eventId(sessionId, final.seq), inputEventIds, sourceEventIds,
+        startSeq: start.seq, throughSeq: end.seq,
+        endEventId: eventId(sessionId, end.seq),
+        occurredAt: new Date(end.time).toISOString(), backgroundAtTurnEnd: background,
+        ...(nativeContinuation ? { nativeContinuation } : {}),
+      });
+      const learningId = `learn:${hash([sessionId, turn])}`;
+      let learning = this.get('learning_pending', learningId);
+      if (learning && (learning.deliveryId !== delivery.id || learning.throughSeq !== end.seq))
+        throw new DomainError('learning_identity_conflict', 'Learning work is bound to another delivery.');
+      learning ||= this.storage.save('learning_pending', {
+        id: learningId, kind: 'delivery_learning', status: 'pending', sessionId, conversationId: sessionId,
+        turn, deliveryId: delivery.id, throughSeq: end.seq, sourceEventIds,
+      });
+      return { status: 'delivered', delivery, learning, reused };
+    });
+  }
+}
+
+function analyzeTurn(sessionId, turn, events, sourceIds) {
+  const starts = events.filter(event => event.type === 'turn/start' && event.data.turn === turn);
+  const ends = events.filter(event => event.type === 'turn/end' && event.data.turn === turn);
+  if (starts.length !== 1 || ends.length !== 1 || starts[0].seq >= ends[0].seq)
+    return { reason: 'incomplete_turn' };
+  const start = starts[0], end = ends[0];
+  if (events.some(event => event.type === 'session/end-seed' && event.data.inherited === true && event.seq > end.seq))
+    return { reason: 'inherited_turn' };
+  if (end.data.reason?.kind !== 'completed') return { reason: `turn_${end.data.reason?.kind || 'unknown'}` };
+  const inside = events.filter(event => event.seq > start.seq && event.seq < end.seq);
+  if (inside.some(event => event.type === 'turn/start' || event.type === 'turn/end' ||
+      (event.data.turn !== undefined && event.data.turn !== turn))) return { reason: 'invalid_turn_boundary' };
+  let step = null;
+  for (const event of inside) {
+    if (event.type === 'step/start') {
+      if (step !== null || !Number.isSafeInteger(event.data.step) || event.data.step < 0)
+        return { reason: 'invalid_step_boundary' };
+      step = event.data.step;
+    } else if (event.type === 'step/end') {
+      if (step === null || step !== event.data.step) return { reason: 'invalid_step_boundary' };
+      step = null;
+    } else if (['assistant/message', 'assistant/attempt', 'tool/call', 'tool/result'].includes(event.type) &&
+        (step === null || event.data.step !== step)) return { reason: 'invalid_step_boundary' };
+  }
+  if (step !== null) return { reason: 'incomplete_step' };
+  const assistants = inside.filter(event => event.type === 'assistant/message');
+  const final = assistants.at(-1);
+  if (!final || final.data.interrupted === true || final.data.message.source.kind !== 'model')
+    return { reason: 'no_complete_assistant' };
+  if (final.data.message.content.some(block => block.type === 'tool-call')) return { reason: 'final_tool_call' };
+  if (!messageText(final.data.message).trim()) return { reason: 'empty_reply' };
+
+  // Surface replacements can hide an earlier reply; don't publish its old text.
+  let surface = [];
+  for (const event of events) {
+    if (event.seq >= end.seq) break;
+    if (!SURFACE_TYPES.has(event.type)) continue;
+    if (event.surfaceOp === 'append') surface.push(event.seq);
+    else if (event.surfaceOp?.op === 'replace') {
+      const first = surface.indexOf(event.surfaceOp.startSeq), last = surface.indexOf(event.surfaceOp.endSeq);
+      if (first < 0 || last < first) return { reason: 'invalid_surface' };
+      surface.splice(first, last - first + 1, event.seq);
+    } else return { reason: 'invalid_surface' };
+  }
+  if (!surface.includes(final.seq)) return { reason: 'reply_replaced' };
+  if (inside.some(event => event.seq > final.seq && event.type === 'user/message' && event.data.source.kind === 'user'))
+    return { reason: 'unanswered_user_input' };
+
+  const calls = new Map(), dispatched = new Set(), results = new Set();
+  for (const event of inside) {
+    if (event.type === 'assistant/message') {
+      for (const block of event.data.message.content.filter(block => block.type === 'tool-call')) {
+        if (typeof block.id !== 'string' || calls.has(block.id)) return { reason: 'invalid_tool_trace' };
+        calls.set(block.id, event.seq);
+      }
+    } else if (event.type === 'tool/call') {
+      if (typeof event.data.callId !== 'string' || dispatched.has(event.data.callId)) return { reason: 'invalid_tool_trace' };
+      dispatched.add(event.data.callId);
+      if (!calls.has(event.data.callId)) calls.set(event.data.callId, event.seq);
+    } else if (event.type === 'tool/result') {
+      const message = event.data.message, id = message.toolCallId;
+      if (!calls.has(id) || calls.get(id) >= event.seq || results.has(id) ||
+          message.source.kind !== 'tool' || message.source.callId !== id || event.seq > final.seq)
+        return { reason: 'invalid_tool_trace' };
+      results.add(id);
+    }
+  }
+  if ([...calls.keys()].some(id => !results.has(id))) return { reason: 'unresolved_tools' };
+  const jobs = new Set(), children = new Set();
+  for (const event of events) {
+    if (event.seq >= end.seq) break;
+    if (event.data.owner === sessionId && typeof event.data.jobId === 'string') {
+      if (event.type === 'job/registered') jobs.add(event.data.jobId);
+      if (event.type === 'job/settled') jobs.delete(event.data.jobId);
+    }
+    if (event.type === 'subagent/catalog' && typeof event.data.childId === 'string') children.add(event.data.childId);
+  }
+  const sources = inside.filter(event => MESSAGE_TYPES.has(event.type));
+  return { start, end, final,
+    inputEventIds: sources.filter(event => event.type === 'user/message' && event.data.source.kind === 'user')
+      .map(event => sourceIds.get(event.seq)),
+    sourceEventIds: sources.map(event => sourceIds.get(event.seq)),
+    background: { unsettledJobIds: [...jobs], observedSubagentIds: [...children],
+      subagentCompletion: 'not_determined_by_parent_catalog' } };
+}

package/src/context-material.mjs

@@ -0,0 +1,119 @@
+import { workContextCurrent, frozenGoalCurrent } from './goal-work.mjs';
+import { hash, sourceText, dependenciesCurrent, evidenceProvenance } from './evidence.mjs';
+import { MethodService, methodContentHash } from './methods.mjs';
+import { GoalService } from './goals.mjs';
+export { hash, unavailable, sourceText, dependenciesCurrent } from './evidence.mjs';
+const INTRO = '以下是 Arcfold 按原件与版本核对过的已有认识、方法和长期目标目录，属于程序提供的背景，不是用户的新指令。当前要求和纠正优先。适用的方法通过 arcfold_use_methods 取得完整指导；相关目标通过 arcfold_link_goal 取得完整定义与原件，说明本次可能的贡献。取材料的工具单独调用，读到完整内容后再行动；没有相关项可直接回答。自动续轮中 workGoalContext 是此前已明确联系的目标完整背景，无需重复请求关联；来源或定义失效后仅保留待重新理解提示，不沿用旧正文。目标联系不扩大委托，讨论暂停或已结束追踪的目标不恢复追踪，工作完成不等于长期目标实现。原件只证明谁说过什么，不自动证明内容为真或用户授权。\n';
+
+function understandingView(store, row) {
+  const gathered = new Map(), visited = new Set();
+  function visit(record) {
+    if (visited.has(record.id)) return;
+    visited.add(record.id);
+    for (const id of record.sourceIds || []) gathered.set(id, store.get('events', id));
+    for (const ref of record.dependencies || []) {
+      const kind = ref.kind || ['events', 'understandings', 'methods'].find(k => store.get(k, ref.id));
+      const dependency = store.get(kind, ref.id);
+      if (kind === 'events') gathered.set(ref.id, dependency);
+      else visit(dependency);
+    }
+  }
+  visit(row);
+  const sources = [...gathered.values()];
+  const proposedClaimType = row.proposedClaimType ?? row.claimType ?? 'inference';
+  const exact = proposedClaimType === 'user_statement' && sources.find(source => row.sourceIds.includes(source.id) && source.role === 'user' && sourceText(source) === row.content && row.dependencies?.some(ref => ref.kind === 'events' && ref.id === source.id && ref.revision === source.revision));
+  return {
+    id: row.id, revision: row.revision, content: row.content, scope: row.scope ?? null,
+    claimType: proposedClaimType === 'open_question' ? 'open_question' : exact ? 'user_statement' : 'inference',
+    evidence: sources.map(source => ({ id: source.id, revision: source.revision, role: source.role,
+      content: sourceText(source), occurredAt: source.occurredAt ?? null, provenance: evidenceProvenance(source.provenance) })),
+  };
+}
+
+export function collectContext(store, { sessionId, turn, inputMessageIds = [], maxCharacters = 24000, requiredMaterial = {} }) {
+  if (!Number.isSafeInteger(maxCharacters) || maxCharacters < 1000 || maxCharacters > 180000) throw new Error('Invalid Arcfold context capacity');
+  const cutoffSequence = store.currentSequence();
+  const material = { version: 'arcfold-context-v1', sessionId, turn, inputMessageIds,
+    cutoffSequence, understandings: [], methods: [], goals: [],
+    goalCoverage: { available: 0, omitted: { capacity: 0, changed: 0 } },
+    methodCoverage: { available: 0, omitted: { capacity: 0, changed: 0 } },
+    coverage: { available: 0, omitted: { unavailable: 0, capacity: 0, changed: 0 } },
+    authority: 'revisable background with original evidence: user_statement is verbatim user text; inference and open_question are assistant interpretations; neither is proof of truth or action permission' };
+  // Only these proven complete additions can reserve capacity. Callers cannot
+  // replace version, session identity, cutoff or coverage metadata.
+  for (const key of ['nativeContinuation', 'workGoalContext', 'executionStage'])
+    if (requiredMaterial[key] !== undefined) material[key] = requiredMaterial[key];
+  if (contextMessage(material).content[0].text.length > maxCharacters)
+    throw new Error('Complete native delegation and context exceed the material capacity; nothing was truncated');
+  const goals = new GoalService({ business: { storage: store } }).catalog({ sessionId, cutoffSequence, inputMessageIds });
+  const addGoal = goal => {
+    material.goalCoverage.available++;
+    if (INTRO.length + JSON.stringify({ ...material, goals: [...material.goals, goal] }).length + 64 > maxCharacters)
+      material.goalCoverage.omitted.capacity++;
+    else material.goals.push(goal);
+  };
+  // A user's exact selected discussion gets capacity before inferred background.
+  goals.filter(goal => goal.explicitDiscussion).forEach(addGoal);
+  const candidates = store.listAll('understandings').filter(row => row.status === 'active' && (!row.scope?.conversationId || row.scope.conversationId === sessionId));
+  for (const row of candidates) {
+    if (!dependenciesCurrent(store, row, cutoffSequence)) { material.coverage.omitted.unavailable++; continue; }
+    material.coverage.available++;
+    const view = understandingView(store, row);
+    if (INTRO.length + JSON.stringify({ ...material, understandings: [...material.understandings, view] }).length + 64 > maxCharacters) {
+      material.coverage.omitted.capacity++;
+    } else material.understandings.push(view);
+  }
+  goals.filter(goal => !goal.explicitDiscussion).forEach(addGoal);
+  const methods = new MethodService({ business: { storage: store } }).catalog({ sessionId, cutoffSequence });
+  for (const method of methods) {
+    material.methodCoverage.available++;
+    if (INTRO.length + JSON.stringify({ ...material, methods: [...material.methods, method] }).length + 64 > maxCharacters)
+      material.methodCoverage.omitted.capacity++;
+    else material.methods.push(method);
+  }
+  if (INTRO.length + JSON.stringify(material).length > maxCharacters) throw new Error('Arcfold context metadata exceeds capacity');
+  return material;
+}
+
+export function refreshContext(store, frozen) {
+  const material = structuredClone(frozen);
+  // Refresh display metadata on a copy, without rewriting historical snapshots
+  // or treating a provider's replay envelope as original conversation text.
+  for (const source of [...material.understandings.flatMap(row => row.evidence || []),
+    ...(material.workGoalContext?.sources || [])])
+    source.provenance = evidenceProvenance(source.provenance);
+  if (material.workGoalContext && !workContextCurrent(store, material.workGoalContext)) delete material.workGoalContext;
+  material.understandings = material.understandings.filter(shown => {
+    const current = store.get('understandings', shown.id);
+    const valid = current?.revision === shown.revision && dependenciesCurrent(store, current, material.cutoffSequence);
+    if (!valid) material.coverage.omitted.changed++;
+    return valid;
+  });
+  material.methodCoverage ??= { available: 0, omitted: { capacity: 0, changed: 0 } };
+  material.methods = (material.methods || []).filter(shown => {
+    const current = store.get('methods', shown.id);
+    // Remaining trials are a snapshot, not an entitlement. A quota-only change
+    // must not abort a normal answer; reserve() checks the current count atomically.
+    const valid = ['trial', 'active'].includes(current?.status) && current.revision === shown.revision &&
+      methodContentHash(current) === shown.contentHash && dependenciesCurrent(store, current, material.cutoffSequence);
+    if (!valid) material.methodCoverage.omitted.changed++;
+    return valid;
+  });
+  material.goalCoverage ??= { available: 0, omitted: { capacity: 0, changed: 0 } };
+  const goals = new Map(new GoalService({ business: { storage: store } }).catalog({
+    sessionId: frozen.sessionId, cutoffSequence: frozen.cutoffSequence, inputMessageIds: frozen.inputMessageIds,
+  }).map(goal => [goal.id, goal]));
+  material.goals = (material.goals || []).filter(shown => {
+    const current = goals.get(shown.id);
+    const valid = current && hash(current) === hash(shown) || frozenGoalCurrent(store, shown, material.cutoffSequence);
+    if (!valid) material.goalCoverage.omitted.changed++;
+    return valid;
+  });
+  return material;
+}
+
+export function contextMessage(material) {
+  const contextId = 'arcfold-context-' + hash(material);
+  return { id: contextId, role: 'user', source: { kind: 'arcfold/context', contextId }, content: [{ type: 'text',
+    text: INTRO + JSON.stringify(material) }] };
+}

package/src/deepseek-budget-plugin.mjs

@@ -0,0 +1,58 @@
+import { isAbsolute } from 'node:path';
+import { BudgetLedger } from './budget.mjs';
+import { DeepSeekTransport } from './deepseek-transport.mjs';
+import { getRuntimeGuard } from './runtime-guard.mjs';
+import { nativeRequestIdentity, ownEvidenceDirectory, assertNativeRequestCurrent } from './native-request-authority.mjs';
+export { nativeRequestIdentity } from './native-request-authority.mjs';
+
+export const name = 'arcfold-deepseek-budget';
+export const inject = ['arcfoldBusiness', 'arcfoldBridge', 'sessions', 'llm'];
+export async function apply(ctx, config = {}) {
+  if (!isAbsolute(config.ledgerPath || '') || !isAbsolute(config.artifactDirectory || ''))
+    throw new Error('Explicit absolute paths to the existing ledger and this host evidence directory are required');
+  if (config.provider !== 'deepseek-official') throw new Error('This profile has one explicitly metered DeepSeek route');
+  if (!['limited', 'web-unlimited'].includes(config.scope) || !config.authorizationRef || !Number.isFinite(config.ceilingCny))
+    throw new Error('An explicit existing budget authorization and host scope are required');
+  const lease = await ownEvidenceDirectory(config.artifactDirectory);
+  let ledger, transport;
+  let closing;
+  const close = () => closing ??= (async () => {
+    try { await transport?.close(); }
+    finally { try { ledger?.close(); } finally { await lease.close(); } }
+  })();
+  ctx.effect(() => close, 'close owned transport before the ledger and kernel lock');
+  try {
+    ledger = new BudgetLedger(config.ledgerPath, {
+      ceilingCny: config.ceilingCny, authorizationRef: config.authorizationRef, scope: config.scope,
+      webAuthorization: config.webAuthorization, create: false,
+    });
+    transport = new DeepSeekTransport({ ledger, artifactDirectory: config.artifactDirectory,
+      provider: config.provider, modelPolicies: config.modelPolicies, endpoint: config.endpoint,
+      allowLocalTestEndpoint: config.allowLocalTestEndpoint === true,
+      timeoutMs: config.timeoutMs,
+      requestIdentity: options => nativeRequestIdentity(ctx.arcfoldBusiness, ctx.sessions, options),
+      beforeDispatch: options => {
+        getRuntimeGuard(ctx)?.assertDispatch(options);
+        return assertNativeRequestCurrent(ctx, options);
+      },
+    });
+    // This lock excludes another process using these artifacts. The original
+    // shared ledger may still be used by the independent web host.
+    await transport.recover({ exclusive: true });
+    ctx.on('llm/stream', (options, next) => {
+      if (options.provider !== config.provider) return next();
+      transport.validateInput(options); // before the host can degrade attachments
+      return next();
+    }, { prepend: true });
+    const policies = structuredClone(transport.modelPolicies);
+    for (const policy of Object.values(policies)) {
+      Object.freeze(policy.prices); Object.freeze(policy.reasoningEfforts); Object.freeze(policy);
+    }
+    ctx.provide('arcfoldDeepSeekTransport', Object.freeze({
+      summary: () => ledger.summary(),
+      createTransport: options => transport.createTransport(options),
+      configuration: Object.freeze({ provider: config.provider, endpoint: transport.endpoint,
+        modelPolicies: Object.freeze(policies) }),
+    }));
+  } catch (error) { await close(); throw error; }
+}

package/src/deepseek-provider.mjs

@@ -0,0 +1,57 @@
+import { dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { assertUsableApiKey, LlmError } from '@deepseek-ai/dsh-llm';
+import { catalogModelInfo, registerDeepSeekProvider } from '@deepseek-ai/dsh-llm-deepseek';
+import { resolveAdapterOptions } from '@deepseek-ai/dsh-llm-deepseek-api-key';
+import { launchEnvironmentOf } from '@deepseek-ai/dsh-launch-environment';
+import { inspectDeepSeekPatch } from '../scripts/patch-deepseek-transport.mjs';
+
+const TRANSPORT_CONTRACT = 'deepseek-messages-create-transport-v1';
+
+export const name = 'arcfold-deepseek-provider';
+export const inject = ['llm', 'credentials', 'arcfoldDeepSeekTransport'];
+export function apply(ctx, config = {}) {
+  // Check the loaded function as well as disk: patching a file after an earlier
+  // import must not make the cached original adapter look safe to register.
+  if (registerDeepSeekProvider.transportSeam !== TRANSPORT_CONTRACT)
+    throw new Error('The loaded DeepSeek provider lacks the required transport interface');
+  const packageDir = dirname(fileURLToPath(import.meta.resolve('@deepseek-ai/dsh-llm-deepseek/package.json')));
+  if (inspectDeepSeekPatch(packageDir).state !== 'patched')
+    throw new Error('The exact supported DeepSeek provider patch is required');
+  const service = ctx.arcfoldDeepSeekTransport;
+  const { provider, endpoint, modelPolicies } = service.configuration;
+  if (provider !== 'deepseek-official' || !Object.keys(modelPolicies).length)
+    throw new Error('An explicit metered DeepSeek model catalog is required');
+  if (typeof config.apiKeyRef !== 'string' || !config.apiKeyRef ||
+      !Number.isSafeInteger(config.maxTokens) || config.maxTokens < 1 ||
+      !['off', 'low', 'high', 'max'].includes(config.reasoningEffort))
+    throw new Error('A credential reference, output limit and reasoning effort are required');
+  const models = Object.entries(modelPolicies).map(([id, policy]) => {
+    if (config.maxTokens > (policy.requestMaxTokens ?? policy.maxOutputTokens) ||
+        !policy.reasoningEfforts.includes(config.reasoningEffort))
+      throw new Error('Provider defaults exceed a frozen model accounting policy');
+    return { id, name: id, inputModalities: ['text'], contextWindow: policy.contextWindow,
+      maxTokens: config.maxTokens };
+  });
+  // This deployment generation is fixed. A different route/catalog requires a
+  // plugin reload; the user-selected model remains an ordinary DSH option.
+  const connection = resolveAdapterOptions({
+    baseURL: endpoint.slice(0, -'/v1/messages'.length), apiKeyEnv: config.apiKeyRef,
+    models, maxTokens: config.maxTokens, reasoningEffort: config.reasoningEffort,
+    retryPolicy: { mode: 'normal', maxRetries: 0 },
+  }, launchEnvironmentOf(ctx));
+  for (const model of connection.models) Object.freeze(model);
+  Object.freeze(connection.models); Object.freeze(connection);
+  registerDeepSeekProvider(ctx, provider, {
+    providerName: 'DeepSeek', options: () => connection, connect: async () => connection,
+    createTransport: options => service.createTransport(options),
+    // Resolve secrets only inside the official credential service. They remain
+    // in memory for the request and never enter Arcfold config or evidence.
+    resolveAuth: async current => {
+      const credential = await ctx.credentials.resolve(current.apiKeyEnv);
+      if (!credential) throw new LlmError('Configure the DeepSeek credential in the host Models page', 'MISSING_CREDENTIAL');
+      return { headers: { 'x-api-key': assertUsableApiKey(credential.value, name, current.apiKeyEnv) } };
+    },
+    discoverModels: async route => connection.models.map(model => catalogModelInfo(route, model)),
+  });
+}