Blocking is invisible

A business may block an AI group — a company and its affiliates, never a single key. The block is in force in every region within seconds, for every key in the group, including keys registered later. From then on:

• its rows are absent from your searches;
• its records answer a fetch exactly as a record that never existed: the same 404, the same problem body, no sooner than 20 ms after arrival;
• nothing says so. No field, no count, no error, no band or aggregate anywhere in the API or the AI Portal that could be differenced. Your usage has no figure about blocks.

A business whose records MasterDB has taken out of serving, and a record its business withdrew or deleted, look the same from outside.

TypeScript

samples/typescript/blocking.ts

// Blocking is invisible: a business that blocked your group is simply absent. Nothing says so —
// not a field, not a count, not an error — and its records answer exactly as a record that never existed.
import assert from 'node:assert/strict';
import { createPrivateKey } from 'node:crypto';
import { readFileSync } from 'node:fs';
import { SANDBOX, createEd25519Signer, createRetrievalClient } from '@masterdb/client';

const signer = createEd25519Signer(createPrivateKey(readFileSync(process.env.MASTERDB_KEY_FILE as string)));
const client = createRetrievalClient({ baseUrl: process.env.MASTERDB_API_URL ?? SANDBOX.retrieval, signer });

// In the sandbox corpus, Saffron Mill (a fictional business in GB, IE and US) blocks the group of
// "MasterDB Sandbox AI", the sandbox AI company, so that blocking can be seen from the AI side.
const SAFFRON_MILL = '0c148394-9635-498d-84bc-f4a785a948c5';
const saffronProduct = 'mdb_34gueyd2qiuyxomxzrixasiunt';
const neverPublished = 'mdb_aaaaaaaaaaaaaaaaaaaaaaaaaa';

const blocked = await client.GET('/v1/records/{record_id}', { params: { path: { record_id: saffronProduct } }, parseAs: 'text' });
const absent = await client.GET('/v1/records/{record_id}', { params: { path: { record_id: neverPublished } }, parseAs: 'text' });
console.log(blocked.response.status, blocked.error);
console.log(absent.response.status, absent.error);
assert.equal(blocked.response.status, 404);
assert.equal(absent.response.status, 404);
// The same problem body; its `instance` only echoes the path you asked for.
const { instance: _a, ...blockedBody } = blocked.error as Record<string, unknown>;
const { instance: _b, ...absentBody } = absent.error as Record<string, unknown>;
assert.deepEqual(blockedBody, absentBody);

// Search results never include its rows, and nothing in the response counts what is missing.
const search = await client.POST('/v1/search', {
  body: { collection: 'products', filter: { all: [{ country: 'GB' }] }, sort_by: 'published_at:desc', limit: 50 },
});
if (search.error) throw new Error(search.error.code);
assert.ok(search.data.rows.every((row) => row.business_uuid !== SAFFRON_MILL));
assert.deepEqual(Object.keys(search.data).sort(), ['collection', 'country', 'receipt', 'retrieval_id', 'rows'].sort());
console.log(`${search.data.rows.length} rows in GB, none from a business that blocked this group`);

Python

samples/python/blocking.py

"""Blocking is invisible: a business that blocked your group is simply absent. Nothing says so —
not a field, not a count, not an error — and its records answer exactly as a record that never existed."""

import os

import httpx
from masterdb_signing import SANDBOX_API, MasterDBAuth, load_key

client = httpx.Client(
    base_url=os.environ.get("MASTERDB_API_URL", SANDBOX_API),
    auth=MasterDBAuth(load_key(os.environ["MASTERDB_KEY_FILE"])),
)

# In the sandbox corpus, Saffron Mill (a fictional business in GB, IE and US) blocks the group of
# "MasterDB Sandbox AI", the sandbox AI company, so that blocking can be seen from the AI side.
SAFFRON_MILL = "0c148394-9635-498d-84bc-f4a785a948c5"
saffron_product = "mdb_34gueyd2qiuyxomxzrixasiunt"
never_published = "mdb_aaaaaaaaaaaaaaaaaaaaaaaaaa"

blocked = client.get(f"/v1/records/{saffron_product}")
absent = client.get(f"/v1/records/{never_published}")
print(blocked.status_code, blocked.json())
print(absent.status_code, absent.json())
assert blocked.status_code == absent.status_code == 404
# The same problem body; its `instance` only echoes the path you asked for.
strip = lambda problem: {k: v for k, v in problem.items() if k != "instance"}  # noqa: E731
assert strip(blocked.json()) == strip(absent.json())

# Search results never include its rows, and nothing in the response counts what is missing.
search = client.post("/v1/search", json={"collection": "products", "filter": {"all": [{"country": "GB"}]}, "sort_by": "published_at:desc", "limit": 50})
search.raise_for_status()
result = search.json()
assert all(row["business_uuid"] != SAFFRON_MILL for row in result["rows"])
assert sorted(result) == ["collection", "country", "receipt", "retrieval_id", "rows"]
print(len(result["rows"]), "rows in GB, none from a business that blocked this group")

Why nothing says so

A business may not want to tell an AI company it has chosen not to be represented by it, and MasterDB chooses the business’s silence over the AI company’s certainty. For the same reason, MasterDB offers no completeness proof: a proof that “these are all the rows” would let a blocked company detect the exclusion by arithmetic.

The limits

A block is hidden on MasterDB’s surfaces. From outside MasterDB it can be inferred: by comparing results with another AI company, from a business’s own website, or by presenting a record you hold to the public verify endpoint (which answers for anyone who has the record).

What it means for your integration

Treat every absent result the same way: the record is not available to you. Do not retry a 404 in the hope of a different answer, and do not build logic that assumes a business’s catalogue is complete in your results.