@arcforge/platform 2.0.188 → 2.0.190

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@arcforge/platform",
3
- "version": "2.0.188",
3
+ "version": "2.0.190",
4
4
  "description": "The Axon developer platform — headless project discovery, blueprint scanning, typegen, agent lifecycle, registry, benches and tests. Shared by the CLI/TUI and the Fleet extension.",
5
5
  "type": "module",
6
6
  "private": false,
@@ -44,20 +44,20 @@
44
44
  "deploy": "echo \"This package is published ONLY by apps/tui/scripts/release.ts, which pins workspace:* deps to concrete versions first. Publishing it directly ships an unresolvable dependency.\" && exit 1"
45
45
  },
46
46
  "dependencies": {
47
- "@arcforge/session": "2.0.188",
48
- "@arcforge/engines": "2.0.188",
49
- "@arcforge/err": "2.0.188",
50
- "@arcforge/types": "2.0.188",
51
- "@arcforge/cloud": "2.0.188",
52
- "@arcforge/capsule": "2.0.188",
53
- "@arcforge/core": "2.0.188",
54
- "@arcforge/vstr": "2.0.188",
47
+ "@arcforge/session": "2.0.190",
48
+ "@arcforge/engines": "2.0.190",
49
+ "@arcforge/err": "2.0.190",
50
+ "@arcforge/types": "2.0.190",
51
+ "@arcforge/cloud": "2.0.190",
52
+ "@arcforge/capsule": "2.0.190",
53
+ "@arcforge/core": "2.0.190",
54
+ "@arcforge/vstr": "2.0.190",
55
55
  "fft.js": "^4.0.4",
56
56
  "h3": "^1.15.11",
57
57
  "semver": "^7.7.4",
58
58
  "sharp": "^0.35.3",
59
59
  "typescript": "5.9.2",
60
- "@arcforge/link": "2.0.188"
60
+ "@arcforge/link": "2.0.190"
61
61
  },
62
62
  "devDependencies": {
63
63
  "@arcforge/air": "2.0.187",
@@ -12,7 +12,7 @@ import { assertConfigContained } from "./imports"
12
12
  import { Assets } from "./assets"
13
13
  import type { ArtifactsT } from "./artifacts"
14
14
  import type { StageT } from "./stage"
15
- import type { AgentImage, BundleResult } from "./types"
15
+ import type { AgentImage, BundleResult, BundleTarget } from "./types"
16
16
 
17
17
  /** Config keys the bundle reads that aren't part of the core authoring type yet. */
18
18
  type PublishableConfig = AxonConfig & {
@@ -47,7 +47,24 @@ export function Agent(opts: AgentOpts) {
47
47
  const frame = Frame({ root: root, kind: "agent" })
48
48
 
49
49
  return {
50
- async build(): Promise<BundleResult> {
50
+ /**
51
+ * `target` is required and has no default, deliberately.
52
+ *
53
+ * A published artifact and a deployable one are DIFFERENT artifacts
54
+ * with opposite requirements, and the difference used to be invisible
55
+ * — one `build()` served both. Deploy wants a RESOLUTION: exact
56
+ * versions, reproducible, because the target boots what was built.
57
+ * Publish wants a DECLARATION: ranges resolved on the consumer's
58
+ * machine against THEIR kernel.
59
+ *
60
+ * Shipping the lockfile to a consumer froze `@cody/io-engine` at the
61
+ * version the publisher happened to have, so a clone installed a cognet
62
+ * built for kernel ABI 10 onto a CLI providing ABI 11 and failed at
63
+ * prepare — with a message about a pin nobody in that session had
64
+ * chosen. A default here would let that class back in silently, so
65
+ * there is none: every caller states which artifact it wants.
66
+ */
67
+ async build(target: BundleTarget): Promise<BundleResult> {
51
68
  const loaded = await Config(root)
52
69
 
53
70
  // Before anything is compiled or staged. A config that reaches
@@ -107,7 +124,7 @@ export function Agent(opts: AgentOpts) {
107
124
  const stageDir = join(bundleDir, ".stage")
108
125
  try {
109
126
  await mkdir(stageDir, { recursive: true })
110
- await copyTree(root, stageDir)
127
+ await copyTree(root, stageDir, target)
111
128
  await stageSourceModules(root, stageDir, loaded, modules)
112
129
  await stageCognet(frame, bundleDir, stageDir)
113
130
 
@@ -127,10 +144,23 @@ export function Agent(opts: AgentOpts) {
127
144
  `${frame.name}/.dockerignore`,
128
145
  `${frame.name}/${BUNDLE_COGNET_DIR}`,
129
146
  )
130
- // The lockfile is what makes the consumer's install the SAME
131
- // install: without it `bun install` re-resolves every range and
132
- // the agent that ships is not the agent that was tested.
133
- if (fsx.exists(join(stageDir, "bun.lock"))) entries.push("bun.lock")
147
+ /*
148
+ * The lockfile ships to a DEPLOY and never to a publish.
149
+ *
150
+ * For a deploy it is the point: the image build must produce
151
+ * the same tree that was tested, so the exact resolution
152
+ * travels with it.
153
+ *
154
+ * For a publish it is actively wrong. A consumer resolving
155
+ * against their own kernel is the entire mechanism by which an
156
+ * ABI-bound cognet stays compatible — `/api/registry/resolve`
157
+ * answers "the newest version that fits ABI N" — and a shipped
158
+ * lockfile overrides that with whatever the publisher's machine
159
+ * resolved, months ago, against a different kernel. npm has the
160
+ * same rule for the same reason: package-lock.json is never
161
+ * published.
162
+ */
163
+ if (target === "deploy" && fsx.exists(join(stageDir, "bun.lock"))) entries.push("bun.lock")
134
164
  if (fsx.exists(join(stageDir, "bunfig.toml"))) entries.push("bunfig.toml")
135
165
  if (fsx.exists(join(stageDir, "README.md"))) entries.push("README.md")
136
166
 
@@ -185,7 +215,7 @@ export type AgentBundleT = ReturnType<typeof Agent>
185
215
  * publisher's machine from the result — a materialized tree bakes in whichever
186
216
  * platform's natives that machine resolved.
187
217
  */
188
- async function copyTree(root: string, stageDir: string): Promise<void> {
218
+ async function copyTree(root: string, stageDir: string, target: BundleTarget): Promise<void> {
189
219
  // `cognet` is here because an INLINE brain is the agent's own source, and
190
220
  // the most load-bearing source it has. The compiled bundle ships too (see
191
221
  // stageCognet) and is what actually runs, but shipping only that would
@@ -206,10 +236,17 @@ async function copyTree(root: string, stageDir: string): Promise<void> {
206
236
  // same here, it just has to be applied after the recursive copy.
207
237
  await rm(join(stageDir, INLINE_COGNET_DIR, "tsconfig.json"), { force: true })
208
238
 
209
- // bun.lock pins what install resolves; bunfig.toml carries the @axon scope →
210
- // registry mapping, without which a consumer's install cannot resolve an
211
- // Axon module at all.
212
- for (const file of ["package.json", "README.md", "bun.lock", "bunfig.toml"]) {
239
+ // bunfig.toml carries the @axon scope → registry mapping, without which a
240
+ // consumer's install cannot resolve an Axon module at all.
241
+ //
242
+ // bun.lock is staged only for a deploy. Excluding it from the STAGE as well
243
+ // as from the tar entry list is belt and braces on purpose: the entry list
244
+ // is a thing somebody edits, and a file that is not in the stage cannot be
245
+ // added back by an edit that looks harmless.
246
+ const files = ["package.json", "README.md", "bunfig.toml"]
247
+ if (target === "deploy") files.push("bun.lock")
248
+
249
+ for (const file of files) {
213
250
  const source = join(root, file)
214
251
  if (fsx.exists(source)) await cp(source, join(stageDir, file))
215
252
  }
@@ -7,7 +7,7 @@ import { Source } from "./source"
7
7
  import { Stage } from "./stage"
8
8
  import type { ManifestT } from "../manifest"
9
9
  import type { SourceModulesT } from "../modules"
10
- import type { BundleArtifact, BundleIdentity, BundleImage, SourceImage } from "./types"
10
+ import type { BundleArtifact, BundleIdentity, BundleImage, BundleTarget, SourceImage } from "./types"
11
11
 
12
12
  type BundleOpts = {
13
13
  root: string
@@ -60,7 +60,7 @@ export function Bundle(opts: BundleOpts) {
60
60
  const module = Module({ root: root, artifacts: artifacts, stage: stage })
61
61
  const source = Source({ root: root, artifacts: artifacts, stage: stage })
62
62
 
63
- async function run(kind: ProjectKind): Promise<BundleArtifact> {
63
+ async function run(kind: ProjectKind, target: BundleTarget): Promise<BundleArtifact> {
64
64
  // Prepare first, unconditionally.
65
65
  //
66
66
  // `build`, `publish` and `deploy` all arrive here, and none of them
@@ -77,7 +77,7 @@ export function Bundle(opts: BundleOpts) {
77
77
  const dir = Frame({ root: root, kind: kind }).path("build")
78
78
 
79
79
  const result = via === "agent"
80
- ? await agent.build()
80
+ ? await agent.build(target)
81
81
  : via === "module"
82
82
  ? await module.build()
83
83
  : await source.build(kind as SourceImage["kind"])
@@ -122,19 +122,19 @@ export function Bundle(opts: BundleOpts) {
122
122
  * bundle mid-operation is a caller that just rewrote package.json and
123
123
  * knows it.
124
124
  */
125
- session(kind: ProjectKind) {
125
+ session(kind: ProjectKind, target: BundleTarget) {
126
126
  let artifact: BundleArtifact | null = null
127
127
 
128
128
  return {
129
129
  /** The artifact, built on first call and reused thereafter. */
130
130
  async current(): Promise<BundleArtifact> {
131
- artifact ??= await run(kind)
131
+ artifact ??= await run(kind, target)
132
132
  return artifact
133
133
  },
134
134
 
135
135
  /** Discard and rebuild — call after mutating package.json. */
136
136
  async rebuild(): Promise<BundleArtifact> {
137
- artifact = await run(kind)
137
+ artifact = await run(kind, target)
138
138
  return artifact
139
139
  },
140
140
  }
@@ -13,4 +13,5 @@ export type {
13
13
  BundleImage,
14
14
  BundleArtifact,
15
15
  BundleIdentity,
16
+ BundleTarget,
16
17
  } from "./types"
@@ -109,3 +109,21 @@ export type BundleArtifact = {
109
109
  */
110
110
  assetsTarball: string | null
111
111
  }
112
+
113
+ /**
114
+ * Which artifact a bundle is producing.
115
+ *
116
+ * A published artifact and a deployable one are different things with opposite
117
+ * requirements, and this is what makes the caller say which:
118
+ *
119
+ * "publish" DECLARATIONS only. Dependencies are ranges the consumer resolves
120
+ * on their own machine, against their own kernel ABI. No lockfile:
121
+ * freezing a consumer's resolution to the publisher's is what
122
+ * installed an ABI-10 cognet onto an ABI-11 CLI.
123
+ * "deploy" A RESOLUTION. Exact versions travel with the artifact, because
124
+ * the image build must reproduce the tree that was tested.
125
+ *
126
+ * No default anywhere. The bug this exists to prevent was invisible precisely
127
+ * because one artifact silently served both.
128
+ */
129
+ export type BundleTarget = "publish" | "deploy"
@@ -45,7 +45,7 @@ export function Deploy(opts: DeployOpts) {
45
45
  // step the caller can render honestly. Without it a failure during
46
46
  // publish marks the bundle as the thing that failed.
47
47
  report({ step: "bundling" })
48
- const session = bundle.session("agent")
48
+ const session = bundle.session("agent", "deploy")
49
49
  let artifact = await session.current()
50
50
 
51
51
  while (true) {
@@ -322,7 +322,21 @@ export function Installer(opts: InstallerOpts) {
322
322
  // `track: "latest"` skips this: the whole point is to
323
323
  // re-resolve and overwrite the declared range, so treating
324
324
  // it as an untouchable pin is exactly the wrong answer.
325
- if (existing !== undefined && !constraint && options.track !== "latest") {
325
+ /*
326
+ * An ABI-bound install is never "already installed" on the
327
+ * strength of a declared range.
328
+ *
329
+ * The range answers "what did the author allow"; the
330
+ * question here is "does what is on disk fit THIS kernel",
331
+ * and those come apart exactly when it matters. A cloned
332
+ * agent declaring `^0.1.0` short-circuited here, so the
333
+ * ABI-aware resolve below never ran, and bun installed the
334
+ * lockfile's ABI-10 cognet onto an ABI-11 kernel.
335
+ *
336
+ * Re-resolving costs one registry call and is the only way
337
+ * to answer the question actually being asked.
338
+ */
339
+ if (existing !== undefined && !constraint && options.track !== "latest" && options.abi === undefined) {
326
340
  // …unless the range was auto-resolved against a
327
341
  // DIFFERENT registry than the one now configured. Such
328
342
  // a range describes a version this registry may never
@@ -340,12 +354,30 @@ export function Installer(opts: InstallerOpts) {
340
354
  }
341
355
 
342
356
  const version = await resolveVersion(name, constraint, options.abi)
343
- // `keepRange` re-applies the operator already declared, so
344
- // an update moves the version without narrowing the user's
345
- // constraint into a pin. See InstallOptions.
346
- const range = options.keepRange && constraint
347
- ? `${existingRange?.match(/^[\^~]/)?.[0] ?? ""}${version}`
348
- : constraint ?? `^${version}`
357
+ /*
358
+ * An ABI-resolved version is written as an EXACT pin.
359
+ *
360
+ * `resolveVersion` asked the registry "the newest version
361
+ * that fits kernel ABI N" and got a specific answer. Writing
362
+ * `^that` throws the answer away: the npm protocol has no
363
+ * concept of an ABI — deliberately, it is what makes a
364
+ * cognet installable by `bun add` at all — so any range left
365
+ * for bun to resolve is a range resolved WITHOUT the ABI.
366
+ * `^0.1.0` spanning an ABI-10 and an ABI-11 build is exactly
367
+ * that, and it is how a clone got the wrong one.
368
+ *
369
+ * A range is a semver compatibility claim, and an ABI-bound
370
+ * artifact is not semver-compatible in the way it implies.
371
+ * That is the whole reason `abi` exists as a separate axis.
372
+ */
373
+ const range = options.abi !== undefined
374
+ ? version
375
+ : options.keepRange && constraint
376
+ // `keepRange` re-applies the operator already
377
+ // declared, so an update moves the version without
378
+ // narrowing the user's constraint into a pin.
379
+ ? `${existingRange?.match(/^[\^~]/)?.[0] ?? ""}${version}`
380
+ : constraint ?? `^${version}`
349
381
 
350
382
  if (existing === range) {
351
383
  results.push({ status: "already-installed", name, version })
@@ -2,7 +2,7 @@ import type { FrameworkSource } from "./manifest/package"
2
2
  import { resolveDefaultBaseUrl, type AxonCloudClient, type DeployOptions, type DeployStep } from "@arcforge/cloud"
3
3
  import { err } from "@arcforge/err"
4
4
  import type { ProviderEntry } from "@arcforge/types"
5
- import { Bundle, type BundleArtifact } from "./bundle"
5
+ import { Bundle, type BundleArtifact, type BundleTarget } from "./bundle"
6
6
  import { Cognet } from "./cognet"
7
7
  import { Deploy, type DeployResult } from "./deploy"
8
8
  import { Installer } from "./installer"
@@ -194,8 +194,20 @@ export function Project(opts: ProjectOpts) {
194
194
  generate: typegen.generate,
195
195
 
196
196
  /** Package into the publishable artifact — image.json + source.tar.gz. */
197
- bundle(): Promise<BundleArtifact> {
198
- return bundle.build(kind)
197
+ /**
198
+ * `axon bundle` — package this project for inspection.
199
+ *
200
+ * Defaults to deploy-shaped, because that is what a person asking to
201
+ * see the artifact means: the complete, resolved tree that would boot.
202
+ *
203
+ * The default lives HERE and nowhere deeper. `Agent.build()` requires
204
+ * the target explicitly, because that is the layer where getting it
205
+ * wrong is invisible; this is a user-facing verb with a settled
206
+ * meaning, and `bundle("publish")` is how you inspect what a publish
207
+ * would actually ship — which is the thing nobody could see before.
208
+ */
209
+ bundle(target: BundleTarget = "deploy"): Promise<BundleArtifact> {
210
+ return bundle.build(kind, target)
199
211
  },
200
212
 
201
213
  /** Install declared modules, then generate types. What `axon prepare`/`dev` run. */
@@ -98,7 +98,7 @@ export function Publish(opts: PublishOpts) {
98
98
  if (!isPublishable(kind)) throw err("PUBLISH_UNSUPPORTED_KIND", { context: { kind } })
99
99
 
100
100
  report({ step: "bundling" })
101
- const session = bundle.session(kind)
101
+ const session = bundle.session(kind, "publish")
102
102
  let artifact = await session.current()
103
103
 
104
104
  // Before ANY registry mutation. A published version is immutable, so
@@ -4,7 +4,7 @@
4
4
  export { Runtime, type RuntimeT } from "./runtime"
5
5
  export { Escalations, type EscalationsT, type EscalationHandler } from "./escalations"
6
6
  export { Resolve, type ResolveT, type ResolvedAgent, type RefKind } from "./resolve"
7
- export { isRemote, type InstanceT, type InstanceSource, type RemoteTarget, type SpawnOpts } from "./instances"
7
+ export { isLinked, isRemote, type InstanceT, type InstanceSource, type RemoteTarget, type SpawnOpts } from "./instances"
8
8
  export type { AgentT } from "./agent"
9
9
  export { stageFor, unitFor, type BootStage, type BootProgress, type BuildUnit, type UnitTiming } from "./progress"
10
10
  export { sessionHasEntries, sessionHead, isListableSession, type SessionRecord, type SessionHead } from "./sessions"