@vercel/factory 0.0.13 → 0.0.15

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,32 +1,68 @@
-import { i as StoreDriver } from "../driver-BJutB0PE.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 {
   body: string;
   etag: string;
 }
+/** Exact blob pathname requested from storage. */
+interface ReadBlobInput {
+  pathname: string;
+}
+/** Blob body and conditional-write policy used for one storage write. */
+interface WriteBlobInput extends ReadBlobInput {
+  body: string;
+  overwrite: boolean;
+  ifMatch?: string;
+}
+/** Path prefix used to list matching blobs. */
+interface ListBlobPathsInput {
+  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>;
+  read(input: ReadBlobInput): 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[]>;
+  write(input: WriteBlobInput): Promise<void>;
+  listPaths(input: ListBlobPathsInput): Promise<readonly string[]>;
 }
+/** Default private Vercel Blob client used by the durable Factory store driver. */
 declare const vercelBlobClient: BlobClient;
+/** Bounds retries and exponential backoff for transient Blob operations. */
+interface BlobRetryOptions {
+  /** Maximum attempts of a single read or write, including the first. Default 3. */
+  attempts?: number;
+  /** Backoff base in milliseconds; doubles each retry. Default 250. */
+  baseDelayMs?: number;
+  /** Ceiling on total elapsed retry time so a real outage still surfaces as a failure. Default 5000. */
+  maxTotalMs?: number;
+}
+/** Configures the Blob client, namespace, read concurrency, and transient retries. */
 interface BlobDriverOptions {
   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 and receipts are exactly as safe as on
- * Postgres (create-if-absent is atomic). Updates read the latest content,
+ * 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.
+ * overwriting the winner. Reads and writes retry with backoff on transient
+ * (5xx/429/network) failures, bounded by attempts and total elapsed time;
+ * once exhausted, the failure surfaces as TransientStoreError so a real
+ * outage does not hang a caller retrying forever.
  */
 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

package/dist/blob/index.mjs

@@ -1,4 +1,5 @@
-import { n as RecordNotFoundError, r as VersionConflictError, t as RecordExistsError } from "../driver-Bbd25rNM.mjs";
+import { RecordExistsError, RecordNotFoundError, TransientStoreError, VersionConflictError } from "../store/driver.mjs";
+import { artifactReference, createArtifactStore, parseArtifactRef } from "./artifacts.mjs";
 import { get, list, put } from "@vercel/blob";
 //#region src/blob/index.ts
 function isNotFoundError(error) {
@@ -10,8 +11,44 @@ function isAlreadyExistsError(error) {
 function isPreconditionError(error) {
 	return error instanceof Error && (error.name === "BlobPreconditionFailedError" || /precondition|etag|412/iu.test(error.message));
 }
+const TRANSIENT_NETWORK_ERROR_CODES = /* @__PURE__ */ new Set([
+	"ECONNRESET",
+	"ECONNREFUSED",
+	"ETIMEDOUT",
+	"ENOTFOUND",
+	"EAI_AGAIN",
+	"EPIPE",
+	"EHOSTUNREACH",
+	"ENETUNREACH",
+	"UND_ERR_CONNECT_TIMEOUT",
+	"UND_ERR_SOCKET",
+	"UND_ERR_HEADERS_TIMEOUT"
+]);
+function isTransientBlobError(error) {
+	if (!(error instanceof Error)) return false;
+	if (isAlreadyExistsError(error) || isPreconditionError(error) || isNotFoundError(error)) return false;
+	const code = error.code;
+	if (code !== void 0 && TRANSIENT_NETWORK_ERROR_CODES.has(code)) return true;
+	if (error.name === "AbortError") return true;
+	if (/fetch failed|network|socket hang up|timed? ?out|ECONNRESET|ECONNREFUSED|ETIMEDOUT|ENOTFOUND|EAI_AGAIN/iu.test(error.message)) return true;
+	return /(?:^|[^0-9])(?:429|5\d{2})(?:[^0-9]|$)/u.test(error.message);
+}
+function jsonValuesEqual(a, b) {
+	if (a === b) return true;
+	if (typeof a !== typeof b) return false;
+	if (a === null || b === null || typeof a !== "object" || typeof b !== "object") return false;
+	if (Array.isArray(a) || Array.isArray(b)) {
+		if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false;
+		return a.every((item, index) => jsonValuesEqual(item, b[index]));
+	}
+	const aKeys = Object.keys(a);
+	const bKeys = Object.keys(b);
+	if (aKeys.length !== bKeys.length) return false;
+	return aKeys.every((key) => Object.hasOwn(b, key) && jsonValuesEqual(a[key], b[key]));
+}
+/** Default private Vercel Blob client used by the durable Factory store driver. */
 const vercelBlobClient = {
-	async read(pathname) {
+	async read({ pathname }) {
 		let result;
 		try {
 			result = await get(pathname, {
@@ -28,15 +65,15 @@ const vercelBlobClient = {
 			etag: result.blob.etag
 		};
 	},
-	async write(pathname, body, overwrite, ifMatch) {
-		await put(pathname, body, {
+	async write({ pathname, body, overwrite, ifMatch }) {
+		await put(pathname, body === "" ? Buffer.alloc(0) : body, {
 			access: "private",
 			allowOverwrite: overwrite,
 			contentType: "application/json",
-			...ifMatch === void 0 ? {} : { ifMatch }
+			...ifMatch === void 0 ? {} : { ifMatch: ifMatch.replace(/^W\//u, "") }
 		});
 	},
-	async listPaths(prefix) {
+	async listPaths({ prefix }) {
 		const paths = [];
 		let cursor;
 		do {
@@ -53,22 +90,57 @@ const vercelBlobClient = {
 };
 /**
 * Store driver on Vercel Blob: durable and dependency-free (one Blob store on
-* the project, no database). Inserts and receipts are exactly as safe as on
-* Postgres (create-if-absent is atomic). Updates read the latest content,
+* 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.
+* overwriting the winner. Reads and writes retry with backoff on transient
+* (5xx/429/network) failures, bounded by attempts and total elapsed time;
+* once exhausted, the failure surfaces as TransientStoreError so a real
+* outage does not hang a caller retrying forever.
 */
 function createBlobDriver(options = {}) {
 	const client = options.client ?? vercelBlobClient;
+	const now = options.now ?? Date.now;
 	const prefix = options.prefix ?? "factory";
+	const readConcurrency = options.readConcurrency ?? 32;
+	if (!Number.isInteger(readConcurrency) || readConcurrency < 1) throw new Error("Blob read concurrency must be a positive integer");
+	const retry = {
+		attempts: options.retry?.attempts ?? 3,
+		baseDelayMs: options.retry?.baseDelayMs ?? 250,
+		maxTotalMs: options.retry?.maxTotalMs ?? 5e3
+	};
+	let activeReads = 0;
+	const readWaiters = [];
+	const activeLists = /* @__PURE__ */ new Map();
+	async function withTransientRetry(collection, id, operation) {
+		const start = now();
+		for (let attempt = 0;; attempt += 1) try {
+			return await operation();
+		} catch (error) {
+			if (!isTransientBlobError(error)) throw error;
+			const nextDelayMs = retry.baseDelayMs * 2 ** attempt;
+			if (attempt >= retry.attempts - 1 || now() - start + nextDelayMs > retry.maxTotalMs) throw new TransientStoreError(collection, id, error);
+			await new Promise((resolve) => setTimeout(resolve, nextDelayMs));
+		}
+	}
+	async function limitedRead(pathname) {
+		if (activeReads < readConcurrency) activeReads += 1;
+		else await new Promise((resolve) => readWaiters.push(resolve));
+		try {
+			return await client.read({ pathname });
+		} finally {
+			const waiter = readWaiters.shift();
+			if (waiter === void 0) activeReads -= 1;
+			else waiter();
+		}
+	}
 	function pathFor(collection, id) {
 		return `${prefix}/${collection}/${id}.json`;
 	}
 	async function readRecord(collection, id) {
 		let object;
 		try {
-			object = await client.read(pathFor(collection, id));
+			object = await withTransientRetry(collection, id, () => limitedRead(pathFor(collection, id)));
 		} catch (error) {
 			if (isNotFoundError(error)) return null;
 			throw error;
@@ -82,6 +154,14 @@ function createBlobDriver(options = {}) {
 			etag: object.etag
 		};
 	}
+	async function wroteThisInsert(collection, id, value) {
+		const after = await readRecord(collection, id);
+		return after !== null && after.version === 1 && jsonValuesEqual(after.value, value);
+	}
+	async function wroteThisUpdate(collection, id, value, expectedNewVersion) {
+		const after = await readRecord(collection, id);
+		return after !== null && after.version === expectedNewVersion && jsonValuesEqual(after.value, value);
+	}
 	return {
 		name: "blob",
 		async get(collection, id) {
@@ -91,51 +171,95 @@ function createBlobDriver(options = {}) {
 				version: record.version
 			};
 		},
-		async insert(collection, id, value) {
+		async insert({ collection, id, value }) {
+			let attempts = 0;
 			try {
-				await client.write(pathFor(collection, id), JSON.stringify({
-					value,
-					version: 1
-				}), false);
+				await withTransientRetry(collection, id, () => {
+					attempts += 1;
+					return client.write({
+						pathname: pathFor(collection, id),
+						body: JSON.stringify({
+							value,
+							version: 1
+						}),
+						overwrite: false
+					});
+				});
 			} catch (error) {
-				if (isAlreadyExistsError(error)) throw new RecordExistsError(collection, id);
+				if (isAlreadyExistsError(error)) {
+					if (attempts > 1 && await wroteThisInsert(collection, id, value)) return;
+					throw new RecordExistsError(collection, id);
+				}
 				throw error;
 			}
 		},
-		async update(collection, id, value, expectedVersion) {
+		async update({ collection, id, value, expectedVersion }) {
 			const existing = await readRecord(collection, id);
 			if (existing === null) throw new RecordNotFoundError(collection, id);
 			if (existing.version !== expectedVersion) throw new VersionConflictError(collection, id, expectedVersion);
+			let attempts = 0;
 			try {
-				await client.write(pathFor(collection, id), JSON.stringify({
-					value,
-					version: expectedVersion + 1
-				}), true, existing.etag.replace(/^W\//u, ""));
+				await withTransientRetry(collection, id, () => {
+					attempts += 1;
+					return client.write({
+						pathname: pathFor(collection, id),
+						body: JSON.stringify({
+							value,
+							version: expectedVersion + 1
+						}),
+						overwrite: true,
+						ifMatch: existing.etag.replace(/^W\//u, "")
+					});
+				});
 			} catch (error) {
-				if (isPreconditionError(error)) throw new VersionConflictError(collection, id, expectedVersion);
+				if (isPreconditionError(error)) {
+					if (attempts > 1 && await wroteThisUpdate(collection, id, value, expectedVersion + 1)) return;
+					throw new VersionConflictError(collection, id, expectedVersion);
+				}
 				throw error;
 			}
 		},
 		async list(collection) {
-			const dir = `${prefix}/${collection}/`;
-			const paths = await client.listPaths(dir);
-			const entries = [];
-			for (const pathname of paths) {
-				const id = pathname.slice(dir.length).replace(/\.json$/u, "");
-				const record = await readRecord(collection, id);
-				if (record !== null) entries.push({
-					id,
-					record: {
-						value: record.value,
-						version: record.version
+			const active = activeLists.get(collection);
+			if (active !== void 0) return active;
+			const listing = (async () => {
+				const dir = `${prefix}/${collection}/`;
+				const paths = await client.listPaths({ prefix: dir });
+				const entries = new Array(paths.length);
+				let next = 0;
+				let failure;
+				const workers = Array.from({ length: Math.min(readConcurrency, paths.length) }, async () => {
+					while (next < paths.length && failure === void 0) {
+						const index = next++;
+						const id = paths[index].slice(dir.length).replace(/\.json$/u, "");
+						try {
+							const record = await readRecord(collection, id);
+							entries[index] = record === null ? null : {
+								id,
+								record: {
+									value: record.value,
+									version: record.version
+								}
+							};
+						} catch (error) {
+							failure ??= error;
+						}
 					}
 				});
+				await Promise.all(workers);
+				if (failure !== void 0) throw failure;
+				return entries.filter((entry) => entry !== null);
+			})();
+			activeLists.set(collection, listing);
+			try {
+				return await listing;
+			} finally {
+				if (activeLists.get(collection) === listing) activeLists.delete(collection);
 			}
-			return entries;
 		}
 	};
 }
 //#endregion
-export { createBlobDriver, vercelBlobClient };
+export { artifactReference, createArtifactStore, createBlobDriver, parseArtifactRef, vercelBlobClient };
 
 //# sourceMappingURL=index.mjs.map