i3 · Help

01 · The seven laws

Every one of them exists because something specific broke. The red line is what it prevents.

binding on all 15 modules

1

Opening balance first

No module ships until its opening state is loaded and signed off by the responsible manager. Phase 0 is a real physical count, or an accepted snapshot marked unverified.

Prevents: sellable -140,753

2

Reconcile-gated phases

A phase closes only when its ledger agrees with an external truth within tolerance for 7 consecutive days. GATE 0 to GATE 8.

Prevents: shipping on a number nobody checked

3

Events in, never edits

Append-only hash-chained ledger with balance_after. A mistake is fixed by a compensating row, never by editing history.

Prevents: silent restatement of the past

4

Two ledgers, one truth

A quantity ledger keyed (SKU x location x stock_type) and a unit ledger keyed by RFID EPC serial, continuously reconciled against each other.

Prevents: "we have 12" with no idea which 12

5

Composites are first-class

style_groups → skus → recipe_components. A composite sale posts recipe_transform component rows only. The parent never gets a ledger row.

Prevents: phantom parent stock

6

Siblings push, i3 owns

ops2, CSD, GRN, Shopify, RFID and IWMS push signed events. i3 alone decides what they mean for stock. Nothing else writes stock.

Prevents: five systems, five answers

7

Continuous-fix

Every data-quality scenario ships a rule-based fix that scans the whole table, plus a recurring sync that owns it. Never a one-shot patch on one row.

Prevents: the same bug reported twice

?

If a law is inconvenient

Then the design is wrong, not the law. Raise it in the module spec's open questions. Do not route around it in a page.

See any docs/modules/NN-*.md section 12

02 · The 16 stock types

Three dimensions. A unit is in exactly one type at any instant, at exactly one location. Moving between types is a ledger row, never an edit.

5 condition6 custody3 program2 new in i3

Stock type	Dimension	Sellable	Owned by	Enters on	Leaves on	Where you see it
STOCK	Condition	yes	i3	GRN accept, return restock, transfer receive	sale, transfer out, damage, write-off	inventory-live
DISPLAY_GOOD	Condition	store only	Retail	display allocation at a store	quick-sell, return to stockroom, damage	location-detail
DISPLAY_DAMAGED	Condition	no	Retail	display unit found damaged	triage to repair, write-off or discount sale	damages
QUARANTINE	Condition	no	QC	QC hold, suspect batch, customer claim	QC decision to any of 5 buckets	grn
WRITTEN_OFF	Condition	no	Finance	approved write-off only	terminal · nothing leaves	damages
IN_TRANSIT_CUSTOMER	Custody	no	ops2	dispatch scan, gate verify	delivered, NDR, RTO	rfid
IN_TRANSIT_RETURN	Custody	no	CSD / ops2	return AWB created and picked up	returns scan at HQ_319	returns
LOST_IN_TRANSIT	Custody	no	ops2	carrier declares loss, or 21d no scan	claim settled, or found	drift
RTS_PENDING	Custody	no	Ops	staged for return to supplier	RTS shipped to supplier	rts
RESERVED	Custody	held	CSD	hold placed for an exchange or a VIP	hold released, or converted to a sale	returns
RECEIVED_NOT_INVOICED	Custody	no	Finance	GRN posted before the supplier invoice	invoice booked · 72h SLA	grn
INFLUENCER_POOL	Program	no	Marketing	allocation to the influencer pool	loan dispatched, gifted, or returned to STOCK	influencer
SAMPLE_POOL	Program	no	Marketing	sample classified as pool after QC	consumed, gifted, or returned to STOCK	samples
SAMPLE_QC	Program	no	Marketing	sample received from a supplier	classified within 72h to POOL or STOCK	samples
IN_PRODUCTION	Condition new	no	i3	PO line confirmed into factory WIP	PI issued, moves to GIT_INBOUND	production
GIT_INBOUND	Custody new	no	i3	PI shipped, goods left the supplier	GRN receipt at HQ_319	git

In i2 these last two were virtual locations, which made "how much is in production for PO-2026-118" unanswerable. In i3 they are stock types, so they are queryable per PO line.

03 · Ledger vocabulary

These 18 words explain almost every "the number looks wrong" question. Learn them once.

Audit log ↗

ledger_entriescore

The append-only quantity ledger. One row per movement of one SKU at one location in one stock type. Never updated, never deleted.

quantity_deltacore

Signed change this row makes. A sale is negative, a receipt is positive. A transfer is two rows that sum to zero.

balance_aftercore

The running balance for that key immediately after this row. If balance_after disagrees with the sum of deltas, the chain is broken and everything downstream is suspect.

hash chaincore

Each row hashes its own contents plus the previous row's hash. A nightly verify job walks the chain. Tampering is detectable, not preventable.

idempotency_keycore

Uniqueness is the pair (source_system, idempotency_key), never the key alone. Two systems may legitimately use the same key string.

compensating rowcore

The only way to fix a wrong posting. A new row with the opposite delta and a link to what it reverses. History stays intact.

movement_chaincore

The ordered hops a unit must pass through. Hops cannot be skipped: a unit cannot go from STOCK to delivered without passing IN_TRANSIT_CUSTOMER.

unit_ledgerrfid

The serial-level ledger keyed by EPC. Says which physical unit, where, and when it was last seen by a reader.

recipe_transformcomposite

The posting a composite sale produces: component rows only. Selling one BX-MSR31 posts minus one of each child, and nothing at all against BX-MSR31.

set availabilitycomposite

Computed as min(child availability) at read time. Never stored. If you store it, it goes stale the moment a child moves.

sku_aliasesregistry

Old SKU strings that still resolve. Shopify keys on variant.id, not the SKU string, because renames are routine.

scenario_codeclassifier

Which of the roughly 50 rules classified this event. An unmatched event gets no posting and lands in the drift queue instead.

shadow modeclassifier

A rule that fires and records but posts nothing. Every new rule starts here until its hit rate is proven.

drift caserecon

A recorded disagreement between i3 and an external truth, with evidence attached. Open, investigating, resolved or accepted.

sellablederived

STOCK minus RESERVED at sellable locations. It is derived, so it can never be adjusted directly. Adjust the thing underneath it.

on-handderived

Every physically present type at a location. Includes DISPLAY_GOOD and QUARANTINE. Bigger than sellable, always.

authorityconflict

Who wins when two systems disagree about one fact. See the matrix below. RFID gate reads beat every claim about physical existence.

reconciliation identitygate

opening + receipts - sales +/- adjustments +/- returns = closing, with zero unexplained residual. Every gate tests it nightly.

04 · Why is my number wrong

Work down the tree. Stop at the first yes. Nine cases out of ten it is one of the first three nodes.

do not hand-edit a balance

What it actually turned out to be

Last 90 days · 214 "the number is wrong" reports, by root cause

214 reports

Sellable vs
on-hand 71Composite
parent 48Missing
GRN 34Sibling
silent 22Classifier
miss 17Timing
12Real drift
8Chain
break 2

55% of all reports are the first two nodes of the tree. That is a documentation problem, not a data problem, which is why this page exists.

The five steps

If the tree does not resolve it

Open the SKU page and read the movement timeline, not the balance. The balance is a conclusion, the timeline is the evidence.
Find the last row where the balance was right. Everything before it is fine, so only look after it.
Check the event browser for that window. A missing posting usually means a missing or unclassified event, not a wrong one.
If the event exists but posted nothing, it is a classifier rule gap. Open classifier and map the rule.
If the event never arrived, it is a sibling contract gap. Check sibling events for silence on that source.

The fix is never one row. When you find it, the correction scans the whole table for the same pattern and ships with a recurring job that owns it. A patch on the reported order number is not a fix.

05 · Phase gates

A phase closes only when its gate holds for 7 consecutive days. Today is GATE-1 day 6.

GATE-1 green, day 6 of 7

Gate	Phase	What it tests	Threshold	Measured now	Status	Pages behind it
GATE-0	Foundation + opening balance	Opening balances signed per location, hash chain verifies	within 1% of Shopify total	0.31%	passed 22-07	opening-stock
GATE-1	Sales and cancellations	i3 sellable vs Shopify available per location-day	< 0.10% · classifier ≥ 99.5%	0.04% · 99.7%	day 6 of 7	inventory-live, shopify-events
GATE-2	Returns, exchanges, repairs	Every ops2 returns-scan and CSD replacement has a posting or an open case	reverse drift < 0.2%	not started	locked	returns, repairs
GATE-3	Inbound: PO, PI, GIT, GRN, QC	GRN receipts post within 5 minutes, PO expected vs received reconciles	100% within 5 min	not started	locked	inflows, grn
GATE-4	Transfers, retail, consignment	In-transit balance nets to zero per completed transfer	store count vs ledger < 0.5% weekly	not started	locked	transfers, consignment
GATE-5	IWMS physical layer	Carton sum vs quantity ledger in HQ zones	< 0.5%	not started	locked	cartons
GATE-6	RFID serial layer	Unit count equals quantity ledger for serialized SKUs at HQ	7 days · gate catch > 99%	shadow · 91% tagged	shadow	rfid, rfid-recon
GATE-7	Programs	Influencer pool matches the Hub, every damage has an incident	exact match	not started	locked	influencer, damages
GATE-8	Intelligence and finance	Monthly close reproducible from the ledger alone	finance signs one full month	not started	locked	reports

A page behind a locked gate is not broken. It renders in gate-blocked state with its shadow data marked as not yet authoritative. See the state library.

06 · Authority matrix

When two systems disagree about one fact, this table decides. It is not negotiable per case.

RFID gate reads beat everything physical

Fact	Authority	i3 does what
Order or refund exists	Shopify	accepts, never invents an order
Sellable and available	Shopify	cross-checks daily, writes back only after cutover
Dispatch, AWB, carrier events	ops2	consumes, never creates an AWB
Return intent and case linkage	CSD	consumes the decision, owns the stock effect
Physical receipt	GRN / IWMS	posts the receipt as a ledger row
Carton, zone and bin position	IWMS	mirrors, does not move cartons
Physical presence of a serial	RFID	a gate read is immutable and wins
PO, PI, production status	i3	owns it outright
Financial write-off approval	Finance	records the approval, cannot self-approve
What an event means for stock	i3	owns it outright · law 6

Reading the matrix

The three questions it answers

"ops2 says shipped, i3 says in stock." ops2 is the authority on dispatch, so the fact is true and i3 is behind. Look for a missing or unclassified dispatch event, not for a wrong balance.

"RFID says the unit left, ops2 has no AWB." The gate read wins on physical existence. The unit is out of the building. That is a P1: something left without a shipment.

"Shopify shows 4, i3 shows 6." Shopify owns sellable. If the gap survives the daily cross-check, i3 opens a drift case rather than silently matching Shopify, because silently matching is how you lose the evidence.

Never resolved by whoever is loudest, whoever asked most recently, or whichever number is more convenient for the report due today.

07 · Keyboard shortcuts

One registry. This table and the ? dialog render from the same source, so they cannot drift apart.

Command palette ↗

Keys	Action	Scope	Needs
⌘ K	Open the command palette	global	viewer
/	Focus the page filter	any table page	viewer
?	Show this shortcut list	global	viewer
Esc	Close the panel, palette or dialog	global	viewer
⌘ .	Toggle light and dark	global	viewer
J K	Next and previous row	any list	viewer
Enter	Open the selected row	any list	viewer
⌘ Enter	Open in the side panel without leaving the page	any list	viewer
X	Select or deselect the row	any list	viewer
E	Mark read	notifications	viewer
A	Acknowledge, stops the escalation timer	notifications	manager
S	Snooze until a chosen time	notifications	manager
M	Mute the rule, expiry and reason required	notifications	ops_manager
V	Cycle saved views	any table page	viewer
G D	Go to the dashboard	global	viewer
G N	Go to notifications	global	viewer
G S	Go to live inventory	global	viewer
G F	Go to drift	global	viewer
G T	Go to transfers	global	viewer
G U	Go to the audit log	global	viewer

08 · Every module

Fifteen modules. Each one has a specification at docs/modules/NN-*.md with its own data model, business rules and acceptance criteria.

15 modules · 72 pages

01Workspace shell
dashboard, notifications, help, login, tour, palette, states 02Inventory views
live pivot, classic table, mix, stock health 03SKU and hierarchy
grandparent, parent, children, merge, price trends 04Locations and IWMS
locations, detail, cartons, IWMS events 05Inbound PO PI production GIT
purchase orders, production, goods in transit, shipments 06GRN QC suppliers RTS
receiving, 5-bucket QC, suppliers, return to supplier 07Transfers
store to store, 2N postings, transfer detail 08Reverse logistics
returns, exchanges, repairs, CSD and ops2 events 09Damages and incidents
4-source intake, incident matching, write-offs 10Stock count and opening balance
sessions, blind count, bulk import, opening stock 11Programs
influencer, samples, consignment 12RFID
gates, unit ledger, 3-way reconcile, mobile scan 13Drift and reconciliation
cases, anomalies, conflicts, corrections, approvals 14Events and classifier rules
Shopify events, rules, alerts, outbox, audit log 15Reports, finance, ops health
reports hub, cash forecast, settings, dev console

09 · Troubleshooting

Sorted by how often it is actually asked. Every answer ends in an action, never in "contact support".

10 of 31 shown

P1 A SKU shows a negative balance. Is that a bug?

Almost never a code bug. Three causes account for nearly all of them:

The opening balance for that location was never signed. Sales then deduct from zero. This is exactly what took i2 to minus 140,753. Check opening stock first.
A GRN was never posted. Goods physically arrived, nobody receipted them, so every subsequent sale deducts from a balance that never got its credit.
A double deduction on a replacement. The replacement dispatch deducted and the original exchange line also deducted. INV1 had 111 of these.

Do not overwrite the balance. Open a ledger correction so the compensating row and its reason are on the record.

P2 Shopify and i3 disagree by a few units. Who is right?

Shopify is the authority on sellable. i3 is the authority on what happened. Both can be correct at once, because they measure different things.

i3 sellable excludes RESERVED, DISPLAY_GOOD and QUARANTINE. Shopify does not know about those.
The daily cross-check compares them per location-day. GATE-1 requires the divergence under 0.10%.
If it survives the cross-check, i3 opens a drift case rather than silently matching Shopify. Silently matching destroys the evidence.

P2 A composite shows zero but its components are in stock

That is correct behaviour. A composite holds no stock of its own. Its availability is computed as min(child availability) at read time, so one exhausted child takes the whole set to zero.

Check the children on the SKU page hierarchy tree. The limiting child is highlighted. If you expected the composite itself to carry stock, the recipe is wrong, not the balance.

P2 A stock movement happened but nothing appeared in i3

Work in this order:

Sibling events. Did the event arrive at all? If the source is silent, the sibling.silent rule should already have raised a P2.
Event browser. It arrived but was it classified? An unmatched event posts nothing by design.
Classifier. Which rule should have caught it? Map the rule in shadow mode first.
Only then look at the ledger. A missing posting is upstream in 9 cases out of 10.

P3 Why did I get paged twice for the same thing?

You should not have. Every alert is unique on (rule_id, dedupe_key, throttle_bucket), so a second producer cannot create a second row. If you genuinely received two, one of these is true:

Two different rules matched the same underlying condition. Fix by merging the rules, not by muting one.
The alert escalated. An escalation is a second message by design, and it can happen only once per alert.
A delivery retry succeeded after appearing to fail. Check the delivery log on notifications.

P3 I muted a rule and I am still seeing the alerts

Correct. Muting suppresses delivery, never the instance. The alerts still accumulate in-app and are still counted, they simply stop reaching Slack and email.

This is deliberate: a mute that hides the record is indistinguishable from a bug, and quiet is not the same as healthy. Every suppressed delivery is logged with a reason.

P3 A page says "gate blocked". Is it broken?

No. The feature exists and its data is being collected, but its reconcile gate has not held for 7 consecutive days, so the numbers are not yet authoritative. The page shows what it has, marked as shadow.

The gate, its threshold and its current measurement are named on the page and in section 05 above.

P3 I cannot see a page that a colleague can see

Access is per app and per role. Open login and access to see exactly what you hold on app i3, and what the page requires. There are four roles: viewer, manager, ops_manager, admin.

Store-scoped pages also depend on which stores you are rostered at. A manager rostered at two stores sees two.

P3 How do I undo something?

You do not undo. You post a compensating row, which is a new ledger entry with the opposite delta and a link to what it reverses. The original stays.

This is law 3, and it is why the audit log is trustworthy. A system that lets you delete history cannot tell you what happened.

P3 What is the difference between the two ledgers?

The quantity ledger says how many, keyed (SKU x location x stock_type). The unit ledger says which ones and where they physically are, keyed by RFID EPC serial.

They are reconciled continuously. Where units exist, the quantity is the count of units. Where they disagree, the gate read wins on physical existence and a drift case records the gap. See 3-way reconcile.