Externals: load each external repo's schemas alongside its artifacts

[avrabe]

Problem

When a downstream repo declares an external in rivet.yaml like:

externals:
  synth:
    path: ../synth
    prefix: synth

rivet validate happily loads synth's artifacts into the graph, but only the downstream repo's schemas are consulted when type-checking those artifacts. Result: every artifact whose type is defined in synth's schema but not in the downstream's schema raises an unknown artifact type ERROR.

In sigil today this produces 326 errors, all of the form:

ERROR: [synth:SWA-002] unknown artifact type 'sw-arch-component'
ERROR: [synth:VG-005] unknown artifact type 'system-req'
ERROR: [synth:E2E-VER-009] unknown artifact type 'sys-verification'
ERROR: [synth:CC-007] unknown artifact type 'sw-req'
...

The artifacts are well-formed in synth's own validation; they only break when sigil tries to type-check them against sigil's schema set (common, dev, stpa, stpa-sec, cybersecurity).

Impact

The 326 schema errors drown out real lifecycle issues in the downstream repo (sigil currently has 54 lifecycle coverage gaps and 41 warnings — these are buried in the noise). rivet validate becomes a wall of red rather than a steering instrument.

Proposed behavior

When loading an external, also load that external's schemas-path (or its declared schema files) into the type-check namespace, scoped to artifacts that originate from that external. Concretely:

1. Resolve the external's own rivet.yaml and read its schemas-path / schemas list.
2. Register those schema types under the external's prefix (e.g. synth:system-req is a known type, but does not collide with downstream's own system-req if it exists).
3. Type-check synth:-prefixed artifacts against synth's schemas, not the downstream's.

If an external's rivet.yaml cannot be located (or it doesn't have one), fall back to a permissive mode that demotes unknown artifact type from ERROR to INFO for externally-prefixed artifacts.

Alternatives considered

• Vendor schemas into the downstream repo — defeats the purpose of externals; creates drift.
• Add the missing types to the downstream schema — same drift problem, plus pollutes the downstream's type namespace with concepts it doesn't own.
• Demote externally-scoped errors globally — loses signal when an external genuinely has malformed artifacts.

Repro

# In sigil (current main), with synth checked out at ../synth:
rivet validate
# Result: FAIL (326 errors, 41 warnings, 114 broken cross-refs)
# All 326 errors are 'synth:* unknown artifact type ...'

Sigil version: rivet 0.4.3 (2d1a16b feat/agent-pipelines-foundation 2026-04-24).

Related

• pulseengine/sigil — most-affected downstream; this issue is filed off a hygiene pass there.

[avrabe]

Triage: the "Proposed behavior" section is close, but it lists implementation steps rather than outcome-shaped, oracle-checkable acceptance bullets. Could you add an explicit ## Acceptance Criteria section in roughly this shape?

## Acceptance Criteria

- [ ] When a downstream `rivet.yaml` declares an external whose own `rivet.yaml` has a `schemas-path`, those schema types are registered under the external's prefix and used to type-check `<prefix>:`-scoped artifacts.
- [ ] In the sigil-with-synth repro from the issue body, `rivet validate` reports 0 `unknown artifact type` errors against `synth:*` artifacts (the 326-error wall is gone).
- [ ] A downstream-local type with the same name as an external type does not collide; verified by a fixture containing both `synth:system-req` and a downstream `system-req`.
- [ ] When an external has no `rivet.yaml` (or no `schemas-path`), `unknown artifact type` for that external's prefixed artifacts is demoted from ERROR to INFO, with a single one-line note explaining the fallback.
- [ ] Integration fixture under `rivet-cli/tests/fixtures/externals-with-schemas/` (or similar) covers both the resolved and the unresolved-fallback paths.
- [ ] No regression: existing externals tests pass; `rivet validate` on the rivet repo itself is unchanged.

Once those land in the body, this can be picked up for implementation.

---

Generated by Claude Code — issue-triage agent run 2026-04-30.

---

Generated by Claude Code