← Files Aholo Lux3DARCHIVED FILE
skills/lux3d/core/contracts/lux3d-commerce.v1.json
11.7 KB · Oct 4, 2026 · 12:33 UTC
{
"contractId": "lux3d-commerce/v1",
"module": "M03",
"status": "plugin-openapi-implementation",
"specBaseline": {
"pageId": "81521733922",
"pageVersion": 23,
"documentVersion": "V0.22",
"reviewedOn": "2026-09-08"
},
"generationContractRef": "lux3d-generation/v1",
"clientSources": {
"meaning": "The ecosystem client that initiated the request.",
"valueOwner": "ecosystems-release-unit",
"requestInjection": "fixed-by-ecosystem-adapter-and-materialized-during-dist-build",
"userOrModelOverrideAllowed": false,
"values": [
{
"code": 1,
"name": "codex",
"releaseUnit": "ecosystems/codex"
},
{
"code": 2,
"name": "claude-code",
"releaseUnit": "ecosystems/claude-code"
},
{
"code": 3,
"name": "deepseek",
"releaseUnit": "ecosystems/deepseek"
}
]
},
"commerceSource": {
"value": "lux_3d",
"meaning": "The fixed Site Service commerce/account lookup source; it is independent from numeric clientSource."
},
"publicSurface": {
"owner": "aholo-openapi",
"status": "routes-confirmed",
"accountEndpoint": "/lux3d/v1/account/balance",
"quoteEndpoint": "/lux3d/v1/pricing/openapi-quotes",
"baseUrls": {
"cn": "https://api.aholo3d.cn",
"intl": "https://api.aholo3d.com/global"
},
"requestUrlComposition": "regional-base-url-plus-canonical-api-path; /global is part of the international base URL only",
"authentication": {
"header": "Authorization",
"value": "raw-api-key",
"bearerPrefixAllowed": false,
"callerSuppliedIdentityHeadersAllowed": false
},
"pluginIntegration": "shared-commerce-client-and-codex-entrypoint",
"pluginDirectSiteServiceCallAllowed": false,
"validationEvidence": "offline-contract-and-adapter-tests; user-supplied-public-success-screenshot; no-agent-live-e2e"
},
"accountContext": {
"meaning": "A real-time trusted account snapshot plus a server-issued context for one user, region, and client source.",
"requiredFields": [
"availableCredits",
"trialCountMap",
"member",
"memberType",
"snapshotAt",
"uniqueId",
"uniqueIdExpiresAt"
],
"balance": {
"recomputedOnEveryRequest": true,
"cachedWithUniqueId": false,
"unknownOrFailedLookupMayReturnZero": false
},
"uniqueId": {
"issuedBy": "lux3d-site-service-after-successful-account-authentication",
"clientGenerated": false,
"format": "^ctx_[0-9a-f]{32}$",
"boundToTrustedContext": [
"userId",
"region",
"clientSource"
],
"redis": {
"activeKey": "lux3d:{stage}:plugin:goal:active:{sourceCode}:{region}:{userId}",
"stageOwner": "server-runtime-configuration",
"regionValues": [
"cn",
"intl"
],
"valueFields": [
"uniqueId",
"userId",
"sourceCode",
"sourceName",
"region",
"issuedAt",
"expiresAt"
],
"createSemantics": "get-or-create-with-set-nx-and-fixed-ttl",
"ttlOwner": "server-configuration",
"clientExpiryField": "uniqueIdExpiresAt",
"ttlRenewedOnRead": false,
"sameActiveKeyReturnsSameUniqueIdBeforeExpiry": true,
"byIdIndexUsed": false,
"uniqueIdReverseLookupUsed": false
},
"differentClientSourceGetsDifferentUniqueId": true,
"invalidatedBy": [
"expiry",
"trusted-user-change",
"region-change",
"client-source-change"
]
},
"request": {
"method": "GET",
"sourceParameter": "query.source",
"sourceRequired": true,
"callerSuppliedUserIdAllowed": false
},
"failurePolicy": {
"redisUnavailable": {
"httpStatus": 503,
"mode": "fail-closed",
"mayIssueLocalFallbackUniqueId": false
}
},
"semantics": {
"commerceSource": "lux_3d",
"sufficientBalanceIsConfirmation": false
}
},
"quotePlan": {
"scope": "one complete normalized plan of OpenAPI invocations",
"requestEnvelope": {
"transport": "json-body",
"requiredFields": [
"source",
"uniqueId",
"items"
],
"source": {
"type": "integer",
"allowedValues": [
1,
2,
3
],
"mustMatchActiveContext": true,
"userOrModelOverrideAllowed": false
},
"additionalFieldsAllowed": false,
"customUniqueIdHeaderUsed": false,
"uniqueIdClientGenerated": false
},
"items": {
"type": "map",
"key": "numeric-string-sequence",
"keyPattern": "^[1-9][0-9]{0,5}$",
"maximumItems": 50,
"itemRequiredFields": [
"endpoint",
"parameters"
],
"itemAdditionalFieldsAllowed": false,
"endpoint": {
"pathMeaning": "region-neutral-capability-path; not a public request URL or region-prefixed HTTP path",
"requiredFields": [
"method",
"path"
],
"method": [
"POST"
],
"pathPrefix": "/lux3d/v1/",
"pathMustExclude": [
"scheme",
"host",
"query",
"fragment",
"dot-segment",
"backslash",
"repeated-slash"
],
"internationalGlobalPrefixAllowed": false,
"automaticCaseOrTrailingSlashNormalization": false
},
"parameters": {
"allowedFields": [
"pathParameters",
"queryParameters",
"body"
],
"completeNormalizedParameterObject": true,
"internalFieldType": "json-object",
"wireFieldType": "serialized-json-object-string",
"serializationBoundary": "commerce-http-adapter",
"callerSuppliedHeadersAllowed": false
}
},
"response": {
"requiredFields": [
"source",
"uniqueId",
"quoteId",
"pricingScope",
"estimatedCreditsTotal",
"details",
"quotedAt",
"expiresAt"
],
"pricingScope": "BEFORE_ACCOUNT_BENEFITS",
"details": {
"type": "map",
"key": "request-sequence",
"value": {
"type": "integer",
"minimum": 0,
"meaning": "estimatedCredits"
},
"additionalFieldsAllowed": false
},
"detailKeyMatchesRequestSequence": true,
"estimatedCreditsTotalEqualsSumOfDetails": true,
"internalFieldsForbidden": [
"method",
"path",
"endpoint",
"parameters",
"pricingBasis",
"pipelineId",
"sku",
"skuCode",
"userId"
]
},
"contextValidation": {
"lookupKeyInputs": [
"trustedUserId",
"trustedRegion",
"body.source"
],
"activeValueUniqueIdMustEqual": "body.uniqueId",
"byIdIndexUsed": false,
"uniqueIdReverseLookupUsed": false,
"sourceResolvedByUniqueId": false
},
"lifecycle": {
"uniqueIdChangedAfterBalanceRefresh": "old-quote-invalid-for-new-context-requote-required",
"requoteUses": [
"same-fixed-source",
"new-uniqueId",
"original-items"
],
"reauthorizationRequiredWhenQuoteChanges": true
},
"semantics": {
"partialQuoteAllowed": false,
"oneUnpriceableItemFailsWholeQuote": true,
"nonPositiveKnownSkuAmount": "whole-quote-error",
"allSkuPricesMissingMayReturnZero": true,
"missingSkuPrice": "server-warning-and-skip",
"duplicateSkuItems": "preserve-and-accumulate",
"failedResolutionMayReturnZero": false,
"accountSpecificFinalDebit": false,
"quoteIsConfirmation": false,
"quoteIsBalanceReservation": false
}
},
"siteServiceInternalProvider": {
"consumer": "aholo-openapi-only",
"account": {
"method": "GET",
"path": "/api/lux3d/account/balance",
"requiredParameters": [
"query.source"
],
"trustedCurrentUserRequired": true,
"trustedRegionRequired": true,
"clientSourceParameter": "query.source",
"commerceSource": "lux_3d",
"callerSuppliedUserIdAllowed": false,
"issuesUniqueIdOnSuccess": true,
"balanceRecomputedOnEveryRequest": true
},
"quote": {
"method": "POST",
"path": "/api/lux3d/pricing/openapi-quotes",
"requiredParameters": [
"body.source",
"body.uniqueId",
"body.items"
],
"sourceParameter": "body.source",
"uniqueIdParameter": "body.uniqueId",
"itemsParameter": "body.items",
"quoteIdGeneratedPerRequest": true,
"quoteIdFormat": "^quote_[0-9a-f]{32}$",
"defaultValiditySeconds": 300,
"resolution": {
"skuCompositionOwner": "ai-generate-service",
"provider": "Lux3dOpenSkuInterface",
"shadowEndpointSuffix": "/task/sku",
"requestBodyForwarding": "same-request-as-corresponding-create-endpoint",
"websiteFreeSkuOverridesApplied": false,
"steps": [
"canonical-create-endpoint-to-AGS-shadow-endpoint",
"AGS-resolves-parameter-dependent-SKU-composition",
"query-current-Aholo-original-SKU-amounts-once",
"preserve-duplicate-SKU-items-and-sum-quantity-times-amount",
"warn-and-skip-SKUs-absent-from-price-table",
"sum-each-invocation",
"sum-complete-plan"
]
},
"failurePolicy": {
"unsupportedEndpoint": "whole-quote-error",
"skuCompositionFailure": "whole-quote-error",
"missingSkuAmount": "warning-and-skip-sku",
"malformedAmount": "whole-quote-error",
"uniqueIdInvalidOrExpired": "whole-quote-error",
"sourceMismatch": "whole-quote-error",
"upstreamFailure": "whole-quote-error",
"redisUnavailable": "service-unavailable-503-fail-closed",
"fallbackEstimatedCreditsTotal": null
}
}
},
"quoteAuditRecord": {
"owner": "lux3d-site-service",
"schemaVersion": 2,
"writeMode": "asynchronous-original-request",
"bucket": "qhfpm",
"key": "lux3dPricingRecord/{sourceName}/{region}/{uniqueId}/{quoteId}.json",
"regionValues": [
"cn",
"intl"
],
"trustedPathFields": [
"sourceName",
"region",
"uniqueId",
"quoteId"
],
"requiredJsonFields": [
"schemaVersion",
"source",
"sourceName",
"region",
"userId",
"uniqueId",
"quoteId",
"requestDigest",
"status",
"receivedAt",
"quotedAt",
"expiresAt",
"pricingScope",
"request",
"result"
],
"request": {
"requiredFields": [
"source",
"uniqueId",
"items"
],
"source": "controller-request-dto-snapshot",
"preservesSerializedParameterStrings": true,
"sanitizedBeforeAsyncSubmission": false
},
"result": {
"requiredFields": [
"estimatedCreditsTotal",
"details"
],
"nullWhenQuoteFails": true
},
"sourceField": {
"type": "integer",
"allowedValues": [
1,
2,
3
]
},
"sourceNameDerivedFromValidatedSource": true,
"userIdAllowedInsideControlledJson": true,
"forbiddenValues": [
"apiKey",
"authorization"
]
},
"pluginImplementation": {
"runtime": "shared/core/runtime/commerce_client.py",
"ports": ["AccountPort", "QuotePort", "QuoteVerificationPort"],
"quoteCommandRefreshesAccountFirst": true,
"quoteVerification": "in-memory-issued-quote-bound-to-account-source-region-request-and-expiry",
"persistedQuoteIsAuthorization": false,
"credentialsPersisted": false,
"m04SubmissionGateImplementedHere": false,
"m02UniqueIdPropagation": "deferred",
"logRedaction": ["apiKey", "authorization", "completeSignedUrl", "rawSensitivePrompt"]
}
}
SHA-256: 4fcf35c1df8415252ce09a9e50a98ad434837661334bae6942632dc3dd409332