@aglyn/plugins-ai 1.0.0-beta.229 → 1.0.0-beta.230

package/src/lib/jobs/ai-job-build-step.d.ts

@@ -0,0 +1,144 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { resolveOrgIdForHost } from '@aglyn/tenant-data-admin/server/organizations';
+import { type AiBuildOps, type AiBuildUnit } from '../model/ai-build-job';
+import type { AiJob, AiJobItemLedger, AiJobKind } from '../model/ai-jobs.types';
+import { type AiBuildOpsContext } from './ai-build-capabilities';
+import { aiJobAdmissionRefusal, type AiJobAdmission } from './ai-job-admission';
+import { readAiDraftNodes } from './ai-job-drafts';
+import { aiPluginDraftAdmissionRefusal, type AiPluginDraftWriterLookup } from './ai-job-plugin-drafts';
+import { type AiJobStepRunner } from './ai-job-text-step';
+import { aiPublishGuidedSite } from './ai-site-publish';
+import { aiJobStepRunnerFor } from './ai-jobs';
+/**
+ * The build step (AGL-3616): the generation step of a `build` job, run once
+ * the member confirmed the plan their request produced.
+ *
+ * Like the site scaffold it generalizes, it builds nothing itself and asks no
+ * model of its own. Each pass takes the next unit in dependency order and
+ * hands it to what builds that kind of thing — a page, layout, form,
+ * component, email design or template to this plugin's own step, under a job
+ * derived for the unit; another plugin's resource to that plugin's writer on
+ * the resource-draft seam, with the content the owner's capability derives
+ * from the item's arguments. One unit, one pass, one recorded spend.
+ *
+ * ── Settled item by item ────────────────────────────────────────────────
+ *
+ * Where a unit stands is read from the job's ITEM LEDGER, never from counting
+ * outputs: the machine writes each pass's row in the transaction that
+ * records its spend (`recordStep`). A unit that fails is a FAILED ROW, not a
+ * failed job: the pass reports it, the machine gives back that item's spend
+ * where the failure was ours, and the next pass builds the next unit. What
+ * depended on it is built without it, or skipped where it cannot stand
+ * without it (`aiBuildDegradation`). The machine ends the job when nothing is
+ * left: `done` when anything was delivered, `failed` — its planning given
+ * back too — when nothing was.
+ *
+ * ── Drafts, unless asked and confirmed ───────────────────────────────────
+ *
+ * Every unit writes the draft its own kind writes, which nothing publishes.
+ * Only a build whose request asked to publish AND whose member ticked the
+ * plan card's box puts its built pages live, once, on its last pass, through
+ * the guided start's publish.
+ */
+/** What a build answers with no confirmed plan to build. */
+export declare const AI_BUILD_NO_PLAN_COPY = "This build has no confirmed plan to build.";
+/** What a unit says when nothing on this site builds its operation any more. */
+export declare const aiBuildUnavailableCopy: (noun: string) => string;
+/** What a page that was reported built but holds none of its plan says. */
+export declare const AI_BUILD_PAGE_NOT_WRITTEN_COPY = "The page was not written from its plan.";
+/**
+ * The most passes a build's step may take: every unit at a page's worst — its
+ * sections and its listing — so a runner that never finishes is still
+ * bounded while the largest plan is not. Try again starts the count over.
+ */
+export declare const AI_BUILD_MAX_PASSES: number;
+/** The job kind a unit is built by, where an AI runner builds it. */
+export declare function aiBuildUnitJobKind(unit: AiBuildUnit, ops: AiBuildOps): AiJobKind | null;
+/** The id a unit's job, and so its draft, is named by. */
+export declare function aiBuildUnitJobId(job: Pick<AiJob, '$id'>, unit: AiBuildUnit): string;
+/**
+ * The job a unit is built under (generalizing `aiSiteUnitJob`): this job's
+ * org, site, creator and model; the kind that builds the unit; a plan
+ * narrowed to the unit, its `new:` references resolved to what was built and
+ * the failed ones left out; and a brief that says what the unit is, what it
+ * is built without, and which blocks its sections place.
+ */
+export declare function aiBuildUnitJob(job: AiJob, unit: AiBuildUnit, context: {
+    kind: AiJobKind;
+    units: readonly AiBuildUnit[];
+    ledger: readonly AiJobItemLedger[];
+    ops: AiBuildOps;
+    briefLines?: readonly string[];
+}): AiJob;
+export interface AiJobBuildStepDeps {
+    /** The runner registry; specs hand in fakes. */
+    runnerFor?: typeof aiJobStepRunnerFor;
+    /** The draft writer registry; specs hand in fakes. */
+    writerFor?: AiPluginDraftWriterLookup;
+    /** The operations this site may use; the registry and its gates otherwise. */
+    opsFor?: (context: AiBuildOpsContext) => Promise<AiBuildOps>;
+    /** A runner kind's own admission, asked before its item runs; the registry's otherwise. */
+    admissionFor?: typeof aiJobAdmissionRefusal;
+    /** Another plugin's admission for its writer; the seam's otherwise. */
+    pluginAdmission?: typeof aiPluginDraftAdmissionRefusal;
+    /** The draft reader a built page is checked through. */
+    readNodes?: typeof readAiDraftNodes;
+    /** The publish a build asked for and confirmed. */
+    publish?: typeof aiPublishGuidedSite;
+}
+/** Whether a build's workspace spends the Free taste. */
+export declare function aiBuildFreeTaste(org: object | null | undefined): boolean;
+export declare function createAiJobBuildStep(deps?: AiJobBuildStepDeps): AiJobStepRunner;
+export declare const runAiJobBuildStep: AiJobStepRunner;
+/**
+ * The least time a build's next pass needs: what the step that builds its
+ * next unit registers for the job derived for it; a page pass's when the
+ * next unit is another plugin's draft, which asks no model.
+ */
+export declare function aiBuildJobRunMinimumMs(job: AiJob): number;
+/**
+ * Why a Free build cannot be confirmed: its estimate is more than the owner's
+ * Free allowance has left this month. Read off the account month the meter
+ * writes, net of give-backs; a read that fails admits, since the reservation
+ * still refuses at the wall.
+ */
+export declare function aiBuildFreeBalanceRefusal(input: {
+    firestore: FirebaseFirestore.Firestore;
+    org: object | null;
+    estimate: number;
+    now: Date;
+}): Promise<string | null>;
+export interface AiBuildAdmissionDeps {
+    opsFor?: (context: AiBuildOpsContext) => Promise<AiBuildOps>;
+    freeBalanceRefusal?: typeof aiBuildFreeBalanceRefusal;
+    ownerOf?: typeof resolveOrgIdForHost;
+    now?: () => Date;
+}
+/**
+ * A build is admitted for a site of the job's own org where a page can be
+ * built; and confirmed only for a plan it can build here — its shape, its
+ * operations as this site has them, and on the Free taste an estimate the
+ * month's Free credits still cover.
+ */
+export declare function createAiBuildJobAdmission(deps?: AiBuildAdmissionDeps): AiJobAdmission;
+export declare const aiBuildJobAdmission: AiJobAdmission;
+/**
+ * Registers the build with the least time a pass needs, the time its next
+ * pass needs, the passes its largest plan may take, and its admission.
+ */
+export declare function registerAiBuildJob(): void;