DEV Community: life

Model wood packaging checks as recorded fields, not a pass verdict

life — Tue, 27 Oct 2026 16:18:35 +0000

Wood packaging compliance works better as a field-recording problem than as an automated pass or fail test. A receiving system can capture what a person observes on a pallet. It cannot decide whether that pallet satisfies 7 CFR 319.40-3, and no field list changes that.

The distinction matters because the regulation does not hand a warehouse a checklist that maps to a database column. It sets conditions on importation, and several of those conditions rest on determinations that belong to APHIS or to an inspector. A system that stores observations and a system that issues verdicts are different systems. Only the first one is honest about what it knows.

Fields a receiving system can record

The first field is material type. The regulation defines bark chips as bark fragments broken or shredded from log or branch surfaces (7 CFR 319.40-1), and it treats wood packaging material as a category with its own conditions under 7 CFR 319.40-3. Recording whether a pallet, a crate or loose dunnage is in front of the receiver is a description, not a classification ruling.

The second field is whether bark is present and how much. 7 CFR 319.40-7(b) sets a surface limit for regulated articles in a lot, and it sets a different rule for raw lumber. A receiver can note that bark is visible and roughly where. A receiver cannot convert that note into a compliance finding, because the percentage test in the regulation is applied to a lot, not to the one pallet on the dock.

The third field is the mark itself, recorded symbol by symbol rather than as a single yes. The mark carries information the regulation describes, and copying each element into its own field keeps the observation separable from any conclusion drawn from it.

The fourth field is pallet count and the supplier or shipper the pallet arrived from. The fifth is a disposition record when something looks wrong, written as what was observed and who was told, not as an outcome the system chose. The sixth is cost responsibility, and 7 CFR 319.40-10 splits it: inspection done on assigned duty hours at the usual posting carries no charge to the importer, yet the same section lets an inspector ask the importer to provide the workers, chemicals and packaging that handling a regulated article requires. Recording who bore which cost is a bookkeeping entry. Assigning that cost in advance is a contractual question for the parties.

wood_packaging_receipt
  material_type          observed | pallet | crate | dunnage | loose wood
  bark_visible           yes | no | unknown
  bark_location_note     free text, observer words only
  mark_present           yes | no | unreadable
  mark_elements          one field per symbol on the mark
  pallet_count           integer
  supplier_name          text
  observation_time       timestamp
  observer               person
  disposition_note       free text, what was seen and who was notified
  cost_bearer_note       free text, agreed between parties
  review_required        always true until a human clears it

Where the model breaks

The first trap is treating a visible mark as proof of compliance. A mark on a pallet is an object a receiver can see. Whether the treatment behind that mark was carried out correctly is not visible, and 7 CFR 319.40-7(c) sends treatment of regulated articles to part 305 of the same chapter. A record that says "mark present" is accurate. A record that says "compliant" is a claim the receiver is not positioned to make.

The second trap is hardcoding an exemption list as permanent. 7 CFR 319.40-3(a) opens with conditions for Canada and Mexico, and those conditions are written into a numbered paragraph that can be amended. A system that bakes the current list into a lookup table will keep answering with a rule that may no longer be the rule. Store the paragraph reference and the retrieval date beside the entry, and have someone confirm the current text before relying on it.

The third trap is letting the system pick the disposition. 7 CFR 319.40-7(a) addresses what happens when APHIS determines that a required document is inaccurate, and the consequence described there is refusal of entry. That is an agency determination. A warehouse workflow can log that a pallet was flagged and that a broker or the importer was contacted. It should not carry a branch that outputs a disposal or return decision on its own authority.

A rule sketch that stops at the human boundary

on receipt of wood packaging:
  record material_type, mark_present, mark_elements, pallet_count, supplier_name
  record bark_visible and bark_location_note in observer words
  set review_required = true

  if mark_present == "unreadable":
      open a manual review task
      notify the party named in the shipment agreement
      do not infer treatment status

  if bark_visible == "yes":
      open a manual review task
      record the observation
      do not compute a percentage against 7 CFR 319.40-7(b)

  if supplier_name is new or mark_elements are incomplete:
      open a manual review task
      ask the importer to confirm the packaging source

  never auto-close review_required
  never write a compliance verdict field
  never trigger a disposal, return or re-treatment action

Every branch in that sketch ends at a person. The code records and routes. It does not conclude.

What the parties should agree before the first pallet

Sellers and providers should agree in writing which observations get recorded, who receives a flagged pallet, and how long the record is kept. They should confirm which party contacts the customs broker when a mark is unreadable, and record that contact rather than assuming it happened. They should consider keeping the raw observer note alongside any later summary, because the note is the evidence and the summary is an interpretation. They should also agree that a disposition decision on wood packaging sits with the importer and the agency that inspects, not with the warehouse system.

What we can see and what we cannot

FulfillNexa by SBT (fulfillnexa.com) owns those rows, not the determination. We cannot issue a treatment certificate, judge whether a mark is genuine, or absorb the consequences of a 7 CFR 319.40-7 disposition. Receiving happens on 24,000 square meters of Chinese space, of which Suzhou holds 13,000 for consolidation work, Dongguan 8,000 for ecommerce storage and per-order picking, and Shenzhen 3,000 for oversize cargo and sea-air transfers.

Model a customs bond as four separate clocks, not one flag

life — Tue, 27 Oct 2026 16:18:10 +0000

A customs bond is not a boolean field on a shipment record. Under 19 CFR part 113 the bond amount, the effective date, the document production clock, the extension decision and the charge for a missing document are separate facts with separate actors, and a schema that stores a single in_bond flag cannot answer any of them.

The question this article answers is how to model those facts as rows tied to a shipment and to an obligation, so that each field can be traced back to the section that governs it.

Why the bond flag fails as a data model

19 CFR 113.1 speaks to the situation no statute or regulation covers: the Commissioner may order security, or give that power to the Revenue Division director, or to the port director. A record that says a shipment is covered therefore says nothing about who required the coverage, for which obligation, or at what amount.

Amount is its own field. 19 CFR 113.13(a) puts a numeric bottom under that column: nothing below $100 for a CBP bond, unless a statute or rule expressly allows a smaller figure. Sufficiency is a separate judgment with its own column, and 19 CFR 113.13(b) names what CBP considers there, starting with past punctuality on duties and charges, the worth and the make-up of the goods, and how the principal handled bond commitments before. A schema that stores one number without the basis for it cannot support a later review under 19 CFR 113.13(c), where CBP periodically reviews each bond on file and the principal has 15 days from the date of notification to remedy a deficiency.

Dates are not one date. 19 CFR 113.26(a) lets a continuous bond, the application tied to it or a rider reach CBP as much as 60 days ahead of the effective date asked for, and the early filing does not move that date. 19 CFR 113.26(b) dates a one-entry bond by the transaction written on CBP Form 301, and 113.26(c) dates a continuous bond by the effective date carried on that form. Filing date, requested effective date and transaction date are three columns, not one.

A schema draft keyed to the sections

The draft below keeps the obligation as its own row so that a bond can cover several obligations and a shipment can carry several obligation rows. Field names are ours. The section references are the ledger's.

bond_record
  bond_id
  bond_type                 -- single transaction | continuous
  principal_name
  principal_legal_designation
  surety_name
  amount_figures            -- 19 CFR 113.21(c)
  date_executed             -- 19 CFR 113.21(b)
  requested_effective_date  -- 19 CFR 113.26(a)
  effective_date            -- 19 CFR 113.26(b) or (c)
  filed_date                -- 19 CFR 113.26(a)

obligation_row
  obligation_id
  shipment_ref
  obligation_type           -- entry | document production | other
  bond_id
  principal_ref
  trade_name_on_bond        -- 19 CFR 113.21(a)(2)
  cbp_request_date
  document_due_date         -- 19 CFR 113.42
  extension_applied_date    -- 19 CFR 113.43(a)
  extension_granted_days
  extension_status          -- none | applied | granted | refused
  charge_event_date         -- 19 CFR 113.45
  charge_basis_note

Two fields in that draft carry more weight than the rest. The document due date is computed from the date of notice from CBP requesting the document, because 19 CFR 113.42 sets delivery within 120 days from that date, with delivery on the next business day accepted as timely if the period ends on a Saturday, Sunday, or holiday. The extension fields exist because 19 CFR 113.43(a) leaves a discretionary call to the port director, or to another officer with the authority: on a written request from the importer, one further window of up to 60 days may be granted.

Two failure modes worth naming

The first is treating a continuous bond as permission to produce documents late. A continuous bond covers multiple transactions, but 19 CFR 113.45 addresses exactly this case: when a continuous bond covers a missing document and the principal fails to produce it on time, the liquidated damages claim is set at what a single transaction bond for that shipment would have been. The continuous form changes how that charge is computed, and it does not remove the clock.

The second is treating possession of event data as assumption of the obligation. The conditions attached to a basic importation and entry bond sit in 19 CFR 113.62, and that section names the obligors as principal and surety, jointly and severally. A fulfillment operator holding warehouse and outbound event rows is neither of those parties. Before any reconciliation report circulates, have the importer of record and the broker state in writing which entity stands as principal on each bond. Record the answer against the obligation row rather than inferring it from who holds the data.

Engineering the due date as a clock, not a delete

Store the document due date as a value that changes through an event, not as a field that gets cleared when the document arrives. A produced document closes the obligation. It does not erase the due date, because the due date is the evidence that the production was timely.

Where the 120-day period is running out, the record should show whether a written application was made and what the port director or CBP officer decided. 19 CFR 113.43(b) also constrains late applications, so the application date belongs in its own column and should not be backfilled from the grant date. Agree with the importer and the broker which party files the application and which party records the outcome. Consider keeping the refused and expired states as first-class values so that a reconciliation report can show them. Confirm with counsel how long each state must be retained before any purge job runs.

The data layer we actually hold

FulfillNexa by SBT (fulfillnexa.com) keeps inbound and outbound event rows for goods received at three Chinese sites. Suzhou carries 13,000 square meters of that capacity and is where East China suppliers are consolidated. Dongguan carries 8,000 square meters used for ecommerce storage and per-order fulfillment, apparel and toys among it. Shenzhen carries 3,000 square meters for oversized cargo and sea-air work. The rows are ours to produce. The bond obligation under 19 CFR part 113 is not, and we are neither a licensed customs broker nor a surety.

Model a drawback claim as a state machine with statutory deadlines

life — Sun, 25 Oct 2026 18:21:42 +0000

A drawback claim is a state machine with statutory deadlines, and a missed transition ends the run. 19 CFR part 190 sequences the flow, and each state has a defined input, a defined actor and a defined failure mode.

State zero is not the claim

Drawback under 19 U.S.C. 1313(j)(1) starts with imported merchandise on which duty, tax or fee was paid, and 19 CFR 190.31(a) sets the condition that the goods went unused inside the United States before that exportation or destruction. Operations that do not amount to manufacture or production are not use under 19 CFR 190.31(c). A warehouse event stream that logs receipt, storage and outbound movement documents that condition without proving it. Ask the importer to confirm which operations were performed on the goods and record that answer against the SKU.

Export or destruction must land inside the five-year window

19 CFR 190.31(b) allows drawback on imported merchandise if, "before the close of the 5-year period beginning on the date of importation and before the drawback claim is filed," the merchandise is exported from the United States or destroyed under CBP supervision. Your event schema needs the importation date as an immutable field, the export or destruction date, and the claim filing date, because the boundary is measured from importation and the claim must follow the export. 19 CFR 190.42(a) states the failure plainly: "Drawback will be denied on merchandise that is exported or destroyed after the statutory 5-year time period." Record all three dates and compare them before anyone treats a lot as claimable.

The notice of intent is a lead-time event

19 CFR 190.35(a) requires the CBP Form 7553 notice of intent to export, destroy or return the merchandise, filed at the port where examination is intended no later than 5 working days before that exportation date, unless CBP agrees to another filing window or has already waived prior notice. The notice must certify the goods went unused inside the United States before they were exported or destroyed, and 19 CFR 190.35(b) asks for the bill of lading number when it is known, whom to contact, and where the goods are being held. Under 19 CFR 190.35(c) CBP then has 2 working days from receipt to say whether it will examine.

A state machine that models the notice as a checkbox rather than a scheduled event with a five-working-day lead will emit export instructions the notice cannot precede. Store the notice filing date, the port, the intended exportation date and the examination decision as separate fields.

Missing the notice does not automatically end the run. 19 CFR 190.36(a) covers goods shipped out or destroyed without the 19 CFR 190.35(a) notice in place as potentially eligible "subject to the following conditions," and the first of those is a written application to the drawback office with the required information. Model the missed notice as a branch into an application state, not as a terminal state, and let the claimant decide whether to pursue it.

Rejected goods and retail returns carry different documents

Rejected merchandise under 19 U.S.C. 1313(c) covers goods that do not conform to sample or specifications, were shipped without the consent of the consignee, were defective as of the time of importation, or were sold at retail and then returned to, and accepted by, the importer or the party that received them from the importer. 19 CFR 190.41 caps that drawback at 99 percent of the duties paid on the goods that were imported and duty-paid.

19 CFR 190.42(b) requires documentation establishing the nonconformity, the lack of consent or the defect. A claimant who was not the importer must also submit a signed statement from the importer and from each prior owner other than the ultimate purchaser of the goods, confirming no other drawback claim was made, and certify that records support that statement. 19 CFR 190.42(c) requires the same Form 7553 notice, filed at the port of intended redelivery to CBP custody.

Retail returns add their own fields under 19 CFR 190.45(b): the claimant designates an import made within 1 year before that exportation or destruction date, and certifies that one 8-digit HTSUS subheading plus the same product identifier cover both the import being designated and the units coming back. 19 CFR 190.45(c) caps the refund at 99 percent of duties paid.

Your schema therefore needs a claim-type field with different required documents per branch, and a product identifier that resolves to the same value on both sides of the designation.

Who holds the claim right

Under 19 CFR 190.33(a)(1), the exporter or destroyer is entitled to claim drawback for direct identification. That party may waive the right and assign it to the importer or any intermediate party, and where the claimant is neither the exporter nor the destroyer, that party's signed certification has to be obtained and kept, waiving the right and confirming it did not and will not let another party claim that exportation or destruction for drawback. The claimant must file that certification with each claim. Record the certificate holder as an identity field with a validity period, not as a role attached to a team.

Three modeling traps

The 99 percent figure is a cap on the allowable refund relative to duties paid, not a yield. Writing it into a business rule as expected recovery converts a statutory ceiling into a forecast the regulation does not make. Record it as a ceiling and let the claimant compute.

The 1-year designation window in 19 CFR 190.45(b) constrains which entry may be designated for a retail return claim. It does not license accepting returns on any schedule. Confirm the return acceptance facts with the importer and keep return acceptance separate from claim eligibility.

Claim rights sit with named parties under 19 CFR 190.33. Treating the right as available to whichever internal team holds the export file is a data model error. Agree with the importer and the exporter who signs the waiver certification, and record that agreement before any claim state opens.

IMPORTED -> IN_STORAGE -> {EXPORTED | DESTROYED}
  require: import_date, duty_paid_amount, no_use_attestation
  guard:  export_or_destroy_date < import_date + 5 years
  guard:  claim_filed_after export_or_destroy_date

EXPORTED -> NOTICE_FILED
  require: form_7553_date, port, intended_export_date,
           contact, location, unused_certification
  guard:  form_7553_date <= intended_export_date - 5 working days
  branch: missing notice -> APPLICATION_STATE (19 CFR 190.36)

NOTICE_FILED -> EXAM_DECISION
  require: decision_date, examine_or_waive
  guard:  decision_date <= form_7553_receipt + 2 working days

EXAM_DECISION -> CLAIM_ASSEMBLED
  require: claim_type, product_identifier, htsus_8,
           waiver_certificate_holder, signed_statements
  branch: rejected goods  -> nonconformity evidence + owner statements
  branch: retail return   -> designated_entry within 1 year + matching id

What a warehouse can honestly export

FulfillNexa by SBT (fulfillnexa.com) can export a dated event stream for the same SKU from inbound receiving through outbound and recovery, which is the class of evidence that has to reconcile against the entry and the claim. The claim and the determination sit with the parties named in 19 CFR 190.33, and we do not sign for them or assert an outcome. Everything we operate sits in China, 24,000 square meters over three cities. The Suzhou floor runs 13,000 square meters of supplier consolidation, Dongguan keeps 8,000 for ecommerce storage and per-order fulfillment, and Shenzhen holds 3,000 for oversized cargo and the sea-air legs in between.

Model 19 CFR part 163 retention as several start-date fields

life — Sun, 25 Oct 2026 18:21:27 +0000

A retention table for 19 CFR part 163 needs more than one start date, and a schema that stores only an entry date will misclassify every packing list in the system.

The problem is that the regulation states several different clocks. Under 19 CFR 163.4(a), a record required to be made, kept, and rendered for examination and inspection by Customs is kept for 5 years from the date of entry if the record relates to an entry, or 5 years from the date of the activity which required creation of the record. Those are two distinct start events, and the second one is not a fallback for the first. Paragraph (b) then carves out exceptions with their own anchors. Records behind a drawback claim survive until the third anniversary of payment. Packing lists run 60 calendar days past the close of the release or conditional release period, or past whichever of those dates lands later, and a second 60-day clock attaches to redelivery where Customs has demanded the goods back. Where the consignee is neither owner nor purchaser but names a customs broker, that consignee keeps a record pertaining to an informal-entry record, which runs 2 years from that entry date.

A single entry_date + 5 years column cannot express any of that. The table has to carry the anchor as data.

record_row:
  record_id
  record_type            # entry record, packing list, drawback record, informal entry record
  obligated_party        # person described in 19 CFR 163.2(a)
  obligation_basis       # 163.4(a) entry / 163.4(a) activity / 163.4(b)(1) / (b)(2) / (b)(3)
  start_event_type       # entry, activity, claim payment, release end, redelivery demand, informal entry
  start_event_date
  retention_rule_id
  computed_expiry
  storage_form           # original, or alternative under 19 CFR 163.5(b)
  alt_storage_notice_date
  alt_storage_ack
  demand_received_at
  production_due_at

The storage fields are not decoration. Under 19 CFR 163.5(a), records must be maintained as original records, whether paper or electronic, unless alternative storage methods have been adopted under paragraph (b), and must be capable of being retrieved upon lawful request or demand by CBP. Paragraph (b)(1) allows an alternative format only where advance written notification goes to Regulatory Audit at least 30 calendar days before implementation. A row that says "stored electronically" without the notice date and the acknowledgment is a row that cannot answer the retrieval question. Record the notice date and confirm whether any written instruction against alternative storage was received.

The delivery clock belongs in the same row. Under 19 CFR 163.6(a), entry records a Customs officer demands have to be handed over within 30 calendar days after that demand arrives, or faster when Customs sets a shorter window because the records bear on admissibility or release. A request for additional time must be received before the applicable due date and must explain the circumstances. So production_due_at is derived from demand_received_at plus the demanded period, and the shortened case has to be representable. Agree with the obligated party who computes that field and record the basis used.

Two modeling mistakes recur.

The first is collapsing everything into entry plus 5 years. That rule is correct for records that relate to an entry and wrong for records keyed to an activity, to a drawback payment, to the end of a release period, or to an informal entry. The failure is quiet, because the row still has a date in it. Consider splitting retention_rule_id into a closed enumeration and refusing to write a row whose rule does not match its start_event_type. Confirm the enumeration against the paragraph text rather than against a prior system.

The second is treating "we can produce it" as authority to decide what the importer keeps. The duty in 19 CFR 163.2(a) attaches to the persons listed there, including the owner, the importer, the consignee, the party entered as importer of record, entry filers, anyone else who imports merchandise, files a drawback claim, or moves or stores merchandise held under bond, plus their agents and anyone whose activities require filing a declaration or entry. A fulfillment operator holding copies of documents is not thereby the party that decides retention scope for someone else. Record who the obligated party is on each row and agree in writing which party owns which record class. Where a party wants to rely on the voluntary Recordkeeping Compliance Program in 19 CFR 163.12, note that certification is a matter between that party and CBP and that certification leaves CBP free to compel records by summons, court order or another legal process.

Engineers should treat 19 CFR 163.6 delivery as a service level field, not as a deletion policy. Deletion answers "when do we drop this." Production answers "how fast can we hand it over when demanded." Those are different columns with different owners. Keep computed_expiry immutable once written, keep demand_received_at append-only, and agree with the obligated party how a shortened production period is flagged and escalated. Confirm that a record marked for alternative storage can still be retrieved in the original format within the demanded window, and record the result of that check rather than assuming it.

Nothing here determines whether a given record is required, and no table design settles an enforcement outcome. The schema exists so that the anchor, the party, and the clock are visible on the same row.

FulfillNexa by SBT (fulfillnexa.com) works from a data layer of inbound and outbound event rows across 24,000 square meters in China. Suzhou carries 13,000 of that for consolidating East China suppliers, Dongguan 8,000 for ecommerce stock and per-order picking with apparel and toys in scope, and Shenzhen 3,000 for oversized freight on sea-air and air-sea legs. The records described in 19 CFR part 163 belong to the persons named in the regulation. We supply the layer where reconciliation can happen and do not replace anyone's recordkeeping obligation.

Model a hazmat shipping paper as ordered segments, not five columns

life — Sat, 24 Oct 2026 14:09:49 +0000

A hazmat shipping paper becomes testable when the basic description is stored as one ordered array, the mixed-load marker as an enum, and the retention clock as a date field captured from the carrier rather than the order.

Most shipping-paper bugs are not missing data. They are data that arrived in the wrong shape. A description split across five nullable columns cannot express "these five entries, in this order, as one block, with everything else after them." A boolean named is_hazmat cannot express which of three permitted mixed-load markers the offeror chose. A retention_years integer computed from the order timestamp cannot express the rule in 49 CFR 172.201(e), because the clock starts when the initial carrier accepts the material. Reshaping the model is the whole job. Validation falls out of it.

The basic description is an ordered array, not five fields

49 CFR 172.202(a) lists what the shipping description must include: the identification number from Column (4) of the § 172.101 table, the proper shipping name from Column (2), the hazard class or division number from Column (3), the packing group in Roman numerals from Column (5), and the total quantity with its unit of measurement. The regulation treats that set as a single object called the basic description, and and 49 CFR 172.201(a)(4) constrains everything else: anything extra goes after that block, not inside it.

That ordering constraint is the reason to model the description as an array of typed segments with a position index, not as sibling columns. Each segment carries a kind drawn from a closed set, and the validator asserts that the five required kinds appear once each, in the sequence the regulation lists, with no additional-information segment at a lower index than the last required one. Packing group has its own wrinkle. 49 CFR 172.202(a)(4) excepts Class 1 materials, self-reactive substances, Division 5.2 materials, and entries not assigned a packing group from the requirement, so the assertion is conditional on the material, not unconditional. Store the exception basis alongside the segment or the validator will fire on correct papers.

Hazard class carries two separate conditionals under 49 CFR 172.202(a)(3). A subsidiary class or division number need not be entered at all when no matching subsidiary label is required. And when it is entered, it goes in parentheses immediately after the primary class or division number, except for combustible liquids.

segment := {
  position:      int,          # 1-based, dense, no gaps
  kind:          enum,         # id_number | psn | hazard_class | packing_group | quantity | additional
  value:         string,
  unit:          string|null,  # required when kind = quantity
  exception_ref: string|null   # e.g. "172.202(a)(4)" when the segment is legitimately absent
}

assert description.segments
  .filter(s => s.kind in REQUIRED_FIVE)
  .map(s => s.kind)
  == ["id_number","psn","hazard_class","packing_group","quantity"]

assert description.segments
  .filter(s => s.kind == "additional")
  .every(s => s.position > position_of("quantity"))

Quantity deserves its own note. 49 CFR 172.202(a)(5) requires the total quantity by mass or volume, or by activity for Class 7 materials, together with the applicable unit of measurement, and excepts transportation by aircraft from the requirement. A quantity segment without a unit should fail validation rather than pass as an empty string.

The mixed-load marker is an enum with three members

When a hazardous material and a non-regulated material share one shipping paper, 49 CFR 172.201(a)(1) gives the offeror three acceptable ways to distinguish the hazardous entry: enter it first, enter it in a color that clearly contrasts with the non-regulated description, or place an "X" before the basic description in a column captioned "HM." A boolean collapses those into one bit and loses the choice. Store the marker as an enum whose members are first_position, contrasting_color, and hm_column_x, then assert that exactly one is set whenever the paper carries both kinds of material.

Two smaller rules ride along. 49 CFR 172.201(a)(2) requires the shipping description and all copies used for transportation to be legible and printed in English, manually or mechanically. 49 CFR 172.201(a)(3) bars any code or abbreviation in the required description unless the subchapter specifically authorizes or requires it. The second is checkable against a maintained allowlist of authorized abbreviations, and it is worth running as a lint rather than a hard block, because the allowlist has to track the subchapter.

Page count and the total-page notation are their own fields

A multi-page shipping paper has a structural requirement that gets skipped when documents are assembled at print time. Under 49 CFR 172.201(c) a paper may run over several pages provided the pages number in sequence and page one states how many pages there are in total, the rule offering "Page 1 of 4 pages" as its own example.

Model page_number, page_total, and total_notation_present as first-class fields on the document, not as artifacts of the PDF renderer. The assertion is trivial once the fields exist: page numbers form a dense sequence from one to page_total, and total_notation_present is true on the first page whenever page_total exceeds one. A renderer that paginates after the fact cannot satisfy this, which is the point. The notation is a property of the document the offeror provides, not of the file that leaves the printer.

The emergency phone needs two checks, not one

49 CFR 172.201(d) asks for two things on the face of the paper: an emergency response telephone number, and where that number routes through a service provider, the name or contract number of whoever holds the agreement with the provider. Those are separate obligations and they fail separately.

The first check is availability: a number is present and parses as a dialable number in the expected format. The second is accountability: if a service provider is in use, a named person or contract number is recorded against that provider. A paper can pass the first and fail the second, which is exactly the case a single emergency_contact string hides. Keep the provider relationship as a reference to a record rather than free text, so the contract number can be re-verified when it changes.

Retention forks on cargo class and starts at carrier acceptance

49 CFR 172.201(e) sets two periods. Hazardous waste keeps its copy for three years past acceptance by the first carrier; everything else covered by the subpart keeps two, and the trigger event is the same in both branches. Each copy must include the date of acceptance by the initial carrier, with a stated alternative for rail, vessel, or air shipments where the date on the waybill, airbill, or bill of lading may be used instead.

The engineering consequence is that acceptance date must be an independent, immutable field. Deriving a retention deadline from an order timestamp produces a date that is wrong by however long the goods sat before handover, and the error runs in the direction that loses records early. Store carrier_accepted_on and acceptance_date_source, the latter distinguishing a direct acceptance date from a transport-document date, then compute the deadline from the cargo classification. The same section requires the copy to be accessible at or through the principal place of business and producible to an authorized official at reasonable times and locations, so the record needs a location pointer as well as a date.

The shipper's certification is stored as wording, signer and time

49 CFR 172.204(a) requires the person offering the material to certify conformity by printing on the shipping paper either the certification in 49 CFR 172.204(a)(1) or the declaration in 49 CFR 172.204(a)(2). The two texts differ, and the regulation permits a substitution in each: "herein-named" may replace "above-named" in the first, and "above" may replace "below" in the second where appropriate.

Storing a certified: true flag discards the only thing that matters later, which is which wording appeared and who put it there. Store the exact text, the variant used, the signer identity, and the signing timestamp. Rail shipments have a further permitted path under 49 CFR 172.204(a)(3), where the certification may be received verbally or with an electronic signature, so the record type should distinguish a printed certification from a captured one.

Marking and description are separate obligations with separate chapters. Nothing in the shipping-paper model above substitutes for country-of-origin marking on the article or its container.

What we can check, and what we cannot

FulfillNexa by SBT (fulfillnexa.com) operates three sites in China: Suzhou at 13,000 square meters, Dongguan at 8,000, and Shenzhen at 3,000. Our systems can validate field presence and segment order on a shipping paper. They cannot verify that a certification's content matches the goods actually in the box. The offeror signs 49 CFR 172.204, not the warehouse.

Model hazmat training as a per-person, per-function authorization row

life — Sat, 24 Oct 2026 14:09:06 +0000

A warehouse can answer "can this person handle this hazmat shipment today" as a database lookup if the training record is modeled as one authorization row per person and function, with an explicit expiry predicate. The rule text already supplies every field that row needs.

The row is per person and per function, not per person

49 CFR 172.702(a) puts the duty on the employer, in one sentence: every hazmat employee it has gets trained to the standard the subpart sets. The unit of training is not the employee. It is the employee crossed with the function, because 49 CFR 172.704(a)(2)(i) ties function-specific training to the requirements and special permits that apply to the functions that person actually performs.

A single training table keyed on employee ID cannot express that. Two people trained on the same general awareness module may hold different function authorizations, and one person may hold several. Model the authorization as its own row and let the employee table hold only identity.

Five columns the record must carry, and one more the rule adds

49 CFR 172.704(d) states that the record "must include" five items, and each maps to a column rather than to a scanned PDF page.

training_record
  employee_name              -- 172.704(d)(1)
  last_completion_date       -- 172.704(d)(2)
  material_ref               -- 172.704(d)(3) description, copy, or location
  provider_name_address      -- 172.704(d)(4)
  trained_and_tested_flag    -- 172.704(d)(5) certification

authorization
  employee_id  -> training_record.employee_name
  function_code
  status                     -- active | supervised_only | blocked

The fifth item is the one engineering teams drop. 49 CFR 172.704(d)(5) wants the employer's own certification that the worker was both trained and tested. Testing is a separate duty in its own right under 49 CFR 172.702(d), which asks that each employee be tested by appropriate means on the subjects 172.704 covers. Training without a test result is an incomplete row. Store the flag as a boolean that defaults to false and cannot be flipped by the training import alone.

The material reference deserves a note. The rule accepts "a description, copy, or the location of the training materials." A pointer into a document store satisfies the third option, provided the pointer resolves. A dead link is not a location.

The predicate has two branches, and both must be evaluated

Authorization is not a single date comparison. 49 CFR 172.704(c)(2) sets the recurrent cycle: "A hazmat employee must receive the training required by this subpart at least once every three years." 49 CFR 172.704(c)(1) opens a separate window for people who are new or who changed functions. Two conditions attach: an already trained and knowledgeable hazmat employee supervises the work directly, and the training has to close within 90 days of the hire or the move.

Read together, those two lines mean a valid authorization needs a completion date inside the three-year cycle, or an open 90-day window with a named supervisor attached to the assignment. The second branch is not a pass. It is a conditional state that must carry the supervisor's identity, since an unsupervised new hire falls outside 49 CFR 172.704(c)(1) entirely.

A predicate that checks only the three-year cycle will approve a brand-new employee with no record at all. A predicate that checks only the 90-day window will approve someone whose last completion date is years stale. Both branches, every time.

Deletion policy cannot be a fixed number of days

The retention clause in 49 CFR 172.704(d) is conditional on employment, not on elapsed time: the employer must retain the record "for as long as that employee is employed by that employer as a hazmat employee and for 90 days thereafter." A cron job that deletes rows older than some constant will either destroy a live authorization or keep a stale one past its lawful life.

The retention boundary is an event, not a duration. Termination date plus 90 days. Until that event fires, the record stays regardless of age, which is why a training completion from four years ago must still be present even though it fails the currency predicate. Currency and retention are different questions and belong in different columns.

Treating departure as an immediate delete is the classic failure. The record must survive the person's last day by 90 days, and 49 CFR 172.704(d) also obliges the employer to hand that current-training record over when an authorized DOT official asks, at a reasonable time and place. A record deleted at offboarding cannot be produced on request.

Where the boundary sits for a fulfillment warehouse

Training duty rests with the hazmat employer under 49 CFR 172.702(a), and 49 CFR 172.702(c) allows that training to come from "the hazmat employer or other public or private sources." Sourcing training from a third party does not move the obligation. 49 CFR 172.704(c)(4) is blunt about it: "Each hazmat employer is responsible for compliance with the requirements of this subchapter regardless of whether the training required by this subpart has been completed."

A fulfillment warehouse is not the hazmat employer of its customers' staff and does not issue training conclusions for anyone. What a warehouse can hold is the data layer that lets the employer's own record stay resolvable. Nothing more.

FulfillNexa by SBT (fulfillnexa.com) keeps the receiving side of that data layer on three Chinese floors, the largest being 13,000 square meters at Suzhou. What lands at goods-in is an arrival timestamp, a weight and piece count per SKU, and a dated packing change. None of the three is a training record and none substitutes for one. The declared number stays the customer's.

Prove the same unit came back by modelling repair, swap and substitution

life — Fri, 23 Oct 2026 09:40:07 +0000

A unit that leaves the country for repair and comes back is only defensible if the record can prove the same physical article returned and only the described work happened. Model that proof as assertions bound to a serial number, not as a note on an order.

The invariant lives on the serial, not the order

An order is a container for commercial intent. A serial is a container for identity. When a unit crosses a border twice, the question a reviewer will eventually ask is not which order it belonged to but whether the thing that came back is the thing that left. Attach the claim to the serial and the order becomes a pointer to it.

The claim itself has two halves. The first half asserts physical continuity: this serial left, this serial returned, same article. The second half asserts work scope: the operations recorded against the serial are the only operations performed. Write both as assertions with a subject, a predicate, and evidence references, so a later reader can evaluate them without reading a free-text note.

Under 19 CFR 10.8(a)(1) the person who performed the work declares that the articles received are the articles exported, that they were received solely for repair or alteration, that only the described work was done, and that no substitution was made. That is four assertions in one sentence. A schema that stores it as a blob cannot answer which of the four is disputed.

Substitution is a different event type

Three events look similar in a status column and are not similar at all. A repair changes the condition of a part and leaves the part in place. A part swap removes one component and installs another, so the serial persists while a child serial changes. A unit swap replaces the serial itself, which breaks the continuity assertion outright.

An "updated in place" row collapses all three into one mutation. The row records that something about the unit is different, which is exactly the fact a reviewer needs decomposed. Once the distinction is gone from the event log, no downstream query can recover it.

Give each event a distinct type and a distinct payload. A repair carries the before-condition, the after-condition, and the work description. A part swap carries the removed component identifier, the installed component identifier, and the reason. A unit swap carries the retired serial and the successor serial, and it should be modeled as a terminal event for the original identity rather than an update to it.

Two declarations, two owners, two clocks

The declaration shape in 19 CFR 10.8 separates the party who did the work from the party with knowledge at the origin side. The first declaration comes from the repairer and covers receipt, scope, cost or value of the work, and the no-substitution statement. The second comes from the owner, importer, consignee, or agent and affirms that the repairer's declaration is true, that the articles were not made in the United States under the subheading cited in the regulation, and that they left without benefit of drawback.

Two declarations mean two field owners. The repairer owns receipt date, work description, and completion. The origin-side party owns export date, export port, and the origin facts about manufacture. Neither party should be able to write the other's fields, and the export timestamp must come from the origin side because the repairer cannot observe it.

A single merged record destroys that provenance. Keep the declarations as separate signed objects that reference the same serial, and let the entry record cite both rather than restate either.

Unchanged is a test, not a status

The claim under 19 CFR 10.1(a) rests on goods coming back with no increase in value and no improvement in condition. That is a comparison, and a comparison needs three facts held separately: the before-state at export, the work log during the absence, and the after-state at return.

Store the before-state as a snapshot with a hash and a timestamp. Store the work log as append-only events. Store the after-state as its own snapshot. The test then evaluates whether the work log is empty or contains only operations that the claim permits, and whether the after-state matches the before-state on the attributes the claim covers.

A status field reading "unchanged" asserts the conclusion without the inputs. When the conclusion is challenged, the reviewer needs the three facts, and a boolean cannot produce them.

The threshold is paperwork, not a tax answer

19 CFR 10.1(a) applies the two-declaration requirement to shipments valued over $2,500 claimed free under the cited subheadings. Read that as a documentation trigger. The number decides which paperwork is required, not what duty is owed.

Keep the distinction in code by naming the field for what it does. A predicate called requiresTwoDeclarations is honest. A field called isDutyFree is not, because it invites a UI to render a tax conclusion the record cannot support.

The same discipline applies one paragraph later. Under 19 CFR 10.1(b), where returned goods are worth more than $2,500 and the U.S. maker's name and address are not plainly on them, the Center director can demand further documentation, a statement from the manufacturer or an export invoice or transport document among the examples the rule gives. That is a conditional evidence request, so the model needs a slot for supplementary evidence and a flag for whether the marking condition is satisfied. Surface the flag as an evidence gap, never as an outcome.

Event sourcing keeps the claim answerable

An append-only log makes the no-substitution claim evaluable at any future date, because the sequence of events is the proof. Corrections arrive as new events that supersede earlier ones, and the earlier ones remain visible.

emit("unit.received", serial="SN-1042", at=ts1, by="repairer")
emit("work.performed", serial="SN-1042", kind="repair", part="P-77", at=ts2)
emit("unit.returned", serial="SN-1042", at=ts3, evidence=[snap_before, snap_after])
assert no_event(kind="part.swap" or kind="unit.swap", serial="SN-1042")

The assertion at the end is the claim. It runs against the log rather than against a mutable row, so a later edit cannot silently erase a substitution event. Values above are illustrative.

What the floor records

The floor keeps three timestamps per unit: arrival, packing configuration, and any dated change to that configuration. Suzhou holds 13,000 square meters of that operation alongside the Dongguan and Shenzhen sites in China, and the record is kept under the name FulfillNexa by SBT (fulfillnexa.com). It answers a question about what was received and does not decide one.

A compliance document is not a column on your product row

life — Fri, 23 Oct 2026 09:36:15 +0000

A test summary that describes a cell model cannot live as a boolean or a file attachment on a product row. It needs its own document record, a recorded claim that links it to the SKU, and a date dimension, because the rule that governs it asks what was true on the day the goods moved. The rest of this article treats that as a data modeling problem rather than a filing cabinet problem.

The summary is a document, not a column

Under 49 CFR 173.185(a)(3), every manufacturer and subsequent distributor of lithium cells or batteries made on or after January 1, 2008 must make a test summary available, with button cells installed in equipment excepted. The summary is a piece of evidence about a tested type. It has its own issuer, its own creation date, its own contents and its own revision history. None of those attributes belong to a product record.

A boolean has_un38_3_summary collapses all of that into one bit and loses the ability to answer when the bit was set, by whom, and against which document. A file attachment on the product row is slightly better, since it preserves the artifact, but it still makes the document a property of the product. The document outlives the product row, can cover several products, and can be superseded while the product row stays untouched.

Model the summary as a first-class entity with a stable identifier, a version, an issuer, and a pointer to the stored file plus a hash of its contents. Point the product at the document through a separate link record. That link record is where the interesting work happens.

The join between SKU and summary is a claim

Paragraph (a)(3) lets the document identify either the cell and battery model or, if it was drawn up for a finished product holding the cell, that product model. That single sentence creates the identity problem. The document may describe a component two levels below the thing being sold, or it may describe the assembled product, and nothing in the file tells your database which of those it is doing.

So the join is not a foreign key that the file carries. It is an assertion made by a person or a process that this summary covers this SKU in this configuration. Record it as an assertion with an author, a timestamp, a method, and the specific model string copied from the document. Store the model string as text exactly as it appears, not as a normalized key. Normalization destroys the evidence that the claim was checked against the source.

A useful shape is a link table with sku_id, summary_id, asserted_by, asserted_at, matched_model_string, match_basis, and a state field. The match_basis column tells a later reviewer whether the match was made on a cell model, a battery model, or a product model, because those are three different strengths of claim.

The fields the rule enumerates

Paragraph (a)(3) lists ten elements the summary must include. Treat each as a typed field rather than free text, and decide nullability from whether the element is conditional in the rule.

The manufacturer name is required and non-null. Manufacturer contact information is required and must carry address, telephone, email and website, so model it as a structured contact object with four non-null members rather than one string. The laboratory name and its contact block follow the same pattern. The unique test report identification number is required and should carry a uniqueness constraint, since it is the natural key for the report.

The report date is required and should be a date, not a timestamp, because the rule speaks of a date of test report. The description block is required and contains the chemistry, which is an enumeration of lithium ion or lithium metal, the mass of the cell or battery as a numeric quantity with a unit, the watt-hour rating or lithium content as a numeric quantity with a unit and a discriminator saying which of the two applies, a physical description as text, and the model number as text.

The list of tests conducted and their results is required and is best modeled as an array of test entries with a name and a pass or fail outcome. References to assembled battery testing and to the edition of the UN Manual used are conditional, so allow null. The name and title of a responsible person is required and should be two fields, not one.

One short block makes the conditional shape concrete. Values below stand in for any shipment and are not drawn from a real filing.

summary {
  report_id: string, unique
  report_date: date
  chemistry: enum(li_ion, li_metal)
  mass: {value: decimal, unit: enum(g, kg)}
  energy: {kind: enum(wh, li_content), value: decimal}
  model_string: string  # verbatim, not normalized
  tests: array<{name: string, result: enum(pass, fail)}>
}

A date-gated rule is a schema problem

Paragraph (a)(5) imposes a marking duty on each lithium ion battery beginning May 10, 2024, requiring the watt-hour rating on the outside case. A global requires_wh_marking flag cannot express that. The record has to answer a question about a specific shipping date, and the answer differs on either side of the boundary.

Effective-dated rule rows solve this cleanly. Store each rule with a valid_from and a nullable valid_to, and resolve the applicable rule set at the shipment date rather than at query time against current configuration. The same pattern covers the January 1, 2008 manufacture cutoff in paragraph (a)(3), which gates whether a summary is required at all. Two date boundaries, two rows, one resolution function.

The payoff is auditability. When a reviewer asks why a record was considered complete in March 2024, the system can replay the rule set that was in force then instead of applying today's logic to yesterday's shipment.

Swapping a cell invalidates the join

Paragraph (a)(1) requires each cell or battery to be of a type proven to meet the UN Manual criteria, and it states plainly that cells and batteries are subject to those tests regardless of whether the cells used to build the battery are of a tested type. Read that sentence as a data rule. The tested type attaches to the cell, and the assembly does not inherit the proof automatically.

A supplier swap or a new product shell therefore breaks the link. The pipeline should move the link record into a blocking state, not emit a warning that scrolls past. Blocking means the SKU cannot advance to a pick-and-pack step until a person re-asserts the join against a summary that names the new configuration. Warnings get acknowledged and forgotten. A blocked state forces a decision with a name and a timestamp attached.

Three ways this fails quietly

A summary that describes an earlier revision is the most common failure, because the file is present, the hash matches, and nobody notices that the document predates the cell change. Version the summary and compare the version against the link record's asserted_at.

A product renamed but not re-joined is the second. The model string in the summary no longer matches the product record, but the foreign key still resolves, so the UI shows a link. Store the matched model string on the link record and re-run the comparison whenever either side changes.

The third is a user interface that prints the word compliant as a single token. That word hides which document was checked, on what date, by whom, and against which rule set. Replace it with the summary identifier, the report date, the link author, and the rule version resolved for the shipment date.

On the receiving floor, each SKU arriving at a China site is weighed, counted and given a packing configuration at the point of receipt, and any later packing change is recorded with a date rather than absorbed silently. Suzhou holds 13,000 square meters of that operation, with Dongguan and Shenzhen handling the rest. FulfillNexa by SBT (fulfillnexa.com) treats the resulting record as an input to whoever holds the compliance document, not a compliance verdict.

A security filing with field-level deadlines needs a field-level schema

life — Thu, 22 Oct 2026 06:48:04 +0000

A filing whose fields carry different deadlines should be stored as one record per field, each with its own due date, source and version, rather than as one row per shipment.

Why one deadline per shipment record breaks

The naive model attaches a single transmit-by timestamp to the shipment and treats the filing as a document that goes out once. The Importer Security Filing does not work that way. Under 19 CFR 149.2(b), the seller, buyer, importer of record number and consignee number are due no later than 24 hours before the cargo is loaded aboard the vessel at the foreign port. The same 24-hour pre-lading anchor covers the manufacturer or supplier, the party being shipped to, the origin country and the classification line. Container stuffing location and consolidator are different. Those two are due as early as possible, and in no event later than 24 hours prior to arrival in a United States port, with a carve-out written into the same sentence for lading at a foreign port less than a 24-hour voyage from the closest United States port.

A single isf_due_at column cannot represent that. Set it to the pre-lading cutoff and the stuffing fields look late when they are not. Set it to arrival minus 24 hours and the eight pre-lading fields look comfortably early while the vessel sails. The failure is quiet. Nothing errors. The record simply reports the wrong state for half its fields for the length of the voyage.

Per-field deadlines change the schema, the queue and the meaning of an error

Move the deadline onto the field. Each element row carries its own due_at, computed from whichever anchor applies to that element, plus the anchor type that produced it. The eight pre-lading elements anchor to the estimated loading date at the foreign port. The two container elements anchor to estimated arrival, unless the voyage is under 24 hours, in which case the anchor is lading at the foreign port.

The queue follows the data. Work is scheduled per element, not per shipment, so the stuffing location task appears on a different day from the HTSUS task and neither blocks the other. A shipment is not "ready" or "not ready" as a whole. It has a count of elements outstanding and a count overdue, and those two numbers diverge.

A validation error changes meaning too. A missing HTSUS number eight days before lading is a normal state. The same gap four hours before lading is an incident. The same gap after lading is a compliance event that no amount of late data repairs. Encoding the error without the element and the anchor makes those three situations indistinguishable, and the alerting that follows will either fire constantly or never.

Two fields the digital pipeline cannot know

Container stuffing location and consolidator describe physical facts about where the container was packed and by whom. No order management system observes either one. The vendor knows the factory address, not the CFS. The forwarder may know the consolidator, or may know the booking party instead. These are the two fields most likely to be filled with a plausible guess, and they are the two with the latest deadline, which means the guess usually survives until arrival.

Treat both as externally sourced by default. Mark them as unverified on entry, require a named source, and let the deadline drive escalation rather than letting a default value satisfy the field.

The verification escape hatch and its engineering shape

19 CFR 149.2(c) anticipates exactly this problem. Where the party transmitting the filing receives information from another party, CBP weighs how that party acquired the information in ordinary commercial practice and whether it could verify it. Where the transmitting party is not reasonably able to verify the information, the rule permits transmitting on the basis of what that party reasonably believes to be true.

That permission has a shape you can store. A belief is a value plus a source plus a timestamp plus an explicit unverified flag. The record should answer who supplied the value, when it arrived, what channel it came through, and whether anyone attempted verification. When better data arrives, the correction is a new version with its own source, not an overwrite. The belief was true as a statement about what the transmitter knew. Erasing it destroys the only evidence that the reliance was reasonable.

What not to automate: do not let a system promote a believed value to a verified one without a human or a document behind it. Do not auto-fill stuffing location from a factory address.

Update and withdrawal are different transitions

The update duty in 19 CFR 149.2(d) sits with whoever transmitted: between transmission and the cargo entering port limits, anything superseded or improved has to be corrected. The trigger is a change in the world. The goods are still coming.

19 CFR 149.2(e) covers a different event. If the goods are no longer intended to be imported to the United States, the submitting party must withdraw the filing and transmit the reason for the withdrawal. The trigger is a change in intent. The goods are not coming.

Collapse both into an edit and the audit trail loses the distinction between a corrected shipment and an abandoned one. An auditor asking why a filing shows a later HTSUS number needs the update path. An auditor asking why a filing stopped existing needs the withdrawal path and its stated reason. A generic edit answers neither.

Idempotency and lineage

Store superseded values. Every element write appends a version with an effective timestamp and a source, and the current value is a view over the latest version rather than the only row. Transmission attempts key on a deterministic hash of element, value and version so a retry after a timeout does not create a duplicate.

One element might then read like the block below, with the dates and the location strings standing in for any shipment rather than for a real one.

element: stuffing_location
  v1  2026-10-02T09:14Z  "Suzhou CFS"   source: forwarder_email  verified: false
  v2  2026-10-06T22:40Z  "Suzhou CFS B2" source: cfs_confirmation verified: true
  due_at: 2026-10-09T06:00Z  anchor: arrival_minus_24h

The question that matters later is what the transmitter knew on a given day and what it did with that knowledge. Append-only element history answers it. Overwriting does not.

Where the operational record sits

Storage shape is a product decision with an operational consequence. FulfillNexa by SBT (fulfillnexa.com) captures weight, count and packing setup per SKU when goods reach its China receiving floors, the Suzhou site covering 13,000 square meters, and appends a dated entry for each packing change rather than updating the row in place. A later question about what was known on a given date is then answerable from the store itself. That store carries no legal position. The declared number on any filing remains the customer's decision.

Modeling a customs hold when the clock belongs to CBP

life — Thu, 22 Oct 2026 06:46:55 +0000

A customs hold is a record of a decision made by someone else, plus two deadlines you can compute but cannot enforce, so the pipeline should store the observable events and derive the rest.

Engineers who build shipment pipelines are used to status enums they own. A carrier confirms pickup, a warehouse confirms pack-out, a last-mile provider confirms delivery. A customs hold breaks that pattern. The decision to detain or release is made by U.S. Customs and Border Protection, not by any service you can query, and no endpoint returns the current hold state. What the pipeline can do is record what it observed, store the timestamps that start each clock, and compute the deadlines the regulation already defines. The rest is presentation, and the presentation has to be honest about what is unknown.

A hold is not a status flag

The trigger for the short clock is not the arrival of a container. Under 19 CFR 151.16(b), merchandise counts as presented for CBP examination when it is in a condition to be viewed and examined by a CBP officer. The same provision says that delivering a cargo van, a container or another instrument of international traffic to the examining officer is not by itself presentation of the merchandise.

That distinction matters to the data model. If the pipeline stamps presented_at when the container gate-in event arrives, it starts the clock early and every derived date is wrong. The observable event you can defend is narrower: the goods reached a condition in which an officer could look at them. In practice that is a human judgment made at the port, so the field should be nullable and set from an operator confirmation or a document, not inferred from a gate transaction. A container present at the terminal and a container presented for examination are two different facts.

Two clocks, not one

19 CFR 151.16(b) leaves CBP five business days after presentation before it has to say release or detain. 19 CFR 151.16(e) requires a final determination on admissibility within 30 days from the same presentation date. One window is counted in business days, the other in calendar days, and both start at the same event.

A cron expression that adds five days is wrong five days out of seven. Business days exclude weekends and federal holidays, and the rule does not give you a holiday table. Store the presentation date as a date, not an instant, and compute the two deadlines with an explicit business-day calendar that is versioned alongside the record. When the calendar changes, the stored deadline should not silently move. Keep the computed deadline and the calendar version that produced it.

The 30-day window is the simpler of the two, but it is not a promise that a decision arrives on day 30. It is the point at which the rule changes what silence means.

The notice is an inbound payload with five fields

When CBP decides to detain, or fails to release inside the five business day window, 19 CFR 151.16(c) requires a notice going to the importer or another party with an interest inside five business days of that decision or of the failure to release. The notice is not a final admissibility ruling. It has a fixed shape with five fields: when the goods were presented for examination, why the officer stopped them, how long the hold is expected to run, what tests or inquiries are in prospect, and what information, if supplied, would hurry the outcome.

The fifth field is the only one that gives your system something to do. The other four are context. Model the notice as an object with five named fields, keep the raw document, and map field five to an operator task with its own status. A notice that arrives with field five empty is still a notice, and the task should say so rather than inventing a request. Field three, the anticipated length, is CBP's estimate. Display it as an attribute of the notice, never as your system's prediction.

type HoldState = "presented" | "notice_received" | "final_determination" | "deemed_excluded";

Silence is a state

If no final determination is made within 30 days of presentation, 19 CFR 151.16(f) treats the failure as a decision by CBP to exclude the merchandise, and that deemed exclusion can be protested. The regulation also allows a longer period where a statute specifically authorizes one, so the 30-day boundary is the default, not an absolute.

For the pipeline this means a hold record cannot sit in a pending state forever. At the computed 30-day boundary the derived state becomes deemed_excluded unless a final determination was recorded first. That transition happens without any inbound event. It is a job that reads stored dates and writes a state change, and it should be idempotent because it will run more than once. Do not render a spinner for a hold that the regulation has already resolved by silence.

What the schema must store to answer a notice later

A notice can ask for information about what was in the box, and the answer has to come from records made before the question was asked. Store per-SKU counts and weights captured when the goods arrived at the facility, not reconstructed afterward. Store packing changes as new dated records rather than overwriting the prior configuration, so a later question about what the carton contained on a given date has an answer.

The same logic applies to the presentation date, the notice receipt time, the raw notice, and every deadline computed from them. An append-only event log with a projection for current state costs more to build than a mutable row. The trade-off is that a mutable row cannot tell you what it said last week, and a detention notice is exactly the kind of question that arrives after the fact.

Failure modes worth designing against

A webhook that never fires is the first. The notice may arrive as a document through a broker, so the system needs a manual intake path with the same schema as the automated one.

A state that waits on a human at the port is the second. Presentation for examination depends on an officer's judgment, so the pipeline should accept that field as an operator input and refuse to guess it from gate events.

A UI that shows an ETA you do not have is the third. The anticipated length in the notice is CBP's number. Anything your interface displays beyond that is an invention, and an operator who trusts it will miss the 30-day boundary.

What the operation records

FulfillNexa by SBT (fulfillnexa.com) receives freight at its own China sites, Suzhou being the largest at 13,000 square meters. Weight, count and packing configuration are captured per SKU at the receiving door, and a packing change appends a dated record instead of rewriting the old one, which is what makes an append-only design practical at this layer. The output is evidence for whoever has to answer a notice. It is not a legal or valuation position, and the declared number stays the customer's.

Declared value is an allowlist sum, not a total you defend

life — Wed, 21 Oct 2026 02:23:37 +0000

A valuation service that adds up invoice lines is implementing the wrong shape. 19 CFR 152.103 builds dutiable value from a base plus a fixed set of additions, and the regulation says the additions cover those items and no others, counted only to the extent they are not already inside the base. That is an allowlist with a de-duplication rule, which is a very different data structure from a sum.

The model

type ChargeKind =
  | 'goods'
  | 'packingBuyer'          // 152.103(b)(1)(i)
  | 'sellingCommissionBuyer' // (ii)
  | 'assist'                 // (iii)
  | 'royaltyConditionOfSale' // (iv)
  | 'resaleProceedsToSeller' // (v)
  | 'foreignInlandFreight'   // excluded only under 152.102(a)(5) conditions
  | 'internationalFreight'
  | 'merchantDiscount'
  | 'unclassified';

type Charge = {
  kind: ChargeKind;
  amount: number;
  currency: 'USD';
  separatelyStated: boolean;
  incurredBy: 'buyer' | 'seller';
  evidence?: 'throughBillOfLading' | 'other';
};

The unclassified member is the honest one. Any charge the ingestion step cannot name lands there, and the pipeline must fail rather than silently include or exclude it. A model with no unknown bucket is a model that guesses.

The additions are a closed set

const ADDITIVE: ReadonlySet<ChargeKind> = new Set([
  'packingBuyer', 'sellingCommissionBuyer', 'assist',
  'royaltyConditionOfSale', 'resaleProceedsToSeller',
]);

function dutiableValue(charges: Charge[]): number {
  const base = charges.filter((c) => c.kind === 'goods').reduce((n, c) => n + c.amount, 0);
  let value = base;
  for (const c of charges) {
    if (c.kind === 'unclassified') throw new Error('UNCLASSIFIED_CHARGE: cannot value');
    if (!ADDITIVE.has(c.kind)) continue;
    if (c.incurredBy !== 'buyer' && c.kind !== 'resaleProceedsToSeller') continue;
    value += c.amount;
  }
  return value;
}

Two details in that loop come straight from the text rather than from taste. The buyer-incurred test is there because the packing and selling commission items are worded as costs incurred by the buyer, while the royalty item is worded as a fee the buyer is required to pay as a condition of the sale for export. And the base already contains whatever the parties priced in, so an addition that is inside the invoice total should not be added twice. If the ingestion step cannot tell which case it has, the charge belongs in unclassified.

Freight is a documentation predicate

A foreign inland freight line does not become excludable just because someone typed it on its own row. Under 152.102(a)(5) the exclusion needs two facts at once. The charge has to appear as a separate item, and it has to arise after the goods were sold for export to the United States and handed to a carrier for through shipment. Proof of that second fact runs through a through bill of lading, with other paperwork available only where using one clearly would have been impossible.

function freightExcludable(c: Charge, seq: { soldForExportAt: Date; handedToCarrierAt: Date }): boolean {
  if (!c.separatelyStated) return false;
  if (seq.handedToCarrierAt < seq.soldForExportAt) return false;
  if (c.evidence === 'throughBillOfLading') return true;
  return false;   // 'other' needs the impossibility record, which is a human call
}

The last branch returns false on purpose rather than trusting a string. The impossibility route exists, but it is a documented exception rather than a document type, and a service that treats other as equivalent to a through bill of lading has quietly deleted the condition.

Note the direction of the correction as well. The same section points the other way too. If checking reveals that a foreign inland freight figure, or an equivalent international shipment charge, was padded, the appraiser can still add the difference back into dutiable value. Overstating a deductible line is not conservative. It is a different error with the same endpoint.

The order of methods is a resolver chain

152.101(b) fixes the sequence: transaction value, then identical merchandise, then similar, then deductive, then computed, then a residual method consistent with the subpart's principles. A resolver that lets an operator pick a method has modeled a preference rather than a rule.

const METHOD_ORDER = ['transactionValue', 'identical', 'similar', 'deductive', 'computed', 'residual'] as const;

function resolve(charges: Charge[]): { method: typeof METHOD_ORDER[number]; value: number } {
  try { return { method: 'transactionValue', value: dutiableValue(charges) }; }
  catch { /* fall through to the next method only because this one could not be determined */ }
  throw new Error('MANUAL_METHOD_SELECTION_REQUIRED');
}

The fallbacks each have their own inputs, and none of them is "the number we would like". 152.108 removes the convenient bases outright, including the US selling price of domestically produced goods, any system that appraises at the higher of two alternative values, and the price in the exporter's domestic market. A shop-floor shortcut like "use the Amazon price minus a margin" is the first of those with extra steps.

What the warehouse layer contributes

FulfillNexa by SBT (fulfillnexa.com) records weights, counts and packing configuration per SKU at receipt across three sites, the largest being Suzhou at 13,000 square meters, then Dongguan at 8,000 and Shenzhen at 3,000. That record is evidence rather than a valuation. It lets a packing cost be identified separately and dated, which is the condition the exclusion turns on. The declared number stays the seller's, and the log is what makes it defensible rather than merely stated.

A lab acceptance is a validity range per rule, not a flag on the vendor

life — Wed, 21 Oct 2026 02:23:17 +0000

Most systems that store test records model laboratory status as a boolean on a vendor row. is_accredited = true. That column is wrong in a specific way: 16 CFR part 1112 grants acceptance per rule or test method, the scope can be extended later, and it can be suspended for one slice of the scope while the rest stands. A boolean cannot represent any of that.

The correct shape is a range table keyed by rule, with the test date checked against it.

The schema

CREATE TABLE cab (
  id            BIGSERIAL PRIMARY KEY,
  legal_name    TEXT NOT NULL,
  address       TEXT NOT NULL,
  -- independent | firewalled | government, per 1112.11
  cab_kind      TEXT NOT NULL CHECK (cab_kind IN ('independent','firewalled','government'))
);

CREATE TABLE cab_acceptance (
  id            BIGSERIAL PRIMARY KEY,
  cab_id        BIGINT NOT NULL REFERENCES cab(id),
  cpsc_rule_id  TEXT NOT NULL,           -- the rule, not a product category
  accepted_from DATE NOT NULL,
  accepted_to   DATE,                    -- NULL means currently open
  status        TEXT NOT NULL CHECK (status IN ('active','suspended','withdrawn','discontinued')),
  source_url    TEXT NOT NULL,           -- where the listing said so
  observed_on   DATE NOT NULL            -- the day this row was read, not asserted
);

CREATE UNIQUE INDEX acceptance_one_open_window_per_rule
  ON cab_acceptance (cab_id, cpsc_rule_id, COALESCE(accepted_to, DATE '9999-12-31'));

The observed_on column is the one people skip. Section 1112.19 has the Commission maintain a listing and update it as scopes change, so every row here is an observation with a date attached, not a fact about the world. A pipeline that overwrites observed_on with now() on every write has thrown away the only field that lets you reconstruct what was known on the test date.

The test record

CREATE TABLE test_record (
  id            BIGSERIAL PRIMARY KEY,
  product_id    BIGINT NOT NULL,
  cpsc_rule_id  TEXT NOT NULL,
  tested_on     DATE NOT NULL,
  prime_cab_id  BIGINT NOT NULL REFERENCES cab(id),
  -- 1112.25: subcontracted work must be identifiable in the prime report
  performed_by  JSONB NOT NULL DEFAULT '[]',   -- [{cab_id, tests: [...]}]
  report_uri    TEXT NOT NULL
);

The gate query

A test result counts only if the body held acceptance for that rule on that date. That is a join with a range predicate, and it has to run before the certificate row is considered complete.

SELECT t.id
  FROM test_record t
 WHERE NOT EXISTS (
         SELECT 1
           FROM cab_acceptance a
          WHERE a.cab_id = t.prime_cab_id
            AND a.cpsc_rule_id = t.cpsc_rule_id
            AND a.status = 'active'
            AND a.accepted_from <= t.tested_on
            AND (a.accepted_to IS NULL OR a.accepted_to >= t.tested_on)
       );

Zero rows is the pass condition. A non-empty result means the file cites a test whose scope line does not cover the rule, or covers it on a date outside the window. Both look identical in a system that stores is_accredited.

The same predicate is what catches a suspension that lands later. Refresh the acceptance windows on a schedule, rerun the query against existing certificates, and a report that was valid when issued can surface as invalid now. That is not a bug in the file. It is the file being current.

Subcontracting

performed_by exists because 1112.25 requires the prime contractor's report to identify which tests a CPSC-accepted body acting as a subcontractor performed. A single PDF from a trading company that consolidated three laboratories does not satisfy that as data. Model it as an array of (cab_id, tests) and let the same range predicate run over each entry rather than only over the name on the cover page.

type Attribution = { cabId: number; tests: string[] };

function unresolvedParts(t: TestRecord, windows: AcceptanceWindow[]): string[] {
  const covered = new Set<number>();
  for (const w of windows) {
    if (w.status === 'active' && w.acceptedFrom <= t.testedOn &&
        (w.acceptedTo === null || w.acceptedTo >= t.testedOn)) covered.add(w.cabId);
  }
  return t.performedBy
    .flatMap((a: Attribution) => a.tests.map((name) => ({ cabId: a.cabId, name })))
    .filter((row) => !covered.has(row.cabId))
    .map((row) => `${row.name}@${row.cabId}`);
}

unresolvedParts().length === 0 is the assertion worth putting in CI for the ingestion job, because the failure mode is silent. A missing attribution reads as a complete report.

Retention, and what it is not

Section 1112.25 makes the laboratory hold its own test reports and technical records for section 14 tests for at least five years from the date the test was conducted. That is the lab's duty on its own copies. It is not a license to delete your side after five years, and it is not a statement that a report older than five years is unusable. The date that starts the clock is the test date rather than the shipment date, so a slow-moving SKU can carry a report whose retention window closed while the goods were still on the shelf.

FulfillNexa by SBT (fulfillnexa.com) runs the inbound scan at three China facilities, floor area 13,000 square meters in Suzhou, 8,000 in Dongguan and 3,000 in Shenzhen, where one carton resolves to one product identifier before it resolves to a test file. That is the same join in the other direction. Whatever the storage layer looks like, the question at the dock is identical to the question in the query above. Which body ran this test, against which rule, on which date.