InteractionKit
Experimental software often mixes what is manipulated, what is measured, and what gets written to data. InteractionKit makes those relationships explicit before a study runs: each interaction pattern is a typed contract that names its construct, its experimental role, and the exact output columns it emits — so a composition can be checked mechanically, and every data column can be traced to the pattern instance that produced it.
Frozen · v1.0.0 publicly tagged · contract-tested software · no participant data
Three failures this contract layer is built to avoid
Hidden roles. Manipulation and measurement logic buried in UI code, so no reviewer can tell what was manipulated or measured without reading the implementation.
Orphan columns. Behavioral datasets whose columns have no recorded origin, making analysis preparation guesswork.
Late composition bugs. Invalid study ordering discovered only when the study software already runs.
What each pattern declares
The released artifact ships three patterns as JSON Schema contracts. Select one to inspect its construct, experimental role, parameters, and emitted columns. Every output row also carries patternName, patternVersion, trialIndex, scenarioId, and (for ConfidenceDisplay) aiOutput and aiIsCorrect as required columns; each pattern's output schema is closed (additionalProperties: false).
Role labels describe the experimental contract — where the pattern sits in a study design. They do not establish construct validity.
Construct
AI uncertainty communication
The observable representation of an AI system's uncertainty shown before a reliance decision.
Parameters
- format — point_only | range | calibrated_badge
Composition position
- allowedAfter: — (must come first)
- allowedBefore: RelianceDecision
Contract-specific output columns (required)
| Column | Contract constraint |
|---|---|
| displayFormat | point_only | range | calibrated_badge |
| confidenceVisible | boolean |
| confidenceSignalType | point | interval | calibration_summary |
| confidencePoint | number 0–1 or null |
| confidenceRangeLower | number 0–1 or null |
| confidenceRangeUpper | number 0–1 or null |
| calibratedAccuracy | number 0–1 or null |
Role labels describe the experimental contract — where the pattern sits in a study design. They do not establish construct validity.
Construct
Behavioral reliance on AI
A participant's observable choice to accept or reject an AI recommendation.
Parameters
- mode — "binary" (fixed)
Composition position
- allowedAfter: ConfidenceDisplay
- allowedBefore: OutcomeFeedback
Contract-specific output columns (required)
| Column | Contract constraint |
|---|---|
| humanDecision | rely | reject |
| decisionType | "binary" (fixed) |
| responseTimeMs | integer ≥ 0 |
| isOptimalReliance | boolean (reliance matches AI correctness) |
| relianceClassification | appropriate_reliance | appropriate_rejection | overreliance | underreliance |
Role labels describe the experimental contract — where the pattern sits in a study design. They do not establish construct validity.
Construct
Decision outcome feedback
Information shown after a reliance decision that reveals whether the selected action was correct.
Parameters
- timing — "immediate" (fixed)
Composition position
- allowedAfter: RelianceDecision
- allowedBefore: — (terminal)
Contract-specific output columns (required)
| Column | Contract constraint |
|---|---|
| feedbackFormat | "immediate" (fixed) |
| feedbackOutcome | correct | incorrect |
| decisionCorrectness | boolean (whether the reliance choice was optimal) |
| feedbackShownAt | ISO 8601 timestamp |
Can this composition be checked before the study runs?
The composition engine checks ordering, input availability, and branch compatibility, then derives one data schema that records which pattern instance produced each column. Each case below is pinned by an executable test in the released artifact.
Schema validity is a property of the software contract, not of the science: a composition that passes these checks is legal to run — nothing here establishes that a study built on it is scientifically valid.
Ordered primitives
What the engine checks
- Ordering respects each pattern's allowedAfter / allowedBefore constraints.
- Required inputs are available from the initial input or earlier pattern outputs.
- Output columns merge into one derived schema with column origins.
Derived-column provenance (example)
The merged schema records every origin of the column scenarioId:
- ConfidenceDisplay@1.0.0#uncertainty
- RelianceDecision@1.0.0#reliance
- OutcomeFeedback@1.0.0#feedback
Pinned evidence: test: Sequence validates and derives a schema with column origins · test/pattern-system.test.ts
Ordered primitives
What the engine checks
- OutcomeFeedback may only run after RelianceDecision, so starting with it violates the ordering constraint.
- Reversing the sequence also removes the inputs later patterns require.
Rejection reasons
- ordering not allowed
- required input missing
Pinned evidence: test: Sequence rejects missing inputs and disallowed ordering (asserts both error kinds) · test/pattern-system.test.ts
Ordered primitives
What the engine checks
- A Choice composition requires every branch to emit the same output columns.
- The short branch omits the OutcomeFeedback columns, so the branches differ.
Rejection reasons
- branches emit different output columns
Pinned evidence: test: Choice requires branches to emit the same columns · test/pattern-system.test.ts
What this artifact supports — and what it does not establish
What this artifact supports
- Released, typed experiment contracts exist for three interaction patterns, each naming its construct and experimental role.
- Composition ordering and branch compatibility are mechanically checked before a study runs.
- The derived data schema records which pattern instance produced each output column.
- Contract behavior is pinned by executable tests in the released artifact.
What this artifact does not establish
- Construct validity of any pattern.
- Psychometric validity of any collected measure.
- Measurement reliability.
- Human effects or participant results (none exist).
- Causal effects.
- Cross-lab behavioral reproducibility.
- Cross-implementation equivalence.
- Deployment effectiveness.
Where the evidence lives
Every projection on this page is transcribed from the pinned release: the three pattern schemas, the composition engine, and the executable contract tests. The repository's own quick-start reproduces the release payload: npm ci && npm run test:patterns && npx tsc --noEmit && npm run build.
Reading rule: a design-time contract, an object-level intervention system, and a run-time evaluation log answer different questions. InteractionKit supplies the first layer; it does not establish that studies built on it will produce valid or reliable measurements.
Study status
A two-condition study design using these patterns has written design materials and a draft registration document. The study is not registered, has no ethics approval, has collected no participant data, and is deferred — it is not an active priority. This page exists because the design-time contract layer is a released, tested artifact, not because any study has run.