lib.lssm-os-spec

@lssm-tech/lib.lssm-os-spec

Canonical, provider-neutral context and goal contracts for LSSM OS.

The package gives agents and applications one deterministic context capsule for understanding the LSSM ecosystem, plus a goal graph that connects product intent to measurable outcomes without granting runtime authority.

Contract families

• Context: ecosystem manifest, product definitions and bindings, architecture invariants, authority boundaries, strategic priorities, glossary entries, ownership/escalation routes, and the aggregate context capsule.
• Goals: project specs, typed goals, outcome metrics and bindings, observations, conflicts, and blocking harm guardrails.
• Validation: secret detection, canonical ordering, unique identifiers, reference integrity, target-direction checks, and authority/escalation checks.

Every V1 wire value uses contractVersion: "1.0.0", strict object schemas, UTC timestamps, and explicit dataHandling. V1 arrays are canonical when ordered by their stable id; validators reject ambiguous duplicate or dangling references.

Context V2

Context V2 is additive and is the production-write format. It extends product definitions with capability, dependency, policy, maturity, economics, provider, evidence, and topology references. Context V1 remains read-compatible and can only move forward through migrateLssmContextV1ToV2, which retains the complete source payload and binds both versions with deterministic SHA-256 digests.

catalog/ecosystem.v2.json and catalog/package-bindings.v2.json are checked-in, secret-free derived indexes of the single canonical V2 capsule source. The ecosystem index binds the exact capsule digest, so a changed source, index, relation, or manifest digest fails validation. They are included in the published package; consumers should import schemas and helpers from @lssm-tech/lib.lssm-os-spec/context and must not write V1 capsules.

Package binding IDs stay stable when an owning package moves. The canonical capsule records the current physical locator separately from the binding name; regenerate both catalog indexes together from that source before qualification.

This package is a pure platform spec: it validates supplied values and never reads the filesystem or an ambient clock. validateLssmCanonicalCatalogV2 therefore requires the caller's now instant and fails closed with catalog.clock_required without one. Filesystem containment checks for catalog locators live in @lssm-tech/lib.lssm-os-runtime/catalog-locator-node; this package keeps only the lexical validateLssmCanonicalRelativeLocator gate.

V2 also makes product goals, outcomes, non-goals, OSS/managed posture, responsibility boundaries, contract provision/consumption, Connect requirements, first-party consumers, review cadence, and source revision explicit. Capsules carry active work, rules, frozen contracts, decisions, assumptions, evidence, source digests, redaction decisions, and freshness state.

Product intent is referenced, not redefined:

const productIntentRef = {
  id: "activation-intent",
  kind: "product_intent_spec",
  key: "product-intent.activation",
  version: "1.0.0",
};

This identity shape maps to the stable identity/meta fields of ProductIntentSpec while keeping this foundational package independent of the product-intent workflow and runtime.

Runtime topology V1

The additive runtime-topology subpath describes T0 embedded through T5 partitioned deployments, component/version bindings, capacity observations, scale policy and decisions, cache consistency, partition plans, governed topology transitions, receipts, and qualification evidence. These contracts are declarative and provider-neutral: SQL remains authoritative, cache state is derived, and a topology plan never grants execution authority. Runtime Node must bind each observable transition step to its existing signed work order, operation, claim, attempt, fence, and Connect authorization.

T0 may use embedded SQLite, an in-process L1 cache, and a bounded local durable queue. T1 may add the same optional L1 cache while PostgreSQL provides both the authority store and durable queue. Neither requires Redis or an external broker. T2 and T3 are optional qualified capabilities, and T4/T5 claims require their own exact-version evidence. Every cache policy requires bounded single-flight or fenced-lease stampede protection. All component profiles bind the corresponding Agent Platform deployment topology instead of redefining regions or instances.

The additive promote_state_backend and demote_state_backend transition classes are the only T0↔T1 recipes. They require provision, shadow, canary, drain, cutover, reconciliation, rollback, and decommission phases. A database change therefore cannot masquerade as cache, broker, resize, or HA work.

Usage

import {
  LssmContextCapsuleV1Schema,
  assertLssmContextCapsuleV1,
} from "@lssm-tech/lib.lssm-os-spec";

const capsule = LssmContextCapsuleV1Schema.parse(input);
assertLssmContextCapsuleV1(capsule);

The contracts describe intent and governance only. They do not authorize an actor, execute a goal, resolve a conflict, or call a provider.

Entrypoints

• @lssm-tech/lib.lssm-os-spec
• @lssm-tech/lib.lssm-os-spec/common
• @lssm-tech/lib.lssm-os-spec/context
• @lssm-tech/lib.lssm-os-spec/goals
• @lssm-tech/lib.lssm-os-spec/runtime-topology
• @lssm-tech/lib.lssm-os-spec/validation

The additive ./planning-handoff subpath owns the existing strict V1 metadata-only reviewed planning packet, task ledger and receipt validation. Connect remains the only apply authority. Existing Builder schemas and validators forward to this canonical protocol without wire or validation changes.

The companion ./planning-handoff-types, ./planning-handoff-schemas and ./planning-handoff-validation subpaths expose the same canonical declarations, schemas and validators. This is an additive packaging correction; wire versions and Connect authority are unchanged. The existing ./planning-handoff browser condition is retained and emitted as a selective browser bundle with Zod external. Other public roots keep their existing runtime conditions. Checked-in export maps are frozen during prebuild so canonical builds do not rewrite source manifests.

The additive ./delivery-chain and ./delivery-primitives leaves own the existing metadata-only delivery chain artifacts and shared delivery reference/risk schemas. Product intent, Builder plans, Connect decisions, infrastructure work orders, deployment receipts, runtime evidence and outcome observations retain their exact wire versions and canonical digests. Every chain artifact keeps effectAuthority: 'none'; recorded risk and evidence grant no execution authority. Historical ContractSpec delivery imports forward to the same definitions.

The existing root owns the complete provider-neutral LSSM OS configuration declaration family and LSSM_OS_SCOPE_ORDER. Compatibility workspace-config imports forward the same tuple and types. Explicit workspace-config leaves own the pure configuration schemas, constraints, policy/provider merge helpers and secret-reference validation. Clock-defaulted inheritance resolution belongs to @lssm-tech/lib.contracts-runtime-core/workspace-config/lssm-os-inheritance; validation and waiver behavior are preserved.

Control-plane skill contracts

The control-plane/skills/types and validator leaves own the existing signed skill manifest data and deterministic validation. Concrete SchemaModel constructors, signing and verification belong to lssm-os-runtime; importing these contracts grants no installation authority. Legacy contracts-spec exports preserve identity.

Delivery policy contracts

The delivery/authority, delivery/project-profile, delivery/autonomy-context and delivery/scoped-autonomy entries own tenant ownership bindings, project placement profiles and bounded autonomy policy contracts. They share the existing delivery primitives and deterministic serialization. Historical ContractSpec delivery imports forward to these exact definitions.

resolveDeliveryAutonomyV2 computes a restrictive policy explanation from supplied policies and an explicit clock; its result always has authorizesExecution: false. It neither authenticates context nor grants authority. Hosts still obtain current Connect authorization and runtime qualification before effects. Schema versions, digest construction, revocation, expiry, scope and cost checks are unchanged.

Pure control-plane/approval-kernel, connect-materialization and repository-authority-bootstrap leaves preserve the original authority metadata models, literal versions and immutable reference shapes. They perform no signing, provisioning or reviewer enrollment. Existing facade imports remain aliases.

Canonical shared person, project, resource and team slug-edge declarations are available from the explicit shared-entities leaves; historical imports preserve identical definitions.

The delivery leaves own CI budget contracts and manual author attestation declarations; these exports preserve existing authority requirements and do not execute delivery actions.

Configuration reference fixture

The existing LSSM OS configuration reference fixture is owned by the isolated workspace-config/lssm-os-config.fixture subpath. Its contracts-spec compatibility leaf retains the same fixture object and original configuration type.