@kungfu-tech/buildchain 2.10.11 → 2.11.0

package/docs/publication-artifacts.md

@@ -27,6 +27,7 @@ name = "paper-observer-declared-timelines"
 [publication]
 kind = "paper"
 title = "Observer-Declared Timelines for Real-World Agent Work"
+version = "0.1.0"
 primary_artifact = "_build/main.pdf"
 artifact_paths = ["_build/main.pdf"]
 metadata_paths = ["README.md", "docs/MAP.md"]
@@ -35,6 +36,14 @@ site_consumers = ["papers.libkungfu.dev"]
 manifest_path = ".buildchain/publication/publication-artifact.json"
 source_bundle_path = ".buildchain/publication/source.tar.gz"
 
+[publication.archive]
+id = "observer-declared-timelines"
+canonical_url = "https://papers.libkungfu.dev/observer-declared-timelines/"
+latest_url = "https://papers.libkungfu.dev/observer-declared-timelines/latest/"
+latest_evidence_url = "https://papers.libkungfu.dev/observer-declared-timelines/latest/buildchain.release.json"
+immutable_base_url = "https://papers.libkungfu.dev/archive"
+registry_path = ".buildchain/publication/publication-registry.json"
+
 [publication.toolchain]
 type = "latex-docker"
 image = "ghcr.io/kungfu-systems/latex"
@@ -52,6 +61,26 @@ command = "make check"
 `source_paths` are archived into a source bundle. `metadata_paths` are hashed
 and recorded so a site can consume the paper facts without scraping prose.
 
+`publication.archive` turns the publication into an append-only public archive
+contract:
+
+- `canonical_url` is the stable human reader page.
+- `latest_url` and `latest_evidence_url` are movable aliases for the latest
+  reader page and latest evidence.
+- `immutable_base_url` plus `id` and `publication.version` produce a versioned
+  prefix such as
+  `https://papers.libkungfu.dev/archive/observer-declared-timelines/v0.1.0/`.
+- `immutable_url_prefix` can be used instead when the repository already owns
+  the full version prefix.
+- `registry_path` records every published version and its manifest, passport,
+  source bundle, primary artifact, URLs, and SHA-256 digests.
+
+Immutable archive prefixes are append-only. Do not run site deployment commands
+with `sync --delete` or equivalent deletion semantics over those prefixes. A
+same-version republish is allowed only when the immutable digest is unchanged;
+if PDF, source bundle, route, metadata, or toolchain evidence changes for an
+existing version, Buildchain fails before the registry is rewritten.
+
 `publication.toolchain` makes the source-to-PDF transformation part of the
 machine-readable contract. `latex-docker` is the preferred LaTeX profile: the
 workflow pulls the declared image by digest and runs the declared command in
@@ -88,8 +117,11 @@ The workflow:
 - creates a source bundle from `publication.source_paths`;
 - writes `.buildchain/publication/publication-artifact.json`;
 - writes `.buildchain/publication/publication-artifact-passport.json`;
-- uploads one GitHub artifact containing the PDF, manifest, passport, and
-  source bundle.
+- when `[publication.archive]` is configured, writes
+  `.buildchain/publication/publication-registry.json` and verifies same-version
+  immutability;
+- uploads one GitHub artifact containing the PDF, manifest, passport, optional
+  registry, and source bundle.
 
 The wrapper is build-only. It does not publish npm packages, deploy web pages,
 or create GitHub Releases. Release publication can be layered later by a
@@ -123,12 +155,19 @@ the reusable workflow. The generated manifest records:
 - publication toolchain type, image, digest, command, invocation mode, and trust
   classification;
 - timestamp and reproducibility policy;
-- downstream site-consumption hints.
+- downstream site-consumption hints;
+- optional archive routes for canonical, latest, latest evidence, immutable
+  version prefix, and public artifact URLs.
 
 The companion publication artifact passport records the same source and
 artifact evidence plus an explicit responsibility split. Buildchain proves
 declared files and hashes; it does not peer-review paper claims.
 
+When archive config is present, the registry uses the
+`kungfu-buildchain-publication-artifact-registry` contract. A site repository
+can render latest pages and historical version indexes from that registry
+without rebuilding old PDFs from the latest npm package or paper source.
+
 ## Site Consumption
 
 A downstream papers site should treat the publication manifest as the single
@@ -139,7 +178,9 @@ For `paper-observer-declared-timelines`, the expected adoption path is:
 
 ```text
 paper repo builds PDF + manifest + source bundle
+paper repo updates publication-registry.json
 papers site consumes publication-artifact.json
+papers site consumes publication-registry.json for history
 site renders paper page and links the PDF/source bundle
 ```
 

package/docs/release-propagation.md

@@ -85,6 +85,53 @@ The upstream release envelope is the post-finalization fact set:
 The package version and integrity must be exact. Downstream build logic should
 install that version directly, not resolve `alpha` or `latest` again.
 
+Publication repositories can propagate immutable publication archive evidence
+without npm package facts. The upstream envelope then includes
+`publicationArtifact`:
+
+```json
+{
+  "repository": "kungfu-systems/paper-observer-declared-timelines",
+  "channel": "alpha",
+  "tag": "v0.1.0-alpha.1",
+  "sourceSha": "4444444444444444444444444444444444444444",
+  "releasePassport": {
+    "url": "https://github.com/kungfu-systems/paper-observer-declared-timelines/releases/download/v0.1.0-alpha.1/buildchain.release.json",
+    "sha256": "5555555555555555555555555555555555555555555555555555555555555555"
+  },
+  "publicationArtifact": {
+    "id": "observer-declared-timelines",
+    "kind": "paper",
+    "version": "0.1.0-alpha.1",
+    "canonicalUrl": "https://papers.libkungfu.dev/observer-declared-timelines/",
+    "latestUrl": "https://papers.libkungfu.dev/observer-declared-timelines/latest/",
+    "latestEvidenceUrl": "https://papers.libkungfu.dev/observer-declared-timelines/latest/buildchain.release.json",
+    "immutableVersionUrl": "https://papers.libkungfu.dev/archive/observer-declared-timelines/v0.1.0-alpha.1/",
+    "registry": {
+      "url": "https://github.com/kungfu-systems/paper-observer-declared-timelines/releases/download/v0.1.0-alpha.1/publication-registry.json",
+      "sha256": "6666666666666666666666666666666666666666666666666666666666666666"
+    },
+    "manifest": {
+      "url": "https://github.com/kungfu-systems/paper-observer-declared-timelines/releases/download/v0.1.0-alpha.1/publication-artifact.json",
+      "sha256": "7777777777777777777777777777777777777777777777777777777777777777"
+    },
+    "passport": {
+      "url": "https://github.com/kungfu-systems/paper-observer-declared-timelines/releases/download/v0.1.0-alpha.1/publication-artifact-passport.json",
+      "sha256": "8888888888888888888888888888888888888888888888888888888888888888"
+    },
+    "primaryArtifact": {
+      "path": "_build/main.pdf",
+      "url": "https://papers.libkungfu.dev/archive/observer-declared-timelines/v0.1.0-alpha.1/main.pdf",
+      "sha256": "9999999999999999999999999999999999999999999999999999999999999999"
+    }
+  }
+}
+```
+
+This lets a site repository render the latest reader page and historical
+version index from release facts while keeping old PDFs, source bundles,
+manifests, and passports immutable.
+
 ## CLI
 
 Generate a propagation plan:
@@ -111,7 +158,9 @@ The written lock has contract
 `kungfu-buildchain-release-propagation-lock` and records:
 
 - upstream repository, channel, exact tag, source SHA;
-- npm package name, exact version, and sha512 integrity;
+- optional npm package name, exact version, and sha512 integrity;
+- optional publication artifact canonical/latest/immutable URLs, registry,
+  manifest, passport, source bundle, and primary artifact digests;
 - release passport URL and SHA-256;
 - optional site bundle manifest SHA-256;
 - downstream repository, channel, base ref, lock path;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "2.10.11",
+  "version": "2.11.0",
   "private": false,
   "description": "Buildchain Release Passport, release governance, CLI toolkit, and site facts.",
   "repository": "https://github.com/kungfu-systems/buildchain",

package/packages/core/README.md

@@ -67,7 +67,9 @@ writeBuildFacts({ fact, output: ".buildchain/facts/native-core.json" });
 ```
 
 Publication repositories can produce site-consumable paper/report facts without
-becoming web-surface repositories:
+becoming web-surface repositories. When `[publication.archive]` is configured,
+the same API also maintains the append-only publication registry used by site
+repositories for latest and historical version pages:
 
 ```js
 import { writePublicationArtifact } from "@kungfu-tech/buildchain/publication-artifact";

package/packages/core/buildchain-config.js

@@ -397,6 +397,41 @@ function normalizePublicationSection(publication) {
     sourceBundlePath: publication.source_bundle_path === undefined
       ? ".buildchain/publication/source.tar.gz"
       : posixPath(assertString(publication.source_bundle_path, "publication.source_bundle_path")),
+    archive: normalizePublicationArchive(publication.archive),
+  };
+}
+
+function normalizePublicationArchive(archive = undefined) {
+  if (archive === undefined) {
+    return undefined;
+  }
+  assertPlainObject(archive, "publication.archive");
+  const immutableUrlPrefix = archive.immutable_url_prefix === undefined
+    ? ""
+    : assertString(archive.immutable_url_prefix, "publication.archive.immutable_url_prefix");
+  const immutableBaseUrl = archive.immutable_base_url === undefined
+    ? ""
+    : assertString(archive.immutable_base_url, "publication.archive.immutable_base_url");
+  if (!immutableUrlPrefix && !immutableBaseUrl) {
+    throw new Error("publication.archive requires immutable_url_prefix or immutable_base_url");
+  }
+  return {
+    id: archive.id === undefined ? "" : assertString(archive.id, "publication.archive.id"),
+    canonicalUrl: assertString(archive.canonical_url, "publication.archive.canonical_url"),
+    latestUrl: archive.latest_url === undefined
+      ? ""
+      : assertString(archive.latest_url, "publication.archive.latest_url"),
+    latestEvidenceUrl: archive.latest_evidence_url === undefined
+      ? ""
+      : assertString(archive.latest_evidence_url, "publication.archive.latest_evidence_url"),
+    immutableBaseUrl,
+    immutableUrlPrefix,
+    artifactUrlPrefix: archive.artifact_url_prefix === undefined
+      ? ""
+      : assertString(archive.artifact_url_prefix, "publication.archive.artifact_url_prefix"),
+    registryPath: archive.registry_path === undefined
+      ? ".buildchain/publication/publication-registry.json"
+      : posixPath(assertString(archive.registry_path, "publication.archive.registry_path")),
   };
 }
 

package/packages/core/index.js

@@ -186,8 +186,10 @@ export {
 } from "./public-surface-audit.js";
 
 export {
+  PUBLICATION_ARTIFACT_ARCHIVE_CONTRACT,
   PUBLICATION_ARTIFACT_MANIFEST_CONTRACT,
   PUBLICATION_ARTIFACT_PASSPORT_CONTRACT,
+  PUBLICATION_ARTIFACT_REGISTRY_CONTRACT,
   collectPublicationArtifact,
   createPublicationSourceBundle,
   writePublicationArtifact,

package/packages/core/publication-artifact.js

@@ -6,6 +6,8 @@ import { loadBuildchainConfig } from "./buildchain-config.js";
 
 export const PUBLICATION_ARTIFACT_MANIFEST_CONTRACT = "kungfu-buildchain-publication-artifact-manifest";
 export const PUBLICATION_ARTIFACT_PASSPORT_CONTRACT = "kungfu-buildchain-publication-artifact-passport";
+export const PUBLICATION_ARTIFACT_ARCHIVE_CONTRACT = "kungfu-buildchain-publication-artifact-archive";
+export const PUBLICATION_ARTIFACT_REGISTRY_CONTRACT = "kungfu-buildchain-publication-artifact-registry";
 const KFD2_RESIDUAL_RISK_SCHEMA = "https://kfd.libkungfu.dev/schemas/kfd-2/trust-taxonomy.schema.json#/$defs/residualRisk";
 
 function toPosix(value) {
@@ -20,6 +22,28 @@ function sha256FilePath(filePath) {
   return sha256Buffer(fs.readFileSync(filePath));
 }
 
+function sortJson(value) {
+  if (Array.isArray(value)) {
+    return value.map(sortJson);
+  }
+  if (!value || typeof value !== "object") {
+    return value;
+  }
+  return Object.fromEntries(
+    Object.entries(value)
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([key, entry]) => [key, sortJson(entry)]),
+  );
+}
+
+function stableJson(value) {
+  return `${JSON.stringify(sortJson(value), null, 2)}\n`;
+}
+
+function sha256Json(value) {
+  return sha256Buffer(Buffer.from(stableJson(value)));
+}
+
 function repoRelative(cwd, filePath) {
   const relative = path.relative(cwd, filePath);
   return relative && !relative.startsWith("..") && !path.isAbsolute(relative)
@@ -75,6 +99,29 @@ function createdAt(now = new Date()) {
   return now.toISOString();
 }
 
+function ensureTrailingSlash(value) {
+  const text = String(value || "").trim();
+  return text.endsWith("/") ? text : `${text}/`;
+}
+
+function joinUrl(prefix, ...segments) {
+  const base = ensureTrailingSlash(prefix);
+  const suffix = segments
+    .filter(Boolean)
+    .map((segment) => String(segment).replace(/^\/+/, "").replace(/\\/g, "/"))
+    .join("/");
+  return suffix ? `${base}${suffix}` : base;
+}
+
+function versionLabel(version) {
+  const text = String(version || "").trim();
+  return text.startsWith("v") ? text : `v${text}`;
+}
+
+function archiveFileUrl(prefix, relPath) {
+  return joinUrl(prefix, path.posix.basename(toPosix(relPath)));
+}
+
 function publicationToolchainFacts(publication) {
   const envType = String(process.env.BUILDCHAIN_PUBLICATION_TOOLCHAIN_TYPE || "").trim();
   const envToolchain = envType
@@ -138,6 +185,67 @@ function publicationResidualRisk(toolchainFacts) {
   return risks;
 }
 
+function publicationArchiveFacts({ loaded, publication, manifestPath, passportPath, artifacts, bundle }) {
+  if (!publication.archive) {
+    return undefined;
+  }
+  const version = String(publication.version || "").trim();
+  if (!version) {
+    throw new Error("publication.archive requires publication.version");
+  }
+  const archive = publication.archive;
+  const id = archive.id || loaded.config.project?.name || "publication";
+  const immutableVersionPrefix = archive.immutableUrlPrefix
+    ? ensureTrailingSlash(archive.immutableUrlPrefix)
+    : ensureTrailingSlash(joinUrl(archive.immutableBaseUrl, id, versionLabel(version)));
+  const artifactUrlPrefix = archive.artifactUrlPrefix
+    ? ensureTrailingSlash(archive.artifactUrlPrefix)
+    : immutableVersionPrefix;
+  return {
+    contract: PUBLICATION_ARTIFACT_ARCHIVE_CONTRACT,
+    id,
+    version,
+    appendOnly: true,
+    sameVersionRepublish: "fail-on-digest-change",
+    immutablePathPolicy: "do-not-sync-delete-immutable-prefixes",
+    routes: {
+      canonicalUrl: archive.canonicalUrl,
+      latestUrl: archive.latestUrl || archive.canonicalUrl,
+      latestEvidenceUrl: archive.latestEvidenceUrl,
+      immutableVersionPrefix,
+      immutableVersionUrl: immutableVersionPrefix,
+      artifactUrlPrefix,
+    },
+    registry: {
+      contract: PUBLICATION_ARTIFACT_REGISTRY_CONTRACT,
+      path: archive.registryPath,
+    },
+    publicArtifacts: {
+      manifest: {
+        path: toPosix(manifestPath),
+        url: archiveFileUrl(artifactUrlPrefix, manifestPath),
+      },
+      passport: {
+        path: toPosix(passportPath),
+        url: archiveFileUrl(artifactUrlPrefix, passportPath),
+      },
+      sourceBundle: bundle
+        ? {
+            path: bundle.path,
+            url: archiveFileUrl(artifactUrlPrefix, bundle.path),
+            sha256: bundle.sha256,
+            bytes: bundle.bytes,
+          }
+        : undefined,
+      artifacts: artifacts.map((artifact) => ({
+        ...artifact,
+        role: artifact.path === publication.primaryArtifact ? "primary" : "attachment",
+        url: archiveFileUrl(artifactUrlPrefix, artifact.path),
+      })),
+    },
+  };
+}
+
 export function createPublicationSourceBundle({
   cwd = process.cwd(),
   sourcePaths = [],
@@ -166,6 +274,8 @@ export function collectPublicationArtifact({
   sourceBundle = true,
   sourceBundlePath = "",
   generatedAt = "",
+  manifestPath = "",
+  passportPath = "",
 } = {}) {
   const loaded = loadBuildchainConfig(cwd);
   if (!loaded?.config?.publication) {
@@ -195,6 +305,16 @@ export function collectPublicationArtifact({
   const sourceTreeSha = gitValue(cwd, ["rev-parse", `${resolvedSourceSha}^{tree}`]);
   const timestamp = generatedAt || createdAt();
   const toolchain = publicationToolchainFacts(publication);
+  const resolvedManifestPath = manifestPath || publication.manifestPath;
+  const resolvedPassportPath = passportPath || ".buildchain/publication/publication-artifact-passport.json";
+  const archive = publicationArchiveFacts({
+    loaded,
+    publication,
+    manifestPath: resolvedManifestPath,
+    passportPath: resolvedPassportPath,
+    artifacts,
+    bundle,
+  });
   const manifest = {
     schemaVersion: 1,
     contract: PUBLICATION_ARTIFACT_MANIFEST_CONTRACT,
@@ -210,6 +330,7 @@ export function collectPublicationArtifact({
       authors: publication.authors,
       primaryArtifact: publication.primaryArtifact,
       siteConsumers: publication.siteConsumers,
+      archive,
     },
     toolchain,
     source: {
@@ -241,16 +362,38 @@ export function collectPublicationArtifact({
       artifactDigestScope: "publication artifact digests cover files and source bundle, not manifest timestamps",
     },
   };
+  const manifestDigest = `sha256:${sha256Buffer(Buffer.from(JSON.stringify(manifest, null, 2)))}`;
   return {
     manifest,
     passport: {
       schemaVersion: 1,
       contract: PUBLICATION_ARTIFACT_PASSPORT_CONTRACT,
       status: "passed",
-      manifestDigest: `sha256:${sha256Buffer(Buffer.from(JSON.stringify(manifest, null, 2)))}`,
+      manifestDigest,
       source: manifest.source,
       toolchain,
       artifacts: manifest.artifacts,
+      publicationArchive: archive
+        ? {
+            contract: archive.contract,
+            id: archive.id,
+            version: archive.version,
+            routes: archive.routes,
+            registry: archive.registry,
+            publicArtifacts: {
+              manifest: {
+                ...archive.publicArtifacts.manifest,
+                sha256: manifestDigest.replace(/^sha256:/, ""),
+              },
+              passport: archive.publicArtifacts.passport,
+              sourceBundle: archive.publicArtifacts.sourceBundle,
+              artifacts: archive.publicArtifacts.artifacts,
+            },
+            appendOnly: archive.appendOnly,
+            sameVersionRepublish: archive.sameVersionRepublish,
+            immutablePathPolicy: archive.immutablePathPolicy,
+          }
+        : undefined,
       responsibility: {
         producer: "publication repository",
         renderer: "site repository",
@@ -277,31 +420,179 @@ export function collectPublicationArtifact({
   };
 }
 
+function publicationArchiveRecord({ collected, manifestPath, passportPath, registryPath, generatedAt }) {
+  const archive = collected.manifest.publication.archive;
+  if (!archive) {
+    return undefined;
+  }
+  const manifestDigest = sha256FilePath(manifestPath);
+  const passportDigest = sha256FilePath(passportPath);
+  const immutableEvidence = {
+    version: archive.version,
+    source: {
+      sha: collected.manifest.source.sha,
+      treeSha: collected.manifest.source.treeSha,
+      sourceBundle: archive.publicArtifacts.sourceBundle,
+    },
+    routes: archive.routes,
+    artifacts: archive.publicArtifacts.artifacts.map((artifact) => ({
+      path: artifact.path,
+      role: artifact.role,
+      url: artifact.url,
+      bytes: artifact.bytes,
+      sha256: artifact.sha256,
+    })),
+    metadata: collected.manifest.metadata,
+    toolchain: collected.manifest.toolchain,
+  };
+  const immutableDigest = sha256Json(immutableEvidence);
+  const record = {
+    version: archive.version,
+    status: "published",
+    publishedAt: generatedAt || collected.manifest.publishedAt,
+    immutableDigest: `sha256:${immutableDigest}`,
+    source: {
+      repository: collected.manifest.source.repository,
+      sha: collected.manifest.source.sha,
+      treeSha: collected.manifest.source.treeSha,
+      sourceBundle: archive.publicArtifacts.sourceBundle,
+    },
+    routes: archive.routes,
+    artifacts: archive.publicArtifacts.artifacts,
+    metadata: collected.manifest.metadata,
+    manifest: {
+      ...archive.publicArtifacts.manifest,
+      sha256: manifestDigest,
+    },
+    passport: {
+      ...archive.publicArtifacts.passport,
+      sha256: passportDigest,
+    },
+    immutableEvidenceSha256: immutableDigest,
+  };
+  record.recordSha256 = sha256Json({ ...record, recordSha256: undefined });
+  return {
+    registryPath: archive.registry.path || registryPath,
+    record,
+  };
+}
+
+function updatePublicationArchiveRegistry({ cwd, collected, manifestPath, passportPath, registryOutput, generatedAt }) {
+  const archive = collected.manifest.publication.archive;
+  if (!archive) {
+    return undefined;
+  }
+  const registryPath = path.resolve(cwd, registryOutput || archive.registry.path);
+  const { record } = publicationArchiveRecord({
+    collected,
+    manifestPath,
+    passportPath,
+    registryPath,
+    generatedAt,
+  });
+  let registry = {
+    schemaVersion: 1,
+    contract: PUBLICATION_ARTIFACT_REGISTRY_CONTRACT,
+    publication: {
+      id: archive.id,
+      kind: collected.manifest.publication.kind,
+      title: collected.manifest.publication.title,
+      canonicalUrl: archive.routes.canonicalUrl,
+      latestUrl: archive.routes.latestUrl,
+      latestEvidenceUrl: archive.routes.latestEvidenceUrl,
+      siteConsumers: collected.manifest.publication.siteConsumers,
+    },
+    appendOnly: true,
+    sameVersionRepublish: "fail-on-digest-change",
+    immutablePathPolicy: archive.immutablePathPolicy,
+    versions: [],
+  };
+  if (fs.existsSync(registryPath)) {
+    registry = JSON.parse(fs.readFileSync(registryPath, "utf8"));
+    if (registry.contract !== PUBLICATION_ARTIFACT_REGISTRY_CONTRACT) {
+      throw new Error(`publication archive registry has unsupported contract: ${registry.contract || "(missing)"}`);
+    }
+  }
+  const versions = Array.isArray(registry.versions) ? registry.versions : [];
+  const existingIndex = versions.findIndex((entry) => entry.version === record.version);
+  if (existingIndex !== -1) {
+    const existing = versions[existingIndex];
+    if (existing.immutableDigest !== record.immutableDigest) {
+      throw new Error(
+        `publication archive version ${record.version} is immutable: existing digest ${existing.immutableDigest}, new digest ${record.immutableDigest}`,
+      );
+    }
+    versions[existingIndex] = {
+      ...existing,
+      latestObservedAt: generatedAt || collected.manifest.publishedAt,
+    };
+  } else {
+    versions.push(record);
+  }
+  registry = {
+    ...registry,
+    publication: {
+      ...registry.publication,
+      id: archive.id,
+      kind: collected.manifest.publication.kind,
+      title: collected.manifest.publication.title,
+      canonicalUrl: archive.routes.canonicalUrl,
+      latestUrl: archive.routes.latestUrl,
+      latestEvidenceUrl: archive.routes.latestEvidenceUrl,
+      siteConsumers: collected.manifest.publication.siteConsumers,
+    },
+    versions: versions.sort((left, right) => left.version.localeCompare(right.version)),
+  };
+  registry.registrySha256 = sha256Json({ ...registry, registrySha256: undefined });
+  fs.mkdirSync(path.dirname(registryPath), { recursive: true });
+  fs.writeFileSync(registryPath, stableJson(registry));
+  return {
+    path: toPosix(path.relative(cwd, registryPath)),
+    sha256: sha256FilePath(registryPath),
+    record,
+    registry,
+  };
+}
+
 export function writePublicationArtifact({
   cwd = process.cwd(),
   output = "",
   passportOutput = "",
+  registryOutput = "",
   sourceSha = "",
   sourceBundle = true,
   sourceBundlePath = "",
   generatedAt = "",
 } = {}) {
+  const loaded = loadBuildchainConfig(cwd);
+  const manifestOutput = output || loaded.config.publication.manifestPath;
+  const passportPath = passportOutput || ".buildchain/publication/publication-artifact-passport.json";
   const collected = collectPublicationArtifact({
     cwd,
     sourceSha,
     sourceBundle,
     sourceBundlePath,
     generatedAt,
+    manifestPath: manifestOutput,
+    passportPath,
   });
-  const manifestOutput = output || loadBuildchainConfig(cwd).config.publication.manifestPath;
-  const passportPath = passportOutput || ".buildchain/publication/publication-artifact-passport.json";
   fs.mkdirSync(path.dirname(path.resolve(cwd, manifestOutput)), { recursive: true });
   fs.mkdirSync(path.dirname(path.resolve(cwd, passportPath)), { recursive: true });
   fs.writeFileSync(path.resolve(cwd, manifestOutput), `${JSON.stringify(collected.manifest, null, 2)}\n`);
   fs.writeFileSync(path.resolve(cwd, passportPath), `${JSON.stringify(collected.passport, null, 2)}\n`);
+  const registry = updatePublicationArchiveRegistry({
+    cwd,
+    collected,
+    manifestPath: path.resolve(cwd, manifestOutput),
+    passportPath: path.resolve(cwd, passportPath),
+    registryOutput,
+    generatedAt,
+  });
   return {
     ...collected,
     manifestPath: toPosix(manifestOutput),
     passportPath: toPosix(passportPath),
+    registryPath: registry?.path,
+    registry,
   };
 }