@pipelex/sdk 0.3.1 → 0.5.0

package/dist/hooks/claude-mthds-check.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Entry point of the `.mthds` post-edit hook bundle (`check.mjs`).
+ *
+ * One bundle serves all three harnesses behind `--platform=claude|codex|vibe`
+ * (default claude) — the platform decides how the edited file(s) are extracted
+ * from the stdin payload and which stdout dialect the decision is encoded in;
+ * the pipeline itself is identical:
+ *
+ *   1. local lint  (`@pipelex/tools-wasm` — offline, no credentials) → BLOCK on diagnostics
+ *   2. local format (same engine) → write back in place when changed
+ *   3. API validate (`POST /v1/validate` via the SDK, `allow_signatures: true`)
+ *      → BLOCK on an invalid verdict, non-blocking nudge on pending signatures
+ *
+ * Per-platform input: Claude reads `tool_input.file_path` (one file); Codex
+ * parses the `apply_patch` envelope in `tool_input.command` (possibly several
+ * files — outcomes are merged, any block wins); Vibe reads the stable
+ * `post_tool` payload (`tool_status` gate, path resolved against `cwd`).
+ *
+ * Failure posture (fail-open, per the networked-hook plan):
+ * - no `.mthds` in the payload / unparseable stdin → pass silently
+ * - WASM engine fails to load → whole hook unavailable → pass silently
+ * - validate unavailable (no `PIPELEX_API_KEY`, network error, timeout, any
+ *   non-2xx, bundle-gather overflow) → the local lint/format verdicts already
+ *   applied; the validate stage passes silently
+ *
+ * The hook always exits 0; a block/deny is expressed on stdout, never via the
+ * exit code.
+ */
+export {};

package/dist/hooks/claude-mthds-check.js

@@ -0,0 +1,220 @@
+/**
+ * Entry point of the `.mthds` post-edit hook bundle (`check.mjs`).
+ *
+ * One bundle serves all three harnesses behind `--platform=claude|codex|vibe`
+ * (default claude) — the platform decides how the edited file(s) are extracted
+ * from the stdin payload and which stdout dialect the decision is encoded in;
+ * the pipeline itself is identical:
+ *
+ *   1. local lint  (`@pipelex/tools-wasm` — offline, no credentials) → BLOCK on diagnostics
+ *   2. local format (same engine) → write back in place when changed
+ *   3. API validate (`POST /v1/validate` via the SDK, `allow_signatures: true`)
+ *      → BLOCK on an invalid verdict, non-blocking nudge on pending signatures
+ *
+ * Per-platform input: Claude reads `tool_input.file_path` (one file); Codex
+ * parses the `apply_patch` envelope in `tool_input.command` (possibly several
+ * files — outcomes are merged, any block wins); Vibe reads the stable
+ * `post_tool` payload (`tool_status` gate, path resolved against `cwd`).
+ *
+ * Failure posture (fail-open, per the networked-hook plan):
+ * - no `.mthds` in the payload / unparseable stdin → pass silently
+ * - WASM engine fails to load → whole hook unavailable → pass silently
+ * - validate unavailable (no `PIPELEX_API_KEY`, network error, timeout, any
+ *   non-2xx, bundle-gather overflow) → the local lint/format verdicts already
+ *   applied; the validate stage passes silently
+ *
+ * The hook always exits 0; a block/deny is expressed on stdout, never via the
+ * exit code.
+ */
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve as resolvePath } from "node:path";
+import { PipelexApiClient } from "../client.js";
+import { decideAfterLint, decideAfterValidate, encodeOutcome, extractCodexMthdsFiles, extractMthdsFilePath, extractVibeMthdsFilePath, mergeOutcomes, } from "./check-core.js";
+import { gatherBundle } from "./bundle-gather.js";
+/** Per-request ceiling on the one network call — well under the hook's overall timeout. */
+const VALIDATE_TIMEOUT_MS = 10_000;
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(chunk);
+    }
+    return Buffer.concat(chunks).toString("utf-8");
+}
+function parsePlatform(argv) {
+    for (const arg of argv) {
+        if (arg.startsWith("--platform=")) {
+            const value = arg.slice("--platform=".length);
+            if (value === "claude" || value === "codex" || value === "vibe") {
+                return value;
+            }
+        }
+    }
+    return "claude";
+}
+/** The absolute paths of edited `.mthds` files that exist on disk, per platform. */
+function resolveTargets(platform, stdinJson) {
+    let candidates;
+    switch (platform) {
+        case "claude": {
+            const filePath = extractMthdsFilePath(stdinJson);
+            candidates = filePath ? [filePath] : [];
+            break;
+        }
+        case "codex": {
+            candidates = extractCodexMthdsFiles(stdinJson).map((raw) => resolvePath(process.cwd(), raw));
+            break;
+        }
+        case "vibe": {
+            const extracted = extractVibeMthdsFilePath(stdinJson);
+            candidates = extracted
+                ? [resolvePath(extracted.cwd ?? process.cwd(), extracted.filePath)]
+                : [];
+            break;
+        }
+    }
+    // Deleted/renamed-away files have nothing to check (Codex envelopes list
+    // paths that may not survive the patch; Claude edits can race a delete).
+    return candidates.filter((filePath) => existsSync(filePath));
+}
+/**
+ * Load the WASM engine. The one-line "deprecated parameters" warning the
+ * wasm-bindgen loader glue prints on first initialize is dropped — it is
+ * upstream noise, not a hook diagnostic.
+ */
+async function loadEngine() {
+    const engine = await import("@pipelex/tools-wasm");
+    /* eslint-disable no-console */
+    const originalWarn = console.warn;
+    console.warn = (...args) => {
+        if (typeof args[0] === "string" && args[0].includes("deprecated parameters")) {
+            return;
+        }
+        originalWarn.apply(console, args);
+    };
+    try {
+        await engine.initialize();
+    }
+    finally {
+        console.warn = originalWarn;
+    }
+    /* eslint-enable no-console */
+    return engine;
+}
+/**
+ * Run the networked validate stage. Every no-verdict condition maps to
+ * `unavailable` — a machine consumer branches on the structured verdict,
+ * never on transport.
+ */
+async function runValidateStage(filePath) {
+    if (!process.env.PIPELEX_API_KEY) {
+        return { status: "unavailable" };
+    }
+    const gathered = gatherBundle(filePath);
+    if (!gathered.ok) {
+        return { status: "unavailable" };
+    }
+    try {
+        const client = new PipelexApiClient();
+        // The client owns the ceiling: on timeout it aborts the fetch itself, so the
+        // request does not keep running after the hook has given up on it.
+        const result = await client.validateFiles(gathered.files, {
+            allowSignatures: true,
+            timeoutMs: VALIDATE_TIMEOUT_MS,
+        });
+        if (result.is_valid === true) {
+            return {
+                status: "valid",
+                pendingSignatures: Array.isArray(result.pending_signatures)
+                    ? result.pending_signatures
+                    : [],
+            };
+        }
+        if (result.is_valid === false) {
+            return {
+                status: "invalid",
+                message: result.message,
+                validationErrors: Array.isArray(result.validation_errors) ? result.validation_errors : [],
+                renderedMarkdown: result.rendered_markdown,
+            };
+        }
+        return { status: "unavailable" }; // no discriminant — no verdict
+    }
+    catch {
+        return { status: "unavailable" };
+    }
+}
+/** Synchronous fd-1 write — the process exits right after, an async write could truncate. */
+function emit(outcome, platform) {
+    const encoded = encodeOutcome(outcome, platform);
+    if (encoded) {
+        writeFileSync(1, encoded);
+    }
+}
+/** Synchronous fd-2 write, for the same reason. */
+function warn(message) {
+    writeFileSync(2, `[mthds-hook] ${message}\n`);
+}
+/** The full pipeline on one edited file: lint → format write-back → validate. */
+async function checkOneFile(engine, filePath) {
+    let content;
+    try {
+        content = readFileSync(filePath, "utf-8");
+    }
+    catch {
+        return { kind: "pass" }; // file gone since the existence check — nothing to gate
+    }
+    // Stage 1 — local lint
+    const lintStage = {
+        status: "diagnostics",
+        diagnostics: engine.lintMthds(content).diagnostics,
+    };
+    const lintOutcome = decideAfterLint(filePath, lintStage);
+    if (lintOutcome.kind !== "pass") {
+        return lintOutcome;
+    }
+    // Stage 2 — local format, write back in place (mirrors `plxt fmt`)
+    try {
+        const formatted = engine.formatMthds(content);
+        if (formatted.changed) {
+            writeFileSync(filePath, formatted.formatted);
+        }
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        warn(`Warning: format failed: ${message}`);
+    }
+    // Stage 3 — API validate
+    return decideAfterValidate(filePath, await runValidateStage(filePath));
+}
+async function main() {
+    const platform = parsePlatform(process.argv.slice(2));
+    const filePaths = resolveTargets(platform, await readStdin());
+    if (filePaths.length === 0) {
+        return;
+    }
+    let engine;
+    try {
+        engine = await loadEngine();
+    }
+    catch {
+        return; // engine unavailable — whole hook fails open
+    }
+    const outcomes = [];
+    for (const filePath of filePaths) {
+        outcomes.push(await checkOneFile(engine, filePath));
+    }
+    emit(mergeOutcomes(outcomes), platform);
+}
+main()
+    .catch((err) => {
+    // Fail open: an unexpected hook fault must never block the write.
+    const message = err instanceof Error ? err.message : String(err);
+    warn(`Hook error (fail-open): ${message}`);
+})
+    .finally(() => {
+    // The WASM engine (and any raced-out fetch) can hold the event loop open;
+    // the decision is already flushed (synchronous fd writes), so end the
+    // process deterministically.
+    process.exit(0);
+});
+//# sourceMappingURL=claude-mthds-check.js.map

package/dist/hooks/claude-mthds-check.js.map

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

package/dist/index.d.ts

@@ -7,13 +7,15 @@
  * errors. Consumers should import everything they need from `@pipelex/sdk`.
  */
 /** Package version. Kept in sync with `package.json` — enforced by `tests/index.test.ts`. */
-export declare const SDK_VERSION = "0.3.1";
+export declare const SDK_VERSION = "0.5.0";
 export * from "mthds/protocol";
 export { PipelexApiClient, DEFAULT_API_BASE_URL } from "./client.js";
 export type { MthdsFile, ValidateFilesOptions, PipelexApiClientOptions } from "./client.js";
 export { PipelexExecuteResult } from "./execute-result.js";
-export type { DictStuff, DictWorkingMemory, DictPipeOutput, DictRunResultExecute, DryRunStatus, ValidatedPipeEntry, PipelexValidationReport, PipelexInvalidReport, PipelexValidationResult, ValidationErrorCategory, ValidationErrorItem, ConceptRepresentationFormat, BuildInputsRequest, BuildOutputRequest, BuildRunnerRequest, ConceptRequest, PipeSpecRequest, BuildRunnerResponse, ConceptResponse, PipeSpecResponse, } from "./models.js";
+export type { UploadableAsset, UploadFileOptions, UploadRecord } from "./upload.js";
+export type { PrepareInputsRequest, PreparedInputs } from "./prepare-inputs.js";
+export type { DiagnosticKind, DiagnosticRange, Diagnostic, LintResponse, FormatResponse, DictStuff, DictWorkingMemory, DictPipeOutput, DictRunResultExecute, DryRunStatus, ValidatedPipeEntry, PipelexValidationReport, PipelexInvalidReport, PipelexValidationResult, ValidationErrorCategory, ValidationErrorItem, ConceptRepresentationFormat, InputsTemplateFormat, MthdsFileItem, BuildRequestBase, BuildInputsRequest, BuildOutputRequest, BuildRunnerRequest, ConceptRequest, PipeSpecRequest, CrateInvalidReport, BuildInputsValidReport, BuildOutputValidReport, BuildRunnerValidReport, GeneratedArtifact, RunnerStructures, BuildInputsResponse, BuildOutputResponse, BuildRunnerResponse, ConceptResponse, PipeSpecResponse, } from "./models.js";
 export type { UserProfile, MethodData, MethodWriteInput, Membership, MembershipsResponse, SubscriptionResponse, PlanView, InvoiceView, CheckoutResponse, ChangePlanResponse, BillingPortalResponse, PipelexApiKey, PipelexApiKeyCreated, PipelexApiKeyList, GatewayApiKey, GatewayApiKeyStatus, OnboardingRole, OnboardingCurrentTool, OnboardingInputType, OnboardingHeardFrom, OnboardingSubmission, ResolvedStorageUrl, UploadInput, UploadedFile, PipeStatus, PipelineRun, UpdateRunInput, } from "./product-models.js";
 export { isTerminalRunStatus, isSuccessRunStatus } from "./runs.js";
-export type { RunStatus, RunPublic, RunRead, RunResults, RunResultState, WaitForResultOptions, } from "./runs.js";
-export { ApiResponseError, ApiUnreachableError, ClientAuthenticationError, MissingMainStuffError, PipelineExecuteTimeoutError, RunFailedError, RunTimeoutError, RunStillRunningError, RunLifecycleUnavailableError, } from "./errors.js";
+export type { RunStatus, RunPublic, RunRead, RunResults, RunResultState, TokensUsageRecord, WaitForResultOptions, } from "./runs.js";
+export { ApiResponseError, ApiUnreachableError, ClientAuthenticationError, MissingMainStuffError, PipelineExecuteTimeoutError, RunFailedError, RunTimeoutError, RunStillRunningError, RunLifecycleUnavailableError, InputPreparationError, InvalidLocalSourceError, RejectedAssetError, UnsupportedUploadCapabilityError, UploadAuthenticationError, UploadTransportError, } from "./errors.js";

package/dist/index.js

@@ -7,7 +7,7 @@
  * errors. Consumers should import everything they need from `@pipelex/sdk`.
  */
 /** Package version. Kept in sync with `package.json` — enforced by `tests/index.test.ts`. */
-export const SDK_VERSION = "0.3.1";
+export const SDK_VERSION = "0.5.0";
 // ── Pure MTHDS Protocol surface (re-exported from the `mthds/protocol` subpath) ──
 // The standard's interface, wire models, request/options surface, abstract domain
 // shapes, and the protocol-base `PipelineRequestError`. Re-exported so apps have a
@@ -20,5 +20,5 @@ export { PipelexExecuteResult } from "./execute-result.js";
 // ── Run lifecycle (hosted extension — NOT part of the protocol) ──────
 export { isTerminalRunStatus, isSuccessRunStatus } from "./runs.js";
 // ── Typed errors (PipelineRequestError rides the protocol re-export above) ──
-export { ApiResponseError, ApiUnreachableError, ClientAuthenticationError, MissingMainStuffError, PipelineExecuteTimeoutError, RunFailedError, RunTimeoutError, RunStillRunningError, RunLifecycleUnavailableError, } from "./errors.js";
+export { ApiResponseError, ApiUnreachableError, ClientAuthenticationError, MissingMainStuffError, PipelineExecuteTimeoutError, RunFailedError, RunTimeoutError, RunStillRunningError, RunLifecycleUnavailableError, InputPreparationError, InvalidLocalSourceError, RejectedAssetError, UnsupportedUploadCapabilityError, UploadAuthenticationError, UploadTransportError, } from "./errors.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,6FAA6F;AAC7F,MAAM,CAAC,MAAM,WAAW,GAAG,OAAO,CAAC;AAEnC,oFAAoF;AACpF,kFAAkF;AAClF,mFAAmF;AACnF,wBAAwB;AACxB,cAAc,gBAAgB,CAAC;AAE/B,wEAAwE;AACxE,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAGrE,4FAA4F;AAC5F,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAyD3D,wEAAwE;AACxE,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAUpE,+EAA+E;AAC/E,OAAO,EACL,gBAAgB,EAChB,mBAAmB,EACnB,yBAAyB,EACzB,qBAAqB,EACrB,2BAA2B,EAC3B,cAAc,EACd,eAAe,EACf,oBAAoB,EACpB,4BAA4B,GAC7B,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,6FAA6F;AAC7F,MAAM,CAAC,MAAM,WAAW,GAAG,OAAO,CAAC;AAEnC,oFAAoF;AACpF,kFAAkF;AAClF,mFAAmF;AACnF,wBAAwB;AACxB,cAAc,gBAAgB,CAAC;AAE/B,wEAAwE;AACxE,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAGrE,4FAA4F;AAC5F,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AA8E3D,wEAAwE;AACxE,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAWpE,+EAA+E;AAC/E,OAAO,EACL,gBAAgB,EAChB,mBAAmB,EACnB,yBAAyB,EACzB,qBAAqB,EACrB,2BAA2B,EAC3B,cAAc,EACd,eAAe,EACf,oBAAoB,EACpB,4BAA4B,EAC5B,qBAAqB,EACrB,uBAAuB,EACvB,kBAAkB,EAClB,gCAAgC,EAChC,yBAAyB,EACzB,oBAAoB,GACrB,MAAM,aAAa,CAAC"}

package/dist/models.d.ts

@@ -22,10 +22,18 @@ export interface DictWorkingMemory {
  * runtime-internal field produced by the pipelex runtime inside the
  * `pipe_output` payload — it deliberately keeps its name (runtime internals are
  * out of the wire-rename scope).
+ *
+ * **Extension-open**, mirroring `DictPipeOutputAbstract`'s `extra="allow"`: the
+ * runner rides Pipelex extension fields here beside `working_memory` — the usage
+ * pair (`tokens_usages` / `usage_assembly_error`) is the current example. Without
+ * the index signature, reading one means casting the whole value away, and the
+ * two SDK mirrors of the same wire shape disagree on whether it is closed.
  */
 export interface DictPipeOutput {
     working_memory: DictWorkingMemory;
     pipeline_run_id: string;
+    /** Pipelex extension fields the runner rides on the pipe output. */
+    [extension: string]: unknown;
 }
 /**
  * The default `RunResultExecute` binding — the concrete execute result with a
@@ -136,19 +144,95 @@ export interface ValidationErrorItem {
     missing_concept_code?: string;
     declared_concepts?: string[];
 }
+/** Which analysis produced a `Diagnostic` — mirror of `pipelex-tools`' closed kind set. */
+export type DiagnosticKind = "syntax" | "semantic" | "schema";
+/** Source span of a `Diagnostic` — byte offsets plus 1-based line/column coordinates. */
+export interface DiagnosticRange {
+    start_offset: number;
+    end_offset: number;
+    start_line: number;
+    start_col: number;
+    end_line: number;
+    end_col: number;
+}
+/**
+ * One structured lint/format diagnostic — mirror of pipelex's `Diagnostic`.
+ * `severity` stays an open string (the server does not close the vocabulary);
+ * `location` and `range` are `null` when the analysis cannot attribute a span.
+ */
+export interface Diagnostic {
+    kind: DiagnosticKind;
+    severity: string;
+    message: string;
+    location: string | null;
+    range: DiagnosticRange | null;
+}
+/** `POST /v1/lint` 200 body — the diagnostics of one linted `.mthds` file. */
+export interface LintResponse {
+    diagnostics: Diagnostic[];
+}
+/**
+ * `POST /v1/format` 200 body — the canonically formatted content, whether it
+ * differs from the submitted one, and any diagnostics found on the way. A syntax
+ * error yields `changed: false` with the content echoed back unchanged.
+ */
+export interface FormatResponse {
+    formatted: string;
+    changed: boolean;
+    diagnostics: Diagnostic[];
+}
 export type ConceptRepresentationFormat = "json" | "python" | "schema";
-export interface BuildInputsRequest {
-    mthds_contents: string[];
-    pipe_code: string;
+/** Encoding of a `/v1/build/inputs` template. Decides which field carries it back. */
+export type InputsTemplateFormat = "json" | "toml";
+/**
+ * One MTHDS file in a build closure. `source` is an optional provenance label (a
+ * filename, a URI) that the server threads onto every diagnostic it raises from
+ * this file, so an invalid verdict can point at the file that caused it.
+ *
+ * NOT the same type as `MthdsFile` (the one `validateFiles()` takes), which the
+ * client adapts into `/v1/validate`'s parallel `mthds_contents` + `mthds_sources`
+ * arrays: that route spells the label `uri`, this envelope spells it `source`. The
+ * two collapse into one only if `/v1/validate` ever migrates onto `files[]` — a
+ * protocol-level change owned by the MTHDS standard, not ours to make here.
+ */
+export interface MthdsFileItem {
+    content: string;
+    source?: string;
 }
-export interface BuildOutputRequest {
-    mthds_contents: string[];
-    pipe_code: string;
+/**
+ * The closure + pipe selector every `/v1/build/*` route shares.
+ *
+ * Supply the closure EITHER as inline `files` OR as a `method_ref` into the method
+ * registry — never both. `method_ref` is reserved: the registry does not exist yet,
+ * so the server answers `501` for it today.
+ */
+export interface BuildRequestBase {
+    files?: MthdsFileItem[];
+    method_ref?: string;
+    /**
+     * The pipe to project, as a QUALIFIED `domain.pipe_code` ref. Omit it to default
+     * to the closure's declared `main_pipe` — which fails (422) when the closure
+     * declares none, or declares several across its domains.
+     */
+    pipe_ref?: string;
+}
+export interface BuildInputsRequest extends BuildRequestBase {
+    /** `json` (default) puts the parsed template in `inputs`; `toml` puts raw text in `inputs_toml`. */
+    format?: InputsTemplateFormat;
+    /** Emit the ceremonial `{concept, content}` envelope per input. Defaults to the light shape. */
+    explicit?: boolean;
+}
+export interface BuildOutputRequest extends BuildRequestBase {
+    /** `schema` (default) and `json` put a parsed object in `output`; `python` puts source in `output_python`. */
     format?: ConceptRepresentationFormat;
 }
-export interface BuildRunnerRequest {
-    mthds_contents: string[];
-    pipe_code: string;
+export interface BuildRunnerRequest extends BuildRequestBase {
+    /**
+     * Accept unresolved pipe signatures as pending rather than invalid. Alone among
+     * the build routes this one still runs the dry-run sweep, and the flag only ever
+     * parameterized that sweep.
+     */
+    allow_signatures?: boolean;
 }
 export interface ConceptRequest {
     spec: Record<string, unknown>;
@@ -157,12 +241,92 @@ export interface PipeSpecRequest {
     pipe_type: string;
     spec: Record<string, unknown>;
 }
-export interface BuildRunnerResponse {
-    python_code: string;
-    pipe_code: string;
-    success: boolean;
+/**
+ * The `is_valid: false` arm shared by every `/v1/build/*` route.
+ *
+ * The build routes follow `/validate`'s discipline: an unresolvable closure is the
+ * *successful product* of the call (the request was well-formed, the library was
+ * not), so it rides a **200** discriminated on `is_valid` — never a 4xx. Only a
+ * no-verdict condition (an unknown `pipe_ref`, `method_ref`, auth, a server fault)
+ * throws `ApiResponseError`. Branch on `is_valid`, never on the transport.
+ */
+export interface CrateInvalidReport {
+    is_valid: false;
+    validation_errors: ValidationErrorItem[];
     message: string;
 }
+/** Fields the valid arm of every `/v1/build/*` route carries. */
+interface BuildValidReportBase {
+    is_valid: true;
+    /** The qualified pipe that was projected — the RESOLVED selector, always `domain.pipe_code`. */
+    pipe_ref: string;
+    /** The `pipe_ref` as submitted. Absent when it was omitted and defaulted to `main_pipe`. */
+    requested_pipe_ref?: string;
+    message: string;
+}
+/**
+ * The `/v1/build/inputs` valid arm. The template rides ONE of two fields, chosen by
+ * `format`: `inputs` (a parsed object) for `json`, `inputs_toml` (raw text) for
+ * `toml`. TOML cannot be carried as a parsed object without losing what makes it
+ * worth asking for — its concept comments and key order — so the two are separate
+ * fields and the unused one is absent from the body entirely.
+ *
+ * That "absent entirely" is why this is a union rather than one interface with two
+ * optional fields: `format` is a real discriminant, so narrowing on it hands you the
+ * field it selected as REQUIRED, with the other one statically unreachable.
+ */
+interface BuildInputsJsonReport extends BuildValidReportBase {
+    format: "json";
+    explicit: boolean;
+    inputs: Record<string, unknown>;
+    inputs_toml?: never;
+}
+interface BuildInputsTomlReport extends BuildValidReportBase {
+    format: "toml";
+    explicit: boolean;
+    inputs?: never;
+    inputs_toml: string;
+}
+export type BuildInputsValidReport = BuildInputsJsonReport | BuildInputsTomlReport;
+export type BuildInputsResponse = BuildInputsValidReport | CrateInvalidReport;
+/**
+ * The `/v1/build/output` valid arm. Same two-field split as the inputs template, for
+ * the same reason: `schema` and `json` are objects, `python` is source text — and so
+ * it is a discriminated union for the same reason too.
+ */
+interface BuildOutputObjectReport extends BuildValidReportBase {
+    format: "schema" | "json";
+    output: Record<string, unknown>;
+    output_python?: never;
+}
+interface BuildOutputPythonReport extends BuildValidReportBase {
+    format: "python";
+    output?: never;
+    output_python: string;
+}
+export type BuildOutputValidReport = BuildOutputObjectReport | BuildOutputPythonReport;
+export type BuildOutputResponse = BuildOutputValidReport | CrateInvalidReport;
+/** One stamped generated file in the structures projection. */
+export interface GeneratedArtifact {
+    path: string;
+    content: string;
+}
+/**
+ * The typed-structures projection the runner script imports from. Write `artifacts`
+ * and `lock` (as `lock_filename`) under `directory`, relative to the runner script,
+ * and the returned `python_code` runs against them.
+ */
+export interface RunnerStructures {
+    directory: string;
+    artifacts: GeneratedArtifact[];
+    lock: string;
+    lock_filename: string;
+}
+export interface BuildRunnerValidReport extends BuildValidReportBase {
+    python_code: string;
+    structures: RunnerStructures;
+}
+export type BuildRunnerResponse = BuildRunnerValidReport | CrateInvalidReport;
 export interface ConceptResponse {
     success: boolean;
     concept_code: string;
@@ -174,3 +338,4 @@ export interface PipeSpecResponse {
     pipe_type: string;
     toml: string;
 }
+export {};

package/dist/prepare-inputs.d.ts

@@ -0,0 +1,54 @@
+/**
+ * `prepareInputs` — signature-driven input preparation. Resolves the target
+ * pipe's declared inputs via the explicit inputs template, interprets the
+ * caller's compact inputs top-down against it, uploads the file-bearing values,
+ * and returns rewritten inputs (canonical content carrying `pipelex-storage://`
+ * in `url`) plus one upload record per prepared asset.
+ *
+ * The classification mirrors the runtime: `pipelex`'s `input_normalizer` walks
+ * Image/Document contents (recognized by their `url`-bearing shape, incl. nested
+ * in structured content) and `resolve_uri` decides upload vs pass-through. The
+ * declared signature comes from the explicit template (`buildInputs`,
+ * `explicit: true`), whose canonical content shape is the classifier — the file
+ * signal is a value that is a dict containing a `url` key. See the shared
+ * behavior matrix (`wip/upload/behavior-matrix.md`) and `docs/input-preparation.md`.
+ */
+import type { BuildInputsResponse, MthdsFileItem } from "./models.js";
+import type { UploadCapableClient, UploadRecord } from "./upload.js";
+/** What `prepareInputs` takes: the method closure, the target pipe, and the caller's compact inputs. */
+export interface PrepareInputsRequest {
+    /** The method closure — inline MTHDS files. This is the signature source. */
+    files: MthdsFileItem[];
+    /** The pipe to prepare inputs for, as a qualified `domain.pipe_code`; omit to default to the closure's `main_pipe`. */
+    pipe_ref?: string;
+    /** The caller's compact inputs (variable name → value). */
+    inputs: Record<string, unknown>;
+}
+/** The result of `prepareInputs`: rewritten inputs (copy-on-write) plus upload records. */
+export interface PreparedInputs {
+    /** A copy of `inputs` with each file-bearing value rewritten to canonical content carrying `pipelex-storage://` in `url`. */
+    inputs: Record<string, unknown>;
+    /** One record per uploaded asset, exposing `uri`. Pass-through references (http(s), existing storage URIs) produce no record. */
+    uploads: UploadRecord[];
+}
+/** The client surface `prepareInputs` needs: raw `upload` plus the `buildInputs` signature source. */
+export interface PrepareCapableClient extends UploadCapableClient {
+    buildInputs(request: {
+        files: MthdsFileItem[];
+        pipe_ref?: string;
+        format?: "json";
+        explicit?: boolean;
+    }): Promise<BuildInputsResponse>;
+}
+/**
+ * Prepare a pipe's inputs: upload local/byte/data-URL assets at the signature's
+ * file-bearing positions and return copy-on-write rewritten inputs plus upload
+ * records. HTTP(S) URLs and existing `pipelex-storage://` URIs pass through
+ * unchanged. All failures are raised before any run is created.
+ *
+ * The declared signature is resolved from the closure; a closure that does not
+ * resolve throws {@link InputPreparationError}. No-verdict conditions from the
+ * signature route (unknown `pipe_ref`, auth, server fault) surface as the build
+ * route's `ApiResponseError`.
+ */
+export declare function prepareInputs(client: PrepareCapableClient, request: PrepareInputsRequest): Promise<PreparedInputs>;