@potential-guide/check-environment 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 shazhou-ww
+
+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/README.md

@@ -1,3 +1,214 @@
-# Temporary Holding Version
+# Environment check bundles
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Three reusable checks share a library and build into **three independent Task
+Bundles**: `tools`, `directories`, and `network`. No Objective levels, repair
+agents, package installation or long-running sampling are built into them.
+
+```powershell
+pnpm --filter @potential-guide/check-environment... build
+```
+
+The package contains `dist/bundles/<kind>/task.yaml`, the self-contained
+`worker.cjs`, and the distributable `dist/bundles/<kind>.car`.
+`dist/bundles/references.json` records each relative `directory`, `car` and
+standard UnixFS root `cid`. The CAR and directory describe the same file tree
+and root CID; there is no parallel Bundle digest. Build output is ignored by Git.
+
+## Standard author pipeline
+
+The three `*.check.build.yaml` files are the only author declarations.
+Their problemCodes generate the literal business types, runtime allowed-code
+list, result Schema and Reference coverage matrix through
+[`check-sdk/authoring`](../check-sdk/README.md).
+The first stage snapshots source, generated code definitions and validated
+Reference bytes into `dist/staging/<kind>/`, including a generated
+`task.build.yaml` with explicit `runTask` entry and exact resource includes.
+The second stage uses the ordinary Task Bundle `buildTask` API.
+It reads only those fixed business inputs, not the live source or Reference
+directories. No Check-specific compiler is added.
+
+Before acceptance the orchestration compares CAR and directory CIDs and exact
+resource bytes. All three candidates must succeed before `dist/bundles/` and
+its final references.json are replaced together; failures retain accepted
+artifacts and references. Staging and candidate outputs are not release inputs.
+
+Each Bundle contains `schemas/`, `resources/check.json`, and only its own
+`resources/references/en/check.md` plus `problems/<code>.md`. Read them through
+`ipfs://<CID>/resources/references/en/check.md` or the resource index. Reference
+frontmatter accepts only title and description (nonempty, description <=200
+Unicode code points). Filename/language/problem coverage and exact bytes are
+gated; Markdown bodies, sections and links are deliberately not validated.
+Language completeness is declared per Check, with no automatic fallback.
+
+## Migration and entry points
+
+The three Task Bundles are the execution entry points. The retired Check Host
+is not restored, and no old Host command, registration or compatibility forwarding
+is provided. Import/pin the emitted CAR and submit its root CID to the Engine;
+do not submit an npm package name or an old Checker digest as a Bundle.
+
+The library exports (`checkTools`, `checkDirectories`, `checkNetwork`, version
+helpers and the directory write probe) remain shared implementations, not legacy
+task entry points. Existing Objective Workers still consume them without child
+Task scheduling. Removing them would break those consumers rather than migrate
+an old runner. This scope does not migrate `pnpm check`, repository/package
+standardization, devbox-health or setup/self-check Objectives.
+
+## Inputs
+
+Tool versions (numeric dot-separated versions, not npm semver ranges):
+
+```json
+{
+  "tools": [
+    {"command": "node", "args": ["--version"], "minimumVersion": "22.13.0"}
+  ],
+  "checkTimeoutMs": 5000
+}
+```
+
+Version output uses the same numeric version parser as devbox-health. Commands
+run without a shell. On Windows, use a native executable or `node` with the
+absolute JavaScript CLI entry in `args`, not `.cmd`/`.bat` shims. Tools remain
+external prerequisites; the bundle does not install them. Tool launch, timeout,
+output-limit and cleanup faults fail the Run rather than manufacture a gap.
+
+Directories (absolute paths on the **execution machine**):
+
+```json
+{
+  "directories": [
+    {"path": "D:\\Code\\demo", "requirements": ["exists", "read"]},
+    {"path": "D:\\TaskScratch", "requirements": ["exists", "write"]}
+  ]
+}
+```
+
+All entries must be existing directories, not final-component symbolic links.
+`read` checks read/traversal access; `write` creates an exclusive temporary file,
+reads it back and removes it, including on cancellation. No business directory
+is created and no permissions are changed. Ownership and canonical-path
+requirements remain Objective policy, not generic requirements.
+
+DNS and HTTP:
+
+```json
+{
+  "dns": ["localhost"],
+  "http": [
+    {"url": "http://127.0.0.1:8080/health", "expectedStatus": [200], "followRedirects": false}
+  ],
+  "checkTimeoutMs": 4000
+}
+```
+
+At least one DNS or HTTP check is required. Each endpoint has an independent
+timeout. HTTP(S) URLs cannot embed credentials. Redirects are rejected unless
+explicitly enabled. Responses are not downloaded; their bodies are cancelled.
+DNS resolves in a bounded subprocess so cancellation cannot leave a native
+lookup running inside the Worker. Timeout/cancellation is an execution fault,
+not evidence that an endpoint is unavailable.
+
+`checkTimeoutMs` is the per-command/endpoint business budget (default 5000ms).
+The Task Request's separate `timeoutMs` controls task eligibility/lifetime and
+is reserved by the Engine; it is not passed to the business callback.
+
+Each list is bounded to 100 items. The message contract is TypeBox `Never`
+(equivalent to JSON Schema `false`); the checks do not
+accept business messages. Request/Run cancellation still works through the SDK.
+
+## Results and submission
+
+A passing check returns exactly:
+
+```json
+{"pass": true}
+```
+
+A completed check with unmet requirements returns only actual problems:
+
+```json
+{
+  "pass": false,
+  "problems": [
+    {"target": "node", "code": "tool-version", "actual": "20.0.0"}
+  ]
+}
+```
+
+Passing items are omitted. Each problem includes `target`, `code`, and nullable
+`actual`. Failure results require a nonempty `problems` array; passing results
+have no `problems` field. Neither variant includes `checks` or `ok`. Invocation
+faults still fail the Run, not return a check result.
+
+Per-item verbose diagnostics do not belong in Result. The Task SDK supports
+separate bounded Run diagnostics through `context.log`; see
+[Run logs](../../docs/task-run-logs.md). These checks currently emit no diagnostic
+logs and do not repurpose progress or checkpoint as verbose output.
+Console stderr is not a task-history logging channel. Log availability never
+replaces the declared result, failure or physical release evidence.
+
+Changing the business result contract changes the Bundle CID. Rebuild and
+use the new reference from `references.json`; existing CID-addressed content
+retain their original contracts.
+
+After building, import and pin the emitted CAR using an external tool of your
+choice and submit its root CID. For example, with a caller-managed local Kubo:
+
+```powershell
+ipfs dag import --pin-roots=true packages\check-environment\dist\bundles\tools.car
+```
+
+The Engine must be started, authorized and able to fetch the pinned CID through
+its configured IPFS client. Normal task observation is unchanged:
+
+```js
+import {readFile} from "node:fs/promises";
+import {join, resolve} from "node:path";
+
+const directory = resolve("packages", "check-environment", "dist", "bundles");
+const refs = JSON.parse(await readFile(join(directory, "references.json"), "utf8"));
+await engine.submit({
+  requestId,
+  bundle: refs.tools.cid,
+  tools: [{command: process.execPath, args: ["--version"], minimumVersion: "22.13.0"}],
+  timeoutMs: 5000
+}, caller);
+```
+
+Production delivery imports/pins the CAR on the caller-managed node and
+publishes root CID references, optionally with gateway hints. Do not use
+`latest` as executable identity. npm delivers the author/library package;
+the generic Engine does not install it. This change adds local delivery
+verification only, not publication workflows or release authorization.
+
+## Regression verification
+
+```powershell
+pnpm --filter @potential-guide/check-environment... build
+pnpm --filter @potential-guide/check-environment test
+```
+
+The Engine regression imports the emitted CARs, verifies equality with their
+directory trees and root CIDs, runs passing and unmet-requirement inputs for all
+three bundles, and waits for physical release. Tool timeout/output overflow,
+invalid directory paths and HTTP timeout must fail the Run without a fabricated
+check result. Cancellation of an active HTTP request must stop and release the
+Run without a result. Library tests additionally verify process cancellation,
+write-probe cleanup, DNS, HTTP redirects and numeric version handling.
+
+## Objective integration
+
+The same write/readback probe is reused by devbox-health and pguide setup
+(including self-check). Devbox-health also reuses version parsing/comparison.
+Its ownership/canonical-path rules, stage deadlines, command evidence, problem
+IDs and actual compiler/runtime smoke tests remain in the Objective.
+
+These existing Objective Workers call shared library code, bundled into their
+own artifacts; they do **not** submit child Tasks to an Engine. The independent
+bundles use the same implementations and are separately exercised through the
+real Engine in tests. Network checks currently have an independent consumer
+surface; devbox-health keeps its original network execution/evidence path.
+
+Workers are not security sandboxes. Admit tool commands, filesystem paths and
+network targets only from authorized callers in a trusted execution environment.

package/dist/bundles/directories/resources/check.json

@@ -0,0 +1,19 @@
+{
+  "kind": "directories",
+  "languages": [
+    "en"
+  ],
+  "problemCodes": [
+    "not-directory",
+    "directory-unusable"
+  ],
+  "references": {
+    "en": {
+      "check": "resources/references/en/check.md",
+      "problems": {
+        "not-directory": "resources/references/en/problems/not-directory.md",
+        "directory-unusable": "resources/references/en/problems/directory-unusable.md"
+      }
+    }
+  }
+}

package/dist/bundles/directories/resources/references/en/check.md

@@ -0,0 +1,18 @@
+---
+title: Directory access
+description: Check absolute directory paths and explicit exists, read or write requirements.
+---
+
+# Directory access
+
+Input `directories` lists absolute `path` and nonempty `requirements` from
+`exists`, `read`, `write`. Symlinks are not accepted as directories.
+Read uses host access checks. Write creates an exclusive probe file, reads it
+back and deletes it in `finally`; it does not modify existing files.
+The Engine host must have the requested permissions.
+
+Results contain only failures: [not-directory](problems/not-directory.md) or
+[directory-unusable](problems/directory-unusable.md). `target` is the absolute
+path; `actual` is the filesystem error code or null. Invalid input, unexpected
+filesystem errors, readback mismatch and cleanup errors remain execution
+faults. Cancellation propagates after probe cleanup. No repair is performed.

package/dist/bundles/directories/resources/references/en/problems/directory-unusable.md

@@ -0,0 +1,10 @@
+---
+title: Directory unavailable
+description: The directory is missing or requested access failed with a recognized filesystem error.
+---
+
+`target` is the absolute directory path; `actual` is ENOENT, ENOTDIR, EACCES,
+EPERM, EROFS, ENOSPC or EDQUOT. Check path, permissions, filesystem capacity and
+mount state. Resolve the cause separately; no repair is attempted.
+Unexpected errors and cleanup failures are faults, not this problem.
+See [directory checks](../check.md).

package/dist/bundles/directories/resources/references/en/problems/not-directory.md

@@ -0,0 +1,7 @@
+---
+title: Not a directory
+description: The path exists but is not an ordinary directory or is a symbolic link.
+---
+
+`target` is the requested absolute path; `actual` is null. Select an ordinary
+directory rather than a file or symlink. See [directory checks](../check.md).

package/dist/bundles/directories/schemas/0.json

@@ -0,0 +1,51 @@
+{
+  "additionalProperties": false,
+  "type": "object",
+  "required": [
+    "directories"
+  ],
+  "properties": {
+    "directories": {
+      "minItems": 1,
+      "maxItems": 100,
+      "type": "array",
+      "items": {
+        "additionalProperties": false,
+        "type": "object",
+        "required": [
+          "path",
+          "requirements"
+        ],
+        "properties": {
+          "path": {
+            "minLength": 1,
+            "maxLength": 4096,
+            "type": "string"
+          },
+          "requirements": {
+            "minItems": 1,
+            "uniqueItems": true,
+            "type": "array",
+            "items": {
+              "anyOf": [
+                {
+                  "const": "exists",
+                  "type": "string"
+                },
+                {
+                  "const": "read",
+                  "type": "string"
+                },
+                {
+                  "const": "write",
+                  "type": "string"
+                }
+              ]
+            }
+          }
+        }
+      }
+    }
+  },
+  "$id": "https://task.invalid/schema/input"
+}

package/dist/bundles/directories/schemas/1.json

@@ -0,0 +1,74 @@
+{
+  "anyOf": [
+    {
+      "additionalProperties": false,
+      "type": "object",
+      "required": [
+        "pass"
+      ],
+      "properties": {
+        "pass": {
+          "const": true,
+          "type": "boolean"
+        }
+      }
+    },
+    {
+      "additionalProperties": false,
+      "type": "object",
+      "required": [
+        "pass",
+        "problems"
+      ],
+      "properties": {
+        "pass": {
+          "const": false,
+          "type": "boolean"
+        },
+        "problems": {
+          "minItems": 1,
+          "type": "array",
+          "items": {
+            "additionalProperties": false,
+            "type": "object",
+            "required": [
+              "target",
+              "code",
+              "actual"
+            ],
+            "properties": {
+              "target": {
+                "minLength": 1,
+                "maxLength": 4096,
+                "type": "string"
+              },
+              "code": {
+                "anyOf": [
+                  {
+                    "const": "not-directory",
+                    "type": "string"
+                  },
+                  {
+                    "const": "directory-unusable",
+                    "type": "string"
+                  }
+                ]
+              },
+              "actual": {
+                "anyOf": [
+                  {
+                    "type": "string"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ]
+              }
+            }
+          }
+        }
+      }
+    }
+  ],
+  "$id": "https://task.invalid/schema/result"
+}

package/dist/bundles/directories/schemas/2.json

@@ -0,0 +1,4 @@
+{
+  "not": {},
+  "$id": "https://task.invalid/schema/message"
+}

package/dist/bundles/directories/task.yaml

@@ -0,0 +1,22 @@
+$schema: https://shazhou-ww.github.io/potential-guide/schemas/artifacts/task/v1.json
+name: Environment directories check
+runtime:
+  type: node
+  minVersion: 22.13.0
+entry: worker.cjs
+inputSchema:
+  $ref: schemas/0.json
+resultSchema:
+  $ref: schemas/1.json
+messageSchema:
+  $ref: schemas/2.json
+include:
+  - resources/check.json
+  - resources/references/en/check.md
+  - resources/references/en/problems/directory-unusable.md
+  - resources/references/en/problems/not-directory.md
+  - schemas/0.json
+  - schemas/1.json
+  - schemas/2.json
+  - task.yaml
+  - worker.cjs

package/dist/bundles/directories/worker.cjs

@@ -0,0 +1,4 @@
+const __artifactURL = require("node:url").pathToFileURL(__filename).href;
+"use strict";function G(o){if(new Set(o).size!==o.length||o.some(n=>!/^[a-z][a-z0-9-]*$/.test(n)||n.length>4096))throw new Error("Check problem codes must be unique stable names of at most 4096 characters.")}function de(o,n){G(o);let i=new Set(o),r=n.map(a=>{if(!i.has(a.code))throw new Error(`Undeclared Check problem code: ${a.code}`);if(typeof a.target!="string"||!a.target.length||[...a.target].length>4096||a.actual!==null&&typeof a.actual!="string"||Object.keys(a).some(m=>!["target","code","actual"].includes(m)))throw new Error("Invalid Check problem.");return{target:a.target,code:a.code,actual:a.actual}});return r.length?{pass:!1,problems:r}:{pass:!0}}function Q(o,n){return async(i,r)=>{r.signal.throwIfAborted();let a=await n(i,r);return r.signal.throwIfAborted(),de(o,a)}}var F=require("node:worker_threads");var u=class extends Error{code;details;constructor(n,i,r){super(i),this.code=n,this.details=r,this.name="TaskError"}};function b(o,n){throw new u(o,n)}function N(o,n=65536){let i=new Set,r=0;function a(s,k){if((++r>n||k>64)&&b("invalid_payload","JSON structure exceeds limit."),s===null||typeof s=="string"||typeof s=="boolean"||typeof s=="number"&&Number.isFinite(s))return s;(typeof s!="object"||s===null)&&b("invalid_payload","Only finite JSON values are accepted."),i.has(s)&&b("invalid_payload","Cyclic JSON is not accepted.");let E=Array.isArray(s);Object.getPrototypeOf(s)!==(E?Array.prototype:Object.prototype)&&b("invalid_payload","Custom prototypes are not accepted."),i.add(s);let f=Object.getOwnPropertyDescriptors(s),w=Reflect.ownKeys(f),T={},C=[];E&&w.length!==s.length+1&&b("invalid_payload","Sparse or decorated arrays are not accepted.");for(let I of w){typeof I!="string"&&b("invalid_payload","Symbol keys are not accepted.");let x=f[I];(!x||!("value"in x))&&b("invalid_payload","Accessors are not accepted."),!(E&&I==="length")&&(x.enumerable||b("invalid_payload","Hidden properties are not accepted."),E?(I!==String(C.length)&&b("invalid_payload","Invalid array keys."),C.push(a(x.value,k+1))):Object.defineProperty(T,I,{value:a(x.value,k+1),enumerable:!0,writable:!0,configurable:!0}))}return i.delete(s),E?C:T}let m=a(o,0);return new TextEncoder().encode(JSON.stringify(m)).byteLength>n&&b("payload_too_large","JSON payload exceeds byte limit."),m}function A(o){return Array.isArray(o)?`[${o.map(A).join(",")}]`:o&&typeof o=="object"?`{${Object.keys(o).sort().map(n=>`${JSON.stringify(n)}:${A(o[n]??null)}`).join(",")}}`:JSON.stringify(o)}var R=class extends u{result;constructor(n,i,r){super(n,i),this.result=r}};var B="https://shazhou-ww.github.io/potential-guide/schemas/artifacts/task/v1.json";var K={declaration:JSON.parse('{"$schema":"https://shazhou-ww.github.io/potential-guide/schemas/artifacts/task/v1.json","name":"Environment directories check","runtime":{"type":"node","minVersion":"22.13.0"},"entry":"worker.cjs","inputSchema":{"additionalProperties":false,"type":"object","required":["directories"],"properties":{"directories":{"minItems":1,"maxItems":100,"type":"array","items":{"additionalProperties":false,"type":"object","required":["path","requirements"],"properties":{"path":{"minLength":1,"maxLength":4096,"type":"string"},"requirements":{"minItems":1,"uniqueItems":true,"type":"array","items":{"anyOf":[{"const":"exists","type":"string"},{"const":"read","type":"string"},{"const":"write","type":"string"}]}}}}}}},"resultSchema":{"anyOf":[{"additionalProperties":false,"type":"object","required":["pass"],"properties":{"pass":{"const":true,"type":"boolean"}}},{"additionalProperties":false,"type":"object","required":["pass","problems"],"properties":{"pass":{"const":false,"type":"boolean"},"problems":{"minItems":1,"type":"array","items":{"additionalProperties":false,"type":"object","required":["target","code","actual"],"properties":{"target":{"minLength":1,"maxLength":4096,"type":"string"},"code":{"anyOf":[{"const":"not-directory","type":"string"},{"const":"directory-unusable","type":"string"}]},"actual":{"anyOf":[{"type":"string"},{"type":"null"}]}}}}}}]},"messageSchema":{"not":{}},"include":["resources/check.json","resources/references/en/check.md","resources/references/en/problems/directory-unusable.md","resources/references/en/problems/not-directory.md","schemas/0.json","schemas/1.json","schemas/2.json","task.yaml","worker.cjs"]}')};var W=class{capacity;queue=[];waiter;closed=!1;constructor(n){this.capacity=n}push(n){if(this.closed||this.queue.length>=this.capacity)throw new Error("Task inbox unavailable.");this.waiter?(this.waiter({done:!1,value:n}),this.waiter=void 0):this.queue.push(n)}close(){this.closed=!0,this.queue=[],this.waiter?.({done:!0,value:void 0}),this.waiter=void 0}[Symbol.asyncIterator](){return{next:()=>{let n=this.queue.shift();return n?Promise.resolve({done:!1,value:n}):this.closed?Promise.resolve({done:!0,value:void 0}):this.waiter?Promise.reject(new Error("Task inbox has one consumer.")):new Promise(i=>{this.waiter=i})}}}};function Y(o){if(!K)throw new Error("Task SDK requires a build-locked Bundle binding.");let{declaration:n}=K,i=F.parentPort;if(!i||n.$schema!==B)throw new Error("Unsupported Task Worker.");let r=F.workerData;if(typeof r.generation!="string"||!r.generation||!Number.isSafeInteger(r.maxInFlight)||r.maxInFlight<=0||!Number.isSafeInteger(r.maxPayloadBytes)||r.maxPayloadBytes<=0||typeof r.bundle?.cid!="string"||!r.bundle.cid||r.bundle.cid.length>256)throw new Error("Invalid trusted Task Worker configuration.");if(!r.bundle||A(N(r.bundle.declaration,1048576))!==A(N(n,1048576)))throw new Error("Task Worker declaration differs from verified Bundle.");let a=new AbortController,m=new W(r.maxInFlight),s=new Map,k=new Map,E=0,f,w=!1,T=0,C=!1,I=Promise.resolve(),x,oe=0,q=new Map;function ie(t,p={}){let d=++oe,e=p.signal?AbortSignal.any([a.signal,p.signal]):a.signal,c=()=>{},g=()=>{c(),q.get(d)?.reject(new DOMException("Bundle read canceled.","AbortError")),q.delete(d),i.postMessage({generation:r.generation,runId:f,kind:"bundle-cancel",readId:d})};return new ReadableStream({start(h){let l=()=>{g(),h.error(e.reason)};if(c=()=>e.removeEventListener("abort",l),e.aborted){h.error(e.reason);return}e.addEventListener("abort",l,{once:!0})},async pull(h){try{if(w)throw new u("run_finished","Bundle stream is closed.");e.throwIfAborted();let l=await new Promise((O,ce)=>{q.set(d,{resolve:O,reject:ce}),i.postMessage({generation:r.generation,runId:f,kind:"bundle-pull",readId:d,path:t})});if(l.done)c(),h.close();else if(l.chunk instanceof Uint8Array)h.enqueue(l.chunk);else throw new u("invalid_bundle","Invalid Bundle stream chunk.")}catch(l){g(),h.error(l)}},cancel:g},{highWaterMark:0})}let D=0,S=new Map,P=0,z=0,$=!1,_=!1,X=!1,y;function ae(){if(y||_||w||a.signal.aborted||P<=z)return;let t=++D,p=P,d=setTimeout(()=>{_=!0},1e3);y={id:t,count:p,timer:d};try{i.postMessage({generation:r.generation,runId:f,kind:"log-drop",logId:t,count:p})}catch{clearTimeout(d),y=void 0,_=!0}}function Z(){$||y||_||w||a.signal.aborted||($=!0,queueMicrotask(()=>{$=!1,ae()}))}function v(){if(!(X||P<=z)){X=!0;try{i.postMessage({generation:r.generation,runId:f,kind:"log-drop",logId:++D,count:P,final:!0})}catch{}}}function U(){y&&clearTimeout(y.timer),y=void 0,_=!0;for(let t of S.values())clearTimeout(t.timer),t.resolve({state:"unavailable",reason:"channel"});S.clear()}async function se(t){if(w||a.signal.aborted)return{state:"unavailable",reason:"channel"};if(S.size>=Math.min(r.maxInFlight,16))return P=Math.min(Number.MAX_SAFE_INTEGER,P+1),Z(),{state:"dropped",reason:"capacity"};let p=D+1;return new Promise((d,e)=>{let c=setTimeout(()=>{S.delete(p),d({state:"unavailable",reason:"timeout"})},1e3);S.set(p,{resolve:d,reject:e,timer:c});try{i.postMessage({generation:r.generation,runId:f,kind:"log",logId:p,value:t}),D=p}catch(g){clearTimeout(c),S.delete(p),g instanceof Error&&g.name==="DataCloneError"?e(new u("invalid_payload","Task payload cannot be cloned for IPC.")):d({state:"unavailable",reason:"channel"})}})}function M(t,p){if(k.size>=r.maxInFlight)return Promise.reject(new Error("Task channel capacity exceeded."));let d=E+1,e=new Promise((c,g)=>{k.set(d,{resolve:c,reject:g})});try{i.postMessage({generation:r.generation,runId:f,id:d,kind:t,value:p}),E=d}catch(c){k.get(d)?.reject(c instanceof Error&&c.name==="DataCloneError"?new u("invalid_payload","Task payload cannot be cloned for IPC."):c instanceof Error?c:new Error("Task send failed.")),k.delete(d)}return e}function J(t,p){if(w)return Promise.reject(new u("run_finished","Task is finishing."));if(T>=r.maxInFlight)return Promise.reject(new Error("Task channel capacity exceeded."));T++;let d=I.then(()=>M(t,p)).catch(e=>{throw x??=e,e}).finally(()=>{T--});return I=d,d.catch(()=>{}),d}i.postMessage({generation:r.generation,kind:"ready",value:{$schema:n.$schema,cid:r.bundle.cid,inputSchema:n.inputSchema,resultSchema:n.resultSchema,messageSchema:n.messageSchema}}),i.on("message",t=>{if(!t||t.generation!==r.generation)return;if(t.kind==="bundle-data"){let e=q.get(t.readId);if(!e)return;q.delete(t.readId),t.error?e.reject(new u(t.error.code,t.error.message)):e.resolve(t);return}if(t.kind==="log-drop-ack"){if(t.runId!==f||!y||t.logId!==y.id)return;let e=y;clearTimeout(e.timer),y=void 0,t.error||t.value?.state==="unavailable"?_=!0:(z=e.count,_=!1,Z());return}if(t.kind==="log-ack"){if(t.runId!==f)return;let e=S.get(t.logId);if(!e)return;S.delete(t.logId),clearTimeout(e.timer),t.error?e.reject(new u(t.error.code,t.error.message)):e.resolve(t.value);return}if(t.kind==="ack"){let e=k.get(t.id);if(!e)return;k.delete(t.id),t.error?e.reject(new u(t.error.code,t.error.message)):e.resolve();return}if(t.kind==="ping"){i.postMessage({generation:r.generation,kind:"pong"});return}if(t.runId!==f&&t.kind!=="run")return;if(t.kind==="cancel"){i.postMessage({generation:r.generation,runId:f,kind:"stopping"}),a.abort(),U(),m.close();for(let e of s.values())e.abort();return}if(t.kind==="withdraw"){let e=s.get(t.taskId)??new AbortController;s.set(t.taskId,e),e.abort();return}if(t.kind==="message"){let e=t.value,c=s.get(e.taskId)??new AbortController;s.set(e.taskId,c);let g=!1,h=(l,O)=>g||c.signal.aborted?Promise.reject(new Error("Message unavailable.")):(g=!0,J("message-confirm",{taskId:e.taskId,messageId:e.messageId,state:l,...O===void 0?{}:{reason:O}}));m.push(Object.freeze({messageId:e.messageId,taskId:e.taskId,caller:Object.freeze(e.caller),signal:c.signal,payload:e.payload,accept:()=>h("accepted"),reject:l=>h("rejected",l)}));return}if(t.kind!=="run"||f!==void 0)return;f=t.runId;let p=Object.freeze({runId:t.runId,...t.identity?{generation:t.identity.generation,startedAt:t.identity.startedAt}:{},scope:t.scope,signal:a.signal,messages:m,bundle:Object.freeze({read:ie}),progress:e=>J("progress",e),checkpoint:e=>J("checkpoint",e),log:se}),d=async e=>{let c=e;C||=c instanceof u&&["reclamation_failed","reclamation_unknown"].includes(c.code);let g=c instanceof R?c.result:void 0,h=(l,O)=>({code:l instanceof u?l.code.slice(0,128):"run_failed",message:l instanceof Error?l.message.slice(0,512):"Task callback failed.",...O===void 0?{}:{result:O}});try{await M("failed",h(c,g))}catch(l){await M("failed",h(l))}};(async()=>{try{let e=await o(t.input,p);if(w=!0,v(),await I,x!==void 0)throw x;await M("complete",e)}catch(e){w=!0,v(),await I.catch(()=>{}),C||=e instanceof u&&["reclamation_failed","reclamation_unknown"].includes(e.code);let c=x??e;if(a.signal.aborted&&c instanceof Error&&(c.name==="AbortError"||c instanceof u&&["ABORT_ERR","run_canceled"].includes(c.code)))return;await d(c)}})().then(()=>{m.close(),a.abort(),U();for(let e of s.values())e.abort();i.postMessage({generation:r.generation,runId:f,kind:C?"uncertain":"released"}),i.close()},()=>{m.close(),a.abort(),U();for(let e of s.values())e.abort();i.postMessage({generation:r.generation,runId:f,kind:"uncertain"}),i.close()})})}var V=Object.freeze(["not-directory","directory-unusable"]);var re=require("node:crypto"),H=require("node:fs"),j=require("node:fs/promises"),L=require("node:path");function ee(o){return o.filter(n=>!n.ok).map(({target:n,code:i,actual:r})=>{if(i==="pass")throw new Error("A failing check requires a problem code.");return{target:n,code:i,actual:r}})}function te(o){return o instanceof Error&&"code"in o&&typeof o.code=="string"?o.code:void 0}async function le(o,n){n?.throwIfAborted();let i=(0,L.join)(o,`.pguide-check-${(0,re.randomUUID)()}`),r=!1;try{if(await(0,j.writeFile)(i,`directory-check
+`,{flag:"wx",mode:384}),r=!0,n?.throwIfAborted(),await(0,j.readFile)(i,"utf8")!==`directory-check
+`)throw new Error("Directory write probe readback mismatch.")}finally{r&&await(0,j.rm)(i)}}async function ne(o,n={}){if(!o.directories.length||o.directories.length>100)throw new Error("Specify between 1 and 100 directories.");for(let r of o.directories)if(!(0,L.isAbsolute)(r.path)||r.path.includes("\0")||!r.requirements.length||r.requirements.some(a=>!["exists","read","write"].includes(a)))throw new Error("Directories require absolute paths and explicit access requirements.");let i=[];for(let r of o.directories){n.signal?.throwIfAborted();let a="pass",m=null;try{let s=await(0,j.lstat)(r.path);!s.isDirectory()||s.isSymbolicLink()?a="not-directory":(r.requirements.includes("read")&&await(0,j.access)(r.path,H.constants.R_OK|H.constants.X_OK),r.requirements.includes("write")&&await le(r.path,n.signal))}catch(s){if(n.signal?.throwIfAborted(),m=te(s)??null,m===null||!["ENOENT","ENOTDIR","EACCES","EPERM","EROFS","ENOSPC","EDQUOT"].includes(m))throw s;a="directory-unusable"}i.push({target:r.path,ok:a==="pass",code:a,actual:m})}return ee(i)}var ue=Q(V,ne);Y(ue);

package/dist/bundles/network/resources/check.json

@@ -0,0 +1,21 @@
+{
+  "kind": "network",
+  "languages": [
+    "en"
+  ],
+  "problemCodes": [
+    "dns-unavailable",
+    "http-status",
+    "http-unavailable"
+  ],
+  "references": {
+    "en": {
+      "check": "resources/references/en/check.md",
+      "problems": {
+        "dns-unavailable": "resources/references/en/problems/dns-unavailable.md",
+        "http-status": "resources/references/en/problems/http-status.md",
+        "http-unavailable": "resources/references/en/problems/http-unavailable.md"
+      }
+    }
+  }
+}

package/dist/bundles/network/resources/references/en/check.md

@@ -0,0 +1,21 @@
+---
+title: Network reachability
+description: Check explicit DNS names and HTTP status expectations with bounded resource lifetimes.
+---
+
+# Network reachability
+
+Input contains `dns` names and `http` entries with `url`, `expectedStatus`,
+`followRedirects`; at least one check is required. Optional `checkTimeoutMs`
+defaults to 5000 (100–300000). The host requires DNS/network access and Node
+subprocess support. HTTP(S) URLs cannot contain credentials.
+DNS runs in a bounded subprocess; HTTP response bodies are cancelled.
+
+Problems: [DNS unavailable](problems/dns-unavailable.md),
+[unexpected HTTP status](problems/http-status.md),
+[HTTP unavailable](problems/http-unavailable.md).
+Results contain only failures; `target` is the DNS name or URL, `actual` is
+the DNS error/address, status string or fetch diagnostic.
+Timeouts, invalid inputs, unexpected subprocess faults and cleanup failures
+remain execution faults. Cancellation propagates and physical resources are
+released. This is a point-in-time probe, not a network repair or guarantee.

package/dist/bundles/network/resources/references/en/problems/dns-unavailable.md

@@ -0,0 +1,8 @@
+---
+title: DNS unavailable
+description: DNS lookup failed with a recognized availability error.
+---
+
+`target` is the DNS name; `actual` is ENOTFOUND, EAI_AGAIN, EAI_FAIL or ETIMEOUT.
+Check spelling, host DNS configuration and connectivity. Subprocess deadlines
+and unexpected resolver errors remain faults. See [network checks](../check.md).

package/dist/bundles/network/resources/references/en/problems/http-status.md

@@ -0,0 +1,9 @@
+---
+title: Unexpected HTTP status
+description: The HTTP response did not satisfy status and redirect expectations.
+---
+
+`target` is the requested URL; `actual` is the decimal response status.
+Check expectedStatus and followRedirects, endpoint health and authentication.
+A redirect fails when following redirects is disabled, even when listed as an
+expected status. See [network checks](../check.md).

package/dist/bundles/network/resources/references/en/problems/http-unavailable.md

@@ -0,0 +1,9 @@
+---
+title: HTTP unavailable
+description: Fetch failed with a network TypeError rather than a timeout or cancellation.
+---
+
+`target` is the URL; `actual` is the fetch diagnostic string. Check host
+connectivity, TLS trust and endpoint availability without treating the diagnostic
+as a stable machine code. Timeout and cancellation remain faults/cancellation.
+See [network checks](../check.md).

package/dist/bundles/network/schemas/0.json

@@ -0,0 +1,76 @@
+{
+  "additionalProperties": false,
+  "anyOf": [
+    {
+      "properties": {
+        "dns": {
+          "type": "array",
+          "minItems": 1
+        }
+      }
+    },
+    {
+      "properties": {
+        "http": {
+          "type": "array",
+          "minItems": 1
+        }
+      }
+    }
+  ],
+  "type": "object",
+  "required": [
+    "dns",
+    "http"
+  ],
+  "properties": {
+    "checkTimeoutMs": {
+      "minimum": 100,
+      "maximum": 300000,
+      "type": "integer"
+    },
+    "dns": {
+      "maxItems": 100,
+      "type": "array",
+      "items": {
+        "maxLength": 253,
+        "pattern": "^[A-Za-z0-9][A-Za-z0-9.-]*$",
+        "type": "string"
+      }
+    },
+    "http": {
+      "maxItems": 100,
+      "type": "array",
+      "items": {
+        "additionalProperties": false,
+        "type": "object",
+        "required": [
+          "url",
+          "expectedStatus",
+          "followRedirects"
+        ],
+        "properties": {
+          "url": {
+            "minLength": 1,
+            "maxLength": 4096,
+            "type": "string"
+          },
+          "expectedStatus": {
+            "minItems": 1,
+            "uniqueItems": true,
+            "type": "array",
+            "items": {
+              "minimum": 100,
+              "maximum": 599,
+              "type": "integer"
+            }
+          },
+          "followRedirects": {
+            "type": "boolean"
+          }
+        }
+      }
+    }
+  },
+  "$id": "https://task.invalid/schema/input"
+}