Provenance

Every Layer 2 field MAY carry a provenance entry tagging its source. The provenance jsonb is keyed by dotted field path:

{
  "provenance": {
    "behavior.steps.0":      { "pattern": "C", "source": "cri_x + fix_y", "confidence": 0.85, "timestamp": "2026-05-02T11:00:00Z" },
    "behavior.steps.1.kind": { "pattern": "D", "source": "llm:claude-sonnet-4.6", "confidence": 0.70, "timestamp": "2026-05-02T11:01:00Z" },
    "behavior.steps.2":      { "pattern": "A", "source": "manual", "lockedByUser": true, "timestamp": "2026-05-02T11:05:00Z" }
  }
}

ProvenanceEntry shape

type ProvenanceEntry = {
  pattern:       "A" | "B" | "C" | "D";
  source:        string;              // free-form: "manual", "cri_x + fix_y", "llm:claude-sonnet-4.6", ...
  confidence?:   number;              // 0..1, only present for C / D
  lockedByUser?: boolean;             // default false
  timestamp:    string;               // ISO 8601
};

Pattern alphabet

Pattern	Meaning	Stored in provenance?
A — Hand authored	Human typed this directly.	Yes.
B — Convention default	Bridge codegen synthesised from Layer 1 + smart defaults.	No — applied at codegen time.
C — Inferred from examples	Deterministic synthesis from related atoms.	Yes.
D — LLM suggested	Generated by an LLM call (always tagged with model name in `source`).	Yes.

See Concepts → Four patterns for the why-this-split.

Path format

The key is a dotted path into the behavior jsonb. Examples:

behavior.steps.0 — the first step in a feature’s action chain (whole step entry).
behavior.steps.1.kind — the kind discriminator of step 1.
behavior.screens.list.sections.0 — the first section on the list screen of a ui_view.
behavior.before_after.state_diff — the entire state_diff block of a criterion.
behavior.enforced_at.0.kind — the kind of the first enforced_at entry on a rule.

Paths are arbitrarily deep; the merge logic walks them recursively.

The lock flag

lockedByUser: true blocks Pattern B / C / D from overwriting that field on subsequent re-runs. The lock is honored by the merge logic in any conformant tool.

function mergeWithLocks(
  current: { behavior: any; provenance: Record<string, ProvenanceEntry> },
  suggested: { behavior: any; provenance: Record<string, ProvenanceEntry> }
) {
  // For each field path in current.provenance with lockedByUser, keep current value.
  // Otherwise take suggested.
}

The cloud authoring UI exposes a 🔒 toggle in the Provenance tab (Tab 5). Lock things you trust:

Custom action chains you wrote by hand.
Steps that depend on a specific business invariant.
Endpoints the LLM keeps mangling.

Codegen ignores provenance

Codegen targets generally ignore provenance at lowering time — it’s an authoring-side concern. The lowering function consumes behavior directly. Provenance becomes load-bearing only when:

An authoring tool re-runs Pattern C or D (must respect locks).
An audit query asks “who set this field?”.
A diff UI badges fields by provenance pattern.