@esmx/core 3.0.0-rc.116 → 3.0.0-rc.118

package/dist/declaration/semver.mjs

@@ -0,0 +1,229 @@
+const VERSION_RE = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/;
+export function parseSemver(input) {
+  const match = VERSION_RE.exec(input.trim());
+  if (!match) {
+    return null;
+  }
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+    prerelease: match[4] ? match[4].split(".") : []
+  };
+}
+function comparePrerelease(a, b) {
+  if (a.length === 0 && b.length === 0) {
+    return 0;
+  }
+  if (a.length === 0) {
+    return 1;
+  }
+  if (b.length === 0) {
+    return -1;
+  }
+  const length = Math.max(a.length, b.length);
+  for (let i = 0; i < length; i++) {
+    const idA = a[i];
+    const idB = b[i];
+    if (idA === void 0) {
+      return -1;
+    }
+    if (idB === void 0) {
+      return 1;
+    }
+    const numA = /^\d+$/.test(idA) ? Number(idA) : null;
+    const numB = /^\d+$/.test(idB) ? Number(idB) : null;
+    if (numA !== null && numB !== null) {
+      if (numA !== numB) {
+        return numA < numB ? -1 : 1;
+      }
+    } else if (numA !== null) {
+      return -1;
+    } else if (numB !== null) {
+      return 1;
+    } else if (idA !== idB) {
+      return idA < idB ? -1 : 1;
+    }
+  }
+  return 0;
+}
+export function compareSemver(a, b) {
+  if (a.major !== b.major) {
+    return a.major < b.major ? -1 : 1;
+  }
+  if (a.minor !== b.minor) {
+    return a.minor < b.minor ? -1 : 1;
+  }
+  if (a.patch !== b.patch) {
+    return a.patch < b.patch ? -1 : 1;
+  }
+  return comparePrerelease(a.prerelease, b.prerelease);
+}
+function parsePartial(input) {
+  const trimmed = input.trim().replace(/^v/, "");
+  if (trimmed === "" || trimmed === "*" || /^x$/i.test(trimmed)) {
+    return { major: null, minor: null, patch: null, prerelease: [] };
+  }
+  const exact = parseSemver(trimmed);
+  if (exact) {
+    return exact;
+  }
+  const segments = trimmed.split(".");
+  if (segments.length > 3) {
+    return null;
+  }
+  const parsed = [];
+  for (const segment of segments) {
+    if (segment === "*" || /^x$/i.test(segment)) {
+      parsed.push(null);
+    } else if (/^\d+$/.test(segment)) {
+      parsed.push(Number(segment));
+    } else {
+      return null;
+    }
+  }
+  return {
+    major: parsed[0] ?? null,
+    minor: parsed[1] ?? null,
+    patch: parsed[2] ?? null,
+    prerelease: []
+  };
+}
+function lowerBound(partial) {
+  return {
+    major: partial.major ?? 0,
+    minor: partial.minor ?? 0,
+    patch: partial.patch ?? 0,
+    prerelease: partial.prerelease
+  };
+}
+function xRangeUpperBound(partial) {
+  if (partial.major === null) {
+    return null;
+  }
+  if (partial.minor === null) {
+    return { major: partial.major + 1, minor: 0, patch: 0, prerelease: [] };
+  }
+  if (partial.patch === null) {
+    return {
+      major: partial.major,
+      minor: partial.minor + 1,
+      patch: 0,
+      prerelease: []
+    };
+  }
+  return null;
+}
+function caretUpperBound(partial) {
+  if (partial.major === null) {
+    return null;
+  }
+  if (partial.major > 0) {
+    return { major: partial.major + 1, minor: 0, patch: 0, prerelease: [] };
+  }
+  if (partial.minor === null) {
+    return { major: 1, minor: 0, patch: 0, prerelease: [] };
+  }
+  if (partial.minor > 0) {
+    return { major: 0, minor: partial.minor + 1, patch: 0, prerelease: [] };
+  }
+  if (partial.patch === null) {
+    return { major: 0, minor: partial.minor + 1, patch: 0, prerelease: [] };
+  }
+  return { major: 0, minor: 0, patch: partial.patch + 1, prerelease: [] };
+}
+function tildeUpperBound(partial) {
+  if (partial.major === null) {
+    return null;
+  }
+  if (partial.minor === null) {
+    return { major: partial.major + 1, minor: 0, patch: 0, prerelease: [] };
+  }
+  return {
+    major: partial.major,
+    minor: partial.minor + 1,
+    patch: 0,
+    prerelease: []
+  };
+}
+function satisfiesComparator(version, comparator) {
+  const match = /^(\^|~|>=|<=|>|<|=)?\s*(.*)$/.exec(comparator.trim());
+  if (!match) {
+    return null;
+  }
+  const operator = match[1] ?? "";
+  const partial = parsePartial(match[2]);
+  if (!partial) {
+    return null;
+  }
+  const lower = lowerBound(partial);
+  switch (operator) {
+    case ">=":
+      return compareSemver(version, lower) >= 0;
+    case ">":
+      return compareSemver(version, lower) > 0;
+    case "<=":
+      return compareSemver(version, lower) <= 0;
+    case "<":
+      return compareSemver(version, lower) < 0;
+    case "^": {
+      if (compareSemver(version, lower) < 0) {
+        return false;
+      }
+      const upper = caretUpperBound(partial);
+      return upper === null || compareSemver(version, upper) < 0;
+    }
+    case "~": {
+      if (compareSemver(version, lower) < 0) {
+        return false;
+      }
+      const upper = tildeUpperBound(partial);
+      return upper === null || compareSemver(version, upper) < 0;
+    }
+    default: {
+      if (partial.major !== null && partial.minor !== null && partial.patch !== null) {
+        return compareSemver(version, lower) === 0;
+      }
+      if (compareSemver(version, lower) < 0) {
+        return false;
+      }
+      const upper = xRangeUpperBound(partial);
+      return upper === null || compareSemver(version, upper) < 0;
+    }
+  }
+}
+export function satisfiesRange(version, range) {
+  const parsedVersion = parseSemver(version);
+  if (!parsedVersion) {
+    return null;
+  }
+  const trimmed = range.trim();
+  if (trimmed === "" || trimmed === "*" || /^x$/i.test(trimmed)) {
+    return true;
+  }
+  for (const clause of trimmed.split("||")) {
+    const comparators = clause.trim().split(/\s+/).filter(Boolean);
+    if (comparators.length === 0) {
+      return null;
+    }
+    let clauseResult = true;
+    for (const comparator of comparators) {
+      const result = satisfiesComparator(parsedVersion, comparator);
+      if (result === null) {
+        clauseResult = null;
+        break;
+      }
+      if (!result) {
+        clauseResult = false;
+        break;
+      }
+    }
+    if (clauseResult === null) {
+      return null;
+    }
+    if (clauseResult) {
+      return true;
+    }
+  }
+  return false;
+}

package/dist/declaration/semver.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/declaration/semver.test.mjs

@@ -0,0 +1,87 @@
+import { describe, expect, it } from "vitest";
+import { compareSemver, parseSemver, satisfiesRange } from "./semver.mjs";
+describe("parseSemver", () => {
+  it("should parse a plain version", () => {
+    const result = parseSemver("3.4.21");
+    expect(result).toEqual({
+      major: 3,
+      minor: 4,
+      patch: 21,
+      prerelease: []
+    });
+  });
+  it("should parse a prerelease version with build metadata", () => {
+    const result = parseSemver("1.2.3-beta.1+build.5");
+    expect(result).toEqual({
+      major: 1,
+      minor: 2,
+      patch: 3,
+      prerelease: ["beta", "1"]
+    });
+  });
+  it("should return null for non-version input", () => {
+    expect(parseSemver("workspace:*")).toBeNull();
+    expect(parseSemver("not-a-version")).toBeNull();
+    expect(parseSemver("1.2")).toBeNull();
+  });
+});
+describe("compareSemver", () => {
+  it("should order versions by triple then prerelease", () => {
+    const v340 = parseSemver("3.4.0");
+    const v352 = parseSemver("3.5.2");
+    const v352beta = parseSemver("3.5.2-beta.1");
+    if (!v340 || !v352 || !v352beta) {
+      throw new Error("fixture versions must parse");
+    }
+    expect(compareSemver(v340, v352)).toBe(-1);
+    expect(compareSemver(v352, v340)).toBe(1);
+    expect(compareSemver(v352, v352)).toBe(0);
+    expect(compareSemver(v352beta, v352)).toBe(-1);
+  });
+});
+describe("satisfiesRange", () => {
+  it("should handle caret ranges", () => {
+    expect(satisfiesRange("3.5.2", "^3.4.0")).toBe(true);
+    expect(satisfiesRange("4.0.0", "^3.4.0")).toBe(false);
+    expect(satisfiesRange("3.3.9", "^3.4.0")).toBe(false);
+    expect(satisfiesRange("0.2.5", "^0.2.3")).toBe(true);
+    expect(satisfiesRange("0.3.0", "^0.2.3")).toBe(false);
+    expect(satisfiesRange("0.0.3", "^0.0.3")).toBe(true);
+    expect(satisfiesRange("0.0.4", "^0.0.3")).toBe(false);
+  });
+  it("should handle tilde ranges", () => {
+    expect(satisfiesRange("1.2.9", "~1.2.3")).toBe(true);
+    expect(satisfiesRange("1.3.0", "~1.2.3")).toBe(false);
+    expect(satisfiesRange("1.5.0", "~1")).toBe(true);
+    expect(satisfiesRange("2.0.0", "~1")).toBe(false);
+  });
+  it("should handle comparator ranges", () => {
+    expect(satisfiesRange("3.4.0", ">=3.4.0")).toBe(true);
+    expect(satisfiesRange("3.3.9", ">=3.4.0")).toBe(false);
+    expect(satisfiesRange("3.4.0", ">3.4.0")).toBe(false);
+    expect(satisfiesRange("3.4.0", "<=3.4.0")).toBe(true);
+    expect(satisfiesRange("3.4.0", "<3.4.0")).toBe(false);
+    expect(satisfiesRange("3.4.0", "=3.4.0")).toBe(true);
+  });
+  it("should handle exact versions, star and x-ranges", () => {
+    expect(satisfiesRange("3.4.21", "3.4.21")).toBe(true);
+    expect(satisfiesRange("3.4.22", "3.4.21")).toBe(false);
+    expect(satisfiesRange("9.9.9", "*")).toBe(true);
+    expect(satisfiesRange("1.7.0", "1.x")).toBe(true);
+    expect(satisfiesRange("2.0.0", "1.x")).toBe(false);
+    expect(satisfiesRange("1.2.9", "1.2.x")).toBe(true);
+    expect(satisfiesRange("1.3.0", "1.2.x")).toBe(false);
+    expect(satisfiesRange("1.5.0", "1")).toBe(true);
+  });
+  it("should handle compound AND and OR clauses", () => {
+    expect(satisfiesRange("1.5.0", ">=1.2.0 <2.0.0")).toBe(true);
+    expect(satisfiesRange("2.1.0", ">=1.2.0 <2.0.0")).toBe(false);
+    expect(satisfiesRange("2.1.0", "^1.0.0 || ^2.0.0")).toBe(true);
+    expect(satisfiesRange("3.0.0", "^1.0.0 || ^2.0.0")).toBe(false);
+  });
+  it("should return null for unparsable ranges or versions", () => {
+    expect(satisfiesRange("1.0.0", "workspace:*")).toBeNull();
+    expect(satisfiesRange("1.0.0", "npm:vue@^3.0.0")).toBeNull();
+    expect(satisfiesRange("not-a-version", "^1.0.0")).toBeNull();
+  });
+});

package/dist/declaration/test-fixtures.d.ts

@@ -0,0 +1,18 @@
+/** Test-only helpers building fake package trees in temp directories. */
+export interface FixturePackage {
+    /** Directory relative to the fixture root. */
+    dir: string;
+    packageJson: Record<string, unknown>;
+    /** Write a dist/client/manifest.json stub (marks the module as built). */
+    built?: boolean;
+    /** Manifest content for the stub; implies `built`. */
+    manifest?: Record<string, unknown>;
+    /**
+     * Skip auto-creating the empty source files for declared
+     * `esmx.entry`/`esmx.exports` targets — use to trigger E_TARGET_MISSING.
+     */
+    noSources?: boolean;
+}
+export declare function createFixtureRoot(): Promise<string>;
+export declare function writeFixturePackage(rootDir: string, pkg: FixturePackage): string;
+export declare function removeFixtureRoot(rootDir: string): Promise<void>;

package/dist/declaration/test-fixtures.mjs

@@ -0,0 +1,69 @@
+import fs from "node:fs";
+import fsp from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+function declaredTargets(esmx) {
+  if (typeof esmx !== "object" || esmx === null) {
+    return [];
+  }
+  const out = [];
+  const decl = esmx;
+  const entry = decl.entry;
+  if (typeof entry === "object" && entry !== null) {
+    for (const side of Object.values(entry)) {
+      if (typeof side === "string") {
+        out.push(side);
+      }
+    }
+  }
+  const exports = decl.exports;
+  if (typeof exports === "object" && exports !== null) {
+    for (const value of Object.values(exports)) {
+      if (typeof value === "string") {
+        out.push(value);
+      } else if (typeof value === "object" && value !== null) {
+        for (const side of Object.values(
+          value
+        )) {
+          if (typeof side === "string") {
+            out.push(side);
+          }
+        }
+      }
+    }
+  }
+  return out;
+}
+export async function createFixtureRoot() {
+  const dir = await fsp.mkdtemp(path.join(os.tmpdir(), "esmx-declaration-"));
+  return fs.realpathSync(dir);
+}
+export function writeFixturePackage(rootDir, pkg) {
+  const dir = path.join(rootDir, pkg.dir);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(
+    path.join(dir, "package.json"),
+    JSON.stringify(pkg.packageJson, null, 4)
+  );
+  if (pkg.built || pkg.manifest) {
+    const clientDir = path.join(dir, "dist/client");
+    fs.mkdirSync(clientDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(clientDir, "manifest.json"),
+      JSON.stringify(pkg.manifest ?? {})
+    );
+  }
+  if (!pkg.noSources) {
+    for (const target of declaredTargets(pkg.packageJson.esmx)) {
+      const file = path.resolve(dir, target);
+      fs.mkdirSync(path.dirname(file), { recursive: true });
+      if (!fs.existsSync(file)) {
+        fs.writeFileSync(file, "");
+      }
+    }
+  }
+  return dir;
+}
+export async function removeFixtureRoot(rootDir) {
+  await fsp.rm(rootDir, { recursive: true, force: true });
+}

package/dist/declaration/types.d.ts

@@ -0,0 +1,58 @@
+/**
+ * RFC 0001 declaration layer types.
+ *
+ * The `esmx` field of package.json carries strictly local protocol facts:
+ * a module declares only facts about itself (RFC P2).
+ */
+export interface EsmxDeclarationEntry {
+    client?: string;
+    server?: string;
+}
+export interface EsmxDeclarationExportFork {
+    client?: string | false;
+    server?: string | false;
+}
+export type EsmxDeclarationExportValue = string | EsmxDeclarationExportFork;
+export interface EsmxDeclaration {
+    entry?: EsmxDeclarationEntry;
+    exports?: Record<string, EsmxDeclarationExportValue>;
+    provides?: string[];
+    uses?: string[];
+}
+/**
+ * Complete diagnostic taxonomy from RFC 0001 §7, plus E_SCHEMA for
+ * declaration shape violations (the RFC ships a JSON Schema but assigns
+ * no code to schema failures; one code is needed so agents can detect them).
+ */
+export declare const DiagnosticCode: {
+    readonly E_NOT_LINKED: "E_NOT_LINKED";
+    readonly E_NOT_BUILT: "E_NOT_BUILT";
+    readonly E_CYCLE: "E_CYCLE";
+    readonly E_VERSION: "E_VERSION";
+    readonly E_DUP_PROVIDER: "E_DUP_PROVIDER";
+    /** A declared entry/exports target file does not exist on disk. */
+    readonly E_TARGET_MISSING: "E_TARGET_MISSING";
+    readonly E_NOT_USED: "E_NOT_USED";
+    readonly E_NO_EXPORT: "E_NO_EXPORT";
+    readonly E_PROTOCOL: "E_PROTOCOL";
+    readonly E_PROTOCOL_IN_BEHAVIOR: "E_PROTOCOL_IN_BEHAVIOR";
+    readonly E_SCHEMA: "E_SCHEMA";
+    readonly W_MULTI_MAJOR: "W_MULTI_MAJOR";
+    readonly W_NO_RANGE: "W_NO_RANGE";
+    readonly W_TYPE_DRIFT: "W_TYPE_DRIFT";
+};
+export type DiagnosticCodeValue = (typeof DiagnosticCode)[keyof typeof DiagnosticCode];
+export type DiagnosticSeverity = 'error' | 'warning';
+export type DiagnosticCheck = 'intent';
+/** Structured diagnostic matching the RFC `esmx validate --json` envelope. */
+export interface Diagnostic {
+    code: string;
+    severity: DiagnosticSeverity;
+    module: string;
+    package?: string;
+    check?: DiagnosticCheck;
+    found?: string;
+    required?: string;
+    message: string;
+    fix: string;
+}

package/dist/declaration/types.mjs

@@ -0,0 +1,21 @@
+export const DiagnosticCode = {
+  E_NOT_LINKED: "E_NOT_LINKED",
+  E_NOT_BUILT: "E_NOT_BUILT",
+  E_CYCLE: "E_CYCLE",
+  E_VERSION: "E_VERSION",
+  E_DUP_PROVIDER: "E_DUP_PROVIDER",
+  /** A declared entry/exports target file does not exist on disk. */
+  E_TARGET_MISSING: "E_TARGET_MISSING",
+  // Build-time (phase 3) codes: emitted by the bundler during its
+  // per-specifier traversal, NOT by the build-free `esmx validate` (which
+  // never lexes source). Reserved here so the bundler emits them with the
+  // same envelope; do not wire emit paths into the resolver.
+  E_NOT_USED: "E_NOT_USED",
+  E_NO_EXPORT: "E_NO_EXPORT",
+  E_PROTOCOL: "E_PROTOCOL",
+  E_PROTOCOL_IN_BEHAVIOR: "E_PROTOCOL_IN_BEHAVIOR",
+  E_SCHEMA: "E_SCHEMA",
+  W_MULTI_MAJOR: "W_MULTI_MAJOR",
+  W_NO_RANGE: "W_NO_RANGE",
+  W_TYPE_DRIFT: "W_TYPE_DRIFT"
+};

package/dist/index.d.ts

@@ -1,6 +1,9 @@
 export { type App, createApp } from './app';
 export { type BuildEnvironment, type COMMAND, Esmx, type EsmxOptions, type ImportMap, type ScopesMap, type SpecifierMap } from './core';
-export type { ManifestJson, ManifestJsonChunk, ManifestJsonChunks, ManifestJsonExport, ManifestJsonExports } from './manifest-json';
+export type { Diagnostic, DiagnosticCheck, DiagnosticCodeValue, DiagnosticSeverity, EsmxDeclaration, EsmxDeclarationEntry, EsmxDeclarationExportFork, EsmxDeclarationExportValue, ReadDeclarationResult, ResolveDeclarationOptions, ResolveDeclarationResult, SupplyEntry, SupplyGroup } from './declaration';
+export { DiagnosticCode, esmxDeclarationSchema, readDeclaration, resolveDeclaration } from './declaration';
+export type { ManifestJson, ManifestJsonChunk, ManifestJsonChunks, ManifestJsonExport, ManifestJsonExports, ManifestJsonProvide, ManifestProtocolFields } from './manifest-json';
+export { buildManifestProtocolFields, MANIFEST_PROTOCOL_VERSION } from './manifest-json';
 export type { ModuleConfig, ModuleConfigExportExport, ModuleConfigExportExports, ModuleConfigExportObject, ModuleConfigImportMapping, ParsedModuleConfig, ParsedModuleConfigEnvironment, ParsedModuleConfigExport, ParsedModuleConfigExports, ParsedModuleConfigLink } from './module-config';
 export type { PackConfig, ParsedPackConfig } from './pack-config';
 export { RenderContext, type RenderContextOptions, type RenderFiles, type ServerRenderHandle } from './render-context';

package/dist/index.mjs

@@ -2,6 +2,16 @@ export { createApp } from "./app.mjs";
 export {
   Esmx
 } from "./core.mjs";
+export {
+  DiagnosticCode,
+  esmxDeclarationSchema,
+  readDeclaration,
+  resolveDeclaration
+} from "./declaration/index.mjs";
+export {
+  buildManifestProtocolFields,
+  MANIFEST_PROTOCOL_VERSION
+} from "./manifest-json.mjs";
 export {
   RenderContext
 } from "./render-context.mjs";

package/dist/manifest-json.d.ts

@@ -1,10 +1,36 @@
 import type { BuildEnvironment } from './core';
 import type { ParsedModuleConfig } from './module-config';
+/**
+ * Manifest protocol version emitted by the bundler plugins (RFC 0001 §5).
+ * The linker rejects manifests whose `protocol` is HIGHER than this value.
+ */
+export declare const MANIFEST_PROTOCOL_VERSION = 2;
 export interface ManifestJson {
+    /**
+     * Manifest protocol version (RFC 0001 §5). Absent in pre-v2 manifests;
+     * readers treat absence as protocol 1 and skip v2-only checks.
+     */
+    protocol: number;
     /**
      * Module name
      */
     name: string;
+    /**
+     * Module version, transcribed from the module's package.json at build
+     * time (RFC 0001 §5). Pre-v2 manifests default to '0.0.0' at read time.
+     */
+    version: string;
+    /**
+     * Resolved versions for every pkg-export (`pkg: true`) package, captured
+     * at build time (RFC 0001 §5).
+     * Type: Record<package specifier, provide record>
+     */
+    provides: Record<string, ManifestJsonProvide>;
+    /**
+     * Consumption edges transcribed from the module's package.json `esmx.uses`
+     * declaration (RFC 0001 §5). Pre-v2 manifests default to [] at read time.
+     */
+    uses: string[];
     /**
      * Scope-specific import mappings
      * Type: Record<scope name, import mappings within that scope>
@@ -24,6 +50,24 @@ export interface ManifestJson {
      * Type: Record<source file, compilation information>
      */
     chunks: ManifestJsonChunks;
+    /**
+     * Subresource Integrity (SRI) hashes for build output files.
+     * Only generated in production builds to avoid development overhead.
+     * Type: Record<file path, integrity hash>
+     */
+    integrity?: Record<string, string>;
+}
+/**
+ * Build-time facts about one provided (pkg-export) package (RFC 0001 §5).
+ */
+export interface ManifestJsonProvide {
+    /**
+     * The RESOLVED installed version of the provided package at build time,
+     * read from node_modules/<pkg>/package.json relative to the module root.
+     * Subpath specifiers (e.g. `vue/jsx-runtime`) resolve via their parent
+     * package. '0.0.0' when the package could not be resolved.
+     */
+    version: string;
 }
 /**
  * Export item configuration mapping
@@ -69,6 +113,23 @@ export interface ManifestJsonChunk {
      */
     resources: string[];
 }
+/**
+ * The RFC 0001 §5 protocol fields shared by every bundler manifest plugin.
+ */
+export interface ManifestProtocolFields {
+    protocol: number;
+    version: string;
+    provides: Record<string, ManifestJsonProvide>;
+    uses: string[];
+}
+/**
+ * Builds the RFC 0001 §5 manifest protocol fields (`protocol`, `version`,
+ * `provides`, `uses`) from the module root's package.json plus the list of
+ * pkg-export package specifiers the bundler plugin computed. Shared by the
+ * @esmx/rspack, @esmx/rsbuild and @esmx/vite manifest plugins so their output
+ * cannot drift.
+ */
+export declare function buildManifestProtocolFields(moduleRoot: string, provides: string[]): ManifestProtocolFields;
 /**
  * Get service manifest files
  */

package/dist/manifest-json.mjs

@@ -1,20 +1,83 @@
+import fs from "node:fs";
 import fsp from "node:fs/promises";
 import path from "node:path";
+export const MANIFEST_PROTOCOL_VERSION = 2;
+function readJsonObjectSync(filePath) {
+  let json;
+  try {
+    json = JSON.parse(fs.readFileSync(filePath, "utf-8"));
+  } catch {
+    return null;
+  }
+  if (typeof json !== "object" || json === null || Array.isArray(json)) {
+    return null;
+  }
+  return json;
+}
+function parentPackageName(specifier) {
+  const segments = specifier.split("/");
+  return specifier.startsWith("@") ? segments.slice(0, 2).join("/") : segments[0];
+}
+function resolveInstalledVersionSync(fromDir, packageName) {
+  let dir = path.resolve(fromDir);
+  for (; ; ) {
+    const candidate = path.join(dir, "node_modules", packageName);
+    const pkg = readJsonObjectSync(path.join(candidate, "package.json"));
+    if (pkg) {
+      return typeof pkg.version === "string" && pkg.version !== "" ? pkg.version : null;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) {
+      return null;
+    }
+    dir = parent;
+  }
+}
+export function buildManifestProtocolFields(moduleRoot, provides) {
+  const pkg = readJsonObjectSync(path.resolve(moduleRoot, "package.json"));
+  const version = pkg && typeof pkg.version === "string" && pkg.version !== "" ? pkg.version : "0.0.0";
+  const esmx = pkg && typeof pkg.esmx === "object" && pkg.esmx !== null ? pkg.esmx : null;
+  const uses = Array.isArray(esmx?.uses) ? esmx.uses.filter((item) => typeof item === "string") : [];
+  const providesField = {};
+  for (const name of provides) {
+    const resolvedVersion = resolveInstalledVersionSync(
+      moduleRoot,
+      parentPackageName(name)
+    );
+    providesField[name] = {
+      version: resolvedVersion ?? "0.0.0"
+    };
+  }
+  return {
+    protocol: MANIFEST_PROTOCOL_VERSION,
+    version,
+    provides: providesField,
+    uses
+  };
+}
 export async function getManifestList(env, moduleConfig) {
   return Promise.all(
     Object.values(moduleConfig.links).map(async (item) => {
       const filename = path.resolve(item[env], "manifest.json");
+      let data;
       try {
-        const data = await JSON.parse(
-          await fsp.readFile(filename, "utf-8")
-        );
-        data.name = item.name;
-        return data;
+        data = await JSON.parse(await fsp.readFile(filename, "utf-8"));
       } catch (e) {
         throw new Error(
           `'${item.name}' service '${filename}' file read error on environment '${env}': ${e instanceof Error ? e.message : String(e)}`
         );
       }
+      data.name = item.name;
+      data.protocol = typeof data.protocol === "number" ? data.protocol : 1;
+      if (data.protocol > MANIFEST_PROTOCOL_VERSION) {
+        throw new Error(
+          `[E_PROTOCOL] '${item.name}' service '${filename}' declares manifest protocol ${data.protocol}, but this linker supports up to ${MANIFEST_PROTOCOL_VERSION}. Upgrade esmx, or rebuild '${item.name}' with a matching toolchain.`
+        );
+      }
+      data.version = typeof data.version === "string" ? data.version : "0.0.0";
+      data.provides = typeof data.provides === "object" && data.provides !== null ? data.provides : {};
+      data.uses = Array.isArray(data.uses) ? data.uses : [];
+      return data;
     })
   );
 }