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 apip 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
integritydigest (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=1refuses everythird_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.
Manifest
Every extension carries anextensions.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_versionmajor must equal the kind’s*_INTERFACE_VERSIONmajor.compatible_codecalc/compatible_contractare 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
integritydigest; 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 theintegritydigest, 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
AVerifier.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.