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.
160 lines
7.1 KiB
Markdown
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.
|