Friction Contribution

Version boundary. The hyodo friction command is introduced in HyoDo 4.17.0. HyoDo 4.16.x and earlier do not expose this command. Friction Contribution v1 is local only: HyoDo does not upload friction data, and network transport is disabled.

HyoDo can turn local hyodo.agent-event/v1 traces into coarse, privacy-transformed hyodo.friction-contribution/v1 records.

local agent events
      ↓
local friction derivation
      ↓
strict allow-listed contribution
      ↓ preview or explicit local export
hyodo.friction-export/v1

The point is to define the sensor contract before any population collector exists.

Check the instrument before using it

hyodo --version
hyodo friction --help

If hyodo --version reports 4.16.x or earlier, hyodo friction is not part of that installation. Upgrade to a 4.17.0-or-newer release before following the commands below. Release channels can publish at different times: do not infer that a package index already serves 4.17.0 from a source-tree version or a GitHub Release. The installed hyodo --version and command help are the runtime boundary that matters.

OFF by default

hyodo friction status
hyodo friction preview
hyodo friction on --yes
hyodo friction export --yes
hyodo friction off
hyodo friction contract --json

friction on means prepare derived contribution records locally. It is not network consent. The local state explicitly records network_consent: false, and Friction Contribution v1 has no upload transport.

A future collector must request fresh, separate consent rather than inheriting this local setting.

hyodo friction export is the separate Lane C local-file step. It requires enabled=true and explicit --yes, writes .hyodo/friction-export.json by default (or the user-provided --out path), and never uploads. Disabled state, missing confirmation in a non-TTY, or an unreadable ledger fail closed without silently writing an artifact.

The export envelope uses hyodo.friction-export/v1 and reuses the preview’s observation and 18-field contribution objects. It keeps exported_at at the envelope level and never adds run ids, event ids, actor ids, paths, prompts, raw arguments, or ledger rows.

What a contribution may contain

The strict v1 schema allows coarse fields such as:

{
  "schema": "hyodo.friction-contribution/v1",
  "source_schema": "hyodo.agent-event/v1",
  "hyodo_version": "4.17.0",
  "task_class": "code_change",
  "risk_bucket": "medium",
  "orchestration_pattern": "fanout",
  "event_count_bucket": "4-7",
  "parallelism_bucket": "2",
  "retry_bucket": "1",
  "rework_bucket": "0",
  "verification_failure_bucket": "1",
  "human_intervention_bucket": "0",
  "approval_wait_bucket": "none",
  "resource_conflict_bucket": "0",
  "evidence_completeness": "complete",
  "outcome": "pass",
  "provider_class": "anthropic",
  "source_quality": "complete"
}

The JSON Schema uses additionalProperties: false; print the installed contract with hyodo friction contract --json.

What cannot leave through this contract

There are no v1 fields for raw prompts, responses, source code, diffs, file contents, file paths, credentials, emails, raw commands, raw event bodies, event_id, run_id, actor_id, exact timestamps, persistent user IDs, or persistent machine IDs.

Some of those values may be inspected locally during derivation. For example, distinct actors sharing a step can establish a fan-out pattern, and timestamps around an ASK can establish a wait bucket. The source values are then discarded from the contribution shape.

Exact model names are reduced to a coarse provider class. Unknown evidence is reported as unknown or unobserved instead of being guessed.

Measurement boundary

Friction Contribution v1 derives coarse operational signals such as retry, rework, intervention, wait, resource-conflict, evidence-completeness, and outcome buckets. It does not automatically decide whether an observed friction episode was necessary, productive, or avoidable.

Those categories are research labels. Classifying them defensibly may require outcome context, causal comparison, independent review, or human annotation. A lower retry count, for example, is not automatically a better outcome if the missing retry would have caught an error.

Measured policy only

Caller-asserted ALLOW / DENY / ASK claims do not become friction outcomes. The deriver only reads a decision when HyoDo evaluator provenance is present in the ledger.

That keeps a caller from manufacturing a favorable population prior by simply claiming its own work was allowed.

The authority invariant

Population evidence → support recommendation  ✅
Population evidence → execution authority         ❌
Population evidence → override local policy       ❌
Population evidence → override Evidence Gate      ❌

Population experience can eventually help answer what support profile is useful here? It cannot answer whether this action is authorized?

That separation keeps three responsibilities distinct:

Authorization policy — whether?
Support allocation — what support profile?
Evidence validation — done?

No collector yet

v1 deliberately ships without a telemetry endpoint, uploader, installation identifier, population-prior download, or automatic support-allocation change. The export is a local, explicit file write only; it is not a collector. The first goal is an inspectable, reproducible local measurement contract.

See the support-allocation field note for the strategy-prior and collaboration-topology hypothesis, the Research page for the broader empirical program, and the repository’s docs/FRICTION_CONTRIBUTION.md for the detailed protocol boundary.