Type actor operation references

[cardmagic]

Scheduled watchdogs currently need .recoverIfStuck! and accept misspelled operation names or incorrect arguments. This adds actor-specific schedule/transmit inference and independent checks for literal effect callbacks, and prepares version 0.14.9. Runtime staging and validation remain unchanged.

Addresses #46. Ruby counterpart: solid-objects-ruby#66. Rebased onto main at 00f3929, preserving the payload contracts and documentation merged in #48. The release notes include both typing improvements.

Before:

this.schedule({ at: deadline, key: "watchdog" }).recoverIfStuck!({ generation })

After:

this.schedule({ at: deadline, key: "watchdog" }).recoverIfStuck({ generation })
this.emit("run_model", { arguments: { generation }, onFailure: "failTurn" })

Type compatibility: this retains strict scheduling on the existing methods. Subclasses explicitly overriding schedule or transmit with the broad ScheduledOperations return type must update their override signatures to match the generic Actor methods. The compile-only fixture records that diagnostic; this is a compile-time compatibility change. Normal callers, generic actor/reference use, existing emit overrides, and deliberately dynamic names retain their supported paths.

Receiver inference handles calls inside actor methods, inherited operations, private members, and lifecycle overrides. Both callback literals are checked independently; deliberately widened strings retain runtime validation. Effect and commit-action names remain strings because their registries are runtime-wide. Per-actor registry inference is deferred. The parameter-style checker ignores TypeScript's erased this parameter.

Validation after rebase and version bump:

• pnpm run format:check and pnpm run check pass, including source/type fixtures, examples, documentation, and Cloudflare declarations.
• pnpm test: 377 passed, 21 environment-gated skips.
• pnpm run build, pnpm run test:cloudflare, and pnpm run check:cloudflare pass, including the Wrangler dry run.
• pnpm run test:package passes against the built 0.14.9 tarball, checking both operation and payload contracts through root/core entry points.
• node scripts/release-notes.mjs 0.14.9 produces the combined release notes; package and exported runtime versions match.

The rebase preserves both merged payload examples and operation-reference guidance in docs/api.md. Release preparation updates the PR branch; publishing remains a separate step.

[cardmagic]

@greptileai please review this draft at head 0a8caa4. The broad legacy schedule/transmit override incompatibility is explicitly recorded as a pending user design decision; please check the receiver inference, independent callback constraints, package declarations, and any additional compatibility or correctness gaps.

[greptile-apps]

Greptile Summary

The PR adds actor-specific typing for scheduled and transmitted operations, independently checks literal effect callback names, combines the rebased effect-payload contracts, and prepares release 0.14.9.

• Exports ScheduledOperationsFor, EffectOptions, effect callback payload types, and SerializedError through the root and core entry points.
• Preserves deliberately dynamic operation and callback paths with runtime validation.
• Updates documentation and compile-only fixtures for inferred operations, callback payloads, legacy override compatibility, and installed-package declarations.
• Aligns package, runtime, changelog, and packaged-artifact version metadata at 0.14.9.

Confidence Score: 5/5

The PR appears safe to merge; the combined type surfaces and release metadata are consistent, and no outstanding blocking failure remains.

Root and core exports expose the documented operation and payload contracts, installed-package checks exercise both contract groups, and all checked release metadata agrees on version 0.14.9. The sole previous finding was resolved after Greptile accepted the compatibility rationale, so it is not outstanding.

Important Files Changed

Filename	Overview
src/actor.ts	Adds receiver-sensitive schedule/transmit overloads and independently inferred effect callback options while preserving runtime staging and validation.
src/reference.ts	Introduces the actor-specific scheduled-operation map and excludes lifecycle hooks from callable operation names.
src/types.ts	Exports shared success and failure callback envelope types with serialized errors.
scripts/release-artifact-smoke.mjs	Compiles both operation-reference and effect-payload fixtures against the installed 0.14.9 tarball.
package.json	Advances package metadata to version 0.14.9 consistently with the runtime constant and changelog.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  Actor["Concrete Actor type"] --> Schedule["schedule / transmit"]
  Schedule --> Operations["ScheduledOperationsFor<ActorType>"]
  Operations --> CheckedOperation["Typed operation name and arguments"]
  Actor --> Emit["emit(effect, options)"]
  Emit --> Callbacks["Independently inferred success/failure callbacks"]
  Runtime["Runtime registry validation"] --> Schedule
  Runtime --> Emit
  Package["Root and core entry points"] --> Consumer["Installed-package type fixtures"]
  Operations --> Package
  Callbacks --> Package

Loading

_{Reviews (3): Last reviewed commit: "chore: prepare version 0.14.9" | Re-trigger Greptile}

[cardmagic]

@greptileai please review head 453acef. The new inference annotations use Actor, Pick<this, Keys>, and ignored callback return values. The existing effect-argument Record<string, unknown> contract is preserved as explained in the resolved thread; narrowing that input would violate the requested API compatibility. The separate legacy-override design decision remains pending and this PR remains a draft.

[cardmagic]

@greptileai please review head d41384d after the rebase onto main and 0.14.9 release preparation. The conflict resolutions preserve both payload and operation typing docs and installed-package checks. The documented legacy schedule/transmit override annotation incompatibility remains explicit; please check the combined type surfaces and release metadata.