Open-source manufacturing ERP, MES and QMS. Quoting, MRP, inventory, shop floor, quality and lot/serial traceability on one Postgres schema, with a REST API and MCP server. Self-host or use Carbon Cloud.
@carbon/database
DB types, Supabase/Kysely clients, audit config, event system types, rate limiting, migrations, and pagination utilities.
Always
- Use
pnpm db:migrate:new <name>to create migrations;pnpm db:migrateto apply (regenerates types). There is nodb:build. - Tables: composite PK
("id", "companyId"),iddefaultid()orid('prefix')— never raw UUID. Audit columns (createdBy/createdAt/updatedBy/updatedAt) with inlineREFERENCES "user"("id"). - RLS: every public table's policies are a rule in
src/authz/manifest.ts(usuallycompany("<module>")— the four standard policies) and the RLS helpers aresrc/authz/helpers/<name>.sql.pnpm db:migratesyncs them locally;pnpm --filter @carbon/database authz migration <name>ships them to production (migration.test.tsfails until it does). See.claude/rules/authz-manifest.md. - Event-system functions (dispatch, subscriptions, queue wake-up, audit log, search index, embeddings) are one file each in
src/event-system/functions/(<name>.sql,util.<name>.sqlfor theutilschema), synced and shipped by the sameauthz sync/authz migrationcommands. Edit the file; never redefine one in a migration. - Import
Databasetype from@carbon/database;KyselyDatabase/Kyselyfrom@carbon/database/client. A function that may be handed a transaction runs its writes throughwithTransaction(db, fn)from the same file: it joins the transactiondbalready is, else opens one (Kysely refusestransaction()on aTransaction). Never hand-editsrc/types.ts— it's generated. scriptRunis a deliberate exception to the table conventions above: nocompanyId, no composite PK, SELECT-only RLS. It is the per-database ledger of one-off scripts thatci/src/migrations.tsruns aftersupabase db push— seescripts/one-off/README.md.- User-owned preference rows are the other deliberate exception:
notificationPreference,userModulePreferenceandpushSubscriptionuse anxid()id, a single-columnPRIMARY KEY ("id")and nocreatedBy/updatedBy. A row belongs to one user and only that user writes it, so the audit columns would always repeatuserId. They keepcompanyId(FK,ON DELETE CASCADE) for tenant attribution and the RLS ruleowner("userId")+member("companyId").notificationPreference.companyIdis NULL for an account-level topic (only the changelog newsletter,getNotificationTopicScopein@carbon/notifications): one row per user, uniqueNULLS NOT DISTINCT, RLSowner("userId")alone for that row. No CHECK names the topics:getNotificationTopicScopeis the only place that decides, and every reader and writer goes throughnotificationPreferenceCompanyId, so a row stored under the wrong scope (a per-company newsletter row from an older backup) is never read.pushSubscriptionis unique per browserendpoint, not per company (one browser, one owner); see.ai/specs/2026-10-08-web-push-notifications.md. It is intentionally NOT tenant-scoped soselectWipeableTables(company-backup.ts) cannot select it and a company restore cannot erase it. A migration landing in this package is also what triggers those scripts to deploy (.github/workflows/supabase.ymlonly fires onpackages/database/supabase/**). - A new table whose CHECK needs one of several nullable FKs set (an invoice OR a memo,
imagePathORmodelUploadId) and that the demo datasets seed goes inPARENT_CHECK_TABLESinsrc/datasets/wipe.ts. The wipe before a re-apply nulls every nullable FK into a table it clears, so that CHECK aborts the whole apply ("new row … violates check constraint").pnpm db:check:datasetsre-applies each dataset over itself to catch exactly this. - Use
fetchAllFromTablefor paginated reads that exceed the 1000-row Supabase limit. It pages withoutcount: "exact"(aCOUNT(*) OVER ()per page is not free) and fetches the pages past the first concurrently.fetchAllRecordsis the same pager over a query FACTORY (() => builder) — a factory, because supabase-js builders are mutable, so concurrent awaits on one builder all fetch whichever.range()was set last. - Use
fetchAllByIds(ids, (batch) => query.in(col, batch).order(...))for a read keyed by an id list that can grow with the data. It sends 100 ids per request, because.in()writes every id into the URL and the gateway rejects a long request line (HTTP 431). It pages each group withfetchAllRecords, and one failed group fails the whole read.
Ask First
Adding a new event system handler type to the
handlerTypeCHECK constraint.Changing
audit.config.tsentity definitions (affects which tables get audited and how diffs are computed).Modifying
src/client.ts(the Node-only Kysely/node-postgres client shared by the apps, jobs and postings, including its NUMERIC/DATE type parsers).Declare event triggers in
src/event-system/attachments.ts, and write interceptor / statement-handler bodies as files insrc/event-system/handlers/.authz syncapplies both;authz migration <name>ships them. Never callattach_event_trigger,attach_statement_handlerorset_event_triggersin a migration.A table is realtime when its attachments entry lists
broadcast_table_changes.REALTIME_TABLES(src/realtime-tables.ts) is derived from the manifest. See.claude/rules/realtime-system.md.
Never
- Specify decimal places in
NUMERICcolumns (use bareNUMERIC). - Use
000000for the HHMMSS portion of migration timestamps (causes cross-branch collisions). - Recreate or call the retired RLS helpers
has_role,has_company_permission,get_companies_with_permission,get_permission_companies— dropped in20260927224314_retire-legacy-rls-helpers.sql(they admitted customer and supplier portal accounts);authz-fixes.test.sqlasserts they stay gone. - Write
CREATE/ALTER POLICYon a public table, or define a managed RLS helper or event-system function, in a migration — and never hand-edit a generated authz migration orsrc/authz/baseline.json. - Write a
SECURITY DEFINERfunction that trusts a company id from its caller withoutPERFORM assert_company_access(company_id)first — everypublicfunction is an API endpoint (see.claude/rules/database-migration-patterns.md). REVOKE EXECUTEon apublicfunction: on this Postgres image calling it then segfaults the backend. Guard inside the function, or make itSECURITY INVOKER.
Validation Commands
pnpm db:migrate # Apply pending migrations + regenerate types
pnpm db:types # Regenerate types only
pnpm db:check:datasets # Validate + dry-run every demo dataset against the schema (writes nothing)
pnpm --filter @carbon/database typecheck
pnpm --filter @carbon/database test
pnpm --filter @carbon/database authz check # local DB vs manifest (exit 3 = drift)
pnpm --filter @carbon/database authz migration <name> # ship unshipped rules/helpers
Key Exports
| Subpath | Provides |
|---|---|
. (index) |
Database type, fetchAllFromTable, fetchAllRecords (takes a query factory), fetchAllByIds (100 ids per .in() request, each group paged), fetchRecordsInBatches, journalReference (journalLine.documentLineReference values). The datetime derivation API lives in @carbon/utils |
./client |
Node-only. Kysely, KyselyDatabase, getPostgresClient, and getProcessPool() (one shared pool per process — never create another, never end it outside an exiting script); registers the NUMERIC → Number and DATE → YYYY-MM-DD type parsers at module load (see .claude/rules/numeric-precision.md) |
./methods |
Make-method helpers shared by get-method and @carbon/planning (getJobMethodTree, getQuoteMethodTree, traverseJobMethod, calculateQuoteLinePrices, …) |
./job-quantities-engine |
computeJobQuantities / flattenJobQuantityTree — the pure job-quantity cascade behind the recalculate posting |
./mrp-engine |
explodeBom, makeKey, makeLocationItemKey, makeActualKey, … — the pure MRP compute engine consumed by @carbon/planning's runMrp and by getMethod (production.service.ts) |
./configuration-rule |
runConfigurationRule — runs configurator rule code in QuickJS (WebAssembly) with no host access and time/memory limits — plus transpileRule (sucrase: wraps a stored rule body in configure(params) and strips its types, throws on a syntax error). Both are used by getMethod (apps/erp/app/modules/production/production.service.ts, importTypeScript) and the ERP rule editor, so a preview and a job run the same JavaScript. Never run rule code with new Function/eval/import() |
./rows |
PostgREST-shaped reads and writes over Kysely (selectRows, single / maybeSingle / many with { data, error }, insertRows / updateRows / deleteRows, rpcRows / rpcValue, inOrder, filter helpers isNull / notNull / neq / notIn / …). Rows go through to_jsonb, so they equal what PostgREST returns. Used by every posting and by calculateQuoteLinePrices when it is given a Kysely handle |
./fetch-all |
fetchAll — serial paginated PostgREST reads from a query factory (the root's fetchAllRecords is the concurrent, strictly typed variant) |
./json |
toJson / toJsonColumns — pre-serialise json/jsonb values written through Kysely (the driver sends strings and arrays unquoted) |
./price-trace |
quoteToOrderPriceTrace — the price trace a sales order line carries when convertDocument (shared.service.ts, ported from the convert server function) turns a quote into an order |
./account-import |
Client-safe, pure. The chart of accounts import planner: planAccountImport(chartRows, defaultRows, ctx, resolutions) (the customer's chart and default accounts file + group context → claims, updates, creates, merges, plain deletes, replacements (accounts in use that need a target row, with the pick), role and fixed asset class moves, errors), isApplicable, REFERENCE_POLICY (every foreign key to account as a policy union — repoint, repoint-if-status, repoint-if-parent-status, history; the apply-account-import live test compares it with the catalog), requiredRoles, ROLE_NAMES, assetClassKey / assetClassLabel / defaultKeyLabel, classOfAccountType. Pinned by account-import.test.ts |
./account-import-reads |
Server-only. loadAccountImportContext(db, companyGroupId, companyId) — the chart, the group's companies (with their cutover), defaults and fixed asset classes, and per account the references a merge moves (documents, posted or not, Draft or Provisional journal lines, and the references with no foreign key) and the history it cannot, one query per table. isAccountInUse(db, companyGroupId, accountId) — whether anything in the group refers to an account, from the same list, so a false answer means a delete will not be refused |
./supersession-pick |
The supersession rules shared by MRP, get-method and picking (buildSupersessionRedirectMap, buildConsumeFirstHops, settleConsumeFirstLine, resolveMadeLinePull, consumableInWholeAssemblies, …) |
./strict-backflush |
Client-safe (type-only Kysely import; no ./rows, so the BoM badges can bundle it). The strict backflush rules shared by activation, release, the backflush, the badges and the settings card: needsPullFrom / PULLED_ITEM_TYPES, missingPullFromLocations, getPullFromLocations / isPullFromLocation (an active work center AND an active storage unit), getStrictBackflushSettings (the location gates strict), getMethodPartsMissingPullFrom + activationRefusalMessage, pullFromStorageUnit (a picked line's Pull From: the oldest pick line's source), strictBackflushLockKey (the advisory lock key SQL backflush_job_materials builds too), binShortfall, summarizeList / MESSAGE_LIST_LIMIT. Pinned by strict-backflush.test.ts |
./supplier-part-price |
Supplier part prices are stored as quoted (per purchase unit, in the part's currencyCode); convertUnitPrice puts one on a purchase document in its currency, buildSupplierPriceMap turns them into base per-inventory-unit costing breaks. Shared by the ERP, methods.ts and the postings so every reader converts the same way |
./picked-consumption |
Consumption follows what was picked (linesideCredit, getPickedBudgets, allocateAcrossBudgets, …) — the one definition of usable lineside stock shared by the pick-list generator and the issue backflush |
./machine-time |
Every function takes a Kysely transaction (KyselyTx). The locks and writes that end machine time, shared by the OEE sync, the MES Machine button, the device mapping writes and the Sense uninstall hook: lockWorkCenterDevice (FOR UPDATE on the work center's workCenterDevice row), lockMachinePress (that lock, then a transaction advisory lock per work center — the one lock order every writer takes), recordManualMachinePress (a Machine Start/Pause: takes the press time under the locks unless given, ends every open Machine event on the work center at it, and on a mapped work center ends the open unattributed time and sets lastManualChangeAt via GREATEST and unplannedPressAt via LEAST; returns { mapped, endedEventIds, pressedAt }), endSensorMachineTime (ends the system Machine events and the open unattributed time when a device leaves a work center). Pinned by machine-time.test.ts (needs SUPABASE_DB_URL). See .claude/rules/oee-provider.md |
./posting |
buildPaymentJournal / buildMemoJournal (src/build-payment-journal.ts, src/build-memo-journal.ts) for postPayment / postMemo (invoicing.service.ts, ported from the server functions) and the dataset tiers |
./precision / ./accounting-currency / ./accounting-posting / ./sales-posting-amounts / ./ledger |
The pure numeric-precision API, FX conversion, journal role vocabulary, sales posting amounts, and ledger helpers (AccountType, AccountClass, isAccountClass, credit, debit, accountTypeFromClass, debitSigned — the debit-signed value of a natural-signed amount on a class, and back; toStoredAmount — the natural-signed amount of a debit or a credit). They live here, not in @carbon/utils, because the posting builders need them and this package cannot import @carbon/utils (turbo cycle); @carbon/utils re-exports them, so app code imports them from there. Keep them free of imports outside each other |
./run-journals |
Client-safe, pure. The one construction of the period-run and scrap journals: buildDepreciationJournals, buildDeferredTaxJournals (with deferredTaxSettings and DEFERRED_TAX_MIN_AMOUNT), buildDisposalJournal, buildRecognitionJournals (with recognitionAccountWithoutClass; its sources.leases / sources.leaseAssets are required, and a lessee row whose lease or asset is not in them throws). Lines carry dimension values by entity type; the caller writes the journal, its period and status, line references and dimension ids. Used by the ERP's postDepreciationRun / postDisposal / postRevenueRecognitionRun (accounting.service.ts) and the enable's legacy backfill (activateAccounting, same file), pinned by run-journals.test.ts |
./run-type |
Client-safe. The two period runs on one engine: RunType, RUN_SEQUENCE, RUN_LABEL / runLabelSentence, RUN_SOURCE_TYPE (the journal source type a run posts as — a lease run's is Lease Run, read by buildRecognitionJournals), runTypeFilter (the revenueRecognitionSchedule rows a run claims) and runTypeOfScheduleRow |
./lease-months |
Client-safe, pure. Lessee lease months: addMonths (clamped), leaseMonthsAt, leaseMonthsThrough, leaseMonthEnd, leaseMonthShare, paymentMonthIndex and scheduleMonthOfPayment (the schedule month that pays a payment point). Re-exported by @carbon/utils lease-math, and read by the accounting cutover's open items (accounting-cutover/lease-payments.ts), so the opening lease balances count payments the way the schedule pays them |
./accounting-posting |
Client-safe. The journal status lists each kind of reader uses: GL_JOURNAL_STATUSES (Posted, Reversed — balances, reports, tie-outs), DOCUMENT_JOURNAL_STATUSES (Provisional, Posted, Reversed — one document's chain), OPEN_ITEM_JOURNAL_STATUSES (Provisional, Posted — payment control lines, void checks), and PRE_CUTOVER_JOURNAL_STATUSES (Provisional, Superseded — the statuses only a posting from before the cutover carries; no balance or chain reader uses it). Also the posting descriptions and classifyAccountingPostingRole |
./journal-posting-status |
Server-only. The status an automatic posting writes: journalPostingStatus / readAccountingCutoverDate (read companySettings FOR SHARE), postingStatusFor, assertPostingStatusUnchanged (the in-transaction re-read, throws POSTING_STATUS_CHANGED_ERROR). And the account a line takes when its default is empty: OPTIONAL_DEFAULT_ROLES, DEFAULT_FALLBACKS (used in every company state), resolveDefaultAccount (a stand-in on retained earnings before the cutover), configuredDefaultAccount, MissingAccountDefaultError (status 400, message from missingDefaultMessage with the OPTIONAL_DEFAULT_LABELS label) |
./accounting-cutover-dates |
isBeforeCutover(postingDate, cutoverDate) — the date rule of the pre-cutover voids; false when the company has no cutover |
./cost-relief |
The one definition of FIFO / LIFO cost relief, pure: isCostLayer / isCostRelief (Kysely filters for the costLedger rows that open or relieve a layer; a job return is not a layer), orderLayersForConsumption (serial units first), relieveLayers (one relief) and replayReliefs (a sequence of layers and reliefs). Used by calculateCOGS, the enable's re-cost (recostOutbound), the cutover inventory and the legacy movement costs |
./payment-processor-fee |
Server-only. readPaymentProcessorFees — the processor fee a payment withheld, read from its stripe-connect externalIntegrationMapping row, so a payment journal built again (a pre-cutover void, a legacy payment) books the fee the posting booked. Also countedProcessorFee, processorFeeAccount, MISSING_PROCESSOR_FEE_ACCOUNT_ERROR |
./accounting-cutover-reads |
Server-only. The accounting cutover's reads over Kysely (getActivationReadiness, getCutoverOpenItems, getCutoverInventory, getCutoverFixedAssets, getMigrationClearing, getCutoverOpeningInputs, getLegacyDocumentCounts, hasLegacyDocuments — one statement of EXISTS tests over the same detection, for a yes/no) and its pre-enable writes (saveOpeningTrialBalance, applyCarbonToOpeningTrialBalance, setCutoverInvoiceIgnored — the accountingCutoverIgnoredInvoice rows getCutoverOpeningInputs leaves out of items and returns as ignoredItems, except an invoice in settledFromCutoverIds (settled in Carbon on or after the cutover), which stays open — and updateCutoverAccumulatedDepreciation, which refuse after the cutover by reading it FOR SHARE). Each takes a Kysely or a Transaction first, so the wizard loaders and the enable transaction run the same queries. The file is only the public entry: the reads live in src/accounting-cutover/ (shared.ts — the company, its defaults and ACCOUNT_DEFAULT_COLUMNS, the explicit list readiness requires, checked against the table at compile time; readiness.ts, open-items.ts, inventory.ts, fixed-assets.ts, trial-balance.ts, legacy-counts.ts, and lease-payments.ts — the payments a lease's schedule and its invoices disagree on at the cutover, which move the opening lease liability and net investment) |
./accounting-cutover |
Client-safe. The pure planner (buildOpeningJournalLines — takes the Migration Clearing account with its class, refuses one that is not Equity and refuses unbalanced lines — migrationClearingByAccount, isIgnorableOpenItem, applyCarbonToTrialBalance, planInventoryReset, unitCostAtCutover, recostOutbound) and the values the ERP and the enable must agree on: MIGRATION_CLEARING_TOLERANCE / isMigrationClearingZero, MIGRATION_CLEARING_ACCOUNT_CLASS, ACTIVATION_CUTOVER_PARAM, dayBeforeCutover |
./legacy-documents |
Server-only. The one detection of legacy documents (.ai/specs/implemented/2026-10-08-accounting-cutover.md section 5a): posted, dated on or after the cutover, with no journal. Each function (legacySalesInvoices, legacyPayments, legacyShipments, legacyAdjustmentCostRows, legacyJobMovements, legacyDepreciationRunLines, …) returns a Kysely query, not rows: activateAccounting (accounting.service.ts, ported from the activate-accounting server function) executes it, and getLegacyDocumentCounts (./accounting-cutover-reads) counts the same rows for the wizard. Also LEGACY_DOCUMENT_FAMILIES (the families in the order the enable writes them), LegacyDocumentCounts, assetsLeavingWithoutJournal and REBUILT_DISPOSAL_METHOD |
./deposit-scope |
loadSalesInvoiceDocumentIds (the rental agreements / sales orders each sales invoice bills, one query) and loadDepositScope (a deposit payment's document + readable id) — the reads behind "a customer deposit funds only its own document", shared by replaceInvoiceSettlements and post-payment |
./sequence |
getNextSequences (count numbers in one statement; getNextSequence is its count-of-one) / getNextRevisionSequence — document numbers, formatted in TypeScript (date tokens in the company timezone). getNextSerialNumbers — serial numbers, a wrapper over SQL get_next_serial_numbers, which formats them so the job completion in SQL and TypeScript callers agree. Serial number timing: getSerialNumberTiming (the item's, else the company's), resolveSerialNumberTiming (the same from an item value already read), assignSerialNumberIfMissing (first-touch numbering of one unit), getSpawnSerialNumber (the number for a spawned unit, null under production) |
./serial-number-timing |
Client-safe. serialNumberTimings, SerialNumberTiming, asSerialNumberTiming — the timing values the ERP's forms and tables import; ./sequence re-exports them |
./receipt-serials |
releaseReceiptSerialEntities(db, companyId, ids) — the one way a receipt serial is taken off a receipt, inside the caller's Kysely transaction: an entity with no itemLedger history is deleted, one with history only loses its Receipt / Receipt Line / Receipt Line Index attributes. Shared by the ERP's receipt serial routes and the receipt line split (receiptLineSplit in shared.service.ts). planReceiptSerialRelease is the pure split; idsWithStockHistory is the one "has stock movements" test. idsWithLiveStockHistory is the same test without the rows of voided receipts (a void writes its reversal under the receipt's documentId), and voidedReceiptIds filters receipt ids to the voided ones — together they let a serial from a voided receipt be received again as the same entity |
./stock-transfer |
expandSerialTrackedLines, isBelowReplenishmentLevel, levelReplenishmentQuantity (the fewest whole kanban quantities that reach a level), kanbanReplenishmentNote — the stock-transfer line and kanban-note rules shared by the ERP's insertStockTransfer and replenishKanban (inventory.service.ts, ported from the kanban-replenish server function) |
./seed-data |
The company seed data (accounts, sequences, groups + getGroupId, …) used by seedCompany (settings.service.ts, ported from the seed-company server function) and the dataset tooling |
| (no subpath) | src/sql-effects.ts — sqlFunctionEffects(sources) / loadSqlFunctionEffects(): whether a SQL function writes, reads or cannot be told, read off its current definition with libpg-query (every migration, then the managed function files). The API generator imports it by path to refuse a read tool that calls a writing function. An extension function it meets must be added to EXTERNAL_READS or EXTERNAL_WRITES; reviewed dynamic SQL to REVIEWED_DYNAMIC_READS |
./event |
QueueMessage, EventSchema, createEventSystemSubscription, deleteEventSystemSubscription |
./quality |
Inspection execution engine shared by ERP + MES (upsertInspectionSample, upsertInspectionMeasurement, dispositionInspection — optional one-shot requireOpen, reconcileInspectionSamplingPlans, changeInspectionDocument, getOrCreateJobOperationInspection, pure valuateMeasurement, from src/inspection-verdict.ts, which the dataset seed shares); Passed/Failed/Partial are all hard-terminal and samples linked from productionQuantity.inspectionSampleId are locked; every fn takes a Kysely<KyselyDatabase> first arg — authorize at the route, see .claude/rules/inspection-system.md |
./sampling |
Z1.4 / ISO 2859-1 sampling resolvers (resolveSamplingPlan, resolveFeatureSamplingPlan) used by post-receipt and the inspection engine |
./audit.config / ./audit.types |
auditConfig, AuditEntityType, getAuditableTableNames, and the audit type surface. The audit ENGINE (getEntityAuditLog, enableAuditLog, insertAuditLogEntries, …) MOVED to the commercial @carbon/ee/audit.server; config + types stay here (client-safe, generic schema types consumed by CE packages) |
./ratelimit |
checkApiKeyRateLimit (Postgres RPC wrapper) |
./datasets |
applyDataset(pgClient, { companyId, userId, dataset, timeZone, wipeFirst? }) — the one entry point that fills a company with an industry dataset, in a single transaction; wipeFirst clears prior business data inside that same transaction while preserving bootstrap config. Plus DATASETS, getDataset, datasetKeys, datasetForIndustry. Consumed by onboarding (industry.tsx) and the company-template Inngest job. See Dev Seed below |
./seed-workflows |
buildSeedWorkflows, SEED_WORKFLOW_BUILDERS, EVENT_SOURCES — the seeded workflow definitions and tier 11's event→table map (datasets/tiers/workflow-definitions.ts); @carbon/ee's seed-workflows.test.ts pins both to the workflow catalog |
./dataset-rule-fields |
RULE_FIELDS — the rule-builder fields a seeded sales/storage rule may test (datasets/rule-fields.ts); @carbon/utils's field-registry.test.ts pins it to field-registry.ts |
. (root, from src/timezone.ts + src/utils.ts) |
getCompanyTimeZone(db, companyId) / getLocationTimeZone(db, locationId, companyId) — business-timezone resolvers, overloaded for Supabase client or Kysely handle (they throw on query failure rather than silently falling back); AnyPostgresClient + isKysely guard for writing such overloads. SQL siblings: company_today(companyId) / location_today(locationId, companyId) replace CURRENT_DATE for business dates in DB functions (SECURITY INVOKER — callers must be SECURITY DEFINER or service-role). ERP routes should prefer the Redis-cached wrappers of the same names in ~/modules/shared/shared.service |
Dev Seed
src/datasets/ splits data from engine, and both the dev CLI and onboarding's
company-template job go through the same applyDataset() entry point (./datasets).
- Data —
data/<key>/, one file per slice, pure TypeScript literals with no SQL and no ids. Registered inDATASETS(datasets/index.ts). Five keys ship today, one per onboarding industry:satellite,robotics,precision,motor,defense. New seed data goes here, not in a tier: the tiers are industry-agnostic shared code, and hard-coding one industry's content into them breaks every other dataset. - Engine —
tiers/01-foundation.ts…tiers/12-planning.ts, run in numeric order because each tier depends on ids the earlier ones put inctx.refs. The ordering IS the contract. Change a tier only to support a new shape of data. ADatasethas twelve slices;ops(tier 10) carries maintenance, training, timecards, suggestions and notes.
Dates are signed day-offsets resolved against the company's today — never JS Date, never
CURRENT_DATE in a tier's SQL. Primary keys must never be literals: several tables
(externalLink, period) have globally-unique keys, so a fixed id collides on the second
company seeded into the same database.
pnpm db:seed:dev runs src/seed-dev.ts (the dev CLI); cli.ts parses its args,
bootstrap.ts sets up the company and wipe.ts clears prior data. cli.ts and bootstrap.ts
are dev tooling (the dev CLI and the drift check), outside the ./datasets export. wipe.ts is
reached from the shared engine via applyDataset's wipeFirst option, which both the dev CLI
and the company-template job use; it is not exported on its own.
After its seed commits, seed-dev.ts spawns pnpm --filter @carbon/jobs plan:company -- --company <id> --user <id> to run MRP + the scheduler (a spawn, not an import:
@carbon/planning depends on this package). --skip-plan opts out; a failed run only prints
a warning with the command to re-run. Under portless it passes
NODE_EXTRA_CA_CERTS=~/.portless/ca.pem when that file exists and the variable is unset.
pnpm db:check:datasets (src/check-datasets.ts) has two layers. First the pure
validateDataset (datasets/validate.ts) cross-checks every dataset with no database —
ref resolution, required status coverage, on-hand ≥ 0, journal balance, settlement
consistency — so a broken dataset blocks the commit even when the stack is down. Then datasets/verify.ts applies every dataset to
a scratch company, asserts the datasets/coverage.ts row-count floors, and always rolls back,
so it writes nothing; this layer skips with a warning when there is no database. The pre-commit
hook runs it on any packages/database/** change.
Per-module seed scripts were folded into this structure: seed-change-orders.ts and its
db:seed:change-orders script are gone, replaced by tiers/08-change-orders.ts.
Full feature context: .claude/rules/onboarding-company-templates.md.
Cross-References
.claude/rules/conventions-database.md— table template, column types, migration checklist.claude/rules/database-patterns.md— client factories, services, Kysely transactions.claude/rules/authz-manifest.md— RLS policies and helpers: manifest, sync, shipping.claude/rules/database-migration-patterns.md— SQL conventions, enums, triggers, RLS for tables withoutcompanyId.claude/rules/event-system.md— trigger dispatch, PGMQ queue, handler typespackages/auth/— Supabase client factories (getCarbon,getCarbonServiceRole)packages/jobs/— Inngest event handlers that consume the event queue