@citeark/agent 0.3.20

package/src/contracts/execution-mode.mjs

@@ -0,0 +1,19 @@
+export const EXECUTION_MODES = new Set([
+  "agent_planned",
+  "fixed_entrypoint",
+]);
+
+/**
+ * Old Research Plan records predate executionMode and promised an immutable
+ * entrypoint. Keep that meaning for compatibility. Newly compiled plans state
+ * their mode explicitly and default to Agent-owned execution planning.
+ */
+export function resolveExecutionMode(protocol) {
+  return EXECUTION_MODES.has(protocol?.executionMode)
+    ? protocol.executionMode
+    : "fixed_entrypoint";
+}
+
+export function agentPlansExecution(protocol) {
+  return resolveExecutionMode(protocol) === "agent_planned";
+}

package/src/contracts/execution-timeouts.mjs

@@ -0,0 +1,45 @@
+const MINUTES_PER_HOUR = 60;
+
+// These are anomaly circuit breakers, not scheduling targets. New Research
+// Plans must still declare an explicit timeout based on the complete workload.
+export const LEGACY_EXECUTION_TIMEOUT_FALLBACK_MINUTES = 12 * MINUTES_PER_HOUR;
+
+export const EXECUTION_TIMEOUT_CAPS_MINUTES = Object.freeze({
+  proxy: 168 * MINUTES_PER_HOUR,
+  approximate: 168 * MINUTES_PER_HOUR,
+  faithful: 168 * MINUTES_PER_HOUR,
+  exact: 168 * MINUTES_PER_HOUR,
+});
+
+export const GCP_BATCH_PROVISIONING_GRACE_PER_ATTEMPT_MINUTES = 2 * MINUTES_PER_HOUR;
+export const GCP_BATCH_CONTROLLER_FINALIZATION_GRACE_MINUTES = 1 * MINUTES_PER_HOUR;
+
+export function executionTimeoutCapMinutes(fidelity) {
+  return EXECUTION_TIMEOUT_CAPS_MINUTES[fidelity]
+    ?? EXECUTION_TIMEOUT_CAPS_MINUTES.faithful;
+}
+
+export function gcpBatchControllerWaitTimeoutMinutes({
+  executionTimeoutMinutes,
+  infrastructureRetryCount = 0,
+}) {
+  const timeoutMinutes = positiveFiniteNumber(
+    executionTimeoutMinutes,
+    LEGACY_EXECUTION_TIMEOUT_FALLBACK_MINUTES,
+  );
+  const retryCount = Number.isInteger(infrastructureRetryCount)
+    && infrastructureRetryCount >= 0
+    ? infrastructureRetryCount
+    : 0;
+  const provisioningAttempts = retryCount + 1;
+  return Math.ceil(
+    timeoutMinutes
+    + provisioningAttempts * GCP_BATCH_PROVISIONING_GRACE_PER_ATTEMPT_MINUTES
+    + GCP_BATCH_CONTROLLER_FINALIZATION_GRACE_MINUTES,
+  );
+}
+
+function positiveFiniteNumber(value, fallback) {
+  const numeric = Number(value);
+  return Number.isFinite(numeric) && numeric > 0 ? numeric : fallback;
+}

package/src/contracts/execution-workload.mjs

@@ -0,0 +1,68 @@
+/** Pure workload arithmetic shared by the compiler, runtime helper and verifier. */
+export function executionWorkloadIssues(workload) {
+  if (workload === undefined) return [];
+  if (!workload || typeof workload !== "object" || Array.isArray(workload)) return ["protocol.workload must be an object"];
+  const issues = [];
+  if (typeof workload.unit !== "string" || !workload.unit.trim()) issues.push("protocol.workload.unit is required");
+  if (!Array.isArray(workload.groups) || !workload.groups.length) return [...issues, "protocol.workload.groups must contain the full scientific workload"];
+  const ids = new Set();
+  for (const group of workload.groups) {
+    if (typeof group?.id !== "string" || !group.id.trim() || ids.has(group.id)) issues.push("workload group ids must be nonempty and unique");
+    ids.add(group?.id);
+    if (!Number.isSafeInteger(group?.units) || group.units < 1) issues.push("workload group units must be positive safe integers");
+    if (typeof group?.description !== "string" || !group.description.trim()) issues.push("workload groups must describe their scientific scope");
+  }
+  return issues;
+}
+
+export function assessExecutionFeasibility({ workload, probes, completed = [], remainingSeconds, publicationReserveSeconds = 300 }) {
+  const issues = executionWorkloadIssues(workload);
+  if (!workload) issues.push("A declared workload is required for a measured forecast");
+  if (!Number.isFinite(remainingSeconds) || remainingSeconds < 0) issues.push("remainingSeconds must come from the current runner ledger");
+  if (!Number.isFinite(publicationReserveSeconds) || publicationReserveSeconds < 300) issues.push("Reserve at least 300 seconds for evidence publication");
+  if (issues.length) throw new TypeError(issues.join("; "));
+  const expected = new Map(workload.groups.map((group) => [group.id, group.units]));
+  if (!Array.isArray(completed) || new Set(completed.map((item) => item?.groupId)).size !== completed.length
+    || completed.some((item) => !expected.has(item?.groupId)
+      || !Number.isSafeInteger(item.units) || item.units < 0 || item.units > expected.get(item.groupId)
+      || typeof item.evidencePath !== "string" || !item.evidencePath.trim())) {
+    throw new TypeError("Completed work must have unique declared groups, bounded counts and raw evidence");
+  }
+  const groups = workload.groups.map((group) => {
+    const done = completed.find((item) => item.groupId === group.id)?.units ?? 0;
+    if (!Number.isSafeInteger(done) || done < 0 || done > group.units) throw new TypeError(`Invalid completed count for ${group.id}`);
+    const samples = (probes ?? []).filter((item) => item.groupId === group.id);
+    const valid = samples.filter((item) => Number.isSafeInteger(item.units) && item.units > 0
+      && Number.isFinite(item.durationSeconds) && item.durationSeconds > 0
+      && typeof item.evidencePath === "string" && item.evidencePath.trim());
+    // Use the slowest observed rate; do not assume unmeasured parallel speedup.
+    const secondsPerUnit = valid.length ? Math.max(...valid.map((item) => item.durationSeconds / item.units)) : null;
+    const remainingUnits = group.units - done;
+    return { groupId: group.id, totalUnits: group.units, completedUnits: done, remainingUnits, secondsPerUnit,
+      forecastSeconds: remainingUnits === 0 ? 0 : secondsPerUnit === null ? null : remainingUnits * secondsPerUnit,
+      evidencePaths: [...new Set(valid.map((item) => item.evidencePath))] };
+  });
+  const complete = groups.every((group) => group.forecastSeconds !== null);
+  const forecastSeconds = complete ? groups.reduce((total, group) => total + group.forecastSeconds, 0) : null;
+  return {
+    schemaVersion: "1.0", kind: "citeark.execution-feasibility",
+    status: !complete ? "insufficient_evidence" : forecastSeconds + publicationReserveSeconds <= remainingSeconds ? "fits" : "requires_replanning",
+    forecastSeconds, remainingSeconds, publicationReserveSeconds, groups,
+    basis: "measured-rates-and-declared-workload; not a guarantee of completion",
+  };
+}
+
+export function executionWorkloadCompletionIssues(workload, completed) {
+  if (!workload) return [];
+  const issues = executionWorkloadIssues(workload);
+  if (!Array.isArray(completed)) return [...issues, "Successful execution requires workload completion records"];
+  const expected = new Map((workload.groups ?? []).map((group) => [group.id, group.units]));
+  const ids = completed.map((item) => item?.groupId);
+  if (new Set(ids).size !== ids.length || ids.some((id) => !expected.has(id))) issues.push("Completion groups must be unique and declared");
+  for (const [id, units] of expected) {
+    const record = completed.find((item) => item.groupId === id);
+    if (record?.units !== units || !Number.isSafeInteger(record?.units)) issues.push(`Incomplete workload ${id}: expected ${units} units`);
+    if (typeof record?.evidencePath !== "string" || !record.evidencePath.trim()) issues.push(`Missing raw completion evidence for ${id}`);
+  }
+  return issues;
+}

package/src/contracts/preflight-schema.mjs

@@ -0,0 +1,25 @@
+export const PREFLIGHT_SCHEMA_VERSIONS = Object.freeze(["0.1", "0.2", "0.3"]);
+export const CURRENT_PREFLIGHT_SCHEMA_VERSION = "0.3";
+export const PREFLIGHT_SCHEMA_VERSION_SET = new Set(PREFLIGHT_SCHEMA_VERSIONS);
+
+export const MAX_PREFLIGHT_MINUTES = 240;
+export const MIN_PUBLIC_ASSET_PREFLIGHT_MINUTES = 30;
+
+export const PREFLIGHT_CHECK_KINDS = new Set([
+  "runtime",
+  "dependencies",
+  "dataset_loader",
+  "assets",
+  "entrypoint",
+  "parser",
+  "smoke_test",
+  "duration",
+]);
+
+export function supportsPreflightSchemaVersion(value) {
+  return PREFLIGHT_SCHEMA_VERSION_SET.has(value);
+}
+
+export function describeSupportedPreflightSchemaVersions() {
+  return PREFLIGHT_SCHEMA_VERSIONS.join("、");
+}

package/src/contracts/public-contract.mjs

@@ -0,0 +1,63 @@
+/** One prospective projection, shared by compilation and CAP publication. */
+export function researchPublicContract(experiment) {
+  const protocol = experiment?.protocol ?? {};
+  return {
+    implementation: {
+      repository: experiment?.repository?.url,
+      revision: experiment?.repository?.commit,
+      ...(protocol.executionMode ? { executionMode: protocol.executionMode } : {}),
+      ...(protocol.objective ? { objective: protocol.objective } : {}),
+      entrypoint: protocol.entrypoint,
+      requiredCommandFragments: protocol.requiredCommandFragments ?? [],
+    },
+    parameters: protocol.parameters ?? [],
+    measurements: (Array.isArray(experiment?.measurements) ? experiment.measurements : []).map((item) => {
+      const measurement = item ?? {};
+      return {
+        id: measurement.id ?? measurement.reportedMeasurementId,
+        metric: measurement.metric,
+        ...(measurement.quantityKind ? { quantityKind: measurement.quantityKind } : {}),
+        unit: measurement.unit,
+        evidenceParser: { id: measurement.parser?.id, version: measurement.parser?.version },
+      };
+    }),
+    ...(experiment?.reproductionScope ? { reproductionScope: experiment.reproductionScope, requiredReproductionScope: experiment.requiredReproductionScope } : {}),
+    resources: { computeRequirement: experiment?.compute ?? {}, environment: experiment?.environment ?? {} },
+    ...(protocol.benchmark ? { benchmark: protocol.benchmark } : {}),
+    ...(protocol.preflight ? { preflight: protocol.preflight } : {}),
+  };
+}
+
+const PRIVATE_FIELDS = new Set([
+  'reportedvalue', 'targetvalue', 'acceptancecriterion', 'acceptancecriteria',
+  'verificationtolerance', 'verificationpolicy', 'privatepolicy', 'policyreveal',
+]);
+const fieldName = value => String(value).replace(/[_\s-]/g, '').toLowerCase();
+
+/**
+ * Enforce private policy structure, not a vocabulary ban on scientific prose.
+ * Numerical solver tolerances are public algorithm parameters. Bare tolerance
+ * in a measurement or at the contract root is an acceptance-policy field.
+ * This does not claim to prove semantic blindness of arbitrary text or code.
+ */
+export function publicContractPolicyIssues(contract) {
+  const issues = [];
+  function visit(value, parts) {
+    if (!value || typeof value !== 'object') return;
+    for (const [key, child] of Object.entries(value)) {
+      const name = fieldName(key);
+      const location = [...parts, key];
+      if (PRIVATE_FIELDS.has(name)
+        || (name === 'tolerance' && (parts.length === 0 || parts[0] === 'measurements'))) {
+        issues.push(`${location.join('.')} contains a private verification-policy field`);
+      }
+      // Also recognize records representing parameters by name rather than key.
+      if (name === 'name' && typeof child === 'string' && PRIVATE_FIELDS.has(fieldName(child))) {
+        issues.push(`${location.join('.')} names a private verification-policy field`);
+      }
+      visit(child, location);
+    }
+  }
+  visit(contract, []);
+  return issues;
+}

package/src/contracts/subject-tags.mjs

@@ -0,0 +1,31 @@
+export const SUBJECT_TAGS = new Set([
+  "cs-ai", "cs-ar", "cs-cc", "cs-ce", "cs-cg", "cs-cl", "cs-cr", "cs-cv", "cs-cy", "cs-db",
+  "cs-dc", "cs-dl", "cs-dm", "cs-ds", "cs-et", "cs-fl", "cs-gl", "cs-gr", "cs-gt", "cs-hc",
+  "cs-ir", "cs-it", "cs-lg", "cs-lo", "cs-ma", "cs-mm", "cs-ms", "cs-na", "cs-ne", "cs-ni",
+  "cs-oh", "cs-os", "cs-pf", "cs-pl", "cs-ro", "cs-sc", "cs-sd", "cs-se", "cs-si", "cs-sy",
+  "econ-em", "econ-gn", "econ-th",
+  "eess-as", "eess-iv", "eess-sp", "eess-sy",
+  "math-ac", "math-ag", "math-ap", "math-at", "math-ca", "math-co", "math-ct", "math-cv",
+  "math-dg", "math-ds", "math-fa", "math-gm", "math-gn", "math-gr", "math-gt", "math-ho",
+  "math-it", "math-kt", "math-lo", "math-mg", "math-mp", "math-na", "math-nt", "math-oa",
+  "math-oc", "math-pr", "math-qa", "math-ra", "math-rt", "math-sg", "math-sp", "math-st",
+  "astro-ph-co", "astro-ph-ep", "astro-ph-ga", "astro-ph-he", "astro-ph-im", "astro-ph-sr",
+  "cond-mat-dis-nn", "cond-mat-mes-hall", "cond-mat-mtrl-sci", "cond-mat-other",
+  "cond-mat-quant-gas", "cond-mat-soft", "cond-mat-stat-mech", "cond-mat-str-el", "cond-mat-supr-con",
+  "gr-qc",
+  "hep-ex", "hep-lat", "hep-ph", "hep-th",
+  "math-ph",
+  "nlin-ao", "nlin-cd", "nlin-cg", "nlin-ps", "nlin-si",
+  "nucl-ex", "nucl-th",
+  "physics-acc-ph", "physics-ao-ph", "physics-app-ph", "physics-atm-clus", "physics-atom-ph",
+  "physics-bio-ph", "physics-chem-ph", "physics-class-ph", "physics-comp-ph", "physics-data-an",
+  "physics-ed-ph", "physics-flu-dyn", "physics-gen-ph", "physics-geo-ph", "physics-hist-ph",
+  "physics-ins-det", "physics-med-ph", "physics-optics", "physics-plasm-ph", "physics-pop-ph",
+  "physics-soc-ph", "physics-space-ph",
+  "quant-ph",
+  "q-bio-bm", "q-bio-cb", "q-bio-gn", "q-bio-mn", "q-bio-nc", "q-bio-ot", "q-bio-pe",
+  "q-bio-qm", "q-bio-sc", "q-bio-to",
+  "q-fin-cp", "q-fin-ec", "q-fin-gn", "q-fin-mf", "q-fin-pm", "q-fin-pr", "q-fin-rm",
+  "q-fin-st", "q-fin-tr",
+  "stat-ap", "stat-co", "stat-me", "stat-ml", "stat-ot", "stat-th",
+]);