# Flow predicate language

Status: design decision record for Harn Flow v0. This page records the
predicate-language decisions and the implementation shape they imply.

Flow predicates are repo-local Harn functions that gate candidate slices. They
are not a separate DSL. A repository declares them in per-directory
`invariants.harn` files, and Flow discovers them with the same root-to-leaf
shape used by directory metadata. The goal is a policy surface that can be
audited, replayed, and proposed by agents without letting agents silently expand
their own authority.

## Implementation state

The design in this document assumes the following implementation state:

| Area | Status |
|---|---|
| Predicate executor and hard kind budgets | Landed. |
| Cross-slice fairness scheduler and aggregate budget envelopes | Landed. |
| `invariants.harn` discovery and attributes | Landed. |
| `InvariantResult`, evidence, and remediation types | Landed. |
| Hierarchical predicate composition | In progress. |
| Predicate hash replay audit | In progress. |
| Archivist persona | Landed as deterministic propose-only scan output. |
| Fixer persona | In progress. |

## Predicate declarations

Every shipping predicate is a top-level Harn function marked with
`@invariant` and exactly one execution kind:

```harn
@invariant
@deterministic
@archivist(
  evidence: ["https://example.com/team/security-rule"],
  confidence: 0.94,
  source_date: "2026-04-26",
  coverage_examples: ["crates/api/src/auth.rs"]
)
fn no_raw_tokens(slice) {
  return flow_invariant_allow()
}

@invariant
@semantic(fallback: no_raw_tokens)
@archivist(
  evidence: ["https://example.com/team/security-rule"],
  confidence: 0.84,
  source_date: "2026-04-26",
  coverage_examples: ["crates/api/src/auth.rs"]
)
fn no_raw_tokens_semantic_review(slice) {
  return flow_invariant_warn("semantic review found risky token-like text")
}
```

`@deterministic` predicates are pure Harn. They cannot use the network, shell,
LLM calls, host tools, clocks, random sources, or mutable ambient state.

`@semantic(fallback: name)` predicates may make one cheap judge call over
pre-baked evidence captured in `@archivist(...)`. The fallback must name a
deterministic predicate declared in the same `invariants.harn` file or an
ancestor file. They still cannot fetch fresh evidence during slice evaluation.

The result is an `InvariantResult`:

```harn
flow_invariant_allow()
flow_invariant_warn("needs cleanup soon")
flow_invariant_block("secret_leak", "raw token appears in the diff")
flow_invariant_require_approval("role", "security")
```

Evidence items point at atoms, metadata paths, transcript spans, or external
citations. Remediation is inert: it is input to Fixer, never an auto-apply
instruction.

## Decision 1: budget semantics under concurrency

Default stance: per-slice budget envelopes with a fairness scheduler.

Per-predicate global budgets are too easy to game. A slice can split one costly
semantic check into many tiny predicates and consume the same shared resources
while looking compliant. Per-slice serial budgets avoid that but create
head-of-line blocking: one semantic-heavy slice can delay small deterministic
slices behind it.

The v0 rule is:

- Each predicate keeps a hard local timeout by kind: deterministic predicates
  use the existing 50 ms CPU target, and semantic predicates use the existing
  2 s wall-clock target with one cheap judge call and a token cap.
- Each candidate slice also gets one aggregate evaluation envelope covering all
  predicates selected for that slice.
- The scheduler admits work fairly across slices, not just within one slice.
  When multiple slices are queued, no slice may occupy all semantic lanes, and
  deterministic work for later slices must continue to make progress while
  earlier semantic work is waiting.
- Budget exhaustion is a structured `Block` with code `budget_exceeded`, never
  a panic and never an implicit approval.

The simple implementation target is weighted round-robin across active slices:
run deterministic predicates first, then semantic predicates with a small
bounded semantic lane count. Within a slice, preserve deterministic output order
by sorting records after execution, as the current executor already does.

This keeps the mental model dumb: predicates are still ordinary Harn functions,
but admission control is owned by the Flow scheduler instead of by each
predicate.

### Implementation

The scheduler lives on
[`PredicateExecutor`](https://docs.rs/harn-vm/latest/harn_vm/flow/struct.PredicateExecutor.html)
and is configured via `PredicateSchedulerConfig`:

- `max_deterministic_lanes` / `max_semantic_lanes` — global concurrency caps
  shared across every queued slice. Deterministic and semantic lanes are
  independent semaphores, which is what makes deterministic work continue to
  make progress while semantic work is queued behind a scarce cheap-judge
  budget.
- `max_deterministic_lanes_per_slice` / `max_semantic_lanes_per_slice` —
  per-slice caps that prevent any single slice from occupying every global
  lane. The default semantic-per-slice cap of 1 plus FIFO permit ordering is
  enough to interleave queued slices fairly under the typical 2-lane semantic
  budget.
- `slice_deterministic_envelope` / `slice_semantic_envelope` — aggregate
  per-kind wall-clock envelopes for one slice. Once exhausted, every
  remaining predicate of that kind for that slice short-circuits to a
  structured `Block { error: { code: "budget_exceeded" } }` instead of
  silently allowing it through.

Use `PredicateExecutor::execute_slices(slices)` when more than one candidate
slice is queued together. The single-slice convenience method
`execute_slice(slice, predicates)` still works and routes through the same
scheduler so per-slice envelopes apply uniformly.

## Decision 2: bootstrap signing

Default stance: add a minimal, hand-authored root `meta-invariants.harn` that
governs predicate authorship. Archivist may propose edits to `invariants.harn`,
but Archivist may not author or auto-promote the root bootstrap policy.

`meta-invariants.harn` is intentionally smaller than normal predicate files. It
answers only "what predicate changes are acceptable for review?" and must not
become a second application policy layer.

The required bootstrap checks are:

- Predicate files must be valid Harn and must use `@invariant` plus exactly one
  of `@deterministic` or `@semantic`.
- Every non-bootstrap predicate must carry `@archivist(...)` provenance with
  evidence, confidence, source date, and coverage examples.
- `@semantic` predicates must name a deterministic fallback predicate in the
  same file or an ancestor file.
- External citations must be fetched at authoring time and pinned in the
  predicate metadata; evaluation-time network fetches are forbidden.
- Predicate edits proposed by Archivist remain propose-only. Promotion requires
  a human approval signature in the slice approval chain.
- Edits to `meta-invariants.harn` require human maintainer approval and are
  validated against the previous committed bootstrap policy hash. The initial
  root file is seeded by a human-reviewed commit.

This is similar in spirit to supply-chain attestation systems such as
in-toto/SLSA: the policy code, the subject it evaluated, and the actor that
approved it must be separable audit facts. Harn's subject is a Flow slice rather
than a build artifact, but the trust boundary is the same.

### `meta-invariants.harn` shape and validators

The bootstrap file is parsed by the existing Harn lexer/parser — the only
syntactic novelty is a top-level `@bootstrap_maintainers(approvers: [...])`
attribute that lists human maintainer roles or principals allowed to promote
bootstrap edits. A maintainer entry is `"role:<name>"` (matched as
`Approver::Role`) or `"user:<id>"` / any other string (matched as
`Approver::Principal`). Repos that omit the attribute fall back to a single
`role:flow-platform` approver — the same default used by the Ship Captain
predicate-count ceiling.

Two Rust functions in
`crates/harn-vm/src/flow/predicates/bootstrap.rs` carry the policy:

- `validate_predicate_edit(proposed_source, author, previous_policy)` runs
  the bootstrap rules against a proposed `invariants.harn` edit. Missing
  `@archivist(...)` provenance, partial provenance fields, kind-collision
  attributes, and unresolved semantic fallbacks are all promoted from the
  parser's soft warnings into hard `Block` verdicts with stable codes
  (`bootstrap_missing_archivist`, `bootstrap_archivist_provenance_incomplete`,
  `bootstrap_kind_collision`, `bootstrap_missing_semantic_fallback`,
  `bootstrap_unresolved_semantic_fallback`). The previous bootstrap policy
  hash is pinned in the validation result so the slice approval chain has an
  explicit audit pointer.
- `validate_bootstrap_edit(proposed_source, author, previous_policy)` runs
  against a proposed `meta-invariants.harn` edit. Archivist authorship is a
  hard `Block` (`bootstrap_archivist_cannot_author_bootstrap`); any
  non-Archivist actor returns `RequireApproval` routed to one of the
  previous policy's maintainers (or the default role on initial seed). The
  previous policy hash and the proposed policy hash are both pinned in the
  result.

`harn flow ship watch` and `harn flow archivist scan` now surface the
discovered bootstrap policy alongside the existing predicate validation
payload. When `meta-invariants.harn` is present at the predicate root, the
JSON output includes `bootstrap_policy.status = "present"` together with the
policy hash and the resolved maintainer list; otherwise the field reports
`status = "absent"` and the path Flow looked for. The actual `Block` /
`RequireApproval` verdicts from the validators are returned to in-process
callers (Archivist promotion, future `harn flow validate` subcommand) — Ship
Captain only surfaces the discovered policy hash and maintainers, since
Phase 0 doesn't yet evaluate proposed edits during atom emission.

## Decision 3: semantic predicate determinism

Default stance: every `@semantic` predicate must have a deterministic fallback.

Pinned model identifiers and temperature zero are useful audit metadata, but
they are not a replay guarantee. Provider behavior, model patch versions,
safety filters, and context packaging can drift. Treating semantic predicates
as inherently non-replayable is honest but too weak for a shipping gate.

The v0 rule is:

- `@semantic` predicates may influence a current slice only when they declare a
  deterministic fallback.
- The fallback must be evaluated and recorded in `invariants_applied` alongside
  the semantic predicate.
- If the semantic predicate and fallback disagree, the stricter verdict wins:
  `Block` over `RequireApproval` over `Warn` over `Allow`.
- Replay audits use the pinned predicate source hashes. Semantic result drift is
  advisory unless the deterministic fallback also fails.
- Predicate hashes include the predicate source. For semantic predicates, audit
  records should additionally retain model id, provider id, prompt hash,
  evidence hashes, token cap, and cheap judge version.

This keeps semantic checks useful for judgement-heavy review while making the
replay path depend on deterministic code. It also aligns with policy engines
such as CEL and OPA: fast deterministic checks should carry the enforceable
contract, while richer evaluators can annotate and escalate.

## Decision 4: cross-directory slice composition

Default stance: use the union of all predicates applicable to every touched
directory, with de-duplication for shared ancestors and explicit explosion
limits.

Intersection is unsafe. If a slice touches `docs/` and `crates/harn-vm/`, the
predicate set common to both directories may exclude the VM-specific invariant
that actually matters. Union is stricter and matches the semantics users expect:
touching a directory means accepting that directory's rules.

The v0 rule is:

- For each touched directory, collect root-to-leaf `invariants.harn` files.
- Union the resulting predicate declarations across touched directories.
- De-duplicate shared ancestors by `(source_dir, predicate_name)`.
- Keep same-named predicates in sibling directories independent.
- Compose ancestor and child results by strictness. A child may tighten an
  ancestor, but it cannot relax a shallower `Block`; equal strictness keeps the
  shallower predicate canonical.
- Enforce a predicate-count ceiling before evaluation. If a slice exceeds the
  ceiling, Flow returns a structured `RequireApproval` or `Block` explaining
  the predicate explosion instead of silently skipping rules.

### Default ceiling

The `PredicateCeiling::default()` in `crates/harn-vm/src/flow/predicates/compose.rs`
sets:

- `require_approval_threshold = 256` — at this size the `flow-platform` role
  is asked to co-sign before the slice ships.
- `block_threshold = 1024` — at this size Flow refuses the slice with the
  stable error code `predicate_count_explosion`.

These limits are operational, not perf. The
`crates/harn-vm/benches/flow_predicate_union.rs` benchmarks measure resolve and
ceiling-check cost across normal, high-fanout, and pathological fixtures: the
union itself is microsecond-scale even at ~2000 predicates and the ceiling
check is sub-100µs. The binding constraint is downstream evaluation —
deterministic predicates carry a 50ms wall-clock budget each, so a 256-predicate
slice can spend 13s of serial work before Ship Captain even renders results.
The ceiling makes that cost visible to a human before it becomes load-bearing.

The structured violation surfaces:

- `count` and `threshold` so operators can see how far over budget the slice is.
- Up to five `top_contributors`, each `{ relative_dir, count }`, so it is
  obvious which directory's `invariants.harn` is fanning out.
- `level` of `require_approval` or `block`.

`harn flow ship watch` already routes the violation into its
`predicate_validation.ceiling` payload and propagates the level into
`mock_pr.validation_status`.

The open implementation work is exhausted. Ship Captain may evaluate
cross-directory unions without a human in the loop only because the ceiling
makes the cost visible and bounded.

## Replay and audit contract

Every shipped slice records every predicate hash and result that gated it. A
later predicate change cannot retroactively unship historical work.

Replay audit is advisory by default:

- A slice is replayed against current `@retroactive` predicates.
- Drift is reported with current predicate hashes and historical-only hashes.
- `harn flow replay-audit --fail-on-drift` may turn advisory drift into a CI
  failure for repositories that want that policy.
- Historical slices are never rewritten by replay.

This matches the append-only Flow model: new facts create new atoms, slices, or
audit records; they do not mutate old shipping decisions.

## Archivist proposal scans

Archivist v0 is intentionally dumb and review-first. It does not promote
predicates and it does not fetch live evidence during slice evaluation. The CLI
entrypoint inventories a repository, loads the Flow persona manifest when it is
present, mines local convention and motion signals, and emits proposal records
with concrete Harn predicate source:

```bash
harn flow archivist scan . --json
harn flow archivist scan . --manifest examples/personas/flow.harn.toml \
  --store .harn/flow.sqlite --shadow-days 30 --out .harn/archivist/proposals.json
```

The JSON payload contains:

- `manifest`: whether the Archivist persona manifest loaded and which
  `[[personas]]` entry was used.
- `inventory`: detected stacks, lockfiles, config files, and source roots.
- `convention_signals`: lint/config files and inline `invariant:` comments.
- `motion_signals`: recent git-log buckets such as tests, formatting, Flow
  predicates, and release docs.
- `existing_predicates`: discovered `invariants.harn` predicates and discovery
  diagnostics.
- `proposals`: review-ready `@invariant` + `@archivist(...)` predicate source,
  evidence URLs, confidence, source date, coverage examples, and a permanent
  `propose_only` autonomy marker.
- `shadow_evaluation`: best-effort coverage against recent Flow atoms in the
  local SQLite store, including false-positive candidates with atom ids,
  transcript refs, and diff spans.

If no Flow store exists, `shadow_evaluation.status` is `no_flow_store` rather
than an error. That keeps initial repo bootstrap useful while making the
absence of atom history explicit.

## Remaining implementation work

The decisions above leave one concrete implementation gap beyond the landed
predicate runtime: deterministic fallback metadata and enforcement for
`@semantic` predicates. Bootstrap validation, approval-chain checks,
cross-slice scheduling, aggregate predicate budgets, and cross-directory
predicate ceilings are covered by the implementation described above.

## External reference points

The design intentionally stays close to proven policy and provenance shapes:

- CEL emphasizes fast, safe, host-data-only policy evaluation:
  <https://cel.dev/>.
- OPA treats side-effect-free policy evaluation as the normal case and requires
  care around I/O builtins:
  <https://www.openpolicyagent.org/docs/extensions>.
- in-toto and SLSA use attestations that bind subjects, predicates, and
  provenance:
  <https://slsa.dev/blog/2023/05/in-toto-and-slsa>.
