Skip to main content
Jira progress: loading…

FOGE-REC

Pergamum Pulse

FOGE → SSSR Signal Discovery / Resolution Contract

Version: 0.1.0
Status: Draft architectural contract
Direction: FOGE → SSSR
Primary phase: FOGE compilation / governance time
Secondary use: Runtime resolution planning
Execution owner: ZSSR for materialization/routing where execution is required
Runtime value authority: Not SSSR


1. Purpose​

The FOGE → SSSR Signal Discovery / Resolution Contract defines how FOGE converts a governed semantic data need into one or more canonical ZAYAZ signals without inventing data semantics, hardcoding physical locations or confusing data discoverability with runtime satisfaction.

The contract answers:

Given a governed information need from Pergamum, what canonical ZAYAZ data can satisfy that need, where can it be found or derived, and what must happen to obtain it?

The responsibility chain is:

Pergamum Pulse
governs what information is required
↓
FOGE
holds executable semantic data need
↓
SSSR
identifies canonical signal semantics
+ physical/data-location reality
+ dependencies
+ acquisition/materialization metadata
↓
FOGE binding
↓
ZSSR
routes materialization where required
↓
runtime candidate value(s)
↓
validation / evidence / trust evaluation
↓
FOGE item state

2. Constitutional boundary

2.1 FOGE owns​

FOGE owns:

  • the exact Pergamum-derived data need;
  • requirement lineage;
  • required grain;
  • cardinality;
  • completeness;
  • period requirements;
  • evidence expectations;
  • derivation permissions;
  • estimate permissions;
  • requirement-specific freshness constraints;
  • requirement-specific acceptance constraints; and
  • the interaction consequences of unresolved information.

FOGE does not own the canonical definition of the underlying signal.


2.2 SSSR owns​

SSSR owns or governs discovery of:

  • canonical signal identity;
  • canonical signal meaning;
  • signal type and shape;
  • units where applicable;
  • physical data location;
  • schema/table/column addressing;
  • JSON paths;
  • API paths;
  • file/object paths;
  • source format;
  • access path;
  • dependencies;
  • registered calculation/materialization dependencies;
  • fallback relationships;
  • handler/resolver metadata;
  • availability metadata;
  • update frequency;
  • default granularity;
  • source-system relationship;
  • signal aliases;
  • deprecation/supersession;
  • resolution metadata; and
  • governed relationships to other signals.

SSSR answers:

What data object corresponds to this meaning, and how may ZAYAZ reach or construct it?


2.3 ZSSR owns​

ZSSR owns execution routing.

Where SSSR says that a required signal is:

DERIVABLE

ZSSR may route work to a governed compute engine.

Where SSSR says:

ACQUIRABLE

ZSSR may route work to an API, connector, system agent, human acquisition workflow or other governed capability.

SSSR describes the route.

ZSSR executes the route.


2.4 SSSR does not own runtime truth​

SSSR is not the canonical store of every runtime value.

For example:

SSSR may know:

sssr:<some workforce signal>
↓
physical location:
HR database / API / canonical table
↓
handler:
registered HR resolver

SSSR does not therefore own:

Company X has 412 employees.

That is runtime data.


3. Input object: FOGE Semantic Data Need

The input to SSSR is a Semantic Data Need produced during FOGE compilation.

Conceptually:

data_need:
data_need_ref: <FOGE-local-stable-reference>

requirement_refs:
- <Pergamum-requirement-reference>

semantic_concept:
pp_concept_ref: <governed-concept-reference>

value_kind: numeric

grain:
subject: organization

temporal_scope:
basis: reporting_period

constraints:
unit: null
cardinality: one
completeness: required

derivation:
permitted: true

estimates:
permitted: false

Exact schema identity and identifier formats remain governed separately.


4. Data Need identity is not Signal identity

The following identities MUST remain separate:

Pergamum Requirement
≠
FOGE Data Need
≠
SSSR Signal
≠
Physical field

Example:

PP requirement:
workforce gender distribution

FOGE data need:
worker gender classification

SSSR signal:
canonical worker-gender signal

physical binding:
hr.employee.gender_code

FOGE MUST NOT encode:

hr.employee.gender_code

as though it were the semantic requirement.

Likewise SSSR MUST NOT interpret:

workforce gender distribution

as a legal obligation.


5. Discovery request

FOGE SHOULD submit a discovery request containing sufficient semantics for SSSR to resolve the need without relying on label similarity alone.

Conceptually:

signal_discovery_request:
contract_version: "0.1"

data_need_ref: <ref>

requirement_context:
requirement_refs:
- <PP requirement ref>

semantic_concept:
primary_ref: <governed semantic concept>

canonical_description:
<human-readable semantic description>

value_shape:
kind: classification

grain:
subject: worker

dimensions: []

temporal:
basis: reporting_period

unit:
required: null

cardinality:
mode: one_per_subject

completeness:
mode: complete_population

derivation_policy:
permitted: true

estimation_policy:
permitted: false

evidence_constraints:
source_classes: []

resolution_intent:
purpose: foge_release_compilation

Free-text description may support search.

It MUST NOT be the sole semantic basis for an automatic production binding.


6. SSSR discovery process

SSSR SHOULD evaluate candidates using governed metadata including, where applicable:

canonical semantic identity
aliases
description
data type
shape
grain
unit
domain
physical location
source system
dependencies
fallbacks
handler
availability
update frequency
granularity
validation metadata
supersession state

Search technology may include:

  • exact identifier lookup;
  • semantic indexing;
  • embeddings;
  • controlled aliases;
  • ontology relationships;
  • graph traversal;
  • rules;
  • fuzzy matching; and
  • AI-assisted suggestions.

Search method and binding authority are distinct.

An AI similarity result does not create semantic equivalence.


7. Match classes

Each candidate SHOULD receive an explicit semantic match class.

Recommended v0.1 classes are:

EXACT
GOVERNED_EQUIVALENT
COMPOSITE
TRANSFORMABLE
PARTIAL
CONFLICTING
UNRELATED

EXACT​

The requested semantic concept and canonical signal represent the same governed meaning.

GOVERNED_EQUIVALENT​

A governed mapping establishes semantic equivalence.

COMPOSITE​

Several signals together satisfy the data need.

TRANSFORMABLE​

A governed transformation can convert the signal into the required semantic result.

PARTIAL​

The signal satisfies only part of the requested need.

CONFLICTING​

Meaning, grain, period, unit or another material semantic dimension conflicts.

UNRELATED​

The candidate cannot legitimately satisfy the need.


8. Binding prohibition

FOGE MUST NOT automatically bind a production requirement where the only basis is:

similar field name
similar description
embedding proximity
LLM recommendation
shared unit
shared table
shared framework tag

Those are discovery evidence.

They are not semantic authority.


9. Resolution capability state

For a semantically valid signal candidate, SSSR MUST be able to classify how the signal may be obtained.

Core v0.1 states are:

STORED
DERIVABLE
ACQUIRABLE
UNRESOLVED

These states describe resolution capability.

They are not FOGE runtime item states.


9.1 STORED​

The canonical signal has a governed stored representation.

Example:

resolution:
state: STORED

locator:
type: database
schema: core_data
table: <table>
column: <column>

This does not mean that a valid value exists for every runtime subject.

It means ZAYAZ knows where such a value is stored when available.


9.2 DERIVABLE​

The signal can be deterministically produced from governed dependencies.

Example:

resolution:
state: DERIVABLE

dependencies:
- <signal-a>
- <signal-b>

handler_ref: <governed-computation-handler>

A derivable signal MUST declare:

  • dependencies;
  • transformation/calculation route;
  • required grain;
  • output semantics; and
  • governed handler or computation reference.

FOGE MUST also verify that Pergamum permits derivation for the requirement.


9.3 ACQUIRABLE​

The signal is not presently stored or derivable from available canonical data but a governed acquisition route exists.

Examples:

external API
ERP connector
accounting connector
supplier contribution
official registry
document extraction
user confirmation
manual entry

Conceptually:

resolution:
state: ACQUIRABLE

acquisition:
handler_ref: <registered-handler>
acquisition_class: authoritative_external_api

FOGE MUST NOT equate ACQUIRABLE with MISSING.

Runtime acquisition should be attempted before user interruption where policy permits.


9.4 UNRESOLVED​

No approved signal or governed acquisition/derivation pathway can currently satisfy the semantic need.

This state may mean:

  • no signal exists;
  • candidate semantics are ambiguous;
  • available signals are incompatible;
  • required grain is unsupported;
  • source is unavailable;
  • no permitted derivation exists;
  • required acquisition route is unregistered; or
  • signal governance is incomplete.

Only after governed runtime resolution fails should FOGE normally consider direct human collection.


10. Resolution state is not item state

The following MUST remain separate:

SSSR resolution capability
↓
STORED / DERIVABLE / ACQUIRABLE / UNRESOLVED

from:

FOGE runtime item state
↓
SATISFIED
PREFILLED
NEEDS_CONFIRMATION
MISSING
NOT_APPLICABLE
WAIVED
BLOCKED

For example:

SSSR: STORED
↓
runtime lookup
↓
no row exists
↓
FOGE: MISSING

or:

SSSR: DERIVABLE
↓
ZSSR + computation engine
↓
acceptable result
↓
FOGE: SATISFIED

11. Discovery response

A conceptual response is:

signal_discovery_response:
contract_version: "0.1"

data_need_ref: <ref>

outcome: resolved

candidates:

- signal_ref: <canonical-SSSR-reference>

semantic_match:
class: EXACT
basis:
- <governed semantic mapping or definition>

compatibility:
value_shape: compatible
grain: compatible
unit: compatible
temporal: compatible
cardinality: compatible

resolution:
state: DERIVABLE

dependencies:
- <signal-ref>
- <signal-ref>

handler_ref: <registered-handler>

physical_metadata:
source_format: derived

lifecycle:
status: active

preferred_candidate:
signal_ref: <ref>

governance:
requires_review: false

The exact serialized schema remains to be registered.


12. Compatibility dimensions

Semantic equality alone is insufficient.

A signal binding MUST consider at least:

meaning
value type
shape
grain
dimensions
unit
cardinality
temporal basis
population
geographic basis where material
organizational scope
classification vocabulary
aggregation semantics

Example:

total workforce headcount

is not automatically a valid substitute for:

workforce headcount by business unit and gender

even though they belong to the same semantic family.


13. Grain preservation

SSSR MUST expose enough metadata for FOGE to determine whether the signal can support the required grain.

Example need:

grain:
subject: business_unit

dimensions:
- gender_category

A company-total gender ratio cannot satisfy this requirement if business-unit detail is mandatory.

FOGE MUST NOT silently aggregate or decompose data beyond the governing requirement's permitted methodology.


14. Unit handling

Where units matter, SSSR SHOULD return:

stored unit
canonical unit
conversion capability
conversion handler
conversion provenance

A conversion may be used only where:

  1. signal semantics remain equivalent; and
  2. the governing requirement permits the conversion.

Unit convertibility does not prove semantic equivalence.


15. Composite bindings

One FOGE data need may require several signals.

Example:

workforce gender distribution
↓
worker identity
worker active-status
worker business-unit relationship
worker gender classification
reporting-period boundary

SSSR MUST therefore support composite resolution.

Conceptually:

binding:
mode: composite

components:

- role: population_member
signal_ref: <worker-signal>

- role: inclusion_status
signal_ref: <employment-status-signal>

- role: grouping_dimension
signal_ref: <business-unit-signal>

- role: classification_dimension
signal_ref: <gender-signal>

This is one reason a single signal_ref on a FOGE item cannot be the full architecture.


16. Dependency graph

A DERIVABLE signal MUST expose its dependencies as a graph rather than only a free-text formula.

Conceptually:

required output signal
↓
dependency A
dependency B
dependency C
↓
registered computation / transformation
↓
canonical result

Dependencies may themselves resolve as:

STORED
DERIVABLE
ACQUIRABLE
UNRESOLVED

The resulting resolution graph may therefore be recursive.

Cycles MUST be detected and rejected unless a specifically governed iterative computation model permits them.


17. Fallbacks

SSSR may expose fallback candidates.

Example:

fallbacks:

- signal_ref: <secondary-signal>
conditions:
- primary_unavailable

semantic_match:
class: GOVERNED_EQUIVALENT

Fallback order is not sufficient authority.

Every fallback MUST independently satisfy FOGE's requirement constraints.

A technically available substitute cannot override a Pergamum methodological restriction.


18. Acquisition routes

An ACQUIRABLE signal SHOULD identify the governed acquisition route.

Conceptually:

acquisition:
acquisition_class: connected_source

handler_ref: <registered-handler>

expected_output_signal:
<canonical-signal-ref>

requirements:
authentication: required
subject_identity: required

expected_freshness:
<metadata>

SSSR describes the capability.

ZSSR orchestrates it.


19. Interaction as last acquisition route

Human interaction may itself be a registered acquisition pathway.

For example:

ACQUIRABLE
↓
source class: user contribution

However:

Human collection MUST NOT automatically be preferred merely because FOGE can render a form.

The preferred sequence remains:

existing acceptable data
↓
derivation
↓
connected / authoritative acquisition
↓
confirmation
↓
new manual contribution

subject to the governing requirement and policy.


20. Source authority boundary

SSSR may describe:

source system
source class
authority metadata
validation requirements
provenance capability

but SSSR MUST NOT independently decide:

this runtime value satisfies the legal evidence requirement

That decision belongs to the applicable trust, evidence and validation architecture.

FOGE supplies the required acceptance constraints.

SSSR supplies resolution capabilities.

Runtime assurance services determine acceptance.


21. Freshness

FOGE MAY specify a requirement-specific freshness constraint.

Example:

freshness_requirement:
basis: reporting_period

SSSR MAY expose:

signal_freshness:
update_frequency: daily
latest_available_at: <runtime metadata where permitted>

Whether a particular runtime value is fresh enough is a runtime resolution decision.

A signal can be semantically correct and physically available but still fail the requirement due to stale data.


22. Access and visibility

SSSR SHOULD expose access metadata required to determine whether a signal may be resolved in the current execution context.

This may include:

tenant scope
role scope
purpose restrictions
connector requirements
system permissions
sensitivity classification

Discovery of a signal does not imply authority to read its runtime values.


23. Lifecycle and supersession

A signal response MUST expose lifecycle state.

Examples:

active
deprecated
superseded
pending
retired

FOGE MUST NOT compile a new production release against a retired signal unless an explicit governed historical/replay exception applies.

Where a signal is superseded, SSSR SHOULD expose its successor relationship.

A successor is not automatically semantically equivalent.


24. Ambiguity handling

Where several candidates are plausible and no governed preference resolves them:

outcome: ambiguous
requires_review: true

SSSR MUST return the ambiguity rather than silently choosing.

FOGE compilation should normally block publication of the affected production requirement until resolved.

This is particularly important where candidates differ by:

  • unit;
  • reporting boundary;
  • market/location basis;
  • consolidation scope;
  • denominator;
  • classification vocabulary;
  • estimation methodology; or
  • source authority.

25. Missing signal handling

Where no acceptable signal exists, SSSR may create a proposal for governance review.

An AI system MAY assist by proposing:

signal name
description
likely source
value type
possible aliases
candidate physical location

A proposed signal MUST NOT become a production binding until approved through SSSR governance.

FOGE MUST preserve:

UNRESOLVED

until that governance step completes.


26. FOGE Signal Binding

Once resolution is approved, FOGE should pin the binding into its immutable release.

Conceptually:

foge_signal_binding:
data_need_ref: <FOGE data need>

requirement_refs:
- <PP requirement>

signal_bindings:

- signal_ref: <SSSR signal>
role: primary

semantic_basis:
match_class: EXACT
mapping_refs: []

resolution_capability:
state: DERIVABLE

constraints:
grain: <required-grain>
temporal: <required-period>

sssr_snapshot:
registry_version: <version>
binding_digest: <digest>

This is the compiled bridge between requirement semantics and canonical data semantics.


27. Binding immutability

Once included in a published FOGE release, the binding MUST be replayable.

A later SSSR change must not silently reinterpret an existing release.

Conceptually:

FOGE release 1.0
→ SSSR signal/binding snapshot A

FOGE release 1.1
→ SSSR signal/binding snapshot B

Historical release 1.0 remains reconstructable against A.


28. Runtime handoff boundary

After FOGE has a pinned signal binding, runtime resolution proceeds to the next architectural contract:

FOGE / SSSR → ZSSR Data Need / Materialization Contract

The handoff should contain, conceptually:

materialization_need:
foge_release_ref: <ref>
form_instance_ref: <ref>
data_need_ref: <ref>

pinned_signal_binding:
<binding>

runtime_subject:
<subject-reference>

reporting_period:
<period>

acceptance_constraints:
<FOGE requirement constraints>

ZSSR then determines which registered path should execute.


29. Runtime result returns to FOGE

A successful materialization may return a resolution observation such as:

resolution_observation:
data_need_ref: <ref>

signal_ref: <ref>

outcome: candidate_available

value_ref: <runtime-value-reference>

provenance_ref: <ref>

evidence_refs: []

source_timestamp: <timestamp>

materialization_ref: <execution-reference>

FOGE then combines this with validation, evidence and trust outcomes to determine item state.

SSSR does not mark the FOGE requirement SATISFIED.


30. Canonical workforce acceptance scenario

Pergamum provides:

Requirement:
workforce gender distribution by business unit

FOGE decomposes that into semantic needs:

business-unit population
workforce population
worker → business-unit relationship
worker gender classification
worker active/in-scope status
reporting-period boundary

FOGE submits each need to SSSR.

SSSR may respond:

business-unit population
→ STORED

workforce population
→ STORED

worker → business-unit
→ STORED

worker gender classification
→ STORED

active/in-scope status
→ STORED

gender distribution
→ DERIVABLE
dependencies = above signals
handler = governed aggregation capability

FOGE verifies:

Pergamum permits derivation: YES
required grain supported: YES
complete population supported: YES
estimate policy respected: YES

The immutable FOGE release pins the binding.

At runtime:

FOGE complete Form Instance
↓
ZSSR materializes dependencies
↓
governed aggregation
↓
gender distribution candidate
↓
validation / trust / evidence
↓
SATISFIED

User interaction:

0 questions

31. Partial-resolution scenario

Suppose one business unit lacks gender classifications for part of its workforce.

SSSR's canonical bindings remain valid.

The runtime data does not.

The result may therefore be:

SSSR capability:
DERIVABLE

but:

FOGE runtime:
BLOCKED or MISSING

for the unresolved population.

FOGE may then project only the missing contribution required to complete the distribution.

The full requirement remains intact in the complete Form Instance.


32. Confirmation scenario

Suppose SSSR identifies an existing authoritative signal and ZSSR retrieves a valid value, but Pergamum requires entity attestation.

Then:

SSSR:
STORED

runtime candidate:
available

FOGE:
NEEDS_CONFIRMATION

FOGE presents the known value.

It does not ask the user to re-enter it.


33. Compile-time failure conditions

FOGE SHOULD block production compilation where:

NO_SIGNAL_MATCH
AMBIGUOUS_SIGNAL_MATCH
UNGOVERNED_EQUIVALENCE
INCOMPATIBLE_GRAIN
INCOMPATIBLE_VALUE_SHAPE
INCOMPATIBLE_UNIT
INCOMPATIBLE_TEMPORAL_SCOPE
DERIVATION_PROHIBITED
UNREGISTERED_HANDLER
BROKEN_DEPENDENCY
CYCLIC_DEPENDENCY
RETIRED_SIGNAL
UNRESOLVED_ACQUISITION_PATH

These are conceptual diagnostic classes only.

They are not canonical ZAYAZ error codes until registered.


34. Conformance requirements

A conforming implementation MUST ensure that:

  1. every FOGE data need retains Pergamum requirement lineage;
  2. data-need identity remains separate from signal identity;
  3. physical location never becomes the semantic identity;
  4. semantic matching precedes physical lookup;
  5. fuzzy/AI matching alone cannot create a production binding;
  6. grain compatibility is evaluated;
  7. unit compatibility is evaluated where relevant;
  8. temporal compatibility is evaluated where relevant;
  9. composite signal bindings are supported;
  10. dependencies are explicit;
  11. STORED, DERIVABLE, ACQUIRABLE and UNRESOLVED remain distinct;
  12. resolution capability is not confused with runtime satisfaction;
  13. FOGE derivation policy is respected;
  14. SSSR does not execute work owned by ZSSR;
  15. SSSR does not become a runtime trust authority;
  16. missing signals may be proposed but not silently created as production signals;
  17. bindings are pinned/replayable in published FOGE releases; and
  18. zero-question outcomes remain possible.

35. Implication for FOGE persistence

This contract confirms that the current conceptual model:

FOGE item version
→ one signal_ref

is insufficient as the canonical architecture.

The actual model is:

Pergamum Requirement
↕
FOGE Data Need
↕
FOGE Interaction Item
↕
SSSR Signal(s)

with many-to-many relationships.

A single requirement may contain several data needs.

A single data need may require several signals.

A single signal may satisfy several data needs.

A single interaction item may collect or confirm multiple related signals.


36. Implication for 017_create_foge_definition_foundation.sql

Migration 017 SHOULD remain paused until this contract is reflected in the definition model.

At minimum, the design needs an explicit representation of:

FOGE data needs
FOGE item ↔ data-need relationship
FOGE data-need ↔ SSSR signal binding
binding role
binding semantic basis
binding resolution capability
binding snapshot/version/digest

The exact table names remain to be governed.

The existing signal_ref field may remain as a convenience projection or primary/simple binding only if it is explicitly non-authoritative relative to the full binding model.


37. Foundational principles

The contract is governed by these rules:

Meaning before location.

A FOGE data need is not an SSSR signal.

A signal is not its database column.

Discovery is not equivalence.

Availability is not satisfaction.

SSSR describes how data can be reached; ZSSR performs the work.

Derivation cannot override Pergamum methodology.

Human interaction is an acquisition path of last resort, not FOGE's default.

Published bindings must be immutable and replayable.

The best resolution path may produce zero questions.


38. v0.1 completion criterion

This contract is implementation-ready when the workforce-gender-distribution specimen can deterministically traverse:

Pergamum Requirement
↓
FOGE Data Needs
↓
SSSR discovery
↓
canonical signal bindings
↓
STORED / DERIVABLE / ACQUIRABLE / UNRESOLVED
↓
pinned FOGE release bindings
↓
ZSSR materialization
↓
runtime observations
↓
FOGE item states
↓
minimal interaction

without:

  • inventing a signal;
  • hardcoding a physical field inside FOGE;
  • interpreting law inside SSSR;
  • executing materialization inside SSSR;
  • treating data existence as evidence sufficiency; or
  • asking the user before governed reuse and resolution have been attempted.

39. Governing rule

The FOGE → SSSR boundary can be summarized as:

FOGE tells SSSR exactly what governed information is needed; SSSR tells FOGE which canonical ZAYAZ signals can represent that meaning and how those signals can be found, derived or acquired; ZSSR performs any required work.

GitHub RepoRequest for Change (RFC)