@thinair/factory 0.1.158 → 0.1.164

package/cli/evaluate.ts

@@ -26,8 +26,12 @@ export const EvaluateInput = Schema.Struct({
 });
 export type EvaluateInput = typeof EvaluateInput.Type;
 
+const EvaluateNotice = Schema.Struct({ node: Schema.NullOr(NodeId), at: Schema.NullOr(SourceAt), message: Schema.String });
+
 export const EvaluateOutput = Schema.Struct({
   program: Schema.NullOr(Program),
+  /** Notes that hold nothing: a retired constructor the code still calls runs as its replacement. */
+  notices: Schema.Array(EvaluateNotice),
   problems: Schema.Array(Schema.Struct({
     /** `evaluate`: the code threw while it loaded. `value`: the encoder's checks. */
     step: Schema.Literals(["evaluate", "value"]),
@@ -73,12 +77,13 @@ const evaluate = Effect.fn("factory.evaluate")(function* (inputPath: string) {
           hash: (text) => createHash("sha256").update(text).digest("hex"),
           files: input.files,
         });
-        return { program: encoded.program, problems: encoded.problems.map((problem) => ({ step: "value" as const, ...problem })) };
+        return { program: encoded.program, notices: encoded.notices, problems: encoded.problems.map((problem) => ({ step: "value" as const, ...problem })) };
       },
       catch: (error) => error,
     })),
     Effect.catch((error) => Effect.succeed<EvaluateOutput>({
       program: null,
+      notices: [],
       problems: [{ step: "evaluate", node: null, at: throwAt(error, input.tree), message: `The factory's code threw while it loaded: ${error instanceof Error ? error.message : String(error)}` }],
     })),
   );

package/cli/load.ts

@@ -6,7 +6,7 @@ import { createRequire } from "node:module";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { Context, Effect, Layer, Result, Schema } from "effect";
-import { LOAD_VERSION, LoadJson, LoadPost, type Finding, type Load } from "../domain/load";
+import { holds, LOAD_VERSION, LoadJson, LoadPost, type Finding, type Load } from "../domain/load";
 import { appShapeProblems, AUTHORING_MODULES, folderKey, IGNORED_FOLDERS, isLoadedPath, memberFiles } from "../domain/system-elements/app-shape";
 import { FrameworkVersion, holesOf, type Node, type Program } from "../domain/system-elements/program";
 import { EvaluateOutputJson, type EvaluateInput } from "./evaluate";
@@ -270,7 +270,10 @@ const evaluate = Effect.fn("factory.load.evaluate")(function* (input: Omit<Evalu
   );
   return {
     program: output.program,
-    findings: output.problems.map((problem) => finding(problem.step, problem.message, { node: problem.node, file: problem.at?.file ?? null, line: problem.at?.line ?? null })),
+    findings: [
+      ...output.problems.map((problem) => finding(problem.step, problem.message, { node: problem.node, file: problem.at?.file ?? null, line: problem.at?.line ?? null })),
+      ...output.notices.map((notice) => ({ ...finding("value", notice.message, { node: notice.node, file: notice.at?.file ?? null, line: notice.at?.line ?? null }), notice: true as const })),
+    ],
   };
 });
 
@@ -354,7 +357,7 @@ export const loadFactory = Effect.fn("factory.load")(function* (input: Readonly<
 
   const load: Load = yield* timed(steps, "encode", Effect.sync((): Load => {
     const all = findings.map(pinned(program));
-    return { version: LOAD_VERSION, framework, key: snapshot.key, state: all.length === 0 ? "ready" : "held", program, holes: program === null ? [] : holesOf(program), findings: all, cached: false, steps };
+    return { version: LOAD_VERSION, framework, key: snapshot.key, state: all.some(holds) ? "held" : "ready", program, holes: program === null ? [] : holesOf(program), findings: all, cached: false, steps };
   }));
   const encoded = yield* Schema.encodeEffect(LoadJson)(load).pipe(Effect.mapError((error) => new FactoryLoadFailed({ message: `The load does not encode: ${error.message}` })));
   yield* Effect.tryPromise({ try: () => mkdir(path.dirname(cacheFile), { recursive: true }).then(() => writeFile(cacheFile, JSON.stringify(encoded))), catch: failed("Could not write the load cache.") });

package/domain/load.ts

@@ -22,7 +22,12 @@ export const Finding = Schema.Struct({
   file: Schema.NullOr(Schema.String),
   line: Schema.NullOr(Schema.Int),
   message: Schema.String,
+  /** A note that holds nothing: the code still runs as written (a retired constructor runs as its replacement). */
+  notice: Schema.optionalKey(Schema.Literal(true)),
 });
+
+/** Whether a finding holds the load: every finding but a notice does. */
+export const holds = (finding: Readonly<{ notice?: true | undefined }>) => finding.notice !== true;
 export type Finding = typeof Finding.Type;
 
 /** `ready` runs (live) or draws (preview). `held` keeps the last good revision: its findings say why. */

package/domain/system-elements/compose.ts

@@ -18,7 +18,7 @@ import type { AnyStage, StageSpec } from "./stage";
  * Act, one-time and outward: wake, checkRun, mergePullRequest, post, call.
  *   They go through the act outbox, keyed, with a lease, settled by reading.
  * Seen, read only: output, verdict, ticket, children, fact, judged, pinned,
- *   lifecycle. App-specific questions become facts or job outputs.
+ *   lifecycle, placeable. App-specific questions become facts or job outputs.
  *
  * A rule routes one fact: it returns ticket(stage, key, spec) to file or
  * update a ticket, and acts.
@@ -73,7 +73,7 @@ export interface Child<S extends AnyStage = AnyStage> {
 export const child = <S extends AnyStage>(stage: S, key: string, spec: StageSpec<S>): Child<S> => ({ _tag: "Child", stage, key, spec });
 
 export interface Done { readonly _tag: "Done"; readonly note: string }
-/** This ticket's work is done. */
+/** This ticket's work is done; its note is what the ticket says it did (its why). */
 export const done = (note: string): Done => ({ _tag: "Done", note });
 
 export interface Hold { readonly _tag: "Hold"; readonly reason: string }
@@ -176,6 +176,12 @@ export interface Seen<W extends Work = Work> {
   readonly judged: <A>(question: Question<A>) => Judgment<A>;
   readonly pinned: (name: string) => Schema.Json | undefined;
   readonly lifecycle: Readonly<{ matches: (state: string) => boolean }>;
+  /**
+   * Whether a computer of the factory's fleet can run this job now, room aside: one that offers its os, arch and uses
+   * is up, and admits this factory's work of its kind there (a command on the computer itself, or a sealed VM).
+   * Undefined while the fleet cannot be read. A wanted job no computer can run waits; compose may leave it out instead.
+   */
+  readonly placeable: <J extends W & AnyJob>(job: J) => boolean | undefined;
 }
 
 /** What a rule may read while it routes one fact. */

package/domain/system-elements/node.ts

@@ -158,6 +158,8 @@ export interface Encoder {
   readonly ref: <T extends NodeTag>(to: T, value: Slot<T>) => Ref<T>;
   /** A problem with this node's settings, pinned to it. */
   readonly problem: (message: string) => void;
+  /** A note on this node that holds nothing, pinned to it: its code still runs as written. */
+  readonly notice: (message: string) => void;
 }
 
 /** The rows a floor reads, by the node each belongs to. The records name their nodes by id. */

package/domain/system-elements/pool.ts

@@ -1,5 +1,5 @@
 import { Schema } from "effect";
-import { AUTHORED, authoredHead, head, type Authored, type LiveRows } from "./node";
+import { AUTHORED, authoredHead, head, type Authored, type Encoder, type LiveRows } from "./node";
 
 /*
  * A pool names a provider and an optional narrowing, nothing else.
@@ -22,6 +22,7 @@ export const RETIRED_PROVIDERS = ["macs", "thinair-cloud", "namespace"] as const
 export const Provider = Schema.Literals([...PROVIDERS, ...RETIRED_PROVIDERS]);
 export type Provider = typeof Provider.Type;
 export type AuthoredProvider = (typeof PROVIDERS)[number];
+export type RetiredProvider = (typeof RETIRED_PROVIDERS)[number];
 
 /** Whether a pool names the owner's fleet: `fleet`, or a retired name that meant part of it. */
 export const isFleet = (provider: Provider) => provider === "fleet" || provider === "macs" || provider === "thinair-cloud";
@@ -38,10 +39,12 @@ export type Narrowing = typeof Narrowing.Type;
 export const Node = Schema.TaggedStruct("Pool", { ...head, provider: Provider, ...Narrowing.fields });
 export type Node = typeof Node.Type;
 
-export interface AuthoredPool<P extends AuthoredProvider = AuthoredProvider> extends Authored<"Pool", P> {
+export interface AuthoredPool<P extends AuthoredProvider = AuthoredProvider> extends Authored<"Pool", string> {
   readonly provider: P;
   readonly os: ReadonlyArray<Os>;
   readonly arch: ReadonlyArray<Arch>;
+  /** The retired constructor that made it, when one did: it runs as the fleet, and the load says so. */
+  readonly retired?: RetiredProvider;
 }
 
 type Narrow = Readonly<{ os?: ReadonlyArray<Os>; arch?: ReadonlyArray<Arch> }>;
@@ -53,6 +56,20 @@ const made = <const P extends AuthoredProvider>(provider: P, narrow: Narrow | un
   arch: narrow?.arch ?? [],
 });
 
+/**
+ * A retired constructor, kept so code written before one fleet still loads and its passes still run: it makes the
+ * fleet with the same narrowing, under its own name (`pool:macs`), so its node and every Ref to it stay as they were.
+ */
+const retired = (name: RetiredProvider) => (narrow?: Narrow): AuthoredPool<"fleet"> => ({
+  [AUTHORED]: authoredHead("Pool", name, false),
+  provider: "fleet",
+  os: narrow?.os ?? [],
+  arch: narrow?.arch ?? [],
+  retired: name,
+});
+
+const RETIRED_CALL: Readonly<Record<RetiredProvider, string>> = { macs: "pool.macs()", "thinair-cloud": "pool.thinairCloud()", namespace: "pool.namespace()" };
+
 /** The pools a factory can name. Each is named after its provider: `pool:fleet`. */
 export const pool = {
   /**
@@ -64,9 +81,19 @@ export const pool = {
   fleet: (narrow?: Narrow) => made("fleet", narrow),
   /** GitHub Actions runners, dispatched with the Agents App. */
   githubActions: (narrow?: Narrow) => made("github-actions", narrow),
+  /** @deprecated The fleet: use `pool.fleet()`. It makes the fleet with this narrowing, and the load says so. */
+  macs: retired("macs"),
+  /** @deprecated The fleet, which Thinair Cloud joins once the owner names the factory's Cloud Organization: use `pool.fleet()`. */
+  thinairCloud: retired("thinair-cloud"),
+  /** @deprecated Never had a filling: use `pool.fleet()`. It makes the fleet with this narrowing, and the load says so. */
+  namespace: retired("namespace"),
 };
 
-export const make = (authored: AuthoredPool) => ({ provider: authored.provider, os: [...authored.os], arch: [...authored.arch] });
+export const make = (authored: AuthoredPool, encoder: Encoder) => {
+  if (authored.retired !== undefined)
+    encoder.notice(`${RETIRED_CALL[authored.retired]} is pool.fleet() now: it runs as the fleet with the same narrowing. Rename it to pool.fleet().`);
+  return { provider: authored.provider, os: [...authored.os], arch: [...authored.arch] };
+};
 
 /** The machines placement can use now, from their own facts. */
 export const live = (node: Node, rows: LiveRows) => {

package/domain/system-elements/registry.ts

@@ -67,7 +67,7 @@ export type EncodeOptions = Readonly<{
   files: Readonly<Record<string, FileFacts>>;
 }>;
 
-export type Encoded = Readonly<{ program: Program | null; problems: ReadonlyArray<EncodeProblem> }>;
+export type Encoded = Readonly<{ program: Program | null; problems: ReadonlyArray<EncodeProblem>; notices: ReadonlyArray<EncodeProblem> }>;
 
 /** JSON with keys sorted at every level: two values are the same when this is. */
 const canonicalJson = (value: unknown): string => JSON.stringify(value, (_key, item: unknown) =>
@@ -80,6 +80,7 @@ type Draft = Readonly<{ node: Readonly<Record<string, unknown>> & { readonly at:
 /** Encode a factory's root, as `factory.ts` exports it, into its Program. */
 export const encodeFactory = (root: unknown, options: EncodeOptions): Encoded => {
   const problems: EncodeProblem[] = [];
+  const notices: EncodeProblem[] = [];
   const drafts = new Map<NodeId, Draft>();
   const encodedValues = new Map<object, NodeId>();
   const visiting = new Set<object>();
@@ -117,6 +118,7 @@ export const encodeFactory = (root: unknown, options: EncodeOptions): Encoded =>
     const encoder: Encoder = {
       ref: (tag, slot) => encode(tag, slot, { node: id, at }),
       problem: (message) => problems.push({ node: id, at, message }),
+      notice: (message) => notices.push({ node: id, at, message }),
     };
     const settings = (definitions[made.tag] as Definition<Tag>).make(value as never, encoder);
     visiting.delete(value);
@@ -132,10 +134,10 @@ export const encodeFactory = (root: unknown, options: EncodeOptions): Encoded =>
 
   if (!isAuthored(root) || headOf(root).tag !== "Factory") {
     problems.push({ node: null, at: { file: "factory.ts", line: 1 }, message: "factory.ts's default export is the factory: export default defineFactory({ ... })." });
-    return { program: null, problems };
+    return { program: null, problems, notices };
   }
   encode("Factory", root, null);
-  if (broken) return { program: null, problems };
+  if (broken) return { program: null, problems, notices };
 
   // A node's digest covers its content and, when it holds code, the import closure of its file,
   // stopping at files that make other nodes: those nodes have digests of their own.
@@ -165,9 +167,9 @@ export const encodeFactory = (root: unknown, options: EncodeOptions): Encoded =>
   const decoded = Schema.decodeUnknownResult(Program)({ version: LANGUAGE_VERSION, framework: options.framework, root: ROOT_ID, nodes });
   if (Result.isFailure(decoded)) {
     problems.push({ node: null, at: null, message: `The program does not decode: ${decoded.failure.message}` });
-    return { program: null, problems };
+    return { program: null, problems, notices };
   }
   for (const problem of graphProblems(decoded.success))
     problems.push({ node: problem.node, at: (decoded.success.nodes[problem.node] as Node | undefined)?.at ?? null, message: problem.message });
-  return { program: decoded.success, problems };
+  return { program: decoded.success, problems, notices };
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thinair/factory",
-  "version": "0.1.158",
+  "version": "0.1.164",
   "description": "The Thinair factory SDK: the language a factory's code is written in, and the loader that checks it.",
   "license": "Apache-2.0",
   "type": "module",