dsh-bettertaskgraphs 0.2.3 → 0.3.0-rc.11

package/README.md

@@ -1,5 +1,9 @@
 # dsh-bettertaskgraphs
 
+当前候选版本为 `0.3.0-rc.11`。独立运行保留动态上下文开发前 `0.2.3` 的五个工具、初始指引与事务语义；通用扩展接口供其他插件登记工作流和会话策略。动态上下文装配、修改审批及其提示词由扩展插件实现。
+
+配套扩展：[dsh-dynamic-context](https://github.com/oldcitynight/dsh-dynamic-context)。本候选的验证范围与复现方式见 [VALIDATION.md](VALIDATION.md)。
+
 DeepSeek Harness 的事务型任务图 Bundle，包含模型侧的任务图工具和会话输入区的任务图面板。支持嵌套容器、条件分支、单一活动叶节点，以及基于 DSH 会话证据的提交与对账。
 
 面板的事务关系区列出进入条件及对应任务状态。点击「全屏」后，沿连线从左往右阅读。可沿同一条前置链推出的重复条件会合并显示。独立的跨列前置留在目标卡片的进入条件中，并在卡片上标记数量。点击节点可切换所选事务，按 Esc 返回会话。
@@ -18,7 +22,7 @@ npm test
 npm run pack:bundle
 ```
 
-`build` 从前端源码生成可由 DSH Web 加载的 `client.js`。`check` 校验生成物与源码一致，`pack:bundle` 会重新构建前端并生成 `dist/dsh-bettertaskgraphs-0.2.3.tgz`。包内包含服务端模块、Web 构建产物、对应源码和构建脚本，以及 Bundle 配置补丁。
+`build` 从前端源码生成可由 DSH Web 加载的 `client.js`。`check` 校验生成物与源码一致，`pack:bundle` 会重新构建前端并生成 `dist/dsh-bettertaskgraphs-0.3.0-rc.11.tgz`。包内包含服务端模块、Web 构建产物、对应源码和构建脚本，以及 Bundle 配置补丁。
 
 ## 安装到独立 Web profile
 
@@ -26,7 +30,7 @@ npm run pack:bundle
 
 ```sh
 dsh --profile bettertaskgraphs --from-default-profile web --dump-config
-dsh plugin --profile bettertaskgraphs add "$PWD/dist/dsh-bettertaskgraphs-0.2.3.tgz"
+dsh plugin --profile bettertaskgraphs add "$PWD/dist/dsh-bettertaskgraphs-0.3.0-rc.11.tgz"
 dsh --profile bettertaskgraphs --dump-config
 dsh --profile bettertaskgraphs
 ```
@@ -49,6 +53,45 @@ Bundle 默认将会话创建时的工作目录作为项目根，账本位于根
 
 [DSH 官方 Bundle 打包文档](https://github.com/deepseek-ai/deepseek-harness/blob/dsh-v0.2.1-rc.5/docs/user/develop/basic/publish.zh.md)
 
+## 插件间联动 API v1
+
+公共模块导出为 `dsh-bettertaskgraphs/core`、`/store`、`/host`、`/interop`。消费者无需再访问包内私有路径。`ctx.transactionGraph.workflowContract` 固定为 `dsh-taskgraph-workflow-v1`。
+
+宿主插件通过 `registerWorkflowProvider(adapter)` 登记一个联动工作流，返回取消登记函数。adapter 必须给出 contract、version:1、kind、workflowId、真实 projectRoot、operations、authorize、read、execute；subscribe 可发布已提交后的变更通知。重复标识拒绝覆盖，取消登记会取消该入口发起的在途执行。
+
+控制器端接口：
+
+```js
+const graph = ctx.transactionGraph
+const ref = { kind: 'dynamic-context', workflowId: 'project-workflow' }
+const workflows = graph.listWorkflows(controllerAgent)
+const snapshot = graph.readWorkflow(controllerAgent, ref)
+const result = await graph.dispatchWorkflow(controllerAgent, ref, 'run_next', {
+  expectedRevision: snapshot.revision,
+}, signal)
+const unsubscribe = graph.subscribeWorkflows(notice => {
+  // notice 只含 contract、kind、workflowId、type、revision；重新读取提交后的状态。
+})
+```
+
+动态上下文提供 `submit`、`status`、`run_next`；durable 模式另提供 `pause`、`resume`、`reconcile`、`maintenance`。submit 的 request 为 `{proposal:{taskGraph,contextGraph}}`，两张图仍由动态上下文的一个 CAS 文档原子提交。read 返回同一真实任务图、contextVersion、报告引用和执行状态；不返回原始上下文和报告正文。恢复/对账仍须精确 revision、attempt 与检查点票据，不能通过联动接口绕过。
+
+入口只接受当前注册的真实控制器、原始与当前工作目录均在本项目内；worker 不能提升成控制器。参数由对应 provider 严格校验，来源 Agent 和取消信号由宿主绑定，模型参数不能替换。通知监听器异常不会回滚已提交状态。
+
+联动工作流和原生事务图有明确的存储域。现有 `transaction_graph_*` 工具及 Web 面板仍读取其原有会话账本，不镜像动态图，不把模型报告转成正式事务成功。联动 API 也不会自动完成 Goal 或接管 Web 聊天入口。
+
+## 通用会话扩展接口
+
+`extensionContract` 为 `dsh-taskgraph-session-extension-v1`，公共入口为 `/extensions`。
+
+- `registerSessionPolicy({id, allowClassic(agent)})` 返回注销函数。无策略时原有工具与指引保持启用；扩展可对单个会话禁止经典图写入与提示，工具可见性由扩展的会话作用域控制。
+- `createExtensionStore(options)` 创建通用 CAS 存储，不实现扩展业务。默认容量保持原值，调用方可以显式选择容量。
+- `inspectGraphPresence(agent)` 根据原生持久化日志和提交收据，区分从未创建、创建待提交、已存在、提交后丢失/损坏以及不确定的创建记录。缺失历史图不能当作空白会话重建。
+
+独立图依然由五个原有工具推进。rc.11 移除了早期候选中的 `workflowOnly`、`revision` 配置、`transaction_graph_revise` 和 `/revision*` 导出；使用这些早期候选接口的宿主需要调整为扩展插件。结构性 `REVISED` 事件仍可由受信扩展使用，旧已提交 V4 事件可读；遗留待提交修订不会跳过原扩展审批自动落盘。
+
+`artifactProof` 默认上限恢复为 16 MiB；扩展可通过第四参数 `{maxBytes}` 明确扩大自身证据范围，不改变独立任务图默认值。
+
 ## 许可证
 
 Copyright (C) 2026 oldcitynight and contributors.

package/VALIDATION.md

@@ -0,0 +1,22 @@
+# Candidate validation: 0.3.0-rc.11
+
+Validated on 2026-11-13 with Node.js 24.22.2 and DSH 0.2.1-rc.5.
+
+- 103 task-graph tests passed with dynamic-context imports forbidden.
+- A real DSH service mounted independently, exposing the original five tools and guidance.
+- Tool definitions and work policy match the 0.2.3 baseline except for the file header; initial guidance is byte-identical.
+- Client source/build parity passed.
+- The packaged service mounted after an isolated offline installation.
+- The companion dynamic-context candidate passed 348 source tests and 347 installed tests. One upstream-source comparison was skipped only in the installed package; it passed with the upstream source present.
+
+These checks establish the tested program boundaries and fake-backend behavior. They do not certify real-model planning quality, browser interaction, or npm publication. The prior experiment records and frozen artifacts were retained unchanged.
+
+To reproduce this repository's checks:
+
+```sh
+npm ci
+npm test
+npm pack --dry-run
+```
+
+The base package has no dependency on dynamic context. Optional extension logic must register through the public workflow/session interfaces and retain its own model prompts and approval policy.

package/client.js

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: GPL-3.0-only
-// Corresponding source: https://github.com/oldcitynight/dsh-bettertaskgraphs/tree/v0.2.3
+// Corresponding source: https://github.com/oldcitynight/dsh-bettertaskgraphs/tree/v0.3.0-rc.11
 // Generated by scripts/build-client.mjs.
 window.__ModuleLoader__.load({id:"dsh-bettertaskgraphs",factory(require){
 // SPDX-License-Identifier: GPL-3.0-only

package/core.mjs

@@ -266,6 +266,62 @@ function finishLeaf(state, data) {
   activate(state, active.nodeId, data.outcome, data.selectedCase)
 }
 
+/** Normalize a new plan while retaining durable identities and all started work. */
+export function revisedPlan(document, definition) {
+  validateDocument(document)
+  const previous = document.state.plan, plan = normalizePlan(definition, { enableSwitch: previous.enableSwitch })
+  const old = new Map(previous.nodes.map(node => [node.key, node]))
+  const historical = new Set(document.events.flatMap(event => event.data.plan?.nodes.map(node => node.key) ?? []))
+  for (const node of plan.nodes) if (!old.has(node.key) && historical.has(node.key)) fail('RETIRED_TASK_KEY_REUSE')
+  const ids = new Map(plan.nodes.map(node => [node.id, old.get(node.key)?.id ?? node.id]))
+  plan.id = previous.id
+  plan.nodes = plan.nodes.map(node => ({ ...node, id: ids.get(node.id), parent: ids.get(node.parent) ?? null }))
+  plan.edges = plan.edges.map(edge => {
+    const result = { ...edge, from: ids.get(edge.from), to: ids.get(edge.to) }
+    const match = previous.edges.find(row => canonical({ ...row, id: null }) === canonical({ ...result, id: null }))
+    return match ? copy(match) : result
+  })
+  validateRevisionTransition(document.state, plan)
+  return plan
+}
+export function validateRevisionTransition(state, plan) {
+  if (state.active) fail('REVISION_REQUIRES_NO_ACTIVE_ATTEMPT')
+  validatePlan(plan)
+  if (state.plan.id !== plan.id || state.plan.enableSwitch !== plan.enableSwitch) fail('REVISION_GRAPH_IDENTITY_CHANGED')
+  if (canonical(state.plan.edges.filter(edge => edge.kind !== 'prerequisite')) !== canonical(plan.edges.filter(edge => edge.kind !== 'prerequisite')))
+    fail('REVISION_BRANCH_POLICY_IMMUTABLE')
+  const next = new Map(plan.nodes.map(node => [node.id, node]))
+  for (const node of state.plan.nodes) {
+    const leaf = state.leaves[node.id]
+    if (node.parent === null && (!next.has(node.id)
+        || canonical({ ...next.get(node.id), label: node.label }) !== canonical(node))) fail('REVISION_ROOT_IMMUTABLE')
+    if (leaf && !['PENDING', 'INACTIVE'].includes(leaf.status)) {
+      if (canonical(next.get(node.id)) !== canonical(node)) fail('STARTED_TASK_IMMUTABLE')
+      const incoming = p => p.edges.filter(edge => edge.to === node.id)
+      if (canonical(incoming(state.plan)) !== canonical(incoming(plan))) fail('STARTED_TASK_PREREQUISITES_IMMUTABLE')
+    }
+    if (next.has(node.id) && (next.get(node.id).key !== node.key || next.get(node.id).kind !== node.kind)) fail('REVISION_TASK_IDENTITY_CHANGED')
+  }
+}
+function reviseState(state, data) {
+  object(data, ['plan', 'review'], 'revision event')
+  validateRevisionTransition(state, data.plan)
+  const review = data.review
+  if (!review || review.verdict !== 'APPROVE' || review.baseRevision !== state.revision
+      || review.planChecksum !== digest(data.plan) || !/^[a-f0-9]{64}$/.test(review.proposalHash ?? '')
+      || typeof review.updaterRunId !== 'string' || typeof review.reviewerRunId !== 'string'
+      || !review.updaterRunId || !review.reviewerRunId || review.updaterRunId === review.reviewerRunId) fail('INDEPENDENT_REVISION_REVIEW_REQUIRED')
+  const incoming = new Set(data.plan.edges.filter(edge => edge.kind !== 'prerequisite').map(edge => edge.to))
+  state.leaves = Object.fromEntries(data.plan.nodes.filter(node => node.kind === 'leaf').map(node => [node.id,
+    state.leaves[node.id] ?? { status: incoming.has(node.id) ? 'INACTIVE' : 'PENDING', evidence: [], acceptance: 'UNVERIFIED_REFERENCE' }]))
+  state.plan = copy(data.plan)
+  // A newly added predeclared route may originate in an already finished leaf.
+  for (const [id, leaf] of Object.entries(state.leaves)) {
+    if (leaf.status === 'COMPLETE' || leaf.status === 'INCOMPLETE') activate(state, id,
+      leaf.status === 'COMPLETE' ? 'complete' : 'incomplete', leaf.selectedCase ?? null)
+  }
+}
+
 // Deterministic replay is authoritative; snapshots are checked against it.
 export function replay(events) {
   if (!Array.isArray(events) || !events.length || events.length > LIMITS.events) fail('EVENT_LIMIT')
@@ -285,6 +341,8 @@ export function replay(events) {
       const leaves = Object.fromEntries(plan.nodes.filter(node => node.kind === 'leaf').map(node => [node.id,
         { status: incoming.has(node.id) ? 'INACTIVE' : 'PENDING', evidence: [], acceptance: 'UNVERIFIED_REFERENCE' }]))
       state = { schema: 1, revision: 0, plan, leaves, active: null, operations: [] }
+    } else if (event.type === 'REVISED') {
+      reviseState(state, event.data)
     } else if (event.type === 'BEGUN') {
       object(event.data, ['nodeId', 'attemptId', 'owner'], 'begin event')
       if (state.active || !legalNext(state).some(node => node.id === event.data.nodeId)
@@ -381,6 +439,13 @@ export class TransactionGraph {
       return { plan: normalizePlan(definition, { enableSwitch: this.enableSwitch, id: this.id }) }
     }); return view(result, this.owner)
   }
+  revise({ expectedRevision, operationId, plan, review }) {
+    const result = this.mutate(expectedRevision, operationId, 'REVISED', state => {
+      if (!state) fail('NO_PLAN')
+      validateRevisionTransition(state, plan)
+      return { plan: copy(plan), review: copy(review) }
+    }); return view(result, this.owner)
+  }
   begin({ expectedRevision, operationId, choice }) {
     const result = this.mutate(expectedRevision, operationId, 'BEGUN', state => {
       if (!state) fail('NO_PLAN')

package/extensions.mjs

@@ -0,0 +1,24 @@
+// SPDX-License-Identifier: GPL-3.0-only
+import { GraphError } from './core.mjs'
+
+export const EXTENSION_CONTRACT = 'dsh-taskgraph-session-extension-v1'
+
+/** Optional host extensions may suppress the classic interface per session.
+ * Policy, interaction and extension data belong to the registering plugin.
+ * With no provider, the original classic interface is unchanged.
+ */
+export class SessionPolicies {
+  constructor() { this.providers = new Map(); this.closed = false }
+  register({ id, allowClassic }) {
+    if (this.closed || typeof id !== 'string' || !/^[a-z][a-z0-9_-]{0,79}$/.test(id)
+        || typeof allowClassic !== 'function' || this.providers.has(id)) throw new GraphError('SESSION_EXTENSION_CONTRACT_REQUIRED')
+    const entry = { allowClassic }; this.providers.set(id, entry)
+    return () => { if (this.providers.get(id) === entry) this.providers.delete(id) }
+  }
+  allowClassic(agent) {
+    if (this.closed) return false
+    for (const provider of this.providers.values()) if (provider.allowClassic(agent) !== true) return false
+    return true
+  }
+  close() { this.closed = true; this.providers.clear() }
+}

package/host.mjs

@@ -9,6 +9,8 @@ import { KEY, INTENT, RECEIPT, RECOVERY } from './projection.mjs'
 import { administrative, incompleteDisposition, ownedExecutionChain, unresolvedWork, workKey } from './work-policy.mjs'
 
 const fail = (code, detail = code) => { throw new GraphError(code, detail) }
+// Preserve the standalone pre-extension default. Callers may opt into a policy.
+export const ARTIFACT_MAX_BYTES = 16 * 1024 * 1024
 const under = (root, target) => { const relative = path.relative(root, target); return !path.isAbsolute(relative) && relative !== '..' && !relative.startsWith('..' + path.sep) }
 export function realProjectPath(root, requested, { directory = true } = {}) {
   if (typeof requested !== 'string' || !path.isAbsolute(requested)) fail('ABSOLUTE_PROJECT_PATH_REQUIRED')
@@ -38,15 +40,33 @@ function referenceSeq(reference, sessionId) {
   if (!Number.isSafeInteger(value) || value < 0) fail('EVIDENCE_BAD_SEQ')
   return value
 }
-export function artifactProof(projectRoot, ref, signal) {
+export function artifactProof(projectRoot, ref, signal, { maxBytes = ARTIFACT_MAX_BYTES } = {}) {
   if (!ref.sha256) fail('ARTIFACT_SHA_REQUIRED')
+  const identity = readArtifactIdentity(projectRoot, ref, signal, { maxBytes })
+  if (identity.sha256 !== ref.sha256) fail('ARTIFACT_CHANGED_OR_HASH_MISMATCH')
+  return identity
+}
+/** Observation of a historically verified deliverable, never current acceptance. */
+export function artifactCurrentIdentity(projectRoot, ref, signal, options) {
+  if (!ref.sha256) fail('ARTIFACT_SHA_REQUIRED')
+  try {
+    const identity = readArtifactIdentity(projectRoot, ref, signal, options)
+    return { ref: identity.path, acceptedSha256: ref.sha256, currentSha256: identity.sha256,
+      status: identity.sha256 === ref.sha256 ? 'UNCHANGED' : 'CHANGED', stat: identity.stat }
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error
+    return { ref: ref.ref, acceptedSha256: ref.sha256, currentSha256: null, status: 'MISSING' }
+  }
+}
+function readArtifactIdentity(projectRoot, ref, signal, { maxBytes = ARTIFACT_MAX_BYTES } = {}) {
+  if (maxBytes !== null && (!Number.isSafeInteger(maxBytes) || maxBytes < 1)) fail('ARTIFACT_BYTE_POLICY_INVALID')
   const requested = path.isAbsolute(ref.ref) ? ref.ref : path.resolve(projectRoot, ref.ref)
   const file = realProjectPath(projectRoot, requested, { directory: false })
   if (file.toLowerCase().endsWith('.gguf')) fail('MODEL_CONTENT_IS_NOT_TRANSACTION_ARTIFACT')
   const fd = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW)
   try {
     const before = fs.fstatSync(fd, { bigint: true })
-    if (!before.isFile() || before.size > 16n * 1024n * 1024n) fail('ARTIFACT_BYTE_LIMIT')
+    if (!before.isFile() || maxBytes !== null && before.size > BigInt(maxBytes)) fail('ARTIFACT_BYTE_LIMIT')
     const hash = createHash('sha256'), buffer = Buffer.alloc(65536)
     let total = 0n
     while (true) {
@@ -59,8 +79,8 @@ export function artifactProof(projectRoot, ref, signal) {
     const after = fs.fstatSync(fd, { bigint: true }), outside = fs.lstatSync(file, { bigint: true })
     const keys = ['dev', 'ino', 'size', 'mtimeNs', 'ctimeNs']
     if (total !== before.size || keys.some(key => before[key] !== after[key] || before[key] !== outside[key])
-        || fs.realpathSync(file) !== file || hash.digest('hex') !== ref.sha256) fail('ARTIFACT_CHANGED_OR_HASH_MISMATCH')
-    return { kind: 'artifact', refDigest: digest(ref), path: file, sha256: ref.sha256,
+        || fs.realpathSync(file) !== file) fail('ARTIFACT_CHANGED_OR_HASH_MISMATCH')
+    return { kind: 'artifact', refDigest: digest(ref), path: file, sha256: hash.digest('hex'),
       stat: Object.fromEntries(keys.map(key => [key, String(before[key])])) }
   } finally { fs.closeSync(fd) }
 }
@@ -182,6 +202,25 @@ export class DshTransactionHost {
         pending, legalNext: choices(display.legalNext), skipChoices: choices(display.skipChoices) } }
     } catch { return { ...base, status: 'unavailable' } }
   }
+  presence(session) {
+    if (!this.inProject(session)) return { state: 'OUTSIDE_SCOPE', previouslyCommitted: false }
+    const projected = this.projection(session)
+    const previouslyCommitted = projected.receipts.some(row => row.status === 'COMMITTED')
+    try {
+      const binding = this.binding(session)
+      const file = path.join(binding.projectRoot, this.storageRelative, digest(binding), 'transaction-host-journal.json')
+      if (!fs.existsSync(file)) {
+        if (projected.intents.length || projected.receipts.length) fail('HOST_JOURNAL_MISSING_FOR_RECORDED_SESSION')
+        return { state: 'NEVER_CREATED', previouslyCommitted: false, revision: 0 }
+      }
+      const { saved } = this.journal(session, { readOnly: true })
+      return { state: saved.document ? 'PRESENT' : previouslyCommitted ? 'LOST_OR_INVALID_AFTER_COMMIT' : saved.pending ? 'CREATION_PENDING' : 'NEVER_CREATED', previouslyCommitted,
+        revision: saved.document?.revision ?? 0 }
+    } catch (error) {
+      return { state: previouslyCommitted ? 'LOST_OR_INVALID_AFTER_COMMIT' : 'UNKNOWN_INTERRUPTED_CREATION',
+        previouslyCommitted, code: error.code ?? error.name }
+    }
+  }
   assertOwned(authority, exec) {
     const agent = exec.agent
     exec.signal?.throwIfAborted()
@@ -194,6 +233,7 @@ export class DshTransactionHost {
     if (!this.projection(agent.session).turn) fail('OPEN_MODEL_TURN_REQUIRED')
   }
   async authorize(exec) {
+    if (this.allowClassic && !this.allowClassic(exec.agent)) fail('TRANSACTION_GRAPH_SESSION_EXTENSION_DENIED')
     if (!exec.agent || this.ctx.agents.get(exec.agent.id) !== exec.agent || this.ctx.agents.currentInitiator() !== exec.agent) fail('EXACT_CALLING_AGENT_REQUIRED')
     await this.ctx.workingDirectory.ensure(exec.agent, exec.signal)
     const { binding, key } = this.journal(exec.agent.session)
@@ -276,6 +316,7 @@ export class DshTransactionHost {
       if (canonical(current) !== canonical(record)) fail('PENDING_RESULT_CHANGED_DURING_FLUSH')
       if (p.intentSeq === null) saved = journal.bindIntent(p.operationId, record.intentSeq)
       let rejectReason = null
+      if (p.operation === 'revise') rejectReason = 'This retired host revision entry requires its original extension; it cannot commit in standalone mode.'
       if (p.operation === 'finish' && record.status === 'SUCCESS') {
         try {
           const work = this.workState(session, saved, projected)

package/index.mjs

@@ -7,6 +7,9 @@ import { createToolDefinitions } from './tools.mjs'
 import { DshTransactionHost } from './host.mjs'
 import { projection, KEY } from './projection.mjs'
 import { createRemoteContribution } from './remote.mjs'
+import { WorkflowRegistry, WORKFLOW_CONTRACT } from './interop.mjs'
+import { EXTENSION_CONTRACT, SessionPolicies } from './extensions.mjs'
+import { FileGraphStore } from './store.mjs'
 
 export const name = 'dsh-bettertaskgraphs'
 let bindSessionResource
@@ -24,15 +27,20 @@ export default class TransactionGraphPlugin extends TypertRemoteService {
         || Object.keys(config).some(key => !['projectRoot', 'storageRelative', 'enableSwitch'].includes(key)))
       throw new Error('Invalid transaction graph configuration')
     this.host = new DshTransactionHost(ctx, { ...config, appendPluginRecord })
+    this.workflows = new WorkflowRegistry(ctx)
+    this.sessionPolicies = new SessionPolicies()
+    this.host.allowClassic = agent => this.sessionPolicies.allowClassic(agent)
+    Object.defineProperty(this, 'workflowContract', { value: WORKFLOW_CONTRACT })
+    Object.defineProperty(this, 'extensionContract', { value: EXTENSION_CONTRACT })
     ctx.sessionProjections.register(projection)
     for (const definition of createToolDefinitions({ defineTool, hostPort: this.host })) {
       this.host.definitions.set(definition.name, definition)
       ctx.tools.register(definition)
     }
-    ctx.systemPrompt.section({ name: 'project:transaction-graph', order: 46,
-      text: ({ agent }) => this.host.inProject(agent?.session) ? guidance : '' })
-    ctx.systemPrompt.context({ name: 'project:transaction-graph-state', order: 46, required: true, interpolate: false,
-      text: ({ agent }) => this.host.inProject(agent?.session) ? this.host.context(agent) : '' })
+      ctx.systemPrompt.section({ name: 'project:transaction-graph', order: 46,
+        text: ({ agent }) => this.host.inProject(agent?.session) && this.sessionPolicies.allowClassic(agent) ? guidance : '' })
+      ctx.systemPrompt.context({ name: 'project:transaction-graph-state', order: 46, required: true, interpolate: false,
+        text: ({ agent }) => this.host.inProject(agent?.session) && this.sessionPolicies.allowClassic(agent) ? this.host.context(agent) : '' })
     ctx.inject(['typert', 'sessionController'], remoteCtx => {
       const typert = remoteCtx.typert
       if (typert.resources.get('session')?.field !== 'sessionId') throw new Error('Transaction graph requires the native Session RPC resource')
@@ -54,7 +62,7 @@ export default class TransactionGraphPlugin extends TypertRemoteService {
         queueMicrotask(() => { if (!this.host.closed) this.host.schedule(session) })
       }
     })
-    ctx.effect(() => () => this.host.close())
+    ctx.effect(() => () => { this.workflows.close(); this.sessionPolicies.close(); return this.host.close() })
   }
   async status({ sessionId }, signal) {
     signal?.throwIfAborted()
@@ -67,4 +75,15 @@ export default class TransactionGraphPlugin extends TypertRemoteService {
   }
   registerRecoveryVerifier(adapter) { return this.host.registerRecoveryVerifier(adapter) }
   recoverInterrupted(agent, request) { return this.host.recoverInterrupted(agent, request) }
+  registerWorkflowProvider(adapter) { return this.workflows.register(adapter) }
+  listWorkflows(agent) { return this.workflows.list(agent) }
+  readWorkflow(agent, reference) { return this.workflows.read(agent, reference) }
+  dispatchWorkflow(agent, reference, operation, request, signal) { return this.workflows.dispatch(agent, reference, operation, request, signal) }
+  subscribeWorkflows(callback) { return this.workflows.subscribe(callback) }
+  registerSessionPolicy(provider) { return this.sessionPolicies.register(provider) }
+  createExtensionStore(options) {
+    if (this.host.closed) throw new Error('TASK_GRAPH_SERVICE_CLOSED')
+    return new FileGraphStore(options)
+  }
+  inspectGraphPresence(agent) { return this.host.presence(agent.session) }
 }

package/interop.mjs

@@ -0,0 +1,91 @@
+// SPDX-License-Identifier: GPL-3.0-only
+import fs from 'node:fs'
+import path from 'node:path'
+import { copy, GraphError, validateDocument } from './core.mjs'
+
+export const WORKFLOW_CONTRACT = 'dsh-taskgraph-workflow-v1'
+const name = value => typeof value === 'string' && /^[a-z][a-z0-9_-]{0,79}$/.test(value)
+const fail = code => { throw new GraphError(code) }
+const within = (root, target) => { const relative = path.relative(root, target); return relative === '' || relative !== '..' && !relative.startsWith('..' + path.sep) && !path.isAbsolute(relative) }
+
+/** In-process plugin port. A provider's joint ledger remains the sole authority.
+ * No model-supplied callback, synthetic session proof or mirrored commit is used.
+ */
+export class WorkflowRegistry {
+  constructor(ctx) { this.ctx = ctx; this.entries = new Map(); this.listeners = new Set(); this.closed = false }
+  register(adapter) {
+    if (this.closed || adapter?.contract !== WORKFLOW_CONTRACT || !name(adapter.kind) || !name(adapter.workflowId)
+        || !Number.isSafeInteger(adapter.version) || adapter.version !== 1 || typeof adapter.read !== 'function'
+        || typeof adapter.execute !== 'function' || typeof adapter.authorize !== 'function'
+        || !Array.isArray(adapter.operations) || adapter.operations.some(operation => !name(operation))
+        || new Set(adapter.operations).size !== adapter.operations.length) fail('WORKFLOW_ADAPTER_CONTRACT_REQUIRED')
+    if (typeof adapter.projectRoot !== 'string' || !path.isAbsolute(adapter.projectRoot)
+        || fs.realpathSync(adapter.projectRoot) !== adapter.projectRoot || !fs.statSync(adapter.projectRoot).isDirectory()) fail('WORKFLOW_REAL_PROJECT_REQUIRED')
+    const key = `${adapter.kind}:${adapter.workflowId}`
+    if (this.entries.has(key)) fail('WORKFLOW_PROVIDER_ALREADY_REGISTERED')
+    const entry = { ...adapter, operations: Object.freeze([...adapter.operations]), lifecycle: new AbortController() }
+    this.entries.set(key, entry)
+    const publish = event => {
+      if (this.entries.get(key) !== entry || this.closed) return
+      // Only post-commit revision metadata crosses the notification port.
+      const notice = Object.freeze({ contract: WORKFLOW_CONTRACT, kind: entry.kind, workflowId: entry.workflowId,
+        type: typeof event?.type === 'string' ? event.type : 'changed', revision: this.snapshot(entry).revision })
+      for (const callback of this.listeners) { try { callback(notice) } catch (error) { this.ctx.logger?.warn?.(`workflow listener failed: ${error.code ?? error.name}`) } }
+    }
+    let unsubscribe
+    try { unsubscribe = adapter.subscribe?.(publish); entry.unsubscribe = unsubscribe } catch (error) { this.entries.delete(key); throw error }
+    return () => {
+      if (this.entries.get(key) !== entry) return
+      this.entries.delete(key); entry.lifecycle.abort(new GraphError('WORKFLOW_PROVIDER_DISPOSED')); unsubscribe?.()
+    }
+  }
+  authorize(entry, agent) {
+    if (this.closed || !agent || this.ctx.agents.get(agent.id) !== agent || this.ctx.sessions.get(agent.session.id) !== agent.session)
+      fail('WORKFLOW_EXACT_CONTROLLER_REQUIRED')
+    const cwd = this.ctx.workingDirectory.get(agent.session)
+    if (typeof cwd !== 'string' || !within(entry.projectRoot, fs.realpathSync(cwd))
+        || !within(entry.projectRoot, fs.realpathSync(agent.session.header.cwd))) fail('WORKFLOW_CONTROLLER_OUTSIDE_PROJECT')
+    if (entry.authorize(agent) !== true) fail('WORKFLOW_CONTROLLER_NOT_AUTHORIZED')
+  }
+  entry({ kind, workflowId }, agent) {
+    const entry = this.entries.get(`${kind}:${workflowId}`)
+    if (!entry || this.closed) fail('WORKFLOW_PROVIDER_UNAVAILABLE')
+    this.authorize(entry, agent); return entry
+  }
+  snapshot(entry) {
+    const value = copy(entry.read())
+    if (!value || !Number.isSafeInteger(value.revision) || value.revision < 0 || (value.graph === null) !== (value.revision === 0)) fail('WORKFLOW_INVALID_SNAPSHOT')
+    if (value.graph !== null) { validateDocument(value.graph); if (value.graph.revision !== value.revision) fail('WORKFLOW_REVISION_MISMATCH') }
+    return { ...value, contract: WORKFLOW_CONTRACT, kind: entry.kind, workflowId: entry.workflowId,
+      operations: [...entry.operations], goalReached: false }
+  }
+  list(agent) {
+    const result = []
+    for (const entry of this.entries.values()) {
+      try { this.authorize(entry, agent) } catch { continue }
+      result.push({ contract: WORKFLOW_CONTRACT, kind: entry.kind, workflowId: entry.workflowId, revision: this.snapshot(entry).revision, operations: [...entry.operations] })
+    }
+    return result
+  }
+  read(agent, reference) { return this.snapshot(this.entry(reference, agent)) }
+  async dispatch(agent, reference, operation, request, signal) {
+    const entry = this.entry(reference, agent)
+    if (!entry.operations.includes(operation) || !request || typeof request !== 'object' || Array.isArray(request)) fail('WORKFLOW_OPERATION_NOT_SUPPORTED')
+    const input = copy(request), scope = AbortSignal.any([entry.lifecycle.signal, ...(signal ? [signal] : [])])
+    scope.throwIfAborted()
+    const result = await entry.execute(operation, input, { agent, signal: scope })
+    scope.throwIfAborted(); this.authorize(entry, agent)
+    if (this.entries.get(`${entry.kind}:${entry.workflowId}`) !== entry) fail('WORKFLOW_PROVIDER_DISPOSED')
+    return copy(result)
+  }
+  subscribe(callback) {
+    if (this.closed || typeof callback !== 'function') fail('WORKFLOW_LISTENER_REQUIRED')
+    this.listeners.add(callback); return () => this.listeners.delete(callback)
+  }
+  close() {
+    if (this.closed) return
+    this.closed = true
+    for (const entry of this.entries.values()) { entry.lifecycle.abort(new GraphError('WORKFLOW_PROVIDER_DISPOSED')); entry.unsubscribe?.() }
+    this.entries.clear(); this.listeners.clear()
+  }
+}

package/journal.mjs

@@ -27,7 +27,7 @@ export function validateJournal(value, binding) {
         || (row.graphChecksum !== null && !hex(row.graphChecksum)) || !integer(row.resultSeq)
         || (row.reason !== null && (typeof row.reason !== 'string' || row.reason.length > 1200))
         || !hex(row.claimDigest) || !hex(row.candidateChecksum) || !integer(row.intentSeq) || !integer(row.expectedGraphRevision)
-        || !['create', 'begin', 'finish', 'skip', 'reconcile'].includes(row.operation)
+        || !['create', 'begin', 'finish', 'skip', 'reconcile', 'revise'].includes(row.operation)
         || !Array.isArray(row.evidenceDigests) || row.evidenceDigests.length > 32 || row.evidenceDigests.some(x => !hex(x)))
       fail('JOURNAL_CLAIM_INVALID')
     operations.add(row.operationId)
@@ -45,7 +45,7 @@ export function validateJournal(value, binding) {
       'owner', 'bindingDigest', 'expectedGraphRevision', 'candidate', 'resolvedEvidence', 'intentSeq', 'claimDigest', 'clearedWork'])
         || operations.has(p.operationId) || !hex(p.payloadHash) || !hex(p.bindingDigest) || !hex(p.claimDigest)
         || claimDigest(p) !== p.claimDigest || p.bindingDigest !== digest(binding) || p.sessionId !== binding.sessionId
-        || !['create', 'begin', 'finish', 'skip', 'reconcile'].includes(p.operation) || !integer(p.turn)
+        || !['create', 'begin', 'finish', 'skip', 'reconcile', 'revise'].includes(p.operation) || !integer(p.turn)
         || p.expectedGraphRevision !== (value.document?.revision ?? 0) || (p.intentSeq !== null && !integer(p.intentSeq))
         || !Array.isArray(p.resolvedEvidence) || p.resolvedEvidence.length > 32 || !Array.isArray(p.clearedWork) || p.clearedWork.length > 1024
         || p.clearedWork.some(row => !fields(row, ['rootCallId', 'callSeq', 'rootResultSeq', 'eventDigest'])

package/package.json

@@ -1,9 +1,14 @@
 {
   "name": "dsh-bettertaskgraphs",
-  "version": "0.2.3",
+  "version": "0.3.0-rc.11",
   "description": "Transactional task graphs with a conversation panel for DeepSeek Harness",
   "license": "GPL-3.0-only",
-  "keywords": ["dsh", "deepseek-harness", "cordis", "task-graph"],
+  "keywords": [
+    "dsh",
+    "deepseek-harness",
+    "cordis",
+    "task-graph"
+  ],
   "homepage": "https://github.com/oldcitynight/dsh-bettertaskgraphs#readme",
   "repository": {
     "type": "git",
@@ -16,7 +21,12 @@
   "main": "./index.mjs",
   "exports": {
     ".": "./index.mjs",
-    "./client": "./client.js"
+    "./core": "./core.mjs",
+    "./store": "./store.mjs",
+    "./host": "./host.mjs",
+    "./interop": "./interop.mjs",
+    "./client": "./client.js",
+    "./extensions": "./extensions.mjs"
   },
   "files": [
     "client.js",
@@ -25,6 +35,7 @@
     "core.mjs",
     "host.mjs",
     "index.mjs",
+    "interop.mjs",
     "journal.mjs",
     "projection.mjs",
     "remote.mjs",
@@ -32,7 +43,9 @@
     "store.mjs",
     "tools.mjs",
     "view-model.mjs",
-    "work-policy.mjs"
+    "work-policy.mjs",
+    "extensions.mjs",
+    "VALIDATION.md"
   ],
   "engines": {
     "node": "^22.19.0 || >=24.0.0",
@@ -48,6 +61,7 @@
   },
   "publishConfig": {
     "access": "public",
+    "tag": "next",
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {

package/projection.mjs

@@ -17,7 +17,7 @@ const factSchema = z.object({ seq, callId: bounded(512), tool: bounded(300), isE
   outcome: z.enum(['UNVERIFIED', 'FAIL', 'NOT_RUN', 'UNKNOWN']) }).strict()
 const intentSchema = z.object({ version: z.literal(4), operationId: bounded(80), callId: bounded(512),
   rootCallId: bounded(512), turn: seq, sessionId: bounded(512), bindingDigest: hex, claimDigest: hex,
-  operation: z.enum(['create', 'begin', 'finish', 'skip', 'reconcile']), expectedGraphRevision: seq, candidateChecksum: hex,
+  operation: z.enum(['create', 'begin', 'finish', 'skip', 'reconcile', 'revise']), expectedGraphRevision: seq, candidateChecksum: hex,
   clearedWork: z.array(workSchema).max(1024) }).strict()
 const dispatchSchema = z.object({ seq, subCallId: bounded(512), parentCallId: bounded(512), rootCallId: bounded(512),
   tool: bounded(300), isError: z.boolean(), outcome: z.enum(['UNVERIFIED', 'FAIL', 'NOT_RUN', 'UNKNOWN']), eventDigest: hex, turn: seq }).strict()

package/store.mjs

@@ -26,8 +26,8 @@ function regularBoundedJson(file, maximum = LIMITS.bytes) {
   catch (error) { if (error.code === 'ENOENT') return null; throw error }
   try {
     const before = fs.fstatSync(fd)
-    if (!before.isFile() || before.size > maximum || before.size < 1) reject('INVALID_STORE_FILE')
-    const buffer = Buffer.alloc(Math.min(before.size + 1, maximum + 1))
+    if (!before.isFile() || maximum !== null && before.size > maximum || before.size < 1) reject('INVALID_STORE_FILE')
+    const buffer = Buffer.alloc(maximum === null ? before.size + 1 : Math.min(before.size + 1, maximum + 1))
     let count = 0
     while (count < buffer.length) {
       const read = fs.readSync(fd, buffer, count, buffer.length - count, null)
@@ -60,8 +60,8 @@ export class MemoryGraphStore {
 export class FileGraphStore {
   constructor({ projectRoot, directory, fileName = 'transaction-graph.json', maximumBytes = LIMITS.bytes,
     validator = validateDocument, updateValidator = checkNext, readOnly = false }) {
-    if (!/^[a-z][a-z0-9.-]{0,63}$/.test(fileName) || !Number.isSafeInteger(maximumBytes)
-        || maximumBytes < 1 || maximumBytes > 12 * 1024 * 1024 || typeof validator !== 'function' || typeof updateValidator !== 'function') reject('INVALID_STORE_POLICY')
+    if (!/^[a-z][a-z0-9.-]{0,63}$/.test(fileName) || maximumBytes !== null && (!Number.isSafeInteger(maximumBytes)
+        || maximumBytes < 1 || maximumBytes > 12 * 1024 * 1024) || typeof validator !== 'function' || typeof updateValidator !== 'function') reject('INVALID_STORE_POLICY')
     this.maximumBytes = maximumBytes; this.validator = validator; this.updateValidator = updateValidator
     this.readOnly = readOnly
     if (typeof projectRoot !== 'string' || typeof directory !== 'string'
@@ -126,7 +126,7 @@ export class FileGraphStore {
       this.validator(next)
       this.updateValidator(previous, next)
       const content = JSON.stringify(next) + '\n'
-      if (Buffer.byteLength(content) > this.maximumBytes) reject('STORE_BYTE_LIMIT')
+      if (this.maximumBytes !== null && Buffer.byteLength(content) > this.maximumBytes) reject('STORE_BYTE_LIMIT')
       temporary = path.join(this.directory, '.transaction-graph-' + randomUUID() + '.tmp')
       const fd = fs.openSync(temporary, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_NOFOLLOW, 0o600)
       try { temporaryIdentity = fs.fstatSync(fd); fs.writeFileSync(fd, content); fs.fsyncSync(fd) } finally { fs.closeSync(fd) }