OSS-first docs
These docs teach the open system first: contracts, generated surfaces, runtimes, governance, and incremental adoption. Studio shows up as the operating layer on top, not as the source of truth.
Knowledge mutation governance
Provider-backed knowledge is not read-only forever. Email sends, Drive permission changes, tombstone handling, replay repairs, and source metadata updates all need explicit governance before they mutate an external system.
Fail closed
Non-dry-run mutations require an idempotency key and audit evidence. Approval-required operations need approval refs. Outbound sends also need an approved send gate.
Leave evidence
Every evaluation returns an audit envelope with status, missing evidence, idempotency, approval refs, and the decision timestamp.
Runtime gate
const result = await executeGovernedKnowledgeMutation(
{
operation: "drive.permission.update",
sourceId: "src_drive_support",
requiresApproval: true,
governance: {
idempotencyKey: "tenant:drive-permission:123",
auditEvidence: { evidenceRef: "audit://drive/permission/123" },
approvalRefs: [{ id: "approval-123" }],
},
},
() => drive.updatePermission(input),
{ audit: (envelope) => auditTrail.write(envelope) },
);
if (result.status === "blocked") {
return result.auditEnvelope.requiredEvidence;
}ContractSpec surface
Use knowledge.mutation.evaluateGovernance when an app or control-plane workflow needs to expose mutation decisions as a contracted action. It mirrors the runtime helper and gives Connect, ops tools, and review packets one stable contract to reference.
import {
EvaluateKnowledgeMutationGovernance,
} from "@contractspec/lib.contracts-spec/knowledge/operations";
registry.register(EvaluateKnowledgeMutationGovernance);Knowledge and context
Bind trusted knowledge sources to the system without losing governance or isolation.
Telemetry
Instrument surfaces, collect evidence, and keep observability aligned with the contract model.
Why ContractSpec
Keep educational and comparison content reachable without letting it define the primary OSS learning path.