You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
op_system's convolve_history/history_eval_fn machinery has a real, enforced runtime contract: callers pass a history_provider object whose .query(signal_id, body, **options) method gets forwarded as __hist_query inside the compiled history-aware closure (compile.py:1279-1318). This is documented today only as README prose ("Runtime contract from lowering: __hist_query(signal_id, body, **options)") and typed as bare history_provider: object on every public signature that accepts one (CompiledRhs.history_eval_fn, PytreeEvalFn-adjacent wrappers, etc.) — there is no actual Protocol class in the public API to type-check an implementation against.
This matters concretely now: ACCIDDA/op_engine#67 (revised) needs to port ACCIDDA/COVID19_USA's _history.py — a ~400-line fixed-cadence ring-buffer DDE/history provider — into op_engine as the backing implementation for diffrax-based adaptive methods. Without a formal HistoryProvider Protocol exported from op_system, that port has nothing concrete to implement against beyond README prose, and there's no structural protection if the implicit contract drifts as op_system's lowering evolves (e.g. if query's keyword-only options shape changes, nothing would catch a mismatch until a downstream runtime failure).
Scope
Define class HistoryProvider(Protocol): def query(self, signal_id: int, body: Array, **options: object) -> Array: ... (exact signature to be confirmed against the real call site at compile.py:1289) in _typing.py (alongside the existing Array protocol) or a new small module.
Export HistoryProvider from op_system.__init__'s public __all__.
Update CompiledRhs.history_eval_fn and any other history_provider: object-typed signatures to use the new Protocol instead of bare object.
Update the README's runnable convolve_history example (ZeroHistoryProvider class) to reference/type-annotate against the new Protocol.
Acceptance criteria
HistoryProvider importable from op_system.
history_provider parameters across the public API use the Protocol type instead of object (narrows an instance of the broad-object-typing pattern already tracked generally by Tighten backend typing in compile API (replace broad object usage) #78, specifically for this one parameter).
mypy --strict passes for touched modules.
Existing history/convolve_history tests unaffected (this is a typing-only change, no runtime behavior change).
Relationship to other issues / repos
Directly motivated by ACCIDDA/op_engine#67 (diffrax/lineax-backed adaptive methods, needs to port a HistoryProvider implementation) and ACCIDDA/op_engine#26 (tracking). Narrower, protocol-specific instance of the broader typing cleanup tracked by #78.
Motivation
op_system'sconvolve_history/history_eval_fnmachinery has a real, enforced runtime contract: callers pass ahistory_providerobject whose.query(signal_id, body, **options)method gets forwarded as__hist_queryinside the compiled history-aware closure (compile.py:1279-1318). This is documented today only as README prose ("Runtime contract from lowering:__hist_query(signal_id, body, **options)") and typed as barehistory_provider: objecton every public signature that accepts one (CompiledRhs.history_eval_fn,PytreeEvalFn-adjacent wrappers, etc.) — there is no actualProtocolclass in the public API to type-check an implementation against.This matters concretely now:
ACCIDDA/op_engine#67 (revised) needs to portACCIDDA/COVID19_USA's_history.py— a ~400-line fixed-cadence ring-buffer DDE/history provider — intoop_engineas the backing implementation for diffrax-based adaptive methods. Without a formalHistoryProviderProtocol exported fromop_system, that port has nothing concrete to implement against beyond README prose, and there's no structural protection if the implicit contract drifts asop_system's lowering evolves (e.g. ifquery's keyword-onlyoptionsshape changes, nothing would catch a mismatch until a downstream runtime failure).Scope
class HistoryProvider(Protocol): def query(self, signal_id: int, body: Array, **options: object) -> Array: ...(exact signature to be confirmed against the real call site atcompile.py:1289) in_typing.py(alongside the existingArrayprotocol) or a new small module.HistoryProviderfromop_system.__init__'s public__all__.CompiledRhs.history_eval_fnand any otherhistory_provider: object-typed signatures to use the new Protocol instead of bareobject.convolve_historyexample (ZeroHistoryProviderclass) to reference/type-annotate against the new Protocol.Acceptance criteria
HistoryProviderimportable fromop_system.history_providerparameters across the public API use the Protocol type instead ofobject(narrows an instance of the broad-object-typing pattern already tracked generally by Tighten backend typing in compile API (replace broad object usage) #78, specifically for this one parameter).mypy --strictpasses for touched modules.convolve_historytests unaffected (this is a typing-only change, no runtime behavior change).Relationship to other issues / repos
Directly motivated by
ACCIDDA/op_engine#67 (diffrax/lineax-backed adaptive methods, needs to port aHistoryProviderimplementation) andACCIDDA/op_engine#26 (tracking). Narrower, protocol-specific instance of the broader typing cleanup tracked by #78.