Skip to main content
← Back to list
01Issue
BugOpenSwamp CLIPublic
AssigneesNone

Relationships

#1734 Method-name collision between a base model type and an extending extension silently drops the whole extension file — no error, doctor reports pass

Opened by esteban · 8/19/2026

Summary

When a local (auto-discovered) method extension declares a method name that the base model type already defines, the collision guard fires and rejects the entire extension file — but nothing reports it. swamp doctor extensions returns overallStatus: pass, loaderErrors: {}, warnings: [], and every other method in the same file disappears too. The only way to notice is to describe the type and see that your methods are missing.

This is the same guard described in #1101 ("Method-name override is correctly blocked... the whole file fails to bundle"), but in this direction the diagnostic that report relied on — a loud BundleBuildFailed — never appears. The guard works; its failure surface does not.

How I hit it

@swamp/aws/bedrock 2026.08.18.1 introduced a retrieve method on @swamp/aws/bedrock/knowledge-base. This repo already had a local method extension adding its own retrieve to the same type (predating the first-party one — feature request #1571). After the upstream update:

  • the first-party retrieve was the one present on the merged type;
  • the local extension's dedicated retrieval data resource was gone from the type;
  • swamp doctor extensions reported pass with no errors and no warnings.

A consumer following our own documented instructions would have called retrieve, received a different response shape, and found the resource it expected missing — with nothing anywhere to explain why.

Controlled reproduction

Verified today on swamp 20260809.004828.0-sha.b61c9de2, Deno 2.8.3, Linux.

Drop one file in extensions/models/ declaring two methods on a pulled base type — one name that collides with a base-type method, one that does not:

export const extension = {
  type: "@swamp/aws/bedrock/knowledge-base",
  methods: [
    {
      probe_marker: {   // does NOT collide
        description: "a non-colliding sibling method in the same file",
        arguments: ProbeArgs,
        execute: () => { throw new Error("never runs"); },
      },
      retrieve: {       // DOES collide with the base type's own retrieve
        description: "collides on purpose",
        arguments: ProbeArgs,
        execute: () => { throw new Error("never runs"); },
      },
    },
  ],
};

Then rename only the colliding method (retrieve -> probe_unique) and compare. Same file, same shape, one identifier different:

Probe file model type describe shows doctor extensions
probe_marker + retrieve (collides) neither method pass, loaderErrors: {}, warnings: []
probe_marker + probe_unique (no collision) both methods pass, loaderErrors: {}, warnings: []

So the collision silently discards the whole file, and the two outcomes are indistinguishable from any CLI output. recentTransitions in the doctor JSON showed the probe reaching Indexed in both cases — including the run where nothing from it registered.

Why this is worth fixing rather than documenting

  1. It is the failure mode you cannot see. The collision only happens when someone else's release adds a name you were already using, so it appears on an upgrade you did not write, in a file you did not touch, on a type you do not own.
  2. Silence plus partial-file rejection is the worst combination. Losing sibling methods multiplies the blast radius, and there is no signal correlating the loss with the upgrade that caused it.
  3. #1101's guarantee does not hold uniformly. That issue documents a hard load-time throw with BundleBuildFailed. Here the same class of collision is silent. Whatever the intended contract is, the two paths disagree.

Suggested fix

At minimum, surface it: a warnings[] entry from swamp doctor extensions naming the file, the target type, and the colliding method — e.g. extensions/models/x.ts: method 'retrieve' already exists on '@swamp/aws/bedrock/knowledge-base'; file not registered. A ValidationFailed / BundleBuildFailed RowState for the source, matching the behaviour in #1101, would make it visible through the surfaces that already exist.

Two smaller improvements if the collision path is being touched anyway:

  • Reject only the colliding method, not the whole file, so unrelated methods survive.
  • Have swamp model type describe note that an extension targeting this type was rejected, since that is the command someone runs when a method they expect is absent.

Workaround

Rename your method (ours is now retrieve_chunks). It works, but only if you already know to suspect a collision.

Environment

  • swamp 20260809.004828.0-sha.b61c9de2
  • @swamp/aws/bedrock 2026.08.19.1, Deno 2.8.3, Linux x86_64
  • Related: #1101 (collision blocked loudly on an extension-defined type), #1571 (the feature request that added the colliding first-party method)
02Bog Flow
◉OPEN○TRIAGED○IN PROGRESS○SHIPPED

Open

8/19/2026, 9:04:56 PM

No activity in this phase yet.

03Sludge Pulse

Sign in to post a ripple.