@neuralis/brain-core 0.4.0 → 0.4.1

package/README.md

@@ -101,7 +101,7 @@ in the `neuralis-brain-core` skill; the git-plane security floors in `neuralis-s
 
 Lifecycle exports (`src/lifecycle.ts`):
 
-- `init`, `start`, `onBootstrapComplete`, `drain`, `stop`, `api`, `onCredentialChanged`, `health`, `onPrincipalRevoked`, `provisionProject` (`usecases/provisionProject.ts` — a NEW project's declared `seed:'auto'` sources, written complete through the same create path as the boot repair; see `src/services/README.md`), `deprovisionProject` (`usecases/deprovisionProject.ts` — on a PERMANENT project delete, ALL of the project's vector points leave the shared index in ONE bounded `deleteByFilter({ must: [{ field: 'projectId', equals: id }] })` — chunks + folder-ancestor points covered by the same keyword-index filter. MUST-HAVE: a failed delete throws, and so does a degraded boot where Qdrant is configured but the in-memory index is wired (a delete there would leave every real point in Qdrant); the host then stops the purge before any file is removed. It runs BEFORE the fs tree is removed, so resolving the brain infra cannot re-materialize the project dir).
+- `init`, `start`, `onBootstrapComplete`, `drain`, `stop`, `api`, `onCredentialChanged`, `health`, `onPrincipalRevoked`, `provisionProject` (`usecases/provisionProject.ts` — a NEW project's declared `seed:'auto'` sources, written complete through the same create path as the boot repair; see `src/services/README.md`), `deprovisionProject` (`usecases/deprovisionProject.ts` — on a PERMANENT project delete, ALL of the project's vector points leave the shared index in ONE bounded `deleteByFilter({ must: [{ field: 'projectId', equals: id }] })` — chunks + folder-ancestor points covered by the same keyword-index filter. MUST-HAVE: a failed delete throws — an unavailable vector store included (the typed `vector_store_unavailable` refusal) — and the host then stops the purge before any file is removed. It runs BEFORE the fs tree is removed, so resolving the brain infra cannot re-materialize the project dir).
 - `init` state exposes `services["package-source-roots"]` for kernel registration; its `listPackageSourceRoots` delegate is the same function as the direct API method, and its `subscribePackageSourceRoots(listener)` calls `listener(projectId)` after every committed source-config write of the app root (`SourceConfigMutation.onChanged` — fired outside the write lock, a no-op write never fires, a throwing listener is logged and never reaches the writer), so the host re-derives that project's flagged package roots at once.
 - `BrainCoreApi` — `getProjectServices`, `getProjectInfra`, `getFilesystem`, `upsertSourceConfig`, `listShellSourceRoots(projectId)` (every shell-capable source with its persisted permissions; feeds agent-core's shell uri-policy gate and the terminal's host-tab resolver; NOT access-filtered — consumers evaluate the policy against the caller's own `SessionContext`. Rows carry an explicit **`plane`**: `container` sources contribute their `containerRoot`, resolved by the canonical `resolveLocalRoot`; **device-plane** sources contribute a raw `hostRoot` and an intentionally EMPTY `containerRoot` — no container path exists for them, and the empty value is load-bearing, because the consumer's local-plane filter drops rootless entries so a folder on a device can never leak into a local-plane lookup even if `plane` were ignored. The plane is the kernel's `sourcePlane` over the STORED connection (a `host` folder naming a `device` is the device plane), never the slug string — an ordinary folder may legitimately be named `host-notes`. Kinds that host no shell at all (brain vectors, webtop) contribute nothing), and `listSourceRuntimeSummaries(projectId, { userId, agentId, role?, grantedFeatures? })` (the READ sibling of `listShellSourceRoots`, feeding agent-core's `<runtime_stack>` source rendering — **all** connector kinds, **access-filtered** (device-plane rows carry `containerDir: null` — their root is a path in the OPERATOR's filesystem with no container equivalent, and the local-shaped derivation would otherwise print a container path that does not exist, baked into every agent's cached system prompt) via `canAccessScope` (with the source's plane: a user-scope device folder lists only for its owner) → `files.readOthers`/deny-by-default, each row carrying connector, `os_uri`/`container_dir`, the caller-effective uri-policy, `description`, and the cached index snapshot; reads persisted source-config JSON ONLY — no live walk / no vector count — so it is safe to call once per stream. Agent-core renders the stable structure in the cached `<runtime_stack>` prefix and the volatile counts + on/off in `<workspace_live>`. Disabled sources are INCLUDED, marked `enabledEffective:false`). `listPackageSourceRoots(projectId)` (enumerate every project-associated source as a runtime package-source candidate `{ slug, uriRoot, containerRoot, scope, plane, packageFolders, enabled, kind }` — `plane` is `sourcePlane` of the stored connection, the host's only source of it; identity-free like `listShellSourceRoots`, ALL candidates returned so the host applies the floor — package folders + enabled + a root this process opens; `containerRoot` of a device folder is agent-core's `devices.localFolderRoot` answer, asked only on a native host for a folder with package folders — the app's own loopback device inside the owner's ceiling — and `''` for any other device; the host's `projectPackages` consumes it to scan + hot-reload each package folder alongside `_packages/`). Filesystem events reach the `/brain-core/events` SSE route and the discovered `filesystem` channel of the host `/api/events` hub through ONE authorization adapter: it takes the real session, authorizes EACH requested agent deny-by-default (a foreign agent yields zero events, never an existence-confirming error), and filters events by user/project/types and the authorized agent or source.
 
@@ -143,7 +143,7 @@ There is intentionally no README inside the contribution folders; this section i
 ## How it plugs into the package-system kernel
 
 - `init(ctx: PackageInitContext)` builds shared infra (Qdrant + lazy embedder), the per-project `CommunityInfraFactory`, the global `AppSourceConfigStore`, the per-package sync/vector loggers, and the `VectorHealthService`. It returns a `BrainCoreState` and never starts the sync scheduler.
-- `start(state)` begins the background vector activity watch (`startQdrantWatch` wires `usecases/vectorActivityWatch.ts`, every `brainQdrantWatchIntervalMs` — 30 s — `BRAIN_INFRA_MODE=local` only). The vector backend wired at init is **not** hot-swapped (out of scope); the watch surfaces a degraded flag and logs transitions — `vector.qdrant.lost` and `vector.qdrant.recovered` (the latter notes that a restart re-enables Qdrant-backed search when the wired backend is in-memory). While Qdrant is reachable the same tick reads the server's optimizer tracker (one `GET /collections/<c>/optimizations?with=completed`, at most 50 finished runs) — Qdrant does not log its own background optimization — and writes `vector.optimizer.completed {optimizer, status, points, segments, durationMs}` once per finished run (the SERVER's start/finish times, so a run shorter than the tick is not lost), `vector.optimizer.long` once for a run still going after 10 minutes, and `vector.optimizer.overflow {returned}` when every returned run is new while earlier ones were seen (the tracker rolled past runs between two reads). The first read only seeds: runs finished before the process started are not re-logged at every boot. These lines go to the console (`docker logs`) AND `vector.jsonl`; the per-probe `vector.qdrant.health` line stays file-only. The lifecycle `health(state)` returns structured backend/connectivity checks to the generic runtime health aggregate; no vector-status package API is exposed. The interval is cleared in `stop()`.
+- `start(state)` begins the background vector activity watch (`startQdrantWatch` wires `usecases/vectorActivityWatch.ts`, every `brainQdrantWatchIntervalMs` — 30 s — whenever the backend is Qdrant, `local` and `real` alike). Qdrant is wired at init whenever it is intended, reachable or not; the watch is what drives its availability gate: one bounded probe at a time (a probe-only client bounded by `brainQdrantProbeTimeoutMs`, 5 s, boot-read), one immediate probe when a call finds the store gone, and on the first answer the boot-once steps (server-version read, embedding-generation boot with its collection ensure) run once before the gate opens — no restart, ever. It logs `vector.qdrant.lost` and `vector.qdrant.recovered` (held sync jobs then run) and reports `degraded` / `store_unreachable` to health while the gate is closed. Every Qdrant request is bounded by `brainQdrantRequestTimeoutMs` (default 300 000 — the client's own default, so no long index build is newly aborted; boot-read). While Qdrant is reachable the same tick reads the server's optimizer tracker (one `GET /collections/<c>/optimizations?with=completed`, at most 50 finished runs) — Qdrant does not log its own background optimization — and writes `vector.optimizer.completed {optimizer, status, points, segments, durationMs}` once per finished run (the SERVER's start/finish times, so a run shorter than the tick is not lost), `vector.optimizer.long` once for a run still going after 10 minutes, and `vector.optimizer.overflow {returned}` when every returned run is new while earlier ones were seen (the tracker rolled past runs between two reads). The first read only seeds: runs finished before the process started are not re-logged at every boot. These lines go to the console (`docker logs`) AND `vector.jsonl`; the per-probe `vector.qdrant.health` line stays file-only. The lifecycle `health(state)` returns structured backend/connectivity checks to the generic runtime health aggregate; no vector-status package API is exposed. The interval is cleared in `stop()`.
 - `onBootstrapComplete(state, ctx: BootstrapCompleteContext)` is the single deferred-wiring entry point: it reads the published registries through `ctx.platform.connectorRegistries()` and starts the `SyncScheduler` from `ctx.platform.hostIdentity()`. The factory resolves those registries lazily through its init context. There are no imperative setters (`setHostIdentity`, `setConnectorRegistries`).
 - `init` delegates to `wiring.buildBrainState`, wiring the declared `ctx.config` reader and GLOBAL-only `ctx.credentials.resolveCredential` into the embedding provider before shared infrastructure is built. Platform facts are read lazily through `ctx.platform`; no config setter or source-running bootstrap push is exposed. Credential changes reach the bounded lifecycle hook, and runtime health reads structured vector checks.
 - **Data formats.** brain-core's three durable record kinds — `brain-core/embedding-lock` (v3), `brain-core/source-config` (v7) and `brain-core/pending-changes` (v1, the `_pending/changes.jsonl` journal) — are declared on the kernel's data-format ledger at module load (`src/store/dataFormats.ts`) and claimed at the top of `init`, before the first read: a kind a newer binary raised stops the init by name. Per record, the lock's `version` and a source config's or pending change's `formatVersion` (absent = 1) are checked before every rewrite — the check reads the STORED record, never the incoming one, so a config built fresh over a newer file is refused too — and a newer record is never rewritten (the journal's appends stay open; its compaction refuses). Every source-config write stamps the declared version (`SOURCE_CONFIG_FORMAT.version`, 7); an identical re-upsert still writes nothing. `embedding-lock` v3 and `source-config` v7 are `upgrade: offline` kinds: the app refuses to start over older data naming `neuralis upgrade`, which raises them (`scripts/embeddingLockV3.ts`, exported as `@neuralis/brain-core/upgrade`; `source-config` is a chain — the host's `package-identity-v2` step, then `scripts/sourceRootPairV1.ts`, exported as `@neuralis/brain-core/upgrade/source-root-pair`, which fills the root pairs, then `scripts/sourceToFolderV1.ts`, exported as `@neuralis/brain-core/upgrade/source-to-folder`, which merges the old `local` and `host` records into ONE `folder` kind and turns `recognizesPackages` into `packageFolders`, then `scripts/sourceToHostV1.ts`, exported as `@neuralis/brain-core/upgrade/source-to-host`, which spells that kind `host`, then the host's `source-uri-subject-v1` step, which moves owner/admin grant rows to `priority` (the caller's role priority, n or stronger), then the host's `source-use-grants-v1` step, which places agent-core's private-agent rows right after a project's first agent-folder write row and appends one read row per user who already used an agent they did not create — each step passes a record a later step already raised through untouched, so a resumed chain never re-reads one in an older vocabulary). Source configs are written durably, and one that fails validation is skipped AND logged (`source-config.invalid-skipped`), never silently gone.