MongoDB’s Unique Index Still Allows Duplicate Array Items

Inventory I1, owned by tenant T1, contains two assets with code A01: one labeled Pump, another labeled Renamed pump. The update succeeds. Inspection still shows the compound unique index tenant_asset_unique. For an operator investigating the accepted write, that combination looks contradictory: duplicate equipment identities survived a constraint whose name explicitly promises uniqueness.

The explanation is the constraint’s comparison boundary. MongoDB’s 8.0 unique-index reference permits repeated multikey entries belonging to one document when they do not conflict with another document. The index can be operating correctly while the inventory violates its business contract.

That contract has two independent requirements. Each inventory must contain distinct asset codes, and two inventories belonging to the same tenant must never claim the same code. A different label does not create a different identity. Another tenant may legitimately use A01.

This playbook builds a disposable reproduction, retains the unique index, and adds guarded document validation for the internal rule. It then checks rejected-write readbacks, audits legacy records with an independent method, and turns the evidence into an ACCEPT, REPAIR, RERUN, or HOLD decision.

All identifiers and operations below are synthetic. They describe an original engineering fixture, not a customer incident. MongoDB 8.0 is the chosen reference family, not a claim about the newest release. Unversioned documentation is a rolling reference. The recorded execution applies to the exact runtime and local test conditions described below.

Write down the two uniqueness rules

Start with the identity that an equipment owner would recognize. tenantId identifies the tenant. _id identifies the inventory document. assets.code identifies an asset within that tenant. assets.label describes the asset and may change without transferring ownership or creating another asset.

For a valid document d, let C(d) be its ordered sequence of codes. The internal predicate is length(C(d)) = distinctCount(C(d)). The ownership predicate is: for every different document e with the same tenant, intersection(C(d), C(e)) is empty. Both predicates are conditional on the required document shape being valid.

The third row is a positive control. It prevents an accidentally global code restriction from passing as a correct repair. Likewise, a permitted label edit checks that the policy protects identity without freezing descriptive data.

Record these expectations before executing database commands. If the database accepts a forbidden operation, the business decision remains rejection; the implementation needs investigation. Changing the expected result to match the observed result destroys the test’s purpose.

Counts provide supporting evidence only. An array of three entries might contain three assets or two assets with one repeated identity. Two inventories with equal item counts can claim completely different equipment. Acceptance therefore needs the actual codes and ownership assignments alongside the counts.

For readers understanding SQL and NoSQL design tradeoffs, the useful next step here is to keep the selected document model fixed and specify its invariant precisely. The repair will preserve that model while giving each rule an explicit enforcement location.

Build a disposable inventory test database

Use an owned local MongoDB 8.0 server, an available mongosh, Bash, and a writable directory for evidence. The server must be unsharded and bound to loopback. The fixture connects to the exact database refonte_multikey_lab; it refuses an existing populated database. Never replace that name with a shared application database.

The runner and JavaScript file below belong in the same directory. Their ownership marker permits deliberate teardown of fixture collections after evidence is preserved. Unexpected failures leave state available for inspection. A database-name check helps prevent targeting mistakes; it does not establish permission to use somebody else’s server.

Recorded execution: The finished fixture ran on October 17, 2026, using MongoDB 8.0.16, feature compatibility version 8.0, and mongosh 2.5.8, on an owned Ubuntu 24.04.3 standalone server. All twenty-six cases passed, as did persisted-policy checks and both independent audit comparisons. These observations describe the complete published fixture under its recorded conditions.

Recorded baseline and legacy-audit collection options were {}. The repaired collection stored the exact validator printed below with strict and error settings. Both constrained collections retained tenant_asset_unique. All three collections used effective simple collation; their raw metadata omitted an explicit collation field.

The run records the exact server patch, feature compatibility version, shell version, collection options, complete validator, and every index definition. Inspect both the raw metadata and the effective collation. The 8.0 collection-options reference defines simple binary comparison as the default. Preserve omitted metadata fields as returned and record the effective collation separately.

Save this complete runner as run.sh; save the complete lab.js from the validation section beside it.

#!/usr/bin/env bash
set -u
set -o pipefail
script_dir="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
mongo_port="${MONGO_PORT:-27987}"
mongo_shell="${MONGOSH:-mongosh}"
[[ "$mongo_port" =~ ^[0-9]+$ ]] && (( mongo_port > 1023 && mongo_port < 65536 )) || exit 2
evidence_dir="$(mktemp -d "$script_dir/evidence.XXXXXX")" || exit 2
mongo_uri="mongodb://127.0.0.1:$mongo_port/refonte_multikey_lab?directConnection=true"
"$mongo_shell" --norc --quiet "$mongo_uri" --file "$script_dir/lab.js" \
  >"$evidence_dir/run.jsonl" 2>"$evidence_dir/stderr.log"
run_status=$?
printf '{"exitStatus":%d,"port":%d,"database":"refonte_multikey_lab"}\n' \
  "$run_status" "$mongo_port" >"$evidence_dir/run-manifest.json"
printf 'Exit status: %d\nEvidence: %s\n' "$run_status" "$evidence_dir"
exit "$run_status"

With MongoDB 8.0.x and mongosh installed on Linux and available on PATH, start an owned server from the directory containing the saved files. Use the same shell for the later shutdown command, which needs lab_runtime_dir. Stop if startup fails; do not reuse an unexpected listener on the chosen port.

export MONGO_PORT=27987
lab_runtime_dir="$(mktemp -d /tmp/refonte-multikey-runtime.XXXXXX)" || exit 1
mongod --dbpath "$lab_runtime_dir" --bind_ip 127.0.0.1 \
  --port "$MONGO_PORT" --logpath "$lab_runtime_dir/mongod.log" \
  --pidfilepath "$lab_runtime_dir/mongod.pid" --fork || exit 1
bash ./run.sh

The baseline isolates the index’s behavior. The repaired collection carries the full contract. A separate legacy-audit collection deliberately holds synthetic bad records, including ownership conflicts, so the audit can be checked without weakening either tested collection.

Choose identity before choosing an operator

Codes contain one to twelve uppercase ASCII letters or digits. Spaces, lowercase letters, punctuation, and trailing line breaks are invalid. A01 is compared under binary/simple collation. This policy performs neither case folding nor Unicode normalization; a future normalization proposal requires a new identity decision and migration review.

tenantId remains a required, nonempty scalar string. MongoDB’s multikey restrictions matter because the compound index already indexes an array path. The fixture does not introduce a second array-valued indexed field.

Keep this lab separate from the separate problem of MongoDB expiry read policy: its evidence concerns which inventory writes enter the collection.

Prove what the unique multikey index actually rejects

The baseline creates {tenantId: 1, "assets.code": 1} with unique: true, simple collation, and the stable name tenant_asset_unique. Naming the index makes inspection and error interpretation easier, but its key definition and options remain the evidence. A suggestive name cannot establish which fields are constrained.

Seed inventory I1 in tenant T1 with A01/Pump and A02/Valve. Next, attempt to insert I2 in T1 with A01. The expected database result is rejection for a duplicate indexed key. A readback must show that I2 is absent and that I1 retains its original array.

Then insert I3 in T2 with A01. That operation must succeed, and the complete readback must match the proposed document. These paired cases demonstrate tenant scope: the spelling can recur when the tenant changes, while another inventory in the original tenant cannot claim it.

The versioned multikey documentation describes how indexing an array produces index entries. For this fixture, the meaningful ownership combinations are (T1, A01), (T1, A02), and (T2, A01). The first and third are different indexed combinations, even though their code component matches.

Require a successful control on each side of the boundary before studying the failure. If both inserts fail, investigate metadata, preparation, and unexpected state. If both succeed, the intended index may be absent, differently defined, or applied to another collection. Either discrepancy invalidates the comparison until resolved.

The harness retains the command result, error category where applicable, and exact collection snapshots. It also captures index metadata after creation and after the cases. This ties the behavioral evidence to the policy actually installed during the run.

The baseline deliberately lacks document validation. That omission isolates the index while the seed and positive controls remain well shaped. It is not a proposed deployment configuration. The repaired collection is created separately, allowing the two behaviors to be compared without changing the baseline’s enforcement settings halfway through a case.

The broader habit resembles investigating nullable uniqueness in PostgreSQL: read the precise constraint contract before deciding that an accepted write proves a malfunction. Here, the question is exclusively whether repeated array entries belong to one inventory or different inventories.

Reproduce the duplicate that stays inside one document

Reset the baseline to its known seed before each independent case. Push {code: "A01", label: "Renamed pump"} into I1. The expected array, in order, is A01/Pump, A02/Valve, A01/Renamed pump. The expected database result is admission; the expected business result is rejection.

The changed label is intentional. It prevents an observer from replacing the business question with a complete-object comparison. There are two representations, but both claim the same equipment identity inside tenant T1. The rule established earlier does not include the label in that identity.

Now run a separate case from the original seed and push {code: "A01", label: "Pump"}. The expected array ends with an exact repeated embedded object. Keeping these two cases isolated distinguishes duplicate business identity from duplicate serialization and avoids depending on an earlier contaminated state.

Capture every item, field, and array position. A projected list of distinct codes would hide precisely the defect being investigated. A screenshot showing three array elements would prove a count but omit the identity comparison. The full readback supports both interpretations and can be reviewed independently of the write acknowledgment.

For an operational handoff, preserve the original mutation alongside the proposed final document. The mutation explains how the state was requested; the readback establishes what remained. If those disagree, retain the discrepancy and stop the run before resetting anything.

The baseline is a demonstration of the enforcement gap. Its admitted duplicate is a successful reproduction of a deliberately bad business outcome. It must never be described as an inventory that passed the complete contract.

In the recorded run, B3 admitted the changed-label duplicate and B4 admitted the identical-object duplicate. Both readbacks matched the complete expected arrays, while the independent business oracle marked both resulting inventories invalid. The cross-document control had already rejected I2/T1/A01, establishing that the observed gap coexisted with an operating unique index.

The expected arrays below also match the observed readbacks. Each object retains both fields; their order follows the stored array.

Keep the failure matrix independent of the repair

Write the business matrix before installing the validator. The harness stores these decisions separately from its expectations about the baseline’s database behavior.

This separation makes the repair test meaningful. After validation is installed, the first two database outcomes must change while the permitted cases continue to pass. A validator that rejects every update has closed the visible failure by breaking the application contract. Positive controls expose that mistake as clearly as forbidden-write controls expose under-enforcement.

Show why $addToSet is not a code-uniqueness policy

Replacing $push with $addToSet is a tempting application patch. Test the exact boundary before adopting it. From the clean seed, adding the exact object {code: "A01", label: "Pump"} is expected to leave the array unchanged. That no-op is admissible because its final inventory remains valid; mentioning an existing code does not itself violate the contract.

Repeat the experiment with {code: "A01", label: "Renamed pump"}. The label changes the embedded document, so the operation can add it even though its code is already present. The official $addToSet reference defines embedded-document equality using the complete document, including field order; it does not accept a selected identity field for comparison.

The fixture also reverses the field order of an otherwise matching object. Preserve that order when writing the case: constructing both operands through a serializer that normalizes their keys would remove the intended comparison. Array order and embedded-document field order are separate properties; both are visible in the evidence. The exact array-order assertions describe this recorded run; $addToSet does not promise a particular set order.

Finally, start a dedicated case with a duplicate already present, then apply an exact-object $addToSet. The existing duplicate is expected to remain. The operator reference explicitly limits its duplicate-prevention behavior to additions; it does not reconcile prior duplicate elements.

These cases support a narrow conclusion. $addToSet is useful when complete-value equality matches the application’s contract. It is insufficient for this inventory because the application defines identity by code, and allows descriptive labels to change.

Application logic may still use it for other fields whose values have the right equality semantics. That choice does not substitute for enforcing the inventory rule on every admitted document. Keep the two decisions separate in code review: which mutation operator expresses the requested update, and which database policy checks the resulting state?

When investigating an existing implementation, inspect all construction paths for embedded objects. Different labels are already enough to defeat the proposed code policy; field-order differences provide another documented comparison case. Do not rely on the current serializer’s habits as an unwritten business rule. Record the intended identity directly and test it where writes are admitted.

Combine shape validation with projected-key validation

The repair gives the collection two complementary responsibilities. $jsonSchema defines admissible document structure. A separate $expr compares the number of asset entries with the number of distinct projected codes. The compound unique index continues to enforce ownership across inventory documents.

MongoDB’s $jsonSchema reference supports required properties, BSON types, array limits, and item schemas. Here, tenantId must be a nonempty string; assets must be a nonempty array; every item must contain a valid string code and string label. The fixture disallows unknown top-level and item properties, while explicitly allowing _id.

The fixture uses absolute pattern anchors for the ASCII code policy and includes a trailing-newline rejection case. The PCRE2 pattern reference distinguishes the absolute end anchor \z from $, which can match before a terminal newline. Labels remain ordinary strings; uniqueness does not depend on their spelling or formatting.

The distinct-code expression maps each asset to its code. The $setUnion expression combines that sequence with an empty array, removing duplicate values; comparing the two array lengths then exposes repeated codes. MongoDB’s unique indexes and schema validation tutorial illustrates this complementary pattern. This inventory adapts the idea with its own domain, guard, cases, and clean-collection deployment.

The empty set supplies a second array operand; it does not supply a default asset. Empty inventories remain invalid under minItems: 1, even though their original and distinct counts would both be zero. Keeping shape and identity checks separate makes that distinction reviewable.

Save the following complete fixture as lab.js. It includes collection creation, the independent expectation manifest, isolated operations, rejection readbacks, legacy audits, and a failing exit status when an assertion is violated.

// Synthetic, disposable MongoDB 8.0 fixture. No automatic teardown.
const NAME = "refonte_multikey_lab", OWNER = "refonte-multikey-v1";
const INDEX = "tenant_asset_unique", runId = new ObjectId().toString();
let casesRun = 0;
const emit = (event, data) => print(EJSON.stringify({event, runId, ...data}, {relaxed: false}));
const same = (a, b) => EJSON.stringify(a) === EJSON.stringify(b);
function requireOK(ok, message) { if (!ok) throw new Error(message); }
function errorRecord(e) {
  return {name: e.name, code: e.code ?? null, codeName: e.codeName ?? null,
    message: e.message, details: e.errInfo ?? e.errorResponse ?? null};
}
function localGuard() {
  requireOK(db.getName() === NAME, "Select only the exact fixture database");
  const uri = db.getMongo().getURI();
  requireOK(/^mongodb:\/\/(127\.0\.0\.1|localhost|\[::1\]):[0-9]+\/refonte_multikey_lab(?:\?[^#]*)?$/.test(uri)
    && /[?&]directConnection=true(?:&|$)/.test(uri),
    "A direct loopback connection is required");
}
const asset = (code, label) => ({code, label});
const inventory = (id, tenant, assets) => ({_id: id, tenantId: tenant, assets});
const seed = () => inventory("I1", "T1", [asset("A01", "Pump"), asset("A02", "Valve")]);
const withAssets = xs => [inventory("I1", "T1", xs)];
const original = () => seed().assets;
const snapshot = c => c.find({}).sort({_id: 1}).toArray();
const shape = {$jsonSchema: {
  bsonType: "object", required: ["tenantId", "assets"], additionalProperties: false,
  properties: {_id: {}, tenantId: {bsonType: "string", minLength: 1}, assets: {
    bsonType: "array", minItems: 1, items: {
      bsonType: "object", required: ["code", "label"], additionalProperties: false,
      properties: {code: {bsonType: "string", pattern: "\\A[A-Z0-9]{1,12}\\z"},
        label: {bsonType: "string"}}
    }
  }}
}};
const distinctCodes = {$expr: {$cond: [{$isArray: "$assets"}, {$eq: [
  {$size: "$assets"}, {$size: {$setUnion: [
    {$map: {input: "$assets", as: "asset", in: "$$asset.code"}}, []
  ]}}
]}, false]}};
// This oracle deliberately uses ordinary JS, not the validator expression.
function shapeOK(d) {
  const allowed = (x, names) => x !== null && typeof x === "object" && !Array.isArray(x)
    && Object.keys(x).every(k => names.includes(k));
  return allowed(d, ["_id", "tenantId", "assets"])
    && typeof d.tenantId === "string" && d.tenantId.length > 0
    && Array.isArray(d.assets) && d.assets.length > 0 && d.assets.every(a =>
      allowed(a, ["code", "label"]) && typeof a.code === "string"
      && a.code.length >= 1 && a.code.length <= 12 && !/[^A-Z0-9]/.test(a.code)
      && typeof a.label === "string");
}
function contractOK(docs) {
  const owners = new Map();
  for (const d of docs) {
    if (!shapeOK(d)) return false;
    const codes = new Set();
    for (const a of d.assets) {
      if (codes.has(a.code)) return false;
      codes.add(a.code);
      const key = JSON.stringify([d.tenantId, a.code]);
      if (owners.has(key) && owners.get(key) !== d._id) return false;
      owners.set(key, d._id);
    }
  }
  return true;
}
function collectionMetadata(names) {
  return names.map(name => {
    const info = db.getCollectionInfos({name})[0];
    return {name, options: info.options, effectiveCollation:
      info.options.collation ?? {locale: "simple"}, indexes: db.getCollection(name).getIndexes()};
  });
}
function verifyPolicies() {
  const metadata = collectionMetadata(["baseline", "repaired", "legacyAudit"]);
  for (const m of metadata) requireOK(same(m.effectiveCollation, {locale: "simple"}),
    `${m.name}: collection collation differs`);
  for (const m of metadata.filter(x => x.name !== "legacyAudit")) {
    const indexes = m.indexes.filter(x => x.name === INDEX), ix = indexes[0];
    requireOK(indexes.length === 1 && same(ix.key, {tenantId: 1, "assets.code": 1})
      && ix.unique === true && same(ix.collation ?? {locale: "simple"}, {locale: "simple"})
      && !ix.sparse && !ix.partialFilterExpression, `${m.name}: unique index differs`);
  }
  const options = metadata.find(x => x.name === "repaired").options;
  requireOK(same(options.validator, {$and: [shape, distinctCodes]})
    && options.validationLevel === "strict" && options.validationAction === "error",
    "Stored repaired validator/settings differ");
  return metadata;
}
function test(c, spec) {
  // Reset only when the preceding case has passed. A failure stops the script.
  if (!spec.keepState) { c.deleteMany({}); c.insertMany(spec.start ?? [seed()]); }
  const before = snapshot(c);
  if (spec.keepState) requireOK(same(before, spec.start), `${spec.id}: prerequisite state missing`);
  const expected = {businessAdmission: spec.business, databaseAdmission: spec.admit,
    errorCode: spec.code ?? null, finalContract: spec.valid ?? true};
  emit("expectation", {caseId: spec.id, collection: c.getName(),
    documentId: spec.doc ?? "I1", tenant: spec.tenant ?? "T1",
    attemptedCodes: spec.codes, expected, before});
  let result = null, error = null;
  try { result = spec.write(c); } catch (e) { error = errorRecord(e); }
  const after = snapshot(c), admitted = error === null;
  const readbackMatch = same(after, spec.admit ? spec.after : before);
  const actualContract = contractOK(after);
  emit("case", {caseId: spec.id, collection: c.getName(),
    documentId: spec.doc ?? "I1", tenant: spec.tenant ?? "T1", attemptedCodes: spec.codes,
    expected, actualOutcome: admitted ? "admitted" : "rejected", result, error,
    before, after, readbackMatch, actualContract});
  requireOK(admitted === spec.admit, `${spec.id}: unexpected admission/rejection`);
  if (!spec.admit) requireOK(error.code === spec.code, `${spec.id}: unexpected error category`);
  requireOK(readbackMatch, `${spec.id}: exact readback mismatch`);
  requireOK(actualContract === (spec.valid ?? true), `${spec.id}: independent oracle mismatch`);
  casesRun++;
}
const push = a => c => c.updateOne({_id: "I1"}, {$push: {assets: a}});
const add = a => c => c.updateOne({_id: "I1"}, {$addToSet: {assets: a}});
const insert = d => c => c.insertOne(d);
function runCases() {
  const b = db.baseline, r = db.repaired;
  const baseCases = [
    {id: "B1", doc: "I2", codes: ["A01"], business: "reject", admit: false, code: 11000,
      write: insert(inventory("I2", "T1", [asset("A01", "Second pump")]))},
    {id: "B2", doc: "I3", tenant: "T2", codes: ["A01"], business: "admit", admit: true,
      write: insert(inventory("I3", "T2", [asset("A01", "Other tenant pump")])),
      after: [seed(), inventory("I3", "T2", [asset("A01", "Other tenant pump")])]},
    {id: "B3", codes: ["A01"], business: "reject", admit: true, valid: false,
      write: push(asset("A01", "Renamed pump")),
      after: withAssets([...original(), asset("A01", "Renamed pump")])},
    {id: "B4", codes: ["A01"], business: "reject", admit: true, valid: false,
      write: push(asset("A01", "Pump")), after: withAssets([...original(), asset("A01", "Pump")])},
    {id: "B5", codes: ["A03"], business: "admit", admit: true,
      write: push(asset("A03", "Meter")), after: withAssets([...original(), asset("A03", "Meter")])},
    {id: "S1", codes: ["A01"], business: "admit", admit: true,
      write: add(asset("A01", "Pump")), after: [seed()]},
    {id: "S2", codes: ["A01"], business: "reject", admit: true, valid: false,
      write: add(asset("A01", "Renamed pump")),
      after: withAssets([...original(), asset("A01", "Renamed pump")])},
    {id: "S3", codes: ["A01"], business: "reject", admit: true, valid: false,
      write: add({label: "Pump", code: "A01"}),
      after: withAssets([...original(), {label: "Pump", code: "A01"}])},
    {id: "S4", codes: ["A01"], business: "repair-existing", admit: true, valid: false,
      start: withAssets([...original(), asset("A01", "Renamed pump")]),
      write: add(asset("A01", "Pump")),
      after: withAssets([...original(), asset("A01", "Renamed pump")])}
  ];
  for (const spec of baseCases) test(b, spec);
  const repairedCases = [
    {id: "R1", doc: "I4", codes: ["A03", "A04"], business: "admit", admit: true,
      write: insert(inventory("I4", "T1", [asset("A03", "Meter"), asset("A04", "Gauge")])),
      after: [seed(), inventory("I4", "T1", [asset("A03", "Meter"), asset("A04", "Gauge")])]},
    {id: "R2", doc: "I4", codes: ["A03", "A03"], business: "reject", admit: false, code: 121,
      write: insert(inventory("I4", "T1", [asset("A03", "Meter"), asset("A03", "Meter")]))},
    {id: "R3", doc: "I4", codes: ["A03", "A03"], business: "reject", admit: false, code: 121,
      write: insert(inventory("I4", "T1", [asset("A03", "Meter"), asset("A03", "New meter")]))},
    {id: "R4", codes: ["A01"], business: "reject", admit: false, code: 121,
      write: push(asset("A01", "Pump"))},
    {id: "R5", codes: ["A01"], business: "reject", admit: false, code: 121,
      write: push(asset("A01", "Renamed pump"))},
    {...baseCases[0], id: "R6"}, {...baseCases[1], id: "R7"},
    {id: "R8", codes: ["A01", "A01"], business: "reject", admit: false, code: 121,
      write: c => c.updateOne({_id: "I1"}, {$set: {"assets.1.code": "A01"}})},
    {id: "R9", codes: [], business: "reject", admit: false, code: 121,
      write: c => c.updateOne({_id: "I1"}, {$set: {assets: "not-an-array"}})},
    {id: "R10", codes: [], business: "reject", admit: false, code: 121,
      write: c => c.updateOne({_id: "I1"}, {$set: {assets: []}})},
    {id: "R11", codes: [["A01"]], business: "reject", admit: false, code: 121,
      write: c => c.updateOne({_id: "I1"}, {$set: {"assets.0.code": ["A01"]}})},
    {id: "R12", codes: ["a01"], business: "reject", admit: false, code: 121,
      write: c => c.updateOne({_id: "I1"}, {$set: {"assets.0.code": "a01"}})},
    {id: "R13", codes: ["A01\n"], business: "reject", admit: false, code: 121,
      write: c => c.updateOne({_id: "I1"}, {$set: {"assets.0.code": "A01\n"}})},
    {id: "R14", codes: ["A01", "A02"], business: "admit", admit: true,
      write: c => c.updateOne({_id: "I1"}, {$set: {"assets.0.label": "Serviced pump"}}),
      after: withAssets([asset("A01", "Serviced pump"), asset("A02", "Valve")])},
    {...baseCases[4], id: "R15"}
  ];
  for (const spec of repairedCases) test(r, spec);
  const indexBefore = r.getIndexes(), policyBefore = collectionMetadata(["repaired"]);
  const changed = withAssets([asset("A09", "Pump"), asset("A02", "Valve")]);
  test(r, {id: "RB1", codes: ["A09", "A02"], business: "admit", admit: true,
    write: c => c.updateOne({_id: "I1"}, {$set: {"assets.0.code": "A09"}}), after: changed});
  // Dependent rollback preserves the real RB1 state instead of reseeding it.
  test(r, {id: "RB2", codes: ["A01", "A02"], business: "admit", admit: true,
    keepState: true, start: changed,
    write: c => c.updateOne({_id: "I1"}, {$set: {"assets.0.code": "A01"}}), after: [seed()]});
  const indexesUnchanged = same(indexBefore, r.getIndexes());
  const policyUnchanged = same(policyBefore, collectionMetadata(["repaired"]));
  emit("rollback-policy-check", {caseId: "RB2", indexesUnchanged, policyUnchanged,
    metadata: collectionMetadata(["repaired"])});
  requireOK(indexesUnchanged && policyUnchanged, "RB2 changed an admission policy");
}
function auditCollection(c) {
  const docs = snapshot(c), validIds = docs.filter(shapeOK).map(d => d._id);
  const malformed = docs.filter(d => !shapeOK(d));
  const prefix = [{$match: {_id: {$in: validIds}}},
    {$unwind: {path: "$assets", includeArrayIndex: "position"}}];
  const within = c.aggregate([...prefix,
    {$group: {_id: {inventoryId: "$_id", code: "$assets.code"}, tenant: {$first: "$tenantId"},
      count: {$sum: 1}, evidence: {$push: {position: "$position", item: "$assets"}}}},
    {$match: {count: {$gt: 1}}}, {$sort: {"_id.inventoryId": 1, "_id.code": 1}}
  ]).toArray();
  const across = c.aggregate([...prefix,
    {$group: {_id: {tenant: "$tenantId", code: "$assets.code"}, owners: {$addToSet: "$_id"},
      evidence: {$push: {inventoryId: "$_id", position: "$position", item: "$assets"}}}},
    {$match: {"owners.1": {$exists: true}}}, {$sort: {"_id.tenant": 1, "_id.code": 1}}
  ]).toArray();
  for (const x of within) x.evidence.sort((a, b) => Number(a.position) - Number(b.position));
  for (const x of across) {
    x.owners.sort();
    x.evidence.sort((a, b) => a.inventoryId < b.inventoryId ? -1 : a.inventoryId > b.inventoryId
      ? 1 : Number(a.position) - Number(b.position));
  }
  const actual = {within: within.map(x => ({...x._id, tenant: x.tenant, count: x.count,
    evidence: x.evidence.map(e => ({position: Number(e.position), item: e.item}))})),
    across: across.map(x => ({...x._id, owners: x.owners,
      evidence: x.evidence.map(e => ({inventoryId: e.inventoryId, position: Number(e.position), item: e.item}))})),
    malformedIds: malformed.map(x => x._id)};
  return {actual, documents: docs, within, across, malformed};
}
function auditLegacy() {
  db.legacyAudit.insertMany([
    inventory("L1", "T1", [asset("A01", "Pump"), asset("A01", "Renamed pump"), asset("A02", "Valve")]),
    inventory("L2", "T1", [asset("A02", "Spare valve"), asset("A03", "Meter")]),
    inventory("L3", "T2", [asset("A01", "Other tenant pump")]),
    inventory("L4", "T4", "not-an-array"), inventory("L5", "T5", []),
    inventory("L6", "T6", [asset(["A06"], "Invalid code type")]),
    inventory("L7", "T7", [asset("a07", "Invalid code alphabet")])
  ]);
  const expected = {within: [{inventoryId: "L1", code: "A01", tenant: "T1", count: 2,
    evidence: [{position: 0, item: asset("A01", "Pump")},
      {position: 1, item: asset("A01", "Renamed pump")}]}],
    across: [{tenant: "T1", code: "A02", owners: ["L1", "L2"], evidence: [
      {inventoryId: "L1", position: 2, item: asset("A02", "Valve")},
      {inventoryId: "L2", position: 0, item: asset("A02", "Spare valve")}
    ]}], malformedIds: ["L4", "L5", "L6", "L7"]};
  const legacy = auditCollection(db.legacyAudit);
  emit("audit", {collection: "legacyAudit", expected, ...legacy, businessDecision: "REPAIR"});
  requireOK(same(legacy.actual, expected), "Legacy audit differs from hand-enumerated evidence");
  const cleanExpected = {within: [], across: [], malformedIds: []};
  const clean = auditCollection(db.repaired);
  emit("audit", {collection: "repaired", expected: cleanExpected, ...clean, businessDecision: "ACCEPT"});
  requireOK(same(clean.actual, cleanExpected) && contractOK(clean.documents),
    "Repaired collection failed independent final audit");
}
function main() {
  localGuard();
  const admin = db.getSiblingDB("admin"), hello = admin.runCommand({hello: 1});
  const build = admin.runCommand({buildInfo: 1});
  const fcv = admin.runCommand({getParameter: 1, featureCompatibilityVersion: 1});
  const startup = admin.runCommand({getCmdLineOpts: 1});
  requireOK(hello.ok === 1 && hello.msg !== "isdbgrid" && startup.ok === 1
    && !startup.parsed.sharding?.clusterRole, "An unsharded mongod is required");
  requireOK(build.ok === 1 && /^8\.0\.[0-9]+$/.test(build.version), "MongoDB 8.0.x is required");
  requireOK(fcv.ok === 1 && fcv.featureCompatibilityVersion.version === "8.0", "FCV 8.0 is required");
  emit("manifest", {database: NAME, owner: OWNER, connectionUri: db.getMongo().getURI(),
    serverVersion: build.version, serverGitVersion: build.gitVersion,
    featureCompatibilityVersion: fcv.featureCompatibilityVersion, mongoshVersion: version(),
    topology: "unsharded mongod", clusterRole: startup.parsed.sharding?.clusterRole ?? null,
    startedAt: new Date()});
  requireOK(db.getCollectionNames().length === 0, "Target database is not empty; stop and inspect");
  db.createCollection("ownership");
  db.ownership.insertOne({_id: OWNER, runId, database: NAME});
  db.createCollection("baseline", {collation: {locale: "simple"}});
  db.createCollection("repaired", {collation: {locale: "simple"},
    validator: {$and: [shape, distinctCodes]}, validationAction: "error", validationLevel: "strict"});
  db.createCollection("legacyAudit", {collation: {locale: "simple"}});
  for (const name of ["baseline", "repaired"]) {
    db.getCollection(name).createIndex({tenantId: 1, "assets.code": 1},
      {unique: true, name: INDEX, collation: {locale: "simple"}});
  }
  emit("collections", {policyAssertions: "PASS", metadata: verifyPolicies()});
  runCases(); auditLegacy();
  emit("complete", {casesRun, fixtureStatus: "PASS", legacyDecision: "REPAIR",
    finalMetadata: verifyPolicies(),
    note: "Save this ledger before explicit teardown; legacyAudit intentionally remains dirty."});
}
try { main(); } catch (e) { emit("fatal", {casesRun, error: errorRecord(e)}); quit(1); }

Guard expression inputs instead of assuming short-circuit order

The expression starts with $cond and $isArray. Only its array branch reaches $size or $map; its other branch returns false. The MongoDB 8.0 $cond reference defines selection between the two branches. This keeps the expression safe when assets has the wrong outer type.

MongoDB’s $and error-handling rules allow a later expression to raise an error even when an earlier condition is false. Guard the expression’s own inputs instead of relying on the schema branch to protect it. The schema independently rejects invalid item structures and nonscalar codes; a cardinality comparison alone cannot establish those properties.

Review the persisted validator, not merely the source file containing it. The repaired fixture requires both validationLevel: "strict" and validationAction: "error". If metadata differs from the intended policy, stop before interpreting case results. A correct expression installed with the wrong admission settings is an incomplete repair.

Retest inserts, pushes, and edits against both boundaries

Exercise the proposed final documents through several write shapes. A duplicate insert and a duplicate-producing update are distinct regression cases: proving one does not establish that the harness actually tested the other. Retain the case identifier in every ledger row and preserve its corresponding mutation in the archived script.

The complete file also tests malformed scalar codes and the ASCII boundary. Each independent case resets to a known seed only after the previous case has passed. The runner stops on unexpected behavior, so cleanup cannot erase the first discrepancy.

For rejected mutations, compare the full before and after snapshots using Extended JSON serialization. Do not compare only modifiedCount, the targeted array length, or the visible duplicate. The contract requires the rejected attempt to leave the inspected fixture state unchanged. The serialized comparison retains field and array order in this controlled fixture.

Expected validation failures use error category 121; the cross-document collision uses duplicate-key category 11000. The harness records the actual error details instead of making a particular rendered message part of the contract. An unexpected category warrants investigation even if the document happened to remain unchanged.

For admitted operations, require the exact expected state as well as an acknowledgment. That catches a filter which matched nothing or an update which left a plausible but unintended array. A successful command without the intended readback is not a passing positive control.

Audit old documents without trusting the new validator

Treat legacy data as a separate evidence problem. A validator expression is a proposed admission policy; reusing that same expression as the only audit could reproduce the same mistake twice. The fixture therefore includes an independent shape checker and aggregation reports built around explicit item occurrences.

The within-document aggregation unwinds the assets array with its original position, groups by original inventory ID plus code, counts occurrences, and retains the complete offending items. It reports groups whose counts exceed one. This identifies the repeated logical key and preserves the evidence needed to explain each occurrence.

The ownership aggregation groups valid item claims by tenant and code, retains distinct inventory IDs, and reports groups with more than one owner. Repeated entries from a single inventory must not inflate that owner count. The result answers a different question from the within-document report.

Malformed documents are reported separately by the independent JavaScript shape oracle. Do not silently drop them from an audit and describe the remaining output as a clean collection. A shape failure means the ownership analysis is incomplete for that document until its identity is resolved.

Expected findings, also reproduced by the recorded run: L1 repeats A01 at positions zero and one, with labels Pump and Renamed pump. Tenant T1 has an A02 ownership conflict between L1 at position two and L2 at position zero. L4 through L7 have malformed shapes. L3/T2/A01 is permitted. The repaired collection’s corresponding reports are explicitly empty.

Specifically, L4 has non-array assets, L5 has an empty array, L6 has an array-valued code, and L7 has a lowercase code. Their full records remain visible even though they cannot enter the well-shaped ownership comparison.

Compare these results with the hand-enumerated fixture IDs. Check exact offending keys, inventory ownership, occurrence counts, item contents, and positions. A matching number of report rows is insufficient: the same row count could name the wrong inventories.

When applying the approach to owned legacy data, preserve an export of each affected original record together with the report. Keep the export tied to the admission boundary used for the audit so subsequent writes cannot quietly invalidate the proposed repair set. This fixture establishes audit logic on small known data; it is not a capacity measurement.

Separate diagnosis from choosing which asset survives

Two A01 entries with different labels need an owner’s interpretation. They might describe one asset twice, or reveal that two physical assets were assigned the same code. The database report cannot choose which interpretation is correct.

Prepare a change manifest naming the inventory, tenant, repeated code, every original item, proposed final items, owner, and approval. Quarantine ambiguous inventories from the repaired active dataset until that decision exists. Retain their originals for review.

Do not keep the first entry, keep the last entry, merge labels, or delete a convenient array position as an automatic cleanup rule. Those are business changes. The audit’s job is to expose the ambiguity and preserve enough evidence for a deliberate resolution.

Adopt the policy without rewriting history silently

Installing a validator changes admission behavior; it does not reconcile every existing inventory. MongoDB’s 8.0 validation-level reference distinguishes subsequent writes to existing documents from the act of adding rules. A migration therefore needs an explicit data-reconciliation phase as well as a policy-deployment phase.

Use a maintenance interval or another enforceable write-admission boundary while establishing the legacy snapshot and applying approved corrections. Name who controls that boundary, which writers it covers, and what evidence permits reopening. Do not assume that notifying the primary application also stops imports or administrative scripts.

The fixture demonstrates admission into a clean collection with its validator and unique index already installed. In a migration using this pattern, admit approved records through those rules and retain quarantined records outside the accepted dataset with an explicit disposition manifest. Reconcile source identities against accepted and quarantined identities so an omitted inventory cannot disappear behind a clean target audit.

For an existing collection, prepare an execution-specific plan: capture its options and indexes, establish the boundary, export affected records, apply owner-approved repairs, deploy or verify the reviewed validator and unique index, and repeat the independent audit and mutation cases. The commands and sequencing need review against that collection’s actual state. This article makes no zero-downtime claim.

Under strict, inserts and updates are subject to validation. Under moderate, updates to existing invalid documents are not required to become valid, while inserts and updates to valid documents are checked. That exception makes moderate unsuitable as evidence that the final inventory invariant holds throughout the collection.

If moderate validation is used in a separate transition plan, record the exception set and the criterion for ending it. A migration label must not become an indefinite permission for unresolved duplicates. The final acceptance packet must distinguish records reconciled under the full policy from records still awaiting decisions.

Reopen writes only when both the data audit and the installed-policy checks agree. Keeping that order explicit prevents a successful deployment command from being mistaken for completed migration work.

Preserve both constraints during recovery and rollback

Before changing inventory codes, retain the affected original documents, their complete arrays, index definitions, collection collation, validator, validation settings, and the approved change manifest. Associate each backup with the exact admission boundary and execution record. A detached export without its policy context leaves recovery decisions unnecessarily ambiguous.

Rehearse a permitted code change in the disposable repaired collection: change one existing code to another valid, unclaimed code, inspect the result, and then restore its original value. The harness performs this sequence while the unique index and validator remain installed. Both the forward change and reversal must satisfy the current contract.

A real reversal may no longer be admissible if another inventory has legitimately acquired the old code. Recheck current ownership before applying an approved rollback, and preserve rejection evidence if it conflicts. A historical value is not sufficient justification for overriding a current owner.

Separate application-code rollback from removal of a database safety policy. Restoring an earlier application version may be compatible with the installed constraints; removing validation would reopen the admission gap. The latter requires a separate risk decision, a named owner, and a plan for identifying writes admitted during the exception.

Preserve the repair manifest after rollback. Reviewers should be able to connect every inventory’s old identity, intended correction, actual result, and any reversal. Do not overwrite the earlier manifest with the final state and lose that chain of decisions.

Identify writers that can bypass the admission boundary

MongoDB’s 8.0 bypass-validation reference documents per-operation bypass and the relevant bypassDocumentValidation authorization action. Review client options and effective privileges with the database owner. Validation-dependent acceptance must state which writers can bypass it.

Do not enable bypass to make a rejected import succeed. Resolve the document or the approved policy. Review application clients, restore procedures, administrative scripts, and bulk-import paths; one successful mongosh test does not enumerate those writers.

The unique index remains a separate enforcement mechanism. A validation-bypass capability does not establish that the complete two-rule admission policy covers that writer. Unresolved privileged paths keep the adoption decision on HOLD.

Reconcile admitted documents and rejected operations

The evidence ledger connects the business contract to each attempted write. Store it with the runtime manifest, complete scripts, original expectations, before-and-after snapshots, and independent duplicate report. These artifacts should describe the same run, not a mixture of commands copied from different attempts.

Keep baseline discrepancies visible. A row where the business expects rejection and the index-only database admits the write explains the original defect. The corresponding repaired row should show agreement. Suppressing the baseline row would remove the evidence that the repair addresses the demonstrated boundary.

Reconcile admitted inventories by identity, including the allowed second tenant. Reconcile rejected insertions by target absence and owner preservation. Reconcile rejected updates by unchanged complete snapshots. These are different checks, even when all successful assertions end with the same Boolean result in the runner.

Record the index and validator independently. A passing internal-duplicate case does not establish cross-document ownership enforcement; a duplicate-key failure does not establish the shape policy. Require evidence for both layers plus permitted writes, so the test cannot pass by merely blocking activity.

The independent duplicate report is a required deliverable. Include empty reports for clean repaired state and the exact expected findings from deliberately dirty legacy state. An absent report is missing evidence, not an empty result. Retain malformed-document findings alongside ownership findings so their scope remains visible.

An operator developing backend and API engineering foundations can use the ledger to connect request intent with stored identity. The API’s success or error response is one part of that chain; the inspected database state completes the fixture’s evidence.

Reviewers should be able to answer three concrete questions without rerunning anything: what identity was requested, which policy accepted or rejected it, and what document remained? If the packet cannot answer one, classify the gap before approving migration work. A numeric total, an index-list screenshot, or a successful index build does not supply the missing answer.

Turn the evidence into an acceptance decision

Use a decision that names the remaining work. A reproduced database behavior and an approved deployment are different milestones. The fixture can establish the former under recorded conditions; the latter additionally depends on legacy reconciliation, ownership decisions, and the writers allowed to reach the collection.

“Fully reconciled” does not mean that a dirty inventory was silently excluded. Each source inventory must have an accepted destination or an explicit quarantine disposition. A clean active target and an unexplained missing source record are not equivalent to completed reconciliation.

The twenty-six-case PASS means that the fixture matched its expected admissions, rejections, readbacks, and audit findings. The tested repaired state satisfies the contract. The baseline deliberately admits forbidden duplicates, and the synthetic legacy dataset remains REPAIR because its known defects are preserved.

The recorded execution covers disposable synthetic inventories. It does not measure a customer incident or establish a production migration outcome. Keep the scripts, runtime manifest, case ledger, and audit reports together so another operator can distinguish a documented expectation from an outcome actually observed under the recorded conditions.

A passing fixture supports only the tested contract under its recorded server, shell, collation, and admission settings. It leaves organization-specific ownership and writer coverage to the adoption review. Use RERUN for missing reproducible evidence and HOLD for unresolved authority or identity decisions; both are more actionable than a vague “mostly ready.”

Make regression failures actionable

The script exits nonzero on unexpected admission, unexpected rejection, mismatched error category, or incorrect readback. It emits the discrepancy before stopping and preserves database state. The test runner must not deduplicate an unexpected result to make later cases pass.

Archive the evidence directory before teardown. Inspect the final manifest and ensure it belongs to the fixture instance being removed. Save this complete teardown file as teardown.js, then run the guarded command only when the original evidence is safely retained.

// Explicit cleanup only after the run ledger has been saved outside MongoDB.
const NAME = "refonte_multikey_lab", OWNER = "refonte-multikey-v1";
function check(ok, message) { if (!ok) throw new Error(message); }
check(db.getName() === NAME, "Wrong database");
const uri = db.getMongo().getURI();
check(/^mongodb:\/\/(127\.0\.0\.1|localhost|\[::1\]):[0-9]+\/refonte_multikey_lab(?:\?[^#]*)?$/.test(uri)
  && /[?&]directConnection=true(?:&|$)/.test(uri), "Direct loopback only");
const names = db.getCollectionNames();
check(names.every(n => ["ownership", "baseline", "repaired", "legacyAudit"].includes(n)),
  "Unexpected collection: refuse teardown");
const marker = db.ownership.findOne({_id: OWNER});
check(marker && marker.database === NAME, "Fixture ownership marker missing");
const path = process.env.REFONTE_EVIDENCE_FILE;
check(typeof path === "string" && path.length > 0, "Set REFONTE_EVIDENCE_FILE to saved run.jsonl");
const rows = require("fs").readFileSync(path, "utf8").trim().split("\n").map(line => EJSON.parse(line));
check(rows.some(x => x.event === "manifest" && x.runId === marker.runId), "Wrong saved manifest");
check(rows.some(x => ["complete", "fatal"].includes(x.event) && x.runId === marker.runId),
  "Saved evidence lacks a terminal record");
const result = db.dropDatabase();
check(result.ok === 1, "Teardown failed");
print(EJSON.stringify({event: "teardown", database: NAME, runId: marker.runId, result}));

# Enter the exact run.jsonl path printed by run.sh.
read -r -p 'Saved run.jsonl path: ' REFONTE_EVIDENCE_FILE || exit 1
export REFONTE_EVIDENCE_FILE
mongosh --norc --quiet \
  "mongodb://127.0.0.1:${MONGO_PORT:-27987}/refonte_multikey_lab?directConnection=true" \
  --file ./teardown.js || exit 1
# Same shell, and only the owned server started earlier:
mongod --shutdown --dbpath "$lab_runtime_dir"

If the run failed, investigate and preserve its evidence first. A subsequent attempt uses an intentionally cleared disposable fixture; it must receive a new evidence directory so the original discrepancy remains reviewable.

Assign ownership of code identity and ongoing audits

The application owner defines what a code identifies, whether reassignment is allowed, and how ambiguous legacy records should be interpreted. That owner approves the repair manifest. Database mechanics cannot determine whether two differently labeled entries describe one physical asset or two assets requiring distinct codes.

The DBA owns deployment of the reviewed index, validator, collation, and admission settings. That responsibility includes inspecting persisted metadata, planning the write boundary, preserving recovery artifacts, and checking the independent audit. The DBA should escalate unresolved identity questions instead of choosing a survivor by array position.

The release owner owns the regression gate and evidence completeness. A release packet needs the exact scripts and versions, every required case, rejected-write readbacks, and the discrepancy ledger. Where these responsibilities belong to one person, preserve the separate decisions so another reviewer can follow them.

Trigger revalidation when a schema changes, collation changes, a new import path appears, the server or shell version changes, or bypass privileges change. Include application changes that alter code construction or label editing. These events may affect either the values being compared or the paths through which documents are admitted.

Give each trigger an owner and a concrete completion criterion. For example, a new import path must demonstrate permitted writes, forbidden duplicates, and unchanged readbacks through that path under the reviewed privileges. The existing mongosh fixture remains a useful reference, but it cannot stand in for untested client behavior.

Agree on an audit cadence appropriate to the actual write paths and exception policy. Treat new duplicate or malformed-shape findings as discrepancies requiring investigation, not as records to be automatically normalized. Keep the audit’s identity keys stable enough to connect findings with earlier repair manifests.

For readers building database management career foundations, this division of responsibility is practical database work: specifying identity, installing enforcement, and making the result reviewable. It does not depend on memorizing an operator name.

Hand over the compact fixture, runtime manifest, independent audit, and unresolved-decision ledger together. A screenshot of an index list cannot explain a code policy, demonstrate rejection preservation, or tell the next operator whether a legacy inventory was quarantined deliberately.

Develop database validation judgment through structured practice

The central skill is to separate a storage constraint from the complete application invariant. In this inventory, one mechanism checks ownership across documents, another checks projected identity inside each document, and shape validation makes those comparisons meaningful. The evidence must show that each responsibility is installed and tested.

Practice also includes preserving a failed attempt, asking who can authorize an identity change, and rehearsing recovery without casually removing the policy. Those habits make a repair reviewable after its original author has moved on. A clean command acknowledgment is easier to obtain than a coherent evidence packet; the packet is what supports the acceptance decision.

Refonte Learning’s Database Administrator Essentials is listed as a three-month program with twelve to fourteen hours of weekly dedication. Its published subjects include database design, SQL optimization, backup and recovery, performance, security, and cloud database administration. These are relevant foundations for reasoning about database correctness; dedicated MongoDB instruction and this particular multikey lab have not been verified.

After preparing the fixture and evidence handoff, readers seeking structured study can review the Database Administrator Essentials curriculum. Compare its published prerequisites and content with the skills you need to practice, while keeping this article’s acceptance decision grounded in the recorded tests and approved inventory policy.