TTY BPF Instrument Project Charter

Scoping Outline:

Challenges:

• What: "Create ways to..." / "Redesign the..."
  • Host-level observation instrument that can capture terminal byte activity at the kernel boundary without proxying, replacing, or modifying individual TTY devices.
  • Modular BPF-based instrumentation pattern that preserves raw observations, identity context, ordering evidence, fragmentation metadata, timing calibration, and visible loss/status information, while keeping semantic interpretation outside the probe.
  • Tracepoint strategy that is narrow enough to be plausible for upstream kernel acceptance, so long-term use of the instrument does not depend on a small team maintaining private kernel patches indefinitely.
• For Whom: "For <user>... (considering <other stakeholders>)..."
  • Developers, researchers, and infrastructure maintainers who need trustworthy records of terminal activity from multi-user Linux hosts, while preserving enough context for later reconstruction, validation, audit, or analysis.
  • Small research and instructional infrastructure teams that can use BPF-based host instrumentation, but may not have enough durable kernel expertise to maintain private patch sets indefinitely.
  • Future contributors and outside adopters who need the instrument to be understandable, modular, and useful outside its original project setting.
  • Considering kernel maintainers as critical design stakeholders: the tracepoint surface must remain minimal, general-purpose, and reviewable as kernel instrumentation, rather than treating the kernel as a project-specific logging subsystem.
  • Considering downstream consumers such as storage, analysis, privacy, governance, and reporting systems: the instrument should emit factual records with enough context to support those systems, without owning their policies or interpretations.
• Context: "In a world where..." / "Keeping in mind that..."
  • Terminal activity is transient: if TTY byte activity is not observed as it occurs, the exact bytes, timing, ordering context, and kernel-side identity context cannot be reconstructed later from ordinary application state.
  • TTY activity is structurally ambiguous: an apparent terminal session may involve shells, subprocesses, pseudoterminals, process privilege changes, etc. The instrument therefore needs to preserve raw identity axes rather than prematurely deciding what counts as a user, session, stream, or command.
  • Raw terminal bytes are sensitive: the API consumers should not treat capture as endorsement of unrestricted use. Privacy classification, redaction, retention, consent, access control, and governance belong to deployment policy and downstream systems - the instrument's role is to expose system state, so governance is an explicit responsibility of the user.
  • Private kernel patch maintenance is costly for a small research/infrastructure team: the tracepoint design should remain narrow, reviewable, and plausible for upstream acceptance wherever possible.
  • The module should remain application-neutral: EDURange motivates the first deployment and validation workload, but the instrument should be useful to outside users who need careful host-level TTY observation. As an open-source module, EDURange benefits from the instrument's broader circulation and adoption.

Considerations:

• Goals: "We aim to..."
  • Provide an application-neutral TTY observation instrument that can be used by both EDURange and by outside teams without embedding EDURange-specific assumptions into the core design.
  • Preserve captured terminal activity as raw bytes, not decoded commands, prompts, lines, or student actions.
  • Keep kernel-space behavior bounded, observational, and non-interpretive: the probe should copy bytes, attach factual context, assign ordering metadata, and emit records, not analyze terminal content.
  • Make loss visible. Capturing less data with accurate loss/status reporting is preferable to capturing more data whose completeness cannot be trusted.
  • Make sequence accounting, not timestamps alone, the primary basis for ordering and loss placement.
  • Preserve identity as an orthogonal vector of observed facts, not collapsed into a single inferred session identity.
  • Keep the architectural responsibilities clear: tracepoints expose attachment surfaces; BPF probes observe; the spool drains and forwards; and the collator reconstructs. Only downstream consumers interpret, store, redact, govern, or analyze.
  • Make the TTY instrument a reusable model for future host-level instruments, while avoiding premature generalization before the TTY capture path is empirically validated.
• Crux: "We really need to..."
  • Produce trustworthy host-wide TTY observations without turning the kernel into a private logging subsystem.
  • Determine whether the instrument can preserve enough byte, identity, ordering, timing, fragmentation, and loss context for downstream reconstruction while staying non-disruptive under realistic multi-user load.
  • Find the smallest maintainable MVP that demonstrates the full path from kernel observation to user-space reconstruction, while keeping open the long-term path toward upstream tracepoints and broader adoption.

Framing Checklist:

We should discuss these qualities:

• You tried on some behaviors (like empathy and rapid prototyping) on a current project before launching a new one.
• Project is a human, subjective challenge (understanding people is key to the project success).
• Project is geared toward discovery (not optimization).
• Challenge can be solved with a product, service, or event, not a strategy or system (for your first project).
• Those most affected by the work are acknowledged as actors with agency, not simply receivers of outcomes.
• Framing doesn’t embed a solution.
• Framing doesn’t (unintentionally) assume the form of the solution.
• Framing doesn’t (unintentionally) presume people’s needs.
• Goal of the project work is clear without dictating the specific solution outcome.
• You and your team actually care about this challenge. (If not, why are you doing it?)