Opening the link does not subscribe you; use the confirmation button on that page. This link expires soon. If you did not request it, ignore this email.
`,
+ Text: "You requested the TradeGravity research briefing.\n\nReview and confirm your subscription:\n" + confirmation.ConfirmationURL + "\n\nOpening the link does not subscribe you; use the confirmation button on that page. This link expires soon. If you did not request it, ignore this email.\n",
+ }
+ return sender.provider.Send(ctx, message, confirmation.IdempotencyKey)
+}
+
+func main() {
+ databasePath := flag.String("db", "", "private SQLite subscription database path")
+ publicBaseURL := flag.String("base-url", "", "public HTTPS base URL for links generated by the registry")
+ listenAddress := flag.String("listen", "127.0.0.1:8081", "HTTP listen address; use a TLS reverse proxy for public service")
+ enableResendWebhook := flag.Bool("enable-resend-webhook", false, "enable the signed Resend feedback endpoint")
+ enableSignup := flag.Bool("enable-signup", false, "enable the public double-opt-in subscription form")
+ signupAudience := flag.String("signup-audience", "tradegravity-briefing", "fixed audience for the public form")
+ consentSource := flag.String("consent-source", "public-subscribe-form", "consent evidence source label")
+ privacyVersion := flag.String("privacy-notice-version", "v1", "privacy notice version recorded with consent")
+ privacyURL := flag.String("privacy-notice-url", "", "public HTTPS privacy notice URL")
+ confirmationFrom := flag.String("confirmation-from", "", "verified sender used for confirmation mail")
+ confirmationReplyTo := flag.String("confirmation-reply-to", "", "optional reply-to address")
+ confirmationTTL := flag.Duration("confirmation-ttl", 30*time.Minute, "confirmation link lifetime (5m to 24h)")
+ maximumPending := flag.Int("max-pending", 100, "maximum unexpired pending confirmations")
+ flag.Parse()
+
+ secret := []byte(os.Getenv(secretEnvironment))
+ if len(secret) == 0 {
+ fatal(fmt.Errorf("%s is required", secretEnvironment))
+ }
+ registry, err := subscriptions.Open(*databasePath, secret, *publicBaseURL)
+ if err != nil {
+ fatal(err)
+ }
+ defer registry.Close()
+
+ options := subscriptions.HandlerOptions{Now: time.Now}
+ if *enableResendWebhook {
+ webhookSecret := os.Getenv(webhookSecretEnvironment)
+ if strings.TrimSpace(webhookSecret) == "" {
+ fatal(fmt.Errorf("%s is required when the Resend webhook is enabled", webhookSecretEnvironment))
+ }
+ options.ResendWebhookSecret = webhookSecret
+ }
+ if *enableSignup {
+ provider, providerErr := emaildelivery.NewResendProvider(os.Getenv(resendAPIKeyEnvironment), nil)
+ if providerErr != nil {
+ fatal(providerErr)
+ }
+ if strings.TrimSpace(*confirmationFrom) == "" {
+ fatal(errors.New("confirmation-from is required when signup is enabled"))
+ }
+ if _, parseErr := mail.ParseAddress(*confirmationFrom); parseErr != nil {
+ fatal(errors.New("confirmation-from is invalid"))
+ }
+ if strings.TrimSpace(*confirmationReplyTo) != "" {
+ if _, parseErr := mail.ParseAddress(*confirmationReplyTo); parseErr != nil {
+ fatal(errors.New("confirmation-reply-to is invalid"))
+ }
+ }
+ options.Signup = &subscriptions.SignupOptions{Config: subscriptions.SignupConfig{
+ Audience: *signupAudience, ConsentSource: *consentSource, PrivacyNoticeVersion: *privacyVersion,
+ PrivacyNoticeURL: *privacyURL, ConfirmationTTL: *confirmationTTL, DispatchCooldown: time.Minute, MaxPending: *maximumPending,
+ }, Sender: resendConfirmationSender{provider: provider, from: *confirmationFrom, replyTo: *confirmationReplyTo}}
+ }
+ handler, err := registry.HandlerWithOptions(options)
+ if err != nil {
+ fatal(err)
+ }
+ server := &http.Server{
+ Addr: strings.TrimSpace(*listenAddress),
+ Handler: handler,
+ ReadHeaderTimeout: 5 * time.Second,
+ ReadTimeout: 10 * time.Second,
+ WriteTimeout: 10 * time.Second,
+ IdleTimeout: 30 * time.Second,
+ MaxHeaderBytes: 8 << 10,
+ ErrorLog: log.New(os.Stderr, "unsubscribe service: ", 0),
+ }
+ if server.Addr == "" {
+ fatal(errors.New("listen address is required"))
+ }
+
+ ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
+ defer stop()
+ done := make(chan error, 1)
+ go func() {
+ done <- server.ListenAndServe()
+ }()
+ fmt.Printf("subscription service listening (address=%s tls=reverse-proxy-required resend_webhook=%t signup=%t)\n", server.Addr, *enableResendWebhook, *enableSignup)
+
+ select {
+ case err := <-done:
+ if !errors.Is(err, http.ErrServerClosed) {
+ fatal(err)
+ }
+ case <-ctx.Done():
+ shutdownContext, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+ defer cancel()
+ if err := server.Shutdown(shutdownContext); err != nil {
+ fatal(err)
+ }
+ if err := <-done; !errors.Is(err, http.ErrServerClosed) {
+ fatal(err)
+ }
+ }
+}
+
+func fatal(err error) {
+ fmt.Fprintln(os.Stderr, "unsubscribe service failed:", err)
+ os.Exit(1)
+}
diff --git a/cmd/validator/briefing_test.go b/cmd/validator/briefing_test.go
new file mode 100644
index 0000000..56fbbb3
--- /dev/null
+++ b/cmd/validator/briefing_test.go
@@ -0,0 +1,49 @@
+package main
+
+import "testing"
+
+func TestValidateBriefingAcceptsReviewGatedCitedDraft(t *testing.T) {
+ metadata := datasetMeta{GeneratedAt: "2026-07-17T00:00:00Z"}
+ briefing := validValidationBriefing(metadata.GeneratedAt)
+ if err := validateBriefing(metadata, validationPublicationChanges{Status: "changed"}, briefing); err != nil {
+ t.Fatalf("validateBriefing() error = %v", err)
+ }
+}
+
+func TestValidateBriefingRejectsAutomaticSendAndBrokenArithmetic(t *testing.T) {
+ metadata := datasetMeta{GeneratedAt: "2026-07-17T00:00:00Z"}
+ briefing := validValidationBriefing(metadata.GeneratedAt)
+ briefing.Email.SendPolicy = "automatic"
+ if err := validateBriefing(metadata, validationPublicationChanges{Status: "changed"}, briefing); err == nil {
+ t.Fatal("validateBriefing() accepted an automatic send policy")
+ }
+ briefing = validValidationBriefing(metadata.GeneratedAt)
+ briefing.Signals[0].DeltaTradeUSD = 999
+ if err := validateBriefing(metadata, validationPublicationChanges{Status: "changed"}, briefing); err == nil {
+ t.Fatal("validateBriefing() accepted inconsistent signal arithmetic")
+ }
+}
+
+func validValidationBriefing(generatedAt string) validationBriefing {
+ current := validationBriefingObservedValue{USATradeUSD: 120, ChinaTradeUSD: 80, TotalTradeUSD: 200, ChinaShare: 0.4}
+ previous := validationBriefingObservedValue{USATradeUSD: 80, ChinaTradeUSD: 80, TotalTradeUSD: 160, ChinaShare: 0.5}
+ ratio := 0.25
+ signals := []validationBriefingSignal{
+ {ID: "monthly-total-kor", Kind: "reporter_total_change", Title: "Korea total increased", Summary: "Summary", ReporterISO3: "KOR", ReporterName: "Korea, Rep.", Period: "2026-05", PreviousPeriod: "2026-04", Current: current, Previous: previous, DeltaTradeUSD: 40, ChangeRatio: &ratio, ChinaShareDelta: -0.1, Evidence: []string{"./semiconductors/monthly/KOR.json", "./semiconductors/monthly/index.json"}, Interpretation: "Boundary", MeasurementLimit: "Limit"},
+ {ID: "anchor-share-kor", Kind: "anchor_share_shift", Title: "Korea share shifted", Summary: "Summary", ReporterISO3: "KOR", ReporterName: "Korea, Rep.", Period: "2026-05", PreviousPeriod: "2026-04", Current: current, Previous: previous, DeltaTradeUSD: 40, ChangeRatio: &ratio, ChinaShareDelta: -0.1, Evidence: []string{"./semiconductors/monthly/KOR.json", "./semiconductors/monthly/index.json"}, Interpretation: "Boundary", MeasurementLimit: "Limit"},
+ {ID: "product-kor-854232", Kind: "product_total_change", Title: "Korea memories increased", Summary: "Summary", ReporterISO3: "KOR", ReporterName: "Korea, Rep.", Classification: "H6", Code: "854232", Label: "Memories", Period: "2026-05", PreviousPeriod: "2026-04", Current: current, Previous: previous, DeltaTradeUSD: 40, ChangeRatio: &ratio, ChinaShareDelta: -0.1, Evidence: []string{"./semiconductors/monthly/KOR.json", "./semiconductors/reference.json"}, Interpretation: "Boundary", MeasurementLimit: "Limit"},
+ }
+ roles := []string{"cover", "scale", "anchor_balance", "product", "method", "cta"}
+ slides := make([]validationBriefingCarouselSlide, 0, len(roles))
+ for index, role := range roles {
+ slides = append(slides, validationBriefingCarouselSlide{Order: index + 1, Role: role, Headline: "Headline", Body: "Body", Evidence: []string{"./semiconductors/monthly/index.json"}})
+ }
+ return validationBriefing{
+ SchemaVersion: "1.0", GeneratedAt: generatedAt, EditionID: "semiconductor-pulse-2026-05-20260717T000000Z", Status: "ready",
+ Title: "TradeGravity Semiconductor Pulse", Scope: "Scope", LatestPeriod: "2026-05", PreviousPeriod: "2026-04", PublicationStatus: "changed", ReviewRequired: true,
+ Signals: signals,
+ Email: validationBriefingEmail{Subject: "Subject", Preview: "Preview", Markdown: "[Evidence]({{BASE_URL}})", CTALabel: "Inspect", CTAPath: "./?tab=semiconductors", SendPolicy: "manual_review_required", PrimaryGoal: "Inspect evidence"},
+ SocialCarousel: validationBriefingSocialCarousel{Format: "carousel_copy", AspectRatio: "4:5", ReviewPolicy: "manual_review_required", Slides: slides},
+ Caveats: []string{"One", "Two", "Three"}, EvidenceEntryPoint: "./?tab=semiconductors",
+ }
+}
diff --git a/cmd/validator/extended.go b/cmd/validator/extended.go
index ffcae3b..266dedd 100644
--- a/cmd/validator/extended.go
+++ b/cmd/validator/extended.go
@@ -379,6 +379,78 @@ type validationPublicationRevision struct {
ChangeRatio *float64 `json:"change_ratio,omitempty"`
}
+type validationBriefing struct {
+ SchemaVersion string `json:"schema_version"`
+ GeneratedAt string `json:"generated_at"`
+ EditionID string `json:"edition_id"`
+ Status string `json:"status"`
+ Title string `json:"title"`
+ Scope string `json:"scope"`
+ LatestPeriod string `json:"latest_period,omitempty"`
+ PreviousPeriod string `json:"previous_period,omitempty"`
+ PublicationStatus string `json:"publication_status"`
+ ReviewRequired bool `json:"review_required"`
+ Signals []validationBriefingSignal `json:"signals"`
+ Email validationBriefingEmail `json:"email"`
+ SocialCarousel validationBriefingSocialCarousel `json:"social_carousel"`
+ Caveats []string `json:"caveats"`
+ EvidenceEntryPoint string `json:"evidence_entry_point"`
+}
+
+type validationBriefingSignal struct {
+ ID string `json:"id"`
+ Kind string `json:"kind"`
+ Title string `json:"title"`
+ Summary string `json:"summary"`
+ ReporterISO3 string `json:"reporter_iso3"`
+ ReporterName string `json:"reporter_name"`
+ Classification string `json:"classification,omitempty"`
+ Code string `json:"code,omitempty"`
+ Label string `json:"label,omitempty"`
+ Period string `json:"period"`
+ PreviousPeriod string `json:"previous_period"`
+ Current validationBriefingObservedValue `json:"current"`
+ Previous validationBriefingObservedValue `json:"previous"`
+ DeltaTradeUSD float64 `json:"delta_trade_usd"`
+ ChangeRatio *float64 `json:"change_ratio,omitempty"`
+ ChinaShareDelta float64 `json:"china_share_delta"`
+ Evidence []string `json:"evidence"`
+ Interpretation string `json:"interpretation"`
+ MeasurementLimit string `json:"measurement_limit"`
+}
+
+type validationBriefingObservedValue struct {
+ USATradeUSD float64 `json:"usa_trade_usd"`
+ ChinaTradeUSD float64 `json:"china_trade_usd"`
+ TotalTradeUSD float64 `json:"total_trade_usd"`
+ ChinaShare float64 `json:"china_share"`
+}
+
+type validationBriefingEmail struct {
+ Subject string `json:"subject"`
+ Preview string `json:"preview"`
+ Markdown string `json:"markdown"`
+ CTALabel string `json:"cta_label"`
+ CTAPath string `json:"cta_path"`
+ SendPolicy string `json:"send_policy"`
+ PrimaryGoal string `json:"primary_goal"`
+}
+
+type validationBriefingSocialCarousel struct {
+ Format string `json:"format"`
+ AspectRatio string `json:"aspect_ratio"`
+ ReviewPolicy string `json:"review_policy"`
+ Slides []validationBriefingCarouselSlide `json:"slides"`
+}
+
+type validationBriefingCarouselSlide struct {
+ Order int `json:"order"`
+ Role string `json:"role"`
+ Headline string `json:"headline"`
+ Body string `json:"body"`
+ Evidence []string `json:"evidence"`
+}
+
type validationQuality struct {
SchemaVersion string `json:"schema_version"`
GeneratedAt string `json:"generated_at"`
@@ -550,6 +622,13 @@ func validateExtendedDataset(dataDir string, metadata datasetMeta, latest datase
if err := validatePublicationChanges(metadata, semiconductorMonthlyIndex, publicationChanges); err != nil {
return err
}
+ var briefing validationBriefing
+ if err := readJSON(filepath.Join(dataDir, "briefing.json"), &briefing); err != nil {
+ return fmt.Errorf("read briefing.json: %w", err)
+ }
+ if err := validateBriefing(metadata, publicationChanges, briefing); err != nil {
+ return err
+ }
var tariffIndex validationTariffIndex
if err := readJSON(filepath.Join(dataDir, "tariffs", "index.json"), &tariffIndex); err != nil {
return fmt.Errorf("read tariff index: %w", err)
@@ -575,7 +654,7 @@ func validateExtendedDataset(dataDir string, metadata datasetMeta, latest datase
if err := readJSON(filepath.Join(dataDir, "catalog.json"), &catalog); err != nil {
return fmt.Errorf("read catalog.json: %w", err)
}
- if err := validateCatalog(metadata, catalog, publicationChanges); err != nil {
+ if err := validateCatalog(metadata, catalog, publicationChanges, briefing); err != nil {
return err
}
if err := validateExplanations(dataDir, metadata, latest); err != nil {
@@ -588,7 +667,7 @@ func validateExtendedDataset(dataDir string, metadata datasetMeta, latest datase
return validateContext(metadata, latest, contextData)
}
-func validateCatalog(metadata datasetMeta, catalog validationCatalog, publicationChanges validationPublicationChanges) error {
+func validateCatalog(metadata datasetMeta, catalog validationCatalog, publicationChanges validationPublicationChanges, briefing validationBriefing) error {
if catalog.SchemaVersion != "1.0" || catalog.GeneratedAt != metadata.GeneratedAt {
return errorsForExtended("catalog provenance does not match metadata")
}
@@ -611,7 +690,7 @@ func validateCatalog(metadata datasetMeta, catalog validationCatalog, publicatio
}
seen[resource.ID] = resource
}
- for _, required := range []string{"headline_totals", "time_series", "country_context", "product_chapters", "quality", "strategic_hs6", "tariff_schedules", "bilateral_matrix", "semiconductor_atlas", "semiconductor_monthly", "publication_changes", "mirror_reconciliation", "scenario_runs"} {
+ for _, required := range []string{"headline_totals", "time_series", "country_context", "product_chapters", "quality", "strategic_hs6", "tariff_schedules", "bilateral_matrix", "semiconductor_atlas", "semiconductor_monthly", "publication_changes", "distribution_briefing", "mirror_reconciliation", "scenario_runs"} {
if _, ok := seen[required]; !ok {
return fmt.Errorf("catalog is missing resource %q", required)
}
@@ -668,6 +747,14 @@ func validateCatalog(metadata datasetMeta, catalog validationCatalog, publicatio
if changesResource.Status != wantChangesStatus || changesResource.Provider != "tradegravity" || changesResource.ProductLevel != 6 || changesResource.Href != "./changes.json" {
return errorsForExtended("catalog publication change resource does not match changes.json")
}
+ briefingResource := seen["distribution_briefing"]
+ wantBriefingStatus := "partial"
+ if briefing.Status == "ready" {
+ wantBriefingStatus = "ready"
+ }
+ if briefingResource.Status != wantBriefingStatus || briefingResource.Provider != "tradegravity" || briefingResource.ProductLevel != 6 || briefingResource.Href != "./briefing.json" {
+ return errorsForExtended("catalog distribution briefing resource does not match briefing.json")
+ }
return nil
}
@@ -741,6 +828,120 @@ func validatePublicationChanges(metadata datasetMeta, monthly validationSemicond
return nil
}
+func validateBriefing(metadata datasetMeta, changes validationPublicationChanges, briefing validationBriefing) error {
+ if briefing.SchemaVersion != "1.0" || briefing.GeneratedAt != metadata.GeneratedAt || strings.TrimSpace(briefing.EditionID) == "" || strings.TrimSpace(briefing.Title) == "" || strings.TrimSpace(briefing.Scope) == "" {
+ return errorsForExtended("briefing provenance does not match metadata")
+ }
+ if briefing.Status != "ready" && briefing.Status != "unavailable" {
+ return fmt.Errorf("briefing has invalid status %q", briefing.Status)
+ }
+ if briefing.PublicationStatus != changes.Status || !briefing.ReviewRequired || len(briefing.Caveats) < 3 || !validBriefingHref(briefing.EvidenceEntryPoint) {
+ return errorsForExtended("briefing does not preserve publication status, review, caveat, or evidence requirements")
+ }
+ for _, caveat := range briefing.Caveats {
+ if strings.TrimSpace(caveat) == "" {
+ return errorsForExtended("briefing caveats must not be blank")
+ }
+ }
+ email := briefing.Email
+ if strings.TrimSpace(email.Subject) == "" || strings.TrimSpace(email.Preview) == "" || strings.TrimSpace(email.Markdown) == "" || strings.TrimSpace(email.CTALabel) == "" || !validBriefingHref(email.CTAPath) || email.SendPolicy != "manual_review_required" || strings.TrimSpace(email.PrimaryGoal) == "" {
+ return errorsForExtended("briefing email draft is incomplete or not review-gated")
+ }
+ carousel := briefing.SocialCarousel
+ if carousel.Format != "carousel_copy" || carousel.AspectRatio != "4:5" || carousel.ReviewPolicy != "manual_review_required" {
+ return errorsForExtended("briefing carousel contract is invalid")
+ }
+ if briefing.Status == "unavailable" {
+ if len(briefing.Signals) != 0 || len(carousel.Slides) != 0 {
+ return errorsForExtended("unavailable briefing must not publish signals or carousel slides")
+ }
+ return nil
+ }
+ if !monthPattern.MatchString(briefing.LatestPeriod) || !monthPattern.MatchString(briefing.PreviousPeriod) || briefing.LatestPeriod <= briefing.PreviousPeriod || !strings.Contains(email.Markdown, "{{BASE_URL}}") {
+ return errorsForExtended("ready briefing has invalid periods or unresolved delivery template")
+ }
+ wantKinds := []string{"reporter_total_change", "anchor_share_shift", "product_total_change"}
+ if len(briefing.Signals) != len(wantKinds) {
+ return fmt.Errorf("ready briefing has %d signals, want %d", len(briefing.Signals), len(wantKinds))
+ }
+ seenIDs := make(map[string]struct{}, len(briefing.Signals))
+ for index, signal := range briefing.Signals {
+ if signal.Kind != wantKinds[index] || strings.TrimSpace(signal.ID) == "" || strings.TrimSpace(signal.Title) == "" || strings.TrimSpace(signal.Summary) == "" || !iso3Pattern.MatchString(signal.ReporterISO3) || strings.TrimSpace(signal.ReporterName) == "" || !monthPattern.MatchString(signal.Period) || !monthPattern.MatchString(signal.PreviousPeriod) || signal.Period <= signal.PreviousPeriod || strings.TrimSpace(signal.Interpretation) == "" || strings.TrimSpace(signal.MeasurementLimit) == "" {
+ return fmt.Errorf("briefing has incomplete signal %+v", signal)
+ }
+ if _, exists := seenIDs[signal.ID]; exists {
+ return fmt.Errorf("briefing repeats signal id %q", signal.ID)
+ }
+ seenIDs[signal.ID] = struct{}{}
+ if signal.Kind == "product_total_change" {
+ if strings.TrimSpace(signal.Classification) == "" || !hs6Pattern.MatchString(signal.Code) || strings.TrimSpace(signal.Label) == "" {
+ return fmt.Errorf("briefing product signal is incomplete %+v", signal)
+ }
+ } else if signal.Classification != "" || signal.Code != "" || signal.Label != "" {
+ return fmt.Errorf("briefing aggregate signal claims product identity %+v", signal)
+ }
+ if err := validateBriefingObservedValue(signal.Current); err != nil {
+ return fmt.Errorf("briefing signal %s current value: %w", signal.ID, err)
+ }
+ if err := validateBriefingObservedValue(signal.Previous); err != nil {
+ return fmt.Errorf("briefing signal %s previous value: %w", signal.ID, err)
+ }
+ if !isFinite(signal.DeltaTradeUSD) || !approximatelyEqual(signal.DeltaTradeUSD, signal.Current.TotalTradeUSD-signal.Previous.TotalTradeUSD) || !isFinite(signal.ChinaShareDelta) || !approximatelyEqual(signal.ChinaShareDelta, signal.Current.ChinaShare-signal.Previous.ChinaShare) {
+ return fmt.Errorf("briefing signal %s has inconsistent deltas", signal.ID)
+ }
+ if signal.Previous.TotalTradeUSD > 0 {
+ if signal.ChangeRatio == nil || !isFinite(*signal.ChangeRatio) || !approximatelyEqual(*signal.ChangeRatio, signal.DeltaTradeUSD/signal.Previous.TotalTradeUSD) {
+ return fmt.Errorf("briefing signal %s has inconsistent change ratio", signal.ID)
+ }
+ } else if signal.ChangeRatio != nil {
+ return fmt.Errorf("briefing signal %s must omit a ratio with a zero baseline", signal.ID)
+ }
+ if len(signal.Evidence) < 2 {
+ return fmt.Errorf("briefing signal %s has insufficient evidence links", signal.ID)
+ }
+ for _, href := range signal.Evidence {
+ if !validBriefingHref(href) {
+ return fmt.Errorf("briefing signal %s has invalid evidence href %q", signal.ID, href)
+ }
+ }
+ }
+ if briefing.Signals[0].Period != briefing.LatestPeriod || briefing.Signals[0].PreviousPeriod != briefing.PreviousPeriod {
+ return errorsForExtended("briefing edition periods do not match the leading signal")
+ }
+ wantRoles := []string{"cover", "scale", "anchor_balance", "product", "method", "cta"}
+ if len(carousel.Slides) != len(wantRoles) {
+ return fmt.Errorf("briefing carousel has %d slides, want %d", len(carousel.Slides), len(wantRoles))
+ }
+ for index, slide := range carousel.Slides {
+ if slide.Order != index+1 || slide.Role != wantRoles[index] || strings.TrimSpace(slide.Headline) == "" || strings.TrimSpace(slide.Body) == "" || len(slide.Evidence) == 0 {
+ return fmt.Errorf("briefing carousel has invalid slide %+v", slide)
+ }
+ for _, href := range slide.Evidence {
+ if !validBriefingHref(href) {
+ return fmt.Errorf("briefing carousel slide %d has invalid evidence href %q", slide.Order, href)
+ }
+ }
+ }
+ return nil
+}
+
+func validateBriefingObservedValue(value validationBriefingObservedValue) error {
+ values := []float64{value.USATradeUSD, value.ChinaTradeUSD, value.TotalTradeUSD, value.ChinaShare}
+ for _, item := range values {
+ if !isFinite(item) || item < 0 {
+ return fmt.Errorf("contains invalid nonnegative value %v", item)
+ }
+ }
+ if value.ChinaShare > 1 || !approximatelyEqual(value.TotalTradeUSD, value.USATradeUSD+value.ChinaTradeUSD) || (value.TotalTradeUSD > 0 && !approximatelyEqual(value.ChinaShare, value.ChinaTradeUSD/value.TotalTradeUSD)) || (value.TotalTradeUSD == 0 && value.ChinaShare != 0) {
+ return errorsForExtended("totals or China share are inconsistent")
+ }
+ return nil
+}
+
+func validBriefingHref(href string) bool {
+ return strings.HasPrefix(href, "./") && !strings.Contains(href, "..") && !strings.ContainsAny(href, "\r\n")
+}
+
func sortedUnique(values []string) bool {
if !sort.StringsAreSorted(values) {
return false
diff --git a/docs/DATA_SCHEMA.md b/docs/DATA_SCHEMA.md
index 08e0587..eccf5a1 100644
--- a/docs/DATA_SCHEMA.md
+++ b/docs/DATA_SCHEMA.md
@@ -1,6 +1,6 @@
# Published data schema 2.0
-TradeGravity publishes one versioned artifact set under `site/data/`. Headline, product, strategic HS6, semiconductor, publish-to-publish change, tariff, bilateral-matrix, mirror-diagnostic, quality, and explanation artifacts share the trade publication timestamp. The semiconductor reference has its own additive schema and records both its editorial update date and publisher `generated_at`. `catalog.json` and `changes.json` have independent additive schemas and the same publisher timestamp. `context.json` has its own refresh time because it is built before the trade publisher.
+TradeGravity publishes one versioned artifact set under `site/data/`. Headline, product, strategic HS6, semiconductor, publish-to-publish change, distribution briefing, tariff, bilateral-matrix, mirror-diagnostic, quality, and explanation artifacts share the trade publication timestamp. The semiconductor reference has its own additive schema and records both its editorial update date and publisher `generated_at`. `catalog.json`, `changes.json`, and `briefing.json` have independent additive schemas and the same publisher timestamp. `context.json` has its own refresh time because it is built before the trade publisher.
## Time and comparison semantics
@@ -24,6 +24,7 @@ TradeGravity publishes one versioned artifact set under `site/data/`. Headline,
| `semiconductors/monthly/index.json` | Focused monthly reporter/period discovery | UN Comtrade + semiconductor registry |
| `semiconductors/monthly/{ISO3}.json` | Selected HS6 monthly USA/China flows | UN Comtrade |
| `changes.json` | Previous-publication coverage, row, and value deltas for the focused monthly semiconductor layer | Publisher comparison of consecutive publications |
+| `briefing.json` | Review-gated email and 4:5 carousel drafts derived from three cited monthly semiconductor signals | Deterministic publisher calculations over the focused monthly layer |
| `tariffs/index.json` | Importer/year tariff partition discovery | WITS/TRAINS |
| `tariffs/{ISO3}/{YEAR}.json` | Revision-aware strategic HS6 tariff rows | WITS/TRAINS |
| `bilateral-matrix/index.json` | Multi-partner `TOTAL` partition discovery | UN Comtrade |
@@ -39,7 +40,7 @@ TradeGravity publishes one versioned artifact set under `site/data/`. Headline,
The catalog is the stable discovery layer for a dashboard that may grow beyond a few single-file datasets. Each resource declares an `id`, display title, `status`, analytical `grain`, `partitioning`, and an `href` only when an artifact is published. Current statuses are `ready`, `partial`, and `planned`.
-`strategic_hs6`, `semiconductor_atlas`, `semiconductor_monthly`, `publication_changes`, `tariff_schedules`, `bilateral_matrix`, and `mirror_reconciliation` are published resources. The last ID is retained for catalog compatibility, but its title and artifact explicitly describe **unadjusted mirror-reporting diagnostics**, not a reconciled truth. Computed value-added networks and versioned scenario results remain planned contracts and do not claim that those observations exist. Published resources use relative same-origin paths; the validator rejects duplicate IDs, invalid statuses, unsafe paths, and metadata that conflicts with `meta.json`.
+`strategic_hs6`, `semiconductor_atlas`, `semiconductor_monthly`, `publication_changes`, `distribution_briefing`, `tariff_schedules`, `bilateral_matrix`, and `mirror_reconciliation` are published resources. The last ID is retained for catalog compatibility, but its title and artifact explicitly describe **unadjusted mirror-reporting diagnostics**, not a reconciled truth. Computed value-added networks and versioned scenario results remain planned contracts and do not claim that those observations exist. Published resources use relative same-origin paths; the validator rejects duplicate IDs, invalid statuses, unsafe paths, and metadata that conflicts with `meta.json`.
The current product resource demonstrates the intended scaling pattern: a small discovery index plus one reporter file. Higher-volume resources should use period, reporter, importer, industry, or sector chunks named in the catalog rather than expanding `latest.json`.
@@ -209,6 +210,27 @@ Only mapped HS6 codes, monthly periods, and USA/CHN partners are admitted. The i
`status` is `baseline` when no earlier comparable publication exists, `unchanged` when a previous publication exists but no admitted change is found, and `changed` otherwise. A baseline never masquerades as “no change.” The revision list is capped at 20 rows and ordered by the sum of absolute USA and China trade-value changes; global counts remain complete even when the list is truncated. Added and removed rows are counted but not represented as value revisions. The validator checks current-index identity, timestamps, dimensions, counts, finite values, revision arithmetic, and descending magnitude.
+## Reviewed distribution briefing
+
+`briefing.json` uses schema `1.0` and converts the focused monthly semiconductor observations into one inspectable distribution contract. It contains exactly three deterministic signals when two comparable months exist: the largest absolute reporter total change, the largest absolute two-anchor China-share shift, and the largest absolute HS6 product change. Each signal retains current and previous USA/China values, arithmetic deltas, periods, interpretation limits, and relative evidence paths.
+
+The same signals feed two non-publishing draft formats:
+
+- `email` contains subject, preview, Markdown body, evidence CTA, `send_policy: "manual_review_required"`, and a primary goal;
+- `social_carousel` contains six cited `4:5` copy slides with `review_policy: "manual_review_required"` in cover, scale, anchor-balance, product, method, and CTA order.
+
+The top-level `review_required` must remain `true`. A ready artifact is rejected if either channel permits automatic publication. If two comparable months are unavailable, the artifact fails closed with `status: "unavailable"`, no signals, and no sendable copy. The static application can download drafts and copy the evidence link; it does not maintain a subscriber database, send mail, or call a social publishing API. The offline distributor can render matched SVG and 1080×1350 PNG drafts from the validated slide model, but its manifest keeps both send and social authorization false.
+
+An optional local `approval.json` schema `1.0` is created only after the distributor verifies the exact manifest file set, byte counts, and SHA-256 digests. The manifest's carousel record includes the selected native `theme` (`intelligence-dark` or `editorial-light`) and fixed `caption_path: "carousel/caption.md"`. The caption is derived from the validated signals with period, evidence entry point, scope note, restrained tags, and a 1,800-rune project ceiling. A theme, caption, or image change alters hashes and invalidates an earlier approval. The approval records `scope: "content_release"`, the edition and manifest digest, reviewer, non-sensitive audience label, canonical UTC approval time, sorted channels, and fixed review attestations; automatic publishing remains false.
+
+An optional external `instagram-preflight.json` schema `1.0` binds an Instagram-approved manifest and approval digest to the theme, six-slide count, 1080×1350 dimensions, caption rune/hashtag counts, alt-text section count, and boolean integrity checks. It contains no caption text, hashtags, evidence URL, credentials, or account identity. `manual_upload_required` is true and `automatic_publish_authorized` is false. It must remain outside the approved kit; see [INSTAGRAM_PREFLIGHT.md](INSTAGRAM_PREFLIGHT.md).
+
+An optional local `delivery-preflight.json` schema `1.0` can then bind an email-approved edition to the SHA-256 digests of private subscriber and suppression CSVs. It records only aggregate consented, suppressed, suppression-row, and eligible counts; the approved audience label; the template, manifest, and approval digests; an explicit pilot ceiling; required unsubscribe headers and DKIM coverage; and whether individual opaque HTTPS unsubscribe URLs passed validation. It contains no recipient addresses, unsubscribe URLs, tokens, or local file paths. `provider_configured` and `delivery_authorized` remain false. The private CSV schemas and operational limits are documented in [EMAIL_DELIVERY_PREFLIGHT.md](EMAIL_DELIVERY_PREFLIGHT.md); neither the CSVs nor this local plan belongs under `site/data/`.
+
+The optional private subscription registry is deliberately outside the published schema. Its SQLite tables keep random subscription and pending-confirmation IDs, normalized email, audience, active/suppressed state, double-opt-in evidence, confirmation expiry/dispatch state, privacy-notice version, suppression reason/time, provider-feedback event IDs, and global bounced/complaint/provider-suppression state. Purpose-separated HMAC token payloads contain only a version and random ID. Confirmation GET is read-only and explicit POST records consent; globally suppressed addresses cannot receive confirmation or become active. Database files, WAL/SHM files, source/export CSVs, tokens, and secrets must never be published. See [UNSUBSCRIBE_SERVICE.md](UNSUBSCRIBE_SERVICE.md).
+
+An optional local `email-launch-authorization.json` schema `1.0` binds one Resend pilot to the exact preflight digest, edition, audience, sender, content/input digests, eligible count, operator, attestations, and a validity window of no more than one hour. It contains no recipient address or unsubscribe token. The accompanying private delivery-ledger SQLite schema stores only HMAC-derived recipient and delivery keys, aggregate labels, content/idempotency and authorization identifiers, provider message IDs, statuses, timestamps, and bounded non-sensitive reconciliation labels. Accepted and unresolved-pending rows both prevent an automatic resend. A provider-confirmed `not_accepted` resolution can transition back to a pending attempt only when a different launch-authorization digest is supplied later; the audit row and stable provider idempotency key are retained. Neither artifact is published, and neither changes the public `catalog.json`; see [EMAIL_PROVIDER_PILOT.md](EMAIL_PROVIDER_PILOT.md).
+
## Multi-partner bilateral matrix
The matrix index has `product_code: "TOTAL"`, `product_level: 0`, sorted reporter/partner/period dimensions, partition counts, partner-row counts, and source-observation counts. Each reporter/year file contains one row per alphabetic ISO3 partner:
@@ -256,7 +278,7 @@ Run the same validation used before deployment:
go run ./cmd/validator -dir site/data -min-reporters 40
```
-The validator checks cross-file provenance and counts, reporter and period uniqueness, finite numbers, calculated totals/shares/balances, monthly product identities, mirror-pair arithmetic and disclosure, flow-availability identities, strategic registry membership, free/public reference policy, tariff rate identities, catalog contracts, context coverage, collection-run metadata, and every explanation citation.
+The validator checks cross-file provenance and counts, reporter and period uniqueness, finite numbers, calculated totals/shares/balances, monthly product identities, briefing signal arithmetic and review gates, mirror-pair arithmetic and disclosure, flow-availability identities, strategic registry membership, free/public reference policy, tariff rate identities, catalog contracts, context coverage, collection-run metadata, and every explanation citation.
## CSV and filtered JSON
diff --git a/docs/DISTRIBUTION.md b/docs/DISTRIBUTION.md
new file mode 100644
index 0000000..380a713
--- /dev/null
+++ b/docs/DISTRIBUTION.md
@@ -0,0 +1,106 @@
+# Reviewed distribution workflow
+
+TradeGravity uses one evidence contract for its website briefing, email draft, and future social cards. The workflow is deliberately split into **analysis**, **rendering**, **editorial approval**, and **delivery** so that generating an asset never authorizes sending or publishing it.
+
+## Build a local kit
+
+Start from a validator-accepted `briefing.json` and the public URL at which its cited evidence will be available:
+
+```bash
+go run ./cmd/distributor \
+ -briefing examples/sample-data/briefing.json \
+ -out distribution-kit \
+ -base-url https://elecpapaya.github.io/TradeGravity/ \
+ -theme intelligence-dark
+```
+
+`-theme` accepts `intelligence-dark` (the default analytical dark treatment) or `editorial-light` (a restrained light editorial treatment). Both are original, network-free native Go themes over the same validated six-slide model. Theme selection changes the PNG/SVG bytes and is recorded in the manifest, so changing it requires a new kit and approval.
+
+The command refuses unavailable or automatically publishable briefing contracts, insecure public base URLs, and an output directory that already exists. It performs no network request and sends nothing.
+
+The generated directory contains:
+
+```text
+distribution-kit/
+├── manifest.json
+├── REVIEW.md
+├── email/
+│ ├── subject.txt
+│ ├── preview.txt
+│ ├── body.md
+│ └── body.html
+└── carousel/
+ ├── index.html
+ ├── alt-text.md
+ ├── caption.md
+ ├── slide-01.svg … slide-06.svg
+ └── slide-01.png … slide-06.png
+```
+
+After review, the approval command adds `approval.json` beside the manifest. It is intentionally absent from a newly built kit.
+
+`carousel/caption.md` is a review-pending Instagram caption derived only from the three validated signals. It retains the comparison period, evidence entry point, scope warning, and restrained topic tags. The project imposes a 1,800-rune editorial ceiling. Edit the source briefing and regenerate instead of changing the caption independently.
+
+`manifest.json` records the edition, public evidence base, email CTA, selected native theme, caption path, 1080×1350 dimensions, available `png` and `svg` formats, review-pending state, explicit false send/publish authorization, and a byte count and SHA-256 digest for every reviewable file. The manifest is deterministic for the same briefing, base URL, and theme.
+
+## Editorial review
+
+Open `carousel/index.html` locally and preview `email/body.html` on desktop and mobile. Complete `REVIEW.md` before moving any file to an external provider. At minimum, verify:
+
+- all periods, values, directions, and source links against the cited JSON;
+- month-to-month movement is not confused with a publish-to-publish revision;
+- the email has one primary CTA back to the evidence;
+- the six 4:5 cards remain legible at feed size and have reviewed alt text; and
+- caveats do not become causal, routing, capacity, alignment, or investment claims.
+
+The SVG files are editable, resolution-independent originals. The matching PNG files are deterministic 1080×1350 raster assets generated from the same validated slide model; `carousel/index.html` deliberately previews those PNGs so the editor reviews the files intended for upload. Both formats and their SHA-256 hashes are created together, but they remain drafts. If copy or citations change, regenerate the whole kit instead of editing a PNG in place. Platform preview, alt-text entry, caption review, and the final Instagram publish action stay manual.
+
+The PNG renderer uses embedded Go fonts and makes no network request or external-font fetch. This keeps the output repeatable in CI and avoids silently changing typography between builds. Review every card at actual feed size because successful decoding and correct dimensions do not prove platform acceptance or reader comprehension.
+
+Both native palettes are tested across all three gradient stops. Normal text colors must retain at least 4.5:1 contrast, and the 20px bold role labels must retain at least 3:1 against their translucent pills. This automated contrast floor complements—rather than replaces—the feed-size visual and assistive-technology review.
+
+## Record content approval
+
+Complete `REVIEW.md`, then bind the unchanged manifest and all 20 tracked files to a named reviewer, non-sensitive audience label, channel list, and explicit UTC time:
+
+```bash
+go run ./cmd/distribution-approval \
+ -kit distribution-kit \
+ -reviewer elecpapaya \
+ -audience consented-internal-pilot \
+ -channels email,instagram \
+ -approved-at 2026-07-17T12:00:00Z \
+ -attest-reviewed
+```
+
+The command fails if any tracked file was changed or removed, an untracked file was added, the manifest no longer has its review-pending/false-authorization gates, a channel is unsupported, or `approval.json` already exists. Rebuild the entire kit to make a new approval. Never place recipient addresses or provider secrets in the kit or audience label.
+
+`approval.json` has `scope: "content_release"` and binds the manifest's SHA-256 digest, file count, edition, reviewer, audience label, approved channels, time, and fixed attestations. It deliberately keeps `provider_delivery_ready`, `subscriber_consent_ready`, and `automatic_publish_ready` false. A future delivery adapter can call the same verifier and require the intended channel, but must enforce its own consent, suppression, sender, and provider gates.
+
+The approval record proves consistency with the local manifest; it does not authenticate the human reviewer by itself. Preserve it in a protected commit, release artifact, or separately signed record if reviewer authenticity is required.
+
+## Validate the manual Instagram package
+
+After an Instagram-channel approval, run `cmd/instagram-preflight` to recheck the unchanged manifest, six PNG dimensions, caption evidence/scope/tags, and all six alt-text sections. The aggregate output remains outside the kit and cannot publish anything. See [Instagram manual-publish preflight](INSTAGRAM_PREFLIGHT.md).
+
+## Manual GitHub Actions build
+
+The **Build reviewed distribution kit** workflow lets the operator choose either supported native theme, reads the validator-accepted `gh-pages` publication, builds the kit, verifies the theme and false social authorization in the manifest, and uploads it as a 14-day Actions artifact. It is manually dispatched and has read-only repository permissions. It does not have an email token, subscriber list, or social credential.
+
+## Delivery gate
+
+Provider-backed sending remains a separate operator-controlled step. Before enabling it, document and test:
+
+- double opt-in and the exact subscription promise;
+- one-click unsubscribe and a durable suppression list;
+- sender identity, SPF, DKIM, and DMARC;
+- bounce and complaint handling;
+- privacy notice, retention, deletion, and data-processing terms;
+- secret storage outside the browser and generated artifact; and
+- an approval record that binds one reviewed edition and its final hashes to one channel and audience.
+
+The content-release record implements only the editorial part of the last item. Run the provider-neutral [email delivery preflight](EMAIL_DELIVERY_PREFLIGHT.md) locally to validate a private double-opt-in CSV, apply a private suppression CSV, and create an aggregate-only plan. The preflight keeps provider configuration and delivery authorization false.
+
+The [provider-backed email pilot](EMAIL_PROVIDER_PILOT.md) adds a second, short-lived launch approval plus a fail-closed Resend adapter. It replays the exact preflight inputs immediately before sending and records accepted or uncertain attempts in a private HMAC-keyed SQLite ledger. Merely building, approving, or preflighting a kit still cannot send email; the live command additionally requires the matching authorization, provider and ledger secrets, and `-send-live`.
+
+TradeGravity should not use open tracking pixels by default. If aggregate link measurement is later added, disclose it and keep raw subscriber behavior out of the public dataset.
diff --git a/docs/EMAIL_DELIVERY_PREFLIGHT.md b/docs/EMAIL_DELIVERY_PREFLIGHT.md
new file mode 100644
index 0000000..cee97bd
--- /dev/null
+++ b/docs/EMAIL_DELIVERY_PREFLIGHT.md
@@ -0,0 +1,79 @@
+# Email delivery preflight
+
+TradeGravity keeps subscriber addresses outside the repository, static site, distribution kit, approval record, and aggregate preflight artifact. The preflight CLI is a provider-neutral gate between reviewed content and any future network sender. It validates double opt-in evidence, applies a durable suppression list, enforces a small pilot ceiling, and then emits only counts and source-file digests. It sends no email.
+
+## Inputs
+
+Start with a distribution kit whose `approval.json` includes the `email` channel. Keep both CSV files in a private local directory outside the kit.
+
+The subscriber CSV header must be exactly:
+
+```csv
+email,audience,status,consented_at,consent_method,consent_source,privacy_notice_version,unsubscribe_url
+reader@example.invalid,consented-internal-pilot,active,2026-07-10T01:00:00Z,double_opt_in,website-form,v1,https://subscriptions.example.invalid/u/opaque-recipient-token
+```
+
+Every subscriber row must:
+
+- match the non-sensitive audience label in `approval.json`;
+- have `status` equal to `active` and `consent_method` equal to `double_opt_in`;
+- contain an RFC 3339 consent time that is not in the future;
+- record a consent source and privacy-notice version; and
+- use a unique plain email addr-spec without a display name; and
+- provide a unique absolute HTTPS unsubscribe URL containing an opaque recipient token, with no credentials, fragment, or decoded email address.
+
+The suppression CSV header must be exactly:
+
+```csv
+email,reason,suppressed_at
+former-reader@example.invalid,unsubscribed,2026-07-12T03:00:00Z
+```
+
+Allowed reasons are `unsubscribed`, `bounced`, `complaint`, `invalid`, and `manual`. An empty suppression list still needs the header. Suppression always wins over active consent.
+
+## Run the preflight
+
+```bash
+go run ./cmd/distribution-preflight \
+ -kit distribution-kit \
+ -subscribers private/subscribers.csv \
+ -suppressions private/suppressions.csv \
+ -out delivery-preflight.json \
+ -generated-at 2026-07-17T12:30:00Z \
+ -max-recipients 25
+```
+
+The command refuses:
+
+- a kit without a valid email content approval;
+- changed, missing, or untracked kit files;
+- subscriber or suppression inputs stored inside the kit;
+- malformed, duplicate, future-dated, wrong-audience, or non-double-opt-in subscriber rows;
+- malformed or duplicate suppression rows;
+- an empty post-suppression audience; and
+- an eligible audience above the explicit pilot limit.
+
+`delivery-preflight.json` uses file mode `0600` where the operating system supports it and refuses to overwrite an existing file. It records the edition, manifest and approval digests, audience label, subscriber/suppression file digests, aggregate counts, template digest, required unsubscribe headers, and the pilot limit. It contains no recipient addresses, unsubscribe URLs, tokens, or local source paths.
+
+## What remains intentionally false
+
+A passing plan has:
+
+```json
+{
+ "consent_validated": true,
+ "suppression_applied": true,
+ "unsubscribe_urls_validated": true,
+ "contains_recipient_addresses": false,
+ "provider_configured": false,
+ "delivery_authorized": false
+}
+```
+
+The approved HTML and Markdown templates contain exactly one `{{UNSUBSCRIBE_URL}}` placeholder in addition to the single primary evidence CTA. A future sender must replace that placeholder with a recipient-specific HTTPS unsubscribe URL, set `List-Unsubscribe` to that HTTPS URI, set `List-Unsubscribe-Post` to `List-Unsubscribe=One-Click`, and ensure a valid DKIM signature covers both headers. These are the one-click sender requirements defined by [RFC 8058](https://www.rfc-editor.org/rfc/rfc8058.html); Gmail's current sender guidance also requires a visible body link for subscribed messages and one-click support for high-volume senders. ([Gmail sender guidelines](https://support.google.com/mail/answer/81126))
+
+The reference [provider-backed email pilot](EMAIL_PROVIDER_PILOT.md) re-runs the same in-memory preflight immediately before sending, requires unchanged source digests, and obtains a separate short-lived launch authorization. The operator must still authenticate the sender domain and deploy/test the signed Resend feedback handler so bounce, complaint, and provider-suppression events update the private registry before issuing that authorization.
+
+For a provider-neutral implementation that generates these URLs and exports both private CSVs, see the [subscription registry and unsubscribe service](UNSUBSCRIBE_SERVICE.md). It imports existing double-opt-in evidence; it does not create or prove the original opt-in.
+
+Do not upload the CSV inputs to GitHub Actions artifacts. Do not print the eligible in-memory address list, embed it in logs, or copy it into the aggregate JSON. A passing preflight is never a live-send authorization.
diff --git a/docs/EMAIL_PROVIDER_PILOT.md b/docs/EMAIL_PROVIDER_PILOT.md
new file mode 100644
index 0000000..f90345f
--- /dev/null
+++ b/docs/EMAIL_PROVIDER_PILOT.md
@@ -0,0 +1,121 @@
+# Provider-backed email pilot
+
+TradeGravity includes a bounded Resend adapter for a deliberately small, consented email pilot. It is not connected to the static site or GitHub Actions and it does not run on a schedule. A live provider request is possible only when the reviewed kit, private subscriber and suppression inputs, aggregate preflight, short-lived launch authorization, provider API key, delivery-ledger secret, and explicit `-send-live` acknowledgement all agree.
+
+The adapter follows one-email/one-job lifecycle guidance: each semiconductor brief has one primary evidence CTA, one visible unsubscribe link, and no tracking pixel. It sends one provider request per recipient rather than placing multiple readers in `To`, `Cc`, or `Bcc`.
+
+Audience consent may be imported from an existing verified double-opt-in source or collected by the default-off signup/confirmation flow documented in [UNSUBSCRIBE_SERVICE.md](UNSUBSCRIBE_SERVICE.md). Confirmation mail is transactional and does not itself add an address to a briefing audience; only the confirmation-page POST does so.
+
+## Security boundary
+
+Keep these files and values outside the repository, distribution kit, public site, CI logs, and Actions artifacts:
+
+- subscriber and suppression CSVs;
+- `delivery-preflight.json` and `email-launch-authorization.json`;
+- `delivery-ledger.db` plus its WAL/SHM files and backups;
+- `RESEND_API_KEY`; and
+- `TRADEGRAVITY_DELIVERY_SECRET`, a stable random value of at least 32 bytes.
+
+The delivery ledger stores edition and audience labels, content digests, provider/idempotency identifiers, times, and HMAC-derived recipient keys. It does not store recipient addresses, unsubscribe URLs, or rendered bodies. File mode is requested as `0600` where supported, but the operator still needs encrypted storage, access control, backups, retention, and deletion procedures.
+
+The Resend endpoint is compiled as `https://api.resend.com/emails`; it cannot be redirected with a CLI flag that might exfiltrate the API key. HTTP timeouts and response-size limits are enforced, and provider error bodies are not printed.
+
+## 1. Produce the aggregate preflight
+
+Follow [Email delivery preflight](EMAIL_DELIVERY_PREFLIGHT.md) and keep the resulting files private:
+
+```bash
+go run ./cmd/distribution-preflight \
+ -kit distribution-kit \
+ -subscribers private/subscribers.csv \
+ -suppressions private/suppressions.csv \
+ -out private/delivery-preflight.json \
+ -generated-at 2026-07-17T12:30:00Z \
+ -max-recipients 25
+```
+
+## 2. Record a short-lived launch approval
+
+Verify the Resend sender domain, SPF, DKIM, and DMARC; deploy and test both the HTTPS unsubscribe endpoint and the signed feedback endpoint described in [UNSUBSCRIBE_SERVICE.md](UNSUBSCRIBE_SERVICE.md); prove that `email.bounced`, `email.complained`, and `email.suppressed` events become durable suppressions; review privacy controls; and inspect the final eligible pilot list. Then create an authorization that expires within one hour:
+
+```bash
+go run ./cmd/email-launch-approval \
+ -preflight private/delivery-preflight.json \
+ -out private/email-launch-authorization.json \
+ -provider resend \
+ -from 'TradeGravity ' \
+ -reply-to maintainer@example.org \
+ -authorized-by elecpapaya \
+ -authorized-at 2026-07-17T12:35:00Z \
+ -expires-at 2026-07-17T13:05:00Z \
+ -attest-domain-authenticated \
+ -attest-feedback-ready \
+ -attest-privacy-reviewed \
+ -attest-pilot-recipients
+```
+
+The JSON contains aggregate identities and digests but no recipient address or token. It refuses overwrite. Changing the preflight, manifest, approval, email template, subscriber file, suppression file, recipient count, audience, provider, or sender requires a new authorization.
+
+## 3. Send the bounded pilot
+
+Set secrets without writing them into shell history, then run within the authorization window:
+
+```bash
+export RESEND_API_KEY='read-from-your-secret-manager'
+export TRADEGRAVITY_DELIVERY_SECRET='at-least-32-stable-random-bytes'
+
+go run ./cmd/email-delivery \
+ -kit distribution-kit \
+ -subscribers private/subscribers.csv \
+ -suppressions private/suppressions.csv \
+ -preflight private/delivery-preflight.json \
+ -authorization private/email-launch-authorization.json \
+ -ledger private/delivery-ledger.db \
+ -send-at 2026-07-17T12:40:00Z \
+ -send-live
+```
+
+Immediately before the first provider request, the command reruns content approval, double-opt-in, suppression, audience, URL, and pilot-ceiling checks. It compares all live digests and counts with both the original preflight and launch approval. Each request includes:
+
+- one recipient;
+- the approved HTML and Markdown bodies with that recipient's HTTPS link;
+- `List-Unsubscribe: `;
+- `List-Unsubscribe-Post: List-Unsubscribe=One-Click`; and
+- a stable provider `Idempotency-Key` derived from the edition and a secret HMAC recipient identity.
+
+Resend documents custom email headers and `Idempotency-Key` on `POST /emails`; its idempotency window is currently 24 hours. The local ledger is therefore the longer-lived duplicate guard. See [Resend Send Email](https://resend.com/docs/api-reference/emails/send-email) and [Resend idempotency keys](https://resend.com/docs/dashboard/emails/idempotency-keys).
+
+## Failure and reconciliation
+
+An accepted ledger row is skipped on every later run. If the process cannot prove provider acceptance, it leaves a `pending` row and stops. A later run refuses to resend that recipient automatically—even if Resend's 24-hour idempotency window has elapsed. This trades possible non-delivery for protection against an accidental duplicate.
+
+Do not delete or edit the ledger to force a retry. First reconcile the pending idempotency key against the provider dashboard and logs. The signed feedback handler records later suppression outcomes, but it cannot prove whether an unresolved send request was accepted; that delivery-ledger reconciliation remains an operator decision. Treat any pending row as a stopped pilot until the provider outcome is known.
+
+If the provider confirms acceptance, record the exact provider message ID. The recipient argument is used only in memory to derive the existing HMAC ledger key and is neither printed nor stored:
+
+```bash
+go run ./cmd/email-delivery-reconcile \
+ -ledger private/delivery-ledger.db \
+ -edition EDITION_ID \
+ -audience consented-internal-pilot \
+ -recipient 'private-recipient@example.org' \
+ -outcome accepted \
+ -provider-message-id PROVIDER_MESSAGE_ID \
+ -resolved-by elecpapaya \
+ -evidence resend-dashboard-message-match \
+ -resolved-at 2026-07-17T12:50:00Z \
+ -attest-provider-checked
+```
+
+If the provider positively confirms that it did **not** accept the request, use `-outcome not_accepted` and omit `-provider-message-id`. That outcome remains in the ledger as an audit record. The same launch authorization still cannot retry it: create a new unexpired authorization file and run delivery at a later time. The provider idempotency key remains stable across the reconciled retry.
+
+`resolved-by`, `evidence`, and provider message IDs are bounded non-sensitive labels; addresses and URLs are rejected in the stored audit fields. A contradictory second outcome is rejected, while an identical reconciliation is idempotent.
+
+## Current limits
+
+- No live TradeGravity send has been performed or implied by these tools.
+- Provider account creation, domain verification, billing, data-processing terms, webhook registration, and HTTPS deployment are external operator actions.
+- Signed bounce, complaint, and provider-suppression ingestion is implemented, but public HTTPS deployment, provider webhook registration, secret rotation, monitoring, backup/restore, and a real replay drill remain operator responsibilities.
+- Link/open tracking is not enabled; provider-account defaults must also be reviewed.
+- The first pilot should remain small, manually observed, and limited to readers who explicitly expect this edition.
+- Instagram cards remain review-gated manual uploads; email delivery never authorizes social publishing.
diff --git a/docs/INSTAGRAM_PREFLIGHT.md b/docs/INSTAGRAM_PREFLIGHT.md
new file mode 100644
index 0000000..5b1049b
--- /dev/null
+++ b/docs/INSTAGRAM_PREFLIGHT.md
@@ -0,0 +1,41 @@
+# Instagram manual-publish preflight
+
+TradeGravity keeps Instagram publishing manual. `cmd/instagram-preflight` verifies that one unchanged, Instagram-approved distribution kit is ready for a private platform preview without configuring an account credential or authorizing a post.
+
+## Run after content approval
+
+First build and approve the kit for the `instagram` channel as described in [DISTRIBUTION.md](DISTRIBUTION.md). Then write the aggregate preflight outside the kit:
+
+```bash
+go run ./cmd/instagram-preflight \
+ -kit distribution-kit \
+ -out instagram-preflight.json \
+ -generated-at 2026-07-17T14:00:00Z
+```
+
+The command fails unless:
+
+- `approval.json` covers the `instagram` channel and matches the exact manifest;
+- all six manifest-bound PNGs decode at 1080×1350;
+- `caption.md` remains within TradeGravity's 1,800-rune editorial ceiling, contains the public evidence base and scope warning, has 1–8 unique simple hashtags, and has no unresolved placeholder;
+- `alt-text.md` has one evidence section for each slide; and
+- every kit file still matches its recorded byte count and SHA-256 digest.
+
+The output records only edition/theme identities, hashes, counts, dimensions, and boolean checks. It does not contain the caption, hashtags, evidence URL, credentials, or platform account. Its fixed controls remain:
+
+```json
+{
+ "contains_caption_text": false,
+ "contains_credentials": false,
+ "manual_upload_required": true,
+ "automatic_publish_authorized": false
+}
+```
+
+The file is not part of the approved kit and the command refuses to write it inside that directory or overwrite an existing output. It is ignored at the repository root by default.
+
+## Private platform preview
+
+After preflight, use Instagram's own draft or private preview surface manually. Confirm ordering, crop, line wrapping, caption appearance, hashtag wording, alt-text entry, account identity, and rights. Do not treat a passing local preflight as proof that Instagram accepted or published the carousel. Rebuild and reapprove after any content change.
+
+Automatic publishing would require a separate credential-bearing adapter, explicit account and permission checks, platform idempotency, post-result reconciliation, and a new short-lived launch authorization. None of those capabilities are implemented or implied here.
diff --git a/docs/ITERATION_LOG.md b/docs/ITERATION_LOG.md
index c7615e9..e93d50b 100644
--- a/docs/ITERATION_LOG.md
+++ b/docs/ITERATION_LOG.md
@@ -158,3 +158,115 @@ No integration code or market data was added. The investigation produced [`docs/
### Decision and next step
Reject embedding Vibe-Trading, importing its internal Python modules, or using it as the current public site's live backend. Keep a read-only MCP/local companion as a conditional experiment. The next bounded step, if pursued, is Stage 0 only: select a legally usable provider and create a cited 8–12 issuer registry across at least four semiconductor stages before installing or invoking Vibe-Trading.
+
+## TG-2026-003 — Establish a deterministic notebook before a finance MCP
+
+- Date opened: 2026-07-17
+- Status: Proposed; implementation and provider testing have not started
+- Scope: Semiconductor market-research handoff, reproducibility, and data rights
+- Owner: TradeGravity maintainer
+
+### Observation
+
+TradeGravity already publishes versioned JSON and includes a small Jupyter example, but the proposed semiconductor-to-market handoff does not yet have a deterministic reference consumer. The request to compare Notebook and finance MCP options is a maintainer hypothesis, not evidence that users need a stock-research workflow.
+
+The [finance handoff assessment](research/FINANCE_HANDOFF_OPTIONS.md) found that notebook and MCP frameworks can both consume financial data, but neither supplies global listing coverage, correct corporate-action treatment, or redistribution rights by itself. A provider-backed MCP also adds an abstraction layer before TradeGravity has a reference result against which to test it.
+
+### Hypothesis and decision signal
+
+If a pinned Quarto or Jupyter analysis consumes a versioned TradeGravity handoff, a cited issuer registry, and synthetic or locally licensed market inputs, the project can test the value of the combined analysis while keeping calculations, provenance, missing states, and license boundaries inspectable.
+
+Advance to an MCP comparison only when all of the following are true:
+
+- the notebook executes from a clean environment without a browser secret or unrecorded network fallback;
+- each result preserves provider, symbol, exchange/MIC, currency, listing type, price-adjustment basis, retrieval time, and unresolved status;
+- split, dividend, ticker-change, stale-response, missing-day, currency, and ADR cases have deterministic tests; and
+- a selected provider confirms the intended storage, display, derived-data, caching, and retention rights in writing.
+
+Stop or redesign if the leading provider cannot return primary listings and corporate actions across the bounded connector-market sample, or if an MCP result differs from the pinned direct-API reference or omits provenance.
+
+### Change
+
+No notebook, MCP server, provider account, API key, or market-data artifact was added. The investigation produced [`docs/research/FINANCE_HANDOFF_OPTIONS.md`](research/FINANCE_HANDOFF_OPTIONS.md), ranked the local and browser notebook surfaces, compared official finance data/MCP options, defined a canonical evidence contract, and specified a staged provider bake-off.
+
+### Evidence
+
+| Evidence type | Date | Result | Interpretation |
+| --- | --- | --- | --- |
+| Repository review | 2026-07-17 | An existing schema-2.0 Jupyter example reads TradeGravity's public JSON, while CI currently does not execute notebooks | Supports extending a familiar project pattern; does not establish that a market handoff is useful or reproducible yet |
+| Official notebook-tool review | 2026-07-17 | Quarto, marimo, Jupyter/JupyterLite, and Observable can produce different combinations of static, local, and browser analysis; browser-WASM variants have package and secret constraints | Supports a pinned local report first; does not prove compatibility with the final package set |
+| Official provider and MCP review | 2026-07-17 | Candidate services expose price, identifier, filing, and corporate-action capabilities, but plan coverage and redistribution conditions vary; broker-linked MCPs add out-of-scope write operations | Supports a direct, read-only provider bake-off before adopting MCP; does not select a canonical provider |
+| Local deterministic proof | Not measured yet | No handoff schema, issuer registry, fixture, or report has been implemented | Required in Stage 0 |
+| External-user value | Not measured yet | No participant has evaluated the combined report | Required before a public feature or MCP integration |
+
+### Decision and next step
+
+Prefer a Quarto `.qmd` plus a small tested Python calculation module as the first reference consumer; a plain Jupyter notebook remains the minimum-friction fallback. Defer finance MCP adoption and reject broker-capable MCPs for this scope. The next bounded step is Stage 0 only: define the handoff, issuer-registry, and market-evidence schemas, then render a no-network report from synthetic corporate-action fixtures and one cited TradeGravity snapshot.
+
+## TG-2026-004 — Derive reviewed distribution drafts from one evidence contract
+
+- Date opened: 2026-07-17
+- Status: Implemented; local verification complete; production and external evaluation pending
+- Scope: Distribution, editorial safety, privacy, and adoption evidence
+- Owner: TradeGravity maintainer
+
+### Observation
+
+The project can generate evidence-grounded analysis, but publishing a newsletter or Instagram carousel separately would risk inconsistent numbers, missing citations, and unsupported automation. TradeGravity is currently a static site with no consent store, sender identity, suppression list, or social-account publishing boundary. The request for email and card-news distribution is a maintainer product hypothesis, not evidence of audience demand.
+
+### Hypothesis and decision signal
+
+If the publisher derives email and social drafts from the same validated semiconductor observations and requires a human review before either leaves the repository, the maintainer can test distribution usefulness without introducing subscriber PII, browser-held secrets, or uncited claims.
+
+Retain the contract when all of the following are true:
+
+- every ready draft has the same three signal kinds, periods, arithmetic, and cited evidence as the published monthly artifacts;
+- the deployed UI never claims that delivery is configured and never collects an email address;
+- an editor can trace every email section and carousel slide to the cited artifact; and
+- at least two of three intended readers say the brief gives them a reason to inspect the underlying Chip Lens.
+
+Do not enable provider sending or direct social publishing until double opt-in, unsubscribe/suppression handling, privacy retention, sender authentication, platform rights, and an explicit approval gate are documented and tested.
+
+### Change
+
+The implementation adds:
+
+- a deterministic `briefing.json` publisher contract with reporter-scale, two-anchor share-shift, and HS6 product signals;
+- review-gated email Markdown and a cited six-slide 4:5 carousel-copy bundle;
+- validator checks for provenance, periods, totals, shares, deltas, ratios, evidence paths, slide roles, and mandatory human review;
+- Chip Lens controls for inspecting signals, downloading both drafts, and copying the evidence entry point; and
+- a fail-closed unavailable state when two comparable monthly periods do not exist; and
+- an offline review-kit builder that emits one-primary-CTA email HTML/Markdown, a cited Instagram caption, two native themes, six matched 1080×1350 SVG/PNG assets, alt text, an approval checklist, and a deterministic hash manifest, plus a read-only manual Actions workflow.
+- a content-release approval contract and CLI that reject modified, missing, or untracked kit files before binding the manifest digest to a reviewer, audience label, time, and approved channels while leaving provider, consent, and automation readiness false.
+- a local email preflight that verifies email content approval, exact private double-opt-in and suppression schemas, audience match, timestamps, unique opaque HTTPS unsubscribe URLs, suppression precedence, and a pilot ceiling before emitting an address/token-free aggregate plan with provider and delivery authorization false.
+- a separate private SQLite subscription service that imports existing consent or runs a default-off double-opt-in form, sends short-lived confirmation mail with stable idempotency, activates only on explicit POST, exports HMAC links and suppression rows, verifies signed Resend feedback, and prevents globally suppressed addresses from reactivation.
+- a fail-closed Resend pilot adapter that requires a one-hour launch approval bound to the exact preflight, sender, audience, content and input digests; reruns all preflight checks at send time; sends one recipient per request with visible/header one-click links; stores only HMAC recipient identities in a private duplicate-prevention ledger; and requires provider-evidence reconciliation plus a different launch approval before retrying confirmed non-acceptance.
+- an aggregate Instagram manual-publish preflight that rechecks the approved kit, PNG dimensions, caption evidence/scope/tags, and alt-text completeness without storing content or credentials and without authorizing a post.
+
+No live provider account, API key, real subscriber record, tracking pixel, social credential, or automatic publishing action was added. The Resend adapter is explicit, local, and inert without private inputs, a matching short-lived authorization, two environment secrets, and `-send-live`.
+
+### Evidence
+
+| Evidence type | Date | Result | Interpretation |
+| --- | --- | --- | --- |
+| Go unit and static checks | 2026-07-17 | `go test ./...` and `go vet ./...` passed | Establishes deterministic calculations and validator behavior; does not establish production-provider coverage or editorial quality |
+| Frontend contract and structure checks | 2026-07-17 | 45 Node tests and JavaScript syntax checks passed | Establishes browser helper behavior and expected UI wiring; does not establish real-user comprehension |
+| Sample publication validation | 2026-07-17 | `cmd/validator` accepted the synthetic three-reporter publication with `briefing.json` | Establishes a network-free end-to-end artifact contract; synthetic values are not real market evidence |
+| Distribution-kit build | 2026-07-17 | The sample briefing produced review-pending email plus six matched SVG/PNG cards with deterministic SHA-256 entries and explicit false send/publish authorization | Establishes repeatable production inputs and safety gates; does not establish provider delivery or audience value |
+| Distribution-kit render | 2026-07-17 | Six SVGs and six embedded-font PNGs decoded at 1080×1350 with no external assets; representative scale, product, and method PNGs were visually inspected; email HTML rendered on desktop and 390px mobile with one primary CTA plus a utility unsubscribe link, no scripts or images, no horizontal overflow, and no console issues | Establishes bounded visual, dimension, and dependency checks; does not establish inbox-client compatibility, accessibility-tool results, Instagram acceptance, or reader comprehension |
+| Content-approval gate | 2026-07-17 | A fixed-time sample approval verified the 20-file manifest, sorted email/Instagram channels, recorded three attestations, refused overwrite, and retained false provider/consent/automatic-publish readiness; tests rejected tampered caption/email content, missing, and untracked files plus manifest changes after approval | Establishes a reproducible content-to-manifest binding; it does not authenticate the reviewer, prove subscriber consent, configure a provider, or authorize a live send/post |
+| Email consent preflight | 2026-07-17 | Reserved-domain fixtures verified two double-opt-in rows, unique opaque HTTPS unsubscribe URLs, one matched suppression, one eligible recipient, exact audience binding, address/token-free JSON, output non-overwrite, and a 25-recipient ceiling; negative tests rejected wrong audience, non-double-opt-in, future consent, full suppression, over-limit audiences, insecure/duplicate/address-exposing URLs, and inputs inside the kit | Establishes deterministic local consent/suppression and unsubscribe-input gating without persisting addresses or tokens in artifacts; it does not prove a production consent store, working unsubscribe endpoint, provider event handling, sender authentication, or live-delivery authorization |
+| Subscription registry and endpoints | 2026-07-17 | Two reserved-domain consents imported into a mode-0600 SQLite registry; exported tokens decoded without email/audience data; GET retained both active rows; invalid-media POST was rejected; valid and repeated one-click POST produced one stable suppression; signed raw-body bounce feedback suppressed one active address, its replay was idempotent, a forged signature was rejected, and a provider-suppressed address was blocked from later import; registry exports passed the email preflight with no address/token leakage | Establishes the reference storage, token, unsubscribe, signed-feedback, replay, global-suppression, and export behavior locally; it does not prove TLS proxy configuration, production durability, original double opt-in, abuse resistance, privacy operations, provider registration, or public availability |
+| Double-opt-in signup | 2026-07-17 | Reserved-domain tests created a short-lived pending request, verified identity-free purpose-separated tokens, kept confirmation GET read-only, activated on explicit POST, made repeats idempotent, retried uncertain confirmation delivery with the same provider key after cooldown, omitted unsubscribe headers before consent, rejected expired tokens, and withheld mail from a globally bounced address | Establishes local consent-state and confirmation-delivery behavior; it does not prove sender-domain authentication, inbox placement, public rate limiting, privacy operations, or production HTTPS durability |
+| Native carousel theme seam | 2026-07-17 | Added an original `editorial-light` renderer alongside the default `intelligence-dark`; both produce deterministic matched SVG/PNG files from the same validated model, retain evidence and false publish authorization, bind the selected theme into the manifest, reject unknown themes, and pass the existing Instagram approval verifier. Representative cover, scale, and CTA PNGs were visually inspected at 1080×1350 with no clipping | Improves presentation choice without adopting an unescaped browser renderer or weakening provenance; it does not establish audience preference, Instagram acceptance, or automatic publishing rights |
+| Carousel palette contrast | 2026-07-17 | Relative-luminance tests measured header, counter/evidence, headline, body, evidence title, and footer against every gradient stop at a minimum 4.5:1, plus 20px bold role labels against their 16%-accent pills at a minimum 3:1. The light muted color improved from a measured 4.07:1 worst case to above the floor, and the regenerated scale card was visually inspected | Establishes deterministic palette-level contrast; it does not replace zoom, low-vision, screen-reader, feed-size, or platform-client testing |
+| Instagram caption draft | 2026-07-17 | The distributor generated a period-labelled caption from all three validated signals, included the evidence entry point and non-causal/non-investment scope note, enforced a project length ceiling, recorded its path and digest in the manifest, and rejected an independently replaced caption at approval | Closes the manual upload-content gap while preserving one-source consistency; it does not prove hashtag performance, link clickability in a client, platform acceptance, or editorial approval |
+| Instagram manual preflight | 2026-07-17 | An aggregate-only CLI required an unchanged Instagram approval, decoded six 1080×1350 PNGs, checked caption length/evidence/scope/unique restrained tags and six alt-text evidence sections, rejected email-only approval and tampering, refused output inside the kit/overwrite, and retained false credential/content/publish flags | Establishes a reproducible local handoff to private platform preview; it does not prove account permissions, Instagram rendering, upload success, reach, or audience value |
+| Provider pilot adapter | 2026-07-17 | Reserved-domain integration tests bound a short-lived launch approval to an unchanged preflight, sent two isolated requests through a synthetic provider, verified visible and RFC one-click links plus distinct idempotency keys, skipped accepted rows, and stopped an uncertain outcome. Provider-confirmed acceptance then remained skipped; confirmed non-acceptance rejected the same authorization and completed only under a different short-lived authorization while retaining its idempotency key. Repeated/contradictory resolutions and PII-bearing audit labels were tested, and a TLS mock verified the Resend HTTP payload and bounded errors | Establishes local launch, rendering, request, reconciliation, and duplicate-safety behavior without leaking addresses/tokens into authorization or ledger files; it does not prove a verified sender domain, inbox delivery, provider-account settings, public webhook operation, or a live consented audience |
+| Maintainer browser inspection | 2026-07-17 | Synthetic publication rendered at 1440×1000 and 390×844 with three ready signals, enabled draft actions, no horizontal overflow, and no console warnings or errors | Establishes a bounded local responsive rendering check; does not replace assistive-technology or external-reader evaluation |
+| Production artifact | Not measured yet | Public `data/briefing.json` has not been verified | Required after merge and a semiconductor refresh |
+| External-reader value | Not measured yet | No reader has evaluated the email or carousel draft | Required before conducting the provider-backed pilot or automating any social distribution |
+
+### Decision and next step
+
+Keep the provider-neutral draft contract and deterministic PNG renderer as a release candidate. Next, verify the public artifact after deployment, use the exported Markdown with a small consented test audience, and privately preview the generated PNG sequence with reviewed alt text before selecting an email provider or enabling any social integration. Direct publishing remains a separate decision after citation legibility, rights, platform, and audience-value review.
diff --git a/docs/UNSUBSCRIBE_SERVICE.md b/docs/UNSUBSCRIBE_SERVICE.md
new file mode 100644
index 0000000..da2d112
--- /dev/null
+++ b/docs/UNSUBSCRIBE_SERVICE.md
@@ -0,0 +1,136 @@
+# Private subscription registry and unsubscribe service
+
+TradeGravity includes a private reference service for double-opt-in signup, working unsubscribe URLs, and durable suppressions. The static dashboard still never receives an address or API key. The separately deployed service can send a short transactional confirmation through Resend, activate consent only after an explicit confirmation POST, import existing verified consent, export private delivery CSVs, and verify signed provider feedback.
+
+## Security boundary
+
+Keep all of the following outside the repository, `site/data/`, GitHub Actions, Actions artifacts, and the distribution kit:
+
+- `subscriptions.db`, its WAL/SHM files, and backups;
+- the source consent CSV;
+- exported subscriber and suppression CSVs; and
+- `TRADEGRAVITY_UNSUBSCRIBE_SECRET`; and
+- `RESEND_WEBHOOK_SECRET` when provider feedback is enabled.
+- `RESEND_API_KEY` when public signup is enabled.
+
+Use a dedicated directory on an encrypted volume with access limited to the operator account. The tools request mode `0600` for the database and exports where supported, but file mode alone is not encryption or a backup policy.
+
+The secret must contain at least 32 bytes and remain stable while issued links are in circulation. Store it in a secret manager or password manager. Rotating or losing it invalidates existing links. The token contains only a version and random 128-bit subscription ID, authenticated with HMAC-SHA-256; it contains no email address or audience label.
+
+## Import verified consent and create private exports
+
+The source CSV must be produced by a real double-opt-in process and have this exact header:
+
+```csv
+email,audience,status,consented_at,consent_method,consent_source,privacy_notice_version
+reader@example.invalid,consented-internal-pilot,active,2026-07-10T01:00:00Z,double_opt_in,website-form,v1
+```
+
+Set the same secret for registry and service processes, then import and export:
+
+```bash
+export TRADEGRAVITY_UNSUBSCRIBE_SECRET='at-least-32-random-secret-bytes'
+
+go run ./cmd/subscription-registry \
+ -db private/subscriptions.db \
+ -base-url https://subscriptions.example.org/tradegravity/ \
+ -consents private/verified-consents.csv \
+ -audience consented-internal-pilot \
+ -out-subscribers private/delivery-subscribers.csv \
+ -out-suppressions private/delivery-suppressions.csv \
+ -imported-at 2026-07-17T12:00:00Z
+```
+
+The command validates active double opt-in, exact audience labels, timestamps, uniqueness, source, and privacy-notice version. It refuses to overwrite exports. Reimporting an active record updates its consent evidence only when it is not older than the stored record. Reimporting a suppressed record never reactivates it.
+
+The subscriber export has the exact preflight schema and a stable, unique HTTPS unsubscribe URL for each active row. The suppression export contains unsubscribed addresses and timestamps. Feed both directly to [`cmd/distribution-preflight`](EMAIL_DELIVERY_PREFLIGHT.md); never copy them into the repository.
+
+## Enable double-opt-in signup
+
+Signup is disabled unless explicitly configured. After publishing the privacy notice and verifying the sender domain, enable it on the same private service:
+
+```bash
+export TRADEGRAVITY_UNSUBSCRIBE_SECRET='the-same-stable-secret'
+export RESEND_API_KEY='read-from-your-secret-manager'
+
+go run ./cmd/unsubscribe-service \
+ -db private/subscriptions.db \
+ -base-url https://subscriptions.example.org/tradegravity/ \
+ -listen 127.0.0.1:8081 \
+ -enable-signup \
+ -signup-audience tradegravity-briefing \
+ -consent-source public-subscribe-form \
+ -privacy-notice-version v1 \
+ -privacy-notice-url https://example.org/privacy \
+ -confirmation-from 'TradeGravity '
+```
+
+The form is `/tradegravity/subscribe` and the confirmation page is `/tradegravity/confirm`. A request creates a pending record for 30 minutes and sends one transactional email with a stable provider idempotency key. The token contains only a random ID. Neither signup nor confirmation responses disclose whether an address was active or globally suppressed. `GET` on the confirmation link is read-only; only a form-encoded `POST` activates the audience membership. An address that previously unsubscribed may re-consent through this flow, while a bounced, complaining, invalid, or provider-suppressed address cannot. Confirmation mail intentionally has no newsletter unsubscribe header because consent has not yet been completed.
+
+The built-in pending-record cap and one-minute resend cooldown are only backstops. Before exposing the form, apply IP/request-rate limits at the reverse proxy, prevent request-body/query logging, monitor aggregate failures, and consider a privacy-preserving challenge. Do not add `RESEND_API_KEY` to the static site or GitHub Actions.
+
+## Run the unsubscribe endpoint
+
+The Go process listens on loopback by default and expects a production TLS reverse proxy:
+
+```bash
+export TRADEGRAVITY_UNSUBSCRIBE_SECRET='the-same-stable-secret'
+
+go run ./cmd/unsubscribe-service \
+ -db private/subscriptions.db \
+ -base-url https://subscriptions.example.org/tradegravity/ \
+ -listen 127.0.0.1:8081
+```
+
+For that base URL, the public endpoint is `/tradegravity/unsubscribe`; `/healthz` checks database readiness.
+
+The reverse proxy must:
+
+- terminate HTTPS and preserve the full path, query string, request body, and method;
+- allow `GET` and form-encoded `POST` on the unsubscribe path;
+- avoid logging the `token` query value or forwarding it to analytics;
+- preserve `Cache-Control: no-store` and the supplied security headers;
+- impose connection and request-rate limits without requiring cookies or login; and
+- keep the service bound to a private interface.
+
+`GET` validates the token and displays a confirmation form but never changes subscription state, preventing ordinary link previews and scanners from silently unsubscribing a reader. A form-encoded `POST` with `List-Unsubscribe=One-Click` records `unsubscribed` once; repeated valid requests succeed without changing the original suppression time. No response includes the subscriber address.
+
+This matches the one-click body defined by [RFC 8058](https://www.rfc-editor.org/rfc/rfc8058.html). The pilot email sender puts the same URL in the visible body and `List-Unsubscribe` header and sets `List-Unsubscribe-Post: List-Unsubscribe=One-Click`; the configured provider/domain must ensure DKIM covers both headers.
+
+## Enable signed Resend feedback
+
+Register only the suppression-relevant Resend events—`email.bounced`, `email.complained`, and `email.suppressed`—against:
+
+```text
+https://subscriptions.example.org/tradegravity/webhooks/resend
+```
+
+Store the endpoint signing secret separately, then enable the route explicitly:
+
+```bash
+export TRADEGRAVITY_UNSUBSCRIBE_SECRET='the-same-stable-secret'
+export RESEND_WEBHOOK_SECRET='whsec_read-from-your-secret-manager'
+
+go run ./cmd/unsubscribe-service \
+ -db private/subscriptions.db \
+ -base-url https://subscriptions.example.org/tradegravity/ \
+ -listen 127.0.0.1:8081 \
+ -enable-resend-webhook
+```
+
+The handler reads at most 64 KiB, verifies the signature against the untouched raw body and `svix-id`, `svix-timestamp`, and `svix-signature` headers, and only then parses the event. It expects one recipient because the pilot sender emits one provider request per recipient. Event IDs are stored without message bodies and deduplicated for at-least-once delivery. A verified event suppresses every active audience membership for the address and creates a global address suppression that blocks later consent imports. Replays return success without changing the original suppression.
+
+The reverse proxy must preserve those three signature headers and the raw body exactly, allow only POST on the feedback path, avoid request/body logging, and return the service response unchanged so Resend can retry failures. Signature verification follows [Resend's raw-body guidance](https://resend.com/docs/webhooks/verify-webhooks-requests); replay handling follows its documented `svix-id` at-least-once contract.
+
+## Current limits
+
+This is a single-instance reference service, not a hosted mailing platform. Before public use, provide and test:
+
+- production abuse protection for sign-up, confirmation, and unsubscribe traffic;
+- encrypted backups, restore drills, retention, deletion, and operator-access audit;
+- monitoring without query-token or address logging;
+- a deployment plan for SQLite durability or a migration to a managed transactional store;
+- production registration, secret rotation, replay drills, and monitoring for the signed feedback endpoint; and
+- authenticated, idempotent launch authorization for delivery.
+
+Do not link the public TradeGravity site to this service until those controls, the privacy notice, verified sender, and public HTTPS deployment are ready.
diff --git a/docs/USAGE.md b/docs/USAGE.md
index 1262c95..50788db 100644
--- a/docs/USAGE.md
+++ b/docs/USAGE.md
@@ -79,3 +79,23 @@ For a network-free pipeline example, `cmd/sampledata` produces a deterministic S
## CSV and filtered views
All explorer controls affect the treemaps and accessible table. **Download CSV** exports the filtered headline rows in raw source units; **Download filtered JSON** also records the active view state. JSON remains the canonical typed representation. See [DATA_SCHEMA.md](DATA_SCHEMA.md) and [DATA_RIGHTS.md](DATA_RIGHTS.md) before redistribution.
+
+## Reviewed email and social drafts
+
+The Chip Lens distribution desk reads `briefing.json` and shows three deterministic, cited observations. **Download email draft** exports Markdown with a link back to the evidence. **Download carousel copy** exports a six-slide, 4:5 JSON copy bundle whose slides retain evidence URLs. **Copy evidence link** returns readers to the Chip Lens rather than to an uncited claim.
+
+Both exports are editorial inputs, not automatic publishing instructions. Review the periods, values, source scope, wording, and rights before use. TradeGravity's static site does not collect email addresses, manage consent or unsubscribes, send mail, or publish to a social account.
+
+For an offline review package with mobile-first email HTML, a cited Instagram caption, two network-free native themes, six matched editable SVG originals and 1080×1350 PNG upload assets, alt text, file hashes, and an approval checklist, run `cmd/distributor` as documented in [DISTRIBUTION.md](DISTRIBUTION.md). Building that package still does not authorize delivery or social publication.
+
+After completing the checklist, use `cmd/distribution-approval` to verify the manifest and record a content release for `email`, `instagram`, or both. The record contains only a non-sensitive audience label and keeps consent, provider delivery, and automatic publishing false; it is not a subscriber list or a send instruction.
+
+For an Instagram-approved kit, run `cmd/instagram-preflight` outside the kit before opening a private platform draft. It rechecks all six PNG dimensions, caption evidence/scope/tags, alt-text completeness, manifest hashes, and channel approval while emitting only aggregate results with `manual_upload_required: true` and `automatic_publish_authorized: false`. See [INSTAGRAM_PREFLIGHT.md](INSTAGRAM_PREFLIGHT.md).
+
+For an email-approved kit, run `cmd/distribution-preflight` locally with private double-opt-in and suppression CSVs as documented in [EMAIL_DELIVERY_PREFLIGHT.md](EMAIL_DELIVERY_PREFLIGHT.md). Each active row must supply its own opaque HTTPS unsubscribe URL. The command applies suppressions, enforces URL uniqueness and the pilot limit, and writes an aggregate-only plan outside the kit without addresses or tokens. It never sends mail and deliberately leaves provider configuration and delivery authorization false.
+
+If the selected provider does not own consent and unsubscribe state, `cmd/subscription-registry` can import existing verified double-opt-in evidence into a separate private SQLite database and export the two preflight CSVs. The default-off signup mode in `cmd/unsubscribe-service` can instead create pending consent, send a short Resend confirmation, and activate only after the reader's explicit POST. The same service handles scanner-safe unsubscribe links and signed suppressions behind an HTTPS reverse proxy. Follow [UNSUBSCRIBE_SERVICE.md](UNSUBSCRIBE_SERVICE.md) before handling real addresses.
+
+For a deliberately bounded Resend pilot, `cmd/email-launch-approval` converts that exact aggregate preflight into a one-hour authorization only after the operator attests sender authentication, feedback suppression, privacy controls, and the final audience. `cmd/email-delivery` then reruns the live preflight, sends one isolated request per eligible recipient, and records only HMAC recipient identities in a private SQLite duplicate-prevention ledger. It remains inert without the matching files, `RESEND_API_KEY`, `TRADEGRAVITY_DELIVERY_SECRET`, and `-send-live`; see [EMAIL_PROVIDER_PILOT.md](EMAIL_PROVIDER_PILOT.md).
+
+If a provider response is uncertain, the ledger blocks every automatic retry. `cmd/email-delivery-reconcile` can record provider-confirmed acceptance or non-acceptance using the private recipient address only to derive the existing HMAC key. Acceptance becomes permanently skippable; confirmed non-acceptance can be retried only with a different short-lived launch authorization. Never delete the ledger to bypass this gate.
diff --git a/examples/sample-data/README.md b/examples/sample-data/README.md
index cc3d801..3ab201f 100644
--- a/examples/sample-data/README.md
+++ b/examples/sample-data/README.md
@@ -1,9 +1,11 @@
# Synthetic sample dataset
-These files follow TradeGravity schema version 2.0 and contain three fictionalized reporter summaries with five annual periods, HS2 chapters, seven customs-visible semiconductor-stage proxies, 12 synthetic monthly periods, bilateral counterpart reports for mirror diagnostics, country context, quality signals, and evidence-grounded explanations. Values are synthetic and must not be used for research, policy, financial, or historical claims. The design/EDA stage remains context-only because services and intangible flows are not represented by the HS6 fixture.
+These files follow TradeGravity schema version 2.0 and contain three fictionalized reporter summaries with five annual periods, HS2 chapters, seven customs-visible semiconductor-stage proxies, 12 synthetic monthly periods, a review-gated distribution briefing, bilateral counterpart reports for mirror diagnostics, country context, quality signals, and evidence-grounded explanations. Values are synthetic and must not be used for research, policy, financial, or historical claims. The design/EDA stage remains context-only because services and intangible flows are not represented by the HS6 fixture.
The sample is intentionally small, deterministic, and network-independent. CI validates it with the same `cmd/validator` used before production deployment.
+`briefing.json` also drives the synthetic distribution tests. CI builds both email and carousel assets, verifies the cited `caption.md`, records a temporary synthetic Instagram approval, and runs the aggregate manual-publish preflight. No social credential or external request is used.
+
To preview it, copy the entire directory contents—including `products/`, `strategic-hs6/`, `semiconductors/`, `bilateral-matrix/`, `mirror/`, and `explanations/`—into the ignored `site/data/` directory and start a static server as described in the root README.
Regenerate the sample without network access:
diff --git a/examples/sample-data/briefing.json b/examples/sample-data/briefing.json
new file mode 100644
index 0000000..75864a2
--- /dev/null
+++ b/examples/sample-data/briefing.json
@@ -0,0 +1,190 @@
+{
+ "schema_version": "1.0",
+ "generated_at": "2026-07-15T19:53:00Z",
+ "edition_id": "semiconductor-pulse-2023-12-20260715T195300Z",
+ "status": "ready",
+ "title": "TradeGravity Semiconductor Pulse",
+ "scope": "Deterministic distribution brief from selected monthly UN Comtrade HS6 observations against USA and China; not a complete semiconductor market, causal claim, or investment recommendation",
+ "latest_period": "2023-12",
+ "previous_period": "2023-11",
+ "publication_status": "baseline",
+ "review_required": true,
+ "signals": [
+ {
+ "id": "monthly-total-kor",
+ "kind": "reporter_total_change",
+ "title": "Korea, Rep. selected chip trade increased",
+ "summary": "Selected monthly HS6 trade with USA and China moved from US$18.91B to US$19.21B (+1.6%).",
+ "reporter_iso3": "KOR",
+ "reporter_name": "Korea, Rep.",
+ "period": "2023-12",
+ "previous_period": "2023-11",
+ "current": {
+ "usa_trade_usd": 9550853736,
+ "china_trade_usd": 9662829262.560001,
+ "total_trade_usd": 19213682998.56,
+ "china_share": 0.502913952691121
+ },
+ "previous": {
+ "usa_trade_usd": 9371308266.666666,
+ "china_trade_usd": 9537108336,
+ "total_trade_usd": 18908416602.666664,
+ "china_share": 0.5043842927945101
+ },
+ "delta_trade_usd": 305266395.89333725,
+ "change_ratio": 0.016144471655563448,
+ "china_share_delta": -0.0014703401033890895,
+ "evidence": [
+ "./semiconductors/monthly/KOR.json",
+ "./semiconductors/monthly/index.json"
+ ],
+ "interpretation": "A change in the selected two-anchor customs observations worth investigating; it does not establish production, demand, or causality.",
+ "measurement_limit": "Selected monthly HS6 observations against USA and China only; subject to source revisions and coverage limits."
+ },
+ {
+ "id": "anchor-share-jpn",
+ "kind": "anchor_share_shift",
+ "title": "Japan two-anchor balance shifted toward USA",
+ "summary": "China's share of the selected USA-plus-China total moved from 50.4% to 50.3% (-0.1 percentage points).",
+ "reporter_iso3": "JPN",
+ "reporter_name": "Japan",
+ "period": "2023-12",
+ "previous_period": "2023-11",
+ "current": {
+ "usa_trade_usd": 8626577568.000002,
+ "china_trade_usd": 8727716753.280003,
+ "total_trade_usd": 17354294321.280006,
+ "china_share": 0.5029139526911209
+ },
+ "previous": {
+ "usa_trade_usd": 8464407466.666669,
+ "china_trade_usd": 8614162368.000002,
+ "total_trade_usd": 17078569834.666672,
+ "china_share": 0.50438429279451
+ },
+ "delta_trade_usd": 275724486.61333466,
+ "change_ratio": 0.01614447165556331,
+ "china_share_delta": -0.0014703401033890895,
+ "evidence": [
+ "./semiconductors/monthly/JPN.json",
+ "./semiconductors/monthly/index.json"
+ ],
+ "interpretation": "The sign describes movement within the published USA-China anchor pair, not political alignment or global market share.",
+ "measurement_limit": "Selected monthly HS6 observations against USA and China only; subject to source revisions and coverage limits."
+ },
+ {
+ "id": "product-kor-854231",
+ "kind": "product_total_change",
+ "title": "Korea, Rep. · Processors and controllers increased",
+ "summary": "HS6 854231 selected trade moved from US$6.14B to US$6.24B (+1.6%).",
+ "reporter_iso3": "KOR",
+ "reporter_name": "Korea, Rep.",
+ "classification": "H6",
+ "code": "854231",
+ "label": "Processors and controllers",
+ "period": "2023-12",
+ "previous_period": "2023-11",
+ "current": {
+ "usa_trade_usd": 3101765760,
+ "china_trade_usd": 3138131289.6000004,
+ "total_trade_usd": 6239897049.6,
+ "china_share": 0.502913952691121
+ },
+ "previous": {
+ "usa_trade_usd": 3043456000,
+ "china_trade_usd": 3097301760,
+ "total_trade_usd": 6140757760,
+ "china_share": 0.5043842927945101
+ },
+ "delta_trade_usd": 99139289.60000038,
+ "change_ratio": 0.0161444716555633,
+ "china_share_delta": -0.0014703401033890895,
+ "evidence": [
+ "./semiconductors/monthly/KOR.json",
+ "./semiconductors/reference.json"
+ ],
+ "interpretation": "This is a product-level customs observation against USA and China, not company revenue, capacity, or a shipment route.",
+ "measurement_limit": "Selected monthly HS6 observations against USA and China only; subject to source revisions and coverage limits."
+ }
+ ],
+ "email": {
+ "subject": "TradeGravity Semiconductor Pulse · 2023-12",
+ "preview": "Three cited USA-China semiconductor observations for 2023-12; monthly movement is kept separate from publication revisions.",
+ "markdown": "# TradeGravity Semiconductor Pulse\n\nObservation window: 2023-12 vs 2023-11 · publication status: baseline\n\n## Korea, Rep. selected chip trade increased\n\nSelected monthly HS6 trade with USA and China moved from US$18.91B to US$19.21B (+1.6%).\n\nInterpretation boundary: A change in the selected two-anchor customs observations worth investigating; it does not establish production, demand, or causality.\n\n## Japan two-anchor balance shifted toward USA\n\nChina's share of the selected USA-plus-China total moved from 50.4% to 50.3% (-0.1 percentage points).\n\nInterpretation boundary: The sign describes movement within the published USA-China anchor pair, not political alignment or global market share.\n\n## Korea, Rep. · Processors and controllers increased\n\nHS6 854231 selected trade moved from US$6.14B to US$6.24B (+1.6%).\n\nInterpretation boundary: This is a product-level customs observation against USA and China, not company revenue, capacity, or a shipment route.\n\nReview the cited evidence before forwarding or publishing this draft.\n\n[Inspect the evidence]({{BASE_URL}}/?tab=semiconductors)\n\nData scope: selected monthly UN Comtrade HS6 observations against USA and China. Not investment, legal, or policy advice.",
+ "cta_label": "Inspect the evidence",
+ "cta_path": "./?tab=semiconductors",
+ "send_policy": "manual_review_required",
+ "primary_goal": "Return the reader to the cited TradeGravity evidence"
+ },
+ "social_carousel": {
+ "format": "carousel_copy",
+ "aspect_ratio": "4:5",
+ "review_policy": "manual_review_required",
+ "slides": [
+ {
+ "order": 1,
+ "role": "cover",
+ "headline": "TradeGravity Semiconductor Pulse",
+ "body": "Three USA-China semiconductor observations · 2023-12 vs 2023-11",
+ "evidence": [
+ "./semiconductors/monthly/index.json"
+ ]
+ },
+ {
+ "order": 2,
+ "role": "scale",
+ "headline": "Korea, Rep. selected chip trade increased",
+ "body": "Selected monthly HS6 trade with USA and China moved from US$18.91B to US$19.21B (+1.6%).",
+ "evidence": [
+ "./semiconductors/monthly/KOR.json",
+ "./semiconductors/monthly/index.json"
+ ]
+ },
+ {
+ "order": 3,
+ "role": "anchor_balance",
+ "headline": "Japan two-anchor balance shifted toward USA",
+ "body": "China's share of the selected USA-plus-China total moved from 50.4% to 50.3% (-0.1 percentage points).",
+ "evidence": [
+ "./semiconductors/monthly/JPN.json",
+ "./semiconductors/monthly/index.json"
+ ]
+ },
+ {
+ "order": 4,
+ "role": "product",
+ "headline": "Korea, Rep. · Processors and controllers increased",
+ "body": "HS6 854231 selected trade moved from US$6.14B to US$6.24B (+1.6%).",
+ "evidence": [
+ "./semiconductors/monthly/KOR.json",
+ "./semiconductors/reference.json"
+ ]
+ },
+ {
+ "order": 5,
+ "role": "method",
+ "headline": "Read the clocks separately",
+ "body": "Month-to-month customs movement and publish-to-publish revisions answer different questions. Neither proves causality or a physical route.",
+ "evidence": [
+ "./changes.json",
+ "./semiconductors/monthly/index.json"
+ ]
+ },
+ {
+ "order": 6,
+ "role": "cta",
+ "headline": "Inspect the evidence",
+ "body": "Open TradeGravity's Chip Lens for periods, values, sources, coverage, and limitations.",
+ "evidence": [
+ "./?tab=semiconductors"
+ ]
+ }
+ ]
+ },
+ "caveats": [
+ "Monthly customs observations can be volatile, incomplete, and revised.",
+ "USA and China values are the two published anchor relationships, not world totals or physical shipment routes.",
+ "Publication-to-publication revisions are separate from economic month-to-month movement."
+ ],
+ "evidence_entry_point": "./?tab=semiconductors"
+}
diff --git a/examples/sample-data/catalog.json b/examples/sample-data/catalog.json
index 7ec1795..e4fc63f 100644
--- a/examples/sample-data/catalog.json
+++ b/examples/sample-data/catalog.json
@@ -113,6 +113,17 @@
"partitioning": "single bounded change feed",
"href": "./changes.json"
},
+ {
+ "id": "distribution_briefing",
+ "title": "Deterministic email and social briefing",
+ "status": "ready",
+ "provider": "tradegravity",
+ "classification": "source HS revision",
+ "product_level": 6,
+ "grain": "edition × selected monthly observation × distribution channel",
+ "partitioning": "single reviewed-draft publication",
+ "href": "./briefing.json"
+ },
{
"id": "mirror_reconciliation",
"title": "Unadjusted mirror-reporting diagnostics",
diff --git a/go.mod b/go.mod
index 813c686..12d9818 100644
--- a/go.mod
+++ b/go.mod
@@ -2,7 +2,11 @@ module tradegravity
go 1.25.12
-require modernc.org/sqlite v1.53.0
+require (
+ github.com/svix/svix-webhooks v1.97.0
+ golang.org/x/image v0.44.0
+ modernc.org/sqlite v1.53.0
+)
require (
github.com/dustin/go-humanize v1.0.1 // indirect
@@ -11,6 +15,7 @@ require (
github.com/ncruces/go-strftime v1.0.0 // indirect
github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec // indirect
golang.org/x/sys v0.44.0 // indirect
+ golang.org/x/text v0.40.0 // indirect
modernc.org/libc v1.73.4 // indirect
modernc.org/mathutil v1.7.1 // indirect
modernc.org/memory v1.11.0 // indirect
diff --git a/go.sum b/go.sum
index b054032..89ae80e 100644
--- a/go.sum
+++ b/go.sum
@@ -6,21 +6,29 @@ github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
github.com/hashicorp/golang-lru/v2 v2.0.7 h1:a+bsQ5rvGLjzHuww6tVxozPZFVghXaHOwFs4luLUK2k=
github.com/hashicorp/golang-lru/v2 v2.0.7/go.mod h1:QeFd9opnmA6QUJc5vARoKUSoFhyfM2/ZepoAG6RGpeM=
+github.com/jarcoal/httpmock v1.3.1 h1:iUx3whfZWVf3jT01hQTO/Eo5sAYtB2/rqaUuOtpInww=
+github.com/jarcoal/httpmock v1.3.1/go.mod h1:3yb8rc4BI7TCBhFY8ng0gjuLKJNquuDNiPaZjnENuYg=
github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY=
github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
github.com/ncruces/go-strftime v1.0.0 h1:HMFp8mLCTPp341M/ZnA4qaf7ZlsbTc+miZjCLOFAw7w=
github.com/ncruces/go-strftime v1.0.0/go.mod h1:Fwc5htZGVVkseilnfgOVb9mKy6w1naJmn9CehxcKcls=
github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec h1:W09IVJc94icq4NjY3clb7Lk8O1qJ8BdBEF8z0ibU0rE=
github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec/go.mod h1:qqbHyh8v60DhA7CoWK5oRCqLrMHRGoxYCSS9EjAz6Eo=
-golang.org/x/mod v0.36.0 h1:JJjpVx6myfUsUdAzZuOSTTmRE0PfZeNWzzvKrP7amb4=
-golang.org/x/mod v0.36.0/go.mod h1:moc6ELqsWcOw5Ef3xVprK5ul/MvtVvkIXLziUOICjUQ=
-golang.org/x/sync v0.20.0 h1:e0PTpb7pjO8GAtTs2dQ6jYa5BWYlMuX047Dco/pItO4=
-golang.org/x/sync v0.20.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
+github.com/svix/svix-webhooks v1.97.0 h1:vm2fM0/Clun0I5sY/35w+TiZV+DSlaDlAbMqfSOKkmg=
+github.com/svix/svix-webhooks v1.97.0/go.mod h1:ngWxEvc1ll097e5kjOQfLz6PqjZTep6ORvGsV4s6mYg=
+golang.org/x/image v0.44.0 h1:+tDekMZED9+LrtB3G5xzRggpVh9CARjZqROla3R3R+I=
+golang.org/x/image v0.44.0/go.mod h1:V8K3KE9KKKE+pLpQDOeN18w9oacNSvy1tDOirTu4xtY=
+golang.org/x/mod v0.37.0 h1:vF1DjpVEshcIqoEaauuHebaLk1O1forxjxBaVn884JQ=
+golang.org/x/mod v0.37.0/go.mod h1:m8S8VeM9r4dzDwjrKO0a1sZP3YjeMamRRlD+fmR2Q/0=
+golang.org/x/sync v0.22.0 h1:SZjpbeLmrCk4xhRSZFNZW5gFUeCeFgjekvI/+gfScek=
+golang.org/x/sync v0.22.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
golang.org/x/sys v0.44.0 h1:ildZl3J4uzeKP07r2F++Op7E9B29JRUy+a27EibtBTQ=
golang.org/x/sys v0.44.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
-golang.org/x/tools v0.45.0 h1:18qN3FAooORvApf5XjCXgsuayZOEtXf6JK18I3+ONa8=
-golang.org/x/tools v0.45.0/go.mod h1:LuUGqqaXcXMEFEruIVJVm5mgDD8vww/z/SR1gQ4uE/0=
+golang.org/x/text v0.40.0 h1:Ub2Z6/xjgF1WrYQz2nuITOEegKFtiIy+rieRJ5lHZKs=
+golang.org/x/text v0.40.0/go.mod h1:hpnzDAfGV753zIKo+wk3u1bVKCGPbrnF7+7LBF/UHVY=
+golang.org/x/tools v0.47.0 h1:7Kn5x/d1svx/PzryTsqeoZN4TZwqeH5pGWjefhLi/1Q=
+golang.org/x/tools v0.47.0/go.mod h1:dFHnyTvFWY212G+h7ZY4Vsp/K3U4/7W9TyVaAul8uCA=
modernc.org/cc/v4 v4.28.4 h1:Hd/4Es+MBj+/7hSdZaisNyu6bv3V0Dp2MdllyfqaH+c=
modernc.org/cc/v4 v4.28.4/go.mod h1:OnovgIhbbMXMu1aISnJ0wvVD1KnW+cAUJkIrAWh+kVI=
modernc.org/ccgo/v4 v4.34.4 h1:OVnSOWQjVKOYkFxoHYB+qQmSHK5gqMqARM+K9DpR/Ws=
diff --git a/internal/deliverypreflight/preflight.go b/internal/deliverypreflight/preflight.go
new file mode 100644
index 0000000..1e78187
--- /dev/null
+++ b/internal/deliverypreflight/preflight.go
@@ -0,0 +1,543 @@
+package deliverypreflight
+
+import (
+ "bytes"
+ "crypto/sha256"
+ "encoding/csv"
+ "encoding/hex"
+ "encoding/json"
+ "errors"
+ "fmt"
+ "io"
+ "net/mail"
+ "net/url"
+ "os"
+ "path/filepath"
+ "sort"
+ "strings"
+ "time"
+ "unicode"
+
+ "tradegravity/internal/distributionkit"
+)
+
+const (
+ schemaVersion = "1.0"
+ toolVersion = "tradegravity-delivery-preflight/1.0"
+ maxSourceSize = 5 << 20
+)
+
+var subscriberHeader = []string{"email", "audience", "status", "consented_at", "consent_method", "consent_source", "privacy_notice_version", "unsubscribe_url"}
+var suppressionHeader = []string{"email", "reason", "suppressed_at"}
+var allowedSuppressionReasons = map[string]bool{
+ "bounced": true,
+ "complaint": true,
+ "invalid": true,
+ "manual": true,
+ "unsubscribed": true,
+}
+
+type Request struct {
+ KitDir string
+ SubscriberCSV string
+ SuppressionCSV string
+ GeneratedAt time.Time
+ MaxRecipients int
+}
+
+type Plan struct {
+ SchemaVersion string `json:"schema_version"`
+ Tool string `json:"tool"`
+ Status string `json:"status"`
+ Channel string `json:"channel"`
+ EditionID string `json:"edition_id"`
+ ManifestSHA256 string `json:"manifest_sha256"`
+ ApprovalSHA256 string `json:"approval_sha256"`
+ Audience string `json:"audience"`
+ GeneratedAt string `json:"generated_at"`
+ Sources SourceProof `json:"sources"`
+ Counts Counts `json:"counts"`
+ MaxRecipients int `json:"max_recipients"`
+ ConsentValidated bool `json:"consent_validated"`
+ SuppressionApplied bool `json:"suppression_applied"`
+ UnsubscribeURLsValidated bool `json:"unsubscribe_urls_validated"`
+ ContainsRecipientAddresses bool `json:"contains_recipient_addresses"`
+ ProviderConfigured bool `json:"provider_configured"`
+ DeliveryAuthorized bool `json:"delivery_authorized"`
+ UnsubscribePlaceholder string `json:"unsubscribe_placeholder"`
+ RequiredProviderHeaders []string `json:"required_provider_headers"`
+ ListUnsubscribePostValue string `json:"list_unsubscribe_post_value"`
+ UnsubscribeHTTPSRequired bool `json:"unsubscribe_https_required"`
+ RequiredDKIMCoveredHeaders []string `json:"required_dkim_covered_headers"`
+ EmailTemplateSHA256 string `json:"email_template_sha256"`
+}
+
+type SourceProof struct {
+ SubscriberCSVSHA256 string `json:"subscriber_csv_sha256"`
+ SuppressionCSVSHA256 string `json:"suppression_csv_sha256"`
+}
+
+type Counts struct {
+ Consented int `json:"consented"`
+ Suppressed int `json:"suppressed"`
+ SuppressionRows int `json:"suppression_rows"`
+ Eligible int `json:"eligible"`
+}
+
+type Result struct {
+ Plan Plan
+ EligibleRecipients []Recipient
+ JSON []byte
+}
+
+type Recipient struct {
+ Email string
+ UnsubscribeURL string
+}
+
+func Build(request Request) (Result, error) {
+ if request.GeneratedAt.IsZero() {
+ return Result{}, errors.New("preflight generation time is required")
+ }
+ if request.MaxRecipients < 1 || request.MaxRecipients > 1000 {
+ return Result{}, errors.New("max recipients must be between 1 and 1000")
+ }
+ kitRoot, err := canonicalDirectory(request.KitDir)
+ if err != nil {
+ return Result{}, err
+ }
+ approval, manifest, err := distributionkit.VerifyApproved(kitRoot, "email")
+ if err != nil {
+ return Result{}, fmt.Errorf("verify approved email kit: %w", err)
+ }
+
+ subscriberRaw, subscriberPath, err := readExternalSource(kitRoot, request.SubscriberCSV, "subscriber CSV")
+ if err != nil {
+ return Result{}, err
+ }
+ suppressionRaw, suppressionPath, err := readExternalSource(kitRoot, request.SuppressionCSV, "suppression CSV")
+ if err != nil {
+ return Result{}, err
+ }
+ if samePath(subscriberPath, suppressionPath) {
+ return Result{}, errors.New("subscriber and suppression CSVs must be different files")
+ }
+
+ consented, err := parseSubscribers(subscriberRaw, approval.Audience, request.GeneratedAt)
+ if err != nil {
+ return Result{}, err
+ }
+ suppressed, suppressionRows, err := parseSuppressions(suppressionRaw, request.GeneratedAt)
+ if err != nil {
+ return Result{}, err
+ }
+ eligible := make([]Recipient, 0, len(consented))
+ matchedSuppressions := 0
+ for _, recipient := range consented {
+ if suppressed[recipient.Email] {
+ matchedSuppressions++
+ continue
+ }
+ eligible = append(eligible, recipient)
+ }
+ if len(eligible) == 0 {
+ return Result{}, errors.New("no eligible recipients remain after suppression")
+ }
+ if len(eligible) > request.MaxRecipients {
+ return Result{}, fmt.Errorf("eligible recipient count %d exceeds pilot limit %d", len(eligible), request.MaxRecipients)
+ }
+ sort.Slice(eligible, func(first, second int) bool {
+ return eligible[first].Email < eligible[second].Email
+ })
+
+ templateRaw, templateDigest, err := verifiedEmailTemplate(kitRoot, manifest)
+ if err != nil {
+ return Result{}, err
+ }
+ if bytes.Count(templateRaw, []byte("{{UNSUBSCRIBE_URL}}")) != 1 {
+ return Result{}, errors.New("approved email template must contain exactly one unsubscribe placeholder")
+ }
+ markdownRaw, err := os.ReadFile(filepath.Join(kitRoot, "email", "body.md"))
+ if err != nil {
+ return Result{}, fmt.Errorf("read approved email Markdown: %w", err)
+ }
+ if bytes.Count(markdownRaw, []byte("{{UNSUBSCRIBE_URL}}")) != 1 {
+ return Result{}, errors.New("approved email Markdown must contain exactly one unsubscribe placeholder")
+ }
+ lowerTemplate := bytes.ToLower(templateRaw)
+ if bytes.Contains(lowerTemplate, []byte(" unicode.MaxASCII || unicode.IsSpace(r) || unicode.IsControl(r) {
+ return "", errors.New("email address must use a plain ASCII addr-spec")
+ }
+ }
+ parsed, err := mail.ParseAddress(value)
+ if err != nil || parsed.Address != value {
+ return "", errors.New("email address must not contain a display name or invalid syntax")
+ }
+ parts := strings.Split(value, "@")
+ if parts[0] == "" || parts[1] == "" || !strings.Contains(parts[1], ".") || strings.HasPrefix(parts[1], ".") || strings.HasSuffix(parts[1], ".") {
+ return "", errors.New("email address must contain a valid-looking domain")
+ }
+ return strings.ToLower(value), nil
+}
+
+func validateTimestamp(value string, generatedAt time.Time, kind string, line int) error {
+ parsed, err := time.Parse(time.RFC3339, value)
+ if err != nil {
+ return fmt.Errorf("CSV line %d has invalid %s timestamp", line, kind)
+ }
+ if parsed.After(generatedAt) {
+ return fmt.Errorf("CSV line %d has future %s timestamp", line, kind)
+ }
+ return nil
+}
+
+func validateLabel(value, name string, line int) error {
+ if value == "" || len([]rune(value)) > 120 {
+ return fmt.Errorf("CSV line %d has invalid %s", line, name)
+ }
+ for _, r := range value {
+ if unicode.IsControl(r) {
+ return fmt.Errorf("CSV line %d has invalid %s", line, name)
+ }
+ }
+ return nil
+}
+
+func verifiedEmailTemplate(kitRoot string, manifest distributionkit.Manifest) ([]byte, string, error) {
+ var declared *distributionkit.ManifestFile
+ for index := range manifest.Files {
+ if manifest.Files[index].Path == "email/body.html" {
+ declared = &manifest.Files[index]
+ break
+ }
+ }
+ if declared == nil {
+ return nil, "", errors.New("approved manifest does not contain email/body.html")
+ }
+ raw, err := os.ReadFile(filepath.Join(kitRoot, "email", "body.html"))
+ if err != nil {
+ return nil, "", fmt.Errorf("read approved email template: %w", err)
+ }
+ digest := sha256.Sum256(raw)
+ value := hex.EncodeToString(digest[:])
+ if value != declared.SHA256 {
+ return nil, "", errors.New("approved email template digest does not match manifest")
+ }
+ return raw, value, nil
+}
+
+func readExternalSource(kitRoot, path, label string) ([]byte, string, error) {
+ path = strings.TrimSpace(path)
+ if path == "" {
+ return nil, "", fmt.Errorf("%s path is required", label)
+ }
+ absolute, err := filepath.Abs(path)
+ if err != nil {
+ return nil, "", fmt.Errorf("resolve %s: %w", label, err)
+ }
+ originalInfo, err := os.Lstat(absolute)
+ if err != nil {
+ return nil, "", fmt.Errorf("inspect %s: %w", label, err)
+ }
+ if originalInfo.Mode()&os.ModeSymlink != 0 {
+ return nil, "", fmt.Errorf("%s must be a regular non-symlink file", label)
+ }
+ resolved, err := filepath.EvalSymlinks(absolute)
+ if err != nil {
+ return nil, "", fmt.Errorf("resolve %s links: %w", label, err)
+ }
+ if pathWithin(kitRoot, resolved) {
+ return nil, "", fmt.Errorf("%s must stay outside the distribution kit", label)
+ }
+ info, err := os.Lstat(resolved)
+ if err != nil {
+ return nil, "", fmt.Errorf("inspect %s: %w", label, err)
+ }
+ if !info.Mode().IsRegular() || info.Mode()&os.ModeSymlink != 0 {
+ return nil, "", fmt.Errorf("%s must be a regular non-symlink file", label)
+ }
+ if info.Size() > maxSourceSize {
+ return nil, "", fmt.Errorf("%s exceeds the %d-byte limit", label, maxSourceSize)
+ }
+ raw, err := os.ReadFile(resolved)
+ if err != nil {
+ return nil, "", fmt.Errorf("read %s: %w", label, err)
+ }
+ return raw, resolved, nil
+}
+
+func canonicalDirectory(path string) (string, error) {
+ path = strings.TrimSpace(path)
+ if path == "" {
+ return "", errors.New("distribution-kit directory is required")
+ }
+ absolute, err := filepath.Abs(path)
+ if err != nil {
+ return "", fmt.Errorf("resolve distribution-kit directory: %w", err)
+ }
+ resolved, err := filepath.EvalSymlinks(absolute)
+ if err != nil {
+ return "", fmt.Errorf("resolve distribution-kit links: %w", err)
+ }
+ info, err := os.Stat(resolved)
+ if err != nil || !info.IsDir() {
+ return "", errors.New("distribution-kit path must be a directory")
+ }
+ return resolved, nil
+}
+
+func pathWithin(root, candidate string) bool {
+ relative, err := filepath.Rel(root, candidate)
+ if err != nil {
+ return false
+ }
+ return relative == "." || (relative != ".." && !strings.HasPrefix(relative, ".."+string(filepath.Separator)))
+}
+
+func samePath(first, second string) bool {
+ return strings.EqualFold(filepath.Clean(first), filepath.Clean(second))
+}
+
+func equalStrings(first, second []string) bool {
+ if len(first) != len(second) {
+ return false
+ }
+ for index := range first {
+ if first[index] != second[index] {
+ return false
+ }
+ }
+ return true
+}
diff --git a/internal/deliverypreflight/preflight_test.go b/internal/deliverypreflight/preflight_test.go
new file mode 100644
index 0000000..fb5dd09
--- /dev/null
+++ b/internal/deliverypreflight/preflight_test.go
@@ -0,0 +1,201 @@
+package deliverypreflight
+
+import (
+ "bytes"
+ "os"
+ "path/filepath"
+ "strings"
+ "testing"
+ "time"
+
+ "tradegravity/internal/distributionkit"
+)
+
+func TestBuildProducesAggregateOnlyConsentPreflight(t *testing.T) {
+ root, kitDir := buildApprovedKit(t)
+ subscribers := writeFixture(t, root, "subscribers.csv", strings.Join([]string{
+ "email,audience,status,consented_at,consent_method,consent_source,privacy_notice_version,unsubscribe_url",
+ "alpha@example.invalid,pilot-audience,active,2026-07-10T01:00:00Z,double_opt_in,website-form,v1,https://subscriptions.example.invalid/u/opaque-alpha-token",
+ "beta@example.invalid,pilot-audience,active,2026-07-11T02:00:00Z,double_opt_in,website-form,v1,https://subscriptions.example.invalid/u/opaque-beta-token",
+ "",
+ }, "\n"))
+ suppressions := writeFixture(t, root, "suppressions.csv", strings.Join([]string{
+ "email,reason,suppressed_at",
+ "beta@example.invalid,unsubscribed,2026-07-12T03:00:00Z",
+ "old@example.invalid,bounced,2026-07-01T00:00:00Z",
+ "",
+ }, "\n"))
+
+ result, err := Build(Request{
+ KitDir: kitDir,
+ SubscriberCSV: subscribers,
+ SuppressionCSV: suppressions,
+ GeneratedAt: time.Date(2026, 7, 17, 12, 0, 0, 0, time.FixedZone("KST", 9*60*60)),
+ MaxRecipients: 25,
+ })
+ if err != nil {
+ t.Fatalf("Build() error = %v", err)
+ }
+ if result.Plan.Status != "consent_preflight_passed" || result.Plan.Channel != "email" || result.Plan.Audience != "pilot-audience" {
+ t.Fatalf("unexpected preflight identity: %+v", result.Plan)
+ }
+ if result.Plan.Counts.Consented != 2 || result.Plan.Counts.Suppressed != 1 || result.Plan.Counts.SuppressionRows != 2 || result.Plan.Counts.Eligible != 1 {
+ t.Fatalf("unexpected preflight counts: %+v", result.Plan.Counts)
+ }
+ if !result.Plan.ConsentValidated || !result.Plan.SuppressionApplied || !result.Plan.UnsubscribeURLsValidated || result.Plan.ContainsRecipientAddresses || result.Plan.ProviderConfigured || result.Plan.DeliveryAuthorized {
+ t.Fatalf("preflight safety state is wrong: %+v", result.Plan)
+ }
+ if strings.Join(result.Plan.RequiredProviderHeaders, ",") != "List-Unsubscribe,List-Unsubscribe-Post" || result.Plan.ListUnsubscribePostValue != "List-Unsubscribe=One-Click" || !result.Plan.UnsubscribeHTTPSRequired || strings.Join(result.Plan.RequiredDKIMCoveredHeaders, ",") != "List-Unsubscribe,List-Unsubscribe-Post" || len(result.Plan.EmailTemplateSHA256) != 64 {
+ t.Fatalf("unsubscribe contract is incomplete: %+v", result.Plan)
+ }
+ if len(result.EligibleRecipients) != 1 || result.EligibleRecipients[0].Email != "alpha@example.invalid" || result.EligibleRecipients[0].UnsubscribeURL != "https://subscriptions.example.invalid/u/opaque-alpha-token" {
+ t.Fatalf("unexpected in-memory eligible recipients: %v", result.EligibleRecipients)
+ }
+ for _, forbidden := range []string{"alpha@example.invalid", "beta@example.invalid", "opaque-alpha-token", "opaque-beta-token", subscribers, suppressions} {
+ if bytes.Contains(result.JSON, []byte(forbidden)) {
+ t.Fatalf("aggregate plan leaked recipient PII or a local path: %s", forbidden)
+ }
+ }
+
+ output := filepath.Join(root, "delivery-preflight.json")
+ if err := Write(output, kitDir, result.JSON); err != nil {
+ t.Fatalf("Write() error = %v", err)
+ }
+ if err := Write(output, kitDir, result.JSON); err == nil {
+ t.Fatal("Write() overwrote an existing preflight")
+ }
+ if err := Write(filepath.Join(kitDir, "delivery-preflight.json"), kitDir, result.JSON); err == nil {
+ t.Fatal("Write() placed recipient-source metadata inside the approved kit")
+ }
+}
+
+func TestBuildFailsClosedForConsentAudienceSuppressionAndLimit(t *testing.T) {
+ root, kitDir := buildApprovedKit(t)
+ emptySuppressions := writeFixture(t, root, "empty-suppressions.csv", "email,reason,suppressed_at\n")
+ generatedAt := time.Date(2026, 7, 17, 12, 0, 0, 0, time.UTC)
+
+ tests := []struct {
+ name string
+ subscribers string
+ suppressions string
+ max int
+ want string
+ }{
+ {
+ name: "wrong audience",
+ subscribers: "email,audience,status,consented_at,consent_method,consent_source,privacy_notice_version,unsubscribe_url\nalpha@example.invalid,another-audience,active,2026-07-10T00:00:00Z,double_opt_in,form,v1,https://subscriptions.example.invalid/u/wrong-audience-token\n",
+ suppressions: emptySuppressions,
+ max: 25,
+ want: "audience does not match",
+ },
+ {
+ name: "single opt in",
+ subscribers: "email,audience,status,consented_at,consent_method,consent_source,privacy_notice_version,unsubscribe_url\nalpha@example.invalid,pilot-audience,active,2026-07-10T00:00:00Z,single_opt_in,form,v1,https://subscriptions.example.invalid/u/single-token\n",
+ suppressions: emptySuppressions,
+ max: 25,
+ want: "not active double opt-in",
+ },
+ {
+ name: "pilot limit",
+ subscribers: "email,audience,status,consented_at,consent_method,consent_source,privacy_notice_version,unsubscribe_url\nalpha@example.invalid,pilot-audience,active,2026-07-10T00:00:00Z,double_opt_in,form,v1,https://subscriptions.example.invalid/u/limit-alpha-token\nbeta@example.invalid,pilot-audience,active,2026-07-10T00:00:00Z,double_opt_in,form,v1,https://subscriptions.example.invalid/u/limit-beta-token\n",
+ suppressions: emptySuppressions,
+ max: 1,
+ want: "exceeds pilot limit",
+ },
+ {
+ name: "fully suppressed",
+ subscribers: "email,audience,status,consented_at,consent_method,consent_source,privacy_notice_version,unsubscribe_url\nalpha@example.invalid,pilot-audience,active,2026-07-10T00:00:00Z,double_opt_in,form,v1,https://subscriptions.example.invalid/u/suppressed-token\n",
+ suppressions: "email,reason,suppressed_at\nalpha@example.invalid,complaint,2026-07-11T00:00:00Z\n",
+ max: 25,
+ want: "no eligible recipients",
+ },
+ {
+ name: "insecure unsubscribe URL",
+ subscribers: "email,audience,status,consented_at,consent_method,consent_source,privacy_notice_version,unsubscribe_url\nalpha@example.invalid,pilot-audience,active,2026-07-10T00:00:00Z,double_opt_in,form,v1,http://subscriptions.example.invalid/u/insecure-token\n",
+ suppressions: emptySuppressions,
+ max: 25,
+ want: "must be absolute HTTPS",
+ },
+ {
+ name: "address in unsubscribe URL",
+ subscribers: "email,audience,status,consented_at,consent_method,consent_source,privacy_notice_version,unsubscribe_url\nalpha@example.invalid,pilot-audience,active,2026-07-10T00:00:00Z,double_opt_in,form,v1,https://subscriptions.example.invalid/u/alpha%40example.invalid\n",
+ suppressions: emptySuppressions,
+ max: 25,
+ want: "must not expose an email address",
+ },
+ {
+ name: "duplicate unsubscribe URL",
+ subscribers: "email,audience,status,consented_at,consent_method,consent_source,privacy_notice_version,unsubscribe_url\nalpha@example.invalid,pilot-audience,active,2026-07-10T00:00:00Z,double_opt_in,form,v1,https://subscriptions.example.invalid/u/shared-token\nbeta@example.invalid,pilot-audience,active,2026-07-10T00:00:00Z,double_opt_in,form,v1,https://subscriptions.example.invalid/u/shared-token\n",
+ suppressions: emptySuppressions,
+ max: 25,
+ want: "duplicates an unsubscribe URL",
+ },
+ {
+ name: "future consent",
+ subscribers: "email,audience,status,consented_at,consent_method,consent_source,privacy_notice_version,unsubscribe_url\nalpha@example.invalid,pilot-audience,active,2026-07-18T00:00:00Z,double_opt_in,form,v1,https://subscriptions.example.invalid/u/future-token\n",
+ suppressions: emptySuppressions,
+ max: 25,
+ want: "future consent timestamp",
+ },
+ }
+ for _, test := range tests {
+ t.Run(test.name, func(t *testing.T) {
+ subscriberPath := writeFixture(t, root, strings.ReplaceAll(test.name, " ", "-")+"-subscribers.csv", test.subscribers)
+ suppressionPath := test.suppressions
+ if !filepath.IsAbs(suppressionPath) {
+ suppressionPath = writeFixture(t, root, strings.ReplaceAll(test.name, " ", "-")+"-suppressions.csv", test.suppressions)
+ }
+ _, err := Build(Request{KitDir: kitDir, SubscriberCSV: subscriberPath, SuppressionCSV: suppressionPath, GeneratedAt: generatedAt, MaxRecipients: test.max})
+ if err == nil || !strings.Contains(err.Error(), test.want) {
+ t.Fatalf("Build() error = %v, want %q", err, test.want)
+ }
+ })
+ }
+
+ insideKit := filepath.Join(kitDir, "email", "body.md")
+ _, err := Build(Request{KitDir: kitDir, SubscriberCSV: insideKit, SuppressionCSV: emptySuppressions, GeneratedAt: generatedAt, MaxRecipients: 25})
+ if err == nil || !strings.Contains(err.Error(), "outside the distribution kit") {
+ t.Fatalf("Build() inside-kit source error = %v", err)
+ }
+}
+
+func buildApprovedKit(t *testing.T) (string, string) {
+ t.Helper()
+ root := t.TempDir()
+ briefingPath := filepath.Join("..", "..", "examples", "sample-data", "briefing.json")
+ briefing, err := os.ReadFile(briefingPath)
+ if err != nil {
+ t.Fatal(err)
+ }
+ bundle, err := distributionkit.Build(briefing, "https://example.org/TradeGravity/")
+ if err != nil {
+ t.Fatal(err)
+ }
+ kitDir := filepath.Join(root, "kit")
+ if err := distributionkit.Write(kitDir, bundle); err != nil {
+ t.Fatal(err)
+ }
+ _, approvalRaw, err := distributionkit.Approve(kitDir, distributionkit.ApprovalRequest{
+ Reviewer: "reviewer",
+ Audience: "pilot-audience",
+ Channels: []string{"email"},
+ ApprovedAt: time.Date(2026, 7, 17, 0, 0, 0, 0, time.UTC),
+ Attested: true,
+ })
+ if err != nil {
+ t.Fatal(err)
+ }
+ if err := distributionkit.WriteApproval(kitDir, approvalRaw); err != nil {
+ t.Fatal(err)
+ }
+ return root, kitDir
+}
+
+func writeFixture(t *testing.T, root, name, content string) string {
+ t.Helper()
+ path := filepath.Join(root, name)
+ if err := os.WriteFile(path, []byte(content), 0o600); err != nil {
+ t.Fatal(err)
+ }
+ return path
+}
diff --git a/internal/distributionkit/approval.go b/internal/distributionkit/approval.go
new file mode 100644
index 0000000..d69dc3e
--- /dev/null
+++ b/internal/distributionkit/approval.go
@@ -0,0 +1,431 @@
+package distributionkit
+
+import (
+ "bytes"
+ "crypto/sha256"
+ "encoding/hex"
+ "encoding/json"
+ "errors"
+ "fmt"
+ "io"
+ "io/fs"
+ "os"
+ "path/filepath"
+ "sort"
+ "strings"
+ "time"
+)
+
+const (
+ approvalSchemaVersion = "1.0"
+ approvalScope = "content_release"
+)
+
+var allowedApprovalChannels = map[string]bool{
+ "email": true,
+ "instagram": true,
+}
+
+var contentApprovalAttestations = []string{
+ "evidence_periods_values_and_units_reviewed",
+ "claims_caveats_links_and_rights_reviewed",
+ "final_channel_assets_and_alt_text_reviewed",
+}
+
+type ApprovalRequest struct {
+ Reviewer string
+ Audience string
+ Channels []string
+ ApprovedAt time.Time
+ Attested bool
+}
+
+type Approval struct {
+ SchemaVersion string `json:"schema_version"`
+ Tool string `json:"tool"`
+ Scope string `json:"scope"`
+ Status string `json:"status"`
+ EditionID string `json:"edition_id"`
+ ManifestSHA256 string `json:"manifest_sha256"`
+ ManifestFileCount int `json:"manifest_file_count"`
+ ApprovedAt string `json:"approved_at"`
+ Reviewer string `json:"reviewer"`
+ Audience string `json:"audience"`
+ Channels []string `json:"channels"`
+ Attestations []string `json:"attestations"`
+ ProviderDeliveryReady bool `json:"provider_delivery_ready"`
+ SubscriberConsentReady bool `json:"subscriber_consent_ready"`
+ AutomaticPublishReady bool `json:"automatic_publish_ready"`
+}
+
+func Approve(kitDir string, request ApprovalRequest) (Approval, []byte, error) {
+ if err := validateApprovalRequest(request); err != nil {
+ return Approval{}, nil, err
+ }
+ manifest, manifestRaw, err := Verify(kitDir)
+ if err != nil {
+ return Approval{}, nil, err
+ }
+ digest := sha256.Sum256(manifestRaw)
+ channels := append([]string(nil), request.Channels...)
+ sort.Strings(channels)
+ approval := Approval{
+ SchemaVersion: approvalSchemaVersion,
+ Tool: kitToolVersion,
+ Scope: approvalScope,
+ Status: "approved",
+ EditionID: manifest.EditionID,
+ ManifestSHA256: hex.EncodeToString(digest[:]),
+ ManifestFileCount: len(manifest.Files),
+ ApprovedAt: request.ApprovedAt.UTC().Format(time.RFC3339),
+ Reviewer: strings.TrimSpace(request.Reviewer),
+ Audience: strings.TrimSpace(request.Audience),
+ Channels: channels,
+ Attestations: append([]string(nil), contentApprovalAttestations...),
+ ProviderDeliveryReady: false,
+ SubscriberConsentReady: false,
+ AutomaticPublishReady: false,
+ }
+ raw, err := json.MarshalIndent(approval, "", " ")
+ if err != nil {
+ return Approval{}, nil, fmt.Errorf("encode approval: %w", err)
+ }
+ return approval, append(raw, '\n'), nil
+}
+
+func Verify(kitDir string) (Manifest, []byte, error) {
+ return verifyKit(kitDir, false)
+}
+
+func VerifyApproved(kitDir, requiredChannel string) (Approval, Manifest, error) {
+ requiredChannel = strings.TrimSpace(requiredChannel)
+ if !allowedApprovalChannels[requiredChannel] {
+ return Approval{}, Manifest{}, fmt.Errorf("unsupported required channel %q", requiredChannel)
+ }
+ root, err := cleanKitRoot(kitDir)
+ if err != nil {
+ return Approval{}, Manifest{}, err
+ }
+ manifest, manifestRaw, err := verifyKit(root, true)
+ if err != nil {
+ return Approval{}, Manifest{}, err
+ }
+ approvalRaw, err := os.ReadFile(filepath.Join(root, "approval.json"))
+ if err != nil {
+ return Approval{}, Manifest{}, fmt.Errorf("read approval.json: %w", err)
+ }
+ var approval Approval
+ decoder := json.NewDecoder(bytes.NewReader(approvalRaw))
+ decoder.DisallowUnknownFields()
+ if err := decoder.Decode(&approval); err != nil {
+ return Approval{}, Manifest{}, fmt.Errorf("decode approval.json: %w", err)
+ }
+ if err := decoder.Decode(&struct{}{}); !errors.Is(err, io.EOF) {
+ return Approval{}, Manifest{}, errors.New("approval.json contains trailing JSON values")
+ }
+ canonicalApproval, err := marshalCanonicalJSON(approval)
+ if err != nil {
+ return Approval{}, Manifest{}, fmt.Errorf("canonicalize approval.json: %w", err)
+ }
+ if !bytes.Equal(approvalRaw, canonicalApproval) {
+ return Approval{}, Manifest{}, errors.New("approval.json must use the canonical generated encoding")
+ }
+ if err := validateStoredApproval(approval, manifest, manifestRaw, requiredChannel); err != nil {
+ return Approval{}, Manifest{}, err
+ }
+ return approval, manifest, nil
+}
+
+func verifyKit(kitDir string, allowApproval bool) (Manifest, []byte, error) {
+ root, err := cleanKitRoot(kitDir)
+ if err != nil {
+ return Manifest{}, nil, err
+ }
+ manifestPath := filepath.Join(root, "manifest.json")
+ manifestInfo, err := os.Lstat(manifestPath)
+ if err != nil {
+ return Manifest{}, nil, fmt.Errorf("inspect manifest: %w", err)
+ }
+ if !manifestInfo.Mode().IsRegular() {
+ return Manifest{}, nil, errors.New("manifest.json must be a regular file")
+ }
+ manifestRaw, err := os.ReadFile(manifestPath)
+ if err != nil {
+ return Manifest{}, nil, fmt.Errorf("read manifest: %w", err)
+ }
+ var manifest Manifest
+ decoder := json.NewDecoder(bytes.NewReader(manifestRaw))
+ decoder.DisallowUnknownFields()
+ if err := decoder.Decode(&manifest); err != nil {
+ return Manifest{}, nil, fmt.Errorf("decode manifest: %w", err)
+ }
+ if err := decoder.Decode(&struct{}{}); !errors.Is(err, io.EOF) {
+ return Manifest{}, nil, errors.New("manifest contains trailing JSON values")
+ }
+ canonicalManifest, err := marshalCanonicalJSON(manifest)
+ if err != nil {
+ return Manifest{}, nil, fmt.Errorf("canonicalize manifest: %w", err)
+ }
+ if !bytes.Equal(manifestRaw, canonicalManifest) {
+ return Manifest{}, nil, errors.New("manifest.json must use the canonical generated encoding")
+ }
+ if err := validateApprovalManifest(manifest); err != nil {
+ return Manifest{}, nil, err
+ }
+
+ expected := map[string]ManifestFile{"manifest.json": {Path: "manifest.json"}}
+ if allowApproval {
+ expected["approval.json"] = ManifestFile{Path: "approval.json"}
+ }
+ previousPath := ""
+ for _, item := range manifest.Files {
+ if !fs.ValidPath(item.Path) || strings.Contains(item.Path, "\\") || item.Path == "." || item.Path == "manifest.json" || item.Path == "approval.json" {
+ return Manifest{}, nil, fmt.Errorf("manifest contains invalid file path %q", item.Path)
+ }
+ if item.Path <= previousPath {
+ return Manifest{}, nil, errors.New("manifest files must be unique and sorted by path")
+ }
+ previousPath = item.Path
+ if item.MediaType != mediaType(item.Path) || item.Bytes < 0 || len(item.SHA256) != sha256.Size*2 {
+ return Manifest{}, nil, fmt.Errorf("manifest metadata is invalid for %s", item.Path)
+ }
+ if _, err := hex.DecodeString(item.SHA256); err != nil {
+ return Manifest{}, nil, fmt.Errorf("manifest digest is invalid for %s", item.Path)
+ }
+ expected[item.Path] = item
+ }
+
+ seen := map[string]bool{}
+ err = filepath.WalkDir(root, func(path string, entry fs.DirEntry, walkErr error) error {
+ if walkErr != nil {
+ return walkErr
+ }
+ if path == root {
+ return nil
+ }
+ if entry.Type()&os.ModeSymlink != 0 {
+ return fmt.Errorf("distribution kit must not contain symlinks: %s", entry.Name())
+ }
+ if entry.IsDir() {
+ return nil
+ }
+ if !entry.Type().IsRegular() {
+ return fmt.Errorf("distribution kit contains a non-regular file: %s", entry.Name())
+ }
+ relative, relErr := filepath.Rel(root, path)
+ if relErr != nil {
+ return relErr
+ }
+ relative = filepath.ToSlash(relative)
+ item, ok := expected[relative]
+ if !ok {
+ return fmt.Errorf("distribution kit contains untracked file %q", relative)
+ }
+ seen[relative] = true
+ if relative == "manifest.json" || relative == "approval.json" {
+ return nil
+ }
+ content, readErr := os.ReadFile(path)
+ if readErr != nil {
+ return readErr
+ }
+ if len(content) != item.Bytes {
+ return fmt.Errorf("distribution file size changed: %s", relative)
+ }
+ digest := sha256.Sum256(content)
+ if !strings.EqualFold(hex.EncodeToString(digest[:]), item.SHA256) {
+ return fmt.Errorf("distribution file digest changed: %s", relative)
+ }
+ return nil
+ })
+ if err != nil {
+ return Manifest{}, nil, fmt.Errorf("verify distribution kit: %w", err)
+ }
+ if len(seen) != len(expected) {
+ missing := make([]string, 0)
+ for path := range expected {
+ if !seen[path] {
+ missing = append(missing, path)
+ }
+ }
+ sort.Strings(missing)
+ return Manifest{}, nil, fmt.Errorf("distribution kit is missing files: %s", strings.Join(missing, ", "))
+ }
+ return manifest, manifestRaw, nil
+}
+
+func WriteApproval(kitDir string, content []byte) error {
+ root, err := cleanKitRoot(kitDir)
+ if err != nil {
+ return err
+ }
+ target := filepath.Join(root, "approval.json")
+ file, err := os.OpenFile(target, os.O_WRONLY|os.O_CREATE|os.O_EXCL, 0o644)
+ if err != nil {
+ if errors.Is(err, fs.ErrExist) {
+ return errors.New("approval.json already exists; rebuild the kit for a new approval")
+ }
+ return fmt.Errorf("create approval.json: %w", err)
+ }
+ writeErr := func() error {
+ if _, err := file.Write(content); err != nil {
+ return err
+ }
+ return file.Sync()
+ }()
+ closeErr := file.Close()
+ if writeErr != nil {
+ _ = os.Remove(target)
+ return fmt.Errorf("write approval.json: %w", writeErr)
+ }
+ if closeErr != nil {
+ _ = os.Remove(target)
+ return fmt.Errorf("close approval.json: %w", closeErr)
+ }
+ return nil
+}
+
+func validateApprovalRequest(request ApprovalRequest) error {
+ if !request.Attested {
+ return errors.New("explicit review attestation is required")
+ }
+ if err := validateApprovalLabel("reviewer", request.Reviewer, 100); err != nil {
+ return err
+ }
+ if err := validateApprovalAudience(request.Audience); err != nil {
+ return err
+ }
+ if request.ApprovedAt.IsZero() {
+ return errors.New("approval time is required")
+ }
+ if len(request.Channels) == 0 {
+ return errors.New("at least one approval channel is required")
+ }
+ seen := map[string]bool{}
+ for _, channel := range request.Channels {
+ if channel != strings.TrimSpace(channel) || !allowedApprovalChannels[channel] {
+ return fmt.Errorf("unsupported approval channel %q", channel)
+ }
+ if seen[channel] {
+ return fmt.Errorf("duplicate approval channel %q", channel)
+ }
+ seen[channel] = true
+ }
+ return nil
+}
+
+func validateApprovalLabel(name, value string, limit int) error {
+ trimmed := strings.TrimSpace(value)
+ if trimmed == "" || len([]rune(trimmed)) > limit {
+ return fmt.Errorf("%s must contain 1-%d characters", name, limit)
+ }
+ for _, r := range trimmed {
+ if r < 0x20 || r == 0x7f {
+ return fmt.Errorf("%s must not contain control characters", name)
+ }
+ }
+ return nil
+}
+
+func validateApprovalAudience(value string) error {
+ if err := validateApprovalLabel("audience", value, 120); err != nil {
+ return err
+ }
+ if strings.ContainsAny(value, "@/\\") || strings.Contains(value, "://") {
+ return errors.New("audience must be a non-sensitive label, not an address or path")
+ }
+ return nil
+}
+
+func validateApprovalManifest(manifest Manifest) error {
+ if manifest.SchemaVersion != kitSchemaVersion || manifest.Tool != kitToolVersion || !safeIdentifier(manifest.EditionID) {
+ return errors.New("manifest provenance does not match the distribution-kit contract")
+ }
+ if manifest.DistributionStatus != "review_pending" || !manifest.ReviewRequired || manifest.SendAuthorized || manifest.SocialPublishAuthorized {
+ return errors.New("only an unchanged review-pending kit can be approved")
+ }
+ if len(manifest.Files) == 0 || manifest.Carousel.Width != cardWidth || manifest.Carousel.Height != cardHeight || manifest.Carousel.SlideCount != 6 {
+ return errors.New("manifest content contract is incomplete")
+ }
+ if _, err := resolveTheme(manifest.Carousel.Theme); err != nil || strings.TrimSpace(manifest.Carousel.Theme) == "" {
+ return errors.New("manifest carousel theme is unsupported")
+ }
+ if manifest.Carousel.CaptionPath != "carousel/caption.md" {
+ return errors.New("manifest carousel caption contract is incomplete")
+ }
+ if strings.Join(manifest.Carousel.Formats, ",") != "png,svg" {
+ return errors.New("manifest must contain matched PNG and SVG carousel assets")
+ }
+ return nil
+}
+
+func validateStoredApproval(approval Approval, manifest Manifest, manifestRaw []byte, requiredChannel string) error {
+ if approval.SchemaVersion != approvalSchemaVersion || approval.Tool != kitToolVersion || approval.Scope != approvalScope || approval.Status != "approved" {
+ return errors.New("approval.json does not match the content-release contract")
+ }
+ if approval.EditionID != manifest.EditionID || approval.ManifestFileCount != len(manifest.Files) {
+ return errors.New("approval.json does not match the manifest edition")
+ }
+ digest := sha256.Sum256(manifestRaw)
+ if approval.ManifestSHA256 != hex.EncodeToString(digest[:]) {
+ return errors.New("approval.json manifest digest does not match")
+ }
+ if err := validateApprovalLabel("reviewer", approval.Reviewer, 100); err != nil {
+ return fmt.Errorf("invalid stored approval: %w", err)
+ }
+ if err := validateApprovalAudience(approval.Audience); err != nil {
+ return fmt.Errorf("invalid stored approval: %w", err)
+ }
+ approvedAt, err := time.Parse(time.RFC3339, approval.ApprovedAt)
+ if err != nil || approvedAt.UTC().Format(time.RFC3339) != approval.ApprovedAt {
+ return errors.New("approval.json must contain a canonical UTC approval time")
+ }
+ if strings.Join(approval.Attestations, "\n") != strings.Join(contentApprovalAttestations, "\n") {
+ return errors.New("approval.json attestations do not match the content-release contract")
+ }
+ if approval.ProviderDeliveryReady || approval.SubscriberConsentReady || approval.AutomaticPublishReady {
+ return errors.New("content approval must not claim provider, consent, or automatic-publish readiness")
+ }
+ foundRequired := false
+ previous := ""
+ for _, channel := range approval.Channels {
+ if !allowedApprovalChannels[channel] || channel <= previous {
+ return errors.New("approval.json channels must be unique, supported, and sorted")
+ }
+ previous = channel
+ if channel == requiredChannel {
+ foundRequired = true
+ }
+ }
+ if !foundRequired {
+ return fmt.Errorf("content is not approved for channel %q", requiredChannel)
+ }
+ return nil
+}
+
+func cleanKitRoot(kitDir string) (string, error) {
+ kitDir = strings.TrimSpace(kitDir)
+ if kitDir == "" {
+ return "", errors.New("distribution-kit directory is required")
+ }
+ root, err := filepath.Abs(kitDir)
+ if err != nil {
+ return "", fmt.Errorf("resolve distribution-kit directory: %w", err)
+ }
+ info, err := os.Stat(root)
+ if err != nil {
+ return "", fmt.Errorf("inspect distribution-kit directory: %w", err)
+ }
+ if !info.IsDir() {
+ return "", errors.New("distribution-kit path must be a directory")
+ }
+ return root, nil
+}
+
+func marshalCanonicalJSON(value any) ([]byte, error) {
+ raw, err := json.MarshalIndent(value, "", " ")
+ if err != nil {
+ return nil, err
+ }
+ return append(raw, '\n'), nil
+}
diff --git a/internal/distributionkit/approval_test.go b/internal/distributionkit/approval_test.go
new file mode 100644
index 0000000..ab3eaff
--- /dev/null
+++ b/internal/distributionkit/approval_test.go
@@ -0,0 +1,189 @@
+package distributionkit
+
+import (
+ "bytes"
+ "encoding/json"
+ "os"
+ "path/filepath"
+ "strings"
+ "testing"
+ "time"
+)
+
+func TestApproveBindsReviewedContentWithoutClaimingDeliveryReadiness(t *testing.T) {
+ kitDir := buildWrittenKit(t)
+ request := ApprovalRequest{
+ Reviewer: "maintainer-handle",
+ Audience: "consented-internal-pilot",
+ Channels: []string{"instagram", "email"},
+ ApprovedAt: time.Date(2026, 7, 17, 12, 34, 56, 0, time.FixedZone("KST", 9*60*60)),
+ Attested: true,
+ }
+ approval, raw, err := Approve(kitDir, request)
+ if err != nil {
+ t.Fatalf("Approve() error = %v", err)
+ }
+ if approval.Scope != "content_release" || approval.Status != "approved" || strings.Join(approval.Channels, ",") != "email,instagram" {
+ t.Fatalf("unexpected approval contract: %+v", approval)
+ }
+ if approval.ProviderDeliveryReady || approval.SubscriberConsentReady || approval.AutomaticPublishReady {
+ t.Fatalf("content approval overclaims delivery readiness: %+v", approval)
+ }
+ if approval.ApprovedAt != "2026-07-17T03:34:56Z" || len(approval.ManifestSHA256) != 64 || approval.ManifestFileCount != 20 {
+ t.Fatalf("approval provenance is incomplete: %+v", approval)
+ }
+ if len(approval.Attestations) != 3 || !bytes.HasSuffix(raw, []byte("\n")) {
+ t.Fatalf("approval attestation serialization is incomplete: %s", raw)
+ }
+ if err := WriteApproval(kitDir, raw); err != nil {
+ t.Fatalf("WriteApproval() error = %v", err)
+ }
+ verified, verifiedManifest, err := VerifyApproved(kitDir, "email")
+ if err != nil {
+ t.Fatalf("VerifyApproved() error = %v", err)
+ }
+ if verified.ManifestSHA256 != approval.ManifestSHA256 || verifiedManifest.EditionID != approval.EditionID {
+ t.Fatal("VerifyApproved() did not preserve the approval-manifest binding")
+ }
+ if _, _, err := VerifyApproved(kitDir, "instagram"); err != nil {
+ t.Fatalf("VerifyApproved() rejected an approved channel: %v", err)
+ }
+ if err := WriteApproval(kitDir, raw); err == nil {
+ t.Fatal("WriteApproval() overwrote an existing approval")
+ }
+ stored, err := os.ReadFile(filepath.Join(kitDir, "approval.json"))
+ if err != nil || !bytes.Equal(stored, raw) {
+ t.Fatalf("stored approval mismatch: err=%v", err)
+ }
+}
+
+func TestVerifyApprovedRejectsUnapprovedChannelAndManifestChange(t *testing.T) {
+ kitDir := buildWrittenKit(t)
+ approval, raw, err := Approve(kitDir, validApprovalRequest())
+ if err != nil {
+ t.Fatal(err)
+ }
+ if err := WriteApproval(kitDir, raw); err != nil {
+ t.Fatal(err)
+ }
+ if _, _, err := VerifyApproved(kitDir, "instagram"); err == nil || !strings.Contains(err.Error(), "not approved") {
+ t.Fatalf("VerifyApproved() unapproved-channel error = %v", err)
+ }
+
+ manifestPath := filepath.Join(kitDir, "manifest.json")
+ manifestRaw, err := os.ReadFile(manifestPath)
+ if err != nil {
+ t.Fatal(err)
+ }
+ var manifest Manifest
+ if err := json.Unmarshal(manifestRaw, &manifest); err != nil {
+ t.Fatal(err)
+ }
+ manifest.PrimaryGoal = "modified after approval"
+ changed, _ := json.MarshalIndent(manifest, "", " ")
+ if err := os.WriteFile(manifestPath, append(changed, '\n'), 0o644); err != nil {
+ t.Fatal(err)
+ }
+ if _, _, err := VerifyApproved(kitDir, approval.Channels[0]); err == nil || !strings.Contains(err.Error(), "digest does not match") {
+ t.Fatalf("VerifyApproved() changed-manifest error = %v", err)
+ }
+}
+
+func TestApproveRejectsTamperedMissingAndUntrackedFiles(t *testing.T) {
+ t.Run("tampered", func(t *testing.T) {
+ kitDir := buildWrittenKit(t)
+ path := filepath.Join(kitDir, "email", "body.html")
+ if err := os.WriteFile(path, []byte("changed"), 0o644); err != nil {
+ t.Fatal(err)
+ }
+ if _, _, err := Approve(kitDir, validApprovalRequest()); err == nil || !strings.Contains(err.Error(), "size changed") {
+ t.Fatalf("Approve() tamper error = %v", err)
+ }
+ })
+
+ t.Run("caption-tampered", func(t *testing.T) {
+ kitDir := buildWrittenKit(t)
+ path := filepath.Join(kitDir, "carousel", "caption.md")
+ if err := os.WriteFile(path, []byte("uncited replacement caption\n"), 0o644); err != nil {
+ t.Fatal(err)
+ }
+ if _, _, err := Approve(kitDir, validApprovalRequest()); err == nil || (!strings.Contains(err.Error(), "size changed") && !strings.Contains(err.Error(), "digest changed")) {
+ t.Fatalf("Approve() caption tamper error = %v", err)
+ }
+ })
+
+ t.Run("missing", func(t *testing.T) {
+ kitDir := buildWrittenKit(t)
+ if err := os.Remove(filepath.Join(kitDir, "carousel", "slide-06.png")); err != nil {
+ t.Fatal(err)
+ }
+ if _, _, err := Approve(kitDir, validApprovalRequest()); err == nil || !strings.Contains(err.Error(), "missing files") {
+ t.Fatalf("Approve() missing-file error = %v", err)
+ }
+ })
+
+ t.Run("untracked", func(t *testing.T) {
+ kitDir := buildWrittenKit(t)
+ if err := os.WriteFile(filepath.Join(kitDir, "recipient-list.csv"), []byte("must not be stored here"), 0o644); err != nil {
+ t.Fatal(err)
+ }
+ if _, _, err := Approve(kitDir, validApprovalRequest()); err == nil || !strings.Contains(err.Error(), "untracked file") {
+ t.Fatalf("Approve() untracked-file error = %v", err)
+ }
+ })
+}
+
+func TestApproveRejectsMissingAttestationAndUnsafeManifest(t *testing.T) {
+ kitDir := buildWrittenKit(t)
+ request := validApprovalRequest()
+ request.Attested = false
+ if _, _, err := Approve(kitDir, request); err == nil || !strings.Contains(err.Error(), "attestation") {
+ t.Fatalf("Approve() attestation error = %v", err)
+ }
+ request = validApprovalRequest()
+ request.Audience = "reader@example.invalid"
+ if _, _, err := Approve(kitDir, request); err == nil || !strings.Contains(err.Error(), "non-sensitive label") {
+ t.Fatalf("Approve() sensitive-audience error = %v", err)
+ }
+
+ manifestPath := filepath.Join(kitDir, "manifest.json")
+ raw, err := os.ReadFile(manifestPath)
+ if err != nil {
+ t.Fatal(err)
+ }
+ var manifest Manifest
+ if err := json.Unmarshal(raw, &manifest); err != nil {
+ t.Fatal(err)
+ }
+ manifest.SendAuthorized = true
+ unsafeRaw, _ := marshalCanonicalJSON(manifest)
+ if err := os.WriteFile(manifestPath, unsafeRaw, 0o644); err != nil {
+ t.Fatal(err)
+ }
+ if _, _, err := Approve(kitDir, validApprovalRequest()); err == nil || !strings.Contains(err.Error(), "review-pending") {
+ t.Fatalf("Approve() unsafe-manifest error = %v", err)
+ }
+}
+
+func buildWrittenKit(t *testing.T) string {
+ t.Helper()
+ bundle, err := Build(readSampleBriefing(t), "https://example.org/TradeGravity/")
+ if err != nil {
+ t.Fatal(err)
+ }
+ kitDir := filepath.Join(t.TempDir(), "kit")
+ if err := Write(kitDir, bundle); err != nil {
+ t.Fatal(err)
+ }
+ return kitDir
+}
+
+func validApprovalRequest() ApprovalRequest {
+ return ApprovalRequest{
+ Reviewer: "reviewer",
+ Audience: "internal-pilot",
+ Channels: []string{"email"},
+ ApprovedAt: time.Date(2026, 7, 17, 0, 0, 0, 0, time.UTC),
+ Attested: true,
+ }
+}
diff --git a/internal/distributionkit/kit.go b/internal/distributionkit/kit.go
new file mode 100644
index 0000000..06fa48e
--- /dev/null
+++ b/internal/distributionkit/kit.go
@@ -0,0 +1,617 @@
+package distributionkit
+
+import (
+ "crypto/sha256"
+ "encoding/hex"
+ "encoding/json"
+ "errors"
+ "fmt"
+ "html"
+ "io/fs"
+ "net"
+ "net/url"
+ "os"
+ "path/filepath"
+ "sort"
+ "strings"
+)
+
+const (
+ kitSchemaVersion = "1.0"
+ kitToolVersion = "tradegravity-distributor/1.1"
+ captionRuneLimit = 1800
+)
+
+var readySignalKinds = []string{"reporter_total_change", "anchor_share_shift", "product_total_change"}
+var readySlideRoles = []string{"cover", "scale", "anchor_balance", "product", "method", "cta"}
+
+type briefing struct {
+ SchemaVersion string `json:"schema_version"`
+ GeneratedAt string `json:"generated_at"`
+ EditionID string `json:"edition_id"`
+ Status string `json:"status"`
+ Title string `json:"title"`
+ Scope string `json:"scope"`
+ LatestPeriod string `json:"latest_period"`
+ PreviousPeriod string `json:"previous_period"`
+ ReviewRequired bool `json:"review_required"`
+ Signals []signal `json:"signals"`
+ Email emailDraft `json:"email"`
+ SocialCarousel carousel `json:"social_carousel"`
+ Caveats []string `json:"caveats"`
+ EvidenceEntryPoint string `json:"evidence_entry_point"`
+}
+
+type signal struct {
+ ID string `json:"id"`
+ Kind string `json:"kind"`
+ Title string `json:"title"`
+ Summary string `json:"summary"`
+ Period string `json:"period"`
+ PreviousPeriod string `json:"previous_period"`
+ Evidence []string `json:"evidence"`
+}
+
+type emailDraft struct {
+ Subject string `json:"subject"`
+ Preview string `json:"preview"`
+ Markdown string `json:"markdown"`
+ CTALabel string `json:"cta_label"`
+ CTAPath string `json:"cta_path"`
+ SendPolicy string `json:"send_policy"`
+ PrimaryGoal string `json:"primary_goal"`
+}
+
+type carousel struct {
+ Format string `json:"format"`
+ AspectRatio string `json:"aspect_ratio"`
+ ReviewPolicy string `json:"review_policy"`
+ Slides []slide `json:"slides"`
+}
+
+type slide struct {
+ Order int `json:"order"`
+ Role string `json:"role"`
+ Headline string `json:"headline"`
+ Body string `json:"body"`
+ Evidence []string `json:"evidence"`
+}
+
+type Manifest struct {
+ SchemaVersion string `json:"schema_version"`
+ Tool string `json:"tool"`
+ EditionID string `json:"edition_id"`
+ SourceGeneratedAt string `json:"source_generated_at"`
+ DistributionStatus string `json:"distribution_status"`
+ ReviewRequired bool `json:"review_required"`
+ SendAuthorized bool `json:"send_authorized"`
+ SocialPublishAuthorized bool `json:"social_publish_authorized"`
+ BaseURL string `json:"base_url"`
+ PrimaryGoal string `json:"primary_goal"`
+ Email ManifestEmail `json:"email"`
+ Carousel ManifestSocial `json:"carousel"`
+ Files []ManifestFile `json:"files"`
+}
+
+type ManifestEmail struct {
+ Subject string `json:"subject"`
+ Preview string `json:"preview"`
+ CTAURL string `json:"cta_url"`
+}
+
+type ManifestSocial struct {
+ Theme string `json:"theme"`
+ CaptionPath string `json:"caption_path"`
+ AspectRatio string `json:"aspect_ratio"`
+ Width int `json:"width"`
+ Height int `json:"height"`
+ SlideCount int `json:"slide_count"`
+ Formats []string `json:"formats"`
+}
+
+type ManifestFile struct {
+ Path string `json:"path"`
+ MediaType string `json:"media_type"`
+ Bytes int `json:"bytes"`
+ SHA256 string `json:"sha256"`
+}
+
+type Bundle struct {
+ Manifest Manifest
+ Files map[string][]byte
+}
+
+func Build(raw []byte, baseURL string) (Bundle, error) {
+ return BuildWithOptions(raw, baseURL, BuildOptions{})
+}
+
+func BuildWithOptions(raw []byte, baseURL string, options BuildOptions) (Bundle, error) {
+ theme, err := resolveTheme(options.Theme)
+ if err != nil {
+ return Bundle{}, err
+ }
+ var source briefing
+ if err := json.Unmarshal(raw, &source); err != nil {
+ return Bundle{}, fmt.Errorf("decode briefing: %w", err)
+ }
+ if err := validateBriefing(source); err != nil {
+ return Bundle{}, err
+ }
+ root, err := normalizeBaseURL(baseURL)
+ if err != nil {
+ return Bundle{}, err
+ }
+
+ ctaURL, err := resolveRootReference(root, source.Email.CTAPath)
+ if err != nil {
+ return Bundle{}, fmt.Errorf("resolve email CTA: %w", err)
+ }
+ files := map[string][]byte{
+ "email/subject.txt": []byte(source.Email.Subject + "\n"),
+ "email/preview.txt": []byte(source.Email.Preview + "\n"),
+ "email/body.md": renderEmailMarkdown(source, root),
+ "email/body.html": renderEmailHTML(source, ctaURL),
+ "REVIEW.md": renderReviewChecklist(source, root),
+ }
+ fonts, err := newSlideFonts()
+ if err != nil {
+ return Bundle{}, err
+ }
+ defer fonts.Close()
+
+ for _, item := range source.SocialCarousel.Slides {
+ svgPath := fmt.Sprintf("carousel/slide-%02d.svg", item.Order)
+ files[svgPath] = renderSlideSVG(source, item, root, theme)
+ pngPath := fmt.Sprintf("carousel/slide-%02d.png", item.Order)
+ pngContent, renderErr := renderSlidePNG(source, item, compactBaseURL(root), fonts, theme)
+ if renderErr != nil {
+ return Bundle{}, renderErr
+ }
+ files[pngPath] = pngContent
+ }
+ files["carousel/alt-text.md"] = renderAltText(source, root)
+ caption, err := renderInstagramCaption(source, root)
+ if err != nil {
+ return Bundle{}, err
+ }
+ files["carousel/caption.md"] = caption
+ files["carousel/index.html"] = renderCarouselIndex(source)
+
+ manifest := Manifest{
+ SchemaVersion: kitSchemaVersion,
+ Tool: kitToolVersion,
+ EditionID: source.EditionID,
+ SourceGeneratedAt: source.GeneratedAt,
+ DistributionStatus: "review_pending",
+ ReviewRequired: true,
+ SendAuthorized: false,
+ SocialPublishAuthorized: false,
+ BaseURL: root.String(),
+ PrimaryGoal: source.Email.PrimaryGoal,
+ Email: ManifestEmail{
+ Subject: source.Email.Subject,
+ Preview: source.Email.Preview,
+ CTAURL: ctaURL,
+ },
+ Carousel: ManifestSocial{
+ Theme: theme.name,
+ CaptionPath: "carousel/caption.md",
+ AspectRatio: "4:5",
+ Width: 1080,
+ Height: 1350,
+ SlideCount: len(source.SocialCarousel.Slides),
+ Formats: []string{"png", "svg"},
+ },
+ }
+ paths := make([]string, 0, len(files))
+ for path := range files {
+ paths = append(paths, path)
+ }
+ sort.Strings(paths)
+ for _, path := range paths {
+ content := files[path]
+ digest := sha256.Sum256(content)
+ manifest.Files = append(manifest.Files, ManifestFile{
+ Path: path,
+ MediaType: mediaType(path),
+ Bytes: len(content),
+ SHA256: hex.EncodeToString(digest[:]),
+ })
+ }
+ manifestJSON, err := json.MarshalIndent(manifest, "", " ")
+ if err != nil {
+ return Bundle{}, fmt.Errorf("encode manifest: %w", err)
+ }
+ files["manifest.json"] = append(manifestJSON, '\n')
+ return Bundle{Manifest: manifest, Files: files}, nil
+}
+
+func Write(outputDir string, bundle Bundle) error {
+ outputDir = strings.TrimSpace(outputDir)
+ if outputDir == "" {
+ return errors.New("output directory is required")
+ }
+ abs, err := filepath.Abs(outputDir)
+ if err != nil {
+ return fmt.Errorf("resolve output directory: %w", err)
+ }
+ if _, err := os.Stat(abs); err == nil {
+ return fmt.Errorf("output directory already exists: %s", abs)
+ } else if !errors.Is(err, os.ErrNotExist) {
+ return fmt.Errorf("inspect output directory: %w", err)
+ }
+ parent := filepath.Dir(abs)
+ if err := os.MkdirAll(parent, 0o755); err != nil {
+ return fmt.Errorf("create output parent: %w", err)
+ }
+ tempDir, err := os.MkdirTemp(parent, ".tradegravity-distribution-*")
+ if err != nil {
+ return fmt.Errorf("create temporary output: %w", err)
+ }
+ defer os.RemoveAll(tempDir)
+
+ paths := make([]string, 0, len(bundle.Files))
+ for path := range bundle.Files {
+ paths = append(paths, path)
+ }
+ sort.Strings(paths)
+ for _, path := range paths {
+ if !fs.ValidPath(path) || path == "." {
+ return fmt.Errorf("invalid bundle path %q", path)
+ }
+ target := filepath.Join(tempDir, filepath.FromSlash(path))
+ if err := os.MkdirAll(filepath.Dir(target), 0o755); err != nil {
+ return fmt.Errorf("create bundle directory for %s: %w", path, err)
+ }
+ if err := os.WriteFile(target, bundle.Files[path], 0o644); err != nil {
+ return fmt.Errorf("write bundle file %s: %w", path, err)
+ }
+ }
+ if err := os.Rename(tempDir, abs); err != nil {
+ return fmt.Errorf("publish distribution kit: %w", err)
+ }
+ return nil
+}
+
+func validateBriefing(source briefing) error {
+ if source.SchemaVersion != "1.0" || source.Status != "ready" {
+ return errors.New("briefing must be a ready schema 1.0 artifact")
+ }
+ if strings.TrimSpace(source.GeneratedAt) == "" || !safeIdentifier(source.EditionID) {
+ return errors.New("briefing has invalid provenance")
+ }
+ if !source.ReviewRequired || source.Email.SendPolicy != "manual_review_required" || source.SocialCarousel.ReviewPolicy != "manual_review_required" {
+ return errors.New("briefing must require manual review for email and social output")
+ }
+ if source.SocialCarousel.Format != "carousel_copy" || source.SocialCarousel.AspectRatio != "4:5" {
+ return errors.New("briefing carousel must use the reviewed 4:5 copy contract")
+ }
+ if len(source.Signals) != len(readySignalKinds) || len(source.SocialCarousel.Slides) != len(readySlideRoles) {
+ return errors.New("briefing must contain three signals and six slides")
+ }
+ if strings.TrimSpace(source.Email.Subject) == "" || strings.TrimSpace(source.Email.Preview) == "" || strings.TrimSpace(source.Email.Markdown) == "" || strings.TrimSpace(source.Email.CTALabel) == "" || strings.TrimSpace(source.Email.PrimaryGoal) == "" {
+ return errors.New("briefing email contract is incomplete")
+ }
+ if !validRelativeHref(source.Email.CTAPath) || !validRelativeHref(source.EvidenceEntryPoint) {
+ return errors.New("briefing contains an invalid evidence entry point")
+ }
+ for index, item := range source.Signals {
+ if item.Kind != readySignalKinds[index] || strings.TrimSpace(item.ID) == "" || strings.TrimSpace(item.Title) == "" || strings.TrimSpace(item.Summary) == "" {
+ return fmt.Errorf("briefing signal %d does not match the ready contract", index+1)
+ }
+ if item.Period != source.LatestPeriod || item.PreviousPeriod != source.PreviousPeriod || len(item.Evidence) < 2 {
+ return fmt.Errorf("briefing signal %s does not share the edition period and evidence", item.ID)
+ }
+ for _, href := range item.Evidence {
+ if !validRelativeHref(href) {
+ return fmt.Errorf("briefing signal %s has invalid evidence", item.ID)
+ }
+ }
+ }
+ for index, item := range source.SocialCarousel.Slides {
+ if item.Order != index+1 || item.Role != readySlideRoles[index] || strings.TrimSpace(item.Headline) == "" || strings.TrimSpace(item.Body) == "" || len(item.Evidence) == 0 {
+ return fmt.Errorf("briefing slide %d does not match the ready contract", index+1)
+ }
+ for _, href := range item.Evidence {
+ if !validRelativeHref(href) {
+ return fmt.Errorf("briefing slide %d has invalid evidence", item.Order)
+ }
+ }
+ }
+ return nil
+}
+
+func normalizeBaseURL(value string) (*url.URL, error) {
+ parsed, err := url.Parse(strings.TrimSpace(value))
+ if err != nil || parsed.Host == "" {
+ return nil, errors.New("base URL must be an absolute HTTPS URL")
+ }
+ loopback := parsed.Scheme == "http" && isLoopbackHost(parsed.Hostname())
+ if parsed.Scheme != "https" && !loopback {
+ return nil, errors.New("base URL must use HTTPS except for a loopback preview")
+ }
+ if parsed.User != nil || parsed.RawQuery != "" || parsed.Fragment != "" {
+ return nil, errors.New("base URL must not contain credentials, query parameters, or a fragment")
+ }
+ if !strings.HasSuffix(parsed.Path, "/") {
+ parsed.Path += "/"
+ }
+ return parsed, nil
+}
+
+func isLoopbackHost(host string) bool {
+ if strings.EqualFold(host, "localhost") {
+ return true
+ }
+ ip := net.ParseIP(host)
+ return ip != nil && ip.IsLoopback()
+}
+
+func safeIdentifier(value string) bool {
+ if value == "" {
+ return false
+ }
+ for _, r := range value {
+ if (r >= 'a' && r <= 'z') || (r >= 'A' && r <= 'Z') || (r >= '0' && r <= '9') || r == '-' || r == '_' || r == '.' {
+ continue
+ }
+ return false
+ }
+ return true
+}
+
+func validRelativeHref(value string) bool {
+ if !strings.HasPrefix(value, "./") || strings.Contains(value, "\\") || strings.ContainsAny(value, "\r\n") {
+ return false
+ }
+ parsed, err := url.Parse(value)
+ if err != nil || parsed.IsAbs() || parsed.Host != "" {
+ return false
+ }
+ for _, part := range strings.Split(parsed.Path, "/") {
+ if part == ".." {
+ return false
+ }
+ }
+ return true
+}
+
+func resolveRootReference(root *url.URL, href string) (string, error) {
+ if !validRelativeHref(href) {
+ return "", errors.New("reference must be a safe same-origin relative path")
+ }
+ ref, err := url.Parse(href)
+ if err != nil {
+ return "", err
+ }
+ return root.ResolveReference(ref).String(), nil
+}
+
+func resolveEvidenceReference(root *url.URL, href string) string {
+ if !validRelativeHref(href) {
+ return ""
+ }
+ ref, _ := url.Parse(href)
+ if ref.RawQuery != "" && (ref.Path == "." || ref.Path == "./" || ref.Path == "") {
+ return root.ResolveReference(ref).String()
+ }
+ dataRef, _ := url.Parse("data/")
+ dataRoot := root.ResolveReference(dataRef)
+ return dataRoot.ResolveReference(ref).String()
+}
+
+func materializeMarkdown(markdown string, root *url.URL) string {
+ base := strings.TrimSuffix(root.String(), "/")
+ return strings.ReplaceAll(markdown, "{{BASE_URL}}", base)
+}
+
+func renderEmailHTML(source briefing, ctaURL string) []byte {
+ var body strings.Builder
+ body.WriteString("\n")
+ body.WriteString("" + html.EscapeString(source.Email.Subject) + "")
+ body.WriteString("")
+ body.WriteString("
![\"%s\"](\"slide-%02d.png\")