@juicesharp/rpiv-workflow 1.14.0 → 1.14.2

package/handle.ts

@@ -0,0 +1,70 @@
+/**
+ * Artifact handle — the storage-agnostic reference a collector emits and
+ * a parser consumes. Tagged union so collectors / parsers narrow
+ * structurally (`if (h.kind === "fs") fs.readFile(h.path)`); plain
+ * `string` would force a parse on every consumer.
+ *
+ * Four built-in kinds cover the practical universe:
+ *   - `fs`     — cwd-relative or absolute filesystem path.
+ *   - `url`    — RFC-3986 reference (https, file://, custom scheme).
+ *   - `opaque` — external system id (Linear ticket, S3 key, commit SHA).
+ *   - `inline` — bytes the collector gathered directly (rare; useful for
+ *                a binary the consumer wants without an fs round-trip).
+ *
+ * Authors who need a kind not in this list write a custom collector that
+ * emits `opaque` and a custom parser that knows how to dereference it.
+ */
+export type ArtifactHandle =
+	| { kind: "fs"; path: string }
+	| { kind: "url"; href: string }
+	| { kind: "opaque"; id: string }
+	| { kind: "inline"; bytes: Uint8Array; mime?: string };
+
+/**
+ * One artifact a stage produced. The handle is the storage reference;
+ * `role` is an optional user-facing label (`"primary"`, `"patch"`,
+ * `"log"`) downstream stages can route on; `meta` carries any
+ * collector-attached hints the matching parser needs.
+ *
+ * The framework reads `artifacts[0]` as the "primary" artifact for chain
+ * inheritance (side-effect stages without their own artifacts inherit the
+ * upstream list forward). `role` is metadata only — the framework does
+ * not gate on it.
+ */
+export interface Artifact {
+	handle: ArtifactHandle;
+	role?: string;
+	meta?: Record<string, unknown>;
+}
+
+// ---------------------------------------------------------------------------
+// Handle constructors — eliminate kind-literal boilerplate at collector
+// call sites. `fs(path)` reads cleaner than `{ kind: "fs", path }` and
+// keeps the discriminator value in one place.
+// ---------------------------------------------------------------------------
+
+export const fs = (path: string): ArtifactHandle => ({ kind: "fs", path });
+export const url = (href: string): ArtifactHandle => ({ kind: "url", href });
+export const opaque = (id: string): ArtifactHandle => ({ kind: "opaque", id });
+export const inline = (bytes: Uint8Array, mime?: string): ArtifactHandle =>
+	mime !== undefined ? { kind: "inline", bytes, mime } : { kind: "inline", bytes };
+
+/**
+ * Serialise a handle to a human-readable string — used by the runner
+ * when threading the primary artifact into a downstream stage's prompt
+ * input (the prompt is plain text; URLs / paths / opaque ids all have a
+ * natural one-line form). Inline handles serialise to their byte length
+ * since their content isn't meaningfully promptable.
+ */
+export function handleToString(h: ArtifactHandle): string {
+	switch (h.kind) {
+		case "fs":
+			return h.path;
+		case "url":
+			return h.href;
+		case "opaque":
+			return h.id;
+		case "inline":
+			return `inline:${h.bytes.byteLength}b${h.mime ? `;${h.mime}` : ""}`;
+	}
+}

package/package.json

@@ -1,83 +1,87 @@
 {
-  "name": "@juicesharp/rpiv-workflow",
-  "version": "1.14.0",
-  "description": "Pi extension. Chain skills into typed multi-stage workflows with audited JSONL state, predicate routing, and per-stage output validation. Skill-agnostic — bring your own skills.",
-  "keywords": [
-    "pi-package",
-    "pi-extension",
-    "rpiv",
-    "workflow",
-    "skills",
-    "orchestration",
-    "dag",
-    "pipeline"
-  ],
-  "type": "module",
-  "license": "MIT",
-  "author": "juicesharp",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/juicesharp/rpiv-mono.git",
-    "directory": "packages/rpiv-workflow"
-  },
-  "homepage": "https://github.com/juicesharp/rpiv-mono/tree/main/packages/rpiv-workflow#readme",
-  "bugs": {
-    "url": "https://github.com/juicesharp/rpiv-mono/issues"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "scripts": {
-    "test": "vitest run"
-  },
-  "files": [
-    "index.ts",
-    "internal.ts",
-    "api.ts",
-    "artifacts-layout.ts",
-    "audit.ts",
-    "built-ins.ts",
-    "command.ts",
-    "fanout.ts",
-    "host.ts",
-    "internal-utils.ts",
-    "layers.ts",
-    "lifecycle.ts",
-    "load",
-    "output.ts",
-    "messages.ts",
-    "output-spec.ts",
-    "outcomes",
-    "preview.ts",
-    "routing.ts",
-    "runner",
-    "sessions",
-    "state",
-    "transcript.ts",
-    "triggers.ts",
-    "typebox-adapter.ts",
-    "types.ts",
-    "validate-output.ts",
-    "validate-workflow.ts",
-    "docs-protocol.ts",
-    "docs",
-    "README.md",
-    "LICENSE"
-  ],
-  "exports": {
-    ".": "./index.ts",
-    "./internal": "./internal.ts"
-  },
-  "pi": {
-    "extensions": [
-      "./index.ts"
-    ]
-  },
-  "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "*",
-    "@juicesharp/rpiv-config": "*",
-    "@standard-schema/spec": "*",
-    "jiti": "*",
-    "typebox": "*"
-  }
+	"name": "@juicesharp/rpiv-workflow",
+	"version": "1.14.2",
+	"description": "Pi extension. Chain skills into typed multi-stage workflows with audited JSONL state, predicate routing, and per-stage output validation. Skill-agnostic — bring your own skills.",
+	"keywords": [
+		"pi-package",
+		"pi-extension",
+		"rpiv",
+		"workflow",
+		"skills",
+		"orchestration",
+		"dag",
+		"pipeline"
+	],
+	"type": "module",
+	"license": "MIT",
+	"author": "juicesharp",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/juicesharp/rpiv-mono.git",
+		"directory": "packages/rpiv-workflow"
+	},
+	"homepage": "https://github.com/juicesharp/rpiv-mono/tree/main/packages/rpiv-workflow#readme",
+	"bugs": {
+		"url": "https://github.com/juicesharp/rpiv-mono/issues"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"scripts": {
+		"test": "vitest run"
+	},
+	"files": [
+		"index.ts",
+		"internal.ts",
+		"api.ts",
+		"artifacts-layout.ts",
+		"audit.ts",
+		"built-ins.ts",
+		"command.ts",
+		"fanout.ts",
+		"handle.ts",
+		"host.ts",
+		"internal-utils.ts",
+		"layers.ts",
+		"lifecycle.ts",
+		"load",
+		"output.ts",
+		"messages.ts",
+		"output-spec.ts",
+		"outcomes",
+		"predicates.ts",
+		"preview.ts",
+		"routing.ts",
+		"runner",
+		"sessions",
+		"state",
+		"transcript.ts",
+		"triggers.ts",
+		"typebox-adapter.ts",
+		"types.ts",
+		"validate-output.ts",
+		"validate-workflow.ts",
+		"docs-protocol.ts",
+		"docs",
+		"README.md",
+		"LICENSE"
+	],
+	"exports": {
+		".": "./index.ts",
+		"./internal": "./internal.ts"
+	},
+	"pi": {
+		"extensions": [
+			"./index.ts"
+		]
+	},
+	"dependencies": {
+		"@juicesharp/rpiv-config": "^1.14.2",
+		"jiti": "^2.7.0"
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-coding-agent": "*",
+		"@standard-schema/spec": "*",
+		"typebox": "*"
+	}
 }

package/predicates.ts

@@ -0,0 +1,42 @@
+/**
+ * Predicate helpers for `gate(...)` — small, side-effect-free combinators
+ * over a single field value. Each helper returns a `Predicate` that the
+ * runtime evaluates against `Number(output.data[field])`.
+ *
+ * Numeric coercion via `Number(...)` matches the prior `threshold` semantics:
+ * missing or non-numeric fields coerce to `NaN`, and `NaN` compares false
+ * against any threshold. Callers wanting a non-default fall-through let
+ * `gate`'s last-branch fallback handle the unmatched case.
+ */
+
+export type Predicate = (value: number) => boolean;
+
+/** Strictly greater than. */
+export const gt =
+	(n: number): Predicate =>
+	(v) =>
+		v > n;
+
+/** Greater than or equal. */
+export const gte =
+	(n: number): Predicate =>
+	(v) =>
+		v >= n;
+
+/** Strictly less than. */
+export const lt =
+	(n: number): Predicate =>
+	(v) =>
+		v < n;
+
+/** Less than or equal. */
+export const lte =
+	(n: number): Predicate =>
+	(v) =>
+		v <= n;
+
+/** Numeric equality (after `Number(...)` coercion of `output.data[field]`). */
+export const eq =
+	(n: number): Predicate =>
+	(v) =>
+		v === n;