Skip to content

Concentrate Working context behind a runtime-owned module #46

Closed

Description

@frap129

What to build

Replace the runtime's scattered Working-context orchestration with one runtime-owned SessionWorkingContext module. Working context is the monotonic per-session set of observed file paths used when determining Matched rules and retained across compaction.

Construction returns two narrow facets backed by one implementation: a Working-context facet used by the runtime and the existing raw-history adapter facet used by RuleDelivery. SessionStore remains the physical storage implementation, but callers and tests no longer read or mutate its Working-context fields directly.

This is the surviving, narrowed form of architecture-review Candidate 03. It must not restore delivery bookkeeping to SessionStore; RuleDelivery continues to own its ledger, queues, and history-rescan lifecycle.

Acceptance criteria

Interface and ownership

  • The runtime-owned module exposes intent-specific Working-context operations for supplied-message seeding, durable-turn preparation, live tool-call recording, obtaining paths for matching, history invalidation, and compaction preparation.
  • Construction returns separate narrow Working-context and raw-history facets. Runtime callers do not learn readHistory; RuleDelivery does not learn Working-context operations.
  • The raw-history facet satisfies the existing RawHistoryAdapter seam. No second history interface, source registry, generic observation union, mode flag, or host-hook-shaped interface is introduced.
  • The runtime constructs the module alongside its runtime-owned RuleDelivery; the package composition root does not gain another injected implementation.
  • SessionStore remains an in-process implementation dependency with no adapter. Its retained fields use Working-context vocabulary, and only SessionWorkingContext production code reads or mutates them.

Working-context semantics

  • Paths remain a normalized, deduplicated, monotonic per-session set while the SessionStore entry remains resident. Message removal, compaction, history invalidation, and failed reads never subtract paths.
  • Supplied transform messages and successfully fetched raw history are alternative initial seeding sources. The first successful source marks seeding complete, including a successful empty history; live message parts and tool calls continue accumulating afterward.
  • Current user-message parts are accumulated before durable-turn history seeding, so Matched-rule evaluation sees both current and restored paths.
  • Existing path extraction, tool-to-path mapping, normalization, malformed-input tolerance, synthetic-part exclusion, deduplication, matching, and SessionStore eviction semantics remain unchanged.
  • Paths exposed for matching are detached and sorted with an explicit comparator; callers cannot mutate stored Working context.

History sharing, races, and failure

  • A history read used to seed Working context is retained as a one-use prefetch for RuleDelivery, avoiding a second external read.
  • At most eight completed, unconsumed prefetched histories are retained, in insertion order. Evicting a prefetch affects reuse only and does not alter Working context.
  • Concurrent durable-turn preparation for one session shares one in-flight history read; different sessions remain independent.
  • A per-session history revision prevents a read invalidated by message removal or compaction from seeding Working context or refilling the prefetch after it settles.
  • Supplied-message or live observations arriving during an in-flight read are preserved and unioned with any still-valid successful result.
  • An unavailable or rejected history read fails open: current paths remain available, Working context remains unseeded, the result is represented as { ok: false } for RuleDelivery to consume once, and a later durable turn may retry.
  • When RuleDelivery uses the raw-history facet without a prefetch, the facet delegates to the upstream adapter without seeding or otherwise mutating Working context.

Lifecycle integration

  • Message-removal handling independently invalidates Working-context history and marks RuleDelivery history changed; neither module depends on the other.
  • Compaction independently marks RuleDelivery compacted and invokes one Working-context operation that invalidates its history prefetch and returns the optional projection.
  • The compaction projection preserves the existing framing, sanitization, deterministic ordering, 20-path limit, and omitted-path count. Empty Working context produces no projection.
  • Prompt/model/agent capture, Rule snapshot pinning, RuleDelivery state, Matched-rule state, Hook evaluation, and matched-rule persistence remain outside SessionWorkingContext.

Cleanup and tests

  • Runtime-owned context-path extraction, history prefetch bookkeeping, seed orchestration, direct Working-context state access, and compaction formatting are removed after callers migrate.
  • The asymmetric test-only seed counter and getter are removed rather than reproduced in the new module.
  • Focused tests cross the SessionWorkingContext interface and pin both seeding sources, live accumulation, monotonicity, detached ordering, prefetch reuse/bounds, concurrent-read sharing, revision invalidation, fail-open retry, adapter fallback behavior, and compaction projection.
  • Existing tests that directly seed or inspect Working-context SessionStore fields migrate to the new interface or to observable runtime behavior. No new test-only state mutation hook is added.
  • Thin runtime integration tests continue to prove that transform history, durable-turn history, live tool calls, message removal, and compaction affect Matched rules and Rule delivery in the established order.
  • The domain glossary defines Working context, and the README Project Structure entry is updated for the new production module.
  • aube run lint, aubx tsc --noEmit, and aube run test:run pass in that order.

Non-goals

  • Deepening SessionStore as a general behavioral module.
  • Moving prompt/model/agent capture, Rule snapshots, RuleDelivery bookkeeping, Matched-rule state, or LRU policy into Working context.
  • Changing path extraction, normalization, matching, Hook behavior, delivery identities, persisted formats, sidebar behavior, compaction framing, or session eviction semantics.
  • Coupling Working-context invalidation to RuleDelivery or making RuleDelivery reads implicitly mutate Working context.
  • Adding compatibility exports, speculative adapters, configurable prefetch/projection limits, or new public package exports.

Blocked by

  • None (can start immediately).

Activity

  1. frap129 commented on Aug 29, 2026

    @frap129
    OwnerAuthor

    Delivered by b588554 on dev (refactor(rules): concentrate Working context behind SessionWorkingContext).

    All acceptance criteria met:

    • Interface and ownership: runtime-owned SessionWorkingContext in src/session-working-context.ts returns two narrow facets (Working-context ops + raw-history facet satisfying RawHistoryAdapter); SessionStore remains physical storage only.
    • Semantics: monotonic deduplicated paths, alternative seeding sources (supplied messages / fetched history, including successful empty), detached sorted views with explicit comparator.
    • Races and failure: one-use prefetch (max 8, insertion order), shared in-flight reads per session, revision invalidation, fail-open with retry.
    • Lifecycle: message removal and compaction independently invalidate; compaction projection preserves framing/limit/omission count.
    • Cleanup: runtime orchestration, seed counter/getter, and direct storage access removed; focused tests cross the module interface; glossary and README updated.
    • aube run lint, aubx tsc --noEmit, aube run test:run (442 tests) pass in that order.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    ready-for-agentFully specified, ready for an AFK agent

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions