Public API & dependency budget
Which parts of `@weave-kit/engine` are safe to build on, which are still moving, and how the package enforces the boundary.
Not every import is a promise. This page tells you which parts of @weave-kit/engine are safe to
build on, which are still moving, and how the two are kept apart. It is the contract that downstream
packages (the client SDK) and external integrators code against.
Entry points — three tiers
| Import | Tier | Promise |
|---|---|---|
@weave-kit/engine | stable | app / integration contract; breaking changes only in a major release |
@weave-kit/engine/values | stable (browser-safe) | pure as const constants (field types, filter ops, …); zero imports |
@weave-kit/engine/experimental | experimental | under active development; may change in a minor release |
| any other path | internal | not importable — blocked by the exports map (even dist/… deep paths) |
values is a separate subpath for one reason: it must stay free of the Node server runtime
(pg / fastify / isolated-vm) so it can be bundled anywhere, including the browser.
The stable entry covers engine assembly (createEngine, buildEngineFromRegistry), the core
contracts (core/*), data access, identity (the core/provider/identity contracts; runIdentitySync,
createPgIdentitySource, createFunctionIdentitySource, PgIdentityStore, PgIdentityDirectory,
IdentityAdmin, createDirectoryAuthenticator, enforceSyncedIdentity), Git metadata
sync, custom tools, the generic proxy, the protocol adapters
(auth/rest/mcp/events/graphql), the OpenAPI document generator (buildOpenApiDocument), the GraphQL
schema builder (buildGraphQLSchema / registerGraphQL), the named-enum
registry (EnumDefinition / EnumRegistry / buildEnumRegistry / validateEnumDefinition /
loadEnumsDir / resolveEnumRegistry), the audit/script
contract types, and the scaffolder (scaffoldProject, PROJECT_TYPES).
The experimental entry covers the moving parts that aren't worth freezing yet: the
infrastructure/* provider implementations, the metadata cache, the tunnel transport, and the ops
(health/ready) routes.
The tier boundary is enforced by
tests/unit/public-api.test.ts: the stable entry must expose the contract names and must not leak internals, while the experimental entry must expose them. When you move a module between tiers, update that test and this page in the same change.
Extension points
The stable surface exists so you can extend the engine without patching internal paths:
- Auth / identity —
auth.sourceandmcp.identitiesaccept resolvers, or configureidentity.verifier+ the engine directory. Identity sources implement thecore/provider/identitycontracts (IdentitySource/AuthVerifier/IdentityDirectory/IdentityStore) and are config-injected (no global registry); the engine ships thepgandfunctionsources (see Identity). - Providers — implement the
core/provider/*contracts (alerts, identity, event) and inject them; implementations live outsidecore. - Subsystems — enabled through
weavekit.config.tsand dynamically loaded. - Custom tools & guardrail policies —
core/tools+runtime/tools. - Custom field types —
loadFieldTypesDir/resolveFieldTypeRegistry+ configfieldTypes; a project-localfield-types/dir of declarative registrations (see Custom field types). - Named enums —
enums/<name>.jsondeclarations referenced byenumType, loaded vialoadEnumsDir/resolveEnumRegistry(see Named enums). - Generic proxy —
proxy.resolvercarries the application semantics. - Protocol adapters — the
adapters/*registration functions.
Recent additions (0.9 – 1.0)
-
Multi-tenancy (W3) —
IdentitySubject.scopeId,principalScopeId,scopeOf(ctx),scopedQuotaKey(scopeId, key),withDefaultScope(authenticator, scope); configEngineConfig.scope = { enabled?, defaultScope? }. An object field marked"scope": truescopes every read/write (RBAC row scope + RLS + audit) to the subject's scope. An absent scope is single-scope (unchanged behavior); tenant lifecycle / schema-per-tenant are enterprise. -
Execution pipeline + evidence contracts —
EXECUTION_STAGES/ExecutionPlan/Evidence/EvidenceSink(core/tools/pipeline.ts);runPipeline(runtime/execution/pipeline.ts) orchestrates Plan→Validate→Authorize→Guardrail→Approval→Execute→Commit→Evidence;validateToolArgs(core/tools/validate-args.ts) validates tool arguments against the declaredToolJsonSchema(MCP + custom tools). ConfigEngineConfig.evidence.enabledrecords oneweavekit_evidencerow per execution — every data-access write / workflow transition / tool call, with its real outcome (subsystems/evidence). -
Object-path RLS —
EngineConfig.rls = { enforce?, role? }(default off);resolveObjectRlsRole,assertObjectRlsProvisioned,buildObjectRlsPolicies,planObjectRls,OBJECT_RLS_POLICIES/OBJECT_RLS_ROLE_DEFAULT;MigrateOptions.objectRlsprovisions it. -
QueryBudget —
QueryBudget/QUERY_BUDGET_DEFAULTS/resolveQueryBudget/assertQueryBudget(runtime/data-access/query-budget.ts); configEngineConfig.queryBudget. Bounds rows/filters/sorts (data-access), joins / SQL length / statement timeout (restricted SQL) and GraphQL depth. -
Deploy & schema revision —
weave deploy plan|apply;computeSchemaHash/writeSchemaRevision/latestSchemaRevision(runtime/metadata);analyzeImpact/SchemaImpact(core/storage/impact.ts) classifies the planned DDL (impact + data-compat risk). -
Audit durability —
subsystems.audit.mode(best-effort|transactional|durable),AUDIT_MODES,AuditSink.recordInTx;transactional/durablefail closed at startup unlessallowBestEffortFallback(see Audit). -
Access principal —
AccessPrincipal/SYSTEM_CAPABILITIES/userPrincipal/systemPrincipal(core/types/principal.ts).DataAccessContext.principalis required (the implicitsubjectfield was removed — a missing actor is a compile error, not an unrestricted bypass). -
Cursor pagination —
FindOptions.cursor+FindResult.nextCursor/hasMore;encodeCursor/decodeCursor(runtime/data-access); the audit (AuditQuery.cursor/AuditQueryResult.nextCursor) and evidence (queryEvidence) queries expose the same keyset contract. -
Observability seam —
MetricsSink/TraceSink+METRIC_NAMES(core/observability.ts); configEngineConfig.observability;parseTraceparent/TraceContext(core/trace.ts). The engine emits, ships a no-op default, and correlates the inbound W3Ctraceparent(see Observability). Backends are enterprise E6. -
Operational preflight —
weave doctor(read-only) +weave migrate --preflight; deploy-plan impact analysis and config-drift reporting (computeSchemaHashvslatestSchemaRevision).
Dependency budget
A headless engine should install anywhere and start fast, so the dependency surface is a product feature, not an accident:
core/— zero dependencies (types, pure functions,as constvalues).runtime/— Node built-ins (node:*) only; no third-party runtime imports beyond the platform required by the layer.- A new runtime dependency needs a written justification. Prefer a Node built-in, the way the proxy uses the global
fetchandAbortSignal.timeoutinstead of an HTTP client. - Native / optional dependencies (such as
isolated-vm) belong inoptionalDependenciesand must degrade with an actionable error when absent — users who don't use a feature shouldn't pay for it. ./valuesmust never gain a runtime import (guarded bytests/unit/values-browser-safe.test.ts).