Skip to content
ContractSpec
Start here

Package manual · platform

·Governance, decisions and approvals

lib.contractspec-connect

Provider-neutral packet authority and durable decision receipts for ContractSpec Connect.

platformlibraryv0.1.5experimentalwebserverbrowserbunnode
@lssm-tech/lib.contractspec-connect
bun add @lssm-tech/lib.contractspec-connect
Package source ↗Manifest ↗

Manifest declarations describe the current workspace; they do not verify registry publication or runtime execution.

Package guide

Provider-neutral packet authority for ContractSpec Connect.

The ./operations/review/* and ./operations/governance/* subpaths own the existing review decision, assignment, escalation, policy and constraint operation declarations. Their schemas, error contracts, policy references and approval requirements are unchanged. These declarations do not issue approval or execute policy changes; existing compatibility paths forward to the same canonical objects. The root trust-kernel entry remains unchanged.

The package exposes digest-bound context, plan, pre-mutation, post-diff, and promotion decisions without depending on the workspace bundle or a concrete CI, storage, identity, cloud, or analytics provider.

Production hosts use durable_required mode. A permit is usable only when its receipt was appended to the injected durable store and exact read-back matches the issued digest. Durable decisions also require a host-injected Ed25519 signature port; private keys never enter semantic requests. Consumers can use checkConnectPermitFromStore to re-read and verify the signed receipt at the point of use. Missing storage or signing, persistence errors, stale or expired receipts, scope drift, and substituted read-back all fail closed.

ts
import {
  assertConnectPermit,
  createConnectDecisionRequest,
  createConnectPacketAuthority,
} from "@lssm-tech/lib.contractspec-connect";

const authority = createConnectPacketAuthority({
  durabilityMode: "durable_required",
  policy,
  receiptStore,
  signaturePort,
  clock,
  idFactory,
});

const request = createConnectDecisionRequest({
  id: "connect.request.patch-1",
  phase: "pre_mutation",
  scope,
  actorRef: "agent:builder",
  requestedAt: clock.now(),
  contextPacketRef,
  planPacketRef,
  deliveryPlanRef,
  qualityPlanRef,
  target: {
    action: "apply_patch",
    pathPrefixes: ["packages/contracts"],
  },
  predecessorDecisionRefs: [],
});

const receipt = await authority.decide(request);
assertConnectPermit(receipt, {
  phase: "pre_mutation",
  request,
  now: clock.now(),
  requireDurable: true,
});

Connect decides policy. Builder produces candidate code. CI executes approved quality plans. Runtime Nodes execute the separately governed work orders issued through the V3 bridge below. This package does not merge, release, deploy, or execute provider effects.

Reference vocabulary

The Connect reference types (ConnectSha256Digest, ConnectMutationAction, ConnectPromotionAction, ConnectAction, ConnectArtifactRefV1, the decision, context-packet, plan-packet, delivery-plan and quality-plan refs, and ConnectAuthorityScopeV1) are owned by Core at @lssm-tech/lib.contracts-spec-core/connect-references. This package re-exports the same types from ./contracts and the root, so existing imports keep working. Specs that only reference Connect decisions, such as Builder delivery authority, import the Core vocabulary and do not depend on this runtime.

Lifecycle authority for host hooks

@lssm-tech/lib.contractspec-connect/lifecycle-authority decides how an operator's durable hook grant governs host lifecycle hooks and follows the agent's own commits. It is pure: hosts supply a read-only git port (ConnectRepositoryLineagePort) and their governed and operator-only path classification (ConnectPathClassifierPort).

  • CONNECT_LIFECYCLE_SEMANTICS: session start and stop are read-only grant checks, a handoff records a non-terminal checkpoint, no lifecycle hook terminalizes the grant, and merge is a promotion that is never delegated to a local grant.
  • evaluateConnectGrantLineage: an exact grant applies only at its anchor commit; a lineage grant follows HEAD on the same branch through at most CONNECT_GRANT_LINEAGE_MAX_COMMITS descendant commits whose changes stay inside the signed path prefixes and never touch operator-only files. It never widens the signed scope, and repository failures refuse.
  • evaluateConnectLifecycleAuthority: ordered refusals (promotion_not_delegated, no_grant, revoked, expired, workspace_mismatch, actor_mismatch, event_not_granted, scope_mismatch, then the lineage refusals).
  • shellWordsTargetOperatorGrant and isConnectOperatorGrantStorePath name the operator-only grant command and store, so hosts can deny agent self-grants.

The workspace bundle's connect hook commands implement the ports; see docs/refactoring/lssm-ecosystem/HOOK-AUTHORITY-DESIGN.md for the wiring.

Connect-owned Runtime Node V3 issuance

@lssm-tech/lib.contractspec-connect/runtime-v3 exports createConnectRuntimeV3Authority and createConnectEd25519SignaturePort. The issuer runs the existing packet authority in durable_required mode. Hosts supply current policy, append-only receipt storage, a real signature port, a scoped issuance-evidence store, current revocation lookup, trusted clock, ID factory and issuer reference. Missing, unavailable or inconsistent ports fail closed.

issueLifecycle accepts a pre-mutation request plus canonical unsigned standard and mandatory cleanup drafts, two pristine budget reservations and the accepted operation. Caller drafts cannot supply issuer, signature, authorization or issuance time fields. The request actor/scope and the exact draft, plan, source and budget digests are bound into the signed decision request. Connect derives both signed orders and pending cleanup authority from that durable decision, rechecks current policy/revocation, and returns only after exact issuance-evidence read-back. Concurrent exact retries return the same persisted lifecycle; conflicting requests for the same scoped operation cannot replace it.

The standard order expires no later than the policy receipt. The cleanup order has no expiresAt; its review time and execution deadline never erase custody. verifyCleanupCustody verifies retained signed issuance evidence even after normal expiry or revocation. It is historical verification, not permission to execute a cleanup effect. Runtime Node still requires independent current cleanup observation, nonce, scope and custody checks for provider execution.

verifyAdmission checks accepted, authorizing or queued operations with no execution tuple. verifyDispatch remains queued-only. Both reread exact issuance and receipt evidence, recompute the signed payload, verify its Ed25519 signature, reevaluate current policy, check revocation before and after policy work, and reject clock regression or expiry. They implement the canonical runtime verification boundary; SQLite/PostgreSQL still own atomic budget reservation, order registration, claims, queue transport and terminal receipts.

The issuance store is Connect authorization evidence, not another runtime owner. Its append must be atomic first-write-wins for the full tenant/workspace/ environment/operation tuple; immutable records retain the exact draft, request, receipt and resulting lifecycle. Normal revocation is a separate authoritative lookup and must never delete cleanup liability or historical decision evidence.

The WebCrypto adapter signs with host-injected Ed25519 CryptoKey objects and verifies against the configured public key/reference. It does not load keys, generate production identities or fall back to a fixture signer. Tests use real nonextractable ephemeral keys, file-backed SQLite receipt/issuance/revocation state, close/reopen and the actual SQLite Runtime Node issuance/dispatch adapters. Live policy, identity provisioning and key custody remain host configuration.

Tool authority: discovery is not authority

The root entry exports Connect tool authority V1 for MCP servers and tool registries. Discovery describes tools; it never grants identity, approval or effect authority.

  • connectToolKeyV1 derives a server-qualified key (<source>:<serverRef>#<toolName>), so a tool name advertised by another server never borrows a scoped key.
  • filterConnectVisibleToolsV1 shows a caller only the discovered tools whose key is exactly in the caller's allowedToolKeys (no wildcard or prefix matching), each with effectAuthority: 'none'.
  • admitConnectToolInvocationV1 projects one call to an effect only when the tool key and action are in the caller's scope, a pre-mutation request names the caller's actor, the caller's exact scope (digest equality) and exactly this tool, its permit passes checkConnectPermitFromStore, and the Runtime Node V3 standard work order is digest-valid, bound to that permit, inside the scope's tenant and environment, names the tool and the advertised descriptor's digest as its capability, binds the argument digest as its payload, and is exactly the order, request and permit the durable issuance store recorded (work_order_not_issued otherwise). The issuance evidence must then pass Connect's record check and its currency check: revocation, a fresh policy evaluation and the trusted clock (connect_authority_not_current once the decision is revoked, the policy denies or the order expires). Each failed check has its own refusal code.

Admission takes the same ports as createConnectRuntimeV3Authority (policy, receipt, issuance and revocation stores, signature, clock, issuer reference) plus an invocations ledger (ConnectToolInvocationLedgerPortV1). Time comes only from the clock port; the caller passes no admission time. Each issued order is single-use: the first admission is recorded insert-if-absent under the operation scope and read back, and every later admission of that order, with the same or another invocation id, is refused as work_order_already_admitted. A host that crashes after admission resumes from the Runtime Node operation, never by re-admitting. Port failures and timeouts refuse (authority_unavailable).

projected admits the call; it does not execute it. Runtime Node dispatch must still pass verifyDispatch, which re-checks revocation, policy, the trusted clock and the operation's claim and fencing state at the point of execution.

Advertised annotations, claimed scopes or identities, read-only hints and a model's choice of tool are never consulted. A descriptor that changes after authorization is refused as tool_descriptor_changed.

Concrete adapter qualification

The real local Ed25519/durable-authority SQLite composition test belongs to the SQLite integration, which injects Connect into its issuance and dispatch adapters. From repository root, run bun test ./packages/integrations/lssm-os-state-sqlite/src/connect-runtime-v3.test.ts. The Connect package's own bun test remains provider-neutral.

Canonical compatibility leaves: ./operations/registry.governance, ./operations/registry.review. These leaves preserve the original implementations and object/class identity; legacy ContractSpec imports forward to these owners.

Relationships

THIS PACKAGElib.contractspec-connect36 import paths

Arrows point from a package to its direct dependency. Counts are derived from captured workspace manifests.

6 declarations

Declared capabilities

ContractSpec Connect packet authority

Issue and verify digest-bound context, plan, mutation, diff, and promotion decisions.

Scripts

  • publish:pkgbun publish --tolerate-republish --ignore-scripts --verbose
  • publish:pkg:canarybun publish:pkg --tag canary
  • buildcontractspec-bun-build build
  • build:bundlecontractspec-bun-build transpile
  • build:typescontractspec-bun-build types
  • cleanrimraf dist .turbo
  • devcontractspec-bun-build dev
  • lintbun run lint:fix
  • lint:fixnode ../../../../scripts/biome.cjs check --write .
  • lint:checknode ../../../../scripts/biome.cjs check .
  • prebuildcontractspec-bun-build prebuild
  • testbun test
  • typechecktsgo --noEmit