# `nupp.runtime.services.contracts` Canonical contracts for varying numeric, data, storage, and host facilities. Importing this module defines typed service handles and registers catalog loaders without loading their implementations. Setup imports a handle, registers or selects a named provider, and only then requires consumers. A facade resolves its provider during top-level assembly and retains the actual table or functions. Each handle's `Service` annotation is the contract identity used by package checking. Implement the declared interface, including generic, borrowing, and ownership signatures; additional members are permitted. Provider functions here have no implicit receiver unless their signature includes one. Lua providers need matching declarations or a checked adapter. Runtime member checks validate the published shape; behavioral conformance remains the implementation's obligation. For example, a setup module can select a packaged buffer implementation without loading the facade: ```nupp local contracts = require("nupp.runtime.services.contracts") contracts.buffer:select("my-buffer") return require("application") ``` Use these handles rather than defining a second handle with the same string ID. All contracts use API 1 except `data.json`, which uses API 2. Representation services must match the target's layout and pointer conventions. Structvalue and WasmProvider describe members of one storage family; they are not independent selection points. See [Service Providers](../../../../../learn/projects/service-providers/index.html) for registration, package descriptors, initialization, and worker setup. ## Types ### `BitopsProvider` _interface_ ```nupp interface BitopsProvider readonly tobit: function(value: number): integer readonly tohex: function(value: number, digits: number?): string readonly rol: function(value: number, count: number): integer readonly ror: function(value: number, count: number): integer readonly bswap: function(value: number): integer readonly band: function(first: number, ...: number): integer readonly bor: function(first: number, ...: number): integer readonly bxor: function(first: number, ...: number): integer readonly bnot: function(value: number): integer readonly lshift: function(value: number, count: number): integer readonly rshift: function(value: number, count: number): integer readonly arshift: function(value: number, count: number): integer end ``` 32-bit operations with Lua BitOp semantics. Results are signed integers representing 32-bit words, including logical right shift results whose high bit is set. Inputs normalize to 32 bits; shifts and rotates mask counts to five bits. Variadic operations consume every operand. Providers must preserve these conventions even on hosts with unsigned primitives. #### Methods ##### `tobit` ```nupp tobit: function(value: number): integer ``` Normalizes a numeric operand to a signed 32-bit word. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `value` | `number` | | ###### Returns | Type | Description | | --- | --- | | `integer` | | ##### `tohex` ```nupp tohex: function(value: number, digits: number?): string ``` Formats the low requested hexadecimal digits; negative digits select uppercase. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `value` | `number` | | | `digits` | `number?` | | ###### Returns | Type | Description | | --- | --- | | `string` | | ##### `rol` ```nupp rol: function(value: number, count: number): integer ``` Rotates left by the low five bits of count. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `value` | `number` | | | `count` | `number` | | ###### Returns | Type | Description | | --- | --- | | `integer` | | ##### `ror` ```nupp ror: function(value: number, count: number): integer ``` Rotates right by the low five bits of count. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `value` | `number` | | | `count` | `number` | | ###### Returns | Type | Description | | --- | --- | | `integer` | | ##### `bswap` ```nupp bswap: function(value: number): integer ``` Reverses the four bytes of the normalized word. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `value` | `number` | | ###### Returns | Type | Description | | --- | --- | | `integer` | | ##### `band` ```nupp band: function(first: number, ...: number): integer ``` Bitwise conjunction of the first operand and every remaining operand. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `first` | `number` | | | `...` | `number` | | ###### Returns | Type | Description | | --- | --- | | `integer` | | ##### `bor` ```nupp bor: function(first: number, ...: number): integer ``` Bitwise disjunction of every operand. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `first` | `number` | | | `...` | `number` | | ###### Returns | Type | Description | | --- | --- | | `integer` | | ##### `bxor` ```nupp bxor: function(first: number, ...: number): integer ``` Bitwise exclusive-or of every operand. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `first` | `number` | | | `...` | `number` | | ###### Returns | Type | Description | | --- | --- | | `integer` | | ##### `bnot` ```nupp bnot: function(value: number): integer ``` Inverts all 32 bits. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `value` | `number` | | ###### Returns | Type | Description | | --- | --- | | `integer` | | ##### `lshift` ```nupp lshift: function(value: number, count: number): integer ``` Shifts left, discarding bits beyond the word. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `value` | `number` | | | `count` | `number` | | ###### Returns | Type | Description | | --- | --- | | `integer` | | ##### `rshift` ```nupp rshift: function(value: number, count: number): integer ``` Shifts right with zero fill, then returns the signed word representation. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `value` | `number` | | | `count` | `number` | | ###### Returns | Type | Description | | --- | --- | | `integer` | | ##### `arshift` ```nupp arshift: function(value: number, count: number): integer ``` Shifts right with sign extension. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `value` | `number` | | | `count` | `number` | | ###### Returns | Type | Description | | --- | --- | | `integer` | | ### `CastElements` _type_ ```nupp type CastElements = function(element: ctype, pointer: any): any ``` Casts storage to elements of any supplied ctype. The implementation must remain generic in T and use the target's representation; accepting one particular element type is not sufficient. ### `CryptoProvider` _interface_ ```nupp interface CryptoProvider readonly randomBytes: function(count: integer): string end ``` Cryptographically secure randomness for the executing host. Use the host secure random source and propagate its failures. Deterministic pseudo-random generators do not satisfy this contract. Host requests may suspend. #### Methods ##### `randomBytes` ```nupp randomBytes: function(count: integer): string ``` Returns exactly count random bytes. Accepts integers from zero through 1048576; zero returns an empty string. Raises on invalid counts or failure. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `count` | `integer` | | ###### Returns | Type | Description | | --- | --- | | `string` | | ### `CstorageProvider` _interface_ ```nupp interface CstorageProvider readonly boundedCount: function(borrows source: any, count: integer): integer readonly representation: string readonly integers: Int64Provider? readonly structs: StructvalueProvider? readonly host: WasmProvider? readonly layout: (function(subject: any): any)? readonly scalar: function(kind: string): any readonly descriptor: function(value: any): any readonly reference: (function(resolve: function(): any): any)? readonly allocateArray: function(element: any, count: integer): any readonly allocateBytes: function(count: integer): uint8[?] readonly borrowString: function(borrows bytes: string): const uint8[?] borrows (bytes) readonly castBytes: function(borrows pointer: any): const uint8[?] borrows (pointer) readonly castElements: CastElements readonly copy: function(borrows destination: any, borrows source: any, count: integer): nil readonly fill: function(destination: any, count: integer, value: integer): nil readonly sizeOf: function(element: any): integer readonly string: function(borrows source: any, count: integer): string readonly decodeUint8: function(bytes: string): uint32 readonly encodeUint8: function(value: uint32): string readonly decodeInt8: function(bytes: string): int32 readonly encodeInt8: function(value: int32): string readonly decodeUint16: function(bytes: string): uint32 readonly encodeUint16: function(value: uint32): string readonly decodeInt16: function(bytes: string): int32 readonly encodeInt16: function(value: int32): string readonly decodeUint32: function(bytes: string): uint32 readonly encodeUint32: function(value: uint32): string readonly decodeInt32: function(bytes: string): int32 readonly encodeInt32: function(value: int32): string readonly decodeUint64: function(bytes: string): uint64 readonly encodeUint64: function(value: uint64): string readonly decodeInt64: function(bytes: string): int64 readonly encodeInt64: function(value: int64): string readonly decodeFloat32: function(bytes: string): float readonly encodeFloat32: function(value: number): string readonly decodeFloat64: function(bytes: string): number readonly encodeFloat64: function(value: number): string end ``` One coherent family of physical storage operations. `representation` is `native` for native pointers or `linear32` for 32-bit linear memory. The facade checks it against the target before publishing this table. Linear32 implementations must also supply layout, reference, integers, structs, and host. Their structs must be reference-valued. The integer facade must use the exact integer provider attached to this storage family. Allocation, descriptors, scalar codecs, and copies must agree on byte order, alignment, width, and pointer units. Decode inputs contain at least the scalar width in bytes. Borrowed views preserve source lifetimes; `borrows`, generic casts, and const views are part of the implementation contract. Opaque values in these signatures carry provider storage, not permission to change a compiled representation at runtime. #### Methods ##### `boundedCount` ```nupp boundedCount: function(borrows source: any, count: integer): integer ``` Returns the requested count after any representation-specific extent check. Callers remain responsible for valid native pointer extents. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows source` | `any` | | | `count` | `integer` | | ###### Returns | Type | Description | | --- | --- | | `integer` | | ##### `scalar` ```nupp scalar: function(kind: string): any ``` Returns the canonical descriptor for a scalar kind within this provider. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `kind` | `string` | | ###### Returns | Type | Description | | --- | --- | | `any` | | ##### `descriptor` ```nupp descriptor: function(value: any): any ``` Reports layout and bounds for a provider value. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `value` | `any` | | ###### Returns | Type | Description | | --- | --- | | `any` | | ##### `allocateArray` ```nupp allocateArray: function(element: any, count: integer): any ``` Allocates count elements of the supplied descriptor. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `element` | `any` | | | `count` | `integer` | | ###### Returns | Type | Description | | --- | --- | | `any` | | ##### `allocateBytes` ```nupp allocateBytes: function(count: integer): uint8[?] ``` Allocates a writable byte region containing count bytes. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `count` | `integer` | | ###### Returns | Type | Description | | --- | --- | | `uint8\[?\]` | | ##### `borrowString` ```nupp borrowString: function(borrows bytes: string): const uint8[?] borrows (bytes) ``` Returns a read-only byte view whose lifetime borrows the source string. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows bytes` | `string` | | ###### Returns | Type | Description | | --- | --- | | `const uint8\[?\] borrows (bytes)` | | ##### `castBytes` ```nupp castBytes: function(borrows pointer: any): const uint8[?] borrows (pointer) ``` Returns a read-only byte view borrowing the pointer owner. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows pointer` | `any` | | ###### Returns | Type | Description | | --- | --- | | `const uint8\[?\] borrows (pointer)` | | ##### `copy` ```nupp copy: function(borrows destination: any, borrows source: any, count: integer): nil ``` Copies count bytes into destination without replacing its owner. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows destination` | `any` | | | `borrows source` | `any` | | | `count` | `integer` | | ###### Returns | Type | Description | | --- | --- | | `nil` | | ##### `fill` ```nupp fill: function(destination: any, count: integer, value: integer): nil ``` Fills count bytes in destination with the given byte value. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `destination` | `any` | | | `count` | `integer` | | | `value` | `integer` | | ###### Returns | Type | Description | | --- | --- | | `nil` | | ##### `sizeOf` ```nupp sizeOf: function(element: any): integer ``` Returns the descriptor size in bytes. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `element` | `any` | | ###### Returns | Type | Description | | --- | --- | | `integer` | | ##### `string` ```nupp string: function(borrows source: any, count: integer): string ``` Copies count source bytes into an independent Lua string. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows source` | `any` | | | `count` | `integer` | | ###### Returns | Type | Description | | --- | --- | | `string` | | ##### `decodeUint8` ```nupp decodeUint8: function(bytes: string): uint32 ``` Decodes one unsigned 8-bit integer using the target storage byte order. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `bytes` | `string` | | ###### Returns | Type | Description | | --- | --- | | `uint32` | | ##### `encodeUint8` ```nupp encodeUint8: function(value: uint32): string ``` Encodes one unsigned 8-bit integer using the target storage byte order. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `value` | `uint32` | | ###### Returns | Type | Description | | --- | --- | | `string` | | ##### `decodeInt8` ```nupp decodeInt8: function(bytes: string): int32 ``` Decodes one signed 8-bit integer using the target storage byte order. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `bytes` | `string` | | ###### Returns | Type | Description | | --- | --- | | `int32` | | ##### `encodeInt8` ```nupp encodeInt8: function(value: int32): string ``` Encodes one signed 8-bit integer using the target storage byte order. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `value` | `int32` | | ###### Returns | Type | Description | | --- | --- | | `string` | | ##### `decodeUint16` ```nupp decodeUint16: function(bytes: string): uint32 ``` Decodes one unsigned 16-bit integer using the target storage byte order. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `bytes` | `string` | | ###### Returns | Type | Description | | --- | --- | | `uint32` | | ##### `encodeUint16` ```nupp encodeUint16: function(value: uint32): string ``` Encodes one unsigned 16-bit integer using the target storage byte order. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `value` | `uint32` | | ###### Returns | Type | Description | | --- | --- | | `string` | | ##### `decodeInt16` ```nupp decodeInt16: function(bytes: string): int32 ``` Decodes one signed 16-bit integer using the target storage byte order. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `bytes` | `string` | | ###### Returns | Type | Description | | --- | --- | | `int32` | | ##### `encodeInt16` ```nupp encodeInt16: function(value: int32): string ``` Encodes one signed 16-bit integer using the target storage byte order. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `value` | `int32` | | ###### Returns | Type | Description | | --- | --- | | `string` | | ##### `decodeUint32` ```nupp decodeUint32: function(bytes: string): uint32 ``` Decodes one unsigned 32-bit integer using the target storage byte order. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `bytes` | `string` | | ###### Returns | Type | Description | | --- | --- | | `uint32` | | ##### `encodeUint32` ```nupp encodeUint32: function(value: uint32): string ``` Encodes one unsigned 32-bit integer using the target storage byte order. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `value` | `uint32` | | ###### Returns | Type | Description | | --- | --- | | `string` | | ##### `decodeInt32` ```nupp decodeInt32: function(bytes: string): int32 ``` Decodes one signed 32-bit integer using the target storage byte order. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `bytes` | `string` | | ###### Returns | Type | Description | | --- | --- | | `int32` | | ##### `encodeInt32` ```nupp encodeInt32: function(value: int32): string ``` Encodes one signed 32-bit integer using the target storage byte order. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `value` | `int32` | | ###### Returns | Type | Description | | --- | --- | | `string` | | ##### `decodeUint64` ```nupp decodeUint64: function(bytes: string): uint64 ``` Decodes one unsigned 64-bit integer using the target storage byte order. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `bytes` | `string` | | ###### Returns | Type | Description | | --- | --- | | `uint64` | | ##### `encodeUint64` ```nupp encodeUint64: function(value: uint64): string ``` Encodes one unsigned 64-bit integer using the target storage byte order. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `value` | `uint64` | | ###### Returns | Type | Description | | --- | --- | | `string` | | ##### `decodeInt64` ```nupp decodeInt64: function(bytes: string): int64 ``` Decodes one signed 64-bit integer using the target storage byte order. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `bytes` | `string` | | ###### Returns | Type | Description | | --- | --- | | `int64` | | ##### `encodeInt64` ```nupp encodeInt64: function(value: int64): string ``` Encodes one signed 64-bit integer using the target storage byte order. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `value` | `int64` | | ###### Returns | Type | Description | | --- | --- | | `string` | | ##### `decodeFloat32` ```nupp decodeFloat32: function(bytes: string): float ``` Decodes one IEEE-754 binary32 value using the target storage byte order. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `bytes` | `string` | | ###### Returns | Type | Description | | --- | --- | | `float` | | ##### `encodeFloat32` ```nupp encodeFloat32: function(value: number): string ``` Encodes one IEEE-754 binary32 value using the target storage byte order. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `value` | `number` | | ###### Returns | Type | Description | | --- | --- | | `string` | | ##### `decodeFloat64` ```nupp decodeFloat64: function(bytes: string): number ``` Decodes one IEEE-754 binary64 value using the target storage byte order. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `bytes` | `string` | | ###### Returns | Type | Description | | --- | --- | | `number` | | ##### `encodeFloat64` ```nupp encodeFloat64: function(value: number): string ``` Encodes one IEEE-754 binary64 value using the target storage byte order. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `value` | `number` | | ###### Returns | Type | Description | | --- | --- | | `string` | | #### Fields ##### `representation` ```nupp representation: string ``` Target pointer/layout convention: native or linear32. ##### `integers` ```nupp integers: Int64Provider? ``` Integer operations sharing this storage representation; required for linear32. ##### `structs` ```nupp structs: StructvalueProvider? ``` Struct descriptors and row operations sharing this storage family. ##### `host` ```nupp host: WasmProvider? ``` Opaque memory-host operations sharing these allocations and pointers. ##### `layout` ```nupp layout: (function(subject: any): any)? ``` Returns target layout facts for a type or descriptor; required for linear32. ##### `reference` ```nupp reference: (function(resolve: function(): any): any)? ``` Creates a deferred descriptor reference for recursive layouts. ##### `castElements` ```nupp castElements: CastElements ``` Interprets a pointer using any supplied element ctype. ### `HttpCapabilities` _record_ ```nupp record HttpCapabilities streamingResponse: boolean streamingRequest: boolean transportPolicy: boolean connectionPolicy: boolean protocolVersion: boolean end ``` Transport capability flags describing observable HTTP guarantees. A true flag promises the corresponding behavior; callers must not infer support from a provider name or the presence of unrelated methods. #### Fields ##### `streamingResponse` ```nupp streamingResponse: boolean ``` Response bytes become available before the whole response arrives. ##### `streamingRequest` ```nupp streamingRequest: boolean ``` Request bodies may be read incrementally from a reader or file. ##### `transportPolicy` ```nupp transportPolicy: boolean ``` Proxy and per-host certificate policy can be configured by the caller. ##### `connectionPolicy` ```nupp connectionPolicy: boolean ``` Redirect and connection limits can be enforced by the caller. ##### `protocolVersion` ```nupp protocolVersion: boolean ``` The negotiated HTTP version is observable. ### `Int64Provider` _interface_ ```nupp interface Int64Provider readonly int64: function(value: any): any readonly uint64: function(value: any): any readonly add: function(left: any, right: any): any readonly sub: function(left: any, right: any): any readonly mul: function(left: any, right: any): any readonly div: function(left: any, right: any): any readonly mod: function(left: any, right: any): any readonly pow: function(left: any, right: any): any readonly neg: function(value: any): any readonly band: function(left: any, right: any): any readonly bor: function(left: any, right: any): any readonly bxor: function(left: any, right: any): any readonly bnot: function(value: any): any readonly lshift: function(value: any, count: number): any readonly rshift: function(value: any, count: number): any readonly arshift: function(value: any, count: number): any readonly compare: function(left: any, right: any): number readonly toNumber: function(value: any): number readonly toString: function(value: any): string end ``` 64-bit signed and unsigned arithmetic for generated portable operations. Values must retain their full width rather than round through a Lua number. Arithmetic, comparisons, shifts, and conversions must agree with the signedness created by int64/uint64. toNumber is the explicit potentially inexact conversion. When physical storage supplies integers, this must be that same implementation. #### Methods ##### `int64` ```nupp int64: function(value: any): any ``` Constructs or converts a signed 64-bit value. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `value` | `any` | | ###### Returns | Type | Description | | --- | --- | | `any` | | ##### `uint64` ```nupp uint64: function(value: any): any ``` Constructs or converts an unsigned 64-bit value. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `value` | `any` | | ###### Returns | Type | Description | | --- | --- | | `any` | | ##### `add` ```nupp add: function(left: any, right: any): any ``` Adds two full-width values. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `left` | `any` | | | `right` | `any` | | ###### Returns | Type | Description | | --- | --- | | `any` | | ##### `sub` ```nupp sub: function(left: any, right: any): any ``` Subtracts the right operand. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `left` | `any` | | | `right` | `any` | | ###### Returns | Type | Description | | --- | --- | | `any` | | ##### `mul` ```nupp mul: function(left: any, right: any): any ``` Multiplies full-width values. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `left` | `any` | | | `right` | `any` | | ###### Returns | Type | Description | | --- | --- | | `any` | | ##### `div` ```nupp div: function(left: any, right: any): any ``` Divides using the integer representation semantics. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `left` | `any` | | | `right` | `any` | | ###### Returns | Type | Description | | --- | --- | | `any` | | ##### `mod` ```nupp mod: function(left: any, right: any): any ``` Computes the corresponding integer remainder. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `left` | `any` | | | `right` | `any` | | ###### Returns | Type | Description | | --- | --- | | `any` | | ##### `pow` ```nupp pow: function(left: any, right: any): any ``` Raises to an integer power. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `left` | `any` | | | `right` | `any` | | ###### Returns | Type | Description | | --- | --- | | `any` | | ##### `neg` ```nupp neg: function(value: any): any ``` Negates the value. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `value` | `any` | | ###### Returns | Type | Description | | --- | --- | | `any` | | ##### `band` ```nupp band: function(left: any, right: any): any ``` Computes 64-bit conjunction. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `left` | `any` | | | `right` | `any` | | ###### Returns | Type | Description | | --- | --- | | `any` | | ##### `bor` ```nupp bor: function(left: any, right: any): any ``` Computes 64-bit disjunction. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `left` | `any` | | | `right` | `any` | | ###### Returns | Type | Description | | --- | --- | | `any` | | ##### `bxor` ```nupp bxor: function(left: any, right: any): any ``` Computes 64-bit exclusive-or. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `left` | `any` | | | `right` | `any` | | ###### Returns | Type | Description | | --- | --- | | `any` | | ##### `bnot` ```nupp bnot: function(value: any): any ``` Inverts all 64 bits. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `value` | `any` | | ###### Returns | Type | Description | | --- | --- | | `any` | | ##### `lshift` ```nupp lshift: function(value: any, count: number): any ``` Shifts left within the 64-bit representation. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `value` | `any` | | | `count` | `number` | | ###### Returns | Type | Description | | --- | --- | | `any` | | ##### `rshift` ```nupp rshift: function(value: any, count: number): any ``` Shifts right with zero fill. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `value` | `any` | | | `count` | `number` | | ###### Returns | Type | Description | | --- | --- | | `any` | | ##### `arshift` ```nupp arshift: function(value: any, count: number): any ``` Shifts right with sign extension. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `value` | `any` | | | `count` | `number` | | ###### Returns | Type | Description | | --- | --- | | `any` | | ##### `compare` ```nupp compare: function(left: any, right: any): number ``` Returns a negative number, zero, or a positive number for ordering. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `left` | `any` | | | `right` | `any` | | ###### Returns | Type | Description | | --- | --- | | `number` | | ##### `toNumber` ```nupp toNumber: function(value: any): number ``` Converts to a Lua number, which may lose integer precision. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `value` | `any` | | ###### Returns | Type | Description | | --- | --- | | `number` | | ##### `toString` ```nupp toString: function(value: any): string ``` Returns an exact decimal representation. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `value` | `any` | | ###### Returns | Type | Description | | --- | --- | | `string` | | ### `JsonProvider` _interface_ ```nupp interface JsonProvider readonly arrayOf: function(shape: any?): any readonly asArray: MarkContainer readonly asObject: MarkContainer readonly isArray: function(value: any): boolean readonly decode: function(text: string, nullValue: any?): any readonly encode: function(value: any, nullValue: any?): string readonly serialize: function(value: any, nullValue: any?): string readonly encoded: function(value: any, nullValue: any?): any readonly encodedString: function(value: string): any readonly pull: function(text: string, shape: any, nullValue: any?): any readonly verified: function(text: string): any readonly verifiedString: function(text: string): any readonly writer: function(exclusive out: SharedBuffer, nullValue: any?): any readonly NULL: any readonly EMPTY_ARRAY: table readonly EMPTY_OBJECT: table readonly compileSerde: (function(plan: any, unknownMembers: string): any)? readonly decodeSerde: (function(schema: any, text: string): (any?, string?))? readonly decodeSerdeBuffer: (function(schema: any, exclusive input: SharedBuffer): (any?, string?))? end ``` JSON API 2, including portable encoding and optional compiled serde. Arrays, objects, null sentinels, and verified fragments must agree across every member of this table. Keep marker identities stable for the loaded provider. The caller's nullValue controls null conversion; omission follows the public JSON API's nil behavior. Reject malformed syntax, invalid UTF-8, unsupported container shapes, and invalid raw fragments according to that API. The three serde hooks are optional accelerators. If supplied together, compiled schemas and both decode entry points must share their representation and unknown-member policy. All buffer operations use the canonical shared Buffer; they must preserve the declared exclusive access and ownership guarantees. #### Methods ##### `arrayOf` ```nupp arrayOf: function(shape: any?): any ``` Builds an array projection shape with the supplied element shape. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `shape` | `any?` | | ###### Returns | Type | Description | | --- | --- | | `any` | | ##### `isArray` ```nupp isArray: function(value: any): boolean ``` Reports whether a value has JSON array semantics. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `value` | `any` | | ###### Returns | Type | Description | | --- | --- | | `boolean` | | ##### `decode` ```nupp decode: function(text: string, nullValue: any?): any ``` Parses JSON, applying the caller-selected representation of null. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `text` | `string` | | | `nullValue` | `any?` | | ###### Returns | Type | Description | | --- | --- | | `any` | | ##### `encode` ```nupp encode: function(value: any, nullValue: any?): string ``` Serializes a value with this provider's markers and null convention. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `value` | `any` | | | `nullValue` | `any?` | | ###### Returns | Type | Description | | --- | --- | | `string` | | ##### `serialize` ```nupp serialize: function(value: any, nullValue: any?): string ``` Serializes with the same semantics as encode. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `value` | `any` | | | `nullValue` | `any?` | | ###### Returns | Type | Description | | --- | --- | | `string` | | ##### `encoded` ```nupp encoded: function(value: any, nullValue: any?): any ``` Creates a validated encoded-value fragment for subsequent composition. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `value` | `any` | | | `nullValue` | `any?` | | ###### Returns | Type | Description | | --- | --- | | `any` | | ##### `encodedString` ```nupp encodedString: function(value: string): any ``` Creates a fragment containing one escaped JSON string. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `value` | `string` | | ###### Returns | Type | Description | | --- | --- | | `any` | | ##### `pull` ```nupp pull: function(text: string, shape: any, nullValue: any?): any ``` Parses only the value projection described by shape. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `text` | `string` | | | `shape` | `any` | | | `nullValue` | `any?` | | ###### Returns | Type | Description | | --- | --- | | `any` | | ##### `verified` ```nupp verified: function(text: string): any ``` Validates raw JSON and retains a fragment suitable for composition. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `text` | `string` | | ###### Returns | Type | Description | | --- | --- | | `any` | | ##### `verifiedString` ```nupp verifiedString: function(text: string): any ``` Validates a raw encoded JSON string fragment. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `text` | `string` | | ###### Returns | Type | Description | | --- | --- | | `any` | | ##### `writer` ```nupp writer: function(exclusive out: SharedBuffer, nullValue: any?): any ``` Creates a JSON writer over exclusive access to the canonical buffer. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive out` | `SharedBuffer` | | | `nullValue` | `any?` | | ###### Returns | Type | Description | | --- | --- | | `any` | | #### Fields ##### `asArray` ```nupp asArray: MarkContainer ``` Marks and returns the same table as an array, preserving its ownership. ##### `asObject` ```nupp asObject: MarkContainer ``` Marks and returns the same table as an object, preserving its ownership. ##### `NULL` ```nupp NULL: any ``` Stable explicit null marker owned by this loaded implementation. ##### `EMPTY_ARRAY` ```nupp EMPTY_ARRAY: table ``` Stable empty-array marker value. ##### `EMPTY_OBJECT` ```nupp EMPTY_OBJECT: table ``` Stable empty-object marker value. ##### `compileSerde` ```nupp compileSerde: (function(plan: any, unknownMembers: string): any)? ``` Optionally prepares a schema plan with its unknown-member policy. ##### `decodeSerde` ```nupp decodeSerde: (function(schema: any, text: string): (any?, string?))? ``` Optionally decodes a prepared schema, returning value or diagnostic. ##### `decodeSerdeBuffer` ```nupp decodeSerdeBuffer: (function(schema: any, exclusive input: SharedBuffer): (any?, string?))? ``` Optionally decodes from exclusive access to the canonical buffer. ### `MarkContainer` _type_ ```nupp type MarkContainer = function(takes value: T): T preserves value ``` Marks a table while returning the same generic table and ownership. The takes/preserves relation is intentional: an implementation must not copy the container or erase an affine owner while applying its JSON marker. ### `PathProvider` _interface_ ```nupp interface PathProvider readonly separator: function(): string readonly currentDirectory: function(): (string?, string?) readonly canonicalize: function(path: string): (string?, string?) end ``` Environmental path facts, independent of lexical path manipulation. separator reports the host convention. currentDirectory and canonicalize may return nil with an explanatory message when the host has no such facility or an operating-system operation fails. Public Path identity remains in nupp.io.path. #### Methods ##### `separator` ```nupp separator: function(): string ``` Returns the host path separator. ###### Returns | Type | Description | | --- | --- | | `string` | | ##### `currentDirectory` ```nupp currentDirectory: function(): (string?, string?) ``` Returns the process directory or nil and an environmental error. ###### Returns | Type | Description | | --- | --- | | `string?` | | | `string?` | | ##### `canonicalize` ```nupp canonicalize: function(path: string): (string?, string?) ``` Resolves a host filesystem path or returns nil and an error. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `path` | `string` | | ###### Returns | Type | Description | | --- | --- | | `string?` | | | `string?` | | ### `StorageProvider` _interface_ ```nupp interface StorageProvider readonly get: function(name: string): string? readonly set: function(name: string, value: string): nil readonly remove: function(name: string): nil readonly clear: function(): nil end ``` Persistent string key/value storage in the host's application namespace. Missing keys return nil. Successful writes, removals, and clearing complete before returning; host-backed implementations may suspend and may raise on quota or access errors. clear affects the host-defined application namespace, not arbitrary storage outside it. #### Methods ##### `get` ```nupp get: function(name: string): string? ``` Returns the stored string, or nil when the key is absent. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `name` | `string` | | ###### Returns | Type | Description | | --- | --- | | `string?` | | ##### `set` ```nupp set: function(name: string, value: string): nil ``` Stores the complete string value. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `name` | `string` | | | `value` | `string` | | ###### Returns | Type | Description | | --- | --- | | `nil` | | ##### `remove` ```nupp remove: function(name: string): nil ``` Removes the key; an absent key needs no value. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `name` | `string` | | ###### Returns | Type | Description | | --- | --- | | `nil` | | ##### `clear` ```nupp clear: function(): nil ``` Removes all entries in the host-defined application namespace. ###### Returns | Type | Description | | --- | --- | | `nil` | | ### `StructvalueProvider` _interface_ ```nupp interface StructvalueProvider readonly scalar: function(kind: string): any readonly array: function(element: any, count: integer): any readonly define: function(layout: any, methods: table): any readonly referenceValued: boolean end ``` Struct-value operations supplied as part of the storage family. Descriptors, arrays, and constructed values must agree with compiler layouts and canonical struct declarations. referenceValued reports whether a row reference addresses the underlying storage. This interface has no independently selectable handle; representation assembly supplies a compatible implementation. #### Methods ##### `scalar` ```nupp scalar: function(kind: string): any ``` Returns a scalar descriptor accepted by define and array. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `kind` | `string` | | ###### Returns | Type | Description | | --- | --- | | `any` | | ##### `array` ```nupp array: function(element: any, count: integer): any ``` Allocates count elements using this family's element descriptor. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `element` | `any` | | | `count` | `integer` | | ###### Returns | Type | Description | | --- | --- | | `any` | | ##### `define` ```nupp define: function(layout: any, methods: table): any ``` Constructs a type descriptor from a compiler layout and method table. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `layout` | `any` | | | `methods` | `table` | | ###### Returns | Type | Description | | --- | --- | | `any` | | #### Fields ##### `referenceValued` ```nupp referenceValued: boolean ``` Whether row references address their underlying storage. ### `TextBufferProvider` _interface_ ```nupp interface TextBufferProvider readonly new: function(size: (integer | table)?, options: table?): SharedBuffer end ``` Construction of the canonical portable FIFO Buffer. Return the shared Buffer type from nupp.text.buffer.types. Implementations may use native objects or portable state, but all signatures and chaining results must retain that identity. Native pointer and serializer facilities are outside this portable contract. #### Methods ##### `new` ```nupp new: function(size: (integer | table)?, options: table?): SharedBuffer ``` Creates an independent FIFO buffer; accepts a size hint or an options table. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `size` | `(integer | table)?` | | | `options` | `table?` | | ###### Returns | Type | Description | | --- | --- | | `SharedBuffer` | | ### `TimeProvider` _interface_ ```nupp interface TimeProvider readonly wakeAt: function(deadline: number, resume: function(boolean): nil): function(): nil readonly now: function(): number readonly wallTime: function(): number readonly sleep: function(milliseconds: number): nil readonly sleepUntil: function(deadline: number): nil end ``` Clocks and cancellable waits, measured in milliseconds. now is monotonic with an unspecified origin; wallTime is Unix epoch time and must not be used for monotonic deadlines. wakeAt and sleepUntil use the same origin as now. Finite non-negative durations and deadlines are required. Waits cooperate with the selected suspension implementation. Timer callbacks and cancellation functions belong to the current Lua state. #### Methods ##### `wakeAt` ```nupp wakeAt: function(deadline: number, resume: function(boolean): nil): function(): nil ``` Schedules one deadline callback and returns its cancellation function. Registration itself must not suspend the subscriber. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `deadline` | `number` | | | `resume` | `function(boolean): nil` | | ###### Returns | Type | Description | | --- | --- | | `function(): nil` | | ##### `now` ```nupp now: function(): number ``` Returns monotonic milliseconds used for durations and deadlines. ###### Returns | Type | Description | | --- | --- | | `number` | | ##### `wallTime` ```nupp wallTime: function(): number ``` Returns milliseconds since the Unix epoch. ###### Returns | Type | Description | | --- | --- | | `number` | | ##### `sleep` ```nupp sleep: function(milliseconds: number): nil ``` Waits for a relative interval through the current suspension context. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `milliseconds` | `number` | | ###### Returns | Type | Description | | --- | --- | | `nil` | | ##### `sleepUntil` ```nupp sleepUntil: function(deadline: number): nil ``` Waits until an absolute deadline in the now clock domain. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `deadline` | `number` | | ###### Returns | Type | Description | | --- | --- | | `nil` | | ### `UriParts` _record_ ```nupp record UriParts text: string scheme: string authority: string? username: string password: string? host: string? port: integer? path: string query: string? fragment: string? end ``` Normalized absolute-URI components shared by every parser. Use nil for an absent optional component and an empty string for a present empty one. text is the normalized serialization; scheme is normalized consistently with it. The public URI wrapper uses this record without introducing a provider-specific nominal identity. #### Fields ##### `text` ```nupp text: string ``` Normalized complete URI text. ##### `scheme` ```nupp scheme: string ``` Normalized scheme without the colon. ##### `authority` ```nupp authority: string? ``` Serialized authority, or nil if the URI has none. ##### `username` ```nupp username: string ``` Username component, empty when absent. ##### `password` ```nupp password: string? ``` Password component, retaining absent versus empty. ##### `host` ```nupp host: string? ``` Normalized host, or nil for a URI without one. ##### `port` ```nupp port: integer? ``` Explicit non-default port when present. ##### `path` ```nupp path: string ``` Normalized path component. ##### `query` ```nupp query: string? ``` Query without its question mark, or nil when absent. ##### `fragment` ```nupp fragment: string? ``` Fragment without its hash mark, or nil when absent. ### `UriTextProvider` _interface_ ```nupp interface UriTextProvider readonly parse: function(text: string): (UriParts?, string?) end ``` Absolute-URI parsing into canonical components. Return nil and a diagnostic for unsupported or invalid input. Successful parses must make text, authority, host, port, and path mutually consistent and preserve absent versus empty query and fragment values. #### Methods ##### `parse` ```nupp parse: function(text: string): (UriParts?, string?) ``` Parses an absolute URI into shared components or returns nil and a message. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `text` | `string` | | ###### Returns | Type | Description | | --- | --- | | `UriParts?` | | | `string?` | | ### `UuidProvider` _interface_ ```nupp interface UuidProvider readonly uuid4: function(): string readonly uuid7: function(): string end ``` Canonical lowercase, hyphenated UUID generation. Version 4 provides random UUIDs and version 7 provides time-ordered UUIDs. Version and variant bits must be correct; randomness failures must be reported. #### Methods ##### `uuid4` ```nupp uuid4: function(): string ``` Generates a random version 4 UUID. ###### Returns | Type | Description | | --- | --- | | `string` | | ##### `uuid7` ```nupp uuid7: function(): string ``` Generates a time-ordered version 7 UUID. ###### Returns | Type | Description | | --- | --- | | `string` | | ### `WasmProvider` _interface_ ```nupp interface WasmProvider readonly allocate: function(bytes: integer): any readonly pointer: function(allocation: any, index: integer, stride: integer): any readonly offset: function(pointer: any, count: integer): any readonly load: function(pointer: any, byteOffset: integer, kind: string): any readonly store: function(pointer: any, byteOffset: integer, kind: string, value: any): nil readonly copy: function(destination: any, source: any, bytes: integer): nil readonly descriptor: function(value: any): any end ``` Opaque linear-memory operations belonging to a storage implementation. Allocation and pointer values must refer to that implementation's memory host. Offsets and copy lengths are bytes; pointer's index/stride pair locates an element in an allocation. Loads and stores use the scalar kind's width and encoding. Bounds and owner lifetimes must remain valid across every operation. This interface is supplied through CstorageProvider.host, not a separate SPI. #### Methods ##### `allocate` ```nupp allocate: function(bytes: integer): any ``` Allocates the requested number of bytes in this memory host. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `bytes` | `integer` | | ###### Returns | Type | Description | | --- | --- | | `any` | | ##### `pointer` ```nupp pointer: function(allocation: any, index: integer, stride: integer): any ``` Locates a zero-based element using index and byte stride. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `allocation` | `any` | | | `index` | `integer` | | | `stride` | `integer` | | ###### Returns | Type | Description | | --- | --- | | `any` | | ##### `offset` ```nupp offset: function(pointer: any, count: integer): any ``` Offsets an existing pointer by count bytes. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `pointer` | `any` | | | `count` | `integer` | | ###### Returns | Type | Description | | --- | --- | | `any` | | ##### `load` ```nupp load: function(pointer: any, byteOffset: integer, kind: string): any ``` Reads a scalar kind at a byte offset from the pointer. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `pointer` | `any` | | | `byteOffset` | `integer` | | | `kind` | `string` | | ###### Returns | Type | Description | | --- | --- | | `any` | | ##### `store` ```nupp store: function(pointer: any, byteOffset: integer, kind: string, value: any): nil ``` Writes a scalar kind at a byte offset from the pointer. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `pointer` | `any` | | | `byteOffset` | `integer` | | | `kind` | `string` | | | `value` | `any` | | ###### Returns | Type | Description | | --- | --- | | `nil` | | ##### `copy` ```nupp copy: function(destination: any, source: any, bytes: integer): nil ``` Copies bytes between regions belonging to this host. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `destination` | `any` | | | `source` | `any` | | | `bytes` | `integer` | | ###### Returns | Type | Description | | --- | --- | | `nil` | | ##### `descriptor` ```nupp descriptor: function(value: any): any ``` Returns bounds and layout information for a host value. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `value` | `any` | | ###### Returns | Type | Description | | --- | --- | | `any` | | ## Values ### `bitops` _variable_ ```nupp const bitops: services.Service ``` Canonical numeric.bitops API 1 handle. Register or select before its facade loads. ### `buffer` _variable_ ```nupp const buffer: services.Service ``` Canonical text.buffer API 1 handle. Register or select before its facade loads. ### `crypto` _variable_ ```nupp const crypto: services.Service ``` Canonical host.crypto API 1 handle. Register or select before its facade loads. ### `cstorage` _variable_ ```nupp const cstorage: services.Service< CstorageProvider > ``` Canonical representation.cstorage API 1 handle. Register or select before its facade loads. ### `int64` _variable_ ```nupp const int64: services.Service ``` Canonical numeric.int64 API 1 handle. Register or select before its facade loads. ### `json` _variable_ ```nupp const json: services.Service ``` Canonical data.json API 2 handle. Register or select before its facade loads. ### `path` _variable_ ```nupp const path: services.Service ``` Canonical host.path API 1 handle. Register or select before its facade loads. ### `storage` _variable_ ```nupp const storage: services.Service ``` Canonical host.storage API 1 handle. Register or select before its facade loads. ### `time` _variable_ ```nupp const time: services.Service ``` Canonical host.time API 1 handle. Register or select before its facade loads. ### `uri` _variable_ ```nupp const uri: services.Service ``` Canonical host.uri API 1 handle. Register or select before its facade loads. ### `uuid` _variable_ ```nupp const uuid: services.Service ``` Canonical data.uuid API 1 handle. Register or select before its facade loads.