@vev-software/atlas-contracts 0.1.4 → 0.1.6

package/README.md

@@ -23,6 +23,12 @@ import type { LandscapeDocument, Asset } from "@vev-software/atlas-contracts";
 
 Ships type declarations (`dist/index.d.ts`) and ESM; no runtime dependencies.
 
+Digest v1 remains unchanged. `LandscapeDigestV2` adds required per-digest refs,
+optional layer and default-off closed relations. After validating raw JSON against
+`schemas/v2/landscape-digest.schema.json`, call `validateLandscapeDigestV2` for
+cross-item rules. Scope never authorizes sharing; `integrates` requires separate
+stage 2 consent. Both schema versions and their relative dependencies are shipped.
+
 ## Versioning
 
 [SemVer](https://semver.org), derived from the git tag (`vX.Y.Z`) at release. Pre-1.0, the v1

package/dist/index.d.ts

@@ -5,7 +5,7 @@
  */
 /** The atlas-contracts schema major version. */
 export declare const CONTRACT_VERSION: "1";
-export type AssetKind = "system" | "application" | "server" | "infrastructure" | "data-area" | "dataset" | "column";
+export type AssetKind = "system" | "application" | "server" | "infrastructure" | "data-area" | "dataset" | "column" | "integration" | "business-process";
 export type Lifecycle = "draft" | "active" | "retired";
 export type RelationshipType = "runs-on" | "hosts" | "connects-to" | "depends-on" | "part-of" | "joins-on";
 /** A manual, lightweight classification: a key with an optional value. */
@@ -350,3 +350,157 @@ export interface AtlasBundle {
     restore?: RestoreHints | null;
     excluded?: ExcludedCategory[];
 }
+/** Digest classification of an item. Deliberately narrower than `AssetKind`. */
+export type DigestKind = "system" | "application" | "platform" | "vendor";
+/**
+ * The intended change for an item, taken from the Target Architecture contract's change intents
+ * and extended with `replace` for digest purposes.
+ */
+export type PlannedChange = "add" | "change" | "replace" | "retire";
+/**
+ * Which asset kinds and tags were included in a digest. Both arrays are required and may be
+ * empty: an empty `kinds` means no kinds were included, and an empty `tags` means no tag filter
+ * was applied (tag matching is OR within the list, AND with the kind filter).
+ */
+export interface LandscapeDigestScope {
+    kinds: DigestKind[];
+    tags: Tag[];
+}
+/**
+ * One minimized landscape item. Carries only the fields a consented consumer needs; everything
+ * else is forbidden by the schema.
+ */
+export interface LandscapeDigestItem {
+    kind: DigestKind;
+    name: string;
+    lifecycle: Lifecycle;
+    vendor?: string | null;
+    plannedChange?: PlannedChange | null;
+    /** A count only — never the identities of the integrated parties. */
+    integrationCount?: number | null;
+}
+/**
+ * A minimized, versioned summary of an Atlas landscape for consented consumers. `sequence` is
+ * monotonic per `sourceInstanceId` (first is 1, strictly higher after, gaps allowed); consumers
+ * reject a sequence at or below the last accepted for the same source (replay protection).
+ */
+export interface LandscapeDigest {
+    contractVersion: typeof CONTRACT_VERSION;
+    digestId: string;
+    generatedAt: string;
+    sourceInstanceId: string;
+    sequence: number;
+    scope: LandscapeDigestScope;
+    items: LandscapeDigestItem[];
+}
+export declare const LANDSCAPE_DIGEST_V2_VERSION: "2";
+export type DigestLayer = "business" | "application" | "data" | "infrastructure";
+/** integrates is contract-only stage 2, requiring separate explicit consent. */
+export type DigestRelationKind = "runsOn" | "suppliedBy" | "integrates";
+/** Signed inclusion scope; omitted relations means false. Never authorization. */
+export interface LandscapeDigestScopeV2 extends LandscapeDigestScope {
+    relations?: boolean;
+}
+export interface LandscapeDigestItemV2 extends Omit<LandscapeDigestItem, "plannedChange" | "integrationCount"> {
+    /** Required, opaque, 1–64 characters; minted per digest, never a stable asset id. */
+    ref: string;
+    layer?: DigestLayer;
+    plannedChange?: PlannedChange;
+    integrationCount?: number;
+}
+/** Closed edge shape: JSON Schema rejects every additional property. */
+export interface LandscapeDigestRelation {
+    from: string;
+    to: string;
+    kind: DigestRelationKind;
+}
+export interface LandscapeDigestV2 extends Omit<LandscapeDigest, "contractVersion" | "scope" | "items"> {
+    contractVersion: typeof LANDSCAPE_DIGEST_V2_VERSION;
+    scope: LandscapeDigestScopeV2;
+    items: LandscapeDigestItemV2[];
+    /** Omit entirely unless scope.relations is true, including when empty. */
+    relations?: LandscapeDigestRelation[];
+}
+/** Run after JSON Schema validation. Does not grant sharing or consumption permission. */
+export declare function validateLandscapeDigestV2(digest: LandscapeDigestV2): string[];
+export type TargetScopeKind = "estate" | "domain" | "capability-area";
+export type TargetVersionStatus = "draft" | "proposed" | "approved" | "active" | "superseded" | "rejected" | "archived";
+export type ChangeIntent = "add" | "change" | "retire";
+/** What part of the estate a Target Architecture governs. */
+export interface TargetScope {
+    kind: TargetScopeKind;
+    ref?: string | null;
+    name?: string | null;
+}
+/** One asset-level intended change in a target version or gap. */
+export interface TargetAssetMember {
+    intent: ChangeIntent;
+    assetRef?: string | null;
+    asset?: Asset | null;
+    rationale?: string | null;
+}
+/** One relationship-level intended change in a target version or gap. */
+export interface TargetRelationshipMember {
+    intent: ChangeIntent;
+    relationshipRef?: string | null;
+    relationship?: Relationship | null;
+    rationale?: string | null;
+}
+/** One ordered To-Be version (Plateau analogue) in a Target Architecture. */
+export interface TargetVersion {
+    id: string;
+    name: string;
+    sequence: number;
+    status: TargetVersionStatus;
+    rationale?: string | null;
+    intendedHorizon?: string | null;
+    effectiveDate?: string | null;
+    assetChanges?: TargetAssetMember[];
+    relationshipChanges?: TargetRelationshipMember[];
+}
+/** One optional intermediate gap slice inside a transition. */
+export interface TargetGap {
+    id: string;
+    name: string;
+    description?: string | null;
+    assetChanges?: TargetAssetMember[];
+    relationshipChanges?: TargetRelationshipMember[];
+}
+/** One deliverable within a transition work package. */
+export interface Deliverable {
+    id: string;
+    name: string;
+    description?: string | null;
+}
+/** A transition work package grouping one or more deliverables. */
+export interface WorkPackage {
+    id: string;
+    name: string;
+    description?: string | null;
+    deliverables?: Deliverable[];
+}
+/** Optional intermediate transition architecture between two target versions. */
+export interface TargetTransition {
+    id: string;
+    name: string;
+    fromVersionId: string;
+    toVersionId: string;
+    description?: string | null;
+    gaps?: TargetGap[];
+    workPackages?: WorkPackage[];
+}
+/**
+ * A versioned, landscape-level To-Be target: the named target, its ordered versions, the status
+ * vocabulary and optional transition/gap shapes.
+ */
+export interface TargetArchitectureDocument {
+    contractVersion: typeof CONTRACT_VERSION;
+    kind: "target-architecture";
+    id: string;
+    name: string;
+    description?: string | null;
+    scope: TargetScope;
+    generator?: Generator | null;
+    versions: TargetVersion[];
+    transitions?: TargetTransition[];
+}

package/dist/index.js

@@ -5,3 +5,46 @@
  */
 /** The atlas-contracts schema major version. */
 export const CONTRACT_VERSION = "1";
+// --- Landscape share digest v2 (v1 remains unchanged) ---
+export const LANDSCAPE_DIGEST_V2_VERSION = "2";
+/** Run after JSON Schema validation. Does not grant sharing or consumption permission. */
+export function validateLandscapeDigestV2(digest) {
+    const errors = [];
+    const items = new Map();
+    for (const item of digest.items) {
+        if (items.has(item.ref))
+            errors.push("duplicate-ref");
+        items.set(item.ref, item);
+        if (!digest.scope.kinds.includes(item.kind))
+            errors.push("item-outside-scope");
+    }
+    if (digest.relations === undefined)
+        return errors;
+    if (digest.scope.relations !== true)
+        errors.push("relations-not-enabled");
+    if (digest.relations.length > 20000)
+        errors.push("too-many-relations");
+    const edges = new Set();
+    const isSystem = (kind) => kind === "system" || kind === "application";
+    for (const edge of digest.relations) {
+        if (edge.from === edge.to)
+            errors.push("self-edge");
+        const endpoints = edge.kind === "integrates" ? [edge.from, edge.to].sort() : [edge.from, edge.to];
+        const key = JSON.stringify([edge.kind, ...endpoints]);
+        if (edges.has(key))
+            errors.push("duplicate-edge");
+        edges.add(key);
+        const source = items.get(edge.from);
+        const target = items.get(edge.to);
+        if (!source || !target) {
+            errors.push("dangling-ref");
+            continue;
+        }
+        const valid = edge.kind === "runsOn" ? isSystem(source.kind) && target.kind === "platform"
+            : edge.kind === "suppliedBy" ? source.kind !== "vendor" && target.kind === "vendor"
+                : edge.kind === "integrates" && isSystem(source.kind) && isSystem(target.kind);
+        if (!valid)
+            errors.push("invalid-relation-endpoints");
+    }
+    return errors;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vev-software/atlas-contracts",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Public, versioned data model and interop contracts for VEV Atlas — the catalogue asset model plus manual relationships, tags and the landscape import/export document.",
   "license": "Apache-2.0",
   "type": "module",
@@ -16,6 +16,7 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
+    "test": "npm run build && tsc --ignoreConfig --noEmit --strict --target ES2022 --module nodenext test/landscape-digest-v2.types.ts && node --test test/*.test.mjs",
     "prepack": "node scripts/prepack.mjs"
   },
   "devDependencies": {

package/schemas/v1/common.schema.json

@@ -7,7 +7,7 @@
     "AssetKind": {
       "type": "string",
       "description": "The kind of asset held in the catalogue. The data-layer kinds (data-area, dataset, column) model the data architecture beneath a system, down to the column. The AI kinds (ai-service, ai-model) catalogue AI platforms and models as first-class assets.",
-      "enum": ["system", "application", "server", "infrastructure", "data-area", "dataset", "column", "ai-service", "ai-model"]
+      "enum": ["system", "application", "server", "infrastructure", "data-area", "dataset", "column", "ai-service", "ai-model", "integration", "business-process"]
     },
     "Lifecycle": {
       "type": "string",
@@ -21,6 +21,49 @@
       "maxLength": 128,
       "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$"
     },
+    "RelationshipId": {
+      "type": "string",
+      "description": "Stable identifier for a relationship. Never reused or re-meaning'd once published.",
+      "minLength": 1,
+      "maxLength": 128,
+      "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$"
+    },
+    "TargetScopeKind": {
+      "type": "string",
+      "description": "The landscape scope a Target Architecture governs.",
+      "enum": ["estate", "domain", "capability-area"]
+    },
+    "TargetVersionStatus": {
+      "type": "string",
+      "description": "Lifecycle status of a TargetVersion. A TargetArchitecture must carry exactly one active version.",
+      "enum": ["draft", "proposed", "approved", "active", "superseded", "rejected", "archived"]
+    },
+    "ChangeIntent": {
+      "type": "string",
+      "description": "How a target member changes the live estate.",
+      "enum": ["add", "change", "retire"]
+    },
+    "TargetScope": {
+      "type": "object",
+      "description": "What part of the estate a Target Architecture governs: the whole estate, one domain, or one capability area.",
+      "additionalProperties": false,
+      "required": ["kind"],
+      "properties": {
+        "kind": { "$ref": "#/$defs/TargetScopeKind" },
+        "ref": {
+          "type": ["string", "null"],
+          "description": "Optional opaque identifier of the scoped thing when the target does not cover the whole estate.",
+          "minLength": 1,
+          "maxLength": 128
+        },
+        "name": {
+          "type": ["string", "null"],
+          "description": "Optional human-readable scope name.",
+          "minLength": 1,
+          "maxLength": 256
+        }
+      }
+    },
     "Tag": {
       "type": "object",
       "description": "Manual, lightweight classification. A key with an optional value.",

package/schemas/v1/landscape-digest.schema.json

@@ -0,0 +1,105 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.vev.software/atlas/v1/landscape-digest.schema.json",
+  "title": "Atlas landscape share digest (v1)",
+  "description": "A minimized, versioned summary of an Atlas landscape for consented consumers. Push-only sharing surface: Atlas produces the digest and delivers it as a file or over an outbound HTTPS call; a consumer never pulls from the customer's network. Minimization is enforced by the schema (additionalProperties: false): no hostnames, IP addresses, server or discovery details, descriptions, attachments, people, column-level data or credentials. The digest is a summary for sharing — not the customer-owned portability export (landscape.schema.json) and not an import document. See docs/landscape-digest.md.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["contractVersion", "digestId", "generatedAt", "sourceInstanceId", "sequence", "scope", "items"],
+  "properties": {
+    "contractVersion": {
+      "type": "string",
+      "description": "The atlas-contracts schema major version this digest conforms to.",
+      "const": "1"
+    },
+    "digestId": {
+      "type": "string",
+      "description": "Stable identifier for this digest. Opaque to consumers; unique per produced digest (a UUIDv7 is recommended).",
+      "minLength": 1,
+      "maxLength": 128,
+      "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$"
+    },
+    "generatedAt": {
+      "type": "string",
+      "description": "When the digest was produced (RFC 3339).",
+      "format": "date-time"
+    },
+    "sourceInstanceId": {
+      "type": "string",
+      "description": "Opaque identifier of the producing Atlas instance. Consumers use it to scope sequence/replay state; it carries no tenant or customer semantics. A source that resets its sequence must mint a new sourceInstanceId.",
+      "minLength": 1,
+      "maxLength": 128
+    },
+    "sequence": {
+      "type": "integer",
+      "description": "Monotonic per sourceInstanceId: the first digest is sequence 1, each later digest is strictly higher (gaps allowed). Consumers must reject a sequence at or below the last one accepted for the same source (replay protection).",
+      "minimum": 1
+    },
+    "scope": {
+      "$ref": "#/$defs/DigestScope"
+    },
+    "items": {
+      "type": "array",
+      "description": "The minimized landscape items. Every item's kind must be a member of scope.kinds (checked by the conformance kit; JSON Schema cannot express it).",
+      "items": { "$ref": "#/$defs/DigestItem" }
+    }
+  },
+  "$defs": {
+    "DigestKind": {
+      "type": "string",
+      "description": "Digest classification of an item. Deliberately narrower than the catalogue AssetKind: platform folds in server/infrastructure/AI substrate, vendor is a producer-derived summary entry, and data-layer kinds (data-area, dataset, column) are excluded from digests.",
+      "enum": ["system", "application", "platform", "vendor"]
+    },
+    "PlannedChange": {
+      "type": "string",
+      "description": "The intended change for an item, taken from the Target Architecture contract's change intents (add/change/retire) and extended with replace for digest purposes. The shared ChangeIntent vocabulary is not modified.",
+      "enum": ["add", "change", "replace", "retire"]
+    },
+    "DigestScope": {
+      "type": "object",
+      "description": "Which asset kinds and tags were included in this digest. Both arrays are required and may be empty: an empty kinds array means no kinds were included, and an empty tags array means no tag filter was applied (tag matching is OR within the list, AND with the kind filter).",
+      "additionalProperties": false,
+      "required": ["kinds", "tags"],
+      "properties": {
+        "kinds": {
+          "type": "array",
+          "description": "The digest item kinds included.",
+          "items": { "$ref": "#/$defs/DigestKind" },
+          "uniqueItems": true
+        },
+        "tags": {
+          "type": "array",
+          "description": "The tag filters that qualified inclusion (key, and value when present).",
+          "items": { "$ref": "common.schema.json#/$defs/Tag" }
+        }
+      }
+    },
+    "DigestItem": {
+      "type": "object",
+      "description": "One minimized landscape item. Carries only the fields a consented consumer needs: classification, name, lifecycle, and optional vendor / planned change / integration count. Everything else (hostnames, IPs, server and discovery details, descriptions, attachments, people, column-level data, credentials) is forbidden by additionalProperties: false.",
+      "additionalProperties": false,
+      "required": ["kind", "name", "lifecycle"],
+      "properties": {
+        "kind": { "$ref": "#/$defs/DigestKind" },
+        "name": {
+          "type": "string",
+          "description": "The item's catalogue name.",
+          "minLength": 1,
+          "maxLength": 256
+        },
+        "lifecycle": { "$ref": "common.schema.json#/$defs/Lifecycle" },
+        "vendor": {
+          "type": ["string", "null"],
+          "description": "Optional vendor of the item, when known.",
+          "maxLength": 128
+        },
+        "plannedChange": { "$ref": "#/$defs/PlannedChange" },
+        "integrationCount": {
+          "type": "integer",
+          "description": "Optional count of integrations the item participates in. A count only — never the identities of the integrated parties.",
+          "minimum": 0
+        }
+      }
+    }
+  }
+}

package/schemas/v1/target-architecture.schema.json

@@ -0,0 +1,321 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.vev.software/atlas/v1/target-architecture.schema.json",
+  "title": "Atlas Target Architecture document (v1)",
+  "description": "A versioned, landscape-level To-Be target: the named target, its ordered versions, the status vocabulary and optional transition/gap shapes. Product-native truth only: ArchiMate remains a peripheral mapping. See atlas-contracts#35.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["contractVersion", "kind", "id", "name", "scope", "versions"],
+  "properties": {
+    "contractVersion": {
+      "type": "string",
+      "description": "The atlas-contracts schema major version this document conforms to.",
+      "const": "1"
+    },
+    "kind": {
+      "type": "string",
+      "const": "target-architecture"
+    },
+    "id": {
+      "type": "string",
+      "description": "Stable identifier for the target architecture.",
+      "minLength": 1,
+      "maxLength": 128,
+      "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$"
+    },
+    "name": {
+      "type": "string",
+      "description": "Human-readable name of the target architecture.",
+      "minLength": 1,
+      "maxLength": 256
+    },
+    "description": {
+      "type": ["string", "null"],
+      "maxLength": 4096
+    },
+    "scope": {
+      "$ref": "common.schema.json#/$defs/TargetScope"
+    },
+    "generator": {
+      "description": "Optional provenance: what produced this target document.",
+      "oneOf": [
+        { "type": "null" },
+        { "$ref": "common.schema.json#/$defs/Generator" }
+      ]
+    },
+    "versions": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "#/$defs/TargetVersion" },
+      "contains": {
+        "type": "object",
+        "required": ["status"],
+        "properties": {
+          "status": { "const": "active" }
+        }
+      },
+      "minContains": 1,
+      "maxContains": 1
+    },
+    "transitions": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/TargetTransition" },
+      "default": []
+    }
+  },
+  "$defs": {
+    "TargetAssetMember": {
+      "type": "object",
+      "description": "One asset-level intended change in a TargetVersion or transition/gap step.",
+      "additionalProperties": false,
+      "required": ["intent"],
+      "properties": {
+        "intent": { "$ref": "common.schema.json#/$defs/ChangeIntent" },
+        "assetRef": {
+          "oneOf": [
+            { "type": "null" },
+            { "$ref": "common.schema.json#/$defs/AssetId" }
+          ]
+        },
+        "asset": {
+          "oneOf": [
+            { "type": "null" },
+            { "$ref": "asset.schema.json" }
+          ]
+        },
+        "rationale": {
+          "type": ["string", "null"],
+          "maxLength": 4096
+        }
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "intent": { "const": "add" } }, "required": ["intent"] },
+          "then": { "required": ["asset"] }
+        },
+        {
+          "if": { "properties": { "intent": { "const": "change" } }, "required": ["intent"] },
+          "then": { "required": ["assetRef", "asset"] }
+        },
+        {
+          "if": { "properties": { "intent": { "const": "retire" } }, "required": ["intent"] },
+          "then": { "required": ["assetRef"] }
+        }
+      ]
+    },
+    "TargetRelationshipMember": {
+      "type": "object",
+      "description": "One relationship-level intended change in a TargetVersion or transition/gap step.",
+      "additionalProperties": false,
+      "required": ["intent"],
+      "properties": {
+        "intent": { "$ref": "common.schema.json#/$defs/ChangeIntent" },
+        "relationshipRef": {
+          "oneOf": [
+            { "type": "null" },
+            { "$ref": "common.schema.json#/$defs/RelationshipId" }
+          ]
+        },
+        "relationship": {
+          "oneOf": [
+            { "type": "null" },
+            { "$ref": "relationship.schema.json" }
+          ]
+        },
+        "rationale": {
+          "type": ["string", "null"],
+          "maxLength": 4096
+        }
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "intent": { "const": "add" } }, "required": ["intent"] },
+          "then": { "required": ["relationship"] }
+        },
+        {
+          "if": { "properties": { "intent": { "const": "change" } }, "required": ["intent"] },
+          "then": { "required": ["relationshipRef", "relationship"] }
+        },
+        {
+          "if": { "properties": { "intent": { "const": "retire" } }, "required": ["intent"] },
+          "then": { "required": ["relationshipRef"] }
+        }
+      ]
+    },
+    "TargetVersion": {
+      "type": "object",
+      "description": "One ordered To-Be version (ArchiMate Plateau analogue) within a Target Architecture.",
+      "additionalProperties": false,
+      "required": ["id", "name", "sequence", "status"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128,
+          "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$"
+        },
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 256
+        },
+        "sequence": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "status": { "$ref": "common.schema.json#/$defs/TargetVersionStatus" },
+        "rationale": {
+          "type": ["string", "null"],
+          "maxLength": 4096
+        },
+        "intendedHorizon": {
+          "type": ["string", "null"],
+          "maxLength": 128
+        },
+        "effectiveDate": {
+          "type": ["string", "null"],
+          "format": "date"
+        },
+        "assetChanges": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/TargetAssetMember" },
+          "default": []
+        },
+        "relationshipChanges": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/TargetRelationshipMember" },
+          "default": []
+        }
+      }
+    },
+    "TargetGap": {
+      "type": "object",
+      "description": "An optional intermediate gap slice between two target versions.",
+      "additionalProperties": false,
+      "required": ["id", "name"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128,
+          "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$"
+        },
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 256
+        },
+        "description": {
+          "type": ["string", "null"],
+          "maxLength": 4096
+        },
+        "assetChanges": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/TargetAssetMember" },
+          "default": []
+        },
+        "relationshipChanges": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/TargetRelationshipMember" },
+          "default": []
+        }
+      }
+    },
+    "Deliverable": {
+      "type": "object",
+      "description": "One deliverable within a transition work package.",
+      "additionalProperties": false,
+      "required": ["id", "name"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128,
+          "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$"
+        },
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 256
+        },
+        "description": {
+          "type": ["string", "null"],
+          "maxLength": 4096
+        }
+      }
+    },
+    "WorkPackage": {
+      "type": "object",
+      "description": "A transition work package grouping one or more deliverables.",
+      "additionalProperties": false,
+      "required": ["id", "name"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128,
+          "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$"
+        },
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 256
+        },
+        "description": {
+          "type": ["string", "null"],
+          "maxLength": 4096
+        },
+        "deliverables": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/Deliverable" },
+          "default": []
+        }
+      }
+    },
+    "TargetTransition": {
+      "type": "object",
+      "description": "Optional intermediate transition architecture between two versions.",
+      "additionalProperties": false,
+      "required": ["id", "name", "fromVersionId", "toVersionId"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128,
+          "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$"
+        },
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 256
+        },
+        "description": {
+          "type": ["string", "null"],
+          "maxLength": 4096
+        },
+        "fromVersionId": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128,
+          "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$"
+        },
+        "toVersionId": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128,
+          "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$"
+        },
+        "gaps": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/TargetGap" },
+          "default": []
+        },
+        "workPackages": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/WorkPackage" },
+          "default": []
+        }
+      }
+    }
+  }
+}

package/schemas/v2/landscape-digest.schema.json

@@ -0,0 +1,73 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.vev.software/atlas/v2/landscape-digest.schema.json",
+  "title": "Atlas landscape share digest (v2)",
+  "description": "Minimized push-only digest with per-digest refs, optional layer and opt-in relations. Payload scope records sender intent, never authorization. Cross-item invariants require semantic validation; see docs/landscape-digest.md.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["contractVersion", "digestId", "generatedAt", "sourceInstanceId", "sequence", "scope", "items"],
+  "properties": {
+    "contractVersion": { "const": "2" },
+    "digestId": { "$ref": "../v1/landscape-digest.schema.json#/properties/digestId" },
+    "generatedAt": { "$ref": "../v1/landscape-digest.schema.json#/properties/generatedAt" },
+    "sourceInstanceId": { "$ref": "../v1/landscape-digest.schema.json#/properties/sourceInstanceId" },
+    "sequence": { "$ref": "../v1/landscape-digest.schema.json#/properties/sequence" },
+    "scope": { "$ref": "#/$defs/Scope" },
+    "items": { "type": "array", "items": { "$ref": "#/$defs/Item" } },
+    "relations": {
+      "type": "array",
+      "maxItems": 20000,
+      "uniqueItems": true,
+      "items": { "$ref": "#/$defs/Relation" }
+    }
+  },
+  "if": { "required": ["relations"] },
+  "then": {
+    "properties": {
+      "scope": { "required": ["relations"], "properties": { "relations": { "const": true } } }
+    }
+  },
+  "$defs": {
+    "Ref": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 64,
+      "description": "Opaque, unique within this digest and meaningless outside it. Mint anew per digest; never an asset id or stable identifier."
+    },
+    "Scope": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kinds", "tags"],
+      "properties": {
+        "kinds": { "$ref": "../v1/landscape-digest.schema.json#/$defs/DigestScope/properties/kinds" },
+        "tags": { "$ref": "../v1/landscape-digest.schema.json#/$defs/DigestScope/properties/tags" },
+        "relations": { "type": "boolean", "default": false }
+      }
+    },
+    "Item": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["ref", "kind", "name", "lifecycle"],
+      "properties": {
+        "ref": { "$ref": "#/$defs/Ref" },
+        "kind": { "$ref": "../v1/landscape-digest.schema.json#/$defs/DigestKind" },
+        "name": { "$ref": "../v1/landscape-digest.schema.json#/$defs/DigestItem/properties/name" },
+        "lifecycle": { "$ref": "../v1/common.schema.json#/$defs/Lifecycle" },
+        "vendor": { "$ref": "../v1/landscape-digest.schema.json#/$defs/DigestItem/properties/vendor" },
+        "plannedChange": { "$ref": "../v1/landscape-digest.schema.json#/$defs/PlannedChange" },
+        "integrationCount": { "$ref": "../v1/landscape-digest.schema.json#/$defs/DigestItem/properties/integrationCount" },
+        "layer": { "enum": ["business", "application", "data", "infrastructure"] }
+      }
+    },
+    "Relation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["from", "to", "kind"],
+      "properties": {
+        "from": { "$ref": "#/$defs/Ref" },
+        "to": { "$ref": "#/$defs/Ref" },
+        "kind": { "enum": ["runsOn", "suppliedBy", "integrates"] }
+      }
+    }
+  }
+}