@mdbase-dev/connect-protocol 0.1.0-beta.124 → 0.1.0-beta.125

package/dist/manifest.d.ts

@@ -60,3 +60,10 @@ export declare function parseAppManifest(value: unknown, options?: ManifestValid
 /** Validate and clone without changing capability IDs, file aliases, or version. */
 export declare function parseVersionedAppManifest(value: unknown, options?: ManifestValidationOptions): VersionedAppManifest;
 export declare function formatManifestValidationIssues(issues: readonly ManifestValidationIssue[]): string;
+/**
+ * Validate one schema-valid type-pack provision beyond its JSON Schema: the
+ * embedded resources are exactly the manifest's, each digest pins its bytes,
+ * and every seed `upgrade_from` baseline satisfies mdbase 05A. Issue paths are
+ * prefixed with `path`, the provision's location in its enclosing document.
+ */
+export declare function validateTypePackProvision(value: unknown, path?: string): ManifestValidationIssue[];

package/dist/manifest.js

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import { Ajv2020 } from "ajv/dist/2020.js";
 import addFormatsModule from "ajv-formats";
+import { isMap, parseDocument } from "yaml";
 import appManifestSchema from "../schemas/mdbase-app.schema.json" with { type: "json" };
 import legacyAppManifestSchema from "../schemas/mdbase-app.legacy-v1.schema.json" with { type: "json" };
 import { RECORD_EXTENSIONS_CONFIGURATION_PATH } from "./collection-setup.js";
@@ -266,47 +267,99 @@ function validateProvisionRequirements(value) {
                 issues.push(issue(`/provisions/type_packs/${packIndex}/provides`, "contractRequirement", "may only contain contracts required by the application"));
             }
         }
-        const packManifest = asObject(provision.manifest);
-        const declaredResources = Array.isArray(packManifest.resources)
-            ? packManifest.resources.map(asObject)
-            : [];
-        const embeddedResources = Array.isArray(provision.resources)
-            ? provision.resources.map(asObject)
-            : [];
-        const embedded = new Map(embeddedResources.map((resource) => [String(resource.source), resource.document]));
-        if (embedded.size !== embeddedResources.length
-            || new Set(declaredResources.map((resource) => String(resource.source))).size
-                !== declaredResources.length
-            || declaredResources.length !== embeddedResources.length) {
-            issues.push(issue(`/provisions/type_packs/${packIndex}/resources`, "resourceSet", "must match manifest source paths exactly"));
+        issues.push(...validateTypePackProvision(provision, `/provisions/type_packs/${packIndex}`));
+    }
+    return issues;
+}
+/**
+ * Validate one schema-valid type-pack provision beyond its JSON Schema: the
+ * embedded resources are exactly the manifest's, each digest pins its bytes,
+ * and every seed `upgrade_from` baseline satisfies mdbase 05A. Issue paths are
+ * prefixed with `path`, the provision's location in its enclosing document.
+ */
+export function validateTypePackProvision(value, path = "") {
+    const provision = asObject(value);
+    const manifest = asObject(provision.manifest);
+    const declaredResources = Array.isArray(manifest.resources)
+        ? manifest.resources.map(asObject)
+        : [];
+    const embeddedResources = Array.isArray(provision.resources)
+        ? provision.resources.map(asObject)
+        : [];
+    const embedded = new Map(embeddedResources.map((resource) => [String(resource.source), resource.document]));
+    if (embedded.size !== embeddedResources.length
+        || new Set(declaredResources.map((resource) => String(resource.source))).size
+            !== declaredResources.length
+        || declaredResources.length !== embeddedResources.length) {
+        return [issue(`${path}/resources`, "resourceSet", "must match manifest source paths exactly")];
+    }
+    const issues = [];
+    for (const [resourceIndex, resource] of declaredResources.entries()) {
+        const resourcePath = `${path}/manifest/resources/${resourceIndex}`;
+        const source = String(resource.source);
+        const document = embedded.get(source);
+        if (typeof document !== "string") {
+            issues.push(issue(`${path}/resources`, "resourceSet", `is missing manifest source ${source}`));
             continue;
         }
-        for (const [resourceIndex, resource] of declaredResources.entries()) {
-            const source = String(resource.source);
-            if (resource.upgrade_from !== undefined) {
-                const baseline = asObject(resource.upgrade_from);
-                const path = `/provisions/type_packs/${packIndex}/manifest/resources/${resourceIndex}/upgrade_from`;
-                if (resource.kind !== "type" || resource.mode !== "seed") {
-                    issues.push(issue(path, "seedUpgrade", "is only allowed for seed types"));
-                }
-                if (typeof baseline.document === "string"
-                    && baseline.digest !== `sha256:${createHash("sha256").update(baseline.document).digest("hex")}`) {
-                    issues.push(issue(`${path}/digest`, "digest", "does not match the baseline document"));
-                }
-            }
-            const document = embedded.get(source);
-            if (typeof document !== "string") {
-                issues.push(issue(`/provisions/type_packs/${packIndex}/resources`, "resourceSet", `is missing manifest source ${source}`));
-                continue;
-            }
-            const digest = `sha256:${createHash("sha256").update(document).digest("hex")}`;
-            if (digest !== resource.digest) {
-                issues.push(issue(`/provisions/type_packs/${packIndex}/manifest/resources/${resourceIndex}/digest`, "digest", "does not match the embedded document"));
-            }
+        if (sha256(document) !== resource.digest) {
+            issues.push(issue(`${resourcePath}/digest`, "digest", "does not match the embedded document"));
+        }
+        if (resource.upgrade_from !== undefined) {
+            issues.push(...validateSeedUpgrade(resource, document, `${resourcePath}/upgrade_from`));
+        }
+    }
+    return issues;
+}
+/** 05A seed-upgrade baselines: exact, distinct, earlier starters of the same type. */
+function validateSeedUpgrade(resource, document, path) {
+    if (resource.kind !== "type" || resource.mode !== "seed") {
+        return [issue(path, "seedUpgrade", "is only allowed for seed types")];
+    }
+    const desired = typeFrontmatter(document);
+    const listed = Array.isArray(resource.upgrade_from);
+    const baselines = (listed ? resource.upgrade_from : [resource.upgrade_from]).map(asObject);
+    const seen = new Set();
+    const issues = [];
+    for (const [index, baseline] of baselines.entries()) {
+        const baselinePath = listed ? `${path}/${index}` : path;
+        const baselineDocument = String(baseline.document);
+        if (baseline.digest !== sha256(baselineDocument)) {
+            issues.push(issue(`${baselinePath}/digest`, "digest", "does not match the baseline document"));
+        }
+        else if (seen.has(baseline.digest)) {
+            issues.push(issue(`${baselinePath}/digest`, "uniqueBaseline", "duplicates another upgrade baseline"));
+        }
+        else if (baseline.digest === resource.digest) {
+            issues.push(issue(`${baselinePath}/digest`, "seedUpgrade", "must not be the resource's own document"));
+        }
+        seen.add(baseline.digest);
+        const previous = typeFrontmatter(baselineDocument);
+        if (!desired || !previous || previous.kind !== desired.kind || previous.name !== desired.name) {
+            issues.push(issue(`${baselinePath}/document`, "seedUpgrade", "must be a type document with the same kind and name as the resource"));
+        }
+        else if (baseline.version !== undefined && previous.version !== baseline.version) {
+            issues.push(issue(`${baselinePath}/version`, "seedUpgrade", "must equal the version the baseline document declares"));
         }
     }
     return issues;
 }
+/** Top-level frontmatter of a type document, or undefined when it has none. */
+// The identity a type document declares. Only these top-level keys are read, so
+// anchors and aliases elsewhere in a starter are harmless and alias expansion
+// stays disabled.
+function typeFrontmatter(document) {
+    const source = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/u.exec(document)?.[1];
+    if (source === undefined)
+        return undefined;
+    const parsed = parseDocument(source, { uniqueKeys: true });
+    if (parsed.errors.length > 0 || !isMap(parsed.contents))
+        return undefined;
+    return { kind: parsed.get("kind"), name: parsed.get("name"), version: parsed.get("version") };
+}
+function sha256(document) {
+    return `sha256:${createHash("sha256").update(document).digest("hex")}`;
+}
 function validateConfigurationSetup(value) {
     const manifest = asObject(value);
     const requirements = asObject(manifest.requirements);

package/dist/type-packs.d.ts

@@ -35,12 +35,19 @@ export declare const MDBASE_TIMER_FIRED_CONTRACT: {
     readonly version: "1.0.0";
     readonly digest: "sha256:41105be7a7abf33b31ced47e1e1965242236e40ccaea286b959b0a8c591f5642";
 };
+/** Exact bytes of a starter the publisher previously shipped for a seed type. */
+type TypePackUpgradeBaseline = {
+    digest: string;
+    document: string;
+    /** The `version` the baseline document declares, for presentation only. */
+    version?: number;
+};
 export interface TypePackManifestResource {
-    /** Explicit three-way upgrade; only valid for seed type resources. */
-    upgrade_from?: {
-        digest: string;
-        document: string;
-    };
+    /**
+     * Previously shipped starters this seed type may be upgraded from; only valid
+     * for seed type resources. A single baseline is equivalent to a one-item list.
+     */
+    upgrade_from?: TypePackUpgradeBaseline | TypePackUpgradeBaseline[];
     kind: "contract" | "type" | "schema";
     mode: "managed" | "seed";
     source: string;
@@ -78,6 +85,11 @@ export interface TypePackResourceDiff {
     current_digest?: string;
     installed_digest?: string;
     adopted_from_digest?: string;
+    /** The declared baseline an engine upgraded this seed from (seed `update` only). */
+    upgrade_baseline?: {
+        digest: string;
+        version?: number;
+    };
     reason?: string;
 }
 export interface TypePackReceipt {
@@ -85,7 +97,10 @@ export interface TypePackReceipt {
     version: string;
     digest: string;
     installed_by: string;
-    resources: Omit<TypePackResourceDiff, "action" | "current_digest" | "installed_digest" | "reason">[];
+    resources: Array<Omit<TypePackResourceDiff, "action" | "current_digest" | "installed_digest" | "upgrade_baseline" | "reason"> & {
+        /** Seed only: the publisher document the target descends from, when known. */
+        origin_digest?: string;
+    }>;
 }
 export interface TypePackAssessment {
     status: "current" | "install" | "upgrade" | "downgrade" | "reconfigure" | "conflict";
@@ -136,3 +151,4 @@ export type ContractSetupChoice = {
     fields: Record<string, string>;
     binding?: Record<string, unknown>;
 };
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mdbase-dev/connect-protocol",
-  "version": "0.1.0-beta.124",
+  "version": "0.1.0-beta.125",
   "private": false,
   "type": "module",
   "license": "MIT",
@@ -28,7 +28,8 @@
   ],
   "dependencies": {
     "ajv": "^8.20.0",
-    "ajv-formats": "^3.0.1"
+    "ajv-formats": "^3.0.1",
+    "yaml": "^2.9.1"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",

package/schemas/connect-protocol.v1.schema.json

@@ -410,11 +410,27 @@
       "properties": {
         "kind": { "enum": ["contract", "type", "schema"] },
         "mode": { "enum": ["managed", "seed"] },
+        "upgrade_from": {
+          "oneOf": [
+            { "$ref": "#/$defs/typePackUpgradeBaseline" },
+            { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/typePackUpgradeBaseline" } }
+          ]
+        },
         "source": { "type": "string", "minLength": 1, "maxLength": 500 },
         "target": { "type": "string", "minLength": 1, "maxLength": 500 },
         "digest": { "$ref": "#/$defs/digest" }
       }
     },
+    "typePackUpgradeBaseline": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["digest", "document"],
+      "properties": {
+        "digest": { "$ref": "#/$defs/digest" },
+        "document": { "type": "string", "maxLength": 262144 },
+        "version": { "type": "integer", "minimum": 1 }
+      }
+    },
     "typePackSourceResource": {
       "type": "object",
       "additionalProperties": false,

package/schemas/mdbase-app.schema.json

@@ -319,19 +319,26 @@
         "kind": { "enum": ["contract", "type", "schema"] },
         "mode": { "enum": ["managed", "seed"] },
         "upgrade_from": {
-          "type": "object",
-          "additionalProperties": false,
-          "required": ["digest", "document"],
-          "properties": {
-            "digest": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
-            "document": { "type": "string", "maxLength": 262144 }
-          }
+          "oneOf": [
+            { "$ref": "#/$defs/typePackUpgradeBaseline" },
+            { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/typePackUpgradeBaseline" } }
+          ]
         },
         "source": { "type": "string", "minLength": 1, "maxLength": 240 },
         "target": { "type": "string", "minLength": 1, "maxLength": 240 },
         "digest": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" }
       }
     },
+    "typePackUpgradeBaseline": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["digest", "document"],
+      "properties": {
+        "digest": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
+        "document": { "type": "string", "maxLength": 262144 },
+        "version": { "type": "integer", "minimum": 1 }
+      }
+    },
     "typePackSourceResource": {
       "type": "object",
       "additionalProperties": false,