spine-framework 0.4.4 → 0.5.0-rc.5

package/.framework/src/instructions/reference/functions/account-nodes.md

@@ -0,0 +1,75 @@
+---
+title: account-nodes
+audience: both
+kind: reference
+verified_against: f69c37d
+verified_on: 2026-10-30
+source_files:
+  - .framework/functions/account-nodes.ts
+  - .framework/functions/_shared/middleware.ts
+  - .framework/public/_redirects
+---
+
+# account-nodes
+
+## What it does
+
+Returns one account ("node") plus its position in the account hierarchy:
+ancestors, direct children, and full descendants. Used to render account
+trees and breadcrumb navigation.
+
+## Route and methods
+
+`/.netlify/functions/account-nodes`, reachable as
+`GET /api/account-nodes?node_id=<uuid>` (`/api/*` →
+`/.netlify/functions/:splat`). The handler performs no method check — any
+HTTP method with the query parameter works.
+
+## Authentication
+
+Standard `createHandler`: `x-api-key`, internal secret, or
+`Bearer <jwt>` required; anonymous is rejected with 401. Queries run on
+`ctx.db`, so human callers see only what row-level security allows; machine
+and system principals use the service role.
+
+## Request contract
+
+One query parameter:
+
+- `node_id` — required, the `accounts.id` to center the lookup on.
+
+## Response contract
+
+`{ node, ancestors, children, descendants }` inside the standard
+`{ data, error, meta }` envelope:
+
+- `node` — the account row's embedded `type` (`{ type: { id, slug, name,
+  icon, color } }`); the account's own columns are not selected.
+- `ancestors` — rows returned by the `get_account_ancestors` RPC, else `[]`.
+- `children` — active `accounts` rows with `parent_id = node_id`, each
+  shaped `{ type: {...} }`, ordered by `display_name`.
+- `descendants` — rows returned by the `get_account_descendants` RPC, else `[]`.
+
+## Side effects
+
+None — read-only. A `request.get` span is emitted by the middleware like
+every `createHandler` call.
+
+## Errors
+
+| Condition | HTTP | Message |
+|---|---|---|
+| Missing `node_id` | 500 | `node_id is required` |
+| No active account with that id | 500 | `Account node not found` |
+| RPC/query failure | 500 | underlying PostgREST message |
+
+## Agent notes
+
+- The `select` on `node` and `children` contains only the embedded `type`
+  relation — do not expect `display_name`, `slug`, or other account
+  columns on those payloads; fetch the account itself via
+  `/api/admin-data?entity=accounts&id=…` when you need them.
+- `ancestors`/`descendants` come from database functions; their row shape
+  is whatever the RPC returns, not the `{ type }` shape used for `node`.
+- Inactive accounts are filtered from `node` and `children`
+  (`is_active = true`) but RPC results are whatever the functions return.

package/.framework/src/instructions/reference/functions/admin-data.md

@@ -0,0 +1,197 @@
+---
+title: admin-data
+audience: both
+kind: reference
+verified_against: f69c37d
+verified_on: 2026-11-01
+source_files:
+  - .framework/functions/admin-data.ts
+  - .framework/functions/_shared/middleware.ts
+  - .framework/functions/_shared/permissions.ts
+  - .framework/functions/_shared/access.ts
+  - .framework/functions/_shared/security.ts
+  - .framework/public/_redirects
+---
+
+# admin-data
+
+## What it does
+
+`admin-data` is the generic CRUD endpoint for Spine's runtime and config
+tables. One function exposes list, get, stats, create, update, and remove
+across a fixed allowlist of entities, with record-permission evaluation,
+field-level sanitization, type-schema stamping, and trigger firing built in.
+Custom apps are expected to use this endpoint for all runtime-record CRUD
+rather than wrapping it.
+
+## Route and methods
+
+`/.netlify/functions/admin-data`, reachable publicly as `/api/admin-data`
+(`/api/*` is redirected to `/.netlify/functions/:splat` in
+`.framework/public/_redirects`).
+
+Dispatch is by `?action=` plus HTTP method (`.framework/functions/admin-data.ts`
+handler):
+
+| Call | Action |
+|---|---|
+| `GET /api/admin-data?action=list&entity=…` | `list` |
+| `GET /api/admin-data?action=get&entity=…&id=…` | `get` |
+| `GET /api/admin-data?action=stats&entity=…` | `stats` |
+| `POST /api/admin-data?action=create` | `create` |
+| `PATCH /api/admin-data?action=update&entity=…&id=…` | `update` |
+| `DELETE /api/admin-data?action=remove&entity=…&id=…` | `remove` |
+
+Without a recognized `action` (absent or unmatched), the HTTP method alone
+dispatches: `GET` → `get` when `id` is present else `list`, `POST` →
+`create`, `PATCH` → `update`, `DELETE` → `remove`. A `?method=` query
+parameter overrides the HTTP method for dispatch (the middleware copies
+`event.httpMethod` into `query.method` only when the query did not set
+it). A matched action with the wrong method (e.g. `action=list` on `POST`)
+falls through to `Invalid action or method`.
+
+## Authentication
+
+Standard `createHandler` authentication: `x-api-key` (machine), internal
+invoke secret (system), or `Authorization: Bearer <jwt>` (human). Anonymous
+requests are rejected with 401 before the handler runs.
+
+- Humans query through a JWT-scoped client (`ctx.db`), so row-level security
+  applies. Machines, anonymous, and system principals get the service-role
+  client — endpoint-level checks carry the weight.
+- `list` switches to `adminDb` when `principal.isInternal` or the principal
+  is a system admin; otherwise it uses `ctx.db`.
+- `create` calls `resolveFirstSurfacePermissions(personId, accountId,
+  typeSlug, 'create', designSchema)` — a machine whose scopes contain `*:*`
+  bypasses (`isMachineGlobal`); a `*:*` machine also resolves as
+  `system_admin`.
+- `update` runs `validateUpdatePermissions` and lets system admins through
+  regardless of the result.
+- `remove` calls `resolveFirstSurfacePermissions(..., 'delete',
+  existing.design_schema)` with a system-admin bypass.
+- Non-internal audiences never see `visibility: 'internal'` threads, and
+  internal messages on external threads are projected to label-only
+  skeletons via `projectMessageForCustomer`.
+
+## Request contract
+
+`entity` is required on every call and must be one of `VALID_ENTITIES`:
+`accounts`, `people`, `items`, `threads`, `messages`, `links`,
+`attachments`, `watchers`, `item_progress`, `logs`, `test_runs`,
+`observability`, `test_cases`, `types`, `link_types`, `ai_agents`,
+`prompt_configs`.
+
+**list** (query params): `entity`, `search` (ILIKE against a per-entity
+field — e.g. `title` for items, `full_name` for people, `message` for
+logs), `sort_field` (default `created_at`), `sort_direction` (`desc`
+default), `limit` (default 50), `offset` (default 0), `type_slug`,
+`type_slugs` (comma-separated, resolved through `ENTITY_TO_KIND` to
+`type_id` filters), `view`, `flag_only` / `exclude_flag` (filter on
+`data->><flag>` for `items`, `threads`, `messages`, `links`, `attachments`,
+`watchers`). Every other query parameter becomes an `.eq(key, value)`
+filter, with boolean coercion for `is_active`, `is_verified`, `is_primary`.
+Soft-deleted rows are hidden by default — pass `is_active=false` or
+`include_inactive=true` to include them. The default `is_active` filter
+only applies to tables that have the column; `links`, `attachments`,
+`watchers`, `logs`, and `observability` skip it.
+
+**get** (query params): `entity`, `id`, `view`, `lineage` — for `items`,
+parent/child lineage is attached unless `lineage=0`.
+
+**stats** (query params): `entity` only.
+
+**create** (body): `entity` (or `?entity=`), `type_slug` or `type_id` —
+required for every non-raw entity; `account_id` (optional override);
+arbitrary record fields. `design_schema`, `validation_schema`, and `id` in
+the body are stripped. `thread_id`, `target_id`, or `parent_id` in the body
+pull account and `scope` from the parent record.
+
+**update** (query `entity` + `id`; body): record fields; `design_schema`,
+`validation_schema`, `type_id`, `type_slug`, `id`, `entity` are stripped.
+`account_id` is honored only for `entity=people`.
+
+**remove** (query params): `entity`, `id`, `soft` (default `'true'`).
+
+## Response contract
+
+All responses use the middleware envelope:
+`{ "data": <result>, "error": null, "meta": { "requestId", "duration" } }`
+with HTTP 200. Errors return `{ "data": null, "error": "<message>" }` with
+HTTP `err.statusCode || 500`.
+
+- `list` → array of sanitized records; when both `view` and `type_slug`
+  are given and the type resolves, `{ data, schema, view }` (schema = the
+  type's `design_schema`, `view` = `schema.views[view]` or `null`). The
+  exact-count probe runs but the count is not returned.
+- `get` → one sanitized record; `items` records additionally carry
+  `parents`, `children`, and `type_slug` fields from
+  `design_schema.functionality.lineage`. With `view`, returns
+  `{ data, schema, view }`.
+- `stats` → `{ entity, count }`.
+- `create` / `update` → the sanitized row.
+- `remove` → `{ deleted: true, soft: true, data }` on soft delete, or
+  `{ deleted: true, soft: false }` on hard delete.
+
+## Side effects
+
+- Writes to the target table. On create, `design_schema` and
+  `validation_schema` are stamped onto the record from the resolved type
+  (missing `record_permissions` defaults to `PERMISSIONS_ALL` — all
+  actions for everyone), plus `created_by`, `created_at`, `updated_at`,
+  and `account_id` (except `accounts`, which gets `parent_id` instead).
+  `types` and `link_types` skip `created_by`/`updated_by` (`UNAUDITED_ENTITIES`).
+- `scope: 'platform'` schemas force `account_id` to the `spine-system`
+  account; a `thread_id`/`target_id`/`parent_id` parent overrides both
+  account and scope.
+- `fireCreateTriggers` runs after every create (including raw entities) and
+  `fireUpdateTriggers` after every update; trigger errors are logged, not
+  raised. **`fireDeleteTriggers` is imported but never called** — removing
+  a record fires no triggers.
+- `logs`, `test_runs`, `observability`, `test_cases` (`RAW_ENTITIES`)
+  bypass type resolution entirely: create inserts a fixed column whitelist
+  (e.g. `level`+`message` required for `logs`, `suite` for `test_runs`,
+  `metric_name`+`metric_value` for `observability`, `slug`+`name` for
+  `test_cases`) and update skips the `updated_by`/`updated_at` stamps.
+- `checkTypeSlugRateLimit` enforces the app's `rate_limits.<type_slug>_create`
+  policies on create.
+- Every action is wrapped in `withAdminLogging`, which writes
+  admin-operation log rows (entity, action, method, duration, row count).
+
+## Errors
+
+| Condition | HTTP | Message |
+|---|---|---|
+| No/invalid `entity` | 400 (create) / 500 (others) | `Valid entity parameter is required` |
+| Missing `id` on get/update/remove | 500 | `ID parameter is required` / `ID is required for update|delete` |
+| Missing type on create | 400 | `type_id or type_slug is required — every runtime record must reference a type` |
+| Bad `type_id` / inactive type | 500 | `type_id not found: …` / `type_id references an inactive type: …` |
+| `type_slug` on an unmappable entity | 400 | `type_slug is not supported for entity: …` |
+| Missing parent | 403 | `Parent record not found or not accessible` |
+| Permission denied | 403 | `Insufficient permissions to create|update|delete this record` |
+| Record missing or RLS-hidden | 500 | `Record not found or access denied` |
+| Bad flag name | 400 | `Invalid flag field name` |
+| Unknown action/method | 500 | `Invalid action or method` |
+
+## Agent notes
+
+- Always pass `type_slug` (not `type_id`) when creating runtime records —
+  the endpoint resolves it per `kind` via `ENTITY_TO_KIND`
+  (`items`→`item`, `threads`→`thread`, `messages`→`message`, `links`→`link`,
+  `attachments`→`attachment`, `watchers`→`watcher`, `accounts`→`account`,
+  `people`→`person`, `item_progress`→`item_progress`).
+- Soft delete is the default and only applies to `accounts`, `people`,
+  `items`, `threads`, `messages`, `watchers`, `item_progress`,
+  `test_cases` — it sets `is_active=false`. Everything else hard-deletes
+  even without `soft=false`; pass `soft=false` explicitly when you mean it.
+- Delete triggers do not exist in practice: `remove` never calls
+  `fireDeleteTriggers`, so automations keyed on delete events will not run.
+- `?id=` is mirrored into the JSON body by the middleware before the
+  handler runs.
+- Record reads are sanitized per principal: second/third-surface tables and
+  field-level `permissions` in `design_schema` shape what comes back, and a
+  principal with no account context gets only `id`/`created_at`/`updated_at`.
+- A machine API key without `*:*` scope cannot create (the permission
+  lookup is by `people.id`, which machine keys don't have) — use `*:*`
+  keys for server-side writes, or a human JWT.
+- `update` does not re-stamp `design_schema`; changing a record's type
+  is not possible through this endpoint (`type_id` is stripped).

package/.framework/src/instructions/reference/functions/admin-funnel.md

@@ -0,0 +1,90 @@
+---
+title: admin-funnel
+audience: developers, agents
+kind: reference
+verified_against: f69c37d
+verified_on: 2026-10-30
+source_files:
+  - .framework/functions/admin-funnel.ts
+  - .framework/functions/_shared/middleware.ts
+  - .framework/functions/_shared/funnel.ts
+---
+
+# admin-funnel
+
+## What it does
+
+Computes anonymous-visitor → identified-user → installed-instance
+conversion metrics for the platform funnel. It reads `items` rows under
+three app-seeded item types — `funnel_signal`, `anonymous_session`, and
+`spine_instance` — and returns counts, conversion rates, and a
+stage distribution over the last 30 days.
+
+This is framework-internal telemetry for the platform operator (growth
+and install funnel for Spine itself), not per-customer app analytics.
+
+## Route and methods
+
+**None — this file exports no `handler`.** It exports a single
+`createHandler`-wrapped const, `metrics`, which nothing else imports or
+dispatches. As shipped there is no HTTP entrypoint: the file is deployed
+to the functions directory by the assembly script like every other
+`.framework/functions` file, but Netlify has no `handler` export to
+invoke. Treat it as a dormant module pending a dispatch handler (or a
+wiring bug); do not cite it as a live endpoint.
+
+## Authentication
+
+If `metrics` were wired: `createHandler` requires any non-anonymous
+principal — no role check inside the function. All queries run on
+`adminDb` across **all accounts** (see Agent notes).
+
+## Request contract
+
+`metrics(ctx, body)` takes no parameters — the 30-day window is hardcoded.
+
+## Response contract
+
+`{ anonymous_visitors, identified_users, installed_instances,
+conversion_rates: { anonymous_to_identified, identified_to_installed },
+stage_distribution: [{ stage, count, percentage }] }`
+
+- `anonymous_visitors` — `anonymous_session` items in the last 30 days
+  whose `data->lifecycle->>stitched_to_account_id` is null.
+- `identified_users` — distinct `account_id`s on `funnel_signal` items in
+  the last 30 days.
+- `installed_instances` — `spine_instance` items with a non-null
+  `data->>claimed_by_person_id` (all time).
+- `stage_distribution` — counts of `funnel_signal.data->>stage` over the
+  last 30 days, only counting rows that have an `account_id`.
+
+## Side effects
+
+None — read-only aggregation.
+
+## Errors
+
+No explicit error paths. Missing signal types are expected on a clean
+install (the types are seeded by installed apps): when none of the three
+type slugs resolves, `metrics` returns a zeroed payload instead of
+failing. Database errors would surface as thrown errors through
+`createHandler`'s 500 path.
+
+## Agent notes
+
+- **Verify before use.** The missing `handler` export means there is no
+  routed endpoint; check the current tree before assuming
+  `GET /api/admin-funnel` does anything.
+- **Unscoped platform-wide reads.** If wired as-is, every query runs on
+  `adminDb` with no `account_id` filter and no `isSystemAdmin` gate — any
+  authenticated principal would see cross-account funnel data. A
+  `system_admin` check belongs in any dispatch handler that exposes it.
+- Signal data is written elsewhere — `emitSignal` in
+  `.framework/functions/_shared/funnel.ts` inserts typed signal items
+  (`funnel_signal` among them) and fires `item_created` triggers; these
+  admin modules only read the results.
+- The `funnel_signal_use` type seed exists in the framework
+  (`.framework/seeds/types/funnel_signal_use.json`); the
+  `funnel_signal`/`anonymous_session`/`spine_instance` slugs the queries
+  look for are seeded by installed apps, hence the degrade-to-zeros
+  behavior.

package/.framework/src/instructions/reference/functions/admin-install-funnel.md

@@ -0,0 +1,107 @@
+---
+title: admin-install-funnel
+audience: developers, agents
+kind: reference
+verified_against: f69c37d
+verified_on: 2026-10-30
+source_files:
+  - .framework/functions/admin-install-funnel.ts
+  - .framework/functions/_shared/middleware.ts
+  - .framework/functions/_shared/funnel.ts
+---
+
+# admin-install-funnel
+
+## What it does
+
+Install-funnel analytics for the platform operator: download/install/
+first-use/claimed counts, per-day install trends over 30 days, recent
+install records with contact and account joins, a version breakdown, and
+a full export of install-instance records. All data comes from `items`
+rows under the `funnel_signal` type where `data->>source = 'inst'`, plus
+`spine_instance` rows for the version split.
+
+Framework-internal telemetry about Spine installations (serials, app
+versions, environments), not customer app data.
+
+## Route and methods
+
+**None — this file exports no `handler`.** It exports two
+`createHandler`-wrapped consts, `metrics` and `exportData`, which nothing
+imports or dispatches. As shipped there is no HTTP entrypoint; treat it
+as a dormant module pending a dispatch handler (or a wiring bug), not a
+live endpoint.
+
+## Authentication
+
+If wired: `createHandler` requires any non-anonymous principal — no role
+check inside either export. All queries run on `adminDb` across **all
+accounts** (see Agent notes).
+
+## Request contract
+
+Neither export reads parameters — `metrics` uses fixed windows and
+`exportData` returns the full matching set.
+
+## Response contract
+
+`metrics` →
+
+```json
+{
+  "total_downloads": 0,
+  "unique_installers": 0,
+  "active_instances": 0,
+  "conversion_funnel": { "downloads": 0, "installations": 0, "first_use": 0, "claimed": 0 },
+  "install_trends": [{ "date": "YYYY-MM-DD", "downloads": 0, "installations": 0 }],
+  "recent_installs": [{ "id": "…", "serial": "…", "app_version": "…", "environment": "…",
+                        "first_seen_at": "…", "last_signal_at": "…",
+                        "claimed_by": "…", "claimed_at": "…",
+                        "account_name": "…", "person_email": "…" }],
+  "top_versions": [{ "version": "…", "count": 0, "percentage": 0 }]
+}
+```
+
+Field semantics:
+
+- `total_downloads` / `installations` / `first_use` — `funnel_signal`
+  rows with `action_type` `download` / `install` / `first_command`.
+- `unique_installers` — distinct `data->>serial` values.
+- `active_instances` — serialized signals seen in the last 7 days.
+- `claimed` — signals with non-null `data->>claimed_by_person_id`.
+- `install_trends` — 30 daily buckets of download + install counts.
+- `recent_installs` — latest 20 serialized signals joined to
+  `people(email)` and `accounts(name)`.
+- `top_versions` — up to 10 versions by `spine_instance` count share.
+
+`exportData` → `{ instances, exported_at, total_count }` — every
+`funnel_signal` row with `source='inst'` and a serial, full `data` bag,
+`account_id`, and the same people/accounts joins, newest first.
+
+## Side effects
+
+None — read-only.
+
+## Errors
+
+No explicit error paths. When the `funnel_signal` type is absent
+(app-seeded; missing on a clean install) `metrics` returns a zeroed
+payload and `exportData` returns `{ instances: [], …, total_count: 0 }`.
+The 30-day trend loop issues two count queries per day (60 sequential
+queries) — slow but not an error.
+
+## Agent notes
+
+- **Verify before use** — no `handler` export means no routed endpoint;
+  `?action=export`-style dispatch does not exist in the file.
+- **Platform-wide PII.** `exportData` and the `recent_installs` join
+  return `people.email` and `accounts.name` across all accounts via
+  `adminDb`, gated only by authentication if this is ever wired. Any
+  dispatch handler added later must gate on `system_admin` (or narrower)
+  before exposing these exports.
+- The daily-trend loop is 60 round trips per call — do not put it on a
+  hot path; if the endpoint is wired for real use, fold the loop into a
+  single grouped query or RPC.
+- `serial` is the installer-instance identity; `claimed_by_person_id`
+  links an install to a registered person — that join is what makes the
+  export PII-bearing.

package/.framework/src/instructions/reference/functions/admin-signals.md

@@ -0,0 +1,102 @@
+---
+title: admin-signals
+audience: developers, agents
+kind: reference
+verified_against: f69c37d
+verified_on: 2026-10-30
+source_files:
+  - .framework/functions/admin-signals.ts
+  - .framework/functions/_shared/middleware.ts
+  - .framework/functions/_shared/funnel.ts
+---
+
+# admin-signals
+
+## What it does
+
+Two read surfaces over `funnel_signal` items for the platform operator:
+`metrics` aggregates signal totals (all-time, today, this week), a
+conversion rate from high-value signals, top sources, and the 20 most
+recent signals; `audit` lists individual signal records with filters,
+pagination, attribution fields (UTM/referrer/anonymous identity), and an
+unpaginated export mode.
+
+Signals record product-journey events (`action_type`, `stage`, `source`,
+`rating`) — framework-internal telemetry for the platform, not customer
+app analytics.
+
+## Route and methods
+
+**None — this file exports no `handler`.** It exports `metrics` and
+`audit`, both `createHandler`-wrapped, which nothing imports or
+dispatches. As shipped there is no HTTP entrypoint; treat it as a dormant
+module pending a dispatch handler, not a live endpoint.
+
+## Authentication
+
+If wired: `createHandler` requires any non-anonymous principal — no role
+check in either export. All queries run on `adminDb` across **all
+accounts** (see Agent notes).
+
+## Request contract
+
+`metrics` — no parameters; windows are hardcoded (today, trailing 7
+days).
+
+`audit` — query parameters:
+
+| Param | Effect |
+|---|---|
+| `page` (default 1), `limit` (default 50) | Pagination (ignored in export mode) |
+| `date_from`, `date_to` | `created_at` bounds |
+| `source`, `stage`, `action_type` | Exact match on `data->>` fields |
+| `min_rating` | `data->>rating >= value` |
+| `account_id` | Caller-supplied account filter |
+| `search` | OR-match on `accounts.name`, `people.email`, `data->attribution->>first_touch_referrer_domain` (ILIKE) |
+| `export` (any value) | Returns the full formatted array with no range limit |
+
+## Response contract
+
+`metrics` → `{ total_signals, signals_today, signals_this_week,
+conversion_rate, top_sources: [{source, count}], recent_signals: [{id,
+action_type, source, stage, created_at, account_name, rating}] }`.
+`conversion_rate` is the share of this week's signals with
+`data->>rating >= '4'` — a "high-value signal" rate, not a funnel
+conversion.
+
+`audit` → `{ signals, total, page, limit }`, or in export mode the bare
+formatted array. Each signal row: `{ id, action_type, action_value,
+stage, source, created_at, account_name, person_email, anonymous_id,
+session_id, rating, raw_score, referrer_domain, utm_source, utm_medium,
+utm_campaign }` — joined to `people(email)` and `accounts(name)`, with
+identity fields from `data->identity` and attribution from
+`data->attribution`.
+
+## Side effects
+
+None — read-only.
+
+## Errors
+
+- `Failed to fetch signals: <message>` — the one thrown error, on query
+  failure inside `audit`.
+- Missing `funnel_signal` type (app-seeded; absent on clean installs)
+  degrades gracefully: `metrics` returns zeroed metrics, `audit` returns
+  an empty page or `[]` in export mode.
+
+## Agent notes
+
+- **Verify before use** — no `handler` export means no routed endpoint.
+- **Cross-account PII, caller-steered.** `audit` accepts an arbitrary
+  `account_id` filter and returns `people.email`, `accounts.name`,
+  anonymous IDs, session IDs, and UTM attribution across all accounts via
+  `adminDb`. If a dispatch handler is ever added, it needs a
+  `system_admin` gate before this surface is exposed.
+- `export` mode drops the range limit — it returns the entire filtered
+  set, so combined with the joins it is the heaviest call in the file.
+- Rating comparisons are string comparisons on `data->>rating`
+  (`gte '4'`) — works for single digits, but `"10" >= "4"` is false
+  lexicographically; values above 9 would misclassify.
+- Signals are produced by `emitSignal` in
+  `.framework/functions/_shared/funnel.ts` (deduped once per account +
+  `action_type` by default) — this module only reads them.