Canonical rules for writing TypeScript (ES2025+, Node.js native TS) for every execution-agent in the project.
Goal: turn each created or modified TS file into an «Executable Specification» — a readable, machine-parsable artifact in which intent, contract, and refactor hazards can be recovered from the file alone, without chat history or external documentation.
Baseline TS rules layer; referenced from task tickets generated by `task-scaffolding`. Domain-specific conventions (React, Node servers, CLI) are NOT covered here; they live as separate directives layered on top.
**Base axiom:** code will be read, parsed, and modified ONLY by other AI agents and AI IDEs (AI-to-AI ecosystem). Highest values: absolute predictability, semantic density, code introspectability. Comments are agent-authored machine comments — they expose intent, constraints, refactor hazards that code and types do not encode by themselves. English is for code and intent: all keys, methods, JSDoc, and intent comments strictly in English.
Forbid transpile-only syntax. `enum`, `namespace`, and constructor parameter properties (`constructor(private foo: string)`) are forbidden. Native Node.js supports only type stripping; these constructs require AST-to-JS transforms and reliably fail with `SyntaxError` at runtime.
Alternatives: string literal unions (`'a' | 'b'`) or `const + as const` instead of `enum`; assign constructor fields explicitly inside the body.
Truthful encapsulation, not false. Native private fields (`#field`) and the `private` modifier are forbidden. For internal state use `protected` with `_` prefix (`protected _logger`). Omit the `public` modifier.
`#` blocks reflection and decorators. `private` creates false sense of encapsulation: erased at compile time, misleads readers and runtime tooling. `protected _foo` truthfully reflects runtime behavior and preserves metaprogramming hooks.
Declare class fields explicitly in the class body. Put `readonly` on the field declaration, not on constructor parameters. Separates state declaration (what the class holds) from initialization signature (how the class is constructed), removes parameter-property magic, improves introspectability.
Modern TS/JS is mandatory. Use optional chaining (`?.`), nullish coalescing (`??`), logical assignment (`||=`, `&&=`, `??=`). Avoid verbose `if`-checks. Semantic density reduces visual noise, shrinks the surface for nullable-check bugs, and makes the code recoverable by an agent in one pass.
A name reflects a goal (teleology), not a pattern (topology). Forbidden semantic-noise names: `Manager`, `Handler`, `Data`, `Info`, `Wrapper`, `do...`, `process...`. Pattern names tell the next agent nothing about business goal. `OrderFulfillmentPipeline` carries intent; `OrderManager` does not.
Use precise verbs. `retrieve` (not `get`), `verify` (not `check`), `compose` (not `make`). Verbs encode the operation's contract. `get` is ambivalent; `retrieve` implies lookup in an external source with possible failure path.
Method name is a self-contained contract. Method names must be readable as a full contract outside the owner class (`verifyRegistrationData`, not just `validate` inside `UserValidator`). A reading agent often sees a method call without the owner class in focus (import, traceability grep). The name must carry meaning in isolation.
Public methods do not leak implementation. Forbidden infrastructure words in public APIs: `Db`, `Sql`, `Http` (exception: serializer layers, where this IS the contract). Leaking transport into a public name breaks Ports & Adapters and binds consumers to a concrete implementation.
Deliver exactly what the task and contract demand. No unrequested features, extension points, or optionality. Every extra API surface is a future refactor obligation and a source of drift from the contract.
Forbid premature abstractions. Do not abstract logic that has ONE consumer and ONE concrete realization. Abstraction is justified only by confirmed variance or an explicit second consumer; otherwise it complicates grep and reading without payoff.
Minimal error surface. Handle only reachable errors. Do not defend against states proven impossible by types, preconditions, or invariants. Defense against the impossible is dead code — simulates reliability and obstructs reasoning about real failure paths.
Decompose by intent, not by volume. Avoid both monolithic methods AND artificial layering. Extract code only at TRUE intent boundaries that meaningfully improve readability, testability, or isolation. Splitting by line count without intent boundaries creates fictive functions that raise cognitive load without raising verifiability.
Every error message carries a Trace-Prefix. Format: `[ClassName#methodName]` or `[functionName]`. With cause-chains across several log/error layers, the only reliable way to recover the failure point is an explicit prefix; stack aggregators may truncate.
Preserve original context via `{ cause }`. Create and rethrow via `new Error("[Trace-Prefix] ...", { cause })`. NEVER transform `cause` — it can be any value. `cause` is a lossless channel for the root cause; any transform breaks the debug chain.
Catch-Log-Recover is the only pattern in business-logic catch blocks. First `logger.error` with Trace-Prefix and context, then recovery in ONE of two forms depending on the surrounding method's contract:
- throw-style API → `throw new Error("[Trace-Prefix] msg", { cause })`.
- Result-style API → `return fail(error)` (per project Result conventions; the `error` carries `{ cause }` via its own constructor).
`logger.error` records the failure with its context at detection time — this is the LDD trace (debug-level escalation lets an agent reconstruct the data path even when stacks are minified or aggregator-truncated). Recovery preserves control flow.
Both forms require both steps. Skipping `logger.error` makes the failure invisible to the trace; skipping recovery swallows it. NEVER do both (log + throw + return fail) — that re-emits and double-logs across boundaries.
Synchronous validation at the start of the method. Validate arguments synchronously and throw domain errors with context. Earlier validation = fewer state mutations before failure and clearer failure cause from the message.
Raw `console.*` is forbidden. Use the shared logger from `#logger`: `logger[level](message, detail?)`. Levels: `debug` / `info` / `warn` / `error`. One or two arguments: first is a string message, second (when needed) is a `detail` object. **NEVER serialize objects into the message string.** Pseudo-loggers (`const logger = console`) forbidden.
The shared logger is the only sink that can be re-targeted (transport, redaction, sampling) without editing call-sites; raw `console` breaks agent-readable structure.
Message format: `[Trace-Prefix] [stateA → stateB] Description`. State transitions are mandatory at entry, branches, exit, and errors. Description adds NEW information and does not duplicate state.
A state machine in the log makes module behavior reconstructable along a timeline; raw messages without state break recovery.
Message vs detail separation by type. Primitives (paths, codes, numbers, time) → message; complex objects and errors → second `{ ... }` argument, only when needed. Text backends digest serialized objects poorly; structured backends lose searchability if the object is jammed into a string. The split satisfies both.
Timing for long operations only. Measure with `performance.now()`, format as `${time.toFixed(2)}ms`. Timing a trivial operation is noise that dilutes signal; timing an I/O boundary is critical perf-trace.
Logs at entry points, important branches, external I/O / mutations, catch blocks. Loops logged in aggregate, NOT per iteration. In `catch`: ALWAYS `logger.error` with Trace-Prefix and context, then recover via `throw` or `return fail()` per `AX_CATCH_LOG_RECOVER`. Intent-driven density yields a readable story-line; per-iteration spam drowns real signals.
Anchors: `// #region START_[CONTEXT]_[INTENT]` / `// #endregion END_[CONTEXT]_[INTENT]`. Uppercase tokens. Parity mandatory: every `START_X` must have `END_X` in the same file. START_/END_ on top of `#region`/`#endregion` is intentional — paired uppercase tokens are attention anchors for sliding-window LLMs and XML-like span delimiters for long-context retrieval.
When a block has a non-obvious invariant or failure boundary, attach payload inside the anchor (outside it is detached from the block it protects): ONE payload kind → inline on the opening line `// #region START_[NAME] — : `; 2+ kinds → separate comment lines immediately after the opening anchor. Greppable: `#(region|endregion)\s+(START|END)_[A-Z0-9_]+`.
In a complex function wrap EVERY nested control-flow block with independent intent, side effects, or refactor risk: `if`/`else`, `for`/`for...of`, `while`, `switch`, meaningful `case`, `try`, `catch`. Do not skip anchors because the block looks short or locally readable. If another agent may need to isolate, patch, move, or audit the block as a unit, anchors are mandatory. This is patch-grammar, not cosmetic.
Do NOT wrap a trivial guard or single-action branch. Block has no independent policy, no meaningful side effect, no refactor hazard → anchors not needed. An anchor around a single line is noise that dilutes the signal of mandatory anchors and erodes trust in their semantics.
Anchor name describes WHY the block exists. Does NOT restate syntax or literal conditions. `START_APPLY_FALLBACK_STRATEGY`, not `START_IF_NO_PATH`. The name is the only way for a reader-agent to recognize the block's policy without reading the body.
Architecture-level choice. DTOs, configs, API responses → `type`. `interface` reserved for abstractions with inheritance / implementation (polymorphism). A consistent choice makes a type's intent readable at a glance: `interface` signals «polymorphism point»; `type` signals «data shape».
Domain prefix for types from external systems: `ApiResource`, `VendorOrder`, `ErpCatalogItem`. Internal utilities have no prefix. The prefix protects a trust boundary: `OrderItem` (internal) and `VendorOrderItem` (external) are different entities; conflating is a common source of domain bugs.
`Error` subclasses are declared via `class` only. Do NOT replace with `type` or `interface`. Only `class` correctly works with `instanceof`, the prototype chain, and the `cause` chain at runtime. A `type` alias for Error gives no runtime check.
Mandatory protocol for direct implementations of a contract. For every exported runtime root that directly implements a named contract:
1. Keep the root-level `@purpose` (compressed essence).
2. Add `@implements {ContractName} in path` on the root.
3. Add `@see {ContractName#memberName} in path` on every direct public/protected implementation member, unless that member is a true override with a full explicit contract.
Do not stop at the TS `implements` keyword, owner-level class JSDoc, or method «obviousness». These links are mandatory contract edges, not decoration. Without them a reader-agent does not see the implementation→contract link without grep; a member without `@see` is indistinguishable from an override.
File-level meta uses line-comments (`// @tag`), never a JSDoc block — distinct syntactic class from entity JSDoc so LLMs and grep distinguish file-scope from entity-scope unambiguously.
Block of consecutive `//` lines at the very top of the file, before any `import`:
`// @file: ` *(mandatory)*
`// @consumers: ` *(optional; omit when no uniform consumer)*
`// @tasks: [, TASK-ID...]` *(optional; may be added later)*
`@purpose` is NOT a file-level tag — it belongs exclusively to entities. Local entities inherit `@consumers` from file level and MUST NOT redeclare it unless their consumer diverges.
`@consumers:` and `@tasks:` are optional — a coding-only agent may lack full project context. Omit rather than fabricate.
Single-line JSDoc for properties. When defining properties inside `type`, `interface`, or DTOs, generate the JSDoc as a single flat string to preserve vertical density. If multiple tags are required, merge them on the same line using the ` | ` separator. Example: `/** @purpose Smallest id in the range | @invariant >= 0 */`. Multi-line JSDoc blocks are strictly reserved for module roots, classes, and methods.
` | ` separates distinct JSDoc **tags**, not continuation lines of one tag. A multi-sentence `@purpose` is compressed to one sentence — not joined with ` | `. Discard sentences that restate the property name or explain the obvious; keep only the constraint or role that cannot be inferred from the type.
Base JSDoc contract shape for all types, interfaces, methods, fields, properties, getters, setters, functions (incl. `protected`):
- **Default root contract:** `@purpose` (compressed essence). Do NOT replace a root definition or implementation owner with `@see`.
- **Root implementation rule:** exported class or const directly implementing an existing named contract keeps its own `@purpose` AND adds `@implements {InterfaceName} in path`.
- **Member implementation rule:** `@see {InterfaceName#memberName} in path` allowed only for direct public/protected implementation or inheritance edge where behavior matches.
- **Override rule:** override / redefinition (behavior/contract change) → write the full contract explicitly; do not rely only on `@see`.
- **Clarification rule:** if an implementation needs its own `@consumers`, `@invariant`, `@pre`, `@throws`, `@returns`, `@post`, or `@sideEffect` because the inherited contract is being tightened/specialized/extended → treat as override; write the full explicit contract instead of mixing extra tags into a `@see`-only stub.
- **Single-line:** `/** @purpose Verb Object Context */` or `/** @see {InterfaceName#memberName} in ./path */`.
- **Multi-line:** for complex entities, exported implementation roots, or entities with optional tags. Strict order mandatory.
**Optional JSDoc tags (order MANDATORY):**
1. `@consumers` — who consumes the API.
2. `@implements` — the contract root implemented.
3. `@invariant` — constraints, SLA, retry / error policies, ordering guarantees, implementation strategy guarantees that modifying agents must preserve.
4. `@pre` — hidden preconditions before the call.
5. `@param` — one coherent role description. Do NOT duplicate field structure from the type.
6. `@throws` — reason for throw / Promise rejection.
7. `@returns` — business purpose of a successful result / Promise resolution.
8. `@post` — state guarantees after the call.
9. `@sideEffect` — I/O, network, logs, etc.
A strict order and closed vocabulary let a reader-agent parse the JSDoc contract deterministically. File-level tags (`@file:`, `@consumers:`, `@tasks:`) live in `// @tag:` line-comments at file head — never inside entity JSDoc (see `AX_FILE_LEVEL_CONTEXT`).
When each tag is used:
- `@file:`, `@tasks:` — file-level line-comments only; see `AX_FILE_LEVEL_CONTEXT`.
- `@consumers` — file-level line-comment when uniform; entity-level only when consumer diverges from file-level; skip for local helpers.
- `@implements` — required on exported class/const root directly implementing a named interface/contract; skip for data shapes, interfaces, member declarations.
- `@invariant` — stateful entities, resilience / error policy, ordering guarantees, non-local assumptions, implementation-strategy guarantees that modifying agents must preserve.
- `@pre` — ONLY for hidden environment / system-state preconditions not captured by the type signature.
- `@param` — when arguments exist; one coherent role description; do NOT enumerate object fields already in the type.
- `@throws` — when the function can throw / reject; describe failure reason, not generic possibility.
- `@returns` — for non-void / non-never results; describe WHY the caller needs the value, not the TS shape.
- `@post` — state guarantees not already encoded by `@returns`, types, or obvious control flow.
- `@sideEffect` — externally visible effects (network, fs, process, shared-state mutation, emitted events). Routine debug logging alone does NOT justify the tag.
- `@see` — ONLY for direct member implementation / inheritance of an existing contract; do NOT use as a root class/const tag when root owns runtime behavior. Behavior diverges → write the full contract.
Minimum requirements per entity kind:
- **Exported data shapes:** `type` + `@purpose`; use `@consumers` only when consumer diverges from the file-level context declaration.
- **Pure alias / shape-forwarding exports** with no runtime behavior may use a root-level `@see`. But runtime-bearing class/const implementations do NOT replace their owner contract with `@see`.
- **Service interfaces / external-system clients:** require `@invariant` for error policy, retry policy, ordering guarantees, rate limits, or other resilience constraints.
- **Implementations of an existing runtime contract:** owner-level `@purpose` on class/const + `@implements {ContractName} in path` on root + `@see {ContractName#memberName} in path` on each public/protected member when behavior matches.
- **Async functions / methods:** `@returns` describes the resolved value; `@throws` describes the rejected/throw path; `@sideEffect` documents external action when present.
- **Exported config constants:** `@invariant` when value bounds or combinations must remain stable.
- **Within one implementing surface** `@implements` and member-level `@see` MUST use same path style and same contract names — do not mix local-relative and project-root-relative references inside one module.
Exception handling is mandatory in business logic. Any business method with network/file/process I/O, mutation of external state, or integration with an external system MUST wrap the failure point in `try`/`catch` per `AX_CATCH_LOG_RECOVER`. Missing try/catch on an integration boundary turns any transient failure into an un-traced un-contextualized exception.
Trace-Prefix format: `[ClassName#methodName]` or `[functionName]`. Used in all Error messages and log messages.
Complex (triggers non-trivial anchors + full JSDoc optional-tag set) if any: network/file/process I/O; shared-state mutation; retry/fallback/error translation; concurrency, locking, batching. OR any two of: multiple decision points, hidden pre/postconditions, nested control flow, non-local refactor hazard.
Exported data shape: `type`, domain prefix, single-line JSDoc per field, no duplication of TS structure.
```typescript
// @file: ERP catalog item shape shared across the synchronization pipeline.
// @consumers: ErpSynchronizationWorker
// @tasks: TASK-4231
/** @purpose Normalized response from an external ERP catalog. */
export type ErpCatalogItem = {
/** @purpose Unique item identifier in ERP | @invariant Format: 'ERP-12345' */
id: string;
/** @purpose Timestamp of the last synchronization | @invariant Unix epoch milliseconds */
syncedAt: number;
};
```
Data shape with no runtime behavior → `type` + entity `@purpose`. Shared context declared once in file-level `// @file:` / `// @consumers:` header; entity does NOT redeclare `@consumers`.
Service interface: precise optional-tag order, SLA in `@invariant`, side effects exposed explicitly.
```typescript
// @file: Contract surface for vendor reservation integration.
// @consumers: OrderFulfillmentPipeline
/**
* @purpose Gateway for interacting with a vendor API.
* @invariant Retry Policy: Idempotent methods (GET) are retried up to 3 times.
* @invariant Error Policy: All HTTP 5xx are wrapped into VendorNetworkError.
*/
export interface VendorGateway {
/**
* @purpose Synchronous reservation registration: lock stock at the vendor warehouse.
* @invariant Idempotency-Ref must be propagated unchanged across retries; vendor error boundary not normalized before cause-chaining.
* @param idempotencyKey Key (UUIDv4) to prevent duplicated reservations during network retries.
* @throws {VendorStockError} Item is out of stock at the vendor.
* @returns Internal identifier of the created reservation in the vendor system.
* @sideEffect Network: POST /v2/reservations
*/
reserveStock(idempotencyKey: string): Promise;
}
```
`interface` because this is a polymorphism point (Port), not a data shape. Invariants encode resilience policy that would otherwise be lost in the implementation.
Implementation of an existing contract: root keeps `@purpose` + `@implements`; inherited members use `@see`; method body starts with executable code; non-trivial blocks wrapped in compact-form `#region START_...` / `#endregion END_...` anchors.
```typescript
// @file: HTTP implementation of the VendorGateway contract.
// @consumers: OrderFulfillmentPipeline
// @tasks: TASK-1187
import { logger } from '#logger';
/**
* @purpose HTTP adapter for interacting with a vendor API.
* @implements {VendorGateway} in src/domain/contracts/VendorGateway.ts
*/
export class HttpVendorGateway implements VendorGateway {
protected _httpClient: HttpClient;
protected _logger: Logger;
constructor(httpClient: HttpClient, logger: Logger) {
this._httpClient = httpClient;
this._logger = logger;
}
/** @see {VendorGateway#reserveStock} in src/domain/contracts/VendorGateway.ts */
async reserveStock(idempotencyKey: string): Promise {
this._logger.debug(`[HttpVendorGateway#reserveStock] [idle → reserving] ${idempotencyKey}`);
// #region START_VENDOR_API_CALL — invariant: vendor deduplicates retries only when X-Idempotency-Ref is preserved exactly
try {
const response = await this._httpClient.post('/v2/reservations', {
headers: { 'X-Idempotency-Ref': idempotencyKey }
});
this._logger.info(`[HttpVendorGateway#reserveStock] [reserving → reserved] ${response.data.reservationId}`);
return response.data.reservationId;
} catch (cause) {
const error = new Error('[HttpVendorGateway#reserveStock] Reservation failed', { cause });
this._logger.error(`[HttpVendorGateway#reserveStock] [reserving → failed]`, { error });
throw error;
}
// #endregion END_VENDOR_API_CALL
}
}
```
All mandatory protocols together: `// @file:` header, `@implements` on root, `@see` on member, executable-first body, compact single-payload anchor (invariant inlined on `#region` line), Trace-Prefixed log + error, cause-chain.
Async operation with `performance.now()` timing, state transitions in logs, Catch-Log-Recover.
```typescript
// @file: Timed execution helper for long-running async action.
// @consumers: TaskOrchestrator
import { performance } from 'node:perf_hooks';
import { logger } from '#logger';
/**
* @purpose Performs an atomic action with performance measurement and state tracing.
* @invariant On failure: emit `logger.error` with elapsed time, then recover via rethrow with cause-chain (or `return fail(error)` in Result-style APIs) — both steps mandatory per Catch-Log-Recover.
* @param specifier Unique identifier of the target resource or action.
* @throws {Error} When the action fails (wraps the original cause).
* @returns Status of successful execution.
*/
export async function performAction(specifier: string): Promise {
const startedAt = performance.now();
try {
logger.debug(`[performAction] [idle → processing] ${specifier}`);
// ...work...
const time = performance.now() - startedAt;
logger.info(`[performAction] [processing → completed] ${specifier} (${time.toFixed(2)}ms)`);
return 'ok';
} catch (cause) {
const time = performance.now() - startedAt;
const error = new Error('[performAction] Action failed', { cause });
logger.error(
`[performAction] [processing → failed] Other error: ${specifier} (${time.toFixed(2)}ms)`,
{ error }
);
throw error;
}
}
```
Timing justified — operation is long. State transitions explicit. Error path loses neither context (Trace-Prefix + detail) nor cause-chain.
Plain branching without anchors where control flow is self-evident; modern operators yield density without losing intent.
```typescript
// @file: Strategy selection helpers for path-aware processing.
// @consumers: StrategyPlanner
import { logger } from '#logger';
/** @purpose Configuration for choosing a processing strategy. */
export type DecideStrategyConfig = {
/** @purpose Path to the target resource | @invariant Absent value triggers fallback strategy */
path?: string;
};
/**
* @purpose Decides a processing strategy based on whether the config contains a path.
* @param config Configuration parameters.
* @returns Identifier of the chosen strategy.
*/
export function decideStrategy(config: DecideStrategyConfig): string {
logger.debug('[decideStrategy] [ready → choosing]');
if (!config?.path) {
logger.debug('[decideStrategy] [choosing → fallback] No config path provided');
return 'fallback';
}
logger.debug(`[decideStrategy] [choosing → primary] ${config.path}`);
return 'primary';
}
```
Branch is trivial (no independent policy / side effect / refactor hazard) → anchors redundant per `AX_ANCHOR_TRIVIAL_EXCEPTION`. `?.` provides narrowing without verbose checks.
Modern TS operators replace verbose null-checks without losing meaning.
```typescript
const avatarUrl = user?.profile?.getAvatar?.();
cachedImages[avatarUrl] ||= await fetchImage(avatarUrl);
```
The equivalent of 6 lines of `if`-nesting is compressed to 2 without loss of semantics. Canonical «high-signal idiomatic TypeScript».
Anchors around a single `const`; anchor name `START_CHECK_RETRIES` (names syntax, not intent); comment restates the `if`; `Error("Limit")` without Trace-Prefix or cause.
Atomic noise (violates `AX_ANCHOR_TRIVIAL_EXCEPTION`); name violates `AX_ANCHOR_INTENTFUL_NAMES`; comment violates `AX_COMMENT_VOCABULARY`; Error violates `AX_TRACE_PREFIXED_ERRORS`, `AX_ERROR_CHAINING_CAUSE`.
```typescript
const maxRetries = 3;
// #region START_ENFORCE_RETRY_POLICY
// purpose: stop retry fan-out before a degraded upstream turns one request into cascading load
// failure mode: removing this guard converts transient upstream latency into duplicate pressure
if (attempts > maxRetries) {
throw new TessellError(ErrKind.ERR_CHECKOUT_CHARGE_UPSTREAM_UNRESPONSIVE, "[Checkout#charge] Upstream provider unresponsive", {
cause: { attempts, maxRetries }
});
}
// #endregion END_ENFORCE_RETRY_POLICY
```
`enum OrderState { NEW, PAID, SHIPPED }`; `class OrderManager { constructor(private repo: OrderRepo) {} #lastState: OrderState = OrderState.NEW; public process(orderId: string) {} }`.
`enum` breaks under native Node TS (`AX_NO_TRANSPILE_ONLY_CONSTRUCTS`). Constructor parameter property `private repo` transpile-only. `#lastState` blocks reflection (`AX_TRUTHFUL_ENCAPSULATION`). `OrderManager` is semantic noise (`AX_TELEOLOGICAL_NAMING`). `process` generic verb (`AX_VERB_PRECISION`). `public` redundant.
```typescript
// @file: Order lifecycle primitives for checkout domain.
// @consumers: CheckoutPipeline
/** @purpose Lifecycle states an order traverses from creation to fulfillment. */
export type OrderState = 'NEW' | 'PAID' | 'SHIPPED';
/** @purpose Coordinates order lifecycle transitions for the checkout flow. */
export class OrderLifecycle {
protected _repo: OrderRepo;
protected _lastState: OrderState = 'NEW';
constructor(repo: OrderRepo) {
this._repo = repo;
}
/** @purpose Transition the order to PAID after successful charge. */
settleCharge(orderId: string): Promise { /* ... */ }
}
```
`console.log("fetching user " + JSON.stringify({ id }));` then `catch (e) { console.error("failed " + e); throw new Error("fetch failed"); }`.
`console.*` forbidden (`AX_STRUCTURED_LOGGING`). Object serialized into message string (`AX_LOG_MESSAGE_PURITY`). No Trace-Prefix or state transition (`AX_LOG_MESSAGE_FORMAT`). `new Error` without `{ cause }` loses debug chain (`AX_ERROR_CHAINING_CAUSE`). No Trace-Prefix in error (`AX_TRACE_PREFIXED_ERRORS`). `e` concatenated into string — stack lost.
```typescript
// @file: User retrieval entry point against the primary store.
// @consumers: SessionRouter
import { logger } from '#logger';
/**
* @purpose Retrieve a user record by id from the primary store.
* @invariant Storage failure is preserved as `cause` (not transformed); state-transition logs emitted on both success and failure paths.
* @throws {Error} Wraps any storage failure with cause-chain.
* @sideEffect Storage: SELECT from users by id.
*/
export async function retrieveUser(id: string): Promise {
try {
logger.debug(`[retrieveUser] [idle → retrieving] ${id}`);
const user = await db.find(id);
logger.info(`[retrieveUser] [retrieving → retrieved] ${id}`);
return user;
} catch (cause) {
const error = new Error(`[retrieveUser] Storage retrieval failed for ${id}`, { cause });
logger.error(`[retrieveUser] [retrieving → failed] ${id}`, { error });
throw error;
}
}
```
`/** @purpose User DTO. @param id The id field, type string. @param name The name field, type string. @returns Returns a User object with id and name. */ export type User = { id: string; name: string; };`.
`@param`/`@returns` used on a type, not a function (`AX_TAG_USAGE_MATRIX`). JSDoc duplicates TS structure (`AX_FLAT_JSDOC_FOR_PROPERTIES`). `User DTO` carries no business meaning.
```typescript
// @file: Identity shape exposed by session-related APIs.
// @consumers: SessionRouter
/** @purpose Authenticated user identity surfaced to API consumers. */
export type User = {
/** @purpose Stable user identifier | @invariant UUIDv7 format */
id: string;
/** @purpose Display name shown in UI | @invariant Not unique across users */
name: string;
};
```
Code has no TS errors and no transpile-only constructs broken under native Node TS.
npx tsc --noEmit
Exit 0; empty stdout/stderr.
Project-level lint pipeline (format + type-check), per `package.json`.
npm run lint
Exit 0.
Smoke-grep for forbidden transpile-only constructs and raw `console.*`.
rg --follow --no-heading -n "^\s*(enum |namespace |private )|#[a-zA-Z_]+\s*[:=]|\bconsole\.(log|warn|error|info|debug)\b" -t ts --glob '!**/node_modules/**' --glob '!**/dist/**'
Empty (no matches) on new/changed files; matches on pre-existing files tolerated only if outside current task scope.
Verify anchor parity and enable agent grep-navigation: every `// #region START_X` must have `// #endregion END_X` in the same file.
rg --follow --no-heading -n "#(region|endregion)\s+(START|END)_[A-Z0-9_]+" -t ts
For every `START_NAME` occurrence there is a matching `END_NAME` in the same file; counts equal per file.
✅ File has `// @file:` line-comment header; `// @consumers:` / `// @tasks:` when applicable; no `@purpose` at file level.
✅ Every exported entity has valid JSDoc contract per `AX_BASE_CONTRACT_SHAPE`; tag order preserved.
✅ Implementation roots use `@purpose` + `@implements`; member implementations use `@see`; overrides write the full contract.
✅ Comments carry intent (purpose / consumer / invariant / side effect / failure mode / non-goal); do NOT restate syntax.
✅ Anchors on every non-trivial control-flow block; intent-named, not syntax-named; paired `START_X`/`END_X`; compact single-line form when one payload kind, multi-line when 2+.
✅ Trivial guards and single-action branches NOT wrapped in anchors.
✅ Error messages contain Trace-Prefix; rethrow uses `{ cause }`; catch blocks follow Catch-Log-Recover (log + throw OR log + `return fail()` per surrounding contract).
✅ Logs through shared logger from `#logger`; format `[Trace-Prefix] [stateA → stateB] Description`; primitives in message, objects in detail.
✅ Modern TS operators (`?.`, `??`, `||=`, `&&=`, `??=`) instead of verbose null-checks.
✅ Class fields declared explicitly in body; `readonly` on field declaration; `protected _foo` over `private`/`#`.
✅ Names express teleology (business goal), not topology (pattern); precise verbs; public names do NOT leak transport.
✅ Complex functions declare resilience / strategy guarantees via `@invariant`; body starts with executable code.
✅ External-system types carry domain prefix; data shapes use `type`; polymorphism uses `interface`; Error subclasses use `class`.
❌ Use of `enum`, `namespace`, or constructor parameter properties (transpile-only).
❌ Use of the `private` modifier or `#` private fields.
❌ Raw `console.*`, pseudo-logger `const logger = console`, or object serialization into message string.
❌ Error without Trace-Prefix or without `{ cause }` on rethrow inside business logic.
❌ Missing try/catch on integration boundary of a business method.
❌ Comments that restate loops/branches/assignments, or duplicate JSDoc or log messages.
❌ Anchors around atomic operations (lone return, single const) or with syntax-style names.
❌ Missing anchor on non-trivial block with independent policy / side effect / refactor hazard.
❌ Mismatched JSDoc tag order; duplication of TS fields in `@param`/`@returns`; `@see` on a runtime-bearing root instead of `@purpose` + `@implements`.
❌ Mixed implementation reference style (local-relative and project-root-relative `@implements`/`@see` in one module).
❌ Premature abstraction: extracting an interface for a single consumer without confirmed variance.
❌ Defensive code against states excluded by types or invariants.