candor-ts 0.5.12 → 0.5.13

package/AGENTS.md

@@ -144,7 +144,10 @@ curated-κ caveat cuts the other way:** a call into an npm package κ doesn't kn
 NOTHING — invisible, not `Unknown`. The scan's receipt now DISCLOSES these by name (`κ doesn't
 know N packages…`), so the blind spots are per-scan evidence, not a doc footnote: never conclude
 "no effect" through a package that line names (the documented weaker edge of the
-never-silently-pure promise, same as every candor engine's curated classifier). An uncurated
+never-silently-pure promise, same as every candor engine's curated classifier). Each function ALSO
+carries an `invisible` list — the κ-unknown packages it (transitively) reaches — so `inferred` is
+never an unqualified claim PER FUNCTION: `inferred: []` with a non-empty `invisible` means "pure as
+far as candor could see, but it could not see through these" (a LOWER bound), not "pure". An uncurated
 dependency can opt out of that blind spot by declaring `"candorEffects": ["Net", …]` in its
 `package.json` (the §5.1 effect manifest, read declared-not-verified) — its calls then classify to
 the declared set instead of contributing nothing.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "candor-ts",
-  "version": "0.5.12",
+  "version": "0.5.13",
   "description": "candor for TypeScript — per-function side effects, transitively, with a policy gate (candor-spec 0.5)",
   "type": "module",
   "dependencies": {

package/policy.mjs

@@ -103,7 +103,7 @@ export function literalAllowed(effect, reached, values) {
  * transitive inferred; AS-EFF-008 allowlists over the transitive literal surfaces, the no-visible-
  * literal case flagged as uncertifiable; AS-EFF-009 forbid by reachability). One line per violation.
  */
-export function evaluatePolicy(pol, functions, callgraph) {
+export function evaluatePolicy(pol, functions, callgraph, incomplete = new Map()) {
   const out = [];
   const surfaces = { Net: "hosts", Exec: "cmds", Fs: "paths", Db: "tables" };
   for (const f of functions) {
@@ -116,7 +116,11 @@ export function evaluatePolicy(pol, functions, callgraph) {
       if (r.scope && !scopeMatches(f.fn, r.scope)) continue;
       if (!f.inferred.includes(r.effect)) continue;
       const reached = f[surfaces[r.effect]] ?? [];
-      if (reached.length === 0) {
+      // An INCOMPLETE surface (a structurally-invisible reach — a host-establishing call with a runtime/
+      // invisible host) can't be certified even with visible hosts, else a benign literal masks the
+      // invisible forbidden endpoint (the masking evasion). Matches candor-java 0.5.29 / candor-rust.
+      const surfaceIncomplete = incomplete.get(f.fn)?.has(r.effect);
+      if (reached.length === 0 || surfaceIncomplete) {
         out.push(`[AS-EFF-008] \`${f.fn}\` performs ${r.effect} with no visible literal — the surface cannot be certified: \`${r.raw}\``);
       } else {
         const bad = reached.filter((v) => !literalAllowed(r.effect, v, r.values));

package/scan.mjs

@@ -464,7 +464,7 @@ for (const sf of sources) {
         const { line, character } = sf.getLineAndCharacterOfPosition(node.getStart());
         fns.set(ctorQual, { local: `${node.name.text}.constructor`, direct: new Set(), edges: new Set(),
                             hosts: new Set(), tables: new Set(), cmds: new Set(), paths: new Set(),
-                            why: new Set(), entry: false,
+                            blind: new Set(), incomplete: new Set(), why: new Set(), entry: false,
                             loc: `${path.relative(rootDir, sf.fileName)}:${line + 1}:${character + 1}` });
       }
       nodeName.set(node, ctorQual);
@@ -475,7 +475,7 @@ for (const sf of sources) {
       const qual = `${mod}.${n}`;
       const { line, character } = sf.getLineAndCharacterOfPosition(node.getStart());
       fns.set(qual, { local: n, direct: new Set(), edges: new Set(), hosts: new Set(), tables: new Set(),
-                      cmds: new Set(), paths: new Set(), why: new Set(), entry: false, isCjsExport,
+                      cmds: new Set(), paths: new Set(), blind: new Set(), incomplete: new Set(), why: new Set(), entry: false, isCjsExport,
                       loc: `${path.relative(rootDir, sf.fileName)}:${line + 1}:${character + 1}` });
       nodeName.set(node, qual);
       if ((ts.isVariableDeclaration(node) || ts.isPropertyDeclaration(node)) && node.initializer)
@@ -980,6 +980,9 @@ function visitCalls(node) {
           // needs no entry here. Inert ctors (Agent/Server/Socket/TLSSocket/Http2Server*/message shells)
           // still synthesize "new" and stay pure.
           const CONNECTING_CTORS = new Set(["ClientRequest"]);
+          // Host-ESTABLISHING Net call names (the masking-fix allowlist): a Net call by one of these whose
+          // host is not a captured literal leaves the host invisible. Excludes use-verbs (write/end/send).
+          const NET_ESTABLISHING = new Set(["request", "get", "connect", "createConnection", "fetch"]);
           const ctorClassName = ts.isNewExpression(node)
             ? (ts.isConstructorDeclaration(decl) ? decl.parent?.name?.getText?.()
                : (decl.name ? decl.name.getText() : ""))
@@ -1005,6 +1008,14 @@ function visitCalls(node) {
             const lit = firstStringLiteral(node);
             const h = lit && hostLiteral(lit);
             if (h) rec.hosts.add(h);
+            // MASKING fix: a host-ESTABLISHING Net call whose host is NOT a captured literal (runtime URL, or
+            // built elsewhere) leaves the host invisible to the gate → mark the surface incomplete so a
+            // benign literal can't mask it. ALLOWLIST of establishing forms only (request/get/connect/
+            // createConnection/fetch + the connecting ctor) — NEVER use-calls (write/end/send), which would
+            // false-positive on `socket.connect("h").write(data)` (the host is captured at connect). Under-
+            // catches an unlisted establishing verb (safe direction); never over-flags a use-call.
+            else if (NET_ESTABLISHING.has(member) || CONNECTING_CTORS.has(ctorClassName))
+              rec.incomplete.add("Net");
           }
           if (eff === "Db") {
             const lit = firstStringLiteral(node);
@@ -1079,6 +1090,11 @@ function visitCalls(node) {
             } else if (!kappaKnows(pkg) && !depCoveredPkgs.has(pkg)
                 && /node_modules\//.test(file) && !/node_modules\/(@types\/node|typescript)\//.test(file)) {
               unlistedSeen.set(pkg, (unlistedSeen.get(pkg) ?? 0) + 1);
+              // Per-fn HONESTY: this fn calls into a genuinely-blind package (κ-unknown, not dep-covered).
+              // Recorded per fn, propagated transitively, emitted as `invisible` — so `inferred` is never an
+              // unqualified completeness claim. This branch already IS the global-blind condition, so no
+              // post-filter is needed (κ either knows a package or it doesn't).
+              rec.blind.add(pkg);
             }
           }
         }
@@ -1271,7 +1287,7 @@ while (changed) {
         if (!mine.has(e)) { mine.add(e); changed = true; }
   }
 }
-for (const m of ["hosts", "tables", "cmds", "paths"]) {
+for (const m of ["hosts", "tables", "cmds", "paths", "blind", "incomplete"]) {
   let moved = true;
   while (moved) {
     moved = false;
@@ -1286,7 +1302,9 @@ for (const m of ["hosts", "tables", "cmds", "paths"]) {
 const functions = [];
 for (const [name, rec] of fns) {
   const inf = [...inferred.get(name)].sort();
-  if (inf.length === 0 && !rec.entry) continue; // entry points stay visible even when pure
+  // entry points stay visible even when pure; a BLIND fn stays too, so the honesty disclosure survives
+  // on exactly the `inferred: []` fns that need it.
+  if (inf.length === 0 && !rec.entry && rec.blind.size === 0) continue;
   const entry = {
     fn: name,
     loc: rec.loc,
@@ -1303,6 +1321,9 @@ for (const [name, rec] of fns) {
   if (inf.includes("Exec") && rec.cmds.size) entry.cmds = [...rec.cmds].sort();
   if (inf.includes("Fs") && rec.paths.size) entry.paths = [...rec.paths].sort();
   if (rec.direct.has("Unknown") && rec.why.size) entry.unknownWhy = [...rec.why].sort();
+  // HONESTY: the npm packages this fn transitively reaches that κ couldn't see through — effects through
+  // them are NOT in `inferred`, so it is a LOWER BOUND when this is non-empty. Omitted when none.
+  if (rec.blind.size) entry.invisible = [...rec.blind].sort();
   if (rec.entry) entry.entryPoint = true;
   if (rec.isCjsExport) entry.unitKind = "export"; // spec 0.5 draft, informative — per-unit, not by name
   functions.push(entry);
@@ -1339,7 +1360,11 @@ if (policyPath) {
     console.error(`candor-ts: policy ${policyPath} could not be read; gate NOT enforced`);
     process.exit(2);
   }
-  const v = evaluatePolicy(parsePolicy(text), functions, cg);
+  // The masking-incompleteness map (fn -> effects whose surface is incomplete), kept INTERNAL like the
+  // java/rust engines (not a report field) — passed to the gate so an incomplete surface fails closed.
+  const incompleteMap = new Map();
+  for (const [name, rec] of fns) if (rec.incomplete.size) incompleteMap.set(name, rec.incomplete);
+  const v = evaluatePolicy(parsePolicy(text), functions, cg, incompleteMap);
   for (const line of v) console.log(line);
   if (v.length) {
     console.error(`candor-ts: ${v.length} policy violation(s)`);