review rules: the ruled checklist batch; preflight: 2x suite caps; docs: the hand-wired link set

doc/source/reference/embedding/advanced.rst

@@ -36,7 +36,8 @@ AOT pipeline overview
 1. **Compile** the ``.das`` file as normal.
 2. **Run** the AOT tool: ``daslang -aot script.das output.cpp``
 3. **Build** the generated ``.cpp`` alongside your application and
-   link ``libDaScript``.
+   link ``libDaScript`` and ``libDaScript_runtime`` (the full hand-wired
+   link set: :ref:`embedding_c_api`, section *Linking*).
 4. At runtime, ``simulate()`` detects AOT-compiled functions and uses
    them instead of the interpreter.
 

doc/source/reference/embedding/c_api.rst

@@ -38,6 +38,21 @@ but does not expose every C++ feature (e.g. class adapters, custom
 annotations).
 
 
+Linking
+=======
+
+With CMake, ``find_package(DAS REQUIRED)`` and linking
+``DAS::libDaScript`` pulls in the whole link set.  A hand-wired project
+(a plain Visual Studio project, a custom build system) must list it
+all: the daslang runtime is split out of the compiler library, so
+linking ``libDaScript`` alone fails with unresolved symbols such as
+``das::ptr_ref_count::ref_count_track`` — the runtime half defines
+them.  Link ``libDaScript``, ``libDaScript_runtime`` and
+``libUriParser``; on Windows add the system libraries ``dbghelp``,
+``ws2_32``, ``mswsock``, ``advapi32``, ``rpcrt4``.  This applies to the
+C++ API (``daScript.h``) the same way.
+
+
 Explicit-length strings
 =======================
 

install/README.md

@@ -68,6 +68,30 @@ target_link_libraries(your_app PRIVATE DAS::libDaScript)
 
 See `tutorials/integration/` for complete C and C++ embedding examples.
 
+## Embedding without CMake
+
+`DAS::libDaScript` pulls in the rest of the link set automatically; a hand-wired
+project (a plain Visual Studio project, a custom build system) must list it all.
+The daslang runtime is split out of the compiler library, so linking
+`libDaScript` alone fails with unresolved symbols such as
+`das::ptr_ref_count::ref_count_track` - the runtime half defines them.
+
+Link, from `lib/`:
+
+```
+libDaScript.lib  libDaScript_runtime.lib  libUriParser.lib
+```
+
+plus, on Windows, the system libraries:
+
+```
+dbghelp.lib  ws2_32.lib  mswsock.lib  advapi32.lib  rpcrt4.lib
+```
+
+Add `include/` to the include path and compile as C++17 or newer. On
+non-Windows platforms the same three daslang libraries apply, with the platform's
+usual thread and dl libraries in place of the Windows list.
+
 ## Tree-sitter Grammar
 
 A full tree-sitter grammar for daslang is included in `tree-sitter-daslang/`. Use it for:

modules/dasLLVM/LAWS.md

@@ -0,0 +1,14 @@
+# LAWS - ruling provenance (append-only; not a rule document)
+
+- 2026-08-27 - `REVIEW.md` - Boris kept the broad codegen-version trigger against a proposal
+  to narrow it to cached artifacts: "i'd rather bump. sometimes hard to say if it changes
+  emission or not. and cache is not my concern." He also deleted the re-pin carve-out clause
+  outright rather than trimming it: "we are saving very little time. jited dll is not exactly
+  a lot of value... world won't end." Platform clause on the module-suite rule: "yes. its a
+  good rule." Routing line for the pinned emitter hash accepted with the small/ pin-rule
+  rebind ("sure.").
+
+- 2026-08-27 - `REVIEW.md` - the `LLVM_JIT_EMITTER_HASH` routing line added earlier today
+  was removed with the pinned-value arm it routed (dragon duplicate finding; Boris: "okie").
+  The `[tune]` tail of the codegen-version rule was re-mooded from an exemption to
+  trigger-narrowing (dragon REMOVE EXCEPTIONS; wording applied verbatim).

modules/dasLLVM/REVIEW.md

@@ -7,6 +7,9 @@
   `tests/README.md` here). The suite is outside the core `tests/` sweep, so no other lane
   covers it.
 
+- **A change gated on a platform - a `get_platform_name()` test or a target-triple branch -
+  runs the module-owned suite on that platform.**
+
 - **A diff that adds work to, or moves work within, what `run_jit`
   (`daslib/llvm_jit_run.das`) executes - its own body or any callee - also prints an
   `LLVM JIT time:` number for that work: its own line, or the number of a phase that includes
@@ -15,12 +18,9 @@
 
 - **A change that can alter the machine code emitted for identical inputs bumps
   `LLVM_JIT_CODEGEN_VERSION`** (`daslib/llvm_jit_run.das`; what counts as emitting:
-  `ARCHITECTURE.md` sec.1.2). An edit inside an `EMITTER_FILES` file
-  (`tests-cpp/small/test_jit_emitter_pin.cpp`, repo root) that provably leaves the emitted
-  code identical - a comment, a nolint, a same-value rewrite - re-pins
-  `LLVM_JIT_EMITTER_HASH` only. A change that only SELECTS among existing generators'
-  `[llvm_code]` arguments - the `[tune]` stamping - needs neither: stamped arguments fold into
-  the cache keys per function.
+  `ARCHITECTURE.md` sec.1.2). Selecting among existing generators' `[llvm_code]` arguments -
+  the `[tune]` stamping - is not such a change: stamped arguments fold into the cache keys
+  per function.
 
 - **A diff that adds an environment or config input to the cache key folds it inside
   `jit_env_salt` (`daslib/llvm_jit_run.das`), never directly into either cache key - the DLL

tests-cpp/LAWS.md

@@ -0,0 +1,5 @@
+# LAWS - ruling provenance (append-only; not a rule document)
+
+- 2026-08-27 - `REVIEW.md` - Boris adopted the green-by-skip rule ("yes.") and placed it
+  tests-cpp-wide rather than small/-only ("sounds good"). He kept the CMakeLists-owning
+  stray routing line and had big/'s rule unscoped so routed strays bind ("sounds good").

tests-cpp/REVIEW.md

@@ -8,3 +8,8 @@ checklist as well as this one.**
 
 **A test that owns its own `CMakeLists.txt`, wherever the diff puts it, answers to the
 `big/` subfolder's checklist as well as this one.**
+
+**A diff adding or changing a test that returns early on a missing artifact - a file or
+binary the test needs that not every lane builds - says in the PR which lane runs it with
+that artifact present, naming the command.** A self-skipping test reports pass wherever the
+artifact is absent.

tests-cpp/big/LAWS.md

@@ -0,0 +1,5 @@
+# LAWS - ruling provenance (append-only; not a rule document)
+
+- 2026-08-27 - `REVIEW.md` - "under this folder" dropped from the ran-locally rule so a
+  CMakeLists-owning test routed here from tests-cpp/ binds; Boris: keep the routing and
+  unscope ("sounds good").

tests-cpp/big/REVIEW.md

@@ -3,7 +3,7 @@
 **Read `REVIEW_COMMON.md` (repo root) first - its contract binds this checklist.** Architecture
 doc: `skills/internal/writing_cpp_tests.md` (repo root).
 
-**A diff that touches a test under this folder whose ctest labels include `big` says in the
-PR that the test ran and passed on the author's machine, naming the command - `ctest -L big`
-or the test's own binary.** CI runs `ctest -L small` only, so no other run shows that a
-big-labelled test passes.
+**A diff that touches a test whose ctest labels include `big` says in the PR that the test
+ran and passed on the author's machine, naming the command - `ctest -L big` or the test's
+own binary.** CI runs `ctest -L small` only, so no other run shows that a big-labelled test
+passes.

tests-cpp/small/LAWS.md

@@ -0,0 +1,11 @@
+# LAWS - ruling provenance (append-only; not a rule document)
+
+- 2026-08-27 - `REVIEW.md` - pin rule rebound from "loosens or deletes" to the two concrete
+  acts (widens/removes an assertion; updates a pinned value wherever it lives), with a
+  routing line added in modules/dasLLVM/REVIEW.md, after the folder walk failed to surface
+  the checklist for an out-of-folder re-pin in PR 3889; Boris: "sure."
+
+- 2026-08-27 - `REVIEW.md` - the pinned-value arm added earlier today was removed on the
+  dragon's duplicate finding: the pin test CI-enforces that pairing both directions, and
+  Boris applied his own test-enforced-deletion logic ("okie" to the recommendation). The
+  rule keeps the widen/remove arm with the decidable wording.

tests-cpp/small/REVIEW.md

@@ -3,6 +3,7 @@
 **Read `REVIEW_COMMON.md` (repo root) first - its contract binds this checklist.** Architecture
 doc: `skills/internal/writing_cpp_tests.md` (repo root).
 
-**A diff that loosens or deletes a pin assertion also changes, in the same PR, what that
-assertion watches - the struct, offset, or file named in the pin's own assertion text.** A pin
-test (`*_pin.cpp`) asserts that a compiled-in layout, offset, or watched file set stays put.
+**A diff that widens or removes a pin assertion also changes, in the same PR, what that
+assertion watches - the struct, offset, or file named in the pin's own assertion text.** A
+pin test (`*_pin.cpp`) asserts that a compiled-in layout, offset, or watched file set stays
+put.

tests/dastest/test_preflight_config.das

@@ -83,6 +83,6 @@ def test_preflight_config(tt : T?) {
         remove(path)
         t |> success(!empty(error), "invalid config reports an error")
         t |> equal(settings.jit_threads, 0)
-        t |> equal(settings.jit_max_file_time, 60.0)
+        t |> equal(settings.jit_max_file_time, 120.0)
     }
 }

utils/internal/preflight/config.das

@@ -11,7 +11,7 @@ require daslib/toml
 
 struct public PreflightSettings {
     jit_threads : int = 0
-    jit_max_file_time : float = 60.0
+    jit_max_file_time : float = 120.0
 }
 
 //! The pure half of the untracked-files gate: repo-relative paths from

utils/internal/preflight/main.das

@@ -1119,8 +1119,10 @@ def classify_build_fail(gate, base : string; r : tuple<rc : int; out : string>;
 }
 
 def gate_tests_interp(ctx : PreflightCtx) : GateResult {
+    // 2x CI's per-file cap: the chained run executes suites while other gates load the
+    // same cores, and CI's 30 measures scheduler pressure there, not the test
     return run_test_gate("tests-interp",
-        [ctx.daslang, "dastest/dastest.das", "--", "--failures-only", "--max-file-time", "30", "--timeout", "1800", "--test", "tests"],
+        [ctx.daslang, "dastest/dastest.das", "--", "--failures-only", "--max-file-time", "60", "--timeout", "1800", "--test", "tests"],
         "interpreter suite failures")
 }
 
@@ -1194,8 +1196,9 @@ def gate_tests_aot(ctx : PreflightCtx) : GateResult {
         return GateResult(name = "tests-aot", status = GateStatus.Skip, seconds = seconds_since(t0),
             detail = "test_aot binary not found next to daslang ({test_aot})")
     }
+    // 2x CI's per-file cap - same chained-load reasoning as gate_tests_interp
     return run_test_gate("tests-aot",
-        [test_aot, "-use-aot", "dastest/dastest.das", "--", "--use-aot", "--failures-only", "--max-file-time", "30", "--timeout", "1800", "--test", "tests"],
+        [test_aot, "-use-aot", "dastest/dastest.das", "--", "--use-aot", "--failures-only", "--max-file-time", "60", "--timeout", "1800", "--test", "tests"],
         "AOT suite failures (error[50101] → skills/internal/aot_hash_desync_debugging.md)")
 }