@greatwait/contracts 0.1.0-alpha.4 → 0.1.0-alpha.6

package/dist/operational-config.js

@@ -0,0 +1,341 @@
+/**
+ * The single numeric owner for deployment-governed timer, timeout and retry
+ * configuration. Values preserve the accepted policy and measured W9 timing
+ * budgets; this leaf imports no schemas, application code or database runtime.
+ * Change through a reviewed deployment. Retrying a callback, funding operation
+ * or idempotency receipt is a public correctness promise, so organizations may
+ * not override these values. Original owner modules keep compatible exports.
+ */
+export const OPERATIONAL_TIMING = Object.freeze({
+    projectBillingConflictRetryCount: 4,
+    projectBillingConflictRetryBaseMs: 250,
+    billingNoticeBackoffBaseMs: 60_000,
+    automaticFundingBackoffBaseMs: 60_000,
+    controlPlaneBackoffBaseMs: 10,
+    postgresConnectionAcquisitionMs: 2_900,
+    postgresLockMs: 2_000,
+    postgresStatementMs: 2_900,
+    postgresTransactionBudgetMs: 2_900,
+    postgresTransactionMaximumMs: 2_999,
+    apiMutationStatementMs: 5_000,
+    apiMutationBudgetMs: 5_000,
+    apiMutationMaximumMs: 5_000,
+    controlPlaneWriteStatementMs: 5_000,
+    controlPlaneWriteBudgetMs: 5_000,
+    dispatchHedgeAfterMs: 400,
+    dispatchHedgeThirdLegMs: 1_200,
+    apiHedgeAfterMs: 300,
+    authorizationReplayDelaysMs: Object.freeze([500, 1_500, 4_000]),
+    claimProbeCount: 3,
+    claimReclaimCount: 3,
+    claimReclaimWindowMs: 1_200,
+    controlPlaneBackoffCeilingMs: 200,
+    controlPlaneConnectMs: 5_000,
+    conclusionReplayDelaysMs: Object.freeze([250, 1_000, 2_000, 4_000]),
+    hostFullRetryMs: 1_000,
+    deliveryRetryBaseMs: Object.freeze([2_000, 5_000, 15_000, 60_000]),
+    deliveryRetryAfterMaximumMs: 3_600_000,
+    wakeReceiptRetryMs: 5_000,
+    wakeReceiptRecoveryLifetimeMs: 9 * 60_000,
+    repairOverdueGraceSeconds: 10,
+    admissionWindowMs: 1_000,
+    admissionLookaheadMs: 60_000,
+    admissionHedgeAfterMs: 250,
+    admissionRpcBudgetMs: 2_999,
+    unreachableRetryMs: 5_000,
+    heldResponseStepMarginMs: 20_000,
+    sendLeaseMarginSeconds: 12,
+    sendSettlementReserveMs: 7_000,
+    exhaustedClaimRetryMs: 250,
+    retentionCadenceMs: 60 * 60 * 1_000,
+    retentionBacklogCadenceMs: 60 * 1_000,
+    retentionRetryHandoffCount: 5,
+    timerSignalRetryDelaysMs: Object.freeze([250, 1_000]),
+    dispatchWarmHorizonMs: 10_000,
+    sdkAutoRetryCount: 3,
+    sdkAutoRetryBaseMs: 250,
+    sdkAutoRetryMaximumWaitMs: 30_000,
+    callbackMiddlewareLeaseMs: 30_000,
+    automaticFundingSuccessCooldownMs: 15 * 60 * 1_000,
+    automaticFundingClaimLeaseMs: 60 * 1_000,
+    automaticFundingBackoffMaximumMs: 60 * 60 * 1_000,
+    providerCreateFenceMs: 23 * 60 * 60 * 1_000,
+    fundingUnresolvedAfterMs: 15 * 60 * 1_000,
+    fundingRepairMs: 60 * 1_000,
+    fundingActionRequiredRepairMs: 5 * 60 * 1_000,
+    fundingDisputeRepairMs: 5 * 60 * 1_000,
+    billingNoticeBackoffMaximumMs: 86_400_000,
+    billingNoticeClaimMaximumMs: 5 * 60_000,
+    billingNoticeRetryMaximumMs: 60 * 60_000,
+    billingNoticeCatchUpRetryCount: 5,
+    billingNoticeClaimSeconds: 2 * 60,
+    fundingDiscoveryClaimMs: 2 * 60 * 1_000,
+    fundingDiscoveryRetryMaximumMs: 24 * 60 * 60 * 1_000,
+    fundingDiscoveryClaimMaximumMs: 5 * 60 * 1_000,
+    fundingAbandonedAfterMs: 60 * 60 * 1000,
+    checkoutDiscoverySkewSeconds: 60,
+    checkoutDiscoveryWindowSeconds: 23 * 60 * 60,
+    fundingQuoteLifetimeMs: 5 * 60_000,
+    automaticFundingPreviewLifetimeMs: 5 * 60_000,
+    testSinkRefreshMs: 3_000,
+    payloadLintDelayMs: 250,
+    payloadParseBudgetMs: 50,
+    dashboardQueryStaleMs: 30_000,
+    forecastRefreshFloorMs: 30_000,
+    forecastRefreshMaximumMs: 300_000,
+    forecastCoverageSlackMs: 120_000,
+});
+export const OPERATIONAL_TIMING_ENFORCEMENT = Object.freeze({
+    forecastRefreshFloorMs: [
+        "packages/contracts/src/forecast.ts#OPERATIONAL_TIMING.forecastRefreshFloorMs",
+        "packages/scheduling/src/partition-forecast.ts#OPERATIONAL_TIMING.forecastRefreshFloorMs",
+    ],
+    forecastRefreshMaximumMs: [
+        "packages/contracts/src/forecast.ts#OPERATIONAL_TIMING.forecastRefreshMaximumMs",
+        "packages/scheduling/src/partition-forecast.ts#OPERATIONAL_TIMING.forecastRefreshMaximumMs",
+    ],
+    forecastCoverageSlackMs: [
+        "packages/contracts/src/forecast.ts#OPERATIONAL_TIMING.forecastCoverageSlackMs",
+        "packages/scheduling/src/partition-forecast.ts#OPERATIONAL_TIMING.forecastCoverageSlackMs",
+    ],
+    postgresConnectionAcquisitionMs: [
+        "packages/postgres-scheduling/src/postgres-timeouts.ts#DEFAULT_CONNECTION_ACQUISITION_TIMEOUT_MS",
+    ],
+    postgresLockMs: [
+        "packages/postgres-scheduling/src/postgres-timeouts.ts#DEFAULT_LOCK_TIMEOUT_MS",
+    ],
+    postgresStatementMs: [
+        "packages/postgres-scheduling/src/postgres-timeouts.ts#DEFAULT_STATEMENT_TIMEOUT_MS",
+    ],
+    postgresTransactionBudgetMs: [
+        "packages/postgres-scheduling/src/postgres-timeouts.ts#DEFAULT_TRANSACTION_BUDGET_MS",
+    ],
+    postgresTransactionMaximumMs: [
+        "packages/postgres-scheduling/src/postgres-timeouts.ts#MAX_TRANSACTION_BUDGET_MS",
+    ],
+    apiMutationStatementMs: [
+        "packages/postgres-scheduling/src/postgres-timeouts.ts#DEFAULT_MUTATION_STATEMENT_TIMEOUT_MS",
+    ],
+    apiMutationBudgetMs: [
+        "packages/postgres-scheduling/src/postgres-timeouts.ts#DEFAULT_MUTATION_TRANSACTION_BUDGET_MS",
+    ],
+    apiMutationMaximumMs: [
+        "packages/postgres-scheduling/src/postgres-timeouts.ts#MAX_MUTATION_TRANSACTION_BUDGET_MS",
+    ],
+    controlPlaneWriteStatementMs: [
+        "packages/postgres-scheduling/src/postgres-timeouts.ts#CONTROL_PLANE_WRITE_STATEMENT_TIMEOUT_MS",
+    ],
+    controlPlaneWriteBudgetMs: [
+        "packages/postgres-scheduling/src/postgres-timeouts.ts#CONTROL_PLANE_WRITE_BUDGET_MS",
+    ],
+    dispatchHedgeAfterMs: [
+        "packages/postgres-scheduling/src/postgres-timeouts.ts#DISPATCH_HEDGE_AFTER_MS",
+    ],
+    dispatchHedgeThirdLegMs: [
+        "packages/postgres-scheduling/src/postgres-timeouts.ts#DISPATCH_HEDGE_THIRD_LEG_MS",
+    ],
+    apiHedgeAfterMs: [
+        "packages/postgres-scheduling/src/postgres-timeouts.ts#API_HEDGE_AFTER_MS",
+    ],
+    authorizationReplayDelaysMs: [
+        "packages/postgres-scheduling/src/postgres-timeouts.ts#AUTHORIZATION_REPLAY_DELAYS_MS",
+    ],
+    claimProbeCount: [
+        "packages/postgres-scheduling/src/postgres-timeouts.ts#CLAIM_PROBE_ATTEMPTS",
+    ],
+    claimReclaimCount: [
+        "packages/postgres-scheduling/src/postgres-timeouts.ts#CLAIM_RECLAIM_LIMIT",
+    ],
+    claimReclaimWindowMs: [
+        "packages/postgres-scheduling/src/postgres-timeouts.ts#CLAIM_RECLAIM_WINDOW_MS",
+    ],
+    controlPlaneBackoffCeilingMs: [
+        "packages/postgres-scheduling/src/control-plane-database.ts#CONTROL_PLANE_BACKOFF_CEILING_MS",
+    ],
+    controlPlaneConnectMs: [
+        "packages/postgres-scheduling/src/control-plane-database.ts#CONTROL_PLANE_CONNECT_TIMEOUT_MS",
+    ],
+    conclusionReplayDelaysMs: [
+        "packages/application/src/dialer.ts#DEFAULT_CONCLUSION_RETRY_DELAYS_MS",
+    ],
+    hostFullRetryMs: [
+        "packages/application/src/dialer.ts#DEFAULT_HOST_FULL_RETRY_MS",
+        "packages/postgres-scheduling/src/postgres-repository.ts#CLAIM_SEND_HOST_FULL_RETRY_MS",
+    ],
+    deliveryRetryBaseMs: [
+        "packages/application/src/schedule-series.ts#RETRY_BASE_MS",
+    ],
+    deliveryRetryAfterMaximumMs: [
+        "packages/application/src/schedule-series.ts#MAX_RETRY_AFTER_MS",
+    ],
+    wakeReceiptRetryMs: [
+        "packages/application/src/timer-bucket.ts#WAKE_RECEIPT_RETRY_MS",
+    ],
+    wakeReceiptRecoveryLifetimeMs: [
+        "packages/application/src/timer-bucket.ts#WAKE_RECEIPT_RECOVERY_LIFETIME_MS",
+    ],
+    repairOverdueGraceSeconds: [
+        "packages/application/src/timer-bucket-repair.ts#REPAIR_OVERDUE_GRACE_SECONDS",
+    ],
+    admissionWindowMs: [
+        "packages/application/src/admission-window.ts#ADMISSION_WINDOW_MS",
+    ],
+    admissionLookaheadMs: [
+        "packages/application/src/admission-window.ts#ADMISSION_WINDOW_MAX_LOOKAHEAD_MS",
+    ],
+    admissionHedgeAfterMs: [
+        "packages/delivery-runtime/src/admission-hedge.ts#ADMISSION_HEDGE_AFTER_MS",
+    ],
+    admissionRpcBudgetMs: [
+        "packages/delivery-runtime/src/admission-hedge.ts#ADMISSION_RPC_BUDGET_MS",
+    ],
+    unreachableRetryMs: [
+        "packages/delivery-runtime/src/dispatch-admission.ts#UNREACHABLE_RETRY_MS",
+    ],
+    heldResponseStepMarginMs: [
+        "packages/delivery-runtime/src/held-response-carrier.ts#HELD_RESPONSE_STEP_MARGIN_MS",
+    ],
+    sendLeaseMarginSeconds: [
+        "packages/delivery-runtime/src/held-response-carrier.ts#SEND_LEASE_MARGIN_SECONDS",
+    ],
+    sendSettlementReserveMs: [
+        "packages/delivery-runtime/src/held-response-carrier.ts#SEND_SETTLEMENT_RESERVE_MS",
+    ],
+    exhaustedClaimRetryMs: [
+        "packages/timer-bucket/src/durable-object.ts#EXHAUSTED_CLAIM_RETRY_MS",
+    ],
+    retentionCadenceMs: [
+        "packages/retention-worker/src/worker.ts#RETENTION_CADENCE_MS",
+    ],
+    retentionBacklogCadenceMs: [
+        "packages/retention-worker/src/worker.ts#RETENTION_BACKLOG_CADENCE_MS",
+    ],
+    retentionRetryHandoffCount: [
+        "packages/retention-worker/src/worker.ts#RETENTION_RETRY_HANDOFF_COUNT",
+    ],
+    timerSignalRetryDelaysMs: [
+        "apps/api/src/detached-signal.ts#TIMER_SIGNAL_RETRY_DELAYS_MS",
+    ],
+    dispatchWarmHorizonMs: ["apps/api/src/worker.ts#DISPATCH_WARM_HORIZON_MS"],
+    sdkAutoRetryCount: ["packages/api-client/src/client.ts#SDK_AUTO_RETRY_LIMIT"],
+    sdkAutoRetryBaseMs: [
+        "packages/api-client/src/client.ts#SDK_AUTO_RETRY_BASE_DELAY_MS",
+    ],
+    sdkAutoRetryMaximumWaitMs: [
+        "packages/api-client/src/client.ts#SDK_AUTO_RETRY_MAX_WAIT_MS",
+    ],
+    callbackMiddlewareLeaseMs: [
+        "packages/api-client/src/callback-middleware.ts#DEFAULT_LEASE_MS",
+    ],
+    automaticFundingSuccessCooldownMs: [
+        "packages/postgres-scheduling/src/automatic-funding.ts#AUTOMATIC_FUNDING_SUCCESS_COOLDOWN_MS",
+    ],
+    automaticFundingClaimLeaseMs: [
+        "packages/postgres-scheduling/src/automatic-funding.ts#CLAIM_LEASE_MS",
+    ],
+    automaticFundingBackoffMaximumMs: [
+        "packages/postgres-scheduling/src/automatic-funding.ts#MAX_BACKOFF_MS",
+    ],
+    providerCreateFenceMs: [
+        "packages/postgres-scheduling/src/automatic-funding.ts#PROVIDER_CREATE_FENCE_MS",
+        "packages/application/src/execution-funding-provider.ts#EXECUTION_FUNDING_CREATE_FENCE_MS",
+        "apps/api/src/billing/stripe-provider.ts#MAXIMUM_CREATE_AGE_MS",
+    ],
+    fundingUnresolvedAfterMs: [
+        "packages/postgres-scheduling/src/funding.ts#FIFTEEN_MINUTES_MS",
+        "packages/application/src/execution-funding-provider.ts#EXECUTION_FUNDING_UNRESOLVED_AFTER_MS",
+    ],
+    fundingRepairMs: [
+        "packages/postgres-scheduling/src/funding.ts#REPAIR_DELAY_MS",
+    ],
+    fundingActionRequiredRepairMs: [
+        "packages/postgres-scheduling/src/funding.ts#ACTION_REQUIRED_REPAIR_DELAY_MS",
+    ],
+    fundingDisputeRepairMs: [
+        "packages/postgres-scheduling/src/funding.ts#DISPUTE_REPAIR_DELAY_MS",
+    ],
+    billingNoticeBackoffMaximumMs: [
+        "packages/postgres-scheduling/src/billing-notifications.ts#MAX_BACKOFF_MS",
+    ],
+    billingNoticeClaimMaximumMs: [
+        "apps/api/src/billing/billing-notification-store.ts#MAX_CLAIM_MS",
+    ],
+    billingNoticeRetryMaximumMs: [
+        "apps/api/src/billing/billing-notification-store.ts#MAX_RETRY_MS",
+    ],
+    billingNoticeCatchUpRetryCount: [
+        "apps/api/src/billing/billing-notice-catch-up.ts#RETRY_LIMIT",
+    ],
+    billingNoticeClaimSeconds: [
+        "apps/api/src/billing/billing-notification-runtime.ts#CLAIM_SECONDS",
+    ],
+    fundingDiscoveryClaimMs: [
+        "apps/api/src/billing/execution-funding-runtime.ts#DISCOVERY_CLAIM_MS",
+    ],
+    fundingDiscoveryRetryMaximumMs: [
+        "apps/api/src/billing/execution-funding-runtime.ts#DISCOVERY_MAX_RETRY_MS",
+        "apps/api/src/billing/execution-funding-store.ts#MAX_DISCOVERY_RETRY_MS",
+    ],
+    fundingDiscoveryClaimMaximumMs: [
+        "apps/api/src/billing/execution-funding-store.ts#MAX_DISCOVERY_CLAIM_MS",
+    ],
+    fundingAbandonedAfterMs: [
+        "packages/application/src/execution-funding-provider.ts#EXECUTION_FUNDING_ABANDONED_AFTER_MS",
+    ],
+    checkoutDiscoverySkewSeconds: [
+        "apps/api/src/billing/stripe-provider.ts#CHECKOUT_DISCOVERY_SKEW_SECONDS",
+        "apps/api/src/billing/stripe-execution-funding.ts#CHECKOUT_DISCOVERY_SKEW_SECONDS",
+    ],
+    checkoutDiscoveryWindowSeconds: [
+        "apps/api/src/billing/stripe-provider.ts#CHECKOUT_DISCOVERY_WINDOW_SECONDS",
+        "apps/api/src/billing/stripe-execution-funding.ts#CHECKOUT_DISCOVERY_WINDOW_SECONDS",
+    ],
+    fundingQuoteLifetimeMs: [
+        "packages/application/src/execution-funding.ts#QUOTE_LIFETIME_MS",
+    ],
+    automaticFundingPreviewLifetimeMs: [
+        "packages/application/src/automatic-funding.ts#PREVIEW_LIFETIME_MS",
+    ],
+    testSinkRefreshMs: [
+        "apps/dashboard/src/sink-surfaces.tsx#DELIVERIES_REFRESH_MS",
+    ],
+    payloadLintDelayMs: ["apps/dashboard/src/payload-editor.tsx#LINT_DELAY_MS"],
+    payloadParseBudgetMs: [
+        "apps/dashboard/src/payload-editor.tsx#PARSE_BUDGET_MS",
+    ],
+    dashboardQueryStaleMs: [
+        "apps/dashboard/src/main.tsx#STALE_MS",
+        "apps/dashboard/src/schedule-editor.tsx#OPERATIONAL_TIMING.dashboardQueryStaleMs",
+    ],
+    controlPlaneBackoffBaseMs: [
+        "packages/postgres-scheduling/src/control-plane-database.ts#OPERATIONAL_TIMING.controlPlaneBackoffBaseMs",
+    ],
+    automaticFundingBackoffBaseMs: [
+        "packages/postgres-scheduling/src/automatic-funding.ts#OPERATIONAL_TIMING.automaticFundingBackoffBaseMs",
+    ],
+    billingNoticeBackoffBaseMs: [
+        "packages/postgres-scheduling/src/billing-notifications.ts#OPERATIONAL_TIMING.billingNoticeBackoffBaseMs",
+    ],
+    projectBillingConflictRetryBaseMs: [
+        "packages/application/src/project-billing.ts#OPERATIONAL_TIMING.projectBillingConflictRetryBaseMs",
+    ],
+    projectBillingConflictRetryCount: [
+        "packages/application/src/project-billing.ts#OPERATIONAL_TIMING.projectBillingConflictRetryCount",
+    ],
+});
+/** Catalog metadata derives its defaults from the numeric owner above. */
+export const OPERATIONAL_TIMING_CATALOG = Object.freeze(Object.keys(OPERATIONAL_TIMING).map((key) => Object.freeze({
+    key: `operational.${key}`,
+    default: OPERATIONAL_TIMING[key],
+    unit: key.endsWith("Seconds")
+        ? "seconds"
+        : key.endsWith("Count")
+            ? "count"
+            : "milliseconds",
+    scope: "deployment",
+    permittedLayers: ["deployment"],
+    visibility: "operator",
+    changeProcedure: "Reviewed deployment; preserve callback, retry, funding and receipt compatibility",
+    rationale: "Retain the existing measured or copied operating policy; the enforcement owner documents its evidence",
+    enforcement: OPERATIONAL_TIMING_ENFORCEMENT[key],
+})));