sentinelayer-cli 0.1.0

package/src/ai/domain-target-store.js

@@ -0,0 +1,268 @@
+import fsp from "node:fs/promises";
+import path from "node:path";
+
+const REGISTRY_SCHEMA_VERSION = "1.0.0";
+
+function normalizeString(value) {
+  return String(value || "").trim();
+}
+
+function normalizeDomainRecord(record = {}) {
+  return {
+    domainId: normalizeString(record.domainId),
+    domainName: normalizeString(record.domainName) || null,
+    projectId: normalizeString(record.projectId) || null,
+    verificationStatus: normalizeString(record.verificationStatus) || "UNKNOWN",
+    freezeStatus: normalizeString(record.freezeStatus) || "UNKNOWN",
+    trustClass: normalizeString(record.trustClass) || null,
+    verificationMethod: normalizeString(record.verificationMethod) || null,
+    challengeValue: normalizeString(record.challengeValue) || null,
+    proofId: normalizeString(record.proofId) || null,
+    proofStatus: normalizeString(record.proofStatus) || null,
+    proofExpiresAt: normalizeString(record.proofExpiresAt) || null,
+    createdAt: normalizeString(record.createdAt) || new Date().toISOString(),
+    lastUpdatedAt: normalizeString(record.lastUpdatedAt) || new Date().toISOString(),
+    metadata: record.metadata && typeof record.metadata === "object" ? record.metadata : {},
+  };
+}
+
+function normalizeTargetRecord(record = {}) {
+  return {
+    targetId: normalizeString(record.targetId),
+    host: normalizeString(record.host) || null,
+    domainId: normalizeString(record.domainId) || null,
+    projectId: normalizeString(record.projectId) || null,
+    verificationStatus: normalizeString(record.verificationStatus) || "UNKNOWN",
+    status: normalizeString(record.status) || "UNKNOWN",
+    freezeStatus: normalizeString(record.freezeStatus) || "UNKNOWN",
+    challengeValue: normalizeString(record.challengeValue) || null,
+    proofId: normalizeString(record.proofId) || null,
+    proofStatus: normalizeString(record.proofStatus) || null,
+    proofExpiresAt: normalizeString(record.proofExpiresAt) || null,
+    policy:
+      record.policy && typeof record.policy === "object"
+        ? {
+            allowedPaths: Array.isArray(record.policy.allowedPaths) ? record.policy.allowedPaths : [],
+            allowedMethods: Array.isArray(record.policy.allowedMethods) ? record.policy.allowedMethods : [],
+            allowedScenarios: Array.isArray(record.policy.allowedScenarios)
+              ? record.policy.allowedScenarios
+              : [],
+            maxRps: Number.isFinite(Number(record.policy.maxRps)) ? Number(record.policy.maxRps) : null,
+            maxConcurrency: Number.isFinite(Number(record.policy.maxConcurrency))
+              ? Number(record.policy.maxConcurrency)
+              : null,
+            stopConditions:
+              record.policy.stopConditions && typeof record.policy.stopConditions === "object"
+                ? record.policy.stopConditions
+                : {},
+          }
+        : {
+            allowedPaths: [],
+            allowedMethods: [],
+            allowedScenarios: [],
+            maxRps: null,
+            maxConcurrency: null,
+            stopConditions: {},
+          },
+    createdAt: normalizeString(record.createdAt) || new Date().toISOString(),
+    lastUpdatedAt: normalizeString(record.lastUpdatedAt) || new Date().toISOString(),
+    metadata: record.metadata && typeof record.metadata === "object" ? record.metadata : {},
+  };
+}
+
+export function resolveDomainTargetRegistryPath({ outputRoot } = {}) {
+  const resolvedOutputRoot = path.resolve(String(outputRoot || "."));
+  return path.join(resolvedOutputRoot, "aidenid", "domain-target-registry.json");
+}
+
+async function loadRegistryInternal(filePath) {
+  try {
+    const raw = await fsp.readFile(filePath, "utf-8");
+    const parsed = JSON.parse(raw);
+    const domains = Array.isArray(parsed.domains)
+      ? parsed.domains.map((item) => normalizeDomainRecord(item)).filter((item) => item.domainId)
+      : [];
+    const targets = Array.isArray(parsed.targets)
+      ? parsed.targets.map((item) => normalizeTargetRecord(item)).filter((item) => item.targetId)
+      : [];
+    return {
+      schemaVersion: normalizeString(parsed.schemaVersion) || REGISTRY_SCHEMA_VERSION,
+      generatedAt: normalizeString(parsed.generatedAt) || new Date().toISOString(),
+      domains,
+      targets,
+    };
+  } catch (error) {
+    if (error && typeof error === "object" && error.code === "ENOENT") {
+      return {
+        schemaVersion: REGISTRY_SCHEMA_VERSION,
+        generatedAt: new Date().toISOString(),
+        domains: [],
+        targets: [],
+      };
+    }
+    throw error;
+  }
+}
+
+async function writeRegistryInternal(filePath, registry = {}) {
+  const normalized = {
+    schemaVersion: REGISTRY_SCHEMA_VERSION,
+    generatedAt: new Date().toISOString(),
+    domains: Array.isArray(registry.domains) ? registry.domains.map(normalizeDomainRecord) : [],
+    targets: Array.isArray(registry.targets) ? registry.targets.map(normalizeTargetRecord) : [],
+  };
+  await fsp.mkdir(path.dirname(filePath), { recursive: true });
+  await fsp.writeFile(filePath, `${JSON.stringify(normalized, null, 2)}\n`, "utf-8");
+  return normalized;
+}
+
+export async function listDomainTargetRecords({ outputRoot } = {}) {
+  const registryPath = resolveDomainTargetRegistryPath({ outputRoot });
+  const registry = await loadRegistryInternal(registryPath);
+  return {
+    registryPath,
+    domains: registry.domains,
+    targets: registry.targets,
+  };
+}
+
+export async function getDomainById({ outputRoot, domainId } = {}) {
+  const normalizedDomainId = normalizeString(domainId);
+  if (!normalizedDomainId) {
+    throw new Error("domainId is required.");
+  }
+  const { registryPath, domains } = await listDomainTargetRecords({ outputRoot });
+  const domain = domains.find((item) => item.domainId === normalizedDomainId) || null;
+  return {
+    registryPath,
+    domain,
+  };
+}
+
+export async function getTargetById({ outputRoot, targetId } = {}) {
+  const normalizedTargetId = normalizeString(targetId);
+  if (!normalizedTargetId) {
+    throw new Error("targetId is required.");
+  }
+  const { registryPath, targets } = await listDomainTargetRecords({ outputRoot });
+  const target = targets.find((item) => item.targetId === normalizedTargetId) || null;
+  return {
+    registryPath,
+    target,
+  };
+}
+
+export async function recordDomainProofResponse({
+  outputRoot,
+  domain = {},
+  proof = {},
+  context = {},
+} = {}) {
+  const domainId = normalizeString(domain.id || context.domainId);
+  if (!domainId) {
+    throw new Error("Cannot record domain without domain.id.");
+  }
+  const registryPath = resolveDomainTargetRegistryPath({ outputRoot });
+  const registry = await loadRegistryInternal(registryPath);
+  const nowIso = new Date().toISOString();
+  const nextRecord = normalizeDomainRecord({
+    domainId,
+    domainName: domain.domainName,
+    projectId: domain.projectId || context.projectId,
+    verificationStatus: domain.verificationStatus,
+    freezeStatus: domain.freezeStatus,
+    trustClass: domain.trustClass,
+    verificationMethod: domain.verificationMethod,
+    challengeValue: proof.challengeValue || context.challengeValue,
+    proofId: proof.proofId,
+    proofStatus: proof.proofStatus,
+    proofExpiresAt: proof.proofExpiresAt,
+    createdAt: nowIso,
+    lastUpdatedAt: nowIso,
+    metadata: {
+      source: normalizeString(context.source) || "domain",
+      idempotencyKey: context.idempotencyKey || null,
+    },
+  });
+
+  const index = registry.domains.findIndex((item) => item.domainId === domainId);
+  if (index >= 0) {
+    const existing = registry.domains[index];
+    registry.domains[index] = normalizeDomainRecord({
+      ...existing,
+      ...nextRecord,
+      createdAt: existing.createdAt || nextRecord.createdAt,
+      metadata: {
+        ...existing.metadata,
+        ...nextRecord.metadata,
+      },
+    });
+  } else {
+    registry.domains.push(nextRecord);
+  }
+
+  const saved = await writeRegistryInternal(registryPath, registry);
+  const record = saved.domains.find((item) => item.domainId === domainId) || null;
+  return {
+    registryPath,
+    domain: record,
+  };
+}
+
+export async function recordTargetProofResponse({
+  outputRoot,
+  target = {},
+  proof = {},
+  context = {},
+} = {}) {
+  const targetId = normalizeString(target.id || context.targetId);
+  if (!targetId) {
+    throw new Error("Cannot record target without target.id.");
+  }
+  const registryPath = resolveDomainTargetRegistryPath({ outputRoot });
+  const registry = await loadRegistryInternal(registryPath);
+  const nowIso = new Date().toISOString();
+  const nextRecord = normalizeTargetRecord({
+    targetId,
+    host: target.host,
+    domainId: target.domainId || context.domainId || null,
+    projectId: target.projectId || context.projectId || null,
+    verificationStatus: target.verificationStatus,
+    status: target.status,
+    freezeStatus: target.freezeStatus,
+    challengeValue: proof.challengeValue || context.challengeValue,
+    proofId: proof.proofId,
+    proofStatus: proof.proofStatus,
+    proofExpiresAt: proof.proofExpiresAt,
+    policy: target.policy || {},
+    createdAt: nowIso,
+    lastUpdatedAt: nowIso,
+    metadata: {
+      source: normalizeString(context.source) || "target",
+      idempotencyKey: context.idempotencyKey || null,
+    },
+  });
+
+  const index = registry.targets.findIndex((item) => item.targetId === targetId);
+  if (index >= 0) {
+    const existing = registry.targets[index];
+    registry.targets[index] = normalizeTargetRecord({
+      ...existing,
+      ...nextRecord,
+      createdAt: existing.createdAt || nextRecord.createdAt,
+      metadata: {
+        ...existing.metadata,
+        ...nextRecord.metadata,
+      },
+    });
+  } else {
+    registry.targets.push(nextRecord);
+  }
+
+  const saved = await writeRegistryInternal(registryPath, registry);
+  const record = saved.targets.find((item) => item.targetId === targetId) || null;
+  return {
+    registryPath,
+    target: record,
+  };
+}

package/src/ai/identity-store.js

@@ -0,0 +1,270 @@
+import fsp from "node:fs/promises";
+import path from "node:path";
+
+const REGISTRY_SCHEMA_VERSION = "1.0.0";
+const TERMINAL_IDENTITY_STATUSES = new Set(["SQUASHED"]);
+
+function normalizeString(value) {
+  return String(value || "").trim();
+}
+
+function normalizeUpper(value) {
+  return normalizeString(value).toUpperCase();
+}
+
+function normalizeTagList(value) {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  const unique = new Set();
+  for (const item of value) {
+    const normalized = normalizeString(item);
+    if (normalized) {
+      unique.add(normalized);
+    }
+  }
+  return [...unique];
+}
+
+function normalizeLegalHoldStatus(value) {
+  const normalized = normalizeUpper(value);
+  if (!normalized) {
+    return "NONE";
+  }
+  if (normalized === "HOLD" || normalized === "NONE" || normalized === "UNKNOWN") {
+    return normalized;
+  }
+  return normalized;
+}
+
+function normalizeMetadata(value) {
+  const source = value && typeof value === "object" ? value : {};
+  return {
+    ...source,
+    tags: normalizeTagList(source.tags),
+    legalHoldStatus: normalizeLegalHoldStatus(source.legalHoldStatus),
+  };
+}
+
+function normalizeIdentityRecord(record = {}) {
+  const metadata = normalizeMetadata(record.metadata);
+  const legalHoldStatus = normalizeLegalHoldStatus(record.legalHoldStatus || metadata.legalHoldStatus);
+  return {
+    identityId: normalizeString(record.identityId),
+    parentIdentityId: normalizeString(record.parentIdentityId) || null,
+    emailAddress: normalizeString(record.emailAddress) || null,
+    status: normalizeString(record.status) || "UNKNOWN",
+    projectId: normalizeString(record.projectId) || null,
+    orgId: normalizeString(record.orgId) || null,
+    apiUrl: normalizeString(record.apiUrl) || null,
+    createdAt: normalizeString(record.createdAt) || new Date().toISOString(),
+    lastUpdatedAt: normalizeString(record.lastUpdatedAt) || new Date().toISOString(),
+    expiresAt: normalizeString(record.expiresAt) || null,
+    revokedAt: normalizeString(record.revokedAt) || null,
+    squashedAt: normalizeString(record.squashedAt) || null,
+    legalHoldStatus,
+    metadata,
+  };
+}
+
+export function resolveIdentityRegistryPath({ outputRoot } = {}) {
+  const resolvedOutputRoot = path.resolve(String(outputRoot || "."));
+  return path.join(resolvedOutputRoot, "aidenid", "identity-registry.json");
+}
+
+async function loadRegistryInternal(filePath) {
+  try {
+    const raw = await fsp.readFile(filePath, "utf-8");
+    const parsed = JSON.parse(raw);
+    const identities = Array.isArray(parsed.identities)
+      ? parsed.identities.map((item) => normalizeIdentityRecord(item)).filter((item) => item.identityId)
+      : [];
+    return {
+      schemaVersion: normalizeString(parsed.schemaVersion) || REGISTRY_SCHEMA_VERSION,
+      generatedAt: normalizeString(parsed.generatedAt) || new Date().toISOString(),
+      identities,
+    };
+  } catch (error) {
+    if (error && typeof error === "object" && error.code === "ENOENT") {
+      return {
+        schemaVersion: REGISTRY_SCHEMA_VERSION,
+        generatedAt: new Date().toISOString(),
+        identities: [],
+      };
+    }
+    throw error;
+  }
+}
+
+async function writeRegistryInternal(filePath, registry = {}) {
+  const normalized = {
+    schemaVersion: REGISTRY_SCHEMA_VERSION,
+    generatedAt: new Date().toISOString(),
+    identities: Array.isArray(registry.identities) ? registry.identities.map(normalizeIdentityRecord) : [],
+  };
+  await fsp.mkdir(path.dirname(filePath), { recursive: true });
+  await fsp.writeFile(filePath, `${JSON.stringify(normalized, null, 2)}\n`, "utf-8");
+  return normalized;
+}
+
+export async function listIdentities({ outputRoot } = {}) {
+  const registryPath = resolveIdentityRegistryPath({ outputRoot });
+  const registry = await loadRegistryInternal(registryPath);
+  return {
+    registryPath,
+    identities: registry.identities,
+  };
+}
+
+export async function getIdentityById({ outputRoot, identityId } = {}) {
+  const normalizedIdentityId = normalizeString(identityId);
+  if (!normalizedIdentityId) {
+    throw new Error("identityId is required.");
+  }
+  const { registryPath, identities } = await listIdentities({ outputRoot });
+  const identity = identities.find((item) => item.identityId === normalizedIdentityId) || null;
+  return {
+    registryPath,
+    identity,
+  };
+}
+
+export async function recordProvisionedIdentity({
+  outputRoot,
+  response = {},
+  context = {},
+} = {}) {
+  const registryPath = resolveIdentityRegistryPath({ outputRoot });
+  const registry = await loadRegistryInternal(registryPath);
+  const identityId = normalizeString(response.id);
+  if (!identityId) {
+    throw new Error("Cannot record identity without response.id.");
+  }
+
+  const nowIso = new Date().toISOString();
+  const source = normalizeString(context.source) || "provision-email";
+  const nextRecord = normalizeIdentityRecord({
+    identityId,
+    parentIdentityId: response.parentIdentityId || context.parentIdentityId || null,
+    emailAddress: response.emailAddress,
+    status: response.status || "ACTIVE",
+    projectId: response.projectId || context.projectId,
+    orgId: context.orgId,
+    apiUrl: context.apiUrl,
+    createdAt: nowIso,
+    lastUpdatedAt: nowIso,
+    expiresAt: response.expiresAt || null,
+    legalHoldStatus: response.legalHoldStatus || context.legalHoldStatus || "NONE",
+    metadata: {
+      source,
+      idempotencyKey: context.idempotencyKey || null,
+      eventBudget: context.eventBudget ?? null,
+      tags: normalizeTagList(context.tags || response.tags || []),
+      legalHoldStatus: response.legalHoldStatus || context.legalHoldStatus || "NONE",
+    },
+  });
+
+  const index = registry.identities.findIndex((item) => item.identityId === identityId);
+  if (index >= 0) {
+    const existing = registry.identities[index];
+    registry.identities[index] = normalizeIdentityRecord({
+      ...existing,
+      ...nextRecord,
+      createdAt: existing.createdAt || nextRecord.createdAt,
+      metadata: {
+        ...existing.metadata,
+        ...nextRecord.metadata,
+      },
+    });
+  } else {
+    registry.identities.push(nextRecord);
+  }
+
+  const saved = await writeRegistryInternal(registryPath, registry);
+  const identity = saved.identities.find((item) => item.identityId === identityId) || null;
+  return {
+    registryPath,
+    identity,
+  };
+}
+
+export async function updateIdentityStatus({
+  outputRoot,
+  identityId,
+  status,
+  revokedAt = "",
+  squashedAt = "",
+  metadataPatch = {},
+} = {}) {
+  const normalizedIdentityId = normalizeString(identityId);
+  if (!normalizedIdentityId) {
+    throw new Error("identityId is required.");
+  }
+  const nextStatus = normalizeString(status);
+  if (!nextStatus) {
+    throw new Error("status is required.");
+  }
+
+  const registryPath = resolveIdentityRegistryPath({ outputRoot });
+  const registry = await loadRegistryInternal(registryPath);
+  const index = registry.identities.findIndex((item) => item.identityId === normalizedIdentityId);
+  if (index < 0) {
+    throw new Error(`Identity '${normalizedIdentityId}' was not found in local registry.`);
+  }
+
+  const existing = registry.identities[index];
+  registry.identities[index] = normalizeIdentityRecord({
+    ...existing,
+    status: nextStatus,
+    revokedAt: normalizeString(revokedAt) || existing.revokedAt || null,
+    squashedAt: normalizeString(squashedAt) || existing.squashedAt || null,
+    legalHoldStatus: metadataPatch?.legalHoldStatus || existing.legalHoldStatus || "NONE",
+    lastUpdatedAt: new Date().toISOString(),
+    metadata: {
+      ...existing.metadata,
+      ...(metadataPatch && typeof metadataPatch === "object" ? metadataPatch : {}),
+    },
+  });
+
+  const saved = await writeRegistryInternal(registryPath, registry);
+  return {
+    registryPath,
+    identity: saved.identities[index],
+  };
+}
+
+export function filterIdentitiesByTags(identities = [], tags = []) {
+  const requestedTags = normalizeTagList(tags);
+  if (requestedTags.length === 0) {
+    return [...identities];
+  }
+  const required = new Set(requestedTags);
+  return identities.filter((identity) => {
+    const identityTags = normalizeTagList(identity?.metadata?.tags);
+    if (identityTags.length === 0) {
+      return false;
+    }
+    return [...required].every((tag) => identityTags.includes(tag));
+  });
+}
+
+export async function findStaleIdentities({ outputRoot, nowIso = new Date().toISOString() } = {}) {
+  const { registryPath, identities } = await listIdentities({ outputRoot });
+  const nowMs = new Date(nowIso).getTime();
+  const stale = identities.filter((identity) => {
+    const status = normalizeUpper(identity.status);
+    if (TERMINAL_IDENTITY_STATUSES.has(status)) {
+      return false;
+    }
+    const expiresAtMs = new Date(identity.expiresAt || "").getTime();
+    if (!Number.isFinite(expiresAtMs)) {
+      return false;
+    }
+    return expiresAtMs <= nowMs;
+  });
+  return {
+    registryPath,
+    identities,
+    stale,
+  };
+}

package/src/ai/site-store.js

@@ -0,0 +1,145 @@
+import fsp from "node:fs/promises";
+import path from "node:path";
+
+const REGISTRY_SCHEMA_VERSION = "1.0.0";
+
+function normalizeString(value) {
+  return String(value || "").trim();
+}
+
+function normalizeSiteRecord(record = {}) {
+  return {
+    siteId: normalizeString(record.siteId),
+    projectId: normalizeString(record.projectId) || null,
+    identityId: normalizeString(record.identityId) || null,
+    domainId: normalizeString(record.domainId) || null,
+    host: normalizeString(record.host) || null,
+    callbackPath: normalizeString(record.callbackPath) || null,
+    callbackUrl: normalizeString(record.callbackUrl) || null,
+    status: normalizeString(record.status) || "UNKNOWN",
+    dnsCleanupStatus: normalizeString(record.dnsCleanupStatus) || "UNKNOWN",
+    expiresAt: normalizeString(record.expiresAt) || null,
+    teardownReason: normalizeString(record.teardownReason) || null,
+    teardownAt: normalizeString(record.teardownAt) || null,
+    createdAt: normalizeString(record.createdAt) || new Date().toISOString(),
+    lastUpdatedAt: normalizeString(record.lastUpdatedAt) || new Date().toISOString(),
+    dnsCleanupContract:
+      record.dnsCleanupContract && typeof record.dnsCleanupContract === "object"
+        ? record.dnsCleanupContract
+        : {},
+    metadata: record.metadata && typeof record.metadata === "object" ? record.metadata : {},
+  };
+}
+
+export function resolveSiteRegistryPath({ outputRoot } = {}) {
+  const resolvedOutputRoot = path.resolve(String(outputRoot || "."));
+  return path.join(resolvedOutputRoot, "aidenid", "site-registry.json");
+}
+
+async function loadRegistryInternal(filePath) {
+  try {
+    const raw = await fsp.readFile(filePath, "utf-8");
+    const parsed = JSON.parse(raw);
+    const sites = Array.isArray(parsed.sites)
+      ? parsed.sites.map((item) => normalizeSiteRecord(item)).filter((item) => item.siteId)
+      : [];
+    return {
+      schemaVersion: normalizeString(parsed.schemaVersion) || REGISTRY_SCHEMA_VERSION,
+      generatedAt: normalizeString(parsed.generatedAt) || new Date().toISOString(),
+      sites,
+    };
+  } catch (error) {
+    if (error && typeof error === "object" && error.code === "ENOENT") {
+      return {
+        schemaVersion: REGISTRY_SCHEMA_VERSION,
+        generatedAt: new Date().toISOString(),
+        sites: [],
+      };
+    }
+    throw error;
+  }
+}
+
+async function writeRegistryInternal(filePath, registry = {}) {
+  const normalized = {
+    schemaVersion: REGISTRY_SCHEMA_VERSION,
+    generatedAt: new Date().toISOString(),
+    sites: Array.isArray(registry.sites) ? registry.sites.map(normalizeSiteRecord) : [],
+  };
+  await fsp.mkdir(path.dirname(filePath), { recursive: true });
+  await fsp.writeFile(filePath, `${JSON.stringify(normalized, null, 2)}\n`, "utf-8");
+  return normalized;
+}
+
+export async function listSites({ outputRoot, identityId = "" } = {}) {
+  const registryPath = resolveSiteRegistryPath({ outputRoot });
+  const registry = await loadRegistryInternal(registryPath);
+  const normalizedIdentityId = normalizeString(identityId);
+  const filteredSites = normalizedIdentityId
+    ? registry.sites.filter((item) => item.identityId === normalizedIdentityId)
+    : registry.sites;
+  return {
+    registryPath,
+    sites: filteredSites,
+  };
+}
+
+export async function recordTemporarySite({
+  outputRoot,
+  site = {},
+  context = {},
+} = {}) {
+  const siteId = normalizeString(site.id || context.siteId);
+  if (!siteId) {
+    throw new Error("Cannot record temporary site without site.id.");
+  }
+
+  const registryPath = resolveSiteRegistryPath({ outputRoot });
+  const registry = await loadRegistryInternal(registryPath);
+  const nowIso = new Date().toISOString();
+  const nextRecord = normalizeSiteRecord({
+    siteId,
+    projectId: site.projectId || context.projectId,
+    identityId: site.identityId || context.identityId,
+    domainId: site.domainId || context.domainId,
+    host: site.host,
+    callbackPath: site.callbackPath,
+    callbackUrl: site.callbackUrl,
+    status: site.status,
+    dnsCleanupStatus: site.dnsCleanupStatus,
+    expiresAt: site.expiresAt,
+    teardownReason: site.teardownReason,
+    teardownAt: site.teardownAt,
+    createdAt: nowIso,
+    lastUpdatedAt: nowIso,
+    dnsCleanupContract: site.dnsCleanupContract,
+    metadata: {
+      ...(site.metadata && typeof site.metadata === "object" ? site.metadata : {}),
+      source: normalizeString(context.source) || "site-create",
+      idempotencyKey: context.idempotencyKey || null,
+    },
+  });
+
+  const index = registry.sites.findIndex((item) => item.siteId === siteId);
+  if (index >= 0) {
+    const existing = registry.sites[index];
+    registry.sites[index] = normalizeSiteRecord({
+      ...existing,
+      ...nextRecord,
+      createdAt: existing.createdAt || nextRecord.createdAt,
+      metadata: {
+        ...existing.metadata,
+        ...nextRecord.metadata,
+      },
+    });
+  } else {
+    registry.sites.push(nextRecord);
+  }
+
+  const saved = await writeRegistryInternal(registryPath, registry);
+  const savedSite = saved.sites.find((item) => item.siteId === siteId) || null;
+  return {
+    registryPath,
+    site: savedSite,
+  };
+}