WeaveKit Docs
Reference

Enterprise seams

The stable extension points the closed-source enterprise layer implements on top of the MIT engine — and where the boundary is.

The engine (@weave-kit/engine) is a MIT, headless runtime. Governance and compliance capabilities that would otherwise fork core are delivered by a separate closed-source layer (@weave-kit/enterprise, gated on adoption). The engine's job is to keep a small set of stable seams — interfaces whose semantics, error behavior and evolution are contract-tested — so that layer can plug in without depending on engine internals.

Rule: the engine never imports enterprise, and never branches on edition/license. Enterprise never forks core; it implements a seam and injects it through config.

The seams

SeamDeclarationEngine defaultEnterprise
AuditSinkcore/audit/types.tsPG store + best-effort / transactional / durable modesE2 export, retention, WORM/compliance
ApprovalsBackendcore/tools/types.tsin-memory + PGE3 Redis / HA coordination
WorkflowTimerStore / WorkflowBackendcore/types/workflow.tsPG weavekit_workflow_timers (FOR UPDATE SKIP LOCKED)E3 Redis / HA timers
IdentityStorecore/provider/identity/directory.tsPG weavekit_user / weavekit_departmentE1 SCIM / LDAP / HRIS directory sync
AuthSource / Authenticatoradapters/auth/source.tsstatic key map or custom resolverE1 SAML / multi-IdP
AuthVerifieradapters/auth/verify.tsbuilt-in OIDC/JWT (auth.oidc); custom verifiers pluggableE1 SAML / group→role mapping
GuardrailPolicycore/tools/types.tsin-process policiesE5 Redis-backed advanced guardrails
ProxyTargetResolvercore/proxy/types.tsapp-supplied resolvertarget governance / Cloud control plane
MetricsSink / TraceSinkcore/observability/index.tsno-optelemetry backend / Cloud metering (E6)

Every seam except the observability sinks is marked @enterprise-reserved in source — with one MIT carry-over: the engine ships a built-in OIDC/JWT verifier (auth.oidc), and the AuthVerifier seam stays open for SAML and other protocols. tests/unit/seams/ pins the consumer-facing guarantees (error, close, retry, idempotency) so an enterprise implementation can rely on them.

Audit durability

audit.mode selects durability: best-effort (default) is a fire-and-forget process buffer; transactional writes the audit row inside the business transaction; durable writes a transactional outbox row plus a relay (crash-safe, at-least-once). transactional/durable require an in-transaction sink — startup fails closed (assertAuditSinkCapability) unless the host sets allowBestEffortFallback: true. Export, retention and compliance policy are enterprise E2; the engine only captures. For production governance use, prefer transactional/durable (the governance starter preset scaffolds transactional); best-effort may lose the tail on a crash.

Observability (metrics & trace)

The engine emits metrics and finished spans; it ships no dashboard, alerting or exporter. Inject a sink via config.observability:

export default {
  // ...
  observability: {
    metrics: myOtelMetricsSink,   // implements MetricsSink
    trace: myOtelTraceSink,       // implements TraceSink
  },
};

Emitted metrics are the single-source METRIC_NAMES: http.request.duration_ms, http.response, rbac.deny, audit.success, audit.failure, query.budget.reject, pool.state, execution.duration_ms.

Label discipline (contract): label values must be low-cardinality and PII-free. Never put tenant data, record ids, SQL text, credentials or other secrets in labels — those belong in the (audited) data path, not in metrics. Trace correlation uses the inbound W3C traceparent (see core/trace.ts).

Writing a backend

  1. Implement the interface from @weave-kit/engine (types are re-exported from the package root).
  2. Inject it through the corresponding config field (or createEngine options).
  3. Rely on the documented error/close/retry contract — do not depend on engine internals.

Anything not on this list is engine-internal and may change between minor releases; see Contract freeze for the frozen surface.

On this page