Intrepid/prometeu-studio
Intrepid/prometeu-studio
3
0
Fork 0
Code Pull Requests 1 Activity
prometeu-studio/discussion/workflow/decisions/DEC-0013-pbs-sdk-executable-service-bodies.md

7.7 KiB
Raw Blame History

id ticket title status created accepted agenda plans tags
DEC-0013 pbs-service-facade-reserved-metadata Executable SDK Service Bodies for Builtin/Intrinsic-Backed Public Services accepted 2026-04-03 2026-04-03 AGD-0016
PLN-0029
compiler
pbs
sdk
stdlib
lowering
service
intrinsic
sdk-interface

Decision

Domain owner: compiler/pbs

The PBS compiler SHALL support a restricted executable-service model inside SDK_INTERFACE sources.

Under this model:

  1. public SDK service methods MAY contain ordinary PBS executable bodies;
  2. those bodies MAY call reserved hosts, reserved builtin const proxies, and reserved intrinsic-backed values;
  3. imported user callsites to eligible SDK service methods SHALL lower as ordinary callable invocations of the SDK service method body;
  4. intrinsic lowering SHALL occur inside the lowered SDK service body when the body calls the private reserved proxy;
  5. public user code MUST NOT be required to import or reference the private reserved proxy directly.

This decision explicitly rejects the requirement that intrinsic-backed public SDK services MUST lower directly from the user callsite to CALL_INTRINSIC.

For eligible SDK service methods, the normative lowering model is:

  • public user callsite lowers as callable/service method invocation;
  • imported SDK service body lowers as executable PBS code;
  • reserved proxy calls inside that body lower through the existing intrinsic or host machinery;
  • returned values preserve the owner and chaining semantics established by the lowered reserved operation.

@sdk:input SHALL be supported by this model. A service body such as:

declare service Input {
  fn touch() -> InputTouch {
    let touch = LowInput.touch();
    return touch;
  }
}

MUST be valid as ordinary SDK service code, provided it remains within the supported restricted subset defined below.

Rationale

This decision matches the intended SDK API shape:

  • public SDK surfaces such as Input should be expressed as services when that is the product-facing abstraction;
  • private reserved builtins and builtin const proxies should remain implementation details;
  • SDK authors must be allowed to write normal service bodies with locals and intermediate processing rather than being forced into synthetic facade metadata or direct public builtin roots.

The alternative of explicit facade metadata on public service methods was rejected because it creates a second semantic class of services that only imitate ordinary PBS code. The alternative of keeping intrinsic roots public was rejected because it leaks reserved implementation surfaces into the user API.

Technical Specification

1. Eligible Surface

The compiler SHALL define an explicit category of eligible executable SDK service methods.

An eligible executable SDK service method:

  1. MUST be declared in a SourceKind.SDK_INTERFACE module;
  2. MUST belong to a service declaration;
  3. MUST remain within the restricted executable subset defined by compiler validation;
  4. MUST be importable as a callable body by user modules.

Non-eligible declarations in SDK_INTERFACE MUST continue to follow the existing non-executable interface rules.

2. SDK Interface Execution Boundary

SDK_INTERFACE SHALL remain non-executable by default.

The compiler SHALL introduce a narrow exception for eligible SDK service methods only. This exception MUST NOT implicitly generalize to arbitrary interface-level functions, globals, or unrestricted executable declarations.

3. Import Model

When a user module imports a public SDK service:

  1. the imported semantic surface MUST continue to expose the service method signatures;
  2. the lowering pipeline MUST also have access to the executable body of each eligible imported SDK service method;
  3. a user callsite such as Input.touch() MUST be lowerable as an ordinary callable invocation of the imported SDK service method.

The compiler MUST NOT require special public facade metadata to connect the user callsite to the reserved intrinsic owner when the service body already expresses the call explicitly.

4. Lowering Model

For an eligible imported SDK service method:

  1. the public callsite SHALL lower as a callable invocation;
  2. the imported SDK service body SHALL be lowered with the same executable-body discipline applied to ordinary PBS executable code, subject to the restricted subset;
  3. calls inside that body to reserved hosts SHALL continue to use host lowering;
  4. calls inside that body to reserved builtin const proxies SHALL continue to use intrinsic lowering;
  5. any returned reserved value SHALL preserve the return owner and chaining semantics inferred from the lowered reserved call.

As a result:

  • Input.touch() MAY lower to a callable invocation of the imported SDK method;
  • LowInput.touch() inside the SDK body SHALL lower to the intrinsic owner input.touch;
  • chained user code such as Input.touch().x() and Input.pad().a().pressed() MUST remain valid when the returned owner chain is supported by the reserved metadata.

5. Restricted Executable Subset

The compiler SHALL validate eligible executable SDK service methods against an explicit restricted subset.

At minimum, the first supported subset MUST permit:

  • local bindings;
  • ordinary return statements;
  • calls to reserved hosts;
  • calls to reserved builtin const proxies and their intrinsic-return values;
  • straightforward expression composition needed for wrapper-style service methods.

The first supported subset MUST NOT silently permit unsupported executable constructs. If a construct is outside the supported subset, the compiler MUST emit a dedicated diagnostic.

Whether control flow beyond straightforward wrapper composition is included in the first wave SHALL be decided in planning and implementation, but the compiler MUST validate the boundary explicitly rather than relying on accidental behavior.

6. Diagnostics

The compiler SHALL add dedicated diagnostics for executable SDK service bodies that cannot be imported or lowered safely.

These diagnostics MUST distinguish this failure mode from generic unresolved callee failures.

At minimum, diagnostics SHALL cover:

  • SDK service bodies that use unsupported executable constructs;
  • imported SDK service methods that are not eligible for executable lowering;
  • inconsistencies between an imported SDK service signature and the lowered executable body shape;
  • reserved proxy use that cannot preserve required return-owner or chaining behavior.

7. Tests and Conformance

The compiler test suite SHALL be updated to reflect the new normative model.

Tests MUST cover:

  1. public SDK service callsites lowering successfully as callable invocations;
  2. intrinsic lowering occurring inside the imported SDK service body;
  3. returned reserved owners preserving chained method access for values such as InputTouch and InputPad;
  4. use of locals and intermediate processing inside SDK service bodies;
  5. dedicated diagnostics for unsupported executable SDK service bodies.

Existing tests that assume the public Input callsite itself MUST resolve directly to an intrinsic SHALL be revised to match this decision.

Constraints

  • This decision applies to compiler/pbs and to SDK surfaces loaded through SDK_INTERFACE.
  • This decision does not authorize arbitrary executable code throughout interface modules.
  • This decision does not require public exposure of private reserved builtin roots.
  • This decision does not replace the existing host-backed SDK service model; it extends the compiler so intrinsic-backed SDK services can use ordinary service bodies.
  • Any future extension of the restricted executable subset MUST be treated as a follow-up decision or explicit revision if it changes the initial boundary materially.

Revision Log

  • 2026-04-03: Initial draft from AGD-0016.