@mercuryo-ai/agentbrowse 0.2.60 → 0.2.63

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