bbs.profullstack/logicsrc
1
0
Fork 0
mirror of https://github.com/profullstack/logicsrc.git synced 2026-10-01 20:33:50 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 4

Add OpenABTest draft experiment and accounting contracts (#180)

Browse source
This commit is contained in:
Anthony Ettinger 2026-09-13 02:17:35 -07:00 • committed by GitHub
parent 123ba2e39a
commit d8b3126782
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
25 changed files with 1410 additions and 12 deletions
Download patch file Download diff file Expand all files Collapse all files

22
packages/schemas/fixtures/openabtest/adjustment.json Normal file
View file

@ -0,0 +1,22 @@
{
"openabtest": "0.1-draft",
"producerId": "chovy-server",
"manifestId": "chovy-signup-discount-v1",
"manifestRevision": 1,
"participantId": "participant-opaque-7d12",
"at": "2026-09-15T12:00:00Z",
"id": "event-adjustment-42",
"kind": "adjustment",
"payload": {
"assignmentId": "assignment-42",
"variantId": "signup-10",
"conversionId": "purchase-42",
"adjustmentId": "refund-42",
"currency": "USD",
"amountMinor": -3600,
"reason": "refund",
"proofRefs": [
"refund-proof-42"
]
}
}

15
packages/schemas/fixtures/openabtest/assignment.json Normal file
View file

@ -0,0 +1,15 @@
{
"openabtest": "0.1-draft",
"producerId": "chovy-server",
"manifestId": "chovy-signup-discount-v1",
"manifestRevision": 1,
"participantId": "participant-opaque-7d12",
"at": "2026-09-15T12:00:00Z",
"id": "event-assignment-42",
"kind": "assignment",
"payload": {
"assignmentId": "assignment-42",
"variantId": "signup-10",
"cohortId": "eligible-referred-customers"
}
}

69
packages/schemas/fixtures/openabtest/chovy-manifest.json Normal file
View file

@ -0,0 +1,69 @@
{
"openabtest": "0.1-draft",
"id": "chovy-signup-discount-v1",
"revision": 1,
"name": "Chovy referred purchase discount",
"state": "draft",
"cohort": {
"id": "eligible-referred-customers",
"eligibilityRule": "Server-verified eligible referral; exclude self-referrals and invalid attribution. Every referred purchase qualifies.",
"purchaseScope": "all-referred-purchases"
},
"assignment": {
"unit": "user",
"authority": "server",
"keyVersion": "1",
"algorithm": "hmac-sha256-persisted-v1",
"persistence": "sticky"
},
"variants": [
{
"id": "signup-5",
"weight": 1,
"parameters": {
"discountBps": 500
}
},
{
"id": "signup-10",
"weight": 1,
"parameters": {
"discountBps": 1000
}
},
{
"id": "signup-20",
"weight": 1,
"parameters": {
"discountBps": 2000
}
}
],
"window": {
"startsAt": "2026-09-14T00:00:00Z",
"endsAt": "2026-10-14T00:00:00Z"
},
"metrics": {
"primary": "retained-profit-per-eligible-visitor",
"denominator": "unique-eligible-participants",
"conversion": "unique-participants-with-confirmed-purchase",
"profit": "reconciled-net-retained-profit",
"minimumEligiblePerVariant": 100,
"minimumObservationSeconds": 604800,
"winnerPolicy": "manual-review"
},
"guardrails": {
"preserveAcceptedOffers": true,
"preserveAccruedCommissions": true,
"requireReconciledCostsForPayout": true,
"onBreach": "pause-new-assignments"
},
"economics": {
"currency": "USD",
"minorUnitExponent": 2,
"unit": "agent-hour",
"listUnitPriceMinor": 40000,
"modeledUnitCostMinor": 10000,
"minimumRetainedUnitProfitMinor": 5000
}
}

26
packages/schemas/fixtures/openabtest/conversion.json Normal file
View file

@ -0,0 +1,26 @@
{
"openabtest": "0.1-draft",
"producerId": "chovy-server",
"manifestId": "chovy-signup-discount-v1",
"manifestRevision": 1,
"participantId": "participant-opaque-7d12",
"at": "2026-09-15T12:00:00Z",
"id": "event-conversion-42",
"kind": "conversion",
"payload": {
"assignmentId": "assignment-42",
"variantId": "signup-10",
"conversionId": "purchase-42",
"price": {
"offerId": "offer-42",
"acceptedAt": "2026-09-15T11:59:00Z",
"currency": "USD",
"listUnitPriceMinor": 40000,
"chargedUnitPriceMinor": 36000,
"discountBps": 1000,
"quantityMilliUnits": 1000,
"rounding": "half-up",
"totalMinor": 36000
}
}
}

14
packages/schemas/fixtures/openabtest/eligibility.json Normal file
View file

@ -0,0 +1,14 @@
{
"openabtest": "0.1-draft",
"producerId": "chovy-server",
"manifestId": "chovy-signup-discount-v1",
"manifestRevision": 1,
"participantId": "participant-opaque-7d12",
"at": "2026-09-15T12:00:00Z",
"id": "event-eligibility-42",
"kind": "eligibility",
"payload": {
"cohortId": "eligible-referred-customers",
"eligible": true
}
}

16
packages/schemas/fixtures/openabtest/exposure.json Normal file
View file

@ -0,0 +1,16 @@
{
"openabtest": "0.1-draft",
"producerId": "chovy-server",
"manifestId": "chovy-signup-discount-v1",
"manifestRevision": 1,
"participantId": "participant-opaque-7d12",
"at": "2026-09-15T12:00:00Z",
"id": "event-exposure-42",
"kind": "exposure",
"payload": {
"assignmentId": "assignment-42",
"variantId": "signup-10",
"offerId": "offer-42",
"surface": "checkout"
}
}

27
packages/schemas/fixtures/openabtest/reconciliation-pending.json Normal file
View file

@ -0,0 +1,27 @@
{
"openabtest": "0.1-draft",
"producerId": "chovy-server",
"manifestId": "chovy-signup-discount-v1",
"manifestRevision": 1,
"participantId": "participant-opaque-7d12",
"at": "2026-09-15T12:00:00Z",
"id": "event-reconciliation-pending-42",
"kind": "reconciliation",
"payload": {
"assignmentId": "assignment-42",
"variantId": "signup-10",
"conversionId": "purchase-42",
"accountingRevision": 1,
"currency": "USD",
"state": "pending",
"revenueMinor": 36000,
"refundsMinor": 0,
"actualCostMinor": null,
"feesMinor": null,
"affiliateMinor": null,
"retainedProfitMinor": null,
"minimumRetainedProfitMinor": 5000,
"payoutStatus": "withheld",
"proofRefs": []
}
}

30
packages/schemas/fixtures/openabtest/reconciliation.json Normal file
View file

@ -0,0 +1,30 @@
{
"openabtest": "0.1-draft",
"producerId": "chovy-server",
"manifestId": "chovy-signup-discount-v1",
"manifestRevision": 1,
"participantId": "participant-opaque-7d12",
"at": "2026-09-15T12:00:00Z",
"id": "event-reconciliation-42",
"kind": "reconciliation",
"payload": {
"assignmentId": "assignment-42",
"variantId": "signup-10",
"conversionId": "purchase-42",
"accountingRevision": 2,
"currency": "USD",
"state": "reconciled",
"revenueMinor": 36000,
"refundsMinor": 0,
"actualCostMinor": 10000,
"feesMinor": 1000,
"affiliateMinor": 20000,
"retainedProfitMinor": 5000,
"minimumRetainedProfitMinor": 5000,
"payoutStatus": "eligible",
"proofRefs": [
"cost-proof-42",
"fees-proof-42"
]
}
}

11
packages/schemas/package.json
View file

@ -1,7 +1,7 @@
{
"name": "@logicsrc/schemas",
"version": "0.2.0",
"description": "LogicSRC JSON schemas for tasks, agents, runs, events, plugins, the AgentAd ad standard, the OpenOntology knowledge contracts, the OpenContext context plane, the OpenCreds credential vault, OpenRental membership and rental offers, and the OpenWall messaging proposal.",
"version": "0.3.0",
"description": "LogicSRC JSON schemas for tasks, agents, runs, events, plugins, the AgentAd ad standard, the OpenOntology knowledge contracts, the OpenContext context plane, the OpenCreds credential vault, OpenRental membership and rental offers, and the OpenWall messaging proposal. Includes the OpenABTest draft experiment and event contracts.",
"license": "MIT",
"type": "module",
"repository": {
@ -26,7 +26,8 @@
"openontology",
"password-manager",
"standards",
"vault"
"vault",
"openabtest"
],
"publishConfig": {
"access": "public"
@ -92,7 +93,9 @@
"./repo": "./schemas/logicsrc-repo.schema.json",
"./run": "./schemas/logicsrc-run.schema.json",
"./social-post": "./schemas/logicsrc-social-post.schema.json",
"./task": "./schemas/logicsrc-task.schema.json"
"./task": "./schemas/logicsrc-task.schema.json",
"./openabtest-manifest": "./schemas/logicsrc-openabtest-manifest.schema.json",
"./openabtest-event": "./schemas/logicsrc-openabtest-event.schema.json"
},
"files": [
"schemas",

460
packages/schemas/schemas/logicsrc-openabtest-event.schema.json Normal file
View file

@ -0,0 +1,460 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://logicsrc.com/schemas/logicsrc-openabtest-event.schema.json",
"title": "OpenABTest authorized event (0.1 draft)",
"type": "object",
"additionalProperties": false,
"required": [
"openabtest",
"id",
"producerId",
"manifestId",
"manifestRevision",
"participantId",
"at",
"kind",
"payload"
],
"properties": {
"openabtest": {
"const": "0.1-draft"
},
"id": {
"type": "string",
"pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"
},
"producerId": {
"type": "string",
"pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"
},
"manifestId": {
"type": "string",
"pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"
},
"manifestRevision": {
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
},
"participantId": {
"type": "string",
"pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"
},
"at": {
"type": "string",
"format": "date-time"
},
"kind": {
"enum": [
"eligibility",
"assignment",
"exposure",
"conversion",
"adjustment",
"reconciliation"
]
},
"payload": {
"type": "object"
}
},
"allOf": [
{
"if": {
"properties": {
"kind": {
"const": "eligibility"
}
}
},
"then": {
"properties": {
"payload": {
"type": "object",
"additionalProperties": false,
"required": [
"cohortId",
"eligible"
],
"properties": {
"cohortId": {
"type": "string",
"pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"
},
"eligible": {
"const": true
}
}
}
}
}
},
{
"if": {
"properties": {
"kind": {
"const": "assignment"
}
}
},
"then": {
"properties": {
"payload": {
"type": "object",
"additionalProperties": false,
"required": [
"assignmentId",
"variantId",
"cohortId"
],
"properties": {
"assignmentId": {
"type": "string",
"pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"
},
"variantId": {
"type": "string",
"pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"
},
"cohortId": {
"type": "string",
"pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"
}
}
}
}
}
},
{
"if": {
"properties": {
"kind": {
"const": "exposure"
}
}
},
"then": {
"properties": {
"payload": {
"type": "object",
"additionalProperties": false,
"required": [
"assignmentId",
"variantId",
"offerId",
"surface"
],
"properties": {
"assignmentId": {
"type": "string",
"pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"
},
"variantId": {
"type": "string",
"pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"
},
"offerId": {
"type": "string",
"pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"
},
"surface": {
"type": "string",
"pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"
}
}
}
}
}
},
{
"if": {
"properties": {
"kind": {
"const": "conversion"
}
}
},
"then": {
"properties": {
"payload": {
"type": "object",
"additionalProperties": false,
"required": [
"assignmentId",
"variantId",
"conversionId",
"price"
],
"properties": {
"assignmentId": {
"type": "string",
"pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"
},
"variantId": {
"type": "string",
"pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"
},
"conversionId": {
"type": "string",
"pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"
},
"price": {
"type": "object",
"additionalProperties": false,
"required": [
"offerId",
"acceptedAt",
"currency",
"listUnitPriceMinor",
"chargedUnitPriceMinor",
"discountBps",
"quantityMilliUnits",
"rounding",
"totalMinor"
],
"properties": {
"offerId": {
"type": "string",
"pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"
},
"acceptedAt": {
"type": "string",
"format": "date-time"
},
"currency": {
"type": "string",
"pattern": "^[A-Z]{3}$"
},
"listUnitPriceMinor": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"chargedUnitPriceMinor": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"discountBps": {
"type": "integer",
"minimum": 0,
"maximum": 10000
},
"quantityMilliUnits": {
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
},
"rounding": {
"const": "half-up"
},
"totalMinor": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
}
}
}
}
}
}
},
{
"if": {
"properties": {
"kind": {
"const": "adjustment"
}
}
},
"then": {
"properties": {
"payload": {
"type": "object",
"additionalProperties": false,
"required": [
"assignmentId",
"variantId",
"conversionId",
"adjustmentId",
"currency",
"amountMinor",
"reason",
"proofRefs"
],
"properties": {
"assignmentId": {
"type": "string",
"pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"
},
"variantId": {
"type": "string",
"pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"
},
"conversionId": {
"type": "string",
"pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"
},
"adjustmentId": {
"type": "string",
"pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"
},
"currency": {
"type": "string",
"pattern": "^[A-Z]{3}$"
},
"amountMinor": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"reason": {
"enum": [
"refund",
"chargeback",
"correction"
]
},
"proofRefs": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"
},
"uniqueItems": true,
"maxItems": 100,
"minItems": 1
}
}
}
}
}
},
{
"if": {
"properties": {
"kind": {
"const": "reconciliation"
}
}
},
"then": {
"properties": {
"payload": {
"type": "object",
"additionalProperties": false,
"required": [
"assignmentId",
"variantId",
"conversionId",
"accountingRevision",
"currency",
"state",
"revenueMinor",
"refundsMinor",
"actualCostMinor",
"feesMinor",
"affiliateMinor",
"retainedProfitMinor",
"minimumRetainedProfitMinor",
"payoutStatus",
"proofRefs"
],
"properties": {
"assignmentId": {
"type": "string",
"pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"
},
"variantId": {
"type": "string",
"pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"
},
"conversionId": {
"type": "string",
"pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"
},
"accountingRevision": {
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
},
"currency": {
"type": "string",
"pattern": "^[A-Z]{3}$"
},
"state": {
"enum": [
"pending",
"reconciled"
]
},
"revenueMinor": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"refundsMinor": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"actualCostMinor": {
"type": [
"integer",
"null"
],
"minimum": 0,
"maximum": 9007199254740991
},
"feesMinor": {
"type": [
"integer",
"null"
],
"minimum": 0,
"maximum": 9007199254740991
},
"affiliateMinor": {
"type": [
"integer",
"null"
],
"minimum": 0,
"maximum": 9007199254740991
},
"retainedProfitMinor": {
"type": [
"integer",
"null"
],
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"minimumRetainedProfitMinor": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"payoutStatus": {
"enum": [
"withheld",
"eligible"
]
},
"proofRefs": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"
},
"uniqueItems": true,
"maxItems": 100
}
}
}
}
}
}
]
}

291
packages/schemas/schemas/logicsrc-openabtest-manifest.schema.json Normal file
View file

@ -0,0 +1,291 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://logicsrc.com/schemas/logicsrc-openabtest-manifest.schema.json",
"title": "OpenABTest experiment manifest (0.1 draft)",
"type": "object",
"additionalProperties": false,
"required": [
"openabtest",
"id",
"revision",
"name",
"state",
"cohort",
"assignment",
"variants",
"window",
"metrics",
"guardrails"
],
"properties": {
"openabtest": {
"const": "0.1-draft"
},
"id": {
"type": "string",
"pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"
},
"revision": {
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 1000
},
"state": {
"enum": [
"draft",
"running",
"paused",
"closed"
]
},
"cohort": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"eligibilityRule",
"purchaseScope"
],
"properties": {
"id": {
"type": "string",
"pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"
},
"eligibilityRule": {
"type": "string",
"minLength": 1,
"maxLength": 1000
},
"purchaseScope": {
"enum": [
"all-referred-purchases",
"all-eligible-purchases",
"first-eligible-purchase",
"custom"
]
}
}
},
"assignment": {
"type": "object",
"additionalProperties": false,
"required": [
"unit",
"authority",
"keyVersion",
"algorithm",
"persistence"
],
"properties": {
"unit": {
"enum": [
"user",
"account",
"session",
"device",
"custom"
]
},
"authority": {
"const": "server"
},
"keyVersion": {
"type": "string",
"pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"
},
"algorithm": {
"type": "string",
"pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"
},
"persistence": {
"const": "sticky"
}
}
},
"variants": {
"type": "array",
"minItems": 2,
"maxItems": 100,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"weight",
"parameters"
],
"properties": {
"id": {
"type": "string",
"pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"
},
"weight": {
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
},
"parameters": {
"type": "object",
"minProperties": 1,
"maxProperties": 50,
"propertyNames": {
"type": "string",
"pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"
},
"additionalProperties": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
}
]
}
}
}
}
},
"window": {
"type": "object",
"additionalProperties": false,
"required": [
"startsAt",
"endsAt"
],
"properties": {
"startsAt": {
"type": "string",
"format": "date-time"
},
"endsAt": {
"type": "string",
"format": "date-time"
}
}
},
"metrics": {
"type": "object",
"additionalProperties": false,
"required": [
"primary",
"denominator",
"conversion",
"profit",
"minimumEligiblePerVariant",
"minimumObservationSeconds",
"winnerPolicy"
],
"properties": {
"primary": {
"enum": [
"conversion-rate",
"retained-profit-per-eligible-visitor"
]
},
"denominator": {
"const": "unique-eligible-participants"
},
"conversion": {
"const": "unique-participants-with-confirmed-purchase"
},
"profit": {
"const": "reconciled-net-retained-profit"
},
"minimumEligiblePerVariant": {
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
},
"minimumObservationSeconds": {
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
},
"winnerPolicy": {
"const": "manual-review"
}
}
},
"guardrails": {
"type": "object",
"additionalProperties": false,
"required": [
"preserveAcceptedOffers",
"preserveAccruedCommissions",
"requireReconciledCostsForPayout",
"onBreach"
],
"properties": {
"preserveAcceptedOffers": {
"const": true
},
"preserveAccruedCommissions": {
"const": true
},
"requireReconciledCostsForPayout": {
"const": true
},
"onBreach": {
"const": "pause-new-assignments"
}
}
},
"economics": {
"type": "object",
"additionalProperties": false,
"required": [
"currency",
"minorUnitExponent",
"unit",
"listUnitPriceMinor",
"modeledUnitCostMinor",
"minimumRetainedUnitProfitMinor"
],
"properties": {
"currency": {
"type": "string",
"pattern": "^[A-Z]{3}$"
},
"minorUnitExponent": {
"type": "integer",
"minimum": 0,
"maximum": 6
},
"unit": {
"type": "string",
"pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"
},
"listUnitPriceMinor": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"modeledUnitCostMinor": {
"type": [
"integer",
"null"
],
"minimum": 0,
"maximum": 9007199254740991
},
"minimumRetainedUnitProfitMinor": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
}
}
}
}