@n-dx/core 0.1.0

package/packages/rex/dist/schema/levels.js

@@ -0,0 +1,152 @@
+/**
+ * Level system — semantic helpers and configurable display.
+ *
+ * This module provides two things:
+ *
+ * 1. **Semantic helpers** that replace scattered `level === "epic"` /
+ *    `level === "task" || "subtask"` checks with meaningful functions
+ *    (`isRootLevel`, `isWorkItem`, etc.). These derive their answers
+ *    from `LEVEL_HIERARCHY` and `CHILD_LEVEL`, not from string matching.
+ *
+ * 2. **Display configuration** — labels, plurals, and emoji for each level,
+ *    consolidated into a single `LevelConfig`. The default config matches
+ *    current behavior (Epic/Feature/Task/Subtask); users can override
+ *    via `.n-dx.json` → `rex.levels`.
+ *
+ * @module rex/schema/levels
+ */
+import { LEVEL_HIERARCHY, CHILD_LEVEL } from "./v1.js";
+/**
+ * Default display config — matches current behavior.
+ *
+ * Users can override via `.n-dx.json` → `rex.levels` to relabel
+ * the hierarchy (e.g. "Theme"/"Story"/"Task"/"Step").
+ */
+const DEFAULT_DISPLAY = {
+    epic: { label: "Epic", labelPlural: "Epics", emoji: "\u{1F4E6}" }, // 📦
+    feature: { label: "Feature", labelPlural: "Features", emoji: "\u{2728}" }, // ✨
+    task: { label: "Task", labelPlural: "Tasks", emoji: "\u{1F4CB}" }, // 📋
+    subtask: { label: "Subtask", labelPlural: "Subtasks", emoji: "\u{1F539}" }, // 🔹
+};
+/** Active display config. Replaced at startup when user overrides exist. */
+let activeDisplay = { ...DEFAULT_DISPLAY };
+/** Replace the active display config (called on startup with user overrides). */
+export function setLevelDisplay(config) {
+    activeDisplay = config;
+}
+/** Reset to defaults (useful for tests). */
+export function resetLevelDisplay() {
+    activeDisplay = { ...DEFAULT_DISPLAY };
+}
+// ── Semantic helpers ────────────────────────────────────────────────
+/**
+ * Can this level exist at the tree root (no parent)?
+ *
+ * Replaces: `level === "epic"`
+ */
+export function isRootLevel(level) {
+    const parents = LEVEL_HIERARCHY[level];
+    return parents !== undefined && parents.includes(null);
+}
+/**
+ * Is this a work item (actionable leaf-level item)?
+ * Work items are levels that don't have container semantics — they
+ * represent actual units of work, not groupings.
+ *
+ * Replaces: `level === "task" || level === "subtask"`
+ */
+export function isWorkItem(level) {
+    return !isContainerLevel(level) && isValidLevel(level);
+}
+/**
+ * Is this a container level (groups other items)?
+ *
+ * Replaces: `level === "epic" || level === "feature"`
+ */
+export function isContainerLevel(level) {
+    if (!isValidLevel(level))
+        return false;
+    const child = CHILD_LEVEL[level];
+    // A container has children, and those children can themselves have children
+    // (i.e., the container is at least 2 levels above the deepest leaf).
+    // Task is NOT a container even though it can have subtask children —
+    // it's a work item that can be subdivided.
+    if (child === null)
+        return false;
+    const grandchild = CHILD_LEVEL[child];
+    return grandchild !== null;
+}
+/**
+ * Is this the deepest possible level (cannot have children)?
+ *
+ * Replaces: `level === "subtask"` or `CHILD_LEVEL[level] === null`
+ */
+export function isLeafLevel(level) {
+    if (!isValidLevel(level))
+        return false;
+    return CHILD_LEVEL[level] === null;
+}
+/**
+ * Is this a valid level string?
+ */
+export function isValidLevel(level) {
+    return level in LEVEL_HIERARCHY;
+}
+// ── Display helpers ─────────────────────────────────────────────────
+/** Get the display label for a level. e.g. "epic" → "Epic" */
+export function getLevelLabel(level) {
+    return activeDisplay[level]?.label ?? level;
+}
+/** Get the plural display label. e.g. "epic" → "Epics" */
+export function getLevelPlural(level) {
+    return activeDisplay[level]?.labelPlural ?? `${level}s`;
+}
+/** Get the emoji for a level. e.g. "epic" → "📦" */
+export function getLevelEmoji(level) {
+    return activeDisplay[level]?.emoji ?? "\u2022"; // bullet fallback
+}
+/** Get all level display configs (for iteration). */
+export function getLevelDisplayMap() {
+    return activeDisplay;
+}
+// ── Hierarchy navigation ────────────────────────────────────────────
+/** Get the default child level. e.g. "epic" → "feature" */
+export function getChildLevel(level) {
+    if (!isValidLevel(level))
+        return null;
+    return CHILD_LEVEL[level];
+}
+/** Get all valid parent levels (excluding null). e.g. "task" → ["feature", "epic"] */
+export function getParentLevels(level) {
+    if (!isValidLevel(level))
+        return [];
+    return LEVEL_HIERARCHY[level].filter((p) => p !== null);
+}
+/** Get all levels in hierarchy order (shallowest first). */
+export function getAllLevels() {
+    return ["epic", "feature", "task", "subtask"];
+}
+/** Get all work-item levels. */
+export function getWorkItemLevels() {
+    return getAllLevels().filter((l) => isWorkItem(l));
+}
+/** Get all container levels. */
+export function getContainerLevels() {
+    return getAllLevels().filter((l) => isContainerLevel(l));
+}
+/**
+ * Format a level summary string. e.g. { epic: 2, task: 3 } → "2 epics, 3 tasks"
+ */
+export function formatLevelSummary(byLevel) {
+    const order = getAllLevels();
+    const parts = [];
+    for (const level of order) {
+        const count = byLevel[level];
+        if (count) {
+            const label = count === 1 ? getLevelLabel(level).toLowerCase() : getLevelPlural(level).toLowerCase();
+            parts.push(`${count} ${label}`);
+        }
+    }
+    return parts.join(", ");
+}
+//# sourceMappingURL=levels.js.map

package/packages/rex/dist/schema/levels.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"levels.js","sourceRoot":"","sources":["../../src/schema/levels.ts"],"names":[],"mappings":"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"}

package/packages/rex/dist/schema/v1.d.ts

@@ -0,0 +1,341 @@
+/**
+ * Rex schema v1 — canonical type definitions and domain constants.
+ *
+ * This is the single source of truth for Rex's data model. All types
+ * and constants defined here are re-exported via the schema barrel
+ * (`./index.ts`) and the public API (`../public.ts`).
+ *
+ * ## Cross-package type strategy
+ *
+ * - **Hench** depends on Rex and uses `import type` for compile-time
+ *   contracts. These are erased at runtime, so the packages remain
+ *   independently deployable while sharing type safety.
+ *
+ * - **Web server routes** import types and constants from Rex through
+ *   the gateway module (`packages/web/src/server/mcp-deps.ts`), which
+ *   re-exports from this file. No duplication needed.
+ *
+ * - **Web viewer** intentionally duplicates core types (ItemLevel,
+ *   ItemStatus, Priority) because the viewer is bundled as standalone
+ *   browser code via esbuild and cannot import from Node.js packages.
+ *   The duplicates are documented with `@see` back-references and
+ *   verified by compile-time consistency tests.
+ *
+ * When modifying types or constants here, also update:
+ *   - packages/web/src/viewer/components/prd-tree/types.ts (viewer types)
+ *   - packages/web/tests/unit/server/type-consistency.test.ts
+ *
+ * @module rex/schema/v1
+ */
+/**
+ * The schema version string embedded in every PRD document.
+ *
+ * This constant is the contract between rex and all `.rex/prd.json`
+ * consumers: hench (reader/writer via rex-gateway), web server (reader
+ * via MCP and REST), and CI (validator). When the schema changes
+ * incompatibly, bump the major version to trigger `isCompatibleSchema()`
+ * failures at every read boundary, preventing silent data corruption
+ * across the three-tier hierarchy (domain → execution → orchestration).
+ */
+export declare const SCHEMA_VERSION = "rex/v1";
+/**
+ * Check if a schema version string is compatible with the current version.
+ *
+ * Compatibility rules:
+ * - Exact match always passes.
+ * - Same major version (prefix before `/`) is considered compatible
+ *   (e.g. "rex/v1" is compatible with "rex/v1.1" — forward-compatible).
+ * - Different prefix or missing version fails.
+ *
+ * This is a lightweight check that does NOT require Zod. Use it in
+ * hot paths (e.g. web server reads) where full validation is too expensive.
+ */
+export declare function isCompatibleSchema(version: string | undefined): boolean;
+/**
+ * Assert that a document's schema field is compatible with the current version.
+ * Throws a descriptive error if the schema is missing or incompatible.
+ *
+ * Use this at read boundaries (store loads, API handlers) to catch
+ * version drift early rather than letting it surface as cryptic type errors.
+ */
+export declare function assertSchemaVersion(doc: {
+    schema?: string;
+}): void;
+export type ItemLevel = "epic" | "feature" | "task" | "subtask";
+export type ItemStatus = "pending" | "in_progress" | "completed" | "failing" | "deferred" | "blocked" | "deleted";
+export type Priority = "critical" | "high" | "medium" | "low";
+/**
+ * How a task was resolved. Tracks whether completion involved actual code
+ * changes or just configuration overrides, enabling escalation when zones
+ * accumulate too many override-based resolutions.
+ */
+export type ResolutionType = "code-change" | "config-override" | "acknowledgment" | "deferred" | "unclassified";
+/**
+ * Category of a requirement.
+ *
+ * - `technical`: implementation constraints (language, framework, API compatibility)
+ * - `performance`: latency, throughput, resource usage targets
+ * - `security`: authentication, authorization, data protection
+ * - `accessibility`: WCAG compliance, screen reader support
+ * - `compatibility`: browser, OS, device support matrix
+ * - `quality`: code coverage, lint rules, documentation standards
+ */
+export type RequirementCategory = "technical" | "performance" | "security" | "accessibility" | "compatibility" | "quality";
+/**
+ * How a requirement should be validated.
+ *
+ * - `automated`: a command/script can verify it (exit 0 = pass)
+ * - `manual`: requires human inspection and sign-off
+ * - `metric`: a numeric threshold must be met (parsed from output)
+ */
+export type RequirementValidationType = "automated" | "manual" | "metric";
+/**
+ * A structured requirement that can be attached to any PRD item.
+ *
+ * Requirements are first-class objects within the PRD tree.
+ * They carry their own acceptance criteria, validation strategy,
+ * and optional automation command so hench can verify compliance
+ * before marking a task complete.
+ */
+export interface Requirement {
+    /** Unique identifier (UUID). */
+    id: string;
+    /** Human-readable title. */
+    title: string;
+    /** Detailed description of the requirement. */
+    description?: string;
+    /** Requirement category. */
+    category: RequirementCategory;
+    /** How this requirement is validated. */
+    validationType: RequirementValidationType;
+    /** Measurable acceptance criteria for this requirement. */
+    acceptanceCriteria: string[];
+    /**
+     * Shell command that validates this requirement (for `automated` or `metric` types).
+     * Exit code 0 = pass. For `metric` type, stdout should contain the measured value.
+     */
+    validationCommand?: string;
+    /**
+     * Numeric threshold for `metric` validation type.
+     * The measured value (from validationCommand stdout) must be >= this threshold.
+     */
+    threshold?: number;
+    /** Priority of this requirement. */
+    priority?: Priority;
+}
+/**
+ * Audit marker persisted on items created by explicitly overriding
+ * duplicate protection in smart-add flows.
+ */
+export interface DuplicateOverrideMarker {
+    /** Fixed marker type for downstream filtering/reporting. */
+    type: "duplicate_guard_override";
+    /** Duplicate reason category (e.g. exact_title, semantic_title). */
+    reason: string;
+    /** Stable reference combining reason + matched item id. */
+    reasonRef: string;
+    /** Existing PRD item id that was matched as duplicate. */
+    matchedItemId: string;
+    /** Existing PRD item title that was matched as duplicate. */
+    matchedItemTitle: string;
+    /** Existing PRD item level that was matched as duplicate. */
+    matchedItemLevel: ItemLevel;
+    /** Existing PRD item status that was matched as duplicate. */
+    matchedItemStatus: ItemStatus;
+    /** Timestamp when the override-created item was persisted. */
+    createdAt: string;
+}
+/**
+ * Provenance entry for a proposal node that was merged into an existing item
+ * during smart-add duplicate resolution.
+ */
+export interface MergedProposalRecord {
+    /** Stable node key from the proposal set (e.g. p0:task:0:1). */
+    proposalNodeKey: string;
+    /** Human-readable proposal title that was merged. */
+    proposalTitle: string;
+    /** Proposal node level in the generated structure. */
+    proposalKind: "epic" | "feature" | "task";
+    /** Duplicate-reason category used for this merge. */
+    reason: string;
+    /** Similarity score that triggered duplicate detection. */
+    score: number;
+    /** Timestamp when the merge was applied. */
+    mergedAt: string;
+    /** Merge source identifier. */
+    source: "smart-add";
+}
+/** All valid requirement categories as a Set. */
+export declare const VALID_REQUIREMENT_CATEGORIES: Set<RequirementCategory>;
+/** All valid validation types as a Set. */
+export declare const VALID_VALIDATION_TYPES: Set<RequirementValidationType>;
+/** Type guard: narrows a string to RequirementCategory. */
+export declare function isRequirementCategory(value: string | undefined): value is RequirementCategory;
+/** Type guard: narrows a string to RequirementValidationType. */
+export declare function isValidationType(value: string | undefined): value is RequirementValidationType;
+export interface PRDItem {
+    id: string;
+    title: string;
+    status: ItemStatus;
+    level: ItemLevel;
+    description?: string;
+    acceptanceCriteria?: string[];
+    priority?: Priority;
+    tags?: string[];
+    source?: string;
+    blockedBy?: string[];
+    /** Structured requirements associated with this item. */
+    requirements?: Requirement[];
+    startedAt?: string;
+    completedAt?: string;
+    failureReason?: string;
+    /** How this item was resolved (code change, config override, etc.). */
+    resolutionType?: ResolutionType;
+    /** Brief description of how the resolution was achieved. */
+    resolutionDetail?: string;
+    /** Present only when duplicate protection was explicitly overridden. */
+    overrideMarker?: DuplicateOverrideMarker;
+    /** Present when duplicate proposals were merged into this existing item. */
+    mergedProposals?: MergedProposalRecord[];
+    children?: PRDItem[];
+    [key: string]: unknown;
+}
+export interface PRDDocument {
+    schema: string;
+    title: string;
+    items: PRDItem[];
+    [key: string]: unknown;
+}
+/** Token/cost budget thresholds for usage warnings. */
+export interface BudgetThresholds {
+    /** Maximum total tokens (input + output). 0 = unlimited. */
+    tokens?: number;
+    /** Maximum estimated cost in USD. 0 = unlimited. */
+    cost?: number;
+    /**
+     * Warning threshold as a percentage (0–100).
+     * Warn when usage reaches this percentage of the budget.
+     * Default: 80.
+     */
+    warnAt?: number;
+    /** Abort operations when budget is exceeded. Default: false. */
+    abort?: boolean;
+}
+/** Level-of-Effort estimation and decomposition thresholds (stored in config.json). */
+export interface LoEConfig {
+    /**
+     * Maximum task size in engineer-weeks before automatic decomposition.
+     * Tasks with LoE exceeding this threshold are broken into smaller children.
+     * Default: 2.
+     */
+    taskThresholdWeeks?: number;
+    /**
+     * Maximum recursion depth for decomposition.
+     * Prevents runaway decomposition of deeply nested items.
+     * Default: 2.
+     */
+    maxDecompositionDepth?: number;
+    /**
+     * Maximum number of proposal task items per input description before
+     * triggering a secondary LLM consolidation pass. When the LLM produces
+     * more tasks than this ceiling, a re-consolidation prompt is sent to
+     * reduce over-granular output.
+     * Default: 10.
+     */
+    proposalCeiling?: number;
+}
+/** Default LoE configuration values. */
+export declare const LOE_DEFAULTS: {
+    readonly taskThresholdWeeks: 2;
+    readonly maxDecompositionDepth: 2;
+    readonly proposalCeiling: 10;
+};
+/** Configuration for a single facet dimension (stored in config.json). */
+export interface FacetDefinition {
+    label: string;
+    values: string[];
+    required?: boolean;
+}
+export interface RexConfig {
+    schema: string;
+    project: string;
+    adapter: string;
+    validate?: string;
+    test?: string;
+    sourcevision?: string;
+    model?: string;
+    budget?: BudgetThresholds;
+    /** Level-of-Effort estimation thresholds for proposal decomposition. */
+    loe?: LoEConfig;
+    /** Facet dimensions for item classification (e.g. component, concern). */
+    facets?: Record<string, FacetDefinition>;
+    future?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+export interface LogEntry {
+    timestamp: string;
+    event: string;
+    itemId?: string;
+    detail?: string;
+    [key: string]: unknown;
+}
+/** Token usage from a Claude API call. */
+export interface TokenUsage {
+    input: number;
+    output: number;
+    cacheCreationInput?: number;
+    cacheReadInput?: number;
+}
+/** Aggregated token usage across one or more LLM calls. */
+export interface AnalyzeTokenUsage {
+    /** Number of LLM calls made. */
+    calls: number;
+    /** Total input tokens across all calls. */
+    inputTokens: number;
+    /** Total output tokens across all calls. */
+    outputTokens: number;
+    /** LLM vendor used for this token event (e.g. "claude", "codex"). */
+    vendor?: string;
+    /** Model used for this token event. */
+    model?: string;
+    /** Total cache creation input tokens (if any). */
+    cacheCreationInputTokens?: number;
+    /** Total cache read input tokens (if any). */
+    cacheReadInputTokens?: number;
+}
+/**
+ * Canonical priority ordering — lower number = higher priority.
+ * This is the single source of truth for priority sort order.
+ */
+export declare const PRIORITY_ORDER: Record<Priority, number>;
+/**
+ * Valid parent levels for each item level.
+ *
+ * - `null` entries mean the level can be a root (no parent required).
+ * - Multiple entries mean several parent levels are accepted (e.g. a task
+ *   can live under a feature *or* directly under an epic).
+ */
+export declare const LEVEL_HIERARCHY: Record<ItemLevel, Array<ItemLevel | null>>;
+/** All valid item levels as a Set (derived from LEVEL_HIERARCHY keys). */
+export declare const VALID_LEVELS: Set<ItemLevel>;
+/**
+ * All valid item statuses as a Set.
+ * Includes "deleted" — downstream consumers may exclude it for API-settable
+ * status lists (e.g. the web server's VALID_STATUSES omits "deleted").
+ */
+export declare const VALID_STATUSES: Set<ItemStatus>;
+/** All valid priority values as a Set (derived from PRIORITY_ORDER keys). */
+export declare const VALID_PRIORITIES: Set<Priority>;
+/**
+ * Map parent level → default child level for inference.
+ * Used when adding items under a parent without specifying a level.
+ * Subtasks have no children, so they map to null.
+ */
+export declare const CHILD_LEVEL: Record<ItemLevel, ItemLevel | null>;
+/** Type guard: narrows a string to Priority if it's a valid priority value. */
+export declare function isPriority(value: string | undefined): value is Priority;
+/** Type guard: narrows a string to ItemLevel if it's a valid level value. */
+export declare function isItemLevel(value: string | undefined): value is ItemLevel;
+/** Type guard: narrows a string to ItemStatus if it's a valid status value. */
+export declare function isItemStatus(value: string | undefined): value is ItemStatus;
+export declare function DEFAULT_CONFIG(project: string): RexConfig;

package/packages/rex/dist/schema/v1.js

@@ -0,0 +1,179 @@
+/**
+ * Rex schema v1 — canonical type definitions and domain constants.
+ *
+ * This is the single source of truth for Rex's data model. All types
+ * and constants defined here are re-exported via the schema barrel
+ * (`./index.ts`) and the public API (`../public.ts`).
+ *
+ * ## Cross-package type strategy
+ *
+ * - **Hench** depends on Rex and uses `import type` for compile-time
+ *   contracts. These are erased at runtime, so the packages remain
+ *   independently deployable while sharing type safety.
+ *
+ * - **Web server routes** import types and constants from Rex through
+ *   the gateway module (`packages/web/src/server/mcp-deps.ts`), which
+ *   re-exports from this file. No duplication needed.
+ *
+ * - **Web viewer** intentionally duplicates core types (ItemLevel,
+ *   ItemStatus, Priority) because the viewer is bundled as standalone
+ *   browser code via esbuild and cannot import from Node.js packages.
+ *   The duplicates are documented with `@see` back-references and
+ *   verified by compile-time consistency tests.
+ *
+ * When modifying types or constants here, also update:
+ *   - packages/web/src/viewer/components/prd-tree/types.ts (viewer types)
+ *   - packages/web/tests/unit/server/type-consistency.test.ts
+ *
+ * @module rex/schema/v1
+ */
+/**
+ * The schema version string embedded in every PRD document.
+ *
+ * This constant is the contract between rex and all `.rex/prd.json`
+ * consumers: hench (reader/writer via rex-gateway), web server (reader
+ * via MCP and REST), and CI (validator). When the schema changes
+ * incompatibly, bump the major version to trigger `isCompatibleSchema()`
+ * failures at every read boundary, preventing silent data corruption
+ * across the three-tier hierarchy (domain → execution → orchestration).
+ */
+export const SCHEMA_VERSION = "rex/v1";
+/**
+ * Check if a schema version string is compatible with the current version.
+ *
+ * Compatibility rules:
+ * - Exact match always passes.
+ * - Same major version (prefix before `/`) is considered compatible
+ *   (e.g. "rex/v1" is compatible with "rex/v1.1" — forward-compatible).
+ * - Different prefix or missing version fails.
+ *
+ * This is a lightweight check that does NOT require Zod. Use it in
+ * hot paths (e.g. web server reads) where full validation is too expensive.
+ */
+export function isCompatibleSchema(version) {
+    if (!version)
+        return false;
+    if (version === SCHEMA_VERSION)
+        return true;
+    // Allow forward-compatible minor versions (e.g. "rex/v1.1" matches "rex/v1")
+    return version.startsWith(SCHEMA_VERSION + ".");
+}
+/**
+ * Assert that a document's schema field is compatible with the current version.
+ * Throws a descriptive error if the schema is missing or incompatible.
+ *
+ * Use this at read boundaries (store loads, API handlers) to catch
+ * version drift early rather than letting it surface as cryptic type errors.
+ */
+export function assertSchemaVersion(doc) {
+    if (!isCompatibleSchema(doc.schema)) {
+        throw new Error(`Incompatible PRD schema: found "${doc.schema ?? "(missing)"}",` +
+            ` expected "${SCHEMA_VERSION}". ` +
+            `Run "rex validate" to check and migrate your PRD.`);
+    }
+}
+/** All valid requirement categories as a Set. */
+export const VALID_REQUIREMENT_CATEGORIES = new Set([
+    "technical",
+    "performance",
+    "security",
+    "accessibility",
+    "compatibility",
+    "quality",
+]);
+/** All valid validation types as a Set. */
+export const VALID_VALIDATION_TYPES = new Set([
+    "automated",
+    "manual",
+    "metric",
+]);
+/** Type guard: narrows a string to RequirementCategory. */
+export function isRequirementCategory(value) {
+    return value !== undefined && VALID_REQUIREMENT_CATEGORIES.has(value);
+}
+/** Type guard: narrows a string to RequirementValidationType. */
+export function isValidationType(value) {
+    return value !== undefined && VALID_VALIDATION_TYPES.has(value);
+}
+/** Default LoE configuration values. */
+export const LOE_DEFAULTS = {
+    taskThresholdWeeks: 2,
+    maxDecompositionDepth: 2,
+    proposalCeiling: 10,
+};
+/**
+ * Canonical priority ordering — lower number = higher priority.
+ * This is the single source of truth for priority sort order.
+ */
+export const PRIORITY_ORDER = {
+    critical: 0,
+    high: 1,
+    medium: 2,
+    low: 3,
+};
+/**
+ * Valid parent levels for each item level.
+ *
+ * - `null` entries mean the level can be a root (no parent required).
+ * - Multiple entries mean several parent levels are accepted (e.g. a task
+ *   can live under a feature *or* directly under an epic).
+ */
+export const LEVEL_HIERARCHY = {
+    epic: [null],
+    feature: ["epic"],
+    task: ["feature", "epic"],
+    subtask: ["task"],
+};
+// ── Validation sets ────────────────────────────────────────────────
+/** All valid item levels as a Set (derived from LEVEL_HIERARCHY keys). */
+export const VALID_LEVELS = new Set(Object.keys(LEVEL_HIERARCHY));
+/**
+ * All valid item statuses as a Set.
+ * Includes "deleted" — downstream consumers may exclude it for API-settable
+ * status lists (e.g. the web server's VALID_STATUSES omits "deleted").
+ */
+export const VALID_STATUSES = new Set([
+    "pending",
+    "in_progress",
+    "completed",
+    "failing",
+    "deferred",
+    "blocked",
+    "deleted",
+]);
+/** All valid priority values as a Set (derived from PRIORITY_ORDER keys). */
+export const VALID_PRIORITIES = new Set(Object.keys(PRIORITY_ORDER));
+// ── Child level inference ──────────────────────────────────────────
+/**
+ * Map parent level → default child level for inference.
+ * Used when adding items under a parent without specifying a level.
+ * Subtasks have no children, so they map to null.
+ */
+export const CHILD_LEVEL = {
+    epic: "feature",
+    feature: "task",
+    task: "subtask",
+    subtask: null,
+};
+// ── Type guards ────────────────────────────────────────────────────
+/** Type guard: narrows a string to Priority if it's a valid priority value. */
+export function isPriority(value) {
+    return value !== undefined && VALID_PRIORITIES.has(value);
+}
+/** Type guard: narrows a string to ItemLevel if it's a valid level value. */
+export function isItemLevel(value) {
+    return value !== undefined && VALID_LEVELS.has(value);
+}
+/** Type guard: narrows a string to ItemStatus if it's a valid status value. */
+export function isItemStatus(value) {
+    return value !== undefined && VALID_STATUSES.has(value);
+}
+export function DEFAULT_CONFIG(project) {
+    return {
+        schema: SCHEMA_VERSION,
+        project,
+        adapter: "file",
+        sourcevision: "auto",
+    };
+}
+//# sourceMappingURL=v1.js.map

package/packages/rex/dist/schema/v1.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"v1.js","sourceRoot":"","sources":["../../src/schema/v1.ts"],"names":[],"mappings":"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"}