Expand description
Proc-macros that declare Portaki Wasm module metadata at compile time.
Each macro prepends an invisible const block (via emit::write_emission) that writes a
JSON fragment when OUT_DIR is set during cargo build — Cargo sets it only for a crate
with a build script, so a module keeps a build.rs (fn main() {} is enough). A wasm32 build
without one fails at portaki_module! with that advice. Fragments land under:
{OUT_DIR}/portaki-emissions/{kind}-{sanitized_key}.jsonwhere OUT_DIR is Cargo’s per-crate build output directory (e.g.
target/debug/build/<crate-hash>/out/ for host builds, or the analogous path under
target/wasm32-unknown-unknown/ for Wasm targets).
§Build pipeline
- Module source uses these macros (typically via
portaki_sdk::prelude::*re-exports). cargo build --target wasm32-unknown-unknownexpands macros and writes emission files.portaki buildcallsfind_emissions_dir, which picks the most recently modifiedportaki-emissionsdirectory undertarget/, thencollect_emissions+generate_manifestmerge fragments intotarget/portaki/manifest.json.portaki lintvalidates capability ids against the host catalog (portaki_sdk::capability::ALL/is_known), i18n keys, and manifest shape.
A portaki.module.json catalog at the module root can override or supplement emissions; if
neither emissions nor a catalog exist, portaki build fails.
§Emission kinds
| Macro | kind field | Filename pattern |
|---|---|---|
portaki_module | module | module-{id}.json |
entity | entity | entity-{StructName}.json |
entity_indexes | entity_indexes | entity_indexes-{EntityName}.json |
surface | surface | surface-{context}_{id}.json |
query | query | query-{name}.json |
command | command | command-{name}.json |
params | params | params-{TypeName}.json |
config | config (+ query legacyConfig, command legacyConfigAdopted) | config-{StructName}.json |
email_vars | email_vars (+ query emailContext) | email_vars-emailContext.json |
email_blocks | email_blocks (+ query emailContext) | email_blocks-emailContext.json |
event_handler | event_handler | event_handler-{event_type}.json |
capability | capability | capability-{id}.json |
connector | connector_builtin | connector_builtin-{builtin}.json |
custom_connector | connector_custom | connector_custom-{id}.json |
connector_op | connector_op | connector_op-{fn_name}.json |
entity_indexes emissions are written for Atlas/migration tooling; they are not merged into
manifest.json today (only entity field metadata is).
§Wasm runtime code generation
portaki_module additionally emits Extism export shims (portaki_query, portaki_command) and
a __getrandom_v03_custom hook when target_arch = "wasm32".
query, command, and surface emit inventory::submit! handler registrations that wire
manifest operation names to the annotated Rust function via JSON dispatch — a
HandlerRegistration on wasm32, a HandlerDeclaration (with the handler’s kind and surface
context) on native targets, where the test-utils conformance battery reads it.
Macros§
- bundle_
text - A text of the module’s own bundles, in every language they have — an
I18nText. - portaki_
module_ decl - Function-like module declaration (
portaki_module!(…)).
Attribute Macros§
- capability
- Declares a required or optional host capability dependency.
- choice
- A unit enum a declared field picks from (
unstable).label = "rule.status": a value’s label is the bundle keyrule.status.<value>;#[icon(IconName::X)]on a variant gives its icon. Writes the derives,portaki_sdk::resource::Choice, and the values for the manifest. - collection
- A collection the SDK stores (
unstable):#[collection(name = "rules", item = Rule, meta = Display, max = 30, import)]on a unit struct. Generatesload/save, theupdateConfigcommand (host form),importRows(withimport), the host queryreadRows(withread: the rows as declared, for the platform’s guest assistant — only on rows the guest sees, never on a record),publishReadiness(unlessreadiness = false), thePortakiResourceentity and the manifest’sresources[]entry. - command
- Declares a mutating gateway command operation.
- config
- Declares the module’s host configuration: the struct is the schema, the platform the store.
- connector
- Declares use of a built-in platform connector (manifest reference only).
- connector_
op - Declares one HTTP operation on the most recently emitted custom connector, or a validator stub.
- custom_
connector - Declares a custom HTTP connector implemented by the module.
- Declares an email the command sends, so the manifest lists it without anyone writing JSON.
- email_
blocks - Declares the blocks a module adds to Portaki stay emails, per email.
- email_
vars - Declares the variables a module gives Portaki guest emails, per template, on the function that computes them.
- entity
- Declares a persistent entity schema for Atlas and
host::repo. - entity_
indexes - Declares repository indexes for an entity (Atlas spatial/field indexes).
- event_
handler - Declares a subscription to a platform event type.
- item
- A row type of a declared collection (
unstable), or withmetaits settings. Each#[field(label = "…", required, max_chars = N, between(a, b), description = "…")]is declared: kind from the Rust type (I18nText,String,bool, numbers, a#[choice]enum;kind = "time_range"on aString). Addsid, the derives,#[serde(default)], andportaki_sdk::resource::Item(orMeta).key = "title": the natural key an import dedupes on. - nav
- Declares a host dashboard entry that no surface renders.
- params
- Describes the arguments of a query or command, so tooling can offer a form for them.
- portaki_
module - Declares module identity and bootstraps Wasm exports.
- query
- Declares a read-only gateway query operation.
- record
- A record the SDK stores (
unstable): what a guest deposits during a stay and the host follows.#[record(name = "reports", item = Report, status = ReportStatus, due_hours = 24, task_title = "…", task_done = "…", hooks)]on a unit struct. Generateslist/for_stay/get, the commandssubmit(guest),add,setStatus,note, the querylistForStay, the timeline contract whendue_hoursis set, and the entity. Withhooks, the module implementsportaki_sdk::resource::RecordHooks(guard, on_created, on_note). - surface
- Declares a host or guest SDUI surface renderer.
- wire
- Marks a struct or enum as a Portaki wire JSON DTO (gateway / SDUI / events / email).