Commit 1a95155
committed
docs(runtime-subsystem): document intercept hook, annotations, and cache integration
Updates docs/architecture docs/subsystems/4. Runtime & Middleware Framework.md
to reflect the M1 + M2 + M3 work that landed under TML-2143:
- Updated the runWithMiddleware lifecycle to start with the intercept
step, with hit-path semantics for skipping beforeExecute / runDriver /
onRow.
- Added the source field to the AfterExecuteResult shape shown in the
Middleware API section.
- New 'Intercepting Execution' section documenting RuntimeMiddleware.intercept:
chain semantics, hit path, row shape, verification ordering, error
path, the WeakMap-correlated plan-identity invariant (with a forward
reference to ADR 025), and family-agnostic construction with the cache
middleware as the canonical example.
- New 'Annotations' subsection covering OperationKind, defineAnnotation,
ValidAnnotations<K, As>, lane integration on SQL DSL + ORM Collection,
the runtime applicability check, plan.meta.annotations storage, and
reserved namespaces (codecs, target keys).
- Documented the new RuntimeMiddlewareContext fields: identityKey(exec)
(BLAKE2b-512 digest of the execution identity, populated by family
runtimes) and scope ('runtime' | 'connection' | 'transaction').
- Updated the lifecycle sequence diagram to branch on the intercept hit
vs. driver path and show source: 'middleware' / 'driver' on
afterExecute.
- Updated the Execution Pipeline and Connection Lifecycle text snippets
to reflect the intercept step.
- Updated the Rewriting ASTs scope note: short-circuiting via intercept
and user-authored annotations are no longer 'deferred to later
milestones' — they are documented above.
- Extended the Testing Strategy with the intercept matrix, annotation
surface, family identityKey impls, cache middleware unit + integration
coverage, and SQL runtime scope plumbing.
Closes C.2 of the cache-middleware project.1 parent 5d25e45 commit 1a95155
1 file changed
Lines changed: 141 additions & 26 deletions
0 commit comments