@zhchxiao123/dsh-devflow 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zhchxiao123
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/devflow/devflow/README.md
+README.md: 81a9147155d182c5fea6e7b2aebc3c6dd1cf1b9c
+README.zh.md: 8613bd2b93adf3b35f59ef39b4e61be1d1927813

package/README.md

@@ -0,0 +1,56 @@
+# @zhchxiao123/dsh-devflow
+
+English | [中文](README.zh.md)
+
+Service Definition for the **`ctx.devflow` capability seam**: file-backed task cards moving through a fixed development pipeline. This package owns the card vocabulary (`DevCard`, `DevStage`, journal entry types, the branded `DevflowCardId`) and the journal decode/replay shared by every consumer. Storage belongs to a provider such as [`dsh-devflow-filesystem`](../devflow-filesystem/README.md); the model-facing tools are [`dsh-tool-devflow`](../tool-devflow/README.md).
+
+## Service
+
+`DevflowStore` is an abstract Cordis `Service` on `ctx.devflow` (one implementation per context; a second registration throws).
+
+Every operation carries an explicit **devflow root** dimension: reads take an optional trailing `root`, requests carry an optional `root` field resolved into their spec, and `ClaimOptions` carries one for the lease. An omitted root falls back to the implementation's configured default, so single-root deployments never mention it; a returned `DevCard` always names the resolved `root` it belongs to, and cards with equal ids under different roots are different cards. Which root a caller passes is the caller's decision — the model tools and `/devflow` derive `<session cwd>/.devflow` from the invoking session, and the seam itself never maps workspaces to directories. The session-scoped reads are the one exception, because their caller is a browser that must never send paths: `listForSession` and `detailForSession` take the *viewing session's id* and resolve it host-side (the live or persisted session's header cwd, through the optionally composed `sessions`/`sessionPersistence` services) into the same root dimension; an unknown session is a stable rejection. `detailForSession` aggregates one card's read value, its decoded journal, and its lease holder (`DevCardDetail`) in a single round trip for the board's detail view, re-reading once when a transition tears the pair. [`dsh-devflow-web`](../devflow-web/README.md) is what puts those two on a browser channel.
+
+| Method | Behavior |
+|---|---|
+| `list(filter?, root?)` | One root's cards ordered by id; `filter.stage` narrows to one current location, `filter.parent` to one card's children. |
+| `read(id, root?)` | One card with journal-derived state; a missing card throws. |
+| `history(id, root?)` | The card's complete decoded journal, oldest first, stream-validated like a read (a structurally invalid journal fails loudly, naming file and line). |
+| `holder(id, root?)` | The card's current lease holder (`ClaimHolder`: owner plus last heartbeat), `undefined` while unclaimed; a corrupt claim record fails loudly. |
+| `resolveCreate(request)` | Explicit defaulting: turns a caller `CreateRequest` (title, Markdown body, optional slug, actor, optional parent, optional root) into the fully specified `CreateSpec` — the slug derived from the title when omitted, the root resolved, plus the creation timestamp. |
+| `create(spec)` | Creates one card: parent validation → sequence-number allocation (continuing past archived cards, so an id is never reissued) → exclusive directory creation → the journal's first `created` entry (the only commit point) → projection write → `devflow/card-created`. Domain rejections resolve `ok: false` with a stable code (`empty-title`, `invalid-slug`, `exists`, `unknown-parent`, `nested-parent`, `parent-settled`); only infrastructure failures reject. |
+| `resolve(request)` | Explicit defaulting: turns a caller `TransitionRequest` into the fully specified `TransitionSpec` with its resolved root and commit timestamp. |
+| `transition(spec)` | Commits one move: revision CAS → edge check → `devflow/transition` waterfall → journal append (the only commit point) → projection rewrite → `devflow/stage-changed`. Domain rejections resolve `ok: false` with a stable code (`revision-mismatch`, `illegal-edge`, `reason-required`, `vetoed`); only infrastructure failures reject. |
+| `claim(id, owner, options?)` | Takes the card's exclusive lease; a held lease resolves with the current holder, unless `options.staleAfterMs` marks its heartbeat lapsed — then the lease is taken over with a journaled `claim-expired` entry. |
+| `attachArtifact(request)` | Registers a stage deliverable in the journal against the current stage; rejected while `blocked` or `done`, with the same revision check as `transition`. |
+| `archiveDone(root?)` | Moves every archivable `done` card of one root out of the active set into that root's archive, keyed by the month of its last journal entry; a decomposed requirement archives as one family (a done child waits for its parent, then joins the parent's month bucket). Archived cards leave `list` but keep their complete journal. Returns the archived ids in id order. |
+
+Current state always comes from journal replay; a card file's frontmatter is a rebuildable projection. Implementations must fail a read loudly on a structurally invalid journal (naming file and line), warn-and-override on projection drift, and publish state and notifications only after the journal committed. Legal edges (`isLegalTransition`): the pipeline order, rework from `reviewing`/`testing` back to `developing`, `blocked` entry from any non-terminal location, and recovery only to the exact interrupted stage. A rework edge (`isReworkEdge`) without a `reason` is rejected `reason-required`, so the next holder always learns what to fix.
+
+## Stages and journal
+
+`DevStage` is the closed union `draft | designing | ready | developing | reviewing | testing | done`; `blocked` is a bypass location that remembers the stage it interrupted (`CardLocation = DevStage | 'blocked'`). The journal entry union is `created | transition | artifact | claim-expired`, decoded by `decodeJournalEntry` (the durable-boundary validator) and folded by `foldJournal`, which enforces: contiguous revisions from 1, `created` first and only first, transitions departing the current location, and blocked recovery returning exactly to the remembered stage.
+
+A requirement too big for one card becomes a **parent card plus one child card per slice**. The edge is the `created` entry's `parent`, so it is fixed at creation, replayable, and never re-pointed; `foldJournal` surfaces it as `DevCard.parent` and the frontmatter `parent:` is its projection. The breakdown is one level deep — a card carrying `parent` is never itself a parent — and parent and children always share a root. Which cards may take children is the provider's creation-time decision (`unknown-parent`, `nested-parent`, `parent-settled`); the seam holds no rule about how a parent's own stage relates to its children's.
+
+## Events
+
+| Event | Mode | Meaning |
+|---|---|---|
+| `devflow/transition` | `waterfall` | Single-decision pipeline before the commit, dispatched with the complete `TransitionAttempt` (spec plus departure); a policy listener that owns the decision returns `{ allowed: false, reason }` without calling `next()`. [`dsh-devflow-gates`](../devflow-gates/README.md) runs command policies here. |
+| `devflow/card-created` | `emit` | A new card entered the active set: its journal committed the first `created` entry. |
+| `devflow/stage-changed` | `emit` | A card settled at a new location after a committed transition. |
+
+The invariant companion validates the emit streams: `card-created` announces only fresh drafts at revision 1 for never-seen ids and never hangs a card under one the stream already knows to be a child, and per card, `stage-changed` revisions strictly increase while every notification reports an actual move.
+
+## Model Experience
+
+Indirectly, through the model-facing tools in dsh-tool-devflow: the service interface itself registers no prompt or schema.
+
+#### KV Cache effect
+
+None; this package neither assembles nor sends a provider request.
+
+## Known Limitations and Deferred Work
+
+- **The archive is write-only** — `archiveDone` removes done cards from the active set; no seam operation lists or restores archived cards.
+- **No card editing after creation** — `create` fixes the title and body once; changing a card's content remains a direct edit of its `card.md` in the provider's on-disk format.

package/README.zh.md

@@ -0,0 +1,56 @@
+# @zhchxiao123/dsh-devflow
+
+[English](README.md) | 中文
+
+**`ctx.devflow` 能力缝的 Service Definition**：以文件为载体、沿固定研发流水线移动的任务卡。本包拥有卡片词汇（`DevCard`、`DevStage`、journal 条目类型、branded 的 `DevflowCardId`）与供所有消费者共用的 journal 解码/回放。存储属于 [`dsh-devflow-filesystem`](../devflow-filesystem/README.zh.md) 这样的 Provider；模型工具是 [`dsh-tool-devflow`](../tool-devflow/README.zh.md)。
+
+## 服务
+
+`DevflowStore` 是注册在 `ctx.devflow` 上的抽象 Cordis `Service`（每个 context 只允许一个实现；重复注册抛错）。
+
+每个操作都携带显式的 **devflow root** 维度：读取带可选的尾参 `root`，请求携带可选的 `root` 字段并解析进各自的 spec，`ClaimOptions` 为租约携带一个。省略的 root 回退到实现配置的默认根，单根部署因此完全不用提它；返回的 `DevCard` 永远标明其所属的已解析 `root`，不同根下 id 相同的卡是不同的卡。调用方传哪个根由调用方决定——模型工具与 `/devflow` 从发起会话推导 `<会话 cwd>/.devflow`，缝本身从不做工作区到目录的映射。按会话取值的那两个读是唯一的例外，因为它们的调用方是绝不能发送路径的浏览器：`listForSession` 与 `detailForSession` 接收*查看会话的 id*，在 host 侧（经可选组合的 `sessions`/`sessionPersistence` 服务读取活跃或持久化会话头部的 cwd）解析成同一个 root 维度；未知会话是稳定拒绝。`detailForSession` 把一张卡的读值、已解码 journal 与租约持有者(`DevCardDetail`)聚合为一次往返，供看板的详情视图使用，并在流转撕开这对读取时重读一次。把这两个读搬到浏览器通道上的是 [`dsh-devflow-web`](../devflow-web/README.zh.md)。
+
+| 方法 | 行为 |
+|---|---|
+| `list(filter?, root?)` | 一个根的卡片，按 id 排序；`filter.stage` 收窄到一个当前位置，`filter.parent` 收窄到一张卡的子卡。 |
+| `read(id, root?)` | 一张带 journal 推导状态的卡片；卡片缺失抛错。 |
+| `history(id, root?)` | 卡片完整的已解码 journal,从旧到新,流校验与读取一致(结构非法的 journal 指明文件与行号 fail-loud)。 |
+| `holder(id, root?)` | 卡片当前租约持有者(`ClaimHolder`:owner 加最后心跳),未认领为 `undefined`;损坏的 claim 记录 fail-loud。 |
+| `resolveCreate(request)` | 显式默认值补全：把调用方的 `CreateRequest`（标题、Markdown 正文、可选 slug、actor、可选 parent、可选 root）变成完全确定的 `CreateSpec`——slug 省略时由标题推导，root 解析定型，并盖上创建时间戳。 |
+| `create(spec)` | 创建一张卡：父卡校验 → 顺序号分配（越过归档卡续排，id 永不复用）→ 独占目录创建 → journal 首条 `created`（唯一提交点）→ 投影写入 → `devflow/card-created`。领域拒绝以稳定 code（`empty-title`、`invalid-slug`、`exists`、`unknown-parent`、`nested-parent`、`parent-settled`）解析为 `ok: false`；仅基础设施故障才 reject。 |
+| `resolve(request)` | 显式默认值补全：把调用方的 `TransitionRequest` 变成完全确定的 `TransitionSpec`，带已解析的 root 与提交时间戳。 |
+| `transition(spec)` | 提交一次移动：revision CAS → 边合法性 → `devflow/transition` waterfall → journal 追加（唯一提交点）→ 投影重写 → `devflow/stage-changed`。领域拒绝以稳定 code（`revision-mismatch`、`illegal-edge`、`reason-required`、`vetoed`）解析为 `ok: false`；仅基础设施故障才 reject。 |
+| `claim(id, owner, options?)` | 取得卡片的独占租约；租约已被持有时解析出当前持有者——除非 `options.staleAfterMs` 判定其心跳已过期，此时接管租约并以 `claim-expired` 条目入 journal。 |
+| `attachArtifact(request)` | 按当前阶段在 journal 登记一个阶段产物；`blocked` 或 `done` 时拒绝，revision 检查与 `transition` 相同。 |
+| `archiveDone(root?)` | 把一个根中每张可归档的 `done` 卡按其最后一条 journal 的月份移出活跃集合、归入该根的档案；拆分需求以族为单位归档（已完成的子卡等待父卡，随后并入父卡的月份桶）。归档卡从 `list` 消失但保留完整 journal。按 id 顺序返回归档的 id。 |
+
+当前状态永远来自 journal 回放；卡片文件的 frontmatter 是可重建的投影。实现必须在 journal 结构非法时读取即失败（指明文件与行号），在投影漂移时告警并覆盖，且只在 journal 提交之后发布状态与通知。合法边（`isLegalTransition`）：流水线顺序、`reviewing`/`testing` 打回 `developing`、任意非终态进入 `blocked`、且只能恢复到被打断的那个阶段。无 `reason` 的打回边（`isReworkEdge`）以 `reason-required` 拒绝，下一个持有者永远知道要修什么。
+
+## 阶段与 journal
+
+`DevStage` 是闭合联合 `draft | designing | ready | developing | reviewing | testing | done`；`blocked` 是记住被打断阶段的旁路位置（`CardLocation = DevStage | 'blocked'`）。journal 条目联合为 `created | transition | artifact | claim-expired`，由 `decodeJournalEntry`（持久化边界校验器）解码、`foldJournal` 折叠，后者强制：revision 从 1 连续、`created` 必须且只能是首条、transition 必须从当前位置出发、blocked 恢复必须回到被记住的阶段。
+
+一张卡装不下的大需求拆成**一张父卡加每个切片一张子卡**。这条边就是 `created` 条目的 `parent`，因此创建时即固定、可回放、永不改指；`foldJournal` 把它折出为 `DevCard.parent`，frontmatter 的 `parent:` 是其投影。拆分只有一层——带 `parent` 的卡自身永远不会成为父卡——父卡与子卡始终同根。哪些卡可以接子卡是 provider 的创建期决策（`unknown-parent`、`nested-parent`、`parent-settled`）；缝本身不持有"父卡阶段与子卡阶段如何关联"的任何规则。
+
+## 事件
+
+| 事件 | 模式 | 含义 |
+|---|---|---|
+| `devflow/transition` | `waterfall` | 提交前的单决策管线，以完整 `TransitionAttempt`（spec 加出发位置）分发；拥有决策的策略监听器不调 `next()` 直接返回 `{ allowed: false, reason }`。[`dsh-devflow-gates`](../devflow-gates/README.zh.md) 在此运行命令策略。 |
+| `devflow/card-created` | `emit` | 一张新卡进入活跃集合：其 journal 提交了首条 `created`。 |
+| `devflow/stage-changed` | `emit` | 一次已提交的流转后，卡片落在新位置。 |
+
+不变量伴生插件校验 emit 流：`card-created` 只宣告从未见过的 id、处于 draft 且 revision 为 1 的新卡，且绝不把新卡挂到流中已知为子卡的卡下；每张卡的 `stage-changed` revision 严格递增，且每次通知都报告真实移动。
+
+## Model Experience
+
+Indirectly, through the model-facing tools in dsh-tool-devflow: the service interface itself registers no prompt or schema.
+
+#### KV Cache effect
+
+None; this package neither assembles nor sends a provider request.
+
+## Known Limitations and Deferred Work
+
+- **档案只写不读** — `archiveDone` 把 done 卡移出活跃集合；没有缝操作能列出或恢复归档卡。
+- **创建后无卡片编辑** — `create` 一次性固定标题与正文；改动卡片内容仍是按 Provider 磁盘格式直接编辑其 `card.md`。

package/lib/index.js

@@ -0,0 +1,325 @@
+import { join } from "node:path";
+import { Service } from "@deepseek-ai/cordis";
+//#region packages/devflow/src/stages.ts
+/** The pipeline stages in flow order; `blocked` is a bypass, not a member. */
+const DEV_STAGES = [
+	"draft",
+	"designing",
+	"ready",
+	"developing",
+	"reviewing",
+	"testing",
+	"done"
+];
+/**
+* Narrow an unknown value to a pipeline stage.
+* @param value - the candidate value.
+* @returns `true` when `value` is one of {@link DEV_STAGES}.
+*/
+function isDevStage(value) {
+	return typeof value === "string" && DEV_STAGES.includes(value);
+}
+/**
+* Narrow an unknown value to a card location (a stage or `blocked`).
+* @param value - the candidate value.
+* @returns `true` when `value` is a stage or the `blocked` bypass.
+*/
+function isCardLocation(value) {
+	return value === "blocked" || isDevStage(value);
+}
+/**
+* Brand a raw string as a {@link DevflowCardId}. The id equals the card's
+* directory name; construction lives here because this package owns the brand.
+* @param value - the card directory name.
+* @returns the branded id.
+*/
+function DevflowCardId(value) {
+	return value;
+}
+/** Forward and rework edges of the pipeline; `blocked` legality lives in {@link isLegalTransition}. */
+const FLOW = {
+	draft: ["designing"],
+	designing: ["ready"],
+	ready: ["developing"],
+	developing: ["reviewing"],
+	reviewing: ["testing", "developing"],
+	testing: ["done", "developing"],
+	done: []
+};
+/**
+* Whether one stage move is a legal edge of the state machine.
+*
+* Main flow follows the pipeline order; `reviewing` and `testing` may rework
+* to `developing`; any non-terminal location may enter `blocked`; a blocked
+* card may only recover to the exact stage it interrupted.
+* @param from - the card's current location.
+* @param to - the requested target location.
+* @param blockedFrom - the remembered origin stage while `from` is `blocked`.
+* @returns `true` when the move is a legal edge.
+*/
+function isLegalTransition(from, to, blockedFrom) {
+	if (from === to) return false;
+	if (from === "blocked") return to === blockedFrom;
+	if (to === "blocked") return from !== "done";
+	return FLOW[from].includes(to);
+}
+/**
+* Whether a legal edge moves the card backwards (a rework). Rework edges
+* require a recorded `reason` so the next holder knows what to fix.
+* @param from - the departing location.
+* @param to - the target location.
+* @returns `true` for `reviewing -> developing` and `testing -> developing`.
+*/
+function isReworkEdge(from, to) {
+	return to === "developing" && (from === "reviewing" || from === "testing");
+}
+//#endregion
+//#region packages/devflow/src/journal.ts
+/**
+* Journal decoding and replay for the devflow seam. The journal is the
+* authoritative card history; the card file's frontmatter is a rebuildable
+* projection. Both the filesystem provider and the invariant companion fold
+* entries through this module so every consumer derives identical state.
+* @module @zhchxiao123/dsh-devflow/src/journal
+*/
+/**
+* Decode one parsed journal value into a {@link DevflowJournalEntry}.
+*
+* This is the durable-boundary validator: journal lines come from a file that
+* humans and other processes may write, so every field is checked and a bad
+* entry throws instead of being skipped.
+* @param value - one JSON-parsed journal line.
+* @returns the validated entry.
+* @throws {Error} naming the first violated field.
+*/
+function decodeJournalEntry(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new Error("journal entry must be a JSON object");
+	const entry = value;
+	const rev = entry.rev;
+	if (typeof rev !== "number" || !Number.isInteger(rev) || rev < 1) throw new Error("journal entry field \"rev\" must be a positive integer");
+	if (typeof entry.at !== "string" || entry.at.length === 0) throw new Error("journal entry field \"at\" must be a non-empty string");
+	switch (entry.type) {
+		case "created": return {
+			rev,
+			at: entry.at,
+			type: "created",
+			by: decodeActor(entry.by),
+			...decodeOptionalCardId(entry, "parent")
+		};
+		case "transition":
+			if (!isCardLocation(entry.from)) throw new Error("transition field \"from\" must be a stage or \"blocked\"");
+			if (!isCardLocation(entry.to)) throw new Error("transition field \"to\" must be a stage or \"blocked\"");
+			return {
+				rev,
+				at: entry.at,
+				type: "transition",
+				from: entry.from,
+				to: entry.to,
+				...entry.by !== void 0 ? { by: decodeActor(entry.by) } : {},
+				...decodeOptionalString(entry, "reason"),
+				...entry.gate !== void 0 ? { gate: decodeGate(entry.gate) } : {}
+			};
+		case "artifact":
+			if (typeof entry.path !== "string" || entry.path.length === 0) throw new Error("artifact field \"path\" must be a non-empty string");
+			if (!isDevStage(entry.stage)) throw new Error(`artifact field "stage" must be one of ${DEV_STAGES.join(", ")}`);
+			return {
+				rev,
+				at: entry.at,
+				type: "artifact",
+				path: entry.path,
+				stage: entry.stage,
+				...entry.by !== void 0 ? { by: decodeActor(entry.by) } : {}
+			};
+		case "claim-expired":
+			if (entry.previousOwner === void 0) throw new Error("claim-expired field \"previousOwner\" is required");
+			return {
+				rev,
+				at: entry.at,
+				type: "claim-expired",
+				previousOwner: decodeActor(entry.previousOwner),
+				by: decodeActor(entry.by)
+			};
+		default: throw new Error(`journal entry field "type" must be created, transition, artifact, or claim-expired (got ${JSON.stringify(entry.type)})`);
+	}
+}
+/**
+* Replay a complete journal into the card's current state.
+*
+* Validates the structural invariants of the durable stream: revisions are the
+* contiguous sequence 1..n, the first entry is `created`, every transition
+* departs from the current location, a move to `blocked` remembers its origin,
+* and the matching recovery returns exactly there.
+* @param entries - decoded entries in file order.
+* @returns the folded card state.
+* @throws {Error} naming the first violated invariant and its entry revision.
+*/
+function foldJournal(entries) {
+	if (entries.length === 0) throw new Error("journal is empty; every card starts with a \"created\" entry");
+	const state = {
+		stage: "draft",
+		revision: 0,
+		artifacts: []
+	};
+	for (const [index, entry] of entries.entries()) {
+		if (entry.rev !== index + 1) throw new Error(`journal entry ${index + 1} carries rev ${entry.rev}; revisions must be contiguous from 1`);
+		if (index === 0) {
+			if (entry.type !== "created") throw new Error("journal entry 1 must be \"created\"");
+			if (entry.parent !== void 0) state.parent = entry.parent;
+			state.revision = entry.rev;
+			continue;
+		}
+		switch (entry.type) {
+			case "created": throw new Error(`journal entry rev ${entry.rev} repeats "created"`);
+			case "transition":
+				if (entry.from !== state.stage) throw new Error(`transition rev ${entry.rev} departs from "${entry.from}" but the card is at "${state.stage}"`);
+				if (entry.to === state.stage) throw new Error(`transition rev ${entry.rev} does not move the card (already at "${entry.to}")`);
+				if (entry.to === "blocked") state.blockedFrom = entry.from;
+				else if (state.stage === "blocked") {
+					if (entry.to !== state.blockedFrom) throw new Error(`transition rev ${entry.rev} recovers to "${entry.to}" but the card blocked from "${state.blockedFrom}"`);
+					delete state.blockedFrom;
+				}
+				state.stage = entry.to;
+				state.revision = entry.rev;
+				break;
+			case "artifact":
+				state.artifacts.push(entry.path);
+				state.revision = entry.rev;
+				break;
+			case "claim-expired": state.revision = entry.rev;
+		}
+	}
+	return state;
+}
+function decodeGate(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new Error("transition field \"gate\" must be a JSON object");
+	const gate = value;
+	if (gate.approvedBy === void 0) throw new Error("transition field \"gate\" requires \"approvedBy\"");
+	return { approvedBy: decodeActor(gate.approvedBy) };
+}
+function decodeActor(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new Error("actor must be a JSON object");
+	const actor = value;
+	switch (actor.kind) {
+		case "human": return {
+			kind: "human",
+			...decodeOptionalString(actor, "name")
+		};
+		case "agent": return {
+			kind: "agent",
+			...decodeOptionalString(actor, "session")
+		};
+		case "command": return {
+			kind: "command",
+			...decodeOptionalString(actor, "name")
+		};
+		default: throw new Error(`actor field "kind" must be human, agent, or command (got ${JSON.stringify(actor.kind)})`);
+	}
+}
+function decodeOptionalCardId(record, key) {
+	const value = record[key];
+	if (value === void 0) return {};
+	if (typeof value !== "string" || value.length === 0) throw new Error(`field "${key}" must be a non-empty card id when present`);
+	return { [key]: DevflowCardId(value) };
+}
+function decodeOptionalString(record, key) {
+	const value = record[key];
+	if (value === void 0) return {};
+	if (typeof value !== "string" || value.length === 0) throw new Error(`field "${key}" must be a non-empty string when present`);
+	return { [key]: value };
+}
+//#endregion
+//#region packages/devflow/src/index.ts
+/**
+* Service Definition of the `ctx.devflow` capability seam: file-backed task
+* cards whose stage moves through a fixed pipeline. This package owns the card
+* vocabulary and the journal decode/replay used by every consumer. Storage
+* mechanics belong to a provider such as `@zhchxiao123/dsh-devflow-filesystem`;
+* model-facing tools belong to `@zhchxiao123/dsh-devflow-tool`.
+* @module @zhchxiao123/dsh-devflow
+*/
+/**
+* Abstract task-card store registered as `ctx.devflow` (one implementation per
+* context; loading a second throws, cordis' standard duplicate-service
+* behavior). Subclass, implement the abstract methods, and load the subclass
+* as a plugin.
+*
+* Implementations must honor these read-side semantics:
+* - Current state comes from journal replay ({@link foldJournal}); the card
+*   file's frontmatter is a projection. On disagreement the journal wins and
+*   the drift is warned, never silently adopted.
+* - A structurally invalid journal fails the read loudly, naming the file and
+*   line; a card is never silently skipped.
+*/
+var DevflowStore = class extends Service {
+	constructor(ctx) {
+		super(ctx, "devflow");
+	}
+	/**
+	* {@link list} scoped to a viewing session's workspace, the face every
+	* browser channel reads through.
+	* @param filter - optional narrowing; omitted lists every card.
+	* @param sessionId - the viewing session; its workspace resolves host-side
+	*   to the devflow root, so the wire never carries a file path. Omitted
+	*   lists the default root.
+	* @returns cards ordered by id.
+	*/
+	async listForSession(filter, sessionId) {
+		return this.list(filter, await this.sessionRoot(sessionId));
+	}
+	/**
+	* One card's detail scoped to a viewing session's workspace: the read value,
+	* its complete decoded journal, and the current lease holder in one round
+	* trip.
+	* @param id - the card id (its directory name).
+	* @param sessionId - the viewing session; resolved like {@link listForSession}.
+	* @returns the aggregated detail; `holder` is absent while the card is unclaimed.
+	*/
+	async detailForSession(id, sessionId) {
+		const root = await this.sessionRoot(sessionId);
+		let card = await this.read(id, root);
+		let entries = await this.history(id, root);
+		if (entries.at(-1)?.rev !== card.stageRevision) {
+			card = await this.read(id, root);
+			entries = await this.history(id, root);
+		}
+		const holder = await this.holder(id, root);
+		return {
+			card,
+			entries,
+			...holder === void 0 ? {} : { holder }
+		};
+	}
+	/**
+	* Resolve a viewing session into its workspace devflow root: the live or
+	* persisted session's header cwd maps to `<cwd>/.devflow`, and a session
+	* without a cwd derives no root (the implementation default applies). The
+	* browser sends only the session id — this host-side step is what keeps
+	* a root off the wire the browser can choose.
+	* @param sessionId - the viewing session, or `undefined` for the default root.
+	* @returns the derived root, or `undefined` when none derives.
+	* @throws {Error} for an unknown session, or when no session service is composed.
+	*/
+	async sessionRoot(sessionId) {
+		if (sessionId === void 0) return void 0;
+		const id = sessionId;
+		const live = this.ctx.get("sessions")?.get(id);
+		if (live !== void 0) return rootOfCwd(live.header.cwd);
+		const persistence = this.ctx.get("sessionPersistence");
+		if (persistence === void 0) throw new Error(`devflow: cannot resolve session ${sessionId}: no session service is composed`);
+		let cwd;
+		try {
+			cwd = (await persistence.inspect(id)).meta.cwd;
+		} catch (error) {
+			throw new Error(`devflow: unknown session ${sessionId}`, { cause: error });
+		}
+		return rootOfCwd(cwd);
+	}
+};
+/** The workspace's devflow root for a session cwd; no cwd derives no root. */
+function rootOfCwd(cwd) {
+	return cwd === void 0 ? void 0 : join(cwd, ".devflow");
+}
+//#endregion
+export { DEV_STAGES, DevflowCardId, DevflowStore, DevflowStore as default, decodeJournalEntry, foldJournal, isCardLocation, isDevStage, isLegalTransition, isReworkEdge };
+
+//# sourceMappingURL=index.js.map

package/lib/invariant.js

@@ -0,0 +1,42 @@
+//#region packages/devflow/src/invariant.ts
+const PACKAGE_NAME = "@zhchxiao123/dsh-devflow";
+/** Cordis companion plugin name. */
+const name = "devflow-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* Validate the devflow notification streams: `devflow/card-created` announces
+* only fresh drafts at revision 1 for ids the stream has never seen and never
+* nests a breakdown two levels deep, and per card, `devflow/stage-changed`
+* revisions strictly increase while every notification reports an actual move.
+*/
+const install = (ctx, fail) => {
+	const lastRevision = /* @__PURE__ */ new Map();
+	const children = /* @__PURE__ */ new Set();
+	const key = (card) => `${card.root} ${card.id}`;
+	ctx.on("devflow/card-created", (card) => {
+		if (card.stage !== "draft" || card.stageRevision !== 1) fail(`devflow/card-created for card ${card.id} reports "${card.stage}" at rev ${card.stageRevision}; a card must enter the board as "draft" at revision 1`);
+		if (lastRevision.has(key(card))) fail(`devflow/card-created repeats card ${card.id} of root ${card.root}; an id is never reissued`);
+		if (card.parent !== void 0) {
+			if (children.has(`${card.root} ${card.parent}`)) fail(`devflow/card-created hangs card ${card.id} under ${card.parent}, which is itself a child; the breakdown is one level deep`);
+			children.add(key(card));
+		}
+		lastRevision.set(key(card), card.stageRevision);
+	}, { global: true });
+	ctx.on("devflow/stage-changed", (card, from) => {
+		if (card.stage === from) fail(`devflow/stage-changed for card ${card.id} reports no move (still at "${from}")`);
+		const previous = lastRevision.get(key(card));
+		if (previous !== void 0 && card.stageRevision <= previous) fail(`devflow/stage-changed for card ${card.id} carries rev ${card.stageRevision} after rev ${previous}; revisions must strictly increase`);
+		lastRevision.set(key(card), card.stageRevision);
+	}, { global: true });
+};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };
+
+//# sourceMappingURL=invariant.js.map

package/lib/types/client.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Client-namespace projection of the devflow domain: a pure re-export of the
+ * package's types outlet. Client code imports ONLY the client namespace
+ * (repo discipline), so `./client` projects the same single-source content
+ * `./types` serves to host consumers — zero duplication.
+ *
+ * @module @zhchxiao123/dsh-devflow/client
+ */
+export type * from './types.ts';
+//# sourceMappingURL=client.d.ts.map

package/lib/types/client.js

@@ -0,0 +1,10 @@
+/**
+ * Client-namespace projection of the devflow domain: a pure re-export of the
+ * package's types outlet. Client code imports ONLY the client namespace
+ * (repo discipline), so `./client` projects the same single-source content
+ * `./types` serves to host consumers — zero duplication.
+ *
+ * @module @zhchxiao123/dsh-devflow/client
+ */
+export {};
+//# sourceMappingURL=client.js.map