18 more AL/BC patterns: data-modeling, testing, style, security, error-handling, ui, upgrade, web-services, appsource (#157)

* Add 18 more community AL/BC patterns across appsource, data-modeling, error-handling, security, style, testing, ui, upgrade, and web-services

Second contribution from CURABIS ApS, generalized from patterns observed across real AppSource/PTE development. Cross-checked against the current microsoft/knowledge corpus before opening; several originally-drafted candidates were dropped as duplicates of existing files.

* Address Jesper Schulz-Wedde's review on PR #157

- release-must-update-app-version.md: reframe around AppSource's actual
  strict full-version-ordering requirement; scope branching-policy
  claims as team convention, not platform rule.
- pictures-must-use-media-not-blob.md: MediaSet is a collection of
  independent media objects, not automatic image variants/thumbnails.
- log-writes-must-survive-rollback.{md,good.al}: StartSession's only
  data channel into the new session is its Record parameter to a
  TableNo-scoped codeunit; a setter called on a local instance before
  starting the session populates nothing in the new session.
- exposed-objects-must-be-in-a-permission-set.md: correct the three
  exposure mechanisms (Web Services config, PageType/QueryType=API,
  ServiceEnabled as a method-only attribute).
- pages-must-not-contain-business-logic.md: scope to persisted
  mutations and cross-entry-point rules; presentation-only
  calculations and table-owned invariants are not violations.
- given-blocks-must-cover-full-precondition-chain.good.al: replace
  invented LibrarySales calls with the real API
  (CreateCustomer/CreateSalesOrderForCustomerNo/PostSalesDocument).
- test-feature-scenario-tags.{md,good.al}: move [SCENARIO] inside the
  test procedure body to match the current BCApps corpus; keep
  [FEATURE] at codeunit level per Microsoft's own documented option.
- ui-test-codeunit-naming.md: scope the _UT suffix and adjacent-ID
  pairing as an explicit team convention, not a BCApps-wide standard.
- page-design-must-match-bc-page-type-conventions.md /
  table-design-must-match-bc-table-type-conventions.md: Card's
  single-key primary-key claim is a contextual heuristic, not a
  mandatory constraint (Ship-to Address, Customer/Vendor Bank Account
  are real composite-key Card pages); a Subsidiary table with its own
  identity commonly gets List+Card, not Worksheet/Tabular.
- api-page-least-privilege-write-access.{md,good.al}: only page-placed
  fields are ever exposed; set InsertAllowed/DeleteAllowed=false in the
  good sample so a narrow field set can't still create/delete records.
- source-organized-by-feature-not-object-type.md,
  test-one-when-per-test.md: scope as team/testing-design conventions,
  not Microsoft platform requirements.
- upgrade-tag-logic-must-not-nest-deeply.md: add the Microsoft Learn
  citation that already backs the two-level nesting limit.
- Wire the new articles into the testing/data-modeling/error-handling/
  security/ui review skills' candidate-selection signals.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* Address second round of Jesper Schulz-Wedde's review on PR #157

- log-writes-must-survive-rollback.good.al: fixed invalid trigger
  OnRun(var Rec: ...) declaration; Rec is implicit when TableNo is set.
- exposed-objects-must-be-in-a-permission-set.md: distinguished the three
  exposure mechanisms (page/query web service or API, codeunit published
  as a web service, [ServiceEnabled] bound action on a page) and their
  actual permission targets (page/query "..." = X vs codeunit "..." = X).
- code-must-not-change-workdate.md: scoped from an absolute "never" to
  "not as a side effect of unrelated logic" - verified real WorkDate(x)
  setter usage in BCApps demo-data generators and test codeunits.
- bcpt-scenarios-must-be-app-specific.md: SingleInstance and
  StartScenario/EndScenario reframed as context-dependent patterns, not
  mandatory requirements - BCPT Create Customer uses neither.
- test-feature-scenario-tags.good.al/.bad.al: replaced the invented
  LibrarySales.CreateCustomerWithPrice/"Item Price Mgt." calls with a real,
  verified price-list-line test using Library - Sales/Library - Inventory/
  Library - Price Calculation.
- page-design-must-match-bc-page-type-conventions.md: scoped the missing
  UsageCategory anti-pattern to pages intended as searchable entry points.
- defensive-vs-offensive-code-must-match-blast-radius.md/.good.al/.bad.al:
  replaced the VAT registration number "low blast radius" example with a
  genuinely cosmetic field (customer home page URL).
- source-organized-by-feature-not-object-type.md: anti-pattern reframed as
  inconsistency with a repo's own convention, not the object-type scheme
  itself.
- pictures-must-use-media-not-blob.md: removed leftover "image variants"
  wording contradicting the already-corrected MediaSet description.

Proactively fixed while sweeping all fixtures for invented APIs:
- given-blocks-must-cover-full-precondition-chain.bad.al: PostSalesOrder
  called with wrong arity and referenced an undeclared variable.
- ui-test-codeunit-naming.good.al/.bad.al: replaced the same fake
  "Item Price Mgt."/TestPage "Item Price" with real Library - Sales calls
  and the real Customer Card TestPage.

Worklist completeness: added review-skill cues for the 12 of 18 new rules
that had none (al-appsource-review.md, al-data-modeling-review.md,
al-error-handling-review.md, al-security-review.md, al-style-review.md x3,
al-testing-review.md x2, al-ui-review.md, al-upgrade-review.md,
al-web-services-review.md), and fixed test-feature-scenario-tags' cue,
which only matched the compliant (tagged) shape instead of the anti-pattern
(untagged/generic-named test).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* Fix ten focused correctness items plus sample links from Jesper's 2026-09-15 re-review

Six carried-over threads:
- api-page-least-privilege-write-access fixtures: added the mandatory
  EntityName/EntitySetName properties (AL0485).
- pages-must-not-contain-business-logic fixtures: Sales Line has no
  "Total Amount" field; replaced with the real "Line Amount" (field 103).
- test-feature-scenario-tags.good.al and test-one-when-per-test.good.al:
  CreatePriceHeader leaves a price list in Draft status, which price
  calculation ignores. Added Validate(Status, Active) + Modify before the
  sales line that depends on it. Verified Status field/enum against
  PriceListHeader.Table.al and PriceStatus.Enum.al in the BCApps clone.
- exposed-objects-must-be-in-a-permission-set.md: a published codeunit is
  a SOAP endpoint (SOAP is deprecated), not OData - Page/Query are the
  OData object types. Corrected and pointed new integrations at API
  pages/queries instead.
- al-error-handling-review.md: the log-writes-must-survive-rollback cue
  selected on Session.StartSession, which only appears in the compliant
  fix, never in the anti-pattern - the bad fixture could never be
  worklisted. Recued on the actual risk shape (log insert around a
  failed TryFunction/GetLastError* path, then raise/propagate), with
  StartSession as an explicit compliant discriminator instead.
- page-design-must-match-bc-page-type-conventions.md: the enum value is
  NavigatePage, not Navigate; noted the type list is a selected subset,
  not an exhaustive PageType catalogue (PromptDialog, ConfigurationDialog,
  UserControlHost, XmlPort also exist, out of this article's scope).

Four new correctness gaps:
- release-must-update-app-version.md: "the version is the only identity"
  was backwards - id is the app's stable identity, version identifies a
  release/code-state of it.
- defensive-vs-offensive-code-must-match-blast-radius.good.al: the "low
  blast radius" example had no else branch, so a failed Customer.Get()
  left the field at its prior/default value instead of the explicit
  chosen fallback the article claims to demonstrate. Added the else.
- bcpt-scenarios-must-be-app-specific.good.al: InitTest and both measured
  StartScenario/EndScenario sections were empty/comment-only, so the
  "app-specific" fixture measured no actual work. Filled in a real,
  self-contained header+line creation path.
- upgrade-tag-logic-must-not-nest-deeply.good.al: the flattened version
  dropped both safety conditions the bad fixture had (Discount % = 0,
  nonblank posting group), silently changing behavior instead of just
  removing nesting. Extracted the guarded update into a helper with both
  conditions preserved as early exits.

Also converted this PR's remaining plain-backtick "See sample:" sample
references (16 articles) to the READ-convention markdown-link form,
matching the fix already made on #156/#158.

Rebased onto upstream/main (conflicts in al-ui-review.md, al-style-review.md,
al-upgrade-review.md against merged upstream PRs - all additive, both
sides' worklist cues retained).

* Fix four merge-critical issues from Jesper's 2026-09-22 review

- pages-must-not-contain-business-logic.good.al/.bad.al: the "good"
  codeunit still directly assigned real Sales Line."Line Amount" and
  called Modify(), bypassing the field's normal Validate cascade
  (discount, VAT, related-amount maintenance) - persisting inconsistent
  document lines regardless of which object the code lived in. Replaced
  the real Sales Line example with a self-contained "Sample Order Line"
  table and switched the codeunit to Validate()/Modify(true), so the
  fixture demonstrates the page-vs-codeunit separation without teaching
  unsafe direct field writes to a real BC document table.
- bcpt-scenarios-must-be-app-specific.good.al: Customer.FindFirst()
  assumed a pre-existing customer (fails against an empty environment),
  and a session-local NextNo counter for the header key collides across
  concurrent BCPT sessions and repeated runs. Creates its own customer
  when none exists, and generates keys from CreateGuid() instead of an
  in-memory counter.
- upgrade-tag-logic-must-not-nest-deeply: the rule conflated two
  different things - nesting one tag's existence check inside another
  (the real anti-pattern Microsoft's guidance warns against) with
  having business-data safety conditions inside a single tagged
  migration's own loop body (which Microsoft's own worked example does,
  and its own design guidance explicitly requires: "Implement extra
  safety checks to avoid data corruption, even though you're using
  upgrade tags"). Rewrote the Description/Best Practice/Anti Pattern to
  scope the rule to actual tag nesting and migrations blended under one
  tag, and rewrote both fixtures: good.al now shows two safety
  conditions correctly nested inside one migration's own loop plus a
  second, genuinely separate migration as its own flat tagged
  procedure; bad.al now shows the real anti-pattern, one tag's check
  nested inside another's guarded body.
- table-design-must-match-bc-table-type-conventions: the rule and its
  worklist cue fired on any new table with a keys block, forcing
  buffers, queues, logs, mapping tables, and staging tables into the
  nearest-looking one of nine business-record archetypes. Added an
  explicit scope note that these nine types aren't an exhaustive table
  catalogue, and narrowed the al-data-modeling-review.md cue to require
  positive evidence (a type-specific naming suffix, key shape, or
  usage) before worklisting, instead of a bare keys/primary-key
  declaration.

* Narrow upgrade-tag nesting cue to match revised article

Cue now flags only nested upgrade-tag checks or functionally unrelated
migrations under one tag, and explicitly excludes record loops and
business-data safety guards belonging to a single migration.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
Co-authored-by: Jesper Schulz-Wedde <jesper.schulzwedde@microsoft.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

microsoft/knowledge/data-modeling/code-must-not-change-workdate.bad.al

@@ -0,0 +1,9 @@
+codeunit 50101 "Batch Job Runner"
+{
+    procedure AdvanceToNextBusinessDay()
+    begin
+        // Anti-pattern: repurposes the user's session WorkDate as a
+        // scratch variable for unrelated business logic.
+        WorkDate(CalcDate('<1D>', WorkDate()));
+    end;
+}

microsoft/knowledge/data-modeling/code-must-not-change-workdate.good.al

@@ -0,0 +1,11 @@
+codeunit 50100 "Posting Date Helper"
+{
+    procedure GetDefaultPostingDate(): Date
+    var
+        PostingDate: Date;
+    begin
+        // Read the work date to default a value; never write to it.
+        PostingDate := WorkDate();
+        exit(PostingDate);
+    end;
+}

microsoft/knowledge/data-modeling/code-must-not-change-workdate.md

@@ -0,0 +1,58 @@
+---
+bc-version: [all]
+domain: data-modeling
+keywords: [workdate, session-setting, user-control, side-effect]
+technologies: [al]
+countries: [w1]
+application-area: [all]
+---
+
+# Application code must not change the WorkDate
+
+## Description
+
+The work date is a per-user session setting the user controls from the
+client (the date shown in the top-right corner, used to default posting
+dates and date filters). Business logic unrelated to that setting must not
+call `WorkDate(NewDate)` as a side effect of doing something else — that
+silently changes what the user sees and defaults to for the rest of their
+session, a surprising, hard-to-trace behavior change the user never asked
+for and has no visibility into. This is not a blanket ban on the setter
+itself: BCApps' own demo-data generators legitimately save the current
+work date, set a specific one to backdate the data they create, and
+restore it afterward (see `CreateDemoEDocsBE.Codeunit.al`'s
+`WorkDate(SampleInvoiceDate)` / `WorkDate(SavedWorkDate)` pair), and test
+codeunits routinely set `WorkDate` deliberately to control the date context
+a test runs under (hundreds of calls across BCApps' test suite, for
+example `SustainabilityPostingTest.Codeunit.al`). Both are the code's
+*actual purpose*, not a side effect of something unrelated.
+
+This is a call-direction distinction for the read side: reading the
+current work date via `WorkDate` (or `WorkDate()` with no argument) is
+always fine.
+
+## Best Practice
+
+Read the work date to default a value. Only write to it when changing it
+*is* the operation being performed — implementing the user's own
+work-date/settings action, or a test or demo-data routine that deliberately
+establishes a date context (saving and restoring the prior value if the
+routine must leave the session as it found it). Business logic that exists
+to do something else must never write `WorkDate` as an incidental side
+effect; if a calculation needs a specific date, pass or compute that date
+as a local variable instead.
+
+See sample: [`code-must-not-change-workdate.good.al`](code-must-not-change-workdate.good.al).
+
+## Anti Pattern
+
+Setting the work date from within a codeunit, report, or page action whose
+purpose is unrelated to the user's date preference — for example, a
+posting or calculation routine that calls `WorkDate(SomeDate)` to make its
+own logic simpler. This changes session state the user owns for the
+duration of a call that was never about the work date, and never restores
+it. This is a different case from a test or demo-data routine explicitly
+declaring a date context: the anti-pattern is unrelated logic silently
+mutating state it does not own, not the setter form itself.
+
+See sample: [`code-must-not-change-workdate.bad.al`](code-must-not-change-workdate.bad.al).

microsoft/knowledge/data-modeling/pictures-must-use-media-not-blob.bad.al

@@ -0,0 +1,11 @@
+table 50111 "Sample Item Card"
+{
+    fields
+    {
+        field(1; "No."; Code[20]) { }
+        field(50; Picture; BLOB)
+        {
+            Caption = 'Picture';
+        }
+    }
+}

microsoft/knowledge/data-modeling/pictures-must-use-media-not-blob.good.al

@@ -0,0 +1,11 @@
+table 50110 "Sample Item Card"
+{
+    fields
+    {
+        field(1; "No."; Code[20]) { }
+        field(50; Picture; Media)
+        {
+            Caption = 'Picture';
+        }
+    }
+}

microsoft/knowledge/data-modeling/pictures-must-use-media-not-blob.md

@@ -0,0 +1,49 @@
+---
+bc-version: [all]
+domain: data-modeling
+keywords: [blob, media, mediaset, picture-field, image-field, table-design]
+technologies: [al]
+countries: [w1]
+application-area: [all]
+---
+
+# Pictures must be stored in a Media/MediaSet field, not BLOB
+
+## Description
+
+`BLOB` is still a valid AL field type for arbitrary binary data, but it is
+not the right choice for storing pictures or images. The current
+recommendation is the `Media` field type for a single image, or
+`MediaSet` when a record needs several independent images (e.g. multiple
+product photos) — `MediaSet` is a collection of separately-imported media
+objects, each with its own identity; it does not generate resized variants
+or thumbnails on its own, and displaying more than one item still requires
+custom page handling. Media/MediaSet integrate with the platform's
+picture control and media repository, which a plain `BLOB` field does not
+— but any derived preview or thumbnail image still has to be generated
+explicitly and stored in its own field, regardless of which type holds the
+source image.
+
+`BLOB` remains the correct choice for genuinely arbitrary binary payloads
+that are not images and don't benefit from the media pipeline (e.g. a raw
+file attachment blob unrelated to picture rendering).
+
+## Best Practice
+
+Use `Media` for a single image, or `MediaSet` for multiple independent
+images, for any field that holds a picture.
+
+See sample: [`pictures-must-use-media-not-blob.good.al`](pictures-must-use-media-not-blob.good.al).
+
+## Anti Pattern
+
+A `BLOB` field named "Picture" compiles and stores the image bytes, but
+it misses the picture control integration and media repository that a
+`Media`/`MediaSet` field provides for free — the anti pattern is choosing
+`BLOB` for image storage out of habit rather than recognizing that the
+field is holding a picture, not generic binary data. A related anti
+pattern: assuming `MediaSet` gives automatic image variants or thumbnails
+because it sounds like a collection with derived versions — it is only a
+collection of independently-imported media objects.
+
+See sample: [`pictures-must-use-media-not-blob.bad.al`](pictures-must-use-media-not-blob.bad.al).

microsoft/knowledge/data-modeling/table-design-must-match-bc-table-type-conventions.bad.al

@@ -0,0 +1,17 @@
+table 50121 "Sample Ledger Entry"
+{
+    fields
+    {
+        // Anti-pattern: a Ledger table's key must never be user-editable.
+        field(1; "Entry No."; Integer) { }
+        field(2; "Posting Date"; Date) { }
+        field(3; Amount; Decimal) { }
+    }
+    keys
+    {
+        key(PK; "Entry No.") { Clustered = true; }
+    }
+    // No AutoIncrement, no guard against manual insert/delete — a user or
+    // integration can renumber or remove entries, breaking the Ledger
+    // type's audit-trail guarantee.
+}

microsoft/knowledge/data-modeling/table-design-must-match-bc-table-type-conventions.good.al

@@ -0,0 +1,16 @@
+table 50120 "Sample Ledger Entry"
+{
+    fields
+    {
+        // Ledger primary key: Integer "Entry No.", set only by posting.
+        field(1; "Entry No."; Integer) { AutoIncrement = true; }
+        field(2; "Posting Date"; Date) { }
+        field(3; Amount; Decimal) { }
+    }
+    keys
+    {
+        key(PK; "Entry No.") { Clustered = true; }
+    }
+    // No user-facing Insert/Delete/Modify path is exposed; rows are
+    // created exclusively by the posting routine.
+}

microsoft/knowledge/data-modeling/table-design-must-match-bc-table-type-conventions.md

@@ -0,0 +1,99 @@
+---
+bc-version: [all]
+domain: data-modeling
+keywords: [tables, table-design, naming-conventions, primary-key, master-table, ledger-table, journal-table, register-table, document-table, setup-table, subsidiary-table, supplemental-table]
+technologies: [al]
+countries: [w1]
+application-area: [all]
+---
+
+# Tables must match one of Business Central's nine table-type conventions
+
+## Description
+
+Business Central's Base Application follows nine recurring table types —
+Master, Supplemental, Subsidiary, Ledger, Register, Journal, Document,
+Document History, and Setup. Each type fixes a naming pattern, a
+primary-key shape, and a set of associated pages. A new or extended table
+whose design doesn't match the conventions of its own type is either
+misclassified or built inconsistently with the rest of the application,
+and should be flagged in review even if it compiles. Before assigning a
+primary key or naming a new table, first identify which of the nine types
+it is — that answer fixes almost every other design decision.
+
+## Best Practice
+
+Match the table's design to its type:
+
+1. **Master** (Customer, Item) — one record is the subject; primary key
+   `Code[20]` named `No.`; description field in `DataCaptionFields`; Card +
+   List (+ Statistics) pages.
+2. **Supplemental** (Currency, Language) — used across functional areas;
+   primary key `Code[10]` named `Code`; one List page, plural name, set as
+   `LookupPageID`.
+3. **Subsidiary** (Item Vendor) — subsidiary to a Master/Supplemental
+   table; primary key is the parent key field(s), optionally + `Line No.`;
+   page shape depends on whether the table carries its own identity: a
+   pure parent-join table (Item Vendor) typically gets a plain List page
+   filtered by the calling page, while a subsidiary table that supplements
+   a master record with its own identity — parent key + own code, e.g.
+   Ship-to Address, Customer/Vendor Bank Account — commonly gets a
+   List+Card pair instead, for direct editing of that record.
+4. **Ledger** (Cust. Ledger Entry) — transactional record of a functional
+   area; primary key `Integer` `Entry No.`, always auto-generated by
+   posting, never user-editable, no free add/delete; List page as
+   `LookupPageID`/`DrillDownPageID`.
+5. **Register** (G/L Register) — table of contents for its Ledger, one row
+   per posting run; primary key `Integer` `No.`, auto-generated; carries
+   `From Entry No.`/`To Entry No.`; List page with a link to the Ledger.
+6. **Journal** (Resource Journal Line) — where users enter data before
+   posting to a Ledger; primary key Template + Batch + `Integer` `Line No.`;
+   Worksheet page with `AutoSplitKey`, a Posting action, and a link to the
+   Ledger.
+7. **Document** (Sales Header/Line) — posts to Ledgers via Journals, not
+   directly; Header primary key `Code[20]` `No.` (or + `Option Document
+   Type`); Line primary key = Header key renamed `<Document> No.` +
+   `Integer Line No.`; Document/Card page with a Posting action and a lines
+   subpage.
+8. **Document History** (Posted Sales Invoice Header/Line) — posted copy of
+   a Document table, created during posting; mirrors the source table's
+   fields; never user-editable; same page shape but the Line-equivalent is
+   a List page, not a Worksheet.
+9. **Setup** (General Ledger Setup) — exactly one record for a functional
+   area; primary key `Code[10]` named `Primary Key`, always blank; one page
+   with the key field hidden, whose `OnOpenPage` creates the singleton the
+   first time it's opened (`Reset()` → `Get()` → if not found, `Init()` →
+   `Insert()`) rather than assuming the record pre-exists.
+
+A table named "Setup" that holds more than one record follows Subsidiary
+rules instead — the name alone is not proof of type. When a table's
+identity can't be resolved from its definition alone (e.g. a "Setup"-named
+table with a real business-field key and no page), say so explicitly
+rather than forcing a classification; settling it requires checking actual
+row cardinality or call sites, not just the object definition.
+
+These nine types cover Business Central's *business-record* tables — they
+are not an exhaustive catalogue of every legitimate table shape. A
+temporary/buffer table, a work queue, a log or telemetry table, a
+cross-reference/mapping table with no business meaning of its own, or a
+staging/working table used only inside one process is not required to fit
+any of the nine, and forcing one into the nearest-looking type (usually
+Ledger, because it has an `Integer` key, or Subsidiary, because it has a
+composite key) produces a harmful redesign recommendation for a table that
+was never meant to carry that type's guarantees. Apply this rule only when
+the table's name, fields, or usage genuinely establish it as one of the
+nine business-record types; when nothing points that way, this rule simply
+does not apply — that is not the same as an unresolved classification.
+
+See sample: [`table-design-must-match-bc-table-type-conventions.good.al`](table-design-must-match-bc-table-type-conventions.good.al).
+
+## Anti Pattern
+
+A table that mixes conventions from two types — for example, a "Ledger"
+table with a user-editable primary key that lets users freely insert or
+delete rows — is not "flexible", it is either misclassified or has skipped
+a design step. A Ledger table's `Entry No.` must come only from the
+posting routine; exposing it as an editable field breaks the type's core
+guarantee that entries are an immutable, sequential audit trail.
+
+See sample: [`table-design-must-match-bc-table-type-conventions.bad.al`](table-design-must-match-bc-table-type-conventions.bad.al).