docs/knowledge-register.md
Linked repository file from this build.
# Iris knowledge register
Status: current. Reconciled September 13, 2026.
The [review specification](./snap-negative-vertical-slice-minimal-spec.md) controls behavior.
This register separates source evidence, application decisions and unresolved policy.
The user confirmed [FS-Neg-fields-and-values.md](./FS-Neg-fields-and-values.md) as the current
field authority. The VBA transmission writer is obsolete. Current fields and leading-zero
codes do not establish federal wire compatibility. The local workbook has FS Neg and FS
Computation only. Its BF:BH element/nature lookup was transcribed to
`src/programs/snap-negative/nature-catalog.json`.
The sibling repository `/home/phantompc/dev/vba` was read without changes at `82d3de5`.
The separately supplied `FS Negative Template Workbook.xlsm` is untracked there.
| Fact | Source |
| ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- |
| Negative preflight uses File of Records and BIS Negative. FOR sheet is FS Cash main file. | `populateMacrosV2/modules/Core_Preflight.vba`, `Run_Populate.vba` |
| Review prefixes are 60, 61, 65 and 66. | `Core_Types`, operator confirmation |
| Negative installs FS Computation only. | `Config_Settings.GetPopulateMutableRangeSpecs` |
| Edit check requires F29 and E52/N52 if F29 is 1. Passing stamps AQ17. | `Run_Review.RunEditCheckSNAPNegative` |
| Final selection uses sole populated column, then smallest absolute error, Comp I on a tie. | `Review_SNAP_Utils.ApplyFSComputationResultsToSchedule` |
| Selected values and income synchronize to Final SAQC. | Same routine and `SyncFSComputationIncomeToSchedule` |
| Historic folders use Clean/Error/Drop. Examiner labels now use Valid/Invalid/Drop. | `Review_Approval.vba`, September 13 program-manager demo corrections |
No executable Negative central/batch check module was found. The app's full check means
its versioned template checks, not parity with an unavailable ruleset. Items 12b/11 and
14b/Section V supply the implemented cross-field implications. Other programs remain
separate: Supplemental prefix 55, TANF CAR prefix 34, and MA population without BIS in V2.2.
TANF is not sent to QCS. These facts do not extend Negative intake to those programs.
## Verified Negative delimited intake map
`BIS Delim/SNAP/Module2.vba` imports closed/suspended and rejected pipe files with double-quote
text qualifiers. It copies rejected A:AP rows into the closed/suspended workbook and inserts
A30:AP30 headers. It does not move columns or import individuals. Module1's column moves
belong to other SNAP files and must not be applied to Negative.
The Negative branches of `Files of Record/{HBG,PGH,SE}/Delimited_File_Mod.vba` use the same
map below. `Log of Records/Delimited_File_Mod.vba` repeats that identity map, with explicit
county-area mapping and its AP office filter commented out. The population action map
comes from `populateMacrosV1/populate_snap_neg_delimited_mod.vba` and V2 `Pop_SNAP`.
| Raw column | Meaning and application destination |
| ---------- | ------------------------------------------------------------------- |
| A | QC review number |
| B | Case-record marker. Log of Records accepts C/A and rejects I. |
| C | A Denial, C Termination, S Suspension. Review action codes 1/2/3. |
| E / F | Sample month / year, combined to YYYY-MM |
| G / H | County / district |
| I | Case number |
| J | Category in FOR. Preserved in raw lineage, not a new Negative fact. |
| K | Action date, YYYYMMDD first, plus supported date text |
| S | Notice date except for Suspension, whose notice is blank |
| W | Street address |
| Y / Z / AA | City / state / first five ZIP characters |
| AC / AD | Last / first name |
| AO | Examiner ID |
| AP | Field office used to select HBG/PGH/SE FOR rows |
The parser requires exactly 42 columns and preserves quoted pipes and doubled quotes.
It rejects individual markers. Blank B remains accepted for existing attested synthetic
fixtures. The app imports program-scoped samples, so it does not copy the legacy regional
FOR filter or infer staff assignment from AP. Source rows and file/line metadata remain
in lineage. The synthetic attestation is an application guard, not a BIS column.
Imports start with no verified household, income, final result or examiner outcome. The
server stamps the selected dated policy and examiner received snapshot. Source refresh
preserves existing algorithm and policy bindings. It cannot refresh a Dropped record.
## Computation evidence
The workbook's V65:AE84 supplies household rows 1-20, not an extrapolation from size 8.
Size 20 has gross $20,042, net $10,024, standard deduction $299 and allotment $4,405.
Size 10 net is $5,434 as stored. SUA comes from AB17:AC21. These are workbook values,
not an independent certification of in-force policy.
The April 2026 synthetic example gives Comp I $608 and Comp II $488 versus Eligibility $0,
so Comp II wins. Net-limit equality uses `<=` as an explicit retained demo assumption.
Education line 4 is `MAX(line2-line3,0)`. Line 5 adds it to line 1. The earned deduction
uses line 1. Proration uses monthly benefit, a 30-day month, whole-dollar rounding down,
zero at day 31, and zero when monthly benefit is at most $10. A blank day is unprorated.
The dead line-32 branch references `FS Workbook!L1510`, a Positive sheet absent from this
Negative template. T91:V96 PA CAP values do not authorize Negative CAP rules. PA CAP is
not a question or a blocker. Legacy values are ignored.
### AF self-employment transcription
Read directly from the supplied workbook's FS Computation worksheet XML before coding.
The first AF calculation uses AG result cells, with repeated blocks for the other columns:
| Cell | Formula / role |
| --------------------- | ------------------------------------------------------------ |
| AG8 / AG9 | Farm monthly gross / costs |
| AG10 | `IF(AG8-AG9>0,AG8-AG9,0)` farm gain |
| AG11 | `IF(AG8-AG9<0,AG8-AG9,0)` signed farm loss |
| AG13 / AG14 | Non-farm gross input components |
| AG15 | `AG13+AG14` |
| AG16 | `AG15+AG10` |
| AG17 | Allowable expenses |
| AG18 | `AG16-AG17` |
| AG19 | `AG18+AG11` combined net after farm loss |
| B12 / C12 / D12 / E12 | Include the respective block net only if positive, on line 1 |
| B26 / C26 / D26 / E26 | Absolute negative block net, otherwise zero, on line 8 |
| C27 / D27 / E27 | Subtract line-8 loss from gross on line 9 |
B27 in Eligibility adds line 8 while the other columns subtract it. The September 13 spec
explicitly requires subtraction. Calculation v4 subtracts it consistently and does not
claim exact execution parity with that anomalous Eligibility cell. Gross equal to costs
produces zero gain/loss. Farm loss offsets combined non-farm net before the profit/loss split.
Version v4 adds this behavior and dated policy. Versions v1-v3 retain their prior formulas
and policy windows. The initial v4 table uses $58 for FFY 2026 and 100% actual expense
allowances. A new FY27 draft uses $59. No FY27 limits/allotments have been published or
invented. Default CAO response days remain unset until supplied by the publisher.
## Workflow decisions from the demo
Approval is separate for supervisor, PEC, memo and reporting release. Manager supervisor
coverage does not skip manager perusal. Only the examiner edits federal facts. Kickback
is the correction path. Drops pass supervisor and manager, skip PEC/memo/error summary,
and use manager approval for transmittal inclusion. No FNS drop or likely-conclusion
conditions are encoded or inferred from narrative text.
Memos are generated from state after PEC and edited by the manager on the review. Memo
approval records outbound status only. The manager tracks CAO-reported root cause and a
visible, editable deadline. Reporting release needs CAO agreement with root cause, or
recorded no response after the deadline. A dispute blocks release and cannot be overwritten
as no response. Actual memo sending remains for a later iteration.
`1` is not a universal correct answer. Finding 1 is Valid, but disposition 2 is NSTR,
notice requirement 4 can mean no requirement and no notice, and procedure 3 means not
required. Notice reason accuracy uses 11/12/21/22/99. Recorded reasons and contact codes
have their own meanings. The catalog is not a defect map. New non-drop supervisor routing
and memo classification are blocked until management supplies the map.
Exactly one element and one nature are exposed in new edits, memos, Program Error Summary
and transmittal output. Storage keeps an array and historic extras remain readable. Restore
can retain an unchanged historic array, but cannot add or change extra pairs.
## Persistence and performance decisions
The server command schema owns transport types. Server execution owns authorization,
state and cross-record guards. Snapshot/index/events commit together, and shared append-race
recovery checks actor access before replaying or returning a stale revision. Normal draft
previews coalesce repeated edits and copy only mutable branches. Server replay clones.
Received snapshots hold facts/identity/outcome, not Activity. Clear and Reset are ordinary
fact commands with Activity evidence. A short client undo stack retains pre-change state
across saving and tab switches, including section Clear/Reset. It is not server history.
A restored stale Final Result stays stale. Computation edits remain explicit column drafts.
Clerk unsafe metadata stores autosave and computation-diff preferences, both off by default.
Save/navigation/page-hide remain active with autosave off. Appearance and notifications
also use unsafe metadata. None of those preferences grants role or review scope.
Initial workspace, search and Home data arrive with the route. Ordinary search uses the
index, and advanced search selects only requested display paths. Ordered common-field
sorts use indexed columns without a snapshot join unless a filter needs one. Sorts use
stable review-number ties. Review lists remain SQL-paginated with small projections.
Export counts aggregate in SQL from the required eligibility projection.
Reviews/Approval Queue/Home/sidebar use five-minute visible-tab refresh. Notifications have
one poller, ten compact rows before scroll and explicit clearing. Bulk clear applies the
recipient, program and preference scope at a cutoff so newer events remain unread.
Reader storage versions determine unread reviews, independently of notification settings.
## Identity and downstream limits
The fixed synthetic roster has examiners 101-108, supervisors 201/202, manager 301, admin
401, statistics 501 and PEC 601. The baseline is FFY 2026, seed 42. Review 60001 belongs to
examiner 101 and resets to the fixed September fixture. Historic approvals do not fabricate
new release flags. The migration invalidates old report projections before backfill.
Clerk public metadata supplies role, staff ID and program. Missing setup shows a blocking
message with missing/invalid fields and QC administrator contact. Development View as uses
a short-lived ticket after sign-out. Local browser tests need a matching explicit secret.
The server never accepts a client-selected actor as authorization.
ERC is the old Error Reporting Call. The product name is Program Error Summary. It reads
manager release, not general approval or a guessed PEC root cause. Its breakdown uses the
first recorded pair. Internal CSV runs retain filters/time for the page session only.
`findingMemoMacros/v2/erc_epp_database_entry_v2.vba` and the April 2026 table dump identify
`tblTANF_MA_SNAP_Records`, keyed by QC_Record_Number, Program_Type and FFY. Shared Record_Number
and Review_Month are verified. The old writer hardcodes MA and has no configured database
path. The downloadable EPP adapter uses an explicit SNAP marker without asserting a write.
Corrective Action owns the external tracker. Receiver surname/area/district/date/hyperlink
mappings are not inferred.
The transmittal field TSV uses release flags plus manager-approved Drops. Staff perform
QCS portal upload. The obsolete `$!!0ZY` envelope does not define the current form contract.
No federal API, certified wire format, external EPP write or email delivery ships here.
## Open management decisions
1. Which Review-tab codes are PEC defects and how those findings select memo types.
2. Who can flag a Valid case with no defect codes for PEC, if anyone.
3. The path when a CAO correctly names another assistance office as the responsible office.
4. Extra coded fields per drop kind, without an application FNS conditions ruleset.
5. Narrative template bodies. Preset selection must not insert guessed paragraphs.
6. The eventual Activity log policy. This iteration retains the log.
Review numbers are unique within each FFY. Storage,
intake and links use FFY plus review number. This application contains only SNAP Negative;
adding another program requires a separate identity decision.
Before broader deployment, verify dated policy, compare workbook execution,
certify the federal file contract, and complete records management,
identity hardening and retention requirements. Current validation and its limits are in
[implementation status](./implementation-status.md).
The September 13 browser checks confirmed modal income Add/Edit, Escape dismissal, saved
computation undo, section undo, and the shared Policy navigation. Full validation counts
and the test-environment limits are in implementation status.
September 21 intake layout verification: all 42 user-confirmed headers and their
uses are recorded in [BIS Negative input fields](./bis-negative-input.md). The parser
accepts an optional exact-order header row and includes address line 2, middle
initial and telephone. Other source fields remain in exact raw lineage pending
confirmed destinations/code meanings. Synthetic attestation remains required.