Shared capabilities and composition
What should a shared package own?
Reuse is valuable when it completes a defined task. File delivery, process resources, transactions and interfaces each need a clear account of what the shared capability establishes and what remains with the caller.
Choose the boundary around a useful result
Opening an SSH session and completely uploading a batch is independently useful. Deciding when a particular product should publish and activate introduces product policy. The package rules first remove project-specific vocabulary, then ask whether a task still has explicit inputs, results, failure meaning and resource settlement.
Base, System, Remote, Telemetry and Yaostate are selected by capability, not a mandatory stack every project must traverse. Shared tools do not imply shared business meaning. A file may be an image, configuration or user content; overwrite authority and activation remain separate decisions.
Place a successful upload within the complete delivery task
Consider an illustrative composition: delivering completed configuration to an authorized host. Base can retain the exact file and complete content, Remote can upload or publish it atomically in the destination directory, and System can handle native service operations and resources. The project still chooses the host, replaceable path, configuration validity and activation action.
Remote’s atomic publication completes one transfer and rename; it adds no filesystem synchronization, business activation or rollback. If rename may have been sent, the caller retains the original target and uncertainty. Closing the local session does not restore old remote content. The useful boundary is the result actually supplied.
| Capability | Supplied result | Caller responsibility |
|---|---|---|
| Base files and content | Retained files and complete reception or verification | Provenance, stability and overwrite authority |
| Remote publication | One transfer and atomic-replacement outcome | Business activation and extra durability requirements |
| System resources | Control and settlement of acquired native resources | Business readiness and effect scope |
| Project | Target, ordering and business decisions | Compare the final result with independent expectations |
A recorded transaction result does not own external effects
Yaostate supplies typed ordered transactions and results bound to the original operation, request and complete input. At most one business transaction and immutable result commit for that binding, but the handler may run several times after conflicts. One recorded result does not imply one handler execution.
Model calls, object uploads, file writes and external messages therefore stay outside the replayable handler. Projects keep external work with its actual owner and use transactions to interpret acquired results. Uncertainty retains the same request identity and input; a fresh key cannot substitute for an unresolved original.
| Result | Meaning | Unsupported inference |
|---|---|---|
| Recorded | A matching original result is retained | External systems completed automatically |
| Absent | No active-operation result at that snapshot | Never executed or unable to commit later |
| Closed / Purged | The operation has that maintenance state | The original request never committed |
Apply the same boundary to presentation
Common exposes separate entries for pure preferences, browser observations, Svelte composition and styles. Pure values need no browser. Explicit browser initialization acquires observation ownership, while Svelte adapts the application’s existing runtime and underlying owner. Shared presentation requires no second business-state system.
Projects still decide navigation destinations, action eligibility and whether an error permits retry. Components present those established facts clearly; a similar appearance does not imply equal authority. This describes Common’s designed capability, not completion of migration across downstream applications.
Retain the actual owner when work fails
Cancellation can mean only that the caller stopped waiting. Acquired children, mounts, transfers and writes still need settlement or explicit responsibility transfer. Shared packages concentrate that native handling. Projects need not reproduce internal mechanisms, but must retain any residual duty returned to them.
Error meaning determines the next step. Definite non-application, uncertain effects, business rejection and unavailable observation cannot collapse into one automatically retryable error. Preserving the distinction lets projects continue within the original effect scope.
Reuse a completed capability
Consume the public result while its input, platform and responsibility premises hold.
Do not enlarge the supplied guarantee
Local closure is not remote rollback; a transaction result is not external-effect proof.
Verify the consequential bindings left by composition
Consumer verification targets the remaining link between a public capability and the business result: the selected target, original input, result interpretation and ownership transfer. Applicable public guarantees need not be reconstructed in every project.
State the required result
Start with the caller’s task and identify inputs, effects and completion.
Check supplied guarantees
Identify what the public entry establishes and which premises remain caller-owned.
Observe the remaining binding
Use independent target and result observations to expose wrong destinations, repeated effects and lost ownership.