mirror of
https://github.com/LorenEteval/Furious.git
synced 2026-09-22 23:08:08 +03:00
32 lines
2.7 KiB
Markdown
32 lines
2.7 KiB
Markdown
# Interface guidance
|
|
|
|
Inherit the root and package guides. This file preserves dependency-light contracts that multiple implementations can
|
|
satisfy without importing application composition or concrete backends.
|
|
|
|
- This package defines dependency-light contracts shared across layers. It does not import Qt presentation,
|
|
controllers, services, repositories, plugins, or concrete backends; a contract may depend on a small model/constant
|
|
only when that does not trigger application construction or registration.
|
|
- Contracts specify observable ownership, lifecycle, mutation, serialization, callback, and failure semantics. Search
|
|
every representative implementation and contract test before changing one; an implementation may strengthen a
|
|
guarantee but cannot silently weaken it.
|
|
- Interface contracts and the separately versioned plugin API are different compatibility surfaces. Reject
|
|
unsupported shapes at their owning boundary and update implementations/exports together; do not invent a version
|
|
gate for every Python interface or remove an established adapter without tracing its callers.
|
|
- `CoreRuntime` is mechanism-neutral: embedded multiprocessing, direct `subprocess`, or an in-process binding can satisfy
|
|
it. It owns execution only: zero-argument start, passive liveness, typed terminal events, and bounded idempotent
|
|
stop/dispose. Preparation, serialization, readiness, and startup transactions belong outside this contract. Bind its
|
|
event sink once before start; raw exit interpretation occurs once at the concrete runtime boundary. Process/child
|
|
terminology belongs only to implementations that own one.
|
|
- `StorageBackend.data()` deliberately exposes a live mutable collection for compatibility. Do not reinterpret it as a
|
|
snapshot or introduce a second authoritative cache. Editor bindings map input to configuration and back; they do not
|
|
decide runtime, persistence, or host policy.
|
|
- `ApplicationRunner.ExitCode` is a process-boundary protocol. Model encoders may raise, while configuration
|
|
construction deliberately captures diagnostics; do not impose one blanket exception convention on those different
|
|
contracts.
|
|
- Runtime liveness is observational: querying it must not consume an exit, transfer ownership, or dispatch
|
|
callbacks. Keep semantic startup errors separate from raw process codes and readiness timeouts.
|
|
- Verify cheap/import-independent contracts plus representative runtime, storage, editor, application-exit,
|
|
encoding, and configuration implementations. Update this guide when a contract intentionally changes, together
|
|
with all implementers and compatibility tests. Start with `tests/test_interface.py` and
|
|
`tests/test_runtime_lifecycle.py`; include `tests/test_public_api.py` when imports or exports change.
|