candor-ts 0.4.0

package/AGENTS.md

@@ -0,0 +1,117 @@
+# Using candor-ts (instructions for an AI coding agent)
+
+You are working in a TypeScript project. **candor-ts** tells you, for every function, which side
+effects it can reach — network, filesystem, database, subprocess, env, clock — *including effects
+inherited transitively through any chain of calls across files*. Use it instead of tracing call
+chains by hand. The language-agnostic consumption contract is
+[candor-spec/AGENTS.md](https://github.com/tombaldwin/candor-spec/blob/main/AGENTS.md); this file is
+the TypeScript-specific production + query surface.
+
+## Produce a report
+
+Not yet on npm — run from a clone (needs node ≥ 20):
+
+```sh
+git clone --depth 1 https://github.com/tombaldwin/candor-ts /tmp/candor-ts 2>/dev/null \
+  || (cd /tmp/candor-ts && git pull -q)
+( cd /tmp/candor-ts && npm install --no-fund --no-audit )
+
+node /tmp/candor-ts/scan.mjs <project-dir>     # tsconfig.json honored; tests/node_modules excluded
+node /tmp/candor-ts/scan.mjs <dir> --allow-js  # also analyze .js/.mjs sources (walks the tree)
+```
+
+This writes `<project-dir>/.candor/report.json` and `.candor/report.callgraph.json` (override
+with `--out <prefix>`). **Install the TARGET's dependencies first** (`npm install` in the project)
+— without node_modules, imports don't resolve and most functions honestly read `Unknown` (the
+scanner warns loudly). Add `--policy <file>` (or set `CANDOR_POLICY`) to enforce a §6.2 policy over the
+scan: exit 1 on violation, exit 2 LOUDLY if the policy file is unreadable.
+
+**Report shape:** the file is `{ "candor": {version, toolchain, spec}, "functions": [...] }`;
+`functions` is an **array** of entries (not a map — don't index it by name), each carrying **`fn`**
+— module-qualified, `.`-separated
+(`src.db.save` for `save()` in `src/db.ts`; class methods are `src.api.Client.send`) — with
+`inferred` (the full transitive set) / `direct` / `unresolved` / optional `hosts`/`cmds`/`paths`/
+`tables` (the literal surfaces). **Only effectful-or-unresolved functions appear in the report;
+pure functions are omitted** — a function present in the callgraph sidecar but absent from
+`.functions[]` is pure (as far as the engine resolved). In *neither* file = never analyzed
+(a test file? an unexported arrow inside an object literal?) — conclude nothing.
+
+**Multi-package (monorepos / private deps):** point `CANDOR_DEPS` at the dependencies' reports
+(a path list, or a directory of `*.json`); an unclassified call into a package with a loaded
+report inherits that function's recorded transitive effects and literal surfaces, joined by the
+report's `hash` (`package#LocalName`). A report produced by a different candor-ts version is
+downgraded to `Unknown` rather than silently trusted (spec §2.1). Caveat: a type-only boundary
+(`import type` …, the tRPC style) has no runtime calls to inherit through — nothing to join.
+
+## Query it (same names/shapes as the Rust and JVM engines — candor-spec §3.1)
+
+```sh
+Q() { node /tmp/candor-ts/query.mjs "$@"; }; P=".candor/report"   # a function — works in bash AND zsh
+Q show     $P <fn-query> 1          # a function's effects (+ hosts/tables when visible)
+Q where    $P <Effect>   1          # {effect, directly, inherited}
+Q callers  $P <fn-query> 1          # the BLAST RADIUS: {of, direct, transitive} — works for pure fns
+Q map      $P 1                     # {module: {effects, functions}}
+Q whatif   $P <fn> <Effect> [policy]  # pre-edit gate verdict (exit 1 if it would violate)
+Q diff     $P <baseline-prefix> 1   # per-function effect delta (exit 1 on a gained effect)
+Q reachable $P 1                    # what the app DOES at runtime: effects over the entry points
+Q parsepolicy <policy-file>         # the canonical §6.2 parse (what the gate will enforce)
+```
+
+Name queries resolve exact > segment-suffix (`db.save` matches `src.db.save`, never
+`src.db.save_all`) > substring — the same ladder as the other engines. The trailing `1` is the
+want-JSON flag.
+
+- **Blast radius of editing a function** → `callers <fn>` (NOT its `inferred`, which is what the
+  function itself does). Works pre-edit for a still-pure function.
+- **Decide BEFORE you edit** → `whatif <fn> <Effect> [policy]` — every transitive caller gains the
+  effect, crossed with the policy.
+- **After you change code** → `diff` against a baseline report; a gained `Net`/`Db`/`Exec`/`Fs` you
+  didn't intend is a regression in your change.
+
+## TypeScript-specific things to know
+
+- **Arrow-const functions are first-class**: `export const f = async () => …` is analyzed and named
+  like a declaration; calls to it are edges. An arrow assigned inside a function body becomes its
+  own unit (`src.x.helper`) — effects still propagate to the enclosing caller through the edge.
+- **The classifier is curated** (node builtins + a small npm tier: axios/got/node-fetch/undici/ws,
+  pg/mysql2/mongodb/redis/knex, execa/cross-spawn, fs-extra/rimraf/glob, dotenv, winston/pino).
+  An unlisted package contributes nothing — an effect through it is invisible, not `Unknown`. The
+  scanner **names these per scan**: the receipt's `κ doesn't know N packages…` line lists every npm
+  package the code demonstrably calls that κ neither classifies nor has reviewed-pure — read it
+  before concluding "no effect" through anything it names.
+- **`process.env.X` reads are `Env`** (a property read, not a call); `Date.now()` is `Clock`.
+- **DI-style code reads `Unknown` a lot, honestly**: a function-typed parameter or field being
+  called is genuinely indeterminate (rimraf's injected-fs style yields many `Unknown`s — that's the
+  §4 contract, not noise). When every visible call site passes a *named* function, the callback
+  resolves instead. And a method call on a **local-interface-typed value** (`store.save()` where
+  `class PgStore implements Store`) resolves to the local implementors when the dispatch is narrow
+  (≤12 classes) — the layered-DI pattern carries its real effects; only an interface with no
+  visible implementor still reads `Unknown` (`dispatch:<Type>`).
+- **`unknownWhy` names each direct Unknown's origin** (`call:jwt.sign`, `callback:param#0`,
+  `dispatch:<Type>`) — triage starts at the named site. Inheritors carry `Unknown` with no why;
+  follow the callgraph down to the root.
+- **`entryPoint: true` marks runtime-invoked roots** (Nest `@Get/@Post/…` handler methods, Next
+  `route.ts` HTTP exports and `middleware`) — their effects are never orphaned; `reachable` unions
+  over them. Pure entry points stay visible in the report.
+
+A worked policy (§6.2 — one rule per line, `#` comments):
+
+```text
+deny Net domain                       # the domain module reaches no network, transitively
+pure  parse
+allow Db in db  orders ledger.*       # the db module touches ONLY these tables
+forbid domain -> infra
+```
+
+## The trust rule — do not skip this
+
+`inferred` is authoritative for what candor-ts resolved. When `unresolved` is true (or `Unknown` is
+present — a callback value, an `any`-typed callee, resolution landing on a type rather than a
+body), the set may be incomplete: read the source for *that* function before relying on it. Never
+conclude a function is pure while it is marked unresolved. The literal surfaces (`hosts`/`tables`/
+`cmds`/`paths`) are the decidable subset only — absence is never a claim of absence. **And the
+curated-κ caveat cuts the other way:** a call into an npm package κ doesn't know contributes
+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).

package/LICENSE-APACHE

@@ -0,0 +1,201 @@
+                                 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 2026 Tom Baldwin
+
+   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/LICENSE-MIT

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tom Baldwin
+
+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.

package/PROVE-IT.md

@@ -0,0 +1,82 @@
+# Prove it on *your* repo — a 15-minute self-experiment (TypeScript)
+
+The candor family's [evals](https://github.com/tombaldwin/candor-rust/blob/main/EVAL.md) show
+agents miss most of an effect's blast radius on *our* fixtures. You shouldn't care about our
+fixtures. This is the same A/B, run by **your** agent on **your** TypeScript codebase, with every
+claimed result verifiable by you at a file:line. Either outcome is informative — including "candor
+didn't help here" (the prompt reports that too, and says why).
+
+**Requirements:** a TypeScript project, node ≥ 20, any agentic coding tool. (Rust project? Use the
+[Rust variant](https://github.com/tombaldwin/candor-rust/blob/main/PROVE-IT.md); JVM? the
+[JVM variant](https://github.com/tombaldwin/candor-java/blob/main/PROVE-IT.md).)
+
+**Paste this prompt into your agent at the repo root:**
+
+---
+
+```text
+We're testing whether a static effect-analysis tool (candor-ts) tells me things about MY codebase
+that you'd otherwise miss or take longer to find. Follow these steps IN ORDER — the order is the
+experiment's integrity (your manual answer must be committed before the tool's answer exists).
+
+STEP 1 — Pick the target. Choose ONE function in this project's PRODUCTION code (not tests, which
+the scan deliberately excludes as harness code) that performs I/O (network, filesystem, database,
+subprocess) and is called from more than one place — ideally one I care about changing. If I named
+a function in my message, use that. State your choice.
+
+STEP 2 — MANUAL TRACE (commit before looking at any tool output). From source alone, answer:
+"Which functions in this project would be affected if <target> changed its behavior — i.e. every
+TRANSITIVE caller, across all files?" Work as you normally would (grep, read). Write the complete
+list to ./candor-manual-<target>.txt in the repo root (NOT a fixed /tmp name — repeated runs must
+not cross-contaminate) — one function per line, named the way the callgraph keys them:
+module-qualified with "." segments (src.db.save for save() in src/db.ts; class members
+src.api.Client.send, constructors src.api.Client.constructor; a NESTED named function is keyed flat
+under its module, while an anonymous arrow — including one wrapped in a cast — folds into its
+enclosing function). Also note roughly how
+many file-reads/searches it took you.
+
+STEP 3 — Run candor-ts:
+  git clone --depth 1 https://github.com/tombaldwin/candor-ts /tmp/candor-ts
+  (cd /tmp/candor-ts && npm install --no-fund --no-audit)
+  node /tmp/candor-ts/scan.mjs .
+It writes .candor/report.json (per-function transitive effects) and .candor/report.callgraph.json
+(every analyzed function's direct callees, pure ones included).
+
+STEP 4 — Compute the tool's answer from the callgraph sidecar (plain JSON — no magic): write a
+~10-line script that loads the callgraph, builds the reverse edge map, and BFS's from the target to
+collect every transitive caller. Save to ./candor-tool-<target>.txt. (Note .candor/report.json's `functions` is an ARRAY of
+{fn, inferred, …} entries; the callgraph sidecar is a keyed map — don't index the report like a
+map.)
+
+STEP 5 — Diff and VERIFY. Compare the two lists.
+- For each function candor found that your manual trace MISSED: reconstruct the call chain from the
+  callgraph (target ← caller ← caller …) and open ONE file per missed function to confirm the call
+  site is real, quoting the file:line. These are real, verifiable edges — not tool assertions.
+- For each function YOU listed that candor did not: check whether it's a real caller candor missed
+  (a call through a callback value or an `any`-typed callee reads Unknown rather than edging — see
+  the README's trust contract; a genuinely dropped edge is worth reporting at
+  https://github.com/tombaldwin/candor-ts/issues) or a mistake in the trace.
+
+STEP 6 — Scorecard. Report, honestly:
+- target function, and the size of its true radius
+- manual trace: N of M found, the specific functions missed (with the verified file:line evidence),
+  and the file-reads/searches it took
+- candor-ts: one scan + one script, and its own N of M
+- AND if the result is unflattering to candor-ts, say so plainly: if your manual trace found
+  everything (shallow radius, distinctive names — common in small projects), the honest conclusion
+  is "on this codebase candor's value is speed/CI-gating, not completeness." If candor-ts missed
+  real callers (DI-heavy code where calls flow through injected function values is its documented
+  honest-Unknown territory; an unlisted npm package's effects are its documented classifier gap),
+  report that as the tool's limitation.
+
+Do not soften either direction. The point is what's true on THIS repo.
+```
+
+---
+
+## Why this is a fair test
+
+Same protocol as the family's pre-registered evals: the commitment device (manual answer written
+before the tool runs), no circular trust (every claimed miss comes with a call chain whose every
+edge is a real call site in *your* code), and the negative result in-scope. candor-ts is the
+youngest engine — its misses are the most likely in the family, and we want them reported.

package/README.md

@@ -0,0 +1,109 @@
+# candor-ts
+
+<p align="center"><img src="https://raw.githubusercontent.com/tombaldwin/candor/main/assets/beaky.svg" alt="Beaky, the candor canary" width="180"></p>
+
+**candor for TypeScript: per-function side effects, transitively, with a deterministic policy
+gate.** candor-ts resolves every call through the TypeScript compiler API and reports, for each
+function in your project, which effects it can reach — `Net`, `Fs`, `Db`, `Exec`, `Env`, `Clock`,
+… — **including effects inherited through any chain of calls across files**, with an honest
+`Unknown` wherever resolution fails (a callback value, an `any`-typed callee — never silently
+pure). A [candor-spec](https://github.com/tombaldwin/candor-spec) implementation, sibling of the
+[Rust](https://github.com/tombaldwin/candor-rust) and
+[JVM](https://github.com/tombaldwin/candor-java) engines.
+
+**Site:** [candor.poly.io](https://candor.poly.io) — the measured case in five minutes.
+
+```sh
+npm install   # typescript + @types/node
+
+node scan.mjs <project-dir>                 # tsconfig.json honored; tests excluded; writes
+                                            #   <dir>/.candor/report.json + .callgraph.json
+node scan.mjs . --policy .candor/policy     # the §6.2 gate: exit 1 on violation, 2 if unreadable
+
+node query.mjs show     .candor/report db.save 1   # a function's effects (match ladder)
+node query.mjs where    .candor/report Net 1       # direct sources vs inheritors
+node query.mjs callers  .candor/report db.save 1   # the blast radius (transitive callers)
+node query.mjs map      .candor/report 1           # module → effects overview
+node query.mjs whatif   .candor/report db.save Net policy  # pre-edit gate verdict (exit 1)
+node query.mjs diff     .candor/report baseline 1  # per-function effect delta (exit 1 on a gain)
+```
+
+Function names are module-qualified with `.` segments (`src.db.save`), so policy scopes read
+naturally:
+
+```text
+# .candor/policy
+deny Net domain                       # the domain layer reaches no network, even through helpers
+pure  parse                           # parsing is effect-free
+allow Db in db  orders audit_log      # the db layer touches ONLY these tables
+allow Net in billing api.stripe.com   # billing talks ONLY to Stripe
+forbid domain -> infra                # the domain layer must not depend on infra
+```
+
+The report carries the four **literal surfaces** where a declaration makes them decidable —
+`hosts` at `Net` calls, `tables` at `Db` calls (SQL table positions, mirroring the Rust/JVM
+extractors exactly, **plus TypeORM's `@Entity("user")` declarations** read through the receiver's
+`Repository<T>` type argument), `cmds` at `Exec`, path-shaped `paths` at `Fs` — never from a
+runtime-computed value, propagated transitively, enforced by the `allow` rules above. On a real
+Nest app this makes table-level policy live: `allow Db in article.service article comments` flags
+the service reaching `user` and `follows`.
+
+**The classifier** is curated (the same under-report-and-say-so posture as the other engines): the
+Node builtins (`fs`, `net`/`http`/`tls`, `child_process`, `node:sqlite`, `process.env`, the clock)
+plus a small npm tier (axios/got/node-fetch/undici/ws, pg/mysql2/mongodb/redis/knex,
+execa/cross-spawn, fs-extra/rimraf/glob, dotenv, winston/pino). An unlisted package contributes
+nothing — candor never guesses an effect.
+
+## Trust contract (spec §4)
+
+Anything candor-ts can't resolve is `Unknown`, never silently pure: a function-valued parameter or
+field being called, an `any`-typed callee, resolution landing on a type rather than a body.
+Real-world consequence, measured on [rimraf](https://github.com/isaacs/rimraf) (50 files, 55
+functions analyzed): its DI-style fs injection means many functions honestly read `Unknown` —
+that's the contract working, not noise. The report says "can reach", never "does"; an absent
+literal is never a claim of absence.
+
+## Cross-engine consistency — machine-checked
+
+candor-ts runs live in the spec's conformance CI as the third engine in **three differentials**:
+the effect-set oracle (20 shared cases), the §6.2 policy-grammar battery (including `allow Db`),
+and the §3.1 query-shape and match-ladder checks — all three engines must answer identically, on
+every push to the spec.
+
+## What the analysis core implements (and where the spec told it how)
+
+| Piece | Spec source |
+|---|---|
+| Resolve every call via the compiler API (`getResolvedSignature`), never syntax | CLASSIFIER §1 |
+| κ classifies the resolved target's module (`node:fs`→Fs, `node:net`→Net, …) | CLASSIFIER §2, TS notes |
+| `process.env` property read → Env; `Date.now` → Clock | SPEC §1 |
+| Local edges (cross-file) + least-fixpoint propagation | SEMANTICS §5a |
+| Closure bodies attribute to the nearest enclosing function | SEMANTICS §2 |
+| A call resolving to a *type* (function-typed field/param) → `Unknown`, never silent-pure | SPEC §4 |
+| Unmatched external calls contribute nothing (curated-κ caveat) | SEMANTICS §8 C1 |
+| The literal surfaces `hosts`/`cmds`/`paths`/`tables`, literal-read only | SPEC §2 |
+| `{ candor: { version, toolchain, spec: "0.4" }, functions }` envelope; pure fns omitted | SPEC §2/§2.1 |
+| Call-graph sidecar with **every** analyzed function a key | SPEC §2.2 |
+| The gate: AS-EFF-006 / 008 / 009, loud on an unreadable policy | SPEC §6.2 |
+
+## Origin: the derivability proof
+
+This engine began as a deliberately minimal single-file slice written **from the spec documents
+alone** (SPEC.md, SEMANTICS.md, CLASSIFIER.md) — without consulting the Rust or JVM sources — to
+answer executably: *is the spec enough to derive a new-language implementation?* **Yes — 20/20** on
+the shared oracle. That clean-room claim is frozen at commit `a29b152`; everything since
+(multi-file projects, the query surface, the gate, the literal surfaces) is spec-implemented but
+post-hoc, and its guarantee is the conformance differential above, not clean-room provenance. The
+one engine-fix the original derivation needed (a call landing on a function-*type* declaration read
+as pure until §4 was applied to it) remains the proof point: the fix was "do what §4 says", not "go
+read the Rust source".
+
+## Status
+
+Young product (0.1.x): the analysis core, the gate, and the query surface are real,
+behaviorally tested (`node test.mjs`), **soundness-fuzzed with verified teeth** (`node fuzz.mjs` —
+spec §7.13: generated effect chains through every encoded call form, any silent-pure = red), and
+conformance-held. The npm classifier tier is
+deliberately curated and will keep growing case-by-case. Entry points (Nest/Next populations),
+`unknownWhy` origins, `reachable`, cross-package inheritance (`CANDOR_DEPS` + the spec §2 `hash`,
+version-trusted per §2.1), and `--allow-js` are all in. Not yet on npm — run from the clone.

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "candor-ts",
+  "version": "0.4.0",
+  "description": "candor for TypeScript — per-function side effects, transitively, with a policy gate (candor-spec 0.4)",
+  "type": "module",
+  "dependencies": {
+    "@types/node": "^25.9.2",
+    "typescript": "^6.0.3"
+  },
+  "bin": {
+    "candor-ts": "./scan.mjs",
+    "candor-ts-query": "./query.mjs"
+  },
+  "scripts": {
+    "test": "node test.mjs"
+  },
+  "license": "(MIT OR Apache-2.0)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tombaldwin/candor-ts.git"
+  },
+  "homepage": "https://candor.poly.io",
+  "keywords": [
+    "effects",
+    "static-analysis",
+    "side-effects",
+    "call-graph",
+    "policy",
+    "candor"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "scan.mjs",
+    "query.mjs",
+    "policy.mjs",
+    "README.md",
+    "AGENTS.md",
+    "PROVE-IT.md",
+    "LICENSE-MIT",
+    "LICENSE-APACHE"
+  ]
+}