function · events

listen

Registers a generation-scoped callback for one typed post-commit event.

events.listen(event_id, callback) -> subscription_id

Stable ID: events.listen
Owner: app.ScriptPackageHost
Authority: read_only
Timing: post_commit
Availability: Phase 14 package callbacks
Side effects: none
Determinism: Host-created package identity and per-callback budgets.
Introduced: 1.0.0

Usage

Register one Lua function for a documented typed event. The host invokes it after authoritative commit at a safe frame boundary and destroys the subscription with the Lua generation.

Parameters

event_id: stable ID of a registered event.
callback: Lua function receiving one fresh detached callback-local event table.

Returns

A positive opaque subscription ID scoped to the current package and Lua generation.

Cost

At most 64 subscriptions and 64 active deliveries per package dispatch. Source history retains at most 256 events; overflow is diagnosed and bounded.

Fields

This symbol has no fields.

Errors

None

Examples

local subscription = events.listen(
    "events.command.completed",
    function(event)
        feedback = event.payload.command_id .. " completed"
    end
)

API history

1.0.0: Active generation-scoped event delivery added in Phase 14M.