`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<T> 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:

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 for registration, package descriptors, initialization, and worker setup.

Module contents

Types

Type	Kind	Description
`BitopsProvider`	interface	32-bit operations with Lua BitOp semantics.
`CastElements`	type	Casts storage to elements of any supplied ctype.
`CryptoProvider`	interface	Cryptographically secure randomness for the executing host.
`CstorageProvider`	interface	One coherent family of physical storage operations.
`HttpCapabilities`	record	Transport capability flags describing observable HTTP guarantees.
`Int64Provider`	interface	64-bit signed and unsigned arithmetic for generated portable operations.
`JsonProvider`	interface	JSON API 2, including portable encoding and optional compiled serde.
`MarkContainer`	type	Marks a table while returning the same generic table and ownership.
`PathProvider`	interface	Environmental path facts, independent of lexical path manipulation.
`StorageProvider`	interface	Persistent string key/value storage in the host's application namespace.
`StructvalueProvider`	interface	Struct-value operations supplied as part of the storage family.
`TextBufferProvider`	interface	Construction of the canonical portable FIFO Buffer.
`TimeProvider`	interface	Clocks and cancellable waits, measured in milliseconds.
`UriParts`	record	Normalized absolute-URI components shared by every parser.
`UriTextProvider`	interface	Absolute-URI parsing into canonical components.
`UuidProvider`	interface	Canonical lowercase, hyphenated UUID generation.
`WasmProvider`	interface	Opaque linear-memory operations belonging to a storage implementation.

Values

Value	Kind	Description
`bitops`	variable	Canonical numeric.bitops API 1 handle.
`buffer`	variable	Canonical text.buffer API 1 handle.
`crypto`	variable	Canonical host.crypto API 1 handle.
`cstorage`	variable	Canonical representation.cstorage API 1 handle.
`int64`	variable	Canonical numeric.int64 API 1 handle.
`json`	variable	Canonical data.json API 2 handle.
`path`	variable	Canonical host.path API 1 handle.
`storage`	variable	Canonical host.storage API 1 handle.
`time`	variable	Canonical host.time API 1 handle.
`uri`	variable	Canonical host.uri API 1 handle.
`uuid`	variable	Canonical data.uuid API 1 handle.

Types#

`BitopsProvider`interface#

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`#

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`#

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`#

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`#

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`#

bswap: function(value: number): integer

Reverses the four bytes of the normalized word.

Arguments

Name	Type	Description
`value`	`number`

Returns

Type	Description
`integer`

`band`#

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`#

bor: function(first: number, ...: number): integer

Bitwise disjunction of every operand.

Arguments

Name	Type	Description
`first`	`number`
`...`	`number`

Returns

Type	Description
`integer`

`bxor`#

bxor: function(first: number, ...: number): integer

Bitwise exclusive-or of every operand.

Arguments

Name	Type	Description
`first`	`number`
`...`	`number`

Returns

Type	Description
`integer`

`bnot`#

bnot: function(value: number): integer

Inverts all 32 bits.

Arguments

Name	Type	Description
`value`	`number`

Returns

Type	Description
`integer`

`lshift`#

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`#

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`#

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#

type CastElements = function<T>(element: ctype<T>, 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#

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`#

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#

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`#

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`#

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`#

descriptor: function(value: any): any

Reports layout and bounds for a provider value.

Arguments

Name	Type	Description
`value`	`any`

Returns

Type	Description
`any`

`allocateArray`#

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`#

allocateBytes: function(count: integer): uint8[?]

Allocates a writable byte region containing count bytes.

Arguments

Name	Type	Description
`count`	`integer`

Returns

Type	Description
`uint8[?]`

`borrowString`#

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`#

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`#

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`#

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`#

sizeOf: function(element: any): integer

Returns the descriptor size in bytes.

Arguments

Name	Type	Description
`element`	`any`

Returns

Type	Description
`integer`

`string`#

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`#

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`#

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`#

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`#

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`#

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`#

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`#

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`#

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`#

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`#

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`#

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`#

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`#

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`#

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`#

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`#

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`#

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`#

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`#

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`#

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`#

representation: string

Target pointer/layout convention: native or linear32.

`integers`#

integers: Int64Provider?

Integer operations sharing this storage representation; required for linear32.

`structs`#

structs: StructvalueProvider?

Struct descriptors and row operations sharing this storage family.

`host`#

host: WasmProvider?

Opaque memory-host operations sharing these allocations and pointers.

`layout`#

layout: (function(subject: any): any)?

Returns target layout facts for a type or descriptor; required for linear32.

`reference`#

reference: (function(resolve: function(): any): any)?

Creates a deferred descriptor reference for recursive layouts.

`castElements`#

castElements: CastElements

Interprets a pointer using any supplied element ctype.

`HttpCapabilities`record#

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`#

streamingResponse: boolean

Response bytes become available before the whole response arrives.

`streamingRequest`#

streamingRequest: boolean

Request bodies may be read incrementally from a reader or file.

`transportPolicy`#

transportPolicy: boolean

Proxy and per-host certificate policy can be configured by the caller.

`connectionPolicy`#

connectionPolicy: boolean

Redirect and connection limits can be enforced by the caller.

`protocolVersion`#

protocolVersion: boolean

The negotiated HTTP version is observable.

`Int64Provider`interface#

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`#

int64: function(value: any): any

Constructs or converts a signed 64-bit value.

Arguments

Name	Type	Description
`value`	`any`

Returns

Type	Description
`any`

`uint64`#

uint64: function(value: any): any

Constructs or converts an unsigned 64-bit value.

Arguments

Name	Type	Description
`value`	`any`

Returns

Type	Description
`any`

`add`#

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`#

sub: function(left: any, right: any): any

Subtracts the right operand.

Arguments

Name	Type	Description
`left`	`any`
`right`	`any`

Returns

Type	Description
`any`

`mul`#

mul: function(left: any, right: any): any

Multiplies full-width values.

Arguments

Name	Type	Description
`left`	`any`
`right`	`any`

Returns

Type	Description
`any`

`div`#

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`#

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`#

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`#

neg: function(value: any): any

Negates the value.

Arguments

Name	Type	Description
`value`	`any`

Returns

Type	Description
`any`

`band`#

band: function(left: any, right: any): any

Computes 64-bit conjunction.

Arguments

Name	Type	Description
`left`	`any`
`right`	`any`

Returns

Type	Description
`any`

`bor`#

bor: function(left: any, right: any): any

Computes 64-bit disjunction.

Arguments

Name	Type	Description
`left`	`any`
`right`	`any`

Returns

Type	Description
`any`

`bxor`#

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`#

bnot: function(value: any): any

Inverts all 64 bits.

Arguments

Name	Type	Description
`value`	`any`

Returns

Type	Description
`any`

`lshift`#

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`#

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`#

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`#

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`#

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`#

toString: function(value: any): string

Returns an exact decimal representation.

Arguments

Name	Type	Description
`value`	`any`

Returns

Type	Description
`string`

`JsonProvider`interface#

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`#

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`#

isArray: function(value: any): boolean

Reports whether a value has JSON array semantics.

Arguments

Name	Type	Description
`value`	`any`

Returns

Type	Description
`boolean`

`decode`#

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`#

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`#

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`#

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`#

encodedString: function(value: string): any

Creates a fragment containing one escaped JSON string.

Arguments

Name	Type	Description
`value`	`string`

Returns

Type	Description
`any`

`pull`#

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`#

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`#

verifiedString: function(text: string): any

Validates a raw encoded JSON string fragment.

Arguments

Name	Type	Description
`text`	`string`

Returns

Type	Description
`any`

`writer`#

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`#

asArray: MarkContainer

Marks and returns the same table as an array, preserving its ownership.

`asObject`#

asObject: MarkContainer

Marks and returns the same table as an object, preserving its ownership.

`NULL`#

NULL: any

Stable explicit null marker owned by this loaded implementation.

`EMPTY_ARRAY`#

EMPTY_ARRAY: table

Stable empty-array marker value.

`EMPTY_OBJECT`#

EMPTY_OBJECT: table

Stable empty-object marker value.

`compileSerde`#

compileSerde: (function(plan: any, unknownMembers: string): any)?

Optionally prepares a schema plan with its unknown-member policy.

`decodeSerde`#

decodeSerde: (function(schema: any, text: string): (any?, string?))?

Optionally decodes a prepared schema, returning value or diagnostic.

`decodeSerdeBuffer`#

decodeSerdeBuffer: (function(schema: any, exclusive input: SharedBuffer): (any?, string?))?

Optionally decodes from exclusive access to the canonical buffer.

`MarkContainer`type#

type MarkContainer = function<T is table>(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#

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`#

separator: function(): string

Returns the host path separator.

Returns

Type	Description
`string`

`currentDirectory`#

currentDirectory: function(): (string?, string?)

Returns the process directory or nil and an environmental error.

Returns

Type	Description
`string?`
`string?`

`canonicalize`#

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#

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`#

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`#

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`#

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`#

clear: function(): nil

Removes all entries in the host-defined application namespace.

Returns

Type	Description
`nil`

`StructvalueProvider`interface#

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`#

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`#

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`#

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`#

referenceValued: boolean

Whether row references address their underlying storage.

`TextBufferProvider`interface#

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`#

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#

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`#

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`#

now: function(): number

Returns monotonic milliseconds used for durations and deadlines.

Returns

Type	Description
`number`

`wallTime`#

wallTime: function(): number

Returns milliseconds since the Unix epoch.

Returns

Type	Description
`number`

`sleep`#

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`#

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#

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`#

text: string

Normalized complete URI text.

`scheme`#

scheme: string

Normalized scheme without the colon.

`authority`#

authority: string?

Serialized authority, or nil if the URI has none.

`username`#

username: string

Username component, empty when absent.

`password`#

password: string?

Password component, retaining absent versus empty.

`host`#

host: string?

Normalized host, or nil for a URI without one.

`port`#

port: integer?

Explicit non-default port when present.

`path`#

path: string

Normalized path component.

`query`#

query: string?

Query without its question mark, or nil when absent.

`fragment`#

fragment: string?

Fragment without its hash mark, or nil when absent.

`UriTextProvider`interface#

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`#

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#

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`#

uuid4: function(): string

Generates a random version 4 UUID.

Returns

Type	Description
`string`

`uuid7`#

uuid7: function(): string

Generates a time-ordered version 7 UUID.

Returns

Type	Description
`string`

`WasmProvider`interface#

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`#

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`#

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`#

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`#

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`#

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`#

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`#

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#

const bitops: services.Service<BitopsProvider>

Canonical numeric.bitops API 1 handle. Register or select before its facade loads.

`buffer`variable#

const buffer: services.Service<TextBufferProvider>

Canonical text.buffer API 1 handle. Register or select before its facade loads.

`crypto`variable#

const crypto: services.Service<CryptoProvider>

Canonical host.crypto API 1 handle. Register or select before its facade loads.

`cstorage`variable#

const cstorage: services.Service<
    CstorageProvider
>

Canonical representation.cstorage API 1 handle. Register or select before its facade loads.

`int64`variable#

const int64: services.Service<Int64Provider>

Canonical numeric.int64 API 1 handle. Register or select before its facade loads.

`json`variable#

const json: services.Service<JsonProvider>

Canonical data.json API 2 handle. Register or select before its facade loads.

`path`variable#

const path: services.Service<PathProvider>

Canonical host.path API 1 handle. Register or select before its facade loads.

`storage`variable#

const storage: services.Service<StorageProvider>

Canonical host.storage API 1 handle. Register or select before its facade loads.

`time`variable#

const time: services.Service<TimeProvider>

Canonical host.time API 1 handle. Register or select before its facade loads.

`uri`variable#

const uri: services.Service<UriTextProvider>

Canonical host.uri API 1 handle. Register or select before its facade loads.

`uuid`variable#

const uuid: services.Service<UuidProvider>

Canonical data.uuid API 1 handle. Register or select before its facade loads.

nupp.runtime.services.contracts

Module contents

Types

Values

Types#

BitopsProviderinterface#

Methods

tobit#

Arguments

Returns

tohex#

Arguments

Returns

rol#

Arguments

Returns

ror#

Arguments

Returns

bswap#

Arguments

Returns

band#

Arguments

Returns

bor#

Arguments

Returns

bxor#

Arguments

Returns

bnot#

Arguments

Returns

lshift#

Arguments

Returns

rshift#

Arguments

Returns

arshift#

Arguments

Returns

CastElementstype#

CryptoProviderinterface#

Methods

randomBytes#

Arguments

Returns

CstorageProviderinterface#

Methods

boundedCount#

Arguments

Returns

scalar#

Arguments

Returns

descriptor#

Arguments

Returns

allocateArray#

Arguments

Returns

allocateBytes#

Arguments

Returns

borrowString#

Arguments

Returns

castBytes#

Arguments

Returns

copy#

Arguments

Returns

fill#

Arguments

Returns

sizeOf#

Arguments

`nupp.runtime.services.contracts`

`BitopsProvider`interface#

`tobit`#

`tohex`#

`rol`#

`ror`#

`bswap`#

`band`#

`bor`#

`bxor`#

`bnot`#

`lshift`#

`rshift`#

`arshift`#

`CastElements`type#

`CryptoProvider`interface#

`randomBytes`#

`CstorageProvider`interface#

`boundedCount`#

`scalar`#

`descriptor`#

`allocateArray`#

`allocateBytes`#

`borrowString`#

`castBytes`#

`copy`#

`fill`#

`sizeOf`#

`string`#

`decodeUint8`#

`encodeUint8`#

`decodeInt8`#

`encodeInt8`#

`decodeUint16`#

`encodeUint16`#

`decodeInt16`#

`encodeInt16`#

`decodeUint32`#

`encodeUint32`#

`decodeInt32`#

`encodeInt32`#

`decodeUint64`#

`encodeUint64`#

`decodeInt64`#

`encodeInt64`#

`decodeFloat32`#

`encodeFloat32`#

`decodeFloat64`#

`encodeFloat64`#

`representation`#

`integers`#

`structs`#

`host`#

`layout`#