How closely does this model match Temporal?

Start with the architecture map for startup, service boundaries, and transport status.

The ownership split is useful; the implementation is not a scaled-down copy. Read the toy to learn which component makes a decision, then follow the corresponding OSS path below. A class name here is a conceptual counterpart, not a promise that the Go package has the same shape.

Alignment check — 2026-10-04: internal RPC

Findings 4 and 5 below are resolved.

• Roles call each other only over RPC. Requests and responses are upstream's generated historyservice and matchingservice messages (api/, from proto/internal at 39bffa99), sent as proto3 JSON over Effect RPC. No role imports another role; the dependency rules enforce it. Shared-process and separate-process deployments use the same calls (pnpm start --service history).
• History shards are leased. Each History host takes a shard's range-ID lease before serving it, and every execution write is fenced by that lease in memory and PostgreSQL (migration 005). A replaced lease fails the old host's write with ShardOwnershipLost, which names the new owner; HistoryClient retries there. test/cluster.test.ts and test/postgres.integration.ts exercise both paths.
• Matching routes and forwards across hosts. MatchingClient routes by partition owner. Forwarded adds and polls use AddWorkflowTask with forward_info and PollWorkflowTaskQueue with forwarded_source, and a forwarded poll waits at the root host. Cancelling the caller interrupts every hop.
• Poll responses come from History's start response. RecordWorkflowTaskStarted returns the workflow type, event IDs, and history; RecordActivityTaskStarted returns the scheduled event. Matching builds the poll response and task token from them; Frontend only translates. Matching task records no longer carry activity names or inputs.

Remaining differences: the internal transport is Effect RPC framing, not gRPC; tokens are proto3 JSON rather than protobuf bytes; History keeps its internal event log and builds public events at its boundary, so tokens carry internal scheduled-event IDs. Membership is static and hashes by modulo; there is no host failure detection or graceful handoff. The toy uses namespace names where upstream uses namespace IDs.

Alignment check — 2026-10-03

Reviewed tiny-temporal 8a8b9fb against the local Temporal checkout at 39bffa99f0e0252fefb794f6a0cb571464187fca. The DeepWiki architecture overview was used for orientation; the pinned Go implementation is the authority for the comparisons below. This is an architectural review, not a claim of feature or database compatibility.

Assessment: the service responsibilities and top-level layout align. The three reproduced Matching gaps below are now corrected, with regression tests in memory and PostgreSQL. Internal deployment/shard ownership and poll-response assembly remain simplified.

1. Deployment routing — corrected

History now supplies a version directive with each transfer. Matching stores auto tasks in the default physical queue and chooses the deployment when dispatching, using the routing visible to that partition. Pinned tasks remain in their version's queue. Matching no longer reads the whole execution to select a deployment.

This follows upstream's separation of immediate dispatch and backlog storage in AddTask and queue selection.

test/versioning.test.ts backlogs work under v1, changes the current deployment to v2, and verifies auto work reaches v2 while pinned work reaches v1. It also checks stale activity-partition routing until propagation. The PostgreSQL integration repeats deployment selection after rebuilding all server layers. Migration 004 and memory snapshot restore upgrade old version-bound backlog without overwriting destination task IDs.

Limits: this teaches storage versus dispatch routing, not the complete worker-versioning protocol. History.setVersioning is a lab control that updates outstanding transfer directives; it does not invalidate already-spooled or running tasks. Public SDK deployment/versioning APIs and production version-transition validation are not implemented.

2. Child backlog ownership and forwarding — corrected

Normal child partitions now have their own matcher and durable backlog. Adds try local and parent sync matching; an unsuccessful forward spools only at the originating child. Backlog readers retry parent matching and acknowledge the origin after History accepts delivery. Forwarded polls share one completion and deadline across all hops; delivery, cancellation, or unload removes every registration. Unsupported sticky operations are rejected.

This preserves the ownership rule in upstream ForwardTask and forwarded-task fallback. test/polling.test.ts verifies child retention, retryable start failure, ancestor delivery, multi-hop poll cleanup, and sticky rejection. PostgreSQL tests rediscover child backlog after restart with only a root poller.

Limits: parent selection uses a fixed binary tree; forwarding was then local Effect calls (RPC since 2026-10-04). The reader scans stored queues rather than running distributed, paginated readers. Ordinary SDK calls still use the root partition; partition selection is an internal lab API.

3. Persistent user-data version checks — corrected

Both stores now compare the expected version during the write. PostgreSQL uses conditional insert/update and reports UserDataConflict when another manager wins. The local semaphore still protects one manager's cache and migration flags; the database comparison protects against independent managers. This follows upstream task_user_data.go.

test/user-data-concurrency-contract.ts synchronizes two independent managers after reading version 0 and requires exactly one successful write. It also races updates to an existing row. The contract runs against memory and separate PostgreSQL pools.

Limits: the draft CHASM exercise still writes two stores sequentially. Each write checks its version, but the pair is not atomic and can require reconciliation after a partial failure. It does not model CHASM replication or distributed rollout.

4. Deployment and shard boundaries are conceptual — resolved 2026-10-04, see above

One entrypoint hosting several roles is consistent with upstream's DefaultServices. However, upstream keeps internal service RPC boundaries even when roles share a process. The toy directly injects History and Matching; only public Frontend calls cross a network. Four recorded History shard labels share one engine and one SQL partition lock. Membership host labels do not start or route to independent hosts.

This is adequate for tracing responsibilities, but does not exercise internal protobuf contracts, per-shard engines/leases, remote errors, retries, or independent service deployment. Network listeners alone would not supply those semantics.

5. Poll-response assembly sits in a different role — resolved 2026-10-04, see above

The toy's former workflow-service.ts obtained a task from Matching, then read the full execution through Frontend and constructed the poll response. Upstream Matching records the start in History and builds its internal poll response from the returned state/history; Frontend translates that response to the public API. See createPollWorkflowTaskQueueResponse.

The essential start-before-delivery invariant is preserved. For a closer service boundary, Matching should return the task plus the data obtained from History's start operation, with Frontend retaining public wire encoding. Returning only a QueueTask obscures that contract.

Structure and persistence conclusions

• cmd/server, temporal, service/{frontend,history,matching,worker}, and common/persistence follow the useful upstream boundaries. Keeping service interfaces with their Effect layers is a reasonable TypeScript adaptation of Go interfaces and Fx modules.
• common/src/state.ts consolidates concepts spread upstream across api/persistence, api/taskqueue, api/token, common/tqid, and History workflow state. It is a shared teaching vocabulary, not a wire protocol package or a literal upstream directory equivalent.
• Matching correctly keeps durable backlog/range/ack metadata separate from loaded managers and waiting polls. Its scalar acknowledgement model corresponds to the FIFO-style ackManager, not the complete priority/fairness backlog implementations. Per-task checkpoint/delete and consecutive task IDs simplify upstream checkpointing, garbage collection, and range allocation.
• History owns execution transitions and generated transfer/timer/visibility work. Visibility is a storage projection, and SDK workflow execution remains outside the server. These are useful, preserved ownership rules.
• JSONB events, history_partition, and separate toy task tables are intentionally inspectable representations. They do not reproduce upstream history branches, serialized mutable-state maps, history_immediate_tasks / history_scheduled_tasks, or all Matching v2 tables.
• The internal Worker is a scanner sketch. CHASM migration, scaling, and fairness exercises must be read with their explicit limits; they are not evidence of corresponding production systems.

Next alignment work: refine the Matching/History poll result so History returns the state used for delivery as part of recording the start. Internal RPC deployment and real shard ownership are a larger, separate step.

Verification of these corrections

On 2026-10-03, pnpm check passed TypeScript, 83 tests, and the stock SDK retry/timer/signal/result and worker-crash integration. pnpm test:postgres passed the migration, concurrent-write, restart-routing, and process-crash checks described above. A separate stock SDK run against tiny_temporal completed official-greeting-1791082108880 (run-43). SQL inspection confirmed migration 004, 19 saved events, result Hello Ada: approved, completed visibility, and no remaining Matching or transfer tasks for that run. These checks cover the implemented subset, not upstream conformance.

Trace one activity

sequenceDiagram
  participant SDK as SDK Worker
  participant F as Frontend
  participant M as Matching
  participant H as History
  participant Q as History queue processor
  SDK->>F: PollWorkflowTaskQueue
  F->>M: PollWorkflowTaskQueue
  M->>H: RecordWorkflowTaskStarted
  M-->>F: task + history
  F-->>SDK: task + history
  SDK->>F: RespondWorkflowTaskCompleted(schedule activity)
  F->>H: RespondWorkflowTaskCompleted
  H->>Q: transfer task
  Q->>M: AddActivityTask
  SDK->>F: PollActivityTaskQueue
  F->>M: PollActivityTaskQueue
  M->>H: RecordActivityTaskStarted
  M-->>F: activity task
  F-->>SDK: activity task
  SDK->>F: RespondActivityTaskCompleted
  F->>H: RespondActivityTaskCompleted

This diagram shows the upstream response contract, which the toy now follows: every arrow between server roles is a generated historyservice or matchingservice RPC, and Matching returns the task with the data History supplied when it recorded the start. Compare the pinned OSS workflow lifecycle diagrams with docs/walkthrough.md, or run pnpm wire to print the calls.

Where the mapping breaks

1. Storage shape: Database still puts executions, embedded event arrays, History tasks, shard leases, Matching backlog, user data, and visibility in one object. The per-service stores (ExecutionStore, TaskStore, VisibilityStore, NamespaceStore) make ownership a capability each service must be granted, without requiring separate physical databases. The PostgreSQL adapter separates records into tables, and still takes one global lock in addition to the shard row it fences. OSS has ExecutionManager and TaskManager and distinct SQL rows for executions, history, and queues. See the pinned SQL schema.
2. Identity and placement: History shards and Matching partitions have owners, leases, and fencing, but membership is a static list hashed by modulo. Only the root partition serves ordinary worker calls unless the Matching client is given more partitions; the forwarding tree is a fixed binary tree. See Matching architecture.
3. Reliability protocol: History atomically commits state and intents under a shard lease. Matching records starts before delivery; History timeouts recover lost worker attempts. Polls cancel across every RPC hop and task tokens identify attempts. There is no replication, retry backoff, or host failure detection. Activities can execute more than once.
4. Workflow semantics: The generator SDK replays public history one command at a time and interprets signals locally. The optional stock SDK brings its real sandbox and Core runtime through a bounded protocol subset. Updates, child workflows, cancellation, replication, and CHASM runtime remain outside the model.
5. Source structure: cmd/server configures startup, temporal composes one layer graph per host, and each service/*/src/service.ts owns that role's listener and loops. api/ holds generated contracts; proto/ owns the generator; client/ holds the routed clients. In this model, role packages never import each other and common cannot import services or clients (stricter than upstream’s shared Go helper/task packages), and generated code depends only on Effect and local API declarations. Private pnpm workspaces, explicit exports, project references, and dependency-cruiser enforce these boundaries, including type-only imports.

The polling and lifecycle walkthrough shows what happens to waiting polls and in-flight activities when a partition unloads. Each host's Effect scope serves the lifecycle role of upstream service Start/Stop hooks.

For a Matching-to-Walker migration, the toy is most useful for identifying the contract to preserve: History sends tasks; Matching owns task-queue delivery; Frontend routes worker polls; Matching calls History to record starts; Matching's durable backlog and metadata live behind persistence interfaces. It cannot tell you which Walker processes, storage APIs, rollout controls, or hosted-only behaviors to change. Those require reading the Walker and SaaS code directly.

Read the Matching lifecycle lab for current OSS boundaries and a separately labeled exercise based on the proposed CHASM user-data migration.

Review against the upstream architecture assets

Reviewed on 2026-10-05 against the local temporal/architecture-review directory, its generator sources, and the referenced Go code. The core service responsibilities and ordinary workflow-task path align; the import graph and persistence layout are not literal replicas. The generated import inventory reports 159 OSS packages, 9 SaaS packages, and 62 direct internal Matching imports. These are selected packages from that checkout, not the complete Temporal repository or the toy's pinned protobuf revision.

What each asset establishes

Actual runtime correspondence

This is a source-reviewed responsibility diagram, not generated from imports and not a claim that every edge appeared in one trace:

flowchart LR
  SDK[External SDK client / worker] -->|public gRPC| F[Frontend]
  F -->|start, complete, signal, read| H[History]
  F -->|long poll| M[Matching]
  H -->|transfer processor: AddTask| M
  M -->|RecordTaskStarted| H
  M -->|partition forwarding| M
  H -->|state, events, intents; shard fence| ES[ExecutionStore]
  M -->|backlog, metadata, user data; queue fence| TS[TaskStore]
  H -->|asynchronous projection| V[Visibility]
  F -->|list/read| V
  V --> VS[VisibilityStore]

Internal service arrows use generated contracts over Effect RPC here; upstream uses gRPC/protobuf. The embedded teaching SDK calls Frontend through an in-process RPC client; the stock SDK uses public gRPC. The internal Worker is a separate maintenance scanner, not the application worker that polls Frontend.

Evidence in the toy: Frontend handler, History transaction engine, transfer processor, Matching dispatch and forwarding, backlog manager, History start response, and composition. pnpm wire was run during this review and observed start → add workflow task → record workflow-task start → completion → add activity task → record activity-task start → completion. The example filters empty polls and history-result polling, so its output is not a complete distributed trace. Dispatch tests cover rejected transfers and retryable task-start failures.

Corrections and remaining limits

1. Our import policy is stricter than upstream. Upstream Matching imports service/history/api, service/history/hsm/nexusoperations, and service/worker/workerdeployment. Upstream persistence imports service/history/tasks. These are shared code/type dependencies, not in-process calls into another running service. Conversely, Matching receives resource.HistoryClient by injection, so its runtime History calls do not require a direct import of client/history. A source graph is not the service call graph. Our rule remains useful for the smaller model, but must not be described as upstream's exact directory rule.
2. Store ownership has explicit import boundaries. History imports ExecutionStore; Matching imports TaskStore; Frontend uses the visibility manager and namespace registry; the scanner reads several stores. Separate public entrypoints and dependency-cruiser allowlists enforce these imports, including type-only imports. Process composition still supplies a shared persistence layer. This policy is stronger than upstream: Go exports the interfaces from one persistence package and uses typed constructor dependencies, without equivalent per-role visibility restrictions. The import graph does not prove runtime isolation.
3. Storage preserves intent, not physical design or scale. The toy has JSONB records, individual history-event rows, a run-ID-centered schema, two execution foreign keys, and a global History transaction lock in addition to shard fencing. Upstream uses protobuf state, history trees/batches, composite identities, and conditional writes without those foreign keys. Our schema cannot establish upstream throughput, retention, branch behavior, or SQL compatibility.
4. The runtime subset is intentionally smaller. No full worker-deployment control workflows, Nexus/HTTP surface, replication, CHASM runtime, production membership, or complete history-fetch/sticky-cache behavior is implied. The sampled Zinnia poll and the curated ordinary-task diagram describe different paths; neither alone specifies all required behavior.

The review found no reversed ownership or direct cross-service engine call in the implemented task path. It does not establish full Temporal or SaaS equivalence. pnpm deps:graph now generates a side-by-side comparison at three altitudes, pnpm deps:matching opens with Matching's direct neighborhood selected, and pnpm deps:mermaid retains the compact Markdown diagram. All are source-import views; pnpm wire provides an observed execution. Neither substitutes for the other.