PII-free accounts (limited-pii)

A PII-free account stores no plaintext name, email, phone, or postal address in its warehouse. People are matched and found by SHA-256 hashes (person_hash_email, person_hash_phone) and plugin remote ids, so the account can still dedupe, segment, attribute, and report. Use this skill to turn the feature on, remove leftover plaintext from an existing account, verify it, and troubleshoot.

Quick reference

Concepts

The setting

exclude_pii on @engine9/schemas/utilities/limited-pii is the only answer to "is this account PII-free?" Core and the server read it for:

• Install refusal (plaintext plugins and stacks/standard)
• installDefaultPlugins choosing the limited-pii stack
• Skipping leftover plaintext plugin rows in the inbound weave
• Default export table lists and inventory

The limited-pii stack is what new-account setup installs when the setting is on. Libraries do not detect the stack, and the stack has no exclude list. Removing plaintext from an account that already has it is a reviewed server process, not flipping the setting alone.

Different rows, not a flag in the load. When a load starts it reads the plugin table and weaves the inbound steps of whatever is installed. A PII-free account has person_hash steps and no plaintext steps (and with the setting on, leftover plaintext rows are skipped). See the inbound pipeline.

Hashing. Email is trimmed and lowercased, then SHA-256 hashed to email_hash_v1. Phone is normalized to digits (+1 for US ten-digit numbers), then hashed to phone_hash_v1. MD5 (*_hash_md5) is computed only from plaintext and is empty forever for hash-only sources. A source that already supplies email_hash_v1 / phone_hash_v1 is accepted as is. Hashes are pseudonymous match keys, not anonymous: anyone holding an email can compute its hash and test for a match.

What the setting stops. It stops new installs of plaintext plugins and removes plaintext steps from the load. It does not delete anything that already exists. Existing plaintext is hashed, then removed, by the pii-removal flow.

What is PII-free and what is not

Rule: Hashes are not a substitute for consent or policy review. Tell the account owner they are pseudonymous.

Workflow

New account

Two steps, in this order. Sign in first (e9-mcp).

- [ ] plugin install  @engine9/schemas/utilities/limited-pii   (returns the plugin id)
- [ ] plugin setSetting  plugin_id=<that id>  name=exclude_pii  value=true
- [ ] installDefaultPlugins (MCP task, or e9 pluginworker installDefaultPlugins -a <account_id>)
- [ ] Verify

{ "command": "install", "account_id": "<account_id>", "path": "@engine9/schemas/utilities/limited-pii" }
{ "command": "setSetting", "account_id": "<account_id>", "plugin_id": "<utility plugin id>", "name": "exclude_pii", "value": true }

e9 pluginworker installDefaultPlugins -a <account_id>

On the server, bootstrapAccount({ exclude_pii: true }) does both steps (utility + setting, then default plugins).

Rule: Set exclude_pii before installDefaultPlugins. The setting is what steers the install and blocks plaintext plugins. The stack is only the install list.

Existing account: pii-removal

Server only. Core sites that already hold plaintext are out of scope for this flow; they can start PII-free (new account) and respect the setting, but removal/uninstall/backfill live on PIIWorker.

Hashes are captured before any plaintext is dropped. MD5 exists only where plaintext existed. Hashes are pseudonymous.

- [ ] Schedule flow_id "pii-removal" (first task paused for review)
- [ ] Review the plan (names and counts only). Set owner choices on createRemovalPlan if needed:
      discard_names, drop_findings ("table" or "table.column")
- [ ] Confirm: un-pause / run removePii with the plan hash
- [ ] verifyRemoval

{ "action": "schedule", "account_id": "<account_id>", "flow_id": "pii-removal" }

createRemovalPlan writes a plan file with plan_hash. Sections include plaintext plugin rows, person name columns, hash-capture counts, legacy tables, other scan findings, raw input-store files (report only), and blockers. Approval is the plan hash passed to removePii / verifyRemoval.

removePii order: install person_hash → turn on exclude_pii → migrate legacy person_identifier to compact if needed → backfillPersonHash → gate (nothing still missing) → uninstallPlugin each plaintext plugin with drop → upgrade with drop_name_columns (and discard_names when chosen) → drop legacy and approved findings → installDefaultPlugins.

MCP plugin uninstall calls PIIWorker.uninstallPlugin for a single plugin (account admin). Options: id or path, drop, dry_run.

Rule: Do not drop a table, column, or plugin row without the owner's approval of the plan hash. Report the plan first.

Rule: Never pass discard_names unless the owner chose it. Names on person have nowhere else to go on a PII-free account.

Rule: Raw input-store files are reported only. Deleting them breaks future identity rebuilds and is a separate owner decision. Backfilling hashes from raw files is only through a separate identity rebuild.

Hash capture alone

Any server account can run backfillPersonHash without removing anything: it installs person_hash, backfills from person_email / person_phone / transaction contact columns / person_identifier hash rows, and search and segments by hash work immediately.

{
  "action": "schedule",
  "account_id": "<account_id>",
  "path": "@engine9/plugins/e9workers:PIIWorker",
  "method": "backfillPersonHash",
  "options": { "dry_run": true }
}

Run again without dry_run to write. Re-runs write nothing new. missing is the gate the removal flow uses before drops.

Verify

Rule: pii_free: true means the setting is on. It does not prove the data is gone. Always run the table and column checks (and verifyRemoval after a removal).

Regular audit (pii-audit)

PIIWorker.buildPiiSummaryFile scans every base table with the same sampling and classifier as scanTables and writes <account root>/pii/summary.json.gz. It is read only and works on any account, PII-free or not. Schedule the built-in flow pii-audit on a recurring basis to catch PII that new plugin loads bring in.

task schedule { "account_id": "<account_id>", "flow_id": "pii-audit" }

Read it with GET /data/pii/summary (204 until the first audit), MCP file pii/summary.json.gz, or Conductor /pii. Run the audit on demand with POST /data/pii/build or the Run audit button.

Rule: The summary holds table and column names, statuses, and counts only. Do not add sample values to it.

Rules

Rule: exclude_pii is the one check. The limited-pii stack is only what new-account setup installs.

Rule: Never install @engine9/schemas/stacks/standard, person_name, person_email, person_phone, person_address, or transaction/contact_details on a PII-free account. With exclude_pii on, core refuses them.

Rule: Do not read names, emails, or phones to prove a leak. Report column names, counts, and a masked pattern, not the values.

Rule: Do not add a plugin that writes plaintext (custom fields, vendor tables) to a PII-free account without the owner's review.

Troubleshooting

Related documentation

• Person hash plugin
• Inbound pipeline and the weaver
• Install plugins on accounts
• Upgrades and drop_name_columns
• Person identity
• Exports
• Custom fields
• Task API / flows