AISDL Runtime Implementor Guide#

An AISDL Runtime executes an approved System specification. It supplies the technical environment; the System supplies business behavior. An implementation may compile, translate or interpret AIScript, but its observable behavior must match the reference.

This guide organizes implementation responsibilities derived from the current AISDL and AIScript references. It does not introduce another authoring API or prescribe a host language, database product or infrastructure vendor. It is an implementation guide, not an independent certification program.

1. Start With The Contract#

Read the AISDL reference, System Design, the seven resource schemas, the AIScript language and Database Queries.

The resource schemas define document structure; the accompanying explanations and AIScript interfaces define meaning. Passing schema validation alone does not establish correct execution. Examples illustrate the contract, not additional interfaces. Report a contradiction rather than invent behavior to resolve it.

2. Accept A Connected System#

The authored System is a folder containing manifest.json and named resources. Preserve source contents and an identifiable revision. Resource names are unique within their type and references are case-sensitive.

Before activation, check that declared resources, implementation files and references exist; fields and mappings agree with their contracts; and declared Process, Service, Collection, Secret and Event dependencies can be resolved. Process presentations also contain Process references. Do not repair or redesign business behavior silently during compilation.

Keep authored specifications separate from generated execution artifacts. A generated endpoint or listener is infrastructure output, not a second business codebase to maintain.

3. Preserve Language Semantics#

The AIScript reference defines the grammar and all callable interfaces. Support its function-local variables, explicit arguments, checked types and defined evaluation order. Helpers do not implicitly capture a caller's local variables.

Preserve integer range checks, decimal calculation behavior, rounding rules, null handling, object copying, array bounds and statement-only operations. Do not substitute host-language truthiness, floating-point shortcuts, prototype methods or host exception behavior.

Executable statements belong inside functions. execute(input) implements its Process contract; helpers may appear before or after it. Return values, failures and cleanup must retain their specified meaning through the complete function-call chain.

4. Own The Execution Scope#

Create the correct execution context for each invocation. Validate Inputs and ensure successful Outputs match the declared contract. Service and Record handles are not serializable business results.

Execution-owned Service instances and cursors follow the reference's lifecycle. Do not expose host resources to Process code or require authors to close runtime-owned handles manually. Cleanup must not replace a failure already propagating with an unrelated secondary failure.

Direct child Process calls share the execution transaction; they do not create an independent durable commit. External Service effects do not roll back with database work. Preserve this distinction across compilation and execution, including when a failure is caught.

5. Mediate Services#

All capabilities are acquired by declared Service name inside functions. Database, HTTP, TCP, storage, local cache, shared cache, SMTP, messaging and secrets use the same declaration and lookup model. A name is not permission to invent an implementation or undocumented methods.

Implement the documented method signatures, defaults, argument order and result types. Keep deployment-specific connection details outside authored business logic. Configuration type identifiers in Service definitions identify supported adapters; they are not permission to replace their observable interface with another API.

Preserve the documented data-to-bytes conversions. A signed payload and the sent payload must use the same bytes. Verify received signatures against original bytes rather than a parsed and reserialized approximation.

For TCP, implement the selected framing and field encodings as specified; a network read is not inherently a complete message. For HTTP, preserve the distinction between a remote unsuccessful response and an execution failure.

6. Preserve Data And Transaction Behavior#

Implement projections, references, parameter binding, condition snippets, functions, ordering, aggregation and paging according to Database Queries. Loading a Record must not silently fetch unselected fields when code accesses them.

The single-record path is load, change or remove fields, then save. db.update applies bulk changes. Preserve locking and rollback-only behavior where required by the reference. Soft deletion of business records is distinct from physical database administration.

File metadata is data, not file contents or a storage handle. Shared storage has reserved upload and cdn areas. Finalization, metadata, retrieval authorization and byte access must remain distinct. Do not treat an arbitrary filename supplied by a client as authorization to read a host path.

7. Keep Authentication And Business Logic Separate#

The runtime supplies identity and access administration. A Process declares its Audience, incoming authentication method and allowed channels; these concepts are not interchangeable. An Audience association does not grant access.

Preserve channel semantics: omission means all channels; an empty array means none. Preserve the difference between authenticating a token and verifying a request signature. A verified signature does not, by itself, establish a human principal or business-party membership.

Apply deployment-approved credentials and policy without making the AI author guess confidential values. Secret references use the documented security.secrets. convention. Do not place secret values in authored resources, browser presentations, responses or diagnostic output.

8. Implement Async, Events And Scheduling#

Implement async capture, ownership, execution boundaries, result handling and failures exactly as described by AIScript. Do not implement async as a textual rewrite that accidentally shares mutable state or a transaction across separate executions.

Events define business payloads and consumer Input mappings. The runtime provides transport and listener installation. Redelivery is possible; do not advertise exactly-once business outcomes merely because a publish call succeeds.

Scheduling is Process invocation configuration, not a second authored listener program. Document actual overlap, failure and missed-run behavior. Publication and operational configuration must not introduce promises absent from the reference. Business recovery remains an authored Process responsibility.

9. Render Process Apps Through Processes#

Render presentation according to the Process reference and schema. Forms, lookups, actions, lists, metrics, charts and viewers use real typed Process contracts. Do not create direct browser access to a database or Service as a presentation shortcut.

Retain mappings and dependencies for lookup searches, selection resolution and navigation. Presented field labels and actual values must remain distinct. Protect file access and user-originated content; a viewer must not turn an uploaded document into executable application code.

10. Verify Before Claiming Support#

A supported feature needs evidence, not only a parser branch. Maintain a version-specific support matrix and a reproducible conformance test suite. State unsupported features precisely rather than accepting source and dropping its behavior.

Area Minimum test coverage
Resources Valid and invalid schemas; missing references; duplicate names; dependency mappings.
Language Grammar boundaries; evaluation order; numeric edges; nulls; type errors; array mutation.
Execution Helper calls; isolation between invocations; scoped handles; cleanup and failure preservation.
Data Projections; filtering; snippets; groups; aggregates; paging; locks; rollback behavior.
Services Exact calls and conversions; timeout handling; framing; permission denials; secret redaction.
Async and Events Capture boundaries; independent execution; redelivery; failure paths and recovery.
Presentations Real Process invocation; lookup dependencies; action mappings; uploads and authorized viewers.
Security Host-access attempts; unintended effects; tenant isolation; resource exhaustion; configuration boundaries.
Revisions Stable source identity; activation controls; traceable generated artifacts; migration and in-flight-work policy.

The last two rows include operational assurance work around the language contract. Passing language examples alone is not a security audit or industry certification. Publish failures and limitations with the results; do not imply that an implementation has passed independent assessment when it has not.

The Implementation Boundary#

AISDL leaves the business design to its author. The implementation preserves meaning, supplies supported Services and controls execution. It must not become another business-design agent that silently changes the System during publication.

Extensions And Provider Compatibility#

Use the Extensions And Compatibility framework for additional utilities and Services. Publish their exact interfaces and behavior before the AI designs with them. Preserve effect mediation and resource policy across extensions; an extension cannot provide an escape to unrestricted host operations.

Identify supported reference versions, optional extensions and adapter profiles in a compatibility record. The current reference includes concrete adapter identifiers and JVM-local cache terminology. These describe a compatibility profile, not a requirement that every AISDL Runtime use the same host language or backend. A different implementation must establish equivalent behavior explicitly, not ignore the identifiers.

Portability requires compatible observable semantics and a migration plan for data, history, credentials, policies, integrations and in-flight work. Publish tested support and limitations. Do not equate a matching parser with Runtime conformance.

Search AISDL

Search the paper, references and examples.