@citeark/agent 0.3.20

package/schemas/result.schema.json

@@ -0,0 +1,173 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://citeark.com/schemas/agent/result-1.0.json",
+  "title": "CiteArk execution agent result",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "execution", "experiment", "codeChanges", "evidence", "limitations"],
+  "properties": {
+    "schemaVersion": { "const": "1.0" },
+    "workloadCompletion": {
+      "type": "array",
+      "items": {
+        "type": "object", "additionalProperties": false,
+        "required": ["groupId", "units", "evidencePath"],
+        "properties": {
+          "groupId": { "type": "string", "minLength": 1 },
+          "units": { "type": "integer", "minimum": 0 },
+          "evidencePath": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "execution": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["status", "summary", "failure"],
+      "properties": {
+        "status": { "enum": ["succeeded", "failed", "partial"] },
+        "summary": { "type": "string", "minLength": 1 },
+        "failure": {
+          "oneOf": [
+            { "type": "null" },
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["category", "stage", "retryable", "reason"],
+              "properties": {
+                "category": {
+                  "enum": [
+                    "source_unavailable",
+                    "missing_asset",
+                    "dependency_failure",
+                    "environment_incompatible",
+                    "resource_exhausted",
+                    "protocol_ambiguous",
+                    "execution_error",
+                    "metric_unavailable",
+                    "timeout",
+                    "other"
+                  ]
+                },
+                "stage": {
+                  "enum": ["setup", "data", "build", "training", "evaluation", "measurement", "unknown"]
+                },
+                "retryable": { "type": "boolean" },
+                "reason": { "type": "string", "minLength": 1 }
+              }
+            }
+          ]
+        }
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "status": { "const": "succeeded" } }, "required": ["status"] },
+          "then": { "properties": { "failure": { "type": "null" } } },
+          "else": { "properties": { "failure": { "type": "object" } } }
+        }
+      ]
+    },
+    "preflight": {
+      "description": "Structured bounded gate completed before the full scientific command. Required when the execution contract declares protocol.preflight.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["source", "status", "evidencePath", "checks"],
+      "properties": {
+        "source": { "enum": ["agent", "platform_recovery"] },
+        "status": { "enum": ["passed", "failed"] },
+        "evidencePath": { "type": "string", "minLength": 1 },
+        "checks": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["id", "status", "detail"],
+            "properties": {
+              "id": { "type": "string", "minLength": 1 },
+              "status": { "enum": ["passed", "failed"] },
+              "detail": { "type": "string", "minLength": 1 }
+            }
+          }
+        }
+      }
+    },
+    "experiment": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["commands", "entrypoint", "checkpoint"],
+      "properties": {
+        "commands": {
+          "type": "array",
+          "description": "Decisive commands that actually ran. This may be empty for a failed or partial execution that never reached an experimental command.",
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "entrypoint": { "type": ["string", "null"] },
+        "checkpoint": { "type": ["string", "null"] }
+      }
+    },
+    "codeChanges": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["path", "classification", "reason"],
+        "properties": {
+          "path": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Safe path relative to the task root for the changed repository, helper, output, or task environment file; report /job/runtime-venv/... as runtime-venv/..., and never report absolute container or temporary paths."
+          },
+          "classification": { "enum": ["environment", "execution", "scientific"] },
+          "reason": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "diagnosis": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Free-form Agent analysis of what happened, likely causes, remaining uncertainty, and the most useful next check."
+    },
+    "evidence": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["path", "description"],
+        "properties": {
+          "path": { "type": "string", "minLength": 1 },
+          "description": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "outputs": {
+      "description": "Scientific products created by this run. Outputs are distinct from evidence: an output is what the experiment produced, while evidence is what a verifier uses to assess it. The same file may be listed in both arrays.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "kind", "role", "path", "description"],
+        "properties": {
+          "id": { "type": "string", "minLength": 1 },
+          "scientificObjectId": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Explicit identity of the prospective research object realized by this generated material."
+          },
+          "kind": {
+            "enum": ["table", "figure", "dataset", "model", "checkpoint", "text", "archive", "audio", "video", "other"]
+          },
+          "role": { "enum": ["primary", "supporting"] },
+          "path": { "type": "string", "minLength": 1 },
+          "description": { "type": "string", "minLength": 1 },
+          "relatedEvidencePaths": {
+            "type": "array",
+            "uniqueItems": true,
+            "items": { "type": "string", "minLength": 1 }
+          }
+        }
+      }
+    },
+    "limitations": { "type": "array", "items": { "type": "string" } }
+  }
+}

package/schemas/verification-policy.schema.json

@@ -0,0 +1,47 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://citeark.com/schemas/agent/verification-policy-1.0.json",
+  "type": "object",
+  "required": ["schemaVersion", "kind", "contractDigest", "claimVersionId", "targets", "commitment", "policyDigest"],
+  "properties": {
+    "schemaVersion": { "const": "1.0" },
+    "kind": { "const": "citeark.private-verification-policy" },
+    "contractDigest": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
+    "claimVersionId": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
+    "targets": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["measurementId", "metric", "unit", "reportedValue", "comparator", "tolerance"],
+        "properties": {
+          "measurementId": { "type": "string", "minLength": 1 },
+          "metric": { "type": "string", "minLength": 1 },
+          "unit": { "type": "string", "minLength": 1 },
+          "reportedValue": { "type": "number" },
+          "comparator": { "const": "absolute-difference" },
+          "tolerance": { "type": "number", "minimum": 0 },
+          "toleranceSource": {
+            "type": "object",
+            "required": ["kind", "unit"],
+            "properties": {
+              "kind": { "enum": ["explicit", "unit-default", "unconfigured"] },
+              "unit": { "type": "string" },
+              "reason": { "type": "string" }
+            }
+          }
+        }
+      }
+    },
+    "commitment": {
+      "type": "object",
+      "required": ["algorithm", "nonce", "digest"],
+      "properties": {
+        "algorithm": { "const": "citeark-policy-commitment-v1" },
+        "nonce": { "type": "string", "minLength": 22 },
+        "digest": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" }
+      }
+    },
+    "policyDigest": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" }
+  }
+}

package/schemas/verified-conclusion.schema.json

@@ -0,0 +1,58 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://citeark.com/schemas/research/verified-conclusion-0.1.json",
+  "title": "CiteArk evidence-grounded paper conclusion",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "kind", "workId", "generatedAt", "overallStatus", "text", "coverage", "basis", "policy", "conclusionDigest"],
+  "properties": {
+    "schemaVersion": { "const": "0.1" },
+    "kind": { "const": "citeark.verified-conclusion" },
+    "workId": { "type": "string", "minLength": 1 },
+    "generatedAt": { "type": "string", "minLength": 1 },
+    "overallStatus": { "enum": ["tested_claims_supported", "supported", "partially_supported", "not_supported", "inconclusive"] },
+    "text": { "type": "string", "minLength": 1, "maxLength": 1000, "pattern": "^[^\\r\\n]+$" },
+    "coverage": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["structuredClaims", "evaluatedClaims", "unevaluatedClaims", "verificationRecords", "reproduced", "approximatelyReproduced", "notReproduced", "inconclusive"],
+      "properties": {
+        "structuredClaims": { "type": "integer", "minimum": 0 },
+        "evaluatedClaims": { "type": "integer", "minimum": 0 },
+        "unevaluatedClaims": { "type": "integer", "minimum": 0 },
+        "verificationRecords": { "type": "integer", "minimum": 0 },
+        "reproduced": { "type": "integer", "minimum": 0 },
+        "approximatelyReproduced": { "type": "integer", "minimum": 0 },
+        "notReproduced": { "type": "integer", "minimum": 0 },
+        "inconclusive": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "basis": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["claimId", "claimVersionId", "verificationStatus", "assessmentDigest", "integrityStatus", "comparison"],
+        "properties": {
+          "claimId": { "type": "string", "minLength": 1 },
+          "claimVersionId": { "type": ["string", "null"] },
+          "verificationStatus": { "enum": ["reproduced", "approximately_reproduced", "not_reproduced", "inconclusive"] },
+          "assessmentDigest": { "type": ["string", "null"] },
+          "integrityStatus": { "type": ["string", "null"] },
+          "comparison": { "type": ["object", "null"] }
+        }
+      }
+    },
+    "policy": {
+      "type": "object",
+      "required": ["evidenceGrounded", "claimUniverse", "paperWideCoverageEstablished", "maximumDisplayedClaimsPerStatus", "description"],
+      "properties": {
+        "evidenceGrounded": { "const": true },
+        "claimUniverse": { "const": "compiler-structured" },
+        "paperWideCoverageEstablished": { "const": false },
+        "maximumDisplayedClaimsPerStatus": { "type": "integer", "minimum": 0 },
+        "description": { "type": "string", "minLength": 1 }
+      }
+    },
+    "conclusionDigest": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" }
+  }
+}

package/schemas/workspace-summary.schema.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "CiteArk workspace completion summary",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "status", "summary"],
+  "properties": {
+    "schemaVersion": { "const": "2.0" },
+    "status": { "enum": ["completed", "partial", "failed"] },
+    "summary": { "type": "string", "minLength": 1 },
+    "limitations": { "type": "array", "items": { "type": "string" } },
+    "evidence": {
+      "description": "Optional additional raw evidence. Parser inputs and plan records are collected by the platform.",
+      "type": "array",
+      "items": {
+        "type": "object", "required": ["path"],
+        "properties": {
+          "path": { "type": "string", "minLength": 1 },
+          "description": { "type": "string" }
+        }
+      }
+    }
+  }
+}

package/scripts/build-arkgraph-view.mjs

@@ -0,0 +1,12 @@
+import { build } from '../ui/arkgraph/node_modules/esbuild/lib/main.js';
+import { materialCssPlugin } from '../ui/arkgraph/material-build.mjs';
+import { localizationPlugin } from '../ui/arkgraph/localization-build.mjs';
+import {copyFile,mkdir} from 'node:fs/promises';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+const root=path.resolve(path.dirname(fileURLToPath(import.meta.url)),'..');
+const out=path.join(root,'dist/arkgraph');await mkdir(out,{recursive:true});
+for(const locale of ['zh','en'])await build({entryPoints:[path.join(root,'ui/arkgraph/entry.jsx')],bundle:true,minify:true,format:'iife',
+ outfile:path.join(out,locale==='en'?'viewer.en.js':'viewer.js'),define:{'process.env.NODE_ENV':'"production"'},legalComments:'linked',plugins:[...(locale==='en'?[localizationPlugin]:[]),materialCssPlugin]});
+for(const [source,target] of [['frame.html','index.html'],['boot.js','boot.js']])await copyFile(path.join(root,'ui/arkgraph',source),path.join(out,target));
+console.log('Built reusable ArkGraph viewer in English and Chinese.');

package/scripts/check-execution-feasibility.mjs

@@ -0,0 +1,24 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { assessExecutionFeasibility } from "../src/contracts/execution-workload.mjs";
+
+// The Agent chooses and executes representative probes. This helper only
+// projects their measured rates onto the immutable workload and runner ledger.
+const [taskPath, probesPath, ledgerPath, outputPath] = process.argv.slice(2);
+if (!outputPath) throw new Error("Usage: node check-execution-feasibility.mjs task.json probes.json runtime-budget.json report.json");
+const read = async (filename) => JSON.parse(await readFile(filename, "utf8"));
+const [task, observation, ledger] = await Promise.all([read(taskPath), read(probesPath), read(ledgerPath)]);
+const ageSeconds = (Date.now() - Date.parse(ledger.updatedAt)) / 1000;
+if (!Number.isFinite(ageSeconds) || ageSeconds < -5
+  || !Number.isFinite(ledger.totalRuntimeBudgetSeconds) || !Number.isFinite(ledger.consumedRuntimeSeconds)
+  || ledger.totalRuntimeBudgetSeconds <= 0 || ledger.consumedRuntimeSeconds < 0) throw new Error("Invalid runner budget ledger");
+const remainingSeconds = Math.max(0, ledger.totalRuntimeBudgetSeconds - ledger.consumedRuntimeSeconds - Math.max(0, ageSeconds));
+const report = {
+  ...assessExecutionFeasibility({ workload: task.protocol?.workload, probes: observation.probes,
+    completed: observation.completed, remainingSeconds,
+    publicationReserveSeconds: observation.publicationReserveSeconds ?? 300 }),
+  observedAt: new Date().toISOString(),
+  budgetLedger: ledger,
+};
+await writeFile(outputPath, `${JSON.stringify(report, null, 2)}\n`);
+console.log(JSON.stringify(report));
+if (report.status !== "fits") process.exitCode = 78;

package/scripts/check-syntax.mjs

@@ -0,0 +1,15 @@
+import { readdir } from 'node:fs/promises';
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+async function check(directory) {
+  for (const entry of await readdir(directory, { withFileTypes:true })) {
+    const file=path.join(directory,entry.name);
+    if(entry.isDirectory()) await check(file);
+    else if(entry.name.endsWith('.mjs')) {
+      const result=spawnSync(process.execPath,['--check',file],{stdio:'inherit'});
+      if(result.status!==0)process.exit(result.status??1);
+    }
+  }
+}
+await check(fileURLToPath(new URL('../src',import.meta.url)));