@intentius/chant 0.91.0 → 0.93.0

package/src/op/decide-config.test.ts

@@ -0,0 +1,52 @@
+/**
+ * The `decide` block in chant.config, the activity's contract, and the step
+ * builder (#2828: the systemone lexicon's plugin tests, re-homed in core).
+ */
+
+import { describe, expect, it } from "vitest";
+import { ChantConfigSchema } from "../config";
+import { decideContract } from "./activities/activity-contracts";
+import * as activities from "./activities";
+import { decide } from "./builders";
+
+describe("decide.backends in chant.config", () => {
+  const valid = (config: Record<string, unknown>) => ChantConfigSchema.safeParse(config).success;
+
+  it("accepts env and brokered keys, and a keyless local backend", () => {
+    expect(
+      valid({
+        decide: {
+          backends: {
+            systemone: { url: "https://api.typesafe.ai", key: { env: "TYPESAFE_API_KEY" } },
+            studio: { url: "http://127.0.0.1:7071", key: { capability: "inference", member: "box" }, timeoutMs: 5000 },
+            local: { url: "http://127.0.0.1:8080" },
+          },
+        },
+      }),
+    ).toBe(true);
+  });
+
+  it("refuses a literal key, an unknown field, and an unknown key in the block", () => {
+    expect(valid({ decide: { backends: { s: { url: "https://x", key: "sk-literal" } } } })).toBe(false);
+    expect(valid({ decide: { backends: { s: { url: "https://x", token: { env: "K" } } } } })).toBe(false);
+    expect(valid({ decide: { backend: {} } })).toBe(false);
+  });
+});
+
+describe("the decide activity and its contract", () => {
+  it("is one of core's activities, with a contract of the same name", () => {
+    expect(typeof (activities as Record<string, unknown>).decide).toBe("function");
+    expect(decideContract.name).toBe("decide");
+  });
+
+  it("the contract refuses a literal key and an unknown arg", () => {
+    expect(decideContract.args.safeParse({ point: "p", backends: { s: { url: "https://x", key: { env: "K" } } } }).success).toBe(true);
+    expect(decideContract.args.safeParse({ point: "p", backends: { s: { url: "https://x", key: "sk-literal" } } }).success).toBe(false);
+    expect(decideContract.args.safeParse({ point: "p", pont: "typo" }).success).toBe(false);
+  });
+
+  it("the builder makes a fastIdempotent decide step with the point first", () => {
+    const step = decide("slice-tier", { read: { "work-item": "W-002" }, subject: "W-002", id: "tier" });
+    expect(step).toMatchObject({ kind: "activity", fn: "decide", args: { point: "slice-tier", read: { "work-item": "W-002" }, subject: "W-002" }, profile: "fastIdempotent", id: "tier" });
+  });
+});

package/src/op/decide-config.ts

@@ -0,0 +1,80 @@
+/**
+ * The `decide` block in `chant.config.ts`: the backends a decision point's
+ * model decider names, which the `decide` Op activity calls (#2828).
+ *
+ * ```ts
+ * import type { ChantConfig } from "@intentius/chant/config";
+ *
+ * export default {
+ *   decide: {
+ *     backends: {
+ *       systemone: { url: "https://api.typesafe.ai", key: { env: "TYPESAFE_API_KEY" } },
+ *       local: { url: "http://127.0.0.1:8080" },
+ *       studio: { url: "http://127.0.0.1:7071", key: { capability: "inference", member: "box" } },
+ *     },
+ *   },
+ * } satisfies ChantConfig;
+ * ```
+ *
+ * A point's model decider says `"backend": "systemone"`, and that name is the
+ * key here. A backend is an endpoint that speaks the `POST /v1/systemone` wire
+ * format (TypeSafe's, or any server that implements it, #2491) and where its
+ * key comes from.
+ *
+ * The key is never a literal. It is either an environment variable's name, or
+ * a capability the workspace declares as brokered on a box member (#2726).
+ * With a brokered capability the broker holds the credential: it either sets
+ * the variable `env` names for this process, or it is itself the endpoint and
+ * adds the key on the way through, in which case no key is sent from here.
+ * SYS001 refuses a string literal where a key goes.
+ *
+ * This module holds only the schemas, so `../config.ts` can validate the
+ * block without loading the client or anything under `workspace/`.
+ */
+
+import { z } from "zod";
+
+/** A key read from an environment variable at call time. */
+export const envKeySchema = z.strictObject({
+  /** The variable's name. */
+  env: z.string().min(1),
+});
+
+/**
+ * A key reached through a capability a box member declares as brokered
+ * (`box.capabilities` in `chant.workspace.json`, #2726). The capability must be
+ * declared and name a broker, or the call is refused.
+ */
+export const brokeredKeySchema = z.strictObject({
+  /** The capability's name in the box block, such as `inference`. */
+  capability: z.string().min(1),
+  /** The member whose box declares it. Without it, the one member that declares the capability. */
+  member: z.string().min(1).optional(),
+  /**
+   * The environment variable the broker sets with the scoped key. Without it,
+   * the broker is the endpoint and adds the key itself, so none is sent.
+   */
+  env: z.string().min(1).optional(),
+});
+
+export const keySchema = z.union([envKeySchema, brokeredKeySchema]);
+
+export const backendSchema = z.strictObject({
+  /** The server's base URL. `/v1/systemone` is appended. */
+  url: z.string().min(1),
+  /** Where the bearer key comes from. Omitted for a server that takes none, such as a local one. */
+  key: keySchema.optional(),
+  /** How long to wait for an answer before the backend counts as unreachable, in milliseconds. Default 30000. */
+  timeoutMs: z.number().int().positive().optional(),
+});
+
+export const decideConfigSchema = z.strictObject({
+  /** Backend name, as a point's model decider names it, to the backend. */
+  backends: z.record(z.string(), backendSchema).optional(),
+});
+
+export type EnvKey = z.infer<typeof envKeySchema>;
+export type BrokeredKey = z.infer<typeof brokeredKeySchema>;
+export type BackendKey = z.infer<typeof keySchema>;
+export type DecideBackend = z.infer<typeof backendSchema>;
+export type DecideConfig = z.infer<typeof decideConfigSchema>;

package/src/op/decide-read-inputs.ts

@@ -0,0 +1,117 @@
+/**
+ * A point's inputs, read through the read contract.
+ *
+ * A point names each input as a read-contract output, optionally with a
+ * dotted field: `work-item.criteria` is the `criteria` field of a work item as
+ * `records --json` lists it (#2738). The decide activity takes, for each
+ * output, what to read (`read: { "work-item": "W-002" }`), reads it the way
+ * the read contract does, and gives each input its field. Values passed in
+ * `inputs` are taken as given and win over read ones.
+ *
+ * Read by id or name here:
+ *
+ *   record, decision, work-item   a record, by id, from the declared record kinds (`records --json`)
+ *   member                        a member, by name (`ls --json`)
+ *
+ * The other outputs a point may name (finding, region, commit, gate, release,
+ * environment, component) are passed in `inputs`, as the output printed them.
+ * These reads never call a model, and never write. The module loads code
+ * under `workspace/`, so the `decide` activity imports it on first call.
+ */
+
+import { declaredKindFiles, queryDeclaredRecords } from "../workspace/records-cli";
+import { listWorkspace } from "../workspace/ls";
+import { inputOutput } from "../workspace/points";
+
+/** The outputs {@link readInputs} reads by id or name. */
+export const READABLE_OUTPUTS = ["record", "decision", "work-item", "member"] as const;
+
+/** One output a decide step asked to read that could not be read. */
+export class InputReadError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "InputReadError";
+  }
+}
+
+/** A field of `value` by dotted path, or undefined. */
+export function fieldOf(value: unknown, path: string): unknown {
+  let at: unknown = value;
+  for (const part of path.split(".")) {
+    if (at === null || typeof at !== "object" || !Object.prototype.hasOwnProperty.call(at, part)) return undefined;
+    at = (at as Record<string, unknown>)[part];
+  }
+  return at;
+}
+
+async function readRecord(id: string, cwd: string, output: string): Promise<Record<string, unknown>> {
+  const set = await queryDeclaredRecords(declaredKindFiles(cwd), { cwd });
+  const unread: string[] = [];
+  for (const doc of set.kinds) {
+    if ("error" in doc) {
+      unread.push(`${doc.declared.path}: ${doc.error.code}`);
+      continue;
+    }
+    const found = doc.records.find((r) => r.id === id);
+    if (found) return found as unknown as Record<string, unknown>;
+  }
+  throw new InputReadError(`no declared record kind holds a record with id ${id} (read for ${output})${unread.length ? `; not read: ${unread.join(", ")}` : ""}`);
+}
+
+function readMember(name: string, cwd: string): Record<string, unknown> {
+  const doc = listWorkspace({ cwd });
+  if ("error" in doc) throw new InputReadError(`the workspace can't be listed: ${doc.error.code}: ${doc.error.message}`);
+  const found = doc.members.find((m) => m.name === name);
+  if (!found) throw new InputReadError(`the workspace has no member named ${name}`);
+  return found as unknown as Record<string, unknown>;
+}
+
+/**
+ * The value of one declared input from what was read for its output. A
+ * record's field is looked up in its front matter first, then in the record
+ * as `records --json` lists it (`state`, `valid`, `path`...). An input with no
+ * field is the whole value.
+ */
+function inputValue(input: string, output: string, read: Record<string, unknown>): unknown {
+  const field = input.length > output.length ? input.slice(output.length + 1) : "";
+  if (field === "") return read;
+  if (output === "member") return fieldOf(read, field);
+  const fromData = fieldOf(read.data, field);
+  return fromData !== undefined ? fromData : fieldOf(read, field);
+}
+
+export interface ReadInputsResult {
+  inputs: Record<string, unknown>;
+  /** Declared inputs of a read output that the value read does not have. Left out, so no table row matches on them. */
+  missing: string[];
+}
+
+/**
+ * Read each output `read` names, and give the point's inputs that name it
+ * their values. Throws an {@link InputReadError} for an output this does not
+ * read, one the point does not name, or an id that is not there.
+ */
+export async function readInputs(declared: string[], read: Record<string, string>, cwd: string): Promise<ReadInputsResult> {
+  const named = new Set(declared.map(inputOutput));
+  for (const output of Object.keys(read)) {
+    if (!(READABLE_OUTPUTS as readonly string[]).includes(output)) {
+      throw new InputReadError(`${output} is not read by id here; pass its values in inputs, as the read contract printed them (read takes ${READABLE_OUTPUTS.join(", ")})`);
+    }
+    if (!named.has(output)) throw new InputReadError(`the point reads no ${output} input (its inputs are ${declared.join(", ")})`);
+  }
+  const values = new Map<string, Record<string, unknown>>();
+  for (const [output, id] of Object.entries(read)) {
+    values.set(output, output === "member" ? readMember(id, cwd) : await readRecord(id, cwd, output));
+  }
+  const inputs: Record<string, unknown> = {};
+  const missing: string[] = [];
+  for (const input of declared) {
+    const output = inputOutput(input);
+    const value = values.get(output);
+    if (value === undefined) continue;
+    const v = inputValue(input, output, value);
+    if (v === undefined) missing.push(input);
+    else inputs[input] = v;
+  }
+  return { inputs, missing };
+}

package/src/op/gate-approval.ts

@@ -32,7 +32,7 @@
  */
 
 import { createHash } from "node:crypto";
-import { lexiconModulePath } from "../lexicon-module";
+import { lexiconModulePath, importLexiconPackage } from "../lexicon-module";
 import { isStepOutputRef, type StepOutputRef } from "./step-output-ref";
 
 /** What a policy's decision does to the gate. */
@@ -226,7 +226,7 @@ export async function loadGatePolicyEvaluator(lexicon: string): Promise<GatePoli
   const spec = lexiconModulePath(lexicon) ?? `@intentius/chant-lexicon-${lexicon}/gate-policy`;
   let mod: Partial<GatePolicyEvaluator>;
   try {
-    mod = (await import(spec)) as Partial<GatePolicyEvaluator>;
+    mod = (await importLexiconPackage(spec)) as Partial<GatePolicyEvaluator>;
   } catch (err) {
     throw new Error(
       `the gate's policy is evaluated by ${spec}, which could not be loaded: ` +

package/src/op/gate-wait.ts

@@ -0,0 +1,57 @@
+/**
+ * A step whose command stopped at a gate of its own (#2779).
+ *
+ * Some chant commands decide a gate themselves rather than through a `gate`
+ * step: `chant workspace upgrade` stages its patch, records
+ * `workspace-upgrade` / `<scope>` pending on the gate ledger, and exits 3.
+ * An Op step that runs such a command stops its run at that gate by throwing
+ * {@link GateWait} with the pending fact the command recorded. The executor
+ * ends the run there with status `gated`, as it does at a pending `gate`
+ * step: no later step runs, no `onFailure` phase runs, a work lease is
+ * released `gated`, and the run ledger names the gate, with the op it is
+ * recorded under when that isn't the run's own.
+ *
+ * Nothing waits. After `chant approve <op> <gate>` the next run runs the
+ * command again, the command finds the approval, and the step goes on. A
+ * local steward re-runs its own gated run on the first round after the
+ * approval (`./operator.ts`).
+ *
+ * `shell()` throws it for an exit code named in `gatedExit`
+ * (`./activities/shell.ts`); an activity of a lexicon can throw it too.
+ */
+
+import type { PendingGateRecord } from "../lifecycle/gate-ledger";
+
+/** The marker {@link GateWait} carries, so a copy of core linked twice still recognises it. */
+const GATE_WAIT = Symbol.for("chant.op.GateWait");
+
+/**
+ * Thrown by an activity whose command stopped at a gate. Not a failure: the
+ * executor ends the run with status `gated` (see the module doc).
+ */
+export class GateWait extends Error {
+  readonly [GATE_WAIT] = true;
+  constructor(readonly pending: PendingGateRecord) {
+    super(`stopped at gate ${pending.op} / ${pending.gate}: approve it with \`chant approve ${pending.op} ${pending.gate}\` and run again`);
+    this.name = "GateWait";
+  }
+}
+
+/** Is this a {@link GateWait}? Duck-typed on the shared symbol. */
+export function isGateWait(err: unknown): err is GateWait {
+  return !!err && typeof err === "object" && (err as Record<symbol, unknown>)[GATE_WAIT] === true && "pending" in err;
+}
+
+/**
+ * `value` as a pending gate fact, or undefined when it isn't one: it needs
+ * the `op`, `gate`, `timestamp` and `expiresAt` every pending line on the
+ * gate ledger carries.
+ */
+export function asPendingGate(value: unknown): PendingGateRecord | undefined {
+  if (!value || typeof value !== "object") return undefined;
+  const v = value as Record<string, unknown>;
+  for (const key of ["op", "gate", "timestamp", "expiresAt"]) {
+    if (typeof v[key] !== "string" || v[key] === "") return undefined;
+  }
+  return { ...(v as unknown as PendingGateRecord), version: 1, kind: "pending" };
+}

package/src/op/gate.ts

@@ -481,8 +481,13 @@ export async function evaluateGate(port: GateLedgerPort, input: GateCheckInput):
 /**
  * The line every renderer prints to say how a pending gate is cleared. A
  * component gate names its environment (#2574), so the approval picks that
- * environment's pending fact when others stand beside it.
+ * environment's pending fact when others stand beside it. A gate bound to a
+ * plan (#2300) gets `--plan <digest>` too (#2832), so the line approves the
+ * plan the reader was shown and not whatever is pending by the time they run
+ * it.
  */
-export function approveCommand(op: string, gate: string, environment?: string): string {
-  return environment === undefined ? `chant approve ${op} ${gate}` : `chant approve ${op} ${gate} --env ${environment}`;
+export function approveCommand(op: string, gate: string, environment?: string, planDigest?: string): string {
+  return `chant approve ${op} ${gate}` +
+    (environment === undefined ? "" : ` --env ${environment}`) +
+    (planDigest === undefined ? "" : ` --plan ${planDigest}`);
 }

package/src/op/generate-pipeline.ts

@@ -17,7 +17,7 @@
  */
 
 import { discoverOps, type DiscoveredOp } from "./discover";
-import { lexiconModulePath } from "../lexicon-module";
+import { lexiconModulePath, importLexiconPackage } from "../lexicon-module";
 import {
   isLexiconPlugin,
   type LexiconPlugin,
@@ -37,7 +37,7 @@ import {
 async function loadLexiconPlugin(name: string): Promise<LexiconPlugin | null> {
   let mod: Record<string, unknown>;
   try {
-    mod = (await import(lexiconModulePath(name) ?? `@intentius/chant-lexicon-${name}`)) as Record<string, unknown>;
+    mod = (await importLexiconPackage(lexiconModulePath(name) ?? `@intentius/chant-lexicon-${name}`)) as Record<string, unknown>;
   } catch {
     return null;
   }

package/src/op/index.ts

@@ -1,9 +1,9 @@
 export { Op, phase, activity, gate, effect, build, kubectlApply, helmInstall, helmInstallPinned, waitForStack, waitForReady,
-         gitlabPipeline, lifecycleSnapshot, shell, ensureSecret, teardown, envTeardown, k3dUp, k3dDown,
+         gitlabPipeline, lifecycleSnapshot, shell, sourceArchive, releasePlan, releaseRecord, releaseRollbackPlan, releaseRollbackRecord, decide, ensureSecret, teardown, envTeardown, k3dUp, k3dDown,
          k3sInstall, k3sUninstall, flociUp, flociDown,
          flociAzUp, flociAzDown, flociGcpUp, flociGcpDown, httpCheck,
          azGroupEnsure, azGroupDelete, azApply, azDelete, awsApply, awsDelete, gcpApply, gcpDelete, policyGate,
-         guardValidate,
+         guardValidate, workEvidence,
          spriteCreate, spriteExec, spriteCheckpoint, spriteRestore, listCheckpoints, spriteDestroy,
          spriteWriteFile, spriteReadFile, spriteListDir, spriteRemove,
          spriteApplyNetworkPolicy, spriteApplyServices,
@@ -37,6 +37,10 @@ export type {
   LexiconUpgradeOpConfig, LexiconUpgradeOpResources,
   BehaviourOpConfig, BehaviourOpResources,
 } from "./composites";
+export type {
+  ConvergeSymptom, ResourceSymptom, ResourceObservation, ObservedResource, ResourceStatus,
+} from "../lifecycle/symptoms";
+export { parseResourceObservation, CONVERGE_RESOURCE_ENV } from "../lifecycle/symptoms";
 export { receiptActivities, receiptCheckInput } from "./receipt-store";
 export type {
   ReceiptStore, EffectReceiptRef, ReceiptCheckInput, ReceiptActivities, ReceiptActivityOptions,
@@ -51,7 +55,7 @@ export { loadActivities, loadProfiles, resolveActivity } from "./activity-regist
 export type { ActivityFn } from "./activity-registry";
 export { loadActivityContracts, mergeActivityContracts } from "./activity-contract-registry";
 export type { LexiconActivityContractContributor } from "./activity-contract-registry";
-export { ACTIVITY_PROFILES, ACTIVITY_PROFILE_NAMES } from "./activity-profiles";
+export { ACTIVITY_PROFILES, ACTIVITY_PROFILE_NAMES, MAX_STEP_TIMEOUT } from "./activity-profiles";
 export type { ActivityProfile, ActivityProfileName } from "./activity-profiles";
 export { NonRetryableActivityError, nonRetryableFailure } from "./activity-failure";
 export { runOpLocally, parseDuration, OpRunFailure } from "./local-executor";
@@ -105,15 +109,26 @@ export type {
 export {
   discoverConvergeOps, runOperatorRound, runOperatorForever, formatRoundLine,
   formatSignalLine, DEFAULT_OPERATOR_INTERVAL_MS, acquireStewardLease,
+  acquireStewardTurn, STEWARD_TURN_WAIT_MS,
 } from "./operator";
 export {
   declareSteward, isStewardDeclaration, stewardFormFor, stewardOpConfig, normaliseStewardForm, stewardLeaseName,
+  stewardTurnLeaseName,
   STEWARD_KIND, STEWARD_FORMS, STEWARD_NAME_PATTERN, DEFAULT_STEWARD_ENV,
 } from "./steward";
 export type {
   StewardDeclaration, StewardDeclarationConfig, StewardForm, StewardFormSpec, StewardOpInput,
 } from "./steward";
 export { discoverStewards } from "./discover";
+export {
+  askPointInRun, brokeredModelAsk, isPointWait, PointWait, DEFAULT_INFERENCE_CAPABILITY,
+} from "./steward-points";
+export type { AskPointInRunOptions, BrokeredModelAsk, WaitingPoint } from "./steward-points";
+export { GateWait, isGateWait } from "./gate-wait";
+export {
+  currentStewardTurn, enterStewardTurn, setStewardTurn, resetStewardTurn, STEWARD_ENV,
+} from "./steward-turn";
+export type { StewardTurn } from "./steward-turn";
 export type { DiscoveredSteward, StewardDiscoveryResult } from "./discover";
 export type {
   OperatorTickEvent, OperatorRoundOptions, OperatorLoopOptions,