@niscorp/haptic 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/ARTIFACTS.md CHANGED
@@ -112,7 +112,7 @@ A **record stage** (`"kind": "records", "format": "html"`):
112
112
 
113
113
  | Key | Meaning |
114
114
  | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
115
- | `render` | `true` runs the page's own inline scripts before reading it (no network; for addresses or content that a script writes). |
115
+ | `render` | `true` runs the page's own inline scripts before reading it, for addresses or content that a script writes (Node 25 or later, with no network; an earlier Node reads the page as fetched). |
116
116
  | `selector` | CSS for one record. |
117
117
  | `fields` | Field name to a field rule (below). |
118
118
  | `required` | Field names; a record without a non-empty value for one of them is left out. |
package/DESIGN.md CHANGED
@@ -65,7 +65,9 @@ Every model call goes through one module (`calls.ts`): it counts tokens, stops n
65
65
 
66
66
  ## Rendering
67
67
 
68
- jsdom runs the page's own inline scripts with no network and no external files, 600 ms for timers. It runs in a child process under Node's permission model (it reads only its own folder and jsdom's, writes nothing, starts no process), with an empty environment, killed after each page or at 15 s. A page that cannot be rendered is read as fetched. Node's permission model does not close the network; a host that needs that wraps the process in an OS sandbox.
68
+ jsdom runs the page's own inline scripts and loads no external files, 600 ms for timers. jsdom is not a sandbox: a page's script reaches Node itself in the process it runs in, so that process's limits are what hold it. It runs in a child process under Node's permission model: it reads only its own folder and jsdom's, writes nothing, starts no process and opens no connection. `process.kill` and `process._debugProcess` are removed before the page runs, because the permission model would let the script signal any process of the same user, or open another Node process's inspector and run code there. Its environment is empty (on Windows, Node passes on the variables Windows requires: `PATH`, `TEMP`, `USERNAME` and the like). It is killed after each page or at 15 s.
69
+
70
+ Node's permission model closes the network from Node 25. On an earlier Node nothing is rendered, because the script could reach any address, private ones included, past the host's transport. A page that is not rendered is read as fetched.
69
71
 
70
72
  ## Modules
71
73
 
package/README.md CHANGED
@@ -7,7 +7,7 @@ discover({ url, instruction }) → artifact (data) → prepareArtifact(artif
7
7
  search({ instruction }) → one artifact per useful source
8
8
  ```
9
9
 
10
- Scheduling, storage and what happens with the data belong to the caller. The package is private until its first release.
10
+ Scheduling, storage and what happens with the data belong to the caller.
11
11
 
12
12
  ## Run an artifact (no model)
13
13
 
@@ -26,7 +26,7 @@ try {
26
26
  }
27
27
  ```
28
28
 
29
- `prepareArtifact` refuses an artifact whose shape, field names, selectors, Prism programs or output schema are wrong, and names the place of each problem. A run fetches the pages, runs a page's own scripts first when the artifact says so, follows its link stages, reads its records, runs its Prism program and checks the result against its output schema. This entry point never loads a model package.
29
+ `prepareArtifact` refuses an artifact whose shape, field names, selectors, Prism programs or output schema are wrong, and names the place of each problem. A run fetches the pages, runs a page's own scripts first when the artifact says so (on Node 25 or later, which closes the network to them; an earlier Node reads the page as fetched), follows its link stages, reads its records, runs its Prism program and checks the result against its output schema. This entry point never loads a model package.
30
30
 
31
31
  An artifact does not have to come from discovery: a person, a model or a tool can write one. `prepared.inspect({ url }, options)` runs it like `run`, but returns what each page gave at each stage (elements matched, records left out and why, fields left empty) and the records the program saw, even when the run stops. [ARTIFACTS.md](ARTIFACTS.md) is the format, with a hand-written example.
32
32
 
package/STATUS.md CHANGED
@@ -31,6 +31,7 @@ Before this round of work (2026-11-14): held-out 18, 20, 19 of 33; tuned 48, 46,
31
31
  - **Valid but wrong answers** pass every check: a reader that reads "modules" literally. When a field cites a link's address and no field cites that line's text, strict discovery asks Read once which it meant.
32
32
  - **Bot checks** other than DuckDuckGo's image challenge are not detected; PyPI's "Client Challenge" page is why that case left the held-out set.
33
33
  - **Fields across levels** cannot be combined: the program sees only the last level's records.
34
+ - **Rendering needs Node 25 or later**: an earlier Node cannot close the network to a page's scripts, so there the page is read as fetched, and a page whose links a script writes gives its placeholder links.
34
35
  - **Rendering costs about 1.4 s per rendered page** (0.85 s of it starting the process and loading jsdom), twice per discovery: once in the attempt, once in the trial.
35
36
 
36
37
  ## Not built yet
@@ -42,7 +43,7 @@ Before this round of work (2026-11-14): held-out 18, 20, 19 of 33; tuned 48, 46,
42
43
 
43
44
  ## Checking a change
44
45
 
45
- - `pnpm check`: build and the offline tests (no model, no network): the runtime, the four saved discovery runs replayed through `discover` with their recorded model answers, search rounds, the image challenge, readers and transport.
46
+ - `pnpm check`: build and the offline tests (no model, no network): the runtime, the four saved discovery runs replayed through `discover` with their recorded model answers, search rounds, the image challenge, readers and transport. Rendering itself is checked only on Node 25 or later; an earlier Node checks that it is refused.
46
47
  - `pnpm check:package`: the packed package in a fresh consumer runs generated artifacts with every model import refused, and its entry points typecheck with and without the optional peers.
47
48
  - `pnpm check:grammars` (repository root): the `nisc.haptic` grammar against its snapshot, and the captured artifacts upgraded and parsed.
48
49
  - `pnpm bench --set=<set> --round=<name>`, three rounds, then `pnpm grade --set=<set> --round=<a>,<b>,<c>`: each set live (needs `GROQ_API_KEY` and `TYPESAFE_API_KEY` in `.env`; about 0.8M input tokens per tuned round, 1.2M per held-out round), graded with the spread across rounds. A second bench refuses to start while one runs. A change counts when it moves the result beyond that spread.
@@ -1,3 +1,10 @@
1
+ // Runs in its own process under Node's permission model, with an empty environment. jsdom is imported by the absolute
2
+ // address the parent passes, so no package lookup outside the allowed folders happens. Reads { html, url, waitMs } on
3
+ // stdin, runs the page's inline scripts (jsdom loads no external files), waits for timers, writes the page on stdout.
4
+ // The page's scripts reach this process; the permission model still lets it signal any process of the same user and
5
+ // open another Node process's inspector, so those calls are gone before the page runs.
6
+ for (const name of ['kill', '_kill', '_debugProcess'])
7
+ Reflect.deleteProperty(process, name);
1
8
  const jsdomUrl = process.argv[2];
2
9
  if (!jsdomUrl)
3
10
  throw new Error('jsdom address missing');
@@ -29,10 +29,15 @@ const jsdomFiles = () => {
29
29
  folder: modules >= 0 ? entry.slice(0, modules + `${sep}node_modules`.length) : dirname(entry),
30
30
  };
31
31
  };
32
+ // A page's scripts reach Node itself in the child (jsdom is not a sandbox), so the child's limits are all that hold
33
+ // them. Node closes the network to a process run with --permission from version 25, the first to know --allow-net.
34
+ const closesNetwork = process.allowedNodeEnvironmentFlags.has('--allow-net');
32
35
  // The page as its own inline scripts leave it. Runs in a child process: Node's permission model (it reads only its
33
- // own folder and jsdom's, so not the package folder with its .env; no writes, no child processes), an empty
34
- // environment, no external files, killed at the cap.
36
+ // own folder and jsdom's, so not the package folder with its .env; no writes, no child processes, no network), an
37
+ // empty environment, no external files, killed at the cap. Refused on a Node that cannot close the network.
35
38
  export const renderHtml = (html, url, options = {}) => {
39
+ if (!closesNetwork)
40
+ return Promise.reject(new Error("rendering needs Node 25 or later: earlier versions cannot close the network to a page's scripts"));
36
41
  const script = childScript();
37
42
  const jsdom = jsdomFiles();
38
43
  const waitMs = options.waitMs ?? WAIT_MS;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@niscorp/haptic",
3
- "version": "0.1.0",
3
+ "version": "0.2.0",
4
4
  "type": "module",
5
5
  "description": "Request and URL to reusable JSON artifacts; deterministic HTTP, HTML, JSON and XML execution.",
6
6
  "license": "Apache-2.0",
@@ -27,9 +27,9 @@
27
27
  "peerDependencies": {
28
28
  "imagescript": "^3.14.0",
29
29
  "openai": "^7.51.0",
30
- "zod": "^4.6.5",
30
+ "zod": "^4.2.0",
31
31
  "@niscorp/cortex": "^0.1.6",
32
- "@niscorp/prism": "^0.3.3",
32
+ "@niscorp/prism": "^0.3.4",
33
33
  "@niscorp/signal": "^0.1.9",
34
34
  "@niscorp/strata": "^0.1.9"
35
35
  },
@@ -56,10 +56,10 @@
56
56
  "tsx": "4.23.15",
57
57
  "typescript": "^6.0.2",
58
58
  "zod": "^4.6.5",
59
+ "@niscorp/signal": "0.1.9",
59
60
  "@niscorp/cortex": "0.1.6",
60
- "@niscorp/prism": "0.3.3",
61
- "@niscorp/strata": "0.1.9",
62
- "@niscorp/signal": "0.1.9"
61
+ "@niscorp/prism": "0.3.4",
62
+ "@niscorp/strata": "0.1.9"
63
63
  },
64
64
  "files": [
65
65
  "dist",