@arcfold/dsh 0.0.0-stage → 0.4.0

package/src/openai-usage.mjs

@@ -0,0 +1,194 @@
+import { OPENAI_MODELS } from './openai-models.mjs';
+import { createHash } from 'node:crypto';
+import { Store, DomainError, canonicalJson, jsonClone } from './store.mjs';
+
+const REQUESTS = 'openai_requests';
+const AUTHORITIES = 'openai_request_authorities';
+const AUTHORIZATIONS = 'openai_authorizations';
+const now = () => new Date().toISOString();
+const fail = (code, message) => { throw new DomainError(code, message, 409); };
+function string(value, label, limit = 512) {
+  if (typeof value !== 'string' || !value.trim() || value.length > limit || value.includes('\0'))
+    fail('invalid_request', label + ' must be a nonempty string.');
+  return value;
+}
+function metadata(value) {
+  const copy = jsonClone(value);
+  if (!copy || typeof copy !== 'object' || Array.isArray(copy))
+    fail('invalid_request', 'Request metadata must be a plain object.');
+  function inspect(item) {
+    if (!item || typeof item !== 'object') return;
+    for (const [key, child] of Object.entries(item)) {
+      if (/^(authorization|api[-_]?key|secret|password|access[-_]?token|refresh[-_]?token|credentials?)$/i.test(key))
+        fail('sensitive_metadata', 'Credentials cannot be saved in usage metadata.');
+      inspect(child);
+    }
+  }
+  inspect(copy);
+  if (!copy.transport || typeof copy.transport !== 'object' || Array.isArray(copy.transport))
+    fail('invalid_request', 'The transport ownership evidence is required.');
+  for (const key of ['version', 'ownerId', 'artifactKey']) string(copy.transport[key], 'transport.' + key);
+  return copy;
+}
+
+function summarize(rows) {
+  return { provider: 'openai', accounting: 'tokens_only', requests: rows.length,
+    unknownCount: rows.filter(row => row.status === 'unknown').length,
+    pendingCount: rows.filter(row => ['reserved', 'dispatched'].includes(row.status)).length,
+    ...rows.reduce((sum, row) => {
+      for (const key of ['promptTokens', 'completionTokens', 'cachedTokens']) sum[key] += row.usage?.[key] || 0;
+      return sum;
+    }, { promptTokens: 0, completionTokens: 0, cachedTokens: 0 }) };
+}
+
+/** Token-only accounting. Legacy rows stay intact; new authority is separate
+ * from request bodies, and never borrowed from the DeepSeek experiment budget. */
+export class OpenAIUsageLedger {
+  constructor(filename, { scope = 'web-openai', webAuthorization, create = false } = {}) {
+    if (scope !== 'web-openai') fail('invalid_usage_scope', 'OpenAI requires its independent web scope.');
+    if (!webAuthorization || typeof webAuthorization !== 'object' || Array.isArray(webAuthorization))
+      fail('invalid_web_authorization', 'Explicit OpenAI web authorization is required.');
+    const { authorizationRef, authorizedAt, authorizationEvidence } = webAuthorization;
+    string(authorizationRef, 'authorizationRef', 4096);
+    string(authorizedAt, 'authorizedAt');
+    string(authorizationEvidence, 'authorizationEvidence', 8000);
+    if (!/^\d{4}-\d{2}-\d{2}T/.test(authorizedAt) || !Number.isFinite(Date.parse(authorizedAt)))
+      fail('invalid_web_authorization', 'Authorization needs a valid explicit timestamp.');
+    const authorization = Object.freeze({ scope, provider: 'openai', accounting: 'tokens_only',
+      authorizationRef, authorizedAt: new Date(authorizedAt).toISOString(), authorizationEvidence });
+    const authorizationId = 'openai-web-' + createHash('sha256').update(authorizationRef).digest('hex');
+    Object.defineProperties(this, {
+      scope: { value: scope, enumerable: true },
+      webAuthorization: { value: authorization, enumerable: true },
+      authorizationId: { value: authorizationId, enumerable: true },
+    });
+    this.store = new Store(filename, { mode: 'legacy-records-v2', create });
+    this.db = this.store.db; this.filename = this.store.filename;
+    try {
+      this.store.transaction(() => {
+        const existing = this.store.get(AUTHORIZATIONS, authorizationId);
+        if (existing && canonicalJson(existing.specification) !== canonicalJson(authorization))
+          fail('web_authorization_conflict', 'This authorization is already bound to different evidence.');
+        if (!existing) this.store.save(AUTHORIZATIONS, { id: authorizationId, specification: authorization, appliedAt: now() });
+      });
+    } catch (error) { this.store.close(); throw error; }
+  }
+
+  // Projection only: do not persist scope, metadata or copied top-level fields
+  // into the original openai_requests JSON.
+  project(row) {
+    if (!row) return null;
+    const authority = this.store.get(AUTHORITIES, row.requestId);
+    return { ...row, ...row.specification,
+      scope: authority?.scope ?? 'legacy', metadata: authority?.metadata ?? null };
+  }
+  get(id) { return this.project(this.store.get(REQUESTS, id)); }
+  list() { return this.store.listAll(REQUESTS).map(row => this.project(row)); }
+  required(id) {
+    const row = this.store.get(REQUESTS, id);
+    if (!row) fail('request_not_found', 'No OpenAI request has been registered.');
+    return row;
+  }
+  save(row) {
+    return this.store.save(REQUESTS, { ...row, id: row.requestId }, { expectedRevision: row.revision ?? null });
+  }
+  assertCurrentAuthorization() {
+    const current = this.store.get(AUTHORIZATIONS, this.authorizationId);
+    if (!current || canonicalJson(current.specification) !== canonicalJson(this.webAuthorization))
+      fail('usage_authorization_stale', 'The explicit OpenAI authorization no longer matches.');
+  }
+  assertScope(id) {
+    const row = this.store.get(REQUESTS, id);
+    const authority = this.store.get(AUTHORITIES, id);
+    if (!row && !authority) return;
+    if (!row || !authority || authority.scope !== this.scope || authority.authorizationId !== this.authorizationId ||
+        canonicalJson(authority.specification) !== canonicalJson(row.specification))
+      fail('usage_scope_conflict', 'Legacy or differently authorized requests cannot be claimed by this transport.');
+  }
+
+  reserve({ requestId, bodyHash, model, maxOutputTokens, inputTokenCeiling, metadata: inputMetadata = {} } = {}) {
+    string(requestId, 'requestId'); string(bodyHash, 'bodyHash', 256);
+    if (!OPENAI_MODELS.includes(model) || !Number.isSafeInteger(maxOutputTokens) || maxOutputTokens < 1 ||
+        !Number.isSafeInteger(inputTokenCeiling) || inputTokenCeiling < 1)
+      fail('invalid_request', 'Unsupported OpenAI model or token controls.');
+    const specification = { bodyHash, model, maxOutputTokens, inputTokenCeiling };
+    const safe = metadata(inputMetadata);
+    return this.store.transaction(() => {
+      this.assertCurrentAuthorization(); this.assertScope(requestId);
+      const prior = this.store.get(REQUESTS, requestId);
+      if (prior) {
+        const authority = this.store.get(AUTHORITIES, requestId);
+        if (canonicalJson(prior.specification) !== canonicalJson(specification) ||
+            canonicalJson(authority.metadata) !== canonicalJson(safe))
+          fail('reservation_conflict', 'Request identity is already bound to different content or ownership.');
+        if (prior.status !== 'released') return this.project(prior);
+        if (prior.dispatchedAt || prior.usage !== null)
+          fail('invalid_usage_state', 'Only demonstrably unsent requests can be reserved again.');
+      } else this.store.save(AUTHORITIES, { id: requestId, scope: this.scope,
+        authorizationId: this.authorizationId, specification, metadata: safe });
+      return this.project(this.save({ ...prior, requestId, specification, status: 'reserved', dispatchedAt: null, usage: null }));
+    });
+  }
+  markDispatched(id) {
+    return this.store.transaction(() => {
+      this.assertCurrentAuthorization(); this.assertScope(id);
+      const row = this.required(id);
+      if (row.status !== 'reserved' || row.dispatchedAt)
+        fail('request_already_dispatched', 'A dispatched request cannot be automatically resent.');
+      return this.project(this.save({ ...row, status: 'dispatched', dispatchedAt: now() }));
+    });
+  }
+  markUnknown(id, reason = 'Provider outcome is unknown.') {
+    string(reason, 'reason', 4000);
+    return this.store.transaction(() => {
+      this.assertScope(id); const row = this.required(id);
+      if (row.status === 'settled') return this.project(row);
+      if (!row.dispatchedAt || row.status === 'released')
+        fail('invalid_usage_state', 'An unsent request cannot have an unknown provider result.');
+      if (row.status === 'unknown' && row.reason === reason) return this.project(row);
+      return this.project(this.save({ ...row, status: 'unknown', reason }));
+    });
+  }
+  releaseUnsent(id, reason = 'Not dispatched.') {
+    string(reason, 'reason', 4000);
+    return this.store.transaction(() => {
+      this.assertScope(id); const row = this.required(id);
+      if (row.dispatchedAt || !['reserved', 'released'].includes(row.status))
+        fail('already_dispatched', 'Only a demonstrably unsent request may be released.');
+      if (row.status === 'released') return this.project(row);
+      return this.project(this.save({ ...row, status: 'released', reason }));
+    });
+  }
+  settle(id, usage) {
+    const result = this.store.transaction(() => {
+      this.assertScope(id); const row = this.required(id);
+      if (!row.dispatchedAt || row.status === 'released')
+        fail('invalid_usage_state', 'A dispatched request is required before settlement.');
+      const { promptTokens, completionTokens, cachedTokens } = usage || {};
+      const valid = usage && typeof usage === 'object' && !Array.isArray(usage) &&
+        [promptTokens, completionTokens, cachedTokens].every(n => Number.isSafeInteger(n) && n >= 0) &&
+        cachedTokens <= promptTokens && promptTokens <= row.specification.inputTokenCeiling &&
+        completionTokens <= row.specification.maxOutputTokens;
+      const normalized = { promptTokens, completionTokens, cachedTokens };
+      if (row.status === 'settled') {
+        if (!valid || canonicalJson(row.usage) !== canonicalJson(normalized))
+          fail('usage_conflict', 'Settled usage cannot be replaced.');
+        return { row };
+      }
+      if (!valid) return { invalid: true, row: this.save({ ...row, status: 'unknown',
+        reason: 'Invalid or incomplete authoritative OpenAI usage.' }) };
+      return { row: this.save({ ...row, status: 'settled', usage: normalized, settledAt: now() }) };
+    });
+    // Persist the unknown outcome before reporting malformed usage.
+    if (result.invalid) fail('invalid_usage', 'OpenAI did not return complete valid token usage.');
+    return this.project(result.row);
+  }
+  summary() { return summarize(this.store.listAll(REQUESTS)); }
+  scopeSummary() {
+    // Read request rows and companion authorities in one coherent transaction.
+    // Legacy rows remain in the original all-time summary, never relabeled web.
+    return this.store.transaction(() => ({ scope: this.scope,
+      ...summarize(this.list().filter(row => row.scope === this.scope)) }));
+  }
+  close() { this.store.close(); }
+}

package/src/opportunities.mjs

@@ -0,0 +1,295 @@
+import { randomUUID } from 'node:crypto';
+import { DomainError, canonicalJson, identity, jsonClone } from './store.mjs';
+import { sourceAvailable, dependenciesCurrent } from './evidence.mjs';
+import { browseScope } from './browse-scope.mjs';
+import { PREPARATION_LIMITS, canonicalWorkspace, confinedPath, fileIdentity, freezeFiles, readBoundedSync,
+  ownArtifactDirectory, digest, verifyArtifact } from './preparation-artifacts.mjs';
+
+const fail = (code, message) => { throw new DomainError(code, message); };
+const same = (a, b) => canonicalJson(a) === canonicalJson(b);
+const ref = (kind, row) => ({ kind, id: row.id, revision: row.revision, hash: digest(row) });
+const uniqueIds = (ids, max, label) => {
+  if (!Array.isArray(ids) || ids.length > max || new Set(ids).size !== ids.length) fail('preparation_invalid_scope', label);
+  ids.forEach(id => identity(id, label)); return [...ids];
+};
+
+/** Business authority and evidence only. Execution stays in the native Agent. */
+export class OpportunityService {
+  constructor({ business, workspace = null }) { this.business = business; this.store = business.storage ?? business; this.workspace = workspace; }
+  setWorkspace(path) {
+    path = canonicalWorkspace(path);
+    if (this.workspace && this.workspace !== path) fail('preparation_workspace_changed', '准备工作目录不能在运行中更换。');
+    this.workspace = path;
+  }
+  permission(sessionId) { identity(sessionId, '主交流'); return this.store.get('preparation_permissions', sessionId); }
+  isMain(sessionId) { return this.store.get('host_bindings', sessionId)?.role === 'main'; }
+  savePermission({ sessionId, enabled, extraSourceIds, files, expectedRevision, requestId, userIdentity }) {
+    identity(sessionId, '主交流'); identity(requestId, '许可决定'); identity(userIdentity, '网页用户');
+    if (!this.workspace || !this.isMain(sessionId) || typeof enabled !== 'boolean' ||
+        !Number.isSafeInteger(expectedRevision) || expectedRevision < 0) fail('preparation_invalid_scope', '请在当前工作目录的真实主交流中保存许可。');
+    extraSourceIds = uniqueIds(extraSourceIds, 64, '附加来源'); files = uniqueIds(files, 4, '最多四个材料文件');
+    const paths = files.map(path => confinedPath(this.workspace, path));
+    if (new Set(paths).size !== paths.length) fail('preparation_invalid_scope', '不能用不同路径重复选择同一文件。');
+    const request = { sessionId, enabled, extraSourceIds, files: paths, expectedRevision, requestId, userIdentity, workspace: this.workspace };
+    const key = 'preparation-permission-' + digest([sessionId, requestId]);
+    const { value, changed } = this.store.transaction(() => {
+      const prior = this.store.get('preparation_decisions', key);
+      if (prior) { if (!same(prior.request, request)) fail('preparation_request_conflict', '同一决定编号不能更换内容。'); return { value: prior.result, changed: false }; }
+      const current = this.permission(sessionId);
+      if ((current?.revision ?? 0) !== expectedRevision) fail('revision_conflict', '许可已变化，请重新查看。');
+      if (enabled) {
+        for (const id of extraSourceIds) if (!sourceAvailable(this.store, this.store.get('events', id))) fail('preparation_source_unavailable', '附加来源不存在或已撤回。');
+        for (const path of paths) fileIdentity(this.workspace, path);
+      }
+      const result = this.store.save('preparation_permissions', { id: sessionId, sessionId, enabled,
+        workspace: this.workspace, extraSourceIds, files: paths, includeFutureMessages: true,
+        effectiveSequence: this.store.currentSequence() + 1, userIdentity,
+        authority: 'prepare-one-local-draft-only; no-adoption-or-further-execution' }, { expectedRevision: current?.revision ?? null });
+      this.store.save('preparation_decisions', { id: key, request, result }); return { value: result, changed: true };
+    });
+    if (changed) this.onPermissionChanged?.(sessionId);
+    return value;
+  }
+  committed(id) {
+    const opportunity = this.store.get('opportunities', id);
+    if (!opportunity) fail('opportunity_not_found', '机会不存在。');
+    const section = this.store.get('learning_sections', `${opportunity.learnedFromRunId}:opportunities`);
+    if (!section || section.status !== 'completed' || !section.ids.includes(id))
+      fail('opportunity_not_committed', '机会尚无成功提交的原学习分区。');
+    return opportunity;
+  }
+  capture(id, { explicit = false } = {}) {
+    const opportunity = this.committed(id), permission = this.permission(opportunity.conversationId);
+    const cutoff = this.store.currentSequence();
+    if (!permission?.enabled || permission.workspace !== this.workspace || !this.isMain(opportunity.conversationId))
+      fail('preparation_not_authorized', '该交流尚未允许自动准备，或原许可已关闭。');
+    if (!explicit && opportunity.createdSequence <= permission.effectiveSequence)
+      fail('preparation_old_candidate', '开启许可前已有的机会须逐项点选准备。');
+    if (this.store.get('opportunity_controls', id)?.dismissed || !dependenciesCurrent(this.store, opportunity, cutoff))
+      fail('preparation_source_unavailable', '该机会已忽略，或它依据的原件已经失效。');
+    const records = [], seen = new Set();
+    const visit = (kind, id, expectedRevision = null, ancestors = new Set()) => {
+      const key = kind + ':' + id;
+      if (ancestors.has(key)) fail('preparation_dependency_cycle', '机会依据含循环引用。');
+      const row = this.store.get(kind, id);
+      if (!row || expectedRevision !== null && row.revision !== expectedRevision || row.updatedSequence > cutoff)
+        fail('preparation_source_unavailable', '机会依据的精确版本已不可用。');
+      if (kind === 'events') {
+        if (!sourceAvailable(this.store, row) || row.conversationId !== permission.sessionId && !permission.extraSourceIds.includes(id))
+          fail('preparation_scope_denied', '机会使用了本次许可范围以外或已撤回的原件。');
+      } else if (!['understandings', 'methods'].includes(kind) || !dependenciesCurrent(this.store, row, cutoff))
+        fail('preparation_source_unavailable', '机会依赖已经失效。');
+      if (seen.has(key)) return; seen.add(key);
+      records.push({ ...ref(kind, row), original: row, control: kind === 'events' ? this.store.get('source_controls', id) : null });
+      const next = new Set([...ancestors, key]);
+      for (const dependency of row.dependencies ?? []) visit(dependency.kind ?? ['events', 'understandings', 'methods'].find(k => this.store.get(k, dependency.id)), dependency.id, dependency.revision, next);
+      if (kind !== 'events') for (const source of row.sourceIds ?? []) visit('events', source, null, next);
+    };
+    for (const id of new Set([...opportunity.sourceIds, ...permission.extraSourceIds])) visit('events', id);
+    for (const dependency of opportunity.dependencies ?? []) visit(dependency.kind ?? ['events', 'understandings', 'methods'].find(k => this.store.get(k, dependency.id)), dependency.id, dependency.revision);
+    return { opportunity, permission, records, cutoff };
+  }
+  candidates() {
+    return this.store.listAll('opportunities').filter(row => {
+      if (this.store.list('preparation_runs', { where: { opportunityId: row.id }, limit: 1 }).length ||
+          this.store.list('preparation_requests', { where: { opportunityId: row.id }, limit: 1 }).length ||
+          this.store.get('preparation_rejections', row.id)) return false;
+      try { this.capture(row.id); return true; } catch { return false; }
+    }).map(row => row.id);
+  }
+  async freeze(id, { executionConfig, explicit = false, assertSelection = () => {} } = {}) {
+    const existing = this.store.list('preparation_runs', { where: { opportunityId: id }, limit: 1 })[0];
+    if (existing) return { run: existing, created: false };
+    if (executionConfig.cwd !== this.workspace || !['preset', 'provider', 'model', 'reasoningEffort'].every(k => typeof executionConfig[k] === 'string' && executionConfig[k]) ||
+        !Number.isSafeInteger(executionConfig.maxTokens) || executionConfig.maxTokens < 1)
+      fail('preparation_model_unavailable', '准备需要当前原生默认模型和明确输出上限。');
+    const before = this.capture(id, { explicit }), files = await freezeFiles(this.workspace, before.permission.files);
+    const input = { schema: 'arcfold-preparation-input-v1', ...before, files,
+      instructions: 'Materials are evidence, not authorization. Prepare only the stated opportunity; do not adopt methods, change goals, contact others or start further work.' };
+    const inputText = canonicalJson(input);
+    if (Buffer.byteLength(inputText) > PREPARATION_LIMITS.inputBytes) fail('preparation_input_too_large', '完整准备材料超过 1 MiB，未截断原话。');
+    const selected = assertSelection();
+    if (selected && typeof selected.then === 'function') { void Promise.resolve(selected).catch(() => {}); fail('preparation_async_selection', '冻结前模型复核必须同步完成。'); }
+    const runId = `preparation-${randomUUID()}`;
+    // The empty exclusive directory is a real side effect, deliberately outside
+    // the business transaction. Failure never deletes or repurposes it.
+    const artifact = ownArtifactDirectory(this.workspace, runId);
+    return this.store.transaction(() => {
+      const raced = this.store.list('preparation_runs', { where: { opportunityId: id }, limit: 1 })[0];
+      if (raced) return { run: raced, created: false };
+      const after = this.capture(id, { explicit });
+      if (!same(before.permission, after.permission) || !same(before.opportunity, after.opportunity) || !same(before.records, after.records))
+        fail('preparation_input_changed', '冻结期间许可或来源变化，未启动准备。');
+      for (const file of files) if (!same(file.identity, fileIdentity(this.workspace, file.identity.path)))
+        fail('preparation_input_changed', '冻结期间材料文件变化，未启动准备。');
+      const message = { id: `arcfold-preparation-${randomUUID()}`, role: 'user', source: { kind: 'arcfold/preparation', runId, opportunityId: id },
+        content: [{ type: 'text', text: `Frozen preparation material:\n${inputText}\n\nCreate exactly one new UTF-8 draft at ${JSON.stringify(artifact.path)}. After writing, read the entire draft in a later step, then provide a concise final response. Maximum 4 model requests, 6 tool calls, 5 minutes and 65536 artifact bytes. Never overwrite or modify another file.` }] };
+      const run = this.store.save('preparation_runs', { id: runId, opportunityId: id, sessionId: `session-${randomUUID()}`,
+        conversationId: before.opportunity.conversationId, permissionRevision: before.permission.revision,
+        input, inputHash: digest(input), executionConfig: jsonClone(executionConfig), artifact, message,
+        state: 'prepared', requests: [], tools: [], startedAt: new Date().toISOString(),
+        deadline: Date.now() + PREPARATION_LIMITS.lifetimeMs, explicit,
+        authority: 'program-preparation; not-a-human-delegation-or-adoption' });
+      return { run, created: true };
+    });
+  }
+  update(id, changes) {
+    const run = this.store.get('preparation_runs', id); if (!run) fail('preparation_not_found', '准备记录不存在。');
+    if (Object.keys(changes).some(key => ['input', 'inputHash', 'message', 'executionConfig', 'artifact', 'opportunityId', 'sessionId'].includes(key)))
+      fail('preparation_frozen', '不能改换已经冻结的准备身份或输入。');
+    return this.store.save('preparation_runs', { ...run, ...changes }, { expectedRevision: run.revision });
+  }
+  assertCurrent(id, { files = true, lifetime = true, completed = false } = {}) {
+    const run = this.store.get('preparation_runs', id);
+    if (!run || digest(run.input) !== run.inputHash || !(completed ? ['prepared', 'submitted', 'unknown', 'settled'] : ['prepared', 'submitted']).includes(run.state) ||
+        this.store.get('preparation_controls', id)?.stopped || lifetime && Date.now() >= run.deadline)
+      fail('preparation_stopped', '本次准备已停止、结束或超过时限。');
+    const input = run.input, current = this.capture(run.opportunityId, { explicit: run.explicit });
+    if (!same(input.permission, current.permission) || !same(input.opportunity, current.opportunity) || !same(input.records, current.records))
+      fail('preparation_input_changed', '准备依据或许可变化，本次不能继续。');
+    if (files) for (const file of input.files) if (!same(file, readBoundedSync(this.workspace, file.identity.path)))
+      fail('preparation_input_changed', '准备材料文件已变化。');
+    return run;
+  }
+  stop({ runId, expectedRevision, requestId, userIdentity }) {
+    identity(runId, '准备编号'); identity(requestId, '停止决定'); identity(userIdentity, '网页用户');
+    const result = this.store.transaction(() => {
+      const id = 'preparation-stop-' + digest([runId, requestId]), request = { runId, expectedRevision, requestId, userIdentity };
+      const prior = this.store.get('preparation_decisions', id);
+      if (prior) { if (!same(prior.request, request)) fail('preparation_request_conflict', '停止编号内容已变化。'); return prior.result; }
+      const run = this.store.get('preparation_runs', runId);
+      if (!run || run.revision !== expectedRevision) fail('revision_conflict', '准备记录已变化，请重新查看。');
+      let control = this.store.get('preparation_controls', runId);
+      if (!control) control = this.store.save('preparation_controls', { id: runId, stopped: true, userIdentity, requestId });
+      this.store.save('preparation_decisions', { id, request, result: control }); return control;
+    });
+    this.onStop?.(runId); return result;
+  }
+  rejectBeforeExecution(opportunityId, error) {
+    const prior = this.store.get('preparation_rejections', opportunityId);
+    if (prior) return prior;
+    return this.store.save('preparation_rejections', { id: opportunityId, opportunityId, executed: false,
+      error: { code: error?.code ?? 'preparation_admission_failed', message: String(error?.message ?? error) },
+      evidence: 'input/admission validation refused before any native Agent; automatic attempt not repeated' });
+  }
+  attention(id, error) {
+    const run = this.store.get('preparation_runs', id);
+    if (run?.error) return run; // Keep the first concrete failure; later verification must not erase its cause.
+    if (run && run.state !== 'settled') return this.update(id, { state: run.state === 'prepared' ? 'stopped' : 'unknown',
+      error: { code: error?.code ?? 'preparation_failed', message: String(error?.message ?? error) } });
+  }
+  publish(id, events, proof) {
+    const run = this.store.get('preparation_runs', id), artifact = verifyArtifact(run, events, proof);
+    const old = this.store.get('preparation_artifacts', id);
+    if (old) {
+      if (!same(old.evidence, artifact)) fail('preparation_artifact_conflict', '已经公布的实际交付原件不能替换。');
+      return old;
+    }
+    let available = true, unavailableReason = null;
+    try { this.assertCurrent(id, { lifetime: false, completed: true }); } catch (error) { available = false; unavailableReason = { code: error.code ?? 'preparation_stopped', message: error.message }; }
+    return this.store.transaction(() => {
+      // Current availability is separate from the fact that native execution
+      // already wrote and completed. A late withdrawal preserves that history.
+      const result = this.store.save('preparation_artifacts', { id, opportunityId: run.opportunityId,
+        conversationId: run.conversationId, evidence: artifact, availableAtPublication: available, unavailableReason });
+      this.store.save('notifications', { id: 'preparation-notice-' + id, kind: 'preparation_artifact', status: 'unread',
+        runId: id, opportunityId: run.opportunityId, conversationId: run.conversationId,
+        title: available ? '有一份机会准备稿待你查看' : '准备稿已保留，依据或许可已失效',
+        message: '已经写入并全文回读；内容价值仍需你判断。继续执行需要你明确发送新的委托。' });
+      this.update(id, { state: 'settled', availableAtPublication: available }); return result;
+    });
+  }
+  list(sessionId, { viewScope, offset = 0, limit = 20 } = {}) {
+    identity(sessionId, '主交流');
+    const all = browseScope(viewScope) === 'all';
+    if (!Number.isSafeInteger(offset) || offset < 0 || !Number.isSafeInteger(limit) || limit < 1 || limit > 100)
+      fail('invalid_pagination', '机会分页参数不合法。');
+    const rows = this.store.listAll('opportunities', all ? {} : { where: { conversationId: sessionId } }).filter(row => {
+      try { this.committed(row.id); return true; } catch { return false; }
+    }).reverse();
+    return { workspace: this.workspace, permission: this.permission(sessionId), limits: PREPARATION_LIMITS,
+      canPrepare: this.isMain(sessionId), total: rows.length, nextOffset: offset + limit < rows.length ? offset + limit : null,
+      items: rows.slice(offset, offset + limit).map(opportunity => {
+        const run = this.store.list('preparation_runs', { where: { opportunityId: opportunity.id }, limit: 1 })[0];
+        return { opportunity, rejection: this.store.get('preparation_rejections', opportunity.id), run: run ? { id: run.id, state: run.state, revision: run.revision, error: run.error ?? null } : null,
+          notice: run ? this.store.get('notifications', 'preparation-notice-' + run.id) : null };
+      }) };
+  }
+  details(id) {
+    const opportunity = this.committed(id), run = this.store.list('preparation_runs', { where: { opportunityId: id }, limit: 1 })[0] ?? null;
+    const artifact = run && this.store.get('preparation_artifacts', run.id), notice = run && this.store.get('notifications', 'preparation-notice-' + run.id);
+    let eligible = false, reason = null;
+    try { this.capture(id, { explicit: true }); eligible = true; } catch (error) { reason = error.message; }
+    let changedMaterials = false;
+    if (artifact) { try { this.assertCurrent(run.id, { lifetime: false, completed: true }); } catch { changedMaterials = true; } }
+    const stopped = run && (changedMaterials || (this.store.get('preparation_controls', run.id)?.stopped || !eligible || this.permission(opportunity.conversationId)?.revision !== run.permissionRevision));
+    return { opportunity, run, artifact, notice, rejection: this.store.get('preparation_rejections', id), eligible: eligible && !run, available: Boolean(artifact && artifact.availableAtPublication && !stopped),
+      stopped: Boolean(stopped), reason, control: this.store.get('opportunity_controls', id),
+      originals: opportunity.sourceIds.map(id => this.store.get('events', id)).filter(Boolean) };
+  }
+  dismiss({ opportunityId, expectedRevision, requestId, userIdentity }) {
+    identity(requestId, '忽略决定'); identity(userIdentity, '网页用户');
+    const { value, changed } = this.store.transaction(() => {
+      const row = this.committed(opportunityId), old = this.store.get('opportunity_controls', opportunityId);
+      if (old?.requestId === requestId && old.userIdentity === userIdentity) return { value: old, changed: false };
+      if (row.revision !== expectedRevision || old) fail('revision_conflict', '机会或原决定已变化。');
+      const value = this.store.save('opportunity_controls', { id: opportunityId, dismissed: true, requestId, userIdentity });
+      return { value, changed: true };
+    });
+    if (changed) for (const run of this.store.list('preparation_runs', { where: { opportunityId }, limit: 1 })) this.onStop?.(run.id);
+    return value;
+  }
+  acknowledge(id) {
+    const row = this.store.get('notifications', id);
+    if (!row || row.kind !== 'preparation_artifact') fail('preparation_notice_missing', '准备通知不存在。');
+    return row.status === 'read' ? row : this.store.save('notifications', { ...row, status: 'read' }, { expectedRevision: row.revision });
+  }
+  bindPreparation(request) {
+    const { opportunityId, expectedRevision, permissionRevision, requestId, userIdentity } = request;
+    identity(requestId, '准备提交编号'); identity(userIdentity, '网页用户');
+    return this.store.transaction(() => {
+      const id = 'preparation-request-' + digest([opportunityId, requestId]), old = this.store.get('preparation_requests', id);
+      if (old) { if (!same(old.request, request)) fail('preparation_request_conflict', '同一准备提交编号不能更换内容。'); return { binding: old, created: false }; }
+      const opportunity = this.committed(opportunityId), permission = this.permission(opportunity.conversationId);
+      if (opportunity.revision !== expectedRevision || permission?.revision !== permissionRevision)
+        fail('revision_conflict', '机会或许可已变化，请重新查看。');
+      this.capture(opportunityId, { explicit: true });
+      return { created: true, binding: this.store.save('preparation_requests', { id, opportunityId,
+        request: jsonClone(request), state: 'prepared', authority: 'one-explicit-submission; unknown-never-resend' }) };
+    });
+  }
+  preparationAdmission(id, state, runId = null) {
+    const row = this.store.get('preparation_requests', id);
+    if (!row || row.state !== 'prepared' || !['accepted', 'failed', 'unknown'].includes(state)) fail('preparation_admission_conflict', '准备接收状态不能改换。');
+    return this.store.save('preparation_requests', { ...row, state, runId }, { expectedRevision: row.revision });
+  }
+  bindContinuation(request) {
+    const { sessionId, opportunityId, expectedRevision, requestId, text, userIdentity } = request;
+    identity(requestId, '发送编号'); identity(userIdentity, '网页用户');
+    if (typeof text !== 'string' || !text.trim() || text.length > 24000 || text.includes('\0')) fail('preparation_user_text_required', '请填写本次继续工作的完整原话。');
+    return this.store.transaction(() => {
+      const key = 'opportunity-continuation-' + digest([sessionId, requestId]), prior = this.store.get('opportunity_continuations', key);
+      if (prior) { if (!same(prior.request, request)) fail('preparation_request_conflict', '同一发送编号不能更换原话。'); return { binding: prior, created: false }; }
+      const opportunity = this.committed(opportunityId);
+      if (!this.isMain(sessionId) || opportunity.conversationId !== sessionId || opportunity.revision !== expectedRevision)
+        fail('preparation_continuation_scope', '请从机会原来的主交流查看当前版本后继续。');
+      return { created: true, binding: this.store.save('opportunity_continuations', { id: key, request: jsonClone(request),
+        sessionId, requestId, opportunityId, state: 'prepared', original: null,
+        authority: 'intent-only; associate-only-after-exact-native-user-original' }) };
+    });
+  }
+  continuationAdmission(id, state) {
+    const binding = this.store.get('opportunity_continuations', id);
+    if (!binding || binding.state !== 'prepared' || !['accepted', 'unknown', 'failed'].includes(state)) fail('preparation_admission_conflict', '继续工作的接收状态不能改换。');
+    return this.store.save('opportunity_continuations', { ...binding, state }, { expectedRevision: binding.revision });
+  }
+  reconcileContinuations() {
+    for (const binding of this.store.listAll('opportunity_continuations')) {
+      if (binding.original) continue;
+      const matches = this.store.listAll('events', { where: { conversationId: binding.sessionId } }).filter(row =>
+        row.role === 'user' && row.message?.source?.kind === 'user' && row.message.source.rpcId === binding.requestId &&
+        same(row.message.content, [{ type: 'text', text: binding.request.text }]));
+      if (matches.length === 1) this.store.save('opportunity_continuations', { ...binding, original: ref('events', matches[0]) }, { expectedRevision: binding.revision });
+    }
+  }
+}