Files
archie/docs/prds/payload-field-mapping.md
T
sam 65e6b2f65b docs(prds): normalise statuses and remove writing dated to its own day
Three defects the first sweep left behind, each caught by a rule the guard
did not yet have.

Statuses. RULES.md gives three; the tree had 25 values, and the free-text ones
were carrying progress. "Implemented (wiring landed)" and "Ratified (rev. 2e).
Rev. 2e adds the OpenTaskByPR lookup. Rev. 2d revised section 10..." were both
changelogs living in the one field the other rules exempt. Every PRD now
declares Draft, Approved or Finalised and nothing else; five that declared
nothing now declare one. A revision number moves to **Revision:**, a pointer
to the authoritative document to **Authority:**, and what a past revision
changed to git. CLAUDE.md's citation of state-store-contract rev. 2e still
resolves.

Stale cross-references. "Supersedes the 2026-09-03 open question", "this
bullet previously said", "an earlier draft of this document claimed" all point
at text the reader cannot see, because it was replaced. A supersede marker
survives only when it names a file, a section or a symbol that can be found.

Temporal hedges. 100 uses of today, currently and right now across 31 files.
Each dates its sentence to the day it was written: "[notify] today is one
webhook URL, read in one place" stops being true the moment this design lands,
while still reading as the premise it rests on.

The header-field exemption was also too wide. "**Date:** 2026-09-03, Channel
resolved 2026-09-22" smuggled a dated status into the one line the rules did
not read; the exemption is now a Date holding only a date and a Status holding
only one of the three.
2026-09-22 00:38:35 +10:00

160 lines
7.1 KiB
Markdown

# Payload field mapping -- decision
**Status:** Approved
**Date:** 2026-08-22
**Beads issue:** `archie-core-t2db.3`, depends on `t2db.1`, blocks `t2db.4`
Answers what a "mapping" is, where it lives, and what "resolve against a
real event" means precisely enough to implement. `t2db.4` (binding: matcher
+ mapping + workflow) is out of scope -- this bead ships the mapping
concept and its preview only, as a standalone entity `t2db.4` will later
reference by ID.
## Decision: a new `internal/domain/mapping` package, SQLite storage
`internal/domain/mapping` owns the mapping vocabulary and the pure
resolve/preview rule; `internal/store` persists it (mirrors
`captures.go`'s shape exactly -- inline schema const, narrow store
interface, `*store.Store` implementation); `internal/webui/api_mapping.go`
is the transport. This follows `docs/prds/event-capture-storage.md`'s own
placement precedent: `internal/store` is where this daemon's persistence
already lives, not `internal/infrastructure` (that layer holds
cross-domain services -- config, eventbus, modelcatalog -- not this
daemon's primary store).
### Why a domain package and not just a store table
Resolving a path against a payload and deciding "missing vs null vs
type-changed" is a rule, not a query -- CLAUDE.md's domain layer owns
"language, state, rules, operations" precisely so this logic is testable
without a database and reusable by `t2db.4`'s runtime trigger path without
either package importing the other's transport concerns.
## Mapping shape
```go
type Mapping struct {
ID int64
Name string
SourceHint string // free-text label (e.g. "sentry"), organisational only -- not enforced against Capture.Source
Fields []Field
CreatedAt time.Time
UpdatedAt time.Time
}
type Field struct {
Name string // the name the workflow receives
Path string // dot/bracket path into the payload, see below
Type FieldType // expected type, checked at resolve time
Required bool // Required=false + missing is not a failure; Required=false + wrong type still is
}
type FieldType string // "string" | "number" | "bool" | "object" | "array" | "any"
```
`SourceHint` is advisory only: an operator authors a mapping by clicking
through one example capture, but the mapping is not pinned to that
capture's exact source string, because `t2db.4`'s matcher (not this bead)
decides which events a binding applies to. Pinning here would duplicate
that decision in the wrong layer.
## Path syntax
Dot-separated keys with `[N]` for array indices: `data.items[0].id`. No
wildcards, no filters, no external library -- the grammar is exactly what a
click-through UI needs to express (this key, then this key, then this
index), and every path in a mapping was generated by clicking a value in a
real payload, never hand-written against a spec. A hand-rolled parser
(~30 lines: split on `.`, strip `[N]` suffixes) is less risk than a new
dependency for a grammar this small.
## Resolve semantics (the preview AND the future runtime path)
```go
func Resolve(fields []Field, payload []byte) (values map[string]any, failures []Failure)
type Failure struct {
FieldName string
Path string
Reason string // "missing" | "null" | "type_mismatch"
}
```
Decode with `json.Decoder.UseNumber()` (matches `webhookguard.RedactPayload`'s
existing convention) so int/float distinction survives for type checking.
Walk each field's path independently -- one field's failure does not stop
resolution of the others, because the whole point of preview is showing
the operator every problem at once, not the first one.
- Path segment doesn't exist, or indexes past an array's length -> `missing`
- Path resolves to JSON `null` -> `null`
- Path resolves to a value whose JSON type doesn't match `Field.Type`
(`"any"` always matches) -> `type_mismatch`
- `Required: false` suppresses `missing` only, never `null` or
`type_mismatch` -- a field that's present but the wrong shape is always
worth surfacing, since silently coercing it is exactly the "agent
confabulates around a blank field" failure this bead exists to prevent.
**This is the same function both consumers use.** `t2db.3`'s preview calls
it against an operator-picked capture and renders every result, pass or
fail, in the UI -- that satisfies this bead's "fail loudly" acceptance
criterion, because at this stage the only runtime consumer of a mapping
*is* the human previewing it. `t2db.4` will call the identical function
when a live event triggers a binding and turn any non-empty `failures` into
a visible operator-facing failure (park the task / surface in the
inspector) instead of starting a workflow with blank fields -- that wiring
is `t2db.4`'s job, not duplicated here.
## Storage
`internal/store/mappings.go`, `field_mappings` table: `id, name,
source_hint, fields_json, created_at, updated_at`. `fields_json` is the
`[]Field` slice JSON-encoded into one column -- fields have no independent
query need (nothing filters "mappings with a field named X"), so a
join table would be structure with no consumer, the same failure mode
`organisation.md` bans for empty layering.
`MappingStore` interface (narrow, mirrors `CaptureStore`):
`InsertMapping`, `ListMappings`, `GetMapping`, `UpdateMapping`,
`DeleteMapping`.
## HTTP surface
All under `/api/mappings`, token-gated like every other `/api/*` route (no
bypass -- unlike capture, nothing here accepts unauthenticated input):
- `GET /api/mappings` / `POST /api/mappings` -- list / create
- `GET|PATCH|DELETE /api/mappings/{id}`
- `POST /api/mappings/preview` -- body `{fields: []Field, capture_id:
int64}`, calls `mapping.Resolve` against that capture's stored (already
redacted) `Body` and returns `{values, failures}`. Deliberately takes
loose `fields` rather than a saved mapping ID, so an operator can iterate
before saving anything -- "never ship a mapping the operator has not seen
resolve against real data" requires preview to work pre-save.
Preview resolves against `CapturedEvent.Body`, which is already
redaction-passed (`webhookguard.RedactPayload`, per
`event-capture-storage.md`) -- a mapped field pointing at a
sensitive-keyed path previews as the literal string `"[redacted]"`, not the
real value. This is accepted, not fixed here: it is the stored ground
truth, the same payload `t2db.4`'s runtime path will resolve against, and a
preview mismatch would be worse than an honest one.
## Frontend
New `ui/src/mappings/` feature folder, same three-file split as
`ui/src/captures/`: `mappings.js` (page: list, fetch, create/edit flow),
`mapping-editor.js` (pure, unit-testable: renders a captured payload as a
clickable tree -- clicking a leaf appends a field row with `Path`
pre-filled -- plus the field table and preview-result rendering),
`mappings.css`. Creating a mapping starts from an existing captured event
(reuses `api.captures`), so the editor always has a real payload to click
through and preview against, never a blank form.
## What this does not decide
The binding entity, its matcher, its draft/pending_approval/armed state
machine, and turning a runtime `Resolve` failure into a parked task are
`t2db.4`. Per-source HMAC secret registration is `t2db.5`. This bead ships
the mapping concept, its storage, and its preview only.