@intentius/chant 0.79.0 → 0.81.0

package/src/lifecycle/status.ts

@@ -15,10 +15,15 @@
  *    for it. Someone (or some pipeline) deployed outside the recorded path.
  *  - **stale** — a release record exists but nothing live corresponds to it
  *    anymore (the component disappeared from observation).
- *  - **drifted** — the environment's live/owned resources don't confirm the
- *    recorded digest one way or the other from this join alone (recorded,
- *    but live identity can't be read back to a digest) — surfaced as a
- *    lower-confidence signal rather than silently treated as "reconciled".
+ *  - **drifted** — a release record exists and the component is observed
+ *    live, but a positive live observation contradicts the record (#2513):
+ *    the live identity a lexicon reports (`attributes.digest` /
+ *    `attributes.gitSha`) differs from the recorded release's, the ownership
+ *    marker went from chant's to someone else's, or the live configuration
+ *    changed against a lifecycle snapshot taken at or after the release (the
+ *    `update` verdict `lifecycle plan` gives). Only things chant saw count:
+ *    a resource it could not read, or one that reports no identity, never
+ *    makes a component drifted.
  *  - **reconciled** — a release record exists and live evidence (via
  *    ownership) confirms the component is present and owned by chant.
  *  - **unknown** — live evidence was requested and could not be read (#1089),
@@ -37,7 +42,9 @@
  */
 
 import type { ChangeSet, ChangeAction } from "./change-set";
+import type { ResourceMetadata } from "../lexicon";
 import { latestPerComponent, type ReleaseRecord } from "./release-ledger";
+import { isLegacyContentDigest } from "./legacy-digest";
 import type { BuildLedgerEntry, ComponentBomSummary } from "./build-ledger";
 import { unobservedReasonText, type UnobservedReason } from "../observation";
 
@@ -166,6 +173,99 @@ export interface LiveComponentEvidence {
    * configured.
    */
   rollup?: ComponentResourceRollup;
+  /**
+   * What the component's live resources say they are running (#2513), one
+   * entry per present resource that reported an identity attribute
+   * ({@link LIVE_IDENTITY_ATTRIBUTES}). A resource that reports none has no
+   * entry: no identity is no evidence, never a mismatch.
+   */
+  identities?: LiveIdentity[];
+  /**
+   * Positive live observations that changed against the last lifecycle
+   * snapshot (#2513), each stamped with that snapshot's timestamp so the
+   * status join can drop a change the release itself made (a snapshot taken
+   * before the release). When present, `reconcileStatus` reads these instead
+   * of the bare `action === "update"`.
+   */
+  driftSignals?: LiveDriftSignal[];
+}
+
+/**
+ * The `ResourceMetadata.attributes` keys a lexicon sets to report which build
+ * a live resource is running (#2513), and the release-record field each one is
+ * compared with. Opt-in: a lexicon that sets neither is reconciled on presence,
+ * ownership and snapshot drift alone, exactly as before.
+ *
+ * - `digest` — the artifact digest serving now (`sha256:...`). Matches the
+ *   record's `digest`, or its `inputDigest` when the record has one.
+ * - `gitSha` — the commit the live build came from. Matches the record's
+ *   `gitSha`; an abbreviated sha (7+ characters) matches by prefix.
+ */
+export const LIVE_IDENTITY_ATTRIBUTES = { digest: "digest", gitSha: "gitSha" } as const;
+
+/** One live resource's reported identity (#2513). */
+export interface LiveIdentity {
+  /** The live entity/resource name that reported it. */
+  entity: string;
+  digest?: string;
+  gitSha?: string;
+}
+
+/** One live change against the last snapshot (#2513). */
+export interface LiveDriftSignal {
+  entity: string;
+  /**
+   * `attributes` — the change set's `update` (status, physicalId, lastUpdated
+   * or an attribute changed). `ownership` — the snapshot read chant's marker
+   * and the live read now reads none (`owned` -> `foreign`), or the marker now
+   * names a different stack/env. `unknown` on either side is never a signal.
+   */
+  kind: "attributes" | "ownership";
+  /** The snapshot's timestamp. Absent when the caller did not say. */
+  since?: string;
+  /** Human-readable backing (the changed paths, the marker transition). */
+  detail?: string;
+}
+
+/**
+ * The per-entity observation `liveEvidenceFromChangeSet` reads identity and
+ * marker transitions from (#2513). `now` is the live read; `then`/`thenAt`
+ * are the last lifecycle snapshot's record for the same entity, when one
+ * exists.
+ */
+export interface EntityLiveRead {
+  now?: ResourceMetadata;
+  then?: ResourceMetadata;
+  thenAt?: string;
+}
+
+function identityOf(entity: string, meta: ResourceMetadata | undefined): LiveIdentity | undefined {
+  const attrs = meta?.attributes;
+  if (!attrs) return undefined;
+  const digest = attrs[LIVE_IDENTITY_ATTRIBUTES.digest];
+  const gitSha = attrs[LIVE_IDENTITY_ATTRIBUTES.gitSha];
+  const d = typeof digest === "string" && digest.length > 0 ? digest : undefined;
+  const g = typeof gitSha === "string" && gitSha.length > 0 ? gitSha : undefined;
+  if (!d && !g) return undefined;
+  return { entity, ...(d ? { digest: d } : {}), ...(g ? { gitSha: g } : {}) };
+}
+
+/**
+ * An ownership transition between the snapshot and now that contradicts a
+ * chant release. `unknown` on either side answers nothing and is skipped, the
+ * same way the change set never escalates `unknown` (#1089, #1168).
+ */
+function ownershipChange(then: ResourceMetadata | undefined, now: ResourceMetadata | undefined): string | undefined {
+  if (!then || !now) return undefined;
+  if (then.ownership === "owned" && now.ownership === "foreign") {
+    return "ownership marker was chant's at the last snapshot and is gone now";
+  }
+  const a = then.marker;
+  const b = now.marker;
+  if (a && b && (a.stack !== b.stack || (a.env !== undefined && b.env !== undefined && a.env !== b.env))) {
+    return `ownership marker changed from ${a.stack}${a.env ? `/${a.env}` : ""} to ${b.stack}${b.env ? `/${b.env}` : ""}`;
+  }
+  return undefined;
 }
 
 /**
@@ -211,6 +311,11 @@ export function mergeLiveEvidence(
       // Base first: the counts come from the change set, and a stack
       // observation has none to offer.
       ...(b?.rollup ?? sup.rollup ? { rollup: b?.rollup ?? sup.rollup } : {}),
+      // Identity and snapshot drift come from the per-resource reads; a stack
+      // observation carries neither, so dropping them here would make
+      // `drifted` unreachable again on every lexicon with a stack observer.
+      ...(b?.identities ? { identities: b.identities } : {}),
+      ...(b?.driftSignals ? { driftSignals: b.driftSignals } : {}),
     });
   }
   return merged;
@@ -299,7 +404,18 @@ function mergeEvidence(entries: LiveComponentEvidence[]): LiveComponentEvidence
   // actually seen live, which already answers "is this deployed".
   const unobserved = live ? undefined : entries.find((e) => e.unobserved)?.unobserved;
 
-  return { live, ownership, action, ...(unobserved ? { unobserved } : {}), rollup: rollUp(entries) };
+  const identities = entries.flatMap((e) => e.identities ?? []);
+  const driftSignals = entries.flatMap((e) => e.driftSignals ?? []);
+
+  return {
+    live,
+    ownership,
+    action,
+    ...(unobserved ? { unobserved } : {}),
+    rollup: rollUp(entries),
+    ...(identities.length ? { identities } : {}),
+    ...(driftSignals.length ? { driftSignals } : {}),
+  };
 }
 
 /**
@@ -317,9 +433,41 @@ function mergeEvidence(entries: LiveComponentEvidence[]): LiveComponentEvidence
 export function liveEvidenceFromChangeSet(
   cs: ChangeSet,
   nameMapping?: LiveNameMapping,
+  opts?: {
+    /**
+     * Per-entity live read and snapshot record (#2513). With it, the evidence
+     * carries the identity each live resource reports and the drift signals
+     * (stamped with the snapshot's time) `reconcileStatus` reads for
+     * `drifted`. Without it, the evidence is what it was before: the change
+     * set's `action` alone.
+     */
+    observations?: Map<string, EntityLiveRead>;
+  },
 ): Map<string, LiveComponentEvidence> {
   const evidenceByName = new Map<string, LiveComponentEvidence>();
   for (const entry of cs.entries) {
+    const obs = opts?.observations?.get(entry.name);
+    // Identity and marker transitions only from a resource that was actually
+    // read present. An unobserved or absent entity contributes nothing.
+    const identity = entry.evidence.live ? identityOf(entry.name, obs?.now) : undefined;
+    const driftSignals: LiveDriftSignal[] = [];
+    if (obs && entry.action === "update") {
+      driftSignals.push({
+        entity: entry.name,
+        kind: "attributes",
+        ...(obs.thenAt ? { since: obs.thenAt } : {}),
+        ...(entry.deltas?.length ? { detail: entry.deltas.map((d) => d.path).join(", ") } : {}),
+      });
+    }
+    const ownershipDetail = obs && entry.evidence.live ? ownershipChange(obs.then, obs.now) : undefined;
+    if (ownershipDetail) {
+      driftSignals.push({
+        entity: entry.name,
+        kind: "ownership",
+        ...(obs?.thenAt ? { since: obs.thenAt } : {}),
+        detail: ownershipDetail,
+      });
+    }
     evidenceByName.set(entry.name, {
       rollup: rollUp([
         {
@@ -342,6 +490,8 @@ export function liveEvidenceFromChangeSet(
             },
           }
         : {}),
+      ...(identity ? { identities: [identity] } : {}),
+      ...(driftSignals.length ? { driftSignals } : {}),
     });
   }
 
@@ -404,6 +554,7 @@ export function reconcileStatus(
 
     let reconciliation: ComponentStatusRow["reconciliation"];
     let detail: string;
+    let contradiction: string | undefined;
 
     if (!liveEvidence) {
       // No live evidence requested at all (digest-only / offline mode) — the
@@ -437,9 +588,9 @@ export function reconcileStatus(
       detail = evidence?.partial
         ? `recorded ${recorded.timestamp} (digest ${recorded.digest}), but only ${evidence.partial.present} of ${evidence.partial.total} deploy units observed live now (missing: ${evidence.partial.missing.join(", ")})`
         : `recorded ${recorded.timestamp} (digest ${recorded.digest}), but nothing observed live now`;
-    } else if (recorded && evidence?.action === "update") {
+    } else if (recorded && (contradiction = contradictsRecord(recorded, evidence!))) {
       reconciliation = "drifted";
-      detail = `recorded ${recorded.timestamp} (digest ${recorded.digest}), but live configuration has drifted since`;
+      detail = `recorded ${recorded.timestamp} (digest ${recorded.digest}), but ${contradiction}`;
     } else {
       reconciliation = "reconciled";
       detail = `recorded ${recorded!.timestamp} (digest ${recorded!.digest}), live and consistent`;
@@ -467,6 +618,66 @@ export function reconcileStatus(
   return rows;
 }
 
+/** `sha256:abc` and `abc` name the same digest; anything else compares exactly. */
+function sameDigest(a: string, b: string): boolean {
+  const bare = (d: string) => d.replace(/^sha256:/, "");
+  return a === b || bare(a) === bare(b);
+}
+
+/** Full shas compare exactly; an abbreviated one (7+ chars) matches by prefix. */
+function sameGitSha(a: string, b: string): boolean {
+  if (a === b) return true;
+  const [short, long] = a.length <= b.length ? [a, b] : [b, a];
+  return short.length >= 7 && long.startsWith(short);
+}
+
+function notBefore(since: string, recordedAt: string): boolean {
+  const s = Date.parse(since);
+  const r = Date.parse(recordedAt);
+  // An unparseable timestamp cannot place the change after the release, so
+  // it is not attributed to drift since it.
+  return !Number.isNaN(s) && !Number.isNaN(r) && s >= r;
+}
+
+/**
+ * Does live evidence for a present, recorded component contradict its latest
+ * release record (#2513)? Returns why, or `undefined` when nothing seen says
+ * so. Every rule reads a positive observation; a missing identity, an
+ * `unknown` ownership or a resource nobody read is not a contradiction.
+ */
+function contradictsRecord(recorded: ReleaseRecord, evidence: LiveComponentEvidence): string | undefined {
+  for (const id of evidence.identities ?? []) {
+    if (id.digest !== undefined) {
+      const matches =
+        sameDigest(id.digest, recorded.digest) ||
+        (recorded.inputDigest !== undefined && sameDigest(id.digest, recorded.inputDigest));
+      if (!matches) return `live ${id.entity} reports digest ${id.digest}`;
+    }
+    if (id.gitSha !== undefined && !sameGitSha(id.gitSha, recorded.gitSha)) {
+      return `live ${id.entity} reports git sha ${id.gitSha}, recorded ${recorded.gitSha}`;
+    }
+  }
+
+  if (evidence.driftSignals) {
+    // A signal against a snapshot taken before the release may be the release
+    // itself, so only a change seen since the release counts. A signal with no
+    // `since` was produced by a caller that did not say, and counts.
+    const since = evidence.driftSignals.filter((d) => d.since === undefined || notBefore(d.since, recorded.timestamp));
+    const first = since[0];
+    if (first) {
+      const what = first.kind === "ownership" ? first.detail ?? "ownership marker changed" : `live configuration of ${first.entity} changed${first.detail ? ` (${first.detail})` : ""}`;
+      const more = since.length > 1 ? ` (+${since.length - 1} more)` : "";
+      return `${what} since the snapshot of ${first.since ?? "an earlier read"}${more}`;
+    }
+    return undefined;
+  }
+
+  // Evidence assembled without per-entity observations: the change set's own
+  // `update` verdict is the only drift signal there is.
+  if (evidence.action === "update") return "live configuration has drifted since";
+  return undefined;
+}
+
 /**
  * Answer "which build is in `envA`, and is it the one tested in `envB`" —
  * the single-query comparison the epic names explicitly — for one component
@@ -491,6 +702,13 @@ export interface CrossEnvComparison {
   same: boolean;
   /** The identities `same` was decided on (`inputDigest ?? digest` per side), when both sides had one and they differ from the digests shown. */
   comparedOn?: { a: string; b: string };
+  /**
+   * Set when the two identities differ and exactly one of them is a
+   * `legacy-digest` value from before real SHA-256 (#2514). The same content
+   * hashes differently in the two forms, so `same: false` then says nothing
+   * about whether the builds match.
+   */
+  mixedDigestForms?: true;
 }
 
 /** Compare the latest recorded digest for `component` between two environments' release records. */
@@ -512,5 +730,8 @@ export function compareAcrossEnvironments(
     digestB: latestB?.digest,
     same: !!idA && !!idB && idA === idB,
     ...(comparedOnInputs && idA && idB ? { comparedOn: { a: idA, b: idB } } : {}),
+    ...(idA && idB && idA !== idB && isLegacyContentDigest(idA) !== isLegacyContentDigest(idB)
+      ? { mixedDigestForms: true as const }
+      : {}),
   };
 }

package/src/lint/rules/comp/comp003-mutating-no-rollback.ts

@@ -24,9 +24,8 @@
  * component.schema.json), a component may attach a `noRollback: "<reason>"`
  * string property directly on the step to declare the compensation gap is
  * intentional and understood, or supply its own explicit compensation via a
- * component-level `rollback` field (as the ALB/ECS pilot does with
- * `rollback-previous`) or a sibling `rollback-previous`/`snapshot-before` step
- * in the same phase.
+ * component-level `rollback` field or a sibling
+ * `rollback-previous`/`snapshot-before` step in the same phase.
  *
  * Triggers on: a bare `{ kind: "run-migration", ... }` step with no
  * `noRollback` reason, no component-level `rollback`, and no sibling

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

@@ -129,3 +129,40 @@ export const behaviourFindingContract = activityContract(
     mergeRequest: z.string().optional(),
   }),
 );
+
+/**
+ * The propose-only template upgrade (#2550, ws-032). `args` mirrors
+ * `ProposeWorkspaceUpgradeArgs` without its test hooks. `returns` names what
+ * a step reads: whether anything changed, whether it was proposed, the patch
+ * digest the command's gate would bind, and the branch and pull request.
+ */
+export const proposeWorkspaceUpgradeContract = activityContract(
+  "proposeWorkspaceUpgrade",
+  z.strictObject({
+    scope: z.string().optional(),
+    to: z.string().optional(),
+    mode: z.enum(["report", "branch", "pull-request"]).optional(),
+    branch: z.string().optional(),
+    base: z.string().optional(),
+    remote: z.string().optional(),
+    allowCode: z.boolean().optional(),
+    cwd: z.string().optional(),
+  }),
+  z.object({
+    scope: z.string(),
+    mode: z.enum(["report", "branch", "pull-request"]),
+    changed: z.boolean(),
+    proposed: z.boolean(),
+    checksOk: z.boolean(),
+    from: z.string().nullable(),
+    to: z.string().nullable(),
+    digest: z.string(),
+    manualSteps: z.number(),
+    governance: z.boolean(),
+    branch: z.string().optional(),
+    commit: z.string().optional(),
+    pushed: z.boolean().optional(),
+    prUrl: z.string().optional(),
+    summary: z.string(),
+  }),
+);

package/src/op/activities/index.ts

@@ -147,3 +147,13 @@ export type {
   BehaviourFindingDeps,
   BaseCheckout,
 } from "./predict-behaviour";
+
+// The propose-only template upgrade (#2550). Loads the workspace code on first
+// call only, so importing this module loads nothing under `workspace/`.
+export { proposeWorkspaceUpgrade } from "./propose-upgrade";
+export type {
+  ProposeWorkspaceUpgradeArgs,
+  ProposeWorkspaceUpgradeResult,
+  ProposeUpgradeMode,
+  CommandRunner,
+} from "./propose-upgrade";

package/src/op/activities/propose-upgrade.ts

@@ -0,0 +1,206 @@
+/**
+ * proposeWorkspaceUpgrade — the propose-only activity behind scheduled
+ * template upgrades (#2550, D9, ws-032).
+ *
+ * `chant workspace upgrade` is a core command. An Op, including a workspace Op
+ * later (#2554), schedules it through this activity, which stages the same
+ * upgrade (fetch, migrate, merge per file, build, lint and `workspace check`
+ * in a worktree) and then only proposes it:
+ *
+ * - `report` (default): stage and check, and return the summary.
+ * - `branch`: commit the patch on a proposal branch, by default
+ *   `chant/upgrade/<scope>`, and push it when the repository has the remote.
+ * - `pull-request`: the branch, plus an open pull request against the default
+ *   branch, created once and edited on later runs.
+ *
+ * It never writes the default branch or the checked-out branch, and it never
+ * applies the patch to the working tree, so an Op cannot rewrite itself or
+ * the gates that judge it. Review and merge of the pull request are the
+ * approval. The PR body names the patch digest, the value `chant workspace
+ * upgrade` binds its gate to, so the two paths approve the same thing.
+ *
+ * The workspace code loads on first call, so importing core's activities
+ * loads nothing under `workspace/` (#2525 rule 5).
+ */
+
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import type { StagedUpgrade } from "../../workspace/lineage-upgrade";
+
+const execFileAsync = promisify(execFile);
+
+export type ProposeUpgradeMode = "report" | "branch" | "pull-request";
+
+export interface ProposeWorkspaceUpgradeArgs {
+  /** The lineage scope: `"."` (default) or a vendor scope's directory. */
+  scope?: string;
+  /** The target ref. Defaults to the ref the scope is pinned at, so a moving ref such as a branch is followed. */
+  to?: string;
+  mode?: ProposeUpgradeMode;
+  /** The proposal branch. Default `chant/upgrade/<scope>`, with `root` for `"."`. */
+  branch?: string;
+  /** The branch the pull request targets. Default: the remote's default branch. */
+  base?: string;
+  /** The remote to push to. Default `origin`. */
+  remote?: string;
+  /** Run code migrations. Default false. */
+  allowCode?: boolean;
+  /** The directory holding the lineage lock. Default: the working directory. */
+  cwd?: string;
+  /** Replaces the git and gh child processes. For tests. */
+  _run?: CommandRunner;
+  /** Replaces build and lint in the worktree. For tests. */
+  _runChant?: import("../../workspace/lineage-upgrade").ChantRunner;
+}
+
+/** Runs `git` or `gh` with arguments, returning stdout. Rejects on a non-zero exit. */
+export type CommandRunner = (bin: "git" | "gh", args: string[], cwd: string) => Promise<string>;
+
+export interface ProposeWorkspaceUpgradeResult {
+  scope: string;
+  mode: ProposeUpgradeMode;
+  /** Whether the template has anything new for the scope. */
+  changed: boolean;
+  /** Whether a branch or pull request was written. */
+  proposed: boolean;
+  checksOk: boolean;
+  from: string | null;
+  to: string | null;
+  /** The patch digest `chant workspace upgrade` binds its gate to. */
+  digest: string;
+  manualSteps: number;
+  governance: boolean;
+  branch?: string;
+  commit?: string;
+  pushed?: boolean;
+  prUrl?: string;
+  summary: string;
+}
+
+const defaultRun: CommandRunner = async (bin, args, cwd) => (await execFileAsync(bin, args, { cwd, maxBuffer: 64 * 1024 * 1024 })).stdout;
+
+/** The proposal branch for a scope. */
+export function proposalBranch(scope: string): string {
+  return `chant/upgrade/${scope === "." ? "root" : scope.replace(/[^A-Za-z0-9._/-]/g, "-")}`;
+}
+
+/** The marker that finds this scope's pull request again. */
+export function proposalMarker(scope: string): string {
+  return `<!-- chant-workspace-upgrade:${scope} -->`;
+}
+
+function body(staged: StagedUpgrade, lines: string[]): string {
+  return [
+    proposalMarker(staged.scope),
+    `## Template upgrade: \`${staged.scope}\``,
+    "",
+    `\`${staged.template}\` from \`${staged.from ?? "(no ref)"}\` to \`${staged.to ?? "(no ref)"}\`.`,
+    "",
+    `Patch digest: \`${staged.digest}\``,
+    "",
+    "```",
+    ...lines,
+    "```",
+    "",
+    staged.manualSteps.length > 0
+      ? `${staged.manualSteps.length} file(s) did not merge cleanly and are kept as they were, each with a manual step. \`chant workspace check\` fails until each is merged and resolved with \`chant workspace lineage resolve <path>\`.`
+      : "Every file merged cleanly.",
+    staged.governance ? "\nThis upgrade changes governance files. Review it under the rules on the default branch, not the ones it proposes." : "",
+    "",
+    "Proposed by the `proposeWorkspaceUpgrade` activity. It never writes the default branch.",
+  ].join("\n");
+}
+
+async function defaultBranch(run: CommandRunner, repo: string, remote: string): Promise<string | null> {
+  try {
+    const ref = (await run("git", ["symbolic-ref", "--short", `refs/remotes/${remote}/HEAD`], repo)).trim();
+    return ref.startsWith(`${remote}/`) ? ref.slice(remote.length + 1) : ref;
+  } catch {
+    return null;
+  }
+}
+
+/** Stage a workspace upgrade and propose it as a branch or pull request. Never writes the default branch. */
+export async function proposeWorkspaceUpgrade(args: ProposeWorkspaceUpgradeArgs): Promise<ProposeWorkspaceUpgradeResult> {
+  const mode = args.mode ?? "report";
+  const run = args._run ?? defaultRun;
+  const remote = args.remote ?? "origin";
+  const { stageUpgrade, describeStaged, commitStagedUpgrade } = await import("../../workspace/lineage-upgrade");
+  const staged = await stageUpgrade({
+    root: args.cwd ?? process.cwd(),
+    scope: args.scope,
+    to: args.to,
+    allowCode: args.allowCode,
+    ...(args._runChant ? { runChant: args._runChant } : {}),
+  });
+  try {
+    const lines = describeStaged(staged);
+    const result: ProposeWorkspaceUpgradeResult = {
+      scope: staged.scope,
+      mode,
+      changed: staged.changed,
+      proposed: false,
+      checksOk: staged.checksOk,
+      from: staged.from,
+      to: staged.to,
+      digest: staged.digest,
+      manualSteps: staged.manualSteps.length,
+      governance: staged.governance !== null,
+      summary: lines.join("\n"),
+    };
+    if (!result.changed || !result.checksOk || mode === "report") return result;
+
+    const branch = args.branch ?? proposalBranch(staged.scope);
+    const remoteDefault = await defaultBranch(run, staged.repo, remote);
+    const base = args.base ?? remoteDefault;
+    let current: string | null = null;
+    try {
+      current = (await run("git", ["symbolic-ref", "--short", "HEAD"], staged.repo)).trim();
+    } catch {
+      // Detached HEAD: nothing checked out to protect.
+    }
+    for (const [what, name] of [["default branch", remoteDefault], ["base branch", base], ["checked-out branch", current]] as const) {
+      if (name && branch === name) {
+        throw new Error(`proposeWorkspaceUpgrade only proposes: it will not write the ${what} "${name}". Choose another branch.`);
+      }
+    }
+    if (mode === "pull-request" && !base) {
+      throw new Error(`proposeWorkspaceUpgrade: cannot tell the default branch of "${remote}"; pass base`);
+    }
+
+    const title = `chore(upgrade): ${staged.template} ${staged.to ?? ""} (${staged.scope})`.replace(/\s+/g, " ").replace(" )", ")");
+    result.commit = commitStagedUpgrade(staged, branch, `${title}\n\nPatch digest: ${staged.digest}\n`);
+    result.branch = branch;
+    result.proposed = true;
+
+    let hasRemote = false;
+    try {
+      await run("git", ["remote", "get-url", remote], staged.repo);
+      hasRemote = true;
+    } catch {
+      hasRemote = false;
+    }
+    if (hasRemote) {
+      // The proposal branch is rebuilt from the default branch on every run, so it is replaced.
+      await run("git", ["push", "--force", remote, `${result.commit}:refs/heads/${branch}`], staged.repo);
+      result.pushed = true;
+    } else {
+      result.pushed = false;
+    }
+    if (mode !== "pull-request") return result;
+    if (!hasRemote) throw new Error(`proposeWorkspaceUpgrade: no remote "${remote}" to open a pull request on`);
+
+    const text = body(staged, lines);
+    const existing = (await run("gh", ["pr", "list", "--head", branch, "--state", "open", "--json", "url", "--jq", ".[0].url // empty"], staged.repo)).trim();
+    if (existing) {
+      await run("gh", ["pr", "edit", existing, "--title", title, "--body", text], staged.repo);
+      result.prUrl = existing;
+    } else {
+      const out = await run("gh", ["pr", "create", "--base", base!, "--head", branch, "--title", title, "--body", text], staged.repo);
+      result.prUrl = out.trim().split("\n").pop();
+    }
+    return result;
+  } finally {
+    staged.dispose();
+  }
+}

package/src/op/activity-contract-registry.ts

@@ -36,6 +36,7 @@
 
 import * as coreContracts from "./activities/activity-contracts";
 import { collectActivityContracts, type ActivityContract } from "./activity-contract";
+import { importLexiconModule } from "../lexicon-module";
 
 /**
  * The shape {@link loadActivityContracts} reads off a plugin: an optional
@@ -74,16 +75,29 @@ export async function loadActivityContracts(
 
   for (const entry of lexicons) {
     const name = typeof entry === "string" ? entry : entry.name;
+    let contributor: LexiconActivityContractContributor | undefined = typeof entry === "string" ? undefined : entry;
     try {
-      const spec = `@intentius/chant-lexicon-${name}/op/activity-contracts`;
-      collectActivityContracts((await import(spec)) as Record<string, unknown>, contracts);
+      // chant #2520 — a lexicon declared by module path has no subpath to
+      // import. Its plugin's `activityContracts()` member stands in for it;
+      // given only the name, the plugin is read from the declared module.
+      const local = await importLexiconModule(name);
+      if (local !== undefined) {
+        contributor ??= Object.values(local).find(
+          (v): v is LexiconActivityContractContributor =>
+            typeof v === "object" && v !== null && (v as { name?: unknown }).name === name &&
+            typeof (v as { activityContracts?: unknown }).activityContracts === "function",
+        );
+      } else {
+        const spec = `@intentius/chant-lexicon-${name}/op/activity-contracts`;
+        collectActivityContracts((await import(spec)) as Record<string, unknown>, contracts);
+      }
     } catch {
       // Lexicon absent or declares no contracts at the conventional subpath.
     }
 
-    if (typeof entry !== "string" && typeof entry.activityContracts === "function") {
+    if (contributor !== undefined && typeof contributor.activityContracts === "function") {
       try {
-        for (const contract of entry.activityContracts()) contracts.set(contract.name, contract);
+        for (const contract of contributor.activityContracts()) contracts.set(contract.name, contract);
       } catch {
         // A plugin member that throws contributes nothing, the same as one that is absent.
       }