ContractSpec docs

OSS-first docs

These docs teach the open system first: contracts, generated surfaces, runtimes, governance, and incremental adoption. Studio shows up as the operating layer on top, not as the source of truth.

AI index

ContractEntitySpec — Declarative Entity Contract (Layer 1 + 2)

ContractEntitySpec is the entity contract supporting two adoption layers: Layer 1 (slug + edges only) and Layer 2 (full EntitySpec<TFields> + edges). Schema layer's defineEntity is untouched per A4.

field.key.label
ContractEntitySpec — Declarative Entity Contract (Layer 1 + 2)
field.version.label
field.type.label
field.title.label
ContractEntitySpec — Declarative Entity Contract (Layer 1 + 2)
field.description.label

ContractEntitySpec is the entity contract supporting two adoption layers: Layer 1 (slug + edges only) and Layer 2 (full EntitySpec<TFields> + edges). Schema layer's defineEntity is untouched per A4.

field.tags.label
tech,contracts,entities,graph
field.owners.label
field.stability.label
public

Purpose

`ContractEntitySpec` is the entity contract. It provides:

1.

A canonical **entity slug** via `meta.key`.

2.

Optional **inline edges** (`edges?: EdgeSpec[]`).

3.

Standard **ownership metadata** (version, stability, owners, tags).

4.

**Layer 2**: optional `entity?: EntitySpec<TFields>` for DB-modeling semantics

delegated to `@lssm-tech/lib.schema`'s `EntitySpec`.

Layer Summary

| Layer | What ships | `entity` field | |-------|------------|-----------------| | **Layer 1** | slug + edges | omitted | | **Layer 2** | slug + full `EntitySpec<TFields>` + edges | required |

Layer 1 Usage (slug + edges)

import { defineContractEntity } from '@lssm-tech/lib.contracts-spec';

export const UserEntity = defineContractEntity({
  meta: {
    key: 'user',
    version: '1.0.0',
    description: 'Platform user entity.',
    stability: 'stable',
    owners: ['platform.core'],
    tags: ['user', 'auth'],
  },
  edges: [
    { id: 'user-to-project', from: 'user', to: 'project', relation: 'has-many', cardinality: 'one-to-many', directed: true },
  ],
});

Layer 2 Usage (full EntitySpec + edges)

import { defineContractEntity } from '@lssm-tech/lib.contracts-spec';
import { defineEntity, field } from '@lssm-tech/lib.schema';

export const UserEntity = defineContractEntity({
  meta: {
    key: 'user',
    version: '1.0.0',
    description: 'Platform user with auth + profile.',
    stability: 'stable',
    owners: ['platform.core'],
    tags: ['user', 'auth'],
  },
  entity: defineEntity({
    name: 'User',
    description: 'Platform user with auth + profile.',
    fields: {
      id: field.id(),
      email: field.email(),
      createdAt: field.createdAt(),
    },
  }),
  edges: [
    { id: 'user-to-project', from: 'user', to: 'project', relation: 'has-many', cardinality: 'one-to-many', directed: true },
  ],
});

A4 Constraint

The schema layer's `defineEntity` (`@lssm-tech/lib.schema`) remains untouched. `defineContractEntity` accepts its output via **structural typing** — no wrapping, no re-implementation, no modification to the schema package.

Registry Precondition (C12)

The `EntityRegistry` holding this spec **must** be initialized before graph `DataViewRenderer` accesses entity slugs or edge relationships.