FAMEPy 0.1.0rc1__tar.gz

famepy-0.1.0rc1/.gitignore

@@ -0,0 +1,51 @@
+# Python environments, caches and build products
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+build/
+dist/
+*.egg-info/
+.tox/
+.nox/
+.cache/
+
+# Compiled artifacts and local FAME installations
+*.dll
+*.so
+*.so.*
+*.dylib
+*.pyd
+*.o
+*.obj
+*.lib
+*.a
+vendor/
+
+# Local databases, diagnostics and reports; synthetic fixtures can be added
+# explicitly after review. Never add production databases to this repository.
+*.db
+*.db.*
+*.sqlite
+*.sqlite3
+test-results/
+local-results/
+*.log
+
+# Credentials and local editor settings
+.env
+.env.*
+!.env.example
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db
+*.swp
+*~

famepy-0.1.0rc1/.pre-commit-config.yaml

@@ -0,0 +1,18 @@
+repos:
+  - repo: local
+    hooks:
+      - id: public-files
+        name: public text hygiene and privacy patterns
+        entry: python scripts/check_public.py
+        language: system
+        types: [text]
+      - id: ruff
+        name: ruff
+        entry: python -m ruff check
+        language: system
+        types: [python]
+      - id: ruff-format
+        name: ruff format
+        entry: python -m ruff format --check
+        language: system
+        types_or: [python, markdown]

famepy-0.1.0rc1/CHANGELOG.md

@@ -0,0 +1,59 @@
+# Changelog
+
+Versions follow [PEP 440](https://peps.python.org/pep-0440/). A version
+is built and verified once by a rehearsal run whose artifact is reviewed,
+and only that reviewed artifact is promoted to the index (see
+[releasing](docs/releasing.md)). An entry marked *unreleased* has not been
+promoted.
+
+## 0.1.0rc1 (unreleased)
+
+First release candidate. FAMEPy is a pure-Python package that binds the
+FAME CHLI library through `ctypes`, with the behavior of
+[FAME.jl](https://github.com/bankofcanada/FAME.jl) as the reference and
+[TimeSeriesEconPy](https://github.com/Nic2020/TimeSeriesEconPy) as the
+time-series model. A separately installed, licensed FAME runtime is
+required for every native operation; nothing of it is distributed.
+
+Included:
+
+- Runtime lifecycle: one initialization per process, terminal
+  finalization, trusted library discovery through `FAME` or
+  `FAMEPY_LIBRARY`, diagnostics and a subprocess symbol probe without
+  native calls.
+- Databases: the five local access modes, the work database, explicit
+  posting, connection strings passed through the local open (the
+  reference's read-only remote route); the server-connection write modes
+  are refused before any native call, as neither wrapper binds them.
+- Raw object I/O for precision, numeric, Boolean, date, string and
+  namelist scalars and series with preserved missing categories,
+  subranges, exact-width scalars and complete validation before the first
+  native call; wildcard listing with filters; command execution with
+  recursive `INPUT` expansion; opt-in extended error text.
+- The TimeSeriesEconPy bridge: every reference value kind, every reference
+  frequency anchor, workspace, mapping and multivariate writes, workspace
+  reads with name transformation, per-object reporting variants, and the
+  missing, empty and text policies. String values are ASCII by default and
+  can be exchanged as raw bytes or, opt-in, as strict UTF-8; names, paths
+  and commands stay ASCII.
+- A FAME-to-DataEcon migration workflow with a plan-first, refuse-by-default
+  loss policy and structural verification on read.
+- A consolidated native validation runner (eleven groups, isolated worker
+  processes, sanitized reports, optional FAME.jl differential checks) and a
+  benchmark harness with verified read-backs.
+
+Evidence for this candidate is summarized in
+[capability status](docs/capabilities.md) and the
+[parity ledger](docs/parity.md): the eleven validation groups passed on one
+Windows and one Linux installation with the FAME.jl comparisons configured
+on both, the benchmark scenarios completed on both, and a bounded read-only
+comparison of one small approved remote selection was equal through both
+wrappers on both hosts. These are statements about the inspected
+installations, not blanket version coverage.
+
+Deliberate differences from the reference are documented in
+[contracts](docs/contracts.md) and the ledger: no restart of the runtime in
+one process, missing Booleans refused instead of read as `true`, a scalar
+NaN written as NC, integer scalars kept exact or refused, an explicit mode
+required for path writes, and whole-value UTF-8 decoding instead of the
+reference's byte-length slicing.

famepy-0.1.0rc1/CONTRIBUTING.md

@@ -0,0 +1,45 @@
+# Contributing
+
+Treat every tracked file, commit, workflow log, issue and distribution as public.
+Keep internal project labels, private plans and links, personal contact details,
+staff names and institutional discussions out of these surfaces. Retain legally
+required copyright notices and factual upstream attribution. Use the project
+contact `statespaceecon@gmail.com` where a contact address is needed.
+
+Use synthetic test data. Do not add production databases, connection strings,
+credentials, vendor headers, help files, licensed libraries or raw diagnostic
+logs. Review generated files as carefully as source. Ignore rules and automated
+checks assist review; they cannot prove that an arbitrary file is safe to publish.
+
+## Development
+
+Python 3.11 or newer is required. The foundation is tested without FAME:
+
+```sh
+uv sync --locked
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy
+uv run pytest
+uv run pre-commit run --all-files
+uv build
+```
+
+Unit tests use the in-memory fake backend in `tests/fake_native.py`; it models
+the package's own contracts and is not FAME behavior evidence. The validation
+runner's self-test drives that fake through real subprocesses.
+
+The independent C shim needs a compiler (MSVC on Windows, GCC/Clang on Linux).
+Run from a compiler-enabled terminal:
+
+```sh
+uv run python scripts/build_test_shim.py
+```
+
+Set `FAMEPY_TEST_SHIM` to the **absolute** path printed by the builder, then run
+pytest again. CI requires these tests; an ordinary developer run without the
+variable reports them as skipped. The shim contains no vendor code and does not
+certify FAME compatibility. See [native validation](docs/native-validation.md).
+
+Install hooks with `uv run pre-commit install` if desired. Before publication,
+review Git history and built wheel/sdist contents as well as the current tree.

famepy-0.1.0rc1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nic2020
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

famepy-0.1.0rc1/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.5
+Name: FAMEPy
+Version: 0.1.0rc1
+Summary: Python bindings and time-series integration for the FAME CHLI library
+Project-URL: Repository, https://github.com/Nic2020/FAMEPy
+Project-URL: Issues, https://github.com/Nic2020/FAMEPy/issues
+License-Expression: MIT AND BSD-3-Clause
+License-File: LICENSE
+License-File: licenses/FAME.jl.txt
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: numpy>=1.26
+Requires-Dist: timeserieseconpy>=0.0.1.dev3
+Description-Content-Type: text/markdown
+
+# FAMEPy
+
+Python bindings for the FAME CHLI library with integration for
+[TimeSeriesEconPy](https://github.com/Nic2020/TimeSeriesEconPy).
+The behavioral reference is
+[FAME.jl](https://github.com/bankofcanada/FAME.jl).
+
+**Status: first release candidate (0.1.0rc1). The operational core,
+the full TimeSeriesEconPy bridge (runtime lifecycle, local databases, raw
+object I/O, listing, commands, every reference frequency anchor, every
+value kind, workspace reads and writes, the string value text policies),
+the opt-in extended error text and the FAME-to-DataEcon migration
+workflow passed the consolidated eleven-group validation campaign on one
+Windows and one Linux host with an installed FAME, with the FAME.jl
+comparisons configured on both; the benchmark harness completed its
+scenarios on both; and a bounded read-only comparison of one small
+approved remote selection was equal through the reference and this
+package on both hosts. See [capability status](docs/capabilities.md),
+the [parity ledger](docs/parity.md) and the [changelog](CHANGELOG.md).
+These are statements about the inspected installations, not blanket
+version coverage.**
+
+Implemented: runtime lifecycle, databases (the five local access modes, work
+database, explicit posting), raw scalar and series I/O for precision,
+numeric, Boolean, date, string and namelist objects with preserved missing
+categories, wildcard listing with filters, command execution with recursive
+INPUT expansion, and the TimeSeriesEconPy bridge: values of every reference
+kind, all reference frequency anchors, workspace/mapping/multivariate
+writes and workspace reads with name transformation and per-object
+reporting, with string values as ASCII, raw bytes or strict UTF-8.
+Also: opt-in extended error text, a
+[FAME-to-DataEcon migration workflow](docs/migration.md) and a
+[benchmark harness](docs/benchmarks.md).
+Not implemented: server-connection writes (the reference's remote route is
+read-only and neither wrapper binds a named-connection write API),
+multivariate reconstruction on read (not in the reference either).
+
+Windows and Linux x86-64 are the intended runtime platforms. A separately
+installed, licensed FAME runtime is required for FAME operations; it is not
+distributed with this project. FAMEPy depends on TimeSeriesEconPy;
+TimeSeriesEconPy remains independent of FAMEPy and FAME.
+
+## Install and try
+
+From a clone, with Python 3.11 or newer:
+
+```sh
+python -m pip install .
+python -m famepy            # discovery report, exits 1 without FAME
+python -m famepy --probe    # symbol presence in a subprocess, no CHLI calls
+```
+
+The package builds without FAME, vendor headers or a C compiler and does not
+bundle FAME. Set `FAME` to the installation (required for licensing) or
+`FAMEPY_LIBRARY` to an absolute trusted library path. Load only trusted
+native libraries.
+
+```python
+import famepy
+from famepy import bridge
+from tsecon import TSeries, mm
+
+famepy.initialize()  # once per process
+bridge.write_tseries("synthetic.db", "ts", TSeries(mm(2020, 1), [1.0, 2.0]), mode="create")
+print(bridge.read_tseries("synthetic.db", "ts"))
+famepy.finalize()  # terminal; use a new process for another runtime
+```
+
+See [installation](docs/installation.md) (including offline wheelhouses),
+[usage](docs/usage.md), [contracts](docs/contracts.md),
+[capability status](docs/capabilities.md), the [parity ledger](docs/parity.md),
+[migration](docs/migration.md), [benchmarks](docs/benchmarks.md),
+[native validation](docs/native-validation.md),
+the [ABI checklist](docs/abi-checklist.md), [releasing](docs/releasing.md),
+the [changelog](CHANGELOG.md), [contributing](CONTRIBUTING.md)
+and [security/privacy](SECURITY.md).
+
+## Validating against an installed FAME
+
+`python -m famepy.validation --native --scratch <new-dir> --report <file>` runs
+the consolidated campaign (lifecycle, databases, raw types, discovery,
+commands, bridge, frequencies, workspace, extended errors, migration, text) in
+isolated subprocesses inside a fresh run directory of a new or empty
+scratch, and writes one schema-validated report without paths or native
+text. A group passes only when every required case passed.
+`python -m famepy.benchmarks --native ...` produces the separate benchmark
+report. See [native validation](docs/native-validation.md).
+
+## Repository conventions
+
+Text files use UTF-8 and LF on Windows and Linux, except Windows batch scripts.
+Git attributes preserve database and native-library files as binary.
+Local databases, FAME binaries, environments and test reports are ignored.
+Do not commit licensed runtime files or private database contents.
+
+## Licensing
+
+Original code uses the MIT license in `LICENSE`. Code tables, ABI declarations
+and behavior adapted from FAME.jl retain its BSD 3-Clause notices in
+[licenses/FAME.jl.txt](licenses/FAME.jl.txt). Both licenses ship with the package.
+FAME itself is a separate proprietary product.

famepy-0.1.0rc1/README.md

@@ -0,0 +1,101 @@
+# FAMEPy
+
+Python bindings for the FAME CHLI library with integration for
+[TimeSeriesEconPy](https://github.com/Nic2020/TimeSeriesEconPy).
+The behavioral reference is
+[FAME.jl](https://github.com/bankofcanada/FAME.jl).
+
+**Status: first release candidate (0.1.0rc1). The operational core,
+the full TimeSeriesEconPy bridge (runtime lifecycle, local databases, raw
+object I/O, listing, commands, every reference frequency anchor, every
+value kind, workspace reads and writes, the string value text policies),
+the opt-in extended error text and the FAME-to-DataEcon migration
+workflow passed the consolidated eleven-group validation campaign on one
+Windows and one Linux host with an installed FAME, with the FAME.jl
+comparisons configured on both; the benchmark harness completed its
+scenarios on both; and a bounded read-only comparison of one small
+approved remote selection was equal through the reference and this
+package on both hosts. See [capability status](docs/capabilities.md),
+the [parity ledger](docs/parity.md) and the [changelog](CHANGELOG.md).
+These are statements about the inspected installations, not blanket
+version coverage.**
+
+Implemented: runtime lifecycle, databases (the five local access modes, work
+database, explicit posting), raw scalar and series I/O for precision,
+numeric, Boolean, date, string and namelist objects with preserved missing
+categories, wildcard listing with filters, command execution with recursive
+INPUT expansion, and the TimeSeriesEconPy bridge: values of every reference
+kind, all reference frequency anchors, workspace/mapping/multivariate
+writes and workspace reads with name transformation and per-object
+reporting, with string values as ASCII, raw bytes or strict UTF-8.
+Also: opt-in extended error text, a
+[FAME-to-DataEcon migration workflow](docs/migration.md) and a
+[benchmark harness](docs/benchmarks.md).
+Not implemented: server-connection writes (the reference's remote route is
+read-only and neither wrapper binds a named-connection write API),
+multivariate reconstruction on read (not in the reference either).
+
+Windows and Linux x86-64 are the intended runtime platforms. A separately
+installed, licensed FAME runtime is required for FAME operations; it is not
+distributed with this project. FAMEPy depends on TimeSeriesEconPy;
+TimeSeriesEconPy remains independent of FAMEPy and FAME.
+
+## Install and try
+
+From a clone, with Python 3.11 or newer:
+
+```sh
+python -m pip install .
+python -m famepy            # discovery report, exits 1 without FAME
+python -m famepy --probe    # symbol presence in a subprocess, no CHLI calls
+```
+
+The package builds without FAME, vendor headers or a C compiler and does not
+bundle FAME. Set `FAME` to the installation (required for licensing) or
+`FAMEPY_LIBRARY` to an absolute trusted library path. Load only trusted
+native libraries.
+
+```python
+import famepy
+from famepy import bridge
+from tsecon import TSeries, mm
+
+famepy.initialize()  # once per process
+bridge.write_tseries("synthetic.db", "ts", TSeries(mm(2020, 1), [1.0, 2.0]), mode="create")
+print(bridge.read_tseries("synthetic.db", "ts"))
+famepy.finalize()  # terminal; use a new process for another runtime
+```
+
+See [installation](docs/installation.md) (including offline wheelhouses),
+[usage](docs/usage.md), [contracts](docs/contracts.md),
+[capability status](docs/capabilities.md), the [parity ledger](docs/parity.md),
+[migration](docs/migration.md), [benchmarks](docs/benchmarks.md),
+[native validation](docs/native-validation.md),
+the [ABI checklist](docs/abi-checklist.md), [releasing](docs/releasing.md),
+the [changelog](CHANGELOG.md), [contributing](CONTRIBUTING.md)
+and [security/privacy](SECURITY.md).
+
+## Validating against an installed FAME
+
+`python -m famepy.validation --native --scratch <new-dir> --report <file>` runs
+the consolidated campaign (lifecycle, databases, raw types, discovery,
+commands, bridge, frequencies, workspace, extended errors, migration, text) in
+isolated subprocesses inside a fresh run directory of a new or empty
+scratch, and writes one schema-validated report without paths or native
+text. A group passes only when every required case passed.
+`python -m famepy.benchmarks --native ...` produces the separate benchmark
+report. See [native validation](docs/native-validation.md).
+
+## Repository conventions
+
+Text files use UTF-8 and LF on Windows and Linux, except Windows batch scripts.
+Git attributes preserve database and native-library files as binary.
+Local databases, FAME binaries, environments and test reports are ignored.
+Do not commit licensed runtime files or private database contents.
+
+## Licensing
+
+Original code uses the MIT license in `LICENSE`. Code tables, ABI declarations
+and behavior adapted from FAME.jl retain its BSD 3-Clause notices in
+[licenses/FAME.jl.txt](licenses/FAME.jl.txt). Both licenses ship with the package.
+FAME itself is a separate proprietary product.

famepy-0.1.0rc1/SECURITY.md

@@ -0,0 +1,20 @@
+# Security and privacy
+
+Report security issues privately to `statespaceecon@gmail.com`. Please provide
+a synthetic reproduction and omit credentials, private databases and raw logs.
+This project is in its first release-candidate cycle; no production support
+or response-time guarantee is currently offered.
+
+Importing FAMEPy does not load FAME. Library discovery uses explicit absolute
+paths or the configured FAME installation, not a current-directory/PATH search.
+Only point the optional probe at trusted libraries: loading a native library
+executes its loader code. A subprocess limits the effect of a crash; it is not
+a security sandbox.
+
+Diagnostic reports intentionally omit paths, hostnames and raw loader output.
+Review reports before sharing them. FAMEPy does not transmit reports or perform
+network requests of its own. Opening a database through a connection string
+is an explicit user operation on the caller's already configured route; the
+string is passed to the library unchanged and never appears in diagnostics,
+`repr` or error messages. No vendor runtime, credentials or databases are
+bundled.

famepy-0.1.0rc1/docs/abi-checklist.md

@@ -0,0 +1,110 @@
+# Per-function ABI checklist
+
+This table lists every native call the package and its validation runner use,
+with the candidate declaration the package binds. Before the first native
+campaign on a host, compare each row with the installed header and record
+match or difference per row (conclusions only, never header text). A mismatch
+blocks the operations that use that row, not unrelated groups.
+
+Conventions: `cfm*` functions return `void` and take a leading `int *status`
+(the binding initializes it to -1 and treats any nonzero result as failure);
+`fame_*` functions return `int` status. `int` is 32-bit signed, `index` is the
+64-bit signed `fame_index`, `range` is the 24-byte structure `{int frequency;
+index start; index end}` with offsets 0/8/16 and alignment 8. Text is passed
+as NUL-terminated `char *`; the package sends NUL-free bytes and accepts only
+ASCII `str` values in this release. "Owned" means the package allocates the
+buffer and keeps it alive for the call. Every text argument carries its
+direction: `in/out text` is text the older calling convention lets the
+library rewrite in place (trimmed, upper-cased), so the binding passes an
+owned NUL-terminated copy (`char *`), never the caller's bytes; `input text`
+is documented as input only (`const char *` in the newer convention) and is
+passed as given. Pointer widths are the same either way; the distinction
+is ownership, and it must be confirmed against the installed header per
+host like every other row rather than inferred from a passing width check.
+
+| Function | Candidate arguments (after status where applicable) | Direction and ownership | Used by |
+|---|---|---|---|
+| cfmini | none | initializes the library; requires the FAME environment variable for licensing | lifecycle |
+| cfmfin | none | finalizes; all handles become invalid | lifecycle |
+| cfmver | `float *version` | output, owned 4-byte float | lifecycle |
+| cfmfame | `char *command` | input text, NUL-terminated, at most 2**20 bytes (reference-derived bound) | commands |
+| cfmopwk | `int *key` | output database key | database |
+| cfmopdb | `int *key, char *name, int mode` | output key; in/out text (owned copy; the library trims it); mode 1-5 for this local open (6 and 7 are modes of the open on a named server connection, which is not bound, and are refused before the call; the local open is documented to return the bad-mode status for them) | database |
+| cfmpodb | `int key` | posts updates | database |
+| cfmcldb | `int key` | closes without posting | database |
+| cfmsopt | `char *option, char *value` | in/out texts (owned copies; the library trims and upper-cases both), for example `ITEM CLASS` / `ON`; frequency selections use the documented family words (`ITEM FREQUENCY MONTHLY`, ...) and index selections `ITEM INDEX CASE` / `DATE` | discovery |
+| cfmnlen | `int key, char *name, int item(-1), int *length` | in/out name (owned copy); output length excluding terminator | raw data |
+| cfmgtnl | `int key, char *name, int item(-1), char *buffer, int capacity, int *length` | in/out name (owned copy); owned writable buffer of capacity+1 bytes; the whole list comes back as members within braces separated by commas, in the library's own layout | raw data |
+| cfmwtnl | `int key, char *name, int item(-1), char *text` | in/out name and in/out list text (owned copies; the library trims and upper-cases them) | raw data |
+| cfmdlob | `int key, char *name` | in/out name (owned copy); deletes; status 13 when absent | raw data |
+| cfmnwob | `int key, char *name, int class, int frequency, int type, int basis, int observed` | in/out name (owned copy); creates an empty object | raw data |
+| cfmispm | `double value, int *type` | classification output 0-4 | raw data |
+| cfmisnm | `float value, int *type` | classification output | raw data |
+| cfmisbm | `int value, int *type` | classification output | raw data |
+| cfmissm | `char *value, int *type` | input text; classification output | raw data |
+| fame_index_to_year_period | `int frequency, index value, int *year, int *period` | outputs owned | bridge |
+| fame_year_period_to_index | `int frequency, index *out, int year, int period` | 64-bit output (the reference declares this inconsistently; the 64-bit form is used) | bridge |
+| fame_quick_info | `int key, const char *name, int *class, int *type, int *frequency, index *first, index *last` | outputs owned | all |
+| fame_init_wildcard | `int key, int *cursor, const char *pattern, int 0, const char *NULL` | output cursor key | discovery |
+| fame_get_next_wildcard | `int cursor, char *name, int *class, int *type, int *frequency, index *first, index *last, int capacity, int *length` | owned name buffer of capacity+1 bytes; 242-byte capacity; status 18 when longer, with the full length in `length` | discovery |
+| fame_free_wildcard | `int cursor` | releases the cursor; always called in `finally` | discovery |
+| fame_get_precisions | `int key, const char *name, range *range_or_NULL, double *values` | owned float64 buffer of range length (1 for scalars) | raw data |
+| fame_get_numerics | same with `float *values` | owned float32 buffer | raw data |
+| fame_get_booleans | same with `int *values` | owned int32 buffer | raw data |
+| fame_get_dates | same with `index *values` | owned int64 buffer | raw data |
+| fame_len_strings | `int key, const char *name, range *, int *lengths` | owned int32 buffer of range length | raw data |
+| fame_get_strings | `int key, const char *name, range *, char **values, const int *inlen, int *outlen(NULL)` | owned array of owned buffers sized from `fame_len_strings` plus terminators; `inlen` carries those capacities; the optional `outlen` output lengths are not requested (NULL) | raw data |
+| fame_write_precisions | `int key, const char *name, range *, const double *values` | caller's validated float64 buffer, never converted | raw data |
+| fame_write_numerics | same with `const float *` | caller's float32 buffer | raw data |
+| fame_write_booleans | same with `const int *` | caller's int32 buffer | raw data |
+| fame_write_dates | `int key, const char *name, range *, int type, const index *values` | caller's int64 buffer; `type` is the frequency code of the dates | raw data |
+| fame_write_strings | `int key, const char *name, range *, char **values` | owned array of pointers to NUL-terminated byte strings | raw data |
+| fame_date_missing_type | `index value, int *type` | classification output | raw data |
+| cfmlerr | `int *length` (older convention: leading status pointer, void return) | output length of the pending extended error text, excluding the terminator; called only by the opt-in retrieval, immediately before `cfmferr` with a buffer of that length plus one | extended errors |
+
+## Native globals
+
+| Symbol | Candidate type | Use |
+|---|---|---|
+| FAME_INDEX_NC, FAME_INDEX_NA, FAME_INDEX_ND | signed 64-bit | date/index missing sentinels; NC marks empty series ranges |
+| FPRCNC, FPRCNA, FPRCND | double | precision sentinels |
+| FNUMNC, FNUMNA, FNUMND | float | numeric sentinels |
+| FBOONC, FBOONA, FBOOND | int | Boolean sentinels |
+| FSTRNC, FSTRNA, FSTRND | `char[3]` arrays (reported on both inspected installations) | string sentinels; read as bounded arrays, never as pointers |
+
+The package reads the globals once after initialization and compares data
+against them by bit pattern. The validation campaign checks that classifier
+against the library's own `cfmis*m`/`fame_date_missing_type` results before
+the bitwise form is relied on.
+
+## Constants
+
+| Constant | Value used | Source |
+|---|---|---|
+| HSUCC | 0 | reference |
+| HBMODE | 5 | vendor status help (bad or unauthorized access mode, or database not open for the requested access); returned by the local open for modes 6 and 7 on both inspected installations |
+| HNOOBJ | 13 | reference; header-confirmed |
+| HTRUNC | 18 | header-confirmed on both inspected installations |
+| HBOPT | 67 | reference; header-confirmed |
+| HFMENV / HLICFL | 97 / 98 | vendor status help (licensing environment / license file) |
+| HFAMER | 513 | header-confirmed; extended text needs the opt-in path |
+| HNAMLEN | 242 (buffer 243) | header-confirmed v4 name capacity |
+| HNLALL | -1 | reference namelist selector |
+| class, type, frequency, basis, observed codes | as in `famepy._constants` | reference tables |
+
+Unknowns to record per host: the text encoding the library expects for
+names, paths and commands, and whether initialization has root-level
+dependency requirements beyond the library directory. The `cfmlerr` row was
+recorded as the older convention on both inspected installations and is now
+bound; its first native call happens in the `extended_errors` group. Both hosts
+confirmed that initialization happens once per process and that
+finalization is the last native call. Per host, the campaign records rather
+than assumes: the rule for missing observations at the ends of a written
+range per value type (both inspected installations dropped leading and
+trailing ND, emptied all-ND ranges and kept NC and NA endpoints); the
+layout the library uses for a whole namelist (nine bytes for a three-member
+list on both); and the counts the documented family and index words select
+on their own. Whether a given installation's header matches these
+candidate directions, and whether its release honors the documented family
+and index words, is confirmed per host by the checklist review and the
+campaign, never assumed from documentation.