@aopslabs/aops-server 0.2.24 → 0.2.25

package/scripts/domain-backup-provider.mjs

@@ -0,0 +1,246 @@
+#!/usr/bin/env node
+/**
+ * What each domain supplies to a backup set, and what the core owns instead.
+ *
+ * The split follows the measurement rather than symmetry. A domain knows three
+ * things nobody else can know: which relations it owns, which relation is its
+ * migration ledger, and which of its columns point at another domain without a
+ * foreign key to enforce it. Everything else -- the snapshot, the chunk format,
+ * the codec, sequence handling, eligibility -- is identical for every domain, so
+ * it lives in the core. Giving each provider its own codec would be five copies
+ * of one behaviour and five places for them to drift apart.
+ *
+ * DEVIATION FROM THE DISCUSS CONSENSUS, recorded rather than quietly taken.
+ *
+ * The consensus text has each domain provider supply owned tables, the full
+ * migration closure, schema identity, typed text codecs, sequences, ledger
+ * evidence and versioned weak-reference edges. This provider supplies three of
+ * those: owned tables, its ledger relation, and its outbound weak edges. The
+ * rest sits in the core.
+ *
+ * The reason is measurable rather than stylistic. The codec is one behaviour --
+ * values leave as ::text and return as typed casts -- and it is identical for
+ * every domain because it is a property of PostgreSQL, not of any domain. The
+ * same holds for sequence handling and for the closure, which is collected per
+ * *package* and not per domain. Five copies of one behaviour is five places for
+ * them to drift, and a drift between two domains' codecs would be invisible
+ * until it corrupted one domain's restore.
+ *
+ * The operator directed this shape explicitly: "overengineering istemiyorum".
+ *
+ * What the consensus was protecting -- that no domain's specifics are assumed by
+ * the core -- is preserved: the core asks each provider which relations it owns
+ * and which of its columns cross a boundary, and never infers either.
+ *
+ * Ledgers are listed but never restored as data. Measured reason: a ledger row
+ * asserts that a migration ran. Replaying rows independently of the DDL can
+ * assert it about a schema where it did not, and nothing downstream would catch
+ * the lie. On an empty target the engine writes the ledger by applying the
+ * embedded closure; on an existing target the ledger is left alone and only
+ * validated. Either way the bundle carries it as evidence, not as payload.
+ */
+import { createHash } from 'node:crypto'
+import { readFileSync } from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const CONTRACT = 'aops.domain-backup-provider/v1'
+const PROVIDER_CONTRACT_SCHEMA_VERSION = 1
+const repoRoot = fileURLToPath(new URL('../../../', import.meta.url))
+
+/** A relation is payload if a domain owns it and it is not that domain's ledger. */
+export function buildDomainProviders(inventory, { ownedRelations, policyRoots } = {}) {
+  if (inventory?.contract !== 'aops.domain-ownership-inventory/v1') {
+    throw new Error(`domain_backup_provider_inventory_contract_invalid:${String(inventory?.contract)}`)
+  }
+  // Which closure roots belong to a domain is a domain fact, and until now it was
+  // not in the contract at all: the closure arrived from outside as a migration
+  // set manifest, so nothing tied "these bytes" to "this domain".
+  //
+  // Bound by id, not by the migrations directory. The first version used the
+  // directory because both sides carried it, and that held only in a repository
+  // checkout: the npm staging step rewrites every policy root to
+  // `migrations/<id>` while the ownership inventory ships its repository paths
+  // unchanged. In an installed package the two never matched, and a backup on a
+  // real installation refused with root_unmatched. Ids are the same string in
+  // both layouts because both are generated from the same root list.
+  if (!Array.isArray(policyRoots)) throw new Error('domain_backup_provider_policy_roots_absent')
+  const rootsById = new Map()
+  for (const root of policyRoots) {
+    if (rootsById.has(root.id)) {
+      throw new Error(`domain_backup_provider_root_id_ambiguous:${root.id}`)
+    }
+    rootsById.set(root.id, root)
+  }
+  const ledgerByDomain = new Map(inventory.ledgers.map((entry) => [entry.domain, entry.relation]))
+  const edgesByDomain = new Map()
+  for (const edge of inventory.weakEdges ?? []) {
+    if (!edgesByDomain.has(edge.fromDomain)) edgesByDomain.set(edge.fromDomain, [])
+    edgesByDomain.get(edge.fromDomain).push(edge)
+  }
+  // The inventory describes the target state. A backup is taken of whatever state
+  // the database is actually in, and a predecessor still holds the relations its
+  // pending migrations are about to drop -- `missions` on the 0.3.24 predecessor.
+  // Those belong to the domain that created them, so when the caller says which
+  // owned set it is backing up, add them back to that domain rather than leaving
+  // a relation with data in it outside every provider's payload.
+  const owned = ownedRelations ? new Set(ownedRelations) : null
+  const retiringByDomain = new Map()
+  for (const entry of inventory.createdThenDropped ?? []) {
+    // No owned set means the target state, which by definition has already
+    // dropped these. Adding them anyway would produce a provider set matching no
+    // state that ever exists -- neither the target nor any predecessor.
+    if (!owned || !owned.has(entry.table)) continue
+    if (!retiringByDomain.has(entry.domain)) retiringByDomain.set(entry.domain, [])
+    retiringByDomain.get(entry.domain).push(entry.table)
+  }
+  const providers = inventory.domains.map((domain) => {
+    const root = rootsById.get(domain.domain)
+    if (!root) throw new Error(`domain_backup_provider_root_unmatched:${domain.domain}`)
+    return Object.freeze({
+    contractSchemaVersion: PROVIDER_CONTRACT_SCHEMA_VERSION,
+    domain: domain.domain,
+    payloadRelations: [...domain.ownedRelations, ...(retiringByDomain.get(domain.domain) ?? [])].sort(),
+    retiringRelations: Object.freeze([...(retiringByDomain.get(domain.domain) ?? [])].sort()),
+    ledgerRelation: ledgerByDomain.get(domain.domain) ?? null,
+    outboundWeakEdges: Object.freeze(edgesByDomain.get(domain.domain) ?? []),
+    // Which roots produce this domain's relations -- the reference, never the
+    // bytes. The bytes stay in the lineage migration set manifest; duplicating
+    // them per domain would be a second place for them to drift.
+    // Deliberately without the migrations directory. It is inside the contract
+    // hash, and the npm staging step rewrites it: a lineage whose contract was
+    // computed in a checkout would never match the same release installed from
+    // the registry, and the backup would refuse on a real machine while passing
+    // every test in the repository. The root id and its migration table identify
+    // the closure and are the same string in both layouts.
+    closureRoots: Object.freeze([Object.freeze({
+      rootId: root.id,
+      migrationTable: root.migrationTable,
+    })]),
+    // Empty unless the core codec registry does not know a type this domain
+    // uses. An empty list is a claim -- "core handles everything here" -- and it
+    // is inside the contract hash, so it cannot change without being noticed.
+    codecExtensions: Object.freeze([]),
+  })
+  })
+  assertOwnershipDisjoint(providers)
+  return Object.freeze({
+    schemaVersion: 1,
+    contract: CONTRACT,
+    providers: Object.freeze(providers),
+    // The set the core actually reads: payload from every domain, plus every
+    // ledger. It has to equal the owned set the lineage identity was measured
+    // against, or the backup is scoped to a different database than the one the
+    // classifier recognised.
+    payloadRelations: providers.flatMap((p) => p.payloadRelations).sort(),
+    ledgerRelations: providers.map((p) => p.ledgerRelation).filter(Boolean).sort(),
+  })
+}
+
+/**
+ * Two domains claiming one relation is not a conflict to resolve at backup time;
+ * it means ownership is undecided, and a backup scoped by an undecided boundary
+ * would silently include or exclude rows depending on iteration order.
+ */
+export function assertOwnershipDisjoint(providers) {
+  const owner = new Map()
+  for (const provider of providers) {
+    for (const relation of [provider.payloadRelations, provider.ledgerRelation ? [provider.ledgerRelation] : []].flat()) {
+      const existing = owner.get(relation)
+      if (existing && existing !== provider.domain) {
+        throw new Error(`domain_backup_provider_ownership_conflict:${relation}:${existing}:${provider.domain}`)
+      }
+      owner.set(relation, provider.domain)
+    }
+  }
+}
+
+/**
+ * The provider set has to cover exactly the relations the lineage identity was
+ * measured against -- no more, no fewer. A relation the providers do not claim
+ * would be silently dropped from every backup; one they claim but the identity
+ * does not know is a relation nobody derived a reference for.
+ */
+export function assertCoversOwnedIdentity(providerSet, ownedRelations) {
+  const covered = new Set([...providerSet.payloadRelations, ...providerSet.ledgerRelations])
+  const owned = new Set(ownedRelations)
+  const missing = [...owned].filter((relation) => !covered.has(relation)).sort()
+  const extra = [...covered].filter((relation) => !owned.has(relation)).sort()
+  if (missing.length || extra.length) {
+    throw new Error(`domain_backup_provider_coverage_mismatch:missing=${missing.join(',')}:extra=${extra.join(',')}`)
+  }
+  return { covered: covered.size }
+}
+
+/**
+ * The identity of what each domain DECLARED, and nothing else.
+ *
+ * Two properties earn their cost. It hashes only the semantic half: a weak edge
+ * carries a `note` explaining why no foreign key enforces it, and rewording that
+ * note must not invalidate a backup. And it serialises in a fixed key order
+ * rather than whatever order the objects happen to have, so the value describes
+ * the declaration instead of the code path that built it.
+ *
+ * The previous version of this function hashed `JSON.stringify({contract,
+ * providers})` -- note text included, key order incidental -- and was written
+ * nowhere except a CLI progress line. Measured: deleting every weak edge from
+ * the inventory changed it and nothing failed, because no gate consumed it.
+ */
+function canonicalJson(value) {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`
+  if (value && typeof value === 'object') {
+    return `{${Object.keys(value).sort()
+      .map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`).join(',')}}`
+  }
+  return JSON.stringify(value ?? null)
+}
+
+/** The semantic half of one weak edge. `note` is deliberately absent. */
+function semanticWeakEdge(edge) {
+  return {
+    id: edge.id,
+    fromDomain: edge.fromDomain,
+    toDomain: edge.toDomain,
+    toRelation: edge.toRelation,
+    column: edge.column,
+    kind: edge.kind,
+  }
+}
+
+export function providerContractSha256(providerSet) {
+  return createHash('sha256').update(canonicalJson({
+    contract: providerSet.contract,
+    schemaVersion: providerSet.schemaVersion,
+    providers: [...providerSet.providers]
+      .sort((a, b) => (a.domain < b.domain ? -1 : a.domain > b.domain ? 1 : 0))
+      .map((provider) => ({
+        contractSchemaVersion: provider.contractSchemaVersion,
+        domain: provider.domain,
+        payloadRelations: [...provider.payloadRelations].sort(),
+        ledgerRelation: provider.ledgerRelation,
+        closureRoots: [...provider.closureRoots]
+          .sort((a, b) => (a.rootId < b.rootId ? -1 : a.rootId > b.rootId ? 1 : 0)),
+        outboundWeakEdges: [...provider.outboundWeakEdges].map(semanticWeakEdge)
+          .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0)),
+        codecExtensions: [...provider.codecExtensions].sort(),
+      })),
+  })).digest('hex')
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const inventory = JSON.parse(readFileSync(
+    path.join(repoRoot, 'apps/aops-server/scripts/community-domain-ownership-v1.json'), 'utf8'))
+  const policy = JSON.parse(readFileSync(
+    path.join(repoRoot, 'apps/aops-server/scripts/community-migration-policy-v1.json'), 'utf8'))
+  const set = buildDomainProviders(inventory, { policyRoots: policy.roots })
+  for (const provider of set.providers) {
+    process.stdout.write(`${provider.domain.padEnd(12)} payload=${String(provider.payloadRelations.length).padStart(3)}` +
+      `  ledger=${provider.ledgerRelation ?? '-'}  edges=${provider.outboundWeakEdges.length}` +
+      `  roots=${provider.closureRoots.map((r) => r.rootId).join('/')}\n`)
+  }
+  process.stdout.write(`payload=${set.payloadRelations.length} ledger=${set.ledgerRelations.length} ` +
+    `total=${set.payloadRelations.length + set.ledgerRelations.length} ` +
+    `contract=${providerContractSha256(set)}\n`)
+}
+
+export { CONTRACT }