@sonordev/contracts 2.18.0 → 2.21.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -19,7 +19,7 @@ pnpm add @sonordev/contracts
19
19
  | `@sonordev/contracts/seo-pages` | Which `seo_pages` row a path resolves to on a multi-site project | the Sonor API, Signal, site-kit's sitemap sync |
20
20
  | `@sonordev/contracts/seo-meta` | Whether a title or description is fit to ship | site-kit, Signal's SEO gate |
21
21
  | `@sonordev/contracts/llms` | llms.txt sanitizers, the word-safe cut they use (`clipAtWordBoundary`), what each page line says (`pickLlmsPageDescription`: summary, curated meta, served meta, schema description, then a cleaned scrape; `llmsPageTitle`, `isLlmsListablePage`, `groupLlmsPages`, `selectLlmsPages`) and the contract version | site-kit, the Sonor API, Signal's schema validation |
22
- | `@sonordev/contracts/forms` | The honeypot policy | site-kit forms, the Sonor API's form intake |
22
+ | `@sonordev/contracts/forms` | Shared form validation helpers | site-kit forms, the Sonor API's form intake |
23
23
  | `@sonordev/contracts/fleet` | The fleet heartbeat's wire shape | site-kit, the Sonor API |
24
24
  | `@sonordev/contracts/slots` | Slot payload signing, contract v2 (HMAC; Node only). Signs and verifies v1 for older site-kit releases | the Sonor API, site-kit on the server |
25
25
  | `@sonordev/contracts/slot-content` | What a slot of each kind may hold (`normalizeSlotValue`), safe links, the rich-text parser. No `crypto`, so browsers can import it | the Sonor API, site-kit, the dashboard editor |
@@ -42,6 +42,9 @@ pnpm add @sonordev/contracts
42
42
  | `@sonordev/contracts/inbox` | Which inbox cards are decisions a bulk action leaves alone (`isDecisionCard`, `DECISION_INSIGHT_TYPES`) | Signal's inbox decides what "Mark all read" and "Dismiss all" may touch, the dashboard previews the same result before the write |
43
43
  | `@sonordev/contracts/crm-disposition` | What a rep's call outcome (positive, negative or left voicemail) changes on a prospect: the call's outcome and sentiment, the contact's stage, the company's status, today's reminder and outreach (`dispositionTransitions`), and the reasons a negative outcome carries | the Sonor API applies an outcome, the dashboard's calling screen offers the same three buttons and reasons, the sales extension stops flipping a company on dial |
44
44
  | `@sonordev/contracts/decision-roles` | The part a job title says a person plays in a buying decision (`DECISION_ROLES`: owner, decision maker, influencer, gatekeeper), read from the title alone by `decisionRoleForTitle` | the Sonor API's site-people scan and Signal's site-people scout read the same map |
45
+ | `@sonordev/contracts/resonance` | Campaign, consent, measurement, plan, mandate and command parsers, types and JSON schemas | Sites, APIs and the dashboard share the same wire rules |
46
+ | `@sonordev/contracts/resonance-constants` | Small browser-safe measurement wire constants | Browser readers that don't need campaign schemas |
47
+ | `@sonordev/contracts/signal-experiments` | Shared Signal experiment create and update validation | APIs and the dashboard use one experiment boundary |
45
48
 
46
49
  ## Focus closing artwork
47
50
 
@@ -853,6 +856,7 @@ import { createHash } from 'node:crypto'
853
856
  import {
854
857
  ARTICLE_COVER_LAYOUTS, CARD_LAYOUTS, isCardLayoutId, normalizeArticleCoverLayout,
855
858
  normalizeReviewCardVariation, reviewCardVariationFromDigest, reviewCompositionSeed,
859
+ REVIEW_PHOTO_PRESENTATIONS, isReviewPhotoPresentation,
856
860
  } from '@sonordev/contracts/broadcast-layouts'
857
861
 
858
862
  CARD_LAYOUTS // ['stacked', 'headline', 'split', 'anchor']
@@ -861,6 +865,9 @@ isCardLayoutId('stacked') // true: an old post still reads
861
865
  normalizeArticleCoverLayout('stacked') // 'anchor'
862
866
  normalizeArticleCoverLayout('split') // 'headline'
863
867
  normalizeReviewCardVariation('spotlight') // 'signature'
868
+ REVIEW_PHOTO_PRESENTATIONS // ['background']
869
+ isReviewPhotoPresentation('background') // true
870
+ isReviewPhotoPresentation(null) // false: a clear operation is handled by the caller
864
871
 
865
872
  // On the server: a review's composition, stable for its identity.
866
873
  const digest = createHash('sha256').update(reviewCompositionSeed(projectId, reviewId)).digest()
@@ -889,6 +896,13 @@ reviewCardVariationFromDigest(digest) // 'signature' or 'frame'
889
896
  as Signature and anything unknown as the default, Signature.
890
897
  **`isReviewCardVariation`** is the strict check for a request that must
891
898
  name a drawn one.
899
+ - **`REVIEW_PHOTO_PRESENTATIONS`** lists explicit per-review photo choices:
900
+ `background` places the primary photo behind the review text. The
901
+ `ReviewPhotoPresentation` type and `isReviewPhotoPresentation` guard share
902
+ that supported set. The guard accepts explicit values only; input consumers
903
+ handle omission (preserve a saved choice) and `null` (clear it to automatic)
904
+ separately. Existing records without a choice keep their deterministic
905
+ composition; presentation doesn't change the seed or variation draw.
892
906
  - **A review's composition never moves.** It's drawn from the SHA-256 of
893
907
  `reviewCompositionSeed(projectId, reviewId)`, never from anything a person
894
908
  can edit. `reviewCardVariationFromDigest` reads the first four bytes
@@ -1146,3 +1160,545 @@ Use `parseFunnelCreateArgs`, `parseFunnelUpdateArgs`, `parseFunnelRevisionArgs`,
1146
1160
  `parsePublishedFunnelPage` refuses private definition fields and unsafe asset URLs. It supports bounded text paragraphs and bullet lists, with a managed form slug and canonical campaign identity. `managedFunnelPath` reserves `/f/:slug`; a consuming site must opt in and verify its actual routes.
1147
1161
 
1148
1162
  `parseFunnelReadiness`, `parseFunnelOperationReceipt` and the detail/catalog/preview parsers validate bounded response envelopes. Operation receipts bind the exact command target and approved action, and always report zero messages sent by the configuration command. Preview and published-version detail parsers preserve the exact launch or rollback evidence.
1163
+
1164
+
1165
+ ## Authoring Funnel experiments in 2.21.0
1166
+
1167
+ Managed Funnel definitions can optionally save `page.experiment`:
1168
+
1169
+ ```ts
1170
+ import { parseFunnelExperimentAuthoring } from '@sonordev/contracts/funnels'
1171
+
1172
+ const experiment = parseFunnelExperimentAuthoring({
1173
+ experimentId: '11111111-1111-4111-8111-111111111111',
1174
+ experimentRevision: 3,
1175
+ controlVariantKey: 'control',
1176
+ variants: [
1177
+ { variantKey: 'control', content: { headline: 'Workshop news', body: [] } },
1178
+ { variantKey: 'alternative', content: { headline: 'Ideas from the workshop', body: [] } },
1179
+ ],
1180
+ })
1181
+ ```
1182
+
1183
+ This closed author input selects an experiment and supplies keyed headline/body
1184
+ copy. It accepts 2–50 unique variant keys, including the selected control. Keys
1185
+ use the existing 80-character bound; headlines use 160 UTF-16 code units. Bodies
1186
+ use the existing paragraph/bullet limits and 12,000-character aggregate limit per
1187
+ variant. Draft create/update parsers allow blank copy while saving, just like
1188
+ base page copy. `parseFunnelDefinition` and `parseFunnelExperimentAuthoring`
1189
+ require complete copy. The field is supported only on managed pages. Omit it to
1190
+ remove authored experimentation; `null` isn't accepted. Plain Funnel documents
1191
+ and `createFunnelDraft` defaults stay unchanged.
1192
+
1193
+ The authored object accepts only `experimentId`, `experimentRevision`,
1194
+ `controlVariantKey` and `variants`. Each variant accepts only `variantKey` and
1195
+ `content`; content accepts only `headline` and `body`. The base definition keeps
1196
+ one fixed form, offer, brand, route and tracking identity. This input doesn't
1197
+ accept a content digest, goal authority, instance reference or approval flag.
1198
+
1199
+ The native service must resolve the selected real experiment and linked campaign
1200
+ under the current project, site and Full Signal revision, verify the complete
1201
+ native variant set and control, derive the goal from that campaign, and hash each
1202
+ effective full content including the fixed offer. It then produces the existing
1203
+ `PublishedFunnelPage.experimentContent` manifest during normal preview creation.
1204
+ Authored selection is untrusted input; successful parsing grants no readiness,
1205
+ publication, assignment or execution authority. Save, preview, review and publish
1206
+ continue through the existing Funnel lifecycle and approvals. The editor must
1207
+ show every effective variant before review. Lifecycle rebuilds use the saved
1208
+ definition as their content source.
1209
+
1210
+ Matching structural schemas are exported through
1211
+ `FUNNEL_EXPERIMENT_AUTHORING_JSON_SCHEMA`, `FUNNEL_DEFINITION_JSON_SCHEMA`,
1212
+ `FUNNEL_DRAFT_DEFINITION_JSON_SCHEMA` and the existing create/update schemas.
1213
+ Runtime parsers additionally check unique keys, control membership, aggregate
1214
+ body length and managed-page applicability.
1215
+
1216
+ Deploy compatible contracts, parsers, native producer, renderer and editor
1217
+ consumers together before exposing the field. Older strict definition parsers
1218
+ reject `page.experiment` even though the field is optional in 2.21.0. A package
1219
+ upgrade alone doesn't implement native production or authorize publication.
1220
+
1221
+
1222
+ ## Adopting 2.20.0
1223
+
1224
+ Use the same contracts version in every application that exchanges Resonance
1225
+ payloads. This release includes the 2.19 review-photo presentation exports and
1226
+ adds the Resonance and Signal experiment entries. Existing package subpaths stay
1227
+ available. Import a specific entry rather than the package root.
1228
+
1229
+ ```ts
1230
+ import { parseMoney } from '@sonordev/contracts/resonance'
1231
+
1232
+ const budget = parseMoney({ currency: 'USD', amountMicros: '1250000' })
1233
+ ```
1234
+
1235
+ The parsers validate wire data. They don't approve a campaign, authorize spending
1236
+ or confirm provider delivery. Keep those checks in the application that owns the
1237
+ action. Deploy accepting server parsers before enabling new browser fields.
1238
+
1239
+ ## The resonance contract
1240
+
1241
+ Import pure parsers, types and JSON schemas from `@sonordev/contracts/resonance`.
1242
+ `parseResonanceCampaignDraft` accepts bounded incomplete setup; `parseResonanceCampaignDefinition`
1243
+ requires resolved goals, resources, destinations, channels and budget. Existing funnel,
1244
+ Broadcast, Outreach, Files, brand and experiment records retain ownership. Nested
1245
+ references must match the campaign's project and owned-site scope. Server lookups
1246
+ must still validate ownership, current revisions, policy and actual permission.
1247
+
1248
+ `Money` is `{ currency: 'USD', amountMicros: '1250000' }`, exactly 1.25 USD.
1249
+ `parseMoney`, `addMoney`, `moneyToProviderUnits` and `moneyFromProviderUnits` use
1250
+ integer arithmetic. Never pass amounts through `Number` or assume every currency
1251
+ uses cents. Conversion requires the verified provider/account exponent (0, 2, 3 or
1252
+ 6) and native limit; fractional units, overflow and currency mismatch fail.
1253
+ Supported currency codes are exported as `RESONANCE_CURRENCIES`; actual advertiser
1254
+ eligibility, minimum budgets and delivery semantics remain provider checks.
1255
+
1256
+ The initial paid profiles are `google_search` and `meta_retargeting`, distinct
1257
+ from provider IDs `google_ads` and `meta_ads`. They are closed plans, not arbitrary
1258
+ provider JSON or a claim to support every campaign type. Prepared plans bind exact
1259
+ ordered creative copy/media/crop references, destinations, budgets, goal/policy
1260
+ revisions and server-owned compiled manifest references. `resonancePlanIssues`
1261
+ reports blocked, missing or stale capabilities without turning them into success.
1262
+
1263
+ `parseResonanceMandateApprovalPayload(value, target)` validates the exact business
1264
+ payload and project/campaign target. It doesn't approve anything. Resolve original
1265
+ principal and approval provenance through the existing Action Ledger; compute and
1266
+ verify the server digest over `resonanceMandateDigestInput` before admitting effects.
1267
+ The command digest input similarly canonicalizes only parsed command fields.
1268
+ Launch/update/resume and optimization require exact plan/mandate lookups. Safety
1269
+ pause/finish/reconcile commands require root revision and idempotency identity but
1270
+ no fresh creative approval, so stale creative evidence cannot prevent a stop.
1271
+
1272
+ An immutable `PreparedPlan` is stored as an existing campaign version; it is review
1273
+ evidence, not approval authority. Receipt state and unresolved exposure remain
1274
+ separate from approval. An uncertain provider admission requires reconciliation
1275
+ before retry; it must not release liability or repeat creation automatically.
1276
+
1277
+ Metric observations distinguish observed zero from unknown, insufficient, delayed
1278
+ and unavailable values, retain window/timezone and native-unit evidence, and use
1279
+ exact counts/money/ratios. Consent and conversion parsers validate scoped evidence;
1280
+ a browser cannot mint a trusted lead by passing validation. Accepted source rows,
1281
+ current consent/withdrawal and experiment exposure must be verified server-side.
1282
+ No scripts, credentials, cookies or customer personal data belong in these DTOs.
1283
+
1284
+
1285
+ The save/binding/accept command parsers use the same strict wire rules. Updates
1286
+ require an expected root revision; root creation can omit it. Account bindings
1287
+ select existing provider resources, never credentials. Optimizer evidence and
1288
+ immutable decisions have separate parsers: they retain unknown tracking/power
1289
+ checks, exact before/after allocations and remote snapshot identities. Resolve
1290
+ minimum evidence, lag, cooldown and mandate coverage from the referenced frozen
1291
+ policy on the server. Parsed metrics or an actionable decision alone never grant
1292
+ spending authority. A blocked or no-op decision cannot carry allocation effects.
1293
+
1294
+
1295
+ Public measurement configuration is a separate closed DTO. It carries only typed
1296
+ Google Ads tag/Meta pixel identifiers, permitted resource rules and basic consent
1297
+ policy. A measurement occurrence is a view, explicit interest or experiment
1298
+ exposure; it cannot declare an accepted conversion. Consent updates preserve
1299
+ unknown, denied and withdrawn states. These parsers don't load any tags, collect
1300
+ browser data or turn a reported grant into server-verified permission. The browser
1301
+ runtime and server evidence/withdrawal checks must implement those controls.
1302
+
1303
+ Page-view occurrences can include optional `clickIdentifiers`, with exactly one
1304
+ closed shape: `{ gclid: string }`, `{ gbraid: string }` or `{ wbraid: string }`.
1305
+ `parseResonanceClickIdentifiers`, `ResonanceClickIdentifiers` and
1306
+ `RESONANCE_CLICK_IDENTIFIERS_JSON_SCHEMA` share that boundary. Values contain
1307
+ 1 to 1024 characters, with no whitespace or control characters. This is the
1308
+ application's transport bound. Other occurrence kinds reject the field.
1309
+ The browser reads the current URL only after the required advertising grants
1310
+ and scoped proof are available. An observed identifier doesn't authenticate a
1311
+ paid click. The server must verify the same subject, site, current consent and
1312
+ actual form occurrence before using it for conversion matching. Identifiers
1313
+ don't belong in public configuration, receipts, results or logs. Deploy the
1314
+ accepting server parser before enabling browser emission.
1315
+
1316
+ Initial acceptance uses only `{ expectedRevision, ledgerActionId }`. The server
1317
+ loads the approved native payload and current kill state and returns the canonical
1318
+ mandate reference. Clients must never guess a kill revision to construct authority.
1319
+
1320
+
1321
+ Managed definitions contain the closed `optimization.policy`; prepared plans freeze
1322
+ an identical `resolvedEvidencePolicy`. Initial inline policies have `sourceRef: null`.
1323
+ A genuine existing source can supply optional provenance, but a new campaign doesn't
1324
+ need a synthetic experiment, self-referencing plan or new policy table. The first
1325
+ algorithm is explicitly observational qualified-lead CPQL allocation with approved
1326
+ maturity, coverage, uncertainty, attribution, lag and cooldown values. Executable
1327
+ allocation and current source/mandate admission remain server-owned.
1328
+
1329
+ ### Finite preapproved Meta candidates
1330
+
1331
+ The optimization policy also supports the closed `finite_meta_candidates_v1`
1332
+ branch with `decisionKind: 'preapproved_candidate_operation'`. One policy
1333
+ variant belongs to each original plan. The existing mature allocation branch
1334
+ keeps its meaning and shape.
1335
+
1336
+ The finite policy uses `candidateChannelIds` to reference original Meta channels
1337
+ in the same definition. Their existing creatives, account, site, independent
1338
+ adset lifetime cap and original budget flight remain authoritative. The policy
1339
+ doesn't copy those inputs or contain compiled graph hashes. It records an exact
1340
+ reviewed order and schedule, one activation per candidate, concurrency, allowed
1341
+ actions, a typed exploration ceiling, tracking requirements and hard stops.
1342
+ `performanceDecisionPolicy` is explicitly `null`: this profile supports fixed
1343
+ exploration and approved safety stops, with no measured winner, adaptive pruning,
1344
+ budget increase, promotion or causal A/B claim.
1345
+
1346
+ Preparation resolves the original graphs and binds them with the policy in the
1347
+ existing review digest. The existing mandate seals that review. Later evidence
1348
+ and decisions reference the resulting graph identities; their hashes never feed
1349
+ back into the definition policy. No new policy registry or mandate field is used.
1350
+
1351
+ `ResonanceFiniteMetaCandidatePolicy`, `ResonanceFiniteMetaCandidateEvidence` and
1352
+ `ResonancePreapprovedCandidateOperationDecision` narrow the existing generic
1353
+ types. Their parsers, JSON Schemas and digest helpers share the existing
1354
+ `resonance` entry. Cold lifecycle evidence records unobserved measurement as
1355
+ `null`, with no borrowed donor outcomes or invented mature zero. An actionable
1356
+ decision carries exactly one `materialize_and_activate`, `activate_held` or
1357
+ `pause_candidate` action. Blocked and no-op decisions carry none. These decisions
1358
+ don't carry mature adjustments or a fabricated zero-to-cap transfer.
1359
+
1360
+ Pass the actual prepared plan as the optional second argument to
1361
+ `parseResonanceOptimizationEvidence` to check original public scope, manifest,
1362
+ cap and flight. Pass actual evidence and, when available, that plan as the second
1363
+ and third arguments to `parseResonanceOptimizationDecision` to check policy,
1364
+ action, fixed order, freshness and commitment-reference consistency. Parsing a
1365
+ standalone object checks its closed shape; it can't authenticate referenced rows
1366
+ or establish approval. Servers must load and verify the actual accepted plan,
1367
+ native claim, current permission and protected evidence before admission.
1368
+
1369
+ The API and database reserve the full independent cap before the first create.
1370
+ Activating an already paused candidate adds no new exposure only when its exact
1371
+ original physical commitment is already fully held. Resource presence or a
1372
+ reference alone doesn't prove that condition. Pause and donor decreases don't
1373
+ release old holds; uncertain effects retain their original key and reconcile.
1374
+ The public optimize command and existing Ledger workflow are unchanged.
1375
+
1376
+ Provider spend, clicks and impressions retain their own `provider_aggregate`
1377
+ counting unit and `provider_reported` attribution. First-party qualified-cohort
1378
+ observations keep the original objective's counting unit and attribution model.
1379
+ They aren't interchangeable evidence, and neither enables a performance
1380
+ decision in this fixed profile.
1381
+
1382
+ Ordinary optimize actions, including an explicitly allowed candidate pause,
1383
+ remain inside the current policy and mandate expiry. At or after expiry,
1384
+ creation and activation stop; any needed pause uses the existing current-owner
1385
+ safety pause or escalation path. This contract doesn't create post-expiry
1386
+ permission or a second stop-validity clock.
1387
+
1388
+ Public measurement transport uses the dedicated `X-Sonor-Resonance-Subject`
1389
+ header. Config reads do not issue identity. Only an explicit preference action
1390
+ can receive `subjectProof`, `expiresAt`, `currentConsentRevision` and the four
1391
+ purpose receipts. This is an opaque scoped proof, kept in browser memory. Proof expiry isn't
1392
+ consent expiry and must not force recurring consent prompts. Valid current CMP
1393
+ state may support scoped proof renewal/resumption through the authoritative API;
1394
+ until a valid proof is available, exports stay off. Config itself never bootstraps identity.
1395
+ `expectedConsentRevision` atomically fences the complete subject preference batch.
1396
+ The browser must discard stale grant replies, stop immediately on withdrawal,
1397
+ and never replay pre-consent events or bootstrap identity on config/page load.
1398
+ These contracts describe evidence, not an implemented transport or real-person identity.
1399
+
1400
+
1401
+ Tracking-only legacy campaign views retain revision zero; managed campaigns require
1402
+ at least revision one. Creation can adopt a tracking root at zero, but updates need
1403
+ a managed revision. Unknown admission in any child forces reconciliation and cannot
1404
+ be hidden by a failed root label or retry advice. Known reconciled/rejected work
1405
+ may still retry the same original operation when the server authorizes it.
1406
+
1407
+ `parseResonanceSubjectRenewCommand` accepts only current consent/config/policy
1408
+ revisions. Renewal rotates a proof without granting or changing consent. It requires
1409
+ the scoped subject transport and current server/CMP checks; it isn't permission to
1410
+ bootstrap identity from a config read or recover someone else's receipt.
1411
+
1412
+
1413
+ Public renewal includes schema version and the asserted project/site envelope as
1414
+ well as current revisions; the server resolves and verifies that scope from proof
1415
+ and credential. Finite allocation horizons carry verified UTC start/end, timezone
1416
+ and source revision, so eligible total/lifetime budgets can be compared on the
1417
+ same actual period without relabeling daily averages as hard lifetime caps.
1418
+
1419
+ `cpqlMissingOutcomeBound` computes the named observational sensitivity method from
1420
+ trusted unique-contact totals: eligible `n`, fully resolved attribution/dedupe/final
1421
+ qualification intersection `c`, and qualified subset `k`. It returns the ceiling of
1422
+ `10000*(n-c)/(2*k+n-c)`, or unknown when no positive source universe exists. This
1423
+ isn't statistical confidence, causal lift or permission to inject counts from a
1424
+ browser. API source producers must verify the complete universe and spend period;
1425
+ without that witness, the evidence bound remains unknown. Coverage stays separate.
1426
+
1427
+ ### Successor management and attribution fields
1428
+
1429
+ The local 2.20 candidate adds `@sonordev/contracts/signal-experiments` as the
1430
+ single parser for the existing Signal create/update payload. It exports
1431
+ `parseSignalExperimentCreate`, `parseSignalExperimentUpdate`, their types and
1432
+ JSON Schemas. Both operations check unique variant keys and the existing
1433
+ weight-sum tolerance of 0.01. Percentages must be finite and within 0 to 100.
1434
+ Optional allocation and targeting defaults remain the existing service's job.
1435
+ Parsing doesn't grant access or select a variant.
1436
+
1437
+ `/resonance` adds audience draft save and experiment create/update, lifecycle,
1438
+ complete and link command parsers. Each managed experiment command requires
1439
+ `expectedRevision` and `idempotencyKey`. Audience drafts reference the current
1440
+ measurement config's resource rule IDs. The server resolves their scope and
1441
+ provider retention limit. Saving a draft uploads no people or audiences.
1442
+
1443
+ Public source markers use the `sonor_source` parameter and bounded
1444
+ `rsm1.<claims>.<signature>` format. A prepared channel preview can carry an
1445
+ `attributionMarker`; its destination URL must contain exactly that reviewed
1446
+ marker. An occurrence can carry the bounded `sourceMarker` value. The pure
1447
+ parser checks format and URL coherence. The server verifies the signature,
1448
+ purpose, accepted immutable plan and actual resource scope.
1449
+
1450
+ `first_party_last_touch_marker_v1` describes server-recorded first-party source
1451
+ mapping under the reviewed attribution window. It doesn't establish a paid
1452
+ click, a human visit or a causal effect. Unresolved source linkage stays
1453
+ unallocated. The existing resource, audience-rule and experiment-reference
1454
+ readers are also exported so owner projections can use the same validators.
1455
+
1456
+ Qualified-lead prepared plans require a non-null `resolvedQualificationRule`.
1457
+ Other objectives carry an explicit null. The objective keeps the selected
1458
+ `qualificationRule`; the prepared projection shows its actual CRM project ref,
1459
+ `crmVariant`, native `ladderSnapshot`, eligible form and cohort boundaries.
1460
+ `semantic_key` and native preset stage IDs can be null. The parser preserves
1461
+ those native values and never manufactures a stage UUID or infers qualification
1462
+ from a stage's position or won/lost flag.
1463
+
1464
+ The three selected stage partitions must be disjoint and exhaust the resolved
1465
+ native ladder. The public projection must match the selected partitions, native
1466
+ ref, source form, counting unit and maturity delay. API persistence resolves one
1467
+ canonical witness and uses that same object for internal resource evidence and
1468
+ public review. The server must verify its actual source and digest. These shape
1469
+ checks don't establish that a caller supplied genuine database rows.
1470
+
1471
+ `PreparedPlan.expiresAt` is an initial acceptance freshness deadline. Continuing
1472
+ an already accepted campaign uses its current native mandate and budget limits,
1473
+ with current resource and capability checks. The pure initial-readiness helper
1474
+ doesn't replace those authority checks.
1475
+
1476
+ ### Preparing a campaign command
1477
+
1478
+ `parseResonanceCommandPrepareRequest` reads only `expectedRevision` and `idempotencyKey`. The API resolves the accepted plan, current resources and authority for launch, update or resume. `parseResonanceCommandPrepareResponse` reads `{ command, covered, approvalRequirement, reasonCodes }`, where `command` may be `null` and `approvalRequirement` is `existing_mandate`, `current_owner` or `null`. A covered command still needs its required native approval and claim. Resume after a pause requires the current owner's approval through the existing action ledger.
1479
+
1480
+ `@sonordev/contracts/resonance-constants` exports `RESONANCE_SUBJECT_HEADER`, `RESONANCE_SOURCE_MARKER_PARAMETER` and `RESONANCE_ATTRIBUTION_MODEL` without loading campaign schemas. The main Resonance entry re-exports these same literals. Browser adapters can use the constants entry when they don't need a parser.
1481
+
1482
+ ### Delivering a qualified Google conversion
1483
+
1484
+ The existing `ResonanceCommand` union adds `operation: 'deliver_conversion'`. It requires the usual schema version, campaign, prepared plan, review digest, expected revision, idempotency key and mandate reference, plus `channelIds` with exactly one original Google channel and `conversionId` for the persisted canonical qualified fact. The command carries no click identifiers, personal data, provider payload, values, timestamps, native destination or approval flags.
1485
+
1486
+ The original mandate must explicitly include `deliver_conversion` in `allowedOperations`. A launch-only grant doesn't gain delivery permission. The existing original review binds the goal, source, qualification witness and Google configuration; there's no second delivery policy object. The initial profile is `qualified_at_observation_v1` for one managed-form qualified source and one destination. Existing goals with multiple actions are rejected for delivery. Cross-account action ownership remains unsupported.
1487
+
1488
+ `parseResonanceCommand(value, { preparedPlan, mandate, now })` optionally checks those actual parsed objects for original scope and prepared definition revision, goal, budget, account, site, single-action Google profile and the original dispatch window. The one-argument call remains shape validation. An accepted plan's initial freshness deadline doesn't create a reporting tail: new dispatch must remain within its original mandate and budget window. Ordinary delivery stops after expiry; read-only receipt reconciliation doesn't resend it.
1489
+
1490
+ These checks don't authenticate a persisted fact, current principal, kill or finish state, qualification, consent continuity, native claim or export deduplication. The server must verify the protected same-root goal-installation receipt and current native ownership. Setup intent only binds the reviewed local action and strategy; actual destination resolution requires its original successful native setup receipts. Missing or stale provenance blocks delivery. Parsing neither proves that setup ran nor authorizes a provider request. Accepted provider ingestion doesn't establish attribution or bidding success.
1491
+
1492
+ ### Google campaign configuration
1493
+
1494
+ `parseResonanceGoogleConfigurationSaveCommand` reads a strict draft request
1495
+ with `schemaVersion: 1`, `expectedCampaignRevision`, `expectedRevision`,
1496
+ `idempotencyKey`, the required `signalSemantics`,
1497
+ `declaration: { statement, category }` and one top-level mode:
1498
+
1499
+ - `existing`: `nativeGoal: { externalId, actionIds }`, using full native Google
1500
+ resource names. The unique action set is sorted by the parser.
1501
+ - `admitted_setup`: `setupIntent: { requestedGoalName, requestedActionName }`.
1502
+ These are intended display names, bounded to 160 characters, not purported
1503
+ native resources. The server
1504
+ derives the complete setup specification.
1505
+
1506
+ Revision `0` expects no saved configuration. The server checks the campaign
1507
+ and configuration revisions and recovers the original operation by its key.
1508
+ Parsing doesn't save, approve or spend anything. Save the campaign and channel
1509
+ first, retain their IDs, then save their configuration. The configuration
1510
+ response supplies the resulting `campaignRevision`, configuration `revision`,
1511
+ `operationId` and `replayed`. Retry an uncertain save with its original key and
1512
+ body before starting another operation. Re-read the actual campaign after an
1513
+ uncertain initial draft save; its stable ID may now have a later revision.
1514
+
1515
+ The required `signalSemantics` is `qualified_at_observation_v1` for both
1516
+ modes and the setup specification. It describes an explicitly reviewed
1517
+ **historical provider bid signal**, distinct from Sonor's unchanged
1518
+ `current_at_observation` qualified counts. It doesn't promise equal counts or
1519
+ provider count retraction. Existing and new setup profiles currently support
1520
+ only `qualified_lead` with `unique_qualified_contact` and a 1–90 day window.
1521
+ Actual producer eligibility, permanent contact/destination deduplication and
1522
+ delivery remain server checks. Other goal profiles are unsupported.
1523
+
1524
+ The declaration's explicit statement is
1525
+ `DOES_NOT_CONTAIN_EU_POLITICAL_ADVERTISING`; its category is `general`,
1526
+ `housing`, `employment` or `financial_products_services`. The server binds it
1527
+ to actual source, account, creative, copy, destination and region scope, with
1528
+ the actual declarant UUID, timestamp and original
1529
+ `declaredForCampaignRevision`. No permanent statement is inferred from a brand
1530
+ or site. These fields aren't approval identities. The exact statement and
1531
+ resource effects are reviewed within the same campaign mandate.
1532
+
1533
+ `parseResonanceGoogleConfigurationSnapshot` reads the canonical public snapshot
1534
+ with `configurationRevision` and `configurationDigest`. Its top-level mode
1535
+ remains explicit. Existing-mode native goal name and revision may be `null`
1536
+ when draft evidence is unavailable; a real empty provider label stays empty.
1537
+ `parseResonanceGoogleConfigurationReview` requires actual name and SHA-256
1538
+ revision for existing mode.
1539
+
1540
+ Setup mode contains `setupSpec` and `setupDigest`, with no `nativeGoal` or
1541
+ purported native ID/revision. `ResonanceGoogleUploadClicksCustomGoalSpec` has
1542
+ one singular `action`, one matching `goalActionKey`, fixed local dependency
1543
+ keys, requested names and `exclusive_custom_goal_v1`. There are no
1544
+ `actions[]` or `goalActionKeys[]` aliases. The bounded first setup profile is
1545
+ `qualified_lead` with `unique_qualified_contact`, an `UPLOAD_CLICKS` action,
1546
+ `QUALIFIED_LEAD`, `ONE_PER_CLICK`, `primaryForGoal: false`, and the exact
1547
+ objective attribution window from 1 through 90 days. Other new setup pairs
1548
+ are unsupported; longer windows aren't clamped. Actual contact deduplication
1549
+ and delivery identity remain upstream responsibilities. Native per-click
1550
+ counting doesn't implement global contact deduplication. Canonical outcomes
1551
+ and provider reports remain separate.
1552
+
1553
+ `projectResonanceGoogleConfiguration(snapshot, { ready, activationReadiness,
1554
+ reasonCodes })` is the one public view/review projection. The view renames
1555
+ `configurationRevision` to `revision` and adds fresh resolver metadata.
1556
+ `ready` means reviewable, not activated: planned setup uses `pending_setup`,
1557
+ unready configuration uses `blocked`, and existing setup requires final
1558
+ verification or verified native evidence. An unready view returns
1559
+ `review: null`. The corresponding view/save-response parsers validate these
1560
+ shapes without granting authority.
1561
+
1562
+ `resonanceGoogleSetupDigestInput` and
1563
+ `resonanceGoogleConfigurationDigestInput` return canonical JSON for the server
1564
+ hash function. The configuration input omits only its self
1565
+ `configurationDigest`; initial content needs no placeholder. Private
1566
+ eligibility or authorization evidence doesn't belong in this public snapshot.
1567
+ `RESONANCE_GOOGLE_SOURCE_CATEGORIES` and `googleConversionActionSemantics`
1568
+ share native vocabulary with explicit counting and window inputs; vocabulary
1569
+ membership grants no broader setup eligibility.
1570
+ `googleUploadClicksSetupSemantics({ source, countingUnit, attributionWindowDays })`
1571
+ is the shared narrow policy check. It doesn't establish an actual source
1572
+ producer or delivery identity.
1573
+
1574
+ Every prepared preview requires `googleConfiguration`: a strict existing or
1575
+ setup review for Google Search, explicit `null` for other channel kinds.
1576
+ Project, campaign, channel, site, account binding, source, measurement,
1577
+ counting, window and regions must match the enclosing plan. Preparing setup
1578
+ performs no provider mutation. After the same native mandate and admission,
1579
+ actual receipts resolve local keys to native IDs without rewriting the
1580
+ accepted public plan. Activation still needs current native eligibility,
1581
+ source, consent and authority checks. No parser proves those checks occurred.
1582
+
1583
+
1584
+ ### Original Meta website-visit feed
1585
+
1586
+ `ResonanceMandateScope` accepts an optional `websiteVisitFeed` with the profile `sonor_sdk_page_view_fresh_v1` and a `channels` list. Each entry selects an original Meta channel, a `measurementConfigRef`, `resourceRuleRefs` and a `matchingProfileRef`. Account, dataset and site come from that same channel in the reviewed plan. The matching-profile reference identifies the protected configuration-save receipt, its positive integer CAS revision and its digest. No feed is granted when the field is absent. A launch permission, measurement setting or visitor consent alone doesn't grant this feed.
1587
+
1588
+ `RESONANCE_WEBSITE_VISIT_PROFILE` is the fixed, immutable local policy. `resonanceWebsiteVisitProfileDigestInput()` returns its canonical bytes for the server to hash. `resonanceMeasurementConfigDigestInput(config)` parses the measurement config and returns canonical semantic bytes, excluding only `expiresAt`. Current expiry still needs a separate check at capture and every dispatch. Renewal changes no original grant window; a semantic change at the same revision changes the digest. Both helpers retain approved list order and use the same canonical serializer as the existing mandate and command digests.
1589
+
1590
+ The existing command union adds `deliver_website_visit` for the protected native operation path. It carries one original Meta channel and an internal `occurrenceId`, alongside the existing plan, review, revision, idempotency and mandate references. It carries no matching values, timestamps, dataset or provider body. `parseResonanceCommand(value, { preparedPlan, mandate, now })` checks original public grant consistency; it can't establish a protected producer, native claim or permission to send. Manual, public API and MCP entry points must reject attempts to originate this command. Native consumers must use the existing action ledger, standing approval and durable admission path.
1591
+
1592
+ Measurement occurrences gain optional `pagePath` and `metaCookieObservation` fields on `page_view` only. The cookie observation has source `sdk_reported_first_party_cookie` and one or both actual reported `fbp`/`fbc` values. Each value is limited to 1–1024 characters with no whitespace or controls. Matching requires the path and existing resource reference on that same occurrence and navigation. The API must verify the owned site and exact approved rule/path/resource. A separate-origin API can't infer the site's first-party cookies from its own Cookie header. Raw matching belongs only in protected capture persistence, never ledger payloads, operation requests, results, receipts, public configuration or read responses.
1593
+
1594
+ This is an SDK-reported observation. It doesn't prove that a person rendered a page or create a qualified lead or business conversion. The server-only event ID is the internal occurrence UUID; browser/server pairing is unsupported when the browser uses its different public event ID.
1595
+
1596
+ `resonanceWebsiteVisitEventTime({ occurredAt, receivedAt }, { mandate, approvedAt, now })` checks the local time arithmetic and returns epoch seconds from the original reported `occurredAt`. The first receipt and final attempt must each be within 300,000 milliseconds of that original time, inclusive, with zero future allowance. Both original times must follow the original accepted feed approval and stay within its original window. It never substitutes receipt, retry or regrant time. This is Sonor's conservative policy, not a Meta age limit or acceptance guarantee. An authenticated exact-body replay must return its original stored identity and first receipt before new-capture age checks, without insertion, enrichment, queueing or resend. Current consent epochs, grant, kill, claim and global dedupe checks remain native owner responsibilities.
1597
+
1598
+ These pure contracts don't install capture, a protected configuration writer, a matching-profile producer or native delivery. Those owners must implement and verify the actual preparation, original-delivery and terminal non-effect response boundaries before adoption. Parsing a valid payload doesn't make a provider ready or prove delivery.
1599
+
1600
+ ### Original Meta age selection
1601
+
1602
+ An original Meta channel accepts optional `ageConstraint: { mode: 'bounded', min, max } | { mode: 'omitted' } | { mode: 'provider_managed' }`. The provider-managed intent has separate native observation requirements described below. Bounded values are integers from 1 to 120 with `min <= max`; these are local transport bounds, not country, category or provider policy. An absent field preserves legacy bytes and leaves new preparation unresolved. It doesn't select a default. Explicit omission or bounds require an actual current policy witness, and native readback must account for any source-backed normalization. Adapters must block unknown policy rather than ignore the selection or invent ages. This representation doesn't establish that a compiler, account or provider supports it.
1603
+
1604
+ ### Native measurement bootstrap and Meta configuration
1605
+
1606
+ The pure setup contracts describe native owner inputs and saved projections. They don't create provider resources, grant visitor consent, approve spend, or enable the website-visit feed. Native API, SQL, preparation, approval and provider owners must adopt and verify them separately.
1607
+
1608
+ `ResonanceMeasurementConfigurationSaveCommand` selects actual native pages using `{pageId, observedRevision, observedDigest}`. Its closed input also includes `schemaVersion: 1`, `site`, `expectedCampaignRevision`, `expectedConfigurationRevision`, `idempotencyKey`, `enabled` and the basic consent-purpose requirements. It accepts no caller path, rule ID, resource reference, expiry or readiness flag. The three advertising purpose requirements are mandatory; a requirement doesn't grant that purpose to a visitor.
1609
+
1610
+ The native sequence starts with a managed draft and its owned sites; channels can be absent or empty. Measurement bootstrap uses that real draft as an operation audit home. It creates no complete advertising channel. After saving real page rules, the existing audience owner can create logical rules, and the campaign owner can save a complete Meta channel with those returned references. Meta configuration then maps those same logical rules to existing native audiences or admitted creation intent. A present channel still requires its complete original fields.
1611
+
1612
+ Measurement configuration CAS is scoped to project/site. Zero expects actual absence; a legacy or malformed row without protected provenance must block. An audit campaign's revision check doesn't partition the site configuration or advance that campaign's review revision. `projectResonanceMeasurementConfiguration(command, context)` accepts an authorized project, protected current projection, reloaded safe page facts and a native transport expiry. It derives one rule per actual page UUID, sorted by page ID. The page resource revision is canonical UTC milliseconds; the rule revision is the existing full native evidence digest. This preserves distinctions between source updates within one millisecond. Native SQL must independently validate the facts and recompute CAS decisions under its locks.
1613
+
1614
+ Native semantic `configRevision` and `policyRevision` are positive decimal strings. Identical semantics and a new cache expiry preserve them. Page evidence, selected rules or enabled-state changes advance the configuration revision; only consent-policy changes advance the policy revision. Initial provider destinations are `[]`; updates preserve explicitly configured destinations. The helper returns the configuration, friendly page projections and `configurationDigestInput` from the existing `resonanceMeasurementConfigDigestInput`. Hash that exact string once. The save-request digest helper retains original request array order, while derived semantic pages and purposes are sorted.
1615
+
1616
+ Measurement `Current` distinguishes actual `unconfigured` revision zero from a saved `configured` projection with current reasons. `Snapshot` contains the original audit campaign, operation, configuration and friendly page evidence. `SaveResponse` adds `replayed`. The native owner must return an exact original same-key result before fresh CAS/source checks, while enforcing current read permission; a changed request conflicts. No parser proves native provenance.
1617
+
1618
+ The agreed native freshness model is one read-only current-configuration resolver. It checks actual current ownership, protected saved provenance, native page evidence, configuration and policy, then issues a 300-second cache envelope from the database clock. All native purpose, consent, intake, audience, attribution and feed gates must use that same resolver. Reads must not mutate settings, create renewal operations or change original saved bytes. The cache envelope never extends consent, capability, mandate, feed, flight or kill authority. Source drift requires an explicit protected save. This is an adoption requirement, not a claim that those native ports are implemented by this package.
1619
+
1620
+ `ResonanceMetaConfigurationSaveCommand` contains the expected campaign/configuration revisions, schema version, idempotency key and exact original logical audience mappings:
1621
+
1622
+ ```ts
1623
+ { audienceRuleId, mode: 'existing', nativeAudienceRef: { externalId, revision } }
1624
+ // or
1625
+ { audienceRuleId, mode: 'admitted_setup' }
1626
+ ```
1627
+
1628
+ The original channel remains the editable account, dataset, Page, Instagram, country, category, age, budget, creative and destination definition. Save accepts no duplicate channel, provider request, created audience ID for setup intent, matching data or approval flag. The existing native audience reference uses its actual numeric external ID and source evidence revision.
1629
+
1630
+ `ResonanceMetaConfigurationSnapshot` freezes the original channel, root/configuration revisions, reviewed definition digest, saved operation UUID, advertiser and nullable native names, measurement/profile references, friendly rules and resolved audiences. Each audience row is `{audienceRuleRef, name, resourceRuleRef, excludedResourceRuleRefs, selection}`. Its logical name is separate from `selection.nativeAudienceName`; its positive rule is separate from exclusions. Existing selection carries the native reference/name. Admitted selection carries `setup: {kind: 'meta_website_audience_v1', localOutputKey, specDigest}`. The local key is the original SDK `audience:<id>:<revision>` key; `specDigest` identifies the existing SDK audience input. Native HTTP request and compiled graph identities remain distinct private preparation evidence.
1631
+
1632
+ The matching-profile ID is the actual persisted save operation UUID. Its revision is the positive **integer** configuration CAS; measurement configuration/policy strings are different fields. Native save must atomically persist the real operation, settings and snapshot before exposing that reference. A new explicit Meta save advances its configuration CAS and campaign review revision; the snapshot carries the resulting root revision. A replay advances neither. Draft metadata receipts don't require fabricated prepared versions or operational channel rows.
1633
+
1634
+ `resonanceMetaConfigurationDigestInput` omits only its self digest and preserves all original material, including friendly labels. `projectResonanceMetaConfiguration(snapshot, currentMetadata)` returns `{view, review}`. Metadata contains `currentCampaignRevision`, native-owner-derived `currentDefinitionDigest`, `observedAt`, nullable `expiresAt`, `reasonCodes` and `pendingRequirements`. `readyForReview` is derived output: no blockers, a current root revision at least as new as the saved audit revision, an exact match between the current semantic definition digest and the saved reviewed definition digest, and a nonexpired observation horizon. Metadata-only root revision bumps can therefore preserve multiple unchanged channel configurations; original snapshots keep their real save revisions. Native owners must still verify the exact original channel, configuration CAS, saved operation, configuration digest and current source/resource/account/policy facts. A matching campaign digest never substitutes for those checks. The review is the unchanged original snapshot when those prerequisites hold, otherwise `null`. Pending native creation, validation or age observation never grants execution. Pure timestamp ordering doesn't prove freshness when a cached view is consumed; the actual owner and UI must withdraw stale reviewability.
1635
+
1636
+ ### Explicit feed selection and original review
1637
+
1638
+ `parseResonanceMandateDraftRequest` preserves the existing `{expectedRevision, allowedOperations, expiresAt}` request and accepts an optional minimal selection:
1639
+
1640
+ ```ts
1641
+ websiteVisitFeedSelection: {
1642
+ channels: [{ channelId, expectedConfigurationRevision, resourceRuleRefs: [{ id, revision }] }]
1643
+ }
1644
+ ```
1645
+
1646
+ Absent selection preserves no-feed behavior. Empty lists, duplicate selectors, full editable grants and copied destination/profile/readiness fields are rejected. The native owner resolves the exact saved configuration, profile receipt and positive rule versions through the existing mandate authority. An excluded-only page can't become a selected feed permission.
1647
+
1648
+ The existing mandate-draft response remains the raw `ResonanceMandateApprovalPayload`. Before acceptance, reviewers use that original payload with exact immutable configuration review snapshots; mismatched refs, digests, revisions or plan material block review. Latest labels must not replace original reviewed labels. Actual native approval can use the existing legitimate member or invited delegated-agent authority.
1649
+
1650
+ `ResonanceWebsiteVisitFeedReview` is a separate **post-acceptance** projection: `{schemaVersion: 1, approval, mandateRef, configurations, current}`. It requires a genuine nonnull accepted mandate reference. Before acceptance, the native read returns its typed unavailable/not-found result. Original historical snapshots remain readable under current authorized scope when current state is invalidated or unavailable. `eligible` describes current review observation and grants no execution authority. No-feed requires `not_enabled` and an empty configuration list. The saved configuration audit revision can precede the exact original approval/plan revision, but can never follow it. The optional original prepared-plan context checks exact approval/plan revision, matching channel material and definition digest. Native original reads must supply the actual stored plan and verify the selected original configuration identities. Preparation, approval, claim and acceptance still require the exact current native root revision; this configuration review rule does not relax those fences. Actual approval provenance, hashes, source facts, consent and admission remain native checks.
1651
+
1652
+ Native owners plan separate original configuration and accepted feed-review reads under the existing protected configuration/mandate owners. This package adds no endpoint, approval surface or provider client. Public, manual and MCP entry points must continue to reject internal `deliver_website_visit` before filing; a parser or service label never proves protected origin.
1653
+
1654
+ ### Provider-managed age intent
1655
+
1656
+ The additional closed original Meta intent is `{mode: 'provider_managed'}`. It accepts no bounds, default flag or observed native values and never replaces absent, `omitted` or `bounded` intent. Its review promise is: “Use Meta age settings; record the initial observed configuration before activation.”
1657
+
1658
+ Native create and validation requests must omit both age keys. Before activation, the first genuine same-root PAUSED AdSet creator receipt and complete scoped read must seal initial age values **and key presence** once in the existing protected operation. Activation must compare that unchanged observation and every independent non-age, consent, authority and budget gate. Later changes block. This intent makes no claim about exclusive default authorship, unlimited ages, legality or serving. Existing three-mode consumers need explicit preservation, editing and review support before adopting this branch.
1659
+
1660
+
1661
+ ### Reported-cost SQL clock candidate
1662
+
1663
+ The explicit `reported_cpql_conserved_transfer_v1` policy requires `costBasis: 'provider_reported_snapshot_v1'`, `costRevisionRisk: 'accepted_provisional'`, `readClockKind: 'sql_before_provider_read_lower_bound_v1'` and the existing observational allocation thresholds. This is the sole reported-cost policy in this candidate. Earlier unpublished no-clock draft policy/evidence is rejected. Existing mature, finite and default profiles keep their meanings. Adoption requires compatible consumers and this exact policy in the original prepared plan, review and accepted mandate; parsing never grants authority.
1664
+
1665
+ The evidence discriminator is `reported_cpql_sql_clock_v1`. It retains allocation/channel fields, replacing the legacy uncertaintySource with two required closed objects:
1666
+
1667
+ - `channelReportedCost`: basis, protected immutable observationId, sourceEvidenceDigest, reportedSpend, exact queriedFrom/queriedThrough, actual firstReceivedAt/receivedAt, native recordedAt, required readClock, providerFinality unknown and correctionsPossible true.
1668
+ - `outcomeSource`: method `observational_cpql_missing_outcome_bound_v1`, eligibleContacts, fullyResolvedContacts, qualifiedContacts, native sourceRevision, original qualificationRuleRef and universeComplete true.
1669
+
1670
+ The exact readClock is `{kind: 'sql_before_provider_read_lower_bound_v1', notBeforeAt}`. The trusted native producer must await the actual scoped SQL reply before any provider HTTP and bind its unaltered returned lower bound to the same run, target, query and protected immutable source receipt. Caller-supplied, post-read, cached or rebound clocks are invalid. A SQL-generated conservative millisecond lower bound remains a lower bound, never exact HTTP time. The readClock field preserves the actual returned UTC string in evidence/digests, accepting Z or +00:00 with up to six fractional digits; ordinary legacy wire instant formats are unchanged.
1671
+
1672
+ Operational completion, age and decision expiry use SQL chronology: windowEnd <= notBeforeAt <= recordedAt <= observedAt. Raw first/final HTTP receipts remain finite and ordered within their own clock, without numeric comparisons to SQL. Millisecond arithmetic floors any finer native precision conservatively. The native SQL owner must enforce exact retained chronology and current freshness at final claim and every dispatch, together with original mandate/flight limits, actor, kill revision, source and funding guards.
1673
+
1674
+ Keep one exact nonfinal provider spend observation and independent first-party qualified_goals, genuine CRM coverage and channel maturity. Common query windows require completed advertiser-local days with zero milliseconds. Equivalent UTC timestamp representations compare as instants. Query coverage never sets global/channel/provider dataThrough, verifiedSpend or spendPeriodComplete. Passing the actual prepared plan also checks its exact policy/objective, channel/account/site/timezone and frozen qualified cohort.
1675
+
1676
+ `reportedCpqlMissingOutcomeBound` shares the integer outcome sensitivity arithmetic, conditional on reportedSpend. It does not bound cost corrections, establish financial finality, prove causal lift or guarantee cost ordering. Zero cost or no qualified contacts leaves it unavailable. Existing canonical digest functions bind clock kind, immutable cost and independent outcome provenance. Decisions retain observational_allocation/reduce_then_increase, include cost observation IDs and qualification source revisions, and expire by the conservative SQL anchor deadline.
1677
+
1678
+ No new approval surface or engine is introduced. Native budget actions retain their supported original graph and period restrictions. Reported cost releases no donor hold or recipient funding; genuine incremental headroom above reserve remains required. Unknown donor effect stops recipient execution, unsupported funding stays unavailable, and corrections create new immutable history. Parser/schema/source checks cannot authenticate a provider exchange, prove native run binding, grant an action or replace those native checks. This source candidate has no compiled package while the shared build resource is reserved.
1679
+
1680
+
1681
+ ### Public observation pages
1682
+
1683
+ `parseResonanceObservationsPage` reads the existing `{items, nextCursor, observedAt, support}` envelope. Each public item adds four flat native identities to the existing metric: observationId, channelId, versionId and accountBindingId. `parseResonancePublicObservationMetric` extracts those identities and validates the remaining closed metric through the unchanged generic parser. `parseResonanceObservationSupport` validates the closed support union; the page parser then checks cross-object alignment. Matching TypeScript types and JSON schemas are exported from the same Resonance entry. Structural schemas alone do not enforce all semantic relationships.
1684
+
1685
+ Every item has exactly one support entry at the same index, matching all four identities, source, account currency where present, asOf/fetchedAt and dataThrough meaning. A native provider observation may yield spend, impressions and clicks with the same row ID and repeated support; the unique key is observationId plus metric name. Genuine first-party qualified outcomes retain their native row identity and independent qualification sourceRef. Never derive observation identity from that qualification revision or insert contact counts as exposure counts.
1686
+
1687
+ Provider support requires explicit nullable firstReceivedAt, receivedAt, recordedAt and readClock, plus providerFinality unknown, correctionsPossible true and coverageBasis closed_query_snapshot or not_established. Missing required flags fail parsing. First-party support forbids those provider-only fields. A complete closed query remains revisable and does not establish financial finality. Individual clicks or impressions may still be unknown even when row-level query coverage is complete; their value stays null and their metric reason remains separate from the support reason. Legacy/unestablished reporting stays explicit and supplies no operational freshness authority. Raw first/final HTTP timestamps are compared only within their own clock; native readClock bytes retain the final SQL-clock format without restamping.
1688
+
1689
+ Pagination follows native-row UUID order, with at most 100 native rows and 300 expanded metrics per page. A non-null cursor references the last native row, never a metric offset. To display the latest snapshot, group by channel, exact window and metric, then compare support.fetchedAt, which must equal item.asOf as an instant. Do not sum repeated snapshots, turn unknown into zero or infer finality from coverage. The parser preserves reporting data; native API scope, protected producer lineage, original authority, current freshness and funding remain separate requirements.
1690
+
1691
+
1692
+ ### Original read-only provider reporting grant
1693
+
1694
+ The existing mandate draft request accepts optional `providerReporting: {agentContactId, channelIds}`. This closed selector contains only the selected invited agent and explicit channels. It rejects purpose, organization, project, principal and approval fields. Absence stays omitted; null and the superseded Selection-suffix field are invalid. The server must derive the actual organization, project and current invited-agent acts-for principal, never a default agent or the reviewer identity.
1695
+
1696
+ The resolved original mandate has optional `providerReporting: {purpose: 'provider_reporting_refresh', orgId, projectId, agentContactId, principalContactId, channelIds}`. All six fields are required when present. Channels are a unique nonempty UUID list, maximum 100; agent and human principal remain distinct. The grant project must equal the parent mandate project. The original mandate, review payload and canonical digest include the exact resolved binding. No field is backfilled into old mandates and their absent-field digest bytes stay unchanged.
1697
+
1698
+ `ResonanceProviderReportingSelection` and `ResonanceProviderReportingGrant` have separate parser/schema exports. Existing mandate request/scope/approval parsers remain the entry points. Passing the actual prepared plan as the optional second argument to `parseResonanceMandateScope` also checks original plan/review/goal/flight identity and the selected paid channels within mandate sites/accounts and expiry. A public prepared plan has no organization field: exact parent organization equality and real current identities must be established by the protected native owner, not inferred from a project string or parser result.
1699
+
1700
+ This purpose permits read-only report collection and persistence only. It adds no operation, budget mutation, optimization approval, send or child authority. Observation queries must stay within the actual original flight/policy bounds and current native authority. Adding or changing an agent/principal/scope/channel binding requires actual person review through the existing mandate surface; budget-only dominance cannot admit it. The service executor, invited agent and human authorizer remain distinct native actors.
1701
+
1702
+ The existing review surface should display actual named agent, principal and selected scope from the native API projection. Parsing UUIDs is not proof of membership, an invitation, a token, a live acts-for relation or an accepted job claim. Native owners must verify the exact accepted parent grant, organization/project, current job/own claim, actor/principal, kill revision, policy/window, expiry and protected read/write admission before HTTP and persistence. Old mandates without this grant have no scheduled reporting authority. No new approval surface, grant store or bearer retrieval is introduced.
1703
+
1704
+ Observed provider values require complete closed-query support. This is one-way: individual metrics may remain unknown when native query coverage is complete; legacy unknown/null reporting remains readable. It grants no finality, freshness or native authority.