@intentius/chant 0.101.0 → 0.104.0

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/index.ts

@@ -149,6 +149,7 @@ export * from "./resource-attributes";
 export * from "./stack-output";
 export * from "./child-project";
 export * from "./lsp/types";
+export type { SymbolDeclaration, SymbolResolver } from "./workspace/symbols";
 export * from "./lsp/lexicon-providers";
 export * from "./mcp/types";
 export * from "./lifecycle/index";

package/src/lexicon.ts

@@ -3,11 +3,13 @@ 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, ParseContext } 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";
 import type { ArtifactIntegrity } from "./lexicon-integrity";
+import type { GatedWavePipelineOptions } from "./components/gated-wave-pipeline";
+import type { PrLoopPipelineOptions } from "./components/pr-pipeline";
 import type { OkfFile } from "./okf";
 import type { CompletionContext, CompletionItem, HoverContext, HoverInfo, CodeActionContext, CodeAction } from "./lsp/types";
 import type { McpToolContribution, McpResourceContribution } from "./mcp/types";
@@ -26,6 +28,7 @@ import type { DescribeIdentityOptions, DescribeIdentityResult } from "./identity
 import type { DeepNormalizationHooks, DeepObservationResult } from "./deep-observation";
 import type { BehaviourResult, PredictBehaviourOptions } from "./behaviour";
 import type { BehaviourKinds } from "./behaviour-kinds";
+import type { SymbolResolver } from "./workspace/symbols";
 import type { DisruptionQuery, DisruptionVerdict } from "./lifecycle/disruption";
 import type { OwnerChainVerdict } from "./owner-chain";
 import type { CommandGroup } from "./cli/command-group";
@@ -426,12 +429,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 +457,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;
   };
 }
 
@@ -503,6 +539,20 @@ export interface ComponentPipelineOptions {
    * `["chant", "components", "promote", "--from", <env>, "--to", <promoteTo>]`.
    */
   promoteCommand?: string[];
+  /**
+   * Gated waves (#3049): one job per wave instead of one per component. Job
+   * `wave-<k>` runs `chant components fan-out --wave-gate <gate> --wave <k>`
+   * and hands the attempt record to the next job. See
+   * `components/gated-wave-pipeline.ts`. Unset, the pipeline is unchanged.
+   */
+  gatedWaves?: GatedWavePipelineOptions;
+  /**
+   * The pull-request loop (#3183): a plan job on each pull request and an
+   * apply job on each push to the target branch, bound to the digest a
+   * reviewer approved, instead of one job per component. See
+   * `components/pr-pipeline.ts`. Unset, the pipeline is unchanged.
+   */
+  prLoop?: PrLoopPipelineOptions;
   /**
    * The workspace member this pipeline belongs to (#2542, #2524 D19). Core
    * sets it when the project sits in a member of a `chant.workspace.json`;
@@ -857,6 +907,16 @@ export interface StackStatusObservation {
 /**
  * Context for a lexicon's {@link LexiconPlugin.buildRoots} hook (#1548).
  */
+/** What {@link LexiconPlugin.changedUnits} reads (#3183). */
+export interface ChangedUnitsContext {
+  /** The directory `chant.config.*` lives in. Config paths resolve against it. */
+  projectRoot: string;
+  /** The resolved project configuration, for the lexicon's own namespace. */
+  config: Record<string, unknown>;
+  /** Files the change added, modified or deleted, relative to `projectRoot`, with `/` separators. */
+  changedFiles: string[];
+}
+
 export interface BuildRootContext {
   /**
    * The directory the project configuration was loaded from (where
@@ -1160,8 +1220,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 +1271,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 +1338,18 @@ export interface LexiconPlugin {
    */
   buildRoots?(ctx: BuildRootContext): Promise<BuildRootContribution>;
 
+  /**
+   * The units this lexicon owns that a change touched, judged from the
+   * changed files alone (#3183). A unit is a name a component's deploy step
+   * targets (`deploy-units.ts`): the terraform lexicon answers with the
+   * `terraform.roots` entries whose directory, local modules or var files a
+   * changed file sits in. `chant components fan-out --base` and `chant
+   * components pr-plan` add these to the stacks `lifecycle affected` finds,
+   * since a root that is not chant source never shows in an artifact diff.
+   * Omit for lexicons whose units are chant source.
+   */
+  changedUnits?(ctx: ChangedUnitsContext): Promise<string[]>;
+
   /**
    * Facts about the whole read that this lexicon's entities imply, for the
    * graph IR's `meta` bag (#2559). The otel lexicon answers
@@ -1285,6 +1376,18 @@ export interface LexiconPlugin {
   /** Provide code actions for LSP */
   codeActionProvider?(ctx: CodeActionContext): CodeAction[];
 
+  /**
+   * Symbol resolvers for the languages this lexicon's members are written in
+   * (#3313), so `chant workspace graph --intent <path>#<symbol>` names a
+   * declaration in such a file: a table in a `.sql` file, a resource in a
+   * manifest. Each is `{ language, extensions, declarations(path, text) }`,
+   * returning every declaration's dotted name, kind and 1-based line range.
+   * The intent walk asks the lexicons a file's member configures, after
+   * core's TypeScript and JavaScript resolver, which keeps `.ts` and `.js`.
+   * Pure: no I/O, no network. Omit for a lexicon with no such language.
+   */
+  symbolResolvers?(): SymbolResolver[];
+
   // Docs
   /** Generate documentation pages */
   docs?(options?: { verbose?: boolean }): Promise<void>;

package/src/lifecycle/gate-ledger.ts

@@ -117,6 +117,13 @@ export interface GateResolutionRecord {
   gate: string;
   /** Who resolved it — an actor name, the same convention `components release --actor` and `run approve --approver` use. */
   resolvedBy: string;
+  /**
+   * Who carried this approval to chant for `resolvedBy` (#3402): `chant
+   * approve --relayed-by`, such as a follower program relaying a person's
+   * approval. The approver is still `resolvedBy`; a seal covers this field
+   * too. Absent when the approver recorded it themselves.
+   */
+  relayedBy?: string;
   /** ISO-8601 timestamp, caller-supplied (library code never calls `Date.now()` internally). */
   timestamp: string;
   /** Optional free-text context. Before #2028 this was also where a PR link went by convention; put the link in {@link GateResolutionRecord.url} instead and leave this for prose. */
@@ -187,6 +194,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">;

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/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,

package/src/lifecycle/snapshot.ts

@@ -18,7 +18,7 @@ import { formatUnobserved, normalizeObservation, unobservedAll, type UnobservedE
 // property tree is ever rendered or committed. Two lists would eventually
 // disagree about what counts as a secret.
 import { isSensitiveKey } from "../deep-observation";
-import { isResourceDeclarable } from "../declarable";
+import { isObservableDeclarable } from "../declarable";
 
 /**
  * Check for potential sensitive data in resource attributes and return warnings.
@@ -128,7 +128,7 @@ export async function takeSnapshot(
     for (const [name, entity] of buildResult.entities) {
       // Resource declarables only — outputs, parameters and serializer
       // directives have no live counterpart (see lifecycle/observe.ts).
-      if (entity.lexicon === plugin.name && isResourceDeclarable(entity)) {
+      if (entity.lexicon === plugin.name && isObservableDeclarable(entity)) {
         entityNames.push(name);
         entities.set(name, {
           entityType: entity.entityType,