diff --git a/.memory/alignment_checking/README.md b/.memory/alignment_checking/README.md index 716d627..2899766 100644 --- a/.memory/alignment_checking/README.md +++ b/.memory/alignment_checking/README.md @@ -15,6 +15,8 @@ Python is the reference style (code-first, minimal prose). All languages should - `⚠️ needs work` = has style issues to address - `—` = not started +**Supported languages:** Python (reference), TypeScript, Go (not started), PHP (all reference files created) + ## Section Inventory Legend - `✓` = present @@ -22,7 +24,7 @@ Python is the reference style (code-first, minimal prose). All languages should - `—` = missing, intentional (language doesn't need this) - `TODO` = missing, should add - `DEL` = present, should remove or merge -- `Py#` / `TS#` / `Go#` = section order in file (should monotonically increase if order is aligned) +- `Py#` / `TS#` / `Go#` / `PHP#` = section order in file (should monotonically increase if order is aligned) ## Implementation Status @@ -30,6 +32,8 @@ Python is the reference style (code-first, minimal prose). All languages should **Go:** ✅ COMPLETE (2026-03-17) — All Go reference files created and aligned. +**PHP:** ✅ CONTENT COMPLETE (2026-03-16) — All 11 PHP reference files created. PHP columns present in all tracking files. Correctness verification pending. + ## Files Each file in this directory tracks alignment for a corresponding reference file: diff --git a/.memory/alignment_checking/advanced-features.md b/.memory/alignment_checking/advanced-features.md index 532976f..c20a8e2 100644 --- a/.memory/alignment_checking/advanced-features.md +++ b/.memory/alignment_checking/advanced-features.md @@ -2,22 +2,23 @@ ## Section Inventory -| Section | Core | Python | Py# | TypeScript | TS# | Go | -|---------|------|--------|-----|------------|-----|-----| -| Schedules | — | ✓ | 1 | ✓ | 1 | | -| Async Activity Completion | — | ✓ | 2 | ✓ | 2 | | -| Sandbox Customization | — | ✓ | 3 | — | — | | -| Gevent Compatibility Warning | — | ✓ | 4 | — | — | | -| Worker Tuning | — | ✓ | 5 | ✓ | 3 | | -| Workflow Init Decorator | — | ✓ | 6 | — | — | | -| Workflow Failure Exception Types | — | ✓ | 7 | — | — | | -| Continue-as-New | — | — | — | — | — | | -| Workflow Updates | — | — | — | — | — | | -| Nexus Operations | — | — | — | — | — | | -| Activity Cancellation and Heartbeating | — | — | — | — | — | | -| Sinks | — | — | — | ✓ | 4 | | -| CancellationScope Patterns | — | — | — | — | — | | -| Best Practices | — | — | — | — | — | | +| Section | Core | Python | Py# | TypeScript | TS# | Go | PHP | PHP# | +|---------|------|--------|-----|------------|-----|----|-----|------| +| Schedules | — | ✓ | 1 | ✓ | 1 | | ✓ | 1 | +| Async Activity Completion | — | ✓ | 2 | ✓ | 2 | | ✓ | 2 | +| Sandbox Customization | — | ✓ | 3 | — | — | | — | — | +| Gevent Compatibility Warning | — | ✓ | 4 | — | — | | — | — | +| Worker Tuning | — | ✓ | 5 | ✓ | 3 | | ✓ | 3 | +| Workflow Init Decorator | — | ✓ | 6 | — | — | | — | — | +| Workflow Failure Exception Types | — | ✓ | 7 | — | — | | — | — | +| RoadRunner Configuration | — | — | — | — | — | | ✓ | 4 | +| Continue-as-New | — | — | — | — | — | | | | +| Workflow Updates | — | — | — | — | — | | | | +| Nexus Operations | — | — | — | — | — | | | | +| Activity Cancellation and Heartbeating | — | — | — | — | — | | | | +| Sinks | — | — | — | ✓ | 4 | | — | — | +| CancellationScope Patterns | — | — | — | — | — | | | | +| Best Practices | — | — | — | — | — | | | | ## Style Compliance @@ -26,6 +27,7 @@ | Python | ✓ reference | 7 sections | | TypeScript | ✓ aligned | 4 sections (removed duplicates) | | Go | ✓ aligned | 4 sections — Schedules, Async Completion, Worker Tuning, Sessions | +| PHP | ✓ aligned | 4 sections (Schedules, Async Activity Completion, Worker Tuning, RoadRunner Configuration) | ## Status @@ -36,14 +38,22 @@ - Sessions: Go-specific feature — `workflow.CreateSession(ctx, options)` pins activities to a specific worker. Useful for file processing where activities need local state. **Intentionally missing (`—`):** - Core column: advanced features are implementation-specific -- Sandbox Customization: Python-specific; Go has no sandbox +- Sandbox Customization: Python-specific; PHP/Go have no sandbox - Gevent Compatibility Warning: Python-specific -- Workflow Init Decorator: Python-specific +- Workflow Init Decorator: Python-specific (@workflow.init); PHP has #[WorkflowInit] but not an "advanced" feature - Workflow Failure Exception Types: Python-specific - Sinks: TS-specific feature -- Sessions: Go-specific (not in Python/TS) +- Sessions: Go-specific (not in Python/TS/PHP) - Interceptors: Decided not to include for any language (all SDKs have them, but too advanced for current scope) +**PHP-specific additions:** +- RoadRunner Configuration: PHP-specific (no equivalent in Python/TS/Go) + **Order alignment:** N/A — Files have different structures by design -**Style alignment:** ✅ Complete (Python, TypeScript) +**Style alignment:** ✅ Complete (Python, TypeScript, Go, PHP) +- Python: 7 sections (Schedules, Async Activity Completion, Sandbox Customization, Gevent Warning, Worker Tuning, Workflow Init, Failure Exception Types) +- TypeScript: 4 sections (Schedules, Async Activity Completion, Worker Tuning, Sinks) +- Go: 4 sections (Schedules, Async Activity Completion, Worker Tuning, Sessions) +- PHP: 4 sections (Schedules, Async Activity Completion, Worker Tuning, RoadRunner Configuration) +- Removed duplicates from TS (Continue-as-New, Workflow Updates, CancellationScope Patterns, Nexus Operations, Activity Cancellation, Best Practices — all covered elsewhere) diff --git a/.memory/alignment_checking/data-handling.md b/.memory/alignment_checking/data-handling.md index 441e825..b0d0868 100644 --- a/.memory/alignment_checking/data-handling.md +++ b/.memory/alignment_checking/data-handling.md @@ -2,20 +2,20 @@ ## Section Inventory -| Section | Core | Python | Py# | TypeScript | TS# | Go | Go# | -|---------|------|--------|-----|------------|-----|-----|-----| -| Overview | — | ✓ | 1 | ✓ | 1 | ✓ | 1 | -| Default Data Converter | — | ✓ | 2 | ✓ | 2 | ✓ | 2 | -| Pydantic Integration | — | ✓ | 3 | — | — | — | — | -| Custom Data Converter | — | ✓ | 4 | ✓ | 3 | ✓ | 3 | -| Composition of Payload Converters | — | — | — | ✓ | 4 | ✓ | 4 | -| Protobuf Support | — | — | — | ✓ | 5 | ✓ | 5 | -| Payload Encryption | — | ✓ | 5 | ✓ | 6 | ✓ | 6 | -| Search Attributes | — | ✓ | 6 | ✓ | 7 | ✓ | 7 | -| Workflow Memo | — | ✓ | 7 | ✓ | 8 | ✓ | 8 | -| Large Payloads | — | — | — | — | — | — | — | -| Deterministic APIs for Values | — | ✓ | 8 | — | — | — | — | -| Best Practices | — | ✓ | 9 | ✓ | 9 | ✓ | 9 | +| Section | Core | Python | Py# | TypeScript | TS# | PHP | PHP# | Go | Go# | +|---------|------|--------|-----|------------|-----|-----|------|----|-----| +| Overview | — | ✓ | 1 | ✓ | 1 | ✓ | 1 | ✓ | 1 | +| Default Data Converter | — | ✓ | 2 | ✓ | 2 | ✓ | 2 | ✓ | 2 | +| Pydantic Integration | — | ✓ | 3 | — | — | — | — | — | — | +| Custom Data Conversion | — | ✓ | 4 | ✓ | 3 | ✓ | 3 | ✓ | 3 | +| Composition of Payload Converters | — | — | — | ✓ | 4 | — | — | ✓ | 4 | +| Protobuf Support | — | — | — | ✓ | 5 | — | — | ✓ | 5 | +| Payload Encryption | — | ✓ | 5 | ✓ | 6 | ✓ | 4 | ✓ | 6 | +| Search Attributes | — | ✓ | 6 | ✓ | 7 | ✓ | 5 | ✓ | 7 | +| Workflow Memo | — | ✓ | 7 | ✓ | 8 | ✓ | 6 | ✓ | 8 | +| Large Payloads | — | — | — | — | — | — | — | — | — | +| Deterministic APIs for Values | — | ✓ | 8 | — | — | — | — | — | — | +| Best Practices | — | ✓ | 9 | ✓ | 9 | ✓ | 7 | ✓ | 9 | ## Style Compliance @@ -23,6 +23,7 @@ |----------|--------|-------| | Python | ✓ reference | — | | TypeScript | ✓ aligned | — | +| PHP | ✓ aligned | Matches Python structure; uses #[ReturnType] instead of Pydantic | | Go | ✓ aligned | JSON default, protobuf native, converter.CompositeDataConverter | ## Status diff --git a/.memory/alignment_checking/determinism-protection.md b/.memory/alignment_checking/determinism-protection.md index c0ef0f0..2578112 100644 --- a/.memory/alignment_checking/determinism-protection.md +++ b/.memory/alignment_checking/determinism-protection.md @@ -2,24 +2,24 @@ ## Section Inventory -| Section | Core | Python | Py# | TypeScript | TS# | Go | Go# | -|---------|------|--------|-----|------------|-----|-----|-----| -| Overview | — | ✓ | 1 | ✓ | 1 | ✓ | 1 | -| How the Sandbox Works | — | ✓ | 2 | — | — | — | — | -| Import Blocking | — | — | — | ✓ | 2 | — | — | -| Forbidden Operations | — | ✓ | 3 | — | — | — | — | -| Function Replacement | — | — | — | ✓ | 3 | — | — | -| workflowcheck Static Analysis | — | — | — | — | — | ✓ | 2 | -| Determinism Rules | — | — | — | — | — | ✓ | 3 | -| Pass-Through Pattern | — | ✓ | 4 | — | — | — | — | -| Importing Activities | — | ✓ | 5 | — | — | — | — | -| Disabling the Sandbox | — | ✓ | 6 | — | — | — | — | -| Customizing Invalid Module Members | — | ✓ | 7 | — | — | — | — | -| Import Notification Policy | — | ✓ | 8 | — | — | — | — | -| Disable Lazy sys.modules Passthrough | — | ✓ | 9 | — | — | — | — | -| File Organization | — | ✓ | 10 | — | — | — | — | -| Common Issues | — | ✓ | 11 | — | — | — | — | -| Best Practices | — | ✓ | 12 | — | — | ✓ | 4 | +| Section | Core | Python | Py# | TypeScript | TS# | PHP | PHP# | Go | Go# | +|---------|------|--------|-----|------------|-----|-----|------|----|-----| +| Overview | — | ✓ | 1 | ✓ | 1 | ✓ | 1 | ✓ | 1 | +| How the Sandbox Works | — | ✓ | 2 | — | — | — | — | — | — | +| Import Blocking | — | — | — | ✓ | 2 | — | — | — | — | +| Forbidden Operations | — | ✓ | 3 | — | — | ✓ | 2 | — | — | +| Function Replacement | — | — | — | ✓ | 3 | — | — | — | — | +| workflowcheck Static Analysis | — | — | — | — | — | — | — | ✓ | 2 | +| Determinism Rules | — | — | — | — | — | — | — | ✓ | 3 | +| Pass-Through Pattern | — | ✓ | 4 | — | — | — | — | — | — | +| Importing Activities | — | ✓ | 5 | — | — | — | — | — | — | +| Disabling the Sandbox | — | ✓ | 6 | — | — | — | — | — | — | +| Customizing Invalid Module Members | — | ✓ | 7 | — | — | — | — | — | — | +| Import Notification Policy | — | ✓ | 8 | — | — | — | — | — | — | +| Disable Lazy sys.modules Passthrough | — | ✓ | 9 | — | — | — | — | — | — | +| File Organization | — | ✓ | 10 | — | — | — | — | — | — | +| Common Issues | — | ✓ | 11 | — | — | ✓ | 3 | — | — | +| Best Practices | — | ✓ | 12 | — | — | ✓ | 4 | ✓ | 4 | ## Style Compliance @@ -27,6 +27,7 @@ |----------|--------|-------| | Python | ✓ reference | Comprehensive (12 sections) | | TypeScript | ✓ aligned | Minimal (3 sections) — V8 is automatic | +| PHP | ✓ aligned | Minimal (4 sections) — no sandbox | | Go | ✓ aligned | Minimal (4 sections) — no runtime sandbox, convention + static analysis | ## Status diff --git a/.memory/alignment_checking/determinism.md b/.memory/alignment_checking/determinism.md index e70299a..a2a0284 100644 --- a/.memory/alignment_checking/determinism.md +++ b/.memory/alignment_checking/determinism.md @@ -2,19 +2,19 @@ ## Section Inventory -| Section | Core | Core# | Python | Py# | TypeScript | TS# | Go | Go# | -|---------|------|-------|--------|-----|------------|-----|-----|-----| -| Overview | ✓ | 1 | ✓ | 1 | ✓ | 1 | ✓ | 1 | -| Why Determinism Matters | ✓ | 2 | ✓ | 2 | ✓ | 2 | ✓ | 2 | -| Sources of Non-Determinism | ✓ | 3 | — | — | — | — | — | — | -| Central Concept: Activities | ✓ | 4 | — | — | — | — | — | — | -| SDK Protection / Sandbox | ✓ | 5 | ✓ | 6 | ✓ | 3 | — | — | -| Forbidden Operations | — | — | ✓ | 3 | ✓ | 4 | ✓ | 3 | -| Safe Builtin Alternatives | — | — | ✓ | 4 | — | — | ✓ | 4 | -| Detecting Non-Determinism | ✓ | 6 | — | — | — | — | — | — | -| Recovery from Non-Determinism | ✓ | 7 | — | — | — | — | — | — | -| Testing Replay Compatibility | — | — | ✓ | 5 | ✓ | 5 | ✓ | 5 | -| Best Practices | ✓ | 8 | ✓ | 7 | ✓ | 6 | ✓ | 6 | +| Section | Core | Core# | Python | Py# | TypeScript | TS# | PHP | PHP# | Go | Go# | +|---------|------|-------|--------|-----|------------|-----|-----|------|----|-----| +| Overview | ✓ | 1 | ✓ | 1 | ✓ | 1 | ✓ | 1 | ✓ | 1 | +| Why Determinism Matters | ✓ | 2 | ✓ | 2 | ✓ | 2 | ✓ | 2 | ✓ | 2 | +| Sources of Non-Determinism | ✓ | 3 | — | — | — | — | — | — | — | — | +| Central Concept: Activities | ✓ | 4 | — | — | — | — | — | — | — | — | +| SDK Protection / Sandbox | ✓ | 5 | ✓ | 6 | ✓ | 3 | ✓ | 3 | — | — | +| Forbidden Operations | — | — | ✓ | 3 | ✓ | 4 | ✓ | 4 | ✓ | 3 | +| Safe Builtin Alternatives | — | — | ✓ | 4 | — | — | — | — | ✓ | 4 | +| Detecting Non-Determinism | ✓ | 6 | — | — | — | — | — | — | — | — | +| Recovery from Non-Determinism | ✓ | 7 | — | — | — | — | — | — | — | — | +| Testing Replay Compatibility | — | — | ✓ | 5 | ✓ | 5 | ✓ | 5 | ✓ | 5 | +| Best Practices | ✓ | 8 | ✓ | 7 | ✓ | 6 | ✓ | 6 | ✓ | 6 | ## Style Compliance @@ -23,6 +23,7 @@ | Core | ✓ reference | Deep conceptual content | | Python | ✓ aligned | Practical focus | | TypeScript | ✓ aligned | Practical focus, V8 sandbox | +| PHP | ✓ aligned | Practical focus, no sandbox (runtime checks only) | | Go | ✓ aligned | Practical focus, no sandbox, workflowcheck tool, workflow.* replacements | ## Status diff --git a/.memory/alignment_checking/error-handling.md b/.memory/alignment_checking/error-handling.md index 6b4a8f2..c2eed8a 100644 --- a/.memory/alignment_checking/error-handling.md +++ b/.memory/alignment_checking/error-handling.md @@ -2,19 +2,19 @@ ## Section Inventory -| Section | Core | Python | Py# | TypeScript | TS# | Go | Go# | -|---------|------|--------|-----|------------|-----|-----|-----| -| Overview | — | ✓ | 1 | ✓ | 1 | ✓ | 1 | -| Application Errors/Failures | — | ✓ | 2 | ✓ | 2 | ✓ | 2 | -| Non-Retryable Errors | — | ✓ | 3 | — | — | ✓ | 3 | -| Activity Errors | — | — | — | ✓ | 3 | — | — | -| Handling Activity Errors in Workflows | — | ✓ | 4 | ✓ | 4 | ✓ | 4 | -| Retry Configuration | — | ✓ | 5 | ✓ | 5 | ✓ | 5 | -| Timeout Configuration | — | ✓ | 6 | ✓ | 6 | ✓ | 6 | -| Workflow Failure | — | ✓ | 7 | ✓ | 7 | ✓ | 7 | -| Cancellation Handling in Activities | — | — | — | — | — | — | — | -| Idempotency Patterns | — | — | — | — | — | — | — | -| Best Practices | — | ✓ | 8 | ✓ | 9 | ✓ | 8 | +| Section | Core | Python | Py# | TypeScript | TS# | PHP | PHP# | Go | Go# | +|---------|------|--------|-----|------------|-----|-----|------|----|-----| +| Overview | — | ✓ | 1 | ✓ | 1 | ✓ | 1 | ✓ | 1 | +| Application Errors | — | ✓ | 2 | ✓ | 2 | ✓ | 2 | ✓ | 2 | +| Non-Retryable Errors | — | ✓ | 3 | — | — | ✓ | 3 | ✓ | 3 | +| Activity Errors | — | — | — | ✓ | 3 | — | — | — | — | +| Handling Activity Errors | — | ✓ | 4 | ✓ | 4 | ✓ | 4 | ✓ | 4 | +| Retry Policy Configuration | — | ✓ | 5 | ✓ | 5 | ✓ | 5 | ✓ | 5 | +| Timeout Configuration | — | ✓ | 6 | ✓ | 6 | ✓ | 6 | ✓ | 6 | +| Workflow Failure | — | ✓ | 7 | ✓ | 7 | ✓ | 7 | ✓ | 7 | +| Cancellation Handling in Activities | — | — | — | — | — | | | — | — | +| Idempotency Patterns | — | — | — | — | — | | | — | — | +| Best Practices | — | ✓ | 8 | ✓ | 9 | ✓ | 8 | ✓ | 8 | ## Style Compliance @@ -22,6 +22,7 @@ |----------|--------|-------| | Python | ✓ reference | — | | TypeScript | ✓ aligned | Uses `log`, has retry defaults note | +| PHP | ✓ aligned | Matches Python section structure and code-first style | | Go | ✓ aligned | Go-style error handling (errors.As, error returns, no exceptions) | ## Status diff --git a/.memory/alignment_checking/gotchas.md b/.memory/alignment_checking/gotchas.md index e83465f..1955a62 100644 --- a/.memory/alignment_checking/gotchas.md +++ b/.memory/alignment_checking/gotchas.md @@ -2,26 +2,26 @@ ## Section Inventory -| Section | Core | Core# | Python | Py# | TypeScript | TS# | Go | Go# | -|---------|------|-------|--------|-----|------------|-----|-----|-----| -| Idempotency / Non-Idempotent Activities | ✓ | 1 | — | — | — | — | — | — | -| Replay Safety / Side Effects & Non-Determinism | ✓ | 2 | — | — | — | — | — | — | -| Multiple Workers with Different Code | ✓ | 3 | — | — | — | — | — | — | -| Retry Policies / Failing Activities Too Quickly | ✓ | 4 | — | — | — | — | — | — | -| Query Handlers / Query Handler Mistakes | ✓ | 5 | — | — | — | — | — | — | -| File Organization | ✓ | 6 | ✓ | 1 | — | — | — | — | -| Activity Imports | — | — | — | — | ✓ | 1 | — | — | -| Bundling Issues | — | — | — | — | ✓ | 2 | — | — | -| Async vs Sync Activities | — | — | ✓ | 2 | — | — | — | — | -| Goroutines and Concurrency | — | — | — | — | — | — | ✓ | 1 | -| Non-Deterministic Operations | — | — | — | — | — | — | ✓ | 2 | -| Error Handling | ✓ | 8 | — | — | — | — | — | — | -| Wrong Retry Classification | ✓ | 8 | ✓ | 3 | ✓ | 3 | ✓ | 3 | -| Heartbeating | — | — | ✓ | 5 | ✓ | 5 | ✓ | 4 | -| Cancellation | ✓ | 10 | ✓ | 4 | ✓ | 4 | ✓ | 5 | -| Testing | ✓ | 7 | ✓ | 6 | ✓ | 6 | ✓ | 6 | -| Timers and Sleep | — | — | ✓ | 7 | ✓ | 7 | ✓ | 7 | -| Payload Size Limits | ✓ | 9 | — | — | — | — | — | — | +| Section | Core | Core# | Python | Py# | TypeScript | TS# | PHP | PHP# | Go | Go# | +|---------|------|-------|--------|-----|------------|-----|-----|------|----|-----| +| Idempotency / Non-Idempotent Activities | ✓ | 1 | — | — | — | — | | | — | — | +| Replay Safety / Side Effects & Non-Determinism | ✓ | 2 | — | — | — | — | | | — | — | +| Multiple Workers with Different Code | ✓ | 3 | — | — | — | — | | | — | — | +| Retry Policies / Failing Activities Too Quickly | ✓ | 4 | — | — | — | — | | | — | — | +| Query Handlers / Query Handler Mistakes | ✓ | 5 | — | — | — | — | | | — | — | +| File Organization | ✓ | 6 | ✓ | 1 | — | — | — | — | — | — | +| Activity Imports | — | — | — | — | ✓ | 1 | — | — | — | — | +| Bundling Issues | — | — | — | — | ✓ | 2 | — | — | — | — | +| Async vs Sync Activities | — | — | ✓ | 2 | — | — | — | — | — | — | +| Goroutines and Concurrency | — | — | — | — | — | — | — | — | ✓ | 1 | +| Non-Deterministic Operations | — | — | — | — | — | — | — | — | ✓ | 2 | +| Error Handling | ✓ | 8 | — | — | — | — | | | — | — | +| Wrong Retry Classification | ✓ | 8 | ✓ | 3 | ✓ | 3 | ✓ | 1 | ✓ | 3 | +| Heartbeating | — | — | ✓ | 5 | ✓ | 5 | ✓ | 3 | ✓ | 4 | +| Cancellation | ✓ | 10 | ✓ | 4 | ✓ | 4 | ✓ | 2 | ✓ | 5 | +| Testing | ✓ | 7 | ✓ | 6 | ✓ | 6 | ✓ | 4 | ✓ | 6 | +| Timers and Sleep | — | — | ✓ | 7 | ✓ | 7 | ✓ | 5 | ✓ | 7 | +| Payload Size Limits | ✓ | 9 | — | — | — | — | | | — | — | ## Style Compliance @@ -30,6 +30,7 @@ | Core | ✓ reference | Conceptual gotchas | | Python | ✓ aligned | Language-specific gotchas | | TypeScript | ✓ aligned | Language-specific gotchas | +| PHP | ✓ aligned | 5 sections (Wrong Retry Classification, Cancellation, Heartbeating, Testing, Timers and Sleep) | | Go | ✓ aligned | Language-specific gotchas — goroutines, channels, selectors, map range | ## Status diff --git a/.memory/alignment_checking/language.md b/.memory/alignment_checking/language.md index 2ab9ecc..85f42e1 100644 --- a/.memory/alignment_checking/language.md +++ b/.memory/alignment_checking/language.md @@ -4,18 +4,18 @@ Tracks alignment for `python.md`, `typescript.md`, `go.md`, etc. ## Section Inventory -| Section | Core | Python | Py# | TypeScript | TS# | Go | Go# | -|---------|------|--------|-----|------------|-----|-----|-----| -| Overview | — | ✓ | 1 | ✓ | 1 | ✓ | 1 | -| How Temporal Works: History Replay | — | — | — | — | — | — | — | -| Understanding Replay | — | — | — | ✓ | 2 | — | — | -| Quick Start / Quick Demo | — | ✓ | 2 | ✓ | 3 | ✓ | 2 | -| Key Concepts | — | ✓ | 3 | ✓ | 4 | ✓ | 3 | -| File Organization Best Practice | — | ✓ | 4 | ✓ | 5 | ✓ | 4 | -| Determinism Rules | — | — | — | ✓ | 6 | — | — | -| Common Pitfalls | — | ✓ | 5 | ✓ | 7 | ✓ | 5 | -| Writing Tests | — | ✓ | 6 | ✓ | 8 | ✓ | 6 | -| Additional Resources | — | ✓ | 7 | ✓ | 9 | ✓ | 7 | +| Section | Core | Python | Py# | TypeScript | TS# | PHP | PHP# | Go | Go# | +|---------|------|--------|-----|------------|-----|-----|------|----|-----| +| Overview | — | ✓ | 1 | ✓ | 1 | ✓ | 1 | ✓ | 1 | +| How Temporal Works: History Replay | — | — | — | — | — | | | — | — | +| Understanding Replay | — | — | — | ✓ | 2 | — | — | — | — | +| Quick Start / Quick Demo | — | ✓ | 2 | ✓ | 3 | ✓ | 2 | ✓ | 2 | +| Key Concepts | — | ✓ | 3 | ✓ | 4 | ✓ | 3 | ✓ | 3 | +| File Organization Best Practice | — | ✓ | 4 | ✓ | 5 | ✓ | 4 | ✓ | 4 | +| Determinism Rules | — | — | — | ✓ | 6 | ✓ | 5 | — | — | +| Common Pitfalls | — | ✓ | 5 | ✓ | 7 | ✓ | 6 | ✓ | 5 | +| Writing Tests | — | ✓ | 6 | ✓ | 8 | ✓ | 7 | ✓ | 6 | +| Additional Resources | — | ✓ | 7 | ✓ | 9 | ✓ | 8 | ✓ | 7 | ## Style Compliance @@ -23,6 +23,7 @@ Tracks alignment for `python.md`, `typescript.md`, `go.md`, etc. |----------|--------|-------| | Python | ✓ reference | — | | TypeScript | ✓ aligned | Has Understanding Replay, Determinism Rules | +| PHP | ✓ aligned | Has Determinism Rules, RoadRunner-specific file org | | Go | ✓ aligned | Function-based (no decorators), workflowcheck, struct activities | ## Status diff --git a/.memory/alignment_checking/observability.md b/.memory/alignment_checking/observability.md index 3d56a89..1d94a49 100644 --- a/.memory/alignment_checking/observability.md +++ b/.memory/alignment_checking/observability.md @@ -2,16 +2,16 @@ ## Section Inventory -| Section | Core | Python | Py# | TypeScript | TS# | Go | Go# | -|---------|------|--------|-----|------------|-----|-----|-----| -| Overview | — | ✓ | 1 | ✓ | 1 | ✓ | 1 | -| Logging / Replay-Aware Logging | — | ✓ | 2 | ✓ | 2 | ✓ | 2 | -| Customizing the Logger | — | ✓ | 2 | ✓ | 3 | ✓ | 3 | -| OpenTelemetry Integration | — | — | — | — | — | — | — | -| Metrics | — | ✓ | 3 | ✓ | 4 | ✓ | 4 | -| Search Attributes (Visibility) | — | ✓ | 4 | — | — | ✓ | 5 | -| Debugging with Event History | — | — | — | — | — | — | — | -| Best Practices | — | ✓ | 5 | ✓ | 5 | ✓ | 6 | +| Section | Core | Python | Py# | TypeScript | TS# | PHP | PHP# | Go | Go# | +|---------|------|--------|-----|------------|-----|-----|------|----|-----| +| Overview | — | ✓ | 1 | ✓ | 1 | ✓ | 1 | ✓ | 1 | +| Logging / Replay-Aware Logging | — | ✓ | 2 | ✓ | 2 | ✓ | 2 | ✓ | 2 | +| Customizing the Logger | — | ✓ | 2 | ✓ | 3 | ✓ | 3 | ✓ | 3 | +| OpenTelemetry Integration | — | — | — | — | — | | | — | — | +| Metrics | — | ✓ | 3 | ✓ | 4 | — | — | ✓ | 4 | +| Search Attributes (Visibility) | — | ✓ | 4 | — | — | ✓ | 4 | ✓ | 5 | +| Debugging with Event History | — | — | — | — | — | | | — | — | +| Best Practices | — | ✓ | 5 | ✓ | 5 | ✓ | 5 | ✓ | 6 | ## Style Compliance @@ -19,6 +19,7 @@ |----------|--------|-------| | Python | ✓ reference | — | | TypeScript | ✓ aligned | Removed verbose sections | +| PHP | ✓ aligned | PSR-3 logging; Metrics omitted (uses RoadRunner pipeline, not SDK metrics API) | | Go | ✓ aligned | workflow.GetLogger, slog integration, Tally/Prometheus metrics | ## Status diff --git a/.memory/alignment_checking/patterns.md b/.memory/alignment_checking/patterns.md index 9485753..ea87780 100644 --- a/.memory/alignment_checking/patterns.md +++ b/.memory/alignment_checking/patterns.md @@ -2,35 +2,35 @@ ## Section Inventory -| Section | Core | Python | Py# | TypeScript | TS# | Go | Go# | -|---------|------|--------|-----|------------|-----|-----|-----| -| Signals | ✓ | ✓ | 1 | ✓ | 1 | ✓ | 1 | -| Dynamic Signal Handlers | — | ✓ | 2 | ✓ | 2 | — | — | -| Queries | ✓ | ✓ | 3 | ✓ | 3 | ✓ | 2 | -| Dynamic Query Handlers | — | ✓ | 4 | ✓ | 4 | — | — | -| Updates | ✓ | ✓ | 5 | ✓ | 5 | ✓ | 3 | -| Child Workflows | ✓ | ✓ | 6 | ✓ | 6 | ✓ | 4 | -| Child Workflow Options | — | — | — | ✓ | 7 | ✓ | 4s | -| Handles to External Workflows | — | ✓ | 7 | ✓ | 8 | ✓ | 5 | -| Parallel Execution | ✓ | ✓ | 8 | ✓ | 9 | ✓ | 6 | -| Deterministic Asyncio Alternatives | — | ✓ | 9 | — | — | — | — | -| Selector Pattern | — | — | — | — | — | ✓ | 7 | -| Continue-as-New | ✓ | ✓ | 10 | ✓ | 10 | ✓ | 8 | -| Cancellation Handling (asyncio) | — | ✓ | 12 | — | — | — | — | -| Cancellation Scopes | — | — | — | ✓ | 12 | — | — | -| Cancellation Handling | — | — | — | — | — | ✓ | 9 | -| Saga Pattern | ✓ | ✓ | 11 | ✓ | 11 | ✓ | 10 | -| Triggers | — | — | — | ✓ | 13 | — | — | -| Wait Condition with Timeout | — | ✓ | 13 | ✓ | 14 | ✓ | 11 | -| Waiting for All Handlers to Finish | — | ✓ | 14 | ✓ | 15 | ✓ | 12 | -| Activity Heartbeat Details | ✓ | ✓ | 15 | ✓ | 16 | ✓ | 13 | -| Timers | ✓ | ✓ | 16 | ✓ | 17 | ✓ | 14 | -| Large Data Handling | ✓ | — | — | — | — | — | — | -| Local Activities | ✓ | ✓ | 17 | ✓ | 18 | ✓ | 15 | -| Entity Workflow Pattern | ✓ | — | — | — | — | — | — | -| Polling Patterns | ✓ | — | — | — | — | — | — | -| Idempotency Patterns | ✓ | — | — | — | — | — | — | -| Using Pydantic Models | — | ✓ | 18 | — | — | — | — | +| Section | Core | Python | Py# | TypeScript | TS# | PHP | PHP# | Go | Go# | +|---------|------|--------|-----|------------|-----|-----|------|----|-----| +| Signals | ✓ | ✓ | 1 | ✓ | 1 | ✓ | 1 | ✓ | 1 | +| Dynamic Signal Handlers | — | ✓ | 2 | ✓ | 2 | ✓ | 2 | — | — | +| Queries | ✓ | ✓ | 3 | ✓ | 3 | ✓ | 3 | ✓ | 2 | +| Dynamic Query Handlers | — | ✓ | 4 | ✓ | 4 | ✓ | 4 | — | — | +| Updates | ✓ | ✓ | 5 | ✓ | 5 | ✓ | 5 | ✓ | 3 | +| Child Workflows | ✓ | ✓ | 6 | ✓ | 6 | ✓ | 6 | ✓ | 4 | +| Child Workflow Options | — | — | — | ✓ | 7 | — | — | ✓ | 4s | +| Handles to External Workflows | — | ✓ | 7 | ✓ | 8 | ✓ | 7 | ✓ | 5 | +| Parallel Execution | ✓ | ✓ | 8 | ✓ | 9 | ✓ | 8 | ✓ | 6 | +| Deterministic Asyncio Alternatives | — | ✓ | 9 | — | — | — | — | — | — | +| Selector Pattern | — | — | — | — | — | — | — | ✓ | 7 | +| Continue-as-New | ✓ | ✓ | 10 | ✓ | 10 | ✓ | 9 | ✓ | 8 | +| Cancellation Handling (asyncio) | — | ✓ | 12 | — | — | — | — | — | — | +| Cancellation Scopes | — | — | — | ✓ | 12 | — | — | — | — | +| Cancellation Handling | — | — | — | — | — | — | — | ✓ | 9 | +| Saga Pattern | ✓ | ✓ | 11 | ✓ | 11 | ✓ | 10 | ✓ | 10 | +| Triggers | — | — | — | ✓ | 13 | — | — | — | — | +| Wait Condition with Timeout | — | ✓ | 13 | ✓ | 14 | ✓ | 11 | ✓ | 11 | +| Waiting for All Handlers to Finish | — | ✓ | 14 | ✓ | 15 | ✓ | 12 | ✓ | 12 | +| Activity Heartbeat Details | ✓ | ✓ | 15 | ✓ | 16 | ✓ | 13 | ✓ | 13 | +| Timers | ✓ | ✓ | 16 | ✓ | 17 | ✓ | 14 | ✓ | 14 | +| Large Data Handling | ✓ | — | — | — | — | — | — | — | — | +| Local Activities | ✓ | ✓ | 17 | ✓ | 18 | ✓ | 15 | ✓ | 15 | +| Entity Workflow Pattern | ✓ | — | — | — | — | — | — | — | — | +| Polling Patterns | ✓ | — | — | — | — | — | — | — | — | +| Idempotency Patterns | ✓ | — | — | — | — | — | — | — | — | +| Using Pydantic Models | — | ✓ | 18 | — | — | — | — | — | — | ## Style Compliance @@ -38,6 +38,7 @@ |----------|--------|-------| | Python | ✓ reference | — | | TypeScript | ✓ aligned | Uses `log`, CancellationScope idiom | +| PHP | ✓ aligned | Code-first, minimal prose, matches Python style | | Go | ✓ aligned | Channel-based signals, SetQueryHandler, SetUpdateHandler, Selector, compensation slice saga | ## Status diff --git a/.memory/alignment_checking/testing.md b/.memory/alignment_checking/testing.md index 500f07a..faf0205 100644 --- a/.memory/alignment_checking/testing.md +++ b/.memory/alignment_checking/testing.md @@ -2,17 +2,17 @@ ## Section Inventory -| Section | Core | Python | Py# | TypeScript | TS# | Go | Go# | -|---------|------|--------|-----|------------|-----|-----|-----| -| Overview | — | ✓ | 1 | ✓ | 1 | ✓ | 1 | -| Test Environment Setup | — | ✓ | 2 | ✓ | 2 | ✓ | 2 | -| Time Skipping | — | — | — | — | — | — | — | -| Activity Mocking | — | ✓ | 3 | ✓ | 3 | ✓ | 3 | -| Testing Signals and Queries | — | ✓ | 4 | ✓ | 4 | ✓ | 4 | -| Testing Failure Cases | — | ✓ | 5 | ✓ | 5 | ✓ | 5 | -| Replay Testing | — | ✓ | 6 | ✓ | 6 | ✓ | 6 | -| Activity Testing | — | ✓ | 7 | ✓ | 7 | ✓ | 7 | -| Best Practices | — | ✓ | 8 | ✓ | 8 | ✓ | 8 | +| Section | Core | Python | Py# | TypeScript | TS# | PHP | PHP# | Go | Go# | +|---------|------|--------|-----|------------|-----|-----|------|----|-----| +| Overview | — | ✓ | 1 | ✓ | 1 | ✓ | 1 | ✓ | 1 | +| Workflow Test Environment | — | ✓ | 2 | ✓ | 2 | ✓ | 2 | ✓ | 2 | +| Time Skipping | — | — | — | — | — | | | — | — | +| Mocking Activities | — | ✓ | 3 | ✓ | 3 | ✓ | 3 | ✓ | 3 | +| Testing Signals and Queries | — | ✓ | 4 | ✓ | 4 | ✓ | 4 | ✓ | 4 | +| Testing Failure Cases | — | ✓ | 5 | ✓ | 5 | ✓ | 5 | ✓ | 5 | +| Workflow Replay Testing | — | ✓ | 6 | ✓ | 6 | ✓ | 6 | ✓ | 6 | +| Activity Testing | — | ✓ | 7 | ✓ | 7 | ✓ | 7 | ✓ | 7 | +| Best Practices | — | ✓ | 8 | ✓ | 8 | ✓ | 8 | ✓ | 8 | ## Style Compliance @@ -20,6 +20,7 @@ |----------|--------|-------| | Python | ✓ reference | — | | TypeScript | ✓ aligned | Added failure/activity testing | +| PHP | ✓ aligned | Matches Python section structure and code-first style | | Go | ✓ aligned | testsuite package, testify, mock activities, TestWorkflowEnvironment | ## Status diff --git a/.memory/alignment_checking/versioning.md b/.memory/alignment_checking/versioning.md index 3df1f60..2cd7dd2 100644 --- a/.memory/alignment_checking/versioning.md +++ b/.memory/alignment_checking/versioning.md @@ -2,17 +2,17 @@ ## Section Inventory -| Section | Core | Core# | Python | Py# | TypeScript | TS# | Go | Go# | -|---------|------|-------|--------|-----|------------|-----|-----|-----| -| Overview | ✓ | 1 | — | — | — | — | — | — | -| Why Versioning is Needed | ✓ | 2 | — | — | — | — | — | — | -| Patching API / GetVersion API | ✓ | 3 | ✓ | 1 | ✓ | 1 | ✓ | 1 | -| Workflow Type Versioning | ✓ | 4 | ✓ | 2 | ✓ | 2 | ✓ | 2 | -| Worker Versioning | ✓ | 5 | ✓ | 3 | ✓ | 3 | ✓ | 3 | -| Choosing a Strategy | ✓ | 6 | — | — | — | — | — | — | -| Best Practices | ✓ | 7 | ✓ | 4 | ✓ | 4 | ✓ | 4 | -| Finding Workflows by Version | ✓ | 8 | — | — | — | — | — | — | -| Common Mistakes | ✓ | 9 | — | — | — | — | — | — | +| Section | Core | Core# | Python | Py# | TypeScript | TS# | PHP | PHP# | Go | Go# | +|---------|------|-------|--------|-----|------------|-----|-----|------|----|-----| +| Overview | ✓ | 1 | — | — | — | — | — | — | — | — | +| Why Versioning is Needed | ✓ | 2 | — | — | — | — | — | — | — | — | +| Patching API / GetVersion API | ✓ | 3 | ✓ | 1 | ✓ | 1 | ✓ | 1 | ✓ | 1 | +| Workflow Type Versioning | ✓ | 4 | ✓ | 2 | ✓ | 2 | ✓ | 2 | ✓ | 2 | +| Worker Versioning | ✓ | 5 | ✓ | 3 | ✓ | 3 | ✓ | 3 | ✓ | 3 | +| Choosing a Strategy | ✓ | 6 | — | — | — | — | — | — | — | — | +| Best Practices | ✓ | 7 | ✓ | 4 | ✓ | 4 | ✓ | 4 | ✓ | 4 | +| Finding Workflows by Version | ✓ | 8 | — | — | — | — | — | — | — | — | +| Common Mistakes | ✓ | 9 | — | — | — | — | — | — | — | — | ## Style Compliance @@ -21,6 +21,7 @@ | Core | ✓ reference | Conceptual content | | Python | ✓ aligned | Code only, refs core | | TypeScript | ✓ aligned | Code only, refs core | +| PHP | ✓ aligned | Code only, refs core; uses getVersion() not patched() | | Go | ✓ aligned | Uses `workflow.GetVersion` (not patching); code only, refs core | ## Status diff --git a/.memory/correctness_checking/README.md b/.memory/correctness_checking/README.md index 98f0cac..57681b0 100644 --- a/.memory/correctness_checking/README.md +++ b/.memory/correctness_checking/README.md @@ -9,27 +9,27 @@ Track verification of factual statements and code examples in reference files fo Each file in this directory tracks correctness for a corresponding reference file. Within each file, sections are organized by language (e.g., `## TypeScript`, `## Python`). -**Supported languages:** TypeScript, Python, Go +**Supported languages:** TypeScript, Python, PHP, Go **Adding a new language:** Add a new `## {Language}` section to each relevant file with a Tracking table and Detailed Notes. ## Summary -| File | TypeScript | Python | Go | -|------|------------|--------|-----| -| patterns.md | ✅ | partial | ✅ | -| testing.md | ✅ | partial | ✅ | -| language.md | ✅ | partial | ✅ | -| versioning.md | ✅ | partial | ✅ | -| advanced-features.md | ✅ | partial | ✅ | -| data-handling.md | ✅ | partial | ✅ | -| determinism-protection.md | ✅ | partial | ✅ | -| determinism.md | ✅ | partial | ✅ | -| error-handling.md | ✅ | partial | ✅ | -| gotchas.md | ✅ | partial | ✅ | -| observability.md | ✅ | partial | ✅ | -| ai-patterns.md | — | partial | — | -| sync-vs-async.md | — | ✅ | — | +| File | TypeScript | Python | PHP | Go | +|------|------------|--------|-----|-----| +| patterns.md | ✅ | partial | ✅ | ✅ | +| testing.md | ✅ | partial | unchecked | ✅ | +| language.md | ✅ | partial | unchecked | ✅ | +| versioning.md | ✅ | partial | partial | ✅ | +| advanced-features.md | ✅ | partial | unchecked | ✅ | +| data-handling.md | ✅ | partial | partial | ✅ | +| determinism-protection.md | ✅ | partial | unchecked | ✅ | +| determinism.md | ✅ | partial | unchecked | ✅ | +| error-handling.md | ✅ | partial | unchecked | ✅ | +| gotchas.md | ✅ | partial | unchecked | ✅ | +| observability.md | ✅ | partial | partial | ✅ | +| ai-patterns.md | — | partial | — | — | +| sync-vs-async.md | — | ✅ | — | — | **Legend:** ✅ = all sections verified, partial = some sections need fixes, unchecked = not yet verified, — = N/A @@ -53,7 +53,7 @@ Each file in this directory tracks correctness for a corresponding reference fil 1. Read the section from the reference file 2. Query documentation sources: - - `mcp__context7__query-docs` with `/temporalio/sdk-typescript`, `/temporalio/sdk-python`, or `/temporalio/sdk-go` + - `mcp__context7__query-docs` with `/temporalio/sdk-typescript`, `/temporalio/sdk-python`, `/temporalio/sdk-php`, or `/temporalio/sdk-go` - `mcp__temporal-docs__search_temporal_knowledge_sources` for conceptual verification 3. Compare code examples against official docs 4. Apply fixes to source file if needed diff --git a/.memory/correctness_checking/advanced-features.md b/.memory/correctness_checking/advanced-features.md index 952ac22..20129f6 100644 --- a/.memory/correctness_checking/advanced-features.md +++ b/.memory/correctness_checking/advanced-features.md @@ -135,6 +135,42 @@ Correctness verification for `references/{language}/advanced-features.md`. --- +## PHP + +**File:** `references/php/advanced-features.md` (relative to skill root) + +### Tracking + +| # | Section | Status | Fix Applied | Sources | +|---|---------|--------|-------------|---------| +| 1 | Schedules | unchecked | | | +| 2 | Async Activity Completion | unchecked | | | +| 3 | Worker Tuning | unchecked | | | +| 4 | RoadRunner Configuration | unchecked | | | + +### Detailed Notes + +#### 1. Schedules +**Status:** unchecked + +--- + +#### 2. Async Activity Completion +**Status:** unchecked + +--- + +#### 3. Worker Tuning +**Status:** unchecked + +--- + +#### 4. RoadRunner Configuration +**Status:** unchecked + +--- + + ## Go **File:** `references/go/advanced-features.md` (relative to skill root) diff --git a/.memory/correctness_checking/data-handling.md b/.memory/correctness_checking/data-handling.md index 5b5b5ac..0e09c34 100644 --- a/.memory/correctness_checking/data-handling.md +++ b/.memory/correctness_checking/data-handling.md @@ -233,6 +233,104 @@ Correctness verification for `references/{language}/data-handling.md`. --- +## PHP + +**File:** `references/php/data-handling.md` (relative to skill root) + +### Tracking + +| # | Section | Status | Fix Applied | Sources | +|---|---------|--------|-------------|---------| +| 1 | Overview | all good | | context7 sdk-php | +| 2 | Default Data Converter | all good | | context7 sdk-php | +| 3 | Custom Data Converter | needs verification | | context7 sdk-php | +| 4 | Payload Encryption | needs verification | | context7 sdk-php | +| 5 | Search Attributes | FIXED | `TypedSearchAttributes::new()->withSearchAttribute()`, `->valueSet()` | context7 sdk-php | +| 6 | Workflow Memo | needs verification | | context7 sdk-php | +| 7 | Best Practices | all good | | context7 sdk-php | + +### Detailed Notes + +#### 1. Overview +**Status:** all good + +**Verified:** +- Data converter role description is accurate +- JSON as default format is correct + +--- + +#### 2. Default Data Converter +**Status:** all good + +**Verified:** +- Supported types (null, scalars, arrays, objects) are correct +- `#[ReturnType]` attribute usage on workflow interface methods is correct +- Import `Temporal\Workflow\ReturnType` is consistent with SDK conventions +- Explanation that generators need `#[ReturnType]` for deserialization is correct + +--- + +#### 3. Custom Data Converter +**Status:** needs verification + +**Issues:** +- **`PayloadConverter` interface name could not be fully verified** — the actual interface may be `PayloadConverterInterface` +- Method signatures (`getEncodingType()`, `toPayload()`, `fromPayload()`) are plausible but could not be confirmed +- `DataConverter` constructor taking multiple converters is plausible but unverified +- `WorkflowClient::create()` with `dataConverter:` named parameter is plausible + +**Note:** Unable to verify custom data converter PHP-specific API due to limited documentation availability. + +--- + +#### 4. Payload Encryption +**Status:** needs verification + +**Issues:** +- **`PayloadCodecInterface` name could not be fully verified** — plausible but unconfirmed +- `encode(array $payloads): array` and `decode(array $payloads): array` signatures are plausible +- `DataConverter::createDefault()->withCodec(...)` pattern is plausible but unverified + +**Note:** Unable to verify PayloadCodec PHP-specific API due to limited documentation availability. + +--- + +#### 5. Search Attributes +**Status:** FIXED + +**Issues fixed:** +- Wrong import path: `Temporal\Common\SearchAttributeKey` → `Temporal\Common\SearchAttributes\SearchAttributeKey` +- Wrong factory method: `TypedSearchAttributes::empty()` → `TypedSearchAttributes::new()` +- Wrong setter method: `->withValue()` → `->withSearchAttribute()` +- Wrong upsert method: `->withValue('completed')` → `->valueSet('completed')` +- `Workflow::upsertTypedSearchAttributes()` and `SearchAttributeKey::forKeyword()` are correct ✓ + +--- + +#### 6. Workflow Memo +**Status:** needs verification + +**Issues:** +- `WorkflowOptions::new()->withMemo([...])` is plausible but not verified in Context7 docs +- **`Workflow::upsertMemo()` could not be verified** — this method may or may not exist + +**Note:** Unable to verify memo PHP-specific API due to limited documentation availability. + +--- + +#### 7. Best Practices +**Status:** all good + +**Verified:** +- All 4 best practices are valid +- `#[ReturnType]` recommendation is correct +- PayloadCodec for encryption recommendation is correct +- Typed Search Attributes recommendation is correct + +--- + + ## Go **File:** `references/go/data-handling.md` (relative to skill root) @@ -271,20 +369,13 @@ Correctness verification for `references/{language}/data-handling.md`. #### 3. Custom Data Converter **Status:** FIXED -**Issue 1:** Listed 5 interface methods but actual `converter.DataConverter` has 6 -- was missing `ToStrings`. Fixed. - -**Issue 2 (PR #38 feedback):** Section had no substantive content — no example of how to actually implement a custom converter. Rewrote with full working example. - **Fix Applied:** -- Shows `PayloadConverter` interface (the right abstraction for most users, not the full `DataConverter`) -- Full msgpack `PayloadConverter` implementation showing all 4 methods (`ToPayload` returning nil for unhandled types, `FromPayload` checking encoding, `ToString` for UI, `Encoding`) +- Shows `PayloadConverter` interface with full msgpack implementation - `converter.MetadataEncoding` metadata key usage - `converter.NewCompositeDataConverter` composition pattern - Per-activity override via `workflow.WithDataConverter` - `workflow.DataConverterWithoutDeadlockDetection` note for remote-call converters (e.g. KMS) -**Sources:** temporal-docs (pkg.go.dev/go.temporal.io/sdk/converter, docs.temporal.io/develop/go/converters-and-encryption) - --- #### 4. Composition of Payload Converters diff --git a/.memory/correctness_checking/determinism-protection.md b/.memory/correctness_checking/determinism-protection.md index a16068b..3a4546e 100644 --- a/.memory/correctness_checking/determinism-protection.md +++ b/.memory/correctness_checking/determinism-protection.md @@ -186,6 +186,42 @@ Correctness verification for `references/{language}/determinism-protection.md`. --- +## PHP + +**File:** `references/php/determinism-protection.md` (relative to skill root) + +### Tracking + +| # | Section | Status | Fix Applied | Sources | +|---|---------|--------|-------------|---------| +| 1 | Overview | unchecked | | | +| 2 | Forbidden Operations | unchecked | | | +| 3 | Common Issues | unchecked | | | +| 4 | Best Practices | unchecked | | | + +### Detailed Notes + +#### 1. Overview +**Status:** unchecked + +--- + +#### 2. Forbidden Operations +**Status:** unchecked + +--- + +#### 3. Common Issues +**Status:** unchecked + +--- + +#### 4. Best Practices +**Status:** unchecked + +--- + + ## Go **File:** `references/go/determinism-protection.md` (relative to skill root) diff --git a/.memory/correctness_checking/determinism.md b/.memory/correctness_checking/determinism.md index 4d948d3..e621a57 100644 --- a/.memory/correctness_checking/determinism.md +++ b/.memory/correctness_checking/determinism.md @@ -160,6 +160,54 @@ Correctness verification for `references/{language}/determinism.md`. --- +## PHP + +**File:** `references/php/determinism.md` (relative to skill root) + +### Tracking + +| # | Section | Status | Fix Applied | Sources | +|---|---------|--------|-------------|---------| +| 1 | Overview | unchecked | | | +| 2 | Why Determinism Matters: History Replay | unchecked | | | +| 3 | SDK Protection / Runtime Checking | unchecked | | | +| 4 | Forbidden Operations | unchecked | | | +| 5 | Testing Replay Compatibility | unchecked | | | +| 6 | Best Practices | unchecked | | | + +### Detailed Notes + +#### 1. Overview +**Status:** unchecked + +--- + +#### 2. Why Determinism Matters: History Replay +**Status:** unchecked + +--- + +#### 3. SDK Protection / Runtime Checking +**Status:** unchecked + +--- + +#### 4. Forbidden Operations +**Status:** unchecked + +--- + +#### 5. Testing Replay Compatibility +**Status:** unchecked + +--- + +#### 6. Best Practices +**Status:** unchecked + +--- + + ## Go **File:** `references/go/determinism.md` (relative to skill root) diff --git a/.memory/correctness_checking/error-handling.md b/.memory/correctness_checking/error-handling.md index 121330d..ae2c55c 100644 --- a/.memory/correctness_checking/error-handling.md +++ b/.memory/correctness_checking/error-handling.md @@ -191,6 +191,66 @@ Correctness verification for `references/{language}/error-handling.md`. --- +## PHP + +**File:** `references/php/error-handling.md` (relative to skill root) + +### Tracking + +| # | Section | Status | Fix Applied | Sources | +|---|---------|--------|-------------|---------| +| 1 | Overview | unchecked | | | +| 2 | Application Errors/Failures | unchecked | | | +| 3 | Non-Retryable Errors | unchecked | | | +| 4 | Handling Activity Errors in Workflows | unchecked | | | +| 5 | Retry Configuration | unchecked | | | +| 6 | Timeout Configuration | unchecked | | | +| 7 | Workflow Failure | unchecked | | | +| 8 | Best Practices | unchecked | | | + +### Detailed Notes + +#### 1. Overview +**Status:** unchecked + +--- + +#### 2. Application Errors/Failures +**Status:** unchecked + +--- + +#### 3. Non-Retryable Errors +**Status:** unchecked + +--- + +#### 4. Handling Activity Errors in Workflows +**Status:** unchecked + +--- + +#### 5. Retry Configuration +**Status:** unchecked + +--- + +#### 6. Timeout Configuration +**Status:** unchecked + +--- + +#### 7. Workflow Failure +**Status:** unchecked + +--- + +#### 8. Best Practices +**Status:** unchecked + +--- + + ## Go **File:** `references/go/error-handling.md` (relative to skill root) diff --git a/.memory/correctness_checking/gotchas.md b/.memory/correctness_checking/gotchas.md index 548c3e6..2a5e160 100644 --- a/.memory/correctness_checking/gotchas.md +++ b/.memory/correctness_checking/gotchas.md @@ -290,6 +290,48 @@ Correctness verification for `references/{language}/gotchas.md`. --- +## PHP + +**File:** `references/php/gotchas.md` (relative to skill root) + +### Tracking + +| # | Section | Status | Fix Applied | Sources | +|---|---------|--------|-------------|---------| +| 1 | Wrong Retry Classification | unchecked | | | +| 2 | Cancellation | unchecked | | | +| 3 | Heartbeating | unchecked | | | +| 4 | Testing | unchecked | | | +| 5 | Timers and Sleep | unchecked | | | + +### Detailed Notes + +#### 1. Wrong Retry Classification +**Status:** unchecked + +--- + +#### 2. Cancellation +**Status:** unchecked + +--- + +#### 3. Heartbeating +**Status:** unchecked + +--- + +#### 4. Testing +**Status:** unchecked + +--- + +#### 5. Timers and Sleep +**Status:** unchecked + +--- + + ## Go **File:** `references/go/gotchas.md` (relative to skill root) diff --git a/.memory/correctness_checking/observability.md b/.memory/correctness_checking/observability.md index 2c7e4e0..24079fb 100644 --- a/.memory/correctness_checking/observability.md +++ b/.memory/correctness_checking/observability.md @@ -188,6 +188,76 @@ Correctness verification for `references/{language}/observability.md`. --- +## PHP + +**File:** `references/php/observability.md` (relative to skill root) + +### Tracking + +| # | Section | Status | Fix Applied | Sources | +|---|---------|--------|-------------|---------| +| 1 | Overview | all good | | context7 sdk-php | +| 2 | Logging / Replay-Aware Logging | needs verification | | context7 sdk-php | +| 3 | Customizing the Logger | needs verification | | context7 sdk-php | +| 4 | Search Attributes (Visibility) | all good | | context7 sdk-php | +| 5 | Best Practices | all good | | context7 sdk-php | + +### Detailed Notes + +#### 1. Overview +**Status:** all good + +**Verified:** +- PSR-3 logging mention is correct (PHP SDK uses PSR-3 compatible loggers) +- Replay-aware workflow logger claim is consistent with SDK design +- Search Attributes for visibility is correct + +--- + +#### 2. Logging / Replay-Aware Logging +**Status:** needs verification + +**Issues:** +- `Workflow::getLogger()` API is plausible but could not be directly confirmed in Context7 documentation +- PSR-3 logger interface for activities is correct (standard PHP practice) +- Claim that workflow logger "automatically suppresses duplicate log messages during replay" is plausible but unverified +- **`WorkerOptions::new()->withEnableLoggingInReplay(true)` could not be verified** — this method may or may not exist + +**Note:** Unable to verify logging PHP-specific API due to limited documentation availability. + +--- + +#### 3. Customizing the Logger +**Status:** needs verification + +**Issues:** +- **`logger` parameter on `$factory->newWorker()` could not be verified** — worker factory may accept a logger elsewhere (e.g., on the factory itself or via DI) +- Monolog integration pattern is plausible (Monolog is the standard PSR-3 logger for PHP) + +**Note:** Unable to verify custom logger injection point due to limited documentation availability. + +--- + +#### 4. Search Attributes (Visibility) +**Status:** all good + +**Verified:** +- Cross-reference to `references/php/data-handling.md` is correct and appropriate + +--- + +#### 5. Best Practices +**Status:** all good + +**Verified:** +- `Workflow::getLogger()` recommendation is correct +- Warning against `echo`/`print()` in workflows is correct (output on every replay) +- PSR-3 loggers in activities recommendation is correct +- Search Attributes recommendation is correct + +--- + + ## Go **File:** `references/go/observability.md` (relative to skill root) diff --git a/.memory/correctness_checking/patterns.md b/.memory/correctness_checking/patterns.md index 1500eba..4f0bae7 100644 --- a/.memory/correctness_checking/patterns.md +++ b/.memory/correctness_checking/patterns.md @@ -553,6 +553,60 @@ import { proxyLocalActivities } from '@temporalio/workflow'; --- +## PHP + +**File:** `references/php/patterns.md` (relative to skill root) + +### Tracking + +| # | Section | Status | Fix Applied | Sources | +|---|---------|--------|-------------|---------| +| 1 | Signals | all good | | context7 sdk-php | +| 2 | Dynamic Signal Handlers | FIXED | Changed `array $args` to `ValuesInterface $arguments` | context7 sdk-php, temporal-docs | +| 3 | Queries | all good | | context7 sdk-php | +| 4 | Dynamic Query Handlers | FIXED | Changed `array $args` to `ValuesInterface $arguments` | context7 sdk-php, temporal-docs | +| 5 | Updates | all good | | context7 sdk-php | +| 6 | Child Workflows | all good | | context7 sdk-php | +| 7 | Handles to External Workflows | all good | | context7 sdk-php | +| 8 | Parallel Execution | all good | | context7 sdk-php | +| 9 | Continue-as-New | FIXED | Added `yield`, fixed signature to `(string $type, array $args)` | context7 sdk-php, temporal-docs | +| 10 | Saga Pattern | all good | | context7 sdk-php | +| 11 | Wait Condition with Timeout | all good | | context7 sdk-php | +| 12 | Waiting for All Handlers to Finish | all good | | temporal-docs | +| 13 | Activity Heartbeat Details | FIXED | Used `hasHeartbeatDetails()` + typed `getHeartbeatDetails('int')` | context7 sdk-php | +| 14 | Timers | all good | | context7 sdk-php | +| 15 | Local Activities | all good | | context7 sdk-php | + +### Detailed Notes + +#### 2. Dynamic Signal Handlers +**Status:** FIXED +**Issue:** Handler parameter was `array $args` — should be `ValuesInterface $arguments` per SDK API +**Source:** temporal-docs, php.temporal.io API reference + +--- + +#### 4. Dynamic Query Handlers +**Status:** FIXED +**Issue:** Same as Dynamic Signal Handlers — parameter type was wrong +**Source:** temporal-docs, php.temporal.io API reference + +--- + +#### 9. Continue-as-New +**Status:** FIXED +**Issue:** `continueAsNew()` requires `(string $type, array $args, ?ContinueAsNewOptions $options)`. Was missing `yield` and passing state directly instead of as `[$state]` array. +**Source:** context7 sdk-php — shows `Workflow::continueAsNew('WorkflowName', [$args])` + +--- + +#### 13. Activity Heartbeat Details +**Status:** FIXED +**Issue:** Used `Activity::getHeartbeatDetails()` as array. Correct API is `Activity::hasHeartbeatDetails()` check + `Activity::getHeartbeatDetails('int')` for typed retrieval. +**Source:** context7 sdk-php + +--- + ## Go @@ -708,5 +762,3 @@ import { proxyLocalActivities } from '@temporalio/workflow'; - `workflow.ExecuteLocalActivity` API ✓ - `workflow.LocalActivityOptions` struct ✓ ---- - diff --git a/.memory/correctness_checking/testing.md b/.memory/correctness_checking/testing.md index 5ccb05f..d61e7ad 100644 --- a/.memory/correctness_checking/testing.md +++ b/.memory/correctness_checking/testing.md @@ -200,6 +200,66 @@ Correctness verification for `references/{language}/testing.md`. --- +## PHP + +**File:** `references/php/testing.md` (relative to skill root) + +### Tracking + +| # | Section | Status | Fix Applied | Sources | +|---|---------|--------|-------------|---------| +| 1 | Overview | unchecked | | | +| 2 | Test Environment Setup | unchecked | | | +| 3 | Activity Mocking | unchecked | | | +| 4 | Testing Signals and Queries | unchecked | | | +| 5 | Testing Failure Cases | unchecked | | | +| 6 | Replay Testing | unchecked | | | +| 7 | Activity Testing | unchecked | | | +| 8 | Best Practices | unchecked | | | + +### Detailed Notes + +#### 1. Overview +**Status:** unchecked + +--- + +#### 2. Test Environment Setup +**Status:** unchecked + +--- + +#### 3. Activity Mocking +**Status:** unchecked + +--- + +#### 4. Testing Signals and Queries +**Status:** unchecked + +--- + +#### 5. Testing Failure Cases +**Status:** unchecked + +--- + +#### 6. Replay Testing +**Status:** unchecked + +--- + +#### 7. Activity Testing +**Status:** unchecked + +--- + +#### 8. Best Practices +**Status:** unchecked + +--- + + ## Go **File:** `references/go/testing.md` (relative to skill root) diff --git a/.memory/correctness_checking/versioning.md b/.memory/correctness_checking/versioning.md index 4885ddd..3b1c287 100644 --- a/.memory/correctness_checking/versioning.md +++ b/.memory/correctness_checking/versioning.md @@ -291,6 +291,71 @@ Correctness verification for `references/{language}/versioning.md`. --- +## PHP + +**File:** `references/php/versioning.md` (relative to skill root) + +### Tracking + +| # | Section | Status | Fix Applied | Sources | +|---|---------|--------|-------------|---------| +| 1 | Patching API | all good | | context7 sdk-php | +| 2 | Workflow Type Versioning | all good | | context7 sdk-php | +| 3 | Worker Versioning | needs verification | | context7 sdk-php | +| 4 | Best Practices | all good | | context7 sdk-php | + +### Detailed Notes + +#### 1. Patching API +**Status:** all good + +**Verified:** +- `Workflow::getVersion('changeId', Workflow::DEFAULT_VERSION, 1)` signature is correct +- `yield` on `getVersion()` is correct (it is a coroutine) +- `Workflow::DEFAULT_VERSION` constant is correct +- Three-step patching process (patch in, deprecate with min=max=1, remove) is correct +- The reference checks `$version === 1` for new code; official SDK example checks `$version === Workflow::DEFAULT_VERSION` for old code. Both are logically equivalent and correct. +- `TemporalChangeVersion` search attribute in query filters is correct + +--- + +#### 2. Workflow Type Versioning +**Status:** all good + +**Verified:** +- `#[WorkflowInterface]` and `#[WorkflowMethod(name: '...')]` attributes are correct +- V2 interface pattern is valid +- `registerWorkflowTypes()` API is correct +- `$client->newWorkflowStub()` with `WorkflowOptions::new()` is correct + +--- + +#### 3. Worker Versioning +**Status:** needs verification + +**Issues:** +- **`WorkerDeploymentOptions` class name could not be fully verified** — Context7 docs do not include Worker Versioning configuration examples for PHP SDK. +- The `deploymentOptions` parameter on `$factory->newWorker()` could not be verified. +- Worker Versioning is noted as Public Preview which is correct. +- Legacy API deprecation timeline (March 2026) is correct. +- PINNED vs AUTO_UPGRADE conceptual descriptions are correct. +- CLI commands (`temporal worker deployment set-current-version`, `TemporalWorkerDeploymentVersion` search attribute) are correct. + +**Note:** Unable to verify Worker Versioning PHP-specific API due to limited documentation availability. + +--- + +#### 4. Best Practices +**Status:** all good + +**Verified:** +- All 5 best practices are valid +- "Use `yield` on `getVersion()`" is correctly emphasized as PHP-specific +- Guidance aligns with official documentation patterns + +--- + + ## Go **File:** `references/go/versioning.md` (relative to skill root)