1'use strict';
2
3// Dependencies that need no separate producer.
4//
5// A target dependency is normally satisfied by a producer: an import task, setup steps, or an
6// approved census disposition. Some are not produced separately at all: the related data is absent
7// (`no-data`), the dependent write itself creates or resolves it (`within-write`), or the approved
8// mapping writes none of its references (`not-referenced`). This module validates those proofs
9// against the reviewed operation contract in target knowledge and resolves the whole dependency
10// graph with one pure function, so the mapper (before approval), codegen (manifest) and the
11// runtime gate apply the same rules. Bundled rules remain binding; mapper-authored, evidence-bound
12// supplements can fill missing knowledge. Missing guards or evidence require investigation.
13

dependency-proofs.js on GitHub

const

fs

=

require

(

'node:fs'

);

const path = require('node:path');

const crypto = require('node:crypto');

const assessments = require('./operation-assessments');

const REASONS = new Set(['no-data', 'within-write', 'not-referenced']);

const ABSENCE_KINDS = new Set(['zero-row', 'zero-match', 'capability-absent']);

const PREDICATE_OPS = new Set(['equals', 'in', 'present', 'startsWith']);

// Producers whose dependent writes nothing through a transitive ref, or whose own task binds it.

const INHERITABLE = new Set(['import-task', 'disposition', 'no-producer', 'secondary-output', 'child-output', 'inherited']);

const refPattern = /^[a-z0-9-]+\/[a-z0-9-]+$/;

const DOMAINS = path.join(__dirname, '../resources/rp-target-wix/domains');

const hash = bytes => crypto.createHash('sha256').update(bytes).digest('hex');

const equal = (a, b) => JSON.stringify(a) === JSON.stringify(b);

function canonical(value) {

if (Array.isArray(value)) return '[' + value.map(canonical).join(',') + ']';

if (value && typeof value === 'object') return '{' + Object.keys(value).sort().map(key => JSON.stringify(key) + ':' + canonical(value[key])).join(',') + '}';

return JSON.stringify(value);

}

// The one loader for dependency knowledge, shared by the resolver and the runtime gate. Tests may

// point it at a fixture knowledge tree (the same idea as plugin-cms-fallback's targetKnowledgeRoot);

// the rules applied to whatever it loads never change.

let domainsRoot = DOMAINS;

function useTargetKnowledgeRoot(root) {

const prior = domainsRoot;

domainsRoot = root ? path.resolve(root) : DOMAINS;

return () => { domainsRoot = prior; };

}

const MISSING = Object.freeze({ code: 'ENOENT' });

function bundledDomain(ref) {

if (!refPattern.test(ref)) throw new Error(`entity_ref_unknown:${ref}`);

// Parsed once per file version; callers get their own copy, as they did from a fresh parse.

try { const found = require('./cached-json').readJson(path.join(domainsRoot, ref.split('/')[0], 'entities', ref.split('/')[1] + '.json'), MISSING); if (found === MISSING) throw MISSING; return structuredClone(found); }

catch (error) { if (error.code?.startsWith('mapping_assessment_')) throw error; throw new Error(`entity_ref_unknown:${ref}`); }

}

function domain(ref) { return assessments.effectiveDomain(ref, bundledDomain(ref)); }

// The reviewed contract for one write operation, by name or alias. Null when knowledge has none.

function operationContract(entityRef, operation) {

if (!operation) return null;

const contracts = domain(entityRef).operationContracts || {};

for (const [name, contract] of Object.entries(contracts)) if (name === operation || (contract.aliases || []).includes(operation)) return { name, contract };

return null;

}

// Prose (evidence, notes) may change without invalidating a proof; every field a check reads does.

function contractDigest(contract) {

const { evidence: _evidence, notes: _notes, ...semantic } = contract || {};

return hash(canonical(semantic));

}

// The refs a write operation actually depends on: an operation contract may declare an entity-level

// edge inapplicable (Import Order carries no Shipping Options or delivery-profile reference).

function applicableDependsOn(entityRef, operation) {

const deps = domain(entityRef).dependsOn || [];

const found = operationContract(entityRef, operation);

if (!found) return deps;

return [...new Set([...deps,...Object.keys(found.contract.dependencies || {})])].filter(ref => !found.contract.dependencies?.[ref]?.inapplicable);

}

function inapplicableRefs(entityRef, operation) {

const found = operationContract(entityRef, operation);

return found ? Object.entries(found.contract.dependencies || {}).filter(([, dep]) => dep.inapplicable).map(([ref]) => ref) : [];

}

function guardPath(guard) { return typeof guard === 'string' ? guard : guard?.path; }

function discriminated(guard) { return typeof guard === 'object' && guard !== null && guard.equals !== undefined; }

function stripInput(targetPath, writeInput) {

if (typeof targetPath !== 'string') return null;

return writeInput && targetPath.startsWith(writeInput + '.') ? targetPath.slice(writeInput.length + 1) : targetPath;

}

// Path templates overlap when one is the other or an ancestor of it; `[]` and `[n]` compare equal.

function pathsOverlap(a, b) {

const norm = value => value.replace(/\[\d*\]/g, '[]');

const x = norm(a), y = norm(b);

return x === y || y.startsWith(x + '.') || x.startsWith(y + '.') || y.startsWith(x + '[]') || x.startsWith(y + '[]');

}

// --- deterministic payload and record reads ---------------------------------------------------

function valuesAt(value, template) {

const parts = template.split('.'), out = [];

(function visit(node, index) {

if (index === parts.length) { out.push(node); return; }

if (node === null || typeof node !== 'object') return;

const part = parts[index], array = part.endsWith('[]'), key = array ? part.slice(0, -2) : part;

if (!Object.hasOwn(node, key)) return;

if (array) { if (Array.isArray(node[key])) for (const entry of node[key]) visit(entry, index + 1); }

else visit(node[key], index + 1);

})(value, 0);

return out;

}

// A guarded path is present when a payload carries a value there (and, for a discriminated guard,

// that value equals the discriminator). Presence contradicts a proof that no reference is written.

function guardHits(payload, guards) {

const hits = [];

for (const guard of guards || []) {

const template = guardPath(guard);

const values = valuesAt(payload, template).filter(value => value !== undefined && value !== null && value !== '');

if (values.some(value => typeof guard === 'string' || guard.equals === undefined || value === guard.equals)) hits.push(template);

}

return hits;

}

function validatePredicate(predicate) {

if (!predicate || typeof predicate !== 'object') return false;

if (Array.isArray(predicate.any)) return predicate.any.length > 0 && predicate.any.every(validatePredicate);

if (typeof predicate.path !== 'string' || !/^\w+(?:\[\])?(?:\.\w+(?:\[\])?)*$/.test(predicate.path) || !PREDICATE_OPS.has(predicate.op)) return false;

if (predicate.op === 'in') return Array.isArray(predicate.values) && predicate.values.length > 0;

if (predicate.op === 'equals' || predicate.op === 'startsWith') return predicate.value !== undefined && (predicate.op !== 'startsWith' || typeof predicate.value === 'string');

return true;

}

function predicateMatches(record, predicate) {

if (Array.isArray(predicate.any)) return predicate.any.some(clause => predicateMatches(record, clause));

const values = valuesAt(record, predicate.path);

if (predicate.op === 'present') return values.some(value => value !== undefined && value !== null && value !== '');

if (predicate.op === 'equals') return values.some(value => value === predicate.value);

if (predicate.op === 'in') return values.some(value => predicate.values.includes(value));

return values.some(value => typeof value === 'string' && value.startsWith(predicate.value));

}

// --- mapping-plan reads -----------------------------------------------------------------------

function rowOutputs(row) {

const outputs = [];

for (const mapping of row.fieldMappings || []) for (const output of mapping.outputs || []) if (output && typeof output === 'object') outputs.push(output);

return outputs;

}

// One exact write operation per dependent: the preferred writer, plus only the auxiliary operations

// its contract names. A single-create preference beside bulk-create outputs cannot share a proof.

function resolveRowOperation(row) {

const primary = row.preferredWrite?.writerId || null;

const ops = [...new Set(rowOutputs(row).filter(output => !output.targetRef || output.targetRef === row.targetRef).map(output => output.writeOperation).filter(Boolean))].sort();

const found = primary ? operationContract(row.targetRef, primary) : (ops.length === 1 ? operationContract(row.targetRef, ops[0]) : null);

if (!found) return { operation: primary || (ops.length === 1 ? ops[0] : null), contract: null, errors: [] };

const allowed = new Set([found.name, ...(found.contract.aliases || []), ...(found.contract.auxiliaryOperations || [])]);

const extra = ops.filter(op => !allowed.has(op));

return { operation: found.name, contract: found.contract, errors: extra.length ? [`dependency_operation_mixed:${row.targetRef}:${found.name}:${extra.join(',')}`] : [] };

}

// Held or excluded scope is never an executable producer or writer.

const INACTIVE = new Set(['excluded', 'rejected', 'deferred']);

const activeRows = (plan, readEntityMappings) => readEntityMappings(plan).filter(row => row && !INACTIVE.has(row.status));

function rowsByTarget(plan, readEntityMappings) {

const rows = new Map();

for (const row of readEntityMappings(plan)) {

if (!row?.targetRef || !refPattern.test(row.targetRef) || INACTIVE.has(row.status)) continue;

if (!rows.has(row.targetRef)) rows.set(row.targetRef, []);

rows.get(row.targetRef).push(row);

}

return rows;

}

// Paths the dependent's write sends: its own rows' outputs, plus any active output that names its

// write operation, whatever target it is labelled with — the operation decides the request body.

function mappedPaths(rows, targetRef, operation, contract, allRows = []) {

const ops = new Set([operation, ...(contract?.aliases || [])]);

const paths = [];

const add = output => { const target = stripInput(output.targetPath, output.writeInput); if (target) paths.push(target); };

for (const row of rows) for (const output of rowOutputs(row)) {

if (output.targetRef && output.targetRef !== targetRef) continue;

if (output.writeOperation && !ops.has(output.writeOperation)) continue;

add(output);

}

for (const row of allRows) if (!rows.includes(row)) for (const output of rowOutputs(row)) if (ops.has(output.writeOperation)) add(output);

return paths;

}

function mislabelled(plan, readEntityMappings, dependentRef, found) {

const ops = new Set([found.name, ...(found.contract.aliases || [])]);

for (const row of activeRows(plan, readEntityMappings)) for (const output of rowOutputs(row)) {

const targetRef = output.targetRef || row?.targetRef;

if (!ops.has(output.writeOperation) || targetRef === dependentRef) continue;

let owned = null;

try { owned = refPattern.test(targetRef || '') ? operationContract(targetRef, output.writeOperation) : null; } catch { owned = null; }

if (!owned) return true;

}

return false;

}

// --- proof validation -------------------------------------------------------------------------

function proofKey(entityRef, operation, ref) { return `${entityRef}|${operation}|${ref}`; }

function insideProject(projectDir, file) {

if (typeof file !== 'string' || !file) throw new Error('dependency_proof_evidence_path_invalid');

const root = path.resolve(projectDir), absolute = path.resolve(root, file);

if (!absolute.startsWith(root + path.sep)) throw new Error('dependency_proof_evidence_path_invalid');

return absolute;

}

// zero-match: a deterministic predicate over a complete, populated extract. Returns the measured

// count and the extract digest it was measured on; throws when the population is not complete.

// Before approval the extract must also be the census-measured population; at runtime a source

// catch-up extract is re-measured on its own completeness (the census predates it).

// Runtime re-validates before every batch, so a scan is cached per extract file identity and

// predicate: one full scan per distinct extract version, never one per batch, edge or record.

const scanCache = new Map(), scanTotals = { scans: 0, records: 0 };

function statKey(file) { const stat = fs.statSync(file); return `${stat.ino}:${stat.size}:${stat.mtimeMs}:${stat.ctimeMs}`; }

function extractDigest(file) {

const key = 'digest:' + file, stamp = statKey(file), prior = scanCache.get(key);

if (prior?.stamp === stamp) return prior.value;

const value = hash(fs.readFileSync(file)); scanCache.set(key, { stamp, value }); return value;

}

function measureZeroMatch(projectDir, absence, censusRow, work, stage) {

if (!censusRow) throw new Error('dependency_proof_absence_unmeasured');

if (!Number.isInteger(censusRow.recordCount) || censusRow.recordCount <= 0) throw new Error('dependency_proof_population_empty');

if (!validatePredicate(absence.predicate)) throw new Error('dependency_proof_predicate_invalid');

const manifest = JSON.parse(fs.readFileSync(insideProject(projectDir, absence.manifestPath), 'utf8'));

const extractFile = insideProject(projectDir, absence.extractPath);

const key = 'scan:' + extractFile + ':' + canonical(absence.predicate), stamp = statKey(extractFile);

let scan = scanCache.get(key)?.stamp === stamp ? scanCache.get(key).value : null;

if (!scan) {

const bytes = fs.readFileSync(extractFile), records = bytes.toString('utf8').split(/\r?\n/).filter(Boolean).map(line => JSON.parse(line));

scan = { matches: records.filter(record => predicateMatches(record, absence.predicate)).length, extractSha256: hash(bytes), population: records.length };

scanCache.set(key, { stamp, value: scan }); scanTotals.scans++; scanTotals.records += records.length;

if (work) { work.predicateScans++; work.recordsScanned += records.length; }

}

if (!Number.isInteger(manifest.rowsWritten) || manifest.rowsWritten !== manifest.snapshotTotal || scan.population !== manifest.rowsWritten || stage !== 'runtime' && scan.population !== censusRow.recordCount) throw new Error('dependency_proof_population_incomplete');

return scan;

}

// Validate one proposed proof against the reviewed contract, the census and the mapping. `stage`

// 'mapping' and 'codegen' require bound evidence to be current; 'runtime' re-measures a changed

// extract instead (source catch-up) and reports a contradiction rather than throwing.

function validateProof(proof, { rows = new Map(), plan = null, readEntityMappings = () => [], projectDir = null, stage = 'mapping', work = null } = {}) {

const errors = [], key = proof && typeof proof === 'object' ? `${proof.dependentRef}:${proof.ref}` : '<invalid>';

const fail = code => { errors.push(`${code}:${key}`); return { ok: false, errors, proof }; };

if (!proof || typeof proof !== 'object' || typeof proof.id !== 'string' || !proof.id || !refPattern.test(proof.dependentRef || '') || !refPattern.test(proof.ref || '') || typeof proof.operation !== 'string' || !REASONS.has(proof.reason)) return fail('dependency_proof_invalid');

if (typeof proof.explanation !== 'string' || !proof.explanation.trim() || !Array.isArray(proof.evidenceRefs) || !proof.evidenceRefs.length || proof.evidenceRefs.some(ref => typeof ref !== 'string' || !ref)) return fail('dependency_proof_evidence_missing');

let found;

try { found = operationContract(proof.dependentRef, proof.operation); if (!(domain(proof.dependentRef).dependsOn || []).includes(proof.ref) && !Object.hasOwn(found?.contract.dependencies || {},proof.ref)) return fail('dependency_proof_not_a_dependency'); }

catch (error) { return fail(error.message.split(':')[0]); }

if (!found) return fail('dependency_proof_contract_unknown');

const dep = found.contract.dependencies?.[proof.ref];

if (!dep) return fail('dependency_proof_contract_unknown');

if (dep.inapplicable) return fail('dependency_proof_inapplicable');

if (proof.operation !== found.name) return fail('dependency_proof_operation_alias');

if (proof.operationContractDigest !== contractDigest(found.contract)) return fail('dependency_proof_contract_stale');

if (!Array.isArray(dep.guardedPaths) || !dep.guardedPaths.length) return fail('dependency_proof_guard_unknown');

if (!equal(proof.guardedPaths, dep.guardedPaths)) return fail('dependency_proof_guard_mismatch');

const targetRows = plan ? (rowsByTarget(plan, readEntityMappings).get(proof.dependentRef) || []) : [];

if (plan) {

if (!targetRows.length) return fail('dependency_proof_dependent_unmapped');

for (const row of targetRows) { const resolved = resolveRowOperation(row); if (resolved.errors.length || resolved.operation !== found.name) return fail('dependency_proof_operation_mismatch'); }

}

// An output carrying the dependent's write operation under a target that does not own it would

// hide its paths from the guard check below.

if (plan && mislabelled(plan, readEntityMappings, proof.dependentRef, found)) return fail('dependency_proof_operation_mislabelled');

const mapped = plan ? mappedPaths(targetRows, proof.dependentRef, found.name, found.contract, activeRows(plan, readEntityMappings)) : [];

// A `{ path, equals }` guard matches one value at its path (the Gift Cards catalog appId). A plan

// records which paths it writes, not their values, so mapping only refuses plain guards; the

// runtime payload guards (guardHits) enforce the value on every record before it is sent.

const guardMapped = () => mapped.some(target => dep.guardedPaths.some(guard => !discriminated(guard) && pathsOverlap(target, guardPath(guard))));

let status = 'valid', measured = null;

if (proof.reason === 'within-write') {

if (!dep.withinWrite || !Array.isArray(dep.creatingPaths) || !dep.creatingPaths.length) return fail('dependency_proof_within_write_unsupported');

if (!equal(proof.creatingPaths, dep.creatingPaths)) return fail('dependency_proof_creating_paths_mismatch');

const keys = found.contract.recovery?.reconciliationKeys || [];

if (!keys.length) return fail('dependency_proof_recovery_undefined');

if (plan) {

if (guardMapped()) return fail('dependency_proof_guard_mapped');

if (!keys.some(entry => entry.clientAssigned || mapped.some(target => target.replace(/\[\d*\]/g, '[]') === entry.path))) return fail('dependency_proof_reconciliation_key_unmapped');

}

} else {

if (dep.conditional !== true) return fail('dependency_proof_not_conditional');

if (dep.nonReferencePrerequisite) return fail('dependency_proof_prerequisite_remains');

if (plan && guardMapped()) return fail('dependency_proof_guard_mapped');

}

if (proof.reason === 'not-referenced' && plan && targetRows.some(row => row.fieldMappingStatus !== undefined && row.fieldMappingStatus !== 'resolved')) return fail('dependency_proof_mapping_incomplete');

if (proof.reason === 'no-data') {

const absence = proof.absence;

if (!absence || !ABSENCE_KINDS.has(absence.kind)) return fail('dependency_proof_absence_unmeasured');

try {

if (absence.kind === 'zero-row') {

if (!Array.isArray(absence.censusIds) || !absence.censusIds.length) return fail('dependency_proof_absence_unmeasured');

for (const id of absence.censusIds) {

const row = rows.get(id);

if (!row || !Number.isInteger(row.recordCount)) return fail('dependency_proof_absence_unmeasured');

if (row.recordCount !== 0 || row.state !== 'no-data') { if (stage === 'runtime') { status = 'contradicted'; break; } return fail('dependency_proof_absence_contradicted'); }

}

} else if (absence.kind === 'zero-match') {

if (!projectDir) return fail('dependency_proof_absence_unmeasured');

const current = extractDigest(insideProject(projectDir, absence.extractPath));

if (current !== absence.extractSha256 && stage !== 'runtime') return fail('dependency_proof_evidence_stale');

measured = measureZeroMatch(projectDir, absence, rows.get(absence.censusId), work, stage);

if (measured.matches > 0) { if (stage === 'runtime') status = 'contradicted'; else return fail('dependency_proof_absence_contradicted'); }

} else {

if (!projectDir || typeof absence.capability !== 'string' || !absence.capability) return fail('dependency_proof_absence_unmeasured');

const bytes = fs.readFileSync(insideProject(projectDir, absence.evidencePath));

if (hash(bytes) !== absence.evidenceSha256) return fail('dependency_proof_evidence_stale');

const evidence = JSON.parse(bytes.toString('utf8'));

// Only an explicit, scoped absence counts; a missing or failed discovery response does not.

if (evidence?.capability !== absence.capability || evidence.status !== 'absent' || typeof evidence.scope !== 'string' || !evidence.scope || !Number.isFinite(Date.parse(evidence.observedAt))) return fail('dependency_proof_absence_unmeasured');

}

} catch (error) {

if (/^dependency_proof_/.test(error.message)) return fail(error.message);

return fail(error.code === 'ENOENT' ? 'dependency_proof_evidence_missing' : 'dependency_proof_evidence_invalid');

}

return { ok: true, errors, proof, status, measured, contractName: found.name };

}

function validateProofs(proofs, context = {}) {

const valid = new Map(), errors = [];

if (proofs !== undefined && !Array.isArray(proofs)) return { proofs: valid, errors: ['dependency_proofs_invalid'] };

for (const proof of proofs || []) {

const result = validateProof(proof, context);

if (!result.ok) { errors.push(...result.errors); continue; }

const key = proofKey(proof.dependentRef, proof.operation, proof.ref);

if (valid.has(key)) { errors.push(`dependency_proof_duplicate:${proof.dependentRef}:${proof.ref}`); continue; }

valid.set(key, { ...proof, status: result.status, measured: result.measured });

}

return { proofs: valid, errors };

}

// --- graph resolution -------------------------------------------------------------------------

// A setup step is never per-record: a ref that may come from either an import task or a setup step

// (a tax group) is per-record only when an import task produces it.

const SETUP_PRODUCERS = new Set(['setup-step', 'pending-setup']);

function edgeMode(entityRefs, ref, producer) {

if (SETUP_PRODUCERS.has(producer?.kind)) return 'task-complete';

return entityRefs.every(entity => domain(entity).dependencyModes?.[ref] === 'per-record') ? 'per-record' : 'task-complete';

}

// Every ref a dependent needs, operation-aware, with the parents each transitive ref was reached

// through. `operationFor(ref)` names the operation that produces an intermediate ref, if known.

// `adopted` names refs whose task only reads and verifies what already exists on the site (mapping

// `writeMode: 'adopt-only-no-writes'`): nothing is written through them, so their own write-time

// dependencies are not expanded, and the closure keeps the ref and stops there.

function dependencyClosure(entityRefs, operations, operationFor, adopted = new Set()) {

const direct = new Map(), via = new Map(), cycles = [];

for (const entity of entityRefs) for (const ref of applicableDependsOn(entity, operations[entity])) {

// A ref this task writes itself is satisfied inside the task (its writer orders the writes);

// binding it to the task would make the task wait on itself.

if (entityRefs.includes(ref)) continue;

if (!direct.has(ref)) direct.set(ref, []);

direct.get(ref).push(entity);

}

const seen = new Set(direct.keys()), queue = [...direct.keys()];

while (queue.length) {

const parent = queue.shift();

if (adopted.has(parent)) continue;

for (const ref of applicableDependsOn(parent, operationFor(parent))) {

if (entityRefs.includes(ref)) { cycles.push(ref); continue; }

if (!direct.has(ref)) { if (!via.has(ref)) via.set(ref, new Set()); via.get(ref).add(parent); }

if (!seen.has(ref)) { seen.add(ref); queue.push(ref); }

}

return { direct, via, refs: [...seen].sort(), cycles: [...new Set(cycles)].sort() };

}

// Plan-side adopt-only evidence: a target is adopt-only only when every active mapping row for it says

// `writeMode: 'adopt-only-no-writes'`. A target with both kinds of row is `mixed` and refused, because

// the same task would both create and promise to write nothing.

const ADOPT_ONLY_WRITE_MODE = 'adopt-only-no-writes';

function adoptOnlyRefsOf(plan, readEntityMappings) {

const rows = rowsByTarget(plan, readEntityMappings), refs = [], mixed = [];

for (const [targetRef, targetRows] of rows) {

const adopting = targetRows.filter(row => row.writeMode === ADOPT_ONLY_WRITE_MODE).length;

if (adopting === targetRows.length) refs.push(targetRef); else if (adopting) mixed.push(targetRef);

}

return { refs: refs.sort(), mixed: mixed.sort() };

}

// Resolve producers for every dependent. One function serves mapping preflight and codegen; the

// stage adapters only supply who can produce what. A dependent marked `adoptOnly` is honoured only

// when the plan marks every ref it owns adopt-only (`adoptOnlyRefs`); the reverse also holds: a

// dependent owning a plan-adopt-only ref must carry the mark, so a task that omits it is never

// treated as a creating task silently. Either mismatch is an error, and the creating-task rules still

// run for that dependent, so the mark can never be used to skip a dependency. Setup at mapping time is `pending-setup`: it can

// pass structural readiness but is never a producer of record.

function resolveDependencyGraph({ dependents, imports, setupFor = () => null, dispositions = {}, proofs = new Map(), adoptOnlyRefs = [], adoptOnlyMixed = [] }) {

const result = {}, errors = [], usedProofs = new Set();

const approvedAdopt = new Set(adoptOnlyRefs), adopted = new Set(), adoptedTasks = new Set(), adoptErrors = new Map();

for (const dependent of dependents) {

const owned = dependent.entityRefs.filter(ref => approvedAdopt.has(ref)), mixed = dependent.entityRefs.filter(ref => adoptOnlyMixed.includes(ref));

const problems = mixed.map(ref => `dependency_adopt_only_mixed:${dependent.id}:${ref}`);

if (dependent.adoptOnly === true && owned.length === dependent.entityRefs.length && !problems.length) { adoptedTasks.add(dependent.id); dependent.entityRefs.forEach(ref => adopted.add(ref)); }

else if (dependent.adoptOnly === true) problems.push(`dependency_adopt_only_unapproved:${dependent.id}`);

else if (owned.length) problems.push(`dependency_adopt_only_unmarked:${dependent.id}`);

if (problems.length) adoptErrors.set(dependent.id, problems);

}

const producerOf = new Map();

for (const producer of imports) for (const ref of producer.entityRefs) if (!producerOf.has(ref)) producerOf.set(ref, producer);

const operationFor = ref => producerOf.get(ref)?.operations?.[ref];

const secondaryFor = (ref, selfId) => imports.filter(producer => producer.id !== selfId && producer.entityRefs.some(entity => operationContract(entity, producer.operations?.[entity])?.contract.secondaryOutputs?.[ref])).map(producer => ({ kind: 'secondary-output', taskId: producer.id, parentRef: producer.entityRefs.find(entity => operationContract(entity, producer.operations?.[entity])?.contract.secondaryOutputs?.[ref]) }));

// A child entity (a product's variants) is created inside its parent's write. Its identities come

// from the parent task whose reviewed operation declares them; with no such task nothing can name a

// child, so the ref is inherited from the parent and any write of it is refused.

const childOf = ref => { try { return domain(ref).childOf || null; } catch { return null; } };

const childFor = (ref, selfId) => imports.filter(producer => producer.id !== selfId && producer.entityRefs.includes(childOf(ref)) && operationContract(childOf(ref), producer.operations?.[childOf(ref)])?.contract.childOutputs?.[ref]).map(producer => ({ kind: 'child-output', taskId: producer.id, parentRef: childOf(ref) }));

// A child is never imported on its own: its identities exist only in the parent's verified receipt.

for (const producer of imports) for (const ref of producer.entityRefs) if (childOf(ref)) errors.push(`dependency_child_standalone:${producer.id}:${ref}`);

for (const dependent of dependents) {

const taskErrors = [...(adoptErrors.get(dependent.id) || [])], edges = [], bound = new Map(), carried = new Set();

// An adopt-only task writes nothing, so it needs no producer for any dependency of what it adopts.

if (adoptedTasks.has(dependent.id)) { result[dependent.id] = { refs: [], edges: [], dependsOn: [], errors: taskErrors }; continue; }

let closure;

try { closure = dependencyClosure(dependent.entityRefs, dependent.operations || {}, operationFor, adopted); }

catch (error) { errors.push(error.message); result[dependent.id] = { refs: [], edges: [], dependsOn: [], errors: [error.message] }; continue; }

for (const ref of closure.cycles) taskErrors.push(`dependency_cycle:${dependent.id}:${ref}`);

// Direct refs first, then transitive refs in an order where every parent is already bound.

// A child ref is bound after its parent, whose producer decides the child's fallback.

const order = [...closure.direct.keys()].sort((a, b) => Number(Boolean(childOf(a))) - Number(Boolean(childOf(b))) || a.localeCompare(b));

const pending = closure.refs.filter(ref => !closure.direct.has(ref));

while (pending.length) {

const index = pending.findIndex(ref => [...closure.via.get(ref)].every(parent => !pending.includes(parent)));

order.push(...pending.splice(index < 0 ? 0 : index, 1));

}

for (const ref of order) {

const isDirect = closure.direct.has(ref), candidates = [];

// Reached only through per-record parents: each dependent record waits for its own parent

// record, whose write was already gated on this ref, so no task-wide wait is added.

if (!isDirect && [...closure.via.get(ref)].every(parent => carried.has(parent))) {

const producer = { kind: 'inherited', via: [...closure.via.get(ref)].sort() };

bound.set(ref, producer); edges.push({ ref, mode: 'task-complete', producer }); carried.add(ref); continue;

}

// A task is never its own producer: the readiness gate would wait for a pass of itself.

if (!childOf(ref)) for (const producer of imports) if (producer.id !== dependent.id && producer.entityRefs.includes(ref)) candidates.push({ kind: 'import-task', taskId: producer.id });

const scoped = isDirect ? closure.direct.get(ref).map(entity => ({ entity, proof: proofs.get(proofKey(entity, dependent.operations?.[entity], ref)) })) : [];

// Mapping-time `pending-setup` with no planned step is only a placeholder: it yields to a proof.

const setup = setupFor(ref);

if (setup && !(setup.kind === 'pending-setup' && !setup.stepId && scoped.some(row => row.proof))) candidates.push(setup);

if (dispositions[ref]) candidates.push({ kind: 'disposition', censusIds: dispositions[ref].censusIds, reconciliationSha256: dispositions[ref].reconciliationSha256 });

if (isDirect) {

if (scoped.some(row => row.proof)) {

if (!scoped.every(row => row.proof)) { taskErrors.push(`dependency_proof_scope_incomplete:${dependent.id}:${ref}`); continue; }

for (const row of scoped) usedProofs.add(proofKey(row.entity, dependent.operations[row.entity], ref));

candidates.push({ kind: 'no-producer', proofs: scoped.map(({ entity, proof }) => ({ entityRef: entity, operation: proof.operation, reason: proof.reason, proofId: proof.id, operationContractDigest: proof.operationContractDigest })) });

}

// A member task's verified contact identities can satisfy a contact reference only when no

// other producer exists, so two producers never compete for the same reference.

if (!candidates.length) candidates.push(...secondaryFor(ref, dependent.id));

if (!candidates.length && childOf(ref)) candidates.push(...childFor(ref, dependent.id));

if (!candidates.length && childOf(ref) && bound.has(childOf(ref))) candidates.push({ kind: 'inherited', via: [childOf(ref)] });

} else if (!candidates.length) {

const parents = [...closure.via.get(ref)].sort();

if (parents.every(parent => INHERITABLE.has(bound.get(parent)?.kind))) candidates.push({ kind: 'inherited', via: parents });

}

// A proof that this operation writes no reference needs no producer, so a setup step (pending

// at mapping, real at codegen) that makes the ref for other dependents never competes with it:

// mapping and codegen then bind the same proof whether or not the plan has that step (an

// add-on's optional tax group). An import task or a disposition still conflicts.

if (candidates.some(candidate => candidate.kind === 'no-producer')) for (let i = candidates.length - 1; i >= 0; i--) if (['setup-step', 'pending-setup'].includes(candidates[i].kind)) candidates.splice(i, 1);

if (candidates.length > 1 && candidates.some(candidate => candidate.kind === 'no-producer')) { taskErrors.push(`dependency_proof_conflict:${dependent.id}:${ref}`); continue; }

if (candidates.length !== 1) { taskErrors.push(`dependency_${candidates.length ? 'multiply_bound' : 'unbound'}:${ref}`); continue; }

const producer = candidates[0], mode = producer.kind === 'inherited' ? 'task-complete' : edgeMode(dependent.entityRefs, ref, producer);

if (mode === 'per-record' && ['setup-step', 'pending-setup'].includes(producer.kind) || ['secondary-output', 'child-output'].includes(producer.kind) && mode !== 'per-record') taskErrors.push(`dependency_mode_invalid:${dependent.id}:${ref}`);

bound.set(ref, producer); edges.push({ ref, mode, producer });

// A proof that this operation writes no such reference carries nothing through it either:

// the ref's own dependencies (a gift card product's media) add no task-wide wait.

if (mode === 'per-record' || producer.kind === 'no-producer') carried.add(ref);

}

const dependsOn = [...new Set(edges.filter(edge => ['import-task', 'secondary-output', 'child-output'].includes(edge.producer.kind)).map(edge => edge.producer.taskId))].sort();

result[dependent.id] = { refs: closure.refs, edges, dependsOn, errors: taskErrors };

errors.push(...taskErrors);

}

for (const key of proofs.keys()) if (!usedProofs.has(key)) errors.push(`dependency_proof_unused:${key.split('|').join(':')}`);

return { ok: errors.length === 0, errors, tasks: result };

}

// --- mapping preflight (before approval) ------------------------------------------------------

const NEXT_STEPS = {

dependency_unbound: 'Import the dependency, record an approved exclusion, or propose a supported noProducer proof for the exact dependent operation.',

dependency_multiply_bound: 'Keep exactly one producer for this dependency.',

dependency_proof_conflict: 'A dependency with a real producer cannot also be explained as needing none; remove one.',

dependency_operation_mixed: 'Resolve one write operation for this dependent; a single-create preference and bulk-create outputs cannot share a proof.',

dependency_proof_guard_mapped: 'The approved mapping writes a guarded reference path; bind a real producer or stop writing the path.',

dependency_proof_operation_mislabelled: 'A mapping output uses this write operation under a different target; label it with the entity that write creates.',

dependency_proof_contract_stale: 'Target knowledge changed; recompute operationContractDigest and re-review the proof.',

dependency_proof_evidence_stale: 'Source evidence changed; re-measure the proof on the current extract.',

dependency_proof_absence_contradicted: 'The measured data contains the dependency; it is not absent.',

setup_step_claims_import_entity: 'Drop the ref from the setup step; the import task that writes it owns it. A read-only prerequisite check lists no import-owned refs.',

dependency_adopt_only_unapproved: 'The task is marked adopt-only but the approved mapping does not mark every ref it owns adopt-only; fix the mark or the mapping row.',

dependency_adopt_only_unmarked: 'The approved mapping marks this ref adopt-only but the task is not marked adoptOnly: true; emit the mark (rp-import-codegen) or change the mapping row to create.',

dependency_adopt_only_mixed: 'The mapping has adopt-only and creating rows for one target; split them or make every row the same write mode.',

dependency_child_standalone: 'Map these source records into their parent entity; the parent write creates them and its verified receipt names them.',

dependency_proof_expected: 'The mapping writes none of this conditional reference, so nothing has to produce it: add the suggestedProof to mapping-plan.json dependencyProofs. Setup only produces it when a mapped path references it.',

};

const UNPRODUCIBLE_NEXT = 'Nothing can produce this dependency: rp-target-wix has no writer for it and no setup step makes it, so it cannot be imported. Record an approved exclusion (census disposition) for it, or propose a supported noProducer proof for the exact dependent operation.';

// Whether the target has any way to be written: setup, a parent write, a registered writer, or

// guarded raw requests for a native entity with no writer.

// Unknown knowledge keeps the ordinary message.

function producible(ref) {

let entity;

try { entity = domain(ref); } catch { return true; }

if (entity.setupProducible || entity.childOf) return true;

const writers = require('../resources/rp-target-wix/lib/wix-writers.js');

return [entity.preferredWrite?.writerId, ...Object.keys(entity.operationContracts || {})].some(name => typeof writers[name] === 'function') || Boolean(writers.WRITE_BUILDERS_BY_ENTITY[ref]?.length) || require('./target-import-support').rawRequestEntity(ref);

}

function diagnostic(code, dependent = null) {

const [name, ...rest] = code.split(':'), detail = rest.join(':');

const next = name === 'dependency_unbound' && !producible(detail) ? UNPRODUCIBLE_NEXT : NEXT_STEPS[name];

return { code: name, ...(dependent ? { dependent } : {}), detail, next: next || 'Correct the named dependency evidence, then re-run the preflight.' };

}

// The not-referenced proof a dependent's mapping already satisfies for `ref`, or null.

function notReferencedProof(dependent, ref, context) {

const operation = dependent?.operations?.[dependent.id], found = operationContract(dependent?.id, operation), dep = found?.contract.dependencies?.[ref];

if (!dep || dep.conditional !== true || !Array.isArray(dep.guardedPaths) || !dep.guardedPaths.length) return null;

const proof = { id: `${dependent.id.split('/')[1]}-${ref.split('/')[1]}`, dependentRef: dependent.id, operation: found.name, ref, reason: 'not-referenced',

explanation: `The approved ${dependent.id} mapping writes none of ${dep.guardedPaths.map(guardPath).join(', ')}.`,

evidenceRefs: [`mapping/mapping-plan.json#${dependent.id}`], operationContractDigest: contractDigest(found.contract), guardedPaths: dep.guardedPaths };

return validateProof(proof, { ...context, stage: 'mapping' }).ok ? proof : null;

}

function preflightMapping({ plan, reconciliation, dispositions = {}, readEntityMappings, projectDir = null }) {

const started = process.hrtime.bigint(), work = { predicateScans: 0, recordsScanned: 0, dependents: 0, edges: 0 };

const rowsMap = new Map((reconciliation?.rows || []).map(row => [row.censusId, row]));

const byTarget = rowsByTarget(plan, readEntityMappings), errors = [], dependents = [], imports = [];

// The same plan-side evidence codegen reads: a target whose every row adopts what a quick pass made

// is an adopt-only dependent, so mapper and codegen draw the same edges for it.

const adoption = adoptOnlyRefsOf(plan, readEntityMappings);

for (const [targetRef, rows] of byTarget) {

let setupProducible = false;

try { setupProducible = Boolean(domain(targetRef).setupProducible); } catch (error) { errors.push(error.message); continue; }

const resolved = rows.map(resolveRowOperation), ops = [...new Set(resolved.map(row => row.operation))];

for (const row of resolved) errors.push(...row.errors);

if (ops.length > 1) errors.push(`dependency_operation_mixed:${targetRef}:${ops.join(',')}`);

const producer = { id: targetRef, entityRefs: [targetRef], operations: ops.length === 1 && ops[0] ? { [targetRef]: ops[0] } : {}, ...(adoption.refs.includes(targetRef) ? { adoptOnly: true } : {}) };

// Whether setup or an import writes a mapped setup-producible target is decided at codegen, so

// here it stays pending setup as a producer; its own dependencies are still checked.

if (!setupProducible) imports.push(producer);

dependents.push(producer);

}

const setupFor = ref => {

const planned = require('./setup-producers').plannedProducer(plan, ref, projectDir);

if (planned) return planned;

try { return domain(ref).setupProducible ? { kind:'pending-setup' } : null; } catch { return null; }

};

const validated = validateProofs(plan?.dependencyProofs, { rows: rowsMap, plan, readEntityMappings, projectDir, stage: 'mapping', work });

errors.push(...validated.errors);

const graph = resolveDependencyGraph({ dependents, imports, setupFor, dispositions, proofs: validated.proofs, adoptOnlyRefs: adoption.refs, adoptOnlyMixed: adoption.mixed });

const taskErrors = new Set(Object.values(graph.tasks).flatMap(task => task.errors));

errors.push(...graph.errors.filter(error => !taskErrors.has(error)));

work.dependents = dependents.length; work.edges = Object.values(graph.tasks).reduce((sum, task) => sum + task.edges.length, 0);

const diagnostics = [...new Set(errors)].map(code => diagnostic(code));

for (const [id, task] of Object.entries(graph.tasks)) for (const code of new Set(task.errors)) diagnostics.push(diagnostic(code, id));

// A setup-producible ref with no planned setup step and no mapping row of its own stays

// `pending-setup` here, yet nothing will ever make it. When the dependent's reviewed contract makes

// the ref conditional and the mapping writes none of its guarded paths, codegen would find no

// producer (`dependency_unbound`): ask for the not-referenced proof now, ready to add.

for (const [id, task] of Object.entries(graph.tasks)) for (const edge of task.edges) {

if (edge.producer.kind !== 'pending-setup' || edge.producer.stepId || byTarget.has(edge.ref)) continue;

const suggestedProof = notReferencedProof(dependents.find(row => row.id === id), edge.ref, { plan, readEntityMappings, rows: rowsMap, projectDir });

if (suggestedProof) diagnostics.push({ ...diagnostic(`dependency_proof_expected:${edge.ref}`, id), suggestedProof });

}

// The same proof for a conditional ref nothing can produce here (a site's share image with no

// media row): the blocking dependency_unbound row carries it, ready to add, so a mapping that

// writes none of the guarded paths is fixed by the proof rather than by planning a producer.

for (const row of diagnostics) if (row.code === 'dependency_unbound' && row.dependent) {

let suggestedProof = null;

try { suggestedProof = notReferencedProof(dependents.find(dependent => dependent.id === row.dependent), row.detail, { plan, readEntityMappings, rows: rowsMap, projectDir }); } catch { suggestedProof = null; }

if (suggestedProof) Object.assign(row, { suggestedProof, next: `The mapping writes none of this conditional reference: add the suggestedProof to mapping-plan.json dependencyProofs, or map the producer of ${row.detail}.` });

}

const pendingSetup = [...new Set(Object.values(graph.tasks).flatMap(task => task.edges.filter(edge => edge.producer.kind === 'pending-setup').map(edge => edge.ref)))].sort();

// A producer whose mapping rows still have an uninspected field inventory cannot run yet. When

// every row of that target is pending it is not a producer at all (`deferred-mapping`); when only

// some are, a dependent waits for the pending rows its retained writes name in

// requiredSourceEntityRefs (the same prerequisites execution scope uses). Held dependents are

// annotated too. Listed for the review, not a structural error, so an independent subset can

// still be approved provisionally.

const identities = row => [row.sourceEntityRef, row.sourceEntity, row.entityKey].filter(Boolean);

const canonicalId = row => row.sourceEntityRef || row.sourceEntity || row.entityKey;

const pendingRows = new Map();

for (const [targetRef, rows] of byTarget) {

const pending = rows.filter(row => row.fieldMappingStatus === 'pending');

if (pending.length) pendingRows.set(targetRef, { all: pending.length === rows.length, rows: pending });

}

const waiting = [];

for (const [id, task] of Object.entries(graph.tasks)) {

const required = new Set((byTarget.get(id) || []).flatMap(row => row.requiredSourceEntityRefs || []));

for (const edge of task.edges) {

const held = edge.producer.kind === 'import-task' && pendingRows.get(edge.producer.taskId);

if (!held) continue;

const rows = held.all ? held.rows : held.rows.filter(row => identities(row).some(name => required.has(name)));

if (!rows.length) continue;

const sourceEntityRefs = [...new Set(rows.map(canonicalId))].sort();

if (held.all) edge.producer = { kind: 'deferred-mapping', taskId: edge.producer.taskId, sourceEntityRefs };

else edge.pendingSourceEntityRefs = sourceEntityRefs;

waiting.push({ dependent: id, ref: edge.ref, mode: edge.mode, sourceEntityRefs, producerPartlyPending: !held.all,

next: 'Finish the field mapping of the named source entities (for a plugin entity, its full read comes first: resources/rp-source-wordpress/scripts/plugin-full-read.js), or record an approved exclusion. Until then this dependent waits.' });

}

return {

schemaVersion: 1, stage: 'mapping', structuralReady: diagnostics.length === 0, executionReady: false,

errors: diagnostics, pendingSetup, waiting,

tasks: Object.fromEntries(Object.entries(graph.tasks).map(([id, task]) => [id, { operation: dependents.find(row => row.id === id)?.operations?.[id] || null, edges: task.edges }])),

proofs: [...validated.proofs.values()].map(proof => ({ id: proof.id, dependentRef: proof.dependentRef, operation: proof.operation, ref: proof.ref, reason: proof.reason, status: proof.status })),

work: { ...work, elapsedMs: Number((process.hrtime.bigint() - started) / 1000000n) },

};

}

module.exports = {

REASONS, canonical, domain, bundledDomain, useTargetKnowledgeRoot, contractDigest, operationContract, applicableDependsOn, inapplicableRefs, guardHits, guardPath, valuesAt,

validatePredicate, predicateMatches, resolveRowOperation, validateProof, validateProofs, proofKey, dependencyClosure, adoptOnlyRefsOf,

resolveDependencyGraph, preflightMapping, pathsOverlap, scanTotals: () => ({ ...scanTotals }),

};

for (const name of ['preflightMapping', 'resolveDependencyGraph']) {

const run = module.exports[name];

module.exports[name] = options => options.plan ? assessments.withPlan(options.plan, options.projectDir, () => run(options)) : run(options);

}

for (const name of ['validateProof', 'validateProofs']) {

const run = module.exports[name];

module.exports[name] = (proof, options = {}) => options.plan ? assessments.withPlan(options.plan, options.projectDir, () => run(proof, options)) : run(proof, options);

}