@botiverse/k-carrier 0.1.0

package/core/src/artifact/partialPath.ts

@@ -0,0 +1,18 @@
+/**
+ * Where an interrupted download parks its prefix.
+ *
+ * Its own module for the line budget, but the naming rule genuinely belongs in
+ * one place: resume works only if the NEXT attempt derives the same path from
+ * the same URL, so two copies of this rule that drift produce a resume that
+ * silently restarts from zero.
+ */
+import { createHash } from "node:crypto";
+import * as path from "node:path";
+
+function sha256Hex(data: Uint8Array): string {
+  return createHash("sha256").update(data).digest("hex");
+}
+
+export function partialPathFor(resumeDir: string, url: string): string {
+  return path.join(resumeDir, `${sha256Hex(new TextEncoder().encode(url))}.part`);
+}

package/core/src/artifact/source.ts

@@ -0,0 +1,59 @@
+/**
+ * ReleaseSource — where releases come from, and what this install should be on.
+ *
+ * This is the ONLY place in K where version *semantics* live. Everywhere else
+ * (engine, journal, slots, predicates, invariants) a version is an opaque
+ * string compared with `===`. That boundary is deliberate:
+ *
+ *   - "which version is latest" requires a version ORDER, and an order
+ *     requires a versioning SCHEME (semver? dates? build numbers?). Choosing
+ *     it for you would be K deciding your product's versioning.
+ *   - anti-rollback has the same dependency, so it belongs here too.
+ *
+ * Two methods, because they answer two different QUESTIONS (not two steps of
+ * one operation):
+ *   checkForUpdate — policy: should I upgrade, and to what?
+ *   fetchRelease   — named:  give me exactly this version
+ *
+ * Channels ("stable", "nightly", "lts-2024") are not a K concept at all: they
+ * live inside your implementation of this interface. So does long-term
+ * pinning — a source that always returns the same version IS a pin.
+ */
+
+export interface ReleaseContext {
+  /** Version currently installed in the stable slot. */
+  currentVersion: string;
+  /** Manifest target key for this machine, e.g. "linux-x64". */
+  platformKey: string;
+}
+
+/**
+ * Everything K needs to fetch and verify one release's bytes.
+ *
+ * ⚠️ There is deliberately no signature field: K checks integrity (sha256 +
+ * size) and does not verify who produced the artifact. Removed 2026-08-06;
+ * rationale and the OS-code-signing comparison live in docs/design-v1.md §L0.5.
+ */
+export interface Release {
+  version: string;
+  url: string;
+  sha256: string;
+  size: number;
+}
+
+export interface ReleaseSource {
+  /**
+   * Policy question: what should this install upgrade to, if anything?
+   * `null` means "nothing to do" — already current by YOUR definition of
+   * current. Drives `upgrader.upgrade()` (CLI self-upgrade, background checks).
+   */
+  checkForUpdate(ctx: ReleaseContext): Promise<Release | null>;
+
+  /**
+   * Named question: give me exactly this version.
+   * Drives `upgrader.upgradeTo(version)` — a user choosing a version, or a
+   * server pushing "go to 1.2.3". This is also the sanctioned DOWNGRADE path:
+   * downgrade is always explicit, never automatic.
+   */
+  fetchRelease(version: string, ctx: ReleaseContext): Promise<Release>;
+}

package/core/src/artifact/staticManifestSource.ts

@@ -0,0 +1,185 @@
+/**
+ * staticManifestSource — and the manifest.json format itself.
+ *
+ * The format lives HERE, not in a neutral core module, because it is this
+ * source's format: a ReleaseSource that reads a private API, date-stamped
+ * paths or an OCI registry never parses a manifest at all. Keeping it in
+ * core/artifact/manifest.ts implied K owned it, which was misleading.
+ *
+ * staticManifestSource — a batteries-included ReleaseSource for the common
+ * case: one static file host, one stream, semver ordering.
+ *
+ * This is ONE POLICY, not framework law. It encodes choices K has no business
+ * making for everyone:
+ *   - versions are semver and ordered as such
+ *   - "should I upgrade" means "is the served version greater than mine"
+ *   - downgrades are refused here (explicit downgrade goes through
+ *     upgradeTo/fetchRelease instead)
+ *
+ * Publish releases under a different scheme (dates, build numbers), or across
+ * several streams, and you write your own ReleaseSource — without touching K.
+ */
+import { ArtifactError } from "./errors.ts";
+
+import type { Release, ReleaseContext, ReleaseSource } from "./source.ts";
+
+export interface ManifestTarget {
+  /** Artifact filename relative to the release root (served at /<file>). */
+  file: string;
+  /** Lowercase hex sha256 of the artifact bytes (64 chars). */
+  sha256: string;
+  size: number;
+}
+
+export interface Manifest {
+  version: string;
+  /** Platform tag (e.g. "darwin-arm64") -> binary target. */
+  targets: Record<string, ManifestTarget>;
+  /** Track the release was published under (latest | alpha). Optional. */
+}
+
+/**
+ * NOTE: no field here may weaken a check K performs.
+ *
+ * K does not verify authenticity today (see design-v1 §L0.5), but the rule
+ * outlives that decision: the manifest is served BY the release source, i.e.
+ * exactly the party a signature chain would exist to distrust. An earlier
+ * version honoured a manifest-declared `unsigned: true`, which let anyone who
+ * controlled the source turn verification off for every client with one extra
+ * JSON field -- no crypto broken.
+ *
+ * "We accept bytes nobody vouched for" is a decision only the CLIENT can make.
+ * If signing ever lands, the opt-out belongs in the adopter's own code, never
+ * in the payload. A source can offer bytes; it cannot grant itself trust.
+ */
+
+const SHA256_RE = /^[0-9a-f]{64}$/;
+
+export function parseManifest(text: string): Manifest {
+  let obj: unknown;
+  try {
+    obj = JSON.parse(text);
+  } catch {
+    throw new ArtifactError("MANIFEST_INVALID", "manifest is not valid JSON");
+  }
+  if (typeof obj !== "object" || obj === null) {
+    throw new ArtifactError("MANIFEST_INVALID", "manifest must be a JSON object");
+  }
+  const o = obj as Record<string, unknown>;
+
+  if (typeof o.version !== "string" || o.version.trim() === "") {
+    throw new ArtifactError("MANIFEST_INVALID", "manifest.version must be a non-empty string");
+  }
+  if (typeof o.targets !== "object" || o.targets === null) {
+    throw new ArtifactError("MANIFEST_INVALID", "manifest.targets must be an object");
+  }
+  const targets: Manifest["targets"] = {};
+  for (const [platform, raw] of Object.entries(o.targets as Record<string, unknown>)) {
+    if (typeof raw !== "object" || raw === null) {
+      throw new ArtifactError("MANIFEST_INVALID", `targets.${platform} must be an object`);
+    }
+    const t = raw as Record<string, unknown>;
+    if (typeof t.file !== "string" || t.file.trim() === "") {
+      throw new ArtifactError("MANIFEST_INVALID", `targets.${platform}.file must be a non-empty string`);
+    }
+    if (typeof t.sha256 !== "string" || !SHA256_RE.test(t.sha256)) {
+      throw new ArtifactError("MANIFEST_INVALID", `targets.${platform}.sha256 must be 64-char hex`);
+    }
+    if (typeof t.size !== "number" || !Number.isInteger(t.size) || t.size < 0) {
+      throw new ArtifactError("MANIFEST_INVALID", `targets.${platform}.size must be a non-negative integer`);
+    }
+    targets[platform] = { file: t.file, sha256: t.sha256, size: t.size };
+  }
+  if (Object.keys(targets).length === 0) {
+    throw new ArtifactError("MANIFEST_INVALID", "manifest.targets must contain at least one platform");
+  }
+
+  const out: Manifest = { version: o.version, targets };
+  return out;
+}
+
+/** The platform key the client resolves against (os-arch, e.g. darwin-arm64). */
+export function currentPlatformKey(): string {
+  return `${process.platform}-${process.arch}`;
+}
+
+export interface StaticManifestSourceOptions {
+  /** Base URL holding manifest.json and the artifacts, e.g. https://cdn.x/mytool/stable */
+  baseUrl: string;
+  fetchImpl?: typeof fetch;
+}
+
+function numericParts(v: string): number[] {
+  return v.split("-")[0]!.split(".").map((n) => Math.trunc(Number(n)) || 0);
+}
+
+/** Compare two dotted numeric versions; returns >0 when a is newer. */
+function compareSemver(a: string, b: string): number {
+  const [pa, pb] = [numericParts(a), numericParts(b)];
+  for (let i = 0; i < Math.max(pa.length, pb.length); i += 1) {
+    const diff = (pa[i] ?? 0) - (pb[i] ?? 0);
+    if (diff !== 0) return diff;
+  }
+  // A prerelease (1.2.3-rc.1) sorts BELOW its release (1.2.3).
+  const preA = a.includes("-");
+  const preB = b.includes("-");
+  if (preA !== preB) return preA ? -1 : 1;
+  return 0;
+}
+
+function releaseFrom(
+  manifest: Manifest,
+  baseUrl: string,
+  platformKey: string,
+): Release {
+  const target = manifest.targets[platformKey];
+  if (!target) {
+    throw new ArtifactError(
+      "UNSUPPORTED_PLATFORM",
+      `manifest has no target for ${platformKey} (have: ${Object.keys(manifest.targets).join(", ") || "none"})`,
+    );
+  }
+  const base = baseUrl.replace(/\/$/u, "");
+  const release: Release = {
+    version: manifest.version,
+    url: `${base}/${target.file}`,
+    sha256: target.sha256,
+    size: target.size,
+  };
+
+  return release;
+}
+
+export function staticManifestSource(opts: StaticManifestSourceOptions): ReleaseSource {
+  const base = opts.baseUrl.replace(/\/$/u, "");
+  const doFetch = opts.fetchImpl ?? fetch;
+
+  async function loadManifest(): Promise<Manifest> {
+    const res = await doFetch(`${base}/manifest.json`);
+    if (!res.ok) {
+      throw new ArtifactError("DOWNLOAD_FAILED", `manifest.json fetch failed: HTTP ${res.status}`);
+    }
+    return parseManifest(await res.text());
+  }
+
+  return {
+    async checkForUpdate(ctx: ReleaseContext): Promise<Release | null> {
+      const manifest = await loadManifest();
+      // POLICY: only move forward. A served version older than ours is not an
+      // "update" — taking it silently would be an automatic downgrade.
+      if (compareSemver(manifest.version, ctx.currentVersion) <= 0) return null;
+      return releaseFrom(manifest, base, ctx.platformKey);
+    },
+
+    async fetchRelease(version: string, ctx: ReleaseContext): Promise<Release> {
+      const manifest = await loadManifest();
+      if (manifest.version !== version) {
+        throw new ArtifactError(
+          "PINNED_VERSION_MISMATCH",
+          `asked for ${version} but this source serves ${manifest.version}`,
+        );
+      }
+      return releaseFrom(manifest, base, ctx.platformKey);
+    },
+  };
+}

package/core/src/artifact/swap.ts

@@ -0,0 +1,21 @@
+/**
+ * L0 byte swap — delegates the OS-shaped sequence to the platform seam and
+ * keeps the artifact layer's typed-error contract.
+ *
+ * The seam decides HOW bytes get replaced (POSIX rename vs the Windows
+ * move-the-running-image dance); this layer guarantees that a failure is a
+ * typed SWAP_FAILED rather than a raw errno leaking to callers.
+ */
+import { platformOpsFor } from "../platform/index.ts";
+import { ArtifactError } from "./errors.ts";
+
+export async function atomicWriteFile(filePath: string, data: Uint8Array): Promise<void> {
+  try {
+    await platformOpsFor().swapExecutable(filePath, data);
+  } catch (err) {
+    throw new ArtifactError(
+      "SWAP_FAILED",
+      `could not replace ${filePath}: ${(err as Error).message}`,
+    );
+  }
+}

package/core/src/clock.ts

@@ -0,0 +1,22 @@
+/**
+ * Clock seam — core's ONLY access to time.
+ *
+ * Production-grade injection surface (transparency principle §1.8): core
+ * never calls Date.now()/setTimeout directly; everything time-related goes
+ * through an injected Clock. The default is the real system clock, so this
+ * is dependency injection, not a test mode. A future CI ratchet forbids
+ * direct time APIs inside core/ (same technique as Raft's clock-ratchet).
+ */
+export interface Clock {
+  nowMs(): number;
+  /** Schedule fn after ms; returns a cancel function. */
+  after(ms: number, fn: () => void): () => void;
+}
+
+export const systemClock: Clock = {
+  nowMs: () => Date.now(),
+  after: (ms, fn) => {
+    const t = setTimeout(fn, ms);
+    return () => clearTimeout(t);
+  },
+};

package/core/src/converge/lifecycle.ts

@@ -0,0 +1,114 @@
+/**
+ * host_lifecycle_converged — the lifecycle read-back predicate (design-v1
+ * §L3, test-plan M5). Lifted from the supervisor-retirement design.
+ *
+ * An upgrade that "says it happened" must be mechanically provable. Beyond
+ * binary_at_target (the live process), the OS-lifecycle surface must agree:
+ * the supervisor/auto-start entry must actually reference what the upgrade
+ * installed. Evidence comes from a NAMED SSOT surface the platform adapter
+ * declares — a surface that cannot be read back on a real machine may not
+ * claim same-source, and a surface NOT on the adapter's allowlist is
+ * refused outright (未注册面被引用 ⇒ 拒).
+ *
+ * PROJECTION BAN: version strings, release metadata and upgrade counts may
+ * never satisfy this predicate. The surface value must reference the
+ * artifact PATH that was installed — a value derived from metadata (e.g.
+ * "I registered version 2.0.0") is not evidence that the OS will actually
+ * start that artifact. The evaluator checks the read-back against the
+ * expected target PATH; anything else is a refusal.
+ */
+import { ArtifactError } from "../artifact/errors.ts";
+import type { PredicateResult } from "./predicates.ts";
+
+/** A registered (allowlisted) surface with its expected read-back. */
+export interface AllowlistedSurface {
+  surface: ReadbackSurfaceLike;
+  /** What convergence requires the surface to read back (the artifact path). */
+  expectedTarget: string;
+}
+
+import type { ReadbackSurface } from "./predicates.ts";
+type ReadbackSurfaceLike = ReadbackSurface;
+
+export type SurfaceAllowlist = ReadonlyMap<string, AllowlistedSurface>;
+
+/**
+ * Build the allowlist from the app's declared surfaces + their expected
+ * targets. The allowlist IS the trust boundary: an id not on it cannot be
+ * read as evidence.
+ */
+export function buildSurfaceAllowlist(
+  entries: Array<{ surface: ReadbackSurface; expectedTarget: string }>,
+): SurfaceAllowlist {
+  const map = new Map<string, AllowlistedSurface>();
+  for (const entry of entries) {
+    if (map.has(entry.surface.id)) {
+      throw new Error(`duplicate readback surface id ${entry.surface.id}`);
+    }
+    map.set(entry.surface.id, entry);
+  }
+  return map;
+}
+
+/** Read an allowlisted surface; an unregistered id is a typed refusal. */
+export async function readAllowlisted(
+  allowlist: SurfaceAllowlist,
+  id: string,
+): Promise<{ value: string; source: string }> {
+  const entry = allowlist.get(id);
+  if (entry === undefined) {
+    throw new ArtifactError(
+      "UNREGISTERED_SURFACE",
+      `readback surface ${JSON.stringify(id)} is not on the adapter's allowlist`,
+    );
+  }
+  return entry.surface.read();
+}
+
+/**
+ * Evaluate host_lifecycle_converged over every allowlisted surface. All
+ * must read back their expected target PATH (projection ban: a metadata
+ * string cannot reference a path). Returns the predicate result; `source`
+ * names the surfaces that vouched (auditable, not prose).
+ */
+export async function evaluateLifecycleConvergence(
+  allowlist: SurfaceAllowlist,
+  observedAtMs: number,
+): Promise<PredicateResult> {
+  const detail: Record<string, string> = {};
+  const sources: string[] = [];
+  for (const [id, entry] of allowlist) {
+    let value: string;
+    try {
+      const read = await readAllowlisted(allowlist, id);
+      value = read.value;
+    } catch (err) {
+      return {
+        passed: false,
+        source: id,
+        observedAtMs,
+        detail: { error: (err as Error).message },
+      };
+    }
+    detail[id] = value;
+    if (!value.includes(entry.expectedTarget)) {
+      return {
+        passed: false,
+        source: id,
+        observedAtMs,
+        detail: {
+          expected: entry.expectedTarget,
+          got: value,
+          reason: "surface read-back does not reference the installed artifact path",
+        },
+      };
+    }
+    sources.push(id);
+  }
+  return {
+    passed: true,
+    source: sources.join(","),
+    observedAtMs,
+    detail,
+  };
+}

package/core/src/converge/predicates.ts

@@ -0,0 +1,57 @@
+/**
+ * Convergence predicates: an upgrade must mechanically PROVE it happened.
+ * Lifted from the supervisor-retirement design; the part no existing updater has.
+ *
+ * Rules (each enforced by a harness tooth):
+ *  - Evidence for binary_at_target comes from ONE live process
+ *    (ProcessEvidence.pid + startId), never from files/caches.
+ *  - Evidence for host_lifecycle_converged comes from a NAMED SSOT surface
+ *    declared by the platform adapter (e.g. macOS login-item via Electron
+ *    `app.getLoginItemSettings().openAtLogin`). A surface that cannot be
+ *    read back on a real machine may not claim same-source.
+ *  - PROJECTION BAN: version strings, release metadata, upgrade counts and
+ *    any metadata field must NOT satisfy either predicate. The teeth
+ *    feed true metadata + false surfaces and require non-green.
+ *  - FAIL-CLOSED RETIREMENT: legacy lifecycle managers (e.g. an old OS
+ *    supervisor entry) may be retired only AFTER host_lifecycle_converged
+ *    passed; otherwise keep the legacy manager and surface a typed HOLD.
+ */
+export interface PredicateResult {
+  passed: boolean;
+  /** Named surface the evidence was read from (auditable, not prose). */
+  source: string;
+  observedAtMs: number;
+  detail: Record<string, string>;
+}
+
+export interface ConvergenceReport {
+  /**
+   * The version this report evaluated (binary_at_target's TARGET — the
+   * experiment). Consumers MUST join on this, never on the status's
+   * current experiment/stable: a real conclusion pasted onto the wrong
+   * version reads like a lie and is harder to spot than a fake.
+   */
+  version: string;
+  binaryAtTarget: PredicateResult;
+  /**
+   * null = the app declared no OS-lifecycle read-back surface, so this was
+   * never observed. NOT the same as passing.
+   *
+   * It used to be reported as `{passed: true, source:
+   * "no-lifecycle-surfaces-configured"}`, which reads like a checked property
+   * and unlocked `retireLegacyManager()` -- retiring the machine's supervisor
+   * on the strength of something nobody looked at. Silence must never be
+   * spendable as evidence, so the absence has its own value in the type and
+   * every consumer has to handle it.
+   */
+  hostLifecycleConverged: PredicateResult | null;
+}
+
+/**
+ * Platform adapters declare their readback surfaces up front; converge
+ * refuses surfaces not on this allowlist (the named-surface discipline).
+ */
+export interface ReadbackSurface {
+  id: string; // e.g. "electron.getLoginItemSettings.openAtLogin"
+  read(): Promise<{ value: string; source: string }>;
+}

package/core/src/converge/report.ts

@@ -0,0 +1,38 @@
+/**
+ * Building the ConvergenceReport, which is only worth anything if it never
+ * invents a verdict.
+ *
+ * Two rules the shape enforces:
+ *  - a predicate reports what was OBSERVED, never a default. `binaryAtTarget`
+ *    passes because a live process said so, not because we got this far.
+ *  - a property nobody looked at is `null` (undeclared), not `passed: true`.
+ *    Reporting an unexamined property as passing once unlocked
+ *    `retireLegacyManager()` -- retiring the machine's supervisor on the
+ *    strength of silence.
+ */
+import type { ConvergenceReport, PredicateResult } from "./predicates.ts";
+import type { ProcessEvidence } from "../lifecycle/hostAdapter.ts";
+
+export function buildConvergenceReport(input: {
+  version: string;
+  evidence: ProcessEvidence | null;
+  lifecycle: PredicateResult | null;
+  declaredSurfaces: number;
+  nowMs: number;
+}): ConvergenceReport {
+  const { version, evidence, lifecycle, declaredSurfaces, nowMs } = input;
+  const binaryAtTarget: PredicateResult = {
+    passed: evidence !== null && evidence.version === version,
+    source: "host.healthProbe",
+    observedAtMs: nowMs,
+    detail: evidence
+      ? { version: evidence.version, startId: evidence.startId, pid: String(evidence.pid) }
+      : {},
+  };
+  const hostLifecycleConverged: PredicateResult | null =
+    lifecycle ??
+    (declaredSurfaces > 0
+      ? { passed: false, source: "not-converged", observedAtMs: nowMs, detail: {} }
+      : null); // the app declared no surface: never observed, never claimed
+  return { version, binaryAtTarget, hostLifecycleConverged };
+}