@intentius/chant 0.101.0 → 0.104.0

package/src/cli/handlers/lifecycle.test.ts

@@ -97,6 +97,19 @@ function makeBuildResult(entitiesByLexicon: Record<string, string[]>): BuildResu
   } as unknown as BuildResult;
 }
 
+/**
+ * #3001 — a build holding one resource and one property-kind declarable that
+ * the resource inlines, the shape every grafana dashboard with exported panels
+ * has. Only the resource has a live counterpart of its own.
+ */
+function buildWithPropertyKind(lexicon: string): BuildResult {
+  const build = makeBuildResult({ [lexicon]: ["board"] });
+  const panel = { lexicon, entityType: `${lexicon}::Panel`, kind: "property", props: { title: "CPU" } };
+  build.entities.set("board", { lexicon, entityType: `${lexicon}::Board`, kind: "resource", props: { panels: [panel] } } as never);
+  build.entities.set("cpuPanel", panel as never);
+  return build;
+}
+
 const meta = (overrides: Partial<ResourceMetadata> = {}): ResourceMetadata => ({
   type: "AWS::S3::Bucket",
   status: "CREATE_COMPLETE",
@@ -537,6 +550,37 @@ describe("runLifecycleDiff --live", () => {
   });
 
   // #1014 — property-level drift, gated purely on the deep capability.
+  test("hands only resource-kind entities to describeResources and observeResourcesDeep (#3001)", async () => {
+    buildMock.mockResolvedValue(buildWithPropertyKind("graf"));
+    fetchLifecycleMock.mockResolvedValue(undefined);
+    readSnapshotMock.mockResolvedValue(null);
+    const seen: { thin?: string[]; deep?: string[] } = {};
+    const plugins: LexiconPlugin[] = [
+      createMockPlugin({
+        name: "graf",
+        describeResources: async (opts) => {
+          seen.thin = [...opts.entities.keys()];
+          return { board: meta({ type: "graf::Board", physicalId: "uid-1" }) };
+        },
+        observeResourcesDeep: async (opts) => {
+          seen.deep = [...opts.entities.keys()];
+          return deepObservation({ board: { type: "graf::Board", properties: { panels: [{ title: "CPU" }] } } });
+        },
+      }),
+    ];
+    const exit = await runLifecycleDiff({
+      args: makeArgs({ path: "diff", extraPositional: "prod", live: true }),
+      plugins,
+      serializers: plugins.map((p) => p.serializer),
+    });
+    expect(exit).toBe(0);
+    expect(seen.thin).toEqual(["board"]);
+    expect(seen.deep).toEqual(["board"]);
+    const stdout = stdoutBuf.join("\n");
+    expect(stdout).not.toContain("cpuPanel");
+    expect(stdout).toContain("0 missing");
+  });
+
   describe("deep observation (#1014)", () => {
     const withDeep = (over: Parameters<typeof createMockPlugin>[0] = {}) =>
       createMockPlugin({
@@ -872,6 +916,29 @@ describe("runLifecyclePlan", () => {
     expect(stdoutBuf.join("\n")).toContain("bucket");
   });
 
+  test("proposes no create for a property-kind declarable its parent inlines (#3001)", async () => {
+    buildMock.mockResolvedValue(buildWithPropertyKind("graf"));
+    let names: string[] = [];
+    const plugins: LexiconPlugin[] = [
+      createMockPlugin({
+        name: "graf",
+        describeResources: async (opts) => {
+          names = opts.entityNames;
+          return { board: meta({ type: "graf::Board", physicalId: "uid-1" }) };
+        },
+      }),
+    ];
+    const exit = await runLifecyclePlan({
+      args: makeArgs({ path: "plan", extraPositional: "prod", json: true }),
+      plugins,
+      serializers: plugins.map((p) => p.serializer),
+    });
+    expect(exit).toBe(0);
+    expect(names).toEqual(["board"]);
+    const plan = JSON.parse(stdoutBuf.join("\n"));
+    expect(plan.entries.map((e: { name: string }) => e.name)).not.toContain("cpuPanel");
+  });
+
   // #1983 — `--report markdown` emits the reviewer-facing projection instead
   // of the human render, same as `--report gitlab-mr` swaps in the widget JSON.
   test("--report markdown emits the markdown projection instead of the human render", async () => {

package/src/cli/handlers/lifecycle.ts

@@ -42,7 +42,7 @@ import { unknownEnvError, isProdLikeEnvironment } from "../../env";
 import { planTeardown, executeTeardown, type TeardownPlan, type TeardownReport } from "../../lifecycle/teardown";
 import { collectBuildRootContributors } from "../plugins";
 import { applyLiveEndpoint } from "../../live-endpoint";
-import { isResourceDeclarable } from "../../declarable";
+import { isObservableDeclarable } from "../../declarable";
 import { formatError, formatWarning, formatSuccess, formatBold } from "../format";
 import type { CommandContext } from "../registry";
 import type { LifecycleSnapshot } from "../../lifecycle/types";
@@ -812,13 +812,14 @@ async function runLifecycleDiffLive(args: LiveDiffArgs): Promise<LiveDiffOutcome
     }
 
     // Build per-lexicon entity index. Resource declarables only — outputs,
-    // parameters and serializer directives have no live counterpart, and a
+    // parameters, serializer directives and property-kind declarables (read
+    // inside their parent, #3001) have no live counterpart of their own, and a
     // declared name the reader can never resolve reads as missing (see
     // lifecycle/observe.ts).
     const declared = new Set<string>();
     const entities: DeclaredEntities = new Map();
     for (const [name, entity] of args.buildResult.entities) {
-      if (entity.lexicon === lexiconName && isResourceDeclarable(entity)) {
+      if (entity.lexicon === lexiconName && isObservableDeclarable(entity)) {
         declared.add(name);
         // Path origins are carried across explicitly (#1443): this map is plain
         // objects, and the symbol-keyed provenance channel does not survive it.
@@ -1289,11 +1290,11 @@ export async function runLifecyclePlan(ctx: CommandContext): Promise<number> {
         // A receipt has no `props` payload of its own but is declared, diffed,
         // and observed like any resource (#1832) — it joins the declared axis
         // so its lexicon's observation can confirm presence or absence.
-        if (entity.lexicon === lexiconName && (isResourceDeclarable(entity) || isEffectReceipt(entity))) {
+        if (entity.lexicon === lexiconName && (isObservableDeclarable(entity) || isEffectReceipt(entity))) {
           declared.add(name);
           entities.set(name, {
             entityType: entity.entityType,
-            props: (isResourceDeclarable(entity) && entity.props != null ? entity.props : {}) as Record<string, unknown>,
+            props: (isObservableDeclarable(entity) && entity.props != null ? entity.props : {}) as Record<string, unknown>,
           });
         }
       }

package/src/cli/handlers/misc.ts

@@ -324,6 +324,7 @@ export async function runImport(ctx: CommandContext): Promise<number> {
       lexicon: "k8s",
       output: args.output,
       force: args.force,
+      parserOptions: args.parserOption,
     });
     printImportResult(result);
     return result.success ? 0 : 1;
@@ -381,6 +382,7 @@ export async function runImport(ctx: CommandContext): Promise<number> {
     output: ctx.args.output,
     force: ctx.args.force,
     lexicon: ctx.args.lexicon,
+    parserOptions: ctx.args.parserOption,
   });
 
   printImportResult(result);

package/src/cli/handlers/operator.test.ts

@@ -455,6 +455,27 @@ describe("runApprove", () => {
     vi.unstubAllEnvs();
   });
 
+  // #3402 — a relayed approval names who relayed it, typed, not in --note.
+  test("--relayed-by is recorded on the resolution line, and a blank one is refused", async () => {
+    seedPending("fountain-apply", "rollout-gate", PLAN_A);
+    appendGateResolutionMock.mockResolvedValue({
+      commit: "sha",
+      record: { version: 1, op: "fountain-apply", gate: "rollout-gate", resolvedBy: "github:alice", relayedBy: "github:hud-follower", timestamp: "2026-01-01T00:00:00.000Z" },
+    });
+    const errSpy = vi.spyOn(console, "error").mockImplementation(() => undefined);
+
+    expect(await runApprove(ctx({ path: "fountain-apply", extraPositional: "rollout-gate", actor: "github:alice", relayedBy: "github:hud-follower" }))).toBe(0);
+    expect(appendGateResolutionMock).toHaveBeenCalledWith(
+      expect.objectContaining({ resolvedBy: "github:alice", relayedBy: "github:hud-follower" }),
+    );
+    expect(errSpy.mock.calls.flat().join("\n")).toMatch(/resolved by github:alice, relayed by github:hud-follower,/);
+
+    appendGateResolutionMock.mockClear();
+    expect(await runApprove(ctx({ path: "fountain-apply", extraPositional: "rollout-gate", actor: "github:alice", relayedBy: "a\nb" }))).toBe(1);
+    expect(appendGateResolutionMock).not.toHaveBeenCalled();
+    errSpy.mockRestore();
+  });
+
   test("without --url, the surrounding PR/MR job is itself the address", async () => {
     vi.stubEnv("GITHUB_SERVER_URL", "https://github.com");
     vi.stubEnv("GITHUB_REPOSITORY", "INTENTIUS/chant");

package/src/cli/handlers/operator.ts

@@ -9,7 +9,7 @@
 import { lexiconNames } from "../../lexicon-module";
 import { loadChantConfig } from "../../config";
 import { build } from "../../build";
-import { isResourceDeclarable } from "../../declarable";
+import { isObservableDeclarable } from "../../declarable";
 import { collectBuildRootContributors, collectChangeSubscribers } from "../plugins";
 import { discoverOps, discoverStewards } from "../../op/discover";
 import { pickSteward, stewardBesideOf, stewardFormFor, stewardLeaseName, stewardTurnOps, DEFAULT_STEWARD_ENV } from "../../op/steward";
@@ -116,7 +116,7 @@ async function collectOperatorSubscribers(
     // subscription may watch.
     const entities = new Map<string, Map<string, { entityType: string; props: Record<string, unknown> }>>();
     for (const [name, entity] of buildResult.entities) {
-      if (!isResourceDeclarable(entity)) continue;
+      if (!isObservableDeclarable(entity)) continue;
       let perLexicon = entities.get(entity.lexicon);
       if (!perLexicon) entities.set(entity.lexicon, (perLexicon = new Map()));
       perLexicon.set(name, {
@@ -134,6 +134,9 @@ async function collectOperatorSubscribers(
   }
 }
 
+/** A pull request's gate op, `pr-<number>` (#3183, `prOp` in ../../pr-loop.ts). */
+const PR_GATE_OP = /^pr-\d+$/;
+
 // ── chant operator ──────────────────────────────────────────────────────────
 
 /**
@@ -882,7 +885,9 @@ export async function runApprove(ctx: CommandContext): Promise<number> {
     console.error(formatInfo(
       opName === FAN_OUT_GATE_OP
         ? `The next \`chant components fan-out\` decides this gate from scratch and records a fresh pending fact.`
-        : opName === WORKSPACE_UPGRADE_GATE_OP
+        : PR_GATE_OP.test(opName)
+          ? `The next \`chant components pr-apply\` decides this gate from scratch and records a fresh pending fact.`
+          : opName === WORKSPACE_UPGRADE_GATE_OP
           ? `The next \`chant workspace upgrade ${gate}\` decides this gate from scratch and records a fresh pending fact.`
           : `The next \`chant run ${opName}\` decides this gate from scratch and records a fresh pending fact.`,
     ));
@@ -902,6 +907,8 @@ export async function runApprove(ctx: CommandContext): Promise<number> {
     allowSameOrigin: ctx.args.allowSameOrigin,
     ...(ctx.args.roles ? { roles: ctx.args.roles } : {}),
     ...(ctx.args.agent ? { agent: true } : {}),
+    ...(ctx.args.sign !== undefined ? { sign: ctx.args.sign } : {}),
+    ...(ctx.args.relayedBy !== undefined ? { relayedBy: ctx.args.relayedBy } : {}),
   });
   if (!outcome.ok) return 1;
 
@@ -909,7 +916,9 @@ export async function runApprove(ctx: CommandContext): Promise<number> {
     `This records the resolution as a fact; it does not itself re-run anything. ` +
       (opName === FAN_OUT_GATE_OP
         ? `Repeat the \`chant components fan-out\` command and it walks through gate "${gate}".`
-        : opName === WORKSPACE_UPGRADE_GATE_OP
+        : PR_GATE_OP.test(opName)
+          ? `The pull request's apply (\`chant components pr-apply\`) walks through gate "${gate}" when it plans this same digest.`
+          : opName === WORKSPACE_UPGRADE_GATE_OP
           ? `Repeat \`chant workspace upgrade ${gate}\` with the same target, and it applies the patch this approval names.`
           : `Run \`chant run ${opName}\` and it walks through gate "${gate}".`),
   ));
@@ -937,6 +946,13 @@ export interface GateApprovalOptions {
   actor?: string;
   /** `--note` — free-text prose. */
   note?: string;
+  /**
+   * `--relayed-by <principal>` (#3402): who carried this approval to chant for
+   * the approver, such as a follower program relaying a person's approval.
+   * Recorded as `relayedBy` on the resolution line and covered by `--sign`.
+   * The approver is still `--actor`; the relay is not an approver.
+   */
+  relayedBy?: string;
   /** `--url` — the approval surface, validated as absolute http/https. */
   url?: string;
   /**
@@ -959,6 +975,15 @@ export interface GateApprovalOptions {
    * model-authored channel it is one whether or not this is set.
    */
   agent?: boolean;
+  /**
+   * `--sign [<key file>]` (#3163, ws-080): seal the approval with an ssh key,
+   * a key file or true for git's `user.signingkey`. The seal attests the
+   * approver when the signers file at base lists the key for them, and a gate
+   * the declaration's `identity.gates` names counts only sealed approvals.
+   */
+  sign?: string | true;
+  /** Where the workspace and the key file are looked up from. Defaults to the process's directory. */
+  cwd?: string;
   /** Replaces the lexicon evaluator a gate policy is loaded from. For tests. */
   evaluator?: GatePolicyEvaluator;
 }
@@ -1091,6 +1116,16 @@ export async function recordGateApproval(
     return { ok: false };
   }
 
+  // #3402: the relay is a principal, on one line (the seal's payload is LF-joined).
+  const relayedBy = opts.relayedBy?.trim();
+  if (opts.relayedBy !== undefined && (!relayedBy || /[\r\n]/.test(relayedBy))) {
+    console.error(formatError({
+      message: `--relayed-by needs one principal on one line (got ${JSON.stringify(opts.relayedBy)})`,
+      hint: "Name who relayed the approval, such as --relayed-by github:<login> or a principal the signers file lists.",
+    }));
+    return { ok: false };
+  }
+
   const resolvedBy = opts.actor
     ?? (isModelAuthored(origin)
       // A channel that cannot attest to a name does not get to write one down.
@@ -1107,6 +1142,81 @@ export async function recordGateApproval(
     ...(opts.roles && opts.roles.length > 0 ? { roles: [...new Set(opts.roles)] } : {}),
   };
 
+  // #3163, ws-080: the declaration at base may require a checkable approver
+  // (identity.attribution "identified") and a signed approval for this gate
+  // (identity.gates). Both are judged before anything is written.
+  const cwd = opts.cwd ?? process.cwd();
+  const identity = await import("../../workspace/identity");
+  const { scopeSource } = await import("../../workspace/write-scope");
+  const scope = scopeSource(cwd);
+  try {
+    identity.refuseUnidentified(scope, [resolvedBy], opts.actor !== undefined ? "--actor" : "the approver");
+    if (relayedBy) identity.refuseUnidentified(scope, [relayedBy], "--relayed-by");
+  } catch (err) {
+    if (!(err instanceof identity.IdentityError)) throw err;
+    console.error(formatError({
+      message: `Gate "${gate}" on "${opName}" was not approved: ${err.message}`,
+      hint: "Pass --actor <forge identity or signer>, as the surface that signed the person in maps them, for example --actor github:<login>.",
+    }));
+    return { ok: false };
+  }
+  const rule = identity.gateAdmissionFrom(scope, gate);
+  if (rule && opts.sign === undefined) {
+    console.error(formatError({
+      message:
+        `Gate "${gate}" needs a signed approval: chant.workspace.json at base names it in identity.gates` +
+        (rule.requirement.class !== null ? `, from the class ${rule.requirement.class}` : "") +
+        `, and this approval is not signed`,
+      hint: `chant approve ${opName} ${gate} --actor <principal> --sign [<key file>], with a key ${scope.policy.signersPath} at base lists for that principal.`,
+    }));
+    return { ok: false };
+  }
+  const timestamp = new Date().toISOString();
+  let seal: GateResolutionRecord["seal"];
+  if (opts.sign !== undefined) {
+    const { resolveSigningKey, sealGateApproval, SealError } = await import("../../workspace/trust/seal");
+    try {
+      const key = resolveSigningKey(opts.sign, cwd);
+      try {
+        seal = sealGateApproval(key.file, {
+          op: opName,
+          gate,
+          ...(environment !== undefined ? { environment } : {}),
+          ...(planDigest !== undefined ? { planDigest } : {}),
+          resolvedBy,
+          ...(relayedBy ? { relayedBy } : {}),
+          timestamp,
+        });
+      } finally {
+        key.cleanup();
+      }
+    } catch (err) {
+      if (!(err instanceof SealError)) throw err;
+      console.error(formatError({ message: `Gate "${gate}" on "${opName}" was not approved: ${err.message}` }));
+      return { ok: false };
+    }
+  }
+  if (rule) {
+    const why = rule.refuses({
+      op: opName,
+      gate,
+      ...(environment !== undefined ? { environment } : {}),
+      ...(planDigest !== undefined ? { planDigest } : {}),
+      resolvedBy,
+      ...(relayedBy ? { relayedBy } : {}),
+      timestamp,
+      seal,
+    });
+    if (why !== null) {
+      console.error(formatError({
+        message: `Gate "${gate}" on "${opName}" was not approved: ${why}`,
+        hint: `identity.gates.${gate} in chant.workspace.json at base counts only an approval signed by a key ${scope.policy.signersPath} lists for the approver` +
+          (rule.requirement.class !== null ? `, who holds the role of the class ${rule.requirement.class}` : "") + ".",
+      }));
+      return { ok: false };
+    }
+  }
+
   // #2508: a gate with a policy has it evaluated for this approval now, while
   // the approver is known, against the context the gated run recorded. The
   // decision is written next to the approval, so a pass can be traced to the
@@ -1148,7 +1258,9 @@ export async function recordGateApproval(
     op: opName,
     gate,
     resolvedBy,
-    timestamp: new Date().toISOString(),
+    ...(relayedBy ? { relayedBy } : {}),
+    timestamp,
+    ...(seal ? { seal } : {}),
     approver,
     ...(policyDecision ? { policyDecision } : {}),
     ...(opts.note ? { note: opts.note } : {}),
@@ -1164,8 +1276,11 @@ export async function recordGateApproval(
   );
 
   console.error(formatSuccess(
-    `Gate "${gate}" on "${opName}" resolved by ${record.resolvedBy} at ${record.timestamp}` +
+    `Gate "${gate}" on "${opName}" resolved by ${record.resolvedBy}` +
+      (record.relayedBy ? `, relayed by ${record.relayedBy},` : "") +
+      ` at ${record.timestamp}` +
       (record.url ? ` (${record.url})` : "") +
+      (record.seal ? `, signed with ${record.seal.key}` : "") +
       (pushed ? "" : " (local only — the push did not land)"),
   ));
   if (record.planDigest) {