 |
libmemalloc 0.0.0-alpha
The Magic of Memory Transmutation
|
|
libmemalloc 0.0.0-alpha
The Magic of Memory Transmutation
|
Use this standard when writing or reviewing reusable Lua modules, repository scripts and Git hooks. It defines names, formatting, normal control flow, values, errors, ownership, resources, native boundaries and the evidence required for performance changes.
Read Lua Module Architecture for dependency, port and lifecycle rules. Use Common Lua Pitfalls to connect a failure scenario to prevention controls and a verification design. Read Lua comments and readable layout for source presentation and Lua performance and JIT for profiling and optimization procedures.
The Lua guides define their own conventions, explanations and verification requirements. Read the guide index for source layout, documentation, runtime optimization and module design. Distinguish project conventions from language semantics and tool capabilities. Review source and tool configuration changes against these requirements; documentation alone does not establish conformance.
The standard owns normative local rules, the restricted-facility register and performance evidence. The architecture guide owns module boundaries, permitted dependencies, lifecycle composition and release surface. The pitfalls catalogue owns failure scenarios and verification designs; it does not introduce a second set of hidden requirements.
Use stable LSTYLE-*, LPERF-*, LBAN-*, LMOD-* and LPIT-* IDs in reviews, deviations and tests. These identifiers belong to the Lua policy. An ID identifies a control; record the repository commit or document digest when its exact wording matters.
A must or imperative is a project requirement. Should is the expected default and needs a recorded rationale when not followed. May grants permission. A review trigger calls for a recorded design review, not an automatic claim that code is incorrect. Risk and obligation are separate: a presentation violation and a native use-after-free do not have equivalent consequences.
| Class | Meaning |
|---|---|
| CORRECTNESS | Language semantics and satisfied functional contracts. |
| PORTABILITY | Runtime, grammar, representation, platform and native ABI assumptions. |
| SECURITY | External authority, executable input, secrets and trust boundaries. |
| SAFETY | Failure, timing or state behavior within an explicit product hazard model. |
| ARCHITECTURE | Ownership, interfaces, dependencies and lifecycle. |
| ANALYZABILITY | Reviewable rules and reproducible verification evidence. |
| PROJECT_STYLE | Names and presentation choices; not language guarantees. |
Honor the selected language and platform semantics first, then approved product safety/security constraints, then this policy and its authoritative repository configuration. External style guides are supporting references. A contradiction is a defect or a deviation to resolve, not permission to silently select whichever rule is convenient. A configuration change is a reviewed policy change; this document does not authorize weakening existing checks.
A deviation records the rule, baseline, affected paths/profiles, reason, alternatives, risk, compensating controls, evidence, owner, required approver and expiry/review condition. No blanket lint or formatter suppressions are introduced by this set. Do not claim certification, MISRA conformance or a functional-safety level merely because these coding rules were followed.
Repository: RafaelVVolkmer/libmemalloc. Resolve tool versions from the repository lock and configuration files. Relative links refer to this repository, not to the upstream style-guide source.
| Authority | Observed setting |
|---|---|
| Toolchain lock | Lua 5.5.1; Selene 0.31.0; StyLua 2.5.2; LuaLS 3.19.1. |
| EditorConfig | Lua and extensionless hooks: spaces, indentation 3, width 80. |
| StyLua configuration | Lua54 grammar; width 80; Unix newlines; AutoPreferDouble. |
| Selene configuration | Standard libmemalloc-lua. |
| Selene API catalogue | Lua 5.4 grammar; lua51 API base with selected I/O and UTF-8 additions. |
| LuaLS configuration | Runtime Lua 5.5; explicit diagnostic severities. |
| Lua runner | Parser, dictionary consistency, Selene, StyLua and LuaLS. |
| Markdown policy | Markdown lint configuration; ordinary prose width 120. |
Do not collapse these into one version number. The selected execution runtime is Lua 5.5.1; the formatter accepts its configured Lua54 grammar; Selene uses its own declared API catalogue; LuaLS models Lua 5.5. The Selene base does not make Lua 5.1 the execution target. Conversely, LuaLS accepting a name does not prove Selene recognizes it. Features must satisfy every applicable gate.
The catalogue adds signatures for io.lines, io.stderr.write, utf8.codes and utf8.len to its base. It is not blanket approval of every later API such as table.pack, table.unpack, math.type, string.pack or host-specific libraries. Qualify additions through the catalogue, parser, formatter, runtime and tests; do not hide missing names behind global allowlists.
LuaLS marks undefined-global and duplicate-set-field as errors and redefined-local as a warning. The runner invokes LuaLS with --checklevel=Warning. Required executables are resolved through LIBMEMALLOC_LUA, LIBMEMALLOC_LUAC, LIBMEMALLOC_SELENE, LIBMEMALLOC_STYLUA and LIBMEMALLOC_LUALS. A missing required tool is a failure. These observations describe the retrieved configuration, not a full tool run performed while authoring these files.
Use imperative, structured operations with explicit validation, effects, state transitions and output. Small pure functions, closures, callbacks and data-driven dispatch are allowed when their contracts stay visible. Metatable-driven object models need an explicit reason; this set does not require classes, inheritance, fluent interfaces or a particular third-party framework.
Lua values are dynamically typed and objects are managed by the runtime. The runtime model does not supply C pointer ownership, fixed table layout, deterministic resource finalization or OS-thread synchronization. The host profile must identify its numeric model, memory/resource limits, encoding, locale, native dependencies, clock, scheduling and yield rules. LuaLS annotations assist analysis but do not impose runtime types. See the Lua manual.
The baseline is a trusted hosted-tooling profile, not a hard-real-time or hostile-code sandbox profile. LuaJIT, Luau, other Lua versions, embedded hosts and native extensions require separately named assumptions and tests. C object-layout and microarchitecture rules remain with the native adapter. A safety- or security-critical application needs its own hazard/threat analysis and qualification evidence beyond these documents.
Every function declares ret, has one final ::function_output:: label and one final return. Additional result values follow ret. A total predicate may use Boolean ret; an action uses a module-owned status, with zero success and named negative failures. A module chunk ends with its export-table return; that is not an early return from a function.
Only forward goto function_output convergence is allowed. No early function returns, backward jumps, alternate cleanup labels, break or simulated continue are introduced. Declare locals at the start of their lexical block and compile complete functions to catch illegal jumps into scope. Keep loops bounded and progress visible. Nested functions have independent SESE obligations.
This is normal source-level flow, not a guarantee that every exception executes the label. Unprotected errors, host termination, suspension and resource exhaustion need their own contracts. Put protection at the owner of an exception boundary; preserve primary errors and attempt cleanup for acquired resources. pcall does not by itself enforce non-yielding behavior. A qualified <close> profile must address close semantics and cannot be treated as an ordinary reassignable handle. See LSTYLE-046 through LSTYLE-048.
| Item | Lua policy | Local explanation |
|---|---|---|
| Lua indentation | Three spaces. | Source layout. |
| Lua width | 80 columns. | LSTYLE-014. |
| Markdown prose | At most 120 columns. | Repository documentation convention. |
| Source size | Review above 1,000 physical lines. | LSTYLE-019. |
| Dedicated contract size | Review above 500 lines. | LSTYLE-019. |
| Function length | Review cohesion; no numeric cap. | LSTYLE-020. |
| Cyclomatic complexity | Gate at 10 with the declared Lizard adapter convention. | LSTYLE-020. |
| Cognitive complexity | Gate at 15 with the declared Lua AST convention. | LSTYLE-021. |
| Parameter count | Prefer at most five, including context/self. | LSTYLE-022. |
| Public function | MODULE_lowerCamelCase. | LSTYLE-007. |
| Private/internal function | module_lowerCamelCase and lexical local. | LSTYLE-007. |
| Variables and fields | snake_case, with meaningful unit suffixes. | LSTYLE-006. |
| Constants and statuses | MODULE_SCREAMING_CASE. | LSTYLE-010. |
| Annotated record / alias | UpperCamelCase / module_name_t. | LSTYLE-009. |
These metrics are not enforced as a complete policy by the repository Lua runner. Do not substitute an invented numeric report for an analyzer. Source size excludes no lines unless the selected review convention says so; a deviation records its counting and applicability rules.
| Reference | Retained contribution | Deliberate boundary |
|---|---|---|
| LuaRocks | Local scope, modules and three spaces. | Project function names and SESE take precedence. |
| Kong | APIs, errors and production review. | Not its two spaces or early-return style. |
| Roblox | Organization, documentation and readable interfaces. | No tabs, Luau syntax or Roblox host APIs. |
| Olivine Labs | Style, modules and tests. | Legacy examples need current-profile review. |
| Hisham on modules | Lexical state and module tables. | Not a peer-port architecture. |
| Lua manuals | Semantic authority for the selected runtime. | A manual does not choose project style. |
| StyLua, Selene, LuaLS | Tool behavior. | Repository settings and versions. |
Luacheck remains a possible supplementary reference, not a required repository gate introduced here. LuaRocks the style-guide source and LuaRocks the package manager are different concerns. This set does not install packages, add a framework or authorize new third-party dependencies.
Examples marked contextual show one rule in an enclosing module/function contract. They may use previously validated values or documented ports. They are not standalone programs and must not be pasted without their stated preconditions. All complete functions retain SESE. Intentionally noncompliant fragments are examples to review, not approved patterns or code to execute.
Complete appendices supply named files with their imports, contracts and tests. Save only those named blocks to a disposable fixture directory when reproducing the example. A Markdown blockquote marker > is not part of Lua source; it preserves three-space Lua indentation inside the two-space Markdown document policy. Do not copy that marker into a .lua file.
The current runner does not extract Markdown Lua fences. This set therefore distinguishes document structure checks, extracted-source checks, runtime tests and full repository gates. The embedded examples use ordinary supported APIs and Lua54-compatible syntax, but only the executed checks in the authoring record are reported as passed.
Class: PORTABILITY / CORRECTNESS. Obligation: project requirement.
Use the locked Lua 5.5.1 runtime for repository qualification. Write syntax accepted by the configured Lua54 formatter and use APIs recognized by the libmemalloc-lua Selene standard, or obtain a reviewed tool-profile change. Record these as three different constraints.
Rationale: LuaLS selecting Lua 5.5 does not expand the formatter grammar or Selene API catalogue. A successful parser run is not evidence that every other check accepts a feature.
Verification design: Record the lock digest, tool versions, target OS, numeric representation, locale, dependencies and command results. Reject an unsupported required feature rather than silently changing interpreters.
Related failure scenarios: LPIT-051.
Source context: Repository profile; Lua 5.5 manual.
Contract or layout example (not executable):
runtime: Lua 5.5.1 formatter syntax: Lua54 Selene standard: libmemalloc-lua, based on lua51 LuaLS runtime: Lua 5.5
Noncompliant fragment or claim (do not copy):
runtime: whichever lua happens to be on PATH
Class: ANALYZABILITY. Obligation: project requirement.
Apply the Lua language contract before project conventions. Label portability, correctness, security, architecture and presentation requirements separately. A project naming rule must not be described as a Lua implementation restriction.
Rationale: Lua values are dynamically typed. The project does not turn Lua into C, add static memory ownership, or make comments enforce runtime types.
Verification design: For every deviation, record the rule ID, baseline commit, owner, affected paths, rationale, evidence and review condition. Correct diagnostics at their source; do not add blanket suppressions.
Source context: Governance; Lua 5.5 manual.
Contract or layout example (not executable):
rule: LSTYLE-007 class: PROJECT_STYLE reason: preserve project public API spelling
Noncompliant fragment or claim (do not copy):
Lua itself requires MODULE_lowerCamelCase names.
Class: CORRECTNESS. Obligation: project requirement.
Implement operations as explicit validation, state transition, effect and output stages. Permit small pure functions, closures and data-driven dispatch when their state, errors and cost remain visible. Do not hide the application lifecycle in metatables or a fluent DSL.
Rationale: Explicit stages let reviewers follow state changes and failure paths. Closures and tables remain useful when their ownership and effects are visible.
Verification design: Identify every effectful call and state mutation in review. Trace one success path and every failure path to the common output.
Source context: LSTYLE-023.
Contract or layout example (not executable):
validate request -> compute candidate -> perform bounded effect -> publish -> output
Noncompliant fragment or claim (do not copy):
A field read silently opens a file, retries and changes global state.
Class: PORTABILITY / CORRECTNESS. Obligation: project requirement.
Place LuaJIT, Luau, Lua 5.1 and native-host compatibility in separately named profiles. Do not introduce Luau types, continue statements, JIT-only FFI or Lua 5.5-only syntax into the current Lua54 source profile.
Rationale: Shared ancestry does not establish parser, number, standard-library, coroutine or ABI equivalence.
Verification design: Test each claimed runtime separately. Record the unsupported features and keep profile-specific code behind its owning adapter.
Related failure scenarios: LPIT-025.
Source context: Lua 5.4 manual; Lua 5.5 manual; Roblox guide.
Contract or layout example (not executable):
portable source: current Lua54-compatible grammar Luau or LuaJIT backend: separate opt-in profile
Noncompliant fragment or claim (do not copy):
Parse under LuaJIT and declare the source qualified for Lua 5.5.1.
Class: ANALYZABILITY. Obligation: project requirement.
Distinguish complete runnable programs, contextual fragments and intentionally noncompliant examples. Full correct functions must follow the same SESE and naming rules as production code. An illustrative fragment is not an approved exception.
Rationale: A fragment may omit its enclosing module and preconditions; treating it as a runnable program would invent guarantees.
Verification design: Extract complete appendices and run them. Check fragments in a declared harness. Do not execute negative shell, loader, deletion or resource-exhaustion examples.
Related failure scenarios: LPIT-052.
Source context: Example policy.
Contract or layout example (not executable):
Complete program: includes setup, operation and assertions. Contextual fragment: requires the stated owning function or module.
Noncompliant fragment or claim (do not copy):
Mark a fragment with undefined callbacks as a complete implementation.
Class: PROJECT_STYLE. Obligation: project requirement.
Use descriptive snake_case for local variables, parameters and project-owned data fields. Include units or counts when meaningful: _ms, _us, _ns, _bytes, _count, _idx and _pct. Keep Boolean names affirmative.
Rationale: Names identify a value's role and units at its use site. Distinguish byte counts, indices and durations before passing them across a module boundary.
Verification design: Compare names with their contracts and callers. Do not rename external protocol fields without an adapter.
Source context: Lua governance.
Contextual Lua fragment (requires its enclosing contract):
local timeout_ms = 250 local payload_bytes = 0 local retry_count = 3 local is_ready = false
Noncompliant fragment or claim (do not copy):
local TimeOut = 250 local sz = 0
Class: PROJECT_STYLE. Obligation: project requirement.
Use MODULE_lowerCamelCase for project public operations and module_lowerCamelCase for private or module-internal helpers. Define private functions with local function. Use a local table to export only the public names. The name alone provides no encapsulation.
Rationale: The module prefix identifies the owning API, and its case distinguishes public operations from local helpers during review. Lexical scope and export assignments enforce the actual visibility.
Verification design: Inspect exported keys and the lexical scope of helpers. Treat host-defined names and existing compatibility APIs as named boundary exceptions.
Source context: LuaRocks guide.
Contextual Lua fragment (requires its enclosing contract):
local function codec_isByte(value) local ret = false ret = type(value) == "number" and value >= 0 and value <= 255 and value % 1 == 0 ::function_output:: return ret end local function CODEC_isByte(value) local ret = false ret = codec_isByte(value) ::function_output:: return ret end local codec = {} codec.CODEC_isByte = CODEC_isByte
Noncompliant fragment or claim (do not copy):
function parseValue(value) return value end
Class: PROJECT_STYLE. Obligation: project requirement.
Keep the module table local and export a finite, reviewed set of operations. Finish a module chunk with return module_table. That chunk-level return is not a function-level SESE escape. Do not export private helpers solely for tests.
Rationale: Lua has no C linker visibility for ordinary Lua functions. Module privacy comes from lexical reachability and the exported object graph.
Verification design: Enumerate module keys in API tests. Check that state and private function references are absent.
Related failure scenarios: LPIT-004, LPIT-043.
Source context: LMOD-001; Module guidance.
Contextual Lua fragment (requires its enclosing contract):
local codec = {} -- Public operations are assigned here. return codec
Noncompliant fragment or claim (do not copy):
_G.codec = {}
_G.codec.private_state = {}
Class: PROJECT_STYLE. Obligation: project requirement.
Use UpperCamelCase for documented record/class names and prefixed snake_case for aliases; a _t alias suffix is allowed. Describe fields and callback signatures with LuaLS annotations. Do not describe an annotation as runtime validation or a C ABI layout.
Rationale: Distinct type and value names make annotations easier to read. An annotation describes a contract; callers still need runtime validation at external boundaries.
Verification design: Check annotations with LuaLS and validate untrusted values at runtime. Keep public annotation names stable.
Source context: LuaLS annotations.
Contextual Lua fragment (requires its enclosing contract):
---@class CodecConfig ---@field capacity_bytes integer ---@field is_enabled boolean ---@alias codec_status_t integer
Noncompliant fragment or claim (do not copy):
---@class uint32_t -- This annotation forces a 32-bit unsigned runtime integer.
Class: PROJECT_STYLE. Obligation: project requirement.
Use MODULE_SCREAMING_CASE for immutable-by-contract constants and symbolic status or state values. Assign external numeric codes explicitly. Validate sparse values by membership and masks by allowed bits. A count sentinel is not a valid state.
Rationale: Lua has no C enum declaration or unsigned literal suffix. An uppercase table key does not freeze a mutable table.
Verification design: Test unknown, negative, fractional and sentinel inputs. Review mutation of all exported constant tables.
Related failure scenarios: LPIT-015.
Source context: Lua governance.
Contextual Lua fragment (requires its enclosing contract):
local CODEC_OK = 0 local CODEC_EINVAL = -1 local CODEC_STATE_IDLE = 1 local CODEC_STATE_BUSY = 2
Noncompliant fragment or claim (do not copy):
local CODEC_OK = "success sometimes"
Class: PROJECT_STYLE. Obligation: project requirement.
Do not invent leading-underscore project names. Preserve Lua-defined _G, _ENV, _VERSION and metamethod fields such as __index only where the language or host requires them. A reviewed portability marker ends with __; it never starts with __.
Rationale: This is a project naming convention. Preserve the exact spelling of runtime names and metamethods because the runtime looks them up by name.
Verification design: Review all leading-underscore names. Require an actual language or external API purpose; do not create cosmetic pseudo-metamethods.
Source context: Lua metamethods.
Contextual Lua fragment (requires its enclosing contract):
local metadata = { __index = {} } local PLATFORM_FEATURE__ = false
Noncompliant fragment or claim (do not copy):
local __private_cache = {}
local metadata = { index__ = {} }
Class: PROJECT_STYLE. Obligation: project requirement.
Use create/destroy for instance lifetime, init/deinit for initialization of caller-owned state, start/stop for activity, reset for a documented state reset and close for releasing an external handle. Describe whether a closed instance can be reused.
Rationale: GC reachability and semantic resource lifetime are different. A misleading verb can hide allocation, authority or an irreversible transition.
Verification design: Test repeated close, use after close, restart and failed construction according to the declared contract.
Source context: Lua governance.
Contract or layout example (not executable):
create -> configured instance start -> active instance stop -> quiescent instance destroy -> unusable instance
Noncompliant fragment or claim (do not copy):
reset silently closes a caller-owned file and changes its path.
Class: PROJECT_STYLE. Obligation: project requirement.
Use snake_case for Lua filenames and project directories. Use stable dot-separated require names corresponding to the approved source layout. Keep the Lua guide filenames in their established kebab-case form. Preserve Git-defined hook filenames.
Rationale: Case-dependent names and ambiguous search locations make imports dependent on the host filesystem.
Verification design: Test imports on supported platforms and reject case-only module collisions. Review module aliases in the packaging manifest.
Source context: Lua governance.
Contract or layout example (not executable):
codec/packet_parser.lua contracts/sink_port.lua .githooks/pre-commit docs/standards/lua/lua-code-standard.md
Noncompliant fragment or claim (do not copy):
Parser.lua and parser.lua both provide the same logical module.
Class: PROJECT_STYLE. Obligation: project requirement.
Use UTF-8, LF, a final newline, spaces and three columns per Lua indentation level. Keep Lua source at or below 80 columns. Apply AutoPreferDouble rather than an absolute ban on single quotes. Do not add formatter-ignore comments.
Follow Lua comments and readable layout for blank lines, call/check adjacency, LDoc contracts, and the terminal EOF marker. The formatter adapter checks formatter output without the required final empty line; the EOF checker validates that line on the original file. This exception changes no code.
Rationale: The checked-in EditorConfig and StyLua settings outrank external guide formatting choices. A formatter target width is not a justification for an overlong unbreakable token.
Verification design: Run StyLua with tools/lint/code/lua/stylua.toml and the repository EditorConfig checker. Check extensionless Lua hooks too.
Source context: EditorConfig; StyLua config.
Contextual Lua fragment (requires its enclosing contract):
local function codec_isEmpty(value) local ret = false ret = value == "" ::function_output:: return ret end
Noncompliant fragment or claim (do not copy):
local message = "one enormous unbroken source line that exceeds the policy"
Class: PROJECT_STYLE. Obligation: project requirement.
Let StyLua choose continuation indentation and delimiter layout. Break calls and record constructors at syntax boundaries. Split long strings only when concatenation preserves the intended bytes and performance contract.
Rationale: A wrapped diagnostic must not accidentally insert whitespace into a protocol literal. Use three spaces for each indentation level, including continuation blocks.
Verification design: Compare byte-sensitive string results and run the configured formatter. Count the Lua content of examples separately from Markdown quote markers.
Source context: StyLua.
Contextual Lua fragment (requires its enclosing contract):
local message = "The packet header is invalid; " .. "check the declared payload length."
Noncompliant fragment or claim (do not copy):
local token = "ab " .. "cd" -- The inserted space changes the token.
Class: PROJECT_STYLE. Obligation: project requirement.
Use multiline control bodies and explicit call parentheses. Do not use semicolon-packed statements or clever operator chains for control flow. Use parentheses to make mixed operators clear without overriding the configured formatter.
Rationale: The reader should see each state update and decision as a separate step.
Verification design: Review diff-visible state changes and ambiguous arithmetic or Boolean combinations.
Source context: Kong guide.
Contextual Lua fragment (requires its enclosing contract):
local is_ready = false local has_capacity = true if has_capacity then is_ready = true end
Noncompliant fragment or claim (do not copy):
local is_ready=false; if true then is_ready=true end
Class: PROJECT_STYLE. Obligation: project requirement.
Declare a block's ordinary locals before its first executable operation. Keep the block as small as the contract allows. Treat implicit for-loop variables and local-function bindings as Lua-specific declarations. Introduce a nested block for a genuinely later lifetime.
Rationale: This groups initialization for review and prevents jumps from entering the scope of later locals. Do not declare a function-wide cache just to avoid a small block.
Verification design: Inspect every forward goto against local scopes and initialization. Use separate declarations; permit multiple assignment when receiving one documented result tuple.
Related failure scenarios: LPIT-005, LPIT-028.
Source context: Lua local scope.
Contextual Lua fragment (requires its enclosing contract):
local ret = 0 local value = nil local detail = nil ret, value, detail = codec.CODEC_decode(input)
Noncompliant fragment or claim (do not copy):
perform_effect() local owned_handle = acquire()
Class: CORRECTNESS. Obligation: project requirement.
Do not shadow unrelated project locals, imports or standard-library names. Each nested function has its own operation scope and must declare its own ret; its result locals may reuse conventional result names when they do not accidentally capture or conceal state used by that function. Initialize state to a meaningful neutral or invalid value. Use annotations for documented nil-to-value transitions; do not add false work merely to silence a checker.
Rationale: Lua initializes unassigned locals to nil, but that does not establish a valid domain state. A late local can also capture a different binding than expected.
Verification design: Run Selene and LuaLS; review every redefined-local diagnostic. Trace closure bindings and result states on failure.
Related failure scenarios: LPIT-004, LPIT-005.
Source context: Lua scope; LuaLS configuration.
Contextual Lua fragment (requires its enclosing contract):
---@type string|nil local payload = nil local is_valid = false
Noncompliant fragment or claim (do not copy):
local string = {}
local payload = payload
Class: PROJECT_STYLE. Obligation: review trigger.
Review a Lua source file above 1,000 physical lines for cohesion. Apply the 500-line interface review trigger to a dedicated contracts or public-annotation file, not to an invented Lua header. These are review triggers, not automatic correctness failures.
Rationale: Large interfaces increase the work needed to understand callers and compatibility. Review whether each file has one responsibility; function length has no universal numeric cap in this policy.
Verification design: Record the count convention, generated-code scope, owner and decision when retaining a larger file. Do not split a state invariant across arbitrary files.
Source context: Lua governance.
Contract or layout example (not executable):
packet_parser.lua: parsing only packet_contract.lua: fields and public contracts only
Noncompliant fragment or claim (do not copy):
Move every 100th line into a helper solely to satisfy a metric.
Class: ANALYZABILITY. Obligation: required.
Every owned Lua function must satisfy the cyclomatic limit in tools/analysis/c/gates.json, currently 10. The Lua quality gate uses the locked Lizard counter with parser-defined function boundaries. The documented convention counts branches, loops and boolean decisions while isolating nested function bodies.
Rationale: A measured gate makes regression visible across production code, tests and configuration. Formatting alone cannot establish complexity.
Verification design: Retain the complete report with analyzer versions, source digests and policy digest. Review behavior, cohesion and effects alongside the score; a failing function must be decomposed before the gate can pass.
Source context: Lua governance.
Contract or layout example (not executable):
threshold: 10 measurement: lua-ast-lizard-v1 action above threshold: fail and refactor
Noncompliant fragment or claim (do not copy):
StyLua passed, therefore cyclomatic complexity is below 10.
Class: ANALYZABILITY. Obligation: required.
Every owned Lua function must satisfy the cognitive limit in the shared quality policy, currently 15. The Lua quality gate defines lua-cognitive-v1, its AST traversal and independently tested counting rules. This repository metric is not presented as a SonarQube score.
Rationale: A metric supports review but cannot guarantee comprehension. Remove unnecessary nesting and hidden state; moving code into callbacks alone does not establish a clearer design.
Verification design: Store analyzer versions, the convention identifier and all function scores. Parser failure is a gate failure. Test branch behavior and side effects after decomposing a function.
Source context: Lua governance.
Contract or layout example (not executable):
cognitive convention: lua-cognitive-v1 limit: 15 manual review: nested decisions and callback effects inspected
Noncompliant fragment or claim (do not copy):
Report a cognitive score inferred from the number of source lines.
Class: PROJECT_STYLE. Obligation: review trigger.
Prefer at most five parameters per operation, including explicit context and an implicit self parameter. A reviewed DTO may group a cohesive configuration, but an unbounded options table must not hide unrelated controls. Varargs do not evade the count.
Rationale: The parameter threshold is a design review trigger. Typed C parameter checking is not available to validate arbitrary Lua option tables.
Verification design: Review required and optional fields, nil versus absence, defaults and invalid values. Record an exception when an external callback fixes the signature.
Related failure scenarios: LPIT-008.
Source context: Lua governance.
Contract or layout example (not executable):
operation(context, request, deadline_ms) request: documented cohesive fields
Noncompliant fragment or claim (do not copy):
operation(a, b, c, d, e, f, ...)
Class: CORRECTNESS. Obligation: project requirement.
Every project-owned function must declare a visible ret, converge on one final ::function_output:: label and have one final return statement. Return additional documented tuple values only after ret. Do not introduce guard-clause early returns.
Rationale: This is the project's source-level normal-flow policy. It is not proof that exceptions, coroutine suspension or process termination cannot bypass that path.
Verification design: Inspect nested functions separately. Every goto target must be function_output and forward. Use a Lua parser, not a raw keyword count, for future automated enforcement.
Related failure scenarios: LPIT-027, LPIT-029.
Source context: Lua goto.
Contextual Lua fragment (requires its enclosing contract):
local function codec_isNonempty(value) local ret = false if type(value) ~= "string" then goto function_output end ret = #value > 0 ::function_output:: return ret end
Noncompliant fragment or claim (do not copy):
local function codec_isNonempty(value)
if value == nil then
return false
end
return #value > 0
end
Class: CORRECTNESS. Obligation: project requirement.
Use goto only to transfer control forward to the owning function's final function_output label. Do not jump backward, emulate continue, jump into a nested scope or create alternate cleanup labels. A failure inside a loop exits through the function output, not a second loop exit.
Rationale: Lua forbids a jump into the scope of a local. The final label must have the intended cleanup locals in scope; a shared label does not fix skipped acquisition.
Verification design: Compile complete functions. Test failure at each acquisition and prove that only acquired resources are released.
Related failure scenarios: LPIT-028.
Source context: Lua block and goto semantics.
Contextual Lua fragment (requires its enclosing contract):
local function codec_validateCount(value) local ret = 0 if type(value) ~= "number" then ret = -1 goto function_output end if value < 0 then ret = -1 goto function_output end ::function_output:: return ret end
Noncompliant fragment or claim (do not copy):
::retry:: run_operation() goto retry
Class: CORRECTNESS. Obligation: project requirement.
Do not use break or a simulated continue. Use a bound, a progress variable and a termination condition. Use a while loop when completion depends on mutable state. Do not modify a numeric-for control variable to alter iteration.
Rationale: Normal loop completion should be visible at the loop header. An exceptional function-level failure may still converge on function_output.
Verification design: Test empty, one-element, maximum-size, not-found and early-found inputs. Verify monotonic progress or a finite retry budget.
Source context: Lua governance.
Contextual Lua fragment (requires its enclosing contract):
local item_idx = 1 local has_match = false while item_idx <= item_count and not has_match do has_match = items[item_idx] == wanted item_idx = item_idx + 1 end
Noncompliant fragment or claim (do not copy):
for item_idx = 1, item_count do
if items[item_idx] == wanted then
break
end
end
Class: CORRECTNESS. Obligation: project requirement.
Perform effectful calls and capture their results before a condition. Permit named pure predicates in conditions. Do not depend on the relative evaluation order of multiple effectful call arguments or on a short-circuit chain to sequence a transaction.
Rationale: A visible call/result/check sequence makes failure and state mutation auditable.
Verification design: Use mocks to record call order and verify that failure prevents later effects.
Source context: Lua governance.
Contextual Lua fragment (requires its enclosing contract):
local ret = 0 local is_ready = false ret, is_ready = port.PROBE_check(context) if ret == 0 and is_ready then state.is_ready = true end
Noncompliant fragment or claim (do not copy):
send(acquire_next(), advance_cursor()) open_resource() and write_resource() or recover()
Class: CORRECTNESS. Obligation: project requirement.
Prefer iteration for untrusted-depth data. Recursion requires a documented depth/resource bound and profile approval; prohibit it in critical bounded paths. A tail call is not a substitute for the normal-output policy or a bound on total work.
Rationale: Lua recursion, metamethod calls and callbacks can grow execution depth. Reentry may invalidate state even without OS threads.
Verification design: Test maximum depth, cycles and callback reentry. Measure the actual runtime behavior instead of assuming a C-style stack frame size.
Source context: Lua function calls.
Contract or layout example (not executable):
walk input with an explicit bounded work queue reject depth above the configured limit before descending
Noncompliant fragment or claim (do not copy):
Recursively expand arbitrary nested input until the VM fails.
Class: CORRECTNESS. Obligation: project requirement.
Validate the value type before arithmetic, indexing or method calls; then validate shape, membership, range, size and allowed effects. Treat values entering through a public API, configuration, file or callback as untrusted unless a stronger boundary contract is established.
Rationale: A table-shaped value may still have a metatable, missing fields or hostile nested content. An annotation is not a runtime check.
Verification design: Test nil, false, incorrect primitive types, missing keys, nested malformed data, NaN, infinities and over-budget input where applicable.
Related failure scenarios: LPIT-016, LPIT-021.
Source context: Lua values.
Contextual Lua fragment (requires its enclosing contract):
local function codec_isCapacity(value) local ret = false if type(value) ~= "number" then goto function_output end ret = value >= 0 and value <= 4096 and value % 1 == 0 ::function_output:: return ret end
Noncompliant fragment or claim (do not copy):
local size_bytes = request.payload.size_bytes
Class: CORRECTNESS. Obligation: project requirement.
Treat false and nil as different domain values unless the contract explicitly equates them. Preserve a valid false when applying defaults. Remember that zero and an empty string are true in conditions. Use explicit nil checks for absence.
Rationale: Mechanical translation of C truth tests or a value-or-default expression can change configuration semantics.
Verification design: Test false, nil, zero and empty-string values independently for every optional field.
Related failure scenarios: LPIT-001, LPIT-002.
Source context: Lua truth values.
Contextual Lua fragment (requires its enclosing contract):
local is_enabled = config.is_enabled if is_enabled == nil then is_enabled = true end
Noncompliant fragment or claim (do not copy):
local is_enabled = config.is_enabled or true
Class: CORRECTNESS. Obligation: project requirement.
Do not use condition and value_a or value_b as a general conditional expression when value_a may be false or nil. Keep effectful selection in an if/else statement. Permit short-circuit defaults only where discarding false is part of the contract.
Rationale: Lua logical operators return operands rather than always returning booleans.
Verification design: Exercise both branches with truthy and false/nil result values. Check that only the intended effects occur.
Related failure scenarios: LPIT-002, LPIT-003.
Source context: Lua logical operators.
Contextual Lua fragment (requires its enclosing contract):
local selected = nil if is_primary then selected = primary_value else selected = fallback_value end
Noncompliant fragment or claim (do not copy):
local selected = is_primary and primary_value or fallback_value
Class: CORRECTNESS. Obligation: project requirement.
Use one-based dense sequences for ordinary project collections. Use # only when the object is a string or a proven sequence with no holes. Store an explicit count for sparse collections or nil-bearing tuples. Do not rely on # to count a map.
Rationale: Lua table length is a border operation, not a general key count. Integer keys and string keys are distinct.
Verification design: Test empty sequences, a hole at the start/middle/end, sparse high indices and accidental string indices.
Related failure scenarios: LPIT-007, LPIT-009, LPIT-010.
Source context: Lua table length.
Contextual Lua fragment (requires its enclosing contract):
local items = { "header", "payload" } local item_count = #items local total_bytes = 0 for item_idx = 1, item_count do total_bytes = total_bytes + #items[item_idx] end
Noncompliant fragment or claim (do not copy):
local items = { [1] = "a", [3] = "c" }
local item_count = #items
Class: CORRECTNESS. Obligation: project requirement.
Use numeric iteration for a dense indexed sequence and pairs for maps only when order is irrelevant. Do not add keys during a next/pairs traversal. Collect intended updates first when mutation would obscure the traversal contract. Sort explicit keys for deterministic output.
Rationale: Map traversal order is not a serialization, hashing or test-order contract.
Verification design: Repeat tests under different insertion orders and fresh processes. Test removals without accidentally skipping shifted elements.
Related failure scenarios: LPIT-010, LPIT-011, LPIT-012.
Source context: Lua traversal.
Contextual Lua fragment (requires its enclosing contract):
local key_list = { "alpha", "beta", "gamma" } local ordered_fields = {} for key_idx = 1, #key_list do ordered_fields[key_idx] = record[key_list[key_idx]] end
Noncompliant fragment or claim (do not copy):
for key, value in pairs(record) do write_signed_record(key, value) end
Class: ARCHITECTURE / CORRECTNESS. Obligation: project requirement.
Document whether an input table is borrowed read-only, borrowed mutable, copied or retained. Publish outputs only after validation succeeds. A table assignment is reference copying, not an independent snapshot. Define shallow versus recursive copying explicitly.
Rationale: GC prevents neither accidental shared mutation nor semantic use after close. Cycles and metatables make generic deep-copy behavior a design decision.
Verification design: Mutate the caller's input after construction and inspect the instance. Test that rejected input leaves public state unchanged.
Related failure scenarios: LPIT-013, LPIT-014.
Source context: Lua references.
Contextual Lua fragment (requires its enclosing contract):
local snapshot = { timeout_ms = config.timeout_ms }
Noncompliant fragment or claim (do not copy):
local snapshot = config snapshot.timeout_ms = 0
Class: ARCHITECTURE / CORRECTNESS. Obligation: project requirement.
Use named fields for semantic records. Do not depend on constructor order for effects or repeat the same record key. Keep constant tables private or expose an interface that enforces the intended access contract. A __newindex hook alone does not freeze existing fields.
Rationale: Ordinary field writes may bypass __newindex when the key already exists. An uppercase name or annotation is not a write barrier.
Verification design: Test all mutation paths, nested aliases and raw operations when a read-only API is claimed.
Related failure scenarios: LPIT-015.
Source context: Lua constructors and metatables.
Contextual Lua fragment (requires its enclosing contract):
local config = { timeout_ms = 250, retry_count = 3, is_enabled = true, }
Noncompliant fragment or claim (do not copy):
local config = { timeout_ms = 100, timeout_ms = 250 }
Class: CORRECTNESS. Obligation: project requirement.
Give every public operation a fixed documented result shape. Capture all required results and distinguish no results, nil results and a valid false. Do not assume a parenthesized call or a non-final call in a list preserves multiple values.
Rationale: Lua adjusts result counts according to expression position. A wrapper can silently drop an error code or trailing nil.
Verification design: Test success and failure arity, trailing nil and intermediate wrappers. Use a count-bearing representation when values must be stored.
Related failure scenarios: LPIT-006, LPIT-007, LPIT-033.
Source context: Lua result adjustment.
Contextual Lua fragment (requires its enclosing contract):
local ret = 0 local value = nil local detail = nil ret, value, detail = codec.CODEC_decode(input)
Noncompliant fragment or claim (do not copy):
local ret, value = (codec.CODEC_decode(input))
Class: CORRECTNESS. Obligation: project requirement.
Use _bytes for byte lengths and offsets. State whether a string contains arbitrary bytes, ASCII or validated UTF-8. Do not use # or string.sub as a count or slice of Unicode characters. Define normalization separately when identity comparisons require it.
Rationale: Lua strings are immutable byte sequences and may contain embedded zeros. UTF-8 decoding is not normalization or grapheme segmentation.
Verification design: Test empty input, embedded NUL, multibyte sequences, malformed UTF-8 and visually equivalent but differently encoded text.
Related failure scenarios: LPIT-017.
Source context: Lua strings and UTF-8; Selene UTF-8 additions.
Contextual Lua fragment (requires its enclosing contract):
local payload_bytes = #payload local valid_count, invalid_byte_idx = utf8.len(text)
Noncompliant fragment or claim (do not copy):
local character_count = #text
Class: CORRECTNESS. Obligation: project requirement.
Use string.find with plain=true when the searched value is literal text. Treat Lua patterns as a separate interpreted language: quote or reject external pattern syntax according to the input contract. Bound input and pattern work.
Rationale: Lua patterns are not regular expressions; metacharacters can change what a search accepts.
Verification design: Test literal punctuation, percent signs, brackets, empty needles and inputs at the maximum size.
Related failure scenarios: LPIT-018.
Source context: Lua pattern functions.
Contextual Lua fragment (requires its enclosing contract):
local match_start = string.find(text, needle, 1, true)
Noncompliant fragment or claim (do not copy):
local match_start = string.find(text, user_supplied_literal)
Class: CORRECTNESS. Obligation: project requirement.
Keep format strings trusted and validate argument types. Do not pass external replacement text directly as a gsub replacement when percent escapes must remain literal. Use a reviewed escaping or replacement-function boundary.
Rationale: A data string becomes instructions when used as a format, pattern or replacement template.
Verification design: Test percent sequences, unexpected argument types, embedded NUL and oversized output. Keep output budgets explicit.
Related failure scenarios: LPIT-019, LPIT-020.
Source context: Lua string functions.
Contextual Lua fragment (requires its enclosing contract):
local diagnostic = string.format("invalid field: %s", field_name)
Noncompliant fragment or claim (do not copy):
local diagnostic = string.format(untrusted_text, value)
Class: PORTABILITY / CORRECTNESS. Obligation: project requirement.
Reject NaN, infinities, fractions and out-of-range values when the contract requires a bounded count or integer. Do not assume a successful tonumber proves the required textual grammar or integer representation.
Rationale: Lua permits numeric conversions and configurable numeric representations. A domain bound must be checked before it controls work, storage or a native conversion.
Verification design: Test signed text, whitespace, exponents, hexadecimal, fractional values and the largest accepted count. Test the chosen runtime representation independently.
Related failure scenarios: LPIT-021, LPIT-022, LPIT-023, LPIT-024, LPIT-025.
Source context: Lua numerals and conversions.
Contextual Lua fragment (requires its enclosing contract):
local function codec_isBoundedCount(value) local ret = false if type(value) ~= "number" then goto function_output end ret = value >= 0 and value <= 65535 and value % 1 == 0 ::function_output:: return ret end
Noncompliant fragment or claim (do not copy):
local item_count = tonumber(input) or 0
Class: CORRECTNESS. Obligation: project requirement.
For nonnegative bounded counts, compare count against capacity - used before adding. Check multiplication against an established quotient bound before multiplying. Do not translate C unsigned-suffix or UB reasoning into Lua.
Rationale: Lua integer arithmetic may wrap, and floating-point arithmetic may lose precision. A result that looks small after arithmetic does not prove the inputs were safe.
Verification design: Test exact capacity, one beyond, zero, negative and representation boundaries. Establish integer domains before using a subtraction-based bound.
Related failure scenarios: LPIT-024.
Source context: Lua arithmetic.
Contextual Lua fragment (requires its enclosing contract):
if payload_bytes > capacity_bytes - used_bytes then ret = CODEC_ENOSPC end
Noncompliant fragment or claim (do not copy):
if used_bytes + payload_bytes <= capacity_bytes then state.used_bytes = used_bytes + payload_bytes end
Class: PORTABILITY / CORRECTNESS. Obligation: project requirement.
Check divisor and domain before division. Distinguish / from // and specify the intended negative-number rounding rule. Keep logical and/or separate from bitwise operations. Require an explicit width and representation at a binary boundary.
Rationale: Lua arithmetic is not a direct transcription of C integer arithmetic. Bitwise operators, precision and API availability also depend on the selected profile.
Verification design: Test zero divisors, negative operands, large integers and all declared shift or mask bounds. Compile profile-specific operators with every required checker.
Related failure scenarios: LPIT-025.
Source context: Lua arithmetic and bitwise operations.
Contract or layout example (not executable):
division contract: nonnegative counts, divisor greater than zero mask contract: explicit external width and allowed bits
Noncompliant fragment or claim (do not copy):
Assume / on two integers produces a C-style truncated integer.
Class: PORTABILITY / CORRECTNESS. Obligation: project requirement.
Define encoding, byte order, field widths, length limits, ordering and version independently of in-memory Lua tables. Keep string.pack/unpack or native encoders behind a profile-approved adapter; the current Selene catalogue is not a blanket approval of those APIs.
Rationale: Lua tables are not C structs or stable wire layouts. Bytecode is executable runtime-specific content, not a general data format.
Verification design: Use golden vectors, malformed-length tests and cross-platform round trips. Verify canonical ordering where bytes are signed or hashed.
Related failure scenarios: LPIT-011, LPIT-023, LPIT-026.
Source context: Lua binary formats; LSTYLE-001.
Contract or layout example (not executable):
version: 1 length: unsigned 16-bit big-endian payload: exactly length bytes unknown versions: rejected
Noncompliant fragment or claim (do not copy):
Persist string.dump(function) as a portable configuration format.
Class: CORRECTNESS. Obligation: project requirement.
Use ret=0 for success and documented negative module-owned codes for expected failures in action APIs. Return outputs after ret and initialize unavailable outputs to nil. Total predicates may use a Boolean ret; do not use them to conceal multi-state failures.
Rationale: Standard Lua library calls have different return conventions. Translate them at adapters rather than pretending every number is a POSIX errno.
Verification design: Test all documented status codes, tuple positions and output values on failure. Check that false can remain a valid payload.
Related failure scenarios: LPIT-001, LPIT-006, LPIT-030, LPIT-033.
Source context: LSTYLE-035.
Contextual Lua fragment (requires its enclosing contract):
local function codec_getDefault() local ret = 0 local value = false ::function_output:: return ret, value end
Noncompliant fragment or claim (do not copy):
return true -- Sometimes success, sometimes the operation result.
Class: CORRECTNESS. Obligation: project requirement.
Capture and inspect status from I/O, callbacks, process operations, close and protected calls. Preserve the first operation failure unless the public contract explicitly prioritizes a cleanup failure. A pcall success flag is not the wrapped operation's success code.
Rationale: Two success dimensions exist at a protected callback: normal Lua execution and domain-level success.
Verification design: Inject both a thrown error and a normal error tuple. Confirm the caller rejects both and does not publish a partial output.
Related failure scenarios: LPIT-001, LPIT-030.
Source context: Lua protected calls.
Contextual Lua fragment (requires its enclosing contract):
local call_ok = false local operation_ret = nil call_ok, operation_ret = pcall(port.WRITE_send, context, data) if not call_ok or operation_ret ~= 0 then ret = CODEC_EIO end
Noncompliant fragment or claim (do not copy):
local call_ok = pcall(port.WRITE_send, context, data) if call_ok then ret = CODEC_OK end
Class: CORRECTNESS. Obligation: project requirement.
Return expected validation, capacity and availability failures through ret and function_output. Reserve assert and error for documented invariant or host-fatal policies. Always give assert a meaningful message and keep effects outside assertions.
Rationale: Lua assertions are runtime calls; they are not automatically removed in a release build as a C assert macro might be. An assertion can bypass manual cleanup.
Verification design: Run failure tests without relying on assertions for external validation. Check that changing diagnostic settings cannot remove required work.
Related failure scenarios: LPIT-034.
Source context: Lua assert and errors.
Contextual Lua fragment (requires its enclosing contract):
local function codec_validateText(value) local ret = 0 if type(value) ~= "string" then ret = -1 goto function_output end ::function_output:: return ret end
Noncompliant fragment or claim (do not copy):
assert(write_output(data))
Class: CORRECTNESS. Obligation: project requirement.
Use pcall or xpcall at a named boundary that owns translation of thrown failures. Document whether callbacks may throw or yield. Keep error handlers bounded and avoid assuming an error object is a string. Do not silently turn programming errors into successful output.
Rationale: Table access, arithmetic and tostring may invoke metamethods. Manual function_output cleanup does not run after an unprotected exception.
Verification design: Throw a string, a table and an object with a failing __tostring from a test port. Verify stable status mapping, cleanup and retained primary diagnostics.
Related failure scenarios: LPIT-018, LPIT-029, LPIT-030, LPIT-031, LPIT-040.
Source context: Lua error handling.
Contract or layout example (not executable):
call boundary: catch external callback failure normal result: validate callback status and payload error object: retain bounded diagnostic, never assume string
Noncompliant fragment or claim (do not copy):
pcall(every_statement) and ignore all errors
Class: ARCHITECTURE / CORRECTNESS. Obligation: project requirement.
Give every external resource one semantic owner. Record successful acquisitions and release them in reverse dependency order at function_output. Borrowed resources must not be closed by a borrower. Clear references only after applying the documented close-result policy.
Rationale: GC reachability does not establish when a file, process, lock or native handle is released. A reference can remain alive after its resource is invalid.
Verification design: Fail each acquisition, operation and close stage; verify close count, order, preserved error and output state. Include exception paths through the owning protected boundary.
Related failure scenarios: LPIT-027, LPIT-029, LPIT-032, LPIT-035, LPIT-036.
Source context: Lua finalization.
Contract or layout example (not executable):
acquire A -> acquire B -> work -> function_output function_output: release B if acquired, then A if acquired
Noncompliant fragment or claim (do not copy):
Trust __gc to close every file before the next operation.
Class: CORRECTNESS. Obligation: project requirement.
A Lua <close> local requires explicit syntax/checker qualification and an owning adapter contract. Declare it at the start of its lexical block with an immediately valid value. Do not combine automatic close and manual close of the same ownership without a proved idempotent contract.
Rationale: A to-be-closed local has scope-based semantics and may run on unwinding; it is not a writable handle slot. Its close handler may also fail. The baseline examples use explicit cleanup to avoid overstating tool coverage.
Verification design: In a separately qualified example, test normal exit, goto, exception, close failure and coroutine cancellation. Keep close order explicit.
Related failure scenarios: LPIT-037.
Source context: Lua to-be-closed variables.
Contract or layout example (not executable):
adapter profile: to-be-closed resource close owner: exactly one manual cleanup: must not duplicate automatic release
Noncompliant fragment or claim (do not copy):
Declare a nil <close> local and later assign an acquired handle to it.
Class: ARCHITECTURE / CORRECTNESS. Obligation: project requirement.
Compute and validate a candidate before changing externally visible state. State whether an operation provides an unchanged-on-failure, partial-progress or terminal-failure guarantee. Keep caller outputs unchanged or explicitly invalid on failure.
Rationale: SESE centralizes the result but does not make a multi-step operation atomic or roll back effects.
Verification design: Inject failure before and after each publication point. Verify the documented state guarantee rather than only the return code.
Related failure scenarios: LPIT-033.
Source context: Lua governance.
Contextual Lua fragment (requires its enclosing contract):
local candidate_count = used_count + incoming_count -- Bounds were checked before this addition. state.used_count = candidate_count
Noncompliant fragment or claim (do not copy):
state.used_count = state.used_count + 1 validate_untrusted_record(record)
Class: CORRECTNESS. Obligation: project requirement.
Declare budgets for bytes, entries, nesting, queued work, retained diagnostics and retries. Enforce them before growth or repeated work. Avoid unbounded read-all, accumulation and table growth on external input.
Rationale: Lua strings, tables and closures may allocate implicitly. Review memory growth from runtime operations and retained references even when source code has no explicit allocation call.
Verification design: Exercise limits, repeated rejected inputs and long-running workloads. Measure retained memory and allocation behavior on the selected VM.
Related failure scenarios: LPIT-014, LPIT-020.
Source context: Lua memory management.
Contextual Lua fragment (requires its enclosing contract):
if incoming_bytes > capacity_bytes - retained_bytes then ret = CODEC_ENOSPC end
Noncompliant fragment or claim (do not copy):
local payload = file:read("*a") -- Arbitrary external file size.
Class: CORRECTNESS. Obligation: project requirement.
Document VM-level allocation failure and native allocator behavior separately from a normal capacity error. Do not claim that pcall, diagnostic allocation or a Lua cleanup callback always makes out-of-memory recovery safe.
Rationale: Allocating the error report or invoking cleanup may itself need resources. A Lua-level capacity check is not a proof about the entire VM allocator.
Verification design: Use controlled host fault injection where supported and retain the runtime/allocator profile. Keep availability claims narrower than the evidence.
Source context: Lua errors and memory management.
Contract or layout example (not executable):
capacity failure: CODEC_ENOSPC, normal operation contract VM allocation failure: host policy, separately tested
Noncompliant fragment or claim (do not copy):
pcall guarantees graceful recovery from any allocation failure.
Class: ARCHITECTURE / CORRECTNESS. Obligation: project requirement.
Use local functions and explicit operation tables for the ordinary core. Keep metatables small, owned and documented. Do not make field reads, comparisons or tostring perform unexpected I/O, unbounded work or lifecycle transitions.
Rationale: Metamethods are executable callbacks, not passive declarations. Reading a borrowed table may cross a trust boundary.
Verification design: Test missing keys, recursive __index, reentry and throwing metamethods where such objects are allowed. Reject metatables on untrusted record inputs when the contract requires plain data.
Related failure scenarios: LPIT-015, LPIT-016.
Source context: Lua metatables.
Contextual Lua fragment (requires its enclosing contract):
local ret = 0 if type(request) ~= "table" then ret = CODEC_EINVAL elseif getmetatable(request) ~= nil then ret = CODEC_EINVAL end
Noncompliant fragment or claim (do not copy):
return request.payload -- The read may execute an unknown __index.
Class: ARCHITECTURE / CORRECTNESS. Obligation: project requirement.
Document captured mutable state and lifetime for every stored callback. Avoid capturing an entire request graph when a bounded value is sufficient. Define how a callback is unbound and when its captures become unreachable.
Rationale: A closure can retain data long after an operation returns. Capturing a reference is neither a snapshot nor a synchronization mechanism.
Verification design: Replace or mutate the source state in tests and verify intended callback behavior. Check retained memory after unbind and quiescence.
Related failure scenarios: LPIT-042.
Source context: Lua lexical scope; LMOD-016.
Contract or layout example (not executable):
callback capture: private immutable identifier context lifetime: provider remains valid until all calls finish
Noncompliant fragment or claim (do not copy):
Store a closure over an unbounded request, then retain it forever.
Class: CORRECTNESS. Obligation: project requirement.
Only yield at documented scheduler boundaries. Do not yield while private invariants are transient or an external resource requires uninterrupted ownership. Check coroutine.resume status and distinguish yielded results from a completed coroutine.
Rationale: A successful resume may mean suspension rather than completion. Cooperative execution still allows state changes between resumptions.
Verification design: Test every suspension point, errors before and after yield, cancellation and teardown of a suspended task.
Related failure scenarios: LPIT-038, LPIT-039.
Source context: Lua coroutines.
Contract or layout example (not executable):
scheduler contract: yielded / completed / failed are separate states resource contract: ownership survives or is released at each suspension
Noncompliant fragment or claim (do not copy):
Treat the first true result from coroutine.resume as task completion.
Class: ARCHITECTURE / CORRECTNESS. Obligation: project requirement.
Document reentry and synchronization for instances and callbacks. A local busy flag may reject synchronous reentry, but it is not an OS-thread lock. Do not share a Lua state across host threads without the host's approved serialization policy.
Rationale: Independent Lua states, coroutine tasks and native OS threads are different execution domains.
Verification design: Use a callback that attempts to call the same instance. Test teardown during active work under the actual host synchronization model.
Related failure scenarios: LPIT-040, LPIT-041.
Source context: Lua coroutines and C API.
Contextual Lua fragment (requires its enclosing contract):
if state.is_busy then ret = CODEC_EBUSY end
Noncompliant fragment or claim (do not copy):
A boolean is_busy field makes every native-thread call safe.
Class: ARCHITECTURE / CORRECTNESS. Obligation: project requirement.
Keep collectgarbage policy, weak tables and memory-sensitive cache behavior with a named VM or cache owner. Do not disable GC around unbounded work. Weak references are an eviction mechanism, not a guaranteed retained-resource contract.
Rationale: GC scheduling and performance vary by runtime and configuration. Collection of Lua memory does not prove external resource release.
Verification design: Measure bounded workloads with the deployed GC policy and test cache misses after collection. Record retained handles separately from Lua heap estimates.
Related failure scenarios: LPIT-036.
Source context: Lua GC.
Contract or layout example (not executable):
cache: bounded and recreatable GC tuning: VM owner, measured workload and rollback record
Noncompliant fragment or claim (do not copy):
Stop GC permanently to make a benchmark faster.
Class: SECURITY. Obligation: project requirement.
Do not execute external input with load, loadfile or dofile in ordinary modules. A loader adapter must define code origin, integrity, permitted environment, bytecode policy and process capabilities. Treat execution as execution even when the input looks like configuration.
Rationale: An environment table alone is not a complete sandbox or a memory/time limit. Native capabilities can escape a nominally restricted Lua environment.
Verification design: Test rejected code origins, binary chunks and capability access in the loader's isolated test environment. Do not execute hostile samples in general unit tests.
Related failure scenarios: LPIT-016, LPIT-047.
Source context: Lua loading functions; LBAN-001.
Contract or layout example (not executable):
configuration: parse inert data with a size and schema contract code loading: separate trusted adapter
Noncompliant fragment or claim (do not copy):
load(user_configuration)()
Class: SECURITY. Obligation: project requirement.
Use fixed approved module names and a controlled search path. Do not compose require names from untrusted text or mutate package.path/package.cpath inside ordinary modules. Existing trusted dofile bootstrap logic belongs to the composition boundary, not the module core.
Rationale: Search-path order can select a different provider. Clearing package.loaded does not invalidate references already held by consumers.
Verification design: Test a hostile working directory, duplicate module names and missing dependencies. Record which roots and native libraries are trusted.
Related failure scenarios: LPIT-045, LPIT-046.
Source context: Lua require; Repository runner.
Contextual Lua fragment (requires its enclosing contract):
local codec = require("codec.packet_parser")
Noncompliant fragment or claim (do not copy):
local plugin = require(user_supplied_name)
Class: SECURITY. Obligation: project requirement.
Do not concatenate external data into os.execute or io.popen commands. Use the repository's approved platform/process adapter and its documented argv and quoting contract. Standard Lua does not itself supply a universal cross-platform execve-style interface.
Rationale: A list of arguments is only safe if the adapter preserves argument boundaries and accounts for the downstream program's option syntax.
Verification design: Test spaces, quotes, newlines, metacharacters, leading dashes and platform-specific parsing. Check exit status, timeout and output limits.
Related failure scenarios: LPIT-048.
Source context: Lua OS and I/O libraries.
Contract or layout example (not executable):
process port: executable identity plus separate validated arguments external filename: data argument, never shell source
Noncompliant fragment or claim (do not copy):
os.execute("tool " .. untrusted_path)
Class: SECURITY. Obligation: project requirement.
Define the allowed filesystem root, file type, link policy, permissions and lifetime of path validation. Keep file reads, writes, temporary objects and persistence inside the filesystem adapter. Do not claim lexical normalization prevents symlink races.
Rationale: A relative path, a normalized string and an authorized file object are different things.
Verification design: Test traversal, absolute paths, links, replacement between check and use, partial writes and failed close within an isolated fixture.
Related failure scenarios: LPIT-047, LPIT-049.
Source context: Lua governance.
Contract or layout example (not executable):
filesystem contract: trusted root, permitted operation, bounded bytes atomic replacement: only when the platform adapter guarantees it
Noncompliant fragment or claim (do not copy):
Reject ../ and assume all remaining paths are authorized.
Class: SECURITY. Obligation: project requirement.
Use an injected diagnostic port for reusable modules. Bound and sanitize external text, redact secrets, and avoid exposing whole objects or raw callback errors to logs. Do not claim immutable Lua strings can be reliably zeroized from Lua.
Rationale: Formatting and copies can retain sensitive bytes. Module-local logging also couples a library to process-global output.
Verification design: Inspect failure logs for credentials, payloads and control characters. Verify that disabled diagnostics do not change required state transitions.
Related failure scenarios: LPIT-020, LPIT-031, LPIT-050.
Source context: Lua strings.
Contract or layout example (not executable):
diagnostic: operation ID, bounded error code, redacted context secret lifetime: host-owned boundary with an explicit retention policy
Noncompliant fragment or claim (do not copy):
print("request failed", secret_payload, raw_error_object)
Class: PORTABILITY / CORRECTNESS. Obligation: project requirement.
Isolate native bindings and LuaJIT FFI in named adapters. Define ABI, integer conversions, pointer ownership, callback roots, lifetime, thread affinity and error-unwinding rules. Do not copy C pointer casts, bit-field layouts or memory barriers into portable Lua.
Rationale: Native code can reintroduce C memory and concurrency hazards that ordinary Lua tables do not model.
Verification design: Run C-side sanitizers and ABI tests separately from Lua tests. Keep a pure reference implementation where the contract permits one.
Related failure scenarios: LPIT-023, LPIT-026, LPIT-041.
Source context: Lua C API.
Contract or layout example (not executable):
core -> owned port -> native adapter -> qualified C ABI returned native handle: validated type and explicit close state
Noncompliant fragment or claim (do not copy):
Pass a floating-point number as an unchecked native pointer address.
Class: CORRECTNESS. Obligation: project requirement.
Use an injected monotonic clock for elapsed durations and deadlines. Do not treat os.clock as wall time or a general monotonic I/O timer. Use approved entropy for security; math.random is not a cryptographic source. Bound retries and record the seed for reproducible tests.
Rationale: Correctness depends on the meaning of a clock and a random source, not merely on their numeric type.
Verification design: Test clock jumps, deadline expiry, retry exhaustion and deterministic replay. Keep the test RNG out of production authentication or token generation.
Source context: Lua clock and random libraries.
Contract or layout example (not executable):
deadline_ms: injected monotonic clock domain test randomness: logged seed security randomness: separate approved provider
Noncompliant fragment or claim (do not copy):
local token = tostring(math.random())
Class: ANALYZABILITY. Obligation: project requirement.
Reject a missing required checker, unsupported profile, invalid contract or denied authority. Do not turn security checks into optional warnings merely because a tool or dependency is inconvenient. Keep optional developer convenience distinct from required merge or release evidence.
Rationale: A normal exit code from a skipped check is not evidence that the property was checked.
Verification design: Test missing-tool paths and verify they fail with a useful diagnostic. Record not-run rather than pass when evidence is absent.
Related failure scenarios: LPIT-051.
Source context: Repository runner.
Contract or layout example (not executable):
required tool missing -> failure with tool identity check not executed -> NOT RUN, never PASS
Noncompliant fragment or claim (do not copy):
Skip Selene after an error and print "all checks passed".
Class: ANALYZABILITY. Obligation: project requirement.
Describe purpose, parameter domains, return tuple, ownership, effects, error behavior, synchronization, yield policy and resource bounds. Use LuaLS annotations for machine-readable shapes and ordinary prose for guarantees they cannot express.
Rationale: LDoc-style prose and LuaLS annotations complement each other, but duplicating inconsistent type declarations creates a second contract.
Verification design: Compare documentation, runtime checks and tests. Do not add a new mandatory documentation generator that is not present in the repository.
Related failure scenarios: LPIT-008.
Source context: LuaLS annotations; LuaRocks guide.
Contextual Lua fragment (requires its enclosing contract):
--- Validate a bounded byte count without changing external state. ---@param value number ---@return boolean ret
Noncompliant fragment or claim (do not copy):
--- Does stuff. ---@param value any
Class: ANALYZABILITY. Obligation: project requirement.
Run scripts/check/lua.lua from the repository root with the locked tools. Preserve its syntax, dictionary, Selene, StyLua and LuaLS stages. Use LIBMEMALLOC_LUA, LIBMEMALLOC_LUAC, LIBMEMALLOC_SELENE, LIBMEMALLOC_STYLUA and LIBMEMALLOC_LUALS only as documented executable overrides.
Rationale: A parallel ad hoc lint recipe can omit extensionless hooks, the custom standard or warning-level LuaLS failures.
Verification design: Resolve the absolute root with git rev-parse –show-toplevel, change to it and invoke the script there. Save versions and the complete exit status.
Related failure scenarios: LPIT-051.
Source context: Repository runner; Toolchain lock.
Contract or layout example (not executable):
lua ./scripts/check/lua.lua
Noncompliant fragment or claim (do not copy):
Run stylua with default settings and call that repository validation.
Class: ANALYZABILITY. Obligation: project requirement.
The current runner discovers tracked .lua files and extensionless programs through its shebang logic; it does not extract Lua fences from Markdown. Validate embedded complete examples explicitly. Do not claim documentation-only changes caused all examples to be linted by that runner.
Rationale: Documentation examples can drift even when the repository check passes. The wrapper and workflow also have distinct source-detection code.
Verification design: Extract examples to a disposable checkout, use exact paths with direct checkers, and run complete tests. Never accidentally stage extraction artifacts in a production branch.
Related failure scenarios: LPIT-052.
Source context: Repository runner; Workflow Lua job.
Contract or layout example (not executable):
Markdown example -> extracted temporary .lua -> syntax/lint/test tracked repository source -> canonical Lua runner
Noncompliant fragment or claim (do not copy):
The Markdown file was checked, therefore every Lua example was checked.
Class: ANALYZABILITY. Obligation: project requirement.
Cover public contracts, boundary values, malformed inputs, every acquisition stage, callback exceptions, resource cleanup and state after failure. Use mocks for injected ports and a deterministic seed for randomized sequences. Preserve an independent expected-result model.
Rationale: Passing happy-path unit tests or a coverage percentage does not prove ownership, ordering or bounds.
Verification design: Record which requirements each test addresses and which profiles ran. Avoid executing uncontrolled resource exhaustion, arbitrary shell commands or hostile bytecode.
Source context: Common Lua Pitfalls.
Contract or layout example (not executable):
case: callback returns failure assert: failure propagated, busy flag reset, no partial publication
Noncompliant fragment or claim (do not copy):
Assert only that the operation returns a non-nil value.
Class: ANALYZABILITY. Obligation: project requirement.
Identify statement, branch and other coverage metrics separately. Report numerator, denominator, excluded code and unreachable-path justification. Do not equate 100 percent statement coverage with complete path coverage, MC/DC or product assurance.
Rationale: The review discipline requires evidence proportional to the claim. The baseline Lua runner is not a coverage or safety-case generator.
Verification design: Keep reports linked to code and tool versions. Investigate missing branches and mutation-test survivors where such testing is used.
Related failure scenarios: LPIT-054.
Source context: Lua governance.
Contract or layout example (not executable):
statement coverage: measured with named tool branch coverage: separately measured SESE review: separate evidence
Noncompliant fragment or claim (do not copy):
100 percent coverage proves the library safe for every critical system.
Class: ANALYZABILITY. Obligation: project requirement.
Pin runtime and tool dependencies through the repository lock. Treat LuaRocks style guidance separately from LuaRocks package installation. A new rock, native module or test framework requires dependency and profile review; do not add it solely because an external guide mentions it.
Rationale: Package identity, build inputs and transitive native dependencies can change program behavior and authority.
Verification design: Record package version, source integrity, license, native build settings and affected tests. Avoid network installation inside ordinary module initialization.
Source context: Toolchain lock; LuaRocks guide.
Contract or layout example (not executable):
style source: LuaRocks guide new package: separate dependency review tool versions: tools/toolchain/lock.toml
Noncompliant fragment or claim (do not copy):
require a missing package and auto-install it from the network.
Class: PORTABILITY / CORRECTNESS. Obligation: project requirement.
Define which guarantees the Lua module supplies and which require its host or native adapter. Lua owns export visibility, argument validation, status contracts, aliases and logical resource lifetime. The host owns OS-thread synchronization, native memory access, ABI compatibility and process resource enforcement.
Rationale: A reachable Lua reference can hold a closed resource. A coroutine busy flag cannot lock shared native memory against another OS thread. State each guarantee at the boundary that can enforce it.
Verification design: Use the responsibility table and exercise invalid input, closed handles, callback retention and host failures. Identify the owner and test for each requirement.
Source context: Lua and host responsibilities.
Contract or layout example (not executable):
module visibility -> lexical local and explicit exports resource lifetime -> open/closed state and an explicit owner native buffer -> adapter bounds checks and a retained backing allocation
Noncompliant fragment or claim (do not copy):
Use an include guard table to make Lua memory safe.
Class: ANALYZABILITY. Obligation: project requirement.
Apply this new policy to new or deliberately revised code through a reviewed migration plan. Record existing snake_case function APIs, early returns and trusted bootstrap loading as migration items rather than claiming the baseline already satisfies the new SESE/naming policy.
Rationale: The checked-in runner itself uses existing Lua conventions. Passing its checks does not enforce all rules in these documents.
Verification design: Map affected paths, preserve public compatibility at adapters and update tests with each migration. Do not loosen checks to make a migration appear complete.
Source context: Repository runner; Governance.
Contract or layout example (not executable):
existing public name -> compatibility adapter -> project operation SESE migration -> reviewed control-flow change with failure tests
Noncompliant fragment or claim (do not copy):
Claim every existing Lua source already follows these new rules.
Accept a Lua optimization after measuring its benefit for a declared runtime and workload and checking contract equivalence. Lua performance and JIT explains profiling, trace behavior, allocation tradeoffs and the benchmark procedure for applying these controls.
Class: ANALYZABILITY. Obligation: project requirement.
Require a baseline, candidate, representative workload, repeat count and correctness oracle before accepting a performance change. Measure the externally meaningful operation, including necessary validation and cleanup.
Rationale: A faster isolated expression can make the complete operation slower or remove a contract.
Verification design: Record inputs, output equivalence, memory use and dispersion, not only the fastest sample.
Related controls: LSTYLE-068, LSTYLE-069.
Related failure scenarios: LPIT-053.
Source context: Lua runtime and collection model.
Contract or layout example (not executable):
baseline = public operation with validation and cleanup candidate = same operation and contract comparison = correctness plus latency, throughput and memory
Class: ANALYZABILITY. Obligation: project requirement.
Record the Lua implementation and version, native dependencies, operating system, processor, build flags, clock, GC mode and effective workload configuration. Keep JIT and interpreter results separate.
Rationale: The same source can have different costs on different interpreters and native backends.
Verification design: Reproduce the experiment with the recorded environment and preserve raw results.
Related controls: LSTYLE-001, LSTYLE-004.
Source context: Lua runtime and collection model.
Contract or layout example (not executable):
runtime + native modules + workload + clock + GC policy + raw samples
Class: ANALYZABILITY. Obligation: project requirement.
Measure startup/import cost separately from steady-state operations. State whether samples include GC, cache population, native initialization or JIT warm-up in a separate JIT profile.
Rationale: Excluding a cost does not remove that cost from the deployed application.
Verification design: Compare cold and warm runs and include a deployment-representative run with normal collection enabled.
Related controls: LSTYLE-050, LSTYLE-056.
Related failure scenarios: LPIT-053.
Source context: Lua runtime and collection model.
Contract or layout example (not executable):
cold import / first operation / sustained operation / full lifecycle
Class: ANALYZABILITY. Obligation: project requirement.
Report P50, P90, P95 and P99 when the sample count and measurement resolution support them. Name the quantile estimator, sample count and units. Do not describe an observed maximum or P99 as a worst-case execution-time proof.
Rationale: A tail percentile based on too few samples is unstable and does not bound future executions.
Verification design: Retain samples, measurement overhead and uncertainty. Use a separately justified method for hard deadlines.
Related controls: LSTYLE-063, LSTYLE-069.
Related failure scenarios: LPIT-054.
Source context: Lua runtime and collection model.
Contract or layout example (not executable):
P50 / P90 / P95 / P99 + sample count + clock resolution + estimator
Class: ANALYZABILITY. Obligation: project requirement.
Review asymptotic work, repeated scans, copying and external calls before changing local spellings. Keep resource bounds and failure behavior explicit.
Rationale: A linear algorithmic improvement can dominate a small lookup optimization without relying on runtime internals.
Verification design: Measure across input sizes, including empty, typical and maximum accepted values.
Related controls: LSTYLE-050.
Source context: Lua runtime and collection model.
Contract or layout example (not executable):
one validated scan instead of repeated full rescans
Class: ANALYZABILITY. Obligation: project requirement.
For substantial repeated assembly, compare collecting bounded string pieces and table.concat with repeated concatenation. Account for the piece table, final string and peak memory. Do not assume the builder is always faster.
Rationale: Intermediate immutable strings and retained pieces both consume resources.
Verification design: Differential-test empty pieces, embedded NUL bytes and maximum aggregate length. Measure peak memory.
Related controls: LSTYLE-036, LSTYLE-050.
Source context: Lua runtime and collection model.
Contract or layout example (not executable):
validated pieces -> bounded piece table -> one final concatenation
Class: ANALYZABILITY. Obligation: project requirement.
Measure allocation churn before reusing tables or hoisting closures. A reused table must not leak prior values or remain borrowed by a previous caller. A hoisted closure must retain the intended context.
Rationale: Reducing allocation can accidentally introduce shared mutable state or extend object lifetime.
Verification design: Test interleaved instances and retained outputs; compare live memory after repeated operations.
Related controls: LSTYLE-033, LSTYLE-053.
Source context: Lua runtime and collection model.
Contract or layout example (not executable):
private scratch storage + explicit reset + no escaping aliases
Class: ANALYZABILITY. Obligation: project requirement.
Cache a library function locally only when the binding is intended to remain stable and measurements justify the change. Decide how tests and approved dependency replacement interact with that binding.
Rationale: A local alias captures the old function even if the source table later changes.
Verification design: Test supported replacement or initialization order and record the speed difference on the selected runtime.
Related controls: LSTYLE-058.
Source context: Lua runtime and collection model.
Contract or layout example (not executable):
bind once at composition -> stable dependency -> measure
Class: ANALYZABILITY. Obligation: project requirement.
Define cache key semantics, capacity, eviction, invalidation and ownership. Do not use weak tables as a substitute for a specified retention policy.
Rationale: A cache can improve latency while causing stale results or retaining an unbounded object graph.
Verification design: Test configuration changes, key collisions, eviction and memory plateau under adversarial key diversity.
Related controls: LSTYLE-056.
Source context: Lua runtime and collection model.
Contract or layout example (not executable):
cache owner -> capacity -> versioned key -> invalidation test
Class: ANALYZABILITY. Obligation: project requirement.
Attribute crossing, conversion, copying and native work separately where useful, while preserving an end-to-end measurement. Batch only when latency, cancellation and failure reporting remain acceptable.
Rationale: A cheap Lua function may hide expensive native work or process creation.
Verification design: Test partial completion and compare throughput against worst observed latency at each batch size.
Related controls: LSTYLE-059, LSTYLE-062.
Source context: Lua runtime and collection model.
Contract or layout example (not executable):
batch size is a measured parameter, not a universal constant
Class: ANALYZABILITY. Obligation: project requirement.
Retain a clear, independent reference implementation or model for specialized algorithms. Do not generate the oracle from the same optimized transformation being tested.
Rationale: Agreement between two implementations sharing the same defect is weak evidence.
Verification design: Differential-test deterministic corpora, boundary values and randomized sequences.
Related controls: LSTYLE-068.
Source context: Lua runtime and collection model.
Contract or layout example (not executable):
portable reference -> expected result <- specialized candidate
Class: ANALYZABILITY. Obligation: project requirement.
Keep SIMD, cache-line layout, atomics, prefetch, NUMA and ISA dispatch decisions inside the owning native adapter. Lua source cannot promise the physical placement of an ordinary table.
Rationale: Native machine properties need measurements of the deployed implementation; they do not establish physical placement or alignment guarantees for ordinary Lua tables.
Verification design: Review native ABI, bounds, lifetime and machine measurements and test the same public Lua contract against every backend.
Related controls: LSTYLE-062, LSTYLE-071.
Source context: Lua runtime and collection model.
Contract or layout example (not executable):
Lua API -> native adapter -> target-specific implementation
Class: ANALYZABILITY. Obligation: project requirement.
Keep logging, formatting, dynamic loading, process creation and uncontrolled retries out of latency-critical loops unless the execution profile explicitly budgets them.
Rationale: The slow exceptional path is still part of a public operation when it can occur in deployment.
Verification design: Inject slow and failing ports and record the operation behavior and upper resource limits.
Related controls: LSTYLE-050, LSTYLE-063.
Source context: Lua runtime and collection model.
Contract or layout example (not executable):
critical operation -> bounded work; diagnostics -> owned bounded port
Class: ANALYZABILITY. Obligation: project requirement.
Treat collector tuning as a runtime-profile change with latency, memory and long-run evidence. Do not stop collection merely to make a benchmark look faster.
Rationale: Deferred collection can shift time out of the measurement window and increase memory without improving the lifecycle.
Verification design: Include long-running workloads and realistic resource pressure. Record all collector settings.
Related controls: LSTYLE-051, LSTYLE-056.
Related failure scenarios: LPIT-053.
Source context: Lua runtime and collection model.
Contract or layout example (not executable):
compare latency and memory over the complete workload duration
Class: ANALYZABILITY. Obligation: project requirement.
Define performance regression thresholds from representative variance and a controlled environment. Separate deterministic correctness gates from noisy performance signals.
Rationale: A single noisy timing failure can encourage unsafe changes or meaningless baseline resets.
Verification design: Record the review and rerun policy; preserve evidence when updating an accepted baseline.
Related controls: LSTYLE-069.
Source context: Lua runtime and collection model.
Contract or layout example (not executable):
correctness gate + controlled performance experiment + reviewed threshold
Class: ANALYZABILITY. Obligation: project requirement.
Record the change owner, contract preserved, baseline and candidate identities, experiment, correctness evidence, risks and rollback condition.
Rationale: An optimization is an engineering decision, not a permanent claim about every future target.
Verification design: Revisit the decision after runtime, compiler, hardware, dependency or workload changes.
Related controls: LSTYLE-002, LSTYLE-070.
Source context: Lua runtime and collection model.
Contract or layout example (not executable):
claim -> experiment -> raw data -> result -> decision -> revalidation trigger
Each LBAN entry names its scope and permitted owner. The register distinguishes prohibited ordinary-core use from qualified boundary use. It does not prohibit the language runtime from providing these facilities, nor override existing trusted bootstrap behavior without a migration review.
Class: SECURITY / CORRECTNESS. Obligation: project requirement.
Scope: load, loadfile and dofile on externally supplied code or paths. Prohibit in ordinary data-processing modules. Permit only a separately approved code-execution boundary with authority, resource and trust controls. A restricted environment table alone is not a sandbox.
Rationale: The restriction belongs to the named project profile, not a claim that Lua lacks the facility.
Verification design: Review every occurrence and its owner. Exercise the approved alternative and failure handling.
Related controls: LSTYLE-057, LSTYLE-060.
Related failure scenarios: LPIT-047.
Source context: Lua facilities and semantics.
Contract or layout example (not executable):
Parse data with a non-executable decoder and explicit size/schema limits.
Class: SECURITY / CORRECTNESS. Obligation: project requirement.
Scope: Externally supplied compiled Lua bytecode. Prohibit in the ordinary ingress profile. Do not treat binary chunk loading as safe parsing or bytecode stripping as a security boundary.
Rationale: The restriction belongs to the named project profile, not a claim that Lua lacks the facility.
Verification design: Review every occurrence and its owner. Exercise the approved alternative and failure handling.
Related controls: LSTYLE-004, LSTYLE-057.
Source context: Lua facilities and semantics.
Contract or layout example (not executable):
Distribute verified source or explicitly qualified trusted artifacts for the exact runtime.
Class: SECURITY / CORRECTNESS. Obligation: project requirement.
Scope: require names and package.path/package.cpath derived from untrusted input. Prohibit in reusable cores. A bootstrap owner may select verified locations before normal execution. Preserve and review the repository existing trusted bootstrap use of dofile.
Rationale: The restriction belongs to the named project profile, not a claim that Lua lacks the facility.
Verification design: Review every occurrence and its owner. Exercise the approved alternative and failure handling.
Related controls: LSTYLE-058.
Source context: Lua facilities and semantics.
Contract or layout example (not executable):
Use an allowlisted mapping of public choices to trusted implementations.
Class: SECURITY / CORRECTNESS. Obligation: project requirement.
Scope: _G writes, shared library-table mutation and replacing peer functions. Prohibit as ordinary module communication. Test-only replacements require an isolated fixture and guaranteed restoration; injected ports are the default.
Rationale: The restriction belongs to the named project profile, not a claim that Lua lacks the facility.
Verification design: Review every occurrence and its owner. Exercise the approved alternative and failure handling.
Related controls: LSTYLE-008, LSTYLE-052.
Source context: Lua facilities and semantics.
Contract or layout example (not executable):
Export a local table and bind dependencies through the composition root.
Class: SECURITY / CORRECTNESS. Obligation: project requirement.
Scope: module(), setfenv-based module construction and implicit global exports. Do not introduce into the baseline profile. Legacy compatibility belongs behind a named adapter with migration tests.
Rationale: The restriction belongs to the named project profile, not a claim that Lua lacks the facility.
Verification design: Review every occurrence and its owner. Exercise the approved alternative and failure handling.
Related controls: LSTYLE-004, LSTYLE-008.
Source context: Lua facilities and semantics.
Contract or layout example (not executable):
Use lexical locals and return a deliberately constructed module table.
Class: SECURITY / CORRECTNESS. Obligation: project requirement.
Scope: os.execute and io.popen in reusable domain code. Restrict to the process adapter. Reject command strings assembled from external data. A Lua table of strings is not safe argv until the underlying adapter semantics are verified.
Rationale: The restriction belongs to the named project profile, not a claim that Lua lacks the facility.
Verification design: Review every occurrence and its owner. Exercise the approved alternative and failure handling.
Related controls: LSTYLE-059.
Related failure scenarios: LPIT-048.
Source context: Lua facilities and semantics.
Contract or layout example (not executable):
Use an approved executable-plus-arguments adapter with an explicit shell policy.
Class: SECURITY / CORRECTNESS. Obligation: project requirement.
Scope: io.input, io.output and library output through global default streams. Prohibit changing process-wide default streams from reusable modules. CLI entry points own terminal policy; libraries receive an I/O port or explicit handle.
Rationale: The restriction belongs to the named project profile, not a claim that Lua lacks the facility.
Verification design: Review every occurrence and its owner. Exercise the approved alternative and failure handling.
Related controls: LSTYLE-047, LSTYLE-061.
Source context: Lua facilities and semantics.
Contract or layout example (not executable):
Pass the owned or borrowed stream and document closing responsibility.
Class: SECURITY / CORRECTNESS. Obligation: project requirement.
Scope: os.exit in reusable module operations. Prohibit outside the application or test-runner boundary. Do not assume all normal cleanup or pending Lua work executes after process termination.
Rationale: The restriction belongs to the named project profile, not a claim that Lua lacks the facility.
Verification design: Review every occurrence and its owner. Exercise the approved alternative and failure handling.
Related controls: LSTYLE-023, LSTYLE-045.
Source context: Lua facilities and semantics.
Contract or layout example (not executable):
Return a status; the entry point selects an exit code after its shutdown policy.
Class: SECURITY / CORRECTNESS. Obligation: project requirement.
Scope: debug access to hidden state, upvalues or peer implementation details. Restrict to approved diagnostics or isolated tests. Do not make correctness or public operations depend on bypassing another module privacy.
Rationale: The restriction belongs to the named project profile, not a claim that Lua lacks the facility.
Verification design: Review every occurrence and its owner. Exercise the approved alternative and failure handling.
Related controls: LSTYLE-052, LSTYLE-061.
Source context: Lua facilities and semantics.
Contract or layout example (not executable):
Use public contracts and injected test ports without exporting private helpers.
Class: SECURITY / CORRECTNESS. Obligation: project requirement.
Scope: math.random or time values as authentication secrets or security nonces. Prohibit for security-sensitive generation. Select and qualify an appropriate host cryptographic randomness port separately.
Rationale: The restriction belongs to the named project profile, not a claim that Lua lacks the facility.
Verification design: Review every occurrence and its owner. Exercise the approved alternative and failure handling.
Related controls: LSTYLE-063.
Source context: Lua facilities and semantics.
Contract or layout example (not executable):
Inject the security-owned randomness provider with explicit failure handling.
Class: SECURITY / CORRECTNESS. Obligation: project requirement.
Scope: GC stopping, forced collection or weak references used as resource-lifetime correctness. Do not rely on them to release finite external resources or to prove a memory bound. Tuning is restricted to the runtime-profile owner.
Rationale: The restriction belongs to the named project profile, not a claim that Lua lacks the facility.
Verification design: Review every occurrence and its owner. Exercise the approved alternative and failure handling.
Related controls: LSTYLE-047, LSTYLE-056.
Source context: Lua facilities and semantics.
Contract or layout example (not executable):
Use explicit close/destroy contracts and measured, bounded retention.
Class: SECURITY / CORRECTNESS. Obligation: project requirement.
Scope: Early returns, backward goto, break-based function escape and Luau continue. Prohibit in the baseline function-level SESE discipline. Use one ret, one function_output label and one final return; loops have explicit progress and stop conditions.
Rationale: The restriction belongs to the named project profile, not a claim that Lua lacks the facility.
Verification design: Review every occurrence and its owner. Exercise the approved alternative and failure handling.
Related controls: LSTYLE-023, LSTYLE-024, LSTYLE-025.
Source context: Lua facilities and semantics.
Contract or layout example (not executable):
Use forward error convergence and a bounded loop predicate.
Class: SECURITY / CORRECTNESS. Obligation: project requirement.
Scope: Ignoring a fallible I/O result, callback status or protected-call outcome. Prohibit. A protected-call Boolean is not the domain status and zero is truthy in Lua.
Rationale: The restriction belongs to the named project profile, not a claim that Lua lacks the facility.
Verification design: Review every occurrence and its owner. Exercise the approved alternative and failure handling.
Related controls: LSTYLE-043, LSTYLE-044, LSTYLE-046.
Source context: Lua facilities and semantics.
Contract or layout example (not executable):
Store the protected-call outcome and the domain result in distinct variables.
Class: SECURITY / CORRECTNESS. Obligation: project requirement.
Scope: Unbounded read-all, queue growth, recursive parsing or retry loops. Prohibit without a bounded trusted-profile justification. Limits must address bytes, elements, depth, attempts and time as relevant.
Rationale: The restriction belongs to the named project profile, not a claim that Lua lacks the facility.
Verification design: Review every occurrence and its owner. Exercise the approved alternative and failure handling.
Related controls: LSTYLE-027, LSTYLE-050, LSTYLE-063.
Source context: Lua facilities and semantics.
Contract or layout example (not executable):
Validate before allocating or publishing and stop according to a finite contract.
Class: SECURITY / CORRECTNESS. Obligation: project requirement.
Scope: Raw pointer/FFI exposure or arbitrary package.loadlib use in domain modules. Restrict to approved native adapters and trusted loading. A native implementation must satisfy its C ABI, memory and concurrency requirements.
Rationale: The restriction belongs to the named project profile, not a claim that Lua lacks the facility.
Verification design: Review every occurrence and its owner. Exercise the approved alternative and failure handling.
Related controls: LSTYLE-058, LSTYLE-062.
Source context: Lua facilities and semantics.
Contract or layout example (not executable):
Expose a narrow typed-by-contract Lua API with verified native ownership.
Class: SECURITY / CORRECTNESS. Obligation: project requirement.
Scope: Blanket lint disables, formatter ignores and fabricated PASS records. Do not add them to avoid correcting the source or qualifying a needed profile change. An approved deviation is explicit, scoped and independently reviewable.
Rationale: The restriction belongs to the named project profile, not a claim that Lua lacks the facility.
Verification design: Review every occurrence and its owner. Exercise the approved alternative and failure handling.
Related controls: LSTYLE-002, LSTYLE-064, LSTYLE-069.
Source context: Lua facilities and semantics.
Contract or layout example (not executable):
Correct the implementation or report the requirement and evidence as not satisfied.
Use this table to assign implementation and verification work. A host-specific guarantee belongs in the selected profile and adapter contract, with a failure test at its Lua interface.
| Concern | Lua implementation | Host or adapter responsibility |
|---|---|---|
| Visibility | Lexical locals and explicit export tables. | Control module search paths and native loading. |
| Dependencies | Named imports, injected ports and a composition root. | Package the approved source and artifacts. |
| Ownership | Track aliases, retained closures and open/closed state. | Keep native allocations alive until last use. |
| Immutable data | Copy inputs or restrict access to private records. | Define native buffer mutation rights. |
| Numbers | Validate range, precision and arithmetic domains. | Check integer conversions and ABI widths. |
| Serialization | Define encoding, length, order and version. | Implement explicit codecs without layout assumptions. |
| Failures | Return documented statuses; protect exception boundaries. | Translate host failures and preserve cleanup errors. |
| Cleanup | One normal output; close acquired resources in owner order. | Release each handle through its matching API. |
| Callbacks | Document retention, yield and reentry. | Unregister and drain callbacks before freeing context. |
| Concurrency | Track coroutine state and allowed suspension points. | Synchronize OS threads and shared native memory. |
| Resources | Bound work, input sizes and retained state. | Enforce process memory, time and handle limits. |
| Performance | Measure workloads, allocation and trace behavior. | Measure native layout and hardware-specific effects. |
| Verification | Exercise contracts, failure paths and reference results. | Test deployed runtimes, ABIs and native dependencies. |
Save the following block as bounded_resource.lua. It exports RESOURCE_run(ports, context). The ports are a trusted plain table with three stable functions: open_fn(context) returns ret, handle; work_fn(context, handle) returns ret, payload; close_fn(context, handle) returns ret. Allowed statuses are integer zero or one of -1 through -5. Names and meanings in this fixture are 0 success, -1 invalid request, -2 open failure, -3 work failure, -4 close failure and -5 unexpected exception/protocol failure. These are example codes, not POSIX errno values.
The callbacks are synchronous and non-yielding by contract. The example does not enforce a hostile callback sandbox, host thread safety or a yield prohibition. The open callback owns resources it has not returned and must clean them up before raising an error. Any non-nil handle it returns, even with a failure status, transfers one cleanup obligation to this operation. A nil handle on success is a protocol error. A callback that leaks an undisclosed resource cannot be repaired by the caller.
A successful work payload is a string or false. Failure returns nil output. The public result tuple is ret, output, cleanup_ret. The primary operation failure is preserved and the third result reports cleanup failure independently. The close callback receives one attempt, not an automatic retry; a failed close does not prove the underlying resource was released. A production adapter must define its post-failure validity and recovery policy.
All acquisition/work exceptions are protected before shared cleanup. This demonstrates normal and callback-error paths under the fixture assumptions, not recovery from arbitrary OOM, fatal host termination or native process corruption. The multi-branch boundary merits the complexity review; no complexity analyzer score is fabricated here.
Complete named source file:
-- SPDX-License-Identifier: GPL-3.0-only -- Owned callback fixture. Callbacks are trusted, synchronous and non-yielding. local resource = {} local RESOURCE_OK = 0 local RESOURCE_EINVAL = -1 local RESOURCE_EPROTO = -5 local function resource_isStatus(value) local ret = false ret = type(value) == "number" and value >= RESOURCE_EPROTO and value <= RESOURCE_OK and value % 1 == 0 ::function_output:: return ret end --- Run one owned-resource operation and preserve its first failure. ---@param ports table ---@param context table ---@return integer ret ---@return string|false|nil output ---@return integer cleanup_ret local function RESOURCE_run(ports, context) local ret = RESOURCE_EINVAL local cleanup_ret = RESOURCE_OK local output = nil local handle = nil local open_fn = nil local work_fn = nil local close_fn = nil local has_completed = false local operation_ret = nil local is_valid_status = false if type(ports) ~= "table" or getmetatable(ports) ~= nil then goto function_output end open_fn = ports.open_fn work_fn = ports.work_fn close_fn = ports.close_fn if type(open_fn) ~= "function" or type(work_fn) ~= "function" or type(close_fn) ~= "function" then goto function_output end has_completed, operation_ret, handle = pcall(open_fn, context) ret = RESOURCE_EPROTO if not has_completed then goto function_output end is_valid_status = resource_isStatus(operation_ret) if not is_valid_status then goto function_output end ret = operation_ret if ret ~= RESOURCE_OK then goto function_output end if handle == nil then ret = RESOURCE_EPROTO goto function_output end has_completed, operation_ret, output = pcall(work_fn, context, handle) ret = RESOURCE_EPROTO if not has_completed then goto function_output end is_valid_status = resource_isStatus(operation_ret) if not is_valid_status then goto function_output end ret = operation_ret if ret == RESOURCE_OK and type(output) ~= "string" and output ~= false then ret = RESOURCE_EPROTO end ::function_output:: if handle ~= nil then has_completed, operation_ret = pcall(close_fn, context, handle) cleanup_ret = RESOURCE_EPROTO if has_completed then is_valid_status = resource_isStatus(operation_ret) if is_valid_status then cleanup_ret = operation_ret end end handle = nil if ret == RESOURCE_OK and cleanup_ret ~= RESOURCE_OK then ret = cleanup_ret end end if ret ~= RESOURCE_OK then output = nil end return ret, output, cleanup_ret end resource.RESOURCE_run = RESOURCE_run return resource
From a checkout, resolve its root with git rev-parse --show-toplevel, change to that absolute directory and use the locked tools. The canonical invocation is lua ./scripts/check/lua.lua. The word lua here means the selected locked executable, not any unrelated program on PATH. Provide the documented LIBMEMALLOC_* overrides when the executables are installed elsewhere.
The retrieved runner first enumerates tracked Lua sources, including its extensionless-shebang detection path. The workflow has its own source detection. Do not assume every conceivable shebang spelling is discovered; use the repository-supported hook entry form and verify the selected file list. New untracked examples are not automatically part of that list.
| Stage | Actual runner behavior | Evidence it does not supply |
|---|---|---|
| Syntax | Batched luac -p. | Runtime behavior or API correctness. |
| Dictionary | Dictionary generator with --check. | Full prose/security correctness. |
| Selene | Repository selene.toml and libmemalloc-lua standard. | Every rule in the Lua guides. |
| StyLua | --check and repository stylua.toml. | Semantic correctness or ownership. |
| LuaLS | Workspace check with repository config, level Warning. | Runtime enforcement of annotations. |
The dictionary command is lua tools/lint/spell/dictionary/generate.lua --check. The runner invokes Selene and StyLua in bounded batches and LuaLS across the workspace. The runner and workflow, rather than this descriptive table, remain executable authority. EditorConfig and Markdown checks are separate gates. No alternate linter configuration is supplied.
Run the Lua checker and the full local check driver in an indexed checkout. Retain commands, tool identities, exit status, and logs under .cache/logs/checks/. Keep failures visible. A formatter result does not prove SESE, naming, ownership, complexity, or runtime correctness.
Extract complete documentation examples into .cache/tests/lua-examples/ before executing them. Test them with the selected runtime and retain their results; contextual and negative fragments are not standalone test programs. A local Lua 5.4 run does not qualify the locked Lua 5.5 runtime or a LuaJIT profile.
Keep the Lua guides in docs/standards/lua/. No .editorconfig exemption or Lua configuration edit is required by the document layout. In a disposable checkout, extract and lint the complete examples with the pinned tools and review contextual snippets in their owning harness. Run the canonical repository checks and the documentation gates before merge.
Existing Lua, including the retrieved runner, contains snake_case function APIs, early returns and trusted bootstrap loading. The new policy is not a statement that this existing code already conforms. Track naming/SESE migration, preserve supported APIs at adapters and test each behavioral change. Add a dedicated SESE/naming/dependency checker only through a separate reviewed change; the documents do not pretend such automation is already installed.