@zhchxiao123/dsh-devflow 0.1.0

package/lib/types/index.d.ts

@@ -0,0 +1,155 @@
+/**
+ * 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
+ */
+import { Context, Service } from '@deepseek-ai/cordis';
+import type { ArtifactRequest, ArtifactResult, CardFilter, ClaimHolder, ClaimOptions, ClaimResult, CreateRequest, CreateResult, CreateSpec, DevActor, DevCard, DevCardDetail, DevflowCardId, DevflowJournalEntry, TransitionRequest, TransitionResult, TransitionSpec } from './types.ts';
+export type * from './types.ts';
+export { DEV_STAGES, DevflowCardId, isCardLocation, isDevStage, isLegalTransition, isReworkEdge } from './stages.ts';
+export { decodeJournalEntry, foldJournal } from './journal.ts';
+export type { JournalFoldState } from './journal.ts';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        devflow: DevflowStore;
+    }
+}
+/**
+ * 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.
+ */
+export declare abstract class DevflowStore extends Service {
+    constructor(ctx: Context);
+    /**
+     * List the cards in the active set of one root.
+     * @param filter - optional narrowing; omitted lists every card.
+     * @param root - devflow root to list; omitted uses the implementation's default root.
+     * @returns cards ordered by id.
+     */
+    abstract list(filter?: CardFilter, root?: string): Promise<DevCard[]>;
+    /**
+     * Read one card.
+     * @param id - the card id (its directory name).
+     * @param root - devflow root holding the card; omitted uses the implementation's default root.
+     * @returns the card with journal-derived current state.
+     */
+    abstract read(id: DevflowCardId, root?: string): Promise<DevCard>;
+    /**
+     * Read one card's complete decoded journal, in revision order. The stream
+     * is validated like a read: a structurally invalid journal fails loudly,
+     * naming the file and line.
+     * @param id - the card id (its directory name).
+     * @param root - devflow root holding the card; omitted uses the implementation's default root.
+     * @returns the decoded entries, oldest first.
+     */
+    abstract history(id: DevflowCardId, root?: string): Promise<DevflowJournalEntry[]>;
+    /**
+     * Read the card's current lease holder.
+     * @param id - the card id (its directory name).
+     * @param root - devflow root holding the card; omitted uses the implementation's default root.
+     * @returns the holder facts, or `undefined` while the card is unclaimed; a
+     *   corrupt claim record fails loudly.
+     */
+    abstract holder(id: DevflowCardId, root?: string): Promise<ClaimHolder | undefined>;
+    /**
+     * Apply implementation-owned defaults to a creation request: the slug when
+     * omitted, the devflow root when omitted, and the creation timestamp.
+     * @param request - the caller's request.
+     * @returns the fully specified spec to hand to {@link create}.
+     */
+    abstract resolveCreate(request: CreateRequest): CreateSpec;
+    /**
+     * Create one card in the active set: sequence-number allocation, the
+     * exclusive card-directory creation, the journal's first `created` entry
+     * (the only commit point), the projection write, then `devflow/card-created`.
+     * Sequence numbers continue past archived cards, so an id is never reissued.
+     * @param spec - a resolved spec from {@link resolveCreate}, never a raw request.
+     * @returns the outcome; domain rejections resolve with `ok: false`.
+     */
+    abstract create(spec: CreateSpec): Promise<CreateResult>;
+    /**
+     * Apply implementation-owned defaults to a transition request: the devflow
+     * root when omitted and the commit timestamp.
+     * @param request - the caller's request.
+     * @returns the fully specified spec to hand to {@link transition}.
+     */
+    abstract resolve(request: TransitionRequest): TransitionSpec;
+    /**
+     * Commit one stage move: revision check, edge check, the
+     * `devflow/transition` waterfall, the journal append (the only commit
+     * point), the projection rewrite, then `devflow/stage-changed`. State and
+     * notifications publish only after the journal committed.
+     * @param spec - a resolved spec from {@link resolve}, never a raw request.
+     * @returns the outcome; domain rejections resolve with `ok: false`.
+     */
+    abstract transition(spec: TransitionSpec): Promise<TransitionResult>;
+    /**
+     * Take the card's exclusive lease.
+     * @param id - the card to claim.
+     * @param owner - the prospective holder, recorded in the lease.
+     * @param options - staleness takeover policy and root; omitted never takes
+     *   over and uses the implementation's default root.
+     * @returns the live handle, or the current holder when the lease is taken.
+     */
+    abstract claim(id: DevflowCardId, owner: DevActor, options?: ClaimOptions): Promise<ClaimResult>;
+    /**
+     * Register a stage deliverable in the card's journal against its current
+     * stage. A blocked card cannot register artifacts, and the revision check
+     * mirrors {@link transition}.
+     * @param request - card, artifact path, expected revision, and actor.
+     * @returns the outcome; domain rejections resolve with `ok: false`.
+     */
+    abstract attachArtifact(request: ArtifactRequest): Promise<ArtifactResult>;
+    /**
+     * Move every `done` card of one root out of the active set into that root's
+     * archive, keyed by the month of its last journal entry. Archived cards
+     * leave {@link list} but keep their complete journal.
+     * @param root - devflow root to archive; omitted uses the implementation's default root.
+     * @returns the archived card ids, in id order.
+     */
+    abstract archiveDone(root?: string): Promise<DevflowCardId[]>;
+    /**
+     * {@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.
+     */
+    listForSession(filter?: CardFilter, sessionId?: string): Promise<DevCard[]>;
+    /**
+     * 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.
+     */
+    detailForSession(id: DevflowCardId, sessionId?: string): Promise<DevCardDetail>;
+    /**
+     * 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.
+     */
+    protected sessionRoot(sessionId: string | undefined): Promise<string | undefined>;
+}
+export default DevflowStore;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/index.js

@@ -0,0 +1,104 @@
+/**
+ * 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
+ */
+import { join } from 'node:path';
+import { Service } from '@deepseek-ai/cordis';
+export { DEV_STAGES, DevflowCardId, isCardLocation, isDevStage, isLegalTransition, isReworkEdge } from "./stages.js";
+export { decodeJournalEntry, foldJournal } from "./journal.js";
+/**
+ * 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.
+ */
+export class DevflowStore 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);
+        // The card and its journal are two reads of one file; a transition landing
+        // between them would tear the aggregate (revisions are contiguous from 1,
+        // so the last entry's rev must equal the card's). One re-read absorbs the
+        // race; a still-moving card ships its newest pair and the next forwarded
+        // event refetches anyway.
+        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 === undefined ? {} : { 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 === undefined)
+            return undefined;
+        // The wire delivers the id as a validated string; the brand is this
+        // process's own session vocabulary.
+        const id = sessionId;
+        const live = this.ctx.get('sessions')?.get(id);
+        if (live !== undefined)
+            return rootOfCwd(live.header.cwd);
+        const persistence = this.ctx.get('sessionPersistence');
+        if (persistence === undefined) {
+            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 === undefined ? undefined : join(cwd, '.devflow');
+}
+export default DevflowStore;
+//# sourceMappingURL=index.js.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,13 @@
+/** Package-owned devflow event-stream invariants. @module @zhchxiao123/dsh-devflow/invariant */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "devflow-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/invariant.js

@@ -0,0 +1,51 @@
+/** Package-owned devflow event-stream invariants. @module @zhchxiao123/dsh-devflow/invariant */
+const PACKAGE_NAME = '@zhchxiao123/dsh-devflow';
+/** Cordis companion plugin name. */
+export const name = 'devflow-invariant';
+/** Service required before the companion can reserve package ownership. */
+export 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 = new Map();
+    const children = new Set();
+    // Cards from different roots may share an id; the stream relations hold
+    // per root + id, the same key every store and driver book-keeping uses.
+    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 !== undefined) {
+            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 !== undefined && 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.
+ */
+export const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//# sourceMappingURL=invariant.js.map

package/lib/types/journal.d.ts

@@ -0,0 +1,46 @@
+/**
+ * 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
+ */
+import { DevflowCardId } from './stages.ts';
+import type { CardLocation, DevStage, DevflowJournalEntry } from './types.ts';
+/** Card state derived by {@link foldJournal}; the read-side authority. */
+export interface JournalFoldState {
+    /** Current location after the last entry. */
+    stage: CardLocation;
+    /** Revision of the last entry; the optimistic-concurrency token. */
+    revision: number;
+    /** The stage a blocked card returns to; present exactly while `stage` is `blocked`. */
+    blockedFrom?: DevStage;
+    /** The card this one decomposes, from the `created` entry; absent for a top-level card. */
+    parent?: DevflowCardId;
+    /** Artifact paths in registration order. */
+    artifacts: string[];
+}
+/**
+ * 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.
+ */
+export declare function decodeJournalEntry(value: unknown): DevflowJournalEntry;
+/**
+ * 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.
+ */
+export declare function foldJournal(entries: readonly DevflowJournalEntry[]): JournalFoldState;
+//# sourceMappingURL=journal.d.ts.map

package/lib/types/journal.js

@@ -0,0 +1,195 @@
+/**
+ * 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
+ */
+import { DEV_STAGES, DevflowCardId, isCardLocation, isDevStage } from "./stages.js";
+/**
+ * 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.
+ */
+export 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 !== undefined ? { by: decodeActor(entry.by) } : {},
+                ...decodeOptionalString(entry, 'reason'),
+                ...entry.gate !== undefined ? { 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 !== undefined ? { by: decodeActor(entry.by) } : {},
+            };
+        }
+        case 'claim-expired': {
+            if (entry.previousOwner === undefined) {
+                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.
+ */
+export 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 !== undefined)
+                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') {
+                    // `from` is a stage here: the departure check above matched the
+                    // current location, and a blocked card cannot block again.
+                    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;
+                break;
+        }
+    }
+    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 === undefined) {
+        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 === undefined)
+        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 === undefined)
+        return {};
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new Error(`field "${key}" must be a non-empty string when present`);
+    }
+    return { [key]: value };
+}
+//# sourceMappingURL=journal.js.map

package/lib/types/stages.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Runtime stage vocabulary: the ordered stage list, location narrowing, and the
+ * card-id factory. Kept beside the type-only module so `types.ts` stays free of
+ * runtime code.
+ * @module @zhchxiao123/dsh-devflow/src/stages
+ */
+import type { Branded } from '@deepseek-ai/dsh-brand';
+import type { CardLocation, DevStage } from './types.ts';
+/** Opaque id of one task card; equals the card's directory name and never changes. */
+export type DevflowCardId = Branded<'DevflowCardId'>;
+/** The pipeline stages in flow order; `blocked` is a bypass, not a member. */
+export declare const DEV_STAGES: readonly ["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}.
+ */
+export declare function isDevStage(value: unknown): value is DevStage;
+/**
+ * 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.
+ */
+export declare function isCardLocation(value: unknown): value is CardLocation;
+/**
+ * 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.
+ */
+export declare function DevflowCardId(value: string): DevflowCardId;
+/**
+ * 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.
+ */
+export declare function isLegalTransition(from: CardLocation, to: CardLocation, blockedFrom?: DevStage): boolean;
+/**
+ * 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`.
+ */
+export declare function isReworkEdge(from: CardLocation, to: CardLocation): boolean;
+//# sourceMappingURL=stages.d.ts.map