Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript

docs(hcc): state that a non-directory state carries no merge signature

Alfredo Lopeze8698d168af7
diff --git a/docs/architecture/host-storage-layout.md b/docs/architecture/host-storage-layout.md
index e2c4bcc3c..3128932a3 100644
--- a/docs/architecture/host-storage-layout.md
+++ b/docs/architecture/host-storage-layout.md
@@ -49,9 +49,12 @@ SQLite.
**Trigger.** It acts only on the split-layout signature: `state/` is a real
directory (not a symlink) holding at least one `state.db*` entry. Every other
-tree, including an agent folder named `workspace/` or `state/` without a
-database, exits 0 unchanged. Stateful and desktop Hosts therefore never
-change.
+tree exits 0 unchanged, including an agent folder named `workspace/` or
+`state/` without a database, and a `state` that is a symlink or not a
+directory. An agent can create those on a stateful Host, so they must not
+stop it from starting. A stateful or desktop tree changes only if it carries
+the signature, which only the earlier init or an agent-created
+`state/state.db*` entry produces.
**Moves**, in this order:
@@ -73,7 +76,7 @@ stays in `Init:Error`.
| Case | Line contains |
| ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
-| F1: `state`, `workspace` or the PVC root is a symlink, not a directory, or escapes the root; a `state.db*` entry is a symlink | `directory is a symlink`, `is not a directory`, `escapes the workspace PVC root`, `SQLite file is a symlink` |
+| F1: `workspace` or the PVC root is a symlink, not a directory, or escapes the root; a real `state/` cannot be listed and searched; a `state.db*` entry is a symlink or not a regular file; a directory that decides a collision cannot be listed | `directory is a symlink`, `is not a directory`, `escapes the workspace PVC root`, `state directory is not readable and searchable`, `SQLite file is a symlink`, `SQLite file is not a regular file`, `cannot list directory` |
| F2: more than one live database family across the root, `state/` and `workspace/` | `more than one live SQLite database` |
| F3: a name to move already exists at the root, or under both `state/` and `workspace/`; `workspace/lost+found` exists | `destination exists`, `exists under both state/ and workspace/`, `lost+found would remain` |
| F4: the PVC root, `state/` or `workspace/` is not writable by the container uid | `not writable by uid` |
diff --git a/host-context-controller/package-lock.json b/host-context-controller/package-lock.json
index 36c9817a2..837d90a31 100644
--- a/host-context-controller/package-lock.json
+++ b/host-context-controller/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-host-context-controller",
- "version": "0.1.386",
+ "version": "0.1.387",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-host-context-controller",
- "version": "0.1.386",
+ "version": "0.1.387",
"license": "SEE LICENSE IN LICENSE",
"dependencies": {
"@clerum/codex-catalog-projection": "file:../packages/codex-catalog-projection",
diff --git a/host-context-controller/package.json b/host-context-controller/package.json
index 4963b0b4f..756176347 100644
--- a/host-context-controller/package.json
+++ b/host-context-controller/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-host-context-controller",
- "version": "0.1.386",
+ "version": "0.1.387",
"description": "Host Context Controller - provides McpServer CRDs to mcp-host via REST API",
"main": "dist/main.js",
"engines": {
diff --git a/host-context-controller/src/statelessDeployment.ts b/host-context-controller/src/statelessDeployment.ts
index 7b3f78c58..456437990 100644
--- a/host-context-controller/src/statelessDeployment.ts
+++ b/host-context-controller/src/statelessDeployment.ts
@@ -30,12 +30,13 @@ function shellSingleQuote(value: string): string {
*
* The merge runs only when `state/` is a real directory holding a
* `state.db*` entry, the signature the earlier init leaves. Any other tree
- * (stateful, desktop, empty, or a user folder named `state/` or
- * `workspace/`) exits 0 untouched.
+ * exits 0 untouched: stateful, desktop, empty, a user folder named `state/`
+ * or `workspace/`, and a `state` that is a symlink or not a directory (an
+ * agent can create those on a stateful Host, so they must not stop it).
*
* Every refusal prints one line and exits 1 before the first move:
- * F1 `state` or `workspace` is a symlink or not a directory, a real
- * `state/` cannot be listed and searched, a `state.db*` entry is a
+ * F1 `workspace` is a symlink or not a directory, a real `state/`
+ * cannot be listed and searched, a `state.db*` entry is a
* symlink or not a regular file, or a directory that decides a
* collision cannot be listed;
* F2 more than one live database (a `state.db` main file or its journals)
diff --git a/host-context-controller/test/statelessDeployment.workspaceLayoutMerge.test.ts b/host-context-controller/test/statelessDeployment.workspaceLayoutMerge.test.ts
index 77bd39b22..3372ebe00 100644
--- a/host-context-controller/test/statelessDeployment.workspaceLayoutMerge.test.ts
+++ b/host-context-controller/test/statelessDeployment.workspaceLayoutMerge.test.ts
@@ -457,13 +457,25 @@ describe('workspace layout merge', () => {
writeFileSync(join(root, 'elsewhere', 'state.db'), 'not ours')
symlinkSync(join(root, 'elsewhere'), join(root, 'state'))
},
+ 'state is a regular file': root => {
+ writeFileSync(join(root, 'state'), 'user file')
+ },
+ 'state is a dangling symlink': root => {
+ symlinkSync(join(root, 'missing'), join(root, 'state'))
+ },
+ 'workspace is a symlink and there is no state/': root => {
+ mkdirSync(join(root, 'elsewhere'))
+ writeFileSync(join(root, 'elsewhere', 'SOUL.md'), 'user file')
+ symlinkSync(join(root, 'elsewhere'), join(root, 'workspace'))
+ },
}
for (const [name, prepare] of Object.entries(cases)) {
const root = statefulRoot()
prepare(root)
const before = snapshot(root)
- expect(merge(root), name).toEqual({ status: 0, stderr: '' })
- expect(snapshot(root), name).toEqual(before)
+ // Soft, so one failing case does not hide the others.
+ expect.soft(merge(root), name).toEqual({ status: 0, stderr: '' })
+ expect.soft(snapshot(root), name).toEqual(before)
}
// Witness: the split tree is changed by the same script.
const split = splitRoot()