lib.contractspec-connect

@lssm-tech/lib.contractspec-connect

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.

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.

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.