KernDX Conventions
Canonical, tool-agnostic code conventions for the KernDX framework. Applies to all contributors and any AI coding assistant working in this repository.
KernDX — Salesforce managed package framework. Namespace: kern. API: 68.0. Omit namespace in source code.
Subscriber Context
Subscribers may have custom namespaces, additional class prefixes, and different org aliases.
When generating code for subscribers:
- Ask for namespace if not specified
- Apply stated prefix conventions (e.g.,
ACME_SEL_*) - Use
Namespace.ClassNameformat:kern.QRY_Builderagainst the installed managed package; a client namespace (e.g.,ClientNS.QRY_Builder) applies only after the source was renamed withbin/swap-namespace.js
Critical Rules
- Test coverage floors — Apex 100% per file; LWC 95% statements and 95% branches per file (enforced locally by scripts/evaluate-coverage.js; scanner rules catch coverage-theatre anti-patterns)
- Declare sharing —
with sharing,inherited sharing, orwithout sharingexplicitly. Rationale: Apex's implicit-sharing default silently elevates privileges, which is invisible at the call site; an explicit modifier forces an authorial choice every reviewer can see. - Least-privilege sharing — Default
with sharingfor subscriber code (including subscriber selectors that extendkern.SEL_Base). Framework-internal selectors and utilities inside thekernnamespace useinherited sharingto inherit the caller's sharing context.without sharingonly when justified. - NO inline SOQL — Every read goes through a
SEL_*selector;QRY_Builderis the engine under itsqueryproperty, not a second way to read. Inside the framework itself, code may callQRY_Builderdirectly only when the object is chosen at runtime, or when the object has no selector and is not worth one (a setup object such asSetupEntityAccess); every other read uses the object's selector. Rationale: selectors centralize field-sets, FLS posture, and query shape, which makes them tunable, mockable, and auditable; ad-hoc[SELECT ...]queries are invisible to the masking layer and the bypass-audit channel. - NO
System.debug— UseLOG_Builder - NO
LightningElement— UseComponentBuilder - NO fflib layering pattern in subscriber code — extend
kern.SEL_Base(notfflib_SObjectSelector),kern.TRG_Base(notfflib_SObjectDomain),kern.DML_Builder(notfflib_SObjectUnitOfWork); never callnewQueryFactory(). (The framework reuses the BSD-licensedUTIL_SObjectDescribe+DML_Transactionutilities derived from the same lineage — seeNOTICES.md— but subscriber code goes through the kern surface.) - NO abbreviations —
accountnotacc,messagenotmsg. Rationale: full names are searchable across the codebase; abbreviated identifiers ("acc", "msg", "ctx") collide across modules and break grep/IDE jumps for AI tools. - NO
// Given/When/Then/Cleanupcomments - NO test cleanup code — SF resets static state between tests
- NO hardcoded field API names — Use
UTIL_SObjectDescribe.getCachedFieldName(SObjectField)(never a rawgetDescribe()) - Name semantically-meaningful literals — When a literal's meaning is not self-evident, or it repeats, lift it into a named
static finalconstant whose name explains intent (aCUSTOM_METADATA_SUFFIXconstant not a bare'__mdt'; reuse the rule-name constants the masking-rule selector already declares rather than re-typing rule names). Reuse an existing constant before adding one. Keep a new constant local to its owning class (@TestVisibleso tests can read it) until a second consumer genuinely exists — don't pre-promote to a shared utility — and when it is shared, give it a domain-appropriate home (an SObject/metadata constant belongs with describe/selector utilities, never a generic string helper). Judgment, not blanket: a self-evident0/1or a genuinely one-off, locally-obvious string needs no constant — the test is whether a name would help a future reader grasp intent. Rationale: a named constant turns an opaque literal into documentation at the point of use and gives grep/IDE a single definition to jump to and change. - Methods are verbs — name a method for the action it performs (
buildReadme,renderTargetXml,resolveRuleDeployName), not the value it returns (readme,targetXml,ruleDeployName).get*/find*/resolve*/build*/render*/parse*/map*/to*all read as actions; a bare noun-phrase does not. Rationale: a verb says what a call does at the call site without opening the body. A method returningBooleanstarts with a verb too:is*/has*/can*/should*/contains*/exceeds*(shouldUseCache,hasStandardCursorHeadroom,containsUserDependentKeyword), never a statement or an attribute-shaped phrase (dependsOnRunningUser,resultsVaryByRunningUser,userSpecific). Name what the method actually checks (a text search iscontains*), in plain words a reader already knows ("keyword", not "construct"). Rationale:!containsUserDependentKeyword(query)reads as a question about the query at the call site; a statement-shaped name reads as a fact and hides that it is a test. - Prefer safe-navigation + null-coalescing — write
x?.member ?? fallbackoverx == null ? fallback : x.member;?.short-circuits a member access on a possibly-null receiver,??supplies the fallback. Applies only when the else-branch is a member access on that same receiver — a branch that wraps the value (new List{x}) or calls a function of it (f(x)) stays a ternary. Rationale: reads as "the member, or the fallback," and?.also guards a null member. - NO code section separators — No
//====banners - NO inline DML in tests — Use
TST_Builder.build()orDML_Builder - Use
Assert.*notSystem.Assert.* - Prefer
Foobar__cin tests — Standard objects only when required - Minimize
global— Default topublic(or@TestVisible privatefor test factories). Only upgrade toglobalwhen a concrete subscriber use case justifies it —globalis a permanent API contract that subscribers can bind to and is effectively impossible to remove without a breaking release. Before marking any class, method, property, inner class, enum, or DTO fieldglobal, confirm it is genuinely needed by subscriber Apex, not just used internally within thekernnamespace.
Naming Conventions
| Prefix | Use |
|---|---|
UTIL_* | Utilities |
LOG_* | Logging |
QRY_* | Query infrastructure |
SEL_* | Object selectors |
DML_* | DML operations |
MAP_* | In-memory record indexing |
TRG_* | Trigger handlers & dispatcher |
IF_* | Interfaces |
API_* | Web services |
REST_* | REST endpoints |
DTO_* | Data Transfer Objects |
CTRL_* | LWC controllers |
FLOW_* | Flow invocables |
SVC_* | Service facades |
SCHED_* | Schedulables |
BATCH_* | Batch jobs |
TST_* | Test utilities |
*_TEST | Test classes |
Formatting
Apex:
- Tabs (size 3) — Rationale: tabs let each contributor render leading indentation at their preferred visible width without changing the bytes on disk; size 3 matches the framework's own source so subscriber and kern code visually align in diffs. The 180-column limit below counts each leading tab as four columns, as the IDE does.
- Allman bracing — Rationale: opening brace on its own line keeps block boundaries scannable when lines wrap near the 180-char limit; matches the framework's own source so subscriber code reads consistently with
kern.*internals in the same diff. - 180 char lines — Rationale: long-name-friendly (Salesforce identifiers —
kern__SubscriberPackageVersionId__c, ApexDoc tag clusters — get unreadable when wrapped at 80) without going so wide that side-by-side diffs wrap. - Annotation attributes in camelCase, leading lower —
@IsTest(seeAllData=false isParallel=true),@AuraEnabled(cacheable=true),@InvocableVariable(label='Record Id' required=true),@JsonAccess(serializable='always' deserializable='always'). The annotation name itself stays in class case (@IsTest, never@isTest). Rationale: an annotation is used like a class and its attributes like that class's fields, so they follow the same case rules as the rest of the code; Illuminated Cloud's formatter applies this case by default, so a reformat never produces a casing-only diff. - ApexDoc required — Rationale: ApexDoc is the only documentation surface the auto-generated
docs/reference/apex/consumes. A missing ApexDoc block produces a missing API reference for subscribers; PR-gate enforces.
JS: Tabs, single quotes, semicolons, Allman bracing, camelCase, JSDoc required on LWC component classes (@description, @author, @date) and methods with parameters (@param {type} name).
if(condition)
{
// code
}
// Line wrap (>180 chars): opening paren on new line, args indented
List<Account> accounts = kern.QRY_Builder.selectFrom(Account.SObjectType)
.fields
(
new List<String>{ 'Name', 'Type' }
)
.condition(Account.Type).equals('Customer')
.toList();ApexDoc
Class: @description, @see, @author, @group, @date, @since, @example (blank line between tags of different kinds; repeated tags of the same kind, such as two @throws or two @see, sit on consecutive lines with no blank line between them, as the IDE formatter writes them) Method (REQUIRED): @description, @param (each), @return (if non-void), @throws, @since (on a global member), @example (never @date — that is a class-level tag) Properties: All require @descriptionEnums: @description on the enum itself and on every value, one value per line (global, public, private and test enums alike). The value's description says what the value means: the state, kind or choice it stands for, in plain words. It does not name the methods that set or read the value (those are documented on the methods), and a description that restates the name ("The DML rows limit") does not count. Rationale: an enum value is the smallest named decision in the code; a subscriber or an AI agent reading the source cold meets AT_SEND or HALF_OPEN with nothing else to go on, and a list of the values in the enum-level description is not read at the point of use.Bidirectional @see: Main class ↔ test class @since (every global member: class, inner class, enum, interface, interface method, method, constructor, property, field, constant): REQUIRED, naming the package version that introduced the member, written once and never refreshed. Format: @since 1.0; order: after @throws (or @return) and before @example. Optional on public/private/protected members. The tag is the source record of when a member arrived; the reference pages do not display it, the versioned documentation answers "does this exist in my version". npm run docs:validate fails on a global member without one. @date (class declarations ONLY — never on methods or properties): Month Year or Month Year, Month Year (created, modified — at most two values; refresh the second on edit) @example: Must use ```apex code fences with valid Apex Plain text, no HTML: never an HTML tag (<p>, <br>, <ul>, <li>, <b>, <code> and the like) in ApexDoc. A blank * line separates paragraphs, - starts a list item, and code goes in backticks or an @example fence. node scripts/check-apexdoc-plain-language.js reports a tag outside backticks and fences.
ApexDoc on a global member is subscriber-facing documentation — every framework member it names must itself be global. The block is published verbatim to docs/reference/apex/ and ships, so an @description, @param or @example that cites a public member hands a subscriber code that does not compile: in a managed package public does not cross the namespace boundary, which makes it as unreachable as a private or @TestVisible member, and the offline symbol table (global surface only) does not list it either. The remedy is to spell the literal, never to widen the member to global — a promotion to global is a permanent, unwithdrawable API commitment, and no example is worth one. So a shipped example writes newUserWithPermissionSet('System Administrator', company, 'Administrator') — never the public selector constant that holds that same string. Inside a public/private class the constant is the right call: the rule bites only where the ApexDoc ships.
@description quality — written for the cold reader. The reader is a subscriber or new maintainer who cloned the repo and opened the file for the first time. Names carry the what; the ApexDoc carries the why, the contract, and the invariants the code cannot show — that is the point of the comment. Concretely:
- Describe current behaviour only — never relative to history ("as before", "no longer", "previously"): the reader has no before.
- Internal vocabulary (fences, sparse writes, parks, re-drives, sweeps) appears only WITH an in-doc gloss or an explicit pointer to the member that defines it ("see buildSparseUpdate").
- Refer to members by their actual names, never informal aliases ("the bare writer").
- Short sentences or an ordered sequence — never a whole algorithm compressed into one breath.
- A doc that omits behaviour added in the same change is stale; the doc updates with the code.
- Claim only what the code proves. Test
@descriptions state what the test proves and why it matters, not a restatement of the method name.
Plain language, never the plan's words. The reader may not be fluent in English and has never seen the plan, the spec or the review that produced the code. Short sentences, everyday words, one idea per sentence, a term explained the first time it appears. The vocabulary of planning stays in the plan: never a plan code (I3, D11, SAR-1, BUG-008, PLAN-182), never "the spec" or a section number, never "cell", "pinned", "projection", "resting state", "witness" or "losing writer". The team's own slang stays out too, because a reader outside the team cannot look it up: never "zombie", "sidecar", "fixpoint", "brick", "latch", "knob", "egress", "plumbing", "posture", "clobber", "re-arm", "rule universe", "tier-A", "hand-off" or "unkeyed". An em-dash (—) in a comment, an assertion message or a test name is a fault: use a full stop, a comma or a colon instead. The same bar applies to a test method's @description, a Custom Label's text, a log message and a name: a name says what the thing is in the package's own words (getUserWithApiIssueResolverPermissionSet), never a nickname only the plan explains (getResolver, witness). Say the rule, not its label: "a Stalled run cannot have an end time", not "(I1)". node scripts/check-apexdoc-plain-language.js fails on the codes, the words and the em-dash. By default it reads only the lines you added or changed in each modified class, trigger and module (a new file that git does not track yet, or a file renamed since the reference, is read whole) and prints how many matches on older lines it left out (a match is a line that breaks one of these rules); --all reads every line of the whole tree. The prose itself is a review gate, and a description that needs a second read is an Important finding.
// Rejected: one paragraph of plan vocabulary.
* @description ... It only consumes the (from, to) projection of the transition table and the status field
* invariants, and refuses a write that breaks them (I1 to I5) ...
// Accepted: the same contract, said to the reader.
* @description Refuses a change to a chain run that the engine would never make. Runs before every insert and
* every update of AsyncChainExecution__c. The engine (UTIL_AsyncChain.applyRunTransition) is the only code that
* decides how a run moves from one status to another; this action checks each saved row against the moves the
* engine allows and the shape a row must have in each status, and blocks the save when either fails./**
* @description Handler for Foobar defaults.
*
* @see TRG_SetFoobarDefaults_TEST
*
* @author developer@example.com
*
* @group Trigger Actions
*
* @date January 2026
*
* @since 1.0
*/An enum documents itself and each of its values:
/**
* @description How far a Foobar has come through its review.
*/
public enum ReviewState
{
/**
* @description Nobody has opened the record yet. Every new Foobar starts here.
*/
WAITING,
/**
* @description A reviewer has the record open. Other reviewers are told it is taken.
*/
IN_REVIEW,
/**
* @description The review is finished and the record can no longer be edited.
*/
CLOSED
}Trigger Framework
trigger TRG_ObjectName on ObjectName__c (before insert, before update)
{
new TRG_Dispatcher().run();
}- On a trigger for one of your own objects, declare only the events your configured
TriggerAction__mdthandlers need - A trigger the package ships on one of its own custom objects declares all seven events, so a subscriber's action rows run on any of them; the package's own rows on those objects say by their
Event__cwhich pass they need (all of them use before events) - Handlers extend
TRG_Base, implementIF_Trigger.BeforeInsert/BeforeUpdate/AfterInsert/AfterUpdate/BeforeDelete/AfterDelete/AfterUndelete
Metadata: TriggerAction__mdt — TriggerSetting__c (→TriggerSetting__mdt) + Event__c picklist. TriggerSetting__mdt uses SObjectType__c (→EntityDefinition). Record naming: ClassName_Event.
Old records: pair each new record with its old version from the handler's own parameter: Map<Id, SObject> oldRecordsById = new Map<Id, SObject>(oldRecords); then oldRecordsById.get(newRecord.Id). The lazy-loaded triggerOldMap on TRG_Base is null outside a live trigger, so a handler invoked directly (as in the test pattern below) must not rely on it.
Bypass: Object: TRG_Base.bypass(SObjectType)/.isBypassed()/.clearBypass()/.clearAllBypasses() (also String overloads) | Action: .bypassAction(name)/.isActionBypassed()/.clearActionBypass()/.clearAllActionBypasses() | Flow: FLOW_BypassTrigger | Declarative: TriggerSetting__mdt.BypassExecution__c
Test pattern: Build the input record(s) in memory with kern.TST_Builder.of(SObjectType).withoutInsertion().build(), invoke the handler directly (e.g. new TRG_SetFoobarDefaults().beforeInsert(records)), and assert on the in-memory records. To drive the full dispatcher instead, insert with kern.TST_Builder.of(SObjectType).build() (fires the trigger) and assert with the object's SEL_* selector, for example selector.findFirstByField(field, value). No selector for the object yet? Write one.
@IsTest(seeAllData=false isParallel=true)
private class TRG_SetFoobarDefaults_TEST
{
@IsTest
private static void shouldSetDefaultWhenFieldBlank()
{
Foobar__c record = (Foobar__c)kern.TST_Builder.of(Foobar__c.SObjectType).withoutInsertion().build();
List<SObject> records = new List<SObject>{ record };
new TRG_SetFoobarDefaults().beforeInsert(records);
Assert.isNotNull(record.Name, 'Default should be set');
}
}Selector Framework
Extend SEL_Base, define default fields. Custom query methods use query property (NOT QRY_Builder.selectFrom()). query returns a fresh QRY_Builder.Builder pre-configured with SObjectType and default fields.
Namespace prefix: subscriber code MUST reference framework classes with the kern. prefix (e.g. extends kern.SEL_Base). Most examples in this guide are written as framework source and carry no prefix; add kern. when you write the same code outside the package. Framework-internal code (everything under force-app/ of this repository) omits the prefix because it is in the same namespace.
// Subscriber selectors default to `with sharing` — the safest default. Framework-internal selectors
// inside the kern namespace use `inherited sharing` to follow the caller's sharing context.
public with sharing class SEL_Cases extends kern.SEL_Base
{
public SEL_Cases() { super(Case.SObjectType); }
public override List<SObjectField> getFields()
{
return new List<SObjectField>{ Case.Subject };
}
public List<Case> findOpen()
{
return query.condition(Case.IsClosed).equals(false).orderBy(Case.CreatedDate).descending().toList();
}
}Inherited: query (property) | findById(Id)/findById(Set<Id>) | findByIdOrThrow(Id/Set<Id>) | findByField(field, value)/findByField(field, Set/List) | findFirstByField(field, value) | findByFields(Map)/findFirstByFields(Map) | toList()/getFirst()/getRandomItem() | count()/exists() | toQueryLocator()
When to add a custom query method: only when it does something the inherited find* methods cannot express — a different field projection, an ordering, a row limit, a relationship path, or a domain meaning worth naming (like findOpen() above, which bakes in the open-case filter and ordering). If findByField(...) already expresses the query, call it directly instead of wrapping it in a typed alias.
QRY_Builder
Every read goes through a SEL_* selector; QRY_Builder is the engine under its query property, so the builder methods below are called on query. Prefer List<SObjectField> for compile-time safety (List<String> only for relationship traversals).
List<Account> accounts = new SEL_Accounts().query
.fields(new List<SObjectField>{Account.Name, Account.Industry})
.condition(Account.Industry).equals('Tech')
.orderBy(Account.Name).ascending().withLimit(100).toList();Builder: .fields()/.addFields()/.addField()/.relatedField(String)/.relatedFields(List<String>)/.selectAllFields()/.fieldSet()/.subselect(Builder, String) | .condition() → .equals/.notEquals/.greaterThan/.greaterThanOrEquals/.lessThan/.lessThanOrEquals/.isIn/.notInSet/.isNull/.isNotNull/.contains/.startsWith/.endsWith/.includes/.excludes() | .andCondition()/.orCondition()/.addCondition() | .orderBy() → .ascending/.descending/.nullsFirst/.nullsLast() | .orderBy(field, sortDescending)/.orderBy(field, sortDescending, nullsLast) | .groupBy()/.sum()/.avg()/.min()/.max()/.count()/.countDistinct() | .havingSumOf()/.havingAvgOf()/.havingMinOf()/.havingMaxOf()/.havingCountOf()/.havingCount() | .withLimit()/.withOffset()/.withCache()/.usingScope(Scope)/.forUpdate()/.allRows()/.withUserMode()/.stripInaccessible()/.withSharing()/.bypassSharing() | .withDataCategory(groupName) → .at()/.above()/.below()/.aboveOrBelow()
Terminal: .toList()/.getFirst()/.toQueryLocator()/.toCursor()/.toAggregateList() → List<QRY_Builder.AggregateRow> | .getFirstAggregate()/.getPage(page, size) → QueryPage/.getRandomItem()/.getRandomItems(n)/.count()/.exists()/.asMap()/.asMapById(field)/.asMapByString(field)/.asGroupedMapById(field)/.asGroupedMapByString(field)/.asIdSet()/.asIdList()/.asValueSet(field)/.asStringSet(field)/.toSoql()
Aggregates: .groupBy() (call multiple times for multi-field) + functions + .toAggregateList() → List<QRY_Builder.AggregateRow> (NOT AggregateResult) | .rollup() | .cube() | .grouping(field) for ROLLUP/CUBE subtotal detection Subqueries: .subselect(childBuilder, 'RelationshipName')Semi-joins: .condition(field).isIn(subqueryBuilder)/.notIn(subqueryBuilder) — NO terminal methods on subquery. .notInSet(Set/List) for value-based NOT IN; .notIn(Builder) only for anti-join subqueries. Pagination: .getPage(page, size) → QueryPage (.records/.totalRecords/.hasMorePages/.deletedRecords/.cursor)
Security (default USER_MODE via the UserModeQueries_Enabled flag, + inherited sharing): .withUserMode() (USER_MODE, enforces CRUD/FLS/sharing) | .stripInaccessible() (post-query; strips only in SYSTEM_MODE or a bypassSharing() read: under plain USER_MODE the platform still refuses a selected field the user cannot read) | .withSharing() (the with sharing proxy; changes nothing under USER_MODE, which always enforces sharing) | .bypassSharing() (ignores record sharing; under USER_MODE it keeps the object and field checks: hidden fields are removed, a hidden lookup or parent object on a selected path (or behind a child query) refuses the read, an unreadable object or a builder filter or sort on a hidden field is refused, and toQueryLocator()/toCursor()/aggregate reads are refused; add .withSystemMode() to drop the checks too) | .withoutSecurity() (full waiver: SYSTEM_MODE + record sharing bypassed, in one call)
Data Category: .withDataCategory(groupName) → DataCategoryBuilder with .at()/.above()/.below()/.aboveOrBelow() — each with (String) and (List<String>) overloads. Mutually exclusive with WITH SECURITY_ENFORCED — use .withUserMode() for security enforcement with data category queries. One filter per group.
DML_Builder
DML_Builder.TransactionResult result = DML_Builder.newTransaction()
.doInsert(account)
.doInsert(contact, Contact.AccountId, account)
.doUpdate(existingRecord)
.allowPartial().execute();Methods: .doInsert()/.doUpdate()/.doDelete()/.doUpsert()/.doUndelete()/.allowPartial()/.expectRefusal()/.withRetryOnLock()/.bypassSharing()/.suppressLogging()/.suppressExceptions()/.execute()TransactionResult: isSuccess()/getInsertedIds()/getErrors()/getSuccessCount()/getFailureCount()/getFailureMessage() (the reason when suppressExceptions() caught a failure or an error stopped an allowPartial() save; getErrors() does not show it) Parent-child: .doInsert(child, relationshipField, parent) auto-sets lookup. Register the parent with its own .doInsert(), before or after the child: the transaction orders the inserts from the registered relationships. Async: .async() is a type switch, not a config method — it returns DML_AsyncBuilder, whose only members are withBatchSize(Integer) and execute(), and whose execute() returns void, not a TransactionResult. Chain it last: .doUpdate(records).async().withBatchSize(200).execute();
Flow Invocables
global inherited sharing class FLOW_* with @InvocableMethod + nested DTO_Request/DTO_Response. These rules are for framework classes in force-app/; subscriber invocables are public with sharing (see the Flow Invocables rules in AI Agent Instructions.md).
@SuppressWarnings('PMD.AvoidGlobalModifier')
global inherited sharing class FLOW_CreateAccount
{
@InvocableMethod(category='Account Management' label='Create Account' description='Creates an Account.')
global static List<DTO_Response> execute(List<DTO_Request> requests)
{
if(requests == null || requests.size() != 1)
{
throw new IllegalArgumentException('FLOW_CreateAccount expects a single request');
}
DTO_Request request = requests.iterator().next();
Account account = new Account(Name = request.accountName);
DML_Builder.TransactionResult result = DML_Builder.newTransaction().doInsert(account).execute();
DTO_Response response = new DTO_Response();
response.accountId = account.Id;
response.success = result.isSuccess();
return new List<DTO_Response> {response};
}
global inherited sharing class DTO_Request
{
@InvocableVariable(label='Account Name' description='The name for the new Account' required=true)
global String accountName;
}
global inherited sharing class DTO_Response
{
@InvocableVariable(label='Account ID' description='The ID of the created Account')
global Id accountId;
@InvocableVariable(label='Success' description='Whether the operation succeeded')
global Boolean success;
}
}Rules: global inherited sharing on class + DTOs | @SuppressWarnings('PMD.AvoidGlobalModifier') | guard requests.size() == 1 with a platform-native IllegalArgumentException | @InvocableVariable with Label/Description/Required | @InvocableMethod with Category/Label/Description (+ Callout=true for HTTP) | DML_Builder for DML | Method takes List<DTO_Request>, returns void or List<DTO_Response> | Test: Also test shouldThrowWhenNoRequests() with Assert.fail/Assert.isInstanceOfType
LOG_Builder
Async logging via LogEntryEvent__e. Never System.debug().
LOG_Builder.build().error(e).emitAt('MyClass.myMethod');
LOG_Builder.build().info('Done').emitAt('MyClass.myMethod');
LOG_Builder.build().error('Failed').at('PaymentService.charge').forRecord(id).withContext('amount', amount).emit();
LOG_Builder.LogScope scope = LOG_Builder.scope(); /* ... */ scope.close();Levels: .error(Exception/String)/.warn(String)/.info(String)/.debug(String) (also List<String>) Chain: .at(String)/.forRecord(Id)/.withContext(String, Object)/.withSummary(String)Terminal: .emitAt(String) (shorthand for .at().emit()) / .emit()
UTIL_HttpClient
Fluent HTTP client. Static factories: get()/post()/put()/del()/patch(). First arg: Named Credential or ApiCredential__mdt DeveloperName. Second: URL path.
UTIL_HttpClient.post('PaymentGateway', '/charges').body(chargeRequest).send();
UTIL_HttpClient.get('CRM', '/accounts/{id}').pathParam('id', accountId).asMap();
UTIL_HttpClient.post('EmailService', '/send').body(payload).timeout(30000)
.withRetry(3).withCircuitBreaker().onFailure(UTIL_HttpClient.FailureAction.LOG_FAILURE)
.withTriggeringRecord(record.Id).send();Terminal: .send() → HttpResponse | .asString()/.asMap()/.deserialize(Type) | .invoke() (delegation) Builder: .body()/.header()/.headers()/.queryParam()/.pathParam()/.timeout()/.withRetry(n)/.withRetry(n, backoff)/.withExponentialBackoff(n, base) (pick ONE)/.retryOn(Set<Integer>)/.onFailure(FailureAction)/.withCircuitBreaker()/.withTriggeringRecord(Id)/.withCorrelationId()/.skipLogging()/.replaceRequestToken()/.replaceResponseToken()/.withParameter()/.withParameters()Delegation: UTIL_HttpClient.useHandler(API_SendEmail.class).credential('Cred').withParameter(k, v).withTriggeringRecord(id).invoke()
Inbound Web Services
Two-class: REST_* (routing, global inherited sharing) + API_* (implementation, public with sharing, extends API_Inbound). The global inherited sharing rule is for framework classes in force-app/; a subscriber REST_* class is global with sharing (see Inbound Web Services in AI Agent Instructions.md).
@RestResource(urlMapping='/v1/invoices/*')
global inherited sharing class REST_Invoices
{
@HttpPatch
global static void updateInvoice()
{
API_Dispatcher.processInboundService(API_UpdateInvoice.class.getName());
}
}public with sharing class API_* extends API_Inbound. Same pattern as Outbound (configure(), getValidationErrors()) plus:
onSuccess()— DML via inheriteddoInsert()/doUpdate()/doDelete()(NOTDML_Builder)updateResponseDTO()— runs after commit, populate response DTO fromresult.isSuccess- Request and Response DTOs:
@JsonAccess(serializable='always' deserializable='always'),publicprops
DTOs
Extend DTO_JsonBase + @JsonAccess(serializable='always' deserializable='always'). Standalone: @AuraEnabled public. Nested (in API class): private + ApexDoc. 1-3 → nest; 4+ → separate DTO_*.cls file. populate(Id, DTO_NameValues) uses SEL_*.
Outbound Web Services
public with sharing class API_* extends API_Outbound. Overrides: configure() (set DTOs + defaultMockBody), getRequiredInputs(), getValidationErrors().
public with sharing class API_SendEmail extends API_Outbound
{
@TestVisible private static final String PARAM_RECIPIENT = 'recipient';
@TestVisible private static final String PARAM_SUBJECT = 'subject';
private static final String ERROR_NO_EMAIL = 'Triggering record does not have an email address';
public override void configure()
{
super.configure();
requestPayload = new DTO_Request();
responsePayload = new DTO_Response();
defaultMockBody = '{"messageId": "msg-12345"}';
}
public override Set<String> getRequiredInputs()
{
Set<String> requiredInputs = super.getRequiredInputs();
requiredInputs.add(PARAM_RECIPIENT);
requiredInputs.add(PARAM_SUBJECT);
return requiredInputs;
}
public override List<String> getValidationErrors()
{
List<String> errors = new List<String>();
Foobar__c record = (Foobar__c)new SEL_Foobar().findById(apiCall.TriggeringRecordId__c);
if(String.isBlank(record.Email__c)) { errors.add(ERROR_NO_EMAIL); }
return errors;
}
@JsonAccess(serializable='always' deserializable='always')
public class DTO_Request extends DTO_JsonBase
{
/** @description The email recipient address. */
private String recipient;
/** @description The email subject line. */
private String subject;
public override void populate(Id recordId, DTO_NameValues params)
{
super.populate(recordId, params);
Foobar__c record = (Foobar__c)new SEL_Foobar().findById(recordId);
this.recipient = record.Email__c;
this.subject = params.get(PARAM_SUBJECT);
}
}
@JsonAccess(serializable='always' deserializable='always')
public class DTO_Response extends DTO_JsonBase
{
/** @description The message ID from the email gateway. */
private String messageId;
}
}Rules: Default POST (only override if different) | @TestVisible param constants | defaultMockBody in configure() | DTO props private + ApexDoc | Don't override setHeaders()/retry unless required Mock: API_MockFactory.registerErrorMock(serviceName) | API_MockFactory.forService(serviceName).body(json).statusCode(n).register()
Testing
Structure: Constants → @IsTest methods → helpers (no assertions) → inner classes Header: @IsTest(seeAllData=false isParallel=true) private class MyClass_TESTRules: Test class-specific behaviour only | ClassName.class.getName() not hardcoded strings | ApexDoc on all constants | Reference API param constants | Test abort/error conditions User mode under runAs: an inline query inside a low-privilege System.runAs block runs in user mode on API 67+, so read setup objects (Profile, PermissionSet, User.Profile) outside the block or through a systemModeRequired selector; Database.query(soql, AccessLevel.SYSTEM_MODE) is the escape. Stored timestamps keep whole seconds: a DateTime read back from a record is truncated to the second, so it can sit up to 999 ms before the Datetime.now() the test captured around the write. Compare a read-back stamp against a bound at least one second earlier than the capture, through a named tolerance constant (as UTIL_AsyncChainRecovery_TEST does), never against the raw capture: the raw comparison passes most runs and fails at random. A hook a guide tells subscribers to override is tested by overriding it: a framework hook the guides tell subscribers to override (createRetryStrategy, prepareRequest, getRetryableStatusCodes, and the rest) has at least one test that overrides it on a real subclass and asserts the documented effect through the real caller (API_Dispatcher.execute), never only through a hand-built context. A retry test leaves retry budget: a test that asserts a failed call is or is not retried runs with retry budget left (a setting with MaxRetryCount__c above zero and a positive backoff) and asserts Status__c and NextRetry__c together; a test with no budget passes whatever the code does. In the framework's own tests, use the SEL_ApiCall assertions assertServiceRetrying or assertServiceFailed plus the time. assertServiceRetrying is public, so code outside the package cannot call it: a test in your own org reads the call record and asserts the two fields itself.
Exception testing: Assert.fail + Assert.isInstanceOfType — never Boolean exceptionThrown:
try { methodThatShouldThrow(); Assert.fail('Should throw IllegalArgumentException'); }
catch(Exception error) { Assert.isInstanceOfType(error, IllegalArgumentException.class, 'Incorrect Exception Type'); }TST_Builder
TST_Builder.of(SObjectType).build(); // inserted
TST_Builder.of(SObjectType).withoutInsertion().build(); // in-memory
TST_Builder.of(SObjectType).withOverride(field, value).build(); // overrides
TST_Builder.of(SObjectType).withCount(5).buildList(); // bulkMethods: .of()/.withOverrides(Map)/.withOverride(field, value)/.withCycle(field, values)/.withCount(n)/.withChildren(SObjectType, Integer)/.withChildren(SObjectType, Integer, Map)/.withChildren(Builder)/.withChildren(String, Builder)/.withRecordType(String)/.withoutInsertion()/.withoutInsertion(true) (mock IDs)/.build()/.buildList()
TST_Factory
newFeatureFlag(flagName) | newOutboundApiCall(service, recordId[, params]) | newInboundApiCall(service) | newUser(profileName[, companyName]) | insertUser(profileName[, companyName])
- Feature-flag tests:
kern.TST_Factory.newFeatureFlag('FlagName')seeds an active flag. For the off path, simply don't seed it — an unseeded flag is treated as off. - Trigger-action tests: invoke the handler directly — build the input record in memory with
kern.TST_Builder.of(SObjectType).withoutInsertion().build(), call the handler method (e.g.new MyHandler().beforeInsert(records)), and assert on the record (see the Trigger Framework test pattern above). - Custom-validation tests: deploy the rule as CMDT, then assert with the global
kern.UTIL_ValidationTestHelper.assertRuleFails(record, ruleDeveloperName)/assertRulePasses(record, ruleDeveloperName)(or inspectkern.UTIL_ValidationTestHelper.validate(record)).
TST_Mock
DML-free query interception. TST_Mock.of(SObjectType).withOverride(field, val).build() auto-registers for SEL queries. Manual: TST_Mock.register(type, record)/.get(type)/.clear()/.clear(type). Negative-path: TST_Mock.throwsException(type[, Exception/String]) makes any query against type throw — use to exercise catch blocks. Exception fires before record path when both registered; cleared by .clear()/.clear(type).
Test Assertions
// Outbound (preferred convenience overloads)
API_OutboundTestHelper.assertCallSuccessful(serviceName, recordId, parameters)
API_OutboundTestHelper.assertCallSuccessful(serviceName, recordId)
API_OutboundTestHelper.assertCallAborted(serviceName, recordId, parameters)
API_OutboundTestHelper.assertCallAborted(serviceName, recordId)
// Outbound (API call record overloads)
API_OutboundTestHelper.assertCallSuccessful/assertCallFailed/assertCallAborted(apiCalls)
// Inbound
API_InboundTestHelper.setupRestContext([dtoRequest[, headers]])
API_InboundTestHelper.assertCallSuccessful(serviceName[, dtoRequest[, headers]])
API_InboundTestHelper.assertCallFailed(serviceName[, dtoRequest])
API_InboundTestHelper.assertCallAborted(serviceName[, exceptionMessage])
API_InboundTestHelper.assertCallAborted(serviceName, dtoRequest, exceptionMessage)
// Query-based
SEL_ApiCall.assertServiceCompleted/assertServiceFailed/assertServiceAborted(serviceName[, errorPhrase])Outbound Test Pattern
private static final String SERVICE_NAME = API_SendEmail.class.getName();
private static final String TEST_SUBJECT = 'Test Subject';
@IsTest
private static void shouldCompleteSuccessfully()
{
Foobar__c record = (Foobar__c)TST_Builder.of(Foobar__c.SObjectType)
.withOverride(Foobar__c.Email__c, 'test@example.com').build();
Map<String, String> parameters = new Map<String, String>{ API_SendEmail.PARAM_SUBJECT => TEST_SUBJECT };
API_OutboundTestHelper.assertCallSuccessful(SERVICE_NAME, record.Id, parameters);
}
// Abort: create record missing required data → assertCallAborted(SERVICE_NAME, record.Id, parameters)Inbound Test Pattern
Success: setupRestContext(request) → call REST method → SEL_ApiCall.assertServiceCompleted(SERVICE_NAME) Abort: API_InboundTestHelper.assertCallAborted(SERVICE_NAME, new DTO_Request(), 'error message')
SEL_Foobar Field Constants
FIELD_NAME/FIELD_INTEGER/FIELD_TEXT/FIELD_EMAIL/FIELD_PHONE/FIELD_PICKLIST/FIELD_DATE/FIELD_DATETIME/FIELD_DECIMAL/FIELD_CURRENCY/FIELD_PERCENT/FIELD_CHECK_BOX/FIELD_URL/FIELD_LOOKUP/FIELD_GEOLOCATION
LWC
ComponentBuilder (required) — never LightningElement:
import {ComponentBuilder} from 'kern/componentBuilder'; // MUST be kern/, not c/ — the package namespace owns the module
export default class MyComponent extends ComponentBuilder('notification', 'controller')
{
async handleSave()
{
await this.callControllerMethod('saveAccount', {account: this.account});
this.showSuccessToast('Saved');
}
}Modules: notification (showSuccess/Error/Warning/InfoToast, customNotification — showErrorToast auto-normalises Apex error objects via c/utilitySystem.reduceErrors so .catch(error => this.showErrorToast(error)) produces a sensible toast; string args pass through unchanged) | controller (callControllerMethod, handleWireResponse) | navigation (redirectToRecordPage, generateRecordPageURL) | lightning-message (addMessageChannelSubscription, publishLightningMessage, clearSubscriptions) | flow-navigation (dispatchFlowNext/Back/FinishEvent) | allBase (always): dispatchCustomEvent()/consoleLog()/consoleError()/isLoadingHTML: Lightning base components only — not raw HTML. Meta: apiVersion 68.0, isExposed true.
Jest — DOM-based:
Never write jest.mock('c/...') or jest.mock('lightning/...'): once an earlier suite in the same jest worker loads the real module, the mock silently stops intercepting ({virtual: true} does not fix it). Use a moduleNameMapper file mock, assert the shape a stub dispatches, or jest.spyOn the real imported instance. jest.config.js already maps c/componentBuilder to force-app/test/jest-mocks/c/componentBuilder.js, which exports the mock functions:
import {mockCallControllerMethod, mockShowSuccessToast} from 'c/componentBuilder';
// createElement → Object.assign(element, props) → document.body.appendChild → await Promise.resolve()
// expect(mockShowSuccessToast).toHaveBeenCalled();Jest — prototype-based (headless quick actions):
const prototype = require('c/myAction').default.prototype;
const execute = require('@salesforce/apex/CTRL_MyAction.execute').default;
const createMockContext = (overrides = {}) =>
({recordId: 'a00000000000001', showSuccessToast: jest.fn(), showErrorToast: jest.fn(), dispatchEvent: jest.fn(), ...overrides});
// await prototype.invoke.call(context);Jest mocks: lightning/navigation, lightning/messageService, lightning/empApi, lightning/flowSupport
Anti-Patterns
QRY_Builder.selectFrom()inside selector — usequerypropertynew UTIL_HttpClient()— use static factories.toList()on semi-join subquery — pass builder directly to.isIn()/.notIn()- Complex DTO as
@AuraEnabledparameter — LWC Proxy wrappers break Aura deserialization. UseString requestJson+JSON.deserialize()(seeCTRL_ScheduledJob.saveRecord)
Framework Utilities
UTIL_Exceptions (IllegalState/Configuration/NotFoundException) | UTIL_Cache (durable auto() Session→Org, opt-in inTransaction() per-request memoization, opt-in autoWithTransactionFallback() Session→Org→Transaction graceful degradation reporting cacheTypeUsed = Scope.IN_TRANSACTION on the fallback path — inTransaction / IN_TRANSACTION because transaction is on Apex's reserved-words list) | UTIL_CircuitBreaker | UTIL_Retry (linear/exponential) | UTIL_FeatureFlag.isEnabled(flagName) (Apex) / c/featureFlag.isFlagEnabled(flagName) (LWC bridge via CTRL_FeatureFlag) | UTIL_BypassAudit.emit(surface, action, target, extras) / setBypassReason(reason) (framework-wide bypass audit; framework-internal, public) | UTIL_TypeResolver (subscriber-first) | UTIL_String/Date/List/Map/SObject/Email/Random | UTIL_Set (framework-internal, public) | UTIL_SObjectDescribe (request-cached describe wrapper — getDescribe(sobjectType), .getField(name) namespace-aware default, .getFieldDescribe(name) returns cached DescribeFieldResult with isUpdateable/isCreateable; static getCachedFieldDescribe(SObjectField) / getCachedFieldName(SObjectField) for token-keyed lookups) | UTIL_Limits (the only way to read a governor limit, in production and test code alike: UTIL_Limits.dmlStatements().used(), .maximum(), .remaining(), .isExhausted(); a raw Limits.get*() call belongs only in UTIL_Limits_TEST, where the platform is the oracle that proves the wrapper. One path for every reading gives a test a single seam through which it can later be fed different readings)
Async Chain Orchestration
UTIL_AsyncChain — sequences steps across Queueable transactions with shared state, error handling, and progress tracking.
UTIL_AsyncChain.newChain('DataMigration')
.then(new LoadDataStep())
.then(new TransformDataStep(), true)
.withInitialContext('batchSize', 200)
.onError(new NotifyAdminStep())
.onComplete(new CleanupStep())
.execute();IF_Chain.Step: StepResult work(ChainContext context) — implement this interface or extend ChainStep (abstract, adds stepName property). ChainBuilder: .then(step)/.then(step, continueOnError)/.withInitialContext(key, value)/.withMaxSteps(n)/.withMaxContextSize(n)/.withDelayMinutes(n)/ .withDeduplicationKey(key)/.allowRestart()/.withAsyncOptions(opts)/.onError(step)/.onComplete(step)/.execute()/.execute(correlationId)ChainContext: .put(key, value)/.get(key)/.getAs(key, Type)/.has(key)/.getChainExecutionId()/.getCorrelationId()/.getPreviousStepResult()/.getCurrentStepIndex()/.idempotencyKey()/.idempotencyKey(recordId)/.idempotencyKey(grain)StepResult: UTIL_AsyncChain.succeeded()/.succeeded(msg)/.succeeded(msg, data)/.failed(msg)/.failed(exception)/.failedPermanently(msg)/.failedPermanently(exception) — properties: success, message, data, error, permanentFailureApiStep: Wraps API_Outbound handler as a chain step. new UTIL_AsyncChain.ApiStep(API_SendEmail.class).credential('Gateway').withParameter(k, v).withParameterFrom(param, contextKey).triggeringRecord(id).triggeringRecordFrom(contextKey)Status: UTIL_AsyncChain.getStatus(chainExecutionId) → Map<String, Object> (executionId, chainName, status, totalSteps, completedSteps, errorMessage)
Rules for changing the chain engine
These rules are for contributors who change UTIL_AsyncChain itself, not for code that uses it.
- One writer for a run's status. Every change to
AsyncChainExecution__c.Status__cgoes throughapplyRunTransitionwith a namedRunEvent. The trigger that guards a run's status only checks a change made this way; it never makes one, so it does not replace this rule. - A new step-log marker comes with its room and its rule. A marker is a field the engine saves on a step entry in
StepLog__c(for examplestartedorsuccess). A new marker adds its saved width toSTEP_RUNTIME_RESERVE_LENGTHand its rule toresolveStepStatein the same commit. Without both, the step log can run out of room, or a reader can work out the wrong state for the step. A reviewer refuses a diff that has only one of the two. - A new axis re-walks every table it touches before it lands. An axis is a new status, step-log marker, phase or entry path. Before the change lands, walk all three decisions again, case by case: the run status table (
ALLOWED_FROM_STATUSES_BY_RUN_EVENTandTARGET_STATUS_BY_RUN_EVENT), the step resolver (resolveStepState) and the outbound retry decision (scheduleRetryWhenAllowedandisRetryableByPhaseinAPI_Outbound). Mark each case the axis reaches as tested, untested or the same as a tested case, and turn every untested case into a test or a tracked work item. - The trigger backstop never decides a move.
TRG_AsyncChainRunTransitionasksisAllowedRunTransitioninUTIL_AsyncChainwhether a move is allowed and checks the rules a row must meet in its status. Nothing else. A change that puts a list of statuses, a move or a field rule into the trigger action is refused at review; that change belongs inUTIL_AsyncChain. - The tables and resolvers check this engine only. The run status table, the step resolver and the outbound retry decision exist to verify the chain engine and the outbound retry. They are not a framework feature, and they are never made general or opened up for use outside the package.
Schedulable Framework
inherited sharing class SCHED_* extends SCHED_Base implementing IF_Schedulable. The framework creates a schedulable from its name, so the class is global, or public with a Type Resolver, as for every other class created by name. IF_Schedulable extends Schedulable with getParameterDefinitions() and setParameterValues(DTO_NameValues).
@SuppressWarnings('PMD.AvoidGlobalModifier')
global inherited sharing class SCHED_PurgeOldRecords extends SCHED_Base
{
public override List<DTO_ScheduledParameterDefinition> getParameterDefinitions()
{
return new List<DTO_ScheduledParameterDefinition>
{
DTO_ScheduledParameterDefinition.of('objectName').required(),
DTO_ScheduledParameterDefinition.of('batchSize').asNumeric().withDefault('2000')
};
}
public void execute(SchedulableContext context)
{
String objectName = getTextParameter('objectName');
Integer batchSize = getNumericParameter('batchSize');
}
}SCHED_Base accessors: getTextParameter(name)/getNumericParameter(name)/getBooleanParameter(name)DTO_ScheduledParameterDefinition: .of(name) → .required()/.asNumeric()/.asBoolean()/.withDefault(value)/.withDescription(text)
Type Resolution
Chain: PackageClassResolver → ClassTypeResolver__mdt resolvers (by Order__c). Subscriber-first: no namespace → package namespace.
Type handlerType = UTIL_System.getTypeForClassName('TRG_SetFoobarDefaults');
Type validatedType = UTIL_System.getTypeForClassName('TRG_SetFoobarDefaults', IF_Trigger.BeforeInsert.class);Custom resolver: extend UTIL_TypeResolver.BaseClassResolver, register via ClassTypeResolver__mdt (ClassName__c + Order__c).
PMD Rules
Blocks CI: No assertions, trigger logic in trigger, hardcoded IDs, SOQL injection, empty catch, missing ApexDoc Limits: Cyclomatic complexity ≤15/method, ≤50/class; params ≤5; nested ifs ≤4 Suppress: @SuppressWarnings('PMD.RuleName') — justified only
Documentation
Markdown: TOC required (>3 sections), 180 char lines, link class refs to reference/apex/ClassName.mdRelease notes: release-notes/ folder, only global artifacts, describe shipped implementation Code examples: Use framework patterns, add namespace prefix for subscriber org examples
Documentation information architecture
The docs site (docs-site/) orders content by "soonest × oftenest" — how soon a developer needs a page × how often they return to it. This is the rule for deciding where a new page or section goes; it is not a one-off hand-tuned list.
Section tiers (top-level sidebar + top-nav order, most-pertinent first):
- First contact & daily-driver — Getting Started, Fast Starts
- Depth — Guides
- Lookup — API Reference
- Evaluation — Strategic Guides
- Record — Release Notes
A new top-level section slots in by answering the same two questions. Implemented in docs-site/scripts/generate-nav.mjs (TOP_ORDER).
Within-section order — navOrder frontmatter (integer; ties break alphabetically). Bands let an author place a page deterministically by analogy instead of guessing:
| Band | Meaning | Examples |
|---|---|---|
10–29 | core daily-driver | triggers, selectors/queries, DML, security, logging |
30–59 | common | LWC, inbound/outbound APIs, async, feature flags |
60–89 | situational | validations, resilience, data masking, test data |
90+ | tooling / meta | code scanning, E2E testing |
Set navOrder in a hand-written page's frontmatter; generate-nav.mjs consumes it (then the legacy order, then alpha). docs-site/scripts/nav-order.test.mjs fails a Fast Start that lacks a banded navOrder and warns for Guides. The API Reference is ordered separately, by prefix/domain folder (APEX_PREFIX_DOMAIN / REFERENCE_SUBGROUP_ORDER in generate-nav.mjs), mirroring the IDE tree.
F-shape page template — every page leads, top to bottom, with: (1) a one-line what + why; (2) the single fastest path ("see it work"); (3) depth, subsections ordered most-frequent-need first. Reference pages lead with the ## Methods summary (the per-page index) before the per-method detail.
Hand-written page presentation — meta as badges (framework / time / level), key benefits in ::: tip callouts above the relevant code, tinted/bolder decision-matrix table headers. Generated reference markdown stays clean: the only HTML is the per-overload <div class="apex-member"> wrapper (inner content is pure markdown), so the committed .md still reads cleanly on GitHub and in editors — the card look and signature colors come from the theme (CSS + Shiki), not from HTML in the source.