Skip to main content
← Back to list
01Issue
FeatureShippedSwamp Club
Assigneesstack72

Relationships

#1060 Document context.runModel() model-to-model invocation

Opened by stack72 · 7/10/2026· Shipped 7/10/2026

Problem

PR #1810 (4b5be56) added context.runModel() to MethodContext, allowing extension models to call other models mid-execution. The feature is fully implemented and shipped but has zero documentation coverage in the swamp-club docs site (swamp-club/swamp-club).

Worse, several existing docs actively contradict the feature — most notably content/manual/explanation/the-data-layer.md which opens with: "Models in Swamp do not call each other. There is no RPC, no shared memory, no event bus."

Proposed solution

Update the following existing docs and add new content:

Must update (existing docs are now incorrect or incomplete)

  1. content/manual/reference/extensions/model.md — Add runModel to the MethodContext reference section. Document both calling conventions (by definition name, by model type with auto-create), the discriminated result type ({ok, resources} | {ok: false, error}), and that it's unavailable in remote worker contexts.

  2. content/manual/explanation/the-data-layer.md — Revise the opening claim that "models do not call each other." Reframe to explain that data-layer composition remains the default and preferred approach, but context.runModel() enables direct invocation when needed. Explain when each is appropriate.

  3. content/manual/reference/extensions/manifest.md — Update the dependencies field docs (currently install-time only) to explain that dependencies also authorize runtime model-to-model invocation. A model can only invoke models from extensions listed in its own extension's dependencies.

  4. content/manual/explanation/models-types-and-methods.md — Add a section on model-to-model invocation within the execution lifecycle. Cover the concept, safety limits (max depth 10, cycle detection, max 100 invocations per execution, vault secret isolation), and tradeoffs vs data-layer composition.

  5. content/manual/explanation/how-swamp-works.md — Update "models are the unit of work" and "the composition" sections to acknowledge runModel() as a composition primitive alongside data-layer references.

  6. content/manual/reference/extensions/management.md — Update extension info and extension pull output examples to show the new dependency information these commands now surface.

  7. content/manual/explanation/remote-execution.md — Add a note that context.runModel() is not available in remote worker contexts, with the error users will see.

Should add (new content)

  1. New how-to guide (e.g. content/manual/how-to/extensions/invoke-models-from-models.md) — Practical guide showing how to use context.runModel(): setting up manifest dependencies, calling by definition name vs model type, handling success/error results, data ownership semantics (data written under target model's definition, not caller's).

Alternatives

Could document only the MethodContext reference update (#1) and skip the broader docs changes — but this would leave contradictory explanations in place and miss the opportunity to explain the design rationale.

02Bog Flow
✓OPEN✓TRIAGED✓IN PROGRESS✓SHIPPED+ 1 MOREASSIGNED+ 2 MOREREVIEW+ 3 MOREPR_MERGED+ 1 MORENOTIFICATION_SKIPPED

Shipped

7/10/2026, 1:45:15 AM

Click a lifecycle step above to view its details.

03Sludge Pulse
stack72 assigned stack727/10/2026, 1:02:01 AM

Sign in to post a ripple.