Research Payload Family
Research Payload Family shared core v0.1.0
Reusable parameters and selection ladders for choosing faithful data primitives, relationship structures, decision forms, state representations, and durable encodings from domain meaning and dominant operations.
v0.1.0
Begin with domain meaning and dominant operations, then choose the smallest structure that preserves both. This parameter pack turns a programming or systems-design question into an explicit working frame, a selection ladder, a comparison among fitting alternatives, and a proof plan.
Purpose
Use this pack when a research payload, implementation, review, or architecture decision needs to select:
- an atomic value and its semantics;
- a value boundary or aggregate;
- a collection and ordering model;
- a relationship topology;
- a decision form;
- a state representation;
- a durable encoding;
- a concurrency and mutation boundary.
The output is a revisable decision record. It makes the chosen structure, the alternatives, the evidence, and the conditions that would change the choice visible to the next collaborator.
Required parameters
Parameter | What to record | Why it changes the choice |
Problem statement | One observable outcome in domain language | Keeps the structure tied to work rather than syntax |
Domain invariants | Facts that must remain true | Defines the behavior the representation must preserve |
Dominant operations | Read, append, update, search, join, compare, traverse, schedule, reconcile, recover | Exposes the cost and ownership pattern that matters most |
Cardinality and scale | Typical, boundary, and credible growth ranges | Separates present fit from plausible pressure |
Ordering | None, stable insertion, sorted, priority, causal, temporal | Determines collection and event semantics |
Identity | Value identity, entity identity, composite key, content digest, external authority | Prevents accidental equivalence |
Missingness | Absent, unknown, withheld, inapplicable, empty, zero, unresolved | Preserves distinct states that carry different meaning |
Mutation | Immutable, append-only, single-owner mutation, coordinated mutation, event-sourced | Locates change authority |
Concurrency | Single process, multi-thread, multi-process, distributed, eventually consistent | Determines atomicity and conflict handling |
Lifetime | Expression, request, session, job, release, durable record | Connects in-memory design to persistence |
Failure and recovery | Retry, rollback, compensate, reconcile, quarantine, escalate | Makes partial state part of the design |
Target environment | Language, runtime, storage, interface, deployment boundary | Grounds the recommendation in available semantics |
Receiving decision | What this selection will enable | Defines completion |
Accountable receiver | Role that can accept the tradeoff | Keeps authority legible |
A missing parameter becomes an explicit open field when it changes the result. A provisional choice may continue when the open field and its promotion condition remain visible.
Working-frame declaration
State the frame before selecting a primitive or topology.
Frame field | Entry |
In view | The behavior, population, system boundary, and time horizon being represented |
Held aside | Adjacent concerns reserved for another layer or decision |
Dominant operation | The operation whose cost, correctness, or recoverability carries the decision |
Material consequence | What becomes unreliable, expensive, inaccessible, or hard to recover if the shape is wrong |
Evidence available | Source, fixture, trace, benchmark, production observation, domain review |
Decision horizon | Prototype, pilot, release, migration, or durable operating model |
Reopen signal | The observation that would make another shape more fitting |
This declaration is an attention instrument. It supports a deliberate choice while preserving a route back when the working frame changes.
Selection ladder
1. Name the domain atom
Choose the smallest value that has stable meaning.
Examples include a money amount with currency, a timestamp with time zone and clock meaning, a specimen identifier with issuing authority, a normalized code with vocabulary version, or a probability with population and horizon.
A scalar is sufficient when its meaning is complete at the point of use. A dedicated value type becomes useful when validation, units, provenance, or comparison rules travel with the value.
2. Preserve missingness and boundary states
Treat these as distinct candidates where the domain distinguishes them:
- absent;
- unknown;
- withheld;
- not yet observed;
- inapplicable;
- empty collection;
- explicit zero;
- unresolved conflict;
- invalid input;
- expired or superseded value.
Choose a representation that carries the distinctions through parsing, calculation, serialization, display, and recovery.
3. Draw the value boundary
Group values when an invariant belongs to the group.
A value object fits when equality follows content. An entity fits when identity persists across changing attributes. An aggregate fits when one boundary owns consistency. A record or product type fits when fields travel together without independent lifecycle. A tagged union fits when variants have distinct required fields and behaviors.
4. Choose the collection by dominant operation
Dominant need | Candidate shape | Evidence to seek |
Stable sequence and index access | Array or list | Boundary size, insertion pattern, ordering contract |
Membership and uniqueness | Set | Equality semantics, collision behavior, stable serialization |
Keyed lookup | Map or dictionary | Key authority, overwrite policy, missing-key behavior |
Priority retrieval | Heap or priority queue | Tie-breaking, update frequency, maximum size |
FIFO or bounded flow | Queue or deque | Backpressure, capacity, retry and dead-letter behavior |
Ordered range queries | Ordered map, tree, or indexed store | Comparator, update rate, persistence needs |
Relationship traversal | Graph or adjacency representation | Direction, density, cycle semantics, path questions |
Append and replay | Event log | Event identity, ordering, idempotency, snapshot and compaction |
Analytical scan | Columnar or tabular representation | Schema stability, missingness, partitioning, lineage |
The chosen collection should make the common operation ordinary and the consequential misuse visible.
5. Choose the relationship topology
Use ownership and lifecycle to distinguish:
- containment;
- reference;
- parent–child hierarchy;
- directed acyclic graph;
- cyclic graph;
- many-to-many relation;
- temporal relation;
- derived projection;
- event lineage;
- external authority link.
Record whether deletion, versioning, and permission travel across the relationship. A convenient pointer does not establish ownership; the decision record names the owner.
6. Separate data shape from decision shape
The same records can support several decision forms. Select the decision form from change pattern, traceability, and control flow.
Decision form | Strong fit | Watch point |
Guard clauses | A small ordered set of terminating conditions | Order carries meaning |
Lookup table | Stable mapping from normalized key to result | Table ownership and default behavior |
Decision table | Several conditions combine into auditable outcomes | Coverage of combinations and conflicts |
Rule set | Independently evolving policies or eligibility rules | Precedence, explainability, versioning |
State machine | Valid transitions and lifecycle matter | Illegal transitions, recovery, re-entry |
Decision tree | Hierarchical questions and bounded branches | Growth, duplication, stale branches |
Pipeline | Ordered transformations with stage-level evidence | Partial completion and replay |
Strategy or polymorphism | Stable interface with materially different algorithms | Selection authority and shared invariants |
Constraint solver | Many interacting constraints define a feasible set | Explainability, performance, deterministic replay |
Statistical model | Prediction under uncertainty | Population, calibration, drift, recourse, accountable use |
A large conditional can remain the clearest shape when its branches are few, stable, locally owned, and fully visible. Refactoring earns its place when a different shape improves change ownership, evidence, or recovery.
7. Model state and transition authority
For every mutable state, record:
- valid starting states;
- valid transitions;
- transition initiator;
- required evidence;
- idempotency key or replay rule;
- atomicity boundary;
- partial-state behavior;
- recovery or compensation route;
- durable receipt;
- terminal and reopen states.
Represent state explicitly when behavior depends on lifecycle rather than only current field values.
8. Choose the durable representation
Evaluate:
- semantic fidelity;
- schema evolution;
- deterministic serialization;
- human readability;
- machine validation;
- portability;
- referential integrity;
- partial-update behavior;
- migration and rollback;
- digest stability;
- long-term retrieval.
JSON, YAML, CSV, relational tables, document stores, event logs, binary formats, and graph stores each preserve different affordances. The decision names which semantics remain authoritative outside the format.
9. Place mutation, concurrency, and recovery
Prefer one clear mutation owner for each invariant. When several actors can write, specify conflict detection, serialization, optimistic or pessimistic coordination, idempotency, retry, and reconciliation.
A pre-check can support a helpful message. The operation that changes durable state remains the authority for success or failure. Atomic primitives, transactions, conditional writes, compare-and-swap, leases, and append-only records can narrow the interval in which observed state becomes stale.
10. Prove the choice
A fitting proof set includes:
- the ordinary path;
- empty and minimum states;
- maximum and boundary values;
- unknown, withheld, and inapplicable states where material;
- duplicate, collision, and ordering cases;
- invalid transition or malformed input;
- serialization and round-trip behavior;
- retry and replay;
- concurrent change where the environment permits it;
- recovery from an interrupted operation;
- migration from the nearest predecessor shape.
The Evidence-Bearing Verification Annex provides the reusable verification structure.
Comparison record
Score only after the frame and requirements are explicit. Use narrative evidence beside any ordinal rating.
Candidate | Meaning fidelity | Dominant-operation fit | Change ownership | Boundary behavior | Recovery | Portability | Evidence | Decision |
Candidate A | ||||||||
Candidate B | ||||||||
Candidate C |
A weighted score is a comparison aid. The written rationale, disconfirming evidence, and named tradeoff remain part of the decision.
Output contract
Return these elements in order:
- working-frame declaration;
- parameter register;
- domain invariants;
- missingness and boundary-state vocabulary;
- data-shape candidates;
- decision-shape candidates;
- ownership, mutation, and concurrency model;
- durable-representation candidates;
- comparison record;
- selected shape and rationale;
- proof cases;
- migration and recovery route;
- open evidence and reopen condition;
- accountable receiver.
Worked miniature
Problem: select a representation for claim-review status.
- Domain meaning: review status is a lifecycle with authorized transitions, rather than a free-form label.
- Material states: received, evidence_requested, under_review, approved, denied, appealed, superseded.
- Held aside: payment and remittance belong to adjacent processes.
- Candidate shapes: string field, enum, transition table, explicit state machine.
- Selected direction: explicit state machine plus append-only transition receipt.
- Reason: valid transitions, initiator authority, evidence, effective time, and appeal route are consequential.
- Proof: every valid transition; every illegal transition; retry of the same event; concurrent update; supersession; replay; durable round trip.
- Reopen signal: a second jurisdiction introduces materially different parallel or reversible states.
The miniature demonstrates method rather than prescribing a domain implementation.
Completion and re-entry
The parameter pack is complete for a decision when:
- domain meaning and invariants are explicit;
- the dominant operations and boundary conditions are evidenced;
- at least two credible candidates have been compared when a real alternative exists;
- ownership, mutation, persistence, and recovery are visible;
- the selected shape has a material proof plan;
- the accountable receiver and reopen signal are named.
Reopen when scale, operations, authority, concurrency, persistence, regulation, or evidence changes enough to alter the comparison.
Machine-readable companion
```yaml artifact: id: research-payload-family/decision-data-shape-parameter-pack type: ParameterPack version: 0.1.0 public_route: https://kindlight.systems/research-atlas-observatory/decision-data-shape-parameter-pack-meaning-operations-state-durable-representation-v01 inputs: - problem_statement - domain_invariants - dominant_operations - cardinality_and_scale - ordering - identity - missingness - mutation - concurrency - lifetime - failure_and_recovery - target_environment - receiving_decision - accountable_receiver selection_ladder: - working_frame - domain_atom - missingness_and_boundaries - value_boundary - collection - relationship_topology - decision_shape - state_and_transition_authority - durable_representation - mutation_concurrency_recovery - verification output: - decision_record - comparison_record - proof_plan - migration_and_recovery_route - reopen_condition ```
Source lineage
This parameter pack distills and connects these canonical Registry instruments:
- Working Frame Declaration — What Is in View, What Is Held Aside & What Changes the Frame
- Choosing a Decision Shape — Branches, Rules & State Transitions
- Data Shape & Structure Selection Ladder — Practitioner Probe
- Evidence-Bearing Test Design — Behavior, Boundary & Observable Proof
- Research Payload Family — Shared Core, Run Receipt & Promotion Boundaries
The named source pages retain their own scope and authority. This pack supplies a portable execution order and return shape.