 |
libmemalloc 0.0.0-alpha
The Magic of Memory Transmutation
|
|
libmemalloc 0.0.0-alpha
The Magic of Memory Transmutation
|
Use this catalogue when reviewing a failure path, designing a regression test or challenging an assumption behind a Lua implementation. It covers values, tables, text, numeric domains, normal control flow, exceptions, resources, modules, authority and performance evidence.
Each scenario links to normative prevention controls in the Lua standard and modulearchitecture. The catalogue adds no competing normative rules. The governance and example policy apply throughout.
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.
A failure scenario states a trigger, mechanism, affected contract and verification design. It is not proof that every occurrence of a token is a vulnerability. Distinguish a language-semantic error, a project-policy violation and a risk that depends on a trust boundary or execution profile.
The Lua 5.5 manual is the semantic reference for the locked execution target; the Lua 5.4 manual is a supplementary source for the configured source grammar. Repository configuration and the toolchain snapshot in the standard bound what is actually supported. Each entry explains the Lua mechanism, prevention rule and observable failure. Native extensions also need explicit memory, ABI and resource contracts at their Lua boundary.
Tests should inspect state and resource obligations after failure, not only the returned value. Use bounded, deterministic fault injection. Do not execute shell-injection, deletion, arbitrary bytecode or uncontrolled exhaustion fragments. Example snippets are contextual unless explicitly named as a complete program. A detected failure needs its applicability and root cause reviewed; passing a test does not establish an unmeasured global property.
Class: FAILURE_SCENARIO. This entry adds no independent implementation requirement.
Trigger: A status-first operation returns zero on success, and the caller uses it directly as an if condition.
Failure mechanism: Only nil and false are false values in Lua. Zero and an empty string are true values, unlike common C condition idioms.
Prevention controls: LSTYLE-029, LSTYLE-043, LSTYLE-044.
Verification design: Exercise zero, negative status, nil, false and an unexpected status type; assert the selected branch.
Source context: Lua 5.5 reference manual.
Noncompliant fragment or assumption (do not execute):
if operation_status then -- Incorrectly interpreted as failure or success by a C-style assumption. end
Contextual Lua fragment (requires its enclosing contract):
local has_succeeded = operation_status == 0
Class: FAILURE_SCENARIO. This entry adds no independent implementation requirement.
Trigger: A Boolean configuration uses option or default_value to apply a default.
Failure mechanism: The or expression selects its right operand for both nil and false. A deliberate false setting can disappear.
Prevention controls: LSTYLE-029, LSTYLE-030.
Verification design: Pass nil, false and true separately and verify only nil selects the default.
Source context: Lua 5.5 reference manual.
Noncompliant fragment or assumption (do not execute):
local is_enabled = config.is_enabled or true
Contextual Lua fragment (requires its enclosing contract):
local is_enabled = config.is_enabled if is_enabled == nil then is_enabled = true end
Class: FAILURE_SCENARIO. This entry adds no independent implementation requirement.
Trigger: The selected true-branch result can be false or nil.
Failure mechanism: condition and left or right then chooses right even when condition was true. Logical operators return operands, not normalized Boolean values.
Prevention controls: LSTYLE-030.
Verification design: Use false, nil, zero and an empty string as candidate branch results.
Source context: Lua 5.5 reference manual.
Noncompliant fragment or assumption (do not execute):
local chosen = is_selected and false or true
Contextual Lua fragment (requires its enclosing contract):
local chosen = true if is_selected then chosen = false end
Class: FAILURE_SCENARIO. This entry adds no independent implementation requirement.
Trigger: An assignment omits local inside an ordinary module.
Failure mechanism: The assignment targets the applicable environment rather than a new lexical local and can couple otherwise independent callers.
Prevention controls: LSTYLE-008, LSTYLE-018, LMOD-009.
Verification design: Load the module in an isolated fixture and compare environment keys before and after its operations.
Source context: Lua 5.5 reference manual.
Noncompliant fragment or assumption (do not execute):
current_packet = packet
Contextual Lua fragment (requires its enclosing contract):
local current_packet = packet
Class: FAILURE_SCENARIO. This entry adds no independent implementation requirement.
Trigger: A new local uses the same name as an outer variable or function.
Failure mechanism: The new local scope starts after its declaration; the initializer can refer to an outer binding and make intent unclear.
Prevention controls: LSTYLE-017, LSTYLE-018.
Verification design: Review shadow warnings and add tests with different outer and inner values.
Source context: Lua 5.5 reference manual.
Noncompliant fragment or assumption (do not execute):
local value = value or 10
Contextual Lua fragment (requires its enclosing contract):
local configured_value = input_value if configured_value == nil then configured_value = 10 end
Class: FAILURE_SCENARIO. This entry adds no independent implementation requirement.
Trigger: A caller adds parentheses around a function call in a multi-result assignment.
Failure mechanism: An expression in parentheses is adjusted to one result. The status may survive while the payload disappears.
Prevention controls: LSTYLE-035, LSTYLE-043.
Verification design: Test success with payload, failure with nil, and a valid false payload.
Source context: Lua 5.5 reference manual.
Noncompliant fragment or assumption (do not execute):
local ret, payload = (codec.CODEC_decode(input))
Contextual Lua fragment (requires its enclosing contract):
local ret, payload = codec.CODEC_decode(input)
Class: FAILURE_SCENARIO. This entry adds no independent implementation requirement.
Trigger: Results or varargs are stored in a table and later recovered with # or an implicit unpack range.
Failure mechanism: Nil entries are absent keys and the length of a non-sequence does not preserve the original argument count.
Prevention controls: LSTYLE-031, LSTYLE-035.
Verification design: Round-trip tuples containing middle nil values and a trailing nil with a separately recorded count.
Source context: Lua 5.5 reference manual.
Noncompliant fragment or assumption (do not execute):
local values = { first, nil, third }
local count = #values
Contextual Lua fragment (requires its enclosing contract):
local values = { first, nil, third } local value_count = 3
Class: FAILURE_SCENARIO. This entry adds no independent implementation requirement.
Trigger: A caller changes dot invocation to colon or the reverse without changing the contract.
Failure mechanism: Colon syntax supplies the receiver as the first argument; a positional callback can receive shifted arguments.
Prevention controls: LSTYLE-022, LSTYLE-065, LMOD-012.
Verification design: Call through the documented shape and use a mock that validates every argument identity.
Source context: Lua 5.5 reference manual.
Noncompliant fragment or assumption (do not execute):
sink:SINK_write(context, payload) -- Wrong for a two-argument function port.
Contextual Lua fragment (requires its enclosing contract):
local ret = sink.SINK_write(context, payload)
Class: FAILURE_SCENARIO. This entry adds no independent implementation requirement.
Trigger: A table contains holes, non-sequential integer keys or map keys.
Failure mechanism: # identifies a border according to the language rules; it is not a general key counter. Different valid borders must not be treated as corruption.
Prevention controls: LSTYLE-031.
Verification design: Test dense sequences, an early hole and a map. Do not assert one specific # result for a table with multiple borders.
Source context: Lua 5.5 reference manual.
Noncompliant fragment or assumption (do not execute):
local items = { [1] = "a", [3] = "c" }
local item_count = #items
Contextual Lua fragment (requires its enclosing contract):
local items = { "a", "b", "c" } local item_count = 3
Class: FAILURE_SCENARIO. This entry adds no independent implementation requirement.
Trigger: An intended sequence contains a nil entry before later valid elements.
Failure mechanism: ipairs stops at the first absent integer entry. Later data can be silently omitted from validation or output.
Prevention controls: LSTYLE-031, LSTYLE-032.
Verification design: Place a hole at the first, middle and last positions and verify the declared sequence contract rejects it or uses explicit indexing.
Source context: Lua 5.5 reference manual.
Noncompliant fragment or assumption (do not execute):
for _, value in ipairs(sparse_values) do -- Later values can be missed. end
Contextual Lua fragment (requires its enclosing contract):
for value_idx = 1, value_count do local value = values[value_idx] -- Validate presence according to the explicit sequence contract. end
Class: FAILURE_SCENARIO. This entry adds no independent implementation requirement.
Trigger: A serializer, snapshot or test expects pairs to emit keys in a stable order.
Failure mechanism: Table traversal order is not a portable sorting contract. Stable output needs an explicit ordering scheme.
Prevention controls: LSTYLE-032, LSTYLE-042.
Verification design: Create equal maps through different insertion histories and compare canonical output.
Source context: Lua 5.5 reference manual.
Noncompliant fragment or assumption (do not execute):
for key, value in pairs(record) do -- Appending here does not establish canonical order. end
Contextual Lua fragment (requires its enclosing contract):
local ordered_keys = { "id", "length", "state" } for _, key in ipairs(ordered_keys) do local value = record[key] -- Encode this field through the boundary codec. end
Class: FAILURE_SCENARIO. This entry adds no independent implementation requirement.
Trigger: A loop adds previously absent keys while traversing the same table.
Failure mechanism: This is outside the traversal guarantees normally relied on for next/pairs. Even allowed value updates or clearing keys need an explicit algorithm.
Prevention controls: LSTYLE-032.
Verification design: Test insertion, deletion and value-only updates separately using the documented algorithm.
Source context: Lua 5.5 reference manual.
Noncompliant fragment or assumption (do not execute):
for key in pairs(record) do record[key .. "_copy"] = record[key] end
Contextual Lua fragment (requires its enclosing contract):
local updates = {} for key, value in pairs(record) do updates[key .. "_copy"] = value end
Class: FAILURE_SCENARIO. This entry adds no independent implementation requirement.
Trigger: A module stores a caller-owned configuration table directly and expects an immutable snapshot.
Failure mechanism: Both references identify the same table; later caller mutation changes module behavior.
Prevention controls: LSTYLE-033, LMOD-010.
Verification design: Mutate the input after construction and check whether behavior matches the published retention contract.
Source context: Lua 5.5 reference manual.
Noncompliant fragment or assumption (do not execute):
local private_config = caller_config
Contextual Lua fragment (requires its enclosing contract):
local private_config = { capacity_bytes = caller_config.capacity_bytes, is_enabled = caller_config.is_enabled, }
Class: FAILURE_SCENARIO. This entry adds no independent implementation requirement.
Trigger: Top-level fields are copied but one field is a mutable nested table.
Failure mechanism: The copied field still references the same nested object. Recursive copying also needs cycle, depth and identity rules.
Prevention controls: LSTYLE-033, LSTYLE-050, LMOD-010.
Verification design: Mutate a nested field, introduce a shared subtree and test the selected copy policy.
Source context: Lua 5.5 reference manual.
Noncompliant fragment or assumption (do not execute):
local snapshot = { limits = caller_config.limits }
Contextual Lua fragment (requires its enclosing contract):
local snapshot = { max_payload_bytes = caller_config.limits.max_payload_bytes, }
Class: FAILURE_SCENARIO. This entry adds no independent implementation requirement.
Trigger: A table is named as a constant or assigned to a non-reassignable local.
Failure mechanism: Naming does not prevent field mutation; a binding restriction is not deep immutability.
Prevention controls: LSTYLE-010, LSTYLE-034, LSTYLE-052.
Verification design: Review all aliases and mutation sites and verify the public API does not leak the mutable policy table.
Source context: Lua 5.5 reference manual.
Noncompliant fragment or assumption (do not execute):
local LIMITS = { count = 4 }
LIMITS.count = 100
Contextual Lua fragment (requires its enclosing contract):
local LIMITS_COUNT = 4
Class: FAILURE_SCENARIO. This entry adds no independent implementation requirement.
Trigger: A boundary accepts an arbitrary table with metatable-controlled field access.
Failure mechanism: Indexing, length, conversion or other operations can execute metamethod code, throw or mutate state during what appears to be a pure check.
Prevention controls: LSTYLE-028, LSTYLE-052, LSTYLE-057.
Verification design: Use metatables that count or reject field access; enforce the declared plain-record or adapter contract.
Source context: Lua 5.5 reference manual.
Noncompliant fragment or assumption (do not execute):
local capacity_bytes = request.capacity_bytes
Contextual Lua fragment (requires its enclosing contract):
local is_plain_record = type(request) == "table" and getmetatable(request) == nil
Class: FAILURE_SCENARIO. This entry adds no independent implementation requirement.
Trigger: A text operation uses # or string.sub indices as if they were Unicode character positions.
Failure mechanism: Lua strings hold bytes. A multibyte character can be split or counted as several bytes.
Prevention controls: LSTYLE-036.
Verification design: Test ASCII, multibyte UTF-8, embedded NUL and malformed byte sequences with the selected contract.
Source context: Lua 5.5 reference manual.
Noncompliant fragment or assumption (do not execute):
local first_character = string.sub(text, 1, 1)
Contextual Lua fragment (requires its enclosing contract):
local text_size_bytes = #text local codepoint_count, invalid_byte_idx = utf8.len(text)
Class: FAILURE_SCENARIO. This entry adds no independent implementation requirement.
Trigger: A literal search uses string.find without plain=true.
Failure mechanism: Pattern metacharacters change the search and malformed patterns may raise errors.
Prevention controls: LSTYLE-037, LSTYLE-046.
Verification design: Search for literal dots, brackets, percent signs and an empty needle according to the API contract.
Source context: Lua 5.5 reference manual.
Noncompliant fragment or assumption (do not execute):
local start_idx = string.find(haystack, needle)
Contextual Lua fragment (requires its enclosing contract):
local start_idx = string.find(haystack, needle, 1, true)
Class: FAILURE_SCENARIO. This entry adds no independent implementation requirement.
Trigger: External replacement data is used as the replacement template in gsub.
Failure mechanism: Percent sequences in a replacement string have special meaning. Literal external data needs a reviewed replacement strategy.
Prevention controls: LSTYLE-038.
Verification design: Exercise percent characters and capture-like sequences and assert exact output bytes.
Source context: Lua 5.5 reference manual.
Noncompliant fragment or assumption (do not execute):
local output = string.gsub(input, pattern, replacement)
Contextual source fragment (requires an enclosing scope):
Use a validated replacement callback that returns literal data, or a reviewed escaping adapter with exact-byte tests.
Class: FAILURE_SCENARIO. This entry adds no independent implementation requirement.
Trigger: A diagnostic or serializer treats externally supplied text as a string.format template.
Failure mechanism: Format directives can change required arguments and trigger errors or excessive output.
Prevention controls: LSTYLE-038, LSTYLE-050, LSTYLE-061.
Verification design: Test percent sequences, unsupported directives and oversized field widths without allocating uncontrolled output.
Source context: Lua 5.5 reference manual.
Noncompliant fragment or assumption (do not execute):
local output = string.format(user_template, value)
Contextual Lua fragment (requires its enclosing contract):
local output = string.format("value=%s", validated_text)
Class: FAILURE_SCENARIO. This entry adds no independent implementation requirement.
Trigger: A numeric boundary silently applies tonumber or arithmetic coercion to arbitrary input.
Failure mechanism: Conversion can accept representations outside the protocol grammar and does not establish integer, finite or bounded domains.
Prevention controls: LSTYLE-028, LSTYLE-039.
Verification design: Exercise whitespace, fractions, exponent notation, empty strings and non-finite values under the stated input grammar.
Source context: Lua 5.5 reference manual.
Noncompliant fragment or assumption (do not execute):
local size_bytes = tonumber(input) or 0
Contextual Lua fragment (requires its enclosing contract):
local is_valid = type(value) == "number" and value == value and value >= 0 and value <= 4096 and value % 1 == 0
Class: FAILURE_SCENARIO. This entry adds no independent implementation requirement.
Trigger: A check only compares a number against a lower bound or only checks its type.
Failure mechanism: A number can be non-finite in the selected numeric model. NaN is unequal to itself and ordinary comparisons do not behave like a total order.
Prevention controls: LSTYLE-039.
Verification design: Include NaN, both infinities, negative zero and boundary finite values where the profile supports them.
Source context: Lua 5.5 reference manual.
Noncompliant fragment or assumption (do not execute):
local is_valid = type(value) == "number"
Contextual Lua fragment (requires its enclosing contract):
local is_valid = type(value) == "number" and value == value and value >= 0 and value <= 4096
Class: FAILURE_SCENARIO. This entry adds no independent implementation requirement.
Trigger: A large external identifier is represented through a floating-point conversion.
Failure mechanism: The representable exact-integer range depends on the numeric model. Distinct external identifiers can collapse to one numeric value.
Prevention controls: LSTYLE-039, LSTYLE-042, LSTYLE-062.
Verification design: Round-trip values around the profile exactness limit using the specified external representation.
Source context: Lua 5.5 reference manual.
Noncompliant fragment or assumption (do not execute):
local external_id = tonumber(decimal_identifier)
Contextual source fragment (requires an enclosing scope):
Keep identifiers as validated strings when numeric operations are not required; otherwise enforce the selected exact integer domain.
Class: FAILURE_SCENARIO. This entry adds no independent implementation requirement.
Trigger: The code computes offset+length before proving both operands fit the accepted domain.
Failure mechanism: Integer wrap or a loss of numeric precision can make the later bound comparison meaningless for the intended contract.
Prevention controls: LSTYLE-039, LSTYLE-040.
Verification design: Test zero, full capacity, near-capacity inputs and out-of-domain values before computing the sum.
Source context: Lua 5.5 reference manual.
Noncompliant fragment or assumption (do not execute):
local fits = offset_bytes + length_bytes <= capacity_bytes
Contextual Lua fragment (requires its enclosing contract):
local fits = offset_bytes >= 0 and offset_bytes <= capacity_bytes and length_bytes >= 0 and length_bytes <= capacity_bytes - offset_bytes
Class: FAILURE_SCENARIO. This entry adds no independent implementation requirement.
Trigger: A Lua algorithm assumes C truncating division, C remainder signs or a fixed-width C bit-shift model.
Failure mechanism: Lua operators have their own division, modulo, integer and bitwise semantics; the selected runtime manual is authoritative.
Prevention controls: LSTYLE-004, LSTYLE-039, LSTYLE-041.
Verification design: Test negative operands, zero divisors and shift boundaries under each claimed runtime.
Source context: Lua 5.5 reference manual.
Noncompliant fragment or assumption (do not execute):
Assume -3 // 2 has the same truncation contract as C integer division.
Contextual source fragment (requires an enclosing scope):
State quotient/remainder conventions and test negative operands before using the result as an index or protocol field.
Class: FAILURE_SCENARIO. This entry adds no independent implementation requirement.
Trigger: A wire format inherits native sizes, alignment or byte order from a packing operation or native binding.
Failure mechanism: The data ceases to have a stable cross-platform representation. Packing APIs also need checker-profile support.
Prevention controls: LSTYLE-042, LSTYLE-062.
Verification design: Compare known byte vectors on supported targets and reject truncation, trailing data and length mismatch.
Source context: Lua 5.5 reference manual.
Noncompliant fragment or assumption (do not execute):
Serialize the native in-memory table or C object layout directly.
Contextual source fragment (requires an enclosing scope):
Use an explicit byte order, field widths, encoding and total byte count; keep the codec at the serialization boundary.
Class: FAILURE_SCENARIO. This entry adds no independent implementation requirement.
Trigger: A function acquires a resource and returns directly from an intermediate failure branch.
Failure mechanism: The function no longer has the common cleanup point required by project SESE policy.
Prevention controls: LSTYLE-023, LSTYLE-047.
Verification design: Fail each step after acquisition and verify every acquired resource receives exactly one release attempt.
Source context: Lua 5.5 reference manual.
Noncompliant fragment or assumption (do not execute):
if has_failed then return ERROR_CODE end
Contextual source fragment (requires an enclosing scope):
ret = ERROR_CODE goto function_output
Class: FAILURE_SCENARIO. This entry adds no independent implementation requirement.
Trigger: A forward goto crosses a local declaration and targets a label where that local is still in scope.
Failure mechanism: Lua rejects a goto that enters the scope of a local variable. Copying a C cleanup shape mechanically can create a syntax error.
Prevention controls: LSTYLE-017, LSTYLE-024.
Verification design: Compile the complete enclosing function, not a disconnected branch fragment.
Source context: Lua 5.5 reference manual.
Noncompliant fragment or assumption (do not execute):
goto function_output local result = 1 ::function_output:: return result
Contextual Lua fragment (requires its enclosing contract):
local ret = 0 local result = nil -- All forward exits occur after these declarations. ::function_output:: return ret, result
Class: FAILURE_SCENARIO. This entry adds no independent implementation requirement.
Trigger: An operation between acquisition and the label raises an unprotected Lua error.
Failure mechanism: An error unwinds control rather than executing a goto to the label. Source-level normal SESE alone cannot guarantee cleanup.
Prevention controls: LSTYLE-023, LSTYLE-046, LSTYLE-047.
Verification design: Inject exceptions at every fallible callback and verify cleanup through the protection owner.
Source context: Lua 5.5 reference manual.
Noncompliant fragment or assumption (do not execute):
local ret = port.WORK_run(context) -- Assuming every raised error reaches function_output is incorrect.
Contextual Lua fragment (requires its enclosing contract):
local has_completed, operation_ret = pcall(port.WORK_run, context)
Class: FAILURE_SCENARIO. This entry adds no independent implementation requirement.
Trigger: The protected function returns a negative status without raising an error.
Failure mechanism: pcall returns true because execution completed normally; the operation can still have failed.
Prevention controls: LSTYLE-043, LSTYLE-044, LSTYLE-046.
Verification design: Return zero and a negative status from the same callback, then throw an error in a separate case.
Source context: Lua 5.5 reference manual.
Noncompliant fragment or assumption (do not execute):
local is_success = pcall(port.WORK_run, context)
Contextual Lua fragment (requires its enclosing contract):
local has_completed, operation_ret = pcall(port.WORK_run, context) local has_succeeded = has_completed and operation_ret == 0
Class: FAILURE_SCENARIO. This entry adds no independent implementation requirement.
Trigger: A catch boundary receives an arbitrary table or userdata and formats it with tostring.
Failure mechanism: A conversion metamethod can raise another error or expose unintended information while handling the first error.
Prevention controls: LSTYLE-046, LSTYLE-061.
Verification design: Throw a table with a failing __tostring handler and verify a bounded generic diagnostic is used.
Source context: Lua 5.5 reference manual.
Noncompliant fragment or assumption (do not execute):
local diagnostic = tostring(error_value)
Contextual Lua fragment (requires its enclosing contract):
local diagnostic = "callback failed" if type(error_value) == "string" then diagnostic = string.sub(error_value, 1, 160) end
Class: FAILURE_SCENARIO. This entry adds no independent implementation requirement.
Trigger: The cleanup status is assigned directly to ret after an earlier failure.
Failure mechanism: The original operation failure can disappear or be replaced by an unrelated close result.
Prevention controls: LSTYLE-047, LMOD-023.
Verification design: Combine a failed operation with successful close and with failed close; assert the precedence policy.
Source context: Lua 5.5 reference manual.
Noncompliant fragment or assumption (do not execute):
ret = resource.RESOURCE_close(context, handle)
Contextual Lua fragment (requires its enclosing contract):
if ret == 0 and close_ret ~= 0 then ret = close_ret end
Class: FAILURE_SCENARIO. This entry adds no independent implementation requirement.
Trigger: A partially built object or stale payload is returned alongside a failure status.
Failure mechanism: Callers can accidentally observe invalid state or treat old data as a new result.
Prevention controls: LSTYLE-035, LSTYLE-043, LSTYLE-049.
Verification design: Fail before and after each mutation and verify output=nil on every failed return.
Source context: Lua 5.5 reference manual.
Noncompliant fragment or assumption (do not execute):
return ret, partially_initialized_object
Contextual Lua fragment (requires its enclosing contract):
if ret ~= 0 then output = nil end -- The single final return follows the shared output label.
Class: FAILURE_SCENARIO. This entry adds no independent implementation requirement.
Trigger: An implementation puts required behavior inside assert and expects a release build to remove it.
Failure mechanism: Lua assert is an ordinary runtime function call; the C debug/release assertion policy does not transfer automatically.
Prevention controls: LSTYLE-045.
Verification design: Run the same invalid external inputs under the deployment invocation and verify explicit status handling.
Source context: Lua 5.5 reference manual.
Noncompliant fragment or assumption (do not execute):
assert(port.WRITE_commit(context))
Contextual Lua fragment (requires its enclosing contract):
local ret = port.WRITE_commit(context) if ret ~= 0 then -- Propagate through the operation common output. end
Class: FAILURE_SCENARIO. This entry adds no independent implementation requirement.
Trigger: Cleanup indiscriminately closes every handle referenced by a module.
Failure mechanism: Reachability does not grant ownership, and another component may still own and need that handle.
Prevention controls: LSTYLE-047, LMOD-018.
Verification design: Give the module an owner-marked borrowed mock and verify zero close calls.
Source context: Lua 5.5 reference manual.
Noncompliant fragment or assumption (do not execute):
borrowed_file:close()
Contextual source fragment (requires an enclosing scope):
The contract records OWNED or BORROWED. Only the owner closes a borrowed resource; an explicit transfer changes ownership on success.
Class: FAILURE_SCENARIO. This entry adds no independent implementation requirement.
Trigger: A file or native resource is left reachable or abandoned until collection happens.
Failure mechanism: Resource availability and semantic completion cannot depend on an assumed collection schedule.
Prevention controls: LSTYLE-047, LSTYLE-056, LMOD-024.
Verification design: Repeat the lifecycle without forcing GC and count open handles and explicit releases.
Source context: Lua 5.5 reference manual.
Noncompliant fragment or assumption (do not execute):
file = nil
collectgarbage("collect") -- Used as the normal close protocol.
Contextual Lua fragment (requires its enclosing contract):
local close_ret = resource.RESOURCE_close(context, handle)
Class: FAILURE_SCENARIO. This entry adds no independent implementation requirement.
Trigger: Code declares local resource <close> and later assigns nil to it as if transferring ordinary ownership.
Failure mechanism: A to-be-closed variable has restrictions different from an ordinary mutable local. Manual cleanup and the close metamethod also risk duplicate release.
Prevention controls: LSTYLE-048, LMOD-024.
Verification design: Compile and test only within the explicitly qualified close-enabled profile; test normal and error unwinding.
Source context: Lua 5.5 reference manual.
Noncompliant fragment or assumption (do not execute):
local resource <close> = acquire() resource = nil
Contextual source fragment (requires an enclosing scope):
Choose manual owned-handle cleanup or a qualified to-be-closed scope. Do not mix both protocols for the same resource.
Class: FAILURE_SCENARIO. This entry adds no independent implementation requirement.
Trigger: A synchronous port uses pcall and then assumes the callback cannot suspend.
Failure mechanism: Protection against errors and permission to yield are separate aspects of the runtime and host API.
Prevention controls: LSTYLE-054, LMOD-025.
Verification design: Use a callback that attempts to yield in each supported calling context and verify the enforced contract.
Source context: Lua 5.5 reference manual.
Noncompliant fragment or assumption (do not execute):
pcall(callback, context) -- Assumed to enforce a non-yielding boundary.
Contextual source fragment (requires an enclosing scope):
Document and enforce the yield policy at the host/adapter; test it separately from exception handling.
Class: FAILURE_SCENARIO. This entry adds no independent implementation requirement.
Trigger: A coroutine.resume result is processed as the final operation result without checking lifecycle state.
Failure mechanism: A successful resume can represent suspension rather than completion. Resources may still be in use.
Prevention controls: LSTYLE-054, LMOD-022.
Verification design: Exercise created, suspended, completed and failed coroutines and all supported shutdown transitions.
Source context: Lua 5.5 reference manual.
Noncompliant fragment or assumption (do not execute):
local has_succeeded, result = coroutine.resume(worker) -- The coroutine may only have yielded.
Contextual Lua fragment (requires its enclosing contract):
local worker_state = coroutine.status(worker) -- Interpret resume values under the operation state machine.
Class: FAILURE_SCENARIO. This entry adds no independent implementation requirement.
Trigger: An operation marks the instance busy and the callback raises before busy is cleared.
Failure mechanism: All later calls can fail permanently unless error handling converges on state restoration.
Prevention controls: LSTYLE-046, LSTYLE-055, LMOD-016.
Verification design: Throw from the callback, then issue a valid operation and verify the instance is usable.
Source context: Lua 5.5 reference manual.
Noncompliant fragment or assumption (do not execute):
is_busy = true callback(context) is_busy = false
Contextual Lua fragment (requires its enclosing contract):
is_busy = true has_completed, callback_ret = pcall(callback, context) is_busy = false
Class: FAILURE_SCENARIO. This entry adds no independent implementation requirement.
Trigger: Native threads can enter a Lua state or object concurrently.
Failure mechanism: An ordinary Lua field or upvalue does not establish a host synchronization or memory-ordering protocol.
Prevention controls: LSTYLE-055, LSTYLE-062, LMOD-026.
Verification design: Review the host state-access discipline and use target-appropriate native concurrency tests.
Source context: Lua 5.5 reference manual.
Noncompliant fragment or assumption (do not execute):
if not is_busy then is_busy = true -- Assumed safe between native threads. end
Contextual source fragment (requires an enclosing scope):
The host owns exclusive state access or a qualified synchronization protocol; the Lua busy flag only detects synchronous reentry.
Class: FAILURE_SCENARIO. This entry adds no independent implementation requirement.
Trigger: A callback closure keeps a provider wrapper reachable after provider shutdown.
Failure mechanism: The wrapper remains in memory but the external resource is no longer semantically valid.
Prevention controls: LSTYLE-053, LMOD-017, LMOD-022.
Verification design: Retain callbacks across provider close and verify shutdown ordering prevents their invocation.
Source context: Lua 5.5 reference manual.
Noncompliant fragment or assumption (do not execute):
Keep a callback forever because its captured table cannot be collected.
Contextual source fragment (requires an enclosing scope):
Stop and drain the consumer, release callbacks, then close the provider.
Class: FAILURE_SCENARIO. This entry adds no independent implementation requirement.
Trigger: The module export table carries mutable per-request or per-client state.
Failure mechanism: require normally reuses the loaded module value, so independent users can share the same mutable state.
Prevention controls: LSTYLE-008, LMOD-009.
Verification design: Create two clients through the supported API and interleave distinct workloads.
Source context: Lua 5.5 reference manual.
Noncompliant fragment or assumption (do not execute):
module.current_request = request
Contextual Lua fragment (requires its enclosing contract):
local instance_state = { current_request = nil } -- Created separately for each public instance.
Class: FAILURE_SCENARIO. This entry adds no independent implementation requirement.
Trigger: A contract file imports an implementation or a peer directly requires another peer.
Failure mechanism: The apparent interface dependency becomes a runtime implementation dependency and violates project architecture.
Prevention controls: LMOD-003, LMOD-005, LMOD-031.
Verification design: Remove peer implementations from the isolated test tree and load the contract and consumer.
Source context: Lua 5.5 reference manual.
Noncompliant fragment or assumption (do not execute):
local sink = require("peer_storage") -- Inside the reusable consumer.
Contextual source fragment (requires an enclosing scope):
The composition root injects a consumer-owned sink function and context.
Class: FAILURE_SCENARIO. This entry adds no independent implementation requirement.
Trigger: An application clears a cache entry to reset or replace a module in use.
Failure mechanism: Existing tables, closures, native references and suspended work may still refer to the old implementation.
Prevention controls: LSTYLE-058, LMOD-029.
Verification design: Retain an old instance and callback while attempting reload; verify the explicit migration/quiescence protocol.
Source context: Lua 5.5 reference manual.
Noncompliant fragment or assumption (do not execute):
package.loaded["provider"] = nil
Contextual source fragment (requires an enclosing scope):
Reload is a separately reviewed lifecycle, not a normal reset operation.
Class: FAILURE_SCENARIO. This entry adds no independent implementation requirement.
Trigger: Startup resolves trusted code through an attacker-controlled current directory or path.
Failure mechanism: The logical module name can select a different implementation with the program authority.
Prevention controls: LSTYLE-058, LMOD-028.
Verification design: Start from a disposable unrelated directory with a harmless colliding module and verify it cannot be selected.
Source context: Lua 5.5 reference manual.
Noncompliant fragment or assumption (do not execute):
package.path = user_directory .. "/?.lua;" .. package.path
Contextual source fragment (requires an enclosing scope):
Resolve a verified root and use approved module names and loading paths.
Class: FAILURE_SCENARIO. This entry adds no independent implementation requirement.
Trigger: An input file is loaded and executed to recover a configuration table.
Failure mechanism: Returning a table does not make the preceding code non-executable or limit its authority and cost.
Prevention controls: LSTYLE-057, LSTYLE-060, LBAN-001.
Verification design: Use a non-executable data parser and test schema, byte, element and depth limits.
Source context: Lua 5.5 reference manual.
Noncompliant fragment or assumption (do not execute):
local config = dofile(user_selected_path)
Contextual source fragment (requires an enclosing scope):
Decode bounded data and validate the resulting plain record.
Class: FAILURE_SCENARIO. This entry adds no independent implementation requirement.
Trigger: A program concatenates paths, branch names or payload text into a command string.
Failure mechanism: The downstream shell may interpret metacharacters, expansion and quoting differently from the caller intent.
Prevention controls: LSTYLE-059, LBAN-006, LMOD-027.
Verification design: Use harmless arguments containing spaces, quotes, newlines and metacharacters; verify exact argv in a mock.
Source context: Lua 5.5 reference manual.
Noncompliant fragment or assumption (do not execute):
os.execute("tool " .. user_value)
Contextual Lua fragment (requires its enclosing contract):
local ret = process.PROCESS_run({ "tool", user_value })
Class: FAILURE_SCENARIO. This entry adds no independent implementation requirement.
Trigger: An input path passes a string prefix check before privileged file access.
Failure mechanism: Traversal, platform path rules, symbolic links and races can make the resolved object different from the checked string.
Prevention controls: LSTYLE-060, LMOD-027.
Verification design: Test traversal and symlink behavior through the actual platform adapter in a disposable fixture.
Source context: Lua 5.5 reference manual.
Noncompliant fragment or assumption (do not execute):
local is_allowed = string.sub(path, 1, #root) == root
Contextual source fragment (requires an enclosing scope):
Use the approved filesystem boundary and its resolution/authority contract, not a generic Lua prefix helper.
Class: FAILURE_SCENARIO. This entry adds no independent implementation requirement.
Trigger: A diagnostic includes credentials, or code assigns nil to a secret string and calls this secure erasure.
Failure mechanism: Copies, immutable strings, logs and runtime-managed storage can retain the data beyond that assignment.
Prevention controls: LSTYLE-061.
Verification design: Inspect diagnostics and fault paths with synthetic secrets and verify redaction without claiming memory erasure.
Source context: Lua 5.5 reference manual.
Noncompliant fragment or assumption (do not execute):
print("token=" .. token)
token = nil -- Incorrectly claimed as secure zeroization.
Contextual source fragment (requires an enclosing scope):
Emit a bounded event identifier; keep secret-handling guarantees in the qualified security boundary.
Class: FAILURE_SCENARIO. This entry adds no independent implementation requirement.
Trigger: A source passes one runtime parser or linter and the entire repository profile is declared supported.
Failure mechanism: The runtime, Lua54 formatter grammar, custom Selene API catalogue and LuaLS model are separate constraints.
Prevention controls: LSTYLE-001, LSTYLE-064, LSTYLE-066.
Verification design: Record each configured tool stage independently and fail when a mandatory tool is missing.
Source context: Repository runner; Toolchain lock.
Noncompliant fragment or assumption (do not execute):
luac -p passed; therefore every repository check passed.
Contextual source fragment (requires an enclosing scope):
parser + dictionary + Selene + StyLua + LuaLS + required project tests
Class: FAILURE_SCENARIO. This entry adds no independent implementation requirement.
Trigger: Only the three Markdown documents are added, and their Lua examples are never extracted.
Failure mechanism: The current Lua runner does not extract Markdown fences, so its result supplies no direct example execution evidence.
Prevention controls: LSTYLE-005, LSTYLE-067.
Verification design: Extract named complete examples, check syntax, run tests and report actual tool versions.
Source context: Repository runner.
Noncompliant fragment or assumption (do not execute):
The Markdown check passed, therefore all embedded programs were tested.
Contextual source fragment (requires an enclosing scope):
Documentation validation and extracted Lua program validation are separate records.
Class: FAILURE_SCENARIO. This entry adds no independent implementation requirement.
Trigger: An experiment excludes startup, validation, collection or cleanup without reporting the exclusion.
Failure mechanism: The measured improvement may only shift necessary work to another phase or increase memory retention.
Prevention controls: LPERF-001, LPERF-003, LPERF-014.
Verification design: Measure a complete lifecycle and report separate cold and steady-state results. For JIT workloads, follow the measurement procedure, record trace behavior and compare with the same runtime in interpreter mode.
Source context: Lua 5.5 reference manual.
Noncompliant fragment or assumption (do not execute):
Disable GC, time only the loop and report universal latency improvement.
Contextual source fragment (requires an enclosing scope):
Measure the public operation and full workload with recorded GC policy.
Class: FAILURE_SCENARIO. This entry adds no independent implementation requirement.
Trigger: A percentile, observed maximum or coverage report is treated as a correctness or worst-case guarantee.
Failure mechanism: Those measurements have finite scope and do not establish untested paths, future scheduling or all admissible inputs.
Prevention controls: LSTYLE-069, LPERF-004.
Verification design: Record samples, estimator, coverage type, denominator and exclusions, then state the limited claim supported.
Source context: Lua 5.5 reference manual.
Noncompliant fragment or assumption (do not execute):
P99 proves the deadline; 100 percent statements proves all paths.
Contextual source fragment (requires an enclosing scope):
Report measured distributions and named coverage metrics separately from safety, correctness and worst-case timing arguments.
Save the next block as semantic_regression.lua and run it with the selected interpreter. It uses only a host test profile. The NaN fixture is a controlled floating-point expression for the selected runtime; it is not an example of unchecked production arithmetic. Table length on a hole-containing table is intentionally not asserted, because a specific border is not the contract under test.
The program checks truthiness, defaults, multiple-result adjustment, aliases, explicit snapshots, literal search, sequence traversal and bounded arithmetic. Assertions are test-runner failures with messages; production external-input handling still uses the normal status path.
Complete named source file:
-- SPDX-License-Identifier: GPL-3.0-only -- Host-only language regressions: no filesystem or native resource effects. local function sample_getPair() local ret = 0 local output = false ::function_output:: return ret, output end local function sample_isCount(value) local ret = false ret = type(value) == "number" and value == value and value >= 0 and value <= 4096 and value % 1 == 0 ::function_output:: return ret end local function sample_fits(offset_bytes, length_bytes, capacity_bytes) local ret = false local is_valid_offset = false local is_valid_length = false local is_valid_capacity = false is_valid_offset = sample_isCount(offset_bytes) is_valid_length = sample_isCount(length_bytes) is_valid_capacity = sample_isCount(capacity_bytes) if not is_valid_offset or not is_valid_length or not is_valid_capacity then goto function_output end ret = offset_bytes <= capacity_bytes and length_bytes <= capacity_bytes - offset_bytes ::function_output:: return ret end local ret, output = sample_getPair() local adjusted_pair = { (sample_getPair()) } local config = { is_enabled = false } local is_enabled = config.is_enabled local shared = { count = 1 } local alias = shared local snapshot = { count = shared.count } local first_idx = string.find("a.b", ".", 1, true) local sparse = { [1] = "first", [3] = "third" } local visited_count = 0 local is_integer = sample_isCount(4096) local is_fraction = sample_isCount(0.5) local is_nan = sample_isCount(0 / 0) local has_room = sample_fits(4095, 1, 4096) local has_overflow = sample_fits(4095, 2, 4096) local has_bad_type = sample_fits("0", 1, 4096) if is_enabled == nil then is_enabled = true end alias.count = 2 for _ in ipairs(sparse) do visited_count = visited_count + 1 end assert(not not 0, "zero is a true value") assert(not not "", "empty string is a true value") assert(is_enabled == false, "a false setting must survive") assert(ret == 0 and output == false, "false payload lost") assert(adjusted_pair[1] == 0, "parenthesized first result changed") assert(adjusted_pair[2] == nil, "parentheses must adjust to one result") assert(shared.count == 2, "assignment must retain the table alias") assert(snapshot.count == 1, "explicit scalar snapshot changed") assert(first_idx == 2, "literal search interpreted a pattern") assert(visited_count == 1, "ipairs must stop at the hole") assert(is_integer and not is_fraction and not is_nan, "count domain failed") assert(has_room and not has_overflow and not has_bad_type, "bounds failed") print("semantic regression: 12 assertions passed")
Save the next block as resource_regression.lua, next to bounded_resource.lua from the standardappendix. The tuple-shaped case fixture has five explicit positions; nil payload entries are not recovered with a length operator. The outer case collection is a dense sequence. Deliberate callback exceptions and invalid status/payload values are controlled negative tests, not approved production callback behavior.
The test verifies the primary status, payload, cleanup status and exact number of close attempts. It includes a valid false payload and combined work/close failure. A close attempt is not a proof that a real failed native close released its resource. These mocks have no real external handles.
For a clean standalone run, the fixture directory must be the current working directory and the selected interpreter must resolve the local module through a controlled package path. The repository runner does not discover these files while they remain embedded in Markdown.
Complete named source file:
-- SPDX-License-Identifier: GPL-3.0-only -- Complete host regression. Deliberate mock exceptions are caught by the API. local resource = require("bounded_resource") local cases = { { "success", 0, "payload", 0, 1 }, { "false_payload", 0, false, 0, 1 }, { "empty_payload", 0, "", 0, 1 }, { "open_fail", -2, nil, 0, 0 }, { "open_throw", -5, nil, 0, 0 }, { "work_fail", -3, nil, 0, 1 }, { "work_throw", -5, nil, 0, 1 }, { "work_bad_status", -5, nil, 0, 1 }, { "work_bad_payload", -5, nil, 0, 1 }, { "close_fail", -4, nil, -4, 1 }, { "close_throw", -5, nil, -5, 1 }, { "both_fail", -3, nil, -4, 1 }, } local case_count = 0 local function mock_open(context) local ret = 0 local handle = nil assert(context.mode ~= "open_throw", "injected open exception") if context.mode == "open_fail" then ret = -2 goto function_output end handle = { owner = context } ::function_output:: return ret, handle end local function mock_work(context, handle) local ret = 0 local output = "payload" assert(handle.owner == context, "unexpected resource owner") assert(context.mode ~= "work_throw", "injected work exception") if context.mode == "work_fail" or context.mode == "both_fail" then ret = -3 elseif context.mode == "work_bad_status" then ret = "invalid" elseif context.mode == "work_bad_payload" then output = {} elseif context.mode == "false_payload" then output = false elseif context.mode == "empty_payload" then output = "" end ::function_output:: return ret, output end local function mock_close(context, handle) local ret = 0 assert(handle.owner == context, "unexpected close owner") context.close_count = context.close_count + 1 assert(context.mode ~= "close_throw", "injected close exception") if context.mode == "close_fail" or context.mode == "both_fail" then ret = -4 end ::function_output:: return ret end local ports = { open_fn = mock_open, work_fn = mock_work, close_fn = mock_close, } for _, case in ipairs(cases) do local context = { mode = case[1], close_count = 0 } local ret, output, cleanup_ret = resource.RESOURCE_run(ports, context) assert(ret == case[2], "wrong primary result: " .. case[1]) assert(output == case[3], "wrong output: " .. case[1]) assert(cleanup_ret == case[4], "wrong cleanup result: " .. case[1]) assert(context.close_count == case[5], "wrong close count: " .. case[1]) case_count = case_count + 1 end assert(case_count == 12, "incomplete resource regression") print("resource regression: 12 cases passed")
Resolve the repository profile from the standard and the checked-in tool configurations. External references explain their own language and tool contracts; repository rules define the adopted subset.
| Source | Contribution | Evidence limit |
|---|---|---|
| Lua manuals | Values, scope, calls, errors and resources. | Not project coding conventions. |
| LuaRocks guide | Readable Lua, scope, style and modules. | Not the libmemalloc public-name or SESE authority. |
| Kong guide | Production implementation and review considerations. | Its runtime/formatting profile differs. |
| Roblox guide | Organization and documentation. | Luau and Roblox facilities are not baseline Lua. |
| Olivine guide | Conventions and testing discussions. | Review legacy constructs before adoption. |
| Hisham module article | Lexical structure and exports. | Not an isolation or security proof. |
| StyLua | Formatting tool behavior. | Repository configuration narrows use. |
| Selene | Static analysis and custom standards. | Catalogue coverage is not runtime support. |
| LuaLS | Type annotations and language analysis. | Comments do not enforce runtime types. |
No claim is made that this is an exhaustive list of Lua defects or all product-specific threats. The catalogue supplies concrete review/test designs and traceability for the covered controls. See the authoring validation record for exactly which local checks ran and which pinned repository gates did not run.