Jira progress: loading…

SSSR-API

API Signal Metadata Module

(Addendum to SSSR – Smart Searchable Signal Registry)

1. Introduction

The SSSR API Signal Metadata Module extends the Smart Searchable Signal Registry (SSSR) with a dedicated layer for managing API-originated signals. While the core SSSR governs all column-level data definitions across ZAYAZ tables, JSON objects, and frameworks, API-derived signals require their own structured management to prevent registry bloat and to capture their unique characteristics.

Important Clarification This module stores metadata only — not the API data values themselves.

It documents how an external API field is defined, mapped, versioned, and linked to ZAYAZ semantics (SSSR signal IDs, ECO-Numbers™, and USO domains).
The actual data values ingested from APIs are processed by DSAIL, validated, normalized, and then passed into the operational data layer (PostgreSQL, Iceberg, S3).
High-frequency time-series values (e.g., IoT readings, 5-minute consumption logs) are governed by the Time-Series Compaction & Retention Engine (TS-CRE), which executes compaction, downsampling, aggregation, and retention policies.
The API Signal Metadata Module only references retention policies (e.g., via retention_policy and sla_tier) — it does not perform compaction itself.

Why API Signals Need a Dedicated Module API signals differ from traditional table-bound signals in three important ways:

Dynamic Origins — API schemas evolve frequently (ERP, IoT, regulatory feeds) and may add or deprecate fields without warning.
Metadata-Rich Context — Unlike static columns, API signals carry additional attributes such as endpoint definitions, request/response structure, authentication type, versioning, and latency constraints.
Lifecycle Volatility — APIs evolve quickly, introducing new fields, deprecating endpoints, or modifying data structures at a much higher frequency than internal tables.

2. Core Functions of the Module

Create a clean separation within SSSR between static database signals and dynamic API signals.
Provide traceable linkage to ECO-Numbers™, ensuring each external API signal connects to the correct entity, supplier, or verifier in ZAYAZ.
Align all API signals with the Universal Signal Ontology (USO) for discoverability and consistency across modules.
Maintain schema versioning and fallback logic for APIs, enabling graceful handling when endpoints change.
Define retention intent (via metadata), while delegating execution of retention/compaction to TS-CRE.

Strategic Benefits

Scalability: Prevents the main SSSR registry from being overloaded with API-specific definitions.
Resilience: Ensures ZSSR (Smart System Router) can always identify the correct API-signal processing engine, fallback, or verifier flow .
Traceability: Creates a full audit trail of API signal evolution, linked back to ECO-Numbers™, enabling regulatory-grade assurance.
Interoperability: Allows one API signal to feed multiple metrics, frameworks, or extrapolation modules without redundancy.
Compliance Integrity: Time-series growth is managed by TS-CRE, ensuring regulatory reporting remains performant and auditable without overwhelming SSSR.

Example Use Case An energy consumption API publishes hourly grid data. Instead of flooding SSSR with transient columns, the API Signal Metadata Module registers:

Endpoint definition: /energy/v1/hourly_consumption
Expected schema: {eco_number, timestamp, kWh, region_code}
Linked ECO-Number(s): ECO-196-123-456-789
Signal Role: input → scope2_emissions
Fallback Logic: If API unavailable, route to SEM fallback for extrapolation

This structure ensures the signal is both discoverable in SSSR and properly orchestrated by ZSSR, while remaining cleanly separated from internal database signals.

3. Submodules and Design Principles

Submodules

Submodule	Description
API Discovery & Ingestion Metadata	Captures new fields discovered via DSAIL connectors (ERP, IoT, gov APIs), including external_system, endpoint, field_path, schema_hash, and timestamps. No values stored — metadata only.
Signal Mapping & Matching	Links API fields to canonical sssr_signal IDs. Tracks match confidence, review status (proposed → matched → approved → dismissed), and fallback rules.
USO & Domain Classification	Tags API signals with Universal Signal Ontology (USO) attributes: domain_tag, hub_code, source_type, api_subtype, and module_code. Ensures semantic consistency across the platform.
ECO-Number Linkage	Associates API signals with ECO-Numbers™ for supplier/entity traceability and compliance mapping. Provides cross-reference between external identifiers and ZAYAZ master data.
Schema Versioning & Lifecycle	Stores first_seen_at, last_seen_at, schema_version, and status (active, deprecated, orphaned). Allows ZSSR and DSAIL to gracefully degrade if an endpoint changes.
Retention Policy Reference (TS-CRE)	Stores retention policy metadata (e.g., retention_policy, sla_tier), which are executed by TS-CRE for compaction, aggregation, and long-term storage of time-series values.
Governance & Ownership	Captures owner_team, sla_tier, and reviewer_id for API signals, ensuring responsibility assignment, approval workflows, and auditability.

Design Principles

Principle	Description
Metadata-Only	The module never stores data values — only definitions, mappings, and provenance of API signals. Values remain in DSAIL’s normalized data layer; compaction/retention handled by TS-CRE.
Signal-Centric Alignment	Every API field must be linked (directly or via proposal) to a canonical SSSR signal_id. No orphan fields flow into ZAYAZ.
USO-Compliant Classification	All API signals are tagged with Universal Signal Ontology (USO) codes for domain, hub, and source type, ensuring discoverability and interoperability.
ECO-Number Traceability	API signals are cross-linked with ECO-Numbers™ to guarantee supplier- and entity-level traceability.
Versioned & Auditable	API schema changes are versioned and logged; all approvals, rejections, and matches are stored in ALTD for full auditability.
Delegated Retention	The API Signal Metadata Module defines retention intent (via policy references), but TS-CRE executes compaction, aggregation, and downsampling of high-frequency values.
Policy-Aware Routing	Metadata informs ZSSR about which policies (trust, jurisdiction, fallback, retention) apply when routing API signals downstream.
Lifecycle Governance	API signals have explicit ownership, SLA tier, and deprecation policies to prevent registry sprawl, with retention enforcement delegated to TS-CRE.

4. Implementation Guide — SSSR API Signal Metadata Module

The API Signal Metadata extension of SSSR:

Stores metadata only (no values).
Links API fields → canonical sssr_signal IDs.
Cross-references ECO-Numbers™ for traceability.
Defines retention policies (executed by TS-CRE).
Emits events for ZSSR routing and ALTD audit trails.

4.1. Database Schema Design

Table: sssr_api_signal

Column	Type	Description
api_signal_id	TEXT (PK)	Unique ID for the API signal metadata entry.
Canonical alignment
signal_id	TEXT (FK)	References sssr_signal.signal_id (the canonical aligned signal).
matched_signal_id	TEXT	Suggested canonical signal_id (before approval).
status	TEXT	Lifecycle status: proposed, matched, approved, dismissed.
Discovery Metadata
external_system	TEXT	External system name (e.g., sap_erp, iot_meter).
endpoint	TEXT	API endpoint or resource path (e.g., /water/v1/consumption).
field_path	TEXT	JSON path or field identifier within the API response.
schema_hash	TEXT	Hash of API response schema for version tracking.
request_method	TEXT	GET\|POST\|…
request_template	JSONB	Payload/params template (no secrets)
response_sample	JSONB	Trimmed example for debugging
first_seen_at	TIMESTAMPTZ	Timestamp when field was first discovered by DSAIL.
last_seen_at	TIMESTAMPTZ	Most recent successful ingestion of this field.
Units & Normalization
unit_reported	TEXT	Unit as provided by the API (e.g., liters, kWh).
unit_normalized	TEXT	Canonical unit aligned with SSSR/USO (e.g., m3, MJ).
sampling_interval	INTERVAL	E.g., '5 minutes'
value_semantics	TEXT	counter’, ‘gauge’, ‘rate’, ‘categorical’
aggregation_hint	TEXT	‘sum', ‘avg', ‘min’, ‘max’, ‘last’
Matching & Review
match_confidence	REAL	Confidence score (0–1) from automated mapping.
reviewer_id	TEXT	User ID of reviewer/approver.
owner_team	TEXT	Owning team responsible for mapping/maintenance.
Classification (USO)
domain_tag	TEXT	USO domain (e.g., ENV, SOC, GOV).
hub_code	TEXT	USO hub identifier (e.g., GHG, WAT).
source_type	TEXT	Source type (API, IoT, ERP).
api_subtype	TEXT	API subtype (e.g., REST, GraphQL, CSV-feed).
module_code	TEXT	Internal ZAYAZ module reference (e.g., E3_Water).
Traceability
eco_number_id	TEXT (FK)	ECO-Number™ identifier for entity/supplier traceability.
TS-CRE policy
retention_policy	TEXT	References TS-CRE policy profile (e.g., TS-CRE-DAILY-SUM).
sla_tier	TEXT	SLA tier for retention (e.g., realtime, daily, monthly).
API Integration & Security
api_base_url	TEXT	Base URL of the API.
auth_method	TEXT	Authentication type: OAuth2, JWT, API_KEY, BASIC_AUTH.
auth_ref	TEXT	Secure reference (e.g., Vault ID) for credentials (no raw secrets).
Governance
created_at	TIMESTAMPTZ	Record creation timestamp.
updated_at	TIMESTAMPTZ	Record last update timestamp.

Important: Never store API keys or passwords in this table. Instead, store them in HashiCorp Vault or cloud KMS and just link via auth_ref.

sssr-api-signal.sqlGitHub ↗
-- Enum types (optional but recommended for integrity)
DO $$ BEGIN
  CREATE TYPE api_signal_status AS ENUM ('proposed','matched','approved','dismissed');
EXCEPTION WHEN duplicate_object THEN NULL; END $$;

DO $$ BEGIN
  CREATE TYPE value_semantics AS ENUM ('counter','gauge','rate','categorical');
EXCEPTION WHEN duplicate_object THEN NULL; END $$;

DO $$ BEGIN
  CREATE TYPE aggregation_hint AS ENUM ('sum','avg','min','max','last','none');
EXCEPTION WHEN duplicate_object THEN NULL; END $$;

-- Main table
CREATE TABLE IF NOT EXISTS sssr_api_signal (
  api_signal_id      TEXT PRIMARY KEY,    -- ULID/UUID string (client-generated or db)
  -- Canonical alignment
  signal_id          TEXT NULL REFERENCES sssr_semantic_registry(signal_id) ON DELETE RESTRICT, -- approved target
  matched_signal_id  TEXT NULL REFERENCES sssr_semantic_registry(signal_id) ON DELETE RESTRICT, -- suggested target
  status             api_signal_status NOT NULL DEFAULT 'proposed',

  -- Discovery metadata
  external_system    TEXT NOT NULL,        -- e.g., sap_erp, iot_meter, utility_portal
  endpoint           TEXT NOT NULL,        -- e.g., /water/v1/consumption
  field_path         TEXT NOT NULL,        -- e.g., $.payload.meter.reading
  schema_hash        TEXT NULL,            -- fingerprint of response schema
  request_method     TEXT NULL,            -- GET|POST|…
  request_template   JSONB NULL,           -- payload/params template (no secrets)
  response_sample    JSONB NULL,           -- trimmed example for debugging
  first_seen_at      TIMESTAMPTZ NOT NULL DEFAULT now(),
  last_seen_at       TIMESTAMPTZ NULL,

  -- Units & normalization
  unit_reported      TEXT NULL,            -- as provided (liters, kWh…)
  unit_normalized    TEXT NULL,            -- canonical (m3, kWh, MJ…)
  sampling_interval  INTERVAL NULL,        -- e.g., '5 minutes'
  value_semantics    value_semantics NULL, -- counter|gauge|rate|categorical
  aggregation_hint   aggregation_hint NULL,

  -- Matching & review
  match_confidence   REAL NULL CHECK (match_confidence IS NULL OR (match_confidence >= 0 AND match_confidence <= 1)),
  reviewer_id        TEXT NULL,            -- who approved/rejected
  owner_team         TEXT NULL,

  -- Lightweight classification (USO hints)
  domain_tag         TEXT NULL,            -- e.g., ENV
  hub_code           TEXT NULL,            -- e.g., WAT, GHG
  source_type        TEXT NULL,            -- API|IoT|ERP
  api_subtype        TEXT NULL,            -- REST|GraphQL|CSV-feed
  module_code        TEXT NULL,            -- e.g., E3_Water

  -- Traceability
  eco_number_id      TEXT NULL,            -- FK to ECO-Number (ref table), nullable at discovery time

  -- TS-CRE policy
  retention_policy   TEXT NULL,            -- e.g., TS-CRE-RAW5M-HOURLY-MONTHLY
  sla_tier           TEXT NULL,            -- realtime|daily|monthly

  -- API Integration & Security
  api_base_url       TEXT NULL,
  auth_method        TEXT NULL,            -- OAuth2|JWT|API_KEY|BASIC_AUTH
  auth_ref           TEXT NULL,            -- Vault/Secrets ref ONLY (no raw)

  -- Governance
  created_at         TIMESTAMPTZ NOT NULL DEFAULT now(),
  updated_at         TIMESTAMPTZ NOT NULL DEFAULT now()
);

-- De-dupe key to avoid duplicates for the same discovered field
CREATE UNIQUE INDEX IF NOT EXISTS uix_api_field
  ON sssr_api_signal (external_system, endpoint, field_path);

-- Helpful indexes
CREATE INDEX IF NOT EXISTS ix_api_signal_status      ON sssr_api_signal (status);
CREATE INDEX IF NOT EXISTS ix_api_signal_signal_id   ON sssr_api_signal (signal_id);
CREATE INDEX IF NOT EXISTS ix_api_signal_matched_id  ON sssr_api_signal (matched_signal_id);
CREATE INDEX IF NOT EXISTS ix_api_signal_last_seen   ON sssr_api_signal (last_seen_at DESC);
CREATE INDEX IF NOT EXISTS ix_api_signal_eco         ON sssr_api_signal (eco_number_id);

-- Approved rows must have final bindings and TS-CRE attachment
CREATE OR REPLACE FUNCTION sssr_api_signal_enforce() RETURNS trigger AS $$
BEGIN
  IF NEW.status = 'approved' THEN
    IF NEW.signal_id IS NULL THEN
      RAISE EXCEPTION 'Approved sssr_api_signal requires signal_id';
    END IF;
    IF NEW.retention_policy IS NULL THEN
      RAISE EXCEPTION 'Approved sssr_api_signal requires retention_policy';
    END IF;
  END IF;
  NEW.updated_at := now();
  RETURN NEW;
END;
$$ LANGUAGE plpgsql;

DROP TRIGGER IF EXISTS trg_sssr_api_signal_enforce ON sssr_api_signal;
CREATE TRIGGER trg_sssr_api_signal_enforce
BEFORE INSERT OR UPDATE ON sssr_api_signal
FOR EACH ROW EXECUTE FUNCTION sssr_api_signal_enforce();

4.2. APIs to Implement

Propose new API signal

POST /sssr/api-signals/propose
Inserts into sssr_api_signal with status = proposed.
Emits api_signal_proposed.

Review/approve signal

PATCH /sssr/api-signals/{api_sig_id}/review
Updates status → approved/dismissed.
Links to canonical signal_id.
Emits api_signal_approved / api_signal_dismissed.

Version API signal

POST /sssr/api-signals/{api_sig_id}/version
Updates schema info + marks old version deprecated.
Emits api_signal_versioned.

Lookup (ZSSR/Engines)

GET /sssr/api-signals/{signal_id}
Returns USO tags, ECO linkage, retention policy.

4.3. Events to Emit (CMCB → ALTD)

Events must be wired to Kafka/Redpanda topics:

Event	Trigger	Key Fields
api_signal_proposed	New signal discovered	`api_sig_id`, `endpoint`, `field_path`, `uso_tags`
api_signal_approved	Admin approves mapping	`api_sig_id`, `signal_id`, `eco_number_id`, `reviewer_id`
api_signal_versioned	Schema update	`api_sig_id`, `schema_version`, `change_type`
api_signal_deprecated	Old version retired	`api_sig_id`, `superseded_by`
retention_policy_linked (new)	API signal bound to a TS-CRE policy	`api_sig_id`, `retention_policy`, `sla_tier`

4.4. Integration with TS-CRE

Ensure retention_policy in sssr_api_signal maps to a TS-CRE policy ID.
TS-CRE handles compaction, downsampling, aggregation.
When a policy executes, TS-CRE emits retention_policy_applied → ALTD.
SSSR only stores references, not execution state.

4.5. Audit Trail (ALTD)

Every signal lifecycle change (proposal, approval, versioning, retention linking) must write to ALTD.
Payload must include: signal_id, api_sig_id, eco_number_id, zssr_policy_id (if routed), retention_policy.

4.6. Sequence Flow Example

Example: New IoT water consumption API field (payload.liters)

DSAIL discovers field → POST /sssr/api-signals/propose.
Entry stored in sssr_api_signal (status=proposed).
Admin reviews → links to sssr:water.consumption.volume.
Status → approved; eco_number_id set.
retention_policy = TS-CRE-DAILY-SUM added.
TS-CRE executes compaction → emits retention_policy_applied.
ZSSR queries GET /sssr/api-signals/{signal_id} to apply routing policy.
FOGE/CSRD form auto-populates from aggregated signal values.

4.7. Dev Priorities (Thin-Slice Delivery)

Schema + API endpoints for proposal/review/versioning.
Event emissions (api_signal_proposed, etc.) → CMCB.
Linkage with ECO-Numbers.
Retention policy reference (integration stub for TS-CRE).
Admin review UI for matching signals + policies.
ALTD integration (audit events).

5. Signal Onboarding Console — UX slices

5.1. Discovery Inbox (ingest → triage)

Purpose: Catch new/changed fields auto-discovered by DSAIL and queue them for review.
Inputs shown (from sssr_api_signal draft rows): source_id, endpoint_id, field_path, unit_reported, first_seen_at, match_confidence, proposed signal_id.
Actions:
- “Review & Map” → opens Mapping Workspace
- “Dismiss / Snooze” with reason
- Bulk approve identical patterns (regex over field_path)

5.2. Mapping Workspace (map HOW → WHAT)

Left pane (Source): endpoint preview, example payloads, schema diff, field_path, unit_reported, suggested conversions.
Right pane (Canonical): search/select concept signal_id (from signal_registry where row_type='concept'), show canonical unit & validation.
Middle (Transform): unit/scale conversions, value transforms (e.g., L→m³, integrate flow→volume), dimension mapping (e.g., {device_id → eco_number_id}).
Actions: Approve mapping (creates/updates sssr_api_signal), set status (proposed/matched/approved), set eco_number_id.
Safety rails:
- Live test: run transform on sample payload; show normalized value & unit.
- Linter: block approval if canonical unit mismatch unresolved or trust rules unmet.

5.3. Concept Registry Viewer (WHAT)

Purpose: Browse/maintain canonical signals (row_type='concept').
Columns: signal_id, name, unit_canonical, taxonomy_refs, validation_profile, updated_at.
Actions: Create/rename descriptions, adjust validation/fallbacks, not storage.

5.4. Binding Catalog (WHERE)

Purpose: Manage physical placements (row_type='binding'); typically TS-CRE wide tables.
Columns: concept_signal_id, storage_kind, db_schema, table_name, column_name/metric_name, ts_cre_policy_id, writable, effective_(from/to).
Actions: Add raw/compacted bindings, change ts_cre_policy_id, deprecate bindings.

5.5. TS-CRE Policy Picker (retention/compaction)

Inline widget: re-used in Mapping Workspace & Binding Catalog.
Policies: e.g., RAW_30D, DAILY_SUM_2Y, HOURLY_AVG_1Y, MONTHLY_SUM_10Y.
Preview: storage footprint & query latency estimate (back-of-envelope) before save.

5.6. Test Harness / Simulator

Paste payload → run through transform → write to sandbox → see resulting raw + compacted rows.
Verify downstream: quick query helper for “sum last year by ECO-Number” to sanity check.

5.7. Audit & Approvals

Timeline per API signal: api_signal_proposed/approved/versioned, retention applied, binding added/removed, form autopopulated events.
Export audit JSON/CSV.

6. Data the UI edits (by table)

sssr_api_signal (mapping layer)

Editable in UI: signal_id (concept), source_id, endpoint_id, field_path, unit_reported, unit_normalized, transform spec, eco_number_id, retention_policy, status, auth_ref (selector only), match_confidence (view).
Read-only: first_seen_at/last_seen_at, schema_hash, discovery diffs.

signal_registry (concept rows)

Editable: name, description, unit_canonical, validation_profile, taxonomy_refs.
Not here: no storage specifics.

signal_registry (binding rows)

Editable: storage_kind, db_schema, table_name, metric_name/column_name, ts_cre_policy_id, writable, effective_from, effective_to, concept_signal_id.

7. Workflow (happy path)

Discovery: DSAIL proposes payload.liters for src:iot_acme_01 → Discovery Inbox.
Map: Reviewer selects canonical sssr:water.consumption.volume, sets L→m³ conversion, picks ECO-Number, sets retention_policy=DAILY_SUM_2Y → Approve (writes sssr_api_signal).
Bindings: Ops already has binding:tscre.raw and binding:tscre.daily for this concept; if not, create them here and attach ts_cre_policy_id.
Simulate: Paste sample payload → see raw & daily rows populate in sandbox.
Publish: Enable in prod; ZSSR routes FOGE queries to daily binding; ALTD captures event stream.

8. “Make it simpler” guardrails

One screen to rule them all: The Mapping Workspace includes a compact Concept panel (create/find), a Binding tab (add raw/daily), and a TS-CRE policy picker. You rarely leave this page.
Default stacks: For common metrics (kWh, m³, t), pre-select conversions and policies.
AI assist: Auto-suggest canonical signal + unit conversion + ECO-Number lookup by device_id/site_id.
Bulk modes: CSV/YAML import for dozens of endpoints; preview + batch approve.

9. Roles & permissions

Integrator: can propose & map (sssr_api_signal), run simulator.
Data Steward: approve mappings, edit concept rows, set TS-CRE policies.
DB Ops: manage bindings & storage, migrate policies.
Auditor/Verifier: read-only across everything + export audit.

10. Minimal API endpoints your UI will call

GET /registry/signals?row_type=concept&query=…
POST /registry/signals (create concept)
GET /registry/bindings?concept=…
POST /registry/bindings (create binding)
GET /api-signals?status=proposed&source_id=…
POST /api-signals/propose (DSAIL)
PATCH /api-signals/{id} (approve/map/update)
GET /tscre/policies (picker)
POST /simulator/ingest → writes to sandbox raw; compactor job runs on demand

11. Acceptance criteria (MVP)

Map a new API field to an existing concept in < 2 minutes with unit conversion and policy set.
Run a test payload and see raw + compacted records in sandbox.
Create a binding without leaving the Mapping page.
All actions emit audit events; approvals require a second role (four-eyes).
Query helper returns a year sum for the mapped signal by ECO-Number.

12. Why couple it with TS-CRE Policy Maker?

Because retention/compaction is part of the onboarding decision (cost ↔ performance ↔ compliance). If the reviewer can’t see/choose a policy in the same flow, they’ll guess—or forget. Integrating the policy picker closes that loop and prevents data sprawl.

12.1. Mapping Workspace — Wireframe (ASCII)

┌──────────────────────────────────────────────────────────────────────────────┐
│ Discovery Inbox ▸ Mapping Workspace ▸ (Concept Registry) ▸ (Bindings)        │
└──────────────────────────────────────────────────────────────────────────────┘
┌────────────────────────────────────────┬──────────────────────────────────────┐
│ Left: Source (HOW)                     │ Right: Canonical (WHAT)              │
│ ─────────────────────────────────────  │ ───────────────────────────────────  │
│ Source System:  [src:iot_acme_01]      │ Concept Signal: [sssr:water....] ⌕   │
│ Endpoint:       [/v1/water/flow] (i)   │ Name:            Water consumption   │
│ Field Path:     payload.liters         │ Unit (canonical): m3                 │
│ Schema Hash:    sha256:abc123…         │ Validation Profile: {range:…} (✎)    │
│ Last seen:      2025-09-03 10:00Z      │ Taxonomy: ESRS E3.XX (✎)             │
│ Match confidence: 0.94                 │                                      │
│                                        │ ┌──────────── Transform ───────────┐ │
│ Sample Payload ▸ { … }                 │ │ Unit conversion: L → m3          │ │
│ Preview (parsed) ▸ 15.7 L              │ │ Scale/derive: flow→integrate(5m) │ │
│                                        │ │ Dim mapping: device_id→ECO#      │ │
│                                        │ └──────────────────────────────────┘ │
│ ─────────────────────────────────────  │ ───────────────────────────────────  │
│ TS-CRE Policy                          │ Bindings (WHERE)                     │
│  [DAILY_SUM_P2Y ▼] (i)                 │  • tscre_raw:  signal_timeseries_raw │
│ Cost/Perf Estimator ▸ {footprint/lat}  │  • tscre_daily: signal_ts_compacted  │
│                                        │  (+) Add/Change Binding              │
│ ─────────────────────────────────────  │ ───────────────────────────────────  │
│ ECO-Number: [ECO-196-123-456] ⌕        │ Actions                              │
│ Auth Ref:   [vault:acme/iot01]         │  [Test Transform] [Approve Mapping]  │
│ Status:     [proposed ▸ approved]      │  [Save & Publish]  [Dismiss]         │
└────────────────────────────────────────┴──────────────────────────────────────┘

Bottom panel: Simulator
Payload ▸ (paste JSON)   →  [Run]  →  Raw row preview | Daily rollup preview
Audit log (inline): api_signal_proposed → approved → retention_policy_linked → …

Notes for FE team

Left/right split keeps mental model: HOW (source) vs WHAT (concept).
Inline TS-CRE Policy picker + cost/latency hint prevents bad defaults.
“Bindings” is a collapsible panel — most users rarely edit storage.

12.2. ER Diagram (Mermaid)

12.3. End-to-end Sequence (Mermaid)

12.4. Fields the UI edits (quick reference)

sssr_api_signal

signal_id (concept FK), source_id, endpoint_id, field_path
unit_reported, unit_normalized, transform spec (UI-only, persisted as JSON if needed)
eco_number_id, retention_policy, auth_ref, status

signal_registry

Concept rows: name, unit_canonical, validation_profile, taxonomy_refs
Binding rows: storage_kind, db_schema, table_name, metric_name/column_name, ts_cre_policy_id, writable, effective_from, effective_to, concept_signal_id

12.5. Minimal backend endpoints (for FE)

GET /registry/signals?row_type=concept&query=…
POST /registry/signals (create concept)
GET /registry/bindings?concept=…
POST /registry/bindings
GET /api-signals?status=proposed&source_id=…
POST /api-signals/propose (DSAIL)
PATCH /api-signals/{id} (approve/map/update)
GET /tscre/policies
POST /simulator/ingest (sandbox write) / GET /simulator/preview

12.6. Acceptance Tests (MVP)

Map a new API field to an existing concept with unit conversion + TS-CRE policy in ≤ 2 minutes.
Simulator shows raw & daily outputs after one click.
Bindings can be added/edited without leaving Mapping Workspace.
All actions emit audit events; approval requires dual-control.

GitHub Repo Request for Change (RFC)

1. Introduction​

2. Core Functions of the Module​

3. Submodules and Design Principles​

4. Implementation Guide — SSSR API Signal Metadata Module​

4.1. Database Schema Design​

4.2. APIs to Implement​

4.3. Events to Emit (CMCB → ALTD)​

4.4. Integration with TS-CRE​

4.5. Audit Trail (ALTD)​

4.6. Sequence Flow Example​

4.7. Dev Priorities (Thin-Slice Delivery)​

5. Signal Onboarding Console — UX slices​

5.1. Discovery Inbox (ingest → triage)​

5.2. Mapping Workspace (map HOW → WHAT)​

5.3. Concept Registry Viewer (WHAT)​

5.4. Binding Catalog (WHERE)​

5.5. TS-CRE Policy Picker (retention/compaction)​

5.6. Test Harness / Simulator​

5.7. Audit & Approvals​

6. Data the UI edits (by table)​

7. Workflow (happy path)​

8. “Make it simpler” guardrails​

9. Roles & permissions​

10. Minimal API endpoints your UI will call​

11. Acceptance criteria (MVP)​

12. Why couple it with TS-CRE Policy Maker?​

12.1. Mapping Workspace — Wireframe (ASCII)​

12.2. ER Diagram (Mermaid)​

12.3. End-to-end Sequence (Mermaid)​

12.4. Fields the UI edits (quick reference)​

12.5. Minimal backend endpoints (for FE)​

12.6. Acceptance Tests (MVP)​