Native API reference
The tables map the intended application-facing APIs in SDK 0.3.0. TypeScript imports core/workflow symbols from @aiws/sdk, Rust from aiws_sdk plus its modules, and Python from aiws or aiws.core plus its modules. Source definitions and the shared schema are included in the source download.
Core values and functions
Section titled “Core values and functions”| Purpose | TypeScript | Rust | Python |
|---|---|---|---|
| Checked contract from JSON text | parseContract(text): Contract | Contract::parse(text) → Result<Contract> | parse_contract(text) → dict |
| Checked command from JSON text | parseCommand(text): Command | Command::parse(text) → Result<Command> | parse_command(text) → dict |
| Strict JSON | parseStrict(text) | parse_strict(text) → Result<Value> | parse_strict(text) |
| Validate named record | validate(name, value) returns value | validate(name, &value) → Result<()> | validate(name, value) returns value |
| Canonical JSON | canonical(value): string | canonical(&value) → Result<String> | canonical(value) → str |
| Action fingerprint | fingerprint(action): string | fingerprint(&action) → Result<String> | fingerprint(action) → str |
| General canonical digest | sqlite.digest(value) | digest(&value) → Result<String> | core.digest(value) → str |
| Compare delegation | compareGrants(parent, child) | compare_grants(&parent, &child) → Containment | compare_grants(parent, child) |
| Create state | createMission(contract): Snapshot | create_mission(&contract) → Result<Snapshot> | create_mission(contract) → dict |
| Apply pure command | reduce(state, command, nowMs) | reduce(&state, &command, now_ms) → Result<Snapshot> | reduce(state, command, now_ms) |
| Assess completed result | assessSuccess(state, runId) | assess_success(&state, run_id) → Result<Value> | assess_success(state, run_id) |
| Replay events | auditPlayback(contract, events) | audit_playback(&contract, &events) → Result<Snapshot> | audit_playback(contract, events) |
| Compile a data validator | dataValidator(schema): (data) → boolean | data_validator(&schema) → Result<Validator> | data_validator(schema) → Draft202012Validator |
| Enforce a data schema | validateData(schema, data): void | validate_data(&schema, &data) → Result<()> | validate_data(schema, data) → None |
The Rust checked records also expose from_value(Value), parse(&str) and as_value(). These include Contract, Command, Grant, Approval, Action, TriggerDefinition, TriggerEvent and WorkflowGraph. Snapshot offers as_value() for inspection, rather than public mutable fields. TypeScript types and Python dictionary aliases still require runtime validation for untrusted input.
Containment is CONTAINED, NOT_CONTAINED or INDETERMINATE. Only confirmed containment permits delegated scope. Pure reduction returns a new snapshot; a rejected command must not advance its revision. Result assessment returns verifiedSuccessful and reasons; do not infer success solely from one terminal-state string.
Protocol correlation helpers
Section titled “Protocol correlation helpers”These helpers are current source additions after the previously built SDK 0.3.0 binary baseline. They correlate governed AIWS/Praxis identity with an external protocol binding; they do not implement protocol transport and cannot grant authority.
| Purpose | TypeScript | Rust | Python |
|---|---|---|---|
| Binding identity record | ProtocolBindingRef |
ProtocolBindingRef |
validated dictionary passed to protocol_correlation |
| Operation/remote identity record | ProtocolOperationRef |
ProtocolOperationRef |
validated dictionary passed to protocol_correlation |
| Build checked correlation | protocolCorrelation(binding, operation) |
protocol_correlation(binding, operation) |
protocol_correlation(binding, operation) |
| Validate existing correlation | validateProtocolCorrelation(value) |
validate_protocol_correlation(&value) |
validate_protocol_correlation(value) |
Every checked correlation has profile aiws-protocol-correlation/1 and literal authoritative: false. The record contains binding ID/revision, exact protocol/version, manifest/capability digests, local work/run/task/operation/attempt identity and optional remote identity/operation references. It has no dispatch, cancellation, reconciliation, verification or acceptance method.
Workflow helpers
Section titled “Workflow helpers”| TypeScript | Rust | Python | Result and ownership |
|---|---|---|---|
| validateGraph(value) | workflow::validate_graph(&value) | workflow.validate_graph(value) | Checked graph; structural and semantic validation |
| readyNodes(state, runId) | workflow::ready_nodes(&state, run_id) | workflow.ready_nodes(state, run_id) | Eligible node IDs; no dispatch |
| dueSlots(start, interval, nextSlot, now, policy, limit) | workflow::due_slots(start, interval, next_slot, now, policy, limit) | workflow.due_slots(start, interval, next_slot, now, policy, limit) | Low-level due-slot calculation; use tickTrigger for durable cursor/admission semantics |
The slot helper has language-specific low-level numeric types. It is not a cross-language wire command. Applications normally use tickTrigger, which commits admission with the cursor, rather than independently computing slots and guessing a persisted state update.
SQLite store
Section titled “SQLite store”| Operation | TypeScript | Rust | Python |
|---|---|---|---|
| Create/verify mission database | new SqliteStore(path, contract) | SqliteStore::open(path, Some(&contract)) | SqliteStore(path, contract) |
| Reopen existing mission | new SqliteStore(path) | SqliteStore::open(path, None) | SqliteStore(path) |
| Read verified state | store.snapshot() | store.snapshot()? | store.snapshot() |
| Commit a trusted command | store.apply(command, nowMs, expectedRevision?) | store.apply(&command, now_ms, expected_revision)? | store.apply(command, now_ms, expected_revision=None) |
| Export audit text | store.exportAudit() | store.export_audit()? | store.export_audit() |
| Replay audit text | importAudit(text) from /sqlite | sqlite::import_audit(text)? | sqlite.import_audit(text) |
| Read rejection stream | store.diagnostics() | store.diagnostics()? | store.diagnostics() |
| Release resources | store.close() | Drop store after outstanding work finishes | store.close() or a with block |
apply returns the committed Snapshot. Expected revisions are decimal strings (Option<&str> in Rust); a mismatch is REVISION_CONFLICT. Reload and reevaluate policy before retrying a changed-state command. A pre-commit hook is available for fault-injection tests: TypeScript/Python use the extra beforeCommit/before_commit argument, Rust uses apply_with_hook. It is not a public transaction handle for atomically inserting a custom engine queue.
recordRejection/record_rejection writes a protected diagnostic record and telemetry intent. It does not authorize a command or advance mission revision. Most applications let Coordinator use this hook; avoid arbitrary user-provided diagnostic content. Telemetry methods and their arguments are listed under observability.
Coordinator and adapters
Section titled “Coordinator and adapters”| Operation | TypeScript | Rust | Python |
|---|---|---|---|
| Construct | new Coordinator(store, authorize, clock) | Coordinator::new(store, authorizer, clock) | Coordinator(store, authorize, clock) |
| Authorized command | await coordinator.apply(command, expectedRevision?) | coordinator.apply(&command, expected)? | coordinator.apply(command, expected_revision=None) |
| Execute admitted attempt | await coordinator.dispatch(attemptId, adapter, nodeId?) | coordinator.dispatch(attempt_id, &mut adapter, node_id)? | coordinator.dispatch(attempt_id, adapter, node_id=None) |
| Read back uncertainty | await coordinator.reconcile(attemptId, adapter) | coordinator.reconcile(attempt_id, &mut adapter)? | coordinator.reconcile(attempt_id, adapter) |
| Continue with ownership boundary | await coordinator.recover(runId, segmentId) | coordinator.recover(run_id, segment_id)? | coordinator.recover(run_id, segment_id) |
apply, dispatch and reconcile return a Snapshot. recover returns {state, unresolved} in TypeScript and Python, and a (Snapshot, Vec<String>) tuple in Rust. It records a new continuation segment and reports unresolved attempt IDs; it does not call the adapter or decide that a machine should restart automatically.
Authorization contains allowed, policy, mandatoryChecksOk and context. Context requires actor, policyRevision and decisionClass. The host supplies authenticated identity and returns a current decision. The clock returns UTC epoch milliseconds as a canonical decimal string. Rust uses Authorizer and Clock traits; Python uses a callable; TypeScript uses a promise-returning callback.
EffectAdapter.execute performs the side effect. EffectAdapter.reconcile reads external state without repeating the side effect. Both return Outcome with effect = CONFIRMED_APPLIED, CONFIRMED_NOT_APPLIED or UNKNOWN, and actualCost as a decimal string. TypeScript methods return promises; Rust and Python are synchronous. A thrown execute error becomes UNKNOWN, preserving exposure; a failed reconciliation remains an intervention problem, not permission to execute again.
Errors and concurrency
Section titled “Errors and concurrency”TypeScript and Python raise AiwsError with code; Rust returns Result with AiwsError.code. I/O failures can also require host-level handling. Build error handling around phase, committed state and the stable code, not around matching a stack trace. Read troubleshooting before deciding that an exception is safe to retry.
Async TypeScript does not make SQLite calls nonblocking: DatabaseSync blocks its thread. Use suitable workers for synchronous database or adapter calls in a server. Do not share a Python SQLite connection across arbitrary threads or assume the Rust coordinator is a distributed execution lock. All three implementations require an application concurrency and ownership design.
M3 source: nested resource ledger
Section titled “M3 source: nested resource ledger”Import TypeScript LimitStore/LimitCoordinator from @aiws/sdk/limits, Python equivalents from aiws.limits_store, and Rust equivalents from aiws_sdk::limits_store. Pure transitions are in the corresponding limits module. LimitStore(path, config) (Rust LimitStore::open) initializes a human-approved immutable scope tree; reopen without config to replay. snapshot, apply, report and exportEvents (Python/Rust export_events) expose committed state, commands, deterministic exhaustion reports and journal evidence.
Commands: reserve, dispatch, release, unknown, stop, settle and adjust. Request fields are requestId, expectedRevision and command. Raw apply is a trusted/offline interface; use the coordinator for application requests. Authorizers bind actor identity, current policy, scope/purpose, ownership and evidence to the exact command. Stop/settle need evidence; uncertain-outcome resolution and limit adjustments need authenticated humans. See budgets for equivalent executable examples, accounting rules and required host ordering.