@tokenoftrust/storefront-runner 2.0.16 → 2.0.18

package/packages/public-runtime/src/integration/managed-analytics-api-v1.schemas.ts

@@ -286,6 +286,32 @@ const SET_INTEGRATION_INSTALL_STATUS_BODY_SCHEMA = {
 const DELETE_INTEGRATION_INSTALL_BODY_SCHEMA = {
   type: "object", additionalProperties: false, required: ["installId"], properties: { installId: PUBLIC_IDENTIFIER },
 } as const;
+const TEST_DESTINATION_ENVIRONMENT = { type: "string", enum: ["local", "candidate", "staged"] } as const;
+const APPROVED_MARKETING_ACTION_NAME = {
+  type: "string",
+  enum: [
+    "user_clicked_contact_sales_mktg",
+    "user_clicked_create_account_mktg",
+    "user_clicked_login_mktg",
+    "user_clicked_contact_support_consumer_mktg",
+    "user_clicked_contact_support_partner_mktg",
+  ],
+} as const;
+const REGISTER_TEST_DESTINATION_BODY_SCHEMA = {
+  type: "object", additionalProperties: false,
+  required: ["destinationId", "environment"],
+  properties: { destinationId: PUBLIC_IDENTIFIER, environment: TEST_DESTINATION_ENVIRONMENT },
+} as const;
+const DELIVER_TEST_EVENT_BODY_SCHEMA = {
+  type: "object", additionalProperties: false,
+  required: ["destinationId", "eventId", "actionName"],
+  properties: { destinationId: PUBLIC_IDENTIFIER, eventId: PUBLIC_IDENTIFIER, actionName: APPROVED_MARKETING_ACTION_NAME },
+} as const;
+const TEST_DESTINATION_DELIVERY_QUERY_SCHEMA = {
+  type: "object", additionalProperties: false,
+  required: ["destinationId", "eventId"],
+  properties: { destinationId: PUBLIC_IDENTIFIER, eventId: PUBLIC_IDENTIFIER },
+} as const;
 
 export const CREATE_MIGRATION_DRAFT_REQUEST_V1_JSON_SCHEMA = mutationOperationSchema("CreateMigrationDraftRequest", "create-migration-draft-request.schema.json", CREATE_MIGRATION_DRAFT_BODY_SCHEMA);
 export const UPDATE_MIGRATION_DRAFT_REQUEST_V1_JSON_SCHEMA = mutationOperationSchema("UpdateMigrationDraftRequest", "update-migration-draft-request.schema.json", UPDATE_MIGRATION_DRAFT_BODY_SCHEMA);
@@ -294,6 +320,40 @@ export const CREATE_INTEGRATION_INSTALL_REQUEST_V1_JSON_SCHEMA = mutationOperati
 export const REVISE_INTEGRATION_INSTALL_REQUEST_V1_JSON_SCHEMA = mutationOperationSchema("ReviseIntegrationInstallRequest", "revise-integration-install-request.schema.json", REVISE_INTEGRATION_INSTALL_BODY_SCHEMA);
 export const SET_INTEGRATION_INSTALL_STATUS_REQUEST_V1_JSON_SCHEMA = mutationOperationSchema("SetIntegrationInstallStatusRequest", "set-integration-install-status-request.schema.json", SET_INTEGRATION_INSTALL_STATUS_BODY_SCHEMA);
 export const DELETE_INTEGRATION_INSTALL_REQUEST_V1_JSON_SCHEMA = mutationOperationSchema("DeleteIntegrationInstallRequest", "delete-integration-install-request.schema.json", DELETE_INTEGRATION_INSTALL_BODY_SCHEMA);
+export const REGISTER_TEST_DESTINATION_REQUEST_V1_JSON_SCHEMA = mutationOperationSchema("RegisterTestDestinationRequest", "register-test-destination-request.schema.json", REGISTER_TEST_DESTINATION_BODY_SCHEMA);
+export const DELIVER_TEST_EVENT_REQUEST_V1_JSON_SCHEMA = mutationOperationSchema("DeliverTestEventRequest", "deliver-test-event-request.schema.json", DELIVER_TEST_EVENT_BODY_SCHEMA);
+export const GET_TEST_DESTINATION_DELIVERY_REQUEST_V1_JSON_SCHEMA = readOperationSchema("GetTestDestinationDeliveryRequest", "get-test-destination-delivery-request.schema.json", TEST_DESTINATION_DELIVERY_QUERY_SCHEMA);
+
+export const TEST_DESTINATION_V1_JSON_SCHEMA = {
+  $schema: DRAFT,
+  $id: `${BASE}/test-destination.schema.json`,
+  title: "TestDestinationV1",
+  type: "object",
+  additionalProperties: false,
+  required: ["schemaVersion", "destinationId", "environment", "createdAt"],
+  properties: {
+    schemaVersion: { type: "integer", const: 1 },
+    destinationId: PUBLIC_IDENTIFIER,
+    environment: TEST_DESTINATION_ENVIRONMENT,
+    createdAt: { ...SAFE_CONFIG_STRING, format: "date-time" },
+  },
+} as const;
+
+export const TEST_DESTINATION_DELIVERY_V1_JSON_SCHEMA = {
+  $schema: DRAFT,
+  $id: `${BASE}/test-destination-delivery.schema.json`,
+  title: "TestDestinationDeliveryV1",
+  type: "object",
+  additionalProperties: false,
+  required: ["schemaVersion", "destinationId", "eventId", "actionName", "deliveredAt"],
+  properties: {
+    schemaVersion: { type: "integer", const: 1 },
+    destinationId: PUBLIC_IDENTIFIER,
+    eventId: PUBLIC_IDENTIFIER,
+    actionName: APPROVED_MARKETING_ACTION_NAME,
+    deliveredAt: { ...SAFE_CONFIG_STRING, format: "date-time" },
+  },
+} as const;
 
 export const READ_SUCCESS_ENVELOPE_V1_JSON_SCHEMA = {
   $schema: DRAFT,
@@ -376,6 +436,11 @@ export const MANAGED_ANALYTICS_API_V1_JSON_SCHEMAS = Object.freeze({
   reviseIntegrationInstallRequest: REVISE_INTEGRATION_INSTALL_REQUEST_V1_JSON_SCHEMA,
   setIntegrationInstallStatusRequest: SET_INTEGRATION_INSTALL_STATUS_REQUEST_V1_JSON_SCHEMA,
   deleteIntegrationInstallRequest: DELETE_INTEGRATION_INSTALL_REQUEST_V1_JSON_SCHEMA,
+  registerTestDestinationRequest: REGISTER_TEST_DESTINATION_REQUEST_V1_JSON_SCHEMA,
+  deliverTestEventRequest: DELIVER_TEST_EVENT_REQUEST_V1_JSON_SCHEMA,
+  getTestDestinationDeliveryRequest: GET_TEST_DESTINATION_DELIVERY_REQUEST_V1_JSON_SCHEMA,
+  testDestination: TEST_DESTINATION_V1_JSON_SCHEMA,
+  testDestinationDelivery: TEST_DESTINATION_DELIVERY_V1_JSON_SCHEMA,
   readSuccessEnvelope: READ_SUCCESS_ENVELOPE_V1_JSON_SCHEMA,
   mutationSuccessEnvelope: MUTATION_SUCCESS_ENVELOPE_V1_JSON_SCHEMA,
   errorEnvelope: API_ERROR_ENVELOPE_V1_JSON_SCHEMA,

package/packages/public-runtime/src/integration/managed-analytics-api-v1.ts

@@ -10,6 +10,7 @@
 import type { ContractResult } from "./result.js";
 import { Violations, isPlainObject } from "./result.js";
 import { isForbiddenKey } from "./secrets.js";
+import { APPROVED_MARKETING_ACTION_NAMES } from "./events.js";
 import {
   MANAGED_ANALYTICS_PII_VALUE_PATTERN,
   MANAGED_ANALYTICS_SECRET_VALUE_PATTERN,
@@ -112,6 +113,37 @@ export interface MigrationDraftV1 {
   updatedAt: string;
 }
 
+/**
+ * A test destination is intentionally never `live`: it exists so a developer can
+ * prove exactly-once delivery for a new marketing action without touching a real
+ * vendor property. Real first-class adapters (GA4/Meta/Amplitude) fire directly to
+ * their vendor with no server-side readback; this destination is Storefront-owned,
+ * so a delivered event can be read back.
+ */
+export const TEST_DESTINATION_ENVIRONMENTS = ["local", "candidate", "staged"] as const;
+export type TestDestinationEnvironment = (typeof TEST_DESTINATION_ENVIRONMENTS)[number];
+
+export interface TestDestinationV1 {
+  schemaVersion: typeof MANAGED_ANALYTICS_SCHEMA_VERSION;
+  destinationId: OpaquePublicId;
+  environment: TestDestinationEnvironment;
+  createdAt: string;
+}
+
+/**
+ * One delivered event, read back by (destinationId, eventId). `actionName` is
+ * restricted to the program-approved v1 marketing action allowlist — the same
+ * set a tenant's action registry may enable — so this proves delivery for a real
+ * action, never an arbitrary caller-invented event shape.
+ */
+export interface TestDestinationDeliveryV1 {
+  schemaVersion: typeof MANAGED_ANALYTICS_SCHEMA_VERSION;
+  destinationId: OpaquePublicId;
+  eventId: OpaquePublicId;
+  actionName: OpaquePublicId;
+  deliveredAt: string;
+}
+
 export interface PageRequest {
   cursor?: OpaquePublicId;
   limit?: number;
@@ -261,6 +293,25 @@ export interface DeleteIntegrationInstallBody { installId: OpaquePublicId }
 export type DeleteIntegrationInstallRequest = MutationRequest<DeleteIntegrationInstallBody>;
 export type DeleteIntegrationInstallResponse = MutationResult<{ deleted: true }>;
 
+export interface RegisterTestDestinationBody {
+  destinationId: OpaquePublicId;
+  environment: TestDestinationEnvironment;
+}
+export type RegisterTestDestinationRequest = MutationRequest<RegisterTestDestinationBody>;
+export type RegisterTestDestinationResponse = MutationResult<{ destination: TestDestinationV1 }>;
+
+export interface DeliverTestEventBody {
+  destinationId: OpaquePublicId;
+  eventId: OpaquePublicId;
+  actionName: OpaquePublicId;
+}
+export type DeliverTestEventRequest = MutationRequest<DeliverTestEventBody>;
+/** `duplicate: true` when this eventId had already been delivered — the exactly-once proof. */
+export type DeliverTestEventResponse = MutationResult<{ delivery: TestDestinationDeliveryV1; duplicate: boolean }>;
+
+export type GetTestDestinationDeliveryRequest = ReadRequest<{ destinationId: OpaquePublicId; eventId: OpaquePublicId }>;
+export type GetTestDestinationDeliveryResponse = ApiResult<TestDestinationDeliveryV1>;
+
 /** The only backend seam WS2 needs; tests can mock this interface without HTTP. */
 export interface ManagedAnalyticsApiV1Client {
   listAdapterDefinitions(request: ListAdapterDefinitionsRequest): Promise<ListAdapterDefinitionsResponse>;
@@ -557,6 +608,26 @@ export function validateIntegrationRevisionV1(input: unknown): ContractResult<In
   return v.ok ? prepared : { ok: false, violations: v.items };
 }
 
+export function validateTestDestinationV1(input: unknown): ContractResult<TestDestinationV1> {
+  const prepared = snapshotManagedAnalyticsDeclarativeInput<TestDestinationV1>(input); if (!prepared.ok) return prepared;
+  const v = new Violations(); const obj = object(prepared.value, v, ""); if (!obj) return { ok: false, violations: v.items };
+  rejectKeys(obj, ["schemaVersion", "destinationId", "environment", "createdAt"], v, "");
+  literal(obj, "schemaVersion", 1, v, ""); opaqueId(obj, "destinationId", v, ""); enumeration(obj, "environment", TEST_DESTINATION_ENVIRONMENTS, v, ""); timestamp(obj, "createdAt", v, "");
+  const safe = validateManagedAnalyticsSafePayload(obj); if (!safe.ok) v.items.push(...safe.violations);
+  return v.ok ? prepared : { ok: false, violations: v.items };
+}
+
+export function validateTestDestinationDeliveryV1(input: unknown): ContractResult<TestDestinationDeliveryV1> {
+  const prepared = snapshotManagedAnalyticsDeclarativeInput<TestDestinationDeliveryV1>(input); if (!prepared.ok) return prepared;
+  const v = new Violations(); const obj = object(prepared.value, v, ""); if (!obj) return { ok: false, violations: v.items };
+  rejectKeys(obj, ["schemaVersion", "destinationId", "eventId", "actionName", "deliveredAt"], v, "");
+  literal(obj, "schemaVersion", 1, v, ""); opaqueId(obj, "destinationId", v, ""); opaqueId(obj, "eventId", v, "");
+  enumeration(obj, "actionName", APPROVED_MARKETING_ACTION_NAMES, v, "");
+  timestamp(obj, "deliveredAt", v, "");
+  const safe = validateManagedAnalyticsSafePayload(obj); if (!safe.ok) v.items.push(...safe.violations);
+  return v.ok ? prepared : { ok: false, violations: v.items };
+}
+
 export function validateMigrationDraftV1(input: unknown): ContractResult<MigrationDraftV1> {
   const prepared = snapshotManagedAnalyticsDeclarativeInput<MigrationDraftV1>(input); if (!prepared.ok) return prepared;
   const v = new Violations(); const obj = object(prepared.value, v, ""); if (!obj) return { ok: false, violations: v.items };
@@ -649,6 +720,13 @@ const validateSetIntegrationInstallStatusBody: ObjectShapeValidator = (obj, v, p
   rejectKeys(obj, ["installId", "status"], v, path); opaqueId(obj, "installId", v, path); enumeration(obj, "status", INTEGRATION_INSTALL_STATUSES, v, path);
 };
 const validateDeleteIntegrationInstallBody: ObjectShapeValidator = (obj, v, path) => { rejectKeys(obj, ["installId"], v, path); opaqueId(obj, "installId", v, path); };
+const validateRegisterTestDestinationBody: ObjectShapeValidator = (obj, v, path) => {
+  rejectKeys(obj, ["destinationId", "environment"], v, path); opaqueId(obj, "destinationId", v, path); enumeration(obj, "environment", TEST_DESTINATION_ENVIRONMENTS, v, path);
+};
+const validateDeliverTestEventBody: ObjectShapeValidator = (obj, v, path) => {
+  rejectKeys(obj, ["destinationId", "eventId", "actionName"], v, path); opaqueId(obj, "destinationId", v, path); opaqueId(obj, "eventId", v, path); enumeration(obj, "actionName", APPROVED_MARKETING_ACTION_NAMES, v, path);
+};
+const validateTestDestinationDeliveryQuery: ObjectShapeValidator = (obj, v, path) => { rejectKeys(obj, ["destinationId", "eventId"], v, path); opaqueId(obj, "destinationId", v, path); opaqueId(obj, "eventId", v, path); };
 
 export function validateCreateMigrationDraftRequest(input: unknown): ContractResult<CreateMigrationDraftRequest> { return validateMutationOperation(input, validateCreateMigrationDraftBody); }
 export function validateUpdateMigrationDraftRequest(input: unknown): ContractResult<UpdateMigrationDraftRequest> { return validateMutationOperation(input, validateUpdateMigrationDraftBody); }
@@ -657,6 +735,9 @@ export function validateCreateIntegrationInstallRequest(input: unknown): Contrac
 export function validateReviseIntegrationInstallRequest(input: unknown): ContractResult<ReviseIntegrationInstallRequest> { return validateMutationOperation(input, validateReviseIntegrationInstallBody); }
 export function validateSetIntegrationInstallStatusRequest(input: unknown): ContractResult<SetIntegrationInstallStatusRequest> { return validateMutationOperation(input, validateSetIntegrationInstallStatusBody); }
 export function validateDeleteIntegrationInstallRequest(input: unknown): ContractResult<DeleteIntegrationInstallRequest> { return validateMutationOperation(input, validateDeleteIntegrationInstallBody); }
+export function validateRegisterTestDestinationRequest(input: unknown): ContractResult<RegisterTestDestinationRequest> { return validateMutationOperation(input, validateRegisterTestDestinationBody); }
+export function validateDeliverTestEventRequest(input: unknown): ContractResult<DeliverTestEventRequest> { return validateMutationOperation(input, validateDeliverTestEventBody); }
+export function validateGetTestDestinationDeliveryRequest(input: unknown): ContractResult<GetTestDestinationDeliveryRequest> { return validateReadOperation(input, validateTestDestinationDeliveryQuery); }
 
 /** Validate the closed, public-safe error shape before it crosses the API boundary. */
 export function validateApiErrorEnvelope(input: unknown): ContractResult<ApiErrorEnvelope> {

package/packages/public-runtime/src/integration/render-phases.ts

@@ -36,7 +36,7 @@ import {
   renderBrowserEnvironmentScript,
   serializeForInlineScript,
 } from "./environment.js";
-import { defaultConsentSnapshot } from "./consent-broker.js";
+import { defaultConsentSnapshot, type ConsentSnapshot } from "./consent-broker.js";
 
 /**
  * The sentinel a renderer stamps in place of a live CSP nonce. It is a valid
@@ -138,11 +138,16 @@ export function phaseBoundary(phase: ReservedPhase): string {
  * splice regions both document mounts consume. `nonce` is the value stamped onto
  * the emitted inline scripts — pass {@link INTEGRATION_NONCE_PLACEHOLDER} so the
  * renderer can stamp a fresh nonce per response; an empty string omits the
- * attribute (for tests / mounts that stamp uniformly downstream).
+ * attribute (for tests / mounts that stamp uniformly downstream). `consentSnapshot`
+ * is the tenant's actual initial consent state — the snapshot the ext-policy-03
+ * broker computes from its {@link TenantConsentConfig}, seeded before any CMP/banner
+ * interaction; it defaults to {@link defaultConsentSnapshot} (essential-only, fail
+ * closed) for callers with no tenant consent config to resolve.
  */
 export function renderIntegrationPhases(
   plan: EffectivePlan,
   nonce: string = INTEGRATION_NONCE_PLACEHOLDER,
+  consentSnapshot: ConsentSnapshot = defaultConsentSnapshot(),
 ): IntegrationPhaseMarkup {
   assertRenderablePlan(plan);
 
@@ -150,7 +155,7 @@ export function renderIntegrationPhases(
     phaseBoundary("platform.environment") +
     renderBrowserEnvironmentScript(plan.environment, nonce) +
     phaseBoundary("consent.defaults") +
-    inlineFrozenGlobal(INTEGRATION_CONSENT_GLOBAL, defaultConsentSnapshot(), nonce) +
+    inlineFrozenGlobal(INTEGRATION_CONSENT_GLOBAL, consentSnapshot, nonce) +
     phaseBoundary("head.early") +
     inlineFrozenGlobal(INTEGRATION_PLAN_GLOBAL, bootDescriptor(plan), nonce);
 

package/packages/public-runtime/src/publication-artifact.ts

@@ -0,0 +1,203 @@
+import type { PublicationSpaceManifestV1 } from "./publication-space.js";
+import { sha256Hex } from "./hash.js";
+
+/** Renderer-safe description of one immutable publication artifact file. */
+export interface PublicationArtifactFileV1 {
+  lane: "content" | "public-asset" | "authorized-asset";
+  path: string;
+  encoding: "utf8" | "base64";
+  content: string;
+  byteSize: number;
+}
+
+/** Renderer-safe marker for one complete tenant+space+version artifact set. */
+export interface PublicationArtifactBundleV1 {
+  tenant: string;
+  spaceId: string;
+  versionId: string;
+  sourceSha: string;
+  artifactDigest: string;
+  sourceLock: string;
+  visibility: PublicationSpaceManifestV1["visibility"];
+  assetNamespace: string;
+  assetAccess: PublicationSpaceManifestV1["assets"]["access"];
+  files: PublicationArtifactFileV1[];
+}
+
+export interface PublicationArtifactBundleExpectationV1 {
+  tenant: string;
+  spaceId: string;
+  versionId: string;
+  sourceSha: string;
+  artifactDigest: string;
+  forge: string;
+  repo: string;
+  visibility?: PublicationArtifactBundleV1["visibility"];
+  assetNamespace?: string;
+  assetAccess?: PublicationArtifactBundleV1["assetAccess"];
+}
+
+/** Locale-independent canonical order for immutable publication files. */
+export function comparePublicationArtifactFilesV1(
+  left: PublicationArtifactFileV1,
+  right: PublicationArtifactFileV1,
+): number {
+  const leftIdentity = `${left.lane}\0${left.path}`;
+  const rightIdentity = `${right.lane}\0${right.path}`;
+  return leftIdentity < rightIdentity ? -1 : leftIdentity > rightIdentity ? 1 : 0;
+}
+
+function safeArtifactPath(path: string): boolean {
+  return !!path && !path.startsWith("/") && !path.includes("\\") && !path.includes("\0") &&
+    path.split("/").every((part) => !!part && part !== "." && part !== "..");
+}
+
+function hasExactKeys(value: object, keys: readonly string[]): boolean {
+  const actual = Object.keys(value).sort();
+  const expected = [...keys].sort();
+  return actual.length === expected.length && actual.every((key, index) => key === expected[index]);
+}
+
+function decodePublicationArtifactFileV1(file: PublicationArtifactFileV1): Uint8Array | null {
+  try {
+    if (file.encoding === "utf8") return new TextEncoder().encode(file.content);
+    if (file.encoding !== "base64" ||
+      !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(file.content)) return null;
+    const binary = atob(file.content);
+    if (btoa(binary) !== file.content) return null;
+    return Uint8Array.from(binary, (character) => character.charCodeAt(0));
+  } catch {
+    return null;
+  }
+}
+
+function validPublicationArtifactFileV1(value: unknown): value is PublicationArtifactFileV1 {
+  if (!value || typeof value !== "object" || !hasExactKeys(value,
+    ["lane", "path", "encoding", "content", "byteSize"])) return false;
+  const file = value as PublicationArtifactFileV1;
+  return ["content", "public-asset", "authorized-asset"].includes(file.lane) &&
+    ["utf8", "base64"].includes(file.encoding) && typeof file.path === "string" &&
+    safeArtifactPath(file.path) && typeof file.content === "string" &&
+    Number.isSafeInteger(file.byteSize) && file.byteSize >= 0;
+}
+
+/** Decode one canonical portable artifact file while enforcing its declared byte length. */
+export function publicationArtifactFileBytesV1(file: PublicationArtifactFileV1): Uint8Array | null {
+  if (!validPublicationArtifactFileV1(file)) return null;
+  try {
+    const decoded = decodePublicationArtifactFileV1(file);
+    if (!decoded) return null;
+    return decoded.byteLength === file.byteSize ? decoded : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Canonical marker admission shared by the writer-side activation gate and the
+ * renderer. It validates shape, identity, source provenance/lock, and recomputes
+ * the complete file-list digest; a marker cannot define its own admission facts.
+ */
+export async function validatePublicationArtifactBundleV1(
+  value: unknown,
+  expected: PublicationArtifactBundleExpectationV1,
+): Promise<{ ok: true; value: PublicationArtifactBundleV1 } | { ok: false }> {
+  if (!value || typeof value !== "object") return { ok: false };
+  const bundle = value as PublicationArtifactBundleV1;
+  if (!hasExactKeys(bundle, ["tenant", "spaceId", "versionId", "sourceSha", "artifactDigest",
+    "sourceLock", "visibility", "assetNamespace", "assetAccess", "files"]) ||
+    bundle.tenant !== expected.tenant || bundle.spaceId !== expected.spaceId ||
+    bundle.versionId !== expected.versionId || bundle.sourceSha !== expected.sourceSha ||
+    !/^[0-9a-f]{40}$/.test(bundle.sourceSha) || bundle.artifactDigest !== expected.artifactDigest ||
+    !/^[0-9a-f]{64}$/.test(bundle.artifactDigest) || typeof bundle.sourceLock !== "string" ||
+    !/^[0-9a-f]{64}$/.test(bundle.sourceLock) ||
+    !["public", "internal"].includes(bundle.visibility) || typeof bundle.assetNamespace !== "string" ||
+    !bundle.assetNamespace ||
+    !["public", "authorized"].includes(bundle.assetAccess) || !Array.isArray(bundle.files) ||
+    (expected.visibility !== undefined && bundle.visibility !== expected.visibility) ||
+    (expected.assetNamespace !== undefined && bundle.assetNamespace !== expected.assetNamespace) ||
+    (expected.assetAccess !== undefined && bundle.assetAccess !== expected.assetAccess)) return { ok: false };
+  const paths = new Set<string>();
+  for (const file of bundle.files) {
+    if (!validPublicationArtifactFileV1(file) || !publicationArtifactFileBytesV1(file)) {
+      return { ok: false };
+    }
+    if ((file.lane === "public-asset" && bundle.assetAccess !== "public") ||
+      (file.lane === "authorized-asset" && bundle.assetAccess !== "authorized")) return { ok: false };
+    if (paths.has(file.path)) return { ok: false };
+    paths.add(file.path);
+  }
+  try {
+    const digest = await publicationArtifactDigestV1(bundle.files);
+    if (digest !== expected.artifactDigest) return { ok: false };
+    const sourceLock = await publicationArtifactSourceLockV1({
+      tenant: expected.tenant,
+      spaceId: expected.spaceId,
+      forge: expected.forge,
+      repo: expected.repo,
+      sourceSha: expected.sourceSha,
+      versionId: expected.versionId,
+      artifactDigest: digest,
+    });
+    return sourceLock === bundle.sourceLock ? { ok: true, value: bundle } : { ok: false };
+  } catch {
+    return { ok: false };
+  }
+}
+
+/** Canonical content digest shared by the trusted writer and renderer readback. */
+export async function publicationArtifactDigestV1(
+  files: readonly PublicationArtifactFileV1[],
+): Promise<string> {
+  if (!Array.isArray(files)) throw new Error("publication artifact file list is malformed");
+  const ordered = [...files].sort(comparePublicationArtifactFilesV1);
+  const paths = new Set<string>();
+  const rows = await Promise.all(ordered.map(async (file) => {
+    if (!validPublicationArtifactFileV1(file) || paths.has(file.path)) {
+      throw new Error("publication artifact file is malformed or duplicated");
+    }
+    paths.add(file.path);
+    const bytes = publicationArtifactFileBytesV1(file);
+    if (!bytes) throw new Error("publication artifact file is malformed");
+    return `${file.lane}\0${file.path}\0${file.encoding}\0${file.byteSize}\0${await sha256Hex(bytes)}`;
+  }));
+  return sha256Hex(rows.join("\n"));
+}
+
+/** Canonical source lock binds one immutable artifact to its configured source. */
+export function publicationArtifactSourceLockV1(input: {
+  tenant: string;
+  spaceId: string;
+  forge: string;
+  repo: string;
+  sourceSha: string;
+  versionId: string;
+  artifactDigest: string;
+}): Promise<string> {
+  return sha256Hex([
+    input.tenant, input.spaceId, input.forge, input.repo,
+    input.sourceSha, input.versionId, input.artifactDigest,
+  ].join("\0"));
+}
+
+/** Physical immutable namespace. Logical artifact paths are always relative. */
+export function publicationArtifactKeyV1(
+  tenant: string,
+  spaceId: string,
+  versionId: string,
+  lane: PublicationArtifactFileV1["lane"],
+  relativePath: string,
+): string {
+  const identifier = /^[a-z0-9](?:[a-z0-9._-]{0,126}[a-z0-9])?$/;
+  const version = /^pv_[a-z0-9](?:[a-z0-9._:-]{4,122}[a-z0-9])$/;
+  if (!identifier.test(tenant) || !identifier.test(spaceId) || !version.test(versionId)) {
+    throw new Error("publication artifact identity is unsafe");
+  }
+  if (!["content", "public-asset", "authorized-asset"].includes(lane) ||
+    !relativePath || relativePath.startsWith("/") || relativePath.includes("\\") ||
+    relativePath.includes("\0") ||
+    relativePath.split("/").some((part) => !part || part === "." || part === "..")) {
+    throw new Error("publication artifact path is unsafe");
+  }
+  return `publications/${tenant}/${spaceId}/${versionId}/${lane}/${relativePath}`;
+}