@bizagent/dsh 0.0.0-stage → 1.0.0

package/docs/user-guide.zh-CN.md

@@ -0,0 +1,132 @@
+# 用户指南
+
+[文档导航](README.md) · 尚未安装？先看[快速开始](quickstart.zh-CN.md)。
+
+只用个人记忆，可从[存下一条规则](quickstart.zh-CN.md#第一次成功存下一条规则)开始。
+想试团队协作，直接做下面的虚构订单练习；已有组织和未建组织的环境都可用。
+
+## 入口与状态速查
+
+| 你要做什么 | 从哪里进入 | 看什么 |
+| --- | --- | --- |
+| 确认当前 Agent 属于谁 | 会话顶部的 Home 按钮 | Home 名称，以及日常/主/项目/工作会话类型 |
+| 查规则是否保存 | Home 按钮 → 学习 | 资产正文、证据来源、active/candidate 状态 |
+| 查派工和交付 | 会话的「工作与经验」页签 | 工作状态、结果正文、产物、查看执行会话 |
+| 从 Worker 回到负责人 | 工作与经验 → 返回派工会话 | 原来的派工会话 |
+| 找项目并人工验收 | 工作与经验 → 项目；或 BizAgent → 项目 → 我的审核待办 | 当前提交、证据、验收或返工理由 |
+| 回信给 Agent | 会话顶部或 BizAgent 中的「我的收件箱」 | 回复内容、发送回复、标记已处理 |
+| 查这一轮产生了什么 | 回答下方的「本轮留下…项记录」 | 该轮成功保存的经验、工作和项目记录 |
+
+空白新会话需要先发送消息，才会出现完整的会话入口。学习页点击「对话」会重开该 Home 的长期主会话；
+新项目有自己的项目主会话，正式 Work 在另一段执行会话中完成。
+
+三种状态分别回答不同问题：
+
+- **运行中 / 空闲 / 未加载**：DSH Agent 当前是否正在执行；未加载本身不表示失败。
+- **待接单 / 已接单 / 已完成**：正式 Work 的进度；完成后展开结果检查交付内容。
+- **推进中 / 待验收 / 已验收**：Project 的交付与审核进度；页面验收后为 `accepted`，项目详情也可能显示「已通过」。
+
+回执中的「记录时」描述历史，当前状态以工作卡片或项目详情为准。「工作与经验」只列当前会话派出或承接的工作；
+项目列表也受当前 Home 的参与权限影响。找不到时返回负责人/项目会话，或查看自己的审核待办。
+
+## 完成一次协作练习
+
+### 1. 准备两个练习 Home
+
+在 **BizAgent 组织 → 学习 → 创建 Home** 分别填写：
+
+| 字段 | 负责人 | 分析师 |
+| --- | --- | --- |
+| Home 类型 | Personal | Personal |
+| 唯一标识 | `practice-lead` | `practice-analyst` |
+| 显示名称 | 练习负责人 | 练习分析师 |
+| 初始 Identity | 负责上手练习项目的派工、复核和提交，只处理练习数据。 | 承接上手练习的正式 Work，独立核对订单，交付报告和计算日志。 |
+
+将生成 `personal:practice-lead` 和 `personal:practice-analyst`。编号已存在时换用新编号，并同步替换后面的提示语。
+已有组织时练习 Home 创建在当前组织空间；`Personal` 表示成员类型，和外部的「我的个人 Home」分开。
+当前本机用户拥有新建的两个 Home，满足自动派工的同 owner 条件。
+
+**检查**：学习页能分别选择两个 Home。选择负责人，点「对话」，确认会话顶部显示「练习负责人」。
+
+### 2. 教负责人一条规则
+
+在负责人的主会话发送：
+
+> 记住这条仅用于上手练习的规则：订单 GMV 只计 paid，排除 cancelled 和 refunded。
+> 请实际保存到当前 Home，告诉我资产编号和状态。本轮只保存规则。
+
+**检查**：从 Home 按钮进入学习页，展开资产，核对正文、来源和 `active` 状态。
+如果是候选，先核对依据再请 Agent 发布，不要把候选当成已生效规则。
+
+### 3. 创建项目，再进入项目对话
+
+回到负责人的主会话发送：
+
+> 创建 BizAgent 项目「上手练习：订单 GMV 核对」。目标是让练习分析师独立核对四笔虚构订单。
+> 完成标准：正式 Work 在分析师自己的会话接单并完成，交付逐笔报告和计算日志，负责人复核后提交给我人工验收。
+> 本轮只创建项目，订单稍后在项目对话提供。
+
+**检查**：在「工作与经验」的项目栏点这个项目，再点「打开项目对话」。
+会话顶部应显示「项目主会话」及项目名称，和刚才的 Agent 主会话分开。
+
+### 4. 在项目对话派工
+
+发送：
+
+> 先读取当前 Home 保存的上手练习 GMV 规则。订单是 A：paid 100 元，B：paid 200 元，
+> C：cancelled 50 元，D：refunded 30 元。请关联当前项目，向 personal:practice-analyst 派正式 Work。
+> 请分析师在独立会话接单并核对，将逐笔报告和计算日志保存到 artifacts/ 并随结果交付。
+> 结果返回后请复核产物，提交给我人工验收。
+
+**检查**：「工作与经验」出现负责人 → 分析师的工作卡片。用「查看执行会话」核对分析师的 Home 和接单记录，
+再用「返回派工会话」回到项目。结果会自动回传；交付前不要重复派同一个任务。
+
+### 5. 看结果，然后亲自验收
+
+正确结果为 **300 元**：A、B 计入，C、D 排除。展开 Work 的结果检查逐笔说明和产物。
+
+负责人提交后，从项目卡片进入详情：查看当前交付与「下载提交版本」，填写「验收或返工理由」，
+点击「验收通过」；不满足标准时点击「退回返工」。也可从「我的审核待办」查找待验收结果。
+
+**成功标志**：Work 为「已完成」，Project 为「已验收」，结果和已下载的提交版本一致。
+若退回返工，负责人需修订并重新提交，你审核的是新版本。
+
+### 6. 可选：验证收件箱回信
+
+在项目对话发送：
+
+> 读取当前 Home 的 owner，向对应的用户地址（user: 后接实际 owner）发一封普通 Inbox 信件，标题为「上手练习：核对完成」，
+> 简短告知结果与项目状态，然后结束本轮。
+
+打开「我的收件箱」，回复“收到，请确认这条回复，不再派工或修改记忆”，并标记原信已处理。
+
+**检查**：回到原项目会话，它自动接收到你的回复并确认。发信/已处理记录与 Work、Project 的状态各自保存。
+
+## 该用哪种协作方式
+
+| 你的目的 | 用什么 | 行为边界 |
+| --- | --- | --- |
+| 当前对话参考另一个 Home 的知识 | `@` 选择共享 Home / Frame | 在同一会话加入只读上下文，检查输入区 Frame 状态 |
+| 给另一个 Agent 留信或提问 | Inbox | 对方在自己的会话读取、回复；送达和已处理各有记录 |
+| 让对方负责一份明确交付 | 正式 Work | 约定目标和验收标准，在独立工作会话接单、完成 |
+| 围绕长期目标组织交付并由人确认 | Project | 关联 Work，汇总证据，提交后由人验收 |
+| 把经验保存到另一个 Home | Proposal | 目标方主人接受后才进入目标 Home |
+
+`@` 候选提供 Business、Role、Capability 共享 Home，不列出其他 Personal 成员 Home。
+输入 `@`，从带 Home 地址的候选中选中再发送；在输入区查看加载状态，失败时先处理加载提示。
+给分析师派工时直接使用它的地址即可，无需先 `@` 它。
+Frame 条目上的「主导」「协作」描述上下文角色，独立执行要看正式 Work 及执行会话。
+
+## 内置示例团队
+
+首次组织设置中的「创建示例团队」会提供 Sample Shop、两个成员、共享角色/能力、`orders.csv` 和四步向导。
+已有组织时继续用上面的独立练习即可。
+
+内置数据排除 `cancelled`、`refunded`，保留 `paid` 和 `shipped`：
+**120.50 + 45.25 + 200.00 + 34.75 = 400.50 元**。
+它和上面的四笔订单使用不同数据、不同口径。
+
+想继续体验知识分享，可让分析师把规则连同依据提议给 `business:sample-shop`，再到该 Home 的学习页审批。
+
+进阶时再读：[核心概念](concepts.md)、[配置与备份](configuration.md)、[兼容与验证](verification.md)。
+遇到入口、权限或模型问题，先看[排查表](quickstart.zh-CN.md#遇到问题时)。

package/docs/verification.md

@@ -0,0 +1,69 @@
+# Verification and compatibility
+
+[Documentation](README.md) · [中文上手](quickstart.zh-CN.md)
+
+This page separates development baselines, manual acceptance, and reproducible checks.
+
+## Version baselines
+
+| Baseline | Version | Evidence |
+| --- | --- | --- |
+| Package | `@bizagent/dsh` 1.0.0 | Package manifest and [release notes](../CHANGELOG.md). |
+| Installation / development / CI runtime | DSH `0.2.1-rc.2` | Installation guide, dev dependencies, and runtime CI use the same version. DSH peers declare `^0.2.1-rc.2`. |
+| Manual browser acceptance, 2026-10-20 | DSH `0.2.1-rc.2` | The 1.0.0 implementation used in DSH Web with DeepSeek-V4.1-Flash / High. |
+
+Keep an existing working installation unless an upgrade is needed; inspect DSH activation errors
+when using a different version. Other DSH versions need their own compatibility checks.
+
+Within BizAgent 1.x, semantic versioning covers public entry points (`@bizagent/dsh` and
+`@bizagent/dsh/host`), Agent tool names, and persisted file formats. Internal `lib/` modules are
+not a public API; DSH runtime compatibility still needs its own verification.
+
+## What was checked
+
+The 1.0.0 implementation passed **179 automated tests** and a real-model browser exercise with
+**11 checks**:
+
+| Area | Observed behavior |
+| --- | --- |
+| Selected `@Agent` | A logged Frame snapshot reached the model before tool execution. |
+| Save learning | The rule appeared with its body, source, and status. |
+| Recall in another session | The separate Project Main read the saved rule. |
+| Independent formal Work | Another Home's worker accepted and completed the Work. |
+| Result navigation | The result expanded; worker and requester sessions could be opened. |
+| Human Project acceptance | A browser review changed the Project to `accepted`. |
+| Artifact download | Downloaded bytes and SHA-256 matched the submitted snapshot. |
+| Human Inbox reply | Replying in My Inbox resumed the original Project session. |
+| Home creation dialog | Dialog semantics and initial focus were checked after the fix. |
+| Markdown result | The Work result rendered an actual table. |
+| Worker workspace | The worker appeared under its Home workspace without a new execution turn. |
+
+The fictional four-order case is reproducible through the [user guide](user-guide.zh-CN.md).
+Its expected GMV is **300**. The built-in Sample Shop's different dataset gives **400.50**.
+The manual exercise also checked existing data, configuration, and process preservation.
+Private transcripts, runtime identifiers, and credentials are intentionally not part of public examples.
+
+## Repeat the checks
+
+From the repository root, check documentation:
+
+```sh
+node scripts/check-docs.mjs
+git diff --check
+```
+
+From `packages/dsh`, check implementation and isolated runtime integration:
+
+```sh
+npm ci
+npm test
+npm run smoke:local-human
+npm run smoke:session-ui
+```
+
+The smoke scripts start real isolated DSH profiles but use a deterministic local model. They
+test integration, not how a real model chooses tools. The Learning Lab checks service behavior
+without starting DSH. The [user guide](user-guide.zh-CN.md) supplies the real-model manual route.
+
+The browser run covered one complete delivery flow and the listed UI checks. Long-term stability,
+every failure/recovery path, other model routes, and multi-user hosting were not established by it.

package/examples/README.md

@@ -0,0 +1,64 @@
+# Learning Lab
+
+Three scripted cases that run BizAgent's real learning and collaboration services without a model
+or a DSH process. Use them to see what BizAgent records, step by step, in a few seconds.
+
+| Case | From → to | What is learned |
+| --- | --- | --- |
+| `growth` | Personal analyst → Role `growth-strategy` | A retention comparison method with stated limits |
+| `engineering` | Personal developer → Capability `config-review` | A method for verifying backups before configuration changes |
+| `support` | Personal support agent → Business `demo-store` | Product knowledge tied to a product version |
+
+The cases and their wording are fictional teaching material, not real business policies.
+
+## Run
+
+```sh
+cd packages/dsh
+npm ci
+npm run examples                 # all three cases
+npm run examples -- growth       # one case
+node examples/learning-lab.mjs   # after a build, or from an unpacked tarball
+```
+
+Each case uses a fresh temporary directory, removes it afterwards, and prints eleven checks:
+
+```text
+[growth] Growth analysis: comparable retention cohorts
+  1. Candidate saved; default search excludes it; source evidence is readable.
+  2. Stale publication rejected; the reviewed revision is now active.
+  3. Agents cannot approve; a host-authenticated human accepts; replay creates no duplicate.
+  4. A read-only Agent Frame reuses the target index without changing the author Home.
+  5. Future context contains only the index; feedback requests review; owner retires the asset.
+  6. Home files reload correctly; retirement does not alter the author's copy.
+  7. Review progress is explicit; later Session changes remain pending after a ledger reopen.
+  8. Inbox delivery, reply, and handling survive a ledger reopen without changing Work or Memory.
+  9. Formal Work binds one worker Session and one returned result beyond ordinary Inbox replies.
+  10. Project submission records linked Work and a human acceptance across ledger reopen.
+  11. Session Worklog links formal Work, verifies source events, and tracks a Workspace file.
+...
+Learning lab passed: 3 scenarios. Temporary data removed.
+```
+
+## What is real here
+
+| Part | In the lab | Covers |
+| --- | --- | --- |
+| Home files | Real `HomeStore` on a temporary directory | Candidates, revisions, index, retirement, reload |
+| BizAgent service | Real | Ownership, revision conflicts, proposals, feedback, Inbox, Work, Projects, Worklogs |
+| Ledgers | Real schemas and logic over in-memory tables | Records within one process; not persistence across processes |
+| DSH sessions | Small synthetic event logs | Evidence references and bounded reads |
+| Model and data | None; fixed fixtures | Not whether a model calls the tools well |
+
+To see the same loops with a real model, follow the sample team in the
+[quick start](../docs/quickstart.md#use-bizagent).
+
+## Read the code
+
+- [learning-lab.mjs](learning-lab.mjs): the eleven steps in order, each with assertions.
+- [scenarios.mjs](scenarios.mjs): inputs and reviewed text for the three cases.
+- [demo-runtime.mjs](demo-runtime.mjs): the in-memory stand-in for DSH storage and sessions.
+
+The lab imports internal modules from `lib/` to show the current implementation; they are not a
+stable API. Agents use the [tools](../docs/tools.md); hosts use the package entry points listed in
+the [package README](../README.md#package-entry-points).

package/examples/demo-runtime.mjs

@@ -0,0 +1,71 @@
+// A minimal in-memory DSH storage/session adapter for the learning lab.
+// The production plugin gets these facilities from DSH; do not use this adapter for real data.
+import { LearningLedger } from '../lib/ledger.js'
+import { WorkLedger } from '../lib/work-ledger.js'
+import { ProjectLedger } from '../lib/project-ledger.js'
+import { WorklogLedger } from '../lib/worklog-ledger.js'
+
+export async function createDemoRuntime() {
+  const tables = new Map()
+  const sessions = new Map()
+  const facility = {
+    async open() {
+      return {
+        table(name) {
+          if (!tables.has(name)) {
+            const records = new Map()
+            tables.set(name, {
+              get: key => structuredClone(records.get(key)),
+              entries: () => structuredClone(records).entries(),
+              async put(key, value) { records.set(key, structuredClone(value)) },
+            })
+          }
+          return tables.get(name)
+        },
+        async close() {},
+      }
+    },
+  }
+  const ledger = await LearningLedger.open(facility)
+  const workLedger = await WorkLedger.open(facility)
+  const projectLedger = await ProjectLedger.open(facility)
+  const worklogLedger = await WorklogLedger.open(facility)
+  return {
+    ledger,
+    workLedger,
+    projectLedger,
+    worklogLedger,
+    reopenLedger: () => LearningLedger.open(facility),
+    reopenWorkLedger: () => WorkLedger.open(facility),
+    reopenProjectLedger: () => ProjectLedger.open(facility),
+    reopenWorklogLedger: () => WorklogLedger.open(facility),
+    sessionQuery: {
+      async listSessions() {
+        return [...sessions.values()].map(snapshot => ({ header: structuredClone(snapshot.session), live: false, persisted: true }))
+      },
+      async readSession(id) {
+        const session = sessions.get(id)
+        if (!session) throw new Error(`Unknown demo session: ${id}`)
+        return structuredClone(session)
+      },
+    },
+    appendSessionEvent(id, event) {
+      const session = sessions.get(id)
+      if (!session) throw new Error(`Unknown demo session: ${id}`)
+      session.events.push(structuredClone(event))
+    },
+    agent(id, cwd, message) {
+      const events = [
+        { seq: 0, time: 1, type: 'turn/start', data: { turn: 1 } },
+        { seq: 1, time: 2, type: 'user/message', data: { content: [{ type: 'text', text: message }] } },
+      ]
+      sessions.set(id, { session: { id, cwd }, events })
+      return { id, session: liveSession({ id, cwd }, events) }
+    },
+  }
+}
+
+/** The part of a live DSH Session the plugin reads: its header and a snapshot of its event log. */
+export function liveSession(header, events) {
+  return { header, events, snapshotEvents: () => events }
+}

package/examples/learning-lab.mjs

@@ -0,0 +1,263 @@
+import assert from 'node:assert/strict'
+import { mkdir, mkdtemp, realpath, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { HomeStore } from '../lib/home-store.js'
+import { BizAgentService } from '../lib/service.js'
+import { createDemoRuntime } from './demo-runtime.mjs'
+import { scenarios } from './scenarios.mjs'
+
+const requested = process.argv[2] ?? 'all'
+const selected = scenarios.filter(scenario => requested === 'all' || scenario.id === requested)
+if (selected.length === 0 || process.argv.length > 3) {
+  process.stderr.write('Usage: node examples/learning-lab.mjs [all|growth|engineering|support]\n')
+  process.exitCode = 1
+} else {
+  for (const scenario of selected) await runScenario(scenario)
+  process.stdout.write(`Learning lab passed: ${selected.length} scenarios. Temporary data removed.\n`)
+}
+
+async function runScenario(scenario) {
+  const root = await mkdtemp(join(await realpath(tmpdir()), 'bizagent-learning-lab-'))
+  const runtime = await createDemoRuntime()
+  try {
+    const store = new HomeStore(root)
+    await store.initialize()
+    await store.createHome({ address: scenario.author })
+    await store.createHome({ address: scenario.owner })
+    const ownerCwd = join(root, 'owner-work')
+    const service = new BizAgentService(store, runtime.ledger, {
+      homeRoot: root,
+      defaultHome: scenario.author,
+      autoCreateDefaultHome: false,
+      workspaceHomes: [{ root: ownerCwd, address: scenario.owner }],
+      budget: { identityMaxBytes: 1024, indexMaxBytes: 4096 },
+      learningCheckpointEnabled: false,
+    }, runtime.sessionQuery, undefined, undefined, runtime.workLedger, runtime.projectLedger, runtime.worklogLedger)
+    await service.initialize()
+    const author = runtime.agent(`${scenario.id}-author`, root, scenario.observation)
+    const initialRevision = store.getHome(scenario.author).revision
+
+    process.stdout.write(`\n[${scenario.id}] ${scenario.name}\n`)
+    const draft = await service.remember(author, `${scenario.id}-draft`, {
+      kind: scenario.kind, status: 'candidate',
+      description: scenario.description, body: scenario.draft, tags: [scenario.id],
+    })
+    assert.equal((await service.searchMemory(author, {})).count, 0)
+    assert.equal((await service.searchMemory(author, { status: 'candidate' })).count, 1)
+    assert.equal(store.getHome(scenario.author).revision, initialRevision)
+    const evidence = await service.readEvidence(author, { assetId: draft.asset.id })
+    assert.equal(evidence.events[0].text, scenario.observation)
+    process.stdout.write('  1. Candidate saved; default search excludes it; source evidence is readable.\n')
+
+    const reviewed = await service.updateMemory(author, {
+      assetId: draft.asset.id, action: 'revise', expectedRevision: draft.asset.revision,
+      body: scenario.reviewed,
+    })
+    assert.equal(reviewed.asset.status, 'candidate')
+    await assert.rejects(() => service.updateMemory(author, {
+      assetId: draft.asset.id, action: 'publish', expectedRevision: draft.asset.revision,
+    }), /revision conflict/)
+    const read = await service.readMemory(author, `${scenario.id}-read`, draft.asset.id)
+    const published = await service.updateMemory(author, {
+      assetId: read.asset.id, action: 'publish', expectedRevision: read.asset.revision,
+    })
+    assert.equal(published.asset.status, 'active')
+    assert.equal(published.home.revision, initialRevision + 1)
+    process.stdout.write('  2. Stale publication rejected; the reviewed revision is now active.\n')
+
+    const proposed = await service.proposeMemory(author, `${scenario.id}-proposal`, {
+      toAddress: scenario.owner, proposedKind: scenario.kind,
+      description: scenario.description, body: scenario.reviewed, tags: [scenario.id],
+    })
+    assert.equal(store.listAssets(scenario.owner).length, 0)
+    await assert.rejects(() => service.acceptProposal(author, {
+      proposalId: proposed.proposal.id,
+    }), /host-authenticated human review/)
+    const owner = runtime.agent(`${scenario.id}-owner`, ownerCwd, 'Review the scope and evidence of the demo proposal.')
+    await assert.rejects(() => service.acceptProposal(owner, {
+      proposalId: proposed.proposal.id,
+    }), /host-authenticated human review/)
+    const humanDecision = { ownerAddress: scenario.owner, proposalId: proposed.proposal.id,
+      action: 'accept', reviewerId: 'demo-reviewer', authorityRef: 'demo-host:scenario-owner',
+      decision: 'Reviewed against the fictional scenario and its stated scope.' }
+    const accepted = await service.decideProposalAsHuman(humanDecision)
+    const replay = await service.decideProposalAsHuman(humanDecision)
+    assert.equal(replay.idempotentReplay, true)
+    assert.equal(store.listAssets(scenario.owner).length, 1)
+    process.stdout.write('  3. Agents cannot approve; a host-authenticated human accepts; replay creates no duplicate.\n')
+
+    const frame = await service.openFrame(author, { address: scenario.owner, mode: 'contribute' })
+    assert.equal(frame.state.primaryHome, scenario.author)
+    assert.ok(frame.context.includes(scenario.description))
+    const frameHits = await service.searchFrame(author, { query: scenario.description })
+    assert.deepEqual(frameHits.assets.map(item => item.id), [accepted.asset.id])
+    assert.equal((await service.readFrame(author, `${scenario.id}-frame-read`, {
+      assetId: accepted.asset.id,
+    })).asset.id, accepted.asset.id)
+    const reopenedFrameLedger = await runtime.reopenLedger()
+    assert.equal(reopenedFrameLedger.getFrameState(author.id).focusAddress, scenario.owner)
+    await reopenedFrameLedger.close()
+    await service.closeFrame(author)
+    assert.equal((await service.frameStatus(author)).state.frames.length, 0)
+    process.stdout.write('  4. A read-only Agent Frame reuses the target index without changing the author Home.\n')
+
+    const future = runtime.agent(`${scenario.id}-future`, ownerCwd, 'Use the reviewed demo asset in a subsequent task.')
+    const snapshot = service.contextForSession(future.id, ownerCwd)
+    assert.ok(snapshot.includes(scenario.description))
+    assert.ok(!snapshot.includes(scenario.reviewed))
+    await service.readMemory(future, `${scenario.id}-future-read`, accepted.asset.id)
+    const applied = await service.feedback(future, `${scenario.id}-applied`, {
+      assetId: accepted.asset.id, signal: 'applied',
+    })
+    assert.equal(applied.asset.fitness, 0)
+    const confirmed = await service.feedback(future, `${scenario.id}-confirmed`, {
+      assetId: accepted.asset.id, signal: 'confirmed', outcome: scenario.confirmation,
+    })
+    assert.equal(confirmed.asset.fitness, 0.2)
+    await service.feedback(future, `${scenario.id}-contradicted`, {
+      assetId: accepted.asset.id, signal: 'contradicted', outcome: scenario.contradiction,
+    })
+    const failed = await service.feedback(future, `${scenario.id}-failed`, {
+      assetId: accepted.asset.id, signal: 'failed', outcome: scenario.failure,
+    })
+    assert.equal(failed.reviewRequired, true)
+    assert.equal(failed.asset.status, 'active')
+    await service.updateMemory(future, {
+      assetId: accepted.asset.id, action: 'retire', expectedRevision: failed.asset.revision,
+    })
+    assert.equal((await service.searchMemory(future, {})).count, 0)
+    process.stdout.write('  5. Future context contains only the index; feedback requests review; owner retires the asset.\n')
+
+    // Reload actual Markdown files; the demo ledger itself is intentionally ephemeral.
+    const reloaded = new HomeStore(root)
+    await reloaded.initialize()
+    assert.equal(reloaded.readAsset(scenario.owner, accepted.asset.id).status, 'retired')
+    assert.equal(reloaded.readAsset(scenario.author, published.asset.id).status, 'active')
+    assert.deepEqual((await reloaded.doctor()).issues, [])
+    process.stdout.write('  6. Home files reload correctly; retirement does not alter the author\'s copy.\n')
+
+    const learningAgent = runtime.agent(`${scenario.id}-learning`, root, 'Review earlier work for useful experience.')
+    const materials = await service.scanLearningMaterials(learningAgent)
+    assert.deepEqual(materials.materials.map(item => item.sessionId), [author.id])
+    const reviewedMaterial = materials.materials[0]
+    await service.readEpisode(learningAgent, { sessionId: author.id })
+    await service.reviewLearningMaterial(learningAgent, {
+      materialId: reviewedMaterial.id,
+      summary: 'The earlier observation was checked; its reviewed asset already captures the reusable part.',
+    })
+    const resumedLedger = await runtime.reopenLedger()
+    assert.equal(resumedLedger.getMaterialReview(reviewedMaterial.id).materialId, reviewedMaterial.id)
+    await resumedLedger.close()
+    assert.equal((await service.scanLearningMaterials(learningAgent)).materials.length, 0)
+    author.session.events.push({
+      seq: 2, time: 3, type: 'user/message',
+      data: { content: [{ type: 'text', text: 'A later result changes the interpretation of the earlier work.' }] },
+    })
+    const changed = await service.scanLearningMaterials(learningAgent)
+    assert.equal(changed.materials.length, 1)
+    assert.notEqual(changed.materials[0].fingerprint, reviewedMaterial.fingerprint)
+    process.stdout.write('  7. Review progress is explicit; later Session changes remain pending after a ledger reopen.\n')
+
+    const message = await service.sendInboxMessage(author, `${scenario.id}-inbox-send`, {
+      to: [scenario.owner], subject: 'Review the later result',
+      body: 'A later observation may change how we use the earlier asset.',
+      idempotencyKey: `${scenario.id}-later-result`,
+    })
+    assert.equal(message.deliveries[0].status, 'delivered')
+    const inboxLedger = await runtime.reopenLedger()
+    assert.equal(inboxLedger.getInboxMessage(message.message.id).returnToSessionId, author.id)
+    assert.equal(inboxLedger.getInboxDelivery(message.message.id, scenario.owner).status, 'delivered')
+    await inboxLedger.close()
+    assert.equal((await service.listInbox(future, { pendingOnly: true })).messages.length, 1)
+    assert.equal((await service.readInboxMessage(future, message.message.id)).message.body,
+      'A later observation may change how we use the earlier asset.')
+    await service.handleInboxMessage(future, message.message.id)
+    const reply = await service.sendInboxMessage(future, `${scenario.id}-inbox-reply`, {
+      to: [scenario.author], subject: 'Re: Review the later result',
+      body: 'I will review the new evidence before changing the method.', replyTo: message.message.id,
+    })
+    assert.equal(reply.message.rootId, message.message.id)
+    assert.equal((await service.listInbox(future, { pendingOnly: true })).messages.length, 0)
+    assert.equal((await service.listInbox(author)).messages[0].id, reply.message.id)
+    process.stdout.write('  8. Inbox delivery, reply, and handling survive a ledger reopen without changing Work or Memory.\n')
+
+    const project = await service.createProject(author, {
+      title: `${scenario.name} evidence review`,
+      goal: 'Decide how the later observation affects the earlier result.',
+      doneWhen: 'The formal review is returned and the final conclusion is recorded.',
+      idempotencyKey: `${scenario.id}-review-project`,
+    })
+    const assignment = await service.dispatchWork(author, {
+      toAddress: scenario.owner,
+      goal: `Review the later ${scenario.id} result`,
+      acceptanceCriteria: 'Return a concrete conclusion tied to the later observation.',
+      idempotencyKey: `${scenario.id}-formal-review`,
+      projectId: project.project.id,
+    })
+    assert.equal(assignment.work.status, 'open')
+    assert.equal(assignment.notification.message.kind, 'work-request')
+    const workReopened = await runtime.reopenWorkLedger()
+    assert.equal(workReopened.get(assignment.work.id).requestMessageId, assignment.notification.message.id)
+    await workReopened.close()
+    const acceptedWork = await service.acceptWork(future, assignment.work.id)
+    assert.equal(acceptedWork.work.workerSessionId, future.id)
+    const result = await service.completeWork(future, {
+      workId: assignment.work.id,
+      subject: `Reviewed ${scenario.id} result`,
+      body: 'The later observation needs a fresh evidence check before reuse.',
+    })
+    assert.equal(result.work.status, 'completed')
+    assert.equal(result.notification.message.kind, 'work-result')
+    assert.equal((await service.readWork(author, assignment.work.id)).resultDelivery.status, 'delivered')
+    assert.equal((await service.completeWork(future, {
+      workId: assignment.work.id, subject: 'Another result', body: 'Should not replace the first.',
+    })).alreadyCompleted, true)
+    process.stdout.write('  9. Formal Work binds one worker Session and one returned result beyond ordinary Inbox replies.\n')
+
+    const submittedProject = await service.submitProject(author, {
+      projectId: project.project.id,
+      summary: 'Evidence review complete',
+      body: 'The later observation calls for a fresh evidence check before reuse.',
+      doneWhenAssessment: 'The formal review was delivered and the conclusion is recorded.',
+    })
+    // Agents can only request rework; acceptance comes from an authenticated person through the host.
+    await assert.rejects(() => service.reviewProject(author, {
+      projectId: project.project.id, claimId: submittedProject.claim.id,
+      decision: 'accept', reason: 'An agent cannot accept its own Project.',
+    }), /host-authenticated human review/)
+    const reviewedProject = await service.reviewProjectAsHuman('demo-reviewer', {
+      projectId: project.project.id, claimId: submittedProject.claim.id,
+      expectedRevision: submittedProject.project.revision,
+      decision: 'accept', reason: 'The stated completion standard is met in this fictional scenario.',
+    }, principal => principal === 'demo-reviewer')
+    assert.equal(reviewedProject.project.status, 'accepted')
+    const projectReopened = await runtime.reopenProjectLedger()
+    assert.equal(projectReopened.get(project.project.id).acceptedClaimId, submittedProject.claim.id)
+    await projectReopened.close()
+    process.stdout.write('  10. Project submission records linked Work and a human acceptance across ledger reopen.\n')
+
+    await mkdir(ownerCwd, { recursive: true })
+    await writeFile(join(ownerCwd, 'review.txt'), 'The later observation needs a fresh evidence check before reuse.\n')
+    const worklog = (await service.recordWorklog(future, {
+      description: 'Evidence review completed',
+      body: 'The formal review found that the later observation needs a fresh evidence check.',
+      status: 'completed', idempotencyKey: `${scenario.id}-worklog-v1`,
+      files: ['review.txt'], workId: assignment.work.id, projectId: project.project.id,
+    })).worklog
+    assert.equal((await service.searchWorklogs(future, { query: 'review.txt' })).worklogs[0].id, worklog.id)
+    const worklogRead = await service.readWorklog(future, { sessionId: future.id })
+    assert.equal(worklogRead.source.status, 'verified')
+    assert.equal(worklogRead.files[0].status, 'current')
+    const worklogReopened = await runtime.reopenWorklogLedger()
+    assert.equal(worklogReopened.listVersions(future.id)[0].workId, assignment.work.id)
+    await worklogReopened.close()
+    process.stdout.write('  11. Session Worklog links formal Work, verifies source events, and tracks a Workspace file.\n')
+  } finally {
+    await runtime.ledger.close()
+    await runtime.workLedger.close()
+    await runtime.projectLedger.close()
+    await runtime.worklogLedger.close()
+    await rm(root, { recursive: true, force: true })
+  }
+}

package/examples/scenarios.mjs

@@ -0,0 +1,45 @@
+// Fictional teaching fixtures. These statements are not real business policies.
+export const scenarios = [
+  {
+    id: 'growth',
+    name: 'Growth analysis: comparable retention cohorts',
+    author: 'personal:analyst',
+    owner: 'role:growth-strategy',
+    kind: 'method',
+    description: 'Compare retention within matching acquisition cohorts.',
+    observation: 'The demo campaign changed the acquisition mix; the overall retention comparison was misleading.',
+    draft: 'Compare retention by acquisition cohort before explaining the overall change.',
+    reviewed: 'For this demo campaign, compare cohorts with the same acquisition channel and observation window. Report the cohort sizes and the overall result separately; do not infer causality from this comparison alone.',
+    confirmation: 'The second demo analysis separated a mix shift from within-cohort changes.',
+    contradiction: 'A later demo dataset lacks acquisition-channel labels.',
+    failure: 'Applying the procedure to incomplete demo cohorts produced an unsupported conclusion.',
+  },
+  {
+    id: 'engineering',
+    name: 'Engineering: reviewable configuration changes',
+    author: 'personal:developer',
+    owner: 'capability:config-review',
+    kind: 'method',
+    description: 'Verify a restorable backup before changing configuration.',
+    observation: 'A demo configuration edit could not be rolled back because the backup had not been checked.',
+    draft: 'Create and check a backup before changing a configuration file.',
+    reviewed: 'For the demo file-based configuration, save a versioned backup, restore it into an isolated directory, compare its content, and only then edit the original. This procedure does not cover live database migrations.',
+    confirmation: 'The next demo file change was restored successfully from its verified backup.',
+    contradiction: 'A later demo configuration includes generated files absent from the backup.',
+    failure: 'The incomplete demo backup could not recreate the generated configuration.',
+  },
+  {
+    id: 'support',
+    name: 'Support: a scoped product knowledge entry',
+    author: 'personal:support-agent',
+    owner: 'business:demo-store',
+    kind: 'knowledge',
+    description: 'Check order state before explaining the demo cancellation flow.',
+    observation: 'In the fictional demo store, an unshipped order and a shipped order use different cancellation flows.',
+    draft: 'Check whether the demo order has shipped before explaining cancellation.',
+    reviewed: 'Demo policy v1: for an unshipped order, explain the in-app cancellation flow; for a shipped order, hand off to a human support reviewer. This fixture describes a fictional product, not a general refund policy.',
+    confirmation: 'The next demo conversation used the order state to select the documented flow.',
+    contradiction: 'Demo policy v2 changes the flow for partially shipped orders.',
+    failure: 'The old demo entry gives an incorrect answer for a partially shipped order.',
+  },
+]