Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.ilyama.golain.io/llms.txt

Use this file to discover all available pages before exploring further.

Golain does not blindly copy SQLite schemas. Every table’s schema fingerprint is hashed, classified, and — when required — reviewed by an operator before data becomes queryable product storage.

​
Schema fingerprint

Before each batch, the edge agent builds canonical JSON from PRAGMA table_info: 
{
  "table_name": "device_state",
  "columns": [
    { "name": "id", "decl_type_affinity": "INTEGER", "pk_ordinal": 1, "not_null": true },
    { "name": "mode", "decl_type_affinity": "TEXT", "pk_ordinal": 0, "not_null": false }
  ]
}
Rules:
  • Columns sorted by name (not table ordinal).
  • Types mapped to SQLite affinity classes (INTEGER, TEXT, REAL, BLOB, NUMERIC).
  • pk_ordinal: 0 for non-PK columns; 1..N for composite PK members.
  • Indexes, triggers, FKs, defaults — excluded from fingerprint.
Hash: canonical JSON (sorted keys, no whitespace) → SHA-256 → lowercase 64-char hex = schema_hash. Column reorder does not change the hash. Adding/removing columns, changing types, or PK membership does. → Integrator detail: Payload formats — schema observation

​
Classification

When a batch arrives with a hash the cloud has not accepted for this lineage:
ClassificationTypical triggerDefault behavior
compatible_additiveNew nullable columnMay auto-continue if policy allows
compatible_mappedMatches existing bindingsMaterialize
ambiguousFirst schema or unbound columnsReview queued, lineage paused, rows staged
breakingType change, dropped column, PK changeReview queued, lineage paused
unknownParser edge caseTreat as ambiguous
Production default: allow_additive_continue=false → first insert to a new table always hits ambiguous.

​
Schema observation (advisory)

Devices may publish sync/schema/observe when hash changes: 
{
  "format_version": 1,
  "source_table": "device_state",
  "schema_hash": "a3f9...",
  "observed_at": "2026-04-28T09:00:00.000000000Z"
}
Observations warm server-side registry metadata. They do not replace the need for a data batch to trigger classification.

​
Schema review states

StatusMeaning
queuedAwaiting operator claim
in_reviewOperator claimed; inspecting staged rows
approvedColumn actions applied; replay scheduled
rejectedSchema rejected; lineage stays paused
abandonedOperator abandoned (registry path)
Permission for claim/approve/reject: PROJECT_CAN_MANAGE_DEVICES.

​
Column actions (approve)

When approving, specify one action per source column:
ActionEffect
mirrorRelational column in edge_mirror_* table (mirror_column_name optional)
mapMap to existing device_data_point_id → telemetry path
ignoreDrop column from cloud projection
deferLeave unbound — lineage may stay paused if required columns deferred
auto_create_and_mapCreate datapoint + map (requires project policy allow_auto_create_device_data_points=true)
Example approve body: 
{
  "action_version": 1,
  "column_actions": [
    { "source_column_name": "id", "action": "mirror", "mirror_column_name": "id" },
    { "source_column_name": "key", "action": "mirror", "mirror_column_name": "key" },
    { "source_column_name": "value", "action": "mirror", "mirror_column_name": "value" }
  ]
}
All mutations require header Idempotency-Key. → Step-by-step: Schema review workflow

​
What the device does during review

The edge agent does not wait for review completion:
  1. Keeps publishing batches with the new schema_hash.
  2. Cloud stages rows while lineage is paused for review.
  3. After approve, cloud replays staged rows into mirror.
If the server sends pause_lineage (backpressure, not review alone), the device must ACK and buffer locally. → Downlink control

​
Schema drift on device

When application migrations alter SQLite DDL:
  1. Edge recomputes fingerprint on next flush.
  2. Optional sync/schema/observe publish.
  3. Next batch includes new hash → cloud re-classifies.
Reinstall triggers after DDL on enrolled tables (Omega does this on module restart).

​
Events (audit / automation)

Governance emits integration events (for SSE, workflows):
  • integration.edge_schema_review.queued|approved|rejected|abandoned.v1
  • integration.edge_table_lineage.ingestion_paused|ingestion_resumed.v1
  • integration.edge_export_segment.materialized|materialization_failed.v1
Subscribe via project event stream: platform-tui events watch.