lib.growth-runtime
Pure deterministic runtime for GrowthOS referral, affiliate, reward, and payout lifecycles.
@lssm-tech/lib.growth-runtimebun add @lssm-tech/lib.growth-runtimeManifest declarations describe the current workspace; they do not verify registry publication or runtime execution.
Package guide
Pure, provider-neutral GrowthOS lifecycle logic for referral and affiliate programs.
./marketing/forms owns the existing demo-request form and registry using the canonical Growth operation schemas. ./operations/marketing.handlers retains the deterministic sample catalog handlers and synthetic authenticated demo booking behavior; it does not contact a real booking service. Handler signatures use the complete canonical RuntimeCore installation types.
It selects one prioritized, non-stackable attribution winner, enforces consent and identity/organization loop boundaries, projects fixed or BillingOS commission-based rewards, applies approval, maturity, and compensating ledger transitions, builds homogeneous payout batches, validates payout readiness, and signs short-lived acquisition context. Persistence and provider SDK calls belong to integrations.
Marketing and editorial runtime
The optional ./marketing subpath adds MarketingExecutor, EditorialService, EditorialPublicationService, source-aware measurement reconciliation and review-only experiment assessment. Supply current authorization, durable CAS storage, provider, clock and ID ports. No provider effects are available by default. Concurrent workers share durable reservations and publication intents; ambiguous outcomes require reconciliation rather than blind redispatch.
Editorial record v2 (TS-01-EDCORE)
Editorial records are schemaVersion: 2. Content carries a payload discriminated over the eight MarketingContentKind values (blog and landing_page keep title, Markdown and canonical URL; LinkedIn post/message, email, X post/thread and Instagram carousel outline use their native fields), field-addressed claims, the public author, contributor profile, intended sender and recipient bindings, and a pinned briefRevision. editorialContentDigest hashes the canonical v2 form; content must already be NFC/LF-normalized. Long-form compilers read editorialLongForm; native kinds have no Markdown page.
EditorialDependencies.policy is required. Submit binds the evaluator's policy fingerprint; review, schedule, the publisher and the due runner re-evaluate it. A changed fingerprint, or an evaluator refusal once a fingerprint is bound (TS-01-EDGOV), is POLICY_CHANGED; any evaluator issue, or a refusal at submit, is NEEDS_EVIDENCE; and an unavailable evaluator is POLICY_UNAVAILABLE; none of them is treated as allowed. createEditorialPolicyEvaluator from ./marketing/editorial-policy composes the default rules from a host EditorialContextPort and EditorialAuthorPolicy.
Scheduling needs an IANA timeZone (./marketing/editorial-schedule-time) and the three publication acknowledgements; the publish time must be in the future, at most 30 days ahead, with a 15-minute window. A missed window returns the record to approved with a scheduleHold; nothing dispatches late. Reschedule, unschedule and campaign associate (./marketing/editorial-association) are revision-checked commands. All editorial operations are version 2.0.0.
growth.editorial.admit (./marketing/editorial-admission) creates a draft from selected studio candidates with a rights check. It is reachable only through the module's createEditorialAdmissionBridge, never through REST or MCP.
Editorial edits invalidate previous approvals and scheduling. Reviews bind to the exact content digest and policy fingerprint; changes_requested requires a note, and carried issues clear only on a changed revision with a resolution note. Published content requires a separate withdrawal workflow; archiving cannot silently remove a live publication.
Results and learning (TS-01-RESULTS)
./marketing/result-service (MarketingResultService) records, corrects, deletes and lists publication-bound results with provenance and blank-unknown metrics, and imports a reviewed CSV through a host-supplied parser (./marketing/result-import). ./marketing/learning-service (MarketingLearningService) reviews learning proposals into decisions with autoApply: false; an accepted decision yields one next-cycle action holding an unapplied draft brief or campaign revision (briefLearningContext). Deleting a result tombstones its dependents, then invalidates and scrubs dependent decisions and actions. Authority, stores and the CSV adapter are injected ports with refusal by default.
Marketing copy runs (TS-01-GEN)
./marketing/copy-run (MarketingCopyRunService) runs durable, fenced copy generation: admission and the policy fingerprint are checked before any provider call, a reviewed quote and a usage reservation are required, the run is stored with a fence, an attempt and a deadline (at most 60 s) before remote work, and a result is accepted only while the fence, attempt and deadline hold and a recomputed fingerprint matches. A deadline overrun fails the run with GENERATION_EXPIRED and usage unknown; retry and resume open a new attempt and fence. Accepted post drafts go through the draft validator (exact excerpts, numbers, first person, quotations), and brief.extract appends a draft brand revision without confirming it. The generator, usage, draft and store ports are injected.
Audience comments (TS-01-COMMENTS)
./marketing/audience-comment-service (MarketingAudienceCommentService) grants, revokes, recovers, collects and lists audience comments. Missing scopes give COMMENTS_REAUTHORIZATION_REQUIRED, drift gives COMMENTS_SCOPE_CHANGED, and collection admits a durable request and lease before I/O, reads one page under a 60-second deadline, re-checks authority and lease before commit, deduplicates by fingerprint, appends edited versions, refuses to restore a redacted original and persists only a safe failure code. A replayed request key never dispatches again. Visibility returns only the actor's own in-scope, unredacted originals.
Commands
bun run testbun run typecheckbun run lint:checkbun run build
MarketingConversionService reserves conversion identity before dispatch, rechecks current consent and retains uncertain outcomes for read-only reconciliation. Corrections require the accepted predecessor; retractions are terminal. Host authority governs data egress and may independently authorize a retraction after consent revocation.
MarketingObservationService authorizes refresh/read scopes, rejects substituted provider requests and persists observations. marketingObservedStateDigest excludes timestamps and evidence references while retaining scoped resource states for execution planning.
marketing/planning-approval supplies MarketingPlanningApprovalService. Inject current pricing/brand authorization, human-review verification and durable storage. The service issues the existing OperationApprovalReceipt format, bound to exact parsed input and maximum cost. Configure its verifyEvidence callback on createOperationApprovalPort with a durable nonce store; omitting evidence verification is not a supported setup. Issuance returns the persisted receipt, so concurrent calls and replay agree.
marketing/measurement-report sums explicitly requested reporting buckets after source reconciliation. It preserves campaign/creative/creator, currency, timezone and attribution dimensions; missing, partial, stale or future observations keep totals unavailable. Overlapping periods and duplicate authoritative buckets are rejected. These numeric analytics totals do not replace exact-money settlement calculations.
Published builds keep workspace package imports external so dependencies resolve through their owning package manifests rather than being silently inlined across package boundaries.
EditorialService.recovery authorizes scope and each record, validates claim/digest/status/age, and returns a bounded oldest-first batch. It never dispatches publication.
verifyEditorialDeployment checks exact release SHA, ready state, receipt digest, locale coverage and expected canonical URL before returning verified evidence. Hosts must obtain observations from an authorized deployment origin and bind the compiler expectation to the persisted publication claim. This pure verifier does not publish or fetch.
GitEditorialPublisher persists an immutable compiled artifact before its sole Git write attempt. Existing claims reconcile through read-only transport recovery; committed artifacts still require exact deployment proof. The host must implement current authority and native compiler validation.
Git compiler/artifact/authority rejections before dispatch can now return a durable failed-publication receipt when the store supports preparation failures. Existing stores without the capability retain conservative unknown behavior. A failure never supersedes an existing Git attempt, and raw error text is not recorded.
Qualified publishers may implement resumePreparation. The publication service preserves the claim ID, rechecks review/content/current publish authority and claims the expected revision before invoking it. Git resumes reconcile existing attempts and honor preparation-failure fences.
Editorial discovery validates page bounds, UTF-8 ID ordering, scope and all filter bindings before returning summary-schema projections. Scope and every row, including lookahead, require read authorization; denied rows fail the request.
compareEditorialIds exposes the same UTF-8 ordering used by SQL-backed listing so clients can reject non-advancing pages.
readEditorialHistory requires current scope/record authorization and separate authorization for every historical revision. It verifies identity, scope, content digest and ordering before returning historical content.
Editorial history requires contiguous revisions and detects incomplete pages before the observed current revision. Corrupt audit trails fail explicitly.
Relationships
Arrows point from a package to its direct dependency. Counts are derived from captured workspace manifests.
5 declarations
@lssm-tech/lib.billing-specworkspace:^
Read the package manual ↗@lssm-tech/lib.growth-specworkspace:^
Read the package manual ↗@lssm-tech/lib.contracts-runtime-coreworkspace:^
Read the package manual ↗@lssm-tech/lib.contracts-spec-coreworkspace:^
Read the package manual ↗@lssm-tech/lib.contracts-runtime-kernelworkspace:^
Read the package manual ↗
Declared capabilities
Pure deterministic runtime for GrowthOS referral, affiliate, reward, and payout lifecycles.
Scripts
publish:pkgbun publish --tolerate-republish --ignore-scripts --verbosepublish:pkg:canarybun publish:pkg --tag canarybuildcontractspec-bun-build buildbuild:bundlecontractspec-bun-build transpilebuild:typescontractspec-bun-build typesdevcontractspec-bun-build devcleanrimraf dist .turbolintbun lint:fixlint:fixnode ../../../../scripts/biome.cjs check --write .lint:checknode ../../../../scripts/biome.cjs check .testbun testprebuildcontractspec-bun-build prebuildtypechecktsgo --noEmit