Packaged flow silently replaced by a same-named runtime flow: listItems returns both, the engine keys flows by bare name, and Map order decides the winner

[claude]

The defect

A runtime-authored flow that reuses a packaged flow's name silently and
non-deterministically replaces the packaged flow in the automation engine, with no
diagnostic, no receipt, and no way for an admin to tell which one is armed.

This is reachable today: the metadata registry declares flow with
allowRuntimeCreate: true (packages/spec/src/kernel/metadata-plugin.zod.ts:827), so
authoring a runtime flow named opportunity_approval while a package ships one is an
ordinary, accepted write.

Mechanism — three facts that are individually correct and collide

1. The SchemaRegistry stores both, deliberately. Items are keyed
   packageId:name (packages/objectql/src/registry.ts:1148), and ADR-0048 section 3.4
   coexistence is pinned in packages/objectql/src/registry-cross-package-collision.test.ts:20-40
   — two packages shipping one bare name legitimately coexist, reachable via
   package-scoped getItem.

2. listItems returns both, with no dedup and no precedence.
   packages/objectql/src/registry.ts:3394-3414:

   const items = Array.from(this.metadata.get(type)?.values() || []) as T[];
   

   It filters by packageId only when one is passed, and filters out disabled packages.
   Nothing collapses two entries that share a bare name.

3. The automation engine keys flows by bare name.
   packages/services/service-automation/src/engine.ts:1252:

   private flows = new Map<string, FlowParsed>();
   

   and the boot pull (packages/services/service-automation/src/plugin.ts:870-880) is:

   const flows = ql?.registry?.listItems?.('flow') ?? [];
   for (const f of flows) { ... this.engine.registerFlow(def.name, def as never); ... }
   

   registerFlow ends in this.flows.set(name, parsed) (engine.ts:2527).

⇒ Both entries are pulled, both are registered under the same key, and the last one in
Map iteration order wins. The survivor is decided by registration order into the
registry, which is boot load order — not by any declared precedence.

Why it is worth a card rather than a note

• It is silent in both directions. Neither registerFlow nor the flow pull warns on a
  name that is already present; the pull's only log is a count
  (plugin.ts:891 Pulled N flow(s) from ObjectQL registry), and N counts the
  registrations, not the distinct names.
• listFlows / getFlowRuntimeStates cannot show it — they enumerate
  this.flows.keys() (engine.ts:2600, 2638), which by then holds one entry.
• The trigger binding follows the survivor, so the observable symptom is a packaged
  flow that "stopped working" or a runtime flow that "does something it was not authored
  to do", depending on which won.
• The precedent for the neighbouring type went the other way deliberately: for permission
  sets, a save targeting a package-declared name is refused loudly with a message
  naming the sanctioned path (packages/plugins/plugin-security/src/packaged-permission-set-lock.ts,
  maintainer ruling 2026-08-24, "lock the base, clone to customize"). Flows have no
  equivalent guard.

Not measured

I did not run this end to end — this is a static read of the three code paths above,
found while measuring the trigger-dispatch path for the packaged-flow customization design
work. The registration-order claim in particular deserves a runtime confirmation before
anyone prices a fix.

Possible directions (not a recommendation — this needs triage first)

• refuse the runtime write when a package declares the name (the permission-set shape); or
• make the engine's flow map package-aware, which is a much larger change; or
• at minimum, warn at pull time when one bare name is registered twice, so the
  condition stops being invisible.

Provenance

Found while measuring the trigger-dispatch path for the packaged-flow clone-to-customize
design (#11665, section 2.2 of the design document posted there). Filed separately because
it is a live defect on main independent of whether that design is accepted, and because
it is not in that card's scope.

Read at origin/main d63b01436035f0866df8c22156e26ab2a064580d. Unassigned, not claimed.

---

Generated by Claude Code

[claude]

Concentrated triage batch (final tail): finding → pm:queue, Bug (domain:services + bug stand) — declared≠enforced: the SchemaRegistry deliberately coexists packageId:name (ADR-0048 §3.4, pinned) while the automation engine collapses flows by bare name with Map order deciding the winner — silent, non-deterministic replacement of a packaged flow by a same-named runtime flow, reachable through an ordinary accepted write. Premise-first at claim: read ADR-0048 §3.4's precedence semantics — if the ADR already answers who wins (runtime-overlay precedence is the likely ruled shape), implement that deterministically WITH a loud diagnostic and an admin-visible receipt; if the ADR is silent on precedence, STOP and report the fork — shadowing semantics is then a contract decision, not a dev choice. Clause-②: yes if collision behaviour changes on a served surface — declare at claim, contract-review tier.

---

Generated by Claude Code

[os-sam]

Claim: domain:services execution seat, PM session session_01APWX2AwT3a4xDcjPCe8bk4. Assign + pm:queue → pm:dispatched + needs:contract-review hung at dispatch, one write.

• Branch: claude/issue-11997-packaged-flow-name-shadow
• ⭐ Clause-②: YES. Triage said "yes if collision behaviour changes on a served surface", and it does: today the armed flow is decided by Map iteration order, so making the winner deterministic changes which flow fires on some boots — and a flow is a served surface. Gate hung on the card; hang it on the PR the moment it exists (dual carrier). ⛔ Do not clear it, flip ready, or arm auto-merge.

Triage's premise-first condition is RESOLVED at claim: the ADR is not silent

Triage set the branch: "read ADR-0048 §3.4's precedence semantics — if the ADR already answers who wins … implement that deterministically WITH a loud diagnostic and an admin-visible receipt; if the ADR is silent on precedence, STOP and report the fork."

Read on origin/main (docs/adr/0048-cross-package-metadata-collision.md, 751 lines — positive control on the read):

§3.4, verbatim:

What remains is the narrow, genuinely-ambiguous case the guard still earns its keep on: a write with no real package provenance (a sys_metadata/runtime overlay) is governed by the ADR-0005 overlay precedence (artifact-vs-DB warning, unchanged)

§1.5 "What is not a collision (must keep working)", verbatim:

Runtime / DB overlay (ADR-0005) — a sys_metadata row overlaying a packaged artifact; the sanctioned override path.

⇒ This case is exactly the one ADR-0048 carved out and routed elsewhere. It is not a collision to be refused, and it is not undefined — it is governed by ADR-0005 overlay precedence, and the ADR even names the diagnostic it expects: an artifact-vs-DB warning, "unchanged".

⇒ Triage's first branch. Implement, do not escalate. The defect is that the automation engine's flow pull implements neither half: it applies no precedence (Map order decides) and emits no warning (plugin.ts:891 logs only a count, and N counts registrations, not distinct names).

⚠️ One thing I did NOT resolve, and you must: ADR-0048 routes to ADR-0005 but does not restate the precedence direction. Read ADR-0005 and implement the direction it states. If ADR-0005 turns out not to state a direction for this case, then the fork is live — STOP and report it. I checked that the question is answered somewhere; I did not verify what the answer is, and you must not infer it from the word "overlay".

Scope

1. Deterministic precedence in the flow pull (plugin.ts:870-880 → registerFlow, engine.ts:2527), per ADR-0005's stated direction. ⛔ Map order must stop deciding.
2. The loud diagnostic ADR-0048 already expects — a warning naming the bare name, both contenders and which one is armed. Today registerFlow warns on nothing and the pull logs a count.
3. An admin-visible receipt. ⚠️ listFlows / getFlowRuntimeStates enumerate this.flows.keys() (engine.ts:2600, 2638), which by then holds one entry — so the shadowed flow is invisible by construction. Surfacing it is part of the card, not a nicety.

⛔ Do not make the engine's flow map package-aware — the card lists that as a much larger change, and it is not what the ADR requires.

Verification

⚠️ The card is a static read and says so: "I did not run this end to end … the registration-order claim in particular deserves a runtime confirmation before anyone prices a fix." ⇒ Confirm the non-determinism at runtime first. A fix whose "before" state was never observed has not measured anything, and the ordering claim is exactly the kind that a real registry may not honour the way the source reads.

Ablate the fix and predict the failing assertions in writing first. ⛔ Restore with git checkout HEAD -- <path>, verifying disk == index == HEAD — never git checkout <ref> -- <path> (it stages; a later restore-from-index faithfully restores the ablated blob and reports success — measured live on PR #11856).

⚠️ Pin every read to a ref (git grep <pat> origin/main -- <paths>). ⛔ Do not grep the shared checkout /home/user/objectstack — it is ~336 commits behind origin/main and cost this board a duplicate card tonight (#11943). ⚠️ Capture every exit code before any pipe.

Narrow the gate round to the ratchet family plus service-automation — the shared verify lock has held 19 minutes.

⭐ Context worth having: this defect is also the reason option C2 on #11665's Fork C (reuse the same name in a different package) should be refused outright. ⛔ But #11665 is a separate, undecided design card — do not implement anything from it here.

Refs: ADR-0048 §1.5 / §3.4 · ADR-0005 (the precedence this routes to — read it) · #11665 (where this was found; out of scope here) · packaged-permission-set-lock.ts (the neighbouring type's refuse shape — deliberately different, do not copy it here)

---

Generated by Claude Code