@kungfu-tech/buildchain 2.10.4 → 2.10.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "2.10.4",
+  "version": "2.10.5",
   "private": false,
   "description": "Buildchain Release Passport, release governance, CLI toolkit, and site facts.",
   "repository": "https://github.com/kungfu-systems/buildchain",
@@ -20,7 +20,8 @@
     "./diagnostics": "./packages/core/diagnostics.js",
     "./homebrew": "./packages/core/homebrew.js",
     "./issue-reporting": "./packages/core/issue-reporting.js",
-    "./kfd-3-surfaces": "./packages/core/kfd3-surface-register.js",
+    "./kfd": "./packages/core/kfd.js",
+    "./buildchain-layout": "./packages/core/buildchain-layout.js",
     "./release-line-bootstrap": "./packages/core/release-line-bootstrap.js",
     "./readme-badges": "./packages/core/readme-badges.js",
     "./public-surface-audit": "./packages/core/public-surface-audit.js",

package/packages/core/buildchain-config.js

@@ -3,8 +3,12 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { parse, stringify } from "smol-toml";
+import {
+  BUILDCHAIN_CONFIG_PATH,
+  resolveBuildchainConfigPath,
+} from "./buildchain-layout.js";
 
-const CONFIG_FILE = "buildchain.toml";
+const CONFIG_FILE = BUILDCHAIN_CONFIG_PATH;
 const RESERVED_LIFECYCLE_KEYS = new Set(["env", "shell"]);
 const SUPPORTED_VERSION_FILE_TYPES = new Set(["json", "toml", "regex"]);
 const SUPPORTED_VERSION_STRATEGIES = new Set(["semver", "anchored"]);
@@ -97,7 +101,8 @@ function setByDottedKey(target, key, value) {
 }
 
 export function loadBuildchainConfig(cwd = process.cwd()) {
-  const filePath = path.join(cwd, CONFIG_FILE);
+  const configPath = resolveBuildchainConfigPath(cwd);
+  const filePath = path.join(cwd, configPath);
   if (!fs.existsSync(filePath)) {
     return undefined;
   }
@@ -106,13 +111,13 @@ export function loadBuildchainConfig(cwd = process.cwd()) {
   try {
     config = parse(source);
   } catch (error) {
-    throw new Error(`${CONFIG_FILE} parse failed: ${error.message}`);
+    throw new Error(`${configPath} parse failed: ${error.message}`);
   }
   if (config.schema !== 1) {
-    throw new Error(`${CONFIG_FILE} schema must be 1`);
+    throw new Error(`${configPath} schema must be 1`);
   }
   return {
-    path: CONFIG_FILE,
+    path: configPath,
     filePath,
     config: normalizeBuildchainConfig(config),
   };

package/packages/core/buildchain-layout.js

@@ -0,0 +1,157 @@
+import fs from "node:fs";
+import path from "node:path";
+
+export const BUILDCHAIN_DIR = ".buildchain";
+export const BUILDCHAIN_CONFIG_PATH = ".buildchain/buildchain.toml";
+export const LEGACY_BUILDCHAIN_CONFIG_PATH = "buildchain.toml";
+export const BUILDCHAIN_CONTRACT_LOCK_PATH = ".buildchain/contract-lock.json";
+export const LEGACY_BUILDCHAIN_CONTRACT_LOCK_PATH = "buildchain.contract-lock.json";
+export const BUILDCHAIN_KFD3_SURFACE_REGISTRY_PATH = ".buildchain/kfd/kfd-3-surfaces.json";
+export const LEGACY_BUILDCHAIN_KFD3_SURFACE_REGISTRY_PATH = "buildchain.kfd3.json";
+export const BUILDCHAIN_RELEASE_PASSPORT_PATH = ".buildchain/release-passport/buildchain.release.json";
+export const LEGACY_BUILDCHAIN_RELEASE_PASSPORT_PATH = "buildchain.release.json";
+
+export const BUILDCHAIN_GENERATED_DIRS = Object.freeze([
+  ".buildchain/artifacts",
+  ".buildchain/diagnostics",
+  ".buildchain/logs",
+  ".buildchain/tmp",
+  ".buildchain/runtime",
+  ".buildchain/release-state",
+  ".buildchain/release-evidence",
+  ".buildchain/downloaded-manifests",
+  ".buildchain/downloaded-diagnostics",
+  ".buildchain/downloaded-relay-manifests",
+  ".buildchain/relayed-artifacts",
+]);
+
+export function toPosixPath(value) {
+  return String(value || "").split(path.sep).join("/");
+}
+
+export function repoPath(cwd, relativePath) {
+  return path.join(cwd, relativePath);
+}
+
+export function firstExistingRepoPath(cwd, candidates = []) {
+  for (const candidate of candidates) {
+    if (fs.existsSync(repoPath(cwd, candidate))) {
+      return candidate;
+    }
+  }
+  return candidates[0] || "";
+}
+
+export function resolveBuildchainConfigPath(cwd = process.cwd()) {
+  return firstExistingRepoPath(cwd, [
+    BUILDCHAIN_CONFIG_PATH,
+    LEGACY_BUILDCHAIN_CONFIG_PATH,
+  ]);
+}
+
+export function resolveBuildchainContractLockPath(cwd = process.cwd()) {
+  return firstExistingRepoPath(cwd, [
+    BUILDCHAIN_CONTRACT_LOCK_PATH,
+    LEGACY_BUILDCHAIN_CONTRACT_LOCK_PATH,
+  ]);
+}
+
+export function resolveKfd3SurfaceRegistryPath(cwd = process.cwd()) {
+  return firstExistingRepoPath(cwd, [
+    BUILDCHAIN_KFD3_SURFACE_REGISTRY_PATH,
+    LEGACY_BUILDCHAIN_KFD3_SURFACE_REGISTRY_PATH,
+  ]);
+}
+
+export function resolveReleasePassportPath(cwd = process.cwd()) {
+  return firstExistingRepoPath(cwd, [
+    BUILDCHAIN_RELEASE_PASSPORT_PATH,
+    LEGACY_BUILDCHAIN_RELEASE_PASSPORT_PATH,
+  ]);
+}
+
+export function discoverBuildchainRepoFiles(cwd = process.cwd()) {
+  const files = [
+    {
+      kind: "config",
+      canonical: BUILDCHAIN_CONFIG_PATH,
+      legacy: LEGACY_BUILDCHAIN_CONFIG_PATH,
+      tracked: true,
+    },
+    {
+      kind: "contract-lock",
+      canonical: BUILDCHAIN_CONTRACT_LOCK_PATH,
+      legacy: LEGACY_BUILDCHAIN_CONTRACT_LOCK_PATH,
+      tracked: true,
+    },
+    {
+      kind: "kfd-3-surface-registry",
+      canonical: BUILDCHAIN_KFD3_SURFACE_REGISTRY_PATH,
+      legacy: LEGACY_BUILDCHAIN_KFD3_SURFACE_REGISTRY_PATH,
+      tracked: true,
+    },
+    {
+      kind: "release-passport",
+      canonical: BUILDCHAIN_RELEASE_PASSPORT_PATH,
+      legacy: LEGACY_BUILDCHAIN_RELEASE_PASSPORT_PATH,
+      tracked: false,
+    },
+  ];
+  return files.map((entry) => {
+    const canonicalExists = fs.existsSync(repoPath(cwd, entry.canonical));
+    const legacyExists = fs.existsSync(repoPath(cwd, entry.legacy));
+    return {
+      ...entry,
+      canonicalExists,
+      legacyExists,
+      activePath: canonicalExists ? entry.canonical : legacyExists ? entry.legacy : entry.canonical,
+      migrationNeeded: !canonicalExists && legacyExists,
+    };
+  });
+}
+
+export function planBuildchainLayoutMigration({ cwd = process.cwd() } = {}) {
+  const entries = discoverBuildchainRepoFiles(cwd);
+  const moves = entries
+    .filter((entry) => entry.migrationNeeded)
+    .map((entry) => ({
+      kind: entry.kind,
+      from: entry.legacy,
+      to: entry.canonical,
+      tracked: entry.tracked,
+    }));
+  return {
+    schemaVersion: 1,
+    contract: "kungfu-buildchain-repository-layout-migration",
+    cwd: path.resolve(cwd),
+    canonicalRoot: BUILDCHAIN_DIR,
+    status: moves.length > 0 ? "migration-needed" : "current",
+    files: entries,
+    generatedDirs: BUILDCHAIN_GENERATED_DIRS,
+    moves,
+  };
+}
+
+export function migrateBuildchainLayout({ cwd = process.cwd(), write = false, force = false } = {}) {
+  const plan = planBuildchainLayoutMigration({ cwd });
+  const applied = [];
+  if (write) {
+    for (const move of plan.moves) {
+      const from = repoPath(cwd, move.from);
+      const to = repoPath(cwd, move.to);
+      if (fs.existsSync(to) && !force) {
+        throw new Error(`${move.to} already exists; pass --force to overwrite`);
+      }
+      fs.mkdirSync(path.dirname(to), { recursive: true });
+      fs.renameSync(from, to);
+      applied.push(move);
+    }
+  }
+  return {
+    ...plan,
+    write,
+    force,
+    status: write && applied.length === plan.moves.length ? "applied" : plan.status,
+    applied,
+  };
+}

package/packages/core/index.js

@@ -257,6 +257,40 @@ export {
   updateHomebrewTap,
 } from "./homebrew.js";
 
+export {
+  BUILDCHAIN_CONFIG_PATH,
+  BUILDCHAIN_CONTRACT_LOCK_PATH,
+  BUILDCHAIN_DIR,
+  BUILDCHAIN_GENERATED_DIRS,
+  BUILDCHAIN_KFD3_SURFACE_REGISTRY_PATH,
+  BUILDCHAIN_RELEASE_PASSPORT_PATH,
+  LEGACY_BUILDCHAIN_CONFIG_PATH,
+  LEGACY_BUILDCHAIN_CONTRACT_LOCK_PATH,
+  LEGACY_BUILDCHAIN_KFD3_SURFACE_REGISTRY_PATH,
+  LEGACY_BUILDCHAIN_RELEASE_PASSPORT_PATH,
+  discoverBuildchainRepoFiles,
+  migrateBuildchainLayout,
+  planBuildchainLayoutMigration,
+  resolveBuildchainConfigPath,
+  resolveBuildchainContractLockPath,
+  resolveKfd3SurfaceRegistryPath,
+  resolveReleasePassportPath,
+} from "./buildchain-layout.js";
+export {
+  buildchainKfdClaims,
+  collectKfdStatus,
+  discoverKfdStandards,
+  layout,
+  kfd1,
+  kfd2,
+  kfd3,
+  kfd4,
+  listKfdSchemas,
+  normalizeKfdStandardId,
+  readKfdSchema,
+  schemas,
+} from "./kfd.js";
+
 export {
   KFD3_CAPABILITY_QUERY_CONTRACT,
   KFD3_DEFAULT_REGISTRY_PATH,

package/packages/core/kfd.js

@@ -0,0 +1,273 @@
+import fs from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+
+import {
+  createBuildchainKfd1Witness,
+  createBuildchainKfd2Claims,
+  createBuildchainKfd3ArtifactWitness,
+  createBuildchainKfd3PrebuildWitness,
+  createBuildchainKfdClaimRegistry,
+  createBuildchainKfdSurfaceRegistry,
+  createBuildchainPublicClaimDefinitions,
+} from "./buildchain-kfd-claims.js";
+import {
+  migrateBuildchainLayout,
+  planBuildchainLayoutMigration,
+  resolveBuildchainConfigPath,
+  resolveBuildchainContractLockPath,
+  resolveKfd3SurfaceRegistryPath,
+  resolveReleasePassportPath,
+} from "./buildchain-layout.js";
+import {
+  createKfd1ReleaseGateEvidence,
+  createKfd3CollaborationInterfaceReleaseGateEvidence,
+  normalizeKfd1ContractWorldWitness,
+  normalizeKfd3CollaborationInterfaceArtifactWitness,
+  normalizeKfd3CollaborationInterfacePrebuildWitness,
+  resolveKfd1Metadata,
+  resolveKfd2Metadata,
+  resolveKfd3Metadata,
+  validateKfd1ReleaseGateEvidence,
+  validateKfd2TrustTaxonomyEntry,
+  validateKfd3CollaborationInterfaceReleaseGateEvidence,
+} from "./kfd-gate.js";
+import {
+  auditKfd3Surfaces,
+  createKfd3SurfaceWitness,
+  detectKfd3Surfaces,
+  queryKfd3Capabilities,
+  readKfd3SurfaceRegistry,
+  registerKfd3Surfaces,
+  writeKfd3SurfaceRegistry,
+} from "./kfd3-surface-register.js";
+
+const require = createRequire(import.meta.url);
+
+function readJsonPackageExport(exportPath) {
+  return JSON.parse(fs.readFileSync(require.resolve(exportPath), "utf8"));
+}
+
+function readJsonFile(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, "utf8"));
+}
+
+function readJsonInput(value, { cwd = process.cwd(), label = "json" } = {}) {
+  const input = String(value || "").trim();
+  if (!input) {
+    throw new Error(`${label} is required`);
+  }
+  const filePath = path.isAbsolute(input) ? input : path.join(cwd, input);
+  if (fs.existsSync(filePath)) {
+    return readJsonFile(filePath);
+  }
+  return JSON.parse(input);
+}
+
+function readJsonInputs(values = [], { cwd = process.cwd(), label = "json" } = {}) {
+  return values.map((value, index) => readJsonInput(value, { cwd, label: `${label}[${index}]` }));
+}
+
+export function normalizeKfdStandardId(value) {
+  const raw = String(value || "").trim().toLowerCase();
+  const match = raw.match(/^(?:kfd[-\s]?)?([1-9][0-9]*)$/);
+  if (!match) {
+    throw new Error(`unsupported KFD standard: ${value}`);
+  }
+  return `kfd-${match[1]}`;
+}
+
+export function discoverKfdStandards() {
+  const packageJson = readJsonPackageExport("@kungfu-tech/kfd/package.json");
+  const standards = readJsonPackageExport("@kungfu-tech/kfd/standards.json");
+  return {
+    schemaVersion: 1,
+    contract: "kungfu-buildchain-kfd-standard-discovery",
+    package: {
+      name: packageJson.name,
+      version: packageJson.version,
+      repository: packageJson.repository?.url || "",
+    },
+    metadataSchema: standards.metadataSchema || {},
+    source: standards.source || {},
+    standards: Object.entries(standards.standards || {})
+      .map(([key, value]) => ({
+        key: value?.key || key,
+        id: value?.id || value?.label || key,
+        label: value?.label || value?.id || key,
+        title: value?.title || "",
+        status: value?.status || "",
+        revision: value?.revision || 0,
+        schemaIds: { ...(value?.schemaIds || {}) },
+        schemaPaths: { ...(value?.schemaPaths || {}) },
+      }))
+      .sort((a, b) => a.key.localeCompare(b.key)),
+  };
+}
+
+export function listKfdSchemas({ standard = "" } = {}) {
+  const discovery = discoverKfdStandards();
+  const selectedStandard = standard ? normalizeKfdStandardId(standard) : "";
+  const schemas = [];
+  for (const entry of discovery.standards) {
+    if (selectedStandard && normalizeKfdStandardId(entry.key) !== selectedStandard) continue;
+    const names = [...new Set([
+      ...Object.keys(entry.schemaIds || {}),
+      ...Object.keys(entry.schemaPaths || {}),
+    ])].sort();
+    for (const name of names) {
+      schemas.push({
+        standard: entry.key,
+        name,
+        schemaId: entry.schemaIds?.[name] || "",
+        schemaPath: entry.schemaPaths?.[name] || "",
+      });
+    }
+  }
+  return {
+    schemaVersion: 1,
+    contract: "kungfu-buildchain-kfd-schema-list",
+    package: discovery.package,
+    standard: selectedStandard || "",
+    schemas,
+  };
+}
+
+export function readKfdSchema({ standard, schema = "" } = {}) {
+  const selectedStandard = normalizeKfdStandardId(standard);
+  const schemaList = listKfdSchemas({ standard: selectedStandard }).schemas;
+  const selectedSchema = schema
+    ? schemaList.find((entry) => entry.name === schema || entry.schemaId === schema || entry.schemaPath === schema)
+    : schemaList[0];
+  if (!selectedSchema?.schemaPath) {
+    throw new Error(`KFD schema not found for ${selectedStandard}${schema ? `:${schema}` : ""}`);
+  }
+  return {
+    schemaVersion: 1,
+    contract: "kungfu-buildchain-kfd-schema",
+    standard: selectedStandard,
+    name: selectedSchema.name,
+    schemaId: selectedSchema.schemaId,
+    schemaPath: selectedSchema.schemaPath,
+    schema: readJsonPackageExport(`@kungfu-tech/kfd/${selectedSchema.schemaPath}`),
+  };
+}
+
+export const schemas = Object.freeze({
+  discover: discoverKfdStandards,
+  list: listKfdSchemas,
+  read: readKfdSchema,
+});
+
+export const kfd1 = Object.freeze({
+  resolveMetadata: resolveKfd1Metadata,
+  normalizeContractWorldWitness: normalizeKfd1ContractWorldWitness,
+  createReleaseGateEvidence: createKfd1ReleaseGateEvidence,
+  validateReleaseGateEvidence: validateKfd1ReleaseGateEvidence,
+  createBuildchainWitness: createBuildchainKfd1Witness,
+  createGate: ({ cwd = process.cwd(), witnessJsons = [], artifactRoot = "", artifacts = [] } = {}) => createKfd1ReleaseGateEvidence({
+    cwd,
+    artifactRoot,
+    artifacts,
+    witnesses: readJsonInputs(witnessJsons, { cwd, label: "kfd-1 witness" }),
+  }),
+  validateGate: (section) => validateKfd1ReleaseGateEvidence(section),
+});
+
+export const kfd2 = Object.freeze({
+  resolveMetadata: resolveKfd2Metadata,
+  validateTrustTaxonomyEntry: validateKfd2TrustTaxonomyEntry,
+  createBuildchainClaims: createBuildchainKfd2Claims,
+  createBuildchainPublicClaimDefinitions,
+  validateTaxonomyEntries: ({ entries = [], kind = "residualRisk" } = {}) => entries.map((entry, index) => validateKfd2TrustTaxonomyEntry(entry, {
+    kind,
+    label: `${kind}[${index}]`,
+  })),
+});
+
+export const kfd3 = Object.freeze({
+  resolveMetadata: resolveKfd3Metadata,
+  normalizePrebuildWitness: normalizeKfd3CollaborationInterfacePrebuildWitness,
+  normalizeArtifactWitness: normalizeKfd3CollaborationInterfaceArtifactWitness,
+  createReleaseGateEvidence: createKfd3CollaborationInterfaceReleaseGateEvidence,
+  validateReleaseGateEvidence: validateKfd3CollaborationInterfaceReleaseGateEvidence,
+  detectSurfaces: detectKfd3Surfaces,
+  registerSurfaces: registerKfd3Surfaces,
+  auditSurfaces: auditKfd3Surfaces,
+  createSurfaceWitness: createKfd3SurfaceWitness,
+  queryCapabilities: queryKfd3Capabilities,
+  readSurfaceRegistry: readKfd3SurfaceRegistry,
+  writeSurfaceRegistry: writeKfd3SurfaceRegistry,
+  createBuildchainPrebuildWitness: createBuildchainKfd3PrebuildWitness,
+  createBuildchainArtifactWitness: createBuildchainKfd3ArtifactWitness,
+  createBuildchainSurfaceRegistry: createBuildchainKfdSurfaceRegistry,
+});
+
+export const kfd4 = Object.freeze({
+  schemas: {
+    list: (options = {}) => listKfdSchemas({ ...options, standard: "kfd-4" }),
+    read: (options = {}) => readKfdSchema({ ...options, standard: "kfd-4" }),
+  },
+  status: "schema-only",
+});
+
+export const buildchainKfdClaims = Object.freeze({
+  createClaimRegistry: createBuildchainKfdClaimRegistry,
+  createSurfaceRegistry: createBuildchainKfdSurfaceRegistry,
+  createPublicClaimDefinitions: createBuildchainPublicClaimDefinitions,
+});
+
+export function collectKfdStatus({ cwd = process.cwd() } = {}) {
+  const resolvedCwd = path.resolve(cwd);
+  const schemas = listKfdSchemas();
+  const layout = planBuildchainLayoutMigration({ cwd: resolvedCwd });
+  const paths = {
+    config: resolveBuildchainConfigPath(resolvedCwd),
+    contractLock: resolveBuildchainContractLockPath(resolvedCwd),
+    kfd3SurfaceRegistry: resolveKfd3SurfaceRegistryPath(resolvedCwd),
+    releasePassport: resolveReleasePassportPath(resolvedCwd),
+  };
+  const pathStatus = Object.fromEntries(Object.entries(paths).map(([key, relPath]) => [
+    key,
+    {
+      path: relPath,
+      exists: fs.existsSync(path.join(resolvedCwd, relPath)),
+    },
+  ]));
+  return {
+    schemaVersion: 1,
+    contract: "kungfu-buildchain-kfd-status",
+    cwd: resolvedCwd,
+    layout: {
+      status: layout.status,
+      canonicalRoot: layout.canonicalRoot,
+      migrationNeeded: layout.moves.length > 0,
+      moves: layout.moves,
+    },
+    standards: schemas.schemas.reduce((acc, entry) => {
+      acc[entry.standard] ||= [];
+      acc[entry.standard].push({
+        name: entry.name,
+        schemaId: entry.schemaId,
+        schemaPath: entry.schemaPath,
+      });
+      return acc;
+    }, {}),
+    support: {
+      "kfd-1": ["schema", "witness", "gate", "verify"],
+      "kfd-2": ["schema", "taxonomy", "claims"],
+      "kfd-3": ["schema", "detect", "register", "audit", "witness", "query"],
+      "kfd-4": ["schema"],
+    },
+    paths: pathStatus,
+  };
+}
+
+export const layout = Object.freeze({
+  plan: planBuildchainLayoutMigration,
+  migrate: migrateBuildchainLayout,
+  resolveConfigPath: resolveBuildchainConfigPath,
+  resolveContractLockPath: resolveBuildchainContractLockPath,
+  resolveKfd3SurfaceRegistryPath,
+  resolveReleasePassportPath,
+});

package/packages/core/kfd3-surface-register.js

@@ -1,12 +1,13 @@
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
+import { resolveKfd3SurfaceRegistryPath } from "./buildchain-layout.js";
 
 export const KFD3_SURFACE_REGISTRY_CONTRACT = "kungfu-buildchain-kfd-3-surface-registry";
 export const KFD3_SURFACE_DETECTION_CONTRACT = "kungfu-buildchain-kfd-3-surface-detection";
 export const KFD3_SURFACE_AUDIT_CONTRACT = "kungfu-buildchain-kfd-3-surface-audit";
 export const KFD3_CAPABILITY_QUERY_CONTRACT = "kungfu-buildchain-kfd-3-capability-query";
-export const KFD3_DEFAULT_REGISTRY_PATH = "buildchain.kfd3.json";
+export const KFD3_DEFAULT_REGISTRY_PATH = ".buildchain/kfd/kfd-3-surfaces.json";
 
 const KIND_ALIASES = Object.freeze({
   "node-api": "node-api",
@@ -343,15 +344,20 @@ export function detectKfd3Surfaces({ cwd = process.cwd(), kinds = [], artifactPa
   };
 }
 
-export function readKfd3SurfaceRegistry({ cwd = process.cwd(), registryPath = KFD3_DEFAULT_REGISTRY_PATH } = {}) {
-  const filePath = path.resolve(cwd, registryPath);
+function resolveRegistryPath(cwd, registryPath) {
+  return registryPath || resolveKfd3SurfaceRegistryPath(cwd);
+}
+
+export function readKfd3SurfaceRegistry({ cwd = process.cwd(), registryPath = "" } = {}) {
+  const effectiveRegistryPath = resolveRegistryPath(cwd, registryPath);
+  const filePath = path.resolve(cwd, effectiveRegistryPath);
   const registry = readJsonFile(filePath, null);
   if (!registry) {
     return {
       schemaVersion: 1,
       contract: KFD3_SURFACE_REGISTRY_CONTRACT,
       product: {},
-      registryPath,
+      registryPath: effectiveRegistryPath,
       surfaces: [],
     };
   }
@@ -359,24 +365,25 @@ export function readKfd3SurfaceRegistry({ cwd = process.cwd(), registryPath = KF
     schemaVersion: registry.schemaVersion || 1,
     contract: registry.contract || KFD3_SURFACE_REGISTRY_CONTRACT,
     product: registry.product || {},
-    registryPath,
+    registryPath: registry.registryPath || effectiveRegistryPath,
     surfaces: Array.isArray(registry.surfaces) ? registry.surfaces : [],
     policy: registry.policy || {},
   };
 }
 
-export function writeKfd3SurfaceRegistry({ cwd = process.cwd(), registryPath = KFD3_DEFAULT_REGISTRY_PATH, registry }) {
+export function writeKfd3SurfaceRegistry({ cwd = process.cwd(), registryPath = "", registry }) {
+  const effectiveRegistryPath = resolveRegistryPath(cwd, registryPath);
   const next = {
     schemaVersion: 1,
     contract: KFD3_SURFACE_REGISTRY_CONTRACT,
     product: registry.product || {},
-    registryPath,
+    registryPath: effectiveRegistryPath,
     surfaces: uniqueSurfaces(registry.surfaces || []).map((entry) => ({
       ...entry,
       state: entry.state || "declared",
       declaration: entry.declaration || {
         owner: "product",
-        source: "buildchain kfd-3 register",
+        source: "buildchain kfd 3 register",
       },
     })),
     policy: registry.policy || {
@@ -384,13 +391,13 @@ export function writeKfd3SurfaceRegistry({ cwd = process.cwd(), registryPath = K
       declaredButMissing: "fail",
     },
   };
-  writeJsonFile(path.resolve(cwd, registryPath), next);
+  writeJsonFile(path.resolve(cwd, effectiveRegistryPath), next);
   return next;
 }
 
 export function registerKfd3Surfaces({
   cwd = process.cwd(),
-  registryPath = KFD3_DEFAULT_REGISTRY_PATH,
+  registryPath = "",
   kinds = [],
   artifactPath = "",
   product = {},
@@ -435,7 +442,7 @@ export function registerKfd3Surfaces({
 
 export function auditKfd3Surfaces({
   cwd = process.cwd(),
-  registryPath = KFD3_DEFAULT_REGISTRY_PATH,
+  registryPath = "",
   kinds = [],
   artifactPath = "",
 } = {}) {
@@ -490,7 +497,7 @@ export function auditKfd3Surfaces({
 
 export function createKfd3SurfaceWitness({
   cwd = process.cwd(),
-  registryPath = KFD3_DEFAULT_REGISTRY_PATH,
+  registryPath = "",
   kind = "prebuild",
   sourceSha = "",
   artifactPath = "",
@@ -613,7 +620,7 @@ function capabilitiesFromRegistry({ registry, audit, passport = null }) {
 export async function queryKfd3Capabilities({
   cwd = process.cwd(),
   product = "",
-  registryPath = KFD3_DEFAULT_REGISTRY_PATH,
+  registryPath = "",
   passportLocation = "",
   artifactPath = "",
 } = {}) {
@@ -649,15 +656,16 @@ export async function queryKfd3Capabilities({
     };
   }
 
-  const registry = readKfd3SurfaceRegistry({ cwd, registryPath });
-  const hasRegistry = fs.existsSync(path.resolve(cwd, registryPath));
-  const audit = hasRegistry ? auditKfd3Surfaces({ cwd, registryPath, artifactPath }) : null;
+  const effectiveRegistryPath = resolveRegistryPath(cwd, registryPath);
+  const registry = readKfd3SurfaceRegistry({ cwd, registryPath: effectiveRegistryPath });
+  const hasRegistry = fs.existsSync(path.resolve(cwd, effectiveRegistryPath));
+  const audit = hasRegistry ? auditKfd3Surfaces({ cwd, registryPath: effectiveRegistryPath, artifactPath }) : null;
   if (hasRegistry) {
     return {
       schemaVersion: 1,
       contract: KFD3_CAPABILITY_QUERY_CONTRACT,
       product: product || registry.product?.name || registry.product?.id || "local-product",
-      source: { type: "surface-registry", path: registryPath },
+      source: { type: "surface-registry", path: effectiveRegistryPath },
       status: audit.status,
       summary: audit.summary,
       capabilities: capabilitiesFromRegistry({ registry, audit }),