@vercel/factory 0.0.14 → 0.0.16

package/dist/approval-contracts.mjs

@@ -0,0 +1,27 @@
+import { taskIdSchema } from "./schema/id.mjs";
+import { repositorySlugSchema } from "./schema/repository.mjs";
+import { taskSchema } from "./schema/task.mjs";
+import { receiptSchema } from "./schema/receipt.mjs";
+import { findingSchema } from "./schema/finding.mjs";
+import { z } from "zod";
+//#region src/approval-contracts.ts
+/** Validates the stable human reason attached to an approval decision. */
+const approvalRequestSchema = z.strictObject({ reason: z.string().trim().min(1).max(2e3).optional().describe("Reason for the decision; required for rejection. Retain unchanged for retries.") });
+/** Validates one authorized approval proposal and its immutable decision state. */
+const approvalViewSchema = z.object({
+	task: taskSchema.describe("Task requiring or carrying a human decision."),
+	repositories: z.array(repositorySlugSchema).readonly().describe("Configured repository names for this Task."),
+	finding: findingSchema.nullable().describe("Finding that prompted the Task, when available."),
+	decision: receiptSchema.nullable().describe("Immutable decision receipt, or null before a decision.")
+});
+/** Validates a filtered, cursor-paginated page of approval proposals. */
+const approvalPageSchema = z.object({
+	actor: z.string().describe("Authenticated actor used for decision attribution."),
+	items: z.array(approvalViewSchema).readonly().describe("Authorized approvals in the requested order."),
+	totalCount: z.number().int().nonnegative().optional().describe("Number of authorized approvals matching all filters, before pagination."),
+	nextCursor: taskIdSchema.nullable().describe("Continue this filtered listing after this Task ID.")
+});
+//#endregion
+export { approvalPageSchema, approvalRequestSchema, approvalViewSchema };
+
+//# sourceMappingURL=approval-contracts.mjs.map

package/dist/approval-contracts.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"approval-contracts.mjs","names":[],"sources":["../src/approval-contracts.ts"],"sourcesContent":["import { z } from \"zod\";\nimport { taskIdSchema, type TaskId } from \"./schema/id\";\nimport { taskSchema } from \"./schema/task\";\nimport { receiptSchema } from \"./schema/receipt\";\nimport { findingSchema } from \"./schema/finding\";\nimport { repositorySlugSchema, type RepositorySlug } from \"./schema/repository\";\n\n/** Workspace owner and optional individually authenticated actor at the approval boundary. */\nexport interface ApiPrincipal {\n  /** Workspace identity used for existing conversation ownership. */\n  readonly id: string;\n  /** Individually authenticated, provider-qualified actor; absent for anonymous/workload access. */\n  readonly actor?: string;\n}\n\n/** Validates the stable human reason attached to an approval decision. */\nexport const approvalRequestSchema = z.strictObject({\n  reason: z\n    .string()\n    .trim()\n    .min(1)\n    .max(2000)\n    .optional()\n    .describe(\"Reason for the decision; required for rejection. Retain unchanged for retries.\"),\n});\n/** Validates one authorized approval proposal and its immutable decision state. */\nexport const approvalViewSchema = z.object({\n  task: taskSchema.describe(\"Task requiring or carrying a human decision.\"),\n  repositories: z\n    .array(repositorySlugSchema)\n    .readonly()\n    .describe(\"Configured repository names for this Task.\"),\n  finding: findingSchema.nullable().describe(\"Finding that prompted the Task, when available.\"),\n  decision: receiptSchema\n    .nullable()\n    .describe(\"Immutable decision receipt, or null before a decision.\"),\n});\n/** Validates a filtered, cursor-paginated page of approval proposals. */\nexport const approvalPageSchema = z.object({\n  actor: z.string().describe(\"Authenticated actor used for decision attribution.\"),\n  items: z\n    .array(approvalViewSchema)\n    .readonly()\n    .describe(\"Authorized approvals in the requested order.\"),\n  totalCount: z\n    .number()\n    .int()\n    .nonnegative()\n    .optional()\n    .describe(\"Number of authorized approvals matching all filters, before pagination.\"),\n  nextCursor: taskIdSchema\n    .nullable()\n    .describe(\"Continue this filtered listing after this Task ID.\"),\n});\n/** Authorized Task proposal with repository, finding, and decision context. */\nexport type ApprovalView = z.infer<typeof approvalViewSchema>;\n/** Filtered, cursor-paginated approval proposals for one authorized actor. */\nexport type ApprovalPage = z.infer<typeof approvalPageSchema>;\n/** Filters, ordering, and cursor controls for approval discovery. */\nexport interface ApprovalListOptions {\n  readonly repository?: RepositorySlug;\n  readonly status?: \"pending\" | \"decided\" | \"all\";\n  readonly query?: string;\n  readonly sort?: \"created\" | \"priority\" | \"decided\";\n  readonly limit?: number;\n  readonly cursor?: TaskId;\n}\n"],"mappings":";;;;;;;;AAgBA,MAAa,wBAAwB,EAAE,aAAa,EAClD,QAAQ,EACL,OAAO,CAAC,CACR,KAAK,CAAC,CACN,IAAI,CAAC,CAAC,CACN,IAAI,GAAI,CAAC,CACT,SAAS,CAAC,CACV,SAAS,gFAAgF,EAC9F,CAAC;;AAED,MAAa,qBAAqB,EAAE,OAAO;CACzC,MAAM,WAAW,SAAS,8CAA8C;CACxE,cAAc,EACX,MAAM,oBAAoB,CAAC,CAC3B,SAAS,CAAC,CACV,SAAS,4CAA4C;CACxD,SAAS,cAAc,SAAS,CAAC,CAAC,SAAS,iDAAiD;CAC5F,UAAU,cACP,SAAS,CAAC,CACV,SAAS,wDAAwD;AACtE,CAAC;;AAED,MAAa,qBAAqB,EAAE,OAAO;CACzC,OAAO,EAAE,OAAO,CAAC,CAAC,SAAS,oDAAoD;CAC/E,OAAO,EACJ,MAAM,kBAAkB,CAAC,CACzB,SAAS,CAAC,CACV,SAAS,8CAA8C;CAC1D,YAAY,EACT,OAAO,CAAC,CACR,IAAI,CAAC,CACL,YAAY,CAAC,CACb,SAAS,CAAC,CACV,SAAS,yEAAyE;CACrF,YAAY,aACT,SAAS,CAAC,CACV,SAAS,oDAAoD;AAClE,CAAC"}

package/dist/approval.d.mts

@@ -0,0 +1,49 @@
+import { z } from "zod";
+//#region src/approval.d.ts
+/** Validates an open priority label used to match admission policy subjects. */
+declare const approvalPrioritySchema: z.ZodString;
+/**
+ * One approval rule. Every listed field must match for the rule to apply;
+ * absent fields match anything. Rules are evaluated first-match.
+ */
+declare const approvalRuleSchema: z.ZodReadonly<z.ZodObject<{
+  source: z.ZodOptional<z.ZodString>;
+  kind: z.ZodOptional<z.ZodString>;
+  priority: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+  require: z.ZodBoolean;
+}, z.core.$strict>>;
+/** Validates an ordered, first-match set of Task approval rules. */
+declare const approvalPolicySchema: z.ZodReadonly<z.ZodArray<z.ZodReadonly<z.ZodObject<{
+  source: z.ZodOptional<z.ZodString>;
+  kind: z.ZodOptional<z.ZodString>;
+  priority: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+  require: z.ZodBoolean;
+}, z.core.$strict>>>>;
+/** One first-match condition that decides whether admitted work requires approval. */
+type ApprovalRule = z.infer<typeof approvalRuleSchema>;
+/** Ordered admission policy that stamps a Task's approval requirement once. */
+type ApprovalPolicy = z.infer<typeof approvalPolicySchema>;
+/** Open priority label compared exactly by approval policy. */
+type ApprovalPriority = z.infer<typeof approvalPrioritySchema>;
+/** Neutral framework default when an application does not select an approval policy. */
+declare const allowByDefaultApprovalPolicy: readonly Readonly<{
+  require: boolean;
+  source?: string | undefined;
+  kind?: string | undefined;
+  priority?: readonly string[] | undefined;
+}>[];
+/** Immutable intake attributes evaluated against an approval policy. */
+interface ApprovalSubject {
+  source?: string;
+  kind: string;
+  priority?: string;
+}
+/**
+ * Decide at task-creation time whether a task needs approval. Pure: the answer
+ * is stamped on the task and never re-evaluated, so a later policy change
+ * cannot silently release work a human was expecting to see.
+ */
+declare function requiresApproval(policy: ApprovalPolicy, subject: ApprovalSubject): boolean;
+//#endregion
+export { ApprovalPolicy, ApprovalPriority, ApprovalRule, ApprovalSubject, allowByDefaultApprovalPolicy, approvalPolicySchema, approvalPrioritySchema, approvalRuleSchema, requiresApproval };
+//# sourceMappingURL=approval.d.mts.map

package/dist/approval.mjs

@@ -0,0 +1,39 @@
+import { vocabularySchema } from "./schema/common.mjs";
+import { z } from "zod";
+//#region src/approval.ts
+/** Validates an open priority label used to match admission policy subjects. */
+const approvalPrioritySchema = z.string().min(1).max(64).describe("Priority label compared exactly, e.g. P0, P1, urgent, or a custom domain value.");
+/**
+* One approval rule. Every listed field must match for the rule to apply;
+* absent fields match anything. Rules are evaluated first-match.
+*/
+const approvalRuleSchema = z.strictObject({
+	source: vocabularySchema.optional().describe("Signal source, e.g. security_scan or github_issue."),
+	kind: vocabularySchema.optional().describe("Task kind, e.g. code_change."),
+	priority: z.array(approvalPrioritySchema).min(1).readonly().optional().describe("Finding priorities the rule applies to."),
+	require: z.boolean().describe("Whether matching tasks wait for a human before dispatch.")
+}).readonly();
+/** Validates an ordered, first-match set of Task approval rules. */
+const approvalPolicySchema = z.array(approvalRuleSchema).readonly().describe("First-match rules deciding which tasks need a human before they run.");
+/** Neutral framework default when an application does not select an approval policy. */
+const allowByDefaultApprovalPolicy = approvalPolicySchema.parse([{ require: false }]);
+/**
+* Decide at task-creation time whether a task needs approval. Pure: the answer
+* is stamped on the task and never re-evaluated, so a later policy change
+* cannot silently release work a human was expecting to see.
+*/
+function requiresApproval(policy, subject) {
+	for (const rule of policy) {
+		if (rule.source !== void 0 && rule.source !== subject.source) continue;
+		if (rule.kind !== void 0 && rule.kind !== subject.kind) continue;
+		if (rule.priority !== void 0) {
+			if (subject.priority === void 0 || !rule.priority.includes(subject.priority)) continue;
+		}
+		return rule.require;
+	}
+	return false;
+}
+//#endregion
+export { allowByDefaultApprovalPolicy, approvalPolicySchema, approvalPrioritySchema, approvalRuleSchema, requiresApproval };
+
+//# sourceMappingURL=approval.mjs.map

package/dist/approval.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"approval.mjs","names":[],"sources":["../src/approval.ts"],"sourcesContent":["import { z } from \"zod\";\nimport { vocabularySchema } from \"./schema/common\";\n\n/** Validates an open priority label used to match admission policy subjects. */\nexport const approvalPrioritySchema = z\n  .string()\n  .min(1)\n  .max(64)\n  .describe(\"Priority label compared exactly, e.g. P0, P1, urgent, or a custom domain value.\");\n\n/**\n * One approval rule. Every listed field must match for the rule to apply;\n * absent fields match anything. Rules are evaluated first-match.\n */\nexport const approvalRuleSchema = z\n  .strictObject({\n    source: vocabularySchema\n      .optional()\n      .describe(\"Signal source, e.g. security_scan or github_issue.\"),\n    kind: vocabularySchema.optional().describe(\"Task kind, e.g. code_change.\"),\n    priority: z\n      .array(approvalPrioritySchema)\n      .min(1)\n      .readonly()\n      .optional()\n      .describe(\"Finding priorities the rule applies to.\"),\n    require: z.boolean().describe(\"Whether matching tasks wait for a human before dispatch.\"),\n  })\n  .readonly();\n\n/** Validates an ordered, first-match set of Task approval rules. */\nexport const approvalPolicySchema = z\n  .array(approvalRuleSchema)\n  .readonly()\n  .describe(\"First-match rules deciding which tasks need a human before they run.\");\n\n/** One first-match condition that decides whether admitted work requires approval. */\nexport type ApprovalRule = z.infer<typeof approvalRuleSchema>;\n/** Ordered admission policy that stamps a Task's approval requirement once. */\nexport type ApprovalPolicy = z.infer<typeof approvalPolicySchema>;\n/** Open priority label compared exactly by approval policy. */\nexport type ApprovalPriority = z.infer<typeof approvalPrioritySchema>;\n\n/** Neutral framework default when an application does not select an approval policy. */\nexport const allowByDefaultApprovalPolicy = approvalPolicySchema.parse([{ require: false }]);\n\n/** Immutable intake attributes evaluated against an approval policy. */\nexport interface ApprovalSubject {\n  source?: string;\n  kind: string;\n  priority?: string;\n}\n\n/**\n * Decide at task-creation time whether a task needs approval. Pure: the answer\n * is stamped on the task and never re-evaluated, so a later policy change\n * cannot silently release work a human was expecting to see.\n */\nexport function requiresApproval(policy: ApprovalPolicy, subject: ApprovalSubject): boolean {\n  for (const rule of policy) {\n    if (rule.source !== undefined && rule.source !== subject.source) continue;\n    if (rule.kind !== undefined && rule.kind !== subject.kind) continue;\n    if (rule.priority !== undefined) {\n      if (subject.priority === undefined || !rule.priority.includes(subject.priority)) continue;\n    }\n    return rule.require;\n  }\n  return false;\n}\n"],"mappings":";;;;AAIA,MAAa,yBAAyB,EACnC,OAAO,CAAC,CACR,IAAI,CAAC,CAAC,CACN,IAAI,EAAE,CAAC,CACP,SAAS,iFAAiF;;;;;AAM7F,MAAa,qBAAqB,EAC/B,aAAa;CACZ,QAAQ,iBACL,SAAS,CAAC,CACV,SAAS,oDAAoD;CAChE,MAAM,iBAAiB,SAAS,CAAC,CAAC,SAAS,8BAA8B;CACzE,UAAU,EACP,MAAM,sBAAsB,CAAC,CAC7B,IAAI,CAAC,CAAC,CACN,SAAS,CAAC,CACV,SAAS,CAAC,CACV,SAAS,yCAAyC;CACrD,SAAS,EAAE,QAAQ,CAAC,CAAC,SAAS,0DAA0D;AAC1F,CAAC,CAAC,CACD,SAAS;;AAGZ,MAAa,uBAAuB,EACjC,MAAM,kBAAkB,CAAC,CACzB,SAAS,CAAC,CACV,SAAS,sEAAsE;;AAUlF,MAAa,+BAA+B,qBAAqB,MAAM,CAAC,EAAE,SAAS,MAAM,CAAC,CAAC;;;;;;AAc3F,SAAgB,iBAAiB,QAAwB,SAAmC;CAC1F,KAAK,MAAM,QAAQ,QAAQ;EACzB,IAAI,KAAK,WAAW,KAAA,KAAa,KAAK,WAAW,QAAQ,QAAQ;EACjE,IAAI,KAAK,SAAS,KAAA,KAAa,KAAK,SAAS,QAAQ,MAAM;EAC3D,IAAI,KAAK,aAAa,KAAA,GAChB;OAAA,QAAQ,aAAa,KAAA,KAAa,CAAC,KAAK,SAAS,SAAS,QAAQ,QAAQ,GAAG;EAAA;EAEnF,OAAO,KAAK;CACd;CACA,OAAO;AACT"}

package/dist/blob/artifacts.d.mts

@@ -0,0 +1,37 @@
+import { TaskId } from "../schema/id.mjs";
+import { TaskAttemptRef } from "../schema/execution.mjs";
+import { BlobClient } from "./index.mjs";
+import { z } from "zod";
+//#region src/blob/artifacts.d.ts
+declare const artifactRefSchema: z.core.$ZodBranded<z.ZodString, "ArtifactRef", "out">;
+/** A content-addressed reference that binds an artifact to its owning Task attempt and kind. */
+type ArtifactRef = z.infer<typeof artifactRefSchema>;
+/** Valid syntax grants neither read authority nor proof that an artifact exists. */
+declare function parseArtifactRef(value: unknown): ArtifactRef;
+/** Artifact kinds accepted by the Task-bound content-addressed store. */
+type ArtifactKind = "patch" | "report" | "log";
+/** Task attempt, kind, and encoded body used to derive or persist an artifact. */
+interface ArtifactInput extends TaskAttemptRef {
+  kind: ArtifactKind;
+  /** Binary artifacts use base64. */
+  body: string;
+}
+/** Artifact reference and authorized owning Task used for one verified read. */
+interface ReadArtifactInput {
+  ref: ArtifactRef;
+  taskId: TaskId;
+}
+/** Persists and retrieves content-addressed artifacts within a Task authorization boundary. */
+interface ArtifactStore {
+  /** Content-addressed and therefore idempotent; returns the durable reference. */
+  put(artifact: ArtifactInput): Promise<ArtifactRef>;
+  /** Reads require the owning Task and re-verify the content digest. */
+  read(input: ReadArtifactInput): Promise<string>;
+}
+/** Derive a validated, content-addressed reference for an artifact without writing it. */
+declare function artifactReference(artifact: ArtifactInput): ArtifactRef;
+/** Create a Task-bound artifact store that verifies ownership and content digests on reads. */
+declare function createArtifactStore(client: BlobClient): ArtifactStore;
+//#endregion
+export { ArtifactInput, ArtifactKind, ArtifactRef, ArtifactStore, ReadArtifactInput, artifactReference, createArtifactStore, parseArtifactRef };
+//# sourceMappingURL=artifacts.d.mts.map

package/dist/blob/artifacts.mjs

@@ -0,0 +1,45 @@
+import { createHash } from "node:crypto";
+import { z } from "zod";
+//#region src/blob/artifacts.ts
+const artifactRefPattern = /^factory-artifacts\/(task_[a-z0-9]{6,64})\/([1-9]\d{0,8})\/(patch|report|log)\/([0-9a-f]{64})$/u;
+const artifactRefSchema = z.string().regex(artifactRefPattern, "Unrecognized artifact reference").brand();
+/** Valid syntax grants neither read authority nor proof that an artifact exists. */
+function parseArtifactRef(value) {
+	return artifactRefSchema.parse(value);
+}
+const sha256 = (body) => createHash("sha256").update(body).digest("hex");
+/** Derive a validated, content-addressed reference for an artifact without writing it. */
+function artifactReference(artifact) {
+	const ref = `factory-artifacts/${artifact.taskId}/${artifact.attempt}/${artifact.kind}/${sha256(artifact.body)}`;
+	if (!artifactRefPattern.test(ref)) throw new Error("Artifact reference requires a valid Task ID, attempt, and kind");
+	return parseArtifactRef(ref);
+}
+/** Create a Task-bound artifact store that verifies ownership and content digests on reads. */
+function createArtifactStore(client) {
+	return {
+		async put(artifact) {
+			const ref = artifactReference(artifact);
+			await client.write({
+				pathname: ref,
+				body: artifact.body,
+				overwrite: true
+			});
+			return ref;
+		},
+		async read({ ref, taskId: authorizedTaskId }) {
+			const parsed = parseArtifactRef(ref);
+			const match = artifactRefPattern.exec(parsed);
+			if (!match) throw new Error("Unrecognized artifact reference");
+			const [, taskId, , , digest] = match;
+			if (taskId !== authorizedTaskId) throw new Error(`Artifact belongs to ${taskId}, not to the authorized Task ${authorizedTaskId}`);
+			const stored = await client.read({ pathname: parsed });
+			if (!stored) throw new Error(`Artifact ${ref} is unavailable`);
+			if (sha256(stored.body) !== digest) throw new Error(`Artifact ${ref} content does not match its digest`);
+			return stored.body;
+		}
+	};
+}
+//#endregion
+export { artifactReference, createArtifactStore, parseArtifactRef };
+
+//# sourceMappingURL=artifacts.mjs.map

package/dist/blob/artifacts.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifacts.mjs","names":[],"sources":["../../src/blob/artifacts.ts"],"sourcesContent":["import { createHash } from \"node:crypto\";\nimport type { BlobClient } from \"./index\";\nimport type { TaskAttemptRef } from \"../schema/execution\";\nimport type { TaskId } from \"../schema/id\";\nimport { z } from \"zod\";\n\nconst artifactRefPattern =\n  /^factory-artifacts\\/(task_[a-z0-9]{6,64})\\/([1-9]\\d{0,8})\\/(patch|report|log)\\/([0-9a-f]{64})$/u;\nconst artifactRefSchema = z\n  .string()\n  .regex(artifactRefPattern, \"Unrecognized artifact reference\")\n  .brand<\"ArtifactRef\">();\n\n/** A content-addressed reference that binds an artifact to its owning Task attempt and kind. */\nexport type ArtifactRef = z.infer<typeof artifactRefSchema>;\n\n/** Valid syntax grants neither read authority nor proof that an artifact exists. */\nexport function parseArtifactRef(value: unknown): ArtifactRef {\n  return artifactRefSchema.parse(value);\n}\n\n/** Artifact kinds accepted by the Task-bound content-addressed store. */\nexport type ArtifactKind = \"patch\" | \"report\" | \"log\";\n\n/** Task attempt, kind, and encoded body used to derive or persist an artifact. */\nexport interface ArtifactInput extends TaskAttemptRef {\n  kind: ArtifactKind;\n  /** Binary artifacts use base64. */\n  body: string;\n}\n\n/** Artifact reference and authorized owning Task used for one verified read. */\nexport interface ReadArtifactInput {\n  ref: ArtifactRef;\n  taskId: TaskId;\n}\n\n/** Persists and retrieves content-addressed artifacts within a Task authorization boundary. */\nexport interface ArtifactStore {\n  /** Content-addressed and therefore idempotent; returns the durable reference. */\n  put(artifact: ArtifactInput): Promise<ArtifactRef>;\n  /** Reads require the owning Task and re-verify the content digest. */\n  read(input: ReadArtifactInput): Promise<string>;\n}\n\nconst sha256 = (body: string) => createHash(\"sha256\").update(body).digest(\"hex\");\n\n/** Derive a validated, content-addressed reference for an artifact without writing it. */\nexport function artifactReference(artifact: ArtifactInput): ArtifactRef {\n  const ref = `factory-artifacts/${artifact.taskId}/${artifact.attempt}/${artifact.kind}/${sha256(artifact.body)}`;\n  if (!artifactRefPattern.test(ref)) {\n    throw new Error(\"Artifact reference requires a valid Task ID, attempt, and kind\");\n  }\n  return parseArtifactRef(ref);\n}\n\n/** Create a Task-bound artifact store that verifies ownership and content digests on reads. */\nexport function createArtifactStore(client: BlobClient): ArtifactStore {\n  return {\n    async put(artifact) {\n      const ref = artifactReference(artifact);\n      // Same path implies same content, so overwriting is safe and retryable.\n      await client.write({ pathname: ref, body: artifact.body, overwrite: true });\n      return ref;\n    },\n    async read({ ref, taskId: authorizedTaskId }) {\n      const parsed = parseArtifactRef(ref);\n      const match = artifactRefPattern.exec(parsed);\n      if (!match) throw new Error(\"Unrecognized artifact reference\");\n      const [, taskId, , , digest] = match;\n      if (taskId !== authorizedTaskId) {\n        throw new Error(\n          `Artifact belongs to ${taskId}, not to the authorized Task ${authorizedTaskId}`,\n        );\n      }\n      const stored = await client.read({ pathname: parsed });\n      if (!stored) throw new Error(`Artifact ${ref} is unavailable`);\n      if (sha256(stored.body) !== digest) {\n        throw new Error(`Artifact ${ref} content does not match its digest`);\n      }\n      return stored.body;\n    },\n  };\n}\n"],"mappings":";;;AAMA,MAAM,qBACJ;AACF,MAAM,oBAAoB,EACvB,OAAO,CAAC,CACR,MAAM,oBAAoB,iCAAiC,CAAC,CAC5D,MAAqB;;AAMxB,SAAgB,iBAAiB,OAA6B;CAC5D,OAAO,kBAAkB,MAAM,KAAK;AACtC;AA0BA,MAAM,UAAU,SAAiB,WAAW,QAAQ,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,OAAO,KAAK;;AAG/E,SAAgB,kBAAkB,UAAsC;CACtE,MAAM,MAAM,qBAAqB,SAAS,OAAO,GAAG,SAAS,QAAQ,GAAG,SAAS,KAAK,GAAG,OAAO,SAAS,IAAI;CAC7G,IAAI,CAAC,mBAAmB,KAAK,GAAG,GAC9B,MAAM,IAAI,MAAM,gEAAgE;CAElF,OAAO,iBAAiB,GAAG;AAC7B;;AAGA,SAAgB,oBAAoB,QAAmC;CACrE,OAAO;EACL,MAAM,IAAI,UAAU;GAClB,MAAM,MAAM,kBAAkB,QAAQ;GAEtC,MAAM,OAAO,MAAM;IAAE,UAAU;IAAK,MAAM,SAAS;IAAM,WAAW;GAAK,CAAC;GAC1E,OAAO;EACT;EACA,MAAM,KAAK,EAAE,KAAK,QAAQ,oBAAoB;GAC5C,MAAM,SAAS,iBAAiB,GAAG;GACnC,MAAM,QAAQ,mBAAmB,KAAK,MAAM;GAC5C,IAAI,CAAC,OAAO,MAAM,IAAI,MAAM,iCAAiC;GAC7D,MAAM,GAAG,YAAY,UAAU;GAC/B,IAAI,WAAW,kBACb,MAAM,IAAI,MACR,uBAAuB,OAAO,+BAA+B,kBAC/D;GAEF,MAAM,SAAS,MAAM,OAAO,KAAK,EAAE,UAAU,OAAO,CAAC;GACrD,IAAI,CAAC,QAAQ,MAAM,IAAI,MAAM,YAAY,IAAI,gBAAgB;GAC7D,IAAI,OAAO,OAAO,IAAI,MAAM,QAC1B,MAAM,IAAI,MAAM,YAAY,IAAI,mCAAmC;GAErE,OAAO,OAAO;EAChB;CACF;AACF"}

package/dist/blob/index.d.mts

@@ -1,33 +1,105 @@
-import { i as StoreDriver } from "../driver-BC0Mt5KG.mjs";
+import { MillisecondClock } from "../schema/common.mjs";
+import { StoreDriver } from "../store/driver.mjs";
+import { ArtifactInput, ArtifactKind, ArtifactRef, ArtifactStore, ReadArtifactInput, artifactReference, createArtifactStore, parseArtifactRef } from "./artifacts.mjs";
 //#region src/blob/index.d.ts
+/** Blob content paired with the ETag required for compare-and-swap persistence. */
 interface BlobObject {
+  /** Complete UTF-8 body returned by an uncached read. */
   body: string;
+  /** Current object ETag used to fence a later conditional write. */
   etag: string;
 }
+/** Exact blob pathname requested from storage. */
+interface ReadBlobInput {
+  /** Exact namespaced object path; the client must not apply a second namespace. */
+  pathname: string;
+}
+/** Blob body and conditional-write policy used for one storage write. */
+interface WriteBlobInput extends ReadBlobInput {
+  /** Complete replacement body to persist. */
+  body: string;
+  /** Whether an existing path may be replaced; `false` means create-if-absent. */
+  overwrite: boolean;
+  /** Optional ETag that must still match atomically when overwriting. */
+  ifMatch?: string;
+}
+/** Path prefix used to list matching blobs. */
+interface ListBlobPathsInput {
+  /** Path prefix whose complete matching object names are requested. */
+  prefix: string;
+}
 /** The narrow blob operations the driver needs; injectable for tests. */
 interface BlobClient {
-  /** Must return the latest content, never a cached copy. */
-  read(pathname: string): Promise<BlobObject | null>;
-  /** Must reject if overwrite is false and the path exists, or if ifMatch is given and the ETag differs. */
-  write(pathname: string, body: string, overwrite: boolean, ifMatch?: string): Promise<void>;
-  listPaths(prefix: string): Promise<string[]>;
+  /**
+   * Returns the latest content rather than a cached copy, or `null` when absent.
+   *
+   * @param input - Exact object path to read.
+   * @returns Current body and ETag, or `null` when the path does not exist.
+   */
+  read(input: ReadBlobInput): Promise<BlobObject | null>;
+  /**
+   * Persists one complete object and enforces its create or ETag precondition atomically.
+   *
+   * @param input - Exact path, body, overwrite policy, and optional ETag fence.
+   * @returns After the object write is durable at the provider boundary.
+   */
+  write(input: WriteBlobInput): Promise<void>;
+  /**
+   * Lists every object path matching the prefix, following all provider pages.
+   *
+   * @param input - Namespace prefix to enumerate.
+   * @returns Matching exact paths; callers do not depend on their order.
+   */
+  listPaths(input: ListBlobPathsInput): Promise<readonly string[]>;
 }
+/**
+ * Default private Vercel Blob client used by the durable Factory store driver.
+ * Reads explicitly bypass the CDN cache, and writes resolve only after the SDK accepts them.
+ */
 declare const vercelBlobClient: BlobClient;
+/** Bounds retries and exponential backoff for transient Blob operations. */
+interface BlobRetryOptions {
+  /** Positive integer attempts for one read or write, including the first. Default 3. */
+  attempts?: number;
+  /** Finite non-negative backoff base in milliseconds; doubles each retry. Default 250. */
+  baseDelayMs?: number;
+  /** Finite non-negative elapsed-time ceiling in milliseconds. Default 5000. */
+  maxTotalMs?: number;
+}
+/** Configures the Blob client, namespace, read concurrency, and transient retries. */
 interface BlobDriverOptions {
+  /** Blob transport used for reads, conditional writes, and listings; defaults to Vercel Blob. */
   client?: BlobClient;
   /** Path prefix inside the blob store; defaults to "factory". */
   prefix?: string;
   /** Maximum Blob downloads in flight while listing a collection. Default 32. */
   readConcurrency?: number;
+  /** Bounds retry of transient (5xx/429/network) Blob failures on reads and writes. */
+  retry?: BlobRetryOptions;
+  /** Millisecond clock used to bound total retry time. */
+  now?: MillisecondClock;
 }
 /**
- * Store driver on Vercel Blob: durable and dependency-free (one Blob store on
- * the project, no database). Inserts are create-if-absent. Updates read the latest content,
- * bypassing Blob's CDN cache, and write with an ETag precondition, so a
- * writer that lost a race gets a VersionConflictError rather than
- * overwriting the winner.
+ * Creates a durable Vercel Blob driver with atomic compare-and-swap updates.
+ *
+ * @remarks
+ * Inserts are create-if-absent. Updates bypass Blob's CDN cache and use the current ETag, so a
+ * writer that loses a race receives `VersionConflictError` instead of overwriting the winner.
+ * Reads and writes retry only 5xx, 429, and network failures within the configured attempt and
+ * elapsed-time bounds; exhaustion surfaces as `TransientStoreError`. If a transient write may
+ * have landed before its response was lost, the retry reads the record back and treats only the
+ * exact intended value and version as success. A different value remains a real conflict.
+ *
+ * Collection listing downloads records under the shared `readConcurrency` bound, coalesces
+ * concurrent lists of the same collection, and rejects malformed persisted values. Listing the
+ * provider's paths itself is not retried by this driver. The caller owns credentials and any
+ * injected client's lifecycle.
+ *
+ * @param options - Optional Blob transport, namespace, read limit, retry policy, and retry clock.
+ * @returns A `blob` driver suitable for `createStores`.
+ * @throws When concurrency or retry bounds are invalid.
  */
 declare function createBlobDriver(options?: BlobDriverOptions): StoreDriver;
 //#endregion
-export { BlobClient, BlobDriverOptions, BlobObject, createBlobDriver, vercelBlobClient };
+export { type ArtifactInput, type ArtifactKind, type ArtifactRef, type ArtifactStore, BlobClient, BlobDriverOptions, BlobObject, BlobRetryOptions, ListBlobPathsInput, type ReadArtifactInput, ReadBlobInput, WriteBlobInput, artifactReference, createArtifactStore, createBlobDriver, parseArtifactRef, vercelBlobClient };
 //# sourceMappingURL=index.d.mts.map