picatz / picatz/flowstate

design: operational history, business data and audit evidence have three lifetimes and no verb, setting or document tells them apart — no run erasure exists, `DeleteSchedule` leaves its runs, redaction is not erasure, and Temporal retention starts only at close

Open
#1,901 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

design engine kind/design-record security
Dominant language
Go
Stars
9
Forks
0
Avg merge
3h 3m
Merged PRs (30d)
509

Description

Written against b015dc6.

Observed behavior

  • The service has DeleteSchedule (proto/flowstate/v1/service.proto:1266) and no run-erasure RPC. Deleting a schedule leaves the runs it started untouched.
  • Sensitive schedule inputs are redacted on readback (server/schedules.go:947-953); the stored values are not erased by that.
  • Temporal's history retention applies to closed executions, so a long-running workload has no expiry, and an exported history is a second copy with its own lifecycle.
  • The audit trail records decisions, not effects (DEPLOYMENT.md "Audit trail"), and may legitimately outlive the run it describes; nothing states its minimization or retention rules.
  • #1756 designs erasure as per-tenant key deletion. Two corrections belong on it and are posted there: the stock deployment resolves only the null codec (#1866), so "every payload is encrypted" is a seam and not the current behavior; and per-tenant key deletion erases a tenant, not one subject within a tenant.

One "delete everything" verb cannot describe all three classes honestly.

Desired outcome

A design record that names three data classes and gives each its own lifetime and verb:

  1. Operational history: Temporal events, activity results, RunState. Retention is per namespace today; the record says which tier gives which tenant which retention and what a long-running execution's expiry is.
  2. Business data: inputs and outputs a subject can ask to have erased. The record decides the unit of erasure (subject, run, tenant), the mechanism per unit (cryptographic erasure per #1756 for tenant, something finer for subject), and what a read of erased data returns (a typed Erased, per #1756).
  3. Audit evidence: decision records that may deliberately outlive the run. The record states what fields they carry (so no business value is quoted into them), their retention, and who may shorten it.

Each class gets one verb or setting, audited, and flow doctor (#1649) prints the effective retention for each.

Acceptance criteria

  • DEPLOYMENT.md has a table with the three classes, the setting or verb that governs each, and the tier it applies in.
  • A conformance case erases one run's business data and asserts operational history still describes the run, audit evidence still records its decisions, and flow get reports the inputs as erased.
  • The audit record's field list is pinned by a test so a business value cannot enter it.

Constraints and dependencies

  • Adjacent: #1756 (erasure by key deletion, which this record subsumes for the tenant unit), #1866 (null codec), #1733 (actions), #1863 (request_id "forever"), #1747 (claim-check bytes are business data too), #1649.
  • Invariant 7: erasure never requires a secret value to have been in history.

Open questions

  1. Does subject-level erasure need a subject identifier on inputs (a sensitive:-like marker) to be tractable at all?
  2. Who may shorten audit retention, and is it a two-person action (#1752)?

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the Audit trail section in DEPLOYMENT.md, DeleteSchedule in proto/flowstate/v1/service.proto, and the redaction path in server/schedules.go. Read the linked issues #1756, #1866, and #1649 before resolving the open questions about erasure units and audit retention. Done means the deployment table, conformance case, audit-field test, and effective-retention output are specified.

Written by the indexing model from the issue text.

Assessment

Tech stack
go
Domain
backend, documentation, security
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.