@pipelex/sdk 0.46.1 → 0.48.0

package/dist/hooks/validate-stage.js

@@ -0,0 +1,57 @@
+/**
+ * The `.mthds` post-edit hook's networked stage: the edited file's method tree validated through
+ * the SDK (`POST /v1/validate`, `allow_signatures: true`), held to one deadline over the whole
+ * stage, so the hook never outlasts its harness's patience whatever the network does.
+ */
+import { gatherMethodTree } from "./bundle-gather.js";
+import { createHookClient } from "./validate-client.js";
+/**
+ * The deadline over the whole validate stage, well under the hook's overall timeout: the version
+ * handshake, the blob route, the uploads of the files the API lacks (a tree up to the gatherer's
+ * caps, 12 MiB) and the validation itself all run under it.
+ */
+export const VALIDATE_TIMEOUT_MS = 10_000;
+/**
+ * Run the networked validate stage on `filePath`. Every no-verdict condition maps to
+ * `unavailable` — no API key, a tree the gatherer refuses, the deadline running out, any failure
+ * of the client — so a machine consumer branches on the structured verdict, never on transport,
+ * and the lint and format verdicts the hook already applied stand.
+ */
+export async function runValidateStage(filePath, options = {}) {
+    if (options.client === undefined && !process.env.PIPELEX_API_KEY) {
+        return { status: "unavailable" };
+    }
+    // One deadline over the whole stage: the signal reaches every request and upload the
+    // validation makes, each stopped in flight once it fires, so nothing keeps running after the
+    // hook has given up on it.
+    const deadline = AbortSignal.timeout(options.timeoutMs ?? VALIDATE_TIMEOUT_MS);
+    const gathered = await gatherMethodTree(filePath);
+    if (!gathered.ok) {
+        return { status: "unavailable" };
+    }
+    try {
+        const client = options.client ?? createHookClient();
+        const result = await client.validate({ tree: gathered.tree }, true, { signal: deadline });
+        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" };
+    }
+}
+//# sourceMappingURL=validate-stage.js.map

package/dist/hooks/validate-stage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-stage.js","sourceRoot":"","sources":["../../src/hooks/validate-stage.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAExD;;;;GAIG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,MAAM,CAAC;AAU1C;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,QAAgB,EAChB,UAAgC,EAAE;IAElC,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,eAAe,EAAE,CAAC;QACjE,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,CAAC;IACnC,CAAC;IACD,qFAAqF;IACrF,6FAA6F;IAC7F,2BAA2B;IAC3B,MAAM,QAAQ,GAAG,WAAW,CAAC,OAAO,CAAC,OAAO,CAAC,SAAS,IAAI,mBAAmB,CAAC,CAAC;IAC/E,MAAM,QAAQ,GAAG,MAAM,gBAAgB,CAAC,QAAQ,CAAC,CAAC;IAClD,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;QACjB,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,CAAC;IACnC,CAAC;IACD,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,gBAAgB,EAAE,CAAC;QACpD,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE,QAAQ,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC;QAC1F,IAAI,MAAM,CAAC,QAAQ,KAAK,IAAI,EAAE,CAAC;YAC7B,OAAO;gBACL,MAAM,EAAE,OAAO;gBACf,iBAAiB,EAAE,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,kBAAkB,CAAC;oBACzD,CAAC,CAAC,MAAM,CAAC,kBAAkB;oBAC3B,CAAC,CAAC,EAAE;aACP,CAAC;QACJ,CAAC;QACD,IAAI,MAAM,CAAC,QAAQ,KAAK,KAAK,EAAE,CAAC;YAC9B,OAAO;gBACL,MAAM,EAAE,SAAS;gBACjB,OAAO,EAAE,MAAM,CAAC,OAAO;gBACvB,gBAAgB,EAAE,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,iBAAiB,CAAC,CAAC,CAAC,EAAE;gBACzF,gBAAgB,EAAE,MAAM,CAAC,iBAAiB;aAC3C,CAAC;QACJ,CAAC;QACD,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,CAAC,CAAC,+BAA+B;IACnE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,CAAC;IACnC,CAAC;AACH,CAAC"}

package/dist/index.d.ts

@@ -12,9 +12,9 @@ export * from "mthds/protocol";
 export { PipelexApiClient, DEFAULT_API_BASE_URL, isGatewayCutOff } from "./client.js";
 export { buildUserAgent, validateAppInfo, MAX_USER_AGENT_LENGTH } from "./user-agent.js";
 export type { AppInfo, RuntimeInfo } from "./user-agent.js";
-export type { MthdsFile, PipelexApiRunExtensions, PipelexHostedRunExtensions, PipelexRunOptions, PipelexStartOptions, PipelexStartRequestOptions, ValidateMethodSelector, ValidateFilesOptions, ValidateOptions, PipelexApiClientOptions, } from "./client.js";
-export type { BundleResourceBytes, BundleResources } from "./bundle-resources.js";
-export { methodSourceToContents } from "./method-source.js";
+export type { PipelexApiRunExtensions, PipelexHostedRunExtensions, PipelexRunOptions, PipelexStartOptions, PipelexStartRequestOptions, PipelexValidateSource, ValidateMethodSelector, ValidateOptions, PipelexApiClientOptions, } from "./client.js";
+export { INLINE_TREE_MAX_BYTES } from "./method-trees.js";
+export type { MethodTreeForms, MethodTreeLimits } from "./method-trees.js";
 export { parseMethodSelector } from "./method-selector.js";
 export type { ParsedMethodSelector } from "./method-selector.js";
 export { ExactJsonUnsupportedError, parseExactJson, stringifyExactJson } from "./exact-json.js";
@@ -26,15 +26,15 @@ export type { InputFormFault, PrepareInputsBase, PrepareInputsClosure, PrepareIn
 export { inputFormFault } from "./prepare-inputs.js";
 export { locateArtifacts, collectArtifacts, artifactFilename, PIPELEX_STORAGE_SCHEME, BULK_RESOLVE_MAX_URIS, DEFAULT_ARTIFACT_MAX_BYTES, DEFAULT_ARTIFACT_TIMEOUT_MS, DEFAULT_DOWNLOAD_MAX_TOTAL_BYTES, DEFAULT_DOWNLOAD_CONCURRENCY, } from "./artifacts.js";
 export type { ArtifactItemError, ArtifactLocation, ArtifactScope, BulkResolveStorageUrlsInput, BulkResolvedStorageUrls, DownloadArtifactsOptions, DownloadArtifactsRequest, DownloadArtifactsResult, DownloadedArtifact, FetchArtifactOptions, ResolvedArtifact, } from "./artifacts.js";
-export type { DiagnosticKind, DiagnosticRange, Diagnostic, LintResponse, FormatResponse, DictStuff, DictWorkingMemory, DictPipeOutput, DictRunResultExecute, MethodProvenance, PipelexRunResultStart, PipelexHostedToolingExtensions, DryRunStatus, ValidatedPipeEntry, LiftablePipeEntry, PipelexValidationReport, PipelexInvalidReport, PipelexValidationResult, ValidationErrorCategory, ValidationErrorItem, FixSafety, FixOpKind, TomlScalar, TomlValue, FixValue, SetKeyOp, EnsureTableOp, DeleteKeyOp, DeleteTableOp, RenameTableKeyOp, MoveKeyOp, RemapValueOp, FixOp, SuggestedFix, MthdsFileItem, CrateRequestBase, CrateInvalidReport, GeneratedArtifact, ResolveRequest, ResolveValidReport, ResolveResponse, CodegenKind, CodegenTarget, CodegenRequest, CodegenValidReport, CodegenResponse, PipeIORequest, PipeIOValidReport, PipeIOResponse, ModelCheckCategory, ModelReferenceKind, ModelReferenceResolution, ModelReferenceMatchBase, PresetMatch, AliasMatch, WaterfallMatch, HandleMatch, ModelReferenceMatch, ModelReferenceVerdictBase, PresetReferenceVerdict, AliasReferenceVerdict, WaterfallReferenceVerdict, HandleReferenceVerdict, ModelReferenceVerdict, } from "./models.js";
+export type { DiagnosticKind, DiagnosticRange, Diagnostic, LintResponse, FormatResponse, DictStuff, DictWorkingMemory, DictPipeOutput, DictRunResultExecute, MethodProvenance, PipelexRunResultStart, PipelexHostedToolingExtensions, DryRunStatus, ValidatedPipeEntry, LiftablePipeEntry, TreeFileUse, TreeFileRead, PipelexValidationReport, PipelexInvalidReport, PipelexValidationResult, ValidationErrorCategory, ValidationErrorItem, FixSafety, FixOpKind, TomlScalar, TomlValue, FixValue, SetKeyOp, EnsureTableOp, DeleteKeyOp, DeleteTableOp, RenameTableKeyOp, MoveKeyOp, RemapValueOp, FixOp, SuggestedFix, CrateRequestBase, CrateRouteOptions, CrateInvalidReport, GeneratedArtifact, ResolveRequest, ResolveValidReport, ResolveResponse, CodegenKind, CodegenTarget, CodegenRequest, CodegenValidReport, CodegenResponse, PipeIORequest, PipeIOValidReport, PipeIOResponse, ModelCheckCategory, ModelReferenceKind, ModelReferenceResolution, ModelReferenceMatchBase, PresetMatch, AliasMatch, WaterfallMatch, HandleMatch, ModelReferenceMatch, ModelReferenceVerdictBase, PresetReferenceVerdict, AliasReferenceVerdict, WaterfallReferenceVerdict, HandleReferenceVerdict, ModelReferenceVerdict, } from "./models.js";
 export { runCodegenCheck, isStampableArtifactPath, STAMPABLE_ARTIFACT_SUFFIXES, CodegenLockError, } from "./codegen-check.js";
 export type { CodegenCheckInput, CodegenCheckReport, CodegenDrift, CodegenDriftCategory, CodegenTreeFile, } from "./codegen-check.js";
-export type { UserProfile, ListMethodExamplesQuery, ListMethodsQuery, ListMethodVersionsQuery, MethodData, MethodDeletionAccepted, MethodDeletionState, MethodDraftInput, MethodExample, MethodExampleCreateInput, MethodExampleLatestRunInput, MethodExampleLatestRunOutcome, MethodExampleLatestRunRecorded, MethodExampleLatestRunResult, MethodExampleLatestRunStale, MethodExamplePage, MethodExampleUpdateInput, MethodPage, MethodPublished, MethodPublishInput, MethodPublishOutcome, MethodPublishRefusalReason, MethodPublishRefused, MethodPublishResult, MethodPublishUnchanged, MethodRenameInput, MethodSummary, MethodVersion, MethodVersionPage, MethodVersionSummary, MethodWriteInput, Membership, MembershipsResponse, OrgRole, SubscriptionResponse, PlanView, InvoiceView, CheckoutResponse, ChangePlanResponse, BillingPortalResponse, PipelexApiKey, PipelexApiKeyCreated, PipelexApiKeyList, OnboardingRole, OnboardingCurrentTool, OnboardingInputType, OnboardingHeardFrom, OnboardingSubmission, ResolvedStorageUrl, UploadInput, UploadedFile, UploadGrantInput, UploadGrant, ListRunsQuery, PipelineRun, RunDetail, RunHistoryItem, RunPage, UpdateRunInput, } from "./product-models.js";
+export type { UserProfile, ListMethodExamplesQuery, ListMethodsQuery, ListMethodVersionsQuery, MethodData, MethodDeletionAccepted, MethodDeletionState, MethodDetail, MethodDraftInput, MethodExample, MethodExampleCreateInput, MethodExampleLatestRunInput, MethodExampleLatestRunOutcome, MethodExampleLatestRunRecorded, MethodExampleLatestRunResult, MethodExampleLatestRunStale, MethodExamplePage, MethodExampleUpdateInput, MethodPage, MethodPublished, MethodPublishInput, MethodPublishOutcome, MethodPublishRefusalReason, MethodPublishRefused, MethodPublishResult, MethodPublishUnchanged, MethodRenameInput, MethodSummary, MethodTreeInput, MethodVersion, MethodVersionPage, MethodVersionSummary, MethodWriteInput, SavedMethodFile, Membership, MembershipsResponse, OrgRole, SubscriptionResponse, PlanView, InvoiceView, CheckoutResponse, ChangePlanResponse, BillingPortalResponse, PipelexApiKey, PipelexApiKeyCreated, PipelexApiKeyList, OnboardingRole, OnboardingCurrentTool, OnboardingInputType, OnboardingHeardFrom, OnboardingSubmission, ResolvedStorageUrl, UploadInput, UploadedFile, UploadGrantInput, UploadGrant, ListRunsQuery, PipelineRun, RunDetail, RunHistoryItem, RunPage, UpdateRunInput, } from "./product-models.js";
 export { isFresherRunProgress, isTerminalRunStatus, isSuccessRunStatus, RUN_RESULT_ARTIFACTS, } from "./runs.js";
 export type { DegradationReason, GetRunResultOptions, ProgressAttempt, ProgressBatch, ProgressCondition, ProgressFailure, ProgressInvocation, ProgressInvocationStatus, RunDegradation, RunProgress, RunProgressStatus, RunResultArtifact, RunStatus, RunPublic, RunRead, RunResults, RunResultState, StartAndWaitForResultOptions, TokensUsageRecord, WaitForResultOptions, } from "./runs.js";
 export { summarizeUsage } from "./usage.js";
 export type { PipeUsageSummary, RunUsagePair, UsageSummary, UsageSummaryState, UsageTokenTotals, } from "./usage.js";
 export { problemVerdict } from "./error-verdicts.js";
-export { PipelexRequestError, errorVerdictOf, runMayHaveStartedOf, RequestArgumentError, ApiResponseError, ApiUnreachableError, MissingMainStuffError, PagingNotTerminatingError, PipelineExecuteTimeoutError, RunFailedError, RunTimeoutError, RunStillRunningError, RunLifecycleUnavailableError, InputPreparationError, EmptyMethodSourceError, InvalidLocalSourceError, InvalidInputValueError, UploadNotAllowedError, MethodLoadError, RejectedAssetError, UnsupportedUploadCapabilityError, UploadAuthenticationError, UploadTransportError, ArtifactOperationError, ArtifactAuthenticationError, ArtifactFetchError, ScopeUnavailableError, } from "./errors.js";
-export type { ApiResponseErrorOptions, ErrorDomain, ErrorVerdict, IdempotencyErrorCode, MethodErrorCode, RejectedAssetCode, UploadNotAllowedKind, UploadTransportCode, } from "./errors.js";
+export { PipelexRequestError, errorVerdictOf, runMayHaveStartedOf, RequestArgumentError, ApiResponseError, ApiUnreachableError, MissingMainStuffError, PagingNotTerminatingError, PipelineExecuteTimeoutError, RunFailedError, RunTimeoutError, RunStillRunningError, RunLifecycleUnavailableError, InputPreparationError, InvalidLocalSourceError, InvalidInputValueError, UploadNotAllowedError, MethodLoadError, RejectedAssetError, UnsupportedUploadCapabilityError, UploadAuthenticationError, UploadTransportError, ArtifactOperationError, ArtifactAuthenticationError, ArtifactFetchError, ScopeUnavailableError, MethodFileTransferError, } from "./errors.js";
+export type { ApiResponseErrorOptions, ErrorDomain, ErrorVerdict, IdempotencyErrorCode, MethodErrorCode, MethodFileTransferCode, MethodFileTransferOperation, RejectedAssetCode, UploadNotAllowedKind, UploadTransportCode, } from "./errors.js";
 export type { FieldError, MigrationErrorBlock, ProblemDetails, ProviderErrorMetadata, RunErrorReport, UserAction, } from "./error-models.js";

package/dist/index.js

@@ -19,8 +19,11 @@ export { PipelexApiClient, DEFAULT_API_BASE_URL, isGatewayCutOff } from "./clien
 // makes its own raw requests to the API sends the same value, and can check an `appInfo`
 // against the grammar and the length ceiling before constructing a client.
 export { buildUserAgent, validateAppInfo, MAX_USER_AGENT_LENGTH } from "./user-agent.js";
-// Canonical parser: a stored method's polymorphic `MethodData.mthds` source → bundle contents.
-export { methodSourceToContents } from "./method-source.js";
+// A method's tree: the four forms every method-taking route takes it in, the limits
+// `methodTreeLimits` reports, and the inline threshold below which a tree travels whole. The
+// standard's own tree types (`MethodTreeSource`, `BlobRef`, `MissingBlobsResult` and the rest)
+// come with the `mthds/protocol` re-export above.
+export { INLINE_TREE_MAX_BYTES } from "./method-trees.js";
 // A method selector (`mt_…`, `mt_…@<n>`, `mt_…@draft`) → its bare id and the version it names.
 export { parseMethodSelector } from "./method-selector.js";
 // JSON whose integers stay exact: the reader of the answers carrying a person's data (a method
@@ -57,5 +60,5 @@ export { summarizeUsage } from "./usage.js";
 // `runMayHaveStarted`, read with `runMayHaveStartedOf`. `problemVerdict` reads the standard's
 // problem in the same vocabulary, as `errorVerdictOf` reads an `mthds` error.
 export { problemVerdict } from "./error-verdicts.js";
-export { PipelexRequestError, errorVerdictOf, runMayHaveStartedOf, RequestArgumentError, ApiResponseError, ApiUnreachableError, MissingMainStuffError, PagingNotTerminatingError, PipelineExecuteTimeoutError, RunFailedError, RunTimeoutError, RunStillRunningError, RunLifecycleUnavailableError, InputPreparationError, EmptyMethodSourceError, InvalidLocalSourceError, InvalidInputValueError, UploadNotAllowedError, MethodLoadError, RejectedAssetError, UnsupportedUploadCapabilityError, UploadAuthenticationError, UploadTransportError, ArtifactOperationError, ArtifactAuthenticationError, ArtifactFetchError, ScopeUnavailableError, } from "./errors.js";
+export { PipelexRequestError, errorVerdictOf, runMayHaveStartedOf, RequestArgumentError, ApiResponseError, ApiUnreachableError, MissingMainStuffError, PagingNotTerminatingError, PipelineExecuteTimeoutError, RunFailedError, RunTimeoutError, RunStillRunningError, RunLifecycleUnavailableError, InputPreparationError, InvalidLocalSourceError, InvalidInputValueError, UploadNotAllowedError, MethodLoadError, RejectedAssetError, UnsupportedUploadCapabilityError, UploadAuthenticationError, UploadTransportError, ArtifactOperationError, ArtifactAuthenticationError, ArtifactFetchError, ScopeUnavailableError, MethodFileTransferError, } 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,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAE3C,oFAAoF;AACpF,kFAAkF;AAClF,mFAAmF;AACnF,wBAAwB;AACxB,cAAc,gBAAgB,CAAC;AAE/B,wEAAwE;AACxE,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACtF,sFAAsF;AACtF,yFAAyF;AACzF,2EAA2E;AAC3E,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAgBzF,+FAA+F;AAC/F,OAAO,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,+FAA+F;AAC/F,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAE3D,+FAA+F;AAC/F,6FAA6F;AAC7F,iGAAiG;AACjG,8FAA8F;AAC9F,iEAAiE;AACjE,OAAO,EAAE,yBAAyB,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAEhG,iGAAiG;AACjG,kFAAkF;AAClF,OAAO,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAK/E,yFAAyF;AACzF,sEAAsE;AACtE,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AASpD,+FAA+F;AAC/F,0EAA0E;AAC1E,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAErD,uEAAuE;AACvE,wFAAwF;AACxF,0FAA0F;AAC1F,iFAAiF;AACjF,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,gBAAgB,EAChB,sBAAsB,EACtB,qBAAqB,EACrB,0BAA0B,EAC1B,2BAA2B,EAC3B,gCAAgC,EAChC,4BAA4B,GAC7B,MAAM,gBAAgB,CAAC;AAmFxB,+EAA+E;AAC/E,4EAA4E;AAC5E,iFAAiF;AACjF,0EAA0E;AAC1E,OAAO,EACL,eAAe,EACf,uBAAuB,EACvB,2BAA2B,EAC3B,gBAAgB,GACjB,MAAM,oBAAoB,CAAC;AAwE5B,wEAAwE;AACxE,OAAO,EACL,oBAAoB,EACpB,mBAAmB,EACnB,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,WAAW,CAAC;AAwBnB,oFAAoF;AACpF,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAS5C,+EAA+E;AAC/E,gGAAgG;AAChG,8FAA8F;AAC9F,8EAA8E;AAC9E,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EACL,mBAAmB,EACnB,cAAc,EACd,mBAAmB,EACnB,oBAAoB,EACpB,gBAAgB,EAChB,mBAAmB,EACnB,qBAAqB,EACrB,yBAAyB,EACzB,2BAA2B,EAC3B,cAAc,EACd,eAAe,EACf,oBAAoB,EACpB,4BAA4B,EAC5B,qBAAqB,EACrB,sBAAsB,EACtB,uBAAuB,EACvB,sBAAsB,EACtB,qBAAqB,EACrB,eAAe,EACf,kBAAkB,EAClB,gCAAgC,EAChC,yBAAyB,EACzB,oBAAoB,EACpB,sBAAsB,EACtB,2BAA2B,EAC3B,kBAAkB,EAClB,qBAAqB,GACtB,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,6FAA6F;AAC7F,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAE3C,oFAAoF;AACpF,kFAAkF;AAClF,mFAAmF;AACnF,wBAAwB;AACxB,cAAc,gBAAgB,CAAC;AAE/B,wEAAwE;AACxE,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACtF,sFAAsF;AACtF,yFAAyF;AACzF,2EAA2E;AAC3E,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAczF,oFAAoF;AACpF,6FAA6F;AAC7F,+FAA+F;AAC/F,kDAAkD;AAClD,OAAO,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAE1D,+FAA+F;AAC/F,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAE3D,+FAA+F;AAC/F,6FAA6F;AAC7F,iGAAiG;AACjG,8FAA8F;AAC9F,iEAAiE;AACjE,OAAO,EAAE,yBAAyB,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAEhG,iGAAiG;AACjG,kFAAkF;AAClF,OAAO,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAK/E,yFAAyF;AACzF,sEAAsE;AACtE,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AASpD,+FAA+F;AAC/F,0EAA0E;AAC1E,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAErD,uEAAuE;AACvE,wFAAwF;AACxF,0FAA0F;AAC1F,iFAAiF;AACjF,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,gBAAgB,EAChB,sBAAsB,EACtB,qBAAqB,EACrB,0BAA0B,EAC1B,2BAA2B,EAC3B,gCAAgC,EAChC,4BAA4B,GAC7B,MAAM,gBAAgB,CAAC;AAqFxB,+EAA+E;AAC/E,4EAA4E;AAC5E,iFAAiF;AACjF,0EAA0E;AAC1E,OAAO,EACL,eAAe,EACf,uBAAuB,EACvB,2BAA2B,EAC3B,gBAAgB,GACjB,MAAM,oBAAoB,CAAC;AA2E5B,wEAAwE;AACxE,OAAO,EACL,oBAAoB,EACpB,mBAAmB,EACnB,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,WAAW,CAAC;AAwBnB,oFAAoF;AACpF,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAS5C,+EAA+E;AAC/E,gGAAgG;AAChG,8FAA8F;AAC9F,8EAA8E;AAC9E,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EACL,mBAAmB,EACnB,cAAc,EACd,mBAAmB,EACnB,oBAAoB,EACpB,gBAAgB,EAChB,mBAAmB,EACnB,qBAAqB,EACrB,yBAAyB,EACzB,2BAA2B,EAC3B,cAAc,EACd,eAAe,EACf,oBAAoB,EACpB,4BAA4B,EAC5B,qBAAqB,EACrB,uBAAuB,EACvB,sBAAsB,EACtB,qBAAqB,EACrB,eAAe,EACf,kBAAkB,EAClB,gCAAgC,EAChC,yBAAyB,EACzB,oBAAoB,EACpB,sBAAsB,EACtB,2BAA2B,EAC3B,kBAAkB,EAClB,qBAAqB,EACrB,uBAAuB,GACxB,MAAM,aAAa,CAAC"}

package/dist/method-trees.d.ts

@@ -0,0 +1,344 @@
+/**
+ * A method's tree on the client side (see `docs/method-trees.md`): the forms a caller gives a
+ * method's tree in, the listing of a directory through the `mthds` package's own lister, how a
+ * tree becomes the `files` map a request sends, inline or by hash, the blob routes that let a
+ * large tree travel by hash (mthds/docs/spec/protocol.md, "Sending files by hash"), the upload of
+ * a blob the receiver lacks, and the writing of a saved tree to disk.
+ *
+ * The wire types (`MethodTreeSource`, `BlobRef`, `MissingBlob` and the rest) are the standard's,
+ * imported from `mthds/protocol`. A directory is listed by `mthds`'s `listMethodTree`, the
+ * standard's lister with its membership rule, which this module loads by a dynamic import when a
+ * directory is given, so the SDK's static import graph keeps no Node built-in. The choice between
+ * inline and by hash follows `mthds`'s `MthdsApiClient` rule exactly, but its helpers are not
+ * exported on a subpath free of Node built-ins, so this module carries its own copy of them: the
+ * same threshold, the same weighing of the inline map, the same text-or-Base64 choice per file.
+ * SHA-256 is Web Crypto's, and Base64 is written here. Only `writeMethodTreeTo` and
+ * `listDirectoryTree` need Node, which each loads when called.
+ */
+import type { BlobRef, FileEntry, MethodFiles, MethodTreeSource, MethodTreeSourceFile, MissingBlob } from "mthds/protocol";
+import { RequestArgumentError, type MethodFileTransferCode } from "./errors.js";
+import type { SavedMethodFile } from "./product-models.js";
+/**
+ * A method's tree, given in exactly one of four forms. Every route that takes a method's tree
+ * takes these: the runs (`execute`, `start`, `startAndWaitForResult`), `validate`, the crate
+ * routes (`resolve`, `codegen`, `pipeIo`), `prepareInputs` and the saves (`createMethod`,
+ * `writeDraft`).
+ *
+ * - `directory`, a path on disk, listed by the `mthds` package's lister under the MTHDS
+ *   standard's membership rule: rooted at the nearest `METHODS.toml` at or above it, else at the
+ *   directory itself, every file the rule keeps, a run's inputs file (`inputs.json`,
+ *   `inputs.toml`) never among them, under the limits the deployment announces. A `.mthds` file
+ *   named alone is a one-file tree unless a `METHODS.toml` above it roots a larger one. Node only.
+ * - `contents`, each file's bytes or its text by tree path, a map held in memory.
+ * - `tree`, a listed source such as the `MethodTree` `listMethodTree` returns.
+ * - `files`, the protocol's map of file entries, sent as given.
+ *
+ * A `directory`, `contents` or `tree` travels inline when small and by hash otherwise, after the
+ * files the receiver lacks are uploaded (`docs/method-trees.md`).
+ */
+export interface MethodTreeForms {
+    /** The method's directory, listed by the standard's lister. Node only. */
+    directory?: string | null;
+    /** Each file's bytes or text, by tree path. */
+    contents?: Readonly<Record<string, Uint8Array | string>> | null;
+    /** A listed tree, such as the `MethodTree` `listMethodTree` returns. */
+    tree?: MethodTreeSource | null;
+    /** The protocol's map of file entries, sent as given. */
+    files?: MethodFiles | null;
+}
+/**
+ * A method's tree in exactly one of the four forms of `MethodTreeForms`, each pinning the other
+ * three to `never`, so giving two is a compile error. The calls that take the tree beside a
+ * selector it excludes (`validate`, `prepareInputs`) take it in this shape.
+ */
+export type MethodTreeForm = {
+    directory: string;
+    contents?: never;
+    tree?: never;
+    files?: never;
+} | {
+    contents: Readonly<Record<string, Uint8Array | string>>;
+    directory?: never;
+    tree?: never;
+    files?: never;
+} | {
+    tree: MethodTreeSource;
+    directory?: never;
+    contents?: never;
+    files?: never;
+} | {
+    files: MethodFiles;
+    directory?: never;
+    contents?: never;
+    tree?: never;
+};
+/** The four forms of the tree, each pinned to `never`, for a shape that takes no tree. */
+export interface NoMethodTree {
+    directory?: never;
+    contents?: never;
+    tree?: never;
+    files?: never;
+}
+/**
+ * What keeps `value` from being a listed tree as far as the client reads one before any request,
+ * an object with a `files` list, a `digest` string and a `readFile` function, in words for a
+ * refusal ("a list", "an object without them", or its type); `undefined` when it is one. A tree
+ * holding no file passes here, and is refused where it would be sent.
+ */
+export declare function treeShapeFault(value: unknown): string | undefined;
+/**
+ * The limits a deployment holds a tree to, in the shape the `mthds` package's `listMethodTree`
+ * takes as its `limits` option, so a lister stops at the first breach before hashing anything. A
+ * limit the deployment does not announce is absent.
+ */
+export interface MethodTreeLimits {
+    /** The most files a tree may hold. */
+    readonly maxFileCount?: number;
+    /** The largest one file may be, in bytes. */
+    readonly maxFileSize?: number;
+    /** The largest all the files together may be, in bytes. */
+    readonly maxTotalSize?: number;
+}
+/**
+ * Every limit a deployment's handshake announces for a tree under `limits.method_tree`, in bytes
+ * for the sizes, named as `mthds`'s `AnnouncedTreeLimits` names them. A limit not announced is
+ * absent.
+ */
+export interface AnnouncedTreeLimits {
+    /** The files of one tree. */
+    readonly maxFiles?: number;
+    /** One file of it. */
+    readonly maxFileBytes?: number;
+    /** All its files together. */
+    readonly maxTotalBytes?: number;
+    /** The bytes a request carries inline for its tree: its text and Base64 entries. */
+    readonly maxInlineBytes?: number;
+}
+/**
+ * The heaviest inline map, in bytes of its JSON serialization in UTF-8, that a request or a save
+ * sends inline to a deployment keeping a blob store, when the deployment announces no lower inline
+ * limit. Below it a tree is cheaper to send whole than to check and upload; above it every file
+ * travels by hash. `mthds`'s clients use the same threshold.
+ */
+export declare const INLINE_TREE_MAX_BYTES: number;
+/**
+ * How long a version handshake is trusted before the client asks again, `mthds`'s
+ * `HANDSHAKE_TTL_MS`: a deployment's blob store and tree limits change only with a deploy, so a
+ * client asks once per this span rather than before every request, and drops the answer sooner
+ * when a refusal shows it stale (`POST /v1/blobs/missing` gone, a tree refused as too large).
+ */
+export declare const HANDSHAKE_TTL_MS: number;
+/** How many blobs a request or a save uploads at once, and how many files `writeMethodTree` downloads at once. */
+export declare const MAX_CONCURRENT_TRANSFERS = 8;
+/**
+ * What a tree is prepared for, as its refusals and its failed uploads say it: a save of a method, or
+ * a request that runs or reads one (a run, `validate`, `resolve`, `codegen`, `pipeIo`).
+ */
+export interface TreeSending {
+    /** What did not happen because an upload failed, ending its message. */
+    readonly unsent: string;
+    /** What to give instead of a tree holding no file, when there is something. */
+    readonly emptyRemedy?: string;
+}
+/** A save's: a tree holding no file is given as `files: null`, which empties a draft. */
+export declare const SAVE_SENDING: TreeSending;
+/** A request's: a method has at least one file, so there is nothing to give instead. */
+export declare const REQUEST_SENDING: TreeSending;
+/** How a request prepares its tree, beyond what a save needs. */
+export interface TreeSendOptions {
+    /**
+     * Read before each step the tree costs: each file read, the version handshake's use, the blob
+     * route and each upload. Once it has aborted, none of them starts and the abort is thrown; a
+     * request already sent runs to its end.
+     */
+    readonly signal?: AbortSignal | undefined;
+    /**
+     * The request's `read_scope`, under which the blob route is asked which blobs are missing, so
+     * the blobs are uploaded into the store the request's hash entries are read from. The upload
+     * targets the route names are signed for that scope already.
+     */
+    readonly readScope?: string | undefined;
+}
+/**
+ * A map a crate request was given, or `undefined` when it selects or sends nothing: absent, `null`,
+ * or a plain object holding no key, the empty-as-absent rule of the run options and of the Python
+ * SDK. Any other value is kept as given, so the server refuses a `files` that is not a map as the
+ * shape it is rather than reading it as absent.
+ */
+export declare function presentMap<T>(value: T | null | undefined): T | undefined;
+/** The refusal of a tree holding no file, `call` naming the caller's method. */
+export declare function emptyTreeRefusal(call: string, what: string, sending: TreeSending): RequestArgumentError;
+/** Whether a version handshake declares a blob store (`blob_store: true`). */
+export declare function declaresBlobStore(version: object): boolean;
+/**
+ * The tree limits a version handshake announces under `limits.method_tree`. A value that is not a
+ * positive safe integer is left out rather than trusted, and a limit not announced is absent, so a
+ * bare runner, which announces none, yields no limit.
+ */
+export declare function announcedTreeLimits(version: object): AnnouncedTreeLimits;
+/** The announced limits as the lister takes them, so it stops at the first breach before hashing. */
+export declare function listerLimitsOf(announced: AnnouncedTreeLimits): MethodTreeLimits;
+/**
+ * The inline threshold a tree is held to against a receiver keeping a blob store: the lower of
+ * `INLINE_TREE_MAX_BYTES` and the inline limit the receiver announces, as `mthds`'s
+ * `MthdsApiClient` reads it.
+ */
+export declare function inlineThreshold(announced: AnnouncedTreeLimits): number;
+/** What an inline map spends in a request: its JSON serialization with no whitespace, in UTF-8. */
+export declare function inlineMapBytes(files: MethodFiles): number;
+/** The total of a tree's file sizes, in bytes. */
+export declare function treeTotalSize(tree: MethodTreeSource): number;
+/**
+ * Every file's bytes, by tree path, each read and checked by the tree, one file at a time. `signal`
+ * is read before each file: once it has aborted, no further file is read and the abort is thrown.
+ */
+export declare function readTreeBytes(tree: MethodTreeSource, signal?: AbortSignal): Promise<Map<string, Uint8Array>>;
+/**
+ * Every file's bytes, by tree path, read into `read`: a file already there is not read again, so
+ * a request that weighs a tree and then uploads from it, or prepares it a second time, reads each
+ * file once. `signal` is read before each file read, as `readTreeBytes` reads it.
+ */
+export declare function readTreeBytesInto(tree: MethodTreeSource, read: Map<string, Uint8Array>, signal?: AbortSignal): Promise<Map<string, Uint8Array>>;
+/** The whole tree as inline entries, from bytes already read by `readTreeBytes`. */
+export declare function inlineFilesOf(tree: MethodTreeSource, bytesByPath: ReadonlyMap<string, Uint8Array>): MethodFiles;
+/** The whole tree as hash entries, which the platform resolves in the organization's blobs. */
+export declare function hashMethodFiles(tree: MethodTreeSource): MethodFiles;
+/** Each blob of the tree once, in the tree's order: files with the same bytes share one blob. */
+export declare function uniqueBlobs(tree: MethodTreeSource): BlobRef[];
+/** A file of the tree holding each blob, so a missing blob's bytes can be read and uploaded. */
+export declare function fileByBlob(tree: MethodTreeSource): Map<string, MethodTreeSourceFile>;
+/**
+ * Run `task` over `items`, at most `limit` at a time. The first task to fail stops the run: no
+ * queued item is handed out after it, `signal` is aborted so the tasks still in flight can stop
+ * early, and once they have settled the first failure is thrown.
+ */
+export declare function forEachConcurrently<T>(items: readonly T[], limit: number, task: (item: T, signal: AbortSignal) => Promise<void>): Promise<void>;
+/**
+ * Whether an answer refuses a tree as past one of the receiver's limits, as `mthds`'s
+ * `MthdsApiClient` reads one: a `422` whose problem is the core registry's
+ * `method.package_invalid` carrying its numeric `limit` parameter, the hosted platform's
+ * `method_tree_too_large` code, or pipelex-api's `MethodTreeTooLarge` error type.
+ */
+export declare function isMethodTreeTooLarge(status: number, body: string): boolean;
+/**
+ * The blobs a `422` lists as missing, as `mthds`'s `MthdsApiClient` reads them: the
+ * `params.missing_blobs` of a problem coded `request.blobs_missing`, or `undefined` when the
+ * answer is no such problem or the list holds anything but strings.
+ */
+export declare function missingBlobsOf(status: number, body: string): string[] | undefined;
+/**
+ * A signal that aborts when either does, with the reason of the first to abort, and `dispose`,
+ * which detaches it from both once it is no longer needed, so a long-lived signal does not keep
+ * a listener per call. `second` absent gives `first` itself. Built by hand rather than with
+ * `AbortSignal.any`, which older browsers lack.
+ */
+export declare function eitherSignal(first: AbortSignal, second: AbortSignal | undefined): {
+    signal: AbortSignal;
+    dispose: () => void;
+};
+/**
+ * The tree whose files are `contents`, each file's bytes or its text by tree path, a text encoded
+ * in UTF-8. The keys are sent as they are, and the platform refuses one that is not a tree path,
+ * with the `422` `invalid_method_files` naming it. `call` names the caller's method in a refusal.
+ *
+ * Throws `RequestArgumentError` for `contents` holding no file, for a value that is neither a
+ * string nor bytes, and for a text holding a lone surrogate, which no file can hold. `sending` says
+ * what the tree is for, which the refusal of an empty one names.
+ */
+export declare function contentsTreeSource(contents: Readonly<Record<string, Uint8Array | string>>, call: string, sending: TreeSending): Promise<MethodTreeSource>;
+/** A tree listed from the file system: its files, and the absolute path of its root. */
+export interface ListedMethodTree extends MethodTreeSource {
+    /** The absolute path of the root, or `null` for the one-file tree of a `.mthds` file alone. */
+    readonly root: string | null;
+}
+/**
+ * The tree of the method directory `directory`, listed by the `mthds` package's `listMethodTree`
+ * under the MTHDS standard's membership rule and Manifest Discovery, stopping at the first of
+ * `limits` it breaches, before any file is hashed. A run's inputs file is never in it. Node only:
+ * `mthds`'s root entry, which reads the file system, is loaded by this call alone.
+ *
+ * Throws `RequestArgumentError` naming `call` when the directory cannot be listed as a tree, the
+ * `mthds` package's `MethodTreeError` as its `cause` with its `code` (`not_found`,
+ * `symbolic_link`, `limit_exceeded`, `empty_tree` and the rest): a path that names nothing, a
+ * symbolic link or a special file in the tree, a tree past one of `limits`, a tree holding no file.
+ */
+export declare function listDirectoryTree(directory: string, limits: MethodTreeLimits, call: string): Promise<ListedMethodTree>;
+/**
+ * The tree digest of a tree's files: `sha256:` and the SHA-256 of its listing, one line
+ * `<sha256>  <path>` per file, in tree path order.
+ */
+export declare function treeDigestOf(files: readonly MethodTreeSourceFile[]): Promise<string>;
+/** The SHA-256 of `bytes`, in lowercase hexadecimal, by Web Crypto. */
+export declare function sha256Hex(bytes: Uint8Array): Promise<string>;
+/**
+ * Compare two strings byte for byte on their UTF-8 encoding, the order tree paths are sorted in.
+ * JavaScript's own string order compares UTF-16 code units, which puts a character above U+FFFF
+ * before one between U+E000 and U+FFFF, where UTF-8 puts it after.
+ */
+export declare function compareUtf8(left: string, right: string): number;
+/** The entry a file travels as inline: its text when its bytes are UTF-8, its Base64 otherwise. */
+export declare function inlineFileEntry(bytes: Uint8Array): FileEntry;
+/**
+ * Add a file to a map of file entries as an own property, since assigning to a key such as
+ * `__proto__`, a tree path like any other, would set the object's prototype instead of adding the
+ * file.
+ */
+export declare function defineFileEntry(files: MethodFiles, treePath: string, entry: FileEntry): void;
+/** Canonical padded standard Base64 (RFC 4648), with no line break and its pad bits zero. */
+export declare function encodeBase64(bytes: Uint8Array): string;
+/**
+ * Upload one blob's bytes to the target `POST /v1/blobs/missing` named: the bytes as the whole body
+ * of a request with the target's method to its URL, carrying exactly the target's headers and no
+ * credential of the client, since the signed URL authorizes the upload itself. A `412` from a
+ * target asking for a create-only write (`If-None-Match`) means the bytes are already stored, and
+ * counts as uploaded.
+ *
+ * Throws `MethodFileTransferError` (`operation` `upload`) when storage gives no answer within
+ * `timeoutMs` or answers any other non-2xx; neither its message nor any member carries the URL,
+ * nor storage's error body, which can echo the signed request. Its message ends with what did not
+ * happen because of it, `options.unsent`.
+ */
+export declare function uploadBlob(blob: MissingBlob, bytes: Uint8Array, options: {
+    timeoutMs: number;
+    signal?: AbortSignal;
+    unsent: string;
+}): Promise<void>;
+/**
+ * The code of a transfer storage answered with a non-2xx `status`: `storage_error` for one the
+ * fallback table calls retryable (`408`, `429`, a `5xx` other than `501`), `refused` otherwise.
+ */
+export declare function methodFileTransferCodeOfStatus(status: number): MethodFileTransferCode;
+/**
+ * Write a saved tree to disk, each file of `files` at its tree path under `destination`; see
+ * `PipelexApiClient.writeMethodTree`. Node only: the file system modules are loaded when it runs.
+ */
+export declare function writeMethodTreeTo(files: readonly SavedMethodFile[], destination: string, options: {
+    timeoutMs: number;
+}): Promise<void>;
+/**
+ * Refuse a listing whose paths could not be written as a tree, before anything is downloaded. A
+ * platform's listing holds tree paths that never collide; the check guards the disk against any
+ * other listing a caller hands over, such as one built by hand, since a path such as `../x` would
+ * be written outside the destination. Throws `RequestArgumentError`.
+ */
+export declare function refuseUnwritableListing(files: readonly SavedMethodFile[]): void;
+/**
+ * Why `candidate` is not a tree path, or `null` when it is one (mthds/docs/spec/method-tree.md,
+ * "Tree Paths"), the rule the `mthds` package's `treePathViolation` holds.
+ */
+export declare function treePathViolation(candidate: string): string | null;
+/**
+ * The paths that collide: those equal to another once case-folded, and those naming, once
+ * case-folded, a directory of another, with the paths under it, sorted byte for byte. The fold is
+ * `toUpperCase().toLowerCase()`, which agrees with Unicode full case folding on the scripts a file
+ * name uses; a pair it misses still fails the write, which never writes over a file.
+ */
+export declare function pathCollisions(treePaths: readonly string[]): string[];
+/**
+ * `text`, an answer that carries signed links, with every link hidden, for an error to hold: in a
+ * JSON body every `url` member, at any depth, is replaced whole, and in any text, JSON or not, a
+ * truncated body included, the query of every `http(s)` link is replaced, since a signed link's
+ * signature rides its query. A link is a bearer credential, so no error, message or member may
+ * carry one.
+ */
+export declare function redactSignedLinks(text: string): string;