@mercuryo-ai/agentbrowse 0.2.61 → 0.2.63

package/docs/api-reference.md

@@ -97,21 +97,211 @@ Captures a screenshot of the current page.
 
 Closes the browser session.
 
-## Stable Error Code Arrays
+### `match(subject, options)`
 
-The root package exports stable top-level error code arrays for command
-branching:
+Decides which caller-supplied candidate value fits an observed target or
+fillable form. Pure and local — does not call the network and does not
+mutate browser state. See
+[Match / Resolve / Fill Guide](./match-resolve-fill.md) for the full
+mental model.
 
-- `ACT_ERROR_CODES`
-- `ATTACH_ERROR_CODES`
-- `CLOSE_ERROR_CODES`
-- `EXTRACT_ERROR_CODES`
-- `LAUNCH_ERROR_CODES`
-- `NAVIGATE_ERROR_CODES`
-- `OBSERVE_ERROR_CODES`
-- `SCREENSHOT_ERROR_CODES`
+```ts
+function match(
+  subject: TargetDescriptor | ProtectedFillForm,
+  options: AgentbrowseMatchOptions,
+): Promise<AgentbrowseMatchResult>;
+
+interface AgentbrowseMatchOptions {
+  from: AgentbrowseMatchSource;
+  host?: string;
+  protectedTargetRefs?: ReadonlySet<string>;
+}
+```
+
+### `resolve(plan, options)`
+
+Turns one or many `needs_resolution` plans into ready match results
+through a caller-supplied adapter. `ready` results pass through
+untouched. Overloaded for single plan and batch arrays.
+
+```ts
+function resolve(
+  plan: AgentbrowseMatchResult,
+  options: AgentbrowseResolveOptions,
+): Promise<AgentbrowseMatchResult>;
+
+function resolve(
+  plans: ReadonlyArray<AgentbrowseMatchResult>,
+  options: AgentbrowseResolveOptions,
+): Promise<AgentbrowseMatchResult[]>;
+
+interface AgentbrowseResolveOptions {
+  with: AgentbrowseMatchResolver;
+}
+```
+
+### `fill(session, subject, plan, options?)`
+
+Applies a match result to the browser. Dereferences the opaque
+value/artifact ref internally and hands off to the standard `act(...)`
+path (single targets) or `resolver.fill(...)` (grouped protected forms).
+
+```ts
+function fill(
+  session: BrowserCommandSession,
+  subject: Pick<TargetDescriptor, 'ref'> | ProtectedFillForm,
+  plan: AgentbrowseMatchResult,
+  options?: AgentbrowseFillOptions,
+): Promise<AgentbrowseFillResult>;
+
+interface AgentbrowseFillOptions {
+  resolver?: AgentbrowseMatchResolver;
+}
+```
+
+`fill(...)` can run `resolve` inline when you pass a `resolver` for a
+plan that still needs resolution — equivalent to the two-call form. See
+[match-resolve-fill.md → Walk-through 3](./match-resolve-fill.md#walk-through-3--collapsing-to-one-call).
 
-These arrays back the exported `*ErrorCode` types.
+## Result Shape
+
+All main commands share the same top-level pattern.
+
+```ts
+// success
+{ success: true, ...commandSpecificFields }
+
+// failure
+{
+  success: false,
+  error: <ErrorCode>,
+  outcomeType: <OutcomeType>,
+  message: string,
+  reason: string,
+  ...commandSpecificFields,
+}
+```
+
+- `error` — stable top-level code from the per-command table below.
+  Branch on this, not on `reason` or `message`.
+- `outcomeType` — stable outcome category (e.g. `binding_stale`,
+  `blocked`). Same vocabulary per command as the `*_OUTCOME_TYPES`
+  exports.
+- `message` — human-readable short message.
+- `reason` — detailed reason string. Usually a lower-level error code,
+  a truncation detail, or an explanation; see the sticky-owner note
+  below for one common special case.
+
+The root package exports stable arrays backing the `*ErrorCode` and
+`*OutcomeType` types for every command: `ACT_ERROR_CODES`,
+`ACT_OUTCOME_TYPES`, `ATTACH_ERROR_CODES`, `CLOSE_ERROR_CODES`,
+`EXTRACT_ERROR_CODES`, `EXTRACT_OUTCOME_TYPES`, `LAUNCH_ERROR_CODES`,
+`NAVIGATE_ERROR_CODES`, `OBSERVE_ERROR_CODES`, `OBSERVE_OUTCOME_TYPES`,
+`SCREENSHOT_ERROR_CODES`, `SCREENSHOT_OUTCOME_TYPES`.
+
+### Cross-command codes
+
+Any command that drives an already-open browser session may surface:
+
+| `error` | When | Action |
+| --- | --- | --- |
+| `browser_connection_failed` | AgentBrowse could not reach the browser. | Check `reason`. A common special value is `sticky_owner_unrecoverable` — the prior browser session is lost; launch or attach a fresh session before retrying. |
+
+### Error codes by command
+
+#### `launch`
+
+| `error` | When | Action |
+| --- | --- | --- |
+| `browser_launch_failed` | The managed browser could not be started. | Inspect `reason`/`message`; verify the host can run the browser. |
+
+#### `attach`
+
+| `error` | When | Action |
+| --- | --- | --- |
+| `browser_attach_failed` | Could not attach to the provided CDP URL. | Verify the CDP URL is reachable and exposes the protocol. |
+
+#### `navigate`
+
+| `error` | When | Action |
+| --- | --- | --- |
+| `browser_connection_failed` | See Cross-command codes. | — |
+| `navigation_failed` | Navigation did not complete. | Retry, or re-observe to see current page state. |
+
+#### `observe`
+
+| `error` | When | Action |
+| --- | --- | --- |
+| `browser_connection_failed` | See Cross-command codes. | — |
+| `observe_failed` | Page inspection failed (DOM or assistive runtime error). | Retry; if persistent, check the assistive runtime. |
+| `protected_observe_blocked` | The page is under active protected exposure; observation is blocked. | Complete or cancel the protected step first. |
+
+#### `act`
+
+| `error` | When | Action |
+| --- | --- | --- |
+| `act_failed` | Generic action failure not covered by a specific code. | Check `reason`/`message`. |
+| `action_not_allowed_for_target` | The requested action (`click`/`fill`/`type`/`select`/`press`) is not valid for this target kind. | Use an action compatible with the target's capability. |
+| `browser_connection_failed` | See Cross-command codes. | — |
+| `no_observable_progress` | The action ran but no DOM/UI change was detected within the wait window. | Re-observe; the target may need a different interaction. |
+| `stale_target` | The target binding is stale at execution time. | Re-observe and rebind. |
+| `stale_target_ref` | The passed `targetRef` no longer maps to an observed element. | Re-observe. |
+| `target_disabled` | Element is present but disabled. | Wait for enablement or resolve the blocker. |
+| `target_gated` | Element is gated behind an intermediate step. | Resolve the gating step first. |
+| `target_not_actionable` | Element exists but cannot be actioned (visibility or position). | Scroll/expand the owning scope, then re-observe. |
+| `target_readonly` | Element is read-only; `fill`/`type` are not allowed. | Use a different action or a different target. |
+| `target_surface_inactive` | The owning scope is currently inactive (e.g. a closed modal). | Activate or expand the scope first. |
+| `target_surface_not_live` | The owning scope is no longer live on the page. | Re-observe. |
+| `target_surface_unavailable` | The owning scope is not currently available. | Re-observe after any UI transition. |
+| `unknown_target_ref` | The `targetRef` was not issued by a prior `observe(...)`. | Never synthesise refs — pass back what `observe` returned. |
+| `validation_blocked` | The target accepted the input, but page-level validation blocks continuation. | Resolve the validation error and re-observe. |
+
+#### `extract`
+
+| `error` | When | Action |
+| --- | --- | --- |
+| `browser_connection_failed` | See Cross-command codes. | — |
+| `expired_extract_scope` | The scope ref expired (page moved past its lifetime). | Re-observe and use the new scope. |
+| `extract_failed` | Extraction failed at runtime. | Check `reason`/`message` and retry. |
+| `extract_output_truncated` | The assistive runtime returned a structured output that was cut off. | Raise `maxOutputTokens` in your adapter. |
+| `invalid_extract_schema` | The passed schema is not a supported shape. | See [Extraction Schema Rules](#extraction-schema-rules). |
+| `invalid_extract_scope` | The scope ref was provided but is not valid. | Verify the ref came from `observe(...)`. |
+| `stale_extract_scope` | The scope ref is stale against the current DOM. | Re-observe. |
+| `unknown_scope_ref` | The scope ref was not issued by a prior `observe(...)`. | Never synthesise refs. |
+
+#### `screenshot`
+
+| `error` | When | Action |
+| --- | --- | --- |
+| `browser_connection_failed` | See Cross-command codes. | — |
+| `protected_screenshot_blocked` | The page is under active protected exposure; screenshot is blocked. | Complete or cancel the protected step first. |
+| `screenshot_failed` | The screenshot attempt failed. | Check `reason`/`message`. |
+
+#### `close`
+
+| `error` | When | Action |
+| --- | --- | --- |
+| `browser_close_failed` | The browser session could not be closed cleanly. | Usually cosmetic; the process will eventually clean up. |
+
+#### `fill`
+
+Contract failures from `fill(...)` share a dedicated shape,
+`AgentbrowseFillFailureResult`, with `failureSurface: 'contract'` and
+`action: 'fill'`. Browser-level failures (stale refs, validation,
+connection) flow through the underlying `ActResult` / `resolver.fill`
+result instead — see `act` codes above and
+[protected-fill.md](./protected-fill.md).
+
+| `error` | When | 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. Re-observe or branch on the match result first. |
+| `match_ambiguous` | `fill` received an `ambiguous` / `ambiguous_group` plan. | Ask the caller to disambiguate before filling. |
+| `match_resolver_required` | Plan needs external resolution and no `resolver` was supplied, or the resolver is missing the required capability (`.resolve` for needs-resolution, `.fill` for grouped). | Provide a resolver adapter that implements the capability. |
+| `match_value_unavailable` | Internal value accessor is gone. Typically means a `ready` result was serialized 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. |
+
+See [Protected Fill](./protected-fill.md) for the separate error and
+execution-kind vocabulary used by `fillProtectedForm(...)`.
 
 ## Error Classes
 
@@ -123,13 +313,6 @@ For code paths that want `instanceof` checks instead of string matching on
 - `AssistiveStructuredOutputTruncatedError` — thrown when the assistive
   runtime returns a structured output that was cut off mid-response.
 
-## Core Result Shapes
-
-All main commands use the same top-level pattern:
-
-- success: `{ success: true, ... }`
-- failure: `{ success: false, error, outcomeType, message, reason, ... }`
-
 ## Observe Types
 
 ### `ObserveTarget`
@@ -197,6 +380,115 @@ Fields:
 - `framePath`
 - `source`
 
+## Match / Resolve / Fill Types
+
+The exported types for the `match` / `resolve` / `fill` primitives.
+Read [match-resolve-fill.md](./match-resolve-fill.md) for how they
+compose in practice; this section is lookup-only.
+
+### Candidate sources
+
+- `AgentbrowseMatchSource` — union of `Record<string, AgentbrowseMatchValue>`,
+  `ReadonlyArray<AgentbrowseMatchCandidate>`,
+  `AgentbrowseMatchStore`,
+  `ReadonlyArray<AgentbrowseGroupMatchCandidate>`, or
+  `AgentbrowseGroupMatchStore`. All of these are valid `options.from`
+  values for `match(...)`.
+- `AgentbrowseMatchValue` — `string | number`.
+- `AgentbrowseMatchApplicability` — `{ target: 'global' | 'host'; value?: string }`.
+- `AgentbrowseMatchCandidate` — single-field candidate with optional
+  `candidateRef`, `value`, `type`, `label`, `semanticTags`,
+  `applicability`, `resolve` plan.
+- `AgentbrowseGroupMatchCandidate` — grouped candidate with required
+  `fieldKeys` plus optional `candidateRef`, `itemRef`, `label`,
+  `confidence`, `applicability`, `resolve` plan, `artifact`.
+- `AgentbrowseMatchStore` — `{ entries(), read(candidateRef) }`.
+  Opaque single-field store; values stay behind `read`.
+- `AgentbrowseGroupMatchStore` — `{ entries(), readArtifact(candidateRef) }`.
+  Opaque grouped store; artifacts stay behind `readArtifact`.
+
+### Match result union
+
+`AgentbrowseMatchResult` is a discriminated union over `kind`:
+
+- `AgentbrowseReadyMatchResult` — `kind: 'ready'` (single target).
+- `AgentbrowseNeedsResolutionMatchResult` — `kind: 'needs_resolution'`
+  with `plan: AgentbrowseResolutionPlan`.
+- `AgentbrowseAmbiguousMatchResult` — `kind: 'ambiguous'` with
+  `candidates: string[]`.
+- `AgentbrowseNoMatchResult` — `kind: 'no_match'` with a stable
+  `reason`: `'protected_target' | 'no_candidate' | 'scope_ineligible' | 'incompatible_shape' | 'low_confidence'`.
+- `AgentbrowseReadyGroupMatchResult` — `kind: 'ready_group'`.
+- `AgentbrowseNeedsResolutionGroupMatchResult` — `kind: 'needs_resolution_group'`
+  with `plan: AgentbrowseGroupResolutionPlan`.
+- `AgentbrowseAmbiguousGroupMatchResult` — `kind: 'ambiguous_group'`.
+- `AgentbrowseNoGroupMatchResult` — `kind: 'no_match_group'` with the
+  same `reason` vocabulary.
+
+`AgentbrowseResolvableMatchResult` is the narrower union of
+`'needs_resolution' | 'needs_resolution_group'` — what `resolve(...)`
+actually hands to your adapter.
+
+### Resolution plans
+
+- `AgentbrowseResolutionPlan` — `{ targetRef, candidateRef, fieldKey, type?, resolve }`.
+- `AgentbrowseGroupResolutionPlan` — `{ fillRef, pageRef, scopeRef?, purpose, candidateRef, itemRef?, fieldKeys, resolve }`.
+- `AgentbrowseMatchResolutionRequest` — `{ kind: string; key?: string; params?: Record<string, unknown> }`.
+  The `resolve` field on a candidate or plan. AgentBrowse does not
+  interpret `kind` or `key` — they are opaque to the core and meaningful
+  only to your adapter.
+
+### Resolved resources
+
+- `AgentbrowseResolvedResource` — `AgentbrowseResolvedValueResource | AgentbrowseResolvedArtifactResource`.
+- `AgentbrowseResolvedValueResource` — `{ kind: 'value'; value }`.
+- `AgentbrowseResolvedArtifactResource` — `{ kind: 'artifact'; artifact; itemRef?; requestId?; resolutionPath?; claimedAt? }`.
+- `AgentbrowseReadyGroupFillInput` — the shape `resolver.fill` receives:
+  `{ candidateRef, itemRef?, fieldKeys, artifact, requestId?, resolutionPath?, claimedAt? }`.
+
+### Resolver adapter
+
+Two exported interfaces. The `{ resolver }` slot on `fill(...)` accepts
+either via a union; `resolve(plan, { with })` only accepts the main
+resolver.
+
+```ts
+interface AgentbrowseMatchResolver {
+  resolve(plan): Promise<AgentbrowseResolvedResource>;
+  resolveBatch?(plans): Promise<ReadonlyArray<AgentbrowseResolvedResource>>;
+  fill?(session, subject, ready): Promise<Record<string, unknown> & { success: boolean }>;
+}
+
+interface AgentbrowseGroupFillHandler {
+  fill(session, subject, ready): Promise<Record<string, unknown> & { success: boolean }>;
+}
+```
+
+- `AgentbrowseMatchResolver` — full adapter. `resolve` is required;
+  `resolveBatch` and `fill` are optional. Used by `resolve(plan, { with })`
+  and by `fill(...)` for all plan kinds.
+- `AgentbrowseGroupFillHandler` — narrow handler used only at the
+  `fill(...)` boundary when the plan is `ready_group` and no resolution
+  is needed. A handler is not accepted by `resolve(...)`.
+
+At runtime, `fill(...)` picks the right capability via an internal type
+guard (`hasResolveCapability` / `hasGroupFillCapability`). When a
+capability the current plan needs is missing on the passed object,
+`fill(...)` returns a typed `match_resolver_required` failure instead
+of throwing.
+
+See [match-resolve-fill.md → Resolver Interface](./match-resolve-fill.md#resolver-interface)
+for examples of each shape.
+
+### Fill result
+
+- `AgentbrowseFillResult` — `ActResult | AgentbrowseFillFailureResult | (Record<string, unknown> & { success: boolean })`.
+  Single-target fill returns `ActResult`; grouped fill returns whatever
+  your `resolver.fill` returned; contract failures return
+  `AgentbrowseFillFailureResult`.
+- `AgentbrowseFillFailureResult` — `{ success: false; failureSurface: 'contract'; error; outcomeType; message; reason; targetRef?; fillRef?; action: 'fill' }`.
+  See the [`fill` error table](#fill) above for `error` codes.
+
 ## Ref Glossary
 
 - `ref`

package/docs/assistive-runtime.md

@@ -58,6 +58,9 @@ this usually means:
 
 1. Convert the Zod schema to JSON Schema (e.g. with
    `@browserbasehq/stagehand`'s `toJsonSchema`, or your own helper).
+   `@browserbasehq/stagehand` is a direct dependency of this package, so
+   `toJsonSchema` is available without a separate install. Alternatives
+   like `zod-to-json-schema` work too.
 2. Pass it as `response_format: { type: 'json_schema', json_schema: { ... } }`.
 3. Parse `choices[0].message.content` and return `{ data, usage? }`.
 
@@ -99,6 +102,9 @@ by hand.
 
 ## Recommended Setup
 
+The preferred path is a per-client runtime: pass your runtime into
+`createAgentbrowseClient({ assistiveRuntime })` and reuse that client.
+
 ```ts
 import { createAgentbrowseClient } from '@mercuryo-ai/agentbrowse';
 
@@ -106,16 +112,38 @@ const client = createAgentbrowseClient({
   assistiveRuntime: createOpenAiCompatibleAssistiveRuntime({
     baseUrl: 'https://api.openai.com/v1',
     apiKey: process.env.OPENAI_API_KEY!,
-    model: 'gpt-4.1-mini',
+    // Any OpenAI-compatible model that supports structured outputs.
+    model: process.env.OPENAI_MODEL ?? '<your-model>',
   }),
 });
 ```
 
 This pattern works well when:
 
-- your app is multi-tenant
-- you run parallel tests
-- different consumers in one process need different LLM settings
+- your app is multi-tenant;
+- you run parallel tests;
+- different consumers in one process need different LLM settings.
+
+### Per-client vs global runtime
+
+| Setup | When to use |
+| --- | --- |
+| `createAgentbrowseClient({ assistiveRuntime })` | Default. Keeps the runtime scoped to one client, works with multi-tenant and parallel scenarios. |
+| `configureAgentbrowseAssistiveRuntime(runtime)` | Fallback for small scripts and single-tenant processes — sets one global runtime for the whole process. Not recommended when multiple consumers may coexist. |
+
+Global-runtime shape:
+
+```ts
+import { configureAgentbrowseAssistiveRuntime } from '@mercuryo-ai/agentbrowse';
+
+configureAgentbrowseAssistiveRuntime(
+  createOpenAiCompatibleAssistiveRuntime({
+    baseUrl: 'https://api.openai.com/v1',
+    apiKey: process.env.OPENAI_API_KEY!,
+    model: process.env.OPENAI_MODEL ?? '<your-model>',
+  })
+);
+```
 
 ## OpenAI-Compatible Helper Example
 
@@ -232,21 +260,18 @@ Examples:
 - OpenRouter base URL:
   `https://openrouter.ai/api/v1`
 
-## Small Script Fallback
-
-For small scripts, you can also use:
-
-```ts
-import { configureAgentbrowseAssistiveRuntime } from '@mercuryo-ai/agentbrowse';
-```
-
-This is a convenience fallback, not the preferred embedded pattern.
-
 ## What Happens Without Assistive Runtime
 
-- `extract(...)` cannot run successfully
+- `extract(...)` cannot run successfully.
 - `observe(session, goal)` still runs, but quality may be lower because
-  AgentBrowse falls back to local heuristics instead of LLM-assisted ranking
+  AgentBrowse falls back to local heuristics instead of LLM-assisted
+  ranking.
+- `fillProtectedForm(...)` returns
+  `{ kind: 'unexpected_error', reason: 'assisted_value_resolution_failed' }`
+  for fields that require LLM-assisted resolution (split `full_name` into
+  given/family, localised dropdown values like nationality on a
+  non-English page, or any field pinned to the `llm_assisted` policy).
+  See [Protected Fill Guide](./protected-fill.md#split-fields-and-assistive-runtime).
 
 ## Testing Runtime
 

package/docs/getting-started.md

@@ -42,12 +42,14 @@ invalidates them:
 
 After any of the above, call `observe(...)` again and use the new refs.
 
-At a high level, AgentBrowse has three kinds of behavior:
+At a high level, AgentBrowse has four kinds of behavior:
 
 - normal browser execution for `launch`, `navigate`, `observe`, `act`,
   `status`, `screenshot`, and `close`
 - assistive page understanding for `extract` and some goal-based
   `observe(session, goal)` calls
+- deterministic field data-plane for deciding which caller-supplied
+  value belongs in which observed field (`match`, `resolve`, `fill`)
 - protected fill for applying sensitive values you already have through a
   guarded form execution path
 
@@ -155,6 +157,22 @@ serve different intents:
 - `observe(session)` is for general page inspection
 - `observe(session, goal)` is for a focused question
 
+These examples share a shape that works well: each names one control,
+optionally anchored to a surface. A useful goal looks like
+`"find <target> in <surface>"`:
+
+- one target — a single field, button, or grid cell
+- one surface — the active form, the open datepicker, the visible banner
+- one step — the goal describes what the next `act` will target,
+  not the rest of the plan
+
+When the task takes several steps, run one `observe` per step:
+
+1. `observe(session, "find the date picker trigger in the top search form")`
+2. `act(session, trigger.ref, "click")`
+3. `observe(session, "find May 5, 2026 in the open calendar")`
+4. `act(session, cell.ref, "click")`
+
 ### `act(session, targetRef, action, value?)`
 
 Executes a browser action against a `targetRef` returned by `observe(...)`.
@@ -197,6 +215,31 @@ Closes the browser session.
 This also terminates the internal sticky owner. Repeated closes and already-
 dead owner hosts are treated as idempotent.
 
+### `match` / `resolve` / `fill`
+
+Three primitives for the «key–value pairs into an observed form» problem.
+Instead of calling `act(session, ref, 'fill', value)` by hand, the
+primitives let you hand a source of candidate values to `match(...)`,
+resolve externally stored values through a caller-supplied adapter, and
+apply the result to the browser deterministically — without the values
+passing through LLM prompts or public result objects.
+
+The typical shape is `match → (resolve) → fill`:
+
+```ts
+import { match, resolve, fill } from '@mercuryo-ai/agentbrowse';
+
+const matched = await match(emailTarget, {
+  from: { email: 'traveler@example.com' },
+});
+await fill(session, emailTarget, matched);
+```
+
+See the dedicated [Match / Resolve / Fill Guide](./match-resolve-fill.md)
+for the full mental model, walk-throughs (value in hand, external
+lookup, batch, grouped protected forms), and the design rules (no raw
+values in public results, stable resolved refs, adapter boundary).
+
 ## How To Handle Results
 
 All main commands use the same broad pattern:
@@ -264,6 +307,7 @@ See:
 ## Next Docs
 
 - [API Reference](./api-reference.md)
+- [Match / Resolve / Fill Guide](./match-resolve-fill.md)
 - [Configuration Guide](./configuration.md)
 - [Assistive Runtime Guide](./assistive-runtime.md)
 - [Protected Fill Guide](./protected-fill.md)

package/docs/integration-checklist.md

@@ -13,9 +13,38 @@ integration.
 - use `observeResult.targets` as the default flat inventory
 - use `target.ref` as the input to `act(...)`
 - pass a plain schema object or a Zod schema to `extract(...)`
-- branch on stable top-level `error` codes, not on `reason`
+- branch on stable top-level `error` codes, not on `reason` — the
+  per-command list lives in
+  [`api-reference.md` → Error codes by command](./api-reference.md#error-codes-by-command)
 - treat `reason` as human-readable diagnostics, not as a stable switch key
 
+## Match / Resolve / Fill
+
+- branch on `match(...)` result `kind` — never infer from the presence
+  of individual fields on the result object
+- default match results carry `valueRef` / `artifactRef` strings, not
+  raw values; the accessor that dereferences them is a non-enumerable
+  symbol on the `ready` result and does not survive JSON serialization
+  or `structuredClone`. Do not serialize ready results across process
+  boundaries — ship the `needs_resolution` plan instead and let the
+  downstream side run `resolve → fill` in one shot
+- the main `AgentbrowseMatchResolver` has a required `resolve` plus
+  optional `resolveBatch` and optional `fill`. A narrow
+  `AgentbrowseGroupFillHandler` with just `fill` is also accepted in
+  the `{ resolver }` slot on `fill(...)` and is the right shape when
+  the caller already has a ready grouped artifact and does not fetch
+  anything. `resolve(plan, { with })` only accepts the main interface.
+  Runtime `fill(...)` returns `match_resolver_required` when the passed
+  object lacks a capability the current plan needs
+- batch `resolve([...])` preserves input order — downstream code can
+  rebuild the `target → ready` mapping by index
+- use `@mercuryo-ai/agentbrowse/testing` fixture builders
+  (`createFixtureMatchStore`, `createFixtureGroupStore`,
+  `createFixtureResolver`, `fixtureResolvedValue`,
+  `fixtureResolvedArtifact`) in unit tests instead of fabricating match
+  results by hand — hand-built results bypass the accessor pattern and
+  fail to fill
+
 ## Assistive Runtime
 
 - the assistive runtime adapter receives `args.options`
@@ -25,8 +54,8 @@ integration.
 
 ## Testing
 
-- use `@mercuryo-ai/agentbrowse/testing` for the stable fetch-backed assistive
-  runtime helper
+- use `@mercuryo-ai/agentbrowse/testing` for both the fetch-backed
+  assistive runtime helper and the match/resolve/fill fixture builders
 - do not depend on internal fixtures or unexported runtime-state helpers
 
 ## Packaging