FOGE
FOGE — Form Generator Engine
0. Identity and governance status
FOGE is a ZAYAZ Engine in the Computation Hub.
Its stable documentation identity is FOGE.
The current canonical Engine registry does not yet provide a governed FOGE EID, and the exact owning Component below the Computation Hub Module has not yet been resolved in canonical architecture. Those are governance gaps, not invitations to invent local identifiers.
The same rule applies to CSI and CMI bindings: this specification describes the required contracts, but concrete CSI families, CMI bindings and published API routes must be registered through their governing registries before they become production contracts.
This page is the canonical detailed-behaviour specification for FOGE. Legacy Manual chapter 92 is preserved as design lineage, not as higher authority than the current ZAYAZ constitutions, Pergamum Pulse, SSSR, TrustGate-era architecture or later canonical specifications.
1. Purpose
FOGE is not fundamentally a form builder.
FOGE is the governed interaction compiler and runtime projection engine of ZAYAZ.
Its constitutional job is:
Transform governed requirements and canonical signal semantics into immutable interaction releases, then project only the interaction still necessary for the current context.
A visible web form is therefore only one possible output projection.
The canonical object is the governed requirement-and-signal contract behind the interaction.
FOGE may ultimately produce:
- a full reporting form;
- a six-question Delta Form derived from an eighty-seven-item requirement set;
- one confirmation request;
- one evidence-upload task;
- a verifier review queue;
- an API payload contract;
- a machine-to-machine data request;
- a guided policy/document action;
- a disclosure preparation surface; or
- no user-facing form at all when every applicable requirement is already satisfied from acceptable governed data.
This distinction is foundational.
2. The form is a projection, not the source of truth
Traditional form systems start with pages, sections and fields and then ask a user to fill them in.
FOGE starts from the opposite direction:
What is governing this interaction?
↓
What requirements apply?
↓
What canonical signals can satisfy them?
↓
What evidence or authority is required?
↓
What does ZAYAZ already know or derive acceptably?
↓
What remains unresolved?
↓
What is the smallest useful interaction now?
The UI is therefore downstream of governance and resolution.
This allows ZAYAZ to change the interaction without changing the meaning of the underlying requirement and to reuse the same governed signals across frameworks, organizations, channels and reporting periods.
The result is materially different from a questionnaire platform:
FOGE does not ask what it can render. It renders only what ZAYAZ still needs to ask.
3. Constitutional responsibility boundaries
FOGE must remain powerful without becoming an authority it does not own.
| Capability | Primary owner | FOGE responsibility |
|---|---|---|
| Interpret legislation, standards, regulatory guidance and authoritative requirements | Pergamum Pulse | Consume governed requirement packages; never reinterpret source law independently at runtime |
| Determine regulatory applicability semantics and authoritative derivation | Pergamum Pulse | Compile the governed semantics into executable interaction conditions |
| Maintain canonical signal meaning, data type, units and signal identity | SSSR | Bind interaction items to canonical signals; never redefine signal semantics locally |
| Select the applicable prepared release for runtime context | Form Resolver capability | Provide the governed release catalogue and extension rules; accept the resolved selection |
| Route runtime work across components | ZSSR | Expose/consume governed interaction events and routing context |
| Calculate derivable values | MICE / governed compute engines | Declare calculation dependencies and consume governed results |
| Validate incoming values and structural quality | DaVE | Declare validation expectations and consume validation outcomes |
| Evaluate completeness and integrity | DICE | Expose applicable requirement state and consume completeness/integrity findings |
| Evaluate source authority, evidence sufficiency and trust | TrustGate / assurance services | Declare evidence and authority expectations; consume trust decisions rather than scoring trust itself |
| Render flexible interactive UI | FFG | Produce the governed projection and presentation metadata consumed by the renderer |
| Apply contextual presentation relevance | CRE-FFG | Permit relevance-aware presentation without changing mandatory requirement semantics |
| Explain decisions and lineage conversationally | ZARA | Preserve enough lineage for ZARA to explain why an item was asked, satisfied or omitted |
The central invariant is:
Pergamum Pulse governs what the authoritative requirement means. FOGE compiles how that requirement becomes executable interaction. Runtime services resolve whether interaction is still necessary.
FOGE does not become a regulatory authority, trust authority, canonical signal registry, computation engine family or free-form UI framework merely because it orchestrates their outputs.
4. The modern FOGE architecture
FOGE has two fundamentally different operating phases.
4.1 Design and governance time
At design time, authoritative regulatory or methodological knowledge has already been transformed into governed Pergamum Pulse objects and requirement packages.
FOGE compiles those packages against SSSR signal semantics and other governed contracts into immutable FOGE releases.
Authoritative source
↓
Pergamum Pulse knowledge objects
↓
Governed requirement package
↓
FOGE source definition
↓
Schema + reference validation
↓
FOGE compiler
↓
Canonical JSON release
├── runtime database projection
├── search / discovery projection
├── renderer projection
└── immutable artifact storage
4.2 Runtime
At runtime, FOGE does not normally re-read legislation or rebuild regulatory interpretation.
Instead:
Runtime context
↓
Form Resolver capability
↓
Selected immutable FOGE release
+ approved contextual extensions
↓
Complete FOGE Form Instance
↓
Resolution / prefill / calculation / trust checks
↓
Explicit item states
↓
Runtime projection
├── no interaction
├── confirmation task
├── evidence request
├── Delta Form
├── verifier task
└── full form where genuinely required
The design-time release and the runtime instance must never be conflated.
5. Pergamum Pulse → FOGE requirement contract
Pergamum Pulse takes FOGE beyond the original framework-table architecture.
FOGE should not receive free-form legislation, scraped text, an LLM summary or an unversioned list of metrics and decide what the law requires.
It should receive a governed requirement package that is already traceable to authoritative knowledge.
A requirement package must be capable of expressing, where applicable:
- package identity and version;
- authoritative source identity and version;
- derivation chain;
- jurisdiction;
- effective-from / effective-to semantics;
- applicability conditions;
- thresholds;
- organization or object characteristics;
- NACE / sector conditions;
- group, subsidiary or value-chain conditions;
- reporting or operational scope;
- mandatory requirements;
- conditional requirements;
- permitted alternatives;
- voluntary pathways;
- disclosure or data requirements;
- evidence expectations;
- authority requirements;
- calculation permissions or constraints;
- request-minimisation constraints where applicable;
- cross-framework mappings;
- source citations and provenance;
- supersession relationships; and
- stable requirement references suitable for replay and audit.
Conceptually:
requirement_package_id: PP-PKG-EXAMPLE-001
package_version: 1.0.0
source_ref: PP:SOURCE:EXAMPLE
jurisdiction: EU
effective_from: 2026-07-01
applicability:
conditions:
- jurisdiction
- employee_count
- turnover
- nace
- value_chain_role
requirements:
- requirement_ref: PP:REQ:001
requirement_type: quantitative
obligation: mandatory
signal_refs:
- sssr:example.metric
evidence_expectation:
class: source_record
- requirement_ref: PP:REQ:002
requirement_type: attestation
obligation: mandatory
signal_refs:
- sssr:example.attestation
This example is conceptual. Exact package schemas and IDs are governed separately and must not be inferred from the example.
6. FOGE source and release model
6.1 Human-authorable source
FOGE definitions should be maintained as source-controlled YAML or an equivalent governed authoring representation.
A framework package may be organized conceptually as:
foge/
└── frameworks/
└── <framework>/
└── <version>/
├── framework.yaml
├── forms/
├── items/
├── rules/
├── mappings/
├── extensions/
└── manifest.yaml
The exact repository location is an implementation choice and must be governed before it becomes a hardcoded path contract.
6.2 Canonical compiled representation
The FOGE compiler must produce deterministic canonical JSON.
The compiled release must:
- normalize ordering;
- contain no authoring-only comments;
- resolve or pin internal references;
- pin requirement-package versions;
- pin signal and rule versions where applicable;
- preserve source and Pergamum lineage;
- include a content digest;
- be digitally signable or anchorable through the applicable artifact-governance mechanism;
- declare replay characteristics; and
- be immutable after publication.
The governing separation is:
YAML or equivalent = governed authoring representation
Canonical JSON = immutable machine release
Database projection = query/runtime optimization
Runtime state = organization/object-specific execution data
6.3 Immutable releases
A published release is never edited in place.
release_id: FOGE-EXAMPLE-1.0.2
version: 1.0.2
status: active
content_digest: sha256:...
supersedes: FOGE-EXAMPLE-1.0.1
A correction produces a new release.
Historical runtime instances remain pinned to the release under which they were created unless a governed migration explicitly states otherwise.
7. Canonical interaction model
The legacy FOGE chapter was field-centric because fields were the easiest way to describe form generation at the time.
Modern FOGE must be requirement- and signal-centric.
A release conceptually contains:
FOGE Release
├── release metadata
├── Pergamum requirement-package bindings
├── interaction definitions
│ ├── sections / groups
│ ├── items
│ └── presentation hints
├── requirement bindings
├── SSSR signal bindings
├── applicability / required-when rules
├── evidence expectations
├── validation-profile references
├── calculation dependencies
├── authority / trust expectations
├── template / guidance references
├── contextual extension rules
└── lineage + replay metadata
The exact persisted object names are not yet canonical.
The architecture is canonical: requirement semantics and signal semantics remain externally governed; FOGE binds them into executable interaction contracts.
8. Requirements, signals and interaction items are many-to-many
The strongest concept in the original metrics_field_linkage design remains valid, but the modern relationship is broader than metric → field.
Pergamum Requirement(s)
↕
FOGE Item(s)
↕
SSSR Signal(s)
This permits:
- one legal requirement to require several signals;
- one signal to satisfy several requirements;
- one interaction item to collect several related signals where appropriate;
- one signal to be collected through different interaction types in different contexts;
- one shared datum to satisfy multiple frameworks without asking the user twice; and
- one runtime value to retain separate lineage to every requirement it satisfies.
FOGE must not create duplicate semantic fields merely because two frameworks phrase the same underlying data requirement differently.
Conversely, semantic similarity must not be treated as equivalence unless the applicable Pergamum/SSSR mapping is governed.
9. Field and presentation metadata
FOGE still needs presentation metadata, but presentation metadata is not canonical signal meaning.
A FOGE item may specify or reference:
- label or localized label key;
- help text;
- interaction type;
- display grouping;
- render order;
- unit presentation;
- option-set reference;
- confirmation language;
- evidence-upload affordance;
- read-only state;
- visibility hint;
- accessibility metadata; and
- template/guidance actions.
The old numeric InputHandler codes and DSI/SID grammar are not constitutional FOGE identities.
Modern render behavior should be represented through governed, self-describing contracts and registries rather than opaque numeric codes embedded in form logic.
FOGE defines the required interaction semantics; FFG or another governed rendering surface turns those semantics into UI.
10. Contextual extensions
A baseline FOGE release may need specialization for sector, geography, business model, product type, value-chain role or other governed context.
Examples include:
- NACE-specific process detail;
- region-specific evidence;
- sector-specific certificates;
- product-level evidence;
- energy-market detail;
- additional calculation inputs;
- local units or presentation;
- higher-resolution data for a permitted methodology; or
- explicit voluntary information.
Contextual specialization must be represented as a governed extension or overlay, not an invisible mutation of the baseline release.
An extension should preserve at least:
base_release_ref
extension_identity
extension_version
extension_type
applicability_context
reason
rules_or_component_ref
provenance
approval_state
content_digest
10.1 Non-weakening invariant
A contextual extension may specialize or add to a governed baseline, but it may not silently remove, weaken or reinterpret a mandatory Pergamum-derived requirement.
Where a requirement legitimately becomes not applicable, the reason must resolve through governed applicability semantics, not through a UI hide rule.
11. AI use inside FOGE
AI can add significant value to FOGE, but it cannot become requirement authority.
AI may assist with:
- proposing contextual extensions;
- classifying source material against existing signals;
- suggesting likely prefill candidates;
- generating user-friendly explanations;
- summarizing why an item is required;
- generating concise Delta Form language;
- recommending presentation groupings;
- finding duplicate interaction items;
- suggesting evidence categories;
- ranking governed templates or guidance; and
- identifying possible form-definition defects for review.
AI must not:
- invent regulatory obligations;
- create a canonical signal definition merely because a field appears useful;
- silently remove mandatory requirements;
- reinterpret a Pergamum requirement at runtime;
- promote a plausible value to authoritative without the required trust/evidence decision;
- mutate a published release; or
- create an unregistered architectural identity to close a documentation gap.
Material AI-assisted changes to a FOGE definition must be reviewable, versioned and replayable.
12. Form resolution
Runtime context does not normally generate a new regulatory interpretation.
A Form Resolver capability selects the correct prepared release and permitted contextual extensions.
Input context may include:
- organization or object identity;
- E-C-O identity context where relevant;
- jurisdiction;
- reporting period;
- reporting purpose;
- employee count;
- turnover;
- legal form;
- NACE / sector;
- group status;
- value-chain role;
- buyer/supplier context;
- product or facility context;
- known Pergamum applicability context; and
- other governed facts required by the release-selection rules.
A conceptual result is:
resolution_id: FR-EXAMPLE-001
base_release_ref: FOGE-EXAMPLE-2026.2
extensions:
- FOGE-EXT-SECTOR-EXAMPLE
- FOGE-EXT-REGION-EXAMPLE
resolution_basis:
country: SE
employee_count: 412
nace: C24.10
resolved_at: 2026-09-08T10:00:00Z
The example IDs are illustrative only.
The ownership and canonical identity of the Form Resolver capability remain to be finalized. It must not be silently collapsed into FOGE or another engine merely for implementation convenience.
13. The complete FOGE Form Instance
After release selection and approved extension application, ZAYAZ materializes a complete FOGE Form Instance.
The complete instance is the authoritative runtime requirement set for that context.
It must preserve:
FOGE Form Instance
├── pinned base release
├── pinned extension set
├── runtime subject / organization / object context
├── purpose and reporting period
├── applicability basis
├── complete applicable item set
├── requirement and signal bindings
├── resolution observations
├── item runtime states
└── lineage / replay context
FOGE must materialize the complete applicable set before deriving a reduced user-facing projection.
This allows ZAYAZ to explain both:
- why something was asked; and
- why something was not asked.
The Delta Form is never the canonical requirement record.
14. Resolution and prefill
Before exposing an item to a human, ZAYAZ should attempt to satisfy it from permitted governed sources.
Candidate source classes may include:
- existing accepted ZAYAZ data;
- canonical identity/entity data;
- previous accepted contributions;
- authoritative connected source systems;
- accounting, ERP or ACF data;
- official registries and public authoritative data;
- governed external information providers;
- buyer/client-held evidence;
- valid estimates where the requirement permits estimates;
- MICE-derived or engine-derived values where calculation is permitted; and
- user/supplier confirmation or new contribution.
This is not a simple precedence list.
A candidate value is acceptable only when its source authority, freshness, period, evidence, validation and requirement-specific conditions are sufficient.
Each resolution observation should preserve enough information to reconstruct:
candidate value
source reference
source authority
source timestamp / effective period
provenance
confidence where applicable
evidence reference
requirement reference
signal reference
validation outcome
trust / authority decision reference
resolution decision
FOGE declares what is needed. The applicable trust and validation services decide whether the candidate satisfies those expectations.
15. Item runtime states
Every applicable FOGE instance item must resolve to an explicit state.
Recommended core states are:
| State | Meaning | Default user-facing behavior |
|---|---|---|
SATISFIED | Requirement fulfilled from an acceptable governed source | Do not ask |
PREFILLED | Candidate value populated from an acceptable source but presentation may still be useful or required | Show without forcing re-entry |
NEEDS_CONFIRMATION | Candidate exists but confirmation/attestation is required | Ask for confirmation, not re-entry |
MISSING | Required value/evidence cannot be resolved acceptably | Ask only for the missing datum/evidence |
NOT_APPLICABLE | Governed applicability evaluation says the item does not apply | Do not ask; preserve basis |
WAIVED | Governed decision explicitly waives the requirement/item | Do not ask; preserve authority and reason |
BLOCKED | Required context, authority or dependency is unresolved | Prefer internal resolution/escalation before user request |
Additional states may be introduced only when their semantics are governed and do not blur these core meanings.
A UI hide flag is not a substitute for a runtime state.
16. Delta Form projection
The FOGE Delta Form is the unresolved remainder of the complete applicable instance.
It is generated only after:
- release resolution;
- complete instance materialization;
- data reuse;
- prefill attempts;
- permitted calculations;
- source-authority and trust evaluation;
- validation checks needed for resolution; and
- item-state determination.
A Delta Form may contain:
- missing required values;
- required confirmations;
- required attestations;
- missing evidence;
- unresolved conditional questions needed to establish applicability; and
- optional items only where a user has explicitly selected a permitted voluntary pathway.
Example:
Complete FOGE Instance: 87 applicable items
51 SATISFIED from existing governed data
12 SATISFIED / PREFILLED from connected systems
9 SATISFIED / PREFILLED from external authoritative sources
5 SATISFIED from governed calculations
4 NOT_APPLICABLE
3 NEEDS_CONFIRMATION
3 MISSING
────────────────────────────────────────────
87 complete runtime items
FOGE Delta Form
────────────────
3 confirmation items
3 missing items
────────────────
6 user-facing items
The interaction is six items because the requirement set is eighty-seven items — not despite it.
This implements the broader ZAYAZ principle:
No Ask Before Reuse.
17. Zero-question outcome
A successful FOGE execution may produce no form at all.
If every applicable item is satisfied from acceptable governed sources, the correct projection is:
Complete FOGE Form Instance
↓
All applicable items SATISFIED / NOT_APPLICABLE / governed WAIVED
↓
No Delta Form
↓
No unnecessary user action
0 questions is therefore a valid and desirable result, not an error state.
This is especially important for reusable supplier data, recurring reporting periods, integrated ERP/accounting data and machine-to-machine regulatory workflows.
18. Trust, evidence and authority
The legacy FOGE design correctly recognized that a technically known value is not automatically trustworthy enough to satisfy a reporting requirement.
The modern architecture makes the boundary explicit.
FOGE may declare or reference:
- required evidence class;
- acceptable source classes;
- minimum verification state;
- freshness requirements;
- period compatibility;
- attestation requirements;
- verifier requirements;
- required validation profile; and
- trust/authority policy references.
FOGE must not locally invent a trust score or reproduce TrustGate policy logic.
Runtime trust and evidence decisions are consumed as governed outcomes.
This lets two FOGE items use the same candidate signal but reach different states when their evidence or authority requirements differ.
19. Validation boundaries
FOGE requires validation in two distinct places.
19.1 Release validation
The FOGE compiler validates the definition itself before publication.
It must detect, as applicable:
- malformed source packages;
- unresolved Pergamum requirement references;
- unresolved SSSR signal references;
- orphan sections or items;
- broken requirement-to-item mappings;
- broken item-to-signal mappings;
- invalid rule references;
- invalid evidence/profile references;
- circular dependencies where prohibited;
- invalid extension inheritance;
- attempts to weaken mandatory baseline requirements;
- non-deterministic compilation inputs that are not explicitly governed;
- missing release/version metadata; and
- digest mismatch.
19.2 Runtime data validation
DaVE, DICE, TrustGate and other governed validators evaluate runtime values, completeness, integrity, evidence and trust as applicable.
FOGE consumes those findings to update or explain item state.
FOGE should not become a duplicate validator merely because the old implementation contained a foge_validator Python package.
20. FFG and CRE-FFG boundary
FOGE, FFG and CRE-FFG are separate architectural identities and must remain so unless a future governed architecture explicitly changes them.
The intended boundary for the modernized family is:
| Object | Responsibility |
|---|---|
| FOGE | Compile governed requirements into immutable interaction contracts; instantiate complete runtime sets; derive governed projections |
| FFG | Render and operate flexible user interaction surfaces from a FOGE projection and presentation contract |
| CRE-FFG | Apply contextual relevance to presentation, guidance and optional interaction without altering governed mandatory requirement semantics |
The FFG and CRE-FFG pages currently require their own modernization pass. Until that occurs, this boundary should be treated as the target architectural contract rather than an assertion that their existing implementation already conforms.
21. Multi-framework reuse
Pergamum Pulse crosswalks plus SSSR signal semantics allow FOGE to solve one of the largest problems with conventional ESG forms: duplicate collection caused by framework-centric thinking.
Example:
Requirement A (Framework X) ─┐
├── governed semantic mapping ── SSSR Signal S-1
Requirement B (Framework Y) ─┘
│
▼
one accepted value
│
┌────────────────────┴────────────────────┐
▼ ▼
satisfies Requirement A satisfies Requirement B
FOGE should therefore prefer requirement preservation with interaction deduplication.
The system keeps both requirement lineages while collecting or confirming the shared datum once.
A merged user question must never erase framework-specific obligations, citations, evidence conditions or publication semantics.
22. Template, guidance and remediation support
The original FOGE chapter introduced an important usability principle: a validator should not merely say that something is missing; the system should help the user resolve the gap.
That principle remains valid, but content governance must be separated from form logic.
A FOGE item may reference governed:
- templates;
- example documents;
- guidance;
- evidence examples;
- policy starters;
- calculation help;
- Academy learning resources; or
- AI-assisted drafting capabilities.
A guidance resolver may rank applicable options by:
- exact requirement or signal match;
- jurisdiction;
- language;
- NACE / sector;
- approved dependency state;
- template version;
- governance status; and
- governed quality/usefulness metadata.
Suggested content does not satisfy a requirement merely by being suggested or inserted. It must still pass the applicable acceptance, evidence and trust rules.
23. Pergamum Pulse change propagation
Pergamum Pulse makes FOGE continuously evolvable without destroying historical replay.
Regulation / standard / guidance changes
↓
Pergamum Pulse creates or supersedes governed knowledge objects
↓
Requirement package changes under governance
↓
FOGE impact analysis
↓
New FOGE source version
↓
New immutable FOGE release
↓
New runtime contexts resolve against the applicable release
A regulatory change must not silently mutate an already-published FOGE release.
Existing instances remain explainable against the exact source, requirement package and FOGE digest used when they were created.
This enables ZAYAZ to answer both:
- What does the rule require now?
- What did the rule and form require when this historical disclosure or decision was made?
24. Runtime persistence model
Definitions and runtime state must be separated.
24.1 Definition/release projection
The runtime database may project canonical release content into efficient relational structures for lookup and execution.
Conceptual families include:
foge releases
foge forms / interaction definitions
foge sections
foge items
foge requirement bindings
foge signal bindings
foge rules
foge mappings
foge extensions
24.2 Runtime execution state
Organization/object-specific state belongs in governed persistence, not YAML source files.
Conceptually:
FOGE release
↓
FOGE form instance
↓
FOGE form instance items
↓
resolution observations
↓
item states
↓
Delta Form / other projection
Potential physical concepts include:
foge_form_instances
foge_form_instance_items
foge_item_resolution_observations
foge_delta_forms
These table names are illustrative and are not yet canonical DDL.
The physical persistence model must be finalized against the live database architecture before implementation.
24.3 Never store tenant responses in source-controlled form definitions
Tenant/object-specific values, evidence, assessments and workflow state are:
- permission-sensitive;
- mutable over time;
- query-intensive;
- transaction-dependent;
- effective-dated or versioned;
- potentially personal or confidential; and
- subject to concurrent workflows.
They belong in governed runtime persistence and artifact storage.
25. Runtime events
FOGE should expose explicit state transitions through CMCB-aligned events rather than hidden side effects.
Representative event semantics include:
FOGE_FORM_RESOLVED
FOGE_FORM_INSTANCE_CREATED
FOGE_CONTEXT_EXTENSION_APPLIED
FOGE_PREFILL_STARTED
FOGE_ITEM_RESOLVED
FOGE_ITEM_CONFIRMATION_REQUIRED
FOGE_ITEM_MISSING
FOGE_DELTA_FORM_CREATED
FOGE_INSTANCE_COMPLETED
These names are descriptive candidates, not yet registered event contracts.
Before implementation, each event must align with CMCB naming, envelope, CSI/USO lineage and schema-governance conventions.
26. Explainability and audit lineage
Every visible FOGE request must be explainable backward to authority.
Why are we asking this?
↓
Runtime interaction item
↓
FOGE instance item
↓
FOGE release item
↓
Pergamum requirement
↓
Authoritative source / version
↓
Applicability context
FOGE must also explain omission:
Why did we not ask this?
↓
SATISFIED
or PREFILLED without required confirmation
or NOT_APPLICABLE
or WAIVED
or resolved from an acceptable governed source
A replayable record should preserve, where applicable:
- FOGE release identity and digest;
- extension identities and digests;
- Pergamum package and requirement references;
- SSSR signal references and versions;
- runtime-context snapshot/hash;
- Form Resolver version or policy reference;
- resolution observations;
- validation/trust decision references;
- final item states;
- generated projection identity; and
- timestamps and actor/system identity.
This lineage is required for assurance, dispute resolution, historical reporting and regulatory defensibility.
27. Determinism and replay
Given the same governed inputs, FOGE must be able to reproduce the same compiled release and, where the declared runtime inputs are replayable, the same applicable interaction set.
At minimum:
same requirement-package versions
+ same FOGE source version
+ same compiler version
+ same referenced registry versions
= same canonical release digest
For runtime replay:
same pinned FOGE release
+ same approved extension set
+ same relevant context snapshot
+ same governed resolution/trust/validation inputs
= reconstructable item-state and projection decision
Non-deterministic AI suggestions must never be the sole unrecorded basis for a mandatory requirement decision.
28. Security and privacy
FOGE release definitions should contain no tenant-specific secrets or personal data.
Runtime FOGE state may reference:
- personal contact data;
- commercially sensitive source data;
- supplier/client information;
- confidential evidence;
- financial characteristics; and
- regulated reporting information.
Runtime access must therefore be tenant-scoped, purpose-bound and compatible with the governing authorization model.
The release should store evidence requirements and references to governed profiles — not embedded copies of confidential runtime evidence.
Presentation projections should apply data minimization: a user should see only the information and actions appropriate to the role and task.
29. API and service boundary
The legacy implementation proposed a Python/FastAPI /api/validate-form endpoint and direct token authentication.
Those are historical implementation choices, not current constitutional architecture.
No FOGE API route is canonical in this specification yet.
A future API/service contract should expose governed capabilities such as:
compile release
validate release definition
resolve applicable release
instantiate complete form
resolve/prefill item
apply approved extension
project unresolved interaction
retrieve explainability lineage
Before a route becomes canonical it must define:
- API identity;
- route and method;
- input/output schemas;
- authentication;
- authorization;
- tenancy;
- idempotency;
- versioning;
- CSI/USO bindings;
- replay behavior; and
- audit/telemetry requirements.
30. Compile-time conformance requirements
A FOGE release must not be publishable unless the compiler can establish all applicable release invariants.
At minimum, implementation must ensure that:
- every Pergamum requirement binding resolves to an allowed governed source object/version;
- every canonical signal binding resolves through SSSR or the applicable signal registry;
- every item belongs to a valid interaction definition/section;
- every required-when or applicability rule is versioned and resolvable;
- every evidence/validation/trust profile reference resolves where required;
- calculation dependencies resolve to governed computation contracts;
- extension inheritance is explicit;
- no extension silently weakens a mandatory baseline requirement;
- all references included in the canonical release are pinned or deterministically resolvable;
- canonical serialization is deterministic;
- the content digest matches the serialized release;
- release identity/version/supersession metadata is valid; and
- unresolved production-critical governance bindings block promotion to active status.
Warnings are acceptable during review only where the applicable constitutional/lint policy permits them.
31. Runtime conformance requirements
For each runtime instance, implementation must ensure that:
- the selected release is effective for the runtime context;
- all applied extensions are approved and applicable;
- the complete applicable item set exists before a reduced projection is created;
- every item has an explicit runtime state;
- every satisfied item can identify its accepted resolution basis;
- every
NOT_APPLICABLEorWAIVEDstate preserves its governed basis; - every visible request can explain why it remains unresolved;
- a prefilled value is never treated as authoritative solely because it exists;
- runtime responses do not mutate the release definition;
- one accepted signal may satisfy multiple requirements without destroying separate requirement lineage;
- zero-question outcomes are supported; and
- generated Delta Forms are reproducible from the pinned instance state.
32. Acceptance scenarios
32.1 Existing data satisfies everything
Given an applicable release with fifty-four items and acceptable governed values/evidence for every item,
when the instance is resolved,
then FOGE produces no Delta Form and no unnecessary user request.
32.2 One value satisfies two frameworks
Given two Pergamum requirements mapped through governed semantics to the same SSSR signal,
when an acceptable value satisfies both evidence conditions,
then FOGE may collect or resolve the value once while preserving both requirement lineages.
32.3 Known value requires confirmation
Given a value exists in a connected system but the requirement demands supplier/entity attestation,
when the instance is resolved,
then the item becomes NEEDS_CONFIRMATION, not MISSING, and the user confirms rather than re-enters the value.
32.4 AI proposes a sector extension
Given an AI system proposes additional process-emission detail for a relevant NACE sector,
when the extension is reviewed and approved,
then it is versioned as an explicit overlay with provenance and may add requirements or resolution detail, but it cannot silently remove baseline mandatory items.
32.5 Pergamum source is superseded
Given a Pergamum requirement package is superseded,
when FOGE compiles the new governed version,
then a new FOGE release is created while historical instances remain pinned and replayable against their original release.
32.6 Inadequate evidence
Given the signal value is known but its evidence does not satisfy the item requirement,
when trust/evidence evaluation completes,
then FOGE does not mark the item SATISFIED; it requests only the required confirmation or missing evidence.
33. Legacy chapter reconciliation
Legacy Manual chapter 92 contained many ideas that remain architecturally valuable, including:
- context-driven forms;
- framework-to-data mapping;
- many-to-many metric/field linkage;
- reusable field semantics and contextual overrides;
- evidence-aware form generation;
- template suggestions for remediation;
- form-definition validation;
- versioning and auditability; and
- dynamic integration with calculations and external data.
The modern architecture preserves those intentions while changing ownership and implementation boundaries.
| Legacy chapter concept | Modern interpretation |
|---|---|
| FOGE determines legal/framework obligations directly | Pergamum Pulse governs authoritative requirement/applicability semantics; FOGE compiles them |
| Metrics table is primary requirement source | Pergamum requirement objects + governed mappings + SSSR signal semantics become the primary contract |
metrics_field_linkage | Generalized requirement ↔ FOGE item ↔ SSSR signal many-to-many binding |
fields global registry | Governed interaction/presentation metadata referencing canonical signals rather than redefining them |
field_mapping_profile | Contextual interaction configuration / release metadata / extension overlay |
dsi_metadata_profiles and DSI/SID codes | Superseded as constitutional identity by governed registries, signal identities and self-describing contracts |
| Numeric InputHandler codes | Replaced by governed self-describing interaction/render contracts |
| FOGE Materiality/Obligation sub-engines | External governed applicability/materiality/requirement decisions consumed by FOGE as appropriate |
| FOGE trust scoring | Trust/evidence requirements declared by FOGE; scoring/authority decisions owned by TrustGate/validation architecture |
foge_validator validates runtime ESG data | FOGE compiler validates release integrity; DaVE/DICE/TrustGate validate runtime data/evidence/trust |
| Python package / Vue UI / Dockerfile / x-api-token | Historical implementation detail; not constitutional architecture |
| Template Registry resolver | Preserved as governed guidance/template resolution, separated from requirement authority |
| HTML/PDF validator reports | Reporting/presentation concern, not FOGE core responsibility |
The migration therefore does not discard the original design. It extracts its durable architectural idea and moves each responsibility to the subsystem ZAYAZ now has to govern it properly.
34. Implementation need set
This specification is intentionally structured so Hecate/ZARA can derive implementation work without guessing architecture.
The implementation programme should create governed needs for at least the following:
- FOGE architectural registration — resolve the canonical owning Component, EID governance and Engine registry binding.
- FOGE CSI/CMI contract registration — define and register concrete signal families and CMI bindings rather than inventing them in this page.
- Pergamum → FOGE requirement-package schema — define the executable, versioned interchange contract.
- FOGE authoring schema — define the YAML/equivalent source schema and reference rules.
- Deterministic FOGE compiler — validate, resolve, canonicalize and digest releases.
- Immutable release artifact model — persist and retrieve canonical JSON releases with lineage and supersession.
- Runtime release projection — provide efficient database/search access without turning the projection into the source of truth.
- Form Resolver contract — govern its identity/ownership, inputs, selection semantics and output.
- FOGE Form Instance persistence — persist pinned release, context, complete item set and runtime state.
- Resolution/prefill orchestration — resolve candidates from governed sources while preserving provenance, authority and evidence decisions.
- Item-state engine — deterministically assign the governed runtime states in this specification.
- Delta Form projection — derive minimal unresolved interaction from complete instance state.
- FFG/CRE-FFG modernization — align rendering and contextual relevance with the new FOGE boundary.
- Trust/validation integration — bind DaVE, DICE, TrustGate and other applicable outcomes without duplicating their logic.
- Template/guidance resolution — resolve governed supporting content without treating suggestions as evidence automatically.
- CMCB event contracts — register FOGE runtime event schemas and lineage conventions.
- Replay and audit manifest — reconstruct release compilation and runtime projection decisions.
- Security/authorization contract — define tenant, purpose, role and evidence access controls for runtime state.
- Conformance test suite — cover the acceptance scenarios in this specification plus negative and historical-replay cases.
- Legacy migration assessment — determine which existing FOGE/FFG tables, registries, scripts and APIs can be migrated, retired or mapped to the new architecture.
No implementation need should close a governance gap by inventing an identifier or duplicating another subsystem's authority.
35. Open governance gaps
The following are deliberately unresolved at this version:
- canonical FOGE EID;
- canonical owning Component under the Computation Hub Module;
- production CSI input/output families;
- FOGE CMI bindings;
- canonical API identity/routes;
- canonical Pergamum → FOGE interchange schema identity;
- canonical FOGE release schema identity;
- exact runtime database table names and DDL;
- canonical Form Resolver identity and ownership;
- final CMCB event names/schemas; and
- fully modernized FFG and CRE-FFG specifications.
These gaps must remain explicit until the relevant registry/specification work resolves them.
36. Foundational principles
FOGE is governed by five principles:
- Authority before interaction — no form logic may invent the requirement it is executing.
- Signal semantics before fields — canonical data meaning lives outside the UI.
- Complete requirement set before minimal projection — ZAYAZ must know everything applicable before deciding what not to ask.
- Reuse before request — existing acceptable data is resolved before a human is interrupted.
- Replay before automation — every release, resolution and projection must remain explainable against the versions and authority that produced it.
The resulting architecture can be summarized as:
Pergamum Pulse tells ZAYAZ what is governed and why.
SSSR tells ZAYAZ what the data means.
FOGE compiles what interaction contract follows.
Runtime resolution determines what is already satisfied.
FFG renders what remains useful to show or ask.
Trust and validation services determine whether evidence is acceptable.
ZARA explains the entire chain.
And the governing FOGE rule is:
The best form is not the most dynamic form. It is the smallest governed interaction that still satisfies the complete applicable requirement set — including, when possible, no form at all.