@vev-software/atlas-contracts 0.1.5 → 0.1.7

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

@@ -393,6 +393,36 @@ export interface LandscapeDigest {
     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";

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.5",
+  "version": "0.1.7",
   "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/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"] }
+      }
+    }
+  }
+}