nx_supp_formula.nx source
↩ module page · 350 lines · 12982 B
1// nx_supp_formula.nx -- SUPPLEMENT GTM SUITE / FORMULATION + FEASIBILITY rung.
2// Takes a product concept and runs it all the way to a go/no-go: is it legal,
3// does it physically fit a dosage form, what does it cost to make, and does
4// it clear a margin at the price you want to sell it for. Then it runs the
5// same arithmetic BACKWARDS -- from a retail price and a target margin to the
6// ingredient budget you actually have to spend.
7//
8// THREE GATES, IN THE ORDER THAT ACTUALLY KILLS PRODUCTS.
9//
10// 1. LEGAL. One precluded ingredient and there is no product, regardless of
11// how good the formula is. sf_regulatory_verdict NAMES the blocking
12// ingredient rather than returning a bare no -- the same discipline as the
13// hurdle model naming which barrier holds, because "rejected" without
14// "why" gets argued with instead of fixed.
15//
16// 2. PHYSICAL. A dose is a VOLUME before it is a number on a label. Run the
17// clinically studied doses of a full botanical + amino stack and it comes
18// to roughly ten and a half millilitres -- ELEVEN size-00 capsules per
19// serving. Nobody takes eleven capsules. This is the arithmetic behind
20// why so much of the category is under-dosed: the label dose was chosen to
21// fit the capsule, not to match the trial. The honest response is to
22// change the FORMAT, not to quietly cut the dose, and sf_capsules_needed
23// makes that choice explicit instead of accidental.
24//
25// 3. ECONOMIC. At eleven capsules a serving the shells and the encapsulation
26// labour cost about as much as the actives do, so the format decision is
27// also the margin decision -- chemistry and cost point the same way.
28//
29// FAIRY-DUSTING IS DETECTED, NOT ACCOMMODATED. sf_dose_adequacy_permil
30// compares each dose against the low end of the clinically studied range, so
31// a formula carrying a token 50 mg of something trialled at 600 mg is flagged
32// as what it is. Threshold in a named constant, not buried in a branch.
33//
34// COSTS ARE INDICATIVE (see nx_supp_ingredient). Conversion figures are
35// typical contract-manufacturer rates and move with run size; treat every
36// number here as a model to be replaced by quotes, not as a budget.
37//
38// Units: mg, microlitres, CENTS. Margins and adequacy in per-mil.
39//
40// Grounding (cited; researcher-groundable):
41// dshea_21usc321_ff_dietary_ingredient_definition (via nx_supp_ingredient)
42// standard_capsule_shell_volumes_000_to_3
43// contract_manufacturer_encapsulation_rate_ranges
44//
45// genealogy_id: supplement_gtm + nishi_food_science_suite
46
47import "nx_syscalls.nx"
48import "nx_supp_ingredient.nx"
49const SF_MAGIC_1000000: i64 = 1000000
50
51// ===== Verdicts (sealed) ==============================================
52
53const SF_REFUSED_EMPTY: i64 = 0
54const SF_MARKETABLE: i64 = 1
55const SF_REFUSED_DRUG: i64 = 2
56const SF_REFUSED_NOT_DIETARY: i64 = 3
57const SF_REFUSED_UNKNOWN: i64 = 4
58
59// ===== Dosage form ====================================================
60
61const SF_FORMAT_CAPSULE: i64 = 1
62const SF_FORMAT_POWDER: i64 = 2
63
64// Conversion economics, cents. Typical contract rates; scale with run size.
65const SF_SHELL_COST_CENTS: i64 = 1 // per capsule shell
66const SF_ENCAP_COST_CENTS: i64 = 2 // per capsule filled (rounded up)
67const SF_BOTTLE_COST_CENTS: i64 = 50
68const SF_LABEL_COST_CENTS: i64 = 15
69const SF_POWDER_SCOOP_CENTS: i64 = 10
70
71// A dose below this fraction of the clinically studied low end is fairy dust.
72const SF_FAIRY_DUST_PERMIL: i64 = 500
73
74// Every dietary supplement label carries the DSHEA disclaimer. Not optional.
75const SF_DSHEA_DISCLAIMER_REQUIRED: i64 = 1
76
77// ===== The formula ====================================================
78
79struct NxSuppFormula {
80 doses: *i64,
81 n_ing: i64,
82 valid: i64,
83}
84
85func nx_supp_formula_new() -> *NxSuppFormula {
86 let f: *NxSuppFormula = (sys_mmap(32)) as *NxSuppFormula
87 f.doses = (sys_mmap(SI_N * 8)) as *i64
88 f.n_ing = 0
89 f.valid = 1
90 return f
91}
92
93// Set a dose in mg. An out-of-catalog id poisons the formula -- an unknown
94// substance must never be silently dropped from a product it is really in.
95func sf_set_dose(f: *NxSuppFormula, id: i64, dose_mg: i64) -> i64 {
96 if si_valid_id(id) != 1 { f.valid = 0; return 0 }
97 if dose_mg < 0 { f.valid = 0; return 0 }
98 let d: *i64 = f.doses
99 let prev: i64 = d[id]
100 d[id] = dose_mg
101 if prev == 0 {
102 if dose_mg > 0 { f.n_ing = f.n_ing + 1 }
103 }
104 return f.valid
105}
106
107// Load every ingredient at its clinically studied low-end dose.
108func sf_set_clinical(f: *NxSuppFormula, id: i64) -> i64 {
109 let d: i64 = si_clinical_dose_mg(id)
110 return sf_set_dose(f, id, d)
111}
112
113func sf_dose_of(f: *NxSuppFormula, id: i64) -> i64 {
114 if si_valid_id(id) != 1 { return 0 }
115 let d: *i64 = f.doses
116 return d[id]
117}
118
119// ===== Gate 1: legality ===============================================
120
121// The first ingredient that blocks the product, or SI_INVALID if none.
122func sf_first_blocking(f: *NxSuppFormula) -> i64 {
123 var i: i64 = 0
124 var found: i64 = SI_INVALID
125 while i < SI_N {
126 if found == SI_INVALID {
127 let dose: i64 = sf_dose_of(f, i)
128 if dose > 0 {
129 let ok: i64 = si_is_lawful_dietary(i)
130 if ok != 1 { found = i }
131 }
132 }
133 i = i + 1
134 }
135 return found
136}
137
138func sf_regulatory_verdict(f: *NxSuppFormula) -> i64 {
139 if f.valid != 1 { return SF_REFUSED_UNKNOWN }
140 if f.n_ing <= 0 { return SF_REFUSED_EMPTY }
141 let bad: i64 = sf_first_blocking(f)
142 if bad == SI_INVALID { return SF_MARKETABLE }
143 let c: i64 = si_class(bad)
144 if c == SI_CLASS_DRUG { return SF_REFUSED_DRUG }
145 if c == SI_CLASS_NOT_DIETARY { return SF_REFUSED_NOT_DIETARY }
146 return SF_REFUSED_UNKNOWN
147}
148
149func sf_is_marketable(f: *NxSuppFormula) -> i64 {
150 let v: i64 = sf_regulatory_verdict(f)
151 if v == SF_MARKETABLE { return 1 }
152 return 0
153}
154
155// ===== Gate 2: physical form ==========================================
156
157func sf_total_mass_mg(f: *NxSuppFormula) -> i64 {
158 var i: i64 = 0
159 var sum: i64 = 0
160 while i < SI_N {
161 let d: i64 = sf_dose_of(f, i)
162 sum = sum + d
163 i = i + 1
164 }
165 return sum
166}
167
168// Total volume of one serving, microlitres. REFUSES if any dosed ingredient
169// has no density -- an unmeasurable volume must not read as a small one.
170func sf_total_volume_ul(f: *NxSuppFormula) -> i64 {
171 var i: i64 = 0
172 var sum: i64 = 0
173 var bad: i64 = 0
174 while i < SI_N {
175 let d: i64 = sf_dose_of(f, i)
176 if d > 0 {
177 let v: i64 = si_dose_volume_ul(i, d)
178 if v == SI_INVALID { bad = 1 }
179 if v != SI_INVALID { sum = sum + v }
180 }
181 i = i + 1
182 }
183 if bad == 1 { return SI_INVALID }
184 return sum
185}
186
187// Capsules per serving for a given shell, rounding UP -- you cannot ship 10.4
188// capsules, and rounding down would under-deliver the dose.
189func sf_capsules_needed(f: *NxSuppFormula, shell_ul: i64) -> i64 {
190 let vol: i64 = sf_total_volume_ul(f)
191 if vol == SI_INVALID { return SI_INVALID }
192 if vol <= 0 { return 0 }
193 let usable: i64 = si_capsule_usable_ul(shell_ul)
194 if usable <= 0 { return SI_INVALID }
195 let n: i64 = vol / usable
196 let rem: i64 = vol - n * usable
197 if rem > 0 { return n + 1 }
198 return n
199}
200
201func sf_fits_in_capsules(f: *NxSuppFormula, shell_ul: i64, max_caps: i64) -> i64 {
202 let n: i64 = sf_capsules_needed(f, shell_ul)
203 if n == SI_INVALID { return 0 }
204 if n <= max_caps { return 1 }
205 return 0
206}
207
208// The single largest volume contributor -- the ingredient to reformulate,
209// move to a separate powder, or drop. Answers "what is making this ten
210// capsules" instead of leaving it to be guessed.
211func sf_bulkiest_ingredient(f: *NxSuppFormula) -> i64 {
212 var i: i64 = 0
213 var best: i64 = SI_INVALID
214 var bestv: i64 = 0
215 while i < SI_N {
216 let d: i64 = sf_dose_of(f, i)
217 if d > 0 {
218 let v: i64 = si_dose_volume_ul(i, d)
219 if v != SI_INVALID {
220 if v > bestv { bestv = v; best = i }
221 }
222 }
223 i = i + 1
224 }
225 return best
226}
227
228// ===== Dose honesty ===================================================
229
230// Dose as a fraction of the clinically studied low end, per-mil.
231// SI_INVALID when there is no clinical dose to compare against, so a caller
232// cannot mistake "no reference" for "adequate".
233func sf_dose_adequacy_permil(f: *NxSuppFormula, id: i64) -> i64 {
234 let clin: i64 = si_clinical_dose_mg(id)
235 if clin <= 0 { return SI_INVALID }
236 let d: i64 = sf_dose_of(f, id)
237 return d * 1000 / clin
238}
239
240func sf_is_fairy_dusted(f: *NxSuppFormula, id: i64) -> i64 {
241 let a: i64 = sf_dose_adequacy_permil(f, id)
242 if a == SI_INVALID { return 0 }
243 let d: i64 = sf_dose_of(f, id)
244 if d <= 0 { return 0 }
245 if a < SF_FAIRY_DUST_PERMIL { return 1 }
246 return 0
247}
248
249func sf_count_fairy_dusted(f: *NxSuppFormula) -> i64 {
250 var i: i64 = 0
251 var n: i64 = 0
252 while i < SI_N {
253 let fd: i64 = sf_is_fairy_dusted(f, i)
254 n = n + fd
255 i = i + 1
256 }
257 return n
258}
259
260// ===== Gate 3: economics ==============================================
261
262func sf_actives_cost_cents(f: *NxSuppFormula) -> i64 {
263 var i: i64 = 0
264 var sum: i64 = 0
265 while i < SI_N {
266 let d: i64 = sf_dose_of(f, i)
267 if d > 0 {
268 let c: i64 = si_dose_cost_cents(i, d)
269 sum = sum + c
270 }
271 i = i + 1
272 }
273 return sum
274}
275
276// Conversion cost for a whole bottle: shells and filling scale with CAPSULE
277// COUNT, which is why an eleven-capsule serving is so expensive to make.
278func sf_conversion_cost_cents(f: *NxSuppFormula, servings: i64, format: i64, shell_ul: i64) -> i64 {
279 if servings <= 0 { return 0 }
280 let pack: i64 = SF_BOTTLE_COST_CENTS + SF_LABEL_COST_CENTS
281 if format == SF_FORMAT_POWDER { return pack + SF_POWDER_SCOOP_CENTS }
282 let per_serv: i64 = sf_capsules_needed(f, shell_ul)
283 if per_serv == SI_INVALID { return SI_INVALID }
284 let caps: i64 = per_serv * servings
285 let unit: i64 = SF_SHELL_COST_CENTS + SF_ENCAP_COST_CENTS
286 return pack + caps * unit
287}
288
289func sf_cogs_per_bottle_cents(f: *NxSuppFormula, servings: i64, format: i64, shell_ul: i64) -> i64 {
290 if servings <= 0 { return SI_INVALID }
291 let conv: i64 = sf_conversion_cost_cents(f, servings, format, shell_ul)
292 if conv == SI_INVALID { return SI_INVALID }
293 let act: i64 = sf_actives_cost_cents(f)
294 return act * servings + conv
295}
296
297// Gross margin in per-mil of the retail price.
298func sf_gross_margin_permil(retail_cents: i64, cogs_cents: i64) -> i64 {
299 if retail_cents <= 0 { return SI_INVALID }
300 if cogs_cents < 0 { return SI_INVALID }
301 let gross: i64 = retail_cents - cogs_cents
302 return gross * 1000 / retail_cents
303}
304
305// ===== Running it backwards ===========================================
306//
307// The direction a business actually works in: a price and a required margin
308// fix the COGS, the COGS fixes the ingredient budget, and the budget fixes
309// what doses are reachable. If the answer is "less than the clinical dose",
310// that is the product telling you it needs a different price, a different
311// format, or a different formula -- not a smaller number on the label.
312
313func sf_cogs_budget_cents(retail_cents: i64, target_margin_permil: i64) -> i64 {
314 if retail_cents <= 0 { return SI_INVALID }
315 if target_margin_permil < 0 { return SI_INVALID }
316 if target_margin_permil >= 1000 { return SI_INVALID }
317 let keep: i64 = 1000 - target_margin_permil
318 return retail_cents * keep / 1000
319}
320
321// Ingredient budget per SERVING once packaging and filling are paid for.
322// A NEGATIVE result is the honest answer: conversion alone already exceeds
323// the COGS budget, and no formula at all fits that price.
324func sf_actives_budget_per_serving_cents(f: *NxSuppFormula, retail_cents: i64, target_margin_permil: i64, servings: i64, format: i64, shell_ul: i64) -> i64 {
325 if servings <= 0 { return SI_INVALID }
326 let budget: i64 = sf_cogs_budget_cents(retail_cents, target_margin_permil)
327 if budget == SI_INVALID { return SI_INVALID }
328 let conv: i64 = sf_conversion_cost_cents(f, servings, format, shell_ul)
329 if conv == SI_INVALID { return SI_INVALID }
330 let left: i64 = budget - conv
331 return left / servings
332}
333
334// Largest dose of one ingredient a cents budget buys.
335func sf_max_dose_for_budget_mg(id: i64, budget_cents: i64) -> i64 {
336 if si_valid_id(id) != 1 { return 0 }
337 if budget_cents <= 0 { return 0 }
338 let per_kg: i64 = si_cost_cents_per_kg(id)
339 if per_kg <= 0 { return 0 }
340 return budget_cents * SF_MAGIC_1000000 / per_kg
341}
342
343// Does the price support the clinical dose of this ingredient at all?
344func sf_clinical_dose_affordable(id: i64, budget_cents: i64) -> i64 {
345 let clin: i64 = si_clinical_dose_mg(id)
346 if clin <= 0 { return 0 }
347 let max: i64 = sf_max_dose_for_budget_mg(id, budget_cents)
348 if max >= clin { return 1 }
349 return 0
350}