View source for 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?)