Data shapes — the plant's own MES and production data

A collection can say where its plant data lives, so playbooks read it by meaning rather than by table layout. There are four shapes, each with fixed columns (matched without regard to case; extra columns are ignored):

Shape	Columns
statePeriods	start, end (empty = still open), asset, state, reason, category, planned (yes/no)
counts	bucketStart, bucketEnd, asset, product, good, reject, idealRate (may be left out)
measurements	time, asset, product, name, value, unit, recordId (shot, cycle or batch)
checks	time, asset, product, name, result (pass/fail), value, low, high

There is no KPI shape: availability and quality are worked out from state periods and counts.

Name the sources in the model's shapes block (edit it in the Context model view's JSON mode):

"shapes": {
  "statePeriods": "query:MyProject/Artekis/State Periods",
  "counts": "query:MyProject/Artekis/Counts",
  "checks": "script:MyProject/mes.shapes.checks"
}

• query:<Project>/<Path> — a select named query in a project listed in read.projects. It must declare exactly two parameters, start and end (DateTime, sqlType 8), and return the rows whose time (start, bucketStart or time) falls from start up to, not including, end. Alias the columns to the names above (SELECT stop_begin AS start, …).
• script:<Project>/<package.module.function> — a project-library function called as fn(start=…, end=…) that returns a Dataset with the same columns. It runs as the gateway, with a 30-second limit, and only while the policy's read.scriptSources is on (off by default). Use it where a named query cannot reach the data, such as a vendor scripting API.
• Assets: a row's asset is matched to the collection's assets by id, then by name ignoring case. Rows whose asset matches nothing are left out and counted by value; Artekis never invents an asset.
• Checks on every read: a missing column refuses the read and names the column; a row with an empty required cell or a wrongly typed one is left out and counted with the reason.
• Long windows are read in pages: Artekis calls the source one day at a time (UTC days; the newest and oldest page may be part of a day), newest day first, and re-reads a day that returns more than 10,000 rows as two halves (never below an hour), so a 90-day read never asks the database for 90 days at once. A source may return a period that overlaps two days to both; it is kept once, by the day its time falls in.
• Finished days are kept 15 minutes: a whole UTC day that ended at least an hour ago is kept in memory for 15 minutes (at most 200,000 rows in all; a day that does not fit is read live and not kept), so the Findings pages, Ask and the watches do not read the same days again on every view. Today and a window's partial first day are always read live. A stop coded, a count corrected, or a later stop that changes an earlier day's running period reaches these reads within 15 minutes. A day the source refuses (a missing column) is never kept.
• Row cap: at most read.shapeRowCap rows are kept per read (default 50,000). A read that reaches it stops, keeps the newest rows, and answers partial: True with coveredFrom (epoch milliseconds, the oldest time it holds). For a plant with more rows than that over the window a playbook needs, raise the setting on the Policy page.
• A collection with at least one shape mapped is an MES collection.

To check a mapping before any playbook uses it, call system.artekis.contextModel.readShape("<collection>", "statePeriods", start, end) from the Script Console (dates or epoch milliseconds; default the last 24 hours). It returns the typed rows (oldest first, times as epoch milliseconds, each row with its matched assetId), the counts of rows left out and why, pages, rowCap, partial and coveredFrom, or ok: False with code and message. It always calls the source for every day, never the 15-minute store, so it shows a source's fix at once. From a Perspective session it needs the admin level; the Designer reads only collections whose model names its open project.