@cella-lang/c 0.0.0-stage → 0.1.202610110557

package/CHANGES.md

@@ -0,0 +1,46 @@
+# @cella-lang/c 的變更
+
+給使用這個套件的工具（產生 `c.*` 項的翻譯器）看的 API 變更。雜湊（每個定義的 own／merkle，見 `index.json`）在不穩定期可能改變；下面列出改變的定義。
+
+## 未發佈
+
+- 寬字元：`tWChar`、`wstrArr`、`wstrLit`、`WCStr`、`wcstrOk`、`wcslen`、`wcscmp`、`wcscpy`、`wcscat`。
+- 位元欄位（**不相容**：`CType` 多一個建構子 `ctBits t w`，對 `CType` 做 match 的程式要補分支）：`bitsStore`、`bitsVal`；`sizeofV` 的 struct 佈局改以位元計算（`bitsPlace`），不含位元欄位時結果不變。
+- 三維陣列：`init3`、`arr3ToMem`、`planePtr`、`at3`、`set3`。
+- `remquoQ8`（`remquo` 的商只提供 `q % 8`，帶符號；餘數用 `remainder`）。
+
+## 2026-10-10
+
+第一版：C11 的整數。
+- 型別：`_Bool`、`char`、`signed char`、`unsigned char`、`short`、`int`、`long`、`long long` 與其無號版本（`c.tInt p` 等）；平台 `c.lp64P`（char 有號）、`c.aarch64P`（char 無號）。
+- 值 `c.Val t`、字面量 `c.litV`、轉換 `c.cast`；算術 `c.addV`／`subV`／`mulV`／`divV`／`remV`／`negV`；位元 `c.andV`／`orV`／`xorV`／`notV`；移位 `c.shlV`／`shrV`；比較 `c.ltV` 等與邏輯 `c.lnotV`／`landV`／`lorV`（結果是 int）。
+- 控制流：`c.ifC`／`whileC`／`doWhileC`／`forC`（條件是純量不等於 0）、`c.switchC`（標籤轉成提升後的型別；不重複是證明引數）；敘述沿用 `cpp.Stmt`。
+- 輸出：`c.format`、`c.printf`（`printf` 的整數子集；引數 `c.Arg` 由 `c.argV` 做預設引數提升；前置條件 `c.printfOkB`；結果 `c.Printed p`，`c.printedSt`、`c.printedN`）。
+- 陣列：`c.Arr`（`zerosA`、`uninitA`、`initA`）、`c.at`／`setAt`（前置條件 `c.Readable`／`c.InBounds`）、`lenA`、`sizeofA`；迴圈用的 `c.Full t n`（`getK`、`putK`、`fullOf`、`valuesK`、`getKAt`、`readableOfFull`、`ltPred`、`ltPredSucc`）；與 C++ 陣列的 `arrToCpp`、`atToCpp`、`setAtToCpp`。
+- 指標與記憶體（沿用 cpp 的記憶體模型）：`c.Mem`、`c.Ptr`、`c.addrOf`、`c.load`／`store`（前置條件 `c.DerefOk`／`StoreOk`）、`c.endScope`、`loadStore`；陣列退化 `c.arrToMem`、`declArrM`，指標算術 `c.ptrAdd`、`idx`（`c.PtrAddOk`）、`c.ptrDiff`、`ptrLt`、`ptrEq`（`c.SameBlock`）、`loadFullK`；`c.malloc`／`calloc`（失敗是參數）、`c.free`（`c.FreeOk`），引理 `storeDerefOk`、`mallocStoreOk`、`mallocFreeOk`；`void*`：`c.VoidPtr`、`toVoid`、`fromVoid`（`c.UncastOk`）、`voidRoundTrip`；與 C++ 的 `loadToCpp`。
+- 字串：`c.strArr`、`strArrN`、`strLit`（唯讀的字面量）；`<string.h>` 的 `c.strlen`、`strcmp`、`strncmp`、`strcpy`、`strncpy`、`strcat`、`strchr`（前置條件 `c.CStr`／`cstrOk`、`c.CStrN`／`cstrNOk`、`c.strcpyOk`、`strcatOk`、`strncpyOk`）；`printf` 的 `%s`（`c.argS`）；`<ctype.h>` 的 `c.isdigit`、`isalpha`、`isspace`、`isupper`、`islower`、`toupper`、`tolower`（`c.ctypeArg`）。
+- struct：`c.CType`、`c.Members`（`mNil`、`mCons`；成員 `ctInt`、`ctPtr`、`ctArr`、`ctStruct`）、`c.Obj`、`c.Struct`、`memberTy`、`member`、`setMember`、`scalar`、`ptrScalar`、`uninitS`、`zeroS`、`initS`（初始值 `iInt`、`iPtr`、`iList`、`iStr`）；記憶體裡的 struct：`smemNew`、`objAt`、`arrow`、`arrowSet`；`structArr`；成員陣列：`idxOkB`、`elemAt`、`setElem`、`strcpyArr`、`strlenArr`、`readArr`、`argSArr`。`c.malloc`、`c.free`、`c.FreeOk`、`c.ptrAdd`、`c.PtrAddOk`、`c.amem`、`c.aptr` 與 malloc 的引理對任意元素型別（`PtrAddOk`／`FreeOk` 的第一個索引是元素型別：整數寫 `cpp.Val t`）。
+- 陣列參數：`c.readableNB`、`writableNB`、`readK`、`writeK`、`allCells`、`cellAt`、`storeKeepsWritable`、`writableAfterStore`、`writableAfterWriteK`、`ltSelfSucc`；指標的指標：`c.loadP`；argv：`c.Argv`、`mkArgv`、`argvMem`、`argvPtrs`、`argvBase`、`argc`、`argvAt`。
+- 輸入：`c.scanf`、`c.scanfOkB`、目標 `c.STarget`（`tgtInt`、`tgtChars`）、`c.Scanned`（`scanCount`、`scanSt`、`scanVals`、`assignInt`、`scannedBytes`）、`c.bytesToArr`。
+- 多維陣列：`c.rowPtr`、`arr2ToMem`、`at2`、`set2`、`readable2`、`writable2`、`read2K`、`write2K`、`writable2AfterWrite`；泛型的 `allUpTo`、`allUpToAt`、`allUpToCong`。
+- 浮點：`c.Double`、`c.Float`、`dlit`、`flit32`、`infD`、`nanD`、`toDouble`、`toFloat`、`toInt`（`TruncOk`、`truncOk`）、`ltD`、`leD`、`eqD`；printf 的 `f F e E g G`（`c.argF`）；scanf 的 `f e g`（`c.tgtFloat`、`c.assignF`）；`<math.h>`：`sqrt`、`fabs`、`floor`、`ceil`、`round`、`trunc`、`pow`、`fmod`。
+- 函式指標：`c.FTy`、`Sig`、`SigFn`、`FnPtr`、`fnOf`、`fnNull`、`fnCast`、`fnEq`、`callable`、`call`、`call1`、`call2`、`addM`、`subM`、`mulM`；`<stdlib.h>`：`qsort`、`bsearch`（`cmpSig`、`qsortOkB`、`bsearchOkB`）、`readN`。
+- `realloc`（`ReallocOk`、`reallocOk`、`reallocB`）；`memcpy`、`memmove`、`memset`（`MemOk`、`memOk`、`memcpyB`、`memmoveB`、`memsetB`）。
+- `union`：`c.ctUnion`、`Union`、`uactive`、`uget`、`uset`、`initU`、`iField`（初始值的指定成員）、`umemNew`、`uObjAt`、`uArrow`、`uArrowSet`。
+- `<string.h>`：`strstr`、`strrchr`、`strncat`（`strncatB`）、`memcmp`（`memcmpB`）、`memchr`（`memchrB`）。
+- `scanf` 的 `%[`；`strtok`（`TokState`、`tokInit`、`TokRes`、`tokPtr`、`tokMem`、`tokState`、`strtokM`）。
+- 成員陣列的字串函式（值版本）：`strcmpArr`、`strcmpArrLit`、`strcatArr`、`strcpyArrMem`、`strcpyMemArr`。
+- `sprintf`、`snprintf`（`sprintfB`、`snprintfB`、`Written`、`writtenMem`、`writtenN`）、`sscanf`；`Arg` 的 `argStr` 多一個欄位記來源的指標（`argS`、`argSArr` 的用法不變）。
+- 字元與行的 I/O：`putchar`、`puts`、`getchar`（`GotChar`、`gotCh`、`gotSt`）、`fgets`（`fgetsB`、`Fgot`、`fgotPtr`、`fgotMem`、`fgotSt`）。
+- `<stdlib.h>`：`atoi`、`strtol`（`Strtol`、`strtolVal`、`strtolEnd`、`baseOkB`、`parseNum`）、`abs`、`labs`。
+- 可變長度陣列：`vla`、`vla2`、`vlaLen`、`vlaOkB`。
+- `const` 物件：`constArrToMem`、`constAddrOf`。
+- `rand`／`srand`：`RandEnv`、`randEnv`、`RandSt`、`randInit`、`srand`、`rand`、`RandRes`、`randVal`、`randSt2`、`randNat`、`randMaxV`、`randMaxAtLeast`、`randBelow`。
+- 檔案 I/O：`FState`、`fsInit`、`FH`、`fhIsNull`、`fopen`（`Opened`、`openedH`、`openedSt`）、`fclose`、`fprintf`（`FPrinted`）、`fputs`、`fscanf`（`FScanned`）、`fgetsF`（`FFgot`）、`fgetc`、`fileContent`；`fgets` 的核心抽成 `fgetsCore`。
+- `goto` 與標籤：`Jump`、`gotoS`、`retJ`、`withLabels`。
+- `<math.h>` 的其餘：`exp`、`log`、`log10`、`log2`、`exp2`、`sin`、`cos`、`tan`、`asin`、`acos`、`atan`、`atan2`、`expm1`、`log1p`、`sinh`、`cosh`、`tanh`、`asinh`、`acosh`、`atanh`、`cbrt`、`hypot`（沿用 cpp 的正確捨入模型）；`fmin`、`fmax`、`fdim`、`remainder`、`ldexp`、`frexpM`、`frexpE`、`isnan`、`isinf`、`isfinite`、`signbit`、`fma`、`nextafter`、`modfInt`、`modfFrac`、`copysign`、`scalbn`、`logb`、`ilogb`。
+- `<time.h>`：`timeT`、`TimeEnv`（`timeEnv`）、`time`、`srandSeed`、`srandTime`、`difftime`。
+- 跟著 cpp：串流狀態多了 `err` 欄位（`cpp.mkIOS` 多一個參數），C 的輸入函式照樣保留它。
+- 長度修飾 `z`、`j`、`t`（printf 與 scanf；`Len` 多 `lenZ`、`lenJ`、`lenT`）。
+- `sizeof`：`layout`、`sizeofN`、`sizeofV`、`sizeofDouble`、`sizeofFloat`；`strspn`、`strcspn`、`strpbrk`。
+- 依賴 `@cella-lang/cpp`（C 家族共用的整數核心、敘述與輸出狀態）。

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,7 @@
+Cella
+Copyright 2026 SungYu Chang
+
+This product includes software developed by SungYu Chang
+(the Cella proof language: checker, standard library, and playground).
+
+Licensed under the Apache License, Version 2.0 (see LICENSE).

package/README.md

@@ -1,3 +1,206 @@
-# Temporary Holding Version
+# @cella-lang/c
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+C11 integer types for the [Cella](https://www.npmjs.com/package/cella-lang) proof checker, as a compiled module pack.
+
+C's integers are not mathematical integers: widths depend on the platform, signed overflow, division by zero and
+out-of-range shifts are undefined behaviour, and `char` may be signed or unsigned. This library defines the C semantics directly:
+
+- `c.Val t` — a C value of integer type `t` (`c.tInt p`, `c.tUChar`, `c.tBool`, …): an integer plus a proof that it lies in the range of `t`;
+- integer promotions and the usual arithmetic conversions compute the result type (`c.addV p a b ok : c.Val (cpp.common p s t)`);
+- every operation that can be undefined takes the condition as an argument — for concrete values `(cpp.inT refl)` (signed: no overflow),
+  `unit` (unsigned: wraps modulo 2^N), `refl` (divisor not zero), `(c.shlOk refl)` / `(c.shrOk refl)` (shift amount and, for signed `<<`,
+  a result that fits the result type);
+- comparisons and logical operators yield an `int` 0 or 1, as in C;
+- conversions: to `_Bool` is "not zero", to unsigned is modulo 2^N, to signed wraps (implementation-defined; as clang);
+- platforms: `c.lp64P` (x86-64 Linux/macOS, `char` signed), `c.aarch64P` (AArch64 Linux, `char` unsigned).
+
+Statements reuse the language-neutral statement model of `@cella-lang/cpp` (`cpp.Stmt`, `cpp.seq`, `cpp.breakS`, `cpp.continueS`,
+`cpp.returnS`); C adds what differs:
+
+- `c.ifC`, `c.whileC`, `c.doWhileC`, `c.forC` — the condition is a C scalar, true when it is not zero; loops take fuel and end in
+  `cpp.outOfFuel` rather than assuming termination;
+- `c.switchC p e blocks refl` — the controlling expression is promoted, `case` labels are converted to the promoted type before comparing;
+  the last argument proves the converted labels are distinct and there is at most one `default` (in `unsigned int`, `-1` and `4294967295`
+  are the same label, so `refl` fails).
+
+Output: `c.format p fmt args refl : String` and `c.printf p fmt args refl st` (appends to the stream state shared with the C++ model and
+returns the number of characters as an `int`), the integer subset of `printf`: `%d %i %u %o %x %X %c %%`, flags `- + space # 0`, field width
+and precision (digits or `*`), length modifiers `hh h l ll`. Arguments go through the default argument promotions (`c.argV p x`). Undefined
+behaviour is the precondition `c.printfOkB p fmt args ≡ true`: a malformed or unknown conversion, too few arguments, an argument whose type
+does not match the conversion (a signed/unsigned counterpart is allowed only when the value fits both), `#` with `d i u c`, `0` or a
+precision with `c`, anything inside `%%`.
+
+```cella
+import c
+def p : cpp.Platform := c.lp64P
+def n (v : Int) (ok : cpp.inTB (c.tInt p) v ≡ true) : c.Arg := c.argV p (c.litV (c.tInt p) v ok)
+def s : c.format p "%5d|%-+4d|%#x" [n (pos 42) refl, n (pos 7) refl, n (pos 255) refl] refl ≡ "   42|+7  |0xff" := refl   -- accept
+def t : String := c.format p "%d %d" [n (pos 1) refl] refl                                                                   -- reject: too few arguments
+```
+
+Arrays: `c.Arr t` (fixed length; elements may be uninitialized). `c.zerosA t n` (`static`, `= {0}`), `c.uninitA t n` (automatic),
+`c.initA t n [x0, …] refl` (`{…}`; missing elements are zero, too many initializers do not check). `c.at a i (c.readable refl)` reads an
+element that is in bounds and initialized, `c.setAt a i x (c.inBounds refl)` writes in bounds; the index is a C value of any integer
+type. `c.sizeofA p a` is `N * sizeof(T)` as a `size_t`. For loops, `c.Full t n` carries its length and "all initialized" in its type:
+`c.getK f k h` / `c.putK f k h x` take the `h : k < n` given by a counting loop, so the body needs no separate proof of bounds.
+
+```cella
+import c
+def p : cpp.Platform := c.lp64P
+def a : c.Arr (c.tInt p) := c.initA (c.tInt p) 5 [c.litV (c.tInt p) (pos 1) refl, c.litV (c.tInt p) (pos 2) refl] refl
+def s : c.get (c.at a (c.litV (c.tInt p) (pos 3) refl) (c.readable refl)) ≡ pos 0 := refl        -- accept: a[3] is zero
+def t : c.Val (c.tInt p) := c.at a (c.litV (c.tInt p) (pos 5) refl) (c.readable refl)             -- reject: a[5] is out of bounds
+```
+
+Pointers and memory reuse the provenance memory model of `@cella-lang/cpp`: `c.Mem t` and `c.Ptr` (a pointer remembers its allocation
+block and offset). `c.addrOf m x` is `&x`, `c.load m q (c.derefOk refl)` is `*q` (not NULL, block alive, in bounds, initialized),
+`c.store m q v (c.storeOk refl)` is `*q = v`. Arrays decay with `c.arrToMem`; `c.ptrAdd` / `c.idx` require the result to stay inside the
+array or one past its end, `c.ptrDiff` / `c.ptrLt` require both pointers to be in the same array. `c.malloc m n fails` takes whether the
+allocation fails as a parameter (the environment's choice; failure returns NULL), so a verdict must hold for both outcomes — dereferencing
+without a NULL check does not prove. `c.calloc` zero-fills; `c.free` requires NULL or a live block from `malloc`, pointed at its start.
+`c.toVoid` / `c.fromVoid` convert through `void*`, back to the original type only.
+
+```cella
+import c
+def t : cpp.IType := cpp.tInt cpp.lp64P
+def r : c.Allocated t := c.addrOf (c.memNew t) (c.litV t (pos 5) refl)                                     -- int x = 5; int *q = &x;
+def s : c.get (c.load (c.amem r) (c.aptr r) (c.derefOk refl)) ≡ pos 5 := refl                             -- accept: *q is 5
+def u : c.Val t := c.load (c.memNew t) c.nullP (c.derefOk refl)                                            -- reject: *NULL
+```
+
+Strings are NUL-terminated `char` arrays in that memory. `c.strArr p m "abc"` is `char s[] = "abc"`, `c.strArrN p m 10 "abc" refl` is
+`char s[10] = "abc"` (zero-filled; exactly N bytes leaves no NUL), and `c.strLit p m "abc"` is `char *s = "abc"` — a read-only allocation, so
+writing through it does not prove. `<string.h>`: `c.strlen`, `c.strcmp`, `c.strncmp`, `c.strcpy`, `c.strncpy` (writes no NUL when the source is
+not shorter than n), `c.strcat`, `c.strchr`; their preconditions are `c.cstrOk refl` (a NUL is reachable), `c.cstrNOk refl` (the first n bytes
+or a NUL), and `c.strcpyOk refl refl` etc. (the destination is writable and large enough, no overlap). `printf` takes strings with
+`c.argS m q` for `%s` (width, `-`, precision; with a precision the array needs no NUL). `<ctype.h>`: `c.isdigit`, `isalpha`, `isspace`,
+`isupper`, `islower`, `toupper`, `tolower`, whose argument must be an `unsigned char` value or `EOF` (`c.ctypeArg refl`).
+
+```cella
+import c
+def p : cpp.Platform := c.lp64P
+def C : cpp.IType := c.tChar p
+def r : c.Allocated C := c.strLit p (c.memNew C) "hello"
+def s : c.format p "[%-7s]" [c.argS (c.amem r) (c.aptr r)] refl ≡ "[hello  ]" := refl                    -- accept
+def t : c.Mem C := c.store (c.amem r) (c.aptr r) (c.litV C (pos 72) refl) (c.storeOk refl)                 -- reject: writes a string literal
+```
+
+Structs are described by their members, `c.mCons "x" (c.ctInt t) (c.mCons "next" c.ctPtr c.mNil)`, and a struct value has type
+`c.Struct ms`; every scalar member may be uninitialized on its own. `c.initS ms [c.iInt x, …] refl` is an initializer list (missing members
+are zero), `c.member ms "x" s` / `c.setMember ms "x" v s` access by name, and `c.scalar … refl` reads a member that has been initialized.
+In memory, a struct type gets its own `cpp.GMem (c.Struct ms)`: `c.malloc` and `c.free` work for any element type, `c.arrow ms "v" m q` is
+`q->v`, and `c.arrowSet ms "v" x m q (cpp.storeOk refl)` is `q->v = x` — a `malloc`ed struct is initialized member by member, so this
+needs no other member to be initialized. Arrays of structs: `c.structArr`; member arrays and strings are handled as values (`c.setElem`,
+`c.strcpyArr`, `c.strcmpArr`, `c.strcatArr`, `c.strcpyArrMem` / `c.strcpyMemArr` to and from memory, `c.argSArr` for `%s`). A linked list whose every `malloc` may fail is in `tests/t_linked_list.cella`.
+
+```cella
+import c
+def I : cpp.IType := c.tInt c.lp64P
+def Point : c.Members := c.mCons "x" (c.ctInt I) (c.mCons "y" (c.ctInt I) c.mNil)
+def p : c.Struct Point := c.initS Point [c.iInt (c.litV I (pos 1) refl)] refl
+def y : c.get (c.scalar (c.member Point "y" p) refl) ≡ pos 0 := refl                                    -- accept: y is zero-filled
+def u : c.Val I := c.scalar (c.member Point "y" (c.uninitS Point)) refl                                  -- reject: y is uninitialized
+```
+
+Array parameters are pointers, so a function does not know the length: `int sum(int a[], int n)` takes the precondition
+`c.readableNB m a n ≡ true` ("n cells after a are readable"), and `c.readK m a n ok k h` reads `a[k]` for `h : k < n` — the function is
+checked once for any memory and pointer, and a caller with a concrete array proves the precondition by `refl`. Writing is the same with
+`c.writableNB` / `c.writeK`, and `c.writableAfterWriteK` keeps the precondition through a loop. Pointers can be stored in memory
+(`cpp.GMem c.Ptr`, `c.loadP` for `*pp`), and `c.mkArgv p ["prog", "x"]` builds `argv` (NUL-terminated strings, a NULL at `argv[argc]`).
+
+Input: `c.scanf p "%d %s" [c.tgtInt t, c.tgtChars 8] st refl` reads from the input state shared with the C++ model (`cpp.ios "12 abc"`)
+and returns what was read: `c.scanCount p r` (the number of assignments, or EOF), `c.assignInt r k t old` (the k-th assigned value, or the
+old value when the conversion failed), `c.scannedBytes r k` and `c.scanSt r` (the rest of the input). The precondition rejects a target of the
+wrong type, a result that does not fit (`%d` reading `99999999999`), and a `%s` that does not fit its array.
+
+Multi-dimensional arrays: `c.arr2ToMem m R C inits refl` declares `T a[R][C]` (nested or flat initializers), and `c.at2 m a R C i j hi hj ok`
+reads `a[i][j]` with the bounds checked per dimension — `a[0][C]` is out of bounds for the inner array even though it is inside the object.
+A function taking `int a[][C]` gets `c.readable2 m a n C ≡ true` and reads with `c.read2K`.
+
+Floating point: `c.Double` and `c.Float` are IEEE 754 binary64 and binary32 (shared with the C++ model). `c.dlit m e` is the literal
+m × 10^e; `c.toInt t x (c.truncOk refl)` truncates toward zero with the result required to fit; division needs a nonzero divisor.
+`printf` takes doubles through `c.argF` (`%f %e %g` with flags, width and precision), `scanf` reads them into `c.tgtFloat`, and
+`c.sqrt`, `floor`, `ceil`, `round`, `trunc`, `pow`, `fmod`, `fabs`, `exp`, `log`, `log10`, `log2`, `exp2`, `sin`, `cos`, `tan`, `asin`, `acos`,
+`atan`, `atan2`, `expm1`, `log1p`, `sinh`, `cosh`, `tanh`, `asinh`, `acosh`, `atanh`, `cbrt`, `hypot` follow `<math.h>` with correctly rounded results (the standard does not require a correctly rounded libm).
+
+Function pointers: a signature `c.sig [c.fInt t, …] r` describes the type; C functions return `Maybe` (`nothing` is undefined
+behavior in that call, e.g. `c.addM` overflowing). `c.fnOf "f" s f` takes `&f`, `c.fnCast` converts (the pointer remembers the
+function it points to), and `c.call2 s p x y refl` calls through it — the proof says the pointer is not NULL, its type matches the
+function, and the call is defined. `c.qsort` and `c.bsearch` take a comparator `c.FnPtr (c.cmpSig p t)` that must be a consistent
+total order on the array.
+
+Memory functions: `c.realloc m q n fails ok` keeps the first min(old, n) cells and ends the old allocation (failure is a
+parameter, as with `malloc`; `n = 0` is not in the subset). `c.memcpy`, `c.memmove` and `c.memset` count elements, not bytes;
+`memcpy` requires the two ranges not to overlap.
+
+Unions: `c.ctUnion ms` uses the same member list as a struct. A `c.Union ms` remembers which member was written last;
+`c.uset` writes a member and `c.uget ms k u refl` reads it only if it is that member (reading another member reinterprets
+bytes in C, which the model does not represent). `c.initU ms [c.iField "k" v] refl` is `= {.k = v}`.
+
+More of `<string.h>`: `c.strstr`, `c.strrchr`, `c.strncat` (reads at most n bytes of the source), and `c.memcmp` / `c.memchr`
+on character arrays (on `int` arrays `memcmp` compares bytes in memory order, so its sign depends on the representation).
+
+Tokens and lines: `scanf` supports `%[...]` (scan sets, `^` for the complement); `c.strtok` makes the hidden state of
+`strtok` an explicit value — pass `c.tokInit` the first time and the previous `c.tokState` (with a NULL string) afterwards.
+
+Formatting into memory: `c.sprintf` and `c.snprintf` write `c.format`'s output into a buffer (the output must fit and must not
+overlap a `%s` argument; `snprintf` truncates to n − 1 bytes and returns the full length); `c.sscanf` reads from a string in memory.
+
+Character and line I/O: `c.putchar`, `c.puts`, `c.getchar` (EOF at the end of input) and `c.fgets` (at most n − 1 bytes,
+keeping the newline) share the `cpp.IOS` state with `printf` and `scanf`.
+
+Number conversions: `c.atoi` (overflow is undefined, so the result must fit), `c.strtol` (base 0 or 2–36, clamps to
+`LONG_MAX` / `LONG_MIN` and reports where it stopped), `c.abs` and `c.labs` (the most negative value is excluded).
+
+Variable length arrays: `c.vla t m n ok` declares `T a[n]` with a run-time length that must be positive, and `c.vla2` declares
+`T a[r][c]`; the elements start uninitialized.
+
+Const objects: `c.constArrToMem` and `c.constAddrOf` allocate read-only storage, so writing through a pointer that cast the
+`const` away (or passing the array to a function that writes it) is rejected.
+
+Random numbers: the sequence of `rand` is implementation-defined, so it is a parameter (`c.RandEnv`) and a verdict holds for
+every environment — e.g. `rand() % 6 + 1` is between 1 and 6 for any `RAND_MAX` ≥ 32767 and any sequence.
+
+Files: `c.FState` is the file system (an environment given by `c.fsInit`) plus the open files. `c.fopen` takes a `fails`
+parameter like `malloc`, so the NULL check is required; `c.fscanf`, `c.fgetsF`, `c.fgetc`, `c.fprintf`, `c.fputs` and
+`c.fclose` require the handle to be open in a suitable mode.
+
+`goto`: a function body is a table of labeled blocks (`c.withLabels`); `c.gotoS "l"` leaves nested loops and ifs like a
+`return` and resumes at block `l`, and `c.retJ` is the real return. Labels live at the top level of the body.
+
+Length modifiers `z`, `j` and `t` (`printf("%zu", strlen(s))`) use the LP64 types: `size_t` is `unsigned long`, `ptrdiff_t` and
+`intmax_t` are `long`.
+
+`sizeof`: `c.sizeofV pl ct` computes sizes from a type descriptor (struct padding follows the LP64 ABI, which is
+implementation-defined); `c.strspn`, `c.strcspn` and `c.strpbrk` complete the common `<string.h>` functions.
+
+The integer core shared by the C family (type descriptors, platforms, promotions) comes from `@cella-lang/cpp`; C's value type is its own,
+and its relation to C++'s is a proved path on the fragment where both languages agree.
+
+```cella
+import c
+def p : cpp.Platform := c.lp64P
+def x : c.Val (c.tInt p) := c.addV p (c.litV (c.tInt p) (pos 2) refl) (c.litV (c.tInt p) (pos 3) refl) (cpp.inT refl)   -- accept
+def y : c.Val (c.tInt p) := c.shlV p (c.litV (c.tInt p) (pos 1) refl) (c.litV (c.tInt p) (pos 31) refl) (c.shlOk refl)   -- reject: 1 << 31 does not fit int
+```
+
+## Loading
+
+The pack only loads into the `cella-lang` build named by `index.json` (`checkerHash`, `cbfVersion`), on top of the packages it depends on
+(`index.requires.packages`, here `@cella-lang/cpp`); the `peerDependencies` entries pin those versions.
+
+```js
+import init, { init_stdlib_cached, load_module_pack, load_library_pack, check } from 'cella-lang';
+import assets from 'cella-lang/assets';
+// 1. the standard modules it and its dependencies need: index.requires["cella-lang"].modules
+for (const m of JSON.parse(index).requires['cella-lang'].modules) load_module_pack(await bytes(assets.module(m)));
+// 2. the packages it depends on, in order: index.requires.packages (each with its own index.json)
+load_library_pack(cppIndex, 'cpp', await bytes(cppPackUrl));
+// 3. the library itself
+const r = JSON.parse(load_library_pack(index, 'c', await bytes(new URL('./c.cell', libUrl))));
+if (!r.ok) throw new Error(r.error);
+```
+
+## Per-definition hashes
+
+`index.json` lists, for every definition, `own` (its own content) and `merkle` (its content plus everything it depends on).