@intentius/chant 0.102.0 → 0.104.1

package/src/lifecycle/git.ts

@@ -660,44 +660,120 @@ export async function getRemoteLifecycleBranchSha(
 }
 
 /**
- * Push the state branch to remote with --force-with-lease.
+ * Why a push of the state branch did or did not reach the remote.
  *
- * If the remote chant/lifecycle ref has advanced past the local remote-tracking
- * SHA captured at the start of this push, the push is rejected and we throw
- * StaleLifecycleBranchError so the caller can surface a recovery hint.
+ * - `pushed` — the remote now holds the local tip.
+ * - `no-remote` — nothing to push to; local is the whole ledger.
+ * - `stale` — the remote moved past the tip this checkout last saw (another
+ *   writer pushed); fetch, re-apply and retry.
+ * - `failed` — git refused for another reason (no network, no credentials,
+ *   a protected branch); `stderr` is git's first words on it.
+ */
+export type LifecyclePushStatus =
+  | { status: "pushed"; remote: string; commit: string }
+  | { status: "no-remote" }
+  | { status: "stale"; remote: string; expected: string | null; stderr: string }
+  | { status: "failed"; remote: string; stderr: string };
+
+/**
+ * Point `refs/remotes/<remote>/chant/lifecycle` at `sha`, the remote tip this
+ * checkout has just seen (#3391).
  *
- * Returns false (without throwing) only when no remote is configured at all.
+ * The push's lease is that ref, and git only keeps it up to date when the
+ * remote's configured fetch refspec covers `chant/lifecycle`. A single-branch
+ * clone (`git clone --single-branch`, a CI checkout of one ref, a shallow
+ * clone) has a refspec for its one branch only, so neither the explicit
+ * `chant/lifecycle:chant/lifecycle` fetch nor a successful push touches the
+ * tracking ref. The first push of a new branch then succeeds against an empty
+ * lease, and every later one is refused as stale against a remote that holds
+ * exactly what this checkout last pushed. Recording the tip ourselves, only at
+ * the two moments it is known (a fetch that fast-forwarded or found the local
+ * branch ahead, and a push that landed), keeps the lease honest without
+ * widening the clone's refspec. It is never set from a diverged fetch: that is
+ * the case the lease exists to refuse.
  */
-export async function pushLifecycle(opts?: { cwd?: string }): Promise<boolean> {
+async function trackRemoteLifecycle(remote: string, sha: string, cwd?: string): Promise<void> {
   const rt = getRuntime();
-  const remoteResult = await rt.spawn(["git", "remote"], { cwd: opts?.cwd });
-  if (remoteResult.exitCode !== 0 || !remoteResult.stdout.trim()) return false;
+  await rt.spawn(["git", "update-ref", `refs/remotes/${remote}/${STATE_BRANCH}`, sha], { cwd, env: C_LOCALE_ENV });
+}
 
-  const remote = remoteResult.stdout.trim().split("\n")[0];
+/**
+ * Push the state branch to the ledger remote with --force-with-lease and say
+ * what happened (#3391). Never throws for a git refusal; {@link pushLifecycle}
+ * is the throwing form most callers use.
+ */
+export async function pushLifecycleStatus(opts?: { cwd?: string }): Promise<LifecyclePushStatus> {
+  const rt = getRuntime();
+  const cwd = opts?.cwd;
+  const found = await ledgerRemote(cwd);
+  if (found === null) return { status: "no-remote" };
+  if ("failed" in found) return { status: "failed", remote: "(unknown)", stderr: found.stderr };
+  const { remote } = found;
 
   // Capture the lease SHA — if null, the remote ref doesn't exist yet
   // (first-time push) and we send `--force-with-lease=ref:` (empty SHA),
   // which git interprets as "ref does not exist on remote".
   const expected = await getRemoteLifecycleBranchSha(remote, opts);
   const lease = `refs/heads/${STATE_BRANCH}:${expected ?? ""}`;
+  const tip = await getStateBranchTip(cwd);
 
   const pushResult = await rt.spawn(
     ["git", "push", `--force-with-lease=${lease}`, remote, `${STATE_BRANCH}:${STATE_BRANCH}`],
-    { cwd: opts?.cwd },
+    { cwd, env: C_LOCALE_ENV },
   );
 
   if (pushResult.exitCode !== 0) {
-    const stderr = pushResult.stderr ?? "";
+    const stderr = (pushResult.stderr ?? "").trim();
     if (
       stderr.includes("stale info") ||
       stderr.includes("rejected") ||
       stderr.includes("non-fast-forward")
     ) {
-      throw new StaleLifecycleBranchError(expected, stderr);
+      return { status: "stale", remote, expected, stderr };
     }
-    return false;
+    return { status: "failed", remote, stderr };
+  }
+  if (tip) await trackRemoteLifecycle(remote, tip, cwd);
+  return { status: "pushed", remote, commit: tip ?? "" };
+}
+
+/**
+ * Push the state branch to remote with --force-with-lease.
+ *
+ * If the remote chant/lifecycle ref has advanced past the local remote-tracking
+ * SHA captured at the start of this push, the push is rejected and we throw
+ * StaleLifecycleBranchError so the caller can surface a recovery hint.
+ *
+ * Returns false (without throwing) when no remote is configured, or when git
+ * refused the push for a reason other than a stale lease.
+ *
+ * The remote is the ledger's ({@link ledgerRemote}: `origin` when there is one),
+ * the same one {@link fetchLifecycleStatus} reads, and a push that lands
+ * records the tip it pushed as the remote-tracking ref, so the next push's
+ * lease is right in a single-branch clone too (#3391).
+ */
+export async function pushLifecycle(opts?: { cwd?: string }): Promise<boolean> {
+  const result = await pushLifecycleStatus(opts);
+  if (result.status === "stale") throw new StaleLifecycleBranchError(result.expected, result.stderr);
+  return result.status === "pushed";
+}
+
+/**
+ * One line on why a push did not land, for a write document's `notPushed`
+ * (#3391), or null when it did.
+ */
+export function describeLifecyclePush(result: LifecyclePushStatus): string | null {
+  const said = (stderr: string) => (stderr ? `; git said: ${stderr.split("\n").find((l) => l.trim()) ?? stderr}` : "");
+  switch (result.status) {
+    case "pushed":
+      return null;
+    case "no-remote":
+      return `this repository has no remote, so ${STATE_BRANCH} stays local`;
+    case "stale":
+      return `"${result.remote}" holds ${STATE_BRANCH} commits this checkout has not fetched, so the push was refused; fetch ${STATE_BRANCH} and write again${said(result.stderr)}`;
+    case "failed":
+      return `the push of ${STATE_BRANCH} to "${result.remote}" failed${said(result.stderr)}`;
   }
-  return true;
 }
 
 /**
@@ -814,7 +890,12 @@ export async function fetchLifecycleStatus(opts?: { cwd?: string }): Promise<Lif
     ["git", "fetch", remote, `${STATE_BRANCH}:${STATE_BRANCH}`],
     { cwd, env: C_LOCALE_ENV },
   );
-  if (fetchResult.exitCode === 0) return { status: "fetched" };
+  if (fetchResult.exitCode === 0) {
+    // The local branch is now the remote's tip; record it for the push's lease (#3391).
+    const tip = await getStateBranchTip(cwd);
+    if (tip) await trackRemoteLifecycle(remote, tip, cwd);
+    return { status: "fetched" };
+  }
 
   const stderr = (fetchResult.stderr ?? "").trim();
   if (NO_SUCH_REMOTE_REF_RE.test(stderr)) return { status: "absent", remote };
@@ -834,8 +915,13 @@ export async function fetchLifecycleStatus(opts?: { cwd?: string }): Promise<Lif
     ["git", "merge-base", "--is-ancestor", PROBE_REF, `refs/heads/${STATE_BRANCH}`],
     { cwd, env: C_LOCALE_ENV },
   );
+  const remoteTip = contains.exitCode === 0 ? (await rt.spawn(["git", "rev-parse", "--verify", PROBE_REF], { cwd, env: C_LOCALE_ENV })).stdout.trim() : "";
   await rt.spawn(["git", "update-ref", "-d", PROBE_REF], { cwd, env: C_LOCALE_ENV });
-  if (contains.exitCode === 0) return { status: "ahead", remote };
+  if (contains.exitCode === 0) {
+    // Ahead of the remote: its tip is in our history, so it is the right lease (#3391).
+    if (remoteTip) await trackRemoteLifecycle(remote, remoteTip, cwd);
+    return { status: "ahead", remote };
+  }
   return { status: "diverged", remote, stderr };
 }
 

package/src/lint/post-synth.test.ts

@@ -162,6 +162,25 @@ describe("cross-lexicon activity contracts (#2101)", () => {
   });
 });
 
+describe("telemetry attribution (#3375)", () => {
+  const readsTelemetry: PostSynthCheck = {
+    id: "TELEMETRY",
+    description: "reports the attribution the context carries",
+    check(ctx) {
+      return [{ checkId: "TELEMETRY", severity: "warning", message: JSON.stringify(ctx.telemetry ?? null) }];
+    },
+  };
+
+  test("the build's attribution is threaded into the context", () => {
+    const diags = runPostSynthChecks([readsTelemetry], createBuildResult(), undefined, { telemetry: { workspace: "acme" } });
+    expect(diags[0].message).toBe('{"workspace":"acme"}');
+  });
+
+  test("a level-0 run leaves the field undefined", () => {
+    expect(runPostSynthChecks([readsTelemetry], createBuildResult())[0].message).toBe("null");
+  });
+});
+
 describe("isPostSynthCheck", () => {
   test("accepts a well-formed check and rejects others", async () => {
     const { isPostSynthCheck } = await import("./post-synth");

package/src/lint/post-synth.ts

@@ -1,6 +1,7 @@
 import type { Declarable } from "../declarable";
 import type { ActivityContract } from "../op/activity-contract";
 import type { SerializerResult } from "../serializer";
+import type { TelemetryAttribution } from "../telemetry-attribution";
 import type { Severity } from "./rule";
 import { parseOutputDocs, type OutputDoc } from "./output-docs";
 
@@ -55,6 +56,13 @@ export interface PostSynthContext {
    * when it is `undefined`.
    */
   readonly activityContracts?: ReadonlyMap<string, ActivityContract>;
+  /**
+   * The telemetry attribution the build stamped (#2558), from
+   * `resolveTelemetryAttribution`. Set when the project is inside a workspace
+   * or sets `telemetry.attribution: true`, and absent at level 0 and from a
+   * hand-built context. OTEL118 runs only when it is set.
+   */
+  readonly telemetry?: TelemetryAttribution;
   /** Raw build result object */
   buildResult: {
     outputs: Map<string, string | SerializerResult>;
@@ -183,6 +191,14 @@ export interface PostSynthCheck {
   description: string;
   /** Execute the check and return diagnostics */
   check(ctx: PostSynthContext): PostSynthDiagnostic[];
+  /**
+   * `chant audit` skips this check unless the project enables it with a
+   * `lint.rules` entry for its id (chant #3190). Builds are not affected: they
+   * already filter by the lexicon's `lintPresets()`. It exists because the
+   * audit runs every check a lexicon ships, report-only ones included, so a
+   * new check would otherwise change the audit output of every project.
+   */
+  auditOptIn?: boolean;
 }
 
 /** Structural type guard — used to collect project-authored policy checks. */
@@ -201,12 +217,13 @@ export function isPostSynthCheck(value: unknown): value is PostSynthCheck {
  * into the context so a check can branch on the current environment/stack, and
  * `opts.activityContracts` (chant #2101) carries the build's cross-lexicon
  * activity-contract map to the checks that validate Op steps against it.
+ * `opts.telemetry` is the build's resolved telemetry attribution.
  */
 export function runPostSynthChecks(
   checks: PostSynthCheck[],
   buildResult: PostSynthContext["buildResult"],
   env?: string,
-  opts?: { activityContracts?: ReadonlyMap<string, ActivityContract> },
+  opts?: { activityContracts?: ReadonlyMap<string, ActivityContract>; telemetry?: TelemetryAttribution },
 ): PostSynthDiagnostic[] {
   const getDocs = createDocsAccessor(buildResult.outputs);
   const ctx: PostSynthContext = {
@@ -215,6 +232,7 @@ export function runPostSynthChecks(
     env,
     buildResult,
     ...(opts?.activityContracts ? { activityContracts: opts.activityContracts } : {}),
+    ...(opts?.telemetry ? { telemetry: opts.telemetry } : {}),
     get docs(): OutputDoc[] {
       return getDocs();
     },

package/src/meta/declared-imports.test.ts

@@ -43,7 +43,7 @@ const DELIBERATELY_UNDECLARED = new Map<string, string>([
   [
     "@cdktn/hcl2json",
     "carries a ~1.8 MB wasm blob and is only needed by `chant carve`; " +
-      "`terraform/parse.ts` catches the failed import and prints the install line",
+      "`terraform/hcl2json.ts` catches the failed import and prints the install line",
   ],
   [
     "@intentius/chant-lexicon-gitlab",

package/src/op/activities/activity-contracts.ts

@@ -252,6 +252,29 @@ export const sourceArchiveContract = activityContract(
   z.object({ digest: z.string(), archive: z.string(), commit: z.string(), dir: z.string(), files: z.number(), bytes: z.number() }),
 );
 
+const changeSetPart = z.object({
+  member: z.object({ member: z.string(), planDigest: z.string().nullable() }).passthrough(),
+  entries: z.array(z.unknown()),
+});
+
+export const composeChangeSetContract = activityContract(
+  "composeChangeSet",
+  z.strictObject({ parts: z.array(changeSetPart) }),
+  z.object({ document: z.record(z.string(), z.unknown()), digest: z.string(), summary: z.record(z.string(), z.unknown()) }),
+);
+
+export const lifecyclePlanChangeSetContract = activityContract(
+  "lifecyclePlanChangeSet",
+  z.strictObject({ member: z.string(), env: z.string(), cwd: z.string().optional(), owned: z.boolean().optional() }),
+  z.object({ part: changeSetPart }),
+);
+
+export const readChangeSetPartContract = activityContract(
+  "readChangeSetPart",
+  z.strictObject({ member: z.string(), planner: z.enum(["chant", "warden"]), file: z.string(), lexicon: z.string().optional() }),
+  z.object({ part: changeSetPart }),
+);
+
 export const releasePlanContract = activityContract(
   "releasePlan",
   z.strictObject({
@@ -356,3 +379,64 @@ export const releaseRollbackRecordContract = activityContract(
   }),
   z.object({ recorded: z.boolean(), digest: z.string(), env: z.string(), component: z.string(), approver: z.string().nullable() }),
 );
+
+/**
+ * The factory reference Op's activities (#3406, ws-087, ./factory.ts).
+ * OPS013 checks a later step's reference into each result, so `factoryOp`'s
+ * wiring (ask into build, build into check, all three into record) is
+ * validated at `chant build`.
+ */
+const factoryLease = z.unknown();
+const factoryBackends = z.record(z.string(), backendSchema).optional();
+
+export const factoryPickContract = activityContract(
+  "factoryPick",
+  z.strictObject({ cwd: z.string().optional(), kind: z.string().optional() }),
+  z.strictObject({
+    candidates: z.array(z.string()),
+    held: z.array(z.object({ item: z.string(), hold: z.string(), message: z.string() })),
+    keys: z.array(z.string()),
+  }),
+);
+
+export const factoryReadyContract = activityContract(
+  "factoryReady",
+  z.strictObject({ cwd: z.string().optional(), kind: z.string().optional(), also: z.string().optional() }),
+  z.array(z.string()),
+);
+
+export const factoryAskContract = activityContract(
+  "factoryAsk",
+  z.strictObject({ lease: factoryLease, cwd: z.string().optional(), kind: z.string().optional(), backends: factoryBackends }),
+  z.strictObject({
+    item: z.string(),
+    ask: z.boolean(),
+    tier: z.string(),
+    understand: z.string().nullable(),
+    outcome: z.enum(["dropped", "redraft", "ask"]).nullable(),
+  }),
+);
+
+export const factoryBuildContract = activityContract(
+  "factoryBuild",
+  z.strictObject({ lease: factoryLease, ask: z.unknown(), builder: z.string().min(1), context: z.string().optional(), cwd: z.string().optional() }),
+  z.strictObject({ ran: z.boolean(), finished: z.boolean(), exitCode: z.number().nullable(), reverted: z.array(z.string()), note: z.string(), report: z.record(z.string(), z.unknown()).nullable() }),
+);
+
+export const factoryCheckContract = activityContract(
+  "factoryCheck",
+  z.strictObject({ lease: factoryLease, build: z.unknown(), check: z.string().optional(), cwd: z.string().optional() }),
+  z.strictObject({ ran: z.boolean(), ok: z.boolean(), command: z.string().nullable(), evidence: z.array(z.string()), log: z.string().nullable(), report: z.record(z.string(), z.unknown()).nullable() }),
+);
+
+export const factoryRecordContract = activityContract(
+  "factoryRecord",
+  z.strictObject({ lease: factoryLease, ask: z.unknown(), build: z.unknown(), check: z.unknown(), after: z.string().optional(), cwd: z.string().optional() }),
+  z.strictObject({
+    outcome: z.enum(["done", "not_done", "dropped", "redraft", "ask"]),
+    reason: z.string().nullable(),
+    commit: z.string().nullable(),
+    implementsProposed: z.array(z.object({ decision: z.string(), paths: z.array(z.string()) })),
+  }),
+);
+

package/src/op/activities/change-set.ts

@@ -0,0 +1,114 @@
+/**
+ * Op activities for the change-set document (#3181).
+ *
+ * A combined run over several members plans each one in its own step, joins
+ * the parts with {@link composeChangeSet}, and binds its gate to the
+ * document's digest:
+ *
+ * ```ts
+ * phase("Plan", [
+ *   terraformPlan({ root: "estate", id: "estate" }),          // a choudoufu member
+ *   lifecyclePlanChangeSet({ member: "delivery", env: "prod", cwd: "delivery", id: "delivery" }),
+ *   readChangeSetPart({ member: "warden", planner: "warden", file: "warden.plan.json", id: "warden" }),
+ *   composeChangeSet({ parts: [estate.out.changeSet, delivery.out.part, warden.out.part], id: "change-set" }),
+ * ]),
+ * phase("Approve", [gate("approve-run", { plan: stepOutput("change-set", "digest") })]),
+ * ```
+ *
+ * Each activity here only reads: a plan, a file, or the parts it is handed.
+ */
+
+import { exec } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { promisify } from "node:util";
+import {
+  composeChangeSet as compose,
+  lifecyclePlanPart,
+  reconcilePlanPart,
+  type ChangeSetDocument,
+  type ChangeSetPart,
+  type ChangeSetSummary,
+} from "../../change-set";
+import type { ChangeSet as LifecycleChangeSet } from "../../lifecycle/change-set";
+import type { ChangeSet as ReconcileChangeSet } from "../../reconcile";
+import { CHANT_VERSION } from "../../cli/version";
+
+const execAsync = promisify(exec);
+
+export interface ComposeChangeSetArgs {
+  /** One part per member, usually step outputs: `terraformPlan`'s `changeSet`, the other activities' `part`. */
+  parts: ChangeSetPart[];
+}
+
+export interface ComposeChangeSetResult {
+  document: ChangeSetDocument;
+  /** The document's digest. A gate's `plan` binds it. */
+  digest: string;
+  summary: ChangeSetSummary;
+}
+
+/** Join members' parts into one change-set document. Fails when two parts name the same member. */
+export async function composeChangeSet(args: ComposeChangeSetArgs): Promise<ComposeChangeSetResult> {
+  const parts = args.parts ?? [];
+  const missing = parts.findIndex((p) => !p || typeof p !== "object" || !p.member);
+  if (missing !== -1) throw new Error(`composeChangeSet: parts[${missing}] is not a change-set part; did the step that plans it run?`);
+  const document = compose(parts, { chant: CHANT_VERSION });
+  return { document, digest: document.digest, summary: document.summary };
+}
+
+export interface LifecyclePlanChangeSetArgs {
+  /** The workspace member the plan is of. */
+  member: string;
+  env: string;
+  /** The member's directory. Default: the current directory. */
+  cwd?: string;
+  /** Pass `--owned`, so owned resources missing from source plan as deletes. */
+  owned?: boolean;
+}
+
+export interface ChangeSetPartResult {
+  part: ChangeSetPart;
+}
+
+function shellQuote(s: string): string {
+  return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+
+/** `chant lifecycle plan <env> --json` in a chant member's directory, as that member's change-set part. */
+export async function lifecyclePlanChangeSet(args: LifecyclePlanChangeSetArgs, signal?: AbortSignal): Promise<ChangeSetPartResult> {
+  const { stdout } = await execAsync(`chant lifecycle plan ${shellQuote(args.env)}${args.owned ? " --owned" : ""} --json`, {
+    cwd: args.cwd ? resolve(args.cwd) : process.cwd(),
+    signal,
+    maxBuffer: 64 * 1024 * 1024,
+  });
+  return { part: lifecyclePlanPart({ member: args.member, plan: JSON.parse(stdout) as LifecycleChangeSet }) };
+}
+
+export interface ReadChangeSetPartArgs {
+  member: string;
+  /** Which planner wrote the file: `chant` (`lifecycle plan --json`) or `warden` (its reconcile change sets). */
+  planner: "chant" | "warden";
+  /** The plan file, relative to the current directory. */
+  file: string;
+  /** The lexicon the entries belong to, when the plan does not say. */
+  lexicon?: string;
+}
+
+/**
+ * A plan another step or job wrote to a file, as a member's part. A warden
+ * plan is the reconcile `ChangeSet` (`@intentius/chant/reconcile`), or an
+ * array of them, one per cycle and org.
+ */
+export async function readChangeSetPart(args: ReadChangeSetPartArgs): Promise<ChangeSetPartResult> {
+  const plan: unknown = JSON.parse(readFileSync(resolve(args.file), "utf-8"));
+  const lexicon = args.lexicon !== undefined ? { lexicon: args.lexicon } : {};
+  switch (args.planner) {
+    case "chant":
+      return { part: lifecyclePlanPart({ member: args.member, plan: plan as LifecycleChangeSet, ...lexicon }) };
+    case "warden":
+      return { part: reconcilePlanPart({ member: args.member, plan: plan as ReconcileChangeSet | ReconcileChangeSet[], ...lexicon }) };
+    default:
+      throw new Error(`readChangeSetPart: no adapter for planner ${String(args.planner)}; terraform-family plans come from terraformPlan's changeSet`);
+  }
+}

package/src/op/activities/decide.ts

@@ -84,6 +84,8 @@ export interface DecideResult {
   backend: string | null;
   confidence: number | null;
   threshold: number | null;
+  /** For a model's answer: the model's own explanation of it, when the backend gave one (#3345). */
+  reason: string | null;
   /** The people who answered, when people did. */
   answeredBy: string[];
   /** Each decider that was asked and did not answer, and why. */
@@ -159,6 +161,7 @@ function result(q: QuestionView, missing: string[]): DecideResult {
     backend: byModel ? (q.model?.backend ?? null) : null,
     confidence: byModel ? q.confidence : null,
     threshold: byModel ? q.threshold : null,
+    reason: byModel ? q.reason : null,
     answeredBy: q.answeredBy,
     escalations: q.escalations,
     missing,