Factory docs, home
Page navigation

Historical local qualification: Source 7cf4b26e focused Core 22/22 and Dashboard 26/26 checks passed. The historical bounded local record keeps their exact scope. Historical source 7cf4b26e passed the 3,286/3,286 full checks and all 36 installed families. Independent bounded local evidence acceptance passed; exact-final-head CI is recorded separately from this frozen local proof. Module-specific and broader limits remain below.

Status: In progress. Reviewed local candidate, 3 October 2026. Independent source and retained installed stage evidence passed. Bounded concert evidence retains its independently reviewed snapshot. Historical source 7cf4b26e passed the 3,286/3,286 full checks and all 36 installed families. Independent bounded local evidence acceptance passed; exact-final-head CI is recorded separately from this frozen local proof. Fact-linked rendering and durable drafting retain original jobs and replay accounting; no live drafter, publication or customer benefit is qualified. Historical reviewed scope.

Intelligence: none — Claims render from typed facts under fixed rules; the job's optional drafter is a caller port whose templates those rules check; no model sets a fact.

Source: neutral contract, pure workflow, job contract, durable job. Tests: semantics, limits and replay, retained v1 pack, job, drafter, Budget and faults, closures, installed consumer, package proof. Adoption: standalone guide. Packet: W33 steps 1 and 2; gate: lifecycle Growth drafts.

Public package boundary

Import software-factory/marketing-workflow, marketing-workflow-contract, marketing-job or marketing-job-contract. The pure API and neutral contract need only ES2024 declarations. Job declarations use the actual caller Journal and AbortSignal and need caller-supplied compatible Node development declarations. All imports are passive; no package root, source/compiled private path, Journal instance, drafting adapter or publication service is supplied. The original private package candidate retains its historical evidence. Historical 7cf installed/full native execution and independent bounded local evidence acceptance passed.

API

  • generateMarketingPack(brief, facts, asOf) returns a deeply frozen sf-marketing-pack/1 pack. The caller supplies the clock; nothing reads time, files, a journal or a network.
  • revalidateMarketingPack(pack, facts, asOf) returns sf-marketing-validity/1: per block, the pack's historical state beside its current state and refusals. asOf cannot precede the pack's.
  • parseMarketingPack(value) reads a stored pack. A digest mismatch, or any difference from a fresh evaluation of its own brief, facts and asOf, is CORRUPT; nothing is repaired.
  • runMarketingJob(request, ports) runs, resumes or replays one job revision over the caller's Journal (Durable job).
  • MarketingWorkflowError has code (MarketingErrorCode) INVALID, LIMIT or CORRUPT from the pure functions, plus CONFLICT and UNAVAILABLE from the job, a closed reason and a bounded path. MARKETING_LIMITS and MARKETING_JOB_LIMITS hold every bound.

Inputs

A fact (sf-marketing-fact/1) is typed: scope, ID and revision, subject, value (text, or a quantity with its unit), population, window, causal or observational basis, status (active or withdrawn with a time), source pin with digest, checkedAt, optional expiry and qualification, and kind-specific evidence. A quantity without both population and window is INVALID. Kinds: capability, measurement, benefit (Assessment pin and verdict), availability (release pin and probe observation) and competitor (citation and owner approval of that citation's digest).

A brief (sf-marketing-brief/1) names scope, audience, channel, material, maxFactAgeMs and up to 64 blocks. A block template is literal text with {fact:<id>} placeholders. Any brace outside a well-formed placeholder is INVALID.

Rules

A refused block keeps its claim trace and refusals, and its text is null. Nothing is rewritten or softened.

  • Facts: missing-fact, stale-fact (age at least maxFactAgeMs), expired-fact, withdrawn-fact, wrong-scope.
  • Evidence: benefit-unsupported unless the Assessment verdict is supported; availability-without-release; availability-without-probe unless a passing probe is younger than maxFactAgeMs; competitor-citation-stale at 30 days or older; competitor-unapproved unless the owner's approval binds that citation digest and follows its capture.
  • Wording is screened in each cited fact's wording (text value or unit, population, qualification) and in the assembled output with every fact rendered in place. Figure, claim and scope matches in the assembled output are located: a match in literal text, or one that straddles a placeholder (thr{fact:x}, guaran{fact:x}), is refused with a null fact ID, so a figure, term or address split across a placeholder is still found.
  • no-fact-cited; uncited-figure for any numeral character (Unicode category N: decimal digits and other numerals such as ½, ¼, ², ③ or Ⅻ), figure words or written cardinal numbers (three, twenty-one). A figure is cited only when it lies wholly inside an exempt piece of one fact's rendering: the typed amount, a scale word opening its unit (per cent, million), the window dates, or the text value of a capability or availability fact (which may name a version, such as Excel 365). A figure in any other piece of a fact (a unit after its opening word, a population, a qualification, or the text value of a measurement, benefit or competitor fact) is refused with that fact's ID: a figure needs a typed quantity with its population and window. A cited numeral touched by text from outside its own rendering is refused with a null fact ID unless the touching character is whitespace, a bracket or a double quotation mark (or, after it, sentence punctuation): a sign, decimal point, scale symbol, letter, superscript or fraction beside it would change the quantity (-{fact:x} or .{fact:x} reading -38 or .38). A fact's own sign, as in a negative amount, is kept.
  • superlative, guarantee and pricing anywhere in the screened wording.
  • unsupported-causality, unsupported-availability and unsupported-benefit: causal, availability or benefit words are allowed only as a cited fact's own wording, wholly inside one rendering of a fact with a causal basis, availability evidence or benefit evidence respectively. Anywhere else they are refused with a null fact ID, even beside a supporting fact, because nothing binds literal text to that fact (Payroll is now available globally. {fact:export-live} is refused). A cited fact without that basis or kind cannot carry such words (refused with its ID). The supporting fact must still pass its own evidence rules.
  • unsupported-scope for broad-scope words in literal or straddling text (globally, worldwide, everyone, every customer, all regions and similar), which would widen or contradict a cited fact's population or qualification. A fact may state its own scope.
  • personal-data for email addresses, handles, telephone numbers, UK postcodes and National Insurance numbers; postcodes and National Insurance numbers match in any letter case. Personal data is never echoed: when a block holds any, every refusal in that block has a null term.
  • Revalidation adds fact-changed when a cited fact's current digest differs from the pinned one, including withdrawal. A missing current fact is refused, never assumed valid. A block refused at generation stays not-rendered. Any historically valid block now refused makes the result invalidated.

Rendering is fixed: a text value, or amount unit, then population, UTC window dates and qualification in brackets. The screen word lists and rendering are part of sf-marketing-pack/1; changing either needs a new protocol and fixture, never a rewritten history.

Limits and boundaries

Every text field rejects Unicode default-ignorable code points (zero-width and other format characters) as INVALID/shape, and only a plain space or line break may separate literal text from a cited amount. Look-alike letters from other scripts are not normalised or detected.

At most 256 facts, 64 blocks, 16 placeholders per block, 4,000 template characters, 280-character values and 1 MiB canonical input. Over-limit input is LIMIT and refused whole. Malformed values, future metadata (checkedAt, withdrawal, probe, capture or approval after asOf) and duplicate identities are INVALID.

Runtime closure of the pure workflow: the contract, canonical-json, strict-input and errors, plus node:crypto; it has no ports. The job adds its contract, promise-observation (the one bounded Promise observation helper of issue #58), node:buffer and node:util (to recognise a native Promise); it reaches the Journal, clock and drafter only through caller ports and loads no Journal, SQLite, transport, model or publication adapter. A pack grants no permission to publish, and a valid block is not evidence of effectiveness.

The screens are deterministic word lists, not a proof of truth: they catch common unsupported wording, not every paraphrase of availability, benefit, causality or scope, and a short word such as one, cut or global is refused even where it is not a claim. What remains undetected: a plain sentence in literal text that uses none of the listed words (Payroll exports CSV.); a named place or segment in literal text (in the US, for charities), which is not compared with a cited fact's population or qualification; a subject named in literal text (Payroll: {fact:export-live}), which is not compared with the fact's subject; and number words outside the lists (thrice, once, quarter, tenfold, ordinals such as first). A figure in a capability or availability fact's text value is exempt, so that text is trusted as written. The case-insensitive postcode pattern can refuse ordinary text such as Q3 4th. British spelling and independent acceptance are not established by step 1; step 2 adds replay, Budget, cancellation and drafter substitution below, proven with fixture drafters only.

Durable job

runMarketingJob(request, { journal, clock, drafter?, signal? }) resolves with an sf-marketing-job-result/1 value, deeply frozen. The request (sf-marketing-job/1) holds the job identity (caller ID and job ID, each at most 32 characters of the canonical ID grammar, and a revision), the brief, the facts and a fixed Budget. journal is the caller's CommandJournal (only execute and readAggregate are used), clock returns an ISO 8601 UTC millisecond timestamp, drafter is optional and signal is an AbortSignal.

  • Identity and replay. One aggregate per revision, marketing-job:<caller>:<job>:<revision>; command IDs under marketing-job/<caller>/<job>/<revision>/ (start, block/<index>/dispatch, block/<index>/settle, complete). The start payload binds the request digest (the parsed brief and every supplied fact, ordered by ID), the drafter's ID, the Budget and the block count. The same payload replays: a completed job answers replayed: true from the Journal, re-renders its pack and checks the recorded digest, writes nothing and calls nothing. A run that writes start and then observes a peer's completion reports replayed: false; later write-free replay remains true. A changed payload, including another drafter, a larger Budget or an extra uncited fact, is CONFLICT; a changed request needs a new revision, which is independent.
  • Time. The job's asOf is the caller's clock at its first start and is recorded; every run renders at it. The deadline is asOf plus deadlineMs.
  • Drafter. For each block in order, while the Budget allows, the drafter receives an sf-marketing-draft-request/1 value (frozen): the brief's own template, only the cited facts no rule refuses in that block, asOf and maxBytes. The personal-data refusal names no fact, so in a block that holds personal data each cited fact is checked alone, and a fact whose own wording holds personal data is never shown; a block left with no such fact is not-dispatched/no-usable-fact. It returns, or fulfils a native Promise with, { protocol: "sf-marketing-draft/1", blockId, template }, where template is a placeholder-only template or null to decline. The reply must be plain JSON: it goes through canonicalJson, so a nested Promise, class instance, function, accessor or thenable is invalid/not-plain-json and is never called. Every value a caller port hands the job (a reply, a late reply, a rejection reason, a thrown value, a clock reading) first passes through observePromises (src/promise-observation.ts, issue #58's one shared helper; the older per-module walkers move onto it under #58), which attaches a passive reaction to each native Promise held in own data properties, and to what it settles with, within 64 levels and 16,384 steps; it calls no getter, thenable or function. A reply or rejection reason is observed as it arrives, whether or not the run still waits for it (a reply after the deadline, after cancellation, or after the caller's clock threw or returned a malformed reading mid-call), so a refused or abandoned value never leaves a rejection unhandled, and the job survives --unhandled-rejections=strict. Two limits remain: a native Promise whose constructor lookup throws cannot be observed by any part of the language (then, await, Promise.resolve and the combinators all read it first), and nothing beyond the bounds is observed; a drafter is in-process code that can always leave a rejection of its own unhandled. A draft may cite only the facts it was given (citation); a malformed template is template; the step 1 rules then validate it at asOf. A valid draft is used (drafted) only if the whole brief, with the drafts accepted so far, this one and the brief's templates elsewhere, still renders within the pack's 1 MiB limit; otherwise it is invalid/over-limit (measured) and its block keeps its template, so a completed job always renders. a refused draft keeps its refusals but not its text, and its block keeps the brief's template, as do declined, invalid and unknown attempts. A block with no usable fact, or with no drafter, is not-dispatched and costs nothing.
  • Budget. Fixed in the payload and never extended: at most calls dispatches (0–64), bytes of reply (0–262,144) and no dispatch at or after the deadline (deadlineMs 1–3,600,000). Each dispatch reserves min(remaining bytes, 16,384) and records the call and reservation before the drafter runs. Time is read fresh at each step: no dispatch is recorded at or after the deadline, a call whose dispatch is recorded once the deadline has passed is settled unknown/deadline without contacting the drafter, and a reply (returned or fulfilled) at or after the deadline is late: unknown/deadline, debited whole and unused. A measured reply settles at its canonical size; a reply over its reservation is invalid/over-limit and debits the reservation. When calls, bytes or time run out, the remaining blocks are not-dispatched (calls, bytes or deadline) and the pack renders their templates.
  • Unknown outcomes. A drafter that throws, rejects, returns a native Promise whose then throws, is cancelled or is still pending at the deadline (its signal is aborted) is unknown (threw, cancelled, deadline), debited its whole reservation (measured: false), never called again, and its block keeps its template. A run that stops between dispatch and settle (a lost write, a crash) leaves the call in flight: before the deadline another run reports in-progress and writes nothing, because the call may be live; at or after the deadline the call is settled unknown/interrupted. Settling records that the outcome is unknown; it does not prove the call ended. A run whose dispatch command is answered from another run's identical receipt does not call the drafter.
  • Cancellation is cooperative. The job aborts the drafter's own signal, stops waiting and never uses a reply that arrives later, but it cannot stop the drafter's code: a drafter that ignores its signal keeps running, and whatever it does after the job has settled its call unknown (or completed) is an unknown ongoing effect, not a finished one. A later reply writes nothing and is never used.
  • Cancellation. An aborted signal before start writes nothing (asOf null). After a dispatch is recorded, or during a call (the drafter's own signal is aborted, even during a synchronous call), it settles that call unknown/cancelled without using any reply, and resolves cancelled; a drafter is never contacted once the caller's signal is aborted; a later run of the same request resumes under the same Budget and deadline.
  • Record size. Each settled attempt must leave the job record within the Journal's 1 MiB state limit with room for every block still undecided (the largest text-free record each), the largest debits and a pack digest. A result that would not fit, such as a refused draft whose refusal list is large, is recorded whole as invalid/over-limit at its measured size, keeping neither its text nor its refusals, and its block keeps the brief's template; so the job can always settle every call and complete.
  • Timestamps. A clock reading or a stored asOf or deadline must be a canonical UTC millisecond timestamp naming a real instant: one that matches the pattern but names none (month 13, hour 25, 30 February) is INVALID/clock from the clock and CORRUPT in a stored record, never a raw RangeError. A first start whose deadline would fall after year 9999 is INVALID/clock and writes nothing.
  • Storage. A missing Journal, or one that refuses a read or write (closed, read-only, storage failure), is UNAVAILABLE and the drafter is not called before its dispatch is recorded. A stored record whose shape, debits or recorded pack digest fail validation is CORRUPT and never repaired, as is one holding a value the Journal's JSON parsing accepts but canonical JSON refuses (a non-finite number, an unpaired surrogate, a reserved key), never a raw input error; each stored attempt must keep its state's accounting (every dispatched call reserved at least one byte, an unknown or unreadable outcome is unmeasured and debited its whole reservation, a measured reply is debited at least one byte, and only a refused draft keeps refusals). Events: marketing-job.started, .draft-dispatched, .draft-settled, .completed (catalogue).

Not established by step 2: a live model drafter (the lifecycle growth/draft-pack task would sit behind this port), a substitute fact validator, the drafter's own spend or rate limits (the Budget bounds calls and reply bytes, not tokens), cross-process liveness before the deadline, that a drafter has stopped after its call is settled unknown (cancellation is cooperative), the moving of the other modules' Promise walkers onto the shared helper (issue #58), publication (step 3), independent final review and acceptance. The private installed consumer now covers the pure pack and durable job, including separate-process caller Journal replay, changing source facts, substitute fixture drafting and unknown non-retry. See the adoption guide.

Shared value implementation: common contracts. Owning errors, limits, stored identities and authority remain as specified above.

Source: docs/agents/marketing-workflow.md