# DB Fields Registry — Spec

> **Status:** Shipped. Graduating to ai-workspace/docs/.
> **Source:** `ai-workspace/reference-data/treedata5.txt` sections 0301–0317. Registry contains 3,533 entries from the initially available data; remainder can be added by re-running `scripts/generate-field-registry.js` against updated source data.

---

## What is being built

A static registry of all known database field handle identifiers (`hCAz_Account_Code`,
`hMDz_surname`, etc.) plus a validator pass that warns when:

1. A h-prefixed identifier is used in code but is not found in the registry (`ACU-ARG-006`).
2. A h-prefixed identifier is found in the registry but with the wrong casing (`ACU-INT-003`).

Field names are **not** string literals passed to functions. They are bare identifiers used
directly in code expressions (RHS of assignments, function arguments). Currently, all
h-prefixed identifiers are whitelisted by `isDatabaseHandle()` without any registry check.

---

## Design decisions

| Question | Answer |
|---|---|
| Which functions take field names as string args? | None. Field names appear as bare identifiers, not string literals. |
| Severity for unknown field name | Warning (ACU-ARG-006). Never error — the data model evolves and the registry may lag. |
| Case sensitivity at runtime | Case-insensitive. Unknown-case usage gets a separate case-mismatch warning. |
| Source data | `treedata5.txt` section 0301+. One-time import; registry is a committed static file. |
| Dataset completeness | Proceed with currently available data. Registry will expand as more data is sourced. |

---

## Diagnostic rules

### ACU-ARG-006 — `invalidFieldName` — warning
```
"'{name}' does not match any known database field handle."
```
Fires when a h-prefixed identifier (matches `isDatabaseHandle()` pattern) is used in code
but is not found in the registry under any casing.

### ACU-ARG-007 — `fieldHandleCapitalization` — warning
```
"Field handle '{name}' should be '{canonical}'."
```
Fires when a h-prefixed identifier IS found in the registry but with wrong casing.
Note: originally designed as ACU-INT-003 but ACU-INT-003 was already assigned
(interpolationUnclosed). Assigned ACU-ARG-007 at implementation time.

---

## Source data format (treedata5.txt)

```
<entry_id>:<parent_id>:<field_name>:<type>::<help_url>
```

Field name entries appear at depth 3 (8-digit entry IDs like `03010000`). The field name
column contains h-prefixed identifiers. The 2-letter table code is embedded in positions 1–2
of the field name (e.g. `hCAz_Account_Code` → table `CA`).

Example lines:
```
03010000:030100:hCAz_Account_Code:STRING::hCA.htm
03010001:030100:hCAz_Account_Type:STRING::hCA.htm
```

Parsing filter: lines where the entry ID is 8 digits long AND the name column matches
`/^h[A-Z]{2}[a-z]_/`.

---

## Registry design

File: `core/src/builtins/fieldRegistry.js`

```js
// Generated from ai-workspace/reference-data/treedata5.txt
// Key: lowercase field name; Value: { canonical, type, tableCode }
const FIELD_REGISTRY = {
    "hcaz_account_code": { canonical: "hCAz_Account_Code", type: "STRING", tableCode: "CA" },
    // ... ~10,533 entries
};

function isKnownFieldHandle(name) { ... }
function getFieldEntry(name) { ... }    // returns { canonical, type, tableCode } or null

module.exports = { FIELD_REGISTRY, isKnownFieldHandle, getFieldEntry };
```

---

## Registry generator script

File: `scripts/generate-field-registry.js` (dev-only, not shipped in VSIX)

Reads `ai-workspace/reference-data/treedata5.txt`, filters to 8-digit entry IDs with
h-prefixed names, outputs `core/src/builtins/fieldRegistry.js`. Run once; commit the output.

```
node scripts/generate-field-registry.js
```

---

## Validator integration

The new check runs inside `variableValidator.js` (or a new `fieldNameValidator.js`),
alongside the existing variable checks. When a reference to an h-prefixed identifier is
encountered and passes `isDatabaseHandle()`:

1. Look it up in `fieldRegistry` case-insensitively.
2. If not found → emit ACU-ARG-006.
3. If found but canonical casing differs → emit ACU-ARG-007.
4. If found with correct casing → no diagnostic.

The existing `isDatabaseHandle()` whitelist continues to suppress ACU-VAR-001 (undefined
variable) for all h-prefixed identifiers regardless of registry presence — the new diagnostics
are advisory warnings, not errors.

---

## TDD requirement

Write a test in `test/syntax-tests/db-field-names/` before implementing the validator.
Cover: known field (clean), unknown h-prefixed identifier (ACU-ARG-006), correct field with
wrong casing (ACU-ARG-007).

---

## Graduation

Promote to `ai-workspace/docs/` once shipped. If the dataset is later expanded, update the
registry by re-running the generator script and committing the new file — no spec changes needed.
