@mercuryo-ai/agentbrowse 0.2.61 → 0.2.63

package/docs/match-resolve-fill.md

@@ -0,0 +1,699 @@
+# Match / Resolve / Fill Guide
+
+`match`, `resolve`, and `fill` are the data-plane primitives on top of the
+AgentBrowse browser runtime. They exist to answer one deceptively simple
+question: **you have some key–value pairs in your runtime, and you want
+them to end up in the right fields of a form on the page — how do you do
+that cleanly?**
+
+This guide builds the model from first principles. It assumes you have
+already seen [`observe(...)`](./api-reference.md#observesession-goal) and
+[`act(...)`](./api-reference.md#actsession-targetref-action-value); if
+not, read [Getting Started](./getting-started.md) first.
+
+## The Problem
+
+You run `observe(session)` and you get back a page inventory: some
+observed targets (inputs, buttons), some fillable forms. In parallel,
+your runtime holds candidate values — from a profile, a vault, the
+current task context. Somehow you have to decide which value goes in
+which field, and then write it into the browser.
+
+The low-level primitive for writing is
+`act(session, targetRef, 'fill', value)`. It takes exactly one target
+ref and exactly one value string, and it fills the input. That's it. No
+decision logic, no lookup logic.
+
+If all you ever need is "I already know this target takes this value",
+`act(...)` is fine. Real integrations hit three concerns it does not
+help with:
+
+1. **Which candidate wins?** Your runtime has several values that could
+   plausibly belong in an observed field. Picking one by hand is fine
+   when there is a single correspondence (`email → email input`) but
+   becomes brittle when there are multiple candidates, host-specific
+   applicability rules, or protected targets that must be excluded from
+   open-data filling.
+2. **What if the value is not in hand yet?** Passwords, payment cards,
+   and anything behind user approval do not live in your process memory.
+   Something has to go fetch them — and ideally your fetch logic should
+   not be duplicated across every field that needs it.
+3. **What about values that must not touch the LLM prompt?** In agent
+   stacks, the orchestrating model sees everything in the prompt and in
+   the result objects it receives. Passing raw passwords through those
+   objects defeats the whole «kept out of the model» property that makes
+   vaults like MagicPay useful.
+
+The three primitives in this guide address those three concerns in
+order: **`match`** decides, **`resolve`** fetches, **`fill`** applies.
+
+## The Three Primitives
+
+Read them top-to-bottom — that is also the order you call them.
+
+```
+observe()  ──▶  target / fillableForm
+                        │
+                        ▼
+             match(subject, { from })
+                        │
+                        ├── { kind: 'ready', valueRef } ────────┐
+                        ├── { kind: 'needs_resolution', plan } ─┤
+                        └── ambiguous / no_match / group-variants
+                                 │                              │
+                                 ▼                              │
+                       resolve(plan, { with })                  │
+                                 │                              │
+                                 └── { kind: 'ready', valueRef }┤
+                                                                │
+                                                                ▼
+                                          fill(session, subject, plan)
+                                                                │
+                                                                ▼
+                                               act(...) on the browser
+```
+
+- **`match(subject, { from })`** — takes an observed target or fillable
+  form plus a source of candidate values, returns a structured outcome:
+  a ready reference (when the value is already in hand), a plan (when
+  external resolution is needed), or an explicit ambiguity / no-match
+  signal. Pure, local, no network.
+- **`resolve(plan, { with })`** — takes a plan (or an array of plans)
+  and an adapter, and walks each plan through your
+  `AgentbrowseMatchResolver` to produce a ready reference. This is the
+  one step where *your* code talks to a vault, approval UI, secret
+  manager, or any other external source of truth.
+- **`fill(session, subject, plan, { resolver? })`** — applies a ready
+  plan to the browser. It's the only step that dereferences the value
+  (more on that below) and the only step that drives a DOM action.
+
+If you want one sentence to remember: **match is pure; resolve owns the
+adapter; fill owns the browser.**
+
+## Walk-through 1 — value in hand
+
+The simplest case: you already have the value in memory, and you want to
+fill one observed input with it.
+
+```ts
+import { match, resolve, fill } from '@mercuryo-ai/agentbrowse';
+
+const observed = await observe(session);
+if (!observed.success) throw new Error(observed.reason ?? observed.message);
+
+const emailTarget = observed.targets.find((t) => t.inputType === 'email');
+if (!emailTarget) return;
+
+const matched = await match(emailTarget, {
+  from: { email: 'traveler@example.com' },
+});
+// matched is { kind: 'ready', targetRef, fieldKey: 'email', valueRef, confidence }.
+
+await fill(session, emailTarget, matched);
+```
+
+What happened, step by step:
+
+- `match` saw one observed target (the email input) and one candidate
+  coming from `{ email: '…' }`. AgentBrowse scored the candidate against
+  the target (label, `inputType`, `autocomplete`, etc.). High confidence
+  and no ambiguity, so it returned `kind: 'ready'`.
+- The ready result carries a `valueRef` — a stable opaque string, not
+  the email address itself. `JSON.stringify(matched)` does not contain
+  `traveler@example.com`. The value is held inside a non-enumerable
+  accessor on the result object.
+- `fill` used that accessor internally to dereference the value and
+  called `act(session, emailTarget.ref, 'fill', 'traveler@example.com')`.
+- The final result is the regular `ActResult` shape (same contract as a
+  direct `act(...)` call), so you can branch on `success` / `error` the
+  usual way.
+
+If `match` had returned something other than `ready` (for example,
+`ambiguous` because two candidates competed), `fill` would have
+short-circuited with a typed contract failure instead of guessing. See
+[Failure Contract](#failure-contract) below.
+
+### Candidate sources
+
+The `from` option is the same shape in every walk-through. It accepts
+four forms; pick whichever fits how your runtime already holds values:
+
+| Source | Shape | When to use |
+| --- | --- | --- |
+| Plain record | `{ [fieldKey]: value }` | You have a handful of open values in memory — fastest path. |
+| Candidate array | `ReadonlyArray<AgentbrowseMatchCandidate>` | You want full control: `applicability` rules, `semanticTags`, or a `resolve` plan per entry. |
+| `AgentbrowseMatchStore` | `{ entries(), read(candidateRef) }` | You do not want the value to sit inside the candidate list — the store lists metadata and only dereferences values through `read(candidateRef)`. |
+| Group variants | array or store of `AgentbrowseGroupMatchCandidate` | The subject is a fillable form instead of a single target. See [Walk-through 5](#walk-through-5--grouped-protected-forms). |
+
+The first three all produce single-field matches. Mix them as you like
+across calls; the result shape is always the same tagged union.
+
+### How `match` decides
+
+You just saw a successful single-field match. It is useful to understand
+at a conceptual level how the matcher picked the candidate, because the
+inputs you feed it — candidate metadata, applicability rules, target
+metadata — directly shape the result. You do not compute scores by
+hand; what you control is how much signal you hand the matcher.
+
+The matcher runs in two phases: a **filter** phase that drops
+candidates that cannot possibly apply, and a **score** phase that picks
+a winner from what remains.
+
+#### Filter phase
+
+Every one of these filters is hard — if a candidate fails the check,
+it's out. The matcher returns `no_match` with the corresponding reason
+when all candidates drop.
+
+- **Protected-target guard.** If the caller passed
+  `protectedTargetRefs` and the target's ref is in that set, the matcher
+  refuses everything. This is how open-data flows avoid writing values
+  into a password or card input. Reason: `protected_target`.
+- **At least one candidate.** Empty source → reason: `no_candidate`.
+- **Applicability.** A candidate declares
+  `applicability: { target: 'global' }` (applies anywhere) or
+  `{ target: 'host', value: 'example.com' }` (applies only when
+  `options.host` matches). Host-scoped candidates that do not match the
+  current host drop. Reason when zero remain: `scope_ineligible`.
+- **Shape compatibility.** The candidate's value type must be
+  compatible with the target's inferred type. An email input only
+  accepts candidates whose value looks like an email (or whose declared
+  `type` is `email` / `text`). Dates need ISO `YYYY-MM-DD`, numbers
+  need numeric values, URLs need `http(s)://` prefixes. **Secret-typed
+  candidates (`type: 'secret'`) are always rejected** — secrets must
+  flow through the `resolve` plan path in Walk-through 2, never through
+  open-data matching. Reason when zero remain: `incompatible_shape`.
+
+#### Score phase
+
+From the candidates that survived filtering, the matcher ranks by an
+evidence score combining signal strength on both sides:
+
+- **On the target side:** `label`, `displayLabel`, `placeholder`,
+  `inputName`, `inputType`, `autocomplete`, and other accessibility
+  signals collected by `observe(...)`. The matcher looks at direct
+  signals first (high weight) and broader context signals with a
+  small penalty.
+- **On the candidate side:** `fieldKey` (expanded into an evidence
+  vocabulary — for example, `fieldKey: 'email'` also scores against
+  terms like `"e-mail"`, `"email address"`, etc.), `label`, and any
+  `semanticTags` you provide.
+
+Richer candidates win ambiguous cases. The most impactful thing you
+control here is the candidate's metadata — providing `label` and
+`semanticTags` alongside `fieldKey` gives the matcher more handles.
+
+On top of the evidence score, two priority boosts break ties:
+
+- **Host-scoped candidates** (`applicability: { target: 'host', value: <host> }`)
+  get a small boost over global candidates at the same evidence score.
+  Use this when the same field has different values on different sites.
+- **Session-local values** (candidates with `source: 'session_open_value'`
+  — only relevant when you construct `ObservedFieldCandidate` objects
+  via the lower-level API) beat profile-fact ties. Use this to prefer
+  values a user just entered over generic profile defaults.
+
+#### Confidence, ambiguity, and low-confidence — three distinct outcomes
+
+These three adjacent concepts are easy to confuse. They each mean a
+different thing and need a different fix.
+
+- **`confidence: 'high'` / `'medium'` on a `ready` result.** The matcher
+  picked a clear winner; the field only reports whether it was a strong
+  match or a marginal one. Both are safe to fill. Use the field only
+  if your policy wants an extra guard (for example, auto-fill on
+  `'high'` and ask the user on `'medium'`).
+- **`kind: 'no_match'` with `reason: 'low_confidence'`.** No candidate
+  scored high enough to be plausible. Fix: add metadata to your
+  candidates (richer `label`, explicit `type`, `semanticTags`) or
+  narrow the source.
+- **`kind: 'ambiguous'`.** Several candidates scored within a small
+  threshold of the top. The matcher refuses to guess. Fix: disambiguate
+  by passing a narrower source for this target, or pick one of
+  `result.candidates` explicitly in your wrapper.
+
+#### Grouped matching is simpler
+
+When the subject is a fillable form (not a single target), the matcher
+does not run signal-based evidence scoring. It ranks group candidates
+by two things only:
+
+1. **Overlap.** How many of the form's `fieldKeys` the candidate
+   claims to cover.
+2. **Declared confidence** on the candidate itself (`'high'` >
+   `'medium'` > undefined).
+
+The winner gets `confidence: 'high'` when it covers every field the
+form declared, otherwise `'medium'`. Ties on `overlap + confidence`
+surface as `ambiguous_group` rather than being resolved by list
+position — that refusal is a deterministic-contract property of the
+grouped matcher.
+
+## Walk-through 2 — value behind a lookup
+
+Some values cannot live in memory: a password behind approval, a payment
+card stored in a vault, a secret issued per request. For these you
+describe the candidate as *needing resolution* and let AgentBrowse hand
+the plan to a caller-supplied adapter.
+
+The key word is **resolve**, and it has a specific meaning here. It is
+not «resolve a Promise» and not «resolve a conflict». It means:
+
+> Turn a match result that says *«this candidate requires external
+> data»* into a match result that says *«the value is ready — here is
+> the ref»*, by running a caller-supplied adapter.
+
+The adapter is yours. AgentBrowse has no idea what a vault is.
+
+```ts
+const passwordTarget = observed.targets.find((t) => t.inputType === 'password');
+
+const pending = await match(passwordTarget!, {
+  from: [
+    {
+      fieldKey: 'password',
+      type: 'secret',
+      resolve: { kind: 'vault_lookup', key: 'login.password' },
+    },
+  ],
+});
+// pending is { kind: 'needs_resolution', targetRef, fieldKey, candidateRef, confidence, plan }.
+
+const vaultResolver: AgentbrowseMatchResolver = {
+  async resolve(plan) {
+    if ('fillRef' in plan) {
+      throw new Error('This adapter only handles single-field plans.');
+    }
+    // Your real logic goes here — MagicPay request, KMS call, env var, etc.
+    const value = await readFromMyVault(plan.resolve.key!);
+    return { kind: 'value', value };
+  },
+};
+
+const ready = await resolve(pending, { with: vaultResolver });
+// ready is { kind: 'ready', ...same shape as in Walk-through 1 }.
+
+await fill(session, passwordTarget!, ready);
+```
+
+Anatomy of the resolve step:
+
+- `pending.plan` is a plain serialisable object:
+  `{ targetRef, candidateRef, fieldKey, type, resolve: { kind, key? , params? } }`.
+  It fully describes the work without carrying any value. You can log it,
+  pass it across a process boundary, store it in a job queue — nothing
+  sensitive is in there.
+- `vaultResolver.resolve(plan)` returns a typed resource:
+  `{ kind: 'value', value }` for single fields, or
+  `{ kind: 'artifact', artifact, ...metadata }` for grouped plans (see
+  Walk-through 5). AgentBrowse wraps the result into a fresh ready match
+  with a stable `valueRef`.
+- The whole adapter contract is two methods (see
+  [Resolver Interface](#resolver-interface)); you do not subclass
+  anything or register with a runtime. A handwritten object literal is a
+  perfectly valid resolver.
+
+Why bother separating `resolve` from `fill`? Three reasons:
+
+- Your adapter may run slower than the browser step (approval UIs,
+  polling, retries). Keeping them separate lets you log a checkpoint
+  between resolution and application.
+- `resolve` can operate on batches (next walk-through), so several
+  fields can share one lookup round-trip.
+- `resolve` is where all domain-specific behaviour lives. `fill` stays a
+  deterministic one-shot apply. That separation is deliberate — see
+  [Design Rules](#design-rules).
+
+## Walk-through 3 — collapsing to one call
+
+Often you do not need the intermediate ready result. `fill` accepts an
+optional `resolver`; if the plan still needs resolution, `fill` runs it
+inline and applies the result in the same call.
+
+```ts
+await fill(session, passwordTarget!, pending, { resolver: vaultResolver });
+```
+
+This is equivalent to `fill(session, passwordTarget!, await resolve(pending, { with: vaultResolver }))`.
+Use the two-call form when you want to inspect the ready result,
+correlate traces, or batch multiple resolves together. Use the inline
+form for one-shot integrations.
+
+## Walk-through 4 — resolving a batch
+
+`resolve` also accepts an array of match results. Entries that are
+already `ready` pass through untouched; only `needs_resolution` entries
+hit the adapter. When more than one entry needs resolution and your
+adapter implements `resolveBatch`, AgentBrowse calls it once with all of
+the plans.
+
+```ts
+const [emailReady, passwordReady, cardReady] = await resolve(
+  [emailMatch, passwordMatch, cardMatch],
+  { with: vaultResolver },
+);
+```
+
+Two rules matter:
+
+- **Order is preserved.** The output array has the same length and same
+  positions as the input. Your code can rebuild the `target → ready`
+  mapping by index without extra bookkeeping.
+- **Batch is an optimisation, not a requirement.** If your adapter only
+  implements `resolve` (singular), AgentBrowse falls back to
+  `Promise.all` over the single-plan method. Add `resolveBatch` only when
+  one network round-trip can fulfil many plans (typical for vault
+  lookups on one login form).
+
+## Walk-through 5 — grouped protected forms
+
+Up to this point every walk-through filled one field at a time. Some
+forms cannot be filled that way: a protected login form, a payment-card
+form, an identity-document form. Either you fill the whole form atomically
+(so the page's own validation and submit logic sees a consistent state),
+or the caller's protected-fill guardrails apply to the whole form rather
+than to individual inputs.
+
+For these, `match` takes a `fillableForm` (one of the entries in
+`observeResult.fillableForms`) as the subject, and the source is a list
+of group candidates describing whole-form plans:
+
+```ts
+const fillableForm = observed.fillableForms?.find((f) => f.purpose === 'login');
+if (!fillableForm) return;
+
+const matched = await match(fillableForm, {
+  from: [
+    {
+      candidateRef: 'vault_login_1',
+      itemRef: 'vault_login_1',
+      fieldKeys: ['username', 'password'],
+      confidence: 'high',
+      resolve: { kind: 'magicpay_observed_form', key: 'vault_login_1' },
+    },
+  ],
+});
+// matched is { kind: 'needs_resolution_group', fillRef, purpose, candidateRef, itemRef, fieldKeys, confidence, plan }.
+```
+
+Two new things show up here:
+
+- The resolver's `resolve(plan)` is expected to return an **artifact**,
+  not a single value. In the MagicPay case that artifact has shape
+  `{ kind: 'values', values: { username, password } }` plus metadata
+  (`requestId`, `resolutionPath`, `claimedAt`).
+- A fresh capability, `resolver.fill`, takes over the apply step. It
+  receives the session, the form subject, and the ready artifact, and is
+  responsible for actually writing the values into the browser — usually
+  by delegating to `fillProtectedForm(...)` so all the stale-binding,
+  validation, and field-policy guards still apply.
+
+```ts
+const magicpayResolver: AgentbrowseMatchResolver = {
+  async resolve(plan) {
+    if (!('fillRef' in plan)) throw new Error('Expected a grouped plan.');
+    const result = await magicpay.data.resolve(sessionId, buildResolveInput(plan));
+    const final = await magicpay.data.waitForResult(sessionId, result);
+    if (!final.ok || final.artifact.kind !== 'values') throw new Error('…');
+    return {
+      kind: 'artifact',
+      artifact: final.artifact,
+      requestId: final.requestId,
+      resolutionPath: final.resolutionPath,
+      claimedAt: new Date().toISOString(),
+    };
+  },
+  async fill(session, form, ready) {
+    const artifact = ready.artifact as { kind: 'values'; values: Record<string, string> };
+    return fillProtectedForm({
+      session,
+      fillableForm: form,
+      protectedValues: artifact.values,
+    });
+  },
+};
+
+const result = await fill(session, fillableForm, matched, {
+  resolver: magicpayResolver,
+});
+```
+
+The whole flow is still `match → resolve → fill`. The only change is
+that the subject is a form, the candidates describe whole-form plans,
+and the resolver carries a `fill` capability alongside `resolve`.
+
+## Resolver Interface
+
+Two exported interfaces cover what you hand to `resolve(...)` and
+`fill(...)`:
+
+```ts
+// Main adapter — used by resolve() and by fill() when a plan needs
+// external data or when grouped fill is part of the same adapter.
+interface AgentbrowseMatchResolver {
+  resolve(plan): Promise<AgentbrowseResolvedResource>;
+  resolveBatch?(plans): Promise<ReadonlyArray<AgentbrowseResolvedResource>>;
+  fill?(session, form, ready): Promise<Record<string, unknown> & { success: boolean }>;
+}
+
+// Narrow handler — used by fill() when the caller only applies ready
+// grouped artifacts and never fetches external data.
+interface AgentbrowseGroupFillHandler {
+  fill(session, form, ready): Promise<Record<string, unknown> & { success: boolean }>;
+}
+
+type AgentbrowseResolvedResource =
+  | { kind: 'value'; value: string | number }
+  | {
+      kind: 'artifact';
+      artifact: unknown;
+      itemRef?: string;
+      requestId?: string;
+      resolutionPath?: string;
+      claimedAt?: string;
+    };
+```
+
+One parameter slot, two accepted shapes. `fill(session, subject, plan,
+{ resolver })` accepts either interface via a union, and picks which
+capability to call based on the plan's `kind` (`needs_resolution` needs
+`.resolve`, `ready_group` needs `.fill`). `resolve(plan, { with })`
+always requires the main `AgentbrowseMatchResolver` — the `.resolve`
+method has to be there at compile time.
+
+### `AgentbrowseMatchResolver` capabilities
+
+| Capability | Required? | Purpose |
+| --- | --- | --- |
+| `resolve` | Yes, on this interface. | Turn one plan into one ready resource. |
+| `resolveBatch` | Optional — add when several plans share one external call. | Turn many plans into many resources in one call. Must preserve input order. |
+| `fill` | Optional — add when the same adapter also applies grouped protected artifacts. | Apply a ready grouped artifact to the fillable form — usually a thin wrapper over `fillProtectedForm(...)`. |
+
+Implement just `resolve` when your integration only fetches external
+values (single-field flows). Add `fill` alongside when the same adapter
+both fetches the artifact and applies it (the usual shape for a
+MagicPay bridge around a single workflow).
+
+### `AgentbrowseGroupFillHandler` — narrow handler
+
+Use this shape when the caller already has the grouped artifact in
+hand (for example, after a separate `magicpay data.waitForResult(...)`
+outside the AgentBrowse call) and only needs to apply it:
+
+```ts
+import { fill, type AgentbrowseGroupFillHandler } from '@mercuryo-ai/agentbrowse';
+
+const applier: AgentbrowseGroupFillHandler = {
+  async fill(session, form, ready) {
+    return fillProtectedForm({
+      session,
+      fillableForm: form,
+      protectedValues: (ready.artifact as { values: Record<string, string> }).values,
+    });
+  },
+};
+
+await fill(session, fillableForm, readyGroupMatch, { resolver: applier });
+```
+
+Because `AgentbrowseGroupFillHandler` has no `resolve` method,
+`resolve(plan, { with: applier })` would not type-check — that is
+intentional. The narrow shape is only meaningful at the `fill(...)`
+boundary, where the plan is already `ready_group` and no fetching is
+needed.
+
+### Common rules
+
+Both shapes follow the same behavioural contract:
+
+- The adapter does not mutate its input plan — it returns a fresh
+  resource, and AgentBrowse wraps the result.
+- Adapters must throw — not return silently — when a resource cannot be
+  produced for a plan the caller believed was valid. Thrown errors
+  propagate through `resolve(...)` / `fill(...)` to your call site.
+- When you pass a handler that does not carry a capability the plan
+  needs (a `ready_group` plan with a handler lacking `.fill`, or a
+  `needs_resolution_group` plan with a handler lacking `.resolve`),
+  `fill(...)` returns a typed `match_resolver_required` failure instead
+  of throwing. See the [failure contract](#failure-contract) above.
+
+## Design Rules
+
+These rules are public contract, not implementation detail. Rely on
+them.
+
+### No raw values in public match results
+
+Ready match results carry `valueRef` / `artifactRef` strings. The actual
+value or artifact lives in a non-enumerable symbol accessor attached to
+the same object. Only `fill(...)` looks through it.
+
+This has visible consequences:
+
+- `JSON.stringify(ready)` does not contain the value. It is safe to log,
+  snapshot-test, or forward to trace pipelines.
+- `structuredClone(ready)` drops the accessor; the clone is a
+  diagnostic-only snapshot and `fill(...)` will reject it with
+  `match_value_unavailable`.
+- Passing a ready result across a process boundary (a queue, a worker, a
+  subprocess, IPC) drops the accessor for the same reason.
+
+The serialisable shape of the pipeline is the `needs_resolution` plan.
+If your runtime needs to hand work to another process, ship the plan
+there and let the downstream side run `resolve → fill` in one shot.
+
+### Stable resolved refs
+
+After `resolve(plan)` succeeds, the ready result carries a stable ref of
+the form `value:${candidateRef}:resolved` or
+`artifact:${candidateRef}:resolved`. Repeated resolves of the same plan
+produce the same ref.
+
+Use this property when:
+
+- writing snapshot tests that compare match results across runs;
+- correlating traces between a resolve and a later fill;
+- deduplicating resolves by ref before calling fill.
+
+The refs before `resolve` (fresh from a `match` with an inline source)
+also keep the property that they are stable for a given input array —
+they are seeded by `candidateRef` and the input index, not by wall time.
+
+### AgentBrowse makes no network calls
+
+`match` and `fill` are local-only. Only your adapter's `.resolve` /
+`.resolveBatch` / `.fill` methods make network or I/O calls. This is
+the «adapter boundary» — AgentBrowse core has zero knowledge of
+MagicPay, vaults, approval UIs, or any specific transport.
+
+## Result Kinds
+
+`match` returns a tagged union. Always branch on `kind`; never
+infer from the presence of individual fields.
+
+| `kind` | Meaning | Next step |
+| --- | --- | --- |
+| `ready` | Unique candidate; value is in memory. | `fill(...)`. |
+| `needs_resolution` | Unique candidate; value needs external lookup. | `resolve(...)` or `fill(..., { resolver })`. |
+| `ambiguous` | Several candidates tied for this target. | Ask the caller to disambiguate; do not fill speculatively. |
+| `no_match` | No candidate applied. `reason` explains why: `protected_target`, `no_candidate`, `scope_ineligible`, `incompatible_shape`, `low_confidence`. | Skip the target. |
+| `ready_group` | Grouped plan is ready for a fillable form. | `fill(session, form, matched, { resolver })` with `resolver.fill` implemented. |
+| `needs_resolution_group` | Grouped plan still needs an artifact. | `resolve(...)` or `fill(..., { resolver })`. |
+| `ambiguous_group` | Several group candidates tied on overlap + confidence. | Pick one candidate explicitly (e.g. via a wrapper option); do not fill. |
+| `no_match_group` | No group candidate applied. | Skip the form. |
+
+`ambiguous_group` is a deliberate deterministic-contract signal. Before
+the current surface, group matching would silently pick the first
+candidate in list order on a tie; now it raises the tie explicitly and
+forces the caller to decide.
+
+## Failure Contract
+
+When `fill` cannot proceed because of a contract problem, it returns a
+structured failure instead of throwing:
+
+```ts
+interface AgentbrowseFillFailureResult {
+  success: false;
+  failureSurface: 'contract';
+  error:
+    | 'match_no_match'
+    | 'match_ambiguous'
+    | 'match_resolver_required'
+    | 'match_value_unavailable'
+    | 'match_artifact_unavailable';
+  outcomeType: 'blocked' | 'unsupported';
+  message: string;
+  reason: string;
+  targetRef?: string;
+  fillRef?: string;
+  action: 'fill';
+}
+```
+
+Branch on `error`:
+
+| `error` | Root cause | Action |
+| --- | --- | --- |
+| `match_no_match` | `fill` received a `no_match` / `no_match_group` plan, or a subject-shape mismatch (field plan on a form, form plan on a field). | Do not retry with the same input. Check the match result first or re-observe. |
+| `match_ambiguous` | `fill` received an `ambiguous` / `ambiguous_group` plan. | Ask the caller to disambiguate. |
+| `match_resolver_required` | Plan needs external resolution and no `resolver` was passed. For grouped plans, also raised when `resolver.fill` is missing. | Supply the resolver adapter (with `fill` implemented when grouped). |
+| `match_value_unavailable` | Internal accessor is gone. Almost always means a ready result was serialised across a process boundary and the non-enumerable accessor was lost. | Run `resolve` → `fill` inside the same process, or ship the `needs_resolution` plan instead. |
+| `match_artifact_unavailable` | Same failure mode as above, for grouped ready plans. | Same fix. |
+
+Browser-level failures (stale refs, page-level validation, connection)
+surface through the underlying `ActResult` or `resolver.fill` result —
+see [api-reference.md → Error codes by command](./api-reference.md#error-codes-by-command)
+and [protected-fill.md](./protected-fill.md).
+
+## Relation To `act(...)` And `fillProtectedForm(...)`
+
+Three doors into the browser, increasing level of abstraction:
+
+| API | Owns | Use it when |
+| --- | --- | --- |
+| `act(session, ref, 'fill', value)` | One raw target, one raw value. | You already hold the value, you already know the target, you do not need a match decision. |
+| `fillProtectedForm(...)` — from `@mercuryo-ai/agentbrowse/protected-fill` | Applying a ready set of protected values to a fillable form with stale-binding, validation, and field-policy guards. | You already have the values artifact (for example from a MagicPay `artifact.kind === 'values'`) and you do not want `match` / `resolve` orchestration on top. |
+| `fill(session, subject, plan, { resolver? })` | End-to-end `match → resolve → apply`. Grouped subjects route through `resolver.fill`, which typically wraps `fillProtectedForm(...)`. | You want one deterministic surface for deciding, resolving, and applying. Also the right shape when your runtime composes several fields or forms in batch. |
+
+`fillProtectedForm(...)` did not go away — it is still the right call
+when the artifact is in hand and no match/resolve plan is needed. See
+[protected-fill.md](./protected-fill.md) for its full contract.
+
+## Testing Wrappers Around These Primitives
+
+Wrapper packages should exercise the primitives against the published
+`/testing` subpath instead of fabricating result objects by hand:
+
+```ts
+import {
+  createFixtureMatchStore,
+  createFixtureGroupStore,
+  createFixtureResolver,
+  fixtureResolvedValue,
+  fixtureResolvedArtifact,
+} from '@mercuryo-ai/agentbrowse/testing';
+```
+
+Available helpers:
+
+- `createFixtureMatchStore(entries)` — opaque store for single-field
+  matching. Implements `AgentbrowseMatchStore` with a backing
+  in-memory map.
+- `createFixtureGroupStore(entries)` — opaque store for grouped matching.
+  Implements `AgentbrowseGroupMatchStore`.
+- `createFixtureResolver(resourcesByCandidateRef, { enableBatch? })` —
+  adapter that satisfies `AgentbrowseMatchResolver` and records
+  `resolveCalls` / `resolveBatchCalls` for assertions.
+- `fixtureResolvedValue(value)` / `fixtureResolvedArtifact(artifact)` —
+  typed builders for the resolved-resource shape.
+
+See [testing.md](./testing.md) for integration patterns.
+
+## Further Reading
+
+- [API Reference — Match / Resolve / Fill](./api-reference.md)
+- [Protected Fill Guide](./protected-fill.md)
+- [Testing Guide](./testing.md)
+- [Integration Checklist](./integration-checklist.md)