lib.growth-spec

@lssm-tech/lib.growth-spec

Provider-neutral growth and marketing operation contracts for autonomous-company campaign, lifecycle, and publishing handoffs.

./marketing/site-fixtures preserves the representative marketing page/site contracts separately from the existing execution fixtures. ./marketing/validation owns their deterministic structural checks, including density, disclosures, presentation bindings and operation references. Legacy imports retain the same objects and validation behavior.

This package closes the first canonical ContractSpec slice for acquisition and lifecycle growth planning. It defines reviewable contract packets; it does not execute provider actions.

Scope

Use this package to model:

• audience segments and consent/preference boundaries;
• campaigns, experiments, content blocks, landing pages, copy variants, and SEO metadata;
• lifecycle message plans as draft/review handoffs;
• attribution model references and measurable objectives;
• prioritized first- or last-touch referral and affiliate attribution with one non-stackable winner;
• identity or organization participants, links, conversions, reward accruals, and reversals;
• manual or policy-authorized automatic payouts through opaque provider references, disabled until explicitly enabled;
• lifecycle commands and status/list queries for review, retry, and reconciliation;
• brand/safety review, CompanyOS authority, assurance evidence, and approval gates;
• provider/channel bindings as non-secret references only.

Boundary

This package does not deliver messages, publish CMS pages, buy ads, write CRM records, compute analytics dashboards, or own in-product personalization runtime decisions. Use branded references to analytics, personalization, communication, CompanyOS, assurance, integrations, and orchestration surfaces.

Public entrypoints

• @lssm-tech/lib.growth-spec — root barrel
• @lssm-tech/lib.growth-spec/types — contract schemas and types
• @lssm-tech/lib.growth-spec/validation — semantic validation helpers
• @lssm-tech/lib.growth-spec/fixtures — safe synthetic fixtures
• @lssm-tech/lib.growth-spec/referrals — referral and affiliate programs, attribution, ledger, payout, and operation contracts

Marketing Operations

The additive ./marketing subpath models brand revisions, briefs, channel-specific execution targets, bounded mandates, execution receipts, editorial records and measurement/experiment evidence. Existing referral and campaign-handoff contracts remain unchanged. ./marketing/operations and ./marketing/editorial-operations declare the shared REST/MCP operations. They do not execute providers.

External execution and copy generation declare cost-bearing effects; editorial publication declares external side effects. Shared runtime approval checks and independent domain authority ports are required. Generated schemas and OpenAPI live in the repository's Marketing Operations evidence directory.

Commands

• bun run test
• bun run typecheck
• bun run lint:check
• bun run build

Marketing budget changes and creative replacements have separate immutable semantic schemas exported from ./marketing. Execution plans bind them by ID and digest in their evidence, with independent provider-state observations, rights and liability assessments. They preserve Google daily-budget/asset-group semantics and Meta/TikTok lifetime budgets.

./marketing/conversion-operations declares three additive conversion operations: deliver, reconcile and get. Original events and corrections preserve source/destination identity, ordered revisions, consent references, absent values and immutable receipts. No personal matching identifiers belong in these semantic contracts.

./marketing/observation-operations adds resource refresh/get contracts. Observation results carry timestamped snapshots, explicit resource coverage and a stable state digest. Configured state, eligibility and review cannot substitute for each other.

marketing/installation owns standalone/managed installation configuration, health response contracts and worker lifecycle ports. Cross-tenant learning is unavailable by default; readiness does not grant publishing, financial or provider authority.

The planning browser binding identifies actor, scope, brand revision, locale and explicit intent. Canonical planning REST paths are shared with operation contracts. Browser-derived identity does not authorize inference or any proposed action.

marketing/workspace and marketing/workspace-operations define authenticated command center bootstrap. The sole caller selector is brandId; runtime identity and authorized brand revision determine the returned planning binding.

marketing/measurement-report defines explicit reporting periods, authoritative source, freshness bounds and dimension-bound totals with provenance and missing-data reasons.

Experiment protocols reject duplicate guardrail metrics, inverted bounds and non-finite minimum effects. Invalid protocols must be corrected before assessment or promotion.

Published builds keep workspace package imports external so dependencies resolve through their owning package manifests rather than being silently inlined across package boundaries.

The additive growth.editorial.recovery query discovers persisted publishing/unknown records older than a bounded minimum age. Stores opt in through EditorialStore.listRecovery; existing store implementations remain valid.

./marketing/editorial-deployment defines compiler receipt, deployment expectation and observed publication-status contracts. The existing JSON receipt field order is preserved for Hirly compatibility.

EditorialDeploymentVerifier binds deployment evidence retrieval to an explicit marketing scope, persisted publication ID and compiler expectation. Transport failures are represented as unknown evidence.

./marketing/editorial-git defines bounded compiler artifacts, immutable Git dispatch jobs and library-owned compiler/store/transport ports. A Git commit is separate from deployment proof.

./marketing/editorial-source defines expiring, scoped approval for exact source paths at an immutable Git commit. Git artifacts optionally retain sourceCommitSha for provenance without changing existing artifact behavior.

Compilation snapshots support up to 1,000 approved source paths; optional commitPaths select at most 299 of them for the Git artifact, plus its manifest. Git artifact bounds now support 300 files while retaining the 5 MB payload bound.

Selective source approval requires every omitted source to match the pinned target base. Compiler implementations must preserve this invariant so a partial commit deploys the same source snapshot that was reviewed.

EditorialGitStore optionally supports durable preparation-failure receipts. Implement both failure methods with atomic exclusion against dispatch creation; a failure must fence later dispatch for that claim. Known reason codes are defined by ./marketing/editorial-git-failure.

growth.editorial.resume_preparation v1 is a separate external-effect operation requiring fresh approval bound to scope, record, publication ID and expected revision. Ordinary reconciliation remains unchanged.

growth.editorial.list v1 returns paginated summaries filtered by lifecycle status, assignee, locale, format and optional scheduled interval. ID keyset pagination is live rather than a historical snapshot, and full Markdown is excluded.

EditorialWorkspaceDataView and its EN/FR/ES TranslationSpec catalogs define the editorial collection, fields and filters. The source query remains growth.editorial.list; filtering values stay provider-neutral while display keys are localized.

EDITORIAL_GET_PATH exposes the canonical detail-query route for clients without duplicating transport strings.

EditorialDetailDataView defines read-only content, revision, canonical URL and review/publication evidence fields, with the shared EN/FR/ES translation catalogs.

Editorial revision now declares REVISION_CONFLICT (HTTP 409), making stale optimistic edits an explicit failure surface.

EditorialEditForm defines the title/Markdown editing projection and the canonical revision-save action. Scope, expected revision and provenance must come from the verified record, not form fields.

EDITORIAL_REVISION_STATES is shared by runtime transition validation and editor visibility.

Review-control translations are in editorial-review.messages for EN/FR/ES; decision payloads continue using the canonical EditorialReview contract.

EditorialScheduleForm defines destination selection and explicit UTC timestamp entry. Destination catalogs are bounded and require unique identifiers; submitted fields use the existing scheduling operation.

Editorial publication-control translations are available in editorial-publication.messages for EN/FR/ES.

growth.editorial.history exposes at most 20 immutable revisions per page, with an observed current-revision ceiling and ascending revision cursor. The optional listHistory store capability preserves compatibility for existing stores.

EditorialHistoryDataView and EN/FR/ES catalogs describe the read-only revision list, backed by the canonical history query.

Canonical marketing product/demo and lead/estimate operation models now live in marketing/product-operations and marketing/forms-operations. Legacy operations forward to the same objects. Growth uses portable Core definitions and the complete Orchestration artifact reference, preserving policies, fields, defaults and publication authority. Source staging does not establish declaration or runtime acceptance.

marketing/site-contracts owns the complete marketing vocabulary, presentation payload and binding, section, page and site model families. marketing/form-contracts owns all three original marketing/BillingOS estimate FormSpec singletons and their original DocBlock. Legacy paths forward to the same canonical values. Private vocabulary and presentation split files remain unpublished; every existing public build entry is retained.

Canonical compatibility leaves: ./social-media/social-intent-ports, ./social-media/social-media, ./social-media/social-provider-v2, ./social-media/social-scheduling-operations, ./social-media/social-scheduling. Historical ContractSpec imports forward to these exact declarations and implementations.