Skip to content

proposals: extending the call system - #48

Merged
Kinflou merged 3 commits into
mainfrom
proposals/extensibility
Oct 18, 2026
Merged

Kinflou merged 3 commits into
mainfrom
proposals/extensibility

Conversation

@Kinflou

@Kinflou Kinflou commented Oct 18, 2026 •

Copy link
Copy Markdown
Member

A new proposal, proposals/extensibility.md (status: under discussion), tracked in core#120.

  • One mechanism: official encodings are defined the same way as third-party ones. "Official" means maintained here and shipped by default.
  • An encoding is a definition: a versioned name (bare when official, namespaced otherwise), a profile and vectors. The corpus format and the profile schema become a public spec, and the conformance runner becomes a reusable library.
  • Discovery: core learns about a third-party encoding from a dependency's config.idp, and trusts its profile like the dependency's schemas.
  • Generated code: comline.toml maps each encoding to a type per target. An unmapped encoding is an error, never a fallback, and the per-package format trait (generation#67) isn't sealed.
  • Limit: a format can't need more than the generated data model.
  • Transports and dispatchers stay runtime-only, with documented patterns (middleware by wrapping Dispatch).
  • Generators stay a separate question (core#8).
  • The schema-compatibility proposal's open question on third-party profiles now points here.

zensical build --strict passes.

Second commit: handshakes and unchecked (core#121, runtime#18)

  • Handshakes become a third declared axis: comline@1, none, and namespaced custom ones. They're chosen per protocol with @handshake, and their profile states what they verify. runtime#15 becomes comline@2.
  • Unchecked marks giving up a guarantee Comline makes between peers: a weaker handshake, an unproven encoding, a version-rule override, or skipping checks at runtime (*_unchecked). It's written @unchecked = "reason". It's off by default (annotations.unchecked.allowed), required where it applies, and a warning where it doesn't. Consumers accept it per protocol in config.idp. Making a protocol unchecked is major.
  • Schema compatibility gets rows for @handshake and @unchecked, and its escape-hatch question now points to unchecked.

Third commit: marking a given-up guarantee, four options

  • Wording: "a weaker handshake" was the wrong axis. A custom handshake may do more than Comline's; what matters is whether it establishes the guarantees Comline relies on. The extensibility page now names the four guarantees (schema agreement, encoding agreement, encoding conformance, version honesty) and states the rules around the marker without naming it.

  • proposals/guarantee-marker/: four competing proposals for the marker, each with its case for and against:

    • A: @waives(guarantee = "…")
    • B: @assumes(guarantee = "…")
    • C: @unverified = "…"
    • D: keep @unchecked

    The index separates the two underlying choices: whether the marker names the guarantee, and which word.

How developers bring their own formats, framings, transports and
dispatchers: official encodings defined through the same public
mechanism as third-party ones, profiles declared by dependencies,
implementations mapped per target in comline.toml. Tracked in core#120.
Kinflou added 2 commits October 19, 2026 06:39
The handshake joins format and framing: versioned (comline@1, none,
namespaced custom), chosen per protocol, profiled by what it verifies.
Giving up a guarantee is unchecked: @unchecked with a mandatory reason,
off by default, accepted per protocol by consumers, major in the
version comparison. Tracked in core#121 and runtime#18.
"Unchecked" doesn't say who doesn't check what, and "a weaker
handshake" was the wrong axis: a custom handshake may do more than
Comline's, it just doesn't establish what Comline relies on. Comline's
four peer guarantees are now named, the rules around the marker are kept
name-neutral, and four competing proposals weigh the marker itself.
@Kinflou
Kinflou merged commit 7217c29 into main Oct 18, 2026
2 checks passed
@Kinflou
Kinflou deleted the proposals/extensibility branch November 6, 2026 09:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant