@intentius/chant 0.100.0 → 0.102.0

package/src/fold-provenance.test.ts

@@ -508,3 +508,143 @@ describe("fold provenance over a real composite build (#2161)", () => {
     expect(verdicts[3].resolution.kind).toBe("edit-declaration");
   });
 });
+
+// ─────────────────────────────────────────────────────────────────────────
+// chant #3212 — a registered tag inside a composite factory.
+// ─────────────────────────────────────────────────────────────────────────
+
+const runtimePath = resolve(thisDir, "./runtime");
+const provenancePath = resolve(thisDir, "./provenance");
+
+/**
+ * A SQL-shaped tag, the shape the sql lexicon's `table` takes: it builds one
+ * entity out of its text and reports, per interpolation, which of the entity's
+ * fields that interpolation fed. An interpolated entity is a reference and
+ * feeds nothing the author typed, so it reports no field.
+ */
+const TAGS = `
+  import { createResource } from ${JSON.stringify(runtimePath)};
+  import { setInterpolationFields } from ${JSON.stringify(provenancePath)};
+  const Table = createResource("Test::Table", ${JSON.stringify(LEXICON_NAME)}, {});
+  const CLAUSE = { TABLE: "name", "ENGINE =": "engine", "ORDER BY": "orderBy", TTL: "ttl", COMMENT: "comment" };
+
+  export function table(strings, ...values) {
+    const isEntity = (v) => typeof v === "object" && v !== null && "props" in v;
+    let ddl = strings[0];
+    const fields = values.map((v, i) => {
+      ddl += (isEntity(v) ? v.props.name : String(v)) + strings[i + 1];
+      if (isEntity(v)) return [];
+      const at = (k) => strings[i].lastIndexOf(k);
+      const clause = Object.keys(CLAUSE).sort((a, b) => at(b) - at(a))[0];
+      return at(clause) >= 0 ? [CLAUSE[clause], "ddl"] : ["ddl"];
+    });
+    const m = /CREATE TABLE (\\w+) ENGINE = (\\w+) ORDER BY (\\w+)(?: TTL (.+?))?(?: COMMENT (\\w+))?$/.exec(ddl);
+    if (!m) throw new Error("cannot parse: " + ddl);
+    const props = { name: m[1], engine: m[2], orderBy: m[3], ddl };
+    if (m[4]) props.ttl = m[4];
+    if (m[5]) props.comment = m[5];
+    const entity = new Table(props);
+    setInterpolationFields(entity, fields);
+    return entity;
+  }
+`;
+
+const TAG_COMPOSITES = `
+  import { table } from "./tags";
+  import { Composite } from ${JSON.stringify(compositePath)};
+
+  export const EventsTable = Composite((props) => {
+    const rollupName = \`\${props.name}_daily\`;
+    const events = table\`CREATE TABLE \${props.name} ENGINE = MergeTree ORDER BY ts TTL ts + INTERVAL \${props.ttlDays} DAY\`;
+    const rollup = table\`CREATE TABLE \${rollupName} ENGINE = \${"SummingMergeTree"} ORDER BY ts COMMENT \${events}\`;
+    return { events, rollup };
+  }, "EventsTable");
+`;
+
+const TAG_MAIN = `
+  import { table } from "../tags";
+  import { EventsTable } from "../composites";
+
+  export const audit = table\`CREATE TABLE audit ENGINE = MergeTree ORDER BY ts\`;
+  export const clicks = EventsTable({ name: "clicks", ttlDays: 30 });
+`;
+
+describe("fold provenance through a tagged template in a composite factory (#3212)", () => {
+  let testDir: string;
+  let srcDir: string;
+
+  beforeEach(async () => {
+    const dir = join(repoRoot, ".cache", `chant-3212-${process.pid}-${seq++}`);
+    await rm(dir, { recursive: true, force: true });
+    await mkdir(dir, { recursive: true });
+    testDir = await realpath(dir);
+    srcDir = join(testDir, "src");
+    await mkdir(srcDir, { recursive: true });
+    await writeFile(join(testDir, "tags.ts"), TAGS);
+    await writeFile(join(testDir, "composites.ts"), TAG_COMPOSITES);
+    await writeFile(join(srcDir, "main.ts"), TAG_MAIN);
+  });
+
+  afterEach(async () => {
+    await rm(testDir, { recursive: true, force: true });
+  });
+
+  const buildIt = () =>
+    build(srcDir, [namesSerializer], undefined, {
+      fold: true,
+      lexicons: [LEXICON_NAME],
+      intrinsics: [{ name: "table", isTag: true }],
+    });
+
+  test("a field fed by ${props.x} is that parameter, a field the text fixes is a literal", async () => {
+    const result = await buildIt();
+    expect(result.errors).toEqual([]);
+    const events = result.foldProvenance.clicksEvents;
+    const rollup = result.foldProvenance.clicksRollup;
+    const at = (parameters: string[]) => ({ kind: "composite-parameter", composite: "EventsTable", instance: "clicks", parameters });
+    const fixed = { kind: "composite-literal", composite: "EventsTable", instance: "clicks" };
+
+    expect(events.fields.name).toEqual(at(["name"]));
+    expect(events.fields.ttl).toEqual(at(["ttlDays"]));
+    expect(events.fields.ddl).toEqual(at(["name", "ttlDays"]));
+    expect(events.fields.engine).toEqual(fixed);
+    expect(events.fields.orderBy).toEqual(fixed);
+
+    // Through a body `const`; an interpolated literal string is fixed; an
+    // interpolated sibling entity is wiring, so it governs nothing.
+    expect(rollup.fields.name).toEqual(at(["name"]));
+    expect(rollup.fields.engine).toEqual(fixed);
+    expect(rollup.fields.comment).toEqual(fixed);
+    expect(rollup.fields.ddl).toEqual(at(["name"]));
+
+    expect(result.foldProvenance.audit.fields.ttl).toBeUndefined();
+    expect(result.foldProvenance.audit.fields.name).toEqual({ kind: "direct" });
+  });
+
+  test("drift on a parameter-fed field proposes the parameter at the call site", async () => {
+    const result = await buildIt();
+    const provenanceOf = (name: string): EntityProvenance | undefined => {
+      const entity = result.entities.get(name);
+      return entity ? getProvenance(entity) : undefined;
+    };
+    const drift = (name: string, path: string, declared: unknown, live: unknown): DeepEntityDrift => {
+      const origin = originOfPath(provenanceOf(name)?.paths, path);
+      return { name, type: "Test::Table", changes: [{ path, kind: "changed", declared, live, ...(origin ? { origin } : {}) }] };
+    };
+
+    const [ttl, engine] = resolveDeepDrift(
+      [
+        drift("clicksEvents", "ttl", "ts + INTERVAL 30 DAY", "ts + INTERVAL 90 DAY"),
+        drift("clicksEvents", "engine", "MergeTree", "ReplacingMergeTree"),
+      ],
+      provenanceOf,
+    );
+
+    expect(ttl.resolution.kind).toBe("propose-parameter");
+    if (ttl.resolution.kind !== "propose-parameter") throw new Error("unreachable");
+    expect(ttl.resolution.parameters).toEqual(["ttlDays"]);
+    expect(ttl.resolution.instance).toBe("clicks");
+    expect(ttl.resolution.sourceFile).toContain("main.ts");
+    expect(engine.resolution.kind).toBe("refuse-fixed");
+  });
+});

package/src/graph-ir.test.ts

@@ -287,3 +287,86 @@ describe("entity-declared references and stacks", () => {
     expect(ir.nodes.find((n) => n.id === "app/vpc")!.attrs).not.toHaveProperty("stack");
   });
 });
+
+describe("whole declarables held in an entity's fields (#3257)", () => {
+  /** An entity shaped like the sql lexicon's: props non-enumerable, `dependsOn` enumerable. */
+  function holder(dependsOn: unknown[], extra: object = {}) {
+    const e = decl({ lexicon: "sql", entityType: "ClickHouse::Table", ...extra });
+    Object.defineProperty(e, "dependsOn", { value: dependsOn, enumerable: true });
+    return e;
+  }
+
+  test("draws an edge to each node named directly in an enumerable array", () => {
+    const db = decl({ lexicon: "sql", entityType: "ClickHouse::Database" });
+    const target = holder([db]);
+    const events = holder([db]);
+    const mv = holder([db, target, events]);
+    const entities = new Map<string, Declarable>([
+      ["analytics", db],
+      ["dailyActive", target],
+      ["events", events],
+      ["dailyActiveMv", mv],
+    ]);
+    resolveAttrRefs(entities);
+
+    const ir = buildGraphIr(entities);
+    const dep = (from: string, to: string) => ({ from, to, kind: "ref", viaAttr: "dependsOn" });
+    expect(ir.edges).toEqual([
+      dep("dailyActive", "analytics"),
+      dep("dailyActiveMv", "analytics"),
+      dep("dailyActiveMv", "dailyActive"),
+      dep("dailyActiveMv", "events"),
+      dep("events", "analytics"),
+    ]);
+  });
+
+  test("does not walk into the referenced node, and projects it as a $ref", () => {
+    const db = decl({ lexicon: "sql", entityType: "ClickHouse::Database", props: { name: "analytics" } });
+    const events = holder([db]);
+    const entities = new Map<string, Declarable>([
+      ["analytics", db],
+      ["events", events],
+    ]);
+    resolveAttrRefs(entities);
+
+    const ir = buildGraphIr(entities);
+    expect(ir.nodes.find((n) => n.id === "events")!.attrs.dependsOn).toEqual([{ $ref: "analytics" }]);
+  });
+
+  test("an AttrRef and the whole node to the same target collapse to one edge", () => {
+    const db = decl({ lexicon: "sql", entityType: "ClickHouse::Database" });
+    const events = decl({ lexicon: "sql", entityType: "ClickHouse::Table" });
+    const mv = holder([events, new AttrRef(events, "user_id")]);
+    const entities = new Map<string, Declarable>([
+      ["analytics", db],
+      ["events", events],
+      ["mv", mv],
+    ]);
+    resolveAttrRefs(entities);
+
+    const ir = buildGraphIr(entities);
+    expect(ir.edges).toEqual([{ from: "mv", to: "events", kind: "ref", viaAttr: "dependsOn" }]);
+  });
+
+  test("ignores a self reference, and still descends into an inlined property-kind resource", () => {
+    const self: Declarable = holder([]);
+    (self as unknown as { dependsOn: unknown[] }).dependsOn.push(self);
+    const vpc = decl({ lexicon: "aws", entityType: "Vpc" });
+    const inline = decl({
+      lexicon: "aws",
+      entityType: "Listener_Action",
+      kind: "property",
+      props: { vpc: new AttrRef(vpc, "Id") },
+    });
+    const lb = decl({ lexicon: "aws", entityType: "Lb", props: { actions: [inline] } });
+    const entities = new Map<string, Declarable>([
+      ["self", self],
+      ["vpc", vpc],
+      ["lb", lb],
+    ]);
+    resolveAttrRefs(entities);
+
+    const ir = buildGraphIr(entities);
+    expect(ir.edges).toEqual([{ from: "lb", to: "vpc", kind: "ref", viaAttr: "actions" }]);
+  });
+});

package/src/graph-ir.ts

@@ -384,6 +384,23 @@ function refTarget(ref: AttrRef, reverse: Map<object, string>): string | undefin
   return ref.getLogicalName() ?? (parent ? reverse.get(parent) : undefined);
 }
 
+/**
+ * The node id a whole declarable held in a config bag stands for, or undefined
+ * when it is not a node of this graph (an inlined property-kind resource, say,
+ * which is config of the holder and gets walked instead). An entity can name
+ * another entity directly rather than through an AttrRef, as the sql lexicon's
+ * enumerable `dependsOn` does with the tables, views and databases a statement
+ * mentions (#3257); that is a reference to the node, not a nested bag.
+ */
+function nodeReference(
+  value: unknown,
+  reverse: Map<object, string>,
+  nodeIds: Set<string>,
+): string | undefined {
+  const id = reverse.get(value as object);
+  return id !== undefined && nodeIds.has(id) ? id : undefined;
+}
+
 /** Project a value into a JSON-safe, scrubbed form. References become `{ $ref }`. */
 function project(value: unknown, seen: Set<unknown>, reverse: Map<object, string>, nodeIds: Set<string>): unknown {
   if (value === null) return null;
@@ -414,6 +431,9 @@ function project(value: unknown, seen: Set<unknown>, reverse: Map<object, string
   // Nested declarables (e.g. an inlined property-kind resource) keep their
   // config in a non-enumerable `props` bag, like top-level nodes — project that.
   if (isDeclarable(value)) {
+    // Another node held whole is a reference to it, not config to inline.
+    const to = nodeReference(value, reverse, nodeIds);
+    if (to) return { $ref: to } satisfies AttrRefEnvelope;
     const out = projectConfig(value, seen, reverse, nodeIds);
     seen.delete(value);
     return out;
@@ -518,6 +538,15 @@ function collectEdges(
       if (to && to !== from && nodeIds.has(to)) edges.push({ from, to, kind: "ref", viaAttr });
       return;
     }
+    // A whole node held in props or an enumerable field (the sql lexicon's
+    // `dependsOn`) is a reference to it: draw the edge, and do not walk its
+    // config, whose refs belong to that node's own edges (#3257). Checked
+    // before `seen` so the same node under two attributes yields both edges.
+    const held = nodeReference(value, reverse, nodeIds);
+    if (held) {
+      if (held !== from) edges.push({ from, to: held, kind: "ref", viaAttr });
+      return;
+    }
     if (seen.has(value)) return;
     seen.add(value);
     // A nested declarable (an inlined property-kind resource, e.g. a listener's

package/src/import/embedded.test.ts

@@ -85,6 +85,26 @@ describe("EmbeddedImports", () => {
     ]);
   });
 
+  test("an importer that keeps matched content as written is not asked to import it, and its reason is the warning", () => {
+    let imported = 0;
+    const resolver = new EmbeddedImports([
+      {
+        lexicon: "acme",
+        importer: {
+          ...widgets,
+          keepsAsWritten: (c) => ((c.document as { size?: number }).size === 3 ? "a size-3 widget builds back as size 4" : undefined),
+          import: (c) => (imported++, widgets.import(c)),
+        },
+      },
+    ]);
+    expect(resolver.resolve(site())).toBeUndefined();
+    expect(imported).toBe(0);
+    expect(resolver.files).toEqual([]);
+    expect(resolver.warnings).toEqual(['ConfigMap agent data["config.yaml"] is a widget, kept as written: a size-3 widget builds back as size 4']);
+    expect(isEmbeddedReference(resolver.resolve(site({ text: "kind: widget\nsize: 2\n" })))).toBe(true);
+    expect(imported).toBe(1);
+  });
+
   test("when two lexicons match, the first imports it and the other is named", () => {
     const resolver = new EmbeddedImports([
       { lexicon: "acme", importer: widgets },

package/src/import/embedded.ts

@@ -102,6 +102,13 @@ export interface EmbeddedContentImporter {
   readonly what: string;
   /** Whether this content is one it imports. Must not throw on content that is not. */
   matches(content: EmbeddedContent): boolean;
+  /**
+   * Why content it matches is kept as written instead of imported, or
+   * `undefined` to import it. Asked before `import`; the reason is the
+   * warning's. grafana keeps a v2 dashboard, which it reads but would build
+   * back as v1 JSON (#3031).
+   */
+  keepsAsWritten?(content: EmbeddedContent): string | undefined;
   /** Import it. A throw keeps the content as written, with a warning. */
   import(content: EmbeddedContent): EmbeddedImport;
 }
@@ -233,6 +240,12 @@ export class EmbeddedImports implements EmbeddedContentResolver {
       );
     }
 
+    const kept = chosen.importer.keepsAsWritten?.(content);
+    if (kept !== undefined) {
+      this.warnings.push(`${content.location} is ${chosen.importer.what}, kept as written: ${kept}`);
+      return undefined;
+    }
+
     let result: EmbeddedImport;
     try {
       result = chosen.importer.import(content);

package/src/import/parser-options.ts

@@ -0,0 +1,46 @@
+import type { LexiconPlugin } from "../lexicon";
+import type { ParserOptions, ParserOptionSpec } from "./parser";
+
+/**
+ * Check `--parser-option` entries (`key` or `key=value`) against what the
+ * lexicon declares in `parserOptions()` and convert each value to its declared
+ * type (#2994). Returns the options, or an error message naming what is wrong
+ * and what the lexicon accepts. An empty list is always valid.
+ */
+export function resolveParserOptions(
+  plugin: Pick<LexiconPlugin, "name" | "parserOptions">,
+  entries: readonly string[] | undefined,
+): { options: ParserOptions } | { error: string } {
+  const options: ParserOptions = {};
+  if (!entries || entries.length === 0) return { options };
+
+  const specs: ParserOptionSpec[] = plugin.parserOptions?.() ?? [];
+  const accepted =
+    specs.length === 0
+      ? `lexicon "${plugin.name}" declares no parser options`
+      : `${plugin.name} accepts: ${specs.map((s) => `${s.name} (${s.type}): ${s.description}`).join("; ")}`;
+
+  for (const entry of entries) {
+    const eq = entry.indexOf("=");
+    const name = eq === -1 ? entry : entry.slice(0, eq);
+    const raw = eq === -1 ? undefined : entry.slice(eq + 1);
+    const spec = specs.find((s) => s.name === name);
+    if (!spec) {
+      return { error: `Unknown parser option "${name}" for lexicon "${plugin.name}"; ${accepted}.` };
+    }
+    if (spec.type === "boolean") {
+      if (raw === undefined || raw === "true") options[name] = true;
+      else if (raw === "false") options[name] = false;
+      else return { error: `Parser option "${name}" is a boolean: use ${name}, ${name}=true or ${name}=false, got "${raw}".` };
+    } else if (raw === undefined) {
+      return { error: `Parser option "${name}" needs a value: --parser-option ${name}=<${spec.type}>.` };
+    } else if (spec.type === "number") {
+      const n = Number(raw);
+      if (raw.trim() === "" || !Number.isFinite(n)) return { error: `Parser option "${name}" is a number, got "${raw}".` };
+      options[name] = n;
+    } else {
+      options[name] = raw;
+    }
+  }
+  return { options };
+}

package/src/import/parser.ts

@@ -78,6 +78,26 @@ export interface ParseContext {
   readonly embedded?: EmbeddedContentResolver;
 }
 
+/** A value a parser option takes. */
+export type ParserOptionValue = string | number | boolean;
+
+/** The options `chant import --parser-option` hands a lexicon's parser, by name. */
+export type ParserOptions = Record<string, ParserOptionValue>;
+
+/**
+ * One option a lexicon's parser accepts, declared by `LexiconPlugin.parserOptions()`.
+ * `chant import --parser-option <name>[=<value>]` is checked against this list and
+ * the value is converted to `type` before `templateParser(options)` sees it.
+ */
+export interface ParserOptionSpec {
+  /** The key after `--parser-option`, e.g. "acceptLossyV1". */
+  name: string;
+  /** `boolean` takes `true`/`false`, and a bare `--parser-option name` means true. */
+  type: "boolean" | "string" | "number";
+  /** One line, shown when the option is refused and in the docs. */
+  description: string;
+}
+
 /**
  * Interface for template parsers that convert external formats to IR
  */

package/src/lexicon.ts

@@ -3,7 +3,7 @@ import type { Declarable } from "./declarable";
 import type { LintRule } from "./lint/rule";
 import type { RuleSpec } from "./lint/declarative";
 import type { PostSynthCheck } from "./lint/post-synth";
-import type { TemplateParser, TemplateIR } from "./import/parser";
+import type { TemplateParser, TemplateIR, ParseContext, ParserOptions, ParserOptionSpec } from "./import/parser";
 import type { TypeScriptGenerator } from "./import/generator";
 import type { EmbeddedContentImporter } from "./import/embedded";
 import type { AgentConfigImporter } from "./agents/importer";
@@ -426,12 +426,26 @@ export interface InitTemplateSet {
  * repos or version-constant locations. See ./codegen/pinned-upgrade.ts.
  */
 export interface UpstreamPin {
+  /**
+   * Short name for this pin (`clickhouse`, `postgres-17`), used to pick one
+   * pin of a plugin that declares several (`chant dev pinned-upgrade <dir>
+   * <label>`). Optional on a lone `upstreamPin`, where it defaults to the
+   * lexicon's name; required on every entry of `upstreamPins`.
+   */
+  readonly label?: string;
   /** Source file (relative to the lexicon package root) holding the pinned version constant. */
   readonly file: string;
   /** Regex whose first capture group is the current pinned version in `file`. */
   readonly pattern: RegExp;
   /** Rebuild a line that matched `pattern`, substituting the new version. */
   replace(newVersion: string, line: string): string;
+  /**
+   * Set when the version line is not the whole pin: other constants (an image
+   * digest, a checksum) move with it and `replace` cannot compute them. The
+   * upgrade tooling then reports the newer version and this text, and edits
+   * nothing. Say what to move and how.
+   */
+  readonly alsoMoves?: string;
   /** Where to query for the latest stable upstream tag. */
   readonly upstream: {
     readonly owner: string;
@@ -440,6 +454,25 @@ export interface UpstreamPin {
     readonly kind: "releases" | "tags";
     /** Only consider tags ending with this suffix (e.g. "-ee" for GitLab). */
     readonly tagSuffix?: string;
+    /**
+     * Map a raw tag to the version string the pin stores, or null to skip the
+     * tag. For upstreams whose tags are not versions: postgres/postgres tags
+     * are `REL_18_6`, `REL_18_BETA1`, `REL9_6_24`, so
+     * `(t) => /^REL_(\d+)_(\d+)$/.exec(t)?.slice(1).join(".") ?? null` gives
+     * `18.6` and drops betas, release candidates and the old spelling.
+     *
+     * When set, the tool reads every page of the tag list (not just the first
+     * 50), because such lists are not ordered by version, and the version this
+     * returns is what `replace` receives and what the report shows. The pinned
+     * constant may hold either the mapped version or the raw tag.
+     */
+    readonly tagVersion?: (tag: string) => string | null;
+    /**
+     * Only consider versions whose first numeric segment equals the pinned
+     * version's, so a pin on `17.9` reports `17.11` and never `18.6`. For
+     * lexicons that pin one snapshot per major line. Default false.
+     */
+    readonly trackMajor?: boolean;
   };
 }
 
@@ -1160,8 +1193,19 @@ export interface LexiconPlugin {
    */
   detectTemplate?(data: unknown): boolean;
 
-  /** Return a parser for importing external templates into IR */
-  templateParser?(): TemplateParser;
+  /**
+   * Return a parser for importing external templates into IR. `options` holds
+   * the `chant import --parser-option` values, already checked against
+   * `parserOptions()` and converted to their declared types; it is empty when
+   * none were given.
+   */
+  templateParser?(options?: ParserOptions): TemplateParser;
+
+  /**
+   * The options `templateParser` accepts. `chant import --parser-option` refuses
+   * any name not listed here, so a lexicon with no options leaves this out.
+   */
+  parserOptions?(): ParserOptionSpec[];
 
   /** Return a generator for converting IR to TypeScript */
   templateGenerator?(): TypeScriptGenerator;
@@ -1200,6 +1244,14 @@ export interface LexiconPlugin {
   /** How this lexicon pins its upstream schema version + where to check for a newer one (self-upgrade tooling — see ./codegen/pinned-upgrade.ts). Omit for lexicons with no pinned upstream. */
   readonly upstreamPin?: UpstreamPin;
 
+  /**
+   * Further pins, for a lexicon that pins more than one upstream (sql: the
+   * ClickHouse pin in `upstreamPin` plus one Postgres server per major). Each
+   * entry needs a unique `label`. The upgrade tooling checks `upstreamPin` and
+   * every entry here, one report per pin. Omit when there is one pin.
+   */
+  readonly upstreamPins?: readonly (UpstreamPin & { readonly label: string })[];
+
   /**
    * Generate a CI pipeline from the discovered component graph — the
    * `chant build --components --generate <name>` seam. Only CI-provider
@@ -1259,6 +1311,22 @@ export interface LexiconPlugin {
    */
   buildRoots?(ctx: BuildRootContext): Promise<BuildRootContribution>;
 
+  /**
+   * Facts about the whole read that this lexicon's entities imply, for the
+   * graph IR's `meta` bag (#2559). The otel lexicon answers
+   * `{ collector: <topology> }`, which `chant workspace graph` lifts into its
+   * `collectors` section, so core carries the shape of the answer and never
+   * imports the lexicon that computes it.
+   *
+   * Called by `chant graph --format ir` with the discovered entities of the
+   * project, after the plugins are loaded. Return `undefined` or an empty
+   * object when the project declares nothing this lexicon reports; the IR is
+   * then unchanged. Keys must be unique to the lexicon (two lexicons writing
+   * one key is a conflict the graph refuses). Omit for lexicons with nothing
+   * to report.
+   */
+  graphMeta?(entities: ReadonlyMap<string, Declarable>): Record<string, unknown> | undefined;
+
   // LSP
   /** Provide completions for LSP */
   completionProvider?(ctx: CompletionContext): CompletionItem[];
@@ -1989,6 +2057,14 @@ export interface ResourceSelector {
 export type ExportedTemplate = TemplateIR & {
   /** Phantom marker — never present at runtime. */
   readonly __fidelity?: "full-config";
+  /**
+   * The same export parsed again with a {@link ParseContext}, from the
+   * objects already read: no second read of the live target. An exporter
+   * that maps through its import parser offers this so `chant import --from`
+   * can hand embedded content to the lexicon that owns it, as file import
+   * does (#2995). Without it, embedded content is kept as written.
+   */
+  readonly reparse?: (context: ParseContext) => TemplateIR;
 };
 
 /**

package/src/lifecycle/gate-ledger.test.ts

@@ -298,6 +298,20 @@ describe("latestResolutionForPlan (#2300)", () => {
     expect(found.mismatched).toBeUndefined();
   });
 
+  // #2547: plan digests carry a version prefix now. An approval written under
+  // the bare prefix is still an approval of the same plan.
+  test("a resolution recorded under the bare sha256: prefix answers the same plan's jcs1 digest", () => {
+    const found = latestResolutionForPlan([resolution({ planDigest: PLAN_A })], "approve-live-apply", EPOCH, `jcs1-${PLAN_A}`);
+    expect(found.resolution?.resolvedBy).toBe("alex");
+    expect(found.mismatched).toBeUndefined();
+  });
+
+  test("the prefix never makes a different plan match", () => {
+    const found = latestResolutionForPlan([resolution({ planDigest: PLAN_B })], "approve-live-apply", EPOCH, `jcs1-${PLAN_A}`);
+    expect(found.resolution).toBeUndefined();
+    expect(found.mismatched?.planDigest).toBe(PLAN_B);
+  });
+
   test("a resolution for another plan does not, and comes back named", () => {
     const found = latestResolutionForPlan([resolution({ planDigest: PLAN_B })], "approve-live-apply", EPOCH, PLAN_A);
     expect(found.resolution).toBeUndefined();

package/src/lifecycle/gate-ledger.ts

@@ -41,6 +41,7 @@
  * (absent on the resolution lines written before #2119, which is why
  * `"resolution"` is the default reading).
  */
+import { samePlanDigest } from "./plan-digest";
 import { sortedJsonReplacer } from "../utils";
 import { currentGateOrigin, type GateOrigin } from "./gate-origin";
 import type { GateApprover, GatePolicyDecision, ResolvedGateApproval } from "../op/gate-approval";
@@ -186,6 +187,22 @@ export interface GateResolutionRecord {
    * was recorded. Present only when the gate declared a policy.
    */
   policyDecision?: GatePolicyDecision;
+  /**
+   * An ssh signature over this approval by `resolvedBy` (#3163, ws-080):
+   * `chant approve --sign`, in the `chant-gate` namespace over the op, gate,
+   * environment, plan digest, approver and timestamp. It attests the approver
+   * only when the signers file at base lists a key for them. A gate the
+   * declaration's `identity.gates` names counts only approvals whose seal
+   * verifies. Absent on an unsigned approval.
+   */
+  seal?: GateApprovalSeal;
+}
+
+/** A gate approval's seal (#3163): who signed, the key's fingerprint (reported, never trusted), and the armored signature. */
+export interface GateApprovalSeal {
+  signer: string;
+  key: string;
+  signature: string;
 }
 
 export type GateResolutionInput = Omit<GateResolutionRecord, "version" | "kind">;
@@ -513,7 +530,7 @@ export function latestResolutionForPlan(
     if (new Date(r.timestamp).getTime() < since) continue;
     const newest = (best: GateResolutionRecord | undefined) =>
       !best || new Date(r.timestamp).getTime() >= new Date(best.timestamp).getTime();
-    if (r.planDigest === planDigest) {
+    if (samePlanDigest(r.planDigest, planDigest)) {
       if (newest(matched)) matched = r;
     } else if (newest(mismatched)) {
       mismatched = r;

package/src/lifecycle/observe.test.ts

@@ -97,6 +97,24 @@ describe("observeResources", () => {
     expect(names).toEqual(["web-vpc"]);
   });
 
+  it("keeps property-kind declarables out of the observation universe (#3001)", async () => {
+    // A property-kind declarable (a grafana panel, an aws SecurityGroup_Ingress
+    // const) carries props but lives only inside the resource holding it.
+    // Asked about on its own, a reader can only say "absent" or "not observed".
+    const buildResult = {
+      outputs: new Map<string, string>([["aws", "{}"]]),
+      entities: new Map<string, unknown>([
+        ["web-sg", { lexicon: "aws", entityType: "AWS::EC2::SecurityGroup", kind: "resource", props: {} }],
+        ["ingress", { lexicon: "aws", entityType: "AWS::EC2::SecurityGroup.Ingress", kind: "property", props: { FromPort: 443 } }],
+      ]),
+      errors: [],
+    } as unknown as BuildResult;
+    let names: string[] = [];
+    const plugins = [awsPlugin(({ entityNames }) => { names = entityNames; return {}; })];
+    await observeResources("prod", plugins, buildResult);
+    expect(names).toEqual(["web-sg"]);
+  });
+
   it("collects a throwing plugin into errors instead of failing the whole graph, and reports its entities unobserved (#1089)", async () => {
     const plugins = [
       awsPlugin(() => { throw new Error("access denied"); }),

package/src/lifecycle/observe.ts

@@ -25,7 +25,7 @@ import {
 } from "../observation";
 import { zeroResourcesWarning } from "../live-endpoint";
 import { unqualifiedKey } from "./identity";
-import { isResourceDeclarable } from "../declarable";
+import { isObservableDeclarable } from "../declarable";
 
 export interface ObserveResult {
   observations: LiveObservation[];
@@ -150,8 +150,10 @@ export async function observeResources(
       // parameters and serializer directives (gcp's `defaultAnnotations`) are
       // build-time inputs — declared, but with nothing in any cloud to compare
       // against, so keeping them in the universe makes every diff report a
-      // hole (or worse, a deletion) for a resource that cannot exist.
-      if (!isResourceDeclarable(entity)) continue;
+      // hole (or worse, a deletion) for a resource that cannot exist. A
+      // property-kind declarable is read as part of the resource holding it,
+      // never on its own (#3001).
+      if (!isObservableDeclarable(entity)) continue;
       entityNames.push(name);
       entities.set(name, {
         entityType: entity.entityType,
@@ -174,7 +176,7 @@ export async function observeResources(
             stackEntityNames = [];
             stackEntities = new Map();
             for (const [name, entity] of sb.entities) {
-              if (entity.lexicon !== plugin.name || !isResourceDeclarable(entity)) continue;
+              if (entity.lexicon !== plugin.name || !isObservableDeclarable(entity)) continue;
               stackEntityNames.push(name);
               stackEntities.set(name, {
                 entityType: entity.entityType,