docs(spike): side-effect pods design spec (ITL-524)#227
Open
kurodo3[bot] wants to merge 13 commits into
Open
Conversation
…ecution hash (ITL-524) Adds superpowers/specs/2026-07-14-itl-524-side-effect-pods-design.md with a complete design resolving all 10 axes from ITL-524: pod taxonomy (new SideEffectPod class), pass-through output contract, author-declared idempotency, dual-hash (invocation_signature + execution_id), SideEffectContext auto-injection, fail-loud error semantics, DAG ordering, _orcapod_side_effect_invocations invocation log, full reverse-lookup path, and canonical orcapod-<hex> artifact serialization. Includes worked patient audit example with end-to-end reverse-lookup walk-through and explicit reconciliation with ITL-523 post-run hook. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
Remove premature commitment to '-> None' and pass-through contract from the Overview; those are Axis 2 outcomes argued in the Design section. Overview now describes the problem space and the provenance motivation only. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…-524) Goals & Success Criteria now describes what the spike produces (discussed, Edgar-approved decisions per axis) rather than front-loading the design outcomes. Adds explicit statement that final calls belong to Edgar. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…l (ITL-524) SideEffectPodProtocol defines the contract in protocols/; SideEffectPod implements it by extending _FunctionPodBase for implementation reuse. Mirrors existing protocol/implementation pattern throughout the codebase. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…ugh) (ITL-524) Two distinct pod kinds: SinkPod for completion-tracked terminal delivery to external sources, TapPod for always-fire pass-through observation. Retry policy deferred to ITL-526. Grouping under a shared SideEffectPod umbrella deferred. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…hash (ITL-524) Axis 3: SinkPod completion state machine (not-seen/success/failed), retry on explicit re-run only, retry policy deferred to ITL-526. TapPod always fires. Axis 4: Two-part invocation hash (pipeline_hash::full_input_packet_hash) using :: separator. TapPod adds verbatim pipeline_run_id as third component. Full input packet covers tag + data + source + system tag columns. InvocationHashConfig with encoding (hex/base64/binary) and component_length in bytes of raw digest. Table organisation mirrors FunctionNode: pipeline_hash scopes table, input packet hash is row key. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…ion (ITL-524) Single InvocationContext shared by SinkPod and TapPod. Framework injects it when the user function declares a parameter typed InvocationContext — detection by type annotation only, no magic parameter names. Fields: invocation_hash, pod_name, pod_content_hash, pipeline_run_id. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
SinkPodConfig / TapPodConfig with on_error: Literal["raise","log"]="raise". SinkPod always records status="failed" on error regardless of on_error. Logs FunctionPod async/sync error inconsistency as DESIGN_ISSUES F15 and files ITL-527 for future alignment. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Replace SinkPod/TapPod as distinct types with a single SideEffectPod governed by track_completion and pass_on_success config axes. Update Axes 1-6 accordingly. @sink_pod/@tap_pod become convenience decorators. Hash formula now conditioned on track_completion, not type name. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…-524) Rename config flag to drop_on_failure throughout spec. Record Axis 7 decisions: synchronous per-row delivery in v1, max_concurrency model, no global barrier. File ITL-528 for future fire-and-forget delivery mode. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…ITL-524) Invocation tables scoped by pipeline_hash(pod), mirroring FunctionNode. Reverse lookup: parse invocation hash → route to table → look up by full_input_packet_hash. Update column names, status values, lookup steps. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
format_id() accepts optional InvocationHashConfig override for per-call encoding/length control. Documents canonical orcapod- prefix convention, raw hash usage, and dropped InvocationIdentity base type. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
… (ITL-524) Update Reconciliation, Worked Example, Public API Summary, Tests, Scope, Dependencies, and task breakdown. Replace all SideEffectContext/SideEffectConfig/ InvocationIdentity/idempotent references with InvocationContext/SideEffectPodConfig/ track_completion/drop_on_failure. Expand tests to T18. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
superpowers/specs/2026-07-14-itl-524-side-effect-pods-design.mdon_errorvocabulary, proposedInvocationIdentityshared base typeKey design decisions
SideEffectPodclass (sibling ofFunctionPod, shares_FunctionPodBase)idempotent: bool = False; invocations always loggedinvocation_signature=sha256(pod.content_hash().digest + input.content_hash().digest)[:16].hex()(deterministic, 32 hex chars) +execution_id(UUIDv7, unique per run)SideEffectContextauto-injected by type annotationon_error: "raise" | "log"(consistent with ITL-523HookConfig)_orcapod_side_effect_invocationstable in pipeline DBorcapod-{invocation_signature}viactx.format_id()Test plan
_input_data_hashfromsystem_constants.INPUT_DATA_HASH_COL)hooks.pyreviewed against actual implementation (PR feat(function_pod): add post-run hook mechanism (ITL-523) #226)Fixes ITL-524
🤖 Generated with Claude Code