RFC: aep/v0.3 — side-effect class, state-digest kind, drift evidence, approval mode

[telleroutlook]

Design principle (the only litmus test for fields)

The v0.3 schema is graded by whether a downstream reader can answer
three post-run questions from the persisted record alone, without
replaying the app:

1. What authority was available?
2. What authority was exercised?
3. What changed between approval and execution?

Each new field below exists to make exactly one of those answerable.
(Framing credited to @armorer-labs
in a comment on this RFC.)

Acceptance criterion — three-state comparability test

For every state_digest_* field a v0.3 record carries, a
third-party reader must be able to decide exactly one of three
states without further side-channel context:

1. comparable — the digest can be equality-checked against
   another digest of the same kind, without further assumption.
2. not comparable — the digest is recorded for observation
   only; equality is not asserted.
3. comparable under a named weaker assumption — equality
   holds only if the named assumption (e.g., "best-effort
   snapshot", "durable subset only") is accepted.

If a record forces the reader into "I don't know" rather than
one of the three above, the schema has failed at that record.
The per-kind coverage shapes in Gap 2 are graded against this
test, not against field-count exhaustiveness.

(Acceptance criterion credited to
@armorer-labs's fourth-round review.)

Summary

Draft RFC for aep/v0.3, motivated by external review of v0.2 from
@armorer-labs on
WasmAgent/wasmagent discussions #1
and #2,
followed by a second-round design review on this RFC itself.

The current aep/v0.2 schema covers most of what an authority receipt
needs, but four field-level gaps make the record harder to audit
after the fact than it should be. This RFC proposes targeted
additions; nothing in v0.2 is removed. A fifth gap (decision_envelope)
is intentionally deferred to v0.4 in projection-first form (see below).

Gap 1 — side_effect_class beyond a boolean

Today: state_changing: boolean on ActionEvidence.

Problem: A single bit collapses
read-only, mutate-local-sandbox, mutate-external-service, and
network-egress into the same bucket. Auditors and downstream
training filters can't recover which class a record actually was.

Proposal:

// On each ActionEvidence — canonical, source of truth:
side_effect_class: z.enum([
  "read",
  "mutate-local",
  "mutate-external",
  "network-egress",
  "unknown",
]).default("unknown");

// On the top-level AEPRecord — derived summary for training-pipeline
// cohort filters, never authoritative:
run_side_effect_class_max: z.enum([...same values...]).optional();

The unknown value is the default when a tool descriptor doesn't
type itself — paired with a runtime policy rule that downgrades
unknown side effects to require explicit approval at one level higher
than they would have if declared. (See Gap 4.)

state_changing: boolean stays for back-compat — derived from
side_effect_class != "read".

run_side_effect_class_max is explicitly documented as derived from
actions[].side_effect_class (the max under the read < mutate-local
< mutate-external < network-egress < unknown ordering). Consumers
that recompute it must get the same value, or the record is
inconsistent. The summary is for cheap filtering; the actions remain
the truth.

Gap 2 — state_digest_kind + state_digest_coverage

Today: pre_state_digest / post_state_digest are bare hex strings.

Problem: A consumer reading the record can't tell whether the
digest covers a git tree, a sandbox snapshot, a database row set, or
a browser DOM. The digest can stay opaque; the coverage cannot.
Two digests of different kinds, or of the same kind over different
scopes, are not comparable — so the record must say which kind and
over what scope.

Design principle for coverage descriptors:

A digest without a coverage descriptor is not a comparable digest.
A coverage descriptor without an identity-vs-selector split is not
a portable coverage descriptor.

Each coverage descriptor classifies its fields into four buckets,
enforced at the type level (intersection types per kind) even though
the serialized JSON stays flat:

Bucket	What it does	Used for equality?
identity	The "what" being observed; stable, joinable across runs (e.g., database_id, base_image_digest, origin+route_path+frame_path, namespace)	yes — required
selector	The subset chosen (predicates, excludes, selector roots)	yes — must match for equality
boundary	Comparability frame: snapshot id, capture phase, normalization policy	yes — when present, must match
observational	Diagnostic only (row count, file count, timestamps)	never sufficient for equality

TypeScript shape (every per-kind coverage type is a 4-way intersection):

type DbRowsetCoverage =
  CoverageIdentity<"db-rowset"> &
  CoverageSelector<"db-rowset"> &
  CoverageBoundary<"db-rowset"> &
  CoverageObservational;

git-tree is the gold standard — fully recomputable by an
independent reader given the same identity + selector. Other kinds
are graded by how close they get under the three-state acceptance
criterion above.

Proposal: Two paired fields. The kind is a closed enum:

state_digest_kind: z.enum([
  "git-tree",
  "sandbox-fs",
  "db-rowset",
  "browser-dom",
  "kv-snapshot",
  "memory-bag",
  "other",
]);

The coverage descriptor's shape varies by kind:

git-tree (gold standard)

{
  // identity
  tree_sha: string,            // git tree SHA
  tree_root: string,           // "/" or a subpath
  // selector
  path_predicate?: string,     // e.g. "src/**"
  excludes?: string[],         // e.g. [".git/**", "node_modules/**"]
}

Boring on purpose — easiest kind for any consumer to recompute
independently. Equality: tuple of all four fields.

db-rowset

{
  // identity (all required)
  database_id: string,         // operator-stable label, NOT a connection string
  schema: string,
  table: string,
  // selector
  rows_predicate: string,      // SQL or DSL
  query_hash: string,          // sha256(canonicalized predicate)
  // boundary
  snapshot_id?: string,        // Postgres txid / Oracle SCN / SQL Server LSN / ...
  isolation_level?: string,    // "snapshot" | "repeatable-read" | ...
  // observational
  row_count?: number,          // diagnostic only
}

Equality rule: two db-rowset digests are comparable iff
(database_id, schema, table, query_hash, snapshot_id) all match.
With snapshot_id missing, they are comparable under "best-effort, no snapshot" named weaker assumption. The hex digest alone is never
the authority on equality; the identity tuple is.

Raw connection strings are explicitly not used — they include
credentials, vary across replicas, and break equality under failover.

sandbox-fs

{
  // identity
  base_image_digest: string,   // OCI digest of sandbox base
  sandbox_root: string,
  // selector
  include_predicates: string[],
  exclude_predicates: string[],
  // boundary (silent-disagreement closers)
  symlink_policy: "follow" | "no-follow" | "reject",
  generated_paths_included: boolean,
  // observational
  file_count?: number,
}

Equality: identity + selector + boundary tuple. The base image +
symlink policy + generated-paths inclusion are what prevent two
runtimes producing different digests over byte-identical trees.

browser-dom

{
  // identity
  origin: string,              // https://example.com
  route_path: string,          // templated: "/orders/{id}/lines"
  frame_path: string,          // /iframe[0]/iframe[1]/...
  // selector
  selector_root: string,
  selector_kind: "css" | "xpath",
  // boundary (timing changes meaning of same selector)
  capture_phase: "pre-hydration" | "post-hydration" | "post-tool-result" | "stable-quiescent",
  capture_timestamp_ms?: number,
  attribute_order: "as-is" | "sorted-asc",
  whitespace_policy: "preserve" | "collapse",
  // observational
  text_only?: boolean,
}

route_path uses templated form (/orders/{id}/lines, not
/orders/12345/lines) so two requests to the same app route under
different IDs join naturally; the specific ID stays in the digest
itself. Fixes the same-origin-different-route failure mode (an agent
that approves on /orders/{id}/draft and drifts to executing on
/orders/{id}/posted — same origin, same frame, but different
application contract).

memory-bag and kv-snapshot

{
  // identity
  namespace: string,
  // selector
  key_predicate?: string,
  // boundary (one required if backend supports it)
  vector_clock?: Record<string, number>,
  read_timestamp_ms?: number,
  generation_number?: number,
  // boundary — lifecycle
  redaction_profile: string,   // references AEPRecord.redaction_profile
  durable_vs_scratch: "durable-only" | "scratch-only" | "mixed",
  // boundary — mixed-mode partition (REQUIRED when durable_vs_scratch === "mixed")
  mixed_partition?: {
    durable_keys: string[],    // or a predicate
    scratch_keys: string[],    // or a predicate
    audit_equality_basis: "durable-only" | "none",
  },
}

Mixed-mode digests stay emittable (some runtimes can't cleanly
partition without breaking observation) but are audit-comparable
only when mixed_partition is present. Without it, a mixed
digest is not comparable. With audit_equality_basis: "durable-only", it's comparable under named weaker assumption "durable subset only" — maps directly onto the three-state criterion.

The durable_vs_scratch field is the explicit fix for "operator
intent vs ephemeral scratch state" getting pooled.

kv-snapshot

Same shape as memory-bag; the difference is operator-managed vs
agent-internal namespace conventions.

other

Escape hatch for kinds not yet in the enum, with explicit
self-policing:

{
  other_kind: string,                // DNS-style namespace, e.g. "com.example.timestream"
  coverage_schema_version: string,   // vendor-managed semver
  description: string,               // human-readable
}

Namespaced other_kind means two vendors picking the same word
don't collide. The coverage_schema_version lets consumers decide
comparable / not-comparable / weaker-assumption for vendor-specific
kinds without first-class support. Self-policing rule: any namespace
hitting >5% of records is a graduation signal — promote into the
closed enum on the next minor bump.

---

Both pre_state_digest and post_state_digest share a single
state_digest_kind and state_digest_coverage per action (they
represent the same scope before vs after).

Validation rule: any record carrying a pre_state_digest or
post_state_digest must also carry both state_digest_kind and
state_digest_coverage. Records that can't supply the coverage
descriptor must omit the digest entirely. This forces interpretable
state evidence; opaque digest fields without scope are disallowed.

Gap 3 — argument_drift with one-action-per-record semantics

Today: approval_context_hash is a hash carried on the record;
the runtime checks at gate time that the call matches. If a call
gets blocked because of drift, the gate denies — but the persisted
record reveals it only implicitly.

Problem: A historical reader can't distinguish three cases:
(a) call matched approved args exactly,
(b) gate didn't run drift check,
(c) drift was detected and a re-approval happened.

Proposal: Add a typed field:

argument_drift: z.object({
  detected: z.boolean(),
  approved_args_digest: z.string(),
  observed_args_digest: z.string(),
  resolution: z.enum(["matched", "denied"]),
}).optional();

One-action-per-record rule: each ActionEvidence describes
exactly one semantic event. A drift that's denied produces a
self-contained record (decision: "deny", argument_drift.resolution: "denied"). If a re-approval then executes a changed payload, that's
a separate new ActionEvidence whose parent_action_id points
back to the denied one. The new record has its own
approval_context_hash matching the re-approval, and no
argument_drift field — it isn't drifting from anything.

This keeps each record describing one outcome (the denial OR the
later success, not both), and reuses the existing parent_action_id
linkage for the audit trail.

argument_drift.resolution is closed to "matched" | "denied". The
old "re-approved" value from the v1 draft is removed — that case
is now expressed as two linked records.

Gap 4 — approval_mode + approval_extension

Today: decision: enum(["allow", "deny", "ask_user", "dry_run"]).

Problem: ask_user collapses at least five behaviourally
distinct production cases (per @armorer-labs review of v0.2):

1. one-shot approval for an exact payload (payload hash bound)
2. bounded lease for a class of actions (TTL + invocation limit + scope)
3. policy allow with receipt (no prompt, but recorded reason)
4. policy deny with evidence (typed reason: identity / args / taint / scope / delegation)
5. re-approval on drift (model changed args after prior approval)

Proposal: Keep decision as the gross outcome
(allow | deny | ask_user | dry_run) and add an orthogonal mode as
a closed-set enum. Vendor-specific richness goes in a separate
extension object, NOT as other-* enum values — the closed enum is
what makes policy and audit queries stable across runtimes.

approval_mode: z.enum([
  "one-shot-payload",
  "bounded-lease",
  "policy-allow-with-receipt",
  "policy-deny-with-evidence",
  "re-approval-on-drift",
  "none",
]).default("none");

// Vendor / runtime-specific richness — does NOT widen the enum:
approval_extension: z.object({
  namespace: z.string(),     // vendor identifier, e.g. "armorer-labs"
  mode: z.string(),          // vendor-specific mode within that namespace
  evidence_digest: z.string(),
}).optional();

deny_reason_class: z.enum([
  "tool-identity",
  "argument",
  "tainted-input",
  "resource-scope",
  "missing-delegation",
  "policy-rule",
  "other",
]).optional();    // only when decision == "deny"

The bounded-lease mode is the value the v0.2 → v0.3 transition is
really about: it's the case that currently has no enforceable
representation between deny and ask_user, leading to either
rubber-stamp prompting or over-broad session-level approval.

A sixth mode that two runtimes agree on graduates from
approval_extension into the enum on the next minor bump. Until
then, vendor-specific modes don't fragment the policy query surface.

Gap 5 (deferred to v0.4) — decision_envelope as projection first

Today: Authority decision context is assembled across several
top-level fields: decision, subject, resource, capability,
policy_bundle_digest, scope_lease_id, approval_context_hash,
result_digest.

Proposal: Defer the nested record to v0.4. In v0.3, define the
envelope as a documented projection over the v0.3 top-level
fields, with golden-test fixtures showing the materialization.
Consumers that want a stable nested shape can materialize it from
the top-level data; the schema does not yet commit to a nested
record name or shape.

Projection target (subject to revision before v0.4 normative):

// Materialized by consumer code, not stored:
{
  action_class: <derived from side_effect_class>,
  target_boundary: <derived from state_digest_coverage>,
  principal_id: <subject>,
  run_id: <top-level run_id>,
  policy_id: <derived from policy_bundle_digest>,
  policy_version: <derived from policy_bundle_digest>,
  approval_or_lease_id: <approval_context_hash || scope_lease_id>,
  payload_digest: <argument_drift.observed_args_digest || tool_input_digest>,
  expiry_ms: <derived from scope lease, if any>,
  observed_result: <"success" | "failure" | "denied" | "skipped">,
}

Promotion criterion: v0.4 promotes the projection to a normative
decision_envelope nested record once two independent runtimes
emit data whose projection materializes identically on the same
inputs. Until that empirical bar is met, the projection stays in
docs + tests and the schema stays flat.

This avoids the naming-debate trap on a field that no consumer is
yet blocked on.

Migration

• v0.2 records parse fine under v0.3 schema (all new fields optional
  or have defaults).
• v0.3 emitters write schema_version: "aep/v0.3".
• Validators support both (Literal["aep/v0.1", "aep/v0.2", "aep/v0.3"]).
• The 12-dimension trust score already handles missing optional
  dimensions — no change needed there.
• state_changing: boolean stays for v0.2 reader back-compat, even
  though v0.3 emitters write both that field and the new
  side_effect_class.

Non-goals

• No change to the Ed25519 signature contract from v0.2.
• No change to delegation chain fields (parent_action_id,
  causal_chain_id, scope_lease_id) — those already match
  @armorer-labs's "delegation chain" item.
• No change to @wasmagent/otel-exporter mappings — the
  existing AEP↔OTel bridge stays.
• No nested decision_envelope record in v0.3 (deferred — see Gap 5).
• No other-* escape hatch in the approval_mode enum (use
  approval_extension instead).

Open questions (post-second-review)

The four questions in the original draft are resolved by the
second-round review. Remaining:

1. The per-kind state_digest_coverage shapes above are first
   drafts. Implementers who've handled a kind in production (db-rowset
   especially: cross-database joins? sharded tables?) — please
   comment with concrete examples that break the proposed shape.
2. Should argument_drift be allowed on decision: "allow" records
   (i.e., recording that drift was checked and matched), or only on
   deny? Default is to allow on both, but it inflates the
   common-path record.
3. The run_side_effect_class_max summary uses
   read < mutate-local < mutate-external < network-egress < unknown
   as the ordering. Is unknown correctly at the top
   ("treat-as-most-severe") rather than separate from the ordering?

Related

• @armorer-labs review (motivation): WasmAgent/wasmagent#1 and #2
• @armorer-labs second-round review on this RFC: #7 comment
• Current schema: packages/aep/src/types.ts
• Cross-repo contract: docs/aep-contract.md

---

Feedback welcome from anyone running AEP-equivalent audit records in
production, particularly on the per-kind state_digest_coverage
shapes and the decision_envelope projection target shape.

[armorer-labs]

Thanks for writing this up. My bias would be: ship the four point fixes in v0.3, and keep decision_envelope behind an experimental flag or defer it to v0.4 unless you already have cross-runtime consumers waiting on the nested shape.

A few concrete takes on the open questions:

• Keep side_effect_class canonical at the action level, but add an optional run/session summary as a derived max-class. That gives training/export pipelines a cheap cohort filter without making the summary the source of truth.
• For state_digest_kind, I would pair the enum with a small coverage/scope descriptor. db-rowset, sandbox-fs, and browser-dom only become comparable if the reader also knows the database/query boundary, sandbox root, browser origin/frame, or equivalent scope. The digest can stay opaque; the coverage cannot.
• I would let argument_drift.resolution: "denied" propagate to the parent decision only when the record represents the attempted execution. If the model later gets re-approved and executes a changed payload, that should be a separate final action record linked back to the denied drift evidence. Otherwise one record starts describing both the blocked attempt and the later successful action.
• I would keep approval_mode closed-set for the standard modes and add an extension object rather than an other-* enum value. The closed set is valuable for policy and audit queries; vendors can still put richer runtime-specific details under something like approval_extension: { namespace, mode, evidence_digest }.

On decision_envelope, the stable shape is useful, but it is also the field most likely to force naming debates. A practical middle step could be to define the envelope as a projection in docs/tests first: "given these v0.3 top-level fields, this is the portable envelope a consumer can materialize." Once two runtimes emit enough matching data, make the nested record normative.

The Armorer side would mostly care that the record can answer three post-run questions without replaying the app: what authority was available, what authority was exercised, and what changed between approval and execution. The v0.3 fields are close to that if the digest coverage and drift-linking semantics are explicit.

Disclosure: I work on Armorer Labs.

[telleroutlook]

Strong take. Accepting most of this; pushing back on one point; appropriating one framing as the new top-of-RFC design principle. Walking through them in your order.

Scope and sequencing — agreed. Ship the four point fixes in v0.3, defer decision_envelope to v0.4. No cross-runtime consumers are waiting on the nested shape today, and you're right that it's the field most likely to trigger naming debates that block v0.3 over a non-blocking concern. I'll edit RFC #7 to mark Gap 5 as v0.4 + "projection-first" (more below).

side_effect_class summary as derived, not source-of-truth — agreed and adopting verbatim. Adding an optional top-level run_side_effect_class_max on AEPRecord, explicitly documented as derived from actions[].side_effect_class (so training-pipeline writers know they can recompute it from action data and the summary can never disagree with the actions). The canonical answer stays at the action level.

state_digest_kind needs a coverage descriptor — agreed, this was the gap in my draft. "The digest can stay opaque; the coverage cannot" is exactly the right framing. Updating the proposal to pair state_digest_kind: enum with a state_digest_coverage object whose shape varies by kind:

// when kind == "db-rowset"
{ database: "postgres://...", schema: "public", table: "users", rows_predicate: "id IN (...)", row_count?: number }
// when kind == "sandbox-fs"
{ sandbox_root: "/work", path_predicate: "**/*.ts", file_count?: number }
// when kind == "browser-dom"
{ origin: "https://example.com", frame_path: "/iframe[0]/iframe[1]", selector_root?: "css|xpath" }
// when kind == "git-tree"
{ tree_root: "/", path_predicate?: "src/**", excludes?: [".git/**"] }
// when kind == "memory-bag"
{ namespace: "agent_memory", key_predicate?: "user_prefs::*" }

The exact shape per kind will need a small RFC of its own (or follow-up commits to RFC #7), but the principle is locked: a digest without a coverage descriptor is not a comparable digest, and v0.3 will not allow state_digest_* without both fields.

argument_drift.resolution: "denied" propagation — agreed, your model is cleaner. Updating the proposal so a denied drift produces a self-contained record (decision: deny, drift evidence on it, end of story for that record). If a re-approved retry executes a changed payload, it's a separate action record with parent_action_id pointing back to the denied one. That way no single record straddles two semantic events, and parent_action_id already exists in v0.2 so we get the linkage for free.

approval_mode closed-set + approval_extension — agreed, dropping the other-* escape hatch. Closed set is worth more for query stability than the cost of adding a separate extension field is. Final shape:

approval_mode: z.enum([
  "one-shot-payload",
  "bounded-lease",
  "policy-allow-with-receipt",
  "policy-deny-with-evidence",
  "re-approval-on-drift",
  "none",
]);

approval_extension: z.object({
  namespace: z.string(),     // vendor identifier, e.g. "armorer-labs"
  mode: z.string(),          // vendor-specific mode within that namespace
  evidence_digest: z.string(),
}).optional();

The split keeps the policy / audit / training-data layer working off a closed-set enum while leaving room for runtime-specific richness. If Armorer ends up with a sixth standard mode that two runtimes agree on, it graduates from approval_extension into the enum on the next minor bump.

decision_envelope as projection first — adopting. This is the change I'd push hardest of all the items, and it's clearly right. v0.3 will define the envelope as a documented projection over the new top-level fields, with golden-test fixtures showing the materialization. Once two runtimes (e.g., wasmagent-js and a hypothetical Armorer-Guard receipt layer) emit data that produces matching envelopes, v0.4 promotes the projection to a normative nested record. That gives consumers a stable shape now without committing the schema to a naming we'd regret.

---

Your three-question framing is the right top-of-RFC. Moving the Open Questions section out of the way and adding a "Design principle" block at the top of RFC #7:

The v0.3 schema is graded by whether a downstream reader can answer
three post-run questions from the persisted record alone, without
replaying the app:

1. What authority was available?
2. What authority was exercised?
3. What changed between approval and execution?

Each new field exists to make exactly one of those answerable.

This is sharper than anything I had in the original RFC. Crediting the framing inline.

---

Updating RFC #7 with all of the above. Will tag you on the edit so you can sanity-check the digest-coverage shape per kind — that's the part where I'm most likely to under-specify a kind that you've already hit in production.

Disclosure: I maintain wasmagent-js, the project being discussed.

[armorer-labs]

This direction looks right to me. The main thing I would tighten before implementation is to separate "coverage identity" from "coverage selector" so each digest kind has a stable equality story.

A few concrete shape notes:

• db-rowset: include a stable database identity that is not a raw connection string, plus schema/table/query identity and the transaction or snapshot boundary if the database can provide one. Row count is useful, but it is not enough to make two rowset digests comparable.
• sandbox-fs: include sandbox image/base digest, root, include/exclude predicates, symlink policy, and whether generated/ignored paths are inside the digest boundary. Otherwise two runtimes can hash the same apparent tree and silently disagree about node_modules, .git, temp files, or symlink targets.
• browser-dom: origin and frame path are good starts, but I would also include capture timing and normalization policy. A DOM digest taken before hydration, after hydration, or after an async tool result can all describe the same selector root but mean different things.
• memory-bag / kv-snapshot: include namespace, key predicate, version/vector clock or read timestamp if available, and redaction policy. These are often where agent systems accidentally mix durable operator intent with ephemeral scratch state.
• git-tree: keep this as the boring gold standard: tree SHA plus path predicate/excludes. It is the easiest one for downstream consumers to recompute independently.

For the open question on argument_drift, I would allow a compact matched form on allow records, but make the default emitter policy configurable. Compliance-heavy runs may want proof that the drift check happened and matched; high-volume telemetry may only want drift evidence when the result is deny. The important part is that the field should mean "drift check result", not only "bad drift event".

And yes, I would keep unknown at the top of the side-effect ordering for policy purposes. If a tool cannot describe its side-effect class, the runtime should treat it as the most conservative bucket. For analytics you can still segment unknown separately, but policy should not rank it below known network or mutation classes.

The projection-first decision_envelope plan feels like the right migration path. It gives consumers a target shape now, while keeping the v0.3 schema focused on fields that are already carrying audit weight.

Disclosure: I work on Armorer Labs.

[telleroutlook]

Adopting all of this — the "coverage identity vs coverage selector"
distinction is the right framing, and several of these (snapshot
boundary, capture timing, symlink policy) are exactly the kind of
thing that's silent disagreement between two runtimes until someone
tries to diff a digest in production.

Updating RFC #7's Gap 2 with revised per-kind shapes, walking through
your notes:

git-tree — keep as the gold standard

Locked. Tree SHA + path predicate + excludes is what makes this kind
trivially recomputable by an independent reader. Treating git-tree
as the "canonical equality story" that the other kinds should
approach.

db-rowset

Revised shape (your additions in bold-equivalent comments):

{
  // STABLE IDENTITY (not the raw connection string)
  database_id: string,         // e.g. "prod-orders" — operator-stable label
  schema: string,
  table: string,
  // QUERY IDENTITY
  rows_predicate: string,      // SQL or DSL — same shape across digests
  query_hash: string,          // sha256 of canonicalized predicate, for cheap equality
  // SNAPSHOT BOUNDARY (one of these required when DB supports it)
  snapshot_id?: string,        // Postgres txid, Oracle SCN, SQL Server LSN, ...
  isolation_level?: string,    // "snapshot" | "repeatable-read" | ...
  // OBSERVATIONAL
  row_count?: number,          // diagnostic only — never sufficient for equality
}

The database_id change is the biggest semantic shift: raw
connection strings include credentials, vary across replicas, and
break equality under failover. An operator-managed stable label
("prod-orders", "staging-billing") decouples digest identity
from infra topology.

snapshot_id is optional because not every DB exposes one, but when
it's available, two db-rowset digests are only comparable when
they share both query_hash and snapshot_id. Without the snapshot,
the digest is "best-effort at some unspecified time" and consumers
should treat it that way.

sandbox-fs

Revised shape:

{
  // IDENTITY
  base_image_digest: string,   // OCI digest of the sandbox base, e.g. sha256:...
  sandbox_root: string,        // absolute path inside the sandbox
  // SELECTOR
  include_predicates: string[],
  exclude_predicates: string[], // e.g. ["node_modules/**", ".git/**", "**/*.tmp"]
  // POLICY
  symlink_policy: "follow" | "no-follow" | "reject",
  generated_paths_included: boolean,  // are build artifacts inside digest scope?
  // OBSERVATIONAL
  file_count?: number,
}

The base_image_digest + symlink_policy + generated_paths_included
triple is what closes the silent-disagreement window you described.
Two runtimes can have byte-identical paths under sandbox_root and
still produce different digests if one followed symlinks into the
host filesystem or one included target/ while the other excluded
it. Making these explicit means an independent consumer can
recompute the digest if they have the same base image and policy.

browser-dom

Revised shape:

{
  // IDENTITY
  origin: string,              // https://example.com
  frame_path: string,          // /iframe[0]/iframe[1]/...
  // SELECTOR
  selector_root: string,       // CSS or XPath
  selector_kind: "css" | "xpath",
  // TIMING (one of these required)
  capture_phase: "pre-hydration" | "post-hydration" | "post-tool-result" | "stable-quiescent",
  capture_timestamp_ms?: number,  // milliseconds since last network-quiet event
  // NORMALIZATION
  attribute_order: "as-is" | "sorted-asc",
  whitespace_policy: "preserve" | "collapse",
  text_only?: boolean,         // strip element wrappers, hash only text content?
}

capture_phase is the field most likely to be wrong in practice —
a "DOM after the click" digest taken before vs. after hydration
describes the same selector root but different observable trees.
Treating the four phase values as the standard vocabulary; vendors
who need finer granularity can encode it in capture_timestamp_ms
relative to a documented anchor.

memory-bag and kv-snapshot

Revised shape:

{
  // IDENTITY
  namespace: string,           // "agent_memory", "session", ...
  key_predicate?: string,      // glob or DSL — same shape across digests
  // VERSIONING (one of these required if the backend supports it)
  vector_clock?: Record<string, number>,
  read_timestamp_ms?: number,
  generation_number?: number,
  // REDACTION
  redaction_profile: string,   // references the AEPRecord-level redaction_profile
  durable_vs_scratch: "durable-only" | "scratch-only" | "mixed",
}

The durable_vs_scratch field is the explicit fix for "operator
intent vs ephemeral scratch state" getting accidentally pooled —
agent systems routinely write both into the same KV namespace, and
digests over the mixed view are not safely comparable across runs.
A digest over durable-only is the meaningful one for audit; the
scratch-only and mixed values are recorded for completeness but
flagged as not-portable-for-equality.

redaction_profile here references the existing top-level
redaction_profile field on AEPRecord (packages/aep/src/types.ts:55) so the
record stays self-describing: a consumer reading the memory-bag
digest knows which fields were redacted before hashing.

kv-snapshot

Mostly the same shape as memory-bag but the namespace tends to
be operator-managed rather than agent-internal. Reusing the same
field structure.

other

Kept as-is — escape hatch for runtimes shipping a kind not yet in
the enum, explicitly flagged as non-portable for equality. Any
runtime emitting other for more than ~5% of records is a strong
signal a new kind should graduate into the enum.

---

The general rule that emerges from your notes — and that's now
written at the top of Gap 2 — is:

A digest without a coverage descriptor is not a comparable digest.
A coverage descriptor without an identity-vs-selector split is not
a portable coverage descriptor.

That's the principle the per-kind shapes are graded against.

Will push the RFC #7 edit shortly. Tagging you on the diff so you
can spot anything I've under-specified for kinds you've handled in
production.

Disclosure: I maintain wasmagent-js, the project being discussed.

[armorer-labs]

This revision looks much stronger. I like that each coverage kind now has an equality story instead of only a hashing story.

A few last sanity checks I would run before locking the v0.3 shape:

• Make coverage_identity and coverage_selector explicit in the type names, even if the serialized object stays flat. That forces implementers to ask which fields identify the thing being observed versus which fields choose the subset.
• Treat database_id, base_image_digest, origin/frame, and namespace as identity fields that should be stable enough for joins across runs. Treat predicates, excludes, and selector roots as selectors that may change per action.
• For db-rowset, I would avoid making comparability depend only on query_hash + snapshot_id; two databases can share the same query hash and snapshot-ish token. The stable database identity has to participate in equality too.
• For browser-dom, consider adding a url or route identity in addition to origin. A lot of agent failures happen across same-origin app routes where the frame path and selector root are identical but the application state is not.
• For memory-bag, the durable_vs_scratch field is good, but I would also make mixed mode noisy: valid to emit, but downgraded for audit equality unless the record explains which keys were durable and which were scratch.

On other: agreed as an escape hatch, but I would require a namespaced other_kind plus a short coverage schema/version string. Otherwise consumers cannot tell the difference between "new kind we understand out of band" and "opaque hash blob, do not compare."

The direction I would not over-optimize yet is perfect per-kind shape coverage. The useful test is whether a third-party reader can decide one of three states: comparable, not comparable, or comparable only under a named weaker assumption. If v0.3 can answer that consistently, the schema is already doing real work.

Disclosure: I work on Armorer Labs.

[telleroutlook]

Accepting all six and locking the three-state acceptance criterion as the spec's grading rule. Walking through them.

Type-level identity vs selector split — adopting. Updating the
TypeScript shapes to use intersection types:

type CoverageIdentity<K> = { /* the "what" — stable, joinable across runs */ };
type CoverageSelector<K> = { /* the "subset" — may change per action  */ };
type CoverageBoundary<K> = { /* the "comparability frame" — snapshot, timing, policy */ };
type CoverageObservational = { /* diagnostic only, NEVER sufficient for equality */ };

type DbRowsetCoverage =
  CoverageIdentity<"db-rowset"> &
  CoverageSelector<"db-rowset"> &
  CoverageBoundary<"db-rowset"> &
  CoverageObservational;

Serialized JSON stays flat (no nesting), but the type system forces
implementers to classify each new field into exactly one of the four
buckets. Misclassification becomes a compile error rather than a
silent semantic drift. Worth the boilerplate.

database_id participates in equality — adopting and tightening.
You're right that query_hash + snapshot_id is necessary but not
sufficient — two databases can produce the same query hash and the
same opaque snapshot token. Updating the equality rule for
db-rowset:

Two db-rowset digests are comparable iff
(database_id, schema, table, query_hash, snapshot_id) all match.
Without snapshot_id, the digests are comparable only under the
"best-effort, no snapshot" weaker assumption (see acceptance
criterion below) and consumers should treat them that way.

That iff is doing real work — the digest hex alone is not the
authority on equality; the identity tuple is.

browser-dom adds route_path identity — adopting. Adding:

{
  origin: string,
  route_path: string,    // e.g. "/orders/{id}/lines"
  frame_path: string,
  // ... existing fields ...
}

route_path is the application-level identity that distinguishes
same-origin app states. Templated form (/orders/{id}/lines rather
than /orders/12345/lines) so two requests to the same app route
under different IDs join naturally; the specific ID stays in the
selector_root or the page-content digest itself, not in identity.
Concrete failure mode this fixes: an agent that approves a "save
order" action on /orders/{id}/draft and then drifts to executing
on /orders/{id}/posted — same origin, same frame, but the
application contract changed.

memory-bag mixed mode noisy-but-valid — adopting. The
revised rule:

// In MemoryBagCoverage:
durable_vs_scratch: "durable-only" | "scratch-only" | "mixed";

// When durable_vs_scratch === "mixed", the record MUST also carry:
mixed_partition?: {
  durable_keys: string[];     // or a predicate
  scratch_keys: string[];     // or a predicate
  audit_equality_basis: "durable-only" | "none";
};

Mixed-mode digests stay emittable (some runtimes genuinely can't
cleanly partition without breaking observation) but they become
audit-comparable only when the partition is documented. Without
mixed_partition, a mixed-mode digest is not-comparable under
the acceptance criterion. With audit_equality_basis: "durable-only",
it's comparable under the named weaker assumption "durable subset only". Maps cleanly onto the three-state answer.

other escape hatch with other_kind + schema/version —
adopting. Updating:

{ description: string }  // OLD — too loose

// NEW
{
  other_kind: string,            // e.g. "com.example.timestream"
  coverage_schema_version: string,  // e.g. "1.0.0" — vendor-managed
  description: string,           // human-readable
}

Requiring a namespaced other_kind (DNS-style namespace like
com.example.timestream) means two vendors picking the same word
don't collide. The schema/version lets consumers decide
comparable vs not comparable vs comparable under weaker assumption for vendor-specific kinds without needing first-class
support. Self-policing rule unchanged: any namespace hitting >5%
of records is a graduation signal.

---

The acceptance criterion is going to the top of the spec, next
to the three-post-run-questions design principle. Your framing,
rewritten as a normative rule:

A v0.3 AEP record passes the comparability test if, for each
state_digest_* it carries, a third-party reader can decide
exactly one of:

1. comparable — the digest can be equality-checked against
   another digest of the same kind, without further assumption.
2. not comparable — the digest is recorded for observation
   only; equality is not asserted.
3. comparable under a named weaker assumption — equality
   holds only if the named assumption (e.g., "best-effort
   snapshot", "durable subset only") is accepted.

If a record forces the reader into "I don't know" rather than
one of the three above, the schema has failed at that record.

This is a sharper grade than "did we list enough fields per kind?"
It's what makes the per-kind shapes actionable rather than aspirational.

One thing I'm explicitly NOT optimizing further in v0.3, on your
guidance. Per-kind shape exhaustiveness. The mixed partition
shape for memory-bag and the route_path semantics for
browser-dom are the kind of detail that wants empirical data from
real runtimes before we lock the field names. v0.3 ships with the
shapes above; v0.4 or v0.5 refines them based on actual runtime
findings (yours, ours, or a third runtime's). The acceptance
criterion is the stable contract; the per-kind shapes are
evolving.

Will push the RFC #7 edit shortly. After this round I'd consider
the Gap 2 part of v0.3 done for spec purposes; remaining work is
gathering real runtime findings against it. Gaps 1, 3, 4 still
have first-round shapes that haven't gone through this depth of
review — if you have similar bandwidth for those, I'd take the
same treatment, but no pressure.

Disclosure: I maintain wasmagent-js, the project being discussed.

[armorer-labs]

Happy to take the same pass on Gaps 1, 3, and 4. I would do them one at a time, because each one has a different failure mode.

For Gap 1 (run_side_effect_class_max), the important invariant is that the run-level field is derived and never authoritative. I would make the derivation rule explicit enough that a consumer can recompute it from actions and fail the record if the summary disagrees. That also means unknown should dominate the max calculation for policy, while analytics can still segment it separately.

For Gap 3 (argument_drift), I would treat it as a check result with three useful states, not only as a bad-event container:

• checked and matched: optional to emit on high-volume runs, useful on compliance-heavy runs
• checked and drifted: mandatory when the payload changed between approval and execution
• not checked: explicit, so consumers do not confuse missing evidence with a match

The drift record should bind to the approval it is comparing against: approved argument digest, observed execution argument digest, canonicalization version, and the reason the runtime considered them matched or drifted. Otherwise different runtimes can agree that “drift happened” while disagreeing about what equality meant.

For Gap 4 (approval_mode), I would separate the grant shape from the decision outcome. one-shot-payload, bounded-lease, and policy-allow-with-receipt describe the authority shape; allow, deny, expired, revoked, and drift-requires-reapproval describe what happened to that authority. Mixing those into one enum makes lifecycle questions harder later.

A useful acceptance test for both Gaps 3 and 4 is: given only the persisted record, can a reviewer reconstruct whether the executed action was inside the exact authority that existed at execution time? If the answer requires reading runtime logs or trusting the model narrative, the fields are still too implicit.

So my suggested sequence would be:

1. Lock Gap 1 with a deterministic derivation rule and mismatch behavior.
2. Define Gap 3 around approval-to-execution equality, including canonicalization version.
3. Revisit Gap 4 after that, because the approval modes become clearer once drift has a crisp binding to an approval record.

Disclosure: I work on Armorer Labs.

[telleroutlook]

Accepting the sequence and the framing for all three. Working through each gap in your order.

---

Gap 1 — deterministic derivation rule + mismatch behavior

Adopting. Adding an explicit derivation rule to the spec:

ordering: read < mutate-local < mutate-external < network-egress < unknown

run_side_effect_class_max = max(actions[].side_effect_class) under the above ordering

For policy purposes, unknown is the ceiling — a run with any unknown action is treated as if it is the most conservative bucket, regardless of what the other actions declared. For analytics, unknown remains a distinct value that can be segmented separately from network-egress. The two uses are explicit in the spec comment so a reader knows why the ordering exists.

On mismatch behavior: I would make the record fail validation (schema-level reject, not a soft flag) when run_side_effect_class_max is present but disagrees with the recomputed value. The reason is that a soft flag ("warning: summary does not match") can pass silently through pipelines that do not read warnings. If a runtime is emitting an incorrect summary, a hard validation error surfaces the bug immediately. Consumers that omit run_side_effect_class_max entirely are fine — it is optional; the error only fires when the field is present and wrong.

Does that behavior match what you had in mind, or do you prefer the soft flag for a different reason?

---

Gap 3 — argument_drift as a check result

The three-state model is right and I am adopting it:

argument_drift: z.object({
  result: z.enum(["matched", "drifted", "not-checked"]),

  // required on both matched and drifted — binds to the specific approval
  approved_arg_digest: z.string(),
  observed_arg_digest: z.string(),
  canonicalization_version: z.string(),  // e.g. "1.0.0" — matches how equality was defined

  // required on drifted
  drift_reason: z.string().optional(),
}).optional();

Emit policy is configurable: drifted is always mandatory when the payload changed; matched is emitter-controlled (compliance-heavy runs emit it, high-volume telemetry can omit). not-checked is always explicit — its absence from the record is not interpretable as a match.

One question on not-checked: should a runtime that did not perform a drift check be required to emit an explicit not-checked record, or is omitting the field entirely allowed? My inclination is: if the runtime declared approval_mode at all, an omitted drift field is ambiguous (was the check skipped, or was the emitter lazy?), so not-checked should be required whenever approval_mode is not none. If approval_mode == "none", omitting argument_drift is fine. Does that framing match how you would handle it?

---

Gap 4 — authority shape vs. decision outcome

Separating into two fields:

// Authority shape — what grant the runtime issued
approval_grant: z.enum([
  "one-shot-payload",
  "bounded-lease",
  "policy-allow-with-receipt",
  "none",
]);

// Decision outcome — what happened to that authority at execution time
approval_decision: z.enum([
  "allow",
  "deny",
  "expired",
  "revoked",
  "drift-requires-reapproval",
]);

The separation makes lifecycle queries clean: WHERE approval_grant = "bounded-lease" AND approval_decision = "expired" is unambiguous; the original single enum mixed those into one string.

One open question on bounded-lease: the record should carry enough temporal data that a reader can independently verify whether the action was inside the lease window at execution time. Three candidate fields — lease_granted_at_ms, lease_duration_ms, lease_expires_at_ms — carry redundant information, but I would rather be explicit. My current inclination is to require at least two (e.g., grant time + duration, or grant time + expiry), so a reader can cross-check them and fail the record if they are inconsistent. Is that the right shape, or do you have a leaner preference?

---

Your acceptance test — "given only the persisted record, can a reviewer reconstruct whether the executed action was inside the exact authority that existed at execution time?" — is going to the top of the spec alongside the three-question design principle and the three-state comparability test. It is the right grade for both Gap 3 and Gap 4.

Disclosure: I maintain wasmagent-js, the project being discussed.

[armorer-labs]

Yes, that matches the shape I would want.

On Gap 1, I would make summary mismatch a hard validation failure when run_side_effect_class_max is present. Because it is derived, there is no useful partial-trust state: either consumers can recompute it from actions[].side_effect_class, or the record is internally inconsistent. Keeping the field optional is the escape hatch for emitters that do not want the summary yet.

On argument_drift, I would require explicit not-checked whenever an approval grant exists and the runtime did not compare the approved payload to the observed payload. Omitting the field is only safe when there was no approval boundary to compare against, such as approval_grant: "none". Otherwise absence reads too much like “matched” in downstream reports, which is exactly the ambiguity the field is supposed to remove.

I would also make the drift check bind to the specific authority artifact, not only the digests. Something like approval_or_lease_id, approved_arg_digest, observed_arg_digest, and canonicalization_version is enough for a reader to tell which grant was checked and what equality function was used. If the runtime later re-approves and executes a changed payload, that should be a new action record linked to the denied drift record, not a mutation of the old one.

For bounded leases, I would prefer a small redundant tuple and hard consistency checks:

• lease_id
• lease_granted_at_ms
• lease_expires_at_ms
• lease_duration_ms, optional but if present must equal expiry minus grant time
• execution_started_at_ms or the equivalent action timestamp used for the lease check
• invocation ordinal or remaining-invocation evidence if the lease has an invocation count

Requiring grant time plus expiry is clearer than grant time plus duration because it survives rounding and display differences better in audit views. Duration is useful as redundant diagnostic data, but I would not make it the only way to recover the boundary.

For expiry/revocation decisions, the persisted record should let a reviewer recompute the decision: action timestamp inside or outside the lease window, invocation count inside or outside the lease budget, and revocation event id or policy version if the grant was invalidated before nominal expiry. Without those, expired and revoked become labels the runtime asserted rather than decisions the record can support.

So the invariant I would use is: every non-none grant record must either prove the executed action was inside the grant at execution time, or explicitly say which check was not performed and downgrade the confidence of the record. That keeps “not checked” from being silently equivalent to “allowed.”

Disclosure: I work on Armorer Labs.

[HainingYin]

Three implementation-layer notes on the v0.3 shape that should be in the spec before we lock it, mostly to prevent two runtimes silently disagreeing on what an invariant means.

1. Scope the two "canonicalization versions" separately

argument_drift.canonicalization_version from Gap 3 and the AEP-record canonicalization used for the ed25519 signature (packages/aep/src/canonical.ts) are different scopes. The current canonical.ts is a whole-record key-sorted JSON encoder for signing; the drift field's canonicalization_version is per-argument equality semantics (e.g., "is {a:1,b:2} equal to {b:2,a:1} for drift purposes?", "how are floats normalized?", "are trailing whitespace and unicode NFC differences drift?").

If the spec doesn't separate them by name, implementers will reuse one version string for both, and the first time we bump the signing format we'll silently invalidate every prior drift comparison. Concrete suggestion: rename the drift field to something like args_equality_version (or payload_canonicalization_version), and add a one-paragraph "Canonicalization scopes" note to v0.3 listing every place a canonicalization version appears and what it governs.

2. Bind approval_grant: "bounded-lease" to the existing scope_lease_id

v0.2 already carries scope_lease_id on ActionEvidence (types.ts L30). With the new approval_grant enum, the spec should be explicit:

• when approval_grant == "bounded-lease", scope_lease_id is REQUIRED on the same action record;
• the lease-temporal fields from comment[8] (lease_id, lease_granted_at_ms, lease_expires_at_ms, optional lease_duration_ms, execution_started_at_ms, optional invocation ordinal) belong on a bounded_lease_evidence object, and bounded_lease_evidence.lease_id MUST equal scope_lease_id;
• when approval_grant != "bounded-lease", bounded_lease_evidence must be absent (not just optional-and-empty).

The drift binding @armorer-labs mentioned in comment[8] — "the drift check should bind to the specific authority artifact" — also lands here: argument_drift.approval_or_lease_id MUST equal scope_lease_id (when the grant is a lease) or approval_context_hash (when the grant is one-shot-payload). Otherwise we get two disjoint identifiers naming the same authority.

3. Decide which layer enforces "summary == max(actions[].side_effect_class)"

Comment[8] is firm that summary mismatch on run_side_effect_class_max should be a hard validation failure. Worth being explicit about which layer rejects: zod's pure type-shape schema can't express a cross-field invariant like "summary equals max(actions[].side_effect_class) under the defined ordering". Two reasonable places:

• (a) AEPRecordSchema.refine(...) — keeps the invariant in the schema module so any zod-based consumer enforces it automatically.
• (b) verifyAEPRecord() — keeps the schema purely structural and treats cross-field invariants as record-validation rules (alongside signature verification).

Both work; the spec should pick one and say so, otherwise wasmagent-js will enforce it in (a) and a second-runtime implementer will assume (b) and silently emit inconsistent summaries. My preference is (a) because it makes the rejection happen at parse time and gives the same behaviour to every zod consumer, but (b) is defensible if the project wants to keep AEPRecordSchema purely structural. Either way, the spec should also call out that consumers who don't use zod need to replicate the invariant — the comment in v0.3 schema source should explicitly list every cross-field invariant a non-zod implementer has to reproduce (today that's none; with v0.3 it becomes run_side_effect_class_max consistency + the bounded_lease_evidence ↔ scope_lease_id binding + the argument_drift.approval_or_lease_id ↔ authority binding).

---

None of these change the v0.3 design — they tighten where the invariants live so the spec doesn't read fine but get implemented inconsistently. Happy to follow up with a PR against packages/aep/src/types.ts that lays out the cross-field rules as concrete zod refinements once the shape is locked.

[armorer-labs]

These implementation notes are the right level to lock before the schema hardens. I would make two of them normative and one explicitly layered.

For the canonicalization naming, I would avoid a generic canonicalization_version anywhere except the whole-record signing path. Something like args_equality_version is clearer because it says what the version governs: the equality function between the approved payload and the observed payload. That lets signing canonicalization, argument equality, redaction canonicalization, and state-digest canonicalization evolve independently without pretending they are one global version.

For bounded leases, I would make the identifier binding fail closed:

• approval_grant: "bounded-lease" requires scope_lease_id
• bounded_lease_evidence.lease_id must equal scope_lease_id
• argument_drift.approval_or_lease_id must equal scope_lease_id for leases
• bounded_lease_evidence is invalid when the grant is not a lease

That gives a reviewer one authority artifact to follow. Otherwise the record can accidentally describe a lease in one field, a different lease in the drift evidence, and still look structurally valid.

On where to enforce cross-field invariants, I would put the cheap deterministic invariants in the schema refinement layer and leave cryptographic or external checks to verifyAEPRecord() or equivalent. So: run_side_effect_class_max recomputation, lease id binding, grant/evidence presence rules, and drift authority binding should fail at parse/validation time. Signature verification, trust-root checks, and any “does this policy version exist in the registry?” checks belong in the verifier layer.

The spec should still list the invariants in prose for non-zod implementers. Otherwise the TypeScript implementation becomes the real spec by accident, and a second runtime can claim v0.3 compatibility while only validating field names. A small “portable validation rules” section would be enough: structural shape, cross-field invariants, signature/canonical record verification, and optional registry/policy existence checks as separate tiers.

Disclosure: I work on Armorer Labs.