@pipelex/sdk 0.22.0 → 0.24.0

package/README.md

@@ -112,7 +112,7 @@ These pages ship inside the published package, so a reader who has only installe
 | [`docs/architecture.md`](./docs/architecture.md) | The whole client surface: the request pipeline, every route, the typed errors |
 | [`docs/run-results.md`](./docs/run-results.md) | Every field of `RunResults` — the run id as a durable handle, `main_stuff`, `working_memory`, `graph_spec`, the usage pair, produced files |
 | [`docs/run-usage.md`](./docs/run-usage.md) | What a run consumed, record by record, and `summarizeUsage` which folds them into one reading |
-| [`docs/artifact-download.md`](./docs/artifact-download.md) | Turning the `pipelex-storage://` references a run produced back into bytes: `collectArtifacts`, `resolveArtifacts`, `fetchArtifact`, `downloadArtifacts` |
+| [`docs/artifact-download.md`](./docs/artifact-download.md) | Turning the `pipelex-storage://` references a run produced back into bytes: `locateArtifacts`, `collectArtifacts`, `resolveArtifacts`, `fetchArtifact`, `downloadArtifacts`, and how a saved file is named after the field it fills |
 | [`docs/input-preparation.md`](./docs/input-preparation.md) | The other direction — `uploadFile` and `prepareInputs`, which turn local files into references a run can take, and the upload grant a browser page sends a file with |
 | [`docs/crate-routes.md`](./docs/crate-routes.md) | `resolve` and `codegen`, and the offline `runCodegenCheck` that guards a committed tree |
 | [`docs/build-routes.md`](./docs/build-routes.md) | The `/v1/build/*` projections: `buildInputs`, `buildOutput`, `buildRunner` |

package/dist/artifacts.d.ts

@@ -2,8 +2,9 @@
  * The artifact stack — the download twin of `prepareInputs`, in layers so each
  * operation is usable without the next:
  *
- * - {@link collectArtifacts} — a pure walk of any JSON value for the strings that
- *   ARE `pipelex-storage://` references. No network, no key.
+ * - {@link locateArtifacts} — a pure walk of any JSON value for the strings that
+ *   ARE `pipelex-storage://` references, each with every path it sits at.
+ *   {@link collectArtifacts} is the same walk's bare references. No network, no key.
  * - {@link resolveArtifacts} — the platform's bulk resolve route over a whole
  *   list, chunked at the route's bound, one verdict per reference.
  * - {@link fetchArtifact} — a bounded `Response` for one reference: resolved
@@ -20,7 +21,7 @@
  *
  * `node:fs/promises`, `node:path` and `undici` are imported dynamically, behind
  * `isNodeRuntime()`, so the module's static import graph stays free of Node
- * builtins: `collectArtifacts` and `resolveArtifacts` run anywhere, `fetchArtifact`
+ * builtins: the walk and `resolveArtifacts` run anywhere, `fetchArtifact`
  * runs anywhere the global `fetch` does (the dispatcher is a Node refinement), and
  * only `downloadArtifacts` touches a filesystem.
  */
@@ -91,7 +92,10 @@ export interface BulkResolvedStorageUrls {
 export interface FetchArtifactOptions {
     /** Refuse (before a byte is written) and cut (mid-stream) a body over this many bytes. Default 1 GiB. */
     maxBytes?: number;
-    /** Budget for the whole exchange — connect, headers and body. Default 120 s. */
+    /**
+     * Budget for the whole exchange — connect, headers and body. Default 120 s. At most
+     * 2147483647, the longest delay a timer honours.
+     */
     timeoutMs?: number;
     /**
      * Accept a plain `http:` link. Off by default: a general-purpose library does
@@ -135,14 +139,36 @@ export type DownloadArtifactsRequest = DownloadArtifactsOptions & ({
     results: RunResults;
     run_id?: never;
 });
+/**
+ * Where one `pipelex-storage://` reference sits in a walked value — what
+ * {@link locateArtifacts} answers per reference. `found_at` lists every path at
+ * which the reference occurs, in walk order, and is never empty: `found_at[0]` is
+ * where it was first seen, and the path a saved file is named after.
+ *
+ * A path is `$`-rooted: `$` is the walked value itself, an object key matching
+ * `^[A-Za-z_][A-Za-z0-9_]*$` is `.key`, any other key is `["…"]` in JSON string
+ * escaping, and an array index is `[n]` — `$.rooms[3].staged_photo.url`,
+ * `$.items[0].url`, `$["a key"].url`. It is the exact path of the string, the
+ * final `url` of a content object included.
+ */
+export interface ArtifactLocation {
+    /** The reference, exactly as it appears in the walked value. */
+    uri: string;
+    /** Every `$`-rooted path at which the reference occurs, in walk order. */
+    found_at: string[];
+}
 /**
  * One reference's outcome in a download verdict — one shape with nullable fields,
  * like {@link ResolvedArtifact}: either `path` and `size` are set and `error` is
- * null, or `error` is set and both are null. `content_type` is the platform's
- * guess from the reference's extension, known before the fetch, on both arms.
+ * null, or `error` is set and both are null. `found_at` says where the reference
+ * sits in the walked scope, and `content_type` is the platform's guess from the
+ * reference's extension, known before the fetch; both are on both arms, so an
+ * item that was not saved still says which field it would have filled.
  */
 export type DownloadedArtifact = {
     uri: string;
+    /** Every `$`-rooted path in the walked scope where the reference sits; the first one named the file. */
+    found_at: string[];
     /** Absolute path of the written file. */
     path: string;
     content_type: string | null;
@@ -151,6 +177,8 @@ export type DownloadedArtifact = {
     error: null;
 } | {
     uri: string;
+    /** Every `$`-rooted path in the walked scope where the reference sits. */
+    found_at: string[];
     path: null;
     content_type: string | null;
     size: null;
@@ -185,32 +213,68 @@ export interface ArtifactCapableClient {
         signal?: AbortSignal;
     }): Promise<RunResultState>;
 }
+/**
+ * Every `pipelex-storage://` reference inside a JSON-shaped value, each with
+ * every path at which it occurs. The references are deduplicated and kept in
+ * discovery order (the order of their first sighting), and each one's `found_at`
+ * lists its paths in walk order, so `found_at[0]` is where it was first seen.
+ *
+ * The string test is {@link collectArtifacts}'s: a string counts only when it IS
+ * a reference. A path is rooted at `$`, the walked value itself; an object key
+ * matching `^[A-Za-z_][A-Za-z0-9_]*$` is written `.key`, any other key `["…"]` in
+ * JSON string escaping, and an array index `[n]`. The runtime serializes a
+ * produced image or document as content carrying its reference in `url`, so a
+ * typical path ends there: `$.rooms[3].staged_photo.url`, `$.items[0].url`, or
+ * `$.url` for an output that is one image. Pure — no network, no key.
+ */
+export declare function locateArtifacts(value: unknown): ArtifactLocation[];
 /**
  * Every `pipelex-storage://` reference inside a JSON-shaped value, deduplicated,
- * in discovery order. A string counts only when it IS a reference — the whole
- * string, scheme first, with something after the scheme; text that merely
- * contains one does not. The scheme is unambiguous, so this walk is a contract
- * rather than a heuristic: the runtime serializes a produced image or document
- * as content carrying its reference in `url`, beside an expiring `public_url`
- * this walk ignores. Pure — no network, no key — so a consumer can count or
- * list a run's produced files without resolving any of them.
+ * in discovery order — the references of {@link locateArtifacts}, without their
+ * paths. A string counts only when it IS a reference — the whole string, scheme
+ * first, with something after the scheme; text that merely contains one does
+ * not. The scheme is unambiguous, so this walk is a contract rather than a
+ * heuristic: the runtime serializes a produced image or document as content
+ * carrying its reference in `url`, beside an expiring `public_url` this walk
+ * ignores. Pure — no network, no key — so a consumer can count or list a run's
+ * produced files without resolving any of them.
  */
 export declare function collectArtifacts(value: unknown): string[];
 /** A string that is a storage reference: the scheme, then at least one character. */
 export declare function isStorageReference(value: string): boolean;
 /**
- * The bare filename a storage reference is saved under: the last segment of the
- * storage key, reduced to a conservative character set so it can never name
- * anything but a regular file directly inside the target directory. Path
- * separators are the split point, so no traversal survives; leading dots are
- * stripped, so no hidden file and no `..`; everything outside `[A-Za-z0-9._-]`
- * becomes `_`; an empty result falls back to a numbered `artifact-N`. Length is
- * capped with the extension preserved, and an extension is added from the
- * content type when the key carries none. A collision on disk is not this
+ * The bare filename a reference is saved under, named after the field it fills:
+ * the path in `location.found_at[0]`, where the reference was first seen.
+ *
+ * 1. A final object key `url` is dropped, since the runtime's image and
+ *    document contents carry their reference there; a reference under any other
+ *    key keeps that key, and a `url` key that is not final is kept.
+ * 2. Each key is reduced to `[A-Za-z0-9_]`, every other character (`-` and `.`
+ *    included) becoming `_`; an index stays its decimal digits.
+ * 3. The segments are joined with `-`. An empty result — the reference is the
+ *    walked value itself, or its `url` — becomes the scope's name.
+ * 4. Over the filename length cap (`MAX_FILENAME_LENGTH`, extension included),
+ *    the tail is kept: whole leading segments are dropped first, since the last
+ *    ones are the specific ones, and a single segment still too long is cut to
+ *    fit.
+ * 5. A stem Windows reserves for a device (`con`, `prn`, `aux`, `nul`,
+ *    `com0`–`com9`, `lpt0`–`lpt9`, in any case) gets a trailing `_`, so
+ *    `$.aux.url` is saved as `aux_.png`.
+ * 6. The extension is the storage key's own, reduced to `[A-Za-z0-9]`, when it
+ *    has a short one; otherwise the content type's, for the types a run
+ *    produces; otherwise there is none.
+ *
+ * So `$.rooms[3].staged_photo.url` is saved as `rooms-3-staged_photo.png`, and
+ * `$.url` in `main_stuff` as `main_stuff.png`. The stem is ASCII letters, digits,
+ * `_` and the `-` joins, never empty and never a device name, so the name can
+ * only ever be a regular file directly inside the target directory. A collision on disk is not this
  * function's concern: `downloadArtifacts` suffixes the stem (`name-1.ext`) on
  * exclusive creation, so a file is never overwritten.
+ *
+ * Throws `ArtifactOperationError` for a location whose `found_at[0]` is not a path
+ * in the notation {@link locateArtifacts} writes, or for an unknown scope.
  */
-export declare function artifactFilename(uri: string, contentType: string | null | undefined, index: number): string;
+export declare function artifactFilename(location: ArtifactLocation, contentType: string | null | undefined, scope: ArtifactScope): string;
 /**
  * Resolve a list of references through the bulk route, chunked at
  * {@link BULK_RESOLVE_MAX_URIS} per request, and answer one
@@ -264,19 +328,20 @@ export declare function writeFully(writer: ChunkWriter, chunk: Uint8Array): Prom
  * Save a run's produced files under `dir` — Node-only, like the path-string arm
  * of `uploadFile`. Takes a `run_id` (the results are re-read, so a run is
  * downloadable days later) or a `RunResults` in hand; walks the requested scope
- * with {@link collectArtifacts}; resolves the whole set through the bulk route
+ * with {@link locateArtifacts}; resolves the whole set through the bulk route
  * ahead of the workers; then a bounded pool of workers each fetch → open with
  * `wx` → write, re-resolving any link that has expired by the time a worker
- * reaches it. The embedded `public_url` is never used. Files are named by
- * {@link artifactFilename} and never overwritten; a failed or aborted download
- * unlinks its partial file.
+ * reaches it. The embedded `public_url` is never used. Each file is named after
+ * the field it fills, by {@link artifactFilename}'s rule, and never overwritten;
+ * a failed or aborted download unlinks its partial file.
  *
  * Returns a produced verdict: one entry per reference, errors as values. It
  * throws only when no verdict can be produced — `RunStillRunningError` or
  * `RunFailedError` for a run that has not completed, `ScopeUnavailableError`
  * when the scope's artifact is null or missing, `ArtifactAuthenticationError`
  * (carrying the verdict so far) when the resolve route refuses the credential,
- * `ArtifactOperationError` outside Node or for an unusable `dir`, and the
+ * `ArtifactOperationError` outside Node, for an unusable `dir` or for an
+ * unknown `scope`, and the
  * transport and lifecycle errors of the reads it makes (`ApiResponseError` for
  * a deployment without the bulk route, `RunLifecycleUnavailableError` for a
  * bare runner asked by id, `ApiUnreachableError`).