Merge main

packages/compiler/src/backend/llvm/emitter.ts

@@ -2190,6 +2190,12 @@ export class LlEmitter {
       if (this.mod.lib.exports.some((e) => e.returns === "bytes")) {
         this.declare(`declare void @scr_library_bytes_out(ptr, ptr, ptr)`);
       }
+      if (this.mod.lib.exports.some((e) => e.params.includes("cstring"))) {
+        this.declare(`declare ptr @scr_library_cstr_in(ptr, ptr)`);
+      }
+      if (this.mod.lib.exports.some((e) => e.returns === "cstring")) {
+        this.declare(`declare ptr @scr_library_cstr_out(ptr)`);
+      }
     }
     // Helpers assemble BEFORE the declaration table flushes (they add
     // write/abort declarations).
@@ -2966,6 +2972,15 @@ export class LlEmitter {
           ``,
         );
       }
+      if (e.inboundCstringTrap !== undefined) {
+        // The cstring-in helper's host-contract trap message (a NULL
+        // `const char *`): same assembled structured form and SC4012 code.
+        const trapBytes = Buffer.byteLength(e.inboundCstringTrap, "utf8");
+        out.push(
+          `@sc_lib_cstr_trap_${e.symbol} = internal constant [${trapBytes + 1} x i8] c"${llStrBytes(e.inboundCstringTrap)}"`,
+          ``,
+        );
+      }
       e.params.forEach((cls, i) => {
         switch (cls) {
           case "f64":
@@ -3023,6 +3038,13 @@ export class LlEmitter {
             );
             args.push(`ptr %c${i}`);
             break;
+          case "cstring":
+            params.push(`ptr %a${i}`);
+            body.push(
+              `  %c${i} = call ptr @scr_library_cstr_in(ptr %a${i}, ptr @sc_lib_cstr_trap_${e.symbol})`,
+            );
+            args.push(`ptr %c${i}`);
+            break;
         }
       });
       if (e.returns === "string" || e.returns === "bytes") {
@@ -3087,6 +3109,16 @@ export class LlEmitter {
             `  ret void`,
           );
           break;
+        case "cstring":
+          // The result's arena copy, returned as `const char *`.
+          retType = "ptr";
+          body.push(
+            `  %r = call ptr ${target}(${callArgs})`,
+            `  call void @scr_library_check_exc()`,
+            `  %z = call ptr @scr_library_cstr_out(ptr %r)`,
+            `  ret ptr %z`,
+          );
+          break;
       }
       out.push(
         `define ${retType} @${e.symbol}(${params.join(", ")}) ${FN_ATTRS} { ; library export ${e.fnName}`,

packages/compiler/src/backend/llvm/expr-calls.ts

@@ -333,6 +333,16 @@ export function emitCallExpr(
               natArgs.push(`ptr ${data}`, `${host.sizeType} ${len}`);
               break;
             }
+            case "cstring": {
+              // The string's own NUL-terminated data, after the check that
+              // it holds no U+0000 (a C string cannot carry one).
+              host.declare(`declare ptr @scr_library_cstr_arg(ptr)`);
+              const data = B.tmp();
+              B.line(`${data} = call ptr @scr_library_cstr_arg(ptr ${arg.name})`);
+              natTypes.push("ptr");
+              natArgs.push(`ptr ${data}`);
+              break;
+            }
             case "bytes": {
               const lenPtr = B.tmp();
               const len = B.tmp();

packages/compiler/src/backend/llvm/lib-shared.ts

@@ -188,6 +188,7 @@ export const LIB_FN_SYMS: Record<string, string> = {
   "os.uptime": "scr_os_uptime",
   "os.loadavg": "scr_os_loadavg",
   "os.getPriority": "scr_os_get_priority",
+  "os.setPriority": "scr_os_set_priority",
   "os.cpusTake": "scr_os_cpus_take",
   "os.cpusModel": "scr_os_cpus_model",
   "os.cpusField": "scr_os_cpus_field",
@@ -477,6 +478,7 @@ export const LIB_FN_SYMS: Record<string, string> = {
   "strdec.write": "scr_strdec_write",
   "strdec.next": "scr_strdec_next",
   "strdec.end": "scr_strdec_end",
+  "strdec.encoding": "scr_strdec_encoding",
   "stats.isFile": "scr_stats_is_file",
   "stats.isDirectory": "scr_stats_is_dir",
   "stats.isSymbolicLink": "scr_stats_is_symlink",

packages/compiler/src/backend/target-diagnostics.ts

@@ -129,6 +129,7 @@ const WASI_UNAVAILABLE_HOST_FACTS: ReadonlyMap<string, string> = new Map([
   ["os.loadavg", "system load averages (WASI Preview 1 has no load API)"],
   ["os.uptime", "system uptime (WASI Preview 1 has no boot-time API)"],
   ["os.getPriority", "process scheduling priority (WASI Preview 1 has no priority API)"],
+  ["os.setPriority", "process scheduling priority (WASI Preview 1 has no priority API)"],
   ["process.memoryUsageTake", "process memory statistics (WASI Preview 1 has no memory API)"],
   ["process.rss", "process memory statistics (WASI Preview 1 has no memory API)"],
   ["process.ppid", "the parent process id (WASI Preview 1 has no process API)"],

packages/compiler/src/frontend/lowering/builtins/module-calls.ts

@@ -40,6 +40,7 @@ import { lowerForkCall } from "./child-process.js";
 import {
   lowerOsCpusCall,
   lowerOsGetPriorityCall,
+  lowerOsSetPriorityCall,
   lowerOsNetworkInterfacesCall,
   lowerOsUserInfoCall,
   lowerPathFormatCall,
@@ -163,6 +164,9 @@ export function lowerBuiltinModuleCall(
   if (bi.module === "os" && bi.member === "cpus") {
     return lowerOsCpusCall(lowerer, expr, loc);
   }
+  if (bi.module === "os" && bi.member === "setPriority") {
+    return lowerOsSetPriorityCall(lowerer, expr, loc);
+  }
   if (bi.module === "os" && bi.member === "getPriority") {
     return lowerOsGetPriorityCall(lowerer, expr, loc);
   }

packages/compiler/src/frontend/lowering/builtins/operating-system.ts

@@ -10,6 +10,7 @@ import {
   STRING,
   type SrcLoc,
   UNDEFINED_T,
+  VOID,
   arrayOf,
   typeKey,
 } from "../../../ir/ir.js";
@@ -511,6 +512,29 @@ export function lowerPathFormatCall(
   return { kind: "call", callee: helper, args: [value], type: STRING, loc };
 }
 
+/** `os.setPriority([pid, ]priority)` — the one-argument form is pid 0
+ * (Node's `if (priority === undefined) { priority = pid; pid = 0; }`);
+ * the runtime validates both. */
+export function lowerOsSetPriorityCall(
+  lowerer: Lowerer,
+  call: ts.CallExpression,
+  loc: SrcLoc,
+): IrExpr {
+  const args = call.arguments;
+  if (args.length < 1 || args.length > 2 || args.some(ts.isSpreadElement)) {
+    lowerer.noLowering(
+      "setPriority with these arguments",
+      call,
+      "setPriority(priority) or setPriority(pid, priority) takes numbers",
+    );
+  }
+  const [pid, priority] =
+    args.length === 1
+      ? [numLit(0, loc), lowerer.lowerExprExpecting(args[0]!, F64)]
+      : [lowerer.lowerExprExpecting(args[0]!, F64), lowerer.lowerExprExpecting(args[1]!, F64)];
+  return { kind: "libCall", fn: "os.setPriority", args: [pid, priority], type: VOID, loc };
+}
+
 /** `os.getPriority(pid?)` — an omitted or undefined pid is 0 (Node's
  * `if (pid === undefined) pid = 0`); the runtime validates the rest. */
 export function lowerOsGetPriorityCall(

packages/compiler/src/frontend/lowering/builtins/url.ts

@@ -26,6 +26,7 @@ import {
 } from "../../../ir/ir.js";
 import { optionalStringTags } from "./arguments.js";
 import { type BuiltinModuleFn } from "../surfaces.js";
+import { lowerDynDispatchMethodCall } from "../lower-calls.js";
 
 /** URL component assignment captures its receiver and RHS once, and yields
  * the original RHS after the setter performs string conversion. */
@@ -255,10 +256,12 @@ export function lowerSearchParamsNew(
     return { kind: "libCall", fn: "sp.fromPairs", args: [init], type: SEARCH_PARAMS_T, loc };
   }
   if (init.type.kind === "array" && init.type.elem.kind === "record") {
+    const pairs = searchParamsFromTuples(lowerer, init, init.type.elem, loc);
+    if (pairs) return pairs;
     lowerer.unsupported(
       "SC1090",
       arg,
-      "URLSearchParams from tuple-typed pairs (type the pairs as string[][] — the tuple rows have a different layout)",
+      "URLSearchParams from tuple rows other than [string, string] (type the pairs as [string, string][] or string[][])",
     );
   }
   lowerer.unsupported(
@@ -268,6 +271,97 @@ export function lowerSearchParamsNew(
   );
 }
 
+/** `new URLSearchParams(pairs)` over a `[string, string][]` (an
+ * Object.entries result, for example): a helper per tuple shape appends
+ * each pair's name and value in array order. Null for other row types. */
+function searchParamsFromTuples(
+  lowerer: Lowerer,
+  init: IrExpr,
+  row: IrType & { kind: "record" },
+  loc: SrcLoc,
+): IrExpr | null {
+  const shape = lowerer.shapes.get(row.shapeId);
+  if (
+    !shape?.tuple ||
+    shape.fields.length !== 2 ||
+    !shape.fields.every(
+      (field) => (field.name === "0" || field.name === "1") && field.type.kind === "string",
+    )
+  )
+    return null;
+  const key = `sp.fromTuples:${row.shapeId}`;
+  let helper = lowerer.valueHelpers.get(key);
+  if (!helper) {
+    helper = `%sp.fromTuples.${lowerer.valueHelpers.size}`;
+    lowerer.valueHelpers.set(key, helper);
+    const pairsT = init.type;
+    const sp = (): IrExpr => varRef("sp.0", SEARCH_PARAMS_T, loc);
+    const pair = (): IrExpr => varRef("pair.0", row, loc);
+    const field = (name: "0" | "1"): IrExpr => ({
+      kind: "recordGet",
+      obj: pair(),
+      shapeId: row.shapeId,
+      field: name,
+      type: STRING,
+      loc,
+    });
+    const body: IrStmt[] = [
+      {
+        kind: "varDecl",
+        localId: "sp.0",
+        init: { kind: "libCall", fn: "sp.new", args: [], type: SEARCH_PARAMS_T, loc },
+        loc,
+      },
+      countedFor(
+        loc,
+        {
+          kind: "arrIntrinsic",
+          method: "length",
+          receiver: varRef("pairs.0", pairsT, loc),
+          args: [],
+          type: F64,
+          loc,
+        },
+        (index) => [
+          {
+            kind: "varDecl",
+            localId: "pair.0",
+            init: { kind: "arrayGet", arr: varRef("pairs.0", pairsT, loc), index, type: row, loc },
+            loc,
+          },
+          {
+            kind: "exprStmt",
+            expr: {
+              kind: "libCall",
+              fn: "sp.append",
+              args: [sp(), field("0"), field("1")],
+              type: VOID,
+              loc,
+            },
+            loc,
+          },
+        ],
+      ),
+      { kind: "return", value: sp(), loc },
+    ];
+    const fn: IrFunction = {
+      name: helper,
+      params: [{ localId: "pairs.0", name: "pairs", type: pairsT }],
+      returnType: SEARCH_PARAMS_T,
+      locals: [
+        { id: "pairs.0", name: "pairs", type: pairsT, mutable: false },
+        { id: "sp.0", name: "sp", type: SEARCH_PARAMS_T, mutable: false },
+        { id: "i.0", name: "i", type: F64, mutable: true },
+        { id: "pair.0", name: "pair", type: row, mutable: false },
+      ],
+      body,
+      loc,
+    };
+    lowerer.liftedFns.push(fn);
+  }
+  return { kind: "call", callee: helper, args: [init], type: SEARCH_PARAMS_T, loc };
+}
+
 function lowerOptionalStringSearchParams(
   lowerer: Lowerer,
   init: IrExpr,
@@ -534,12 +628,14 @@ export function lowerSearchParamsMethodCall(
   if (name === "forEach" && args.length === 1) {
     return lowerSpForEachCall(lowerer, call, access);
   }
-  if (name === "keys" || name === "values" || name === "entries") {
-    lowerer.unsupported(
-      "SC1090",
-      call,
-      `URLSearchParams iterator objects outside a for-of head (write \`for (const x of sp.${name}())\` directly)`,
-    );
+  if ((name === "keys" || name === "values" || name === "entries") && args.length === 0) {
+    // Outside a for-of head the iterator is a live object: the checked-
+    // dynamic view's iterator walks the pair list by index
+    // (scr_native_sp_step), so entries appended after it was created are
+    // visited, as in Node.
+    const boxed = lowerer.coerceInto(access.expression, lowerer.lowerExpr(access.expression), DYN);
+    const iterator = lowerDynDispatchMethodCall(lowerer, call, access, boxed, false);
+    if (iterator) return iterator;
   }
   lowerer.noLowering(
     `URLSearchParams.${name}`,
@@ -751,3 +847,21 @@ export function lowerLegacyUrlCall(
   }
   return { kind: "libCall", fn: fn.fn, args, type: fn.result, loc };
 }
+
+/** A URLSearchParams value, or a keys()/values()/entries() call on one: an
+ * iterable whose checked-dynamic view walks the live pair list. */
+export function isSearchParamsIterable(lowerer: Lowerer, node: ts.Expression): boolean {
+  while (ts.isParenthesizedExpression(node)) node = node.expression;
+  if (lowerer.mapTypeOf(lowerer.typeOf(node))?.kind === "searchParams") return true;
+  if (
+    !ts.isCallExpression(node) ||
+    node.arguments.length !== 0 ||
+    !ts.isPropertyAccessExpression(node.expression)
+  )
+    return false;
+  const name = node.expression.name.text;
+  return (
+    (name === "keys" || name === "values" || name === "entries") &&
+    lowerer.mapTypeOf(lowerer.typeOf(node.expression.expression))?.kind === "searchParams"
+  );
+}

packages/compiler/src/frontend/lowering/containers/array-construction.ts

@@ -1004,6 +1004,10 @@ export function lowerArrayFromCall(
     if (src.type.kind === "dyn" && args.length === 1) {
       return lowerCheckedArrayFrom(lowerer, src, loc);
     }
+    // Array.from(sp): the checked-dynamic view's live pair iteration.
+    if (src.type.kind === "searchParams" && args.length === 1) {
+      return lowerCheckedArrayFrom(lowerer, lowerer.coerceInto(args[0]!, src, DYN), loc);
+    }
     // A generator (or an iterator adapted into one) drains in order.
     if (src.type.kind === "generator" && args.length === 1) {
       const arrT = lowerer.mapTypeOf(lowerer.typeOf(call));

packages/compiler/src/frontend/lowering/containers/collection-methods.ts

@@ -41,6 +41,7 @@ import {
 } from "../collection-ingestion.js";
 import { strCharsCall } from "./array-construction.js";
 import { arrayElementRead } from "./array-iteration.js";
+import { isSearchParamsIterable } from "../builtins/url.js";
 
 /** Ambient Map method calls. `get`/`set`/`has`/`delete`/`clear` lower to
  * mapIntrinsic; `forEach` desugars to a direct call of a synthetic loop
@@ -1173,6 +1174,11 @@ export function lowerMapSeedNew(
       mapT,
     );
   }
+  // new Map(sp) / new Map(sp.entries()): the checked-dynamic view's live
+  // pairs seed the map in order.
+  if (isSearchParamsIterable(lowerer, argNode)) {
+    return mapFromSeedValue(lowerer, lowerer.lowerExprExpecting(argNode, DYN), mapT);
+  }
   const input = collectionInput(lowerer, argNode);
   if (input) {
     if (!collectionDestinationMatches(lowerer, input, mapT)) return null;

packages/compiler/src/frontend/lowering/lower-classes.ts

@@ -79,7 +79,7 @@ import { isAssertClassNew } from "./assert-instances.js";
 import { lowerArrayConstructor } from "./containers/array-construction.js";
 import { lowerMapSeedNew, lowerSetSeedNew } from "./containers/collection-methods.js";
 import { lowerObjectConstructor } from "./containers/indexed-objects.js";
-import { bufEncoding } from "./containers/bytes.js";
+import { knownBufEncoding } from "./containers/bytes.js";
 import { isSafeToRepeat } from "./expressions/evaluation-safety.js";
 import { lowerSearchParamsNew } from "./builtins/url.js";
 import { lowerTextCodecNew } from "./builtins/text-codecs.js";
@@ -8972,24 +8972,41 @@ export function lowerNew(lowerer: Lowerer, expr: ts.NewExpression): IrExpr {
       );
     }
     // `new StringDecoder(encoding?)` (node:string_decoder): the decoder
-    // is a two-field record — the CANONICAL encoding name (aliases fold
-    // at compile time, exactly what `.encoding` answers in Node) and
-    // the packed-f64 pending state starting at 0 (nothing buffered).
-    // The encoding must be a literal (Node's alias set); omitted means
-    // utf8, Node's default.
+    // is a two-field record — the CANONICAL encoding name (exactly what
+    // `.encoding` answers in Node) and the packed-f64 pending state
+    // starting at 0 (nothing buffered). A literal Buffer encoding folds
+    // its alias at compile time; any other encoding argument is
+    // normalized at run time (Node's normalizeEncoding, which throws
+    // ERR_UNKNOWN_ENCODING for an unknown name). Omitted means utf8,
+    // Node's default.
     if (symbol && symbol.name === "StringDecoder" && lowerer.isStdlibSymbol(symbol)) {
       const args = expr.arguments ?? [];
       if (args.length > 1) {
         lowerer.noLowering("new StringDecoder with 2 arguments", expr, undefined, symbol);
       }
-      const encName =
-        args.length === 1 ? bufEncoding(lowerer, "new StringDecoder", args[0]!) : "utf8";
+      const encNode = args[0];
+      const encT = encNode ? lowerer.typeOf(encNode) : undefined;
+      const encName = !encNode
+        ? "utf8"
+        : encT!.isStringLiteralType()
+          ? knownBufEncoding(encT!.value)
+          : undefined;
+      const encoding: IrExpr =
+        encName !== undefined
+          ? { kind: "strLit", value: encName, type: STRING, loc }
+          : {
+              kind: "libCall",
+              fn: "strdec.encoding",
+              args: [lowerer.lowerExprExpecting(encNode!, DYN)],
+              type: STRING,
+              loc,
+            };
       const decT = lowerer.mapTypeOf(lowerer.typeOf(expr));
       if (decT?.kind !== "record") lowerer.badType(expr, lowerer.typeOf(expr));
       return {
         kind: "recordLit",
         fields: [
-          { name: "%enc", value: { kind: "strLit", value: encName, type: STRING, loc } },
+          { name: "%enc", value: encoding },
           { name: "%pending", value: { kind: "numLit", value: 0, type: F64, loc } },
         ],
         type: decT,

packages/compiler/src/frontend/lowering/lower-exprs.ts

@@ -225,7 +225,7 @@ import {
 } from "./lower-builtin-values.js";
 import { lowerArrayFromValue } from "./containers/array-construction.js";
 import { lowerPerfHooksTypeof } from "./builtins/performance.js";
-import { lowerUrlAssignment } from "./builtins/url.js";
+import { isSearchParamsIterable, lowerUrlAssignment } from "./builtins/url.js";
 import { jsBindingHasOpenWrites } from "./lower-stmts.js";
 import { checkedClassInstanceOf } from "./class-construction.js";
 import { lowerModuleNamespaceElement } from "./module-namespace-elements.js";
@@ -5889,6 +5889,11 @@ export function lowerArrayLiteral(
         const drained = generatorDrain(lowerer, src, type.elem, locOf(el));
         if (drained) src = drained;
       }
+      // `[...sp]` and `[...sp.entries()]` over a URLSearchParams: its
+      // checked-dynamic view iterates the live pair list, and the drained
+      // [name, value] pairs convert to the literal's tuple elements.
+      const searchParamsSource = isSearchParamsIterable(lowerer, el.expression);
+      if (src.type.kind === "searchParams") src = lowerer.coerceInto(el.expression, src, DYN);
       // A native checked iterable can supply scalar elements even when
       // the checker inferred a typed array from its producer. Drain once
       // and validate the elements before the ordinary spread copy.
@@ -5897,7 +5902,8 @@ export function lowerArrayLiteral(
         (type.elem.kind === "dyn" ||
           type.elem.kind === "f64" ||
           type.elem.kind === "string" ||
-          type.elem.kind === "bool")
+          type.elem.kind === "bool" ||
+          searchParamsSource)
       ) {
         src = lowerer.coerceInto(el.expression, checkedIteratorPack(lowerer, src, locOf(el)), type);
       }

packages/compiler/src/frontend/lowering/lower-stmts.ts

@@ -5037,6 +5037,23 @@ function jsObjectBindingExpands(
     ) {
       const name = property(node.left);
       if (name === null || (name !== undefined && !names.has(name))) expands = true;
+      // `state = { _tag: "Done", right }` stores an object with properties
+      // the initializer's shape lacks; later reads of them must see them.
+      const target = unwrap(node.left);
+      const value = unwrap(node.right);
+      const targetSymbol = ts.isIdentifier(target) ? lowerer.resolveValueSymbol(target) : undefined;
+      if (
+        targetSymbol &&
+        aliases.has(targetSymbol) &&
+        ts.isObjectLiteralExpression(value) &&
+        value.properties.some(
+          (field) =>
+            !(ts.isPropertyAssignment(field) || ts.isShorthandPropertyAssignment(field)) ||
+            !(ts.isIdentifier(field.name) || ts.isStringLiteral(field.name)) ||
+            !names.has(field.name.text),
+        )
+      )
+        expands = true;
     }
     if (ts.isDeleteExpression(node) && property(node.expression) !== undefined) expands = true;
     if (

packages/compiler/src/frontend/lowering/surfaces.ts

@@ -1485,6 +1485,9 @@ export const BUILTIN_MODULE_FNS: Record<
       result: F64,
       valueParams: [{ mode: "optional", type: F64, defaultValue: 0 }],
     },
+    // A one-argument call is setPriority(0, priority)
+    // (lowerOsSetPriorityCall completes it).
+    setPriority: { fn: "os.setPriority", params: [F64, F64], result: VOID },
     // Special-cased (lowerOsCpusCall): the call site's CpuInfo[] assembles
     // from one uv_cpu_info snapshot.
     cpus: { fn: "os.cpusTake", params: [], result: VOID },

packages/compiler/src/ir/builtin-effects.ts

@@ -34,6 +34,7 @@ export const MAY_THROW_LIB_FNS: ReadonlySet<IrLibFn> = new Set([
   "cp.spawnDynamic",
   "child.onDyn",
   "text.decoderEncoding",
+  "strdec.encoding",
   "dyn.construct",
   "dyn.reflectApply",
   "dyn.reflectGet",
@@ -556,6 +557,7 @@ export const MAY_THROW_LIB_FNS: ReadonlySet<IrLibFn> = new Set([
   "dyn.arrayProtoCall",
   "process.chdir",
   "os.getPriority",
+  "os.setPriority",
   // Pattern length TypeError, brace-sequence RangeError, and the
   // SyntaxError of a segment regex invalid under the u flag.
   "path.matchesGlob",

packages/compiler/src/ir/builtin-signatures.ts

@@ -550,6 +550,10 @@ export const LIB_FN_SIGS = defineLibFnSignatures({
   /** os.getPriority(pid): validateInt32 (RangeError ERR_OUT_OF_RANGE),
    * then the priority; a failure throws Node's SystemError. */
   "os.getPriority": { argTypes: [F64], result: F64 },
+  /** os.setPriority(pid, priority): validateInt32 for both (priority in
+   * -20..19, RangeError ERR_OUT_OF_RANGE), then the priority; a failure
+   * throws Node's SystemError. */
+  "os.setPriority": { argTypes: [F64, F64], result: VOID },
   /** os.cpus(): cpusTake snapshots every CPU and answers the count;
    * cpusModel(i) and cpusField(i, k) (k: 0 speed, 1 user, 2 nice, 3 sys,
    * 4 idle, 5 irq) read the snapshot. Never throw. */
@@ -3785,6 +3789,9 @@ export const LIB_FN_SIGS = defineLibFnSignatures({
   "strdec.write": { argTypes: [STRING, F64, BYTES_U8], result: STRING },
   "strdec.next": { argTypes: [STRING, F64, BYTES_U8], result: F64 },
   "strdec.end": { argTypes: [STRING, F64], result: STRING },
+  /** A runtime encoding argument's canonical name (Node's normalizeEncoding:
+   * nullish and "" are utf8); an unknown name throws ERR_UNKNOWN_ENCODING. */
+  "strdec.encoding": { argTypes: [DYN], result: STRING },
   // node:readline: the interface handle is f64; the callbacks' func types
   // are program-dependent (the emitter picks the adapter by parameter
   // count), so those slots are null like child.onExit's.

packages/compiler/src/ir/function-references.test.ts

@@ -193,6 +193,7 @@ const MODULE_FIELDS: Record<StringFields<Omit<IrModule, "functions">>, Role> = {
   "lib.exports[].fnName": "reference",
   "lib.exports[].inboundBytesTrap": "other",
   "lib.exports[].inboundIntTrap": "other",
+  "lib.exports[].inboundCstringTrap": "other",
   "lib.trapOverlays[].code": "other",
   "lib.trapOverlays[].teaching": "other",
   "lib.trapOverlays[].remediation": "other",

packages/compiler/src/ir/ir.ts

@@ -1176,8 +1176,19 @@ export interface IrLibExport {
   /** i64/u64 (ask 4): int64_t/uint64_t at the C edge — inbound values
    * range-check in the wrapper (`inboundIntTrap`), internal call sites
    * and returns are compile-time proven before this lands on the IR. */
-  params: ("f64" | "bool" | "string" | "bytes" | "u8" | "u32" | "i32" | "i64" | "u64")[];
-  returns: "f64" | "bool" | "string" | "bytes" | "void" | "i64" | "u64";
+  params: (
+    | "f64"
+    | "bool"
+    | "string"
+    | "cstring"
+    | "bytes"
+    | "u8"
+    | "u32"
+    | "i32"
+    | "i64"
+    | "u64"
+  )[];
+  returns: "f64" | "bool" | "string" | "cstring" | "bytes" | "void" | "i64" | "u64";
   /** The exact sink-message bytes this wrapper passes to the inbound-bytes
    * marshalling helper's trap — present exactly when a parameter is
    * bytes-classed. Already the assembled structured trap-teaching form
@@ -1192,6 +1203,10 @@ export interface IrLibExport {
    * value cannot ride f64 exactly (|v| past 2^53−1). Same assembled
    * structured form and the same SC4012 code — one host-contract story. */
   inboundIntTrap?: string;
+  /** The sibling message for a NULL cstring parameter: present exactly
+   * when a parameter is cstring-classed, passed to scr_library_cstr_in.
+   * Same assembled structured form and the same SC4012 code. */
+  inboundCstringTrap?: string;
 }
 
 /** One runtime-trap overlay row: the profile's teaching (replaces the
@@ -1218,7 +1233,7 @@ export interface IrLibCallback {
   name: string;
   /** The runtime channel slot (profile declaration order). */
   slot: number;
-  params: ("f64" | "bool" | "string" | "bytes" | "u8" | "u32" | "i32")[];
+  params: ("f64" | "bool" | "string" | "cstring" | "bytes" | "u8" | "u32" | "i32")[];
   returns: "f64" | "bool" | "u8" | "u32" | "i32" | "i64" | "u64" | "pointer" | "void";
   /** The unregistered-call trap text (a DETECTED trap: plain bytes the
    * library funnel classifies SC4025 and assembles with the current

packages/compiler/src/ir/validate.ts

@@ -357,7 +357,7 @@ export function validateModule(mod: IrModule): IrValidationError[] {
       const fits = (cls: string, t: IrType): boolean =>
         cls === "bool"
           ? t.kind === "bool"
-          : cls === "string"
+          : cls === "string" || cls === "cstring"
             ? t.kind === "string"
             : cls === "bytes"
               ? t.kind === "bytes" && t.elem === "u8"

packages/compiler/src/library/library-profile.ts

@@ -10,7 +10,7 @@
  *
  * Ratified shape (the ratified library-mode design §5.1 + the ABI ratification session):
  *   {
- *     "profile_format": 1,
+ *     "profile_format": 1 | 2,              // 2 adds the cstring class
  *     "name": "<embedder identity string>",
  *     "entry": "src/lib.ts",                  // ONE module, profile-relative
  *     "emission": "llvm",                // pins the emission; no fallback
@@ -268,6 +268,7 @@ export const LIB_PARAM_CLASSES = [
   "f64",
   "bool",
   "string",
+  "cstring",
   "bytes",
   "u8",
   "u32",
@@ -282,7 +283,16 @@ export const LIB_PARAM_CLASSES = [
  * u8/u32/i32 plumbing classes stay param-only: they were ratified as
  * inbound plumbing, and outbound integers are the proven classes'
  * business. */
-export const LIB_RETURN_CLASSES = ["f64", "bool", "string", "bytes", "void", "i64", "u64"] as const;
+export const LIB_RETURN_CLASSES = [
+  "f64",
+  "bool",
+  "string",
+  "cstring",
+  "bytes",
+  "void",
+  "i64",
+  "u64",
+] as const;
 
 /** Ask 4's declared integer classes (the prove-or-refuse pair). */
 export type LibIntClass = "i64" | "u64";
@@ -297,7 +307,16 @@ export type LibReturnClass = (typeof LIB_RETURN_CLASSES)[number];
  * declared integer classes stay export-map surface: an outbound i64/u64
  * demands the prove-or-refuse machinery, which is scoped to export
  * returns today. */
-const LIB_CALLBACK_PARAM_CLASSES = ["f64", "bool", "string", "bytes", "u8", "u32", "i32"] as const;
+const LIB_CALLBACK_PARAM_CLASSES = [
+  "f64",
+  "bool",
+  "string",
+  "cstring",
+  "bytes",
+  "u8",
+  "u32",
+  "i32",
+] as const;
 /** Marshalling classes legal in a CALLBACK RETURN position (inbound: host
  * → compiled code). Scalars only — every conversion to f64 is exact by
  * construction; a buffer return would need an ownership contract the mode
@@ -377,7 +396,7 @@ export interface LibrarySidecarConfig {
 }
 
 export interface LibraryProfile {
-  profileFormat: 1;
+  profileFormat: 1 | 2;
   name: string;
   /** The profile file that produced this configuration. Semantic
    * designation errors anchor here, where the offending name is written. */
@@ -516,8 +535,16 @@ export function loadLibraryProfile(
     }
     const p = raw as Record<string, unknown>;
     const format = req<number>(p["profile_format"], "profile_format", "number");
-    if (format !== 1)
-      throw new ProfileError(`unsupported profile_format ${format} (this scriptc reads format 1)`);
+    if (format !== 1 && format !== 2)
+      throw new ProfileError(
+        `unsupported profile_format ${format} (this scriptc reads formats 1 and 2)`,
+      );
+    // The cstring class (a NUL-terminated `const char *`) is format 2.
+    const cstringClass = (cls: string, path: string): void => {
+      if (cls === "cstring" && format < 2) {
+        throw new ProfileError(`'${path}' class 'cstring' requires profile_format 2`);
+      }
+    };
     // Root keys are strict (checked AFTER the format gate, so a future
     // format's profile refuses as the wrong format, not as a typo). The
     // ask-5 key names get the pointed message: a `fences` array pasted at
@@ -656,6 +683,7 @@ export function loadLibraryProfile(
             `'${path}.params[${j}]' must be one of ${LIB_PARAM_CLASSES.join("/")}, got ${JSON.stringify(c)}`,
           );
         }
+        cstringClass(c, `${path}.params[${j}]`);
         return c as LibParamClass;
       });
       const returns = req<string>(ee["returns"], `${path}.returns`, "string");
@@ -666,6 +694,7 @@ export function loadLibraryProfile(
             : `'${path}.returns' must be one of ${LIB_RETURN_CLASSES.join("/")}, got '${returns}'`;
         throw new ProfileError(detail);
       }
+      cstringClass(returns, `${path}.returns`);
       entries.push({ export: exportName, symbol, params, returns: returns as LibReturnClass });
     });
 
@@ -709,12 +738,13 @@ export function loadLibraryProfile(
               `'${path}.params[${j}]' must be one of ${LIB_CALLBACK_PARAM_CLASSES.join("/")}, got ${JSON.stringify(cls)}`,
             );
           }
+          cstringClass(cls, `${path}.params[${j}]`);
           return cls as LibCallbackParamClass;
         });
         const cbReturns = req<string>(cc["returns"], `${path}.returns`, "string");
         if (!(LIB_CALLBACK_RETURN_CLASSES as readonly string[]).includes(cbReturns)) {
           const detail =
-            cbReturns === "string" || cbReturns === "bytes"
+            cbReturns === "string" || cbReturns === "cstring" || cbReturns === "bytes"
               ? `'${path}.returns': a callback return stays scalar — a buffer flowing host → library needs an ownership contract the mode does not define; pass buffers as callback parameters (library → host, borrowed for the call) or entry parameters instead`
               : `'${path}.returns' must be one of ${LIB_CALLBACK_RETURN_CLASSES.join("/")}, got '${cbReturns}'`;
           throw new ProfileError(detail);
@@ -1010,7 +1040,7 @@ export function loadLibraryProfile(
     return {
       ok: true,
       profile: {
-        profileFormat: 1,
+        profileFormat: format as 1 | 2,
         name,
         profilePath,
         entry,

packages/compiler/src/library/prepare.ts

@@ -65,6 +65,7 @@ function libClassFits(cls: string, t: IrType): boolean {
     case "bool":
       return t.kind === "bool";
     case "string":
+    case "cstring":
       return t.kind === "string";
     case "bytes":
       return t.kind === "bytes" && t.elem === "u8";
@@ -178,6 +179,18 @@ function resolveLibrarySection(
           profileRemediation(profile, LIB_INBOUND_BYTES_TRAP_CODE),
         );
       }
+      if (e.params.includes("cstring")) {
+        // The host-contract trap for a NULL cstring parameter: a C string
+        // argument is a pointer to NUL-terminated text, never NULL. Same
+        // code and assembly-once discipline as the bytes and integer traps.
+        resolvedExport.inboundCstringTrap = assembleTrapTeaching(
+          profileTeaching(profile, LIB_INBOUND_BYTES_TRAP_CODE) ??
+            "scriptc: library inbound cstring parameter is NULL\n",
+          LIB_INBOUND_BYTES_TRAP_CODE,
+          e.symbol,
+          profileRemediation(profile, LIB_INBOUND_BYTES_TRAP_CODE),
+        );
+      }
       if (e.params.includes("i64") || e.params.includes("u64")) {
         // The sibling host-contract trap for inbound declared-integer
         // parameters (ask 4): a value past ±(2^53−1) cannot ride f64
@@ -524,10 +537,12 @@ export function prepareLibrary(
     // SC4024 diagnostics, unused channels legal, undeclared references
     // refused with the callback teaching. The library lane never loads a
     // native-FFI manifest, so the channel set owns the surface outright.
+    // A cstring channel parameter is a string on the TypeScript side; the
+    // channel's own classes (lib.callbacks) drive the marshalling.
     const cbImports: IrFfiImport[] = profile.callbacks.map((cb) => ({
       name: cb.name,
       symbol: cb.name,
-      params: [...cb.params],
+      params: cb.params.map((cls) => (cls === "cstring" ? "string" : cls)),
       returns: cb.returns,
     }));
     const integerSlotRoots: string[] = [];