@vercel/factory 0.0.14 → 0.0.16

package/dist/schema/factory-config.mjs

@@ -0,0 +1,90 @@
+import { repositorySlugSchema } from "./repository.mjs";
+import { budgetLimitsSchema } from "./budget.mjs";
+import { taskKindSchema } from "./task.mjs";
+import { allowByDefaultApprovalPolicy, approvalPolicySchema } from "../approval.mjs";
+import { slackPrNotificationsSchema } from "./slack-pr-notifications.mjs";
+import { z } from "zod";
+//#region src/schema/factory-config.ts
+/** Validates one repository allowlist entry and its configured dependency ordering. */
+const factoryConfigRepositorySchema = z.strictObject({
+	slug: repositorySlugSchema.describe("Repository this factory may work on."),
+	defaultBranch: z.string().min(1).default("main").describe("Branch changes land on, usually main."),
+	dependsOn: z.array(repositorySlugSchema).readonly().default([]).describe("Repositories that must land changes before this repository.")
+}).readonly();
+const githubConnectorSchema = z.strictObject({
+	owner: z.string().regex(/^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/).describe("GitHub user or organization that owns this connector installation."),
+	connector: z.string().regex(/^github\/[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/).describe("Vercel Connect UID installed for this GitHub owner.")
+}).readonly();
+const slackConnectorSchema = z.strictObject({
+	connector: z.string().regex(/^slack\/[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/).describe("Vercel Connect UID installed for this Slack app."),
+	operatorDirectMessages: z.boolean().default(false).describe("Opt in to operator DMs for human-action requests, digests, and budget alerts. Independent of operator authorization, PR announcements, and replies in the original conversation."),
+	approvalChannel: z.string().regex(/^[CDG][A-Z0-9]+$/u).optional().describe("Explicit Slack channel for approval proposals that have no originating Slack thread. Absent disables cross-channel approval notifications."),
+	autonomousPullRequests: slackPrNotificationsSchema.optional().describe("Channel announcements for every Factory-produced PR, including human-requested work, in addition to the original conversation reply. Saved Slack settings override this default; resetting restores it. Absent disables announcements unless Slack enables them."),
+	autonomousPullRequestsByRepository: z.record(repositorySlugSchema, slackPrNotificationsSchema.nullable()).readonly().optional().describe("Repository-specific PR destinations, taking precedence over the factory-wide default. Null disables announcements for that repository. Saved repository settings override these entries.")
+}).readonly();
+function isSupportedCommitIdentityValue(value, maxBytes) {
+	return value.trim() === value && !/[\0\r\n<>]/u.test(value) && new TextEncoder().encode(value).byteLength <= maxBytes;
+}
+const commitIdentitySchema = z.strictObject({
+	name: z.string().min(1).refine((value) => isSupportedCommitIdentityValue(value, 256)).describe("Name recorded on Factory-authored commits."),
+	email: z.string().email().refine((value) => isSupportedCommitIdentityValue(value, 320)).describe("Email recorded on Factory-authored commits.")
+}).readonly();
+/** Validates stall detection and replacement-attempt limits for running Tasks. */
+const executionPolicySchema = z.strictObject({
+	maxAttempts: z.number().int().min(1).describe("Attempts a task may consume before a stall fails it for good."),
+	stallMinutes: z.number().int().min(1).describe("Minutes without progress before a running task is marked stalled."),
+	stallMinutesByKind: z.partialRecord(taskKindSchema, z.number().int().min(1)).readonly().default({}).describe("Per-kind stall windows for long single-step work, e.g. security_scan: 300.")
+}).readonly();
+/** Conservative default stall window and three-attempt execution policy. */
+const defaultExecutionPolicy = executionPolicySchema.parse({
+	maxAttempts: 3,
+	stallMinutes: 45,
+	stallMinutesByKind: {}
+});
+/** Validates the repositories, operators, connectors, budget, and policies of a Factory. */
+const factoryConfigSchema = z.strictObject({
+	connectors: z.strictObject({
+		github: z.array(githubConnectorSchema).readonly().refine((connectors) => new Set(connectors.map(({ owner }) => owner)).size === connectors.length, "GitHub connector owners must be unique."),
+		slack: z.array(slackConnectorSchema).max(1, "A factory may configure one Slack connector.").readonly().default([])
+	}).readonly().default({
+		github: [],
+		slack: []
+	}).describe("Provider connections available to this factory."),
+	repositories: z.array(factoryConfigRepositorySchema).min(1).readonly().describe("Repositories this factory is allowed to inspect and change."),
+	operators: z.array(z.string().min(1)).min(1).readonly().describe("Provider-qualified identities allowed to operate this factory."),
+	sandboxGitHubCredentials: z.enum(["connect", "vercel"]).default("connect").describe("Credential source selected for trusted GitHub Sandbox operations."),
+	commitIdentity: commitIdentitySchema.default({
+		name: "Vercel Factory",
+		email: "not+real@example.org"
+	}).describe("Replaceable attribution metadata for Factory-authored commits."),
+	approval: approvalPolicySchema.default(allowByDefaultApprovalPolicy).describe("Which Tasks wait for a human before they run. First match wins."),
+	budget: budgetLimitsSchema.default({
+		totalUsd: 500,
+		investigationUsd: 100,
+		perTaskReservationUsd: 5,
+		warningPercent: 80
+	}).describe("Monthly spending thresholds and per-task accounting reservations."),
+	enforceBudget: z.boolean().default(true).describe("Refuse new work above the monthly budget. False keeps cost accounting without spending limits or budget alerts."),
+	execution: executionPolicySchema.default(defaultExecutionPolicy).describe("Stall detection and retry limits for running tasks.")
+}).superRefine((config, ctx) => {
+	const repositories = new Set(config.repositories.map(({ slug }) => slug));
+	for (const [index, connector] of config.connectors.slack.entries()) for (const slug of Object.keys(connector.autonomousPullRequestsByRepository ?? {})) if (!repositories.has(slug)) ctx.addIssue({
+		code: "custom",
+		path: [
+			"connectors",
+			"slack",
+			index,
+			"autonomousPullRequestsByRepository",
+			slug
+		],
+		message: "PR notification destinations must name a configured repository."
+	});
+}).readonly();
+/** Validates a Factory configuration and applies its declared defaults. */
+function defineFactory(config) {
+	return factoryConfigSchema.parse(config);
+}
+//#endregion
+export { defaultExecutionPolicy, defineFactory, executionPolicySchema, factoryConfigRepositorySchema, factoryConfigSchema };
+
+//# sourceMappingURL=factory-config.mjs.map

package/dist/schema/factory-config.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory-config.mjs","names":[],"sources":["../../src/schema/factory-config.ts"],"sourcesContent":["import { z } from \"zod\";\nimport { allowByDefaultApprovalPolicy, approvalPolicySchema } from \"../approval\";\nimport { budgetLimitsSchema } from \"./budget\";\nimport { repositorySlugSchema, type RepositorySlug } from \"./repository\";\nimport { taskKindSchema } from \"./task\";\nimport { slackPrNotificationsSchema } from \"./slack-pr-notifications\";\n\n/** Validates one repository allowlist entry and its configured dependency ordering. */\nexport const factoryConfigRepositorySchema = z\n  .strictObject({\n    slug: repositorySlugSchema.describe(\"Repository this factory may work on.\"),\n    defaultBranch: z\n      .string()\n      .min(1)\n      .default(\"main\")\n      .describe(\"Branch changes land on, usually main.\"),\n    dependsOn: z\n      .array(repositorySlugSchema)\n      .readonly()\n      .default([])\n      .describe(\"Repositories that must land changes before this repository.\"),\n  })\n  .readonly();\n\nconst githubConnectorSchema = z\n  .strictObject({\n    owner: z\n      .string()\n      .regex(/^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/)\n      .describe(\"GitHub user or organization that owns this connector installation.\"),\n    connector: z\n      .string()\n      .regex(/^github\\/[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/)\n      .describe(\"Vercel Connect UID installed for this GitHub owner.\"),\n  })\n  .readonly();\n\nconst slackConnectorSchema = z\n  .strictObject({\n    connector: z\n      .string()\n      .regex(/^slack\\/[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/)\n      .describe(\"Vercel Connect UID installed for this Slack app.\"),\n    operatorDirectMessages: z\n      .boolean()\n      .default(false)\n      .describe(\n        \"Opt in to operator DMs for human-action requests, digests, and budget alerts. Independent of operator authorization, PR announcements, and replies in the original conversation.\",\n      ),\n    approvalChannel: z\n      .string()\n      .regex(/^[CDG][A-Z0-9]+$/u)\n      .optional()\n      .describe(\n        \"Explicit Slack channel for approval proposals that have no originating Slack thread. Absent disables cross-channel approval notifications.\",\n      ),\n    autonomousPullRequests: slackPrNotificationsSchema\n      .optional()\n      .describe(\n        \"Channel announcements for every Factory-produced PR, including human-requested work, in addition to the original conversation reply. Saved Slack settings override this default; resetting restores it. Absent disables announcements unless Slack enables them.\",\n      ),\n    autonomousPullRequestsByRepository: z\n      .record(repositorySlugSchema, slackPrNotificationsSchema.nullable())\n      .readonly()\n      .optional()\n      .describe(\n        \"Repository-specific PR destinations, taking precedence over the factory-wide default. Null disables announcements for that repository. Saved repository settings override these entries.\",\n      ),\n  })\n  .readonly();\n\nfunction isSupportedCommitIdentityValue(value: string, maxBytes: number): boolean {\n  return (\n    value.trim() === value &&\n    !/[\\0\\r\\n<>]/u.test(value) &&\n    new TextEncoder().encode(value).byteLength <= maxBytes\n  );\n}\n\nconst commitIdentitySchema = z\n  .strictObject({\n    name: z\n      .string()\n      .min(1)\n      .refine((value) => isSupportedCommitIdentityValue(value, 256))\n      .describe(\"Name recorded on Factory-authored commits.\"),\n    email: z\n      .string()\n      .email()\n      .refine((value) => isSupportedCommitIdentityValue(value, 320))\n      .describe(\"Email recorded on Factory-authored commits.\"),\n  })\n  .readonly();\n\n/** Validates stall detection and replacement-attempt limits for running Tasks. */\nexport const executionPolicySchema = z\n  .strictObject({\n    maxAttempts: z\n      .number()\n      .int()\n      .min(1)\n      .describe(\"Attempts a task may consume before a stall fails it for good.\"),\n    stallMinutes: z\n      .number()\n      .int()\n      .min(1)\n      .describe(\"Minutes without progress before a running task is marked stalled.\"),\n    stallMinutesByKind: z\n      .partialRecord(taskKindSchema, z.number().int().min(1))\n      .readonly()\n      .default({})\n      .describe(\"Per-kind stall windows for long single-step work, e.g. security_scan: 300.\"),\n  })\n  .readonly();\n\n/** Stall detection and retry limits applied to running Tasks. */\nexport type ExecutionPolicy = z.infer<typeof executionPolicySchema>;\n\n/** Conservative default stall window and three-attempt execution policy. */\nexport const defaultExecutionPolicy = executionPolicySchema.parse({\n  maxAttempts: 3,\n  stallMinutes: 45,\n  stallMinutesByKind: {},\n});\n\n/** Validates the repositories, operators, connectors, budget, and policies of a Factory. */\nexport const factoryConfigSchema = z\n  .strictObject({\n    connectors: z\n      .strictObject({\n        github: z\n          .array(githubConnectorSchema)\n          .readonly()\n          .refine(\n            (connectors) =>\n              new Set(connectors.map(({ owner }) => owner)).size === connectors.length,\n            \"GitHub connector owners must be unique.\",\n          ),\n        slack: z\n          .array(slackConnectorSchema)\n          .max(1, \"A factory may configure one Slack connector.\")\n          .readonly()\n          .default([]),\n      })\n      .readonly()\n      .default({ github: [], slack: [] })\n      .describe(\"Provider connections available to this factory.\"),\n    repositories: z\n      .array(factoryConfigRepositorySchema)\n      .min(1)\n      .readonly()\n      .describe(\"Repositories this factory is allowed to inspect and change.\"),\n    operators: z\n      .array(z.string().min(1))\n      .min(1)\n      .readonly()\n      .describe(\"Provider-qualified identities allowed to operate this factory.\"),\n    sandboxGitHubCredentials: z\n      .enum([\"connect\", \"vercel\"])\n      .default(\"connect\")\n      .describe(\"Credential source selected for trusted GitHub Sandbox operations.\"),\n    commitIdentity: commitIdentitySchema\n      .default({ name: \"Vercel Factory\", email: \"not+real@example.org\" })\n      .describe(\"Replaceable attribution metadata for Factory-authored commits.\"),\n    approval: approvalPolicySchema\n      .default(allowByDefaultApprovalPolicy)\n      .describe(\"Which Tasks wait for a human before they run. First match wins.\"),\n    budget: budgetLimitsSchema\n      .default({\n        totalUsd: 500,\n        investigationUsd: 100,\n        perTaskReservationUsd: 5,\n        warningPercent: 80,\n      })\n      .describe(\"Monthly spending thresholds and per-task accounting reservations.\"),\n    enforceBudget: z\n      .boolean()\n      .default(true)\n      .describe(\n        \"Refuse new work above the monthly budget. False keeps cost accounting without spending limits or budget alerts.\",\n      ),\n    execution: executionPolicySchema\n      .default(defaultExecutionPolicy)\n      .describe(\"Stall detection and retry limits for running tasks.\"),\n  })\n  .superRefine((config, ctx) => {\n    const repositories = new Set<string>(config.repositories.map(({ slug }) => slug));\n    for (const [index, connector] of config.connectors.slack.entries()) {\n      for (const slug of Object.keys(connector.autonomousPullRequestsByRepository ?? {})) {\n        if (!repositories.has(slug))\n          ctx.addIssue({\n            code: \"custom\",\n            path: [\"connectors\", \"slack\", index, \"autonomousPullRequestsByRepository\", slug],\n            message: \"PR notification destinations must name a configured repository.\",\n          });\n      }\n    }\n  })\n  .readonly();\n\n/** Fully resolved repository allowlist entry in a Factory configuration. */\nexport type FactoryConfigRepository = z.infer<typeof factoryConfigRepositorySchema>;\n\n/** Fully resolved and validated Factory configuration. */\nexport type FactoryConfig = z.infer<typeof factoryConfigSchema>;\ntype FactoryConfigSchemaInput = z.input<typeof factoryConfigSchema>;\ntype FactoryConfigConnectorsInput = Readonly<{\n  github: readonly Readonly<z.input<typeof githubConnectorSchema>>[];\n  slack?: readonly Readonly<z.input<typeof slackConnectorSchema>>[];\n}>;\n/** Repository allowlist entry accepted when defining a Factory, before defaults are applied. */\nexport type FactoryConfigRepositoryInput = Readonly<{\n  slug: RepositorySlug;\n  defaultBranch?: string;\n  dependsOn?: readonly RepositorySlug[];\n}>;\n/** Caller input accepted when defining a Factory, before schema defaults are applied. */\nexport type FactoryConfigInput = Readonly<\n  Omit<FactoryConfigSchemaInput, \"connectors\" | \"repositories\" | \"operators\"> & {\n    connectors?: FactoryConfigConnectorsInput;\n    repositories: readonly FactoryConfigRepositoryInput[];\n    operators: readonly string[];\n  }\n>;\n\n/** Validates a Factory configuration and applies its declared defaults. */\nexport function defineFactory(config: FactoryConfigInput): FactoryConfig {\n  return factoryConfigSchema.parse(config);\n}\n"],"mappings":"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"}

package/dist/schema/finding.d.mts

@@ -0,0 +1,125 @@
+import { z } from "zod";
+//#region src/schema/finding.d.ts
+/** Validates the operational urgency assigned to a repository finding. */
+declare const findingPrioritySchema: z.ZodEnum<{
+  P0: "P0";
+  P1: "P1";
+  P2: "P2";
+  P3: "P3";
+}>;
+/** Validates the engineering concern category assigned to a finding. */
+declare const findingCategorySchema: z.ZodEnum<{
+  security: "security";
+  correctness: "correctness";
+  reliability: "reliability";
+  performance: "performance";
+  compatibility: "compatibility";
+  accessibility: "accessibility";
+  documentation: "documentation";
+  maintainability: "maintainability";
+  testing: "testing";
+  usability: "usability";
+}>;
+/** Validates how strongly the available evidence supports a finding. */
+declare const findingVerificationLevelSchema: z.ZodEnum<{
+  unverified: "unverified";
+  supported: "supported";
+  confirmed: "confirmed";
+}>;
+/** Validates the method used to investigate or demonstrate a finding. */
+declare const findingVerificationMethodSchema: z.ZodEnum<{
+  documentation: "documentation";
+  code_inspection: "code_inspection";
+  static_analysis: "static_analysis";
+  manual_reproduction: "manual_reproduction";
+  unit_test: "unit_test";
+  integration_test: "integration_test";
+  e2e_test: "e2e_test";
+  runtime_observation: "runtime_observation";
+}>;
+/**
+ * What was done to check the finding. Forces a reporter to distinguish "I
+ * think this is a problem" from "I demonstrated it", which is the axis a human
+ * approving fixes cares about most.
+ */
+declare const findingVerificationSchema: z.ZodObject<{
+  level: z.ZodEnum<{
+    unverified: "unverified";
+    supported: "supported";
+    confirmed: "confirmed";
+  }>;
+  method: z.ZodEnum<{
+    documentation: "documentation";
+    code_inspection: "code_inspection";
+    static_analysis: "static_analysis";
+    manual_reproduction: "manual_reproduction";
+    unit_test: "unit_test";
+    integration_test: "integration_test";
+    e2e_test: "e2e_test";
+    runtime_observation: "runtime_observation";
+  }>;
+  summary: z.ZodString;
+  limitations: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/** A single problem found in a repository, as a scanner or agent reports it. */
+declare const findingSchema: z.ZodObject<{
+  title: z.ZodString;
+  body: z.ZodString;
+  path: z.ZodOptional<z.ZodString>;
+  line: z.ZodOptional<z.ZodNumber>;
+  endLine: z.ZodOptional<z.ZodNumber>;
+  priority: z.ZodEnum<{
+    P0: "P0";
+    P1: "P1";
+    P2: "P2";
+    P3: "P3";
+  }>;
+  category: z.ZodEnum<{
+    security: "security";
+    correctness: "correctness";
+    reliability: "reliability";
+    performance: "performance";
+    compatibility: "compatibility";
+    accessibility: "accessibility";
+    documentation: "documentation";
+    maintainability: "maintainability";
+    testing: "testing";
+    usability: "usability";
+  }>;
+  verification: z.ZodObject<{
+    level: z.ZodEnum<{
+      unverified: "unverified";
+      supported: "supported";
+      confirmed: "confirmed";
+    }>;
+    method: z.ZodEnum<{
+      documentation: "documentation";
+      code_inspection: "code_inspection";
+      static_analysis: "static_analysis";
+      manual_reproduction: "manual_reproduction";
+      unit_test: "unit_test";
+      integration_test: "integration_test";
+      e2e_test: "e2e_test";
+      runtime_observation: "runtime_observation";
+    }>;
+    summary: z.ZodString;
+    limitations: z.ZodOptional<z.ZodString>;
+  }, z.core.$strict>;
+  tool: z.ZodOptional<z.ZodString>;
+  ruleId: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/** Operational urgency of a repository finding, from P0 through P3. */
+type FindingPriority = z.infer<typeof findingPrioritySchema>;
+/** Engineering concern category used to group a repository finding. */
+type FindingCategory = z.infer<typeof findingCategorySchema>;
+/** Strength of evidence supporting a reported finding. */
+type FindingVerificationLevel = z.infer<typeof findingVerificationLevelSchema>;
+/** Investigation method used to support a reported finding. */
+type FindingVerificationMethod = z.infer<typeof findingVerificationMethodSchema>;
+/** Evidence level, method, and limitations recorded for a finding. */
+type FindingVerification = z.infer<typeof findingVerificationSchema>;
+/** Structured repository problem reported by a scanner or agent. */
+type Finding = z.infer<typeof findingSchema>;
+//#endregion
+export { Finding, FindingCategory, FindingPriority, FindingVerification, FindingVerificationLevel, FindingVerificationMethod, findingCategorySchema, findingPrioritySchema, findingSchema, findingVerificationLevelSchema, findingVerificationMethodSchema, findingVerificationSchema };
+//# sourceMappingURL=finding.d.mts.map

package/dist/schema/finding.mjs

@@ -0,0 +1,67 @@
+import { z } from "zod";
+//#region src/schema/finding.ts
+/** Validates the operational urgency assigned to a repository finding. */
+const findingPrioritySchema = z.enum([
+	"P0",
+	"P1",
+	"P2",
+	"P3"
+]).describe("Urgency of a finding: P0 is drop-everything, P3 is nice-to-have.");
+/** Validates the engineering concern category assigned to a finding. */
+const findingCategorySchema = z.enum([
+	"security",
+	"correctness",
+	"reliability",
+	"performance",
+	"compatibility",
+	"accessibility",
+	"documentation",
+	"maintainability",
+	"testing",
+	"usability"
+]);
+/** Validates how strongly the available evidence supports a finding. */
+const findingVerificationLevelSchema = z.enum([
+	"unverified",
+	"supported",
+	"confirmed"
+]).describe("How sure the reporter is: unverified = suspected from reading; supported = evidence points to it; confirmed = demonstrated.");
+/** Validates the method used to investigate or demonstrate a finding. */
+const findingVerificationMethodSchema = z.enum([
+	"code_inspection",
+	"static_analysis",
+	"manual_reproduction",
+	"unit_test",
+	"integration_test",
+	"e2e_test",
+	"runtime_observation",
+	"documentation"
+]);
+/**
+* What was done to check the finding. Forces a reporter to distinguish "I
+* think this is a problem" from "I demonstrated it", which is the axis a human
+* approving fixes cares about most.
+*/
+const findingVerificationSchema = z.strictObject({
+	level: findingVerificationLevelSchema,
+	method: findingVerificationMethodSchema,
+	summary: z.string().min(1).max(2e3).describe("What was checked and what it showed."),
+	limitations: z.string().min(1).max(2e3).optional().describe("What could not be checked.")
+});
+/** A single problem found in a repository, as a scanner or agent reports it. */
+const findingSchema = z.strictObject({
+	title: z.string().min(1).max(200),
+	body: z.string().min(1).max(8e3).describe("The problem, its impact, and how to fix it. Markdown."),
+	path: z.string().min(1).max(500).optional().describe("Repository-relative file path."),
+	line: z.number().int().min(1).optional(),
+	endLine: z.number().int().min(1).optional(),
+	priority: findingPrioritySchema,
+	category: findingCategorySchema,
+	verification: findingVerificationSchema,
+	tool: z.string().min(1).max(100).optional().describe("Scanner that produced it, e.g. deepsec."),
+	ruleId: z.string().min(1).max(200).optional().describe("Scanner rule or check id, when there is one.")
+});
+//#endregion
+export { findingCategorySchema, findingPrioritySchema, findingSchema, findingVerificationLevelSchema, findingVerificationMethodSchema, findingVerificationSchema };
+
+//# sourceMappingURL=finding.mjs.map

package/dist/schema/finding.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"finding.mjs","names":[],"sources":["../../src/schema/finding.ts"],"sourcesContent":["import { z } from \"zod\";\n\n/** Validates the operational urgency assigned to a repository finding. */\nexport const findingPrioritySchema = z\n  .enum([\"P0\", \"P1\", \"P2\", \"P3\"])\n  .describe(\"Urgency of a finding: P0 is drop-everything, P3 is nice-to-have.\");\n\n/** Validates the engineering concern category assigned to a finding. */\nexport const findingCategorySchema = z.enum([\n  \"security\",\n  \"correctness\",\n  \"reliability\",\n  \"performance\",\n  \"compatibility\",\n  \"accessibility\",\n  \"documentation\",\n  \"maintainability\",\n  \"testing\",\n  \"usability\",\n]);\n\n/** Validates how strongly the available evidence supports a finding. */\nexport const findingVerificationLevelSchema = z\n  .enum([\"unverified\", \"supported\", \"confirmed\"])\n  .describe(\n    \"How sure the reporter is: unverified = suspected from reading; supported = evidence points to it; confirmed = demonstrated.\",\n  );\n\n/** Validates the method used to investigate or demonstrate a finding. */\nexport const findingVerificationMethodSchema = z.enum([\n  \"code_inspection\",\n  \"static_analysis\",\n  \"manual_reproduction\",\n  \"unit_test\",\n  \"integration_test\",\n  \"e2e_test\",\n  \"runtime_observation\",\n  \"documentation\",\n]);\n\n/**\n * What was done to check the finding. Forces a reporter to distinguish \"I\n * think this is a problem\" from \"I demonstrated it\", which is the axis a human\n * approving fixes cares about most.\n */\nexport const findingVerificationSchema = z.strictObject({\n  level: findingVerificationLevelSchema,\n  method: findingVerificationMethodSchema,\n  summary: z.string().min(1).max(2000).describe(\"What was checked and what it showed.\"),\n  limitations: z.string().min(1).max(2000).optional().describe(\"What could not be checked.\"),\n});\n\n/** A single problem found in a repository, as a scanner or agent reports it. */\nexport const findingSchema = z.strictObject({\n  title: z.string().min(1).max(200),\n  body: z\n    .string()\n    .min(1)\n    .max(8000)\n    .describe(\"The problem, its impact, and how to fix it. Markdown.\"),\n  path: z.string().min(1).max(500).optional().describe(\"Repository-relative file path.\"),\n  line: z.number().int().min(1).optional(),\n  endLine: z.number().int().min(1).optional(),\n  priority: findingPrioritySchema,\n  category: findingCategorySchema,\n  verification: findingVerificationSchema,\n  tool: z.string().min(1).max(100).optional().describe(\"Scanner that produced it, e.g. deepsec.\"),\n  ruleId: z\n    .string()\n    .min(1)\n    .max(200)\n    .optional()\n    .describe(\"Scanner rule or check id, when there is one.\"),\n});\n\n/** Operational urgency of a repository finding, from P0 through P3. */\nexport type FindingPriority = z.infer<typeof findingPrioritySchema>;\n/** Engineering concern category used to group a repository finding. */\nexport type FindingCategory = z.infer<typeof findingCategorySchema>;\n/** Strength of evidence supporting a reported finding. */\nexport type FindingVerificationLevel = z.infer<typeof findingVerificationLevelSchema>;\n/** Investigation method used to support a reported finding. */\nexport type FindingVerificationMethod = z.infer<typeof findingVerificationMethodSchema>;\n/** Evidence level, method, and limitations recorded for a finding. */\nexport type FindingVerification = z.infer<typeof findingVerificationSchema>;\n/** Structured repository problem reported by a scanner or agent. */\nexport type Finding = z.infer<typeof findingSchema>;\n"],"mappings":";;;AAGA,MAAa,wBAAwB,EAClC,KAAK;CAAC;CAAM;CAAM;CAAM;AAAI,CAAC,CAAC,CAC9B,SAAS,kEAAkE;;AAG9E,MAAa,wBAAwB,EAAE,KAAK;CAC1C;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AACF,CAAC;;AAGD,MAAa,iCAAiC,EAC3C,KAAK;CAAC;CAAc;CAAa;AAAW,CAAC,CAAC,CAC9C,SACC,6HACF;;AAGF,MAAa,kCAAkC,EAAE,KAAK;CACpD;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AACF,CAAC;;;;;;AAOD,MAAa,4BAA4B,EAAE,aAAa;CACtD,OAAO;CACP,QAAQ;CACR,SAAS,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,GAAI,CAAC,CAAC,SAAS,sCAAsC;CACpF,aAAa,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,GAAI,CAAC,CAAC,SAAS,CAAC,CAAC,SAAS,4BAA4B;AAC3F,CAAC;;AAGD,MAAa,gBAAgB,EAAE,aAAa;CAC1C,OAAO,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,GAAG;CAChC,MAAM,EACH,OAAO,CAAC,CACR,IAAI,CAAC,CAAC,CACN,IAAI,GAAI,CAAC,CACT,SAAS,uDAAuD;CACnE,MAAM,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC,SAAS,gCAAgC;CACrF,MAAM,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS;CACvC,SAAS,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS;CAC1C,UAAU;CACV,UAAU;CACV,cAAc;CACd,MAAM,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC,SAAS,yCAAyC;CAC9F,QAAQ,EACL,OAAO,CAAC,CACR,IAAI,CAAC,CAAC,CACN,IAAI,GAAG,CAAC,CACR,SAAS,CAAC,CACV,SAAS,8CAA8C;AAC5D,CAAC"}

package/dist/schema/id.d.mts

@@ -0,0 +1,43 @@
+import { z } from "zod";
+//#region src/schema/id.d.ts
+/** Validates a stable Factory identifier. */
+declare const factoryIdSchema: z.ZodType<`fac_${string}`, string, z.core.$ZodTypeInternals<`fac_${string}`, string>>;
+/** Validates a stable repository identifier. */
+declare const repositoryIdSchema: z.ZodType<`repo_${string}`, string, z.core.$ZodTypeInternals<`repo_${string}`, string>>;
+/** Validates a stable inbound Signal identifier. */
+declare const signalIdSchema: z.ZodType<`sig_${string}`, string, z.core.$ZodTypeInternals<`sig_${string}`, string>>;
+/** Validates a stable Task identifier. */
+declare const taskIdSchema: z.ZodType<`task_${string}`, string, z.core.$ZodTypeInternals<`task_${string}`, string>>;
+/** Validates a stable Change identifier. */
+declare const changeIdSchema: z.ZodType<`chg_${string}`, string, z.core.$ZodTypeInternals<`chg_${string}`, string>>;
+/** Validates a stable immutable Receipt identifier. */
+declare const receiptIdSchema: z.ZodType<`rcpt_${string}`, string, z.core.$ZodTypeInternals<`rcpt_${string}`, string>>;
+/** Validates a stable communication outbox identifier. */
+declare const outboxIdSchema: z.ZodType<`out_${string}`, string, z.core.$ZodTypeInternals<`out_${string}`, string>>;
+/** Validates a stable immutable answer-event identifier. */
+declare const answerIdSchema: z.ZodType<`ans_${string}`, string, z.core.$ZodTypeInternals<`ans_${string}`, string>>;
+/** Validates a nonempty repository scope expressed as repository identifiers. */
+declare const repositoryIdsSchema: z.ZodReadonly<z.ZodTuple<[z.ZodType<`repo_${string}`, string, z.core.$ZodTypeInternals<`repo_${string}`, string>>], z.ZodType<`repo_${string}`, string, z.core.$ZodTypeInternals<`repo_${string}`, string>>>>;
+/** Constructs a validated nonempty repository scope from typed identifiers. */
+declare function repositoryScope(first: RepositoryId, ...rest: readonly RepositoryId[]): RepositoryIds;
+/** Stable identifier for one configured Factory. */
+type FactoryId = z.infer<typeof factoryIdSchema>;
+/** Stable identifier for one configured repository. */
+type RepositoryId = z.infer<typeof repositoryIdSchema>;
+/** Nonempty ordered repository scope attached to one Task or event. */
+type RepositoryIds = z.infer<typeof repositoryIdsSchema>;
+/** Stable identifier for one normalized inbound Signal. */
+type SignalId = z.infer<typeof signalIdSchema>;
+/** Stable identifier for one durable unit of workflow work. */
+type TaskId = z.infer<typeof taskIdSchema>;
+/** Stable identifier for one human-visible pull-request Change. */
+type ChangeId = z.infer<typeof changeIdSchema>;
+/** Stable identifier for one immutable audit Receipt. */
+type ReceiptId = z.infer<typeof receiptIdSchema>;
+/** Stable identifier for one communication outbox event. */
+type OutboxId = z.infer<typeof outboxIdSchema>;
+/** Stable identifier for one immutable authenticated answer event. */
+type AnswerId = z.infer<typeof answerIdSchema>;
+//#endregion
+export { AnswerId, ChangeId, FactoryId, OutboxId, ReceiptId, RepositoryId, RepositoryIds, SignalId, TaskId, answerIdSchema, changeIdSchema, factoryIdSchema, outboxIdSchema, receiptIdSchema, repositoryIdSchema, repositoryIdsSchema, repositoryScope, signalIdSchema, taskIdSchema };
+//# sourceMappingURL=id.d.mts.map

package/dist/schema/id.mjs

@@ -0,0 +1,32 @@
+import { z } from "zod";
+//#region src/schema/id.ts
+function idSchema(prefix) {
+	const pattern = new RegExp(`^${prefix}_[a-z0-9]{6,64}$`);
+	return z.string().regex(pattern, `Expected ${prefix}_ followed by 6 to 64 lowercase letters or digits`);
+}
+/** Validates a stable Factory identifier. */
+const factoryIdSchema = idSchema("fac");
+/** Validates a stable repository identifier. */
+const repositoryIdSchema = idSchema("repo");
+/** Validates a stable inbound Signal identifier. */
+const signalIdSchema = idSchema("sig");
+/** Validates a stable Task identifier. */
+const taskIdSchema = idSchema("task");
+/** Validates a stable Change identifier. */
+const changeIdSchema = idSchema("chg");
+/** Validates a stable immutable Receipt identifier. */
+const receiptIdSchema = idSchema("rcpt");
+/** Validates a stable communication outbox identifier. */
+const outboxIdSchema = idSchema("out");
+/** Validates a stable immutable answer-event identifier. */
+const answerIdSchema = idSchema("ans");
+/** Validates a nonempty repository scope expressed as repository identifiers. */
+const repositoryIdsSchema = z.tuple([repositoryIdSchema], repositoryIdSchema).readonly();
+/** Constructs a validated nonempty repository scope from typed identifiers. */
+function repositoryScope(first, ...rest) {
+	return repositoryIdsSchema.parse([first, ...rest]);
+}
+//#endregion
+export { answerIdSchema, changeIdSchema, factoryIdSchema, outboxIdSchema, receiptIdSchema, repositoryIdSchema, repositoryIdsSchema, repositoryScope, signalIdSchema, taskIdSchema };
+
+//# sourceMappingURL=id.mjs.map

package/dist/schema/id.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"id.mjs","names":[],"sources":["../../src/schema/id.ts"],"sourcesContent":["import { z } from \"zod\";\n\nfunction idSchema<const Prefix extends string>(prefix: Prefix) {\n  const pattern = new RegExp(`^${prefix}_[a-z0-9]{6,64}$`);\n  return z\n    .string()\n    .regex(\n      pattern,\n      `Expected ${prefix}_ followed by 6 to 64 lowercase letters or digits`,\n    ) as z.ZodType<`${Prefix}_${string}`, string>;\n}\n\n/** Validates a stable Factory identifier. */\nexport const factoryIdSchema = idSchema(\"fac\");\n/** Validates a stable repository identifier. */\nexport const repositoryIdSchema = idSchema(\"repo\");\n/** Validates a stable inbound Signal identifier. */\nexport const signalIdSchema = idSchema(\"sig\");\n/** Validates a stable Task identifier. */\nexport const taskIdSchema = idSchema(\"task\");\n/** Validates a stable Change identifier. */\nexport const changeIdSchema = idSchema(\"chg\");\n/** Validates a stable immutable Receipt identifier. */\nexport const receiptIdSchema = idSchema(\"rcpt\");\n/** Validates a stable communication outbox identifier. */\nexport const outboxIdSchema = idSchema(\"out\");\n/** Validates a stable immutable answer-event identifier. */\nexport const answerIdSchema = idSchema(\"ans\");\n\n/** Validates a nonempty repository scope expressed as repository identifiers. */\nexport const repositoryIdsSchema = z.tuple([repositoryIdSchema], repositoryIdSchema).readonly();\n\n/** Constructs a validated nonempty repository scope from typed identifiers. */\nexport function repositoryScope(\n  first: RepositoryId,\n  ...rest: readonly RepositoryId[]\n): RepositoryIds {\n  return repositoryIdsSchema.parse([first, ...rest]);\n}\n\n/** Stable identifier for one configured Factory. */\nexport type FactoryId = z.infer<typeof factoryIdSchema>;\n/** Stable identifier for one configured repository. */\nexport type RepositoryId = z.infer<typeof repositoryIdSchema>;\n/** Nonempty ordered repository scope attached to one Task or event. */\nexport type RepositoryIds = z.infer<typeof repositoryIdsSchema>;\n/** Stable identifier for one normalized inbound Signal. */\nexport type SignalId = z.infer<typeof signalIdSchema>;\n/** Stable identifier for one durable unit of workflow work. */\nexport type TaskId = z.infer<typeof taskIdSchema>;\n/** Stable identifier for one human-visible pull-request Change. */\nexport type ChangeId = z.infer<typeof changeIdSchema>;\n/** Stable identifier for one immutable audit Receipt. */\nexport type ReceiptId = z.infer<typeof receiptIdSchema>;\n/** Stable identifier for one communication outbox event. */\nexport type OutboxId = z.infer<typeof outboxIdSchema>;\n/** Stable identifier for one immutable authenticated answer event. */\nexport type AnswerId = z.infer<typeof answerIdSchema>;\n"],"mappings":";;AAEA,SAAS,SAAsC,QAAgB;CAC7D,MAAM,UAAU,IAAI,OAAO,IAAI,OAAO,iBAAiB;CACvD,OAAO,EACJ,OAAO,CAAC,CACR,MACC,SACA,YAAY,OAAO,kDACrB;AACJ;;AAGA,MAAa,kBAAkB,SAAS,KAAK;;AAE7C,MAAa,qBAAqB,SAAS,MAAM;;AAEjD,MAAa,iBAAiB,SAAS,KAAK;;AAE5C,MAAa,eAAe,SAAS,MAAM;;AAE3C,MAAa,iBAAiB,SAAS,KAAK;;AAE5C,MAAa,kBAAkB,SAAS,MAAM;;AAE9C,MAAa,iBAAiB,SAAS,KAAK;;AAE5C,MAAa,iBAAiB,SAAS,KAAK;;AAG5C,MAAa,sBAAsB,EAAE,MAAM,CAAC,kBAAkB,GAAG,kBAAkB,CAAC,CAAC,SAAS;;AAG9F,SAAgB,gBACd,OACA,GAAG,MACY;CACf,OAAO,oBAAoB,MAAM,CAAC,OAAO,GAAG,IAAI,CAAC;AACnD"}