Skip to main content
codecalc has four extension kinds. Each has a versioned interface, a machine-readable manifest, a conformance suite, a built-in reference implementation, and a reference third-party extension under examples/extensions/.

Trust model — read this first

An extension is Python that runs IN-PROCESS, and is trusted BY INSTALLATION. This is the same posture as a pip dependency, a pytest plugin, or a Django app: installing one is the trust decision. A manifest and a permission allowlist cannot confine in-process code — an imported module can import os or socket regardless of what it “declared” — so codecalc does not pretend they do. What the manifest and policy do give you is real and useful, just not a sandbox against a hostile extension author:
  • Provenance — an optional integrity digest (sha256:…) the operator pins; the loader refuses a payload whose bytes don’t match. This proves the code is unaltered, not that its author is safe.
  • Operator policy — a permission declaration the operator’s policy must approve, and a per-permission allowlist (CODECALC_EXTENSION_ALLOWED_PERMISSIONS).
  • Audit + discovery — every loaded extension is enumerable (codecalc doctor → extensions) with id, kind, version, origin, health, and supported operations.
  • A kill switch — CODECALC_DISABLE_THIRD_PARTY_EXTENSIONS=1 refuses every third_party-origin extension; built-ins are unaffected.
  • No impersonation — the builtin: id prefix is reserved; a third-party extension that claims it, or collides with a built-in id, is rejected.
The genuinely untrusted input — the payload (the user’s code) — is confined by the execution providers (gVisor / AppContainer / rlimits), a separate, enforced layer. An extension never widens that boundary: a language pack only contributes an argv template; the payload still runs inside the provider sandbox. A renderer or verifier never executes payload code at all. Confining a hostile extension author (WebAssembly, or out-of-process RPC with OS-level restrictions) is out of scope for this version and is the boundary to add if untrusted-author extensions ever become a goal.

Manifest

Every extension carries an extensions.ExtensionManifest (frozen): kind, extension_id, name, version, interface_version, origin (builtin|third_party), compatible_codecalc, compatible_contract, declared_permissions, supported_operations, and optional integrity. Permissions are drawn from a fixed vocabulary (extensions.KNOWN_PERMISSIONS); a permission outside it is refused for any origin.

Policies

  • Compatibility. The enforced gate is an interface-major match: an extension’s interface_version major must equal the kind’s *_INTERFACE_VERSION major. compatible_codecalc / compatible_contract are declared and surfaced in discovery, compared only by major — codecalc does not solve semver ranges (a deliberate non-goal; interface-major matching already guarantees API compatibility).
  • Deprecation. An interface is stable within a major. A breaking change bumps the kind’s major; the previous major is supported for twelve months after the bump (the same window the result contract uses). Additive, compatible changes bump the minor and never break a conforming extension.
  • Signing / integrity. Pin an extension by integrity digest; the loader verifies it. For distribution, third-party extensions SHOULD ship a sigstore build-provenance attestation (the same mechanism codecalc’s own release artifacts use) and be pinned by digest; verifying a signature against an operator-managed keyring is a documented opt-in on top of digest pinning.
  • Security response. A vulnerability in a built-in extension is handled like any codecalc security issue (see SECURITY.md). A third-party extension is the installer’s responsibility, but codecalc gives the operator the tools to respond: pin/repin the integrity digest, narrow the permission allowlist, or disable third-party extensions entirely with the kill switch.

Compatibility, for an extension author

What you can rely on across a *_INTERFACE_VERSION minor bump, without re-reading this document each time: your extension keeps loading and keeps working exactly as it does today. Minor bumps are additive only — a new optional manifest field, a new operation a kind’s protocol supports, a new permission in KNOWN_PERMISSIONS — never a change to what an existing method signature means or a removal of one you already implement. The enforced gate is major-only (see Policies above): write your interface_version against the kind’s current major and it is compatible with every minor released under that major, past or future, with no range to solve. What breaks it: a major bump on the kind you extend. That is the one change this framework does not paper over — a breaking interface change bumps the major, and the previous major keeps working for twelve months after (same window docs/contract/README.md uses for the result contract, and for the same reason: an extension author who gets less notice than a codecalc result client would be the worse-supported half of the same server). codecalc doctor’s extensions block reports the interface version your extension declared alongside the one codecalc currently ships, so a version skew is visible in discovery rather than only in a call failing.

Verifiers submit evidence — they never grade

A Verifier.verify() returns an immutable Evidence record (outcome ∈ supports/refutes/inconclusive) — there is no grade/score field. grades.py alone maps evidence to a grade. The VerifierRegistry.collect_evidence path (a) hands each verifier a deep copy of the claim/context so it cannot poison another verifier or the grader, (b) isolates each call, and (c) drops any evidence for a claim_kind the verifier did not declare. A single third-party supports is advisory input, not a verdict.

Discovering what’s loaded

codecalc doctor includes an extensions block: the framework version, the operator policy (allow_third_party, the allowlist), and every loaded extension’s descriptor. Built-ins load always; third-party extensions load only when the operator wires them and the policy permits.