@forgezero/agent 0.1.28 → 0.1.30

package/README.md

@@ -118,12 +118,30 @@ root-only control socket or signed outbound claim path, then the deployment
 manager validates the checked-in definition and submits it to the common keyed
 queue.
 
+## Project context for any repository
+
+Conversation memory is not a project database. Initialize one vendor-neutral,
+Git-owned context and generate the small files each AI product discovers:
+
+```bash
+fz project init
+# edit .forgezero/project.json and create its named truth sources
+fz project sync
+fz project check
+```
+
+`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, Copilot instructions and the Cursor rule
+are generated adapters. They contain no independent architecture or progress.
+`fz project check` fails when a truth source is missing or an adapter was edited
+by hand. Tools and skills remain optional execution aids; accepted decisions and
+status live in the repository and therefore survive switching AI agents.
+
 ## Deployment definitions
 
-A repository may commit `.fz/deploy.yaml` with its own roles, prerequisite
+A repository may commit `.fz/deploy.json` with its own profiles, prerequisite
 checks, commands, and the exact secret names each step needs. ForgeZero does not
 choose a tenant's database, framework, or deploy shape. The agent validates the
-file before executing any command, prepares only the selected role, and gives a
+file before executing any command, prepares only the selected profile, and gives a
 step only the vault values it explicitly names. `await` returns the complete
 pipeline result; no polling service or persistent queue is required.
 
@@ -131,7 +149,9 @@ The daemon owns source checkout and command execution. Bootstrap explicitly
 awaits release one because the API does not exist yet, then the Agent consumes a
 one-use platform enrolment capability. There is no branch watcher. Every normal
 platform or tenant release is one durable API delivery atomically expanded to
-one row for every explicit compute binding:
+one row for every independently attached compute target. Release-scoped steps
+run on one target elected by stable target ordering, never on a user-declared
+coordinator:
 `pending` is written before dispatch, `running` and a fenced lease before project
 code, and only an awaited successful pipeline writes `deployed`. An expired
 claim can be recovered; its stale token cannot renew or finish.
@@ -188,7 +208,7 @@ An operator may also force a deployment and await the complete result over the
 private control socket:
 
 ```bash
-fz-agent deploy --revision=<full-40-character-commit> --coordinator
+fz-agent deploy --revision=<full-40-character-commit> --release-executor
 fz-agent status
 fz-agent pause
 fz-agent pause-key --key=project:production

package/dist/agent-heartbeat.js

@@ -429,7 +429,7 @@ async function postSignedNode(options, path, body) {
 }
 
 // src/version.ts
-var VERSION2 = "0.1.28";
+var VERSION2 = "0.1.30";
 
 // src/agent-heartbeat.ts
 var unquote = (value) => value.replace(/^['"]|['"]$/g, "");

package/dist/cli/agent-install.d.ts

@@ -44,7 +44,7 @@ export interface InstallOptions {
     controlSocketPath?: string;
     repository?: string;
     branch?: string;
-    role?: string;
+    profile?: string;
     deployRoot?: string;
     publicApiUrl?: string;
     deploymentEnvironment?: Record<string, string>;

package/dist/definition.d.ts

@@ -1,14 +1,20 @@
 import type { Pipeline, PipelineStep } from './pipeline';
 import { type SoftwareRequirement } from './software';
-export declare const PIPELINE_VERSION: 1;
-export interface PipelineRole {
-    name: string;
+/**
+ * Version two separates a repository's deploy recipe from the computes that use
+ * it. A target chooses one named profile in the control plane; compute names,
+ * counts and cluster leadership never belong in Git.
+ */
+export declare const PIPELINE_VERSION: 2;
+export interface PipelineProfile {
     software: readonly SoftwareRequirement[];
 }
 export interface DeployStep extends PipelineStep {
     phase: 'build' | 'release' | 'migrate' | 'health';
-    /** The coordinator runs this on one selected node, never on every replica. */
-    once?: boolean;
+    /** Run on this target, or on the one deterministic release executor. */
+    scope: 'target' | 'release';
+    /** Optional profile filter. An omitted list applies to every profile. */
+    profiles?: readonly string[];
     /** Run only when every named non-secret deployment coordinate has this value. */
     when?: Readonly<Record<string, string>>;
 }
@@ -16,12 +22,12 @@ export interface DeployDefinition {
     version: typeof PIPELINE_VERSION;
     name: string;
     requireAttestation?: boolean;
-    roles: readonly PipelineRole[];
+    profiles: Readonly<Record<string, PipelineProfile>>;
     steps: readonly DeployStep[];
 }
 export declare class DefinitionError extends Error {
     constructor(message: string);
 }
-/** Validate parsed YAML before any command from it is allowed to run. */
+/** Validate parsed JSON before any command from it is allowed to run. */
 export declare function parseDeployDefinition(value: unknown): DeployDefinition;
-export declare function phasePipeline(definition: DeployDefinition, phase: DeployStep['phase']): Pipeline;
+export declare function phasePipeline(definition: DeployDefinition, phase: DeployStep['phase'], profile: string, executeRelease?: boolean): Pipeline;

package/dist/definition.js

@@ -3,6 +3,16 @@ import { readFileSync } from "node:fs";
 var BUN_INSTALLER_SHA256 = "bab8acfb046aac8c72407bdcce903957665d655d7acaa3e11c7c4616beae68dd";
 var ARANGO_SHA256 = "b5a9197b4343f2ed554e1ebc1ef8e6529c7c39cde0035cdc311a4747a3355066";
 var CLOUDFLARED_SHA256 = "9d71c677db00134c1bd4144b7783486b654ad281b1ea62b4972098d19f770f17";
+var OS_CATALOG = [
+  { id: "ubuntu", version: "26.04", architecture: "x64", status: "active" }
+];
+var SOFTWARE_CATALOG = [
+  { id: "bun", version: "1.3.14", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" },
+  { id: "nginx", version: "ubuntu-26.04", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" },
+  { id: "arangodb", version: "3.11.14", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" },
+  { id: "cloudflared", version: "2026.7.3", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" },
+  { id: "ufw", version: "ubuntu-26.04", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" }
+];
 var UBUNTU_2604_X64 = [
   {
     requirement: { id: "bun", version: "1.3.14" },
@@ -41,7 +51,7 @@ function observeSoftwareHost(osRelease = readFileSync("/etc/os-release", "utf8")
     architecture
   };
 }
-function validateSoftwareRequirements(value) {
+function validateSoftwareRequirements(value, options = {}) {
   if (!Array.isArray(value) || value.length > 32)
     throw new Error("software requirements must be an array of at most 32 entries");
   const seen = new Set;
@@ -59,13 +69,18 @@ function validateSoftwareRequirements(value) {
     if (seen.has(requirement.id))
       throw new Error(`duplicate software requirement: ${requirement.id}`);
     seen.add(requirement.id);
+    const catalog = SOFTWARE_CATALOG.find((candidate) => candidate.id === requirement.id && candidate.version === requirement.version);
+    if (!catalog || catalog.status === "retired" || options.channel !== "development" && catalog.status !== "active") {
+      throw new Error(`software requirement is not available for ${options.channel ?? "production"}: ${requirement.id}@${requirement.version}`);
+    }
     return requirement;
   });
 }
 async function ensureSoftwareRequirements(requirementsInput, options) {
   const requirements = validateSoftwareRequirements(requirementsInput);
   const observation = options.observation ?? observeSoftwareHost();
-  if (observation.os.id !== "ubuntu" || observation.os.versionId !== "26.04" || observation.architecture !== "x64") {
+  const os = OS_CATALOG.find((candidate) => candidate.id === observation.os.id && candidate.version === observation.os.versionId && candidate.architecture === observation.architecture);
+  if (!os || os.status !== "active") {
     throw new Error(`unsupported software strategy: ${observation.os.id} ${observation.os.versionId} ${observation.architecture}`);
   }
   const results = [];
@@ -90,7 +105,7 @@ async function ensureSoftwareRequirements(requirementsInput, options) {
 }
 
 // src/definition.ts
-var PIPELINE_VERSION = 1;
+var PIPELINE_VERSION = 2;
 
 class DefinitionError extends Error {
   constructor(message) {
@@ -115,6 +130,7 @@ var exactKeys = (value, allowed, where) => {
   if (unknown.length > 0)
     throw new DefinitionError(`${where} contains unknown field(s): ${unknown.join(", ")}.`);
 };
+var NAME = /^[a-z][a-z0-9-]{0,62}$/;
 var RESERVED_STEP_ENV = new Set([
   "PATH",
   "HOME",
@@ -129,37 +145,52 @@ var RESERVED_STEP_ENV = new Set([
 ]);
 function parseDeployDefinition(value) {
   const root = record(value, "pipeline");
-  exactKeys(root, ["version", "name", "requireAttestation", "roles", "steps"], "pipeline");
+  exactKeys(root, ["$schema", "version", "name", "requireAttestation", "profiles", "steps"], "pipeline");
+  if (root.$schema !== undefined && (typeof root.$schema !== "string" || !root.$schema.startsWith("https://"))) {
+    throw new DefinitionError("pipeline.$schema must be an HTTPS URL.");
+  }
   if (root.version !== PIPELINE_VERSION) {
     throw new DefinitionError(`pipeline.version must be ${PIPELINE_VERSION}.`);
   }
-  if (!Array.isArray(root.roles) || root.roles.length === 0) {
-    throw new DefinitionError("pipeline.roles must contain at least one role.");
+  const rawProfiles = record(root.profiles, "pipeline.profiles");
+  const profileEntries = Object.entries(rawProfiles);
+  if (profileEntries.length === 0 || profileEntries.length > 32) {
+    throw new DefinitionError("pipeline.profiles must contain from 1 to 32 named profiles.");
   }
   if (!Array.isArray(root.steps) || root.steps.length === 0) {
     throw new DefinitionError("pipeline.steps must contain at least one step.");
   }
-  const roles = root.roles.map((raw, index) => {
-    const role = record(raw, `roles[${index}]`);
-    exactKeys(role, ["name", "software"], `roles[${index}]`);
-    if (!Array.isArray(role.software)) {
-      throw new DefinitionError(`roles[${index}].software must be an array.`);
+  const profiles = {};
+  for (const [name, raw] of profileEntries) {
+    if (!NAME.test(name))
+      throw new DefinitionError(`pipeline profile name is invalid: ${name}.`);
+    const profile = record(raw, `profiles.${name}`);
+    exactKeys(profile, ["software"], `profiles.${name}`);
+    if (!Array.isArray(profile.software)) {
+      throw new DefinitionError(`profiles.${name}.software must be an array.`);
     }
-    return {
-      name: text(role.name, `roles[${index}].name`),
-      software: validateSoftwareRequirements(role.software)
-    };
-  });
-  if (new Set(roles.map((role) => role.name)).size !== roles.length) {
-    throw new DefinitionError("pipeline.roles must have unique names.");
+    profiles[name] = { software: validateSoftwareRequirements(profile.software) };
   }
   const phases = new Set(["build", "release", "migrate", "health"]);
   const steps = root.steps.map((raw, index) => {
     const step = record(raw, `steps[${index}]`);
-    exactKeys(step, ["name", "run", "phase", "secrets", "once", "always", "timeoutMs", "when"], `steps[${index}]`);
+    exactKeys(step, ["name", "run", "phase", "scope", "profiles", "secrets", "always", "timeoutMs", "when"], `steps[${index}]`);
     const phase = text(step.phase, `steps[${index}].phase`);
     if (!phases.has(phase))
       throw new DefinitionError(`steps[${index}].phase is not supported.`);
+    if (step.scope !== "target" && step.scope !== "release") {
+      throw new DefinitionError(`steps[${index}].scope must be target or release.`);
+    }
+    let selectedProfiles;
+    if (step.profiles !== undefined) {
+      if (!Array.isArray(step.profiles) || step.profiles.length === 0 || step.profiles.some((name) => typeof name !== "string" || !Object.hasOwn(profiles, name))) {
+        throw new DefinitionError(`steps[${index}].profiles must name existing profiles.`);
+      }
+      selectedProfiles = [...step.profiles];
+      if (new Set(selectedProfiles).size !== selectedProfiles.length) {
+        throw new DefinitionError(`steps[${index}].profiles must not contain duplicates.`);
+      }
+    }
     if (step.secrets !== undefined && (!Array.isArray(step.secrets) || step.secrets.some((name) => typeof name !== "string" || !/^[A-Z_][A-Z0-9_]*$/.test(name)))) {
       throw new DefinitionError(`steps[${index}].secrets must contain names only.`);
     }
@@ -190,8 +221,9 @@ function parseDeployDefinition(value) {
       name: text(step.name, `steps[${index}].name`),
       run: text(step.run, `steps[${index}].run`),
       phase,
+      scope: step.scope,
+      profiles: selectedProfiles,
       secrets: step.secrets,
-      once: step.once === true,
       always: step.always === true,
       timeoutMs,
       when
@@ -204,15 +236,18 @@ function parseDeployDefinition(value) {
     version: PIPELINE_VERSION,
     name: text(root.name, "pipeline.name"),
     requireAttestation: root.requireAttestation === true,
-    roles,
+    profiles,
     steps
   };
 }
-function phasePipeline(definition, phase) {
+function phasePipeline(definition, phase, profile, executeRelease = false) {
+  if (!Object.hasOwn(definition.profiles, profile)) {
+    throw new DefinitionError(`pipeline profile does not exist: ${profile}.`);
+  }
   return {
     name: `${definition.name}:${phase}`,
     requireAttestation: definition.requireAttestation,
-    steps: definition.steps.filter((step) => step.phase === phase)
+    steps: definition.steps.filter((step) => step.phase === phase && (!step.profiles || step.profiles.includes(profile)) && (step.scope === "target" || executeRelease))
   };
 }
 export {

package/dist/deployment-pull.d.ts

@@ -7,12 +7,12 @@ export interface RemoteDeploymentClaim {
     claimToken: string;
     claimExpiresAtTs: number;
     attempt: number;
-    /** True on exactly one compute in a clustered delivery. */
-    coordinator: boolean;
+    /** True on the one target deterministically elected for this release. */
+    releaseExecutor: boolean;
     source: {
         repository: string;
         branch: string;
-        role: string;
+        profile: string;
         knownHosts?: string;
         auth?: GitSourceAuth;
     };

package/dist/deployment.d.ts

@@ -16,8 +16,8 @@ export interface CommandResult {
 export interface DeploymentRequest {
     /** Optional exact commit from a verified webhook. Never a branch name. */
     revision?: string;
-    /** Whether this node is the coordinator allowed to execute `once` steps. */
-    coordinator?: boolean;
+    /** True only for the target deterministically elected for release-scoped steps. */
+    releaseExecutor?: boolean;
 }
 export interface DeploymentResult {
     key: string;
@@ -46,7 +46,7 @@ export interface DeploymentOptions {
     key: string;
     repository: string;
     branch: string;
-    role: string;
+    profile: string;
     root: string;
     publicApiUrl?: string;
     sourceAuth?: GitSourceAuth;
@@ -74,8 +74,8 @@ export declare class DeploymentError extends Error {
 /**
  * One source and one pipeline owner.
  *
- * A request may choose an exact commit and whether this assigned node is the
- * coordinator. It cannot choose a repository, branch, working directory or
+ * A request may choose an exact commit and carry the control plane's
+ * deterministic release-executor decision. It cannot choose a repository, branch, working directory or
  * command: those are sealed into the agent unit and the checked-out definition.
  */
 export declare function createDeploymentManager(options: DeploymentOptions): {