@lssm-tech/lib.builder-spec
Builder's lane keys, execution plan packs and evidence bundle references use the pure @lssm-tech/lib.orchestration-spec/execution-lanes declaration owner. These remain the canonical types forwarded by execution-lanes; Builder does not depend on the execution runtime to describe plans or evidence.
Website: https://contractspec.io
Typed Builder control-plane contracts, capabilities, operations, events, and validation for governed omnichannel authoring.
What It Provides
BuilderWorkspace.authorityScope optionally records the host-verified organization, team and workspace at creation. Legacy records omit it. The scope is evidence for host access checks, not an execution grant or a replacement for current authority.
- Builder workspace, conversation, source, directive, blueprint, plan, preview, readiness, and export types.
- Specs-pack import, analysis, readiness, implementation-plan, task-ledger, Connect decision, apply receipt, trace, progress, alignment, verifier decision, replay, and customer-delivery-loop types for external product-intent packs.
- RoleMorph preview, surface-inspection, policy-diff, policy-variant, missing-binding repair, Workbench packet, preference snapshot/store-port, authorization summary, replay bundle, and assurance/audit evidence types for adaptive operating surfaces.
- Full Builder command/query/event surface aligned with the Builder layer spec pack.
- Capability specs for chat, voice, ingestion, fusion, planning, preview, harness, and export workflows.
- Validation helpers for runtime and host layers, including fail-closed delivery-loop evidence checks.
- Provider-neutral platform intent, planning-port, reviewed handoff, task-ledger, and separate software/operational/production readiness contracts.
Public Entry Points
. resolves through ./src/index.ts./capabilities resolves through ./src/capabilities/index.ts./commands resolves through ./src/commands/index.ts./events resolves through ./src/events/index.ts./queries resolves through ./src/queries/index.ts./types resolves through ./src/types/index.ts./validation resolves through ./src/validation/index.ts
Notes
- This package is a compatibility surface. Additive evolution is preferred.
- Connect authority, decision and plan references (
ConnectAuthorityScopeV1, ConnectDecisionRefV1 and the packet/plan refs) come from the Core vocabulary at @lssm-tech/lib.contracts-spec-core/connect-references. The spec references Connect decisions but never depends on the Connect runtime, which re-exports the same types.
- Provider routing, runtime-mode and risk vocabulary comes from
@lssm-tech/lib.provider-spec, a qualified pure platform spec.
- Builder orchestration reuses execution-lane identifiers and harness evidence references instead of introducing a second runtime taxonomy.
- Generated-app runtime channels are out of scope here; this package models the Builder control plane only.
Builder v2 control-plane records
@lssm-tech/lib.builder-spec publicly exports the Builder v2 control-plane alignment records from both the root entry point and ./types:
BuilderIntentDecisionRecord captures IntentGate ambiguity classification, selected execution lane, escalation decision, and evidence refs before Builder execution proceeds.BuilderToolCapabilityManifest captures scoped tool availability, supported operations, runtime modes, degraded/blocker state, and evidence refs without depending on a concrete MCP/runtime implementation.BuilderToolActivationReceipt records why a scoped tool was activated, the permissions actually used, produced evidence, and optional Connect review packet refs.BuilderTaskLedgerEntry maps Builder-visible task state to leased/running/blocked/completed/stale ledger entries with heartbeat, recovery-rule, and evidence refs.
BUILDER_V2_CONTROL_PLANE_ARTIFACT_KEYS lists the canonical artifact keys for these records.
Contract Intelligence types
Builder-spec now includes additive Contract Intelligence types for contractization reports, portable bundle manifests, selective import decisions, and thin portfolio envelopes. These types are dry-run/advisory surfaces and preserve graph/repo-reality/adoption/replay refs instead of defining a second graph.
Contract Intelligence contracts
@lssm-tech/lib.builder-spec now includes additive Contract Intelligence types for contractization reports, portable bundle manifests, import reconciliation, selective dry-run adoption, portfolio envelopes, vertical patch notes, and recurrent radar reports. These contracts are additive and dry-run oriented.
Builder Intelligence contracts
@lssm-tech/lib.builder-spec now includes additive Builder Intelligence contracts for index manifests, chunks, context packets, durable memory items, trajectories, ReasoningBank-style patterns, SONA-lite routing policies, and stale-memory reports. These contracts are dry-run first: graph refs, source hashes, provenance, path-only redaction, review status, and rollback metadata stay authoritative while embeddings, stores, and adaptive routing remain optional later layers.
RoleMorph preview contracts
@lssm-tech/lib.builder-spec includes additive RoleMorph Builder contracts for serializable role selectors, policy variants, surface summaries, inspection packets, surface diffs, safe missing-binding repair suggestions, Workbench panel packets, preference snapshots/store ports, authorization summaries, replay bundles, and branded assurance/audit evidence requirements. These contracts describe Builder preview, inspection, replay, and evidence surfaces; rendering, durable storage, provider calls, and production authorization remain in host/runtime layers.
Builder customer-delivery-loop contracts
@lssm-tech/lib.builder-spec includes additive interface-first delivery-loop contracts for quote/order/acceptance/account/source refs from BillingOS, customer commitment/work/authority/policy-gate refs from CompanyOS, scoped PRD/test-spec/specs-pack artifacts, implementation plans, task ledgers, Connect/replay refs, acceptance evidence, release capsules, and customer-handoff refs. Validators keep commercial amount-like data in BillingOS refs and block execution-approved, verified, or handed-off states until required evidence exists.
These contracts are evidence/ref aggregates only: provider execution, durable storage, repository writes, app shells, and customer sends remain in host/runtime layers.
BuilderBlueprint can carry additive goal, operational, workload, restriction, provider-policy, logical-architecture, economic, observability, flag/experiment, evolution, provenance, conflict, and locked-field intent. BuilderPlatformPlanningPort is deliberately read-only: it validates, compares architectures and solo/monorepo topology, obtains cost estimate status/ranges/freshness, previews plans, and reports unsatisfiable intent. It has no credential or apply methods.
Neutral intent becomes a PlatformHandoffPacket only after a Connect-bound review. Packets contain metadata-only references and a contract-first ledger across contracts, code, infrastructure, telemetry, cost, flags, and migrations. Apply authority remains with a Connect-authorized runtime.
The compatibility and authority-boundary record is captured in
docs/platform-integration-connect-evidence.md.
PlatformHandoffPacket.digest is Builder's canonical payload SHA-256 hex, excluding the derived id and digest fields. Consumers should use Builder's canonical hashing implementation instead of another domain's digest convention. The digest proves content identity; execution still requires Connect authority.
Managed readiness requires a registered, unblocked, export-capable managed runtime target and an active non-offline provider. Catalog capability alone is insufficient. Rerun readiness after upgrading to refresh persisted reports; this availability check does not replace execution authority or live qualification.
Builder company context is available through the host-owned
builder.companyContext.resolve query and POST
/api/companyos/builder/context/resolve. It accepts an owned workspace ID and a nonempty question up to 4096 UTF-8 bytes. Missing grounding configuration returns 503. The web BFF preserves authentication and response status; the client treats this as a query, never a saved mutation, and does not auto-retry. Context grants no execution authority. Provider configuration, a visible member control and live qualification remain required before advertising it.
Hosted preview evidence
Blueprint-only previews remain pending and have no fabricated hosted URL.
BuilderPreview records source/artifact identity and a canonical deployment receipt reference only after host observation qualifies the target and health. The runtime's optional previewHost reads host-owned deployment state; request payloads cannot supply evidence. Ready requires the exact workspace, blueprint version, source revision, target and artifact set, a digest-valid successful delivery receipt with health evidence, and a recent HTTPS URL observation on an allowed origin. Refresh invalidates previous readiness before observation and rejects blueprint changes during IO. Observation is bounded to twenty seconds.
This bridge does not grant deployment authority. Concrete provider provisioning, live observation adapters and their production qualification remain required.
Snapshot and preview reads also revalidate stored canonical receipt material and blueprint version. Legacy ready records, missing receipts, changed blueprints, tampered digests and stale observations project as pending with no hosted URL; this does not rewrite stored records or require a blanket data migration.
Candidate request and status contracts
BuilderCandidateState and BuilderCandidateStateSchema describe review, approval, queue, execution and evidence states without granting authority. Queued/running states require a canonical operation reference; success also requires receipt and artifact references. Existing plan operations retain their capabilities, while the runtime requires host-verified actor scope and the exact reviewed plan/blueprint digest before delegating to an authority-backed service.
The explicit ./control-plane/constants, execution approval/rejection command and trace-query leaves own the existing declarative ControlPlane operations used by Company projections. Historical ContractSpec imports retain identical schema and operation objects, keys, wire shapes and admin policy. Declarations grant no approval or execution authority; trusted runtime policy enforcement is unchanged.
Product-intent contracts
@lssm-tech/lib.builder-spec/product-intent and ./product-intent/<leaf> own the product-intent schemas (evidence, insights, findings, tickets, patch intents, impact reports, task packs, wireframes), ProductIntentSpec,
ProductIntentRegistry and the port-driven ProductIntentRuntime. Legacy
@lssm-tech/lib.contracts-spec/product-intent imports forward to the same instances.
The control-plane/policies/controlPlaneMessaging.policy entry owns the existing version 2.0.0 messaging safety policy. Its blocked, assisted and autonomous rules are unchanged; contracts-spec forwards the same policy object.
