@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/CHANGELOG.md +46 -0
- package/README.md +557 -1
- package/dist/broadcast-layouts.d.ts +8 -0
- package/dist/broadcast-layouts.js +4 -0
- package/dist/broadcast-layouts.mjs +3 -1
- package/dist/funnels.d.ts +83 -0
- package/dist/funnels.js +66 -6
- package/dist/funnels.mjs +62 -7
- package/dist/outreach.js +45 -1
- package/dist/outreach.mjs +45 -1
- package/dist/resonance-constants.d.ts +4 -0
- package/dist/resonance-constants.js +10 -0
- package/dist/resonance-constants.mjs +6 -0
- package/dist/resonance.d.ts +8054 -0
- package/dist/resonance.js +2014 -0
- package/dist/resonance.mjs +1844 -0
- package/dist/signal-experiments.d.ts +219 -0
- package/dist/signal-experiments.js +270 -0
- package/dist/signal-experiments.mjs +260 -0
- package/dist/wire-schema.d.ts +36 -0
- package/docs.json +21 -0
- package/package.json +19 -3
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` |
|
|
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.
|