Skip to content

Latest commit

 

History

History
568 lines (440 loc) · 64 KB

DECISIONS.md

File metadata and controls

568 lines (440 loc) · 64 KB

DECISIONS.md: Architecture Decision Records & Canonical Ledger

Immutable log of foundational engineering, mathematical, and architectural decisions governing the FunnelScript language, compiler, runtime, and research ecosystem.


Decision Index

ID Title Date Status Primary Driver
DEC-001 Core-Outwards 5-Phase Implementation Strategy 2026-10-31 Accepted Inside-Out engineering discipline; mathematical core before UI
DEC-002 Hypothesis-First & Research-Gated Engineering 2026-10-31 Accepted Preventing speculative implementation; scientific falsifiability
DEC-003 Parsimonious Calibrated Micro-Foundations over LLM Personas 2026-10-31 Accepted Identifiability barrier & SIMD throughput scaling ($10^5$ agents)
DEC-004 Downside Catastrophe Stress-Testing over Point-Forecasts 2026-10-31 Accepted Aleatoric market volatility; insolvency cliff detection
DEC-005 Decoupled Statistical Calibration Contract with PyMC Marketing 2026-10-31 Accepted Complementarity: Macro Bayesian MMM vs. Micro Forward ABM
DEC-006 Two-Tier Hybrid Agent Architecture (Population vs. Cognitive) 2026-10-31 Accepted Computational scaling ($10^5$ SIMD agents + $10^2$ OmniTwin agents)
DEC-007 Epistemic Decoupling: World Truth vs. Agent Belief 2026-10-31 Accepted Modeling human cognitive bias, misinformation, and imperfect perception
DEC-008 The 4-Layer Stack: DSL Kernel vs. First-Party Standard Library 2026-10-31 Accepted FunnelScript is a Programming Language, not a simulation tool
DEC-009 Decoupling Economic Invariants from Compiler Axioms 2026-10-31 Accepted Expressive user-defined constraint blocks (BNPL, Debt, Churn)
DEC-010 The Ontological Subtyping Principle: Agent ⊂ Entity 2026-10-31 Accepted Passive state containers vs. autonomous decision actors
DEC-011 The Living Intellectual Trilogy Mandate 2026-10-31 Accepted Mandatory synchronization of Debates, Decisions, and Out-of-the-Box ledgers
DEC-012 FCM-001: Event-Driven Stochastic State Machine Computational Model 2026-10-31 Accepted Zeigler's DEVS formalism; multi-timescale simulation scaling
DEC-013 FCM-002: Dual-Mode Execution Architecture & Koka-Style Effect System 2026-10-31 Accepted Separation of pure strategy logic from real-world side-effects
DEC-014 Shadow Execution Mode for Risk-Free Live Observation 2026-10-31 Accepted Real-world webhook evaluation with zero mutations
DEC-015 Idempotency Keys and Compensating Actions for Irreversible Live Operations 2026-10-31 Accepted At-most-once execution & compensating sagas for marketing effects
DEC-016 The Terraform-Julia-Solidity Architectural Triad 2026-10-31 Accepted Unifying Declarative IaC, High-Performance ABM, and Financial Safety
DEC-017 The Provider Contract Abstraction & Plan-vs-Apply Lifecycle 2026-10-31 Accepted Decoupling external platforms via pluggable providers and speculative DAG diffs
DEC-018 Static Financial Invariants & Budget Gas Ceilings 2026-10-31 Accepted Smart-contract-inspired compile-time budget verification and runtime spend halts
DEC-019 Domain-Neutral Event Kernel v0 and Inert Effect Intents 2026-10-31 Accepted Executable substrate for DEC-008/012/013 without domain coupling
DEC-020 Dual Distribution Model (Zero-Install NPX/Bunx & Isolated Python Tooling) 2026-10-31 Accepted Frictionless DX across marketing technologists (Node) and ML engineers (Python)
DEC-021 IDE Ecosystem Integration via Language Server Protocol (LSP) 2026-10-31 Accepted Real-time in-editor AST linting and red squiggly error detection in VS Code/Cursor
DEC-022 Contextual World Declarations and Strict Primitive State Typing 2026-10-31 Accepted Additive language syntax and typed AST without marketing schema dependency
DEC-023 Formal 4-Pillar Documentation Architecture (Docs as Code) 2026-10-31 Accepted Knowledge scaffolding across tutorials, specs, Bayesian data, and anti-patterns
DEC-024 The Modular Library, Framework, and Package Manager Ecosystem (fpm) 2026-10-31 Accepted Strategy reusability, business frameworks, industry benchmarks, and fpm registry
DEC-025 Specification-First Open-Source Adoption & Shim Strategy 2026-10-31 Accepted Credibility-first open source, formal spec release, and linter-as-wedge adoption
DEC-026 Community Contribution Architecture (CONTRIBUTING.md & Issue Standard) 2026-10-31 Accepted Low-friction onboarding, architectural boundaries, RFC governance, and triage taxonomy
DEC-027 Contextual World Rules and Snapshot-Atomic Transitions 2026-10-31 Accepted Pure source-level handlers and simultaneous state transitions via EventMachine
DEC-028 Source-Scheduled Local Events Through the Existing Event Calendar 2026-10-31 Accepted Type-checked emit and bounded deterministic event scheduling
DEC-029 Type-Checked Pre-Event Guards for World Rules 2026-10-31 Accepted Deterministic conditional execution of typed World rules
DEC-030 Exact-Typed Local Event Records at Both Calendar Boundaries 2026-10-31 Accepted Static message schemas, strict ingress and pre-enqueue checking
DEC-031 Reproducible Source-Level Stochastic World Transitions 2026-11-01 Accepted Seeded stochastic World transitions
DEC-032 Source-Imported World Modules and Initial Marketing Standard Library 2026-11-01 Accepted Explicit module boundaries and optional domain packages
DEC-033 Tagged Git-Source Experimental Preview and Safe World Onboarding 2026-11-01 Accepted Versioned preview distribution
DEC-034 Repository-Specific Documentation Contracts for the Experimental Preview 2026-11-01 Accepted Documentation link verification
DEC-035 Curated, Named Agent Skills with an Explicit Vendor Boundary 2026-10-31 Accepted Contributor-facing skill bundle integrity
DEC-036 Explicit CLI Failure Taxonomy and Bounded JSON Event Inputs 2026-11-01 Accepted CLI error classification and bounded JSON input
DEC-037 EOF-Safe Parsing and Exact-Typed Narrow World Arithmetic 2026-11-01 Accepted One binary operator, finite float outputs, controlled zero division

Detailed Architecture Decision Records

DEC-001: Core-Outwards 5-Phase Implementation Strategy

  • Status: Accepted
  • Context: A complete marketing programming ecosystem requires an agent cognitive model, an AST parser, a static type linter, a high-throughput runtime simulation engine, developer tooling, and visual web interfaces.
  • Decision: Enforce a strict inside-out development sequence: $$\text{Agent Mind (P1)} \longrightarrow \text{AST & Linter (P2)} \longrightarrow \text{Vectorized Runtime (P3)} \longrightarrow \text{CLI Suite (P4)} \longrightarrow \text{Web Dashboard (P5)}$$
  • Rationale: Premature authoring of visual interfaces or surface-level syntactic wrappers masks foundational mathematical or algorithmic flaws. The core engine must be green before outward layers are constructed.
  • Consequences: All five phases executed with 100% verification (29 Python tests green, 66M agent-days/sec throughput, Bun test green, Vite build clean).

DEC-002: Hypothesis-First & Research-Gated Engineering

  • Status: Accepted
  • Context: AI coding agents frequently generate ungrounded code, speculative interfaces, or tautological mocks without rigorous verification.
  • Decision: Institute an ironclad constitutional directive in AGENTS.md: No agent may generate, modify, or commit code without first articulating:
    1. The Research Anchor (prior art citation).
    2. The Falsifiable Hypothesis ($H$).
    3. The Mathematical Invariant (formal equation or boundary condition).
  • Rationale: Engineering discipline demands that every code alteration is a testable experiment designed to falsify a precise hypothesis.
  • Consequences: Code commits map 1:1 to verified scientific hypotheses ($H_{3.1}$ through $H_{5.2}$).

DEC-003: Parsimonious Calibrated Micro-Foundations over LLM Personas

  • Status: Accepted
  • Context: Debate between instantiating $100,000$ consumers as prompt-engineered LLM personas vs. closed-form numeric vectors.
  • Decision: Standardize agent micro-foundations on 10–15 orthogonal, mathematically bounded variables ($\alpha, \beta, \gamma, \kappa, w, s$) executed via vectorized SIMD array broadcasting (NumPy 2.x). Reserve LLMs strictly for qualitative copy analysis in offline calibration passes.
  • Rationale: LLM-per-agent architectures suffer from parameter unidentifiability, extreme latency ($> 10\text{ hours/trial}$), non-reproducibility, and financial hallucination. Numeric micro-foundations execute at $66,000,000\text{ agent-days/second}$.
  • Consequences: Scalable Monte Carlo simulations with guaranteed deterministic random seeds.

DEC-004: Downside Catastrophe Stress-Testing over Point-Forecasts

  • Status: Accepted
  • Context: Marketing platforms often sell deterministic forecasting ("This funnel will make $150k"). Real markets are open stochastic systems with aleatoric variance.
  • Decision: FunnelScript will never output scalar deterministic predictions. All outputs are multi-trial probability distributions ($P_{10}, P_{50}, P_{90}, \text{Mean}$) accompanied by Value-at-Risk ($\text{VaR}{95}$), Expected Shortfall ($\text{CVaR}{95}$), and Cash Ruin Probability ($P(\text{Insolvency})$).
  • Rationale: Capital preservation precedes profit optimization. Identifying payment clearance starvation cliffs ($\Delta_{\text{settle}}$) saves businesses from bankruptcy before deployment.
  • Consequences: Telemetry engine explicitly models clearance lag and halts ad spend upon operational reserve depletion.

DEC-005: Decoupled Statistical Calibration Contract with PyMC Marketing

  • Status: Accepted
  • Context: The discovery of imMamdouhaboammar/pymc-marketing-mcp (66 Bayesian capabilities) raised the question of whether to merge MMM and FunnelScript into a single codebase.
  • Decision: Keep both projects completely decoupled. Interface exclusively through a versioned JSON schema: calibration_manifest.json.
  • Rationale: PyMC Marketing solves the retrospective macro problem ("What does historical data prove about channel elasticity and posterior uncertainty?"). FunnelScript solves the prospective micro problem ("What happens if we deploy this novel multi-step dynamic strategy tomorrow?"). Tight coupling would compromise the agility and CI suites of both codebases.
  • Consequences: FunnelScript consumes posterior adstock decay ($\lambda$), saturation limits ($K$), and decision gate flags (diagnose_mmm) directly from PyMC exports.

DEC-006: Two-Tier Hybrid Agent Architecture (Population vs. Cognitive)

  • Status: Accepted
  • Context: Evaluating the role of imMamdouhaboammar/OmniTwin (Cognitive Continuity Engine with hierarchical memory, allostasis, and state reducers).
  • Decision: Adopt a two-tier hybrid architecture:
    • Tier 1 (Population Agents, $N = 10^5 - 10^6$): Fast, numeric SIMD state machines for statistical significance and financial distribution metrics.
    • Tier 2 (Cognitive Sentinel Agents, $N = 10^1 - 10^2$): Selected focal personas equipped with hierarchical memory and state reduction (via OmniTwin adapters) to qualitatively test message framing, brand sentiment drift, and narrative resonance.
  • Rationale: Harmonizes macro-statistical rigor with micro-qualitative plausibility without computational blowup.
  • Consequences: Zero slowdown for the core vectorized simulation engine.

DEC-007: Epistemic Decoupling: World Truth vs. Agent Belief

  • Status: Accepted
  • Context: OmniTwin employs a "No ID, No Claim" constraint to prevent AI hallucinations. In market simulation, consumers frequently hold false beliefs, miscalculate discounts, or act on unverified rumors.
  • Decision: Decouple the Physical World State from the Agent's Epistemic Belief State: $$\text{AgentBelief}_i(t) \neq \text{WorldTruth}(t)$$
  • Rationale: Forcing synthetic consumers to possess perfect information destroys the realism of human market dynamics (bounded rationality, asymmetrical information, social contagion).
  • Consequences: Agents can transition states based on subjective, distorted valuations of products and promotions.

DEC-008: The 4-Layer Stack: DSL Kernel vs. First-Party Standard Library

  • Status: Accepted
  • Context: Determining whether terms like audience, touchpoint, campaign, and conversion should be hardcoded compiler keywords.
  • Decision: Formalize FunnelScript as a 4-tier stack:
    1. Layer 01 (Language Core): Minimal computational primitives (entity, agent, state, event, transition, rule, probability, constraint).
    2. Layer 02 (Execution Runtime): Discrete-event simulation scheduler.
    3. Layer 03 (Official Standard Library): std::marketing defining Audience, Touchpoint, and Campaign using public language primitives with zero secret compiler privileges.
    4. Layer 04 (Community Ecosystem): Sector-specific and regional market packages.
  • Rationale: Establishes FunnelScript as an extensible, general programming language (analogous to SQL or Julia) rather than a rigid, single-purpose software application.
  • Consequences: Third-party developers have first-class capabilities to create alternative domain libraries (e.g. B2B procurement models, influencer ecosystems).

DEC-009: Decoupling Economic Invariants from Compiler Axioms

  • Status: Accepted
  • Context: Hardcoding population mass conservation ($\sum N = N_{\text{total}}$), strict zero-credit wallet limits ($P \le w$), and liquid cash halts into the compiler prevents modeling open markets, BNPL, or revolving debt facilities.
  • Decision: Remove model-specific assumptions from the core grammar. Provide generic, expressive constraint declarations:
    ConstraintDeclaration ::= "constraint" Identifier "{" Expression "}"
  • Rationale: The compiler checks syntax, types, and topological validity. Economic models define their own boundary invariants via explicit constraint declarations.
  • Consequences: Full expressive versatility across diverse business structures and geographies.

DEC-010: The Ontological Subtyping Principle: Agent ⊂ Entity

  • Status: Accepted
  • Context: Defining the primary actors and state containers of a FunnelScript program.
  • Decision: Formalize that all Agents are Entities, but not all Entities are Agents: $$\text{Agent} \subset \text{Entity}$$
    • Entity: A passive or externally mutated state container (e.g. Budget, Inventory, AdUnitSlot).
    • Agent: An Entity possessing bounded rationality, internal decision rules, and autonomous initiation (e.g. Consumer, Competitor, Bidder).
  • Rationale: Eliminates conceptual ambiguity in the language type system and simplifies runtime event dispatch.
  • Consequences: Clear inheritance hierarchy in AST node models and runtime state management.

DEC-011: The Living Intellectual Trilogy Mandate

  • Status: Accepted
  • Context: Engineering knowledge, architectural trade-offs, and visionary ideas are frequently lost across development sessions or isolated in transient chat logs.
  • Decision: Mandate the continuous, simultaneous maintenance of the Living Intellectual Trilogy across all sessions:
    1. DEBATES.md: Active philosophical conflicts, trade-offs, and dialectical synthesis.
    2. DECISIONS.md: Immutable canonical log of accepted architectural records.
    3. OUT_OF_THE_BOX.md: Speculative, frontier, non-linear ideas revolving around the core vision.
  • Rationale: Ensures durable institutional memory, complete traceability, and constant alignment between code and vision.
  • Consequences: Enforced as a mandatory rule in AGENTS.md.

DEC-012: FCM-001 — Event-Driven Stochastic State Machine Computational Model

  • Status: Accepted
  • Context: Fixed daily or step-wise tick loops cannot model intraday multi-timescale events (e.g. ad auctions at $t=10^{-3}\text{s}$, sessions at $t=10^1\text{min}$, cart recovery at $t=2\text{h}$, settlement clearing at $t=3\text{d}$) without prohibitive computational overhead.
  • Decision: Establish Zeigler’s Discrete Event Systems Specification (DEVS) as the foundational execution model of FunnelScript: $$W_{t^+} = \mathcal{T}(W_t, e_t, \theta, \xi_t)$$
    • The runtime driver maintains a min-heap priority calendar $\mathcal{Q}$ of discrete events ordered by $(\tau_e, \pi_e)$.
    • Continuous background phenomena (e.g. adstock carryover, brand decay) are computed lazily via analytic step functions upon event arrival.
    • Deterministic pseudo-random seeds guarantee bit-for-bit replayability.
  • Rationale: Eliminates millions of empty loop iterations while providing exact temporal resolution for asynchronous marketing interventions.
  • Consequences: Vectorized cohort batching handles $10^5$ synthetic agents with microsecond event dispatch efficiency.

DEC-013: FCM-002 — Dual-Mode Execution Architecture & Koka-Style Effect System

  • Status: Accepted
  • Context: Unifying offline simulation and live production deployment within one language without polluting simulation loops with network I/O or risking accidental live ad spend.
  • Decision: Decouple tactical strategy logic from side-effect execution via an Algebraic Effect System:
    • Compiled FunnelScript rules yield pure, immutable EffectIntent values (e.g. AdjustBudgetIntent, DispatchMessageIntent, HaltSpendIntent).
    • Effects are executed exclusively by interchangeable, pluggable handlers:
      1. SimulatedEffectHandler: Updates in-memory vector arrays with zero network I/O.
      2. ShadowEffectHandler: Passively monitors real webhook traffic without emitting external mutations.
      3. LiveEffectHandler: Validates safety ceilings, computes HMAC signatures, and calls external provider APIs (Meta, Klaviyo, Shopify).
  • Rationale: Pure strategies remain 100% testable and side-effect free in simulation, while the identical compiled AST can be safely deployed to live production.
  • Consequences: The compiler never links against HTTP clients or API credentials; all side-effects are sandboxed at runtime.

DEC-014: Shadow Execution Mode for Risk-Free Live Observation

  • Status: Accepted
  • Context: Deploying an algorithmic marketing strategy directly to live execution carries severe financial risk if synthetic consumer assumptions diverge from real consumer behavior.
  • Decision: Introduce a first-class Shadow Execution Mode:
    • The runtime ingests real-world event webhooks from live platforms (Shopify orders, Meta spend reports, Stripe webhooks).
    • The strategy state machine evaluates rules in real time, recording all intended actions and computing predicted metrics.
    • Outbound network mutations are intercepted and suppressed; divergence metrics ($\Delta_{\text{actual vs predicted}}$) are logged to telemetry.
  • Rationale: Provides an empirical burn-in observation period to validate strategy behavior and detect modeling drift before committing real marketing capital.
  • Consequences: Establishes a zero-risk bridge between offline simulation and live capital deployment.

DEC-015: Idempotency Keys and Compensating Actions for Irreversible Live Operations

  • Status: Accepted
  • Context: Unlike relational databases where transactions can be rolled back via ROLLBACK, external marketing actions (sent emails, SMS messages, published ad sets) cannot be un-executed. Network retries can also trigger duplicate billing.
  • Decision:
    • Mandate deterministic SHA-256 idempotency keys for all live mutations: $$\text{Key} = \text{SHA256}(\text{strategy_id} \parallel \text{event_id} \parallel \tau_e)$$
    • Require explicit Compensating Actions (Saga pattern) for irreversible side effects when a campaign is paused, canceled, or fails mid-execution (e.g. deactivating a leaked discount code or dispatching correction notifications).
  • Rationale: Guarantees at-most-once execution semantics and predictable failure recovery across distributed third-party marketing APIs.
  • Consequences: LiveEffectHandler verifies idempotency state before dispatching any provider API mutation.

DEC-016: The Terraform-Julia-Solidity Architectural Triad

  • Status: Accepted
  • Context: Marketing systems require a unique fusion of declarative infrastructure topology, stochastic agent simulation, and high-stakes financial risk management.
  • Decision: Formally ground FunnelScript upon three architectural pillars:
    1. Terraform (IaC): Declarative Marketing as Code, resource DAG dependencies, and plan vs apply execution lifecycle.
    2. Julia / Agents.jl (ABM): High-performance numerical simulation, vectorized SIMD array processing, and discrete-event scheduling.
    3. Solidity / Move (Smart Contracts): Static invariant analysis, bounded budget gas consumption, and financial anti-drain protection.
  • Rationale: Eliminates arbitrary ad-hoc designs by borrowing proven paradigms from cloud infrastructure, computational physics, and financial cryptosystems.
  • Consequences: Architectural consensus established; all future compiler and runtime features must trace back to this triad.

DEC-017: The Provider Contract Abstraction & Plan-vs-Apply Lifecycle

  • Status: Accepted
  • Context: Coupling the compiler grammar to specific ad platforms (Meta, Google, TikTok, Klaviyo, Shopify) would create brittle lock-in and violate world-model neutrality.
  • Decision:
    • Define generic provider and resource contracts in the core EBNF grammar (Layer 01).
    • Enforce a two-phase operational lifecycle:
      • funnelscript plan: Validates syntax, builds the resource DAG, calculates estimated daily burn rates, and runs Monte Carlo simulation risk checks.
      • funnelscript apply: Dispatches validated mutations to external platform providers with cryptographic idempotency.
  • Rationale: Allows identical FunnelScript source code to run hermetically in simulation (SimulatedProvider) or manage multi-million dollar live production campaigns (LiveProvider).
  • Consequences: Provider plugins can be developed independently by the community without altering compiler internals.

DEC-018: Static Financial Invariants & Budget Gas Ceilings

  • Status: Accepted
  • Context: In automated execution, algorithmic optimization loops or logic flaws can continuously trigger ad spends or bidding wars, causing catastrophic balance depletion.
  • Decision:
    • Require static upper bounds on capital draw ($C_{\text{max}}$) for all recurring actions, loops, and dynamic triggers.
    • The compiler AST linter rejects any strategy containing unconstrained spending expressions or unbounded retry loops.
    • The runtime driver maintains an immutable daily "budget gas" ceiling ($C_{\text{daily_cap}}$); when consumed, execution halts unconditionally.
  • Rationale: Protects enterprise treasuries with the mathematical certainty of smart-contract execution environments.
  • Consequences: Prevents automated ad-account drain catastrophes before deployment.

DEC-019: Domain-Neutral Event Kernel v0 and Inert Effect Intents

  • Status: Accepted as the first bounded implementation slice of DEC-008, DEC-012, and DEC-013.
  • Research Anchor: Zeigler's discrete-event system specification; Leijen's separation of algebraic effect interfaces from handlers; Python's documented stable priority-queue pattern. See spec/event-kernel-v0.md.
  • Falsifiable Hypotheses: H-K1 stable chronological event ordering; H-K2 seeded replay for pure deterministic reducers; H-K3 finite-time and progress bounds; H-K4 domain-neutral model state and inert external effect descriptions.
  • Mathematical Invariants: A processed event's (time, priority, ordinal) tuple cannot decrease. Newly scheduled events obey time(new) >= time(current); equal-time scheduling cannot decrease priority. The run terminates or raises at a caller-controlled max_events bound.
  • Decision: Introduce a minimal Python reference event kernel taking an opaque user-defined state and reducer and returning a new state, processed/pending events, and effect-intent values. Keep legacy campaign-specific AST/linter and vectorized runtime intact pending a separate migration decision.
  • Safety Boundary: Emission of inert effect descriptions is not enforcement of pure Python callbacks, static capability checking, or safe live execution. No provider handler or live API mutation is implemented in this phase.
  • Consequences: An executable domain-neutral semantic contract and regression checks are available independently of marketing-specific concepts. This does not establish predictive validity or a full DEVS/Koka implementation.

DEC-020: Dual Distribution Model (Zero-Install NPX/Bunx & Isolated Python Tooling)

  • Status: Accepted
  • Context: Language adoption hinges upon developer onboarding friction. Marketing technologists and web engineers predominantly operate within JavaScript/Node runtimes, while quantitative researchers and SREs operate in Python environments.
  • Decision: Distribute FunnelScript through two parallel canonical packaging channels:
    1. Python Distribution: funnelscript-cli on PyPI installed via uv tool install funnelscript-cli or pipx install funnelscript-cli, providing hermetic virtual environment isolation on host operating systems.
    2. JavaScript Distribution: @funnelscript/cli on npm, enabling instantaneous zero-install execution via npx funnelscript or bunx funnelscript.
  • Rationale: Removes installation barriers entirely. A growth engineer can validate a campaign file in seconds without managing Python environments, while an ML pipeline can cleanly pin virtual dependencies.
  • Consequences: Cross-registry packaging pipelines must synchronize version releases between PyPI and npm.

DEC-021: IDE Ecosystem Integration via Language Server Protocol (LSP)

  • Status: Accepted
  • Context: Developers should not have to manually run terminal commands to discover logic bugs, unreachable campaign nodes, or audience mass balance leaks. Building a bespoke standalone IDE introduces high maintenance and adoption resistance.
  • Decision:
    • Implement an open Language Server Protocol (LSP) background daemon in Python (funnelscript-lsp) communicating via JSON-RPC.
    • Package an official client extension for VS Code and Cursor (.vsix).
    • As the developer writes code, the LSP executes the incremental parser and FunnelLinter, rendering real-time inline diagnostics (red squiggly lines for mass leaks, yellow squigglies for liquidity warnings, code completions, and hover documentation).
  • Rationale: Meets developers where they already work. Catches marketing logic errors before files are saved or simulations are executed.
  • Consequences: Strategy authoring achieves enterprise-grade IDE ergonomics identical to Rust Analyzer or Terraform HCL language tools.

DEC-022: Contextual World Declarations and Strict Primitive State Typing

  • Status: Accepted as an additive compiler milestone implementing the already established DEC-008/010 language-core separation.
  • Research Anchor: Cardelli and Wegner (1985) on subtyping; Pierce (2002) on type judgments; Pydantic v2 discriminated AST unions. See spec/world-declarations-v0.md.
  • Falsifiable Hypotheses: H-W1 neutral parsing; H-W2 exact primitive type/uniqueness checking; H-W3 agent-to-entity AST subtyping; H-W4 backward compatibility and blocked unsupported world simulation.
  • Mathematical Invariants: Distinct declaration names per world; distinct state names per declaration; literal_type(value) = declared_type; AgentDefinition <: EntityDefinition.
  • Decision: Support a top-level world Name { entity ... agent ... } source form with explicit state name: type = literal; fields. Treat the four new declaration words as contextual keywords, retaining their legacy identifier status. Use strict int, float, bool, string literal typing without coercion in v0.
  • Compatibility Boundary: Keep legacy strategy AST and marketing simulator unchanged. A world can be statically checked, but simulation is explicitly unsupported until world transitions and runtime construction exist.
  • Consequences: A real, testable syntax-to-AST and type-checking route exists without inventing prebuilt market Worlds. Declaring an agent without behavior is not evidence of autonomy, and static typing is not evidence of predictive accuracy.

DEC-023: Formal 4-Pillar Documentation Architecture (Docs as Code)

  • Status: Accepted
  • Context: A programming language cannot scale or establish developer adoption without authoritative, structured documentation bridging mathematical modeling and practical growth engineering.
  • Decision: Standardize the FunnelScript documentation ecosystem (docs.funnelscript.org) into four canonical knowledge pillars:
    1. The Getting Started Guide: Net-new onboarding, CLI installation (uv tool, pipx, npx), IDE setup, and initial campaign compilation.
    2. The Language Reference: Strict syntactic and semantic specifications of all language blocks, types, and temporal keywords.
    3. The Bayesian & Simulation Guide: Mathematical documentation of PyMC-Marketing posterior calibration, adstock decay ($\lambda$), Hill half-saturation ($K$), and Monte Carlo risk interpretation.
    4. The Marketing Anti-Patterns Handbook: Compiler diagnostic manual displaying side-by-side "Bad Code vs. Good Code" comparisons for attribution cycles, audience mass leaks, and liquidity cliffs.
  • Rationale: Structures knowledge by distinct user intent and expertise levels while integrating automated docstring generation via modern SSG platforms (Mintlify / Fumadocs / MkDocs Material).
  • Consequences: Documentation is maintained as versioned markdown files directly within the repository under continuous CI verification.

DEC-024: The Modular Library, Framework, and Package Manager Ecosystem (fpm)

  • Status: Accepted
  • Context: Requiring developers to author recurring marketing flows (e.g. SaaS trial-to-paid, abandoned cart recovery, multi-channel attribution) from scratch impairs adoption and development velocity.
  • Decision: Establish a multi-tiered package and code-sharing architecture for FunnelScript:
    1. Libraries (libs): Modular, plug-and-play components (fs/channels/meta, fs/audiences/saas) providing pre-modeled kinetics and calibrated psychographic vectors.
    2. Frameworks (frameworks): Holistic business-model templates (GrowthEngine, OmniChannel) enforcing end-to-end structural invariants via Inversion of Control.
    3. Package Manager (fpm): The FunnelScript Package Manager managing dependency resolution, semantic versioning, and distribution of verified open-source and commercial strategy libraries.
    4. Built-in Industry Benchmarks: Standardized baseline parameter libraries (fs/benchmarks/ecommerce/fashion) enabling Day-1 simulation for organizations lacking proprietary PyMC historical data.
  • Rationale: Transforms FunnelScript from a syntax compiler into a global, extensible open-source marketing ecosystem with reusable, composable strategy primitives.
  • Consequences: The compiler must support module import resolution (import "path" as Alias), dependency lockfiles (funnelscript.lock), and decentralized registry publishing.

DEC-025: Specification-First Open-Source Adoption & Shim Strategy

  • Status: Accepted
  • Context: Building an end-to-end multi-tier agent-based compiler and simulation runtime is a massive, multi-year engineering undertaking. Postponing open-source release until full execution runtimes, distributed agent grids, and live provider integrations are finalized stalls adoption and isolates the core team from community feedback.
  • Decision: Adopt a two-stage "Specification-First" and "Linter Shim" wedge strategy:
    1. Standardize and release the formal Language Specification (EBNF grammar, AST schemas, operational semantics) and foundational research papers publicly first.
    2. Ship the lightweight static analysis engine / linter (funnelscript check) as a zero-dependency CLI.
    3. The linter delivers immediate, risk-mitigation value on Day 1 by catching structural marketing flaws (audience mass leaks, attribution cycles, unbounded loops) without requiring any simulation runtime.
    4. Provide clear compilation and runtime extension hooks for community contributors, compiler engineers, and simulation researchers to implement runtime backends (Python, Rust, WASM, Julia).
  • Rationale: Establishes credibility, academic rigor, and immediate practical utility with minimal surface area, converting early adopters from passive observers into active co-creators.
  • Consequences: The formal language specification and static verification contracts become the foundational source of truth; runtime implementations can evolve in parallel without fracturing the language standard.

DEC-026: Community Contribution Architecture (CONTRIBUTING.md & Issue Standard)

  • Status: Accepted
  • Context: An open-source movement requires an accessible, low-friction contribution pipeline that clearly segregates compiler internals, standard libraries, documentation, and external provider adapters.
  • Decision:
    1. Author a comprehensive CONTRIBUTING.md defining development environment setup (uv, bun), testing commands (uv run pytest, bun test), code style invariants (100% English, type annotations, zero unverified mocks), and architectural boundaries.
    2. Establish an explicit issue taxonomy with labeled entry points: good-first-issue (standard library channels, CLI enhancements), compiler (lexer, parser, AST transforms), runtime (simulation performance, discrete-event scheduling), and rfc (grammar proposals, language extensions).
    3. Mandate RFC (Request for Comments) process for any modification to language grammar, type system, or core invariants.
  • Rationale: Reduces contributor cognitive load, provides psychological safety, and enforces production-grade engineering standards across all community contributions.
  • Consequences: Enables scalable community growth while preserving the mathematical and architectural integrity of the core kernel.

DEC-027: Contextual World Rules and Snapshot-Atomic Transitions

  • Status: Accepted (experimental v0 reference interpreter)
  • Context: DEC-019 introduced the domain-neutral event kernel and DEC-022 introduced typed World declarations, but language-authored Worlds were static declarations without operational semantics. Marketers and library authors need a precise, testable state-transition substrate before stochastic or external effect models are added.
  • Decision:
    1. Extend World declarations with contextual rule NAME on event NAME { transition FIELD = EXPR; } blocks and typed expression/transition AST nodes.
    2. Define exact primitive types and restricted expressions (literal, same-owner field reference, numeric reference +/- matching numeric literal); forbid implicit coercion.
    3. Evaluate all assignment right-hand sides against the same pre-event state, apply a copy-on-write update, and reject ambiguous duplicate handlers/targets.
    4. Address input events as Owner.Event; execute through the existing EventMachine with explicit input timestamps and seeded deterministic replay.
    5. Expose a pure run-world CLI and reserve source-level event emission, stochastic decisions, economic models, Live/Shadow effect handlers, and external calibration for separately verified extensions.
  • Research and falsification: spec/rule-transitions-v0.md states H-R1 to H-R4 and mathematical invariants; evals/world-rules-v0.md ties tests to counterexamples.
  • Rationale: Source-level rules become executable without embedding audience/campaign assumptions or creating a second scheduler. Snapshot atomicity makes transition order semantics unambiguous.
  • Consequences: The core remains domain neutral. Runtime tests establish interpreter correctness only, not simulation fidelity or predictive market accuracy.

DEC-028: Source-Scheduled Local Events Through the Existing Event Calendar

  • Status: Accepted (experimental v0 contract)
  • Context: DEC-027 made World rule transitions executable, but source code could not cause subsequent reactions. The event kernel (DEC-019) already schedules reducer-emitted events with deterministic ties and explicit event-count limits.
  • Decision:
    1. Introduce a contextual World-rule statement: emit EventName after Delay;, where Delay is a finite nonnegative integer or floating-point literal in abstract World time units.
    2. Require a statically defined matching handler on the same entity/agent. Permit forward references and recursive local events, but reject unknown handlers and invalid delays before execution.
    3. Lower emitted events to Transition.events on the existing EventMachine; do not add a second scheduler, busy-loop, effect provider, or hidden automatic startup event.
    4. Preserve pre-event snapshot assignments, source order among same-time emissions, and the parent event priority (including zero-delay cases). The event processing cap halts recursive zero-delay cycles; finite horizons leave scheduled events pending.
    5. Defer cross-owner emissions, payloads, conditional triggers, probability distributions, cancellation, persistent delivery, and all Live/Shadow actions to separate typed and capability-gated contracts.
  • Research and falsification: spec/event-emission-v0.md specifies H-E1 through H-E4 and temporal invariants; evals/event-emission-v0.md provides RED/GREEN and regression evidence.
  • Rationale: Causal sequences become expressible in the language using the same discrete-event semantics already tested, while compiler and runtime remain business-domain neutral.
  • Consequences: Worlds can now schedule local events after an externally supplied trigger. They remain neither autonomous digital twins nor validated predictive market models.

DEC-029: Type-Checked Pre-Event Guards for World Rules

  • Status: Accepted (experimental deterministic World language subset)
  • Context: DEC-027 defines snapshot-atomic assignments and DEC-028 permits local source emissions. Without declarative conditions, recursive event chains can only stop at event caps or external input boundaries.
  • Decision:
    1. Support an optional when (field OP literal) immediately after a World rule's on event EventName clause. Compile it into a typed guard AST node, not a runtime string expression.
    2. Resolve field exclusively on the owning entity or agent and require exact primitive type equality with the literal. Support == and != on all primitive types; allow <, <=, > and >= only for numeric fields.
    3. Evaluate the predicate once against the pre-event snapshot before all rule statements. A false guard consumes the incoming event but yields the original state with no new events and no external effects.
    4. Keep expressions deliberately restricted: no boolean conjunctions, arbitrary function calls, probabilistic draws, cross-owner reads or side effects. These need separately specified semantics and tests.
  • Research and falsification: spec/world-guards-v0.md defines H-G1 through H-G4 and safety invariants; evals/world-guards-v0.md maps 20 focused tests and the regression suite to observable counterexamples.
  • Rationale: Conditional decision mechanics become expressible while compiler and runtime retain a small domain-neutral, predictable semantic surface.
  • Limit: Passing a guard test does not validate causal attribution, synthetic agent psychology or calibrated marketing forecasts.

DEC-030: Exact-Typed Local Event Records at Both Calendar Boundaries

  • Status: Accepted (experimental World-language subset)
  • Context: DEC-019's domain-neutral Event object already holds an opaque model-owned payload, while DEC-027 to DEC-029 source rules lacked static knowledge of event data. Mutable or unstructured payloads could reach source handlers with no type contract.
  • Decision:
    1. Add contextual source event Name(field: PrimitiveType, ...); declarations per entity/agent. Validate unique event and field names and restrict to the existing exact int, float, bool, string types.
    2. Allow payload.field in current handler transition expressions, and optional named arguments in same-owner emit Name(field = Expr) after Delay;. Resolve event fields and argument types statically, with no implicit numeric promotion.
    3. Preserve legacy no-payload handlers and source emission statements. Undeclared events have an implicit empty record; structured input to those handlers must fail instead of bypassing type checks.
    4. Validate source interpreter message shape, string keys, exact primitives, and finite floats before any handler runs and before generated messages enter the existing event calendar. Guards cannot bypass validation. Keep the general Python EventMachine opaque and independent of World schemas.
    5. Extend the existing repeatable run-world --event input to accept a JSON event record while preserving OWNER.EVENT@TIME compatibility and source-specified order. No new evaluator, network effects, or scheduler is introduced.
  • Research and falsification: spec/typed-event-payloads-v0.md defines H-P1 to H-P4 and exact-record invariants. evals/typed-event-payloads-v0.md records RED/GREEN evidence, 37 focused tests, 158 total passing Python tests, CLI smoke checks and package build.
  • Rationale: Static message contracts prevent accidental cross-field, wrong-type and nonfinite data propagation while letting communities define arbitrary domain event vocabularies.
  • Limits: No composite records, polymorphism, stochastic decision semantics, cross-owner delivery, persistent queues, empirical market fidelity or Live capability authorization is implied.

DEC-031: Reproducible Source-Level Stochastic World Transitions

  • Status: Accepted (experimental v0 contract, 2026-10-31)
  • Context: The existing event kernel provides an isolated random.Random(seed), but World source transitions were deterministic and ignored that RNG. Introducing an unsourced or independently seeded draw would destroy replay guarantees and weaken science-grade falsification.
  • Decision:
    1. Add contextual typed expressions sample bernoulli(p) returning bool and sample uniform(low, high) returning float only inside transition assignments. Arguments are exact floats from literals, same-owner state, or declared payload.field; no implicit promotion.
    2. Validate constant arguments statically and dynamic values immediately before drawing: Bernoulli 0 <= p <= 1, finite numbers; Uniform finite ordered bounds with finite representable span.
    3. Consume exactly one random() draw per executed operator, including degenerate ranges. A false rule guard uses none. Draws follow transition source order, and every parameter reads the same pre-event snapshot.
    4. Reuse the EventMachine run RNG, with no new scheduler or entropy source. Keep deterministic advance behavior; require caller-supplied rng when advance executes a sampled transition.
    5. Explicitly exclude random guards, event arguments/delays, independent per-agent streams, implicit calibration, Market Twin claims, and Live effects until separately studied.
  • Research and falsification: spec/stochastic-operators-v0.md H-S1 through H-S4, evals/stochastic-operators-v0.md, 25 focused tests and 183 passing Python tests; the existing Bun tests and build were verified.
  • Rationale: Precisely scoped, typed sampling makes synthetic decisions expressible in World code without inventing empirical probabilities or weakening seeded replay.
  • Limits: Reproducible execution is not validated predictive fidelity; event-order changes can shift the random stream and downstream draws.

DEC-032: Source-Imported World Modules and Initial Marketing Standard Library

  • Status: Accepted (experimental v0 contract, 2026-10-31)
  • Context: Domain-neutral World declarations and stochastic rules exist, but without source-level modules community authors cannot reuse standard marketing abstractions across Worlds. Introducing campaign or conversion as compiler keywords would contradict DEC-008/010.
  • Decision:
    1. Support contextual import "reference.fnl" as Alias; statements inside a World, where reference is either a confined relative source path or a packaged std:marketing/... path. Compile imports into ordinary one-owner World declarations under the alias, then use the existing type checker and event kernel.
    2. Restrict the first module contract to exactly one exported entity or agent, aliased to one unique owner. Reject duplicate names, cycles, depth beyond 16 imports, non-World content, absent modules, absolute paths, parent traversal and symlink escapes before any runtime state transition.
    3. Distribute the actual stdlib/marketing/lead_response.fnl World source inside the Python wheel. No Python execution, network retrieval, separate scheduler, marketing-only compiler semantics, or new core dependencies are introduced.
    4. Define the first marketing library as a single-exposure lead-response journey with typed Impression/Checkout events, seeded Bernoulli conversion, one scheduled Checkout, and scenario-defined spend/revenue. A second Impression is deliberately ignored. It is not a consumer population model or empirical economic account.
    5. Treat cpc, order_value, and conversion_probability as user-provided assumptions. Existing float typing checks finiteness, but nonnegative money and real conversion fidelity remain explicit unsolved boundaries.
  • Research and falsification: spec/marketing-stdlib-v0.md (H-M1 to H-M4), evals/marketing-stdlib-v0.md and tests/test_world_modules.py. Packaged-wheel smoke runs outside the repository.
  • Rationale: Makes marketing reuse a library-author decision while preserving the generic language's parser, semantics, scheduler and type system.
  • Limits: No multi-export modules, versioned package registry, source-level parameters, multi-agent financial conservation, cross-owner dispatch, real data calibration, or Live execution authorization.

DEC-033: Tagged Git-Source Experimental Preview and Safe World Onboarding

  • Status: Accepted for candidate v0.2.0a1 (2026-10-31); publication status is independently verified.
  • Context: A packageable language runtime and source-defined Marketing Standard Library exist, but the first-time user still needs a cloned checkout and manually authored source. No repository CI existed, and a green local build was not sufficient evidence for a distribution claim.
  • Decision:
    1. Expose funnelscript init-world TARGET.fnl as a minimal, deterministic World starter with the existing std:marketing/lead_response.fnl import. Use exclusive create mode, reject wrong suffix/missing parent, and preserve existing user bytes on repeated invocation.
    2. Designate PEP 440 0.2.0a1 as the package candidate, with v0.2.0a1 as its Git source reference if safely published. A Git source installation through uvx --from git+https://... is the experimental distribution channel; no PyPI or production release is claimed.
    3. Add pinned GitHub Actions steps for locked Python tests, source/wheel build, clean-directory installed-wheel execution, and Bun frontend lockfile tests/build. Artifacts are retained for 14 days. CI configuration is not evidence of actual remote success.
    4. Keep onboarding examples and disclaimers explicit: a single typed Impression with model-supplied probability, seeded Bernoulli and one delayed Checkout is a reproducible interpreter example, not a validated market prediction or authority to execute Live effects.
  • Research and falsification: spec/developer-preview-v0.md (H-P1 to H-P4), evals/developer-preview-v0.md, tests/test_preview_quickstart.py and a candidate-vs-remote release audit.
  • Rationale: A first independent user can try the reference language without learning the repository internals, while a minimal package/tag/CI path is inspectable and reversible before a public release.
  • Limits: No PyPI publishing, general package registry, module signatures, clean-machine user study, real economic model validation, or Live execution. A source tag alone is not a verified GitHub Release object.

DEC-034: Repository-Specific Documentation Contracts for the Experimental Preview

  • Decision (2026-10-31): Application and research each maintain a contributor entrypoint truthful to the local file tree and automated no-new-dependency checks for canonical relative Markdown links. Shipped World functionality is distinguished from the legacy strategy simulator and proposed ecosystem, calibration, and Live capabilities.
  • Alternatives: Shared copied instructions were falsified by missing research src/ and apps/web/ paths and three broken decision/debate links; a new documentation framework adds risk without solving current failures.
  • Research and tests: H-P5 through H-P7 in spec/developer-preview-v0.md; research tests/test_docs_links.py, application tests/test_documentation_links.py and FL-018. The evaluated public Git tag remains v0.2.0a1.
  • Limits: Link checks do not prove external URLs, code-block correctness, scientific truth, economic conservation or out-of-sample predictive validity.

DEC-035: Curated, Named Agent Skills with an Explicit Vendor Boundary

  • Decision (2026-10-31): Keep the 22 primary repository-bundled skills available for contributors; require directory slugs to equal their hyphenated SKILL frontmatter names, and validate index coverage and immediate local resource links. Keep required scripts and references. Remove only observed redundant archives and ignored local build outputs.
  • Provenance: Agent Skills format specification; research H-B1 through H-B4 (spec/skill-bundle-v0.md) and conformance evaluations. App and research checkouts retain separate ownership while mirroring the 22 primary skill directories.
  • Risk boundary: The vendored academic-paper pipeline refers to upstream shared protocols not fully bundled. A narrow default language-pair registry is included for the observed broken link, but complete offline agent-pipeline behavior is not claimed. Do not erase vendor evidence/scripts simply to reduce line counts.
  • Observed impact: Four naming mismatches and one entrypoint-link failure were corrected; the registry's own abstract-guide link now resolves relative to its actual location. A redundant J-Space archive was removed; ignored Cargo build output was cleaned without changing tracked Rust code. Final full regression: application 219 passed (58 subtests), research 5 passed. No FunnelScript World or marketing simulation semantics change.

DEC-036: Explicit CLI Failure Taxonomy and Bounded JSON Event Inputs

  • Status: Accepted as an experimental CLI boundary contract (2026-11-01).
  • Research anchor: Fail-fast parser contracts, bounded untrusted input parsing, and the existing exact-typed event and finite-time semantics of DEC-030.
  • Falsifiable hypotheses: H-CLI1 unexpected parser implementation faults must not be reported as user syntax errors; H-CLI2 an event JSON input exceeding 65,536 UTF-8 bytes must fail before decoding; H-CLI3 an exporter filesystem failure must return I/O status 2 without an earlier export-success report.
  • Invariants: In check/compile/simulate, known parser/lexer/type/JSON validation failures return 1, source-file read and export OSErrors return 2, and unexpected implementation faults propagate. Existing run-world runtime/error exit code 1 remains unchanged. The JSON byte bound includes whitespace and is applied per JSON --event argument, not to legacy OWNER.EVENT@TIME strings. Event retains sole responsibility for finite, nonnegative timestamps; user-supplied absolute export paths remain valid.
  • Scope and rationale: Narrow classification and failure reporting in the existing CLI; no parser grammar, event semantics, simulation economics, path sandbox, new dependency, or prediction claim. Export notices are delayed until all requested exports have succeeded; this is not multi-file atomicity.
  • Verification boundary: tests/test_cli.py contains direct falsification tests. A local green test run does not certify this behavior in the existing v0.2.0a1 published tag.

DEC-037: EOF-Safe Parsing and Exact-Typed Narrow World Arithmetic

  • Status: Accepted as a bounded experimental World language extension (2026-11-01).
  • Context: DEC-027 originally restricted state +/- literal and subsequent payload typing extended one right operand category. Empty token sequences could accidentally index tokens[-1]; * and / were not supported and comments already claimed //.
  • Decision: Extend the existing World rule-expression parser with one +, -, * or / operation whose left operand is a same-owner state reference and right operand is a matching exact-type literal, same-owner state reference or declared payload field. Retain old single-value and sample expressions. Preserve // comment priority. Permit no chains, precedence grammar, parentheses, casts or arbitrary calls. Produce deliberate ParserError at empty/exhausted input.
  • Typing and runtime: Both operands must be exactly int or exactly float; bool is not numeric. +, -, * preserve operand type; / yields float even for int/int. Compile-time literal zero denominator is invalid; dynamic zero is a controlled runtime failure. Float expression literals/operands and resulting floats must be finite; integer arithmetic remains exact and unbounded, while int/int division conversion overflow is controlled. Initial state type-check policy remains unchanged for compatibility.
  • Scope and rationale: This extends only DEC-027's narrow syntactic subset while preserving its snapshot-atomic semantics, DEC-030 payload checks and DEC-031 event-ordered seeded RNG. It adds no market-financial assumptions or new dependencies.
  • Evidence and limits: H-AR1 through H-AR3 in spec/arithmetic-expressions-v0.md; observed RED/GREEN tests and full verification in evals/arithmetic-expressions-v0.md. This is an interpreter correctness claim, not a real-market validation result.

Phase 006 evidence checkpoint (no new ADR)

The Phase 006 conformance corpus exercises accepted DEC-019, DEC-027 through DEC-032, and DEC-037 on the experimental Python World reference interpreter. H-C1 through H-C3 and their precise falsifiers are specified in spec/world-conformance-v0.md; independently fixed expected/rejection records are evaluated in evals/world-conformance-v0.md. This evidence adds no architectural decision and does not supersede any accepted ADR. Version-pinned canonical JSON is an evaluation artifact, not a new runtime or exposed production trace API. External predictive validity is not inferred.


Phase 007 negative capability checkpoint (no new ADR)

On 2026-11-01, public WorldExecutor and EventMachine execution of two explicitly named owners demonstrated deterministic replay but not stable keyed per-agent substreams. Reversing equal-time input insertion order swaps the first two draws of the shared random.Random(seed) stream. See spec/population-reference-v0.md and evals/population-reference-v0.md, P-RNG-ORDER-1. This is consistent with accepted DEC-019/031 and does not replace their semantic contract. No new population architecture was accepted; a World-backed population adapter remains Proposed. Legacy and World remain non-equivalent. Phase 007 is BLOCKED, with no production change or empirical-validity claim.


Phase 007A opt-in runtime capability checkpoint (no accepted ADR)

On 2026-11-01, a bounded, explicitly opt-in Python PopulationExecutor adapter was implemented and verified against proposed spec/population-identity-rng-v0.md and evals/population-identity-rng-v0.md. It wraps independent WorldExecutor.run instances with stable (world_seed, trial_id, agent_id, stream_role) SHA-256-derived seeds and exact identity partitions; it does not modify DEC-019/031 default World semantics or accept a new language/legacy migration architecture. Agent interactions, shared shocks, within-handler stream roles and state-restoration semantics require a separately Proposed, reviewed, then accepted ADR before implementation. The original P-RNG-ORDER-1 default-World counterexample remains true. Phase 007 financial/metric requirements remain blocked. No independent external reviewer sign-off or statistical calibration was obtained.


Phase 007B bounded financial-model checkpoint (no new accepted ADR)

2026-11-01: Domain-owned MarketingLedger and trial/risk metric evaluators were implemented only in the opt-in Python marketing standard library, governed by proposed spec/financial-ledger-metrics-v0.md and measured evals/financial-ledger-metrics-v0.md. This is consistent with accepted DEC-009: cash, receivable and paid-spend conservation are model rules, NOT unconditional language/compiler semantics. DEC-019, DEC-027, DEC-031 and legacy stochastic/economic behavior remain unchanged. Exact integer minor-unit posting prevents ambient Decimal context from corrupting recorded money. No accepted ADR is created by this checkpoint. Automatic financial events from World, shared financial accounting across interacting agents, credit/tax/refund semantics, source-causal attribution and legacy telemetry migration require separate research and approval. This scope verifies a synthetic ledger, not empirically calibrated marketing behavior or statistical independence.


Phase 007C provenance integration checkpoint (no new accepted ADR)

2026-11-01: Opt-in WorldExecutor.run(trace=[]) and PopulationExecutor.run(trace=True) observe executed World transitions without modifying EventMachine ordering, default RNG, language rules or legacy processing. Domain-owned DeclaredSalePolicy, recognize_sales, and post_provenanced_trial validate state-transition evidence, canonical transaction IDs, idempotent duplicate replay and authoritative MarketingLedger conservation. Constrained to independently executed agent calendars and model-authored event-to-sale policy. The local processed-event index is not a kernel insertion ordinal; mutable/in-process audit evidence is not cryptographically authenticated. Costs, settlements and writeoffs are manually declared and are not World-caused. This is a Proposed reference integration under accepted DEC-009, DEC-019 and DEC-031, not automatic financial World semantics or an Accepted ADR. Further shared-cash interactions, externally valid causality, accounting richness, and calibration require separate review. See spec/transaction-provenance-v0.md and evals/transaction-provenance-v0.md.

Phase 007D financial provenance checkpoint — proposed, NOT an Accepted ADR

2026-11-01: Domain-owned DeclaredFinancialAction and post_authorized_trial() separate verified World-caused sales from author-asserted external paid actions, validate local operation identity and delegate exact cash/receivable conservation to MarketingLedger. Existing Phase 007C unprovenanced adapter remains available without being labeled authenticated. Under DEC-009, no economic rules migrated into compiler or World scheduler. Cryptographic authenticity, persistent replay, shared cash arbitration and empirical calibration require new explicit approval and are not implied. Evidence: spec/financial-consequence-provenance-v0.md, evals/financial-consequence-provenance-v0.md.

Phase 007E — Proposed, not Accepted ADR (2026-11-01)

Bounded implementation record only: opt-in canonical financial audit v1 with strict trace-and-policy restoration and atomic single-writer checkpoint. No change to existing accepted DEC IDs or new Accepted ADR. Producer authentication, actual authorization and shared-state serializability remain undecided pending operator permission and separate threat-model evidence. See spec/durable-financial-provenance-v1.md.

Phase 007F — Implementation checkpoint; no accepted architecture decision

2026-11-01: Opt-in single-writer commit coordinator, versioned deterministic receipt and recovery validation added within the already approved domain boundary. A revalidated complete audit is required before publication; a changed checkpoint requires the previous trusted receipt; a successful acknowledgement requires publication plus revalidation; uncertain syscall outcomes raise an explicit recovery-required exception. Exactly-once network delivery, multi-writer serializability, producer authentication, crash-proof file hardware, and arbitrary valid rollback prevention are not accepted or demonstrated. Existing DEC-009 and Phase 007E contracts remain unchanged. See spec/financial-commit-recovery-007f.md. No new Accepted ADR.

Phase 007G — Proposed language implementation checkpoint, not Accepted ADR

Versioned additions introduce bounded typed arithmetic AST composition, deterministic explicit World declaration imports, and versioned strict event playbook input. Existing DEC-009 accounting boundaries, DEC-027 pre-event snapshot semantics and DEC-031 keyed RNG remain controlling. No legacy engine migration or empirical equivalence decision is made. Research: spec/phase-007g-composable-language-v1.md.