@cat-factory/contracts 0.339.0 → 0.341.0

package/dist/bootstrap.d.ts

@@ -33,9 +33,57 @@ export declare const updateReferenceArchitectureSchema: v.ObjectSchema<{
     readonly defaultInstructions: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MaxLengthAction<string, 8000, undefined>]>, undefined>;
 }, undefined>;
 export type UpdateReferenceArchitectureInput = v.InferOutput<typeof updateReferenceArchitectureSchema>;
-/** Lifecycle of a single "bootstrap repo" run. */
-export declare const bootstrapStatusSchema: v.PicklistSchema<["pending", "running", "succeeded", "failed"], undefined>;
+/**
+ * Lifecycle of a single "bootstrap repo" run.
+ *
+ * `awaiting_review` is the monorepo flow's park: the run has surveyed the monorepo and the
+ * reference template and is holding on a human's adoption decisions. It is NOT terminal and it
+ * is not `running` either: nothing is executing, so a sweeper must not treat it as a dropped
+ * run, and a caller polling for completion must not treat it as one. It waits indefinitely by
+ * design (see `awaiting_review` in `docs/initiatives/monorepo-service-bootstrap.md`).
+ */
+export declare const bootstrapStatusSchema: v.PicklistSchema<["pending", "running", "awaiting_review", "succeeded", "failed"], undefined>;
 export type BootstrapStatus = v.InferOutput<typeof bootstrapStatusSchema>;
+/**
+ * Which half of a monorepo bootstrap a run is in. Null for a plain new-repo bootstrap, which
+ * is one phase and has no adoption decision to make.
+ *
+ *  - `survey`: read both sides, produce the adoption plan, park for review.
+ *  - `apply`:  write the service into the monorepo under the settled plan and open a PR.
+ */
+export declare const bootstrapPhaseSchema: v.PicklistSchema<["survey", "apply"], undefined>;
+export type BootstrapPhase = v.InferOutput<typeof bootstrapPhaseSchema>;
+/**
+ * Bootstrap INTO an existing monorepo instead of into a new repository of its own.
+ *
+ * The target is a repository the workspace already projects (so it is already reachable, and
+ * its `isMonorepo` flag is already the board's) plus the subdirectory the new service will
+ * live in. There is no repo creation and no force-push: the run opens a pull request against
+ * the monorepo's default branch, which is the only shape that is safe against a repository
+ * holding other people's services.
+ */
+export declare const monorepoBootstrapTargetSchema: v.ObjectSchema<{
+    /** The monorepo's numeric VCS id, as the workspace's repo projection lists it. */
+    readonly repoGithubId: v.NumberSchema<undefined>;
+    /**
+     * The new service's subdirectory, relative to the repo root (e.g. `services/billing`).
+     * Must not already exist: a bootstrap writes a service, it never merges into one.
+     */
+    readonly directory: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 400, undefined>]>;
+}, undefined>;
+export type MonorepoBootstrapTarget = v.InferOutput<typeof monorepoBootstrapTargetSchema>;
+/** The resolved monorepo target as a run reports it (the input plus what it resolved to). */
+export declare const monorepoBootstrapRefSchema: v.ObjectSchema<{
+    readonly repoGithubId: v.NumberSchema<undefined>;
+    readonly directory: v.StringSchema<undefined>;
+    /** Owner of the monorepo, resolved from the projection at start. */
+    readonly repoOwner: v.StringSchema<undefined>;
+    /** Name of the monorepo, resolved from the projection at start. */
+    readonly repoName: v.StringSchema<undefined>;
+    /** The branch the run pushes its work to; null until the apply phase dispatches. */
+    readonly branch: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+}, undefined>;
+export type MonorepoBootstrapRef = v.InferOutput<typeof monorepoBootstrapRefSchema>;
 /**
  * How a bootstrap run faulted, so the board can classify the failure (and decide
  * whether a retry is likely to help):
@@ -91,7 +139,7 @@ export declare const bootstrapJobSchema: v.ObjectSchema<{
     readonly repoUrl: v.NullableSchema<v.StringSchema<undefined>, undefined>;
     /** Effective bootstrapper instructions (defaults + per-run), for transparency. */
     readonly instructions: v.StringSchema<undefined>;
-    readonly status: v.PicklistSchema<["pending", "running", "succeeded", "failed"], undefined>;
+    readonly status: v.PicklistSchema<["pending", "running", "awaiting_review", "succeeded", "failed"], undefined>;
     /**
      * The board service frame this run materialises. Created up front (in
      * `running` state) so the bootstrap shows on the board immediately as a
@@ -135,6 +183,67 @@ export declare const bootstrapJobSchema: v.ObjectSchema<{
         }, undefined>, undefined>;
         readonly stepIndex: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
     }, undefined>, undefined>;
+    /**
+     * The monorepo this run is bootstrapping a service INTO, or null for a run that creates a
+     * repository of its own. Its presence is what puts the run on the two-phase, human-reviewed
+     * path; every other field below is null on a new-repo run.
+     */
+    readonly monorepo: v.NullableSchema<v.ObjectSchema<{
+        readonly repoGithubId: v.NumberSchema<undefined>;
+        readonly directory: v.StringSchema<undefined>;
+        /** Owner of the monorepo, resolved from the projection at start. */
+        readonly repoOwner: v.StringSchema<undefined>;
+        /** Name of the monorepo, resolved from the projection at start. */
+        readonly repoName: v.StringSchema<undefined>;
+        /** The branch the run pushes its work to; null until the apply phase dispatches. */
+        readonly branch: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    }, undefined>, undefined>;
+    /** Which half of the monorepo flow the run is in; null on a new-repo run. */
+    readonly phase: v.NullableSchema<v.PicklistSchema<["survey", "apply"], undefined>, undefined>;
+    /** The suggestion the human is reviewing (or the stated reason there is none). */
+    readonly adoptionPlan: v.NullableSchema<v.ObjectSchema<{
+        readonly status: v.PicklistSchema<["ready", "unavailable"], undefined>;
+        readonly unavailableReason: v.NullableSchema<v.PicklistSchema<["model_unavailable", "repo_unreadable", "budget_exhausted", "analysis_unusable"], undefined>, undefined>;
+        readonly unavailableDetail: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MaxLengthAction<string, 600, undefined>]>, undefined>;
+        readonly survey: v.ObjectSchema<{
+            readonly monorepoPaths: v.ArraySchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 400, undefined>]>, undefined>;
+            readonly templatePaths: v.ArraySchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 400, undefined>]>, undefined>;
+            readonly unreadablePaths: v.ArraySchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 400, undefined>]>, undefined>;
+            readonly siblingService: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 400, undefined>]>, undefined>;
+        }, undefined>;
+        readonly decisions: v.ArraySchema<v.ObjectSchema<{
+            readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 80, undefined>]>;
+            readonly area: v.PicklistSchema<["build-tooling", "dependencies", "lint-format", "typecheck", "testing", "ci", "containerization", "runtime-config", "observability", "source-layout", "docs", "other"], undefined>;
+            readonly title: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 200, undefined>]>;
+            readonly monorepoPractice: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MaxLengthAction<string, 600, undefined>]>, undefined>;
+            readonly templatePractice: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MaxLengthAction<string, 600, undefined>]>, undefined>;
+            readonly recommended: v.PicklistSchema<["monorepo", "template", "both", "neither"], undefined>;
+            readonly rationale: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MaxLengthAction<string, 600, undefined>]>;
+            readonly evidence: v.ArraySchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 400, undefined>]>, undefined>;
+        }, undefined>, undefined>;
+        readonly droppedUnevidenced: v.SchemaWithPipe<readonly [v.ArraySchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MaxLengthAction<string, 200, undefined>]>, undefined>, v.MaxLengthAction<string[], number, undefined>]>;
+        readonly model: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly generatedAt: v.NumberSchema<undefined>;
+    }, undefined>, undefined>;
+    /** What the human settled; null until the review is submitted. */
+    readonly adoptionReview: v.NullableSchema<v.ObjectSchema<{
+        readonly decisions: v.ArraySchema<v.ObjectSchema<{
+            readonly id: v.StringSchema<undefined>;
+            readonly area: v.PicklistSchema<["build-tooling", "dependencies", "lint-format", "typecheck", "testing", "ci", "containerization", "runtime-config", "observability", "source-layout", "docs", "other"], undefined>;
+            readonly title: v.StringSchema<undefined>;
+            readonly choice: v.PicklistSchema<["monorepo", "template", "both", "neither"], undefined>;
+            readonly overrodeRecommendation: v.BooleanSchema<undefined>;
+            readonly note: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        }, undefined>, undefined>;
+        readonly notes: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly reviewedByUserId: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly reviewedAt: v.NumberSchema<undefined>;
+    }, undefined>, undefined>;
+    /**
+     * The pull request the apply phase opened against the monorepo; null until it does.
+     * A monorepo bootstrap's deliverable IS a PR: nothing is merged for the reviewer.
+     */
+    readonly prUrl: v.NullableSchema<v.StringSchema<undefined>, undefined>;
     readonly createdAt: v.NumberSchema<undefined>;
     readonly updatedAt: v.NumberSchema<undefined>;
 }, undefined>;
@@ -150,8 +259,26 @@ export type BootstrapJob = v.InferOutput<typeof bootstrapJobSchema>;
 export declare const bootstrapRepoSchema: v.SchemaWithPipe<readonly [v.ObjectSchema<{
     /** Reference architecture to clone from; omit to bootstrap from a freeform prompt. */
     readonly referenceArchitectureId: v.OptionalSchema<v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>, undefined>, undefined>;
-    /** Name for the new repository. */
+    /**
+     * Name of the thing being created: the new REPOSITORY on a plain run, and the new SERVICE
+     * (the board frame's title, and the default leaf of its directory) on a monorepo run.
+     */
     readonly repoName: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.RegexAction<string, "Only letters, digits, '.', '_' and '-' are allowed">, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 100, undefined>]>;
+    /**
+     * Bootstrap into an existing monorepo at this subdirectory instead of creating a new
+     * repository. Present ⇒ the run is two-phase: it surveys the monorepo and the reference
+     * template, parks on `awaiting_review` with an adoption plan, and only writes the service
+     * once a human has settled it.
+     */
+    readonly monorepo: v.OptionalSchema<v.ObjectSchema<{
+        /** The monorepo's numeric VCS id, as the workspace's repo projection lists it. */
+        readonly repoGithubId: v.NumberSchema<undefined>;
+        /**
+         * The new service's subdirectory, relative to the repo root (e.g. `services/billing`).
+         * Must not already exist: a bootstrap writes a service, it never merges into one.
+         */
+        readonly directory: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 400, undefined>]>;
+    }, undefined>, undefined>;
     /**
      * The repository role for the bootstrapped frame (backend service / frontend / library /
      * document repository). Omitted → `service`, so existing callers are unchanged.
@@ -169,6 +296,10 @@ export declare const bootstrapRepoSchema: v.SchemaWithPipe<readonly [v.ObjectSch
 }, undefined>, v.CheckAction<{
     referenceArchitectureId?: string | null | undefined;
     repoName: string;
+    monorepo?: {
+        repoGithubId: number;
+        directory: string;
+    } | undefined;
     type?: "document" | "frontend" | "library" | "service" | undefined;
     description: string;
     private: boolean;

package/dist/bootstrap.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bootstrap.d.ts","sourceRoot":"","sources":["../src/bootstrap.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAmC5B,iEAAiE;AACjE,eAAO,MAAM,2BAA2B;;;;;IAKtC,mDAAmD;;IAEnD,8DAA8D;;IAE9D,gFAAgF;;;;aAIhF,CAAA;AACF,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,2BAA2B,CAAC,CAAA;AAErF,6CAA6C;AAC7C,eAAO,MAAM,iCAAiC;;;;;;aAM5C,CAAA;AACF,MAAM,MAAM,gCAAgC,GAAG,CAAC,CAAC,WAAW,CAC1D,OAAO,iCAAiC,CACzC,CAAA;AAED,kFAAkF;AAClF,eAAO,MAAM,iCAAiC;;;;;;aAM5C,CAAA;AACF,MAAM,MAAM,gCAAgC,GAAG,CAAC,CAAC,WAAW,CAC1D,OAAO,iCAAiC,CACzC,CAAA;AAID,kDAAkD;AAClD,eAAO,MAAM,qBAAqB,4EAA4D,CAAA;AAC9F,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,qBAAqB,CAAC,CAAA;AAEzE;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,0BAA0B,+GAQrC,CAAA;AACF,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,0BAA0B,CAAC,CAAA;AAEnF;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;aAAqB,CAAA;AACxD,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,sBAAsB,CAAC,CAAA;AAE3E,kDAAkD;AAClD,eAAO,MAAM,kBAAkB;;;IAG7B,8FAA8F;;IAE9F,4HAA4H;;IAE5H,gDAAgD;;IAEhD,wFAAwF;;IAExF,2EAA2E;;IAE3E,kFAAkF;;;IAGlF;;;;;;OAMG;;IAEH;;;;OAIG;;;;;;;;;;IAEH,qFAAqF;;IAErF,gFAAgF;;;;;;;;;;;;;;;;;;;;;aAIhF,CAAA;AACF,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,kBAAkB,CAAC,CAAA;AAEnE;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB;IAE5B,sFAAsF;;IAEtF,mCAAmC;;IAEnC;;;OAGG;;IAEH,iDAAiD;;IAEjD,mEAAmE;;IAEnE;;;OAGG;;;;;;;;;oFAON,CAAA;AACD,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,mBAAmB,CAAC,CAAA"}
+{"version":3,"file":"bootstrap.d.ts","sourceRoot":"","sources":["../src/bootstrap.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAoC5B,iEAAiE;AACjE,eAAO,MAAM,2BAA2B;;;;;IAKtC,mDAAmD;;IAEnD,8DAA8D;;IAE9D,gFAAgF;;;;aAIhF,CAAA;AACF,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,2BAA2B,CAAC,CAAA;AAErF,6CAA6C;AAC7C,eAAO,MAAM,iCAAiC;;;;;;aAM5C,CAAA;AACF,MAAM,MAAM,gCAAgC,GAAG,CAAC,CAAC,WAAW,CAC1D,OAAO,iCAAiC,CACzC,CAAA;AAED,kFAAkF;AAClF,eAAO,MAAM,iCAAiC;;;;;;aAM5C,CAAA;AACF,MAAM,MAAM,gCAAgC,GAAG,CAAC,CAAC,WAAW,CAC1D,OAAO,iCAAiC,CACzC,CAAA;AAID;;;;;;;;GAQG;AACH,eAAO,MAAM,qBAAqB,+FAMhC,CAAA;AACF,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,qBAAqB,CAAC,CAAA;AAEzE;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,kDAAkC,CAAA;AACnE,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,oBAAoB,CAAC,CAAA;AAEvE;;;;;;;;GAQG;AACH,eAAO,MAAM,6BAA6B;IACxC,kFAAkF;;IAElF;;;OAGG;;aAEH,CAAA;AACF,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,6BAA6B,CAAC,CAAA;AAEzF,6FAA6F;AAC7F,eAAO,MAAM,0BAA0B;;;IAGrC,oEAAoE;;IAEpE,mEAAmE;;IAEnE,oFAAoF;;aAEpF,CAAA;AACF,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,0BAA0B,CAAC,CAAA;AAEnF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,0BAA0B,+GAQrC,CAAA;AACF,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,0BAA0B,CAAC,CAAA;AAEnF;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;aAAqB,CAAA;AACxD,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,sBAAsB,CAAC,CAAA;AAE3E,kDAAkD;AAClD,eAAO,MAAM,kBAAkB;;;IAG7B,8FAA8F;;IAE9F,4HAA4H;;IAE5H,gDAAgD;;IAEhD,wFAAwF;;IAExF,2EAA2E;;IAE3E,kFAAkF;;;IAGlF;;;;;;OAMG;;IAEH;;;;OAIG;;;;;;;;;;IAEH,qFAAqF;;IAErF,gFAAgF;;;;;;;;;;;;;;;;;;;IAEhF;;;;OAIG;;;;QAhFH,oEAAoE;;QAEpE,mEAAmE;;QAEnE,oFAAoF;;;IA8EpF,6EAA6E;;IAE7E,kFAAkF;;;;;;;;;;;;;;;;;;;;;;;;;IAElF,kEAAkE;;;;;;;;;;;;;;IAElE;;;OAGG;;;;aAIH,CAAA;AACF,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,kBAAkB,CAAC,CAAA;AAEnE;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB;IAE5B,sFAAsF;;IAEtF;;;OAGG;;IAEH;;;;;OAKG;;QAtIL,kFAAkF;;QAElF;;;WAGG;;;IAmID;;;OAGG;;IAEH,iDAAiD;;IAEjD,mEAAmE;;IAEnE;;;OAGG;;;;;;;;;;;;;oFAON,CAAA;AACD,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,mBAAmB,CAAC,CAAA"}

package/dist/bootstrap.js

@@ -1,5 +1,6 @@
 import * as v from 'valibot';
 import { agentFailureSchema, stepSubtasksSchema } from './execution.js';
+import { adoptionPlanSchema, resolvedAdoptionSchema } from './monorepo-adoption.js';
 import { frameRepoTypeSchema } from './primitives.js';
 // ---------------------------------------------------------------------------
 // Repo-bootstrap wire contracts. A "reference architecture" is a named base repo
@@ -55,8 +56,59 @@ export const updateReferenceArchitectureSchema = v.object({
     defaultInstructions: v.optional(instructionsField),
 });
 // ---- Bootstrap jobs --------------------------------------------------------
-/** Lifecycle of a single "bootstrap repo" run. */
-export const bootstrapStatusSchema = v.picklist(['pending', 'running', 'succeeded', 'failed']);
+/**
+ * Lifecycle of a single "bootstrap repo" run.
+ *
+ * `awaiting_review` is the monorepo flow's park: the run has surveyed the monorepo and the
+ * reference template and is holding on a human's adoption decisions. It is NOT terminal and it
+ * is not `running` either: nothing is executing, so a sweeper must not treat it as a dropped
+ * run, and a caller polling for completion must not treat it as one. It waits indefinitely by
+ * design (see `awaiting_review` in `docs/initiatives/monorepo-service-bootstrap.md`).
+ */
+export const bootstrapStatusSchema = v.picklist([
+    'pending',
+    'running',
+    'awaiting_review',
+    'succeeded',
+    'failed',
+]);
+/**
+ * Which half of a monorepo bootstrap a run is in. Null for a plain new-repo bootstrap, which
+ * is one phase and has no adoption decision to make.
+ *
+ *  - `survey`: read both sides, produce the adoption plan, park for review.
+ *  - `apply`:  write the service into the monorepo under the settled plan and open a PR.
+ */
+export const bootstrapPhaseSchema = v.picklist(['survey', 'apply']);
+/**
+ * Bootstrap INTO an existing monorepo instead of into a new repository of its own.
+ *
+ * The target is a repository the workspace already projects (so it is already reachable, and
+ * its `isMonorepo` flag is already the board's) plus the subdirectory the new service will
+ * live in. There is no repo creation and no force-push: the run opens a pull request against
+ * the monorepo's default branch, which is the only shape that is safe against a repository
+ * holding other people's services.
+ */
+export const monorepoBootstrapTargetSchema = v.object({
+    /** The monorepo's numeric VCS id, as the workspace's repo projection lists it. */
+    repoGithubId: v.number(),
+    /**
+     * The new service's subdirectory, relative to the repo root (e.g. `services/billing`).
+     * Must not already exist: a bootstrap writes a service, it never merges into one.
+     */
+    directory: v.pipe(v.string(), v.trim(), v.minLength(1), v.maxLength(400)),
+});
+/** The resolved monorepo target as a run reports it (the input plus what it resolved to). */
+export const monorepoBootstrapRefSchema = v.object({
+    repoGithubId: v.number(),
+    directory: v.string(),
+    /** Owner of the monorepo, resolved from the projection at start. */
+    repoOwner: v.string(),
+    /** Name of the monorepo, resolved from the projection at start. */
+    repoName: v.string(),
+    /** The branch the run pushes its work to; null until the apply phase dispatches. */
+    branch: v.nullable(v.string()),
+});
 /**
  * How a bootstrap run faulted, so the board can classify the failure (and decide
  * whether a retry is likely to help):
@@ -120,6 +172,23 @@ export const bootstrapJobSchema = v.object({
     error: v.nullable(v.string()),
     /** Structured failure diagnostics when `status` is `failed`; null otherwise. */
     failure: v.nullable(bootstrapFailureSchema),
+    /**
+     * The monorepo this run is bootstrapping a service INTO, or null for a run that creates a
+     * repository of its own. Its presence is what puts the run on the two-phase, human-reviewed
+     * path; every other field below is null on a new-repo run.
+     */
+    monorepo: v.nullable(monorepoBootstrapRefSchema),
+    /** Which half of the monorepo flow the run is in; null on a new-repo run. */
+    phase: v.nullable(bootstrapPhaseSchema),
+    /** The suggestion the human is reviewing (or the stated reason there is none). */
+    adoptionPlan: v.nullable(adoptionPlanSchema),
+    /** What the human settled; null until the review is submitted. */
+    adoptionReview: v.nullable(resolvedAdoptionSchema),
+    /**
+     * The pull request the apply phase opened against the monorepo; null until it does.
+     * A monorepo bootstrap's deliverable IS a PR: nothing is merged for the reviewer.
+     */
+    prUrl: v.nullable(v.string()),
     createdAt: v.number(),
     updatedAt: v.number(),
 });
@@ -134,8 +203,18 @@ export const bootstrapJobSchema = v.object({
 export const bootstrapRepoSchema = v.pipe(v.object({
     /** Reference architecture to clone from; omit to bootstrap from a freeform prompt. */
     referenceArchitectureId: v.optional(v.nullable(v.pipe(v.string(), v.minLength(1)))),
-    /** Name for the new repository. */
+    /**
+     * Name of the thing being created: the new REPOSITORY on a plain run, and the new SERVICE
+     * (the board frame's title, and the default leaf of its directory) on a monorepo run.
+     */
     repoName: slugField,
+    /**
+     * Bootstrap into an existing monorepo at this subdirectory instead of creating a new
+     * repository. Present ⇒ the run is two-phase: it surveys the monorepo and the reference
+     * template, parks on `awaiting_review` with an adoption plan, and only writes the service
+     * once a human has settled it.
+     */
+    monorepo: v.optional(monorepoBootstrapTargetSchema),
     /**
      * The repository role for the bootstrapped frame (backend service / frontend / library /
      * document repository). Omitted → `service`, so existing callers are unchanged.

package/dist/bootstrap.js.map

@@ -1 +1 @@
-{"version":3,"file":"bootstrap.js","sourceRoot":"","sources":["../src/bootstrap.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"bootstrap.js","sourceRoot":"","sources":["../src/bootstrap.ts"],"names":[],"mappings":"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"}

package/dist/environment-reachability.d.ts

@@ -1,6 +1,7 @@
 import * as v from 'valibot';
 /**
- * One address a provider states will carry traffic for its environment's URL host.
+ * One place a provider states traffic for its environment's URL host goes: an ADDRESS the platform
+ * dials as written, or a NAME it resolves when it dials.
  *
  * The motivating shape is an org running per-PR preview environments whose per-environment DNS
  * record lives in an internal view while the load balancers fronting it are ordinary names and
@@ -8,16 +9,74 @@ import * as v from 'valibot';
  * it. The only missing thing is a name-to-address mapping, which is exactly what a hosts-file
  * entry (or a Kubernetes `hostAliases` entry) is.
  *
+ * **Exactly one of {@link EnvironmentRouteCandidate.address} and
+ * {@link EnvironmentRouteCandidate.host} is set, and which one is the PROVIDER'S statement**, never
+ * something the platform reads off the spelling. Guessing would rest the security rule on a parse:
+ * `isBridgeableAddress` refuses a non-canonical literal precisely so `2130706433` cannot become
+ * loopback, and a resolver handed that same string answers loopback happily. A candidate stating
+ * neither (or both, which is two claims with no way to tell which was meant) therefore names no
+ * target at all and is RECORDED as one, on the same rule as an address no bridge may name.
+ *
  * `label` is for the human reading a diagnostic ("internal ALB", "public ALB"), never for
  * matching: the platform picks by PROBING, never by name.
  */
-export declare const environmentAddressSchema: v.ObjectSchema<{
-    /** An IP literal. Never a name: a name would just be the lookup that already failed. */
-    readonly address: v.StringSchema<undefined>;
-    /** What this address IS, for the diagnostic. Never load-bearing. */
+export declare const environmentRouteCandidateSchema: v.ObjectSchema<{
+    /** An IP literal, dialled as written. Never a name: see {@link EnvironmentRouteCandidate.host}. */
+    readonly address: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    /**
+     * A NAME the platform RESOLVES at proof time, expanding it in place into the addresses it
+     * answers with.
+     *
+     * For the provider whose stable identity IS a name, which is the ordinary shape of a managed
+     * load balancer: an ALB's addresses change as it scales or gains a zone, and its DNS name is
+     * what the vendor documents a client should use. A provider stating the resolved literals
+     * instead re-pins a snapshot of that set on every poll, and owes bounded resolution, stable
+     * ordering and partial-failure handling of its own.
+     *
+     * Deliberately NOT the URL's own host, which is the lookup that already failed. This is a
+     * DIFFERENT name in a different zone, and its whole point is resolving when that one does not.
+     * Nothing downstream ever sees it: every address it resolves to is graded by
+     * `isBridgeableAddress` exactly as a stated address is, and the proof publishes the ADDRESS that
+     * carried with the name it came from beside it, so a bridge is still built from a literal the
+     * platform itself proved.
+     */
+    readonly host: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    /** What this candidate IS, for the diagnostic. Never load-bearing. */
     readonly label: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
 }, undefined>;
-export type EnvironmentAddress = v.InferOutput<typeof environmentAddressSchema>;
+export type EnvironmentRouteCandidate = v.InferOutput<typeof environmentRouteCandidateSchema>;
+/**
+ * What one candidate actually names, or that it names nothing usable.
+ *
+ * A discriminated result rather than two optional reads at every site, because the three cases
+ * want three different reactions and the third is the one a nullable read renders as absent. Read
+ * through this rather than off the fields, so "which kind is this" is answered once.
+ */
+export type StatedRouteTarget = {
+    kind: 'address';
+    address: string;
+} | {
+    kind: 'host';
+    host: string;
+} | {
+    kind: 'unusable';
+};
+/**
+ * Read a stated candidate as the one thing it names.
+ *
+ * A host is lower-cased because DNS is case-insensitive and this value is both a map key and a
+ * comparison target: two spellings of one balancer name must not resolve twice, nor invalidate a
+ * proof by failing to match themselves.
+ */
+export declare function statedRouteTarget(candidate: EnvironmentRouteCandidate): StatedRouteTarget;
+/**
+ * One candidate as a reader sees it: its value, its label, and a NAME marked as one.
+ *
+ * ONE renderer, because three surfaces print this list (the environment investigation's route
+ * section, its timeline entry and the diagnostics bundle) and a name printed into a sentence about
+ * "the addresses the provider stated" reads as an address somebody typed wrong.
+ */
+export declare function describeRouteCandidate(candidate: EnvironmentRouteCandidate): string;
 /**
  * Why a `ready` environment could not be reached, at the layer the platform can observe.
  *
@@ -29,20 +88,33 @@ export type EnvironmentAddress = v.InferOutput<typeof environmentAddressSchema>;
  *
  *  - `no_candidate`       the environment carries no URL, or one with no host to probe. There
  *                         was nothing to try, which is not the same as trying and failing.
- *  - `name_unresolved`    the URL's host resolved nowhere, and no stated address carried either.
+ *  - `name_unresolved`    a name resolved nowhere: the URL's own host, with no stated candidate
+ *                         carrying either, or one stated NAME whose own lookup answered nothing.
  *  - `no_route`           something resolved and the connect never completed (timeout,
  *                         host/network unreachable). The expensive failure: a lookup that
  *                         worked followed by a connect that hangs.
  *  - `connection_refused` the route carries and nothing is listening on the port.
- *  - `address_refused`    the provider stated an address the platform will not dial: loopback,
- *                         link-local/vendor metadata, or a non-canonical literal. Recorded as an
- *                         attempt rather than dropped, because a refused input is an omission the
- *                         operator has to be able to see.
+ *  - `address_refused`    the provider stated a target the platform will not dial: a loopback,
+ *                         link-local/vendor-metadata or non-canonical address (whether stated or
+ *                         resolved from a stated name), or a candidate naming no single target at
+ *                         all. Recorded as an attempt rather than dropped, because a refused input
+ *                         is an omission the operator has to be able to see.
+ *  - `resolver_unavailable` the provider stated a NAME and nothing in this deployment can turn one
+ *                         into an address. An admission about the PLATFORM, never a verdict about
+ *                         the environment, so it leaves the route unruled-out exactly as
+ *                         `probe_failed` does.
+ *  - `not_attempted`      the platform stopped short of the list its provider stated: it looks up
+ *                         a bounded number of names and dials a bounded number of addresses, so a
+ *                         longer list is a PREFIX. Recorded ONCE, naming how many were passed
+ *                         over, because a reader who assumes a prefix concludes the tail was
+ *                         never stated. Another admission about the PLATFORM: a candidate nothing
+ *                         looked at cannot be part of a verdict that nothing reaches the
+ *                         environment.
  *  - `probe_failed`       the probe itself errored in a way it could not classify. Kept apart
  *                         from the three above so "we could not tell" never renders as a
  *                         verdict about the environment.
  */
-export declare const environmentUnreachableReasonSchema: v.PicklistSchema<["no_candidate", "name_unresolved", "no_route", "connection_refused", "address_refused", "probe_failed"], undefined>;
+export declare const environmentUnreachableReasonSchema: v.PicklistSchema<["no_candidate", "name_unresolved", "no_route", "connection_refused", "address_refused", "resolver_unavailable", "not_attempted", "probe_failed"], undefined>;
 export type EnvironmentUnreachableReason = v.InferOutput<typeof environmentUnreachableReasonSchema>;
 /** One target the proof tried, in the order it was tried, and what came back. */
 export declare const environmentRouteAttemptSchema: v.ObjectSchema<{
@@ -93,6 +165,21 @@ export declare const environmentRouteProofSchema: v.ObjectSchema<{
      * then points further from the cause than no bridge at all did.
      */
     readonly via: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    /**
+     * The stated NAME {@link via} was resolved from, when the candidate that carried was a host
+     * rather than an address. Absent when `via` is itself a stated address, when the URL's own name
+     * carried, and when nothing carried.
+     *
+     * Recorded because the fold decides a `reached` proof's survival on whether the target it names
+     * is still on offer, and for a resolved name that target is the NAME. The address is a snapshot
+     * of a set that rotates (a balancer scaling or gaining a zone changes it, and tells the platform
+     * nothing about whether the proved route still carries), so matching `via` against the candidate
+     * list would drop a good proof on every such event and pay a fresh probe sequence for it.
+     *
+     * Optional so a proof written before this existed still parses, where its absence reads as the
+     * address case, which is what it was.
+     */
+    readonly viaHost: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
     /**
      * The {@link EnvironmentUnreachableReason} when `state` is `not_reached` or `inconclusive`,
      * else null. An open string on the wire so a stored proof written by an older build never fails
@@ -130,11 +217,32 @@ export type EnvironmentRouteProof = v.InferOutput<typeof environmentRouteProofSc
  * offered as well as which were reached, and a re-probe on a later poll re-reads the same claim.
  */
 export declare const environmentReachabilitySchema: v.ObjectSchema<{
-    /** Addresses the provider states carry traffic for the URL's host, in ITS preference order. */
+    /**
+     * The addresses and names the provider states carry traffic for the URL's host, in ITS
+     * preference order.
+     */
     readonly candidates: v.ArraySchema<v.ObjectSchema<{
-        /** An IP literal. Never a name: a name would just be the lookup that already failed. */
-        readonly address: v.StringSchema<undefined>;
-        /** What this address IS, for the diagnostic. Never load-bearing. */
+        /** An IP literal, dialled as written. Never a name: see {@link EnvironmentRouteCandidate.host}. */
+        readonly address: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        /**
+         * A NAME the platform RESOLVES at proof time, expanding it in place into the addresses it
+         * answers with.
+         *
+         * For the provider whose stable identity IS a name, which is the ordinary shape of a managed
+         * load balancer: an ALB's addresses change as it scales or gains a zone, and its DNS name is
+         * what the vendor documents a client should use. A provider stating the resolved literals
+         * instead re-pins a snapshot of that set on every poll, and owes bounded resolution, stable
+         * ordering and partial-failure handling of its own.
+         *
+         * Deliberately NOT the URL's own host, which is the lookup that already failed. This is a
+         * DIFFERENT name in a different zone, and its whole point is resolving when that one does not.
+         * Nothing downstream ever sees it: every address it resolves to is graded by
+         * `isBridgeableAddress` exactly as a stated address is, and the proof publishes the ADDRESS that
+         * carried with the name it came from beside it, so a bridge is still built from a literal the
+         * platform itself proved.
+         */
+        readonly host: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        /** What this candidate IS, for the diagnostic. Never load-bearing. */
         readonly label: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
     }, undefined>, undefined>;
     /** What proving found, or null when nothing has probed this environment yet. */
@@ -150,6 +258,21 @@ export declare const environmentReachabilitySchema: v.ObjectSchema<{
          * then points further from the cause than no bridge at all did.
          */
         readonly via: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        /**
+         * The stated NAME {@link via} was resolved from, when the candidate that carried was a host
+         * rather than an address. Absent when `via` is itself a stated address, when the URL's own name
+         * carried, and when nothing carried.
+         *
+         * Recorded because the fold decides a `reached` proof's survival on whether the target it names
+         * is still on offer, and for a resolved name that target is the NAME. The address is a snapshot
+         * of a set that rotates (a balancer scaling or gaining a zone changes it, and tells the platform
+         * nothing about whether the proved route still carries), so matching `via` against the candidate
+         * list would drop a good proof on every such event and pay a fresh probe sequence for it.
+         *
+         * Optional so a proof written before this existed still parses, where its absence reads as the
+         * address case, which is what it was.
+         */
+        readonly viaHost: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
         /**
          * The {@link EnvironmentUnreachableReason} when `state` is `not_reached` or `inconclusive`,
          * else null. An open string on the wire so a stored proof written by an older build never fails

package/dist/environment-reachability.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"environment-reachability.d.ts","sourceRoot":"","sources":["../src/environment-reachability.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAE5B;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,wBAAwB;IACnC,wFAAwF;;IAExF,oEAAoE;;aAEpE,CAAA;AACF,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,wBAAwB,CAAC,CAAA;AAE/E;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,kCAAkC,uIAO7C,CAAA;AACF,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,kCAAkC,CAAC,CAAA;AAEnG,iFAAiF;AACjF,eAAO,MAAM,6BAA6B;IACxC,iFAAiF;;IAEjF,mFAAmF;;IAEnF;;;;;;;;OAQG;;aAEH,CAAA;AACF,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,6BAA6B,CAAC,CAAA;AAEzF;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,2BAA2B;;IAEtC;;;;;;;;OAQG;;IAEH;;;;OAIG;;IAEH,yEAAyE;;QAtDzE,iFAAiF;;QAEjF,mFAAmF;;QAEnF;;;;;;;;WAQG;;;IA4CH,qCAAqC;;aAErC,CAAA;AACF,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,2BAA2B,CAAC,CAAA;AAErF;;;;;;;;GAQG;AACH,eAAO,MAAM,6BAA6B;IACxC,+FAA+F;;QAlH/F,wFAAwF;;QAExF,oEAAoE;;;IAkHpE,gFAAgF;;;QAnChF;;;;;;;;WAQG;;QAEH;;;;WAIG;;QAEH,yEAAyE;;YAtDzE,iFAAiF;;YAEjF,mFAAmF;;YAEnF;;;;;;;;eAQG;;;QA4CH,qCAAqC;;;IAmBrC;;;;;;;;;;;;;;OAcG;;aAEH,CAAA;AACF,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,6BAA6B,CAAC,CAAA;AAEzF;;;;;;;;GAQG;AACH,MAAM,WAAW,2BAA2B;IAC1C;;;;OAIG;IACH,KAAK,EAAE,OAAO,CAAC,qBAAqB,CAAC,OAAO,CAAC,EAAE,UAAU,CAAC,CAAA;IAC1D,uDAAuD;IACvD,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,wFAAwF;IACxF,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAC9B,YAAY,EAAE,uBAAuB,GAAG,IAAI,GAAG,SAAS,GACvD,2BAA2B,GAAG,SAAS,CAUzC;AAED,wFAAwF;AACxF,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,MAAM,CAAA;IACZ,2FAA2F;IAC3F,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IACnB,4DAA4D;IAC5D,MAAM,EAAE,MAAM,CAAA;CACf;AAKD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,4BAA4B,CAC1C,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC7B,sBAAsB,GAAG,IAAI,CAW/B"}
+{"version":3,"file":"environment-reachability.d.ts","sourceRoot":"","sources":["../src/environment-reachability.ts"],"names":[],"mappings":"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"}