@danypops/papyrus 0.58.0 → 0.58.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/papyrus",
-  "version": "0.58.0",
+  "version": "0.58.2",
   "description": "Daemon-backed graph artifacts, evidence-bearing tasks, rules, skills, and native TUI workflows for Pi",
   "type": "module",
   "main": "./src/index.ts",

package/src/artifact/artifact-scope-store.ts

@@ -2,15 +2,11 @@ import type { ScopeAssignmentSource } from "../project-registry/scope-source.ts"
 import type { ScopeMemberRef } from "../scope-group/scope-group.ts";
 
 /**
- * Project scoping for Docs/Rules/Playbooks: an artifact is explicitly "none" (hidden -- never
- * applicable, never context-injected, regardless of project), explicitly "all" (applies
- * everywhere), or bound to a bounded, non-empty set of explicit members -- never inferred from
- * an accidentally empty join table, which is why `mode` is its own explicit field rather than
- * "members.length === 0 means none/all". A member is either a registered project (from the
- * shared ProjectRegistryStore) or a scope group (from ScopeGroupStore, itself a possibly-nested
- * collection of projects/groups) -- "explicit scope can include nested scopes". Membership is by
- * id, never by root/name, so a registered project's root (or a group's name) can move without a
- * best-effort string rewrite across every artifact that references it.
+ * Project scoping for Docs/Rules/Playbooks: "none" hides an artifact from context injection
+ * entirely, "all" applies it everywhere, "explicit" binds it to a non-empty member set (a
+ * project or a possibly-nested scope group). `mode` is its own field rather than inferred from
+ * an empty member list, and membership is by id rather than root/name, so a project or group can
+ * be renamed/moved without rewriting every artifact that references it.
  */
 export type ArtifactScopeMode = "none" | "all" | "explicit";
 

package/src/artifact/in-memory-artifact-scope-store.ts

@@ -18,9 +18,7 @@ export class InMemoryArtifactScopeStore implements ArtifactScopeStore {
 	private readonly registry: InMemoryProjectRegistryStore;
 	private readonly scopeGroups: ScopeGroupStore;
 
-	// Membership is stored by project/group id, never by root/name, so a registry root move (see
-	// ProjectRegistryStore.registerProject) or a scope group rename needs no rewrite here at all --
-	// unlike InMemoryTaskScopeStore, this store never subscribes to root-move notifications.
+	// Membership is by project/group id, so a registry root move or group rename needs no rewrite here.
 	constructor(registry?: ProjectRegistryStore, scopeGroups?: ScopeGroupStore) {
 		this.registry = registry instanceof InMemoryProjectRegistryStore ? registry : new InMemoryProjectRegistryStore();
 		this.scopeGroups = scopeGroups ?? new InMemoryScopeGroupStore();

package/src/gate/gate-execution.ts

@@ -1,21 +1,8 @@
 /**
- * Gate-execution engine, split out of ops.ts (the artifact-CRUD file) as part of a SOLID-audit-
- * driven decomposition (see Doc "Modularity playbook: building-block-shaped TypeScript modules
- * for papyrus/pi-papyrus" and the "gate-execution engine" child of "Epic: Modularize papyrus/
- * pi-papyrus god-files into building-block modules"). This logic was already unified in a prior
- * refactor (sync/async outcome evaluation shared via evaluateProcessGateResult/spawnErrorGateResult)
- * but still lived inside the artifact-CRUD file until now.
- *
- * Only `runGates`/`runGatesAsync` are real public API -- verified via find_references before this
- * move, not assumed from a grep hit count: the only two real importers were
- * stores/sqlite-gate-runner.ts and test/ops.test.ts (every other `runGates`-named hit in the
- * codebase is Tasks.runGates, a same-named but distinct method that calls into this module only
- * indirectly, through the GateRunner port). Both were updated to import from this file directly;
- * no barrel re-export needed.
- *
- * Depends on ops.ts's own `getArtifact` (still the right owner of that read -- it's real
- * artifact-CRUD, not gate-execution's own concern) -- a one-directional dependency, since ops.ts
- * no longer needs to import anything back from here.
+ * Gate-execution engine. `Tasks.runGates` is a separate, same-named method that calls into this
+ * module only indirectly, through the GateRunner port -- not the same thing as this file's
+ * `runGates`/`runGatesAsync`. Depends on ops.ts's `getArtifact` (real artifact-CRUD, not this
+ * module's own concern); ops.ts does not depend back on this file.
  */
 import { createRequire } from "node:module";
 import {

package/src/handlers/artifact-helpers.ts

@@ -1,9 +1,4 @@
-/**
- * Cross-domain artifact name/id resolution and workflow-run narrative building, split out of
- * handlers/shared.ts as part of a SOLID-audit-driven decomposition (see Doc "Modularity playbook:
- * building-block-shaped TypeScript modules for papyrus/pi-papyrus" and the "handlers/shared.ts
- * split" child of "Epic: Modularize papyrus/pi-papyrus god-files into building-block modules").
- */
+/** Cross-domain artifact name/id resolution and workflow-run narrative building. */
 import { type VehicleContentBlock, VehicleError } from "@danypops/vehicle-core";
 import type { Artifact } from "../artifact/artifact.ts";
 import type { ArtifactStore } from "../artifact/artifact-store.ts";

package/src/handlers/operation-schema.ts

@@ -1,10 +1,7 @@
 /**
- * Generic, domain-agnostic operation-input schema DSL, split out of handlers/shared.ts as part of
- * a SOLID-audit-driven decomposition (see Doc "Modularity playbook: building-block-shaped
- * TypeScript modules for papyrus/pi-papyrus" and the "handlers/shared.ts split" child of "Epic:
- * Modularize papyrus/pi-papyrus god-files into building-block modules"). Nothing here references
- * a specific Papyrus domain (tasks/docs/rules/...) -- a real candidate to eventually become its
- * own building block other Vehicle-backed daemons could reuse directly.
+ * Generic, domain-agnostic operation-input schema DSL. Nothing here references a specific
+ * Papyrus domain (tasks/docs/rules/...) -- a real candidate to eventually become its own building
+ * block other Vehicle-backed daemons could reuse directly.
  */
 import {
 	defineVehicleSchema,

package/src/handlers/paired-mutation.ts

@@ -1,10 +1,4 @@
-/**
- * Vehicle-operation-definer DSL (createOperationDefiner) and the paired add/remove mutation shape
- * built on top of it (definePairedMutation), split out of handlers/shared.ts as part of a
- * SOLID-audit-driven decomposition (see Doc "Modularity playbook: building-block-shaped
- * TypeScript modules for papyrus/pi-papyrus" and the "handlers/shared.ts split" child of "Epic:
- * Modularize papyrus/pi-papyrus god-files into building-block modules").
- */
+/** Vehicle-operation-definer DSL (createOperationDefiner) and the paired add/remove mutation shape built on top of it (definePairedMutation). */
 import { bindVehicleOperation, defineVehicleOperation, type VehicleLimits, type VehicleOperationContext } from "@danypops/vehicle-core";
 import type { VehicleRegistry } from "@danypops/vehicle-server";
 import { looseObjectSchema, passthroughOutput } from "./operation-schema.ts";

package/src/handlers/shared.ts

@@ -1,20 +1,11 @@
 /**
  * Barrel re-exporting the shared schema helpers and name->id resolution used by every per-domain
- * VehicleRegistry projection (notes-vehicle.ts, rules-vehicle.ts, docs-vehicle.ts,
- * artifact-trash-vehicle.ts, ...). Kept as a real file (not a `shared/index.ts` subdirectory) so
- * every existing `from "./shared.ts"` import across the 8 handler files that depend on it keeps
- * resolving unchanged -- this codebase's imports always carry an explicit `.ts` extension, which
- * does not implicitly resolve a bare specifier to a directory's own index file the way Node's
- * CJS `require()` does.
- *
- * The real implementation now lives in four focused sibling modules instead of one 435-line file
- * mixing four unrelated concerns -- see Doc "Modularity playbook: building-block-shaped
- * TypeScript modules for papyrus/pi-papyrus" and the "handlers/shared.ts split" child of "Epic:
- * Modularize papyrus/pi-papyrus god-files into building-block modules":
- *   - operation-schema.ts: generic, domain-agnostic operation-input schema DSL
- *   - paired-mutation.ts: the Vehicle-operation-definer DSL and the paired add/remove shape built on it
- *   - task-classifiers.ts: business-rule error classifiers specific to this package's own domain errors
- *   - artifact-helpers.ts: cross-domain artifact name/id resolution and workflow-run narrative building
+ * VehicleRegistry projection. Kept as a real file (not a `shared/index.ts` subdirectory) so every
+ * existing `from "./shared.ts"` import keeps resolving unchanged -- this codebase's imports
+ * always carry an explicit `.ts` extension, which does not implicitly resolve a bare specifier to
+ * a directory's own index file the way Node's CJS `require()` does. Real implementation lives in
+ * operation-schema.ts (schema DSL), paired-mutation.ts (operation-definer DSL), task-classifiers.ts
+ * (domain error classifiers), artifact-helpers.ts (name/id resolution, workflow-run narrative).
  */
 export {
 	buildWorkflowRunContent,

package/src/handlers/task-classifiers.ts

@@ -1,12 +1,4 @@
-/**
- * Business-rule error classifiers -- turn an ordinary, expected domain rejection into its own
- * classified VehicleError instead of vehicle-registry's generic opaque "handler-failed", split out
- * of handlers/shared.ts as part of a SOLID-audit-driven decomposition (see Doc "Modularity
- * playbook: building-block-shaped TypeScript modules for papyrus/pi-papyrus" and the
- * "handlers/shared.ts split" child of "Epic: Modularize papyrus/pi-papyrus god-files into
- * building-block modules"). Unlike operation-schema.ts, every function here is specific to this
- * package's own domain error types.
- */
+/** Business-rule error classifiers -- turn an ordinary, expected domain rejection into its own classified VehicleError instead of vehicle-registry's generic opaque "handler-failed". */
 import { VehicleError } from "@danypops/vehicle-core";
 import { PlaybookCompositionError } from "../playbook/playbook-definition.ts";
 import { InvalidSessionSecretError } from "../session-identity/session-identity-service.ts";

package/src/project-registry/scope-source.ts

@@ -1,24 +1,9 @@
 import { basename, isAbsolute, normalize } from "node:path";
 import { TASK_PROJECT_ROOT_MAX_LENGTH } from "../constants.ts";
 
-/**
- * How a project root ended up attached to a scoped artifact -- shared across every artifact kind
- * (Tasks, Docs, Rules, Playbooks) rather than owned by Tasks alone, same category as Project
- * itself in project-registry.ts. This lived inside task-scope.ts under the name
- * `TaskScopeSource` until a SOLID audit (see Doc "SOLID pattern analysis: task-event/task-scope
- * shared-kernel extraction") found it consumed identically by artifact/, docs-service.ts,
- * rules-service.ts, playbook-service.ts, and modules/projects.ts -- a Role Interface split
- * couldn't fix this half of the problem because there's no single supplier to narrow a contract
- * for; every one of those five call sites is a peer owner of the same vocabulary. task-scope.ts
- * keeps `TaskScopeSource` as a backward-compatible alias of this type for Task's own call sites.
- */
+/** How a project root got attached to a scoped artifact -- shared across Tasks/Docs/Rules/Playbooks, same category as Project in project-registry.ts. */
 export type ScopeAssignmentSource = "cwd" | "explicit" | "unscoped";
 
-/**
- * Same relocation as ScopeAssignmentSource above, for the same reason: a pure, artifact-kind-
- * agnostic validation/normalization function that every non-Task scope-assigning service already
- * called directly rather than through any Task-owned abstraction.
- */
 export function normalizeProjectRoot(value: string): string {
 	if (!isAbsolute(value)) throw new Error("project_root must be an absolute path");
 	const normalized = normalize(value);

package/src/scope-group/scope-group.ts

@@ -1,17 +1,10 @@
 import { SCOPE_GROUP_ALIAS_MAX_COUNT, SCOPE_GROUP_NAME_MAX_LENGTH } from "../constants.ts";
 
 /**
- * A named, reusable collection of scope members (registered projects and/or other scope groups)
- * -- the "explicit scope can include nested scopes" primitive. Lives alongside the project
- * registry (same shape: id/name/aliases/createdAt/updatedAt) rather than as an Artifact, since
- * it is bookkeeping infrastructure for scoping, not itself a piece of knowledge or work.
- *
- * Deliberately explicit/opt-in membership, not filesystem-path-derived nesting: a registered
- * project whose root happens to be a subdirectory of another registered project's root is NOT
- * automatically its child (a real false-positive confirmed live: alignment-lector is registered
- * under lector/packages/alignment-lector, a subdirectory of lector's own root, but is Lector's
- * adapter for a *different* project, not part of Lector's own scope). A group's membership is
- * only ever what was deliberately added to it.
+ * A named, reusable collection of scope members (registered projects and/or other scope groups).
+ * Membership is explicit/opt-in, never path-derived: a project registered under another
+ * project's root directory (e.g. a vendored adapter package) is not automatically that parent's
+ * child -- only what's deliberately added counts.
  */
 export interface ScopeGroup {
 	id: string;

package/src/task/event/task-event-store.ts

@@ -10,16 +10,7 @@ import {
 	validateTaskEvent,
 } from "./task-event.ts";
 
-/**
- * Role Interface (Fowler: https://martinfowler.com/bliki/RoleInterface.html) for the one
- * collaboration playbook workflow execution actually has with Task's event log: append one event
- * inside a single atomic transaction. Extracted after a SOLID audit found TaskEventStore's full
- * Header Interface (all 4 methods, including history/feed -- pagination concerns that exist
- * purely for Task's own history/feed reader endpoints) threaded unchanged through
- * handlers/playbooks.ts, modules/playbooks.ts, and playbook/workflow-execution.ts, which never
- * calls history()/feed() at all. TaskEventStore still implements this structurally with zero
- * changes to either concrete store; only the playbook-facing field type narrows to this.
- */
+/** What a caller outside Task needs to append events -- history/feed stay on TaskEventStore since only Task's own readers use them. */
 export interface TaskEventSink {
 	atomic<T>(operation: () => T): T;
 	append(event: AppendTaskEvent): TaskEvent;

package/src/task/scope/task-scope-store.ts

@@ -9,17 +9,7 @@ import type {
 	TaskViewPreference,
 } from "./task-scope.ts";
 
-/**
- * Role Interface (Fowler: https://martinfowler.com/bliki/RoleInterface.html) for the one
- * collaboration playbook workflow execution actually has with Task's own scope bookkeeping:
- * assigning a task's project scope when a playbook step creates/advances one. Extracted after a
- * SOLID audit found TaskScopeStore's full Header Interface (all 8 methods -- project-catalog
- * registration, view-preference bookkeeping, task-id listing, none of which playbook ever
- * touches) threaded unchanged through handlers/playbooks.ts, modules/playbooks.ts, and
- * playbook/workflow-execution.ts, which only ever calls .assign(). TaskScopeStore still
- * implements this structurally with zero changes to either concrete store; only the
- * playbook-facing field type narrows to this.
- */
+/** What a caller outside Task needs to assign a task's project scope -- the rest of TaskScopeStore (catalog, views, listing) stays Task-only. */
 export interface TaskScopeAssigner {
 	assign(taskId: string, projectRoot: string | undefined, source: TaskScopeSource): TaskProjectScope;
 }
@@ -34,13 +24,7 @@ export interface TaskScopeStore extends TaskScopeAssigner {
 	registerProject(input: RegisterTaskProjectInput): TaskProject;
 }
 
-/**
- * Task's own scope/view bookkeeping, composing a ProjectRegistryStore for the project-catalog
- * methods (projects/matchingProjects/registerProject) rather than implementing that bookkeeping
- * itself -- see project-registry-store.ts. Pass a shared registry instance to keep Task and a
- * non-Task ArtifactScopeStore resolving against the exact same project identities; omitted, this
- * store gets its own private one (matching this class's own behavior before the extraction).
- */
+/** Pass a shared registry to keep Task and ArtifactScopeStore resolving the same project identities; omitted, this gets its own private one. */
 export class InMemoryTaskScopeStore implements TaskScopeStore {
 	private readonly scopes = new Map<string, TaskProjectScope>();
 	private readonly views = new Map<string, TaskViewPreference>();

package/src/task/scope/task-scope.ts

@@ -6,7 +6,7 @@ export { normalizeProjectRoot } from "../../project-registry/scope-source.ts";
 
 export type TaskViewMode = "project" | "graph" | "all";
 
-/** Task's own name for the shared, kind-neutral scope-assignment provenance -- see scope-source.ts. Kept as a type alias so every existing Task-scope call site keeps working unchanged. */
+/** Alias of ScopeAssignmentSource for Task's own call sites -- see project-registry/scope-source.ts. */
 export type TaskScopeSource = ScopeAssignmentSource;
 
 export interface TaskProjectScope {

package/src/task/task-edges.ts

@@ -10,17 +10,10 @@ import { assertDependencyEdgeAllowed, TaskExecutionBoundExceededError } from "./
 import type { TaskGraph } from "./task-service.ts";
 
 /**
- * Task dependency/containment edge mutations (depend/undepend/contain/uncontain), split out of
- * the Tasks god class as part of a SOLID-audit-driven decomposition (see task b51419a0 and the
- * "TaskEdges" child of "Epic: Modularize papyrus/pi-papyrus god-files into building-block
- * modules"), mirroring the TaskLeaseCoordinator/TaskMutationCoordinator/TaskFocusCoordinator/
- * TaskProjectScope precedent in this same directory.
- *
- * Unlike those simpler extractions, this one only owns the mutation side of edges -- it reads the
- * graph/relationships it needs through injected callbacks (dependencyCheckGraph/dependencyIds/
- * relationships) rather than duplicating that graph-construction machinery, since those reads are
- * shared with concerns that stay on Tasks (list/graph/buildGraph, progress propagation, blockage
- * checks in transition/complete).
+ * Task dependency/containment edge mutations (depend/undepend/contain/uncontain). Reads the
+ * graph/relationships it needs through injected callbacks rather than owning graph construction,
+ * since those reads are shared with concerns that stay on Tasks (list/graph, progress propagation,
+ * blockage checks).
  */
 export class TaskEdges {
 	constructor(

package/src/task/task-focus-coordinator.ts

@@ -21,14 +21,8 @@ export interface TaskFocus {
 export type TaskFocusMutationResult = TaskFocus & TaskMutationMetadata;
 
 /**
- * Task Focus (the single active/paused task per session scope), split out of the Tasks god class
- * as part of a SOLID-audit-driven decomposition (see task b51419a0 and the "TaskFocusCoordinator"
- * child of "Epic: Modularize papyrus/pi-papyrus god-files into building-block modules"), mirroring
- * the existing TaskLeaseCoordinator/TaskMutationCoordinator precedent in this same directory.
- *
- * Focus is orthogonal to lifecycle and lease: focusing a task does not start it, and does not
- * claim its lease -- so this concern has nothing to do with status transitions or worker
- * exclusivity, the other concerns that were previously interleaved with it in one class.
+ * Task Focus (the single active/paused task per session scope). Orthogonal to lifecycle and
+ * lease: focusing a task does not start it and does not claim its lease.
  */
 export class TaskFocusCoordinator {
 	constructor(

package/src/task/task-lease-coordinator.ts

@@ -3,12 +3,9 @@ import type { TaskLease, TaskLeaseView } from "./lease/task-lease.ts";
 import type { TaskLeaseStore } from "./lease/task-lease-store.ts";
 
 /**
- * Task lease management (claim/heartbeat/release/get/reap), split out of the Tasks god class as
- * part of a SOLID-audit-driven decomposition (see task b51419a0). A lease is orthogonal to
- * lifecycle and Focus -- claiming a task does not start it, and does not require it to be
- * Focused -- so its own concern (a single active worker per task, TTL-based) has nothing to do
- * with status transitions, idempotency receipts, or checklist review, the other concerns that
- * were previously interleaved with it in one class.
+ * Task lease management (claim/heartbeat/release/get/reap) -- a single active worker per task,
+ * TTL-based. Orthogonal to lifecycle and Focus: claiming a task does not start it or require it
+ * to be Focused.
  */
 export class TaskLeaseCoordinator {
 	constructor(

package/src/task/task-mutation-coordinator.ts

@@ -41,26 +41,16 @@ function canonicalJson(value: unknown): string {
 }
 
 /**
- * Idempotency-key-backed mutation receipt plumbing, split out of the Tasks god class as part of
- * a SOLID-audit-driven decomposition (see task b51419a0). Owns reserving a "pending" receipt
- * before a real mutation runs, replaying an already-completed one, rejecting a genuinely
- * different payload reused under the same key, and rejecting a NEW attempt against a
- * task+operation that already has one in flight.
+ * Idempotency-key-backed mutation receipt plumbing: reserves a "pending" receipt before a real
+ * mutation runs, replays an already-completed one, rejects a different payload reused under the
+ * same key, and rejects a new attempt against a task+operation that already has one in flight.
  *
- * `validate`, when supplied to prepare(), runs before anything else -- including before the
- * existing/replay lookup -- specifically so a caller-supplied validation failure (e.g. an
- * over-length `reason`) can never leave a receipt reserved with no way to ever mark it complete.
- * This is the direct fix for a real incident (task a54f0649, discovered live completing task
- * d0eb81b7): validation previously ran deep inside the CALLER's own atomic block (appendEvent's
- * own validateTaskEvent), strictly AFTER prepare()'s reserving call had already durably written
- * the receipt as pending. Once that validation threw, nothing downstream ever reached the code
- * path that marks a receipt complete, permanently stranding it -- and since the pending-mutation
- * lock is keyed on (taskId, operation) rather than the idempotency key, that stuck receipt then
- * blocked every subsequent attempt on the same task+operation, under ANY key, until the record's
- * 7-day retention window expired. No self-service recovery existed; the live incident required a
- * direct database row deletion. Every caller that can determine its own event-context validity up
- * front (reason/sessionId length, at minimum) should now pass a `validate` callback here instead
- * of only validating once real mutation work is already underway.
+ * `validate`, when passed to prepare(), runs before the existing/replay lookup, so a
+ * caller-supplied validation failure can never leave a receipt reserved with no way to complete
+ * it -- a stuck pending receipt blocks every later attempt on that task+operation, under any key,
+ * until its retention window expires, with no self-service recovery. Any caller that can
+ * determine its own event-context validity up front should pass `validate` here rather than
+ * validating only once real mutation work is underway.
  */
 export class TaskMutationCoordinator {
 	constructor(

package/src/task/task-project-scope.ts

@@ -18,13 +18,8 @@ export class TaskProjectAmbiguousError extends Error {}
 
 /**
  * Task project-scope management (scopeSelection/setView/assignProject/projects/resolveProject/
- * registerProject), split out of the Tasks god class as part of a SOLID-audit-driven
- * decomposition (see task b51419a0 and the "TaskProjectScope" child of "Epic: Modularize
- * papyrus/pi-papyrus god-files into building-block modules"), mirroring the existing
- * TaskLeaseCoordinator/TaskMutationCoordinator/TaskFocusCoordinator precedent in this directory.
- *
- * list()/graph() (which stay on Tasks -- they're core query/graph-construction, not project-scope
- * itself) still call scopeSelection() on this collaborator via Tasks' own thin delegation.
+ * registerProject). list()/graph() stay on Tasks but still call scopeSelection() here via a thin
+ * delegation, since those are core query/graph-construction, not project-scope itself.
  */
 export class TaskProjectScope {
 	constructor(