`crm_opportunity_line_item.line_number` has no writer, yet the billing hand-off payload ships it on every won deal

[os-steve]

Found while working #1826 (the field-no-consumers display gaps). ⛔ Out of that card's scope — filed rather than fixed there.

The finding

crm_opportunity_line_item.line_number is Field.number({ readonly: true }). Grep the tree for every site that names it, and nothing writes it:

• no hook — opportunity_line_item.hook.ts and the shared _line-item-price-fill.ts never touch it;
• no flow node, no action;
• readonly: true means a user cannot type it either, and since @objectstack/objectql@17.4.0 a static readonly field is stripped from a non-system caller's INSERT as well, so an ordinary rep creating a line cannot seed it even by accident.

The only values that exist are the 19 rows in src/data/, which the seed loader writes as a system caller. test/seed-consistency.test.ts pins those to be 1..n within each parent — a pin on the seed fixture, not evidence of a runtime writer.

Why it matters beyond a blank column

src/flows/billing-handoff.flow.ts puts line_number in LINE_ITEM_FIELDS, the projection that composes the billing payload for both closed_won and contract-activated hand-offs. That payload is described in content/docs/revenue/billing-handoff.mdx (three locales) with "line_number": 1 in the worked example.

So the app hands the billing system a field that is null on every line item created in the product, and non-null only on demo seed rows. The docblock on that flow is explicit that the payload "IS the contract with the billing system" and is authored field-by-field so it cannot silently drift — this is a drift it did not catch, because the field is declared and merely never filled.

The decision this needs

Two coherent answers, and it is a product call, not a mechanical one:

1. Give the ordinal a writer. A per-parent assigner on insert, in the shape _line-item-price-fill.ts already establishes for this pair of objects. Because the field is readonly, the writer has to be a system-context path — which puts it under AGENTS.md house rule 9 (elevate as little as possible), the same question Migrate this repo onto the @objectstack/* 17.4.0 line — the whole-line pin bump, the spec rename via the platform's own codemod, and the two contract changes it surfaces (epic #1579) #1807 settled for crm_campaign_member.added_date. A line then carries a stable ordinal and the billing payload becomes truthful.
2. Retire the ordinal. If the ordering a reader wants is the related list's own sort, the column is a promise nothing keeps. Removal has to clean the declaration plus its carrier sites and drop the key from LINE_ITEM_FIELDS and the three billing-handoff doc pages.

⚠️ Note the twin: crm_quote_line_item.line_number has exactly the same gap, and is the reason that field is reported standing on #1826 rather than given a view column — a column there would render blank on every row a user creates. Whichever answer is chosen should cover both objects, since the two line-item objects deliberately mirror each other.

Refs: #1826 · #1807 (the readonly + elevation precedent) · #1667.

[hotlong]

Ruling: batch #163 item 2 · letter 1 (line_number gets a writer: a per-parent ordinal assigned on insert in system context, in the shape _line-item-price-fill.ts already establishes for this pair — for crm_opportunity_line_item AND crm_quote_line_item; the fields stay readonly) · maintainer 「163 同意」 2026-09-18T14:09Z

Director seat, summon #24, session_01Wj1HUjzyeiBQ8atRf1ZhaL. Presented in detail with the recommendation 1; the maintainer agreed. Facts (this card): crm_opportunity_line_item.line_number is Field.number({ readonly: true }) with no hook, flow or action writing it; since @objectstack/objectql@17.4.0 a static readonly field is stripped from a non-system caller's INSERT, so only the 19 seed rows carry values; billing-handoff.flow.ts ships line_number in LINE_ITEM_FIELDS — the payload its docblock calls the contract with the billing system — and three locales of billing-handoff.mdx show "line_number": 1. Mainstream: Salesforce QuoteLineItem.LineNumber is auto-assigned; OpportunityLineItem carries SortOrder.

Ruling — 1

• On insert of a line item, a system-context assigner writes line_number = (max ordinal under the parent) + 1, for both objects; elevation is the minimum Migrate this repo onto the @objectstack/* 17.4.0 line — the whole-line pin bump, the spec rename via the platform's own codemod, and the two contract changes it surfaces (epic #1579) #1807 settled for crm_campaign_member.added_date. Existing rows with null get back-filled once, in parent order, by the same PR (a one-off system write, ⛔ not a migration framework).
• readonly: true stays — the ordinal is platform-assigned; the seed fixture pin (1..n per parent) becomes a runtime pin too.
• The billing payload and the docs become truthful without changes; ⛔ 2 (retire) would remove a field the billing contract carries.

Four-facet reading: ① the payload contract stops lying; ② the billing system receives the ordinal it was promised; ③ the doc example is true; ④ one hook shape reused, two objects.

Execution

needs-user-decision → pm:queue; metadata stays. Covers #1199's crm_quote_line_item.line_number row. Clause-②: no.

---

Generated by Claude Code

[objectstack-fleet]

Claim: PM loop round R64 (serial dispatch, maintainer instruction verbatim: 「串行派发」) · 2026-09-25T13:29Z
Session: session_01X8U3asekbiC7yWoEPWR4Dg
Branch: claude/issue-1828-line-number-writer
Worktree: hotcrm-issue-1828
Domain: repo:hotcrm (single-lane repo — no domain:* taxonomy)
Seat: repo:hotcrm#1
File surface: src/revenue/objects/opportunity_line_item.hook.ts, src/revenue/objects/quote_line_item.hook.ts, the shared price-fill helper the ruling names (_line-item-price-fill.ts — locate it), a one-off back-fill in the same PR, the line-item tests, content/docs/**/billing-handoff* only if the payload description changes, one .changeset/ (stop on breach; explain in the report)
Container & model: M, mode:subagent, model: opus — default judgement tier, hand-picked (dispatch-gates --tier refuses hotcrm paths from the objectstack checkout)
Clause-②: no
Thread-read: 5731202044
Serial constraints cleared: open PRs — #1950 (epic) touches src/sales/objects/opportunity.hook.ts only among hooks, which is disjoint from the line-item hooks; #1956 (#549) touches quote.object.ts and contract.object.ts, not line items; #1959 (#1258) touches src/sales/data/activity.seed.ts and objectstack.composition.ts. If a seed file needs line_number values, merge main after #1959 lands. #1958 (merged) added relatedListColumns on quote_line_item.object.ts; this card does not edit object files.

[objectstack-fleet]

os-dev-report
{
"issue": 1828,
"status": "done",
"branch": "claude/issue-1828-line-number-writer",
"pr": "#1960",
"session": "session_01X8U3asekbiC7yWoEPWR4Dg (subagent; parent claim comment 5833224216 names this branch)",
"premise_still_valid": true,
"summary": "Premise confirmed on base aa61e1d live: an admin REST insert of either line item stores line_number null, and a supplied 99 is dropped. New shared factory createLineItemNumbering in src/revenue/objects/_line-item-price-fill.ts, registered on both objects (opportunity_line_item_line_number, quote_line_item_line_number; beforeInsert+beforeUpdate, runAs system, priority 110): insert stamps max-under-parent + 1 (+ dispatch.index in a per-row batch); update stamps only a row with no stored ordinal and never renumbers; a no-user system write supplying a number (seed + boot replay) keeps it. One-off back-fill = scripts/backfill-line-number.ts in the backfill-owner-id.ts shape: it PATCHes {line_number: null} per null row, parent by parent, oldest first, and the hook update branch stamps it. readonly: true unchanged; billing payload and docs unchanged (now truthful). Ruling items quoted: "On insert of a line item, a system-context assigner writes line_number = (max ordinal under the parent) + 1, for both objects; elevation is the minimum #1807 settled ... Existing rows with null get back-filled once, in parent order, by the same PR (a one-off system write, not a migration framework)." / "readonly: true stays — the ordinal is platform-assigned; the seed fixture pin (1..n per parent) becomes a runtime pin too." / "The billing payload and the docs become truthful without changes; 2 (retire) would remove a field the billing contract carries." / Execution: "Covers #1199 crm_quote_line_item.line_number row. Clause-2: no" (so no Clause line in the PR body).",
"mechanism_A1": "MEASURED, and sharper than assumed: objectql 17.4.0 stripReadonlyFields skips hookWrittenKeys, so a before-hook write to line_number survives a NON-system insert/update with no elevated write; the engine strip warning itself says "a beforeInsert hook does NOT need this because hook-written keys are not caller-supplied". runAs system therefore elevates only the sibling max read (withRunAs → sudo). Control in the test: hook unbound, rep-supplied 99 is dropped and the row stores none.",
"insert_measurement": "Real ObjectQL (InMemoryDriver, shipped schemas, shipped hooks), context {userId: rep_1}: 3 inserts under p1 → [1,2,3], p2 → [1]; supplied line_number 99 → stored 2; after delete of line 2 the next is 4 ([1,3,4]); batch of 3 → [1,2,3]; system no-user insert with 7 keeps 7; rep update with line_number 42 on a numbered row keeps 1. Both objects. Live on this branch (sqlite dev server, admin REST = non-system): POST crm_opportunity_line_item with line_number 99 → stored 6 (deal numbered 1..5) and 4 (deal numbered 1..3); next POST without it → 7 and 5. Base aa61e1d, same calls: stored null on both objects.",
"backfill_measurement": "DB created on base aa61e1d with 2 null rows under one opportunity (seed rows 1,2,3) and 2 under one draft quote (seed rows 1..4); branch server booted on a copy (boot replay left the nulls untouched). Report: 2 null rows per object, 1 parent each, exit 0. --apply: Backfilled 2/2 per object, 0 left, exit 0; opportunity parent became 1,2,3,4,5 and quote parent 1..6, each in created_at order. Rerun --apply: 0 rows, exit 0 (idempotent). Engine-level twin in test/line-item-line-number.test.ts (rows inserted with the hook unbound, then touched with the hook bound → [1,2,3], second pass unchanged).",
"billing_payload_reading": "Branch server built with HOTCRM_BILLING_ENDPOINT=http://127.0.0.1:4099/billing and a local receiver; Wayne Enterprise License (seed lines 1..3, plus 2 rep-created lines) closed_won after approving the 2 approval requests the line adds triggered and setting win_reason. Captured POST body keys event, version, occurred_at, opportunity, account, line_items; line_items[].line_number = 1,2,3 (seed) and 4,5 (rep-created): non-null on every line. Docs example "line_number": 1 now true; no docs edit.",
"concurrency_A3": "max+1 is read-then-write; no unique index on (parent, line_number); the hook opens no transaction (it runs inside the caller transaction when one exists). Two simultaneous inserts under the same parent can collide. UI reach: the only creator is the related-list Add picker, and objectui plugin-detail RelatedList.tsx awaits each create sequentially, so one user action cannot collide with itself; it needs two users adding lines to the same deal/quote at the same instant. No locking added.",
"backfill_site_A4": "Chosen: a REST script in the shape of scripts/backfill-owner-id.ts (the repo existing one-off). Rejected: a scheduled runAs-system flow sweep (demo_bootstrap shape) because get_record offers no sort, so creation order within a parent cannot be kept, and a new flow must also join the automation docs table in 3 locales (surface breach). A REST caller cannot write a readonly column itself (admin is non-system, the strip bites), hence the hook update branch is the writer and the script only touches. Idempotent: it selects only rows with no ordinal and the hook never renumbers.",
"tests": "All at head 946e409 under os-verify-lock (slot hotcrm-1828), each step exit captured: pnpm validate 0 | typecheck 0 | lint 0 | lint:i18n-gate 0 | hygiene 0 | hygiene:tokens 0 | build 0 | test 0 (Test Files 173 passed; Tests 3713 passed, 1 skipped). Lint field-no-consumers: 5 before (crm_quote_line_item.line_number named, carrier-only, 23 carrier sites) → 4 after, not named. Token ratchet src/revenue: business semantics 15,193 → 15,626 (ceiling 16,000, headroom 374); authored total 18,303 → 18,736 (ceiling 19,000, headroom 264); interaction layer unchanged 2,136; no ceiling touched. Targeted: vitest test/line-item-line-number.test.ts 24/24; plus runtime-coverage, action-sandbox, opportunity-line-item-add-picker, seed-consistency, flow-billing-handoff: 6 files 193/193. First full run caught runtime-coverage (new hooks not in a runtime file) → file added to RUNTIME_TEST_FILES. Ablation (one-off, committed state first): the stamp line replaced on disk via python with count assert (anchor grep 1 → 0, marker 0 → 1), trap-restore armed with absolute path; run: 14 failed / 10 passed of 24 (the 10 = metadata, seed-keep insert/update, strip control, lowering, both objects); restored with git checkout HEAD --, git diff HEAD 0 lines, blob hash a7a48079 equals HEAD blob; rerun 24/24. No dist involved (tests import src). NOT MEASURED: none.",
"gates": {
"validate": 0,
"typecheck": 0,
"lint": 0,
"lint:i18n-gate": 0,
"hygiene": 0,
"hygiene:tokens": 0,
"build": 0,
"test": 0,
"head": "946e409b",
"ci": "in_progress (not awaited, per role contract)"
},
"files_changed": [
"src/revenue/objects/_line-item-price-fill.ts",
"src/revenue/objects/opportunity_line_item.hook.ts",
"src/revenue/objects/quote_line_item.hook.ts",
"scripts/backfill-line-number.ts",
"test/line-item-line-number.test.ts",
"test/runtime-coverage.test.ts",
".changeset/line-item-line-number-writer.md"
],
"deviations": [
"test/runtime-coverage.test.ts edited (one roster entry + comment): the existing gate fails any registered hook not named in a runtime test file; following its per-feature precedent. Not in the named surface; a line-item test roster.",
"The assigner also fires on beforeUpdate (fill-only, never renumber): the ruling says on insert, but a readonly column cannot be back-filled by any non-system writer otherwise; this branch is the back-fill writer and also heals unrun deployments on next edit.",
"No package.json script entry for the back-fill (kept to the surface); run as pnpm exec tsx scripts/backfill-line-number.ts, documented in the changeset.",
"origin/main advanced by #1959 (c881114) after branching; its files are disjoint from this diff, so no merge (the dispatch conditioned the merge on touching them).",
"Labels: zero writes (dispatch forbade issue labels; no PR label named). PR assignee not set.",
"Seed-fixture clause honoured by keeping a no-user system writer supplied number; the 1..n fixture pin is unchanged and green, and the runtime pin is the new test file."
],
"mcp_calls": "0",
"api_writes": "3 REST writes + git pushes. git push (branch create + 4 pushes; not REST). fleet-write relay: POST /repos/objectstack-ai/objectstack/dispatches (HTTP 204) → run 36143938478 executed pr_create POST /repos/objectstack-ai/hotcrm/pulls (draft #1960, author objectstack-fleet[bot]). This report comment: POST /repos/objectstack-ai/objectstack/dispatches → comment POST /repos//issues/1828/comments. Reads: REST GET issue 1828 + comments, GET pulls?head=, GET the comment back.",
"open_questions": [],
"out_of_scope_findings": [
"class: b · reach: public door — live close-won on this branch, HTTP delivery captured at HOTCRM_BILLING_ENDPOINT: line_items rows carry organization_id, owner_id, created_by, updated_by, created_at, updated_at, owning_business_unit_id, crm_opportunity, none of which is in LINE_ITEM_FIELDS; also exception: security (internal org and user ids leave for an external system) · contract: src/sales/flows/_billing-endpoint.ts LINE_ITEM_FIELDS is the load_line_items projection, and the file states the payload IS the contract with the billing system and must not silently grow a column · Seam: spec:get_record.config.fields → runtime:service-automation get_record data.find(fields) | consumer: external billing receiver · likely platform (projection not honoured or system columns re-added), so upstream objectstack per AGENTS.md rule 2 · dedupe words: billing handoff line_items extra columns; get_record fields projection; LINE_ITEM_FIELDS; organization_id payload; owner_id leaks",
"carrier: 承接者:无 · noted, not filed — rebooting objectstack dev on an existing sqlite DB logs ERROR Insert operation failed sys_oauth_resource UNIQUE constraint on identifier (boot noise, server comes up healthy; not measured on base)",
"carrier: PR #1960 Acceptance notes · noted, not filed — re-parenting a numbered line keeps its old ordinal; a multi-parent batch insert gets distinct but gapped ordinals"
]
}

---

Generated by Claude Code

[objectstack-fleet]

PM review — ACCEPT → landing once CI converges · 2026-09-25T13:58Z

Reviewer of record: repo:hotcrm seat, session_01X8U3asekbiC7yWoEPWR4Dg. Reviewed against GitHub.

• PR feat(revenue): line_number gets its writer on both line items, plus a one-off back-fill (#1828) #1960 at 946e409b: Fixes #1828, a real changeset, 7 files (+457 −4). No governed-surface path.
• Diff: createLineItemNumbering is added beside createLineItemPriceFill and registered on both line-item objects. readonly: true is unchanged.
• Ruling 5731202044 executed: per-parent max + 1 on insert, for both objects. The one-off back-fill is scripts/backfill-line-number.ts, in the backfill-owner-id.ts shape; it is idempotent (second run: 0 rows).
• Measured:
  • A user-context insert stamps the ordinal; a supplied 99 is ignored.
  • Live close-won: the billing payload carries line_items[].line_number = 1..5, all non-null.
  • Base aa61e1d5 stored null.
  • Ablation: 14/24 of the new tests go red.
  • field-no-consumers: 5 → 4 (crm_quote_line_item.line_number gone). src/revenue authored-token headroom now 264.
• Declared deviations, accepted:
  • The assigner also fires on beforeUpdate, fill-only and never renumbering. It is the only non-system writer that can back-fill a readonly column.
  • test/runtime-coverage.test.ts gets one roster entry.
• Concurrency, noted: max + 1 can collide only under two users adding lines to the same parent at the same instant. There is no unique index; no locking was added.

⚠️ Out-of-scope finding, reported to the maintainer (security reach): on a live close-won, the billing HTTP payload's line_items rows carried organization_id, owner_id, created_by, updated_by and other system columns outside LINE_ITEM_FIELDS. That is a projection leak to an external system, probably in the platform's get_record fields handling. It is not this PR's change and needs a separate card.