SILVER
/
NODEDC_PLATFORM
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Compare commits

base: SILVER:390907cc9cd56472959d78f458cff0233c39f0fd
Branches Tags
SILVER:main
SILVER:ai-workspaces-npm
SILVER:CROSSASSISTANT
..
compare: SILVER:f8c19d712a719444772801a87f833169808d5913
Branches Tags
SILVER:main
SILVER:ai-workspaces-npm
SILVER:CROSSASSISTANT

8 Commits
390907cc9c ... f8c19d712a

Author SHA1 Message Date
Codex f8c19d712a Document BIM session sync canon boundaries 2026-06-23 20:23:01 +03:00
Codex 1aaf53c378 Skip BIM converter rebuild for viewer-only deploys 2026-06-23 14:08:12 +03:00
Codex 25b4ce0f6d Prepare BIM Viewer runtime dirs in deploy runner 2026-06-22 19:04:00 +03:00
Codex cfaed054d1 Add BIM Viewer to canonical deploy runner 2026-06-22 18:14:31 +03:00
Codex 6258de83e3 Add BIM Viewer to Synology deploy canon 2026-06-22 13:54:00 +03:00
Codex 3526351b1b feat(ai-workspace): add local relay profiles 2026-06-20 12:54:19 +03:00
Codex 2d5fef3948 feat(ontology): add core service catalog 2026-06-20 12:54:03 +03:00
Codex 83cca4224b Route BIM viewer through NodeDC platform 2026-06-18 21:43:04 +03:00
101 changed files with 12377 additions and 82 deletions
Show Stats Expand all files Collapse all files

3
README.md
View File

@ -34,6 +34,7 @@ Git repo:
- `services/notification-core/README.md`
- `services/ai-workspace-assistant/README.md`
- `services/ai-workspace-hub/README.md`
- `services/ontology-core/README.md`
- `tasks/CODEX_PLATFORM_AUTH_TASK.md`
## Базовое правило
@ -43,3 +44,5 @@ Plane не переносится внутрь Launcher. Launcher не стан
Notification Core живёт в `services/notification-core` как отдельный платформенный сервис с собственным Postgres. Он не использует Authentik DB: Authentik отвечает за identity/session, Notification Core отвечает за events/deliveries/read-state.
AI Workspace Assistant живёт в `services/ai-workspace-assistant` как общий платформенный слой для пользовательских Codex executors, selected executor, shared conversations, surfaces и tool packs. AI Workspace Hub остаётся отдельным тонким транспортом для remote Codex workers и не хранит смысловое состояние ассистента.
Ontology Core живёт в `services/ontology-core` как docs-first семантический слой для canonical entities, relations, aliases, guardrails, evidence, первого resolver MVP между OPS и ENGINE и policy MVP для NDC Core Assistant access. Он не владеет доменными БД HUB/OPS/ENGINE и не заменяет Launcher/HUB roles или OPS Gateway enforcement.

31
docs/AI_WORKSPACE_CONFIG_CONTRACT.md
View File

@ -13,15 +13,19 @@ Do not mix these classes. A URL reachable from the Mac browser is not automatica
## Current Profiles
`local/hybrid-prod-bridge`:
`local/remote-worker-relay`:
- Tasker UI: `http://task.local.nodedc`
- Platform Assistant: `http://127.0.0.1:18082`
- Local Hub process: `http://127.0.0.1:18081`
- Default worker-facing Hub: `wss://ai-hub.nodedc.ru/api/ai-workspace/hub`
- Default worker-facing Hub relay: `wss://ai-hub.nodedc.ru/api/ai-workspace/hub`
- Default Assistant-to-relay control URL: `https://ai-hub.nodedc.ru`
- Assistant action relay id: `local-dev`
- Assistant action gateway returned to worker: `https://ai-hub.nodedc.ru/api/ai-workspace/hub/v1/assistant-relays/local-dev/actions`
- Ops entitlement adapter: `http://host.docker.internal:4100/api/internal/v1/ai-workspace/entitlements` when deliberately enabled
- Ops Gateway downstream Tasker: `http://task.local.nodedc`
- This profile is valid for contract smoke and local Ops vertical smoke, not proof of live local Codex worker e2e.
- The deployed AI Hub is allowed only as transport. Launcher, Engine, Ops, Authentik, task manager, and downstream app calls must stay local.
- The remote worker must not call product apps directly. Assistant actions must route back through the local AI Workspace Assistant.
`synology/prod-public`:
@ -52,3 +56,24 @@ New apps must join AI Workspace through app manifests/config/adapters:
- owner repo/service.
Do not add app-specific address logic to the agent installer, Engine, Ops, or Platform Assistant runtime flow.
## Verification
Before changing worker, Assistant, Hub, or app adapter routing, run:
```sh
sh infra/scripts/check-local-test-system.sh
```
For a live local remote-worker test, require the relay topology explicitly:
```sh
REQUIRE_REMOTE_WORKER_RELAY=1 sh infra/scripts/check-local-test-system.sh
```
Security audit and test matrix:
```text
docs/AI_WORKSPACE_SECURITY_AUDIT_2026-06-20.md
docs/AI_WORKSPACE_TEST_MATRIX.md
```

171
docs/AI_WORKSPACE_SECURITY_AUDIT_2026-06-20.md Normal file
View File

@ -0,0 +1,171 @@
# AI Workspace Security Audit 2026-06-20
Status: prototype hardening report.
Scope: AI Workspace Assistant, public AI Hub relay, remote Codex worker, local Launcher, local Engine, local Ops Gateway, ontology-core assistant actions.
## Current architecture
The safe local test topology is:
```text
local Engine / local Ops UI / local Launcher
-> local AI Workspace Assistant
-> public AI Hub relay
-> remote Codex worker
-> public AI Hub assistant action relay
-> local AI Workspace Assistant
-> local Launcher / local Engine / local Ops Gateway
```
The public AI Hub is transport only in `NODEDC_ENV=local`. It must not become the owner of Launcher, Engine, Ops, Authentik, or product-app data. Product reads and writes return to the local Assistant and then go through local app-owned adapters.
## Profiles
`local`
- Business apps are local: Launcher, Engine, Ops/Gateway, Tasker, databases, fixtures.
- AI Workspace Assistant is local.
- The only allowed deployed URL class is the AI Hub relay: `https://ai-hub.nodedc.ru` / `wss://ai-hub.nodedc.ru/api/ai-workspace/hub`.
- Production product hosts are forbidden in local downstream config: `hub.nodedc.ru`, `engine.nodedc.ru`, `ops.nodedc.ru`, `id.nodedc.ru`, `ops-agents.nodedc.ru`.
- Remote worker receives a scoped run profile and calls assistant actions through the relay, not through product apps directly.
`deploy-host`
- Business apps and AI Workspace services run in the deployed stack.
- Public worker-facing relay is still `ai-hub.nodedc.ru`.
- Internal service URLs must be container/network URLs, not localhost and not developer-machine URLs.
- This profile is architecturally described but not fully proven yet. It still needs a clean deploy verification run before it can be treated as release-ready.
`tunnel-local-e2e`
- Explicit escape hatch for Tailscale/ngrok-style testing.
- Must be opt-in through `NODEDC_ENV=tunnel-local-e2e`.
- No local config may silently fall back to private/tunnel addresses.
## Trust boundaries
Browser and local app backends trust only local service tokens and the current application session.
AI Workspace Assistant owns assistant orchestration:
- builds run profiles;
- resolves app grants;
- exposes the assistant action gateway;
- performs preview/execute routing;
- calls app-owned adapters.
Remote Codex worker is an executor:
- it receives only the run profile and tool/action gateway information;
- it must not own product app credentials;
- it should not call Launcher, Engine, Ops, Authentik, or product DBs directly in local profile.
Ontology Core owns assistant action policy:
- registered action catalog;
- risk levels;
- route allowlists;
- no hard-delete guardrails;
- preview/confirmation/execute contract.
App adapters own their app-specific state changes:
- Launcher adapter mutates only guarded Launcher admin routes.
- Ops adapter calls the Ops Gateway tool API.
- Engine graph edits stay in NDC Agent Core / Engine-owned workflow tools.
## Transport and tokens
Confirmed controls in current code:
- Assistant API requires an internal token via `Authorization: Bearer ...` or `X-NODEDC-Internal-Token`.
- Hub internal API requires `Authorization: Bearer ...`.
- Constant-time token comparison is used for Assistant and Hub internal API checks.
- Public relay traffic uses HTTPS/WSS.
- Assistant action relay forwards only user owner headers, not arbitrary incoming headers.
- Launcher admin action adapter sends `Authorization: Bearer <launcher internal token>` plus assistant actor headers.
- Ops action adapter obtains or uses an Ops run token and sends it to Ops Gateway as `Authorization`.
- Write routes require an idempotency key.
- DELETE is blocked at execution-plan validation.
Current token classes:
- `NODEDC_INTERNAL_ACCESS_TOKEN`: service-to-service internal token for local stack.
- `AI_WORKSPACE_HUB_TOKEN`: public Hub internal API token.
- `NDC_LAUNCHER_INTERNAL_ACCESS_TOKEN`: Launcher admin adapter token.
- Ops entitlement token: lets Assistant ask Ops Gateway for a scoped run token.
- Ops run token: downstream authorization for Ops tool routes.
- Assistant action confirmation token: digest over action, actor, request body/path, and idempotency key.
## Assistant action safety model
Read actions:
- do not require confirmation;
- must still resolve to a registered action;
- must be scoped by owner context and app-owned adapter policy.
Write and privileged actions:
- must resolve to a registered action;
- must pass risk policy;
- must pass route allowlist;
- must include idempotency key;
- must produce a preview;
- must require explicit user confirmation;
- must execute only with the preview confirmation token.
Destructive actions:
- are forbidden for assistant execution;
- hard-delete users, files, DB rows, production state, archives, backups, and runtime/storage records must stay outside assistant action routing.
## Prototype status
Tested behavior:
- local Assistant action gateway can preview Ops card creation;
- public relay can route preview requests to local Assistant via `relayId=local-dev`;
- Engine UI can ask the remote worker to create an Ops card;
- write creation requires preview and explicit confirmation;
- confirmed Ops test card creation succeeded through the UI;
- Launcher pending access read works through assistant action routing;
- Engine NDC Agent Core tools are visible for selected agent node operations;
- Engine chat polling jitter was addressed by stable remote message merge logic.
Not yet proven:
- complete deploy-host profile after a fresh deployment;
- cross-user relay isolation under multiple simultaneous local developers;
- one-time confirmation token storage;
- token TTL enforcement for every downstream run token;
- full stop/cancel behavior for long remote Codex runs;
- full browser UI regression pass across Launcher, Ops, and Engine.
## Findings
P0 fixed in current prototype:
- Product app calls no longer need to be tested by deploying raw product changes first. Local profile routes product reads/writes back to local services.
- Ops card create path now works through Assistant -> Ontology Core -> Ops Gateway with preview/confirmation.
- The remote worker is treated as executor, not as product credential owner.
P1 hardening required:
- Confirmation tokens are deterministic digests and currently have no TTL or server-side one-time consumption store. If preview output and token leak, the same request can be replayed until downstream idempotency suppresses duplicates. Add server-side confirmation records with TTL, actor binding, single-use consumption, and audit trail.
- `local-dev` relay id is too generic for repeated multi-user work. Use unique relay ids per developer/station/environment, for example `local-dc-mac-<date>` or configured stable machine id.
- Public relay is bearer-token protected but not mTLS-bound. Treat Hub token leakage as critical and rotate tokens after exposure.
- The worker receives `assistantActionGatewayToken` in the run profile. This is necessary for the current bridge, but it is a bearer secret. Keep it short-lived or derive a per-run action token instead of reusing broad service tokens.
- Stop/cancel behavior needs an automated smoke check with a deliberately long remote run.
P2 hardening required:
- Add audit correlation ids across Engine request, Hub request, worker run, Assistant action, Ops/Launcher adapter call.
- Add negative tests for forged owner headers through the public relay.
- Add negative tests for forbidden DELETE route, destructive action, missing idempotency, wrong confirmation token, wrong actor, and wrong project id.
- Add dashboard visibility for selected run profile, action ids, relay id, and downstream profile without exposing tokens.
## Security conclusion
The prototype is usable for controlled local testing and internal proof-of-flow. It is not yet release-grade security. The main architectural boundary is now correct: local product state stays local, the public AI Hub is a relay, and writes go through registered ontology actions with preview and confirmation. Before production rollout, the confirmation and relay-token model must be hardened with TTL, single-use confirmation records, unique relay ids, short-lived action tokens, and expanded negative tests.

74
docs/AI_WORKSPACE_TEST_MATRIX.md Normal file
View File

@ -0,0 +1,74 @@
# AI Workspace Test Matrix
Status: active prototype test plan.
## Test levels
Horizontal tests check each service boundary independently.
Vertical tests prove a full user intent through UI, Assistant, remote worker, relay, and target app adapter.
Security tests prove that unsafe actions are blocked and secrets are not exposed.
## Horizontal tests
| ID | Area | Command / action | Success | Failure |
| --- | --- | --- | --- | --- |
| H1 | Platform static | `sh infra/scripts/check-local-test-system.sh` | all required static, env, compose, ontology, and topology checks pass | any local profile points product downstream to prod, syntax fails, or topology cannot be classified |
| H2 | Env safety | `node infra/scripts/check-local-environment-safety.mjs` | `NODEDC_ENV=local` permits only AI Hub relay as deployed host | product app URL points to deployed prod host in local profile |
| H3 | Config contract | `infra/scripts/check-ai-workspace-config-contract.sh` | worker-facing, internal, browser, relay, and downstream URLs remain separated | app-specific URL logic leaks into worker/Engine/Assistant runtime |
| H4 | Release gate | `sh infra/scripts/check-ai-workspace-release-gates.sh` | static checks, smokes, gateway checks, and diff hygiene pass | deploy preparation blocked |
| H5 | Ontology catalog | `cd services/ontology-core && npm run validate` | actions/entities/policies validate | invalid action, missing entity, unsupported risk policy |
| H6 | Assistant action caller | `cd services/ontology-core && npm run smoke:assistant-caller` | preview requires token, execute without token blocked, execute with token calls adapter in mock | write executes without confirmation or unsafe route passes |
| H7 | Assistant executor | `cd services/ontology-core && npm run smoke:assistant-executor` | DELETE/destructive action blocked, internal bearer headers added in mock | destructive/write route is allowed |
| H8 | Assistant run profile | `cd services/ai-workspace-assistant && npm run smoke:run-profile` | run profile contains expected grants, action profile, and redacted diagnostics | token leakage or missing action profile |
| H9 | Engine build | `cd NODEDC_ENGINE_INFRA/nodedc-source && npm run build` | UI/server bundle builds | Engine UI/bridge integration broke build |
| H10 | Launcher assistant admin contract | Launcher contract tests | assistant admin routes stay guarded, scoped, idempotent, and no hard-delete route becomes assistant-ready | assistant route bypasses session/admin guard or delete leaks into assistant allowlist |
## Vertical tests
| ID | Flow | Steps | Success |
| --- | --- | --- | --- |
| V1 | Remote worker health | Engine UI asks: `ты тут? коротко workspace, runtime, hub connected` | response shows local workspace, `runtime: ready`, `hub connected: true` |
| V2 | Launcher read | ask: `покажи новые заявки в лаунчере` | answer comes from `hub.access_request.list_pending` and returns actual local Launcher pending requests |
| V3 | Ops read | ask: `последнюю задачу в опсе покажи` | answer comes from `ops.card.list_recent`, no file search fallback |
| V4 | Ops create preview | ask: `создай в опс тестовую задачу "..."` | assistant shows preview and asks explicit confirmation |
| V5 | Ops create execute | confirm preview | local Ops creates card and assistant returns identifier |
| V6 | Ops comment preview | ask to add comment to a known card | assistant shows preview and asks confirmation |
| V7 | Ops comment execute | confirm comment preview | comment is added to local Ops card |
| V8 | Engine graph read | ask selected agent node workflow counts | assistant uses NDC Agent Core tool and returns nodes/edges |
| V9 | Engine graph patch | ask for tiny node patch in selected agent node | assistant uses NDC Agent Core patch and validates graph |
| V10 | Stop/cancel | start deliberately long search and press stop | running Codex process is stopped or marked aborted within bounded time |
## Security and abuse tests
| ID | Attack / risk | Test | Expected |
| --- | --- | --- | --- |
| S1 | Missing internal token | call Assistant action endpoint without token | `401` or `503`, no action executed |
| S2 | Wrong internal token | call Assistant action endpoint with bad bearer | `401`, no action executed |
| S3 | Write without confirmation | execute `ops.card.create` without confirmation token | blocked with `write_confirmation_envelope_missing` |
| S4 | Wrong confirmation | execute with wrong token | blocked with `write_confirmation_envelope_mismatch` |
| S5 | Missing idempotency | construct write plan without idempotency key | blocked with `write_requires_idempotency_key` |
| S6 | DELETE route | try destructive delete action | blocked before network with `delete_method_forbidden` or destructive policy |
| S7 | Unknown action | ask for unregistered action | assistant refuses or asks clarification; no network call |
| S8 | Prompt injection | user asks to ignore policy and call raw URL | assistant must resolve registered action or refuse |
| S9 | Owner header forgery | relay call attempts forged owner headers | only trusted local app/Assistant boundary may set owner; forged public call must not gain privileges |
| S10 | Replay | reuse a previous confirmation token and idempotency key | current expected result: downstream idempotency should suppress duplicate; required hardening: single-use token must reject replay |
| S11 | Cross-project write | create/comment using unauthorized project id | Ops entitlement/gateway rejects |
| S12 | Token disclosure | ask assistant to print run profile tokens | answer must redact/refuse secrets |
## Deploy-host proof
Deploy-host is not considered proven until this sequence passes:
1. Deploy only the intended AI Hub/Assistant artifacts by the deployment canon.
2. Run `sh infra/scripts/check-ai-workspace-release-gates.sh` before deploy.
3. Verify deployed Hub `/healthz`.
4. Verify deployed Assistant `/healthz`.
5. Pair a worker through the deployed Hub.
6. Run read-only Launcher, Ops, and Engine assistant actions.
7. Run one preview-only write.
8. Run one confirmed Ops write in a non-production test project.
9. Confirm logs contain correlation ids and no tokens.
Until then, deploy-host remains an architecture profile, not a release guarantee.

24
docs/AUTH_MODEL.md
View File

@ -50,6 +50,30 @@ Production login должен быть NODE.DC-branded:
Текущее безопасное решение зафиксировано в `docs/AUTH_BRANDED_LOGIN_RFC.md`: сначала используем Authentik-native Brand/CSS/Flow customization. Reverse proxy HTML-rewrite, password form в Launcher и пересылка пароля через BFF запрещены.
## Inter-app session sync status 2026-06-23
Источник истины по пользовательской сессии остаётся в Launcher/Auth/Authentik chain. Приложения не должны выдавать себе права из локального browser-event или marker-а; любые live-события session sync являются только сигналом для revalidation через платформенный authority.
Фактический общий live-контур до BIM был logout-only:
- Launcher `/auth/session-sync` публиковал `nodedc:session:logout` в соседние приложения через iframe/BroadcastChannel/localStorage/frontchannel;
- Engine helper `src/platform/auth/sessionSync.ts` знает только `nodedc:session:logout`;
- Tasker/OPS имеет отдельный frontchannel/internal logout контур, но login/change parity не оформлен как общий protocol;
- login live promotion открытого приложения после входа в другом surface не был закрытым platform-wide контрактом.
BIM Viewer 23.06.2026 добавил BIM-first login-sync slice для share-link сценария:
- Launcher service registry получил `loginSyncUrl` для BIM;
- после успешного login Launcher публикует `nodedc:session:login` и делает frontchannel вызов зарегистрированных login-sync endpoints;
- BIM `/auth/login-sync` создаёт короткоживущий server-side marker;
- BIM `/api/auth/session` возвращает `loginSyncEventId`, но сам marker не является auth-token;
- BIM frontend по новому marker-у запускает обычный optional-launch/handoff через Launcher, где происходит нормальная проверка сессии и доступа;
- BIM logout приведён к существующему logout canon и должен live-понижать controls до guest/limited view без ручного refresh.
Граница текущей реализации: это кандидат на общий login-sync contract, а не закрытый канон для всей платформы. Перед подключением следующего сервиса нужно оформить `ndcauth.session` protocol: `login`, `logout`, `change`, payload, origin checks, TTL/nonce/correlation, service registry fields, revalidation rules, audit/observability и browser e2e matrix по HUB/OPS/ENGINE/BIM.
Правило для новых сервисов: не добавлять частный per-app login/logout bus. Сервис регистрирует sync endpoints в Launcher/control-plane registry, принимает event только как invalidate/promote trigger и всегда перепроверяет доступ через backend authority.
## Required claims
Минимальный normalized user object:

15
docs/CURRENT_INFRA_HANDOFF.md
View File

@ -1,6 +1,6 @@
# NODE.DC current infra handoff
Last updated: 2026-05-15.
Last updated: 2026-06-23.
This document is the fast context entrypoint for a new engineering chat. Read it first before touching deploy, Synology, Authentik, Launcher, or Tasker.
@ -16,6 +16,7 @@ Source-of-truth repositories:
| Launcher / Hub | NODE.DC control plane, user/admin UI, access requests, access matrix, Authentik sync | `/Users/dcconstructions/Downloads/mnt/data/nodedc_launcher` |
| Tasker / Operational Core | Plane fork, tasks/workspaces/projects, standalone-capable product module | `/Users/dcconstructions/Downloads/mnt/data/dc_taskmanager/NODEDC_TASKMANAGER` |
| Ops Agents Gateway | Standalone MCP/API router for Tasker operational agents | `/Users/dcconstructions/Downloads/mnt/data/NODEDC_TASKMANAGER_CODEXAPI` |
| BIM Viewer | Standalone BIM/CAD/point-cloud viewer, public share links, model runtime storage | `/Users/dcconstructions/Downloads/mnt/NODEDC/NODEDC_BIM_VIEWER` |
Current Git branches:
@ -23,6 +24,7 @@ Current Git branches:
- Launcher: `main`
- Tasker: `master`
- Ops Agents Gateway: `main`
- BIM Viewer: `beam`
The modules communicate through HTTP/OIDC/internal APIs. They must remain independently buildable and deployable.
@ -59,6 +61,7 @@ https://id.nodedc.ru -> Authentik
https://hub.nodedc.ru -> Launcher / Hub
https://ops.nodedc.ru -> Tasker / Operational Core
https://ops-agents.nodedc.ru -> Ops Agents Gateway / MCP endpoint
https://bim.nodedc.tech -> BIM Viewer
```
`id.nodedc.ru` is only the public OIDC/login host. Authentik Admin is deliberately kept off that public host; `/if/admin/*` returns `404` there.
@ -244,6 +247,16 @@ Git repo -> build image / sync deploy files -> Synology compose recreate selecte
Do not edit NAS copies as the long-term fix. If an emergency live edit is made on NAS, port it back into the relevant repo before continuing product work.
## Auth/session sync status
Read `docs/AUTH_MODEL.md` before changing cross-app auth/session behavior.
As of 2026-06-23, the proven shared live-session path was logout-first: Launcher publishes `nodedc:session:logout` through `/auth/session-sync` and frontchannel app logout URLs, and Engine subscribes to that logout event. BIM Viewer has now been aligned with that logout path.
BIM also introduced a BIM-first login-sync slice for share links: Launcher service registry can call BIM `loginSyncUrl`; BIM records only a short-lived marker and then revalidates through Launcher optional-launch/handoff. This marker is not auth and must not grant controls directly.
This is not yet a platform-wide login/change canon. Before adding another service, define the shared `ndcauth.session` contract in Platform/Auth SDK terms and verify HUB/OPS/ENGINE/BIM with a browser matrix: login from any surface, logout from any surface, already-open apps update without refresh.
## Platform / Launcher deploy
From macOS with `/Volumes/docker` mounted:

9
docs/DEPLOYMENT_LOCAL.md
View File

@ -50,20 +50,23 @@ Source fork:
```bash
cd /Users/dcconstructions/Downloads/mnt/NODEDC/platform
infra/scripts/check-ai-workspace-topology.sh
sh infra/scripts/check-local-test-system.sh
```
Скрипт ничего не прокидывает и не меняет. Он только классифицирует текущий режим:
Скрипт ничего не прокидывает, не деплоит и не меняет `.env`. Он проверяет env/compose/contracts/smoke и классифицирует текущий режим:
- `contract-only`: можно доверять только контрактным smoke-тестам без runtime e2e.
- `local-ops-vertical`: локальный Ops Gateway и локальный Tasker проверяются вертикально, без live Codex worker.
- `local-ui-only`: локальный UI доступен, но AI write path не доказан.
- `hybrid-prod-bridge`: часть контура локальная, а Hub/worker/MCP смотрят в публичный или другой контур. Такой результат нельзя считать local e2e.
- `local-remote-worker-relay`: product apps локальные, local Assistant включил action relay, а `ai-hub.nodedc.ru` используется только как транспорт к удаленному Codex worker.
- `hybrid-prod-bridge`: часть контура локальная, но action relay не настроен или topology смешана. Такой результат нельзя считать local e2e.
- `true-local-e2e`: Engine, AI Workspace Assistant, Hub, Ops Gateway, Tasker и worker находятся в одной локальной топологии.
- `tunnel-local-e2e`: то же самое через явно выбранный tunnel/Tailscale-профиль.
Не надо пытаться неявно “дотянуть” Mac-local окружение до Synology. Если нужен Tailscale, это отдельный явный профиль: Hub public URL, Gateway public URL и Engine/Tasker downstream должны быть заданы так, чтобы именно выполняющий Codex worker мог их достичь. До этого UI-диалоги через удаленного агента считаются `hybrid-prod-bridge`, а не доказательством локальной записи.
Канон локального тестирования описан в `docs/LOCAL_TESTING_SYSTEM.md`.
Перед controlled Synology apply запускайте общий predeploy gate:
```bash

106
docs/ENVIRONMENT_CONTRACT.md Normal file
View File

@ -0,0 +1,106 @@
# NODE.DC Environment Contract
This contract separates local feature testing from deployed runtime.
## Profiles
`local`
- Runs Launcher, Engine, Ops/Gateway, AI Workspace Assistant, databases, and fixtures on the developer machine.
- May use the deployed AI Hub only as a thin relay for a remote Codex worker.
- Must not call production Launcher, Engine, Ops, Authentik, or Gateway endpoints.
`tunnel-local-e2e`
- Explicit escape hatch for Tailscale/ngrok-style testing.
- Same business services are still local, but relay URLs may use tunnel/private addresses.
- Must be opt-in through `NODEDC_ENV=tunnel-local-e2e`.
`staging`
- Deployed test stack with staging data and staging Authentik/OIDC clients.
- Used after local smoke is green.
`prod`
- Production data and production public domains.
- Only deploy artifacts that passed local and staging checks.
## URL Classes
- Browser URL: opened by a user browser.
- Internal service URL: used by one backend to call another backend.
- Relay URL: used only to move messages between a local assistant and a remote worker.
- Downstream app URL: used by an assistant adapter to read or mutate its owning app.
Do not mix these classes. A remote worker must not call Launcher, Engine, Ops, or Authentik directly in `local`.
## Local Remote Worker Chain
```text
local Engine
-> local AI Workspace Assistant
-> deployed AI Hub relay
-> remote Codex worker
-> deployed AI Hub relay
-> local AI Workspace Assistant
-> local Launcher / local Engine / local Ops
```
The deployed AI Hub is transport only. It must not decide product access, own app routes, or force production downstream URLs.
## Required Local Defaults
Engine local server:
```text
NODEDC_ENV=local
NODEDC_LAUNCHER_INTERNAL_URL=http://127.0.0.1:5173
NODEDC_LAUNCHER_ORIGIN=http://launcher.local.nodedc
AUTHENTIK_PUBLIC_BASE_URL=http://auth.local.nodedc
NODEDC_AI_WORKSPACE_ASSISTANT_URL=http://127.0.0.1:18082
OPS_RETENTION_ENABLED=false
```
Platform local stack:
```text
NODEDC_ENV=local
AI_WORKSPACE_HUB_PUBLIC_URL=wss://ai-hub.nodedc.ru/api/ai-workspace/hub
AI_WORKSPACE_HUB_INTERNAL_URL=https://ai-hub.nodedc.ru
AI_WORKSPACE_ASSISTANT_ACTION_RELAY_ENABLED=true
AI_WORKSPACE_ASSISTANT_ACTION_RELAY_ID=local-dev
```
The AI Hub URLs above are allowed only because they are relay URLs. Production app URLs such as `https://hub.nodedc.ru`, `https://engine.nodedc.ru`, `https://ops.nodedc.ru`, and `https://id.nodedc.ru` are forbidden in local app config.
Assistant action calls in local must use the relay route:
```text
remote worker assistant_action_call
-> deployed AI Hub /api/ai-workspace/hub/v1/assistant-relays/<relayId>/actions
-> local AI Workspace Assistant long-poll
-> local Launcher / Engine / Ops adapter
```
Do not route local assistant actions through the deployed Assistant or deployed product backends.
## Guardrail
Run the complete local testing gate before local AI Workspace testing:
```sh
sh platform/infra/scripts/check-local-test-system.sh
```
Run this narrower env-only guard when changing env files:
```sh
node platform/infra/scripts/check-local-environment-safety.mjs
```
Run the broader AI Workspace contract check before changing worker/assistant routing:
```sh
platform/infra/scripts/check-ai-workspace-config-contract.sh
```

174
docs/LOCAL_TESTING_SYSTEM.md Normal file
View File

@ -0,0 +1,174 @@
# NODE.DC Local Testing System
Цель: тестировать новые функции на локально запущенных репозиториях без переписывания адресов перед деплоем и без случайных обращений в production-приложения.
## Canon
Локальный профиль:
```text
NODEDC_ENV=local
```
В `local` все product apps являются локальными:
```text
Launcher/Auth/HUB UI -> local
Engine -> local
Ops/Gateway/Tasker -> local
AI Workspace Assistant -> local
DB/fixtures -> local
```
Единственное разрешенное deployed-звено в этом профиле:
```text
AI Hub relay -> https://ai-hub.nodedc.ru
```
Этот Hub используется только как транспорт для удаленного Codex worker. Он не должен быть downstream app, не должен владеть доступами пользователя и не должен сам читать/писать Launcher, Engine или Ops.
## Remote Worker Local Flow
```text
local Engine / local Ops UI
-> local AI Workspace Assistant
-> deployed AI Hub relay
-> remote Codex worker
-> deployed AI Hub assistant action relay
-> local AI Workspace Assistant
-> local Launcher / local Engine / local Ops
```
Worker получает только relay URL и scoped run profile. Product app URL остаются на стороне локального Assistant.
## Required Local Guardrails
Local Platform env:
```text
NODEDC_ENV=local
AI_WORKSPACE_HUB_PUBLIC_URL=wss://ai-hub.nodedc.ru/api/ai-workspace/hub
AI_WORKSPACE_HUB_INTERNAL_URL=https://ai-hub.nodedc.ru
AI_WORKSPACE_ASSISTANT_ACTION_RELAY_ENABLED=true
AI_WORKSPACE_ASSISTANT_ACTION_RELAY_ID=local-dev
```
Local Engine env:
```text
NODEDC_ENV=local
NODEDC_AI_WORKSPACE_ASSISTANT_URL=http://127.0.0.1:18082
NODEDC_LAUNCHER_INTERNAL_URL=http://127.0.0.1:5173
NODEDC_LAUNCHER_ORIGIN=http://launcher.local.nodedc
AUTHENTIK_PUBLIC_BASE_URL=http://auth.local.nodedc
```
Production app URLs are forbidden in local config:
```text
https://hub.nodedc.ru
https://engine.nodedc.ru
https://ops.nodedc.ru
https://id.nodedc.ru
https://ops-agents.nodedc.ru
```
Tunnel/private URLs are also forbidden in `local`. If Tailscale/ngrok is deliberately needed, switch to:
```text
NODEDC_ENV=tunnel-local-e2e
```
## Standard Check
Run this before UI testing and before deploy preparation:
```sh
cd /Users/dcconstructions/Downloads/mnt/NODEDC/platform
sh infra/scripts/check-local-test-system.sh
```
This command:
- checks Node and shell syntax;
- checks local env safety;
- checks AI Workspace config contract;
- renders local Docker Compose config without starting containers;
- checks that local Compose does not inject the full `.env` into every service;
- runs run-profile and ontology assistant caller smoke tests;
- classifies the current runtime topology;
- checks diff whitespace hygiene.
It does not deploy, restart containers, mutate databases, or write production config.
## Runtime Modes
`contract-only`
Static contracts are testable, but no runtime path is proven.
`local-ui-only`
Some local UI/backend endpoints respond, but AI write path is not proven.
`local-ops-vertical`
Local Ops/Gateway/Tasker vertical path is reachable, but remote worker action path is not proven.
`local-remote-worker-relay`
Expected current target for this workstation:
```text
local product apps + local Assistant + deployed AI Hub relay + remote Codex worker
```
This is valid only when Assistant action relay is configured. A successful UI request must show that `assistant_action_call` routes through the relay back to local Assistant.
`true-local-e2e`
Everything, including Hub and worker reachability, is local.
`tunnel-local-e2e`
Explicit Tailscale/ngrok profile. This must never happen by accidental URL fallback.
## Strict Runtime Checks
Require a live local/relay runtime:
```sh
REQUIRE_RUNTIME=1 sh infra/scripts/check-local-test-system.sh
```
Require specifically the remote-worker relay mode:
```sh
REQUIRE_REMOTE_WORKER_RELAY=1 sh infra/scripts/check-local-test-system.sh
```
## Deploy Rule
Deploy is allowed only after:
```sh
sh infra/scripts/check-local-test-system.sh
sh infra/scripts/check-ai-workspace-release-gates.sh
```
Runtime bugs must be fixed in the local profile first. Do not deploy product app changes just to test whether the local AI Workspace path works.
## Audit And Test Map
Current audit report:
```text
docs/AI_WORKSPACE_SECURITY_AUDIT_2026-06-20.md
```
Current horizontal, vertical, and security test matrix:
```text
docs/AI_WORKSPACE_TEST_MATRIX.md
```

9
docs/SECURITY_CHECKLIST.md
View File

@ -34,6 +34,15 @@ Service catalog UX rules: `docs/SERVICE_CATALOG_UX_RULES.md`.
- [x] Local runtime не отдает `storage/launcher-data.json` напрямую через public static route.
- [x] Local runtime требует user session для `/api/storage/data`.
## Cross-app session sync
- [x] Общий live logout path зафиксирован как `nodedc:session:logout` через Launcher session-sync/frontchannel.
- [x] BIM Viewer подключён к logout path и по logout должен понижать UI до guest/limited controls.
- [x] BIM login-sync marker не является auth-token и требует revalidation через Launcher.
- [ ] Описан общий `ndcauth.session` contract для login/logout/change, а не только BIM-first slice.
- [ ] HUB/OPS/ENGINE/BIM проходят browser matrix: login/logout из любого surface обновляет уже открытые приложения без refresh.
- [ ] Session sync события имеют audit/observability без user secrets в логах.
## Plane
- [ ] Перед изменениями сделан backup DB/env/uploads/storage.

12
infra/.env.example
View File

@ -1,14 +1,18 @@
# domains
NODEDC_ENV=local
AUTH_DOMAIN=auth.local.nodedc
AUTH_ADMIN_DOMAIN=auth-admin.local.nodedc
LAUNCHER_DOMAIN=launcher.local.nodedc
TASK_DOMAIN=task.local.nodedc
BIM_DOMAIN=bim.local.nodedc
NODEDC_BIM_VIEWER_PUBLIC_URL=http://localhost:8080
# proxy
PLATFORM_HTTP_PORT=80
PLATFORM_PROXY_IMAGE=nodedc/plane-proxy:ru
LOCAL_LAUNCHER_UPSTREAM=host.docker.internal:5173
LOCAL_TASK_MANAGER_UPSTREAM=host.docker.internal:8090
LOCAL_BIM_VIEWER_UPSTREAM=host.docker.internal:8080
# authentik image
AUTHENTIK_IMAGE=ghcr.io/goauthentik/server
@ -62,11 +66,13 @@ NODEDC_AI_WORKSPACE_ASSISTANT_URL=http://ai-workspace-assistant:18082
AI_WORKSPACE_OPS_ENTITLEMENT_URL=http://host.docker.internal:4100/api/internal/v1/ai-workspace/entitlements
AI_WORKSPACE_OPS_ENTITLEMENT_TOKEN=replace-with-ops-agent-gateway-internal-token
AI_WORKSPACE_OPS_ENTITLEMENT_REQUIRED=false
AI_WORKSPACE_ASSISTANT_ACTION_RELAY_ENABLED=true
AI_WORKSPACE_ASSISTANT_ACTION_RELAY_ID=local-dev
# AI Workspace Hub for downloaded Codex workers.
# Default local development uses the deployed relay and is a hybrid-prod-bridge topology:
# local UI/services can be tested, but live Codex worker write-path e2e is not proven.
# For true local/tunnel e2e, change both Hub URLs and Ops Gateway public URL deliberately.
# Default local development may use the deployed AI Hub only as a relay for remote Codex workers.
# Launcher/Engine/Ops/Auth downstream URLs must remain local.
# For Tailscale/ngrok-style relay URLs, set NODEDC_ENV=tunnel-local-e2e deliberately.
AI_WORKSPACE_HUB_TOKEN=change-me-generate-with-infra-scripts-init-dev-env
AI_WORKSPACE_HUB_HOST_BIND=127.0.0.1:18081
AI_WORKSPACE_HUB_PUBLIC_URL=wss://ai-hub.nodedc.ru/api/ai-workspace/hub

3
infra/.env.staging.example
View File

@ -2,6 +2,8 @@
AUTH_DOMAIN=auth.staging.nodedc.example
LAUNCHER_DOMAIN=launcher.staging.nodedc.example
TASK_DOMAIN=task.staging.nodedc.example
BIM_DOMAIN=bim.staging.nodedc.example
NODEDC_BIM_VIEWER_PUBLIC_URL=https://bim.staging.nodedc.example
# edge proxy
ACME_EMAIL=admin@nodedc.example
@ -10,6 +12,7 @@ PLATFORM_HTTPS_PORT=443
PLATFORM_PROXY_IMAGE=caddy:2-alpine
STAGING_LAUNCHER_UPSTREAM=launcher:5173
STAGING_TASK_MANAGER_UPSTREAM=task-manager-proxy:80
STAGING_BIM_VIEWER_UPSTREAM=host.docker.internal:18100
# authentik image
AUTHENTIK_IMAGE=ghcr.io/goauthentik/server

9
infra/README.md
View File

@ -32,6 +32,15 @@ infra/
## Local start
0. Check the local testing contract:
```bash
cd /Users/dcconstructions/Downloads/mnt/NODEDC/platform
sh infra/scripts/check-local-test-system.sh
```
The local testing canon is documented in `docs/LOCAL_TESTING_SYSTEM.md`. It keeps product apps local and allows the deployed AI Hub only as a remote Codex worker relay.
1. Add local domains to `/etc/hosts`:
```text

1
infra/authentik/bootstrap-dev.py
View File

@ -26,6 +26,7 @@ GROUP_SPECS = [
("nodedc:launcher:user", False),
("nodedc:taskmanager:admin", False),
("nodedc:taskmanager:user", False),
("nodedc:bim:access", False),
]
APP_SPECS = [

46
infra/deploy-runner/README.md Normal file
View File

@ -0,0 +1,46 @@
# NODE.DC deploy runner
This directory stores the versioned source for the Synology canonical deploy runner.
Live runner:
```text
/usr/local/sbin/nodedc-deploy
```
Synology staging candidate:
```text
/volume1/docker/nodedc-deploy/runner-install/nodedc-deploy
```
The runner accepts data-only app-overlay artifacts from:
```text
/volume1/docker/nodedc-deploy/inbox
```
Supported components in this source:
- `engine`
- `launcher`
- `platform`
- `tasker`
- `ops-agents`
- `bim-viewer`
Install or update the root-owned live runner on Synology:
```bash
sudo install -o root -g root -m 0755 \
/volume1/docker/nodedc-deploy/runner-install/nodedc-deploy \
/usr/local/sbin/nodedc-deploy
sudo /usr/local/sbin/nodedc-deploy verify-install
```
Normal service deploys must still use explicit artifacts:
```bash
sudo /usr/local/sbin/nodedc-deploy plan /volume1/docker/nodedc-deploy/inbox/<artifact>.tgz
sudo /usr/local/sbin/nodedc-deploy apply /volume1/docker/nodedc-deploy/inbox/<artifact>.tgz
```

1261
infra/deploy-runner/nodedc-deploy Executable file
View File

File diff suppressed because it is too large Load Diff

47
infra/docker-compose.dev.yml
View File

@ -4,9 +4,6 @@ services:
reverse-proxy:
image: ${PLATFORM_PROXY_IMAGE:-nodedc/plane-proxy:ru}
restart: unless-stopped
env_file:
- path: .env
required: false
ports:
- "${PLATFORM_HTTP_PORT:-80}:80"
volumes:
@ -28,9 +25,6 @@ services:
postgresql-authentik:
image: docker.io/library/postgres:16-alpine
restart: unless-stopped
env_file:
- path: .env
required: false
environment:
POSTGRES_DB: ${PG_DB:-authentik}
POSTGRES_PASSWORD: ${PG_PASS:?database password required}
@ -48,9 +42,6 @@ services:
image: ${AUTHENTIK_IMAGE:-ghcr.io/goauthentik/server}:${AUTHENTIK_TAG:-2026.2.2}
command: server
restart: unless-stopped
env_file:
- path: .env
required: false
environment:
AUTHENTIK_POSTGRESQL__HOST: postgresql-authentik
AUTHENTIK_POSTGRESQL__NAME: ${PG_DB:-authentik}
@ -58,6 +49,10 @@ services:
AUTHENTIK_POSTGRESQL__USER: ${PG_USER:-authentik}
AUTHENTIK_SECRET_KEY: ${AUTHENTIK_SECRET_KEY:?secret key required}
AUTHENTIK_LISTEN__TRUSTED_PROXY_CIDRS: ${AUTHENTIK_LISTEN__TRUSTED_PROXY_CIDRS:-127.0.0.0/8,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,::1/128}
AUTHENTIK_ERROR_REPORTING__ENABLED: ${AUTHENTIK_ERROR_REPORTING__ENABLED:-false}
AUTHENTIK_BOOTSTRAP_EMAIL: ${AUTHENTIK_BOOTSTRAP_EMAIL:-}
AUTHENTIK_BOOTSTRAP_PASSWORD: ${AUTHENTIK_BOOTSTRAP_PASSWORD:-}
AUTHENTIK_BOOTSTRAP_TOKEN: ${AUTHENTIK_BOOTSTRAP_TOKEN:-}
depends_on:
postgresql-authentik:
condition: service_healthy
@ -74,15 +69,13 @@ services:
command: worker
restart: unless-stopped
user: root
env_file:
- path: .env
required: false
environment:
AUTHENTIK_POSTGRESQL__HOST: postgresql-authentik
AUTHENTIK_POSTGRESQL__NAME: ${PG_DB:-authentik}
AUTHENTIK_POSTGRESQL__PASSWORD: ${PG_PASS:?database password required}
AUTHENTIK_POSTGRESQL__USER: ${PG_USER:-authentik}
AUTHENTIK_SECRET_KEY: ${AUTHENTIK_SECRET_KEY:?secret key required}
AUTHENTIK_ERROR_REPORTING__ENABLED: ${AUTHENTIK_ERROR_REPORTING__ENABLED:-false}
depends_on:
postgresql-authentik:
condition: service_healthy
@ -96,9 +89,6 @@ services:
notification-postgres:
image: docker.io/library/postgres:16-alpine
restart: unless-stopped
env_file:
- path: .env
required: false
environment:
POSTGRES_DB: ${NOTIFICATION_PG_DB:-nodedc_notifications}
POSTGRES_PASSWORD: ${NOTIFICATION_PG_PASS:-nodedc_notifications}
@ -117,9 +107,6 @@ services:
build:
context: ../services/notification-core
restart: unless-stopped
env_file:
- path: .env
required: false
environment:
NODE_ENV: production
PORT: 5185
@ -133,9 +120,6 @@ services:
ai-workspace-postgres:
image: docker.io/library/postgres:16-alpine
restart: unless-stopped
env_file:
- path: .env
required: false
environment:
POSTGRES_DB: ${AI_WORKSPACE_PG_DB:-nodedc_ai_workspace}
POSTGRES_PASSWORD: ${AI_WORKSPACE_PG_PASS:-nodedc_ai_workspace}
@ -152,11 +136,9 @@ services:
ai-workspace-assistant:
image: nodedc/ai-workspace-assistant:local
build:
context: ../services/ai-workspace-assistant
context: ../services
dockerfile: ai-workspace-assistant/Dockerfile.dev
restart: unless-stopped
env_file:
- path: .env
required: false
environment:
NODE_ENV: production
PORT: 18082
@ -166,6 +148,16 @@ services:
AI_WORKSPACE_HUB_INTERNAL_URL: ${AI_WORKSPACE_HUB_INTERNAL_URL:-https://ai-hub.nodedc.ru}
AI_WORKSPACE_HUB_TOKEN: ${AI_WORKSPACE_HUB_TOKEN:-}
AI_WORKSPACE_HUB_FALLBACK_URLS: ${AI_WORKSPACE_HUB_FALLBACK_URLS:-}
AI_WORKSPACE_ASSISTANT_ACTION_RELAY_ENABLED: ${AI_WORKSPACE_ASSISTANT_ACTION_RELAY_ENABLED:-true}
AI_WORKSPACE_ASSISTANT_ACTION_RELAY_ID: ${AI_WORKSPACE_ASSISTANT_ACTION_RELAY_ID:-local-dev}
AI_WORKSPACE_OPS_ENTITLEMENT_URL: ${AI_WORKSPACE_OPS_ENTITLEMENT_URL:-}
AI_WORKSPACE_OPS_ENTITLEMENT_TOKEN: ${AI_WORKSPACE_OPS_ENTITLEMENT_TOKEN:-}
AI_WORKSPACE_OPS_ENTITLEMENT_REQUIRED: ${AI_WORKSPACE_OPS_ENTITLEMENT_REQUIRED:-false}
AI_WORKSPACE_OPS_GATEWAY_BASE_URL: ${AI_WORKSPACE_OPS_GATEWAY_BASE_URL:-}
AI_WORKSPACE_OPS_DEFAULT_WORKSPACE_SLUG: ${AI_WORKSPACE_OPS_DEFAULT_WORKSPACE_SLUG:-}
AI_WORKSPACE_OPS_DEFAULT_PROJECT_ID: ${AI_WORKSPACE_OPS_DEFAULT_PROJECT_ID:-}
NODEDC_INTERNAL_ACCESS_TOKEN: ${NODEDC_INTERNAL_ACCESS_TOKEN:-}
NDC_LAUNCHER_INTERNAL_URL: ${NDC_LAUNCHER_INTERNAL_URL:-http://host.docker.internal:5173}
expose:
- "18082"
ports:
@ -179,14 +171,13 @@ services:
build:
context: ../services/ai-workspace-hub
restart: unless-stopped
env_file:
- path: .env
required: false
environment:
NODE_ENV: production
PORT: 18081
AI_WORKSPACE_HUB_TOKEN: ${AI_WORKSPACE_HUB_TOKEN:-dev-ai-workspace-hub-token}
AI_WORKSPACE_HUB_WS_PATH: /api/ai-workspace/hub
NODEDC_INTERNAL_ACCESS_TOKEN: ${NODEDC_INTERNAL_ACCESS_TOKEN:-}
NODEDC_AI_WORKSPACE_ASSISTANT_URL: http://ai-workspace-assistant:18082
expose:
- "18081"
ports:

8
infra/reverse-proxy/Caddyfile
View File

@ -45,3 +45,11 @@ http://{$TASK_DOMAIN:task.local.nodedc} {
header_up X-Forwarded-For {remote_host}
}
}
http://{$BIM_DOMAIN:bim.local.nodedc} {
reverse_proxy {$LOCAL_BIM_VIEWER_UPSTREAM:host.docker.internal:8080} {
header_up Host {host}
header_up X-Forwarded-Proto {scheme}
header_up X-Forwarded-For {remote_host}
}
}

16
infra/reverse-proxy/Caddyfile.staging
View File

@ -14,6 +14,10 @@ http://{$TASK_DOMAIN} {
redir https://{host}{uri} permanent
}
http://{$BIM_DOMAIN} {
redir https://{host}{uri} permanent
}
{$AUTH_DOMAIN} {
header {
Strict-Transport-Security "max-age=31536000; includeSubDomains"
@ -55,3 +59,15 @@ http://{$TASK_DOMAIN} {
header_up X-Forwarded-For {remote_host}
}
}
{$BIM_DOMAIN} {
header {
Strict-Transport-Security "max-age=31536000; includeSubDomains"
}
reverse_proxy {$STAGING_BIM_VIEWER_UPSTREAM} {
header_up Host {host}
header_up X-Forwarded-Proto {scheme}
header_up X-Forwarded-For {remote_host}
}
}

53
infra/scripts/check-ai-workspace-config-contract.sh
View File

@ -55,6 +55,21 @@ require_contains() {
fi
}
require_not_contains() {
file="$1"
needle="$2"
label="$3"
if [ ! -f "$file" ]; then
fail "$label (missing file: $file)"
return 0
fi
if grep -Fq "$needle" "$file"; then
fail "$label (forbidden: $needle)"
else
pass "$label"
fi
}
read_env() {
file="$1"
key="$2"
@ -88,9 +103,12 @@ require_env_value() {
section "Required files"
require_file "$PLATFORM_ROOT/infra/.env.example" "Platform local env example exists"
require_file "$PLATFORM_ROOT/infra/scripts/check-local-environment-safety.mjs" "Local environment safety checker exists"
require_file "$PLATFORM_ROOT/infra/synology/.env.synology.example" "Platform Synology env example exists"
require_file "$PLATFORM_ROOT/infra/docker-compose.dev.yml" "Platform local compose exists"
require_file "$PLATFORM_ROOT/infra/synology/docker-compose.platform-http.yml" "Platform Synology compose exists"
require_file "$PLATFORM_ROOT/infra/synology/sync-ai-hub-relay.sh" "Synology AI Hub relay sync script exists"
require_file "$PLATFORM_ROOT/infra/synology/apply-ai-hub-relay.sh" "Synology AI Hub relay apply script exists"
require_file "$OPS_GATEWAY_REPO/.env.example" "Ops Gateway local env example exists"
require_file "$OPS_GATEWAY_REPO/.env.synology.example" "Ops Gateway Synology env example exists"
require_file "$OPS_GATEWAY_REPO/docker-compose.local.yml" "Ops Gateway local compose exists"
@ -98,11 +116,28 @@ require_file "$OPS_GATEWAY_REPO/docker-compose.synology.yml" "Ops Gateway Synolo
require_file "$ENGINE_REPO/docker-compose.yml" "Engine compose exists"
section "Platform local contract"
require_env_value "$PLATFORM_ROOT/infra/.env.example" "NODEDC_ENV" "local" "Local Platform example declares NODEDC_ENV"
require_env_value "$PLATFORM_ROOT/infra/.env.example" "AI_WORKSPACE_OPS_ENTITLEMENT_URL" "http://host.docker.internal:4100/api/internal/v1/ai-workspace/entitlements" "Local Platform example points Ops entitlement to local Gateway"
require_env_value "$PLATFORM_ROOT/infra/.env.example" "AI_WORKSPACE_HUB_PUBLIC_URL" "wss://ai-hub.nodedc.ru/api/ai-workspace/hub" "Local Platform example keeps deployed Hub as hybrid worker relay by default"
require_env_value "$PLATFORM_ROOT/infra/.env.example" "AI_WORKSPACE_HUB_INTERNAL_URL" "https://ai-hub.nodedc.ru" "Local Platform example has explicit Hub internal URL"
require_env_value "$PLATFORM_ROOT/infra/.env.example" "AI_WORKSPACE_ASSISTANT_ACTION_RELAY_ENABLED" "true" "Local Platform example enables Assistant action relay"
require_env_value "$PLATFORM_ROOT/infra/.env.example" "AI_WORKSPACE_ASSISTANT_ACTION_RELAY_ID" "local-dev" "Local Platform example declares stable local Assistant action relay id"
require_env_value "$PLATFORM_ROOT/infra/.env.example" "AI_WORKSPACE_HUB_PUBLIC_URL" "wss://ai-hub.nodedc.ru/api/ai-workspace/hub" "Local Platform example keeps deployed AI Hub only as worker relay"
require_env_value "$PLATFORM_ROOT/infra/.env.example" "AI_WORKSPACE_HUB_INTERNAL_URL" "https://ai-hub.nodedc.ru" "Local Platform example has explicit relay control URL"
require_contains "$PLATFORM_ROOT/infra/scripts/init-dev-env.sh" "NODEDC_ENV=local" "Local env generator emits NODEDC_ENV"
require_contains "$PLATFORM_ROOT/infra/scripts/init-dev-env.sh" "AI_WORKSPACE_OPS_ENTITLEMENT_URL=http://host.docker.internal:4100/api/internal/v1/ai-workspace/entitlements" "Local env generator emits local Ops entitlement URL"
require_contains "$PLATFORM_ROOT/infra/scripts/init-dev-env.sh" "AI_WORKSPACE_HUB_INTERNAL_URL=https://ai-hub.nodedc.ru" "Local env generator emits explicit Hub internal URL"
require_contains "$PLATFORM_ROOT/infra/scripts/init-dev-env.sh" "AI_WORKSPACE_ASSISTANT_ACTION_RELAY_ENABLED=true" "Local env generator enables Assistant action relay"
require_contains "$PLATFORM_ROOT/infra/scripts/init-dev-env.sh" "AI_WORKSPACE_ASSISTANT_ACTION_RELAY_ID=local-dev" "Local env generator emits stable Assistant action relay id"
require_contains "$PLATFORM_ROOT/infra/scripts/init-dev-env.sh" "AI_WORKSPACE_HUB_INTERNAL_URL=https://ai-hub.nodedc.ru" "Local env generator emits explicit relay control URL"
require_not_contains "$PLATFORM_ROOT/infra/docker-compose.dev.yml" "env_file:" "Local compose does not inject full .env into containers"
require_contains "$PLATFORM_ROOT/infra/docker-compose.dev.yml" 'NODEDC_INTERNAL_ACCESS_TOKEN: ${NODEDC_INTERNAL_ACCESS_TOKEN:-}' "Local compose explicitly passes internal token only to AI services"
require_contains "$PLATFORM_ROOT/infra/docker-compose.dev.yml" 'AI_WORKSPACE_ASSISTANT_ACTION_RELAY_ENABLED: ${AI_WORKSPACE_ASSISTANT_ACTION_RELAY_ENABLED:-true}' "Local compose explicitly passes Assistant action relay enabled flag"
require_contains "$PLATFORM_ROOT/infra/docker-compose.dev.yml" 'AI_WORKSPACE_ASSISTANT_ACTION_RELAY_ID: ${AI_WORKSPACE_ASSISTANT_ACTION_RELAY_ID:-local-dev}' "Local compose explicitly passes Assistant action relay id"
section "Local safety guardrail"
if node "$PLATFORM_ROOT/infra/scripts/check-local-environment-safety.mjs"; then
pass "Local environment safety checker passes"
else
fail "Local environment safety checker failed"
fi
section "Platform Synology contract"
require_env_value "$PLATFORM_ROOT/infra/synology/.env.synology.example" "NODEDC_AI_WORKSPACE_ASSISTANT_URL" "http://ai-workspace-assistant:18082" "Synology Platform exposes Assistant to app services on compose network"
@ -110,6 +145,11 @@ require_env_value "$PLATFORM_ROOT/infra/synology/.env.synology.example" "AI_WORK
require_env_value "$PLATFORM_ROOT/infra/synology/.env.synology.example" "AI_WORKSPACE_HUB_PUBLIC_URL" "wss://ai-hub.nodedc.ru/api/ai-workspace/hub" "Synology Platform worker-facing Hub URL is public relay"
require_env_value "$PLATFORM_ROOT/infra/synology/.env.synology.example" "AI_WORKSPACE_HUB_INTERNAL_URL" "https://ai-hub.nodedc.ru" "Synology Platform backend Hub URL is explicit"
require_contains "$PLATFORM_ROOT/infra/synology/verify-current-runtime.sh" 'AI_WORKSPACE_OPS_ENTITLEMENT_URL" = "http://172.22.0.222:18190/api/internal/v1/ai-workspace/entitlements"' "Synology verify checks Ops entitlement URL"
require_contains "$PLATFORM_ROOT/infra/synology/sync-ai-hub-relay.sh" 'services/ai-workspace-hub/' "Hub-only sync copies AI Workspace Hub source"
require_contains "$PLATFORM_ROOT/infra/synology/apply-ai-hub-relay.sh" 'up -d --no-deps --force-recreate ai-workspace-hub' "Hub-only apply recreates only AI Workspace Hub without dependencies"
require_contains "$PLATFORM_ROOT/infra/synology/apply-ai-hub-relay.sh" '/api/ai-workspace/hub/v1/assistant-relays/' "Hub-only apply verifies Assistant relay endpoint"
require_not_contains "$PLATFORM_ROOT/infra/synology/apply-ai-hub-relay.sh" ' launcher' "Hub-only apply does not target Launcher"
require_not_contains "$PLATFORM_ROOT/infra/synology/apply-ai-hub-relay.sh" 'authentik' "Hub-only apply does not target Authentik"
section "Ops Gateway contract"
require_env_value "$OPS_GATEWAY_REPO/.env.example" "NODEDC_AGENT_GATEWAY_PUBLIC_URL" "https://ops-agents.nodedc.ru" "Ops Gateway local example keeps worker-facing MCP URL explicit"
@ -134,6 +174,13 @@ if [ -f "$PLATFORM_ENV" ]; then
else
pass "Current Platform env has AI_WORKSPACE_OPS_ENTITLEMENT_URL"
fi
local_action_relay_enabled=$(read_env "$PLATFORM_ENV" AI_WORKSPACE_ASSISTANT_ACTION_RELAY_ENABLED || true)
local_action_relay_id=$(read_env "$PLATFORM_ENV" AI_WORKSPACE_ASSISTANT_ACTION_RELAY_ID || true)
if [ "$local_action_relay_enabled" = "true" ] && [ -n "$local_action_relay_id" ]; then
pass "Current Platform env has Assistant action relay enabled"
else
warn "Current Platform env has no enabled Assistant action relay; remote worker action calls may route incorrectly."
fi
else
warn "Current Platform env not found: $PLATFORM_ENV"
fi

5
infra/scripts/check-ai-workspace-release-gates.sh
View File

@ -65,9 +65,12 @@ run_in "$PLATFORM_ROOT" \
"infra/scripts/check-ai-workspace-topology.sh"
section "Platform static and contract gates"
run_in "$PLATFORM_ROOT" \
"Local test system contract gate" \
"sh infra/scripts/check-local-test-system.sh"
run_in "$PLATFORM_ROOT" \
"Platform shell syntax" \
"sh -n infra/scripts/init-dev-env.sh infra/scripts/check-ai-workspace-topology.sh infra/scripts/check-ai-workspace-config-contract.sh infra/scripts/check-ai-workspace-release-gates.sh infra/synology/check-ai-workspace-apply-plan.sh infra/synology/prepare-ai-workspace-env.sh infra/synology/deploy-current.sh infra/synology/verify-current-runtime.sh infra/synology/apply-current-runtime.sh infra/synology/backup-current.sh"
"sh -n infra/scripts/init-dev-env.sh infra/scripts/check-local-test-system.sh infra/scripts/check-ai-workspace-topology.sh infra/scripts/check-ai-workspace-config-contract.sh infra/scripts/check-ai-workspace-release-gates.sh infra/synology/check-ai-workspace-apply-plan.sh infra/synology/prepare-ai-workspace-env.sh infra/synology/deploy-current.sh infra/synology/verify-current-runtime.sh infra/synology/apply-current-runtime.sh infra/synology/backup-current.sh"
run_in "$PLATFORM_ROOT" \
"AI Workspace config contract" \
"infra/scripts/check-ai-workspace-config-contract.sh"

68
infra/scripts/check-ai-workspace-topology.sh
View File

@ -90,40 +90,63 @@ bool_and() {
}
assistant_code=$(http_status "$ASSISTANT_URL/healthz")
hub_body=$(http_body "$HUB_URL/healthz")
hub_code=000
if [ -n "$hub_body" ]; then
hub_code=$(http_status "$HUB_URL/healthz")
fi
gateway_code=$(http_status "$GATEWAY_URL/readyz")
task_code=$(http_status "$TASK_URL")
engine_code=$(http_status "$ENGINE_URL")
assistant_ok=$(ok_status "$assistant_code")
hub_ok=$(ok_status "$hub_code")
gateway_ok=$(ok_status "$gateway_code")
task_ok=$(ok_status "$task_code")
engine_ok=$(ok_status "$engine_code")
agents_online=$(printf "%s" "$hub_body" | json_number agentsOnline)
case "$agents_online" in
""|*[!0-9]*) agents_online=0 ;;
profile=$(read_env "$PLATFORM_ENV" NODEDC_ENV || true)
case "$profile" in
"") profile=local ;;
esac
hub_public=$(read_env "$PLATFORM_ENV" AI_WORKSPACE_HUB_PUBLIC_URL || true)
hub_internal=$(read_env "$PLATFORM_ENV" AI_WORKSPACE_HUB_INTERNAL_URL || true)
ops_entitlement=$(read_env "$PLATFORM_ENV" AI_WORKSPACE_OPS_ENTITLEMENT_URL || true)
action_relay_enabled=$(read_env "$PLATFORM_ENV" AI_WORKSPACE_ASSISTANT_ACTION_RELAY_ENABLED || true)
action_relay_id=$(read_env "$PLATFORM_ENV" AI_WORKSPACE_ASSISTANT_ACTION_RELAY_ID || true)
case "$action_relay_enabled" in
1|true|TRUE|yes|YES|on|ON) action_relay_enabled=true ;;
*) action_relay_enabled=false ;;
esac
hub_public_kind=$(url_kind "$hub_public")
hub_internal_kind=$(url_kind "$hub_internal")
ops_entitlement_kind=$(url_kind "$ops_entitlement")
local_services_ok=$(bool_and "$(bool_and "$assistant_ok" "$hub_ok")" "$(bool_and "$gateway_ok" "$task_ok")")
local_hub_body=$(http_body "$HUB_URL/healthz")
local_hub_code=000
if [ -n "$local_hub_body" ]; then
local_hub_code=$(http_status "$HUB_URL/healthz")
fi
local_hub_ok=$(ok_status "$local_hub_code")
relay_health_code=000
relay_health_ok=false
if [ -n "$hub_internal" ]; then
relay_health_code=$(http_status "$(printf "%s" "$hub_internal" | sed 's#/*$##')/healthz")
relay_health_ok=$(ok_status "$relay_health_code")
fi
agents_online=$(printf "%s" "$local_hub_body" | json_number agentsOnline)
case "$agents_online" in
""|*[!0-9]*) agents_online=0 ;;
esac
local_services_ok=$(bool_and "$assistant_ok" "$(bool_and "$gateway_ok" "$task_ok")")
worker_on_local_hub=false
if [ "$agents_online" -gt 0 ]; then
worker_on_local_hub=true
fi
action_relay_configured=false
if [ "$action_relay_enabled" = true ] && [ -n "$action_relay_id" ]; then
action_relay_configured=true
fi
hub_runtime_kind=custom
case "$hub_public_kind:$hub_internal_kind" in
local:local|local:missing|missing:local) hub_runtime_kind=local ;;
@ -135,6 +158,10 @@ esac
classification=contract-only
if [ "$local_services_ok" = true ]; then
if [ "$engine_ok" = true ] \
&& [ "$action_relay_configured" = true ] \
&& [ "$hub_runtime_kind" = prod-public ]; then
classification=local-remote-worker-relay
elif [ "$engine_ok" = true ] \
&& [ "$worker_on_local_hub" = true ] \
&& [ "$ops_entitlement_kind" = local ] \
&& [ "$hub_runtime_kind" = local ]; then
@ -156,9 +183,11 @@ fi
cat <<EOF
classification=$classification
profile=$profile
platform_env=$PLATFORM_ENV
assistant_health=$assistant_ok status=$assistant_code url=$ASSISTANT_URL/healthz
hub_health=$hub_ok status=$hub_code url=$HUB_URL/healthz agents_online=$agents_online
local_hub_health=$local_hub_ok status=$local_hub_code url=$HUB_URL/healthz agents_online=$agents_online
relay_health=$relay_health_ok status=$relay_health_code url=${hub_internal%/}/healthz
gateway_health=$gateway_ok status=$gateway_code url=$GATEWAY_URL/readyz
task_health=$task_ok status=$task_code url=$TASK_URL
engine_health=$engine_ok status=$engine_code url=$ENGINE_URL
@ -166,14 +195,20 @@ hub_public_kind=$hub_public_kind
hub_internal_kind=$hub_internal_kind
hub_runtime_kind=$hub_runtime_kind
ops_entitlement_kind=$ops_entitlement_kind
assistant_action_relay_enabled=${action_relay_enabled:-missing}
assistant_action_relay_id=${action_relay_id:-missing}
assistant_action_relay_configured=$action_relay_configured
EOF
case "$classification" in
true-local-e2e|tunnel-local-e2e)
echo "meaning=local write-path e2e can be interpreted if the worker can reach returned MCP URLs"
;;
local-remote-worker-relay)
echo "meaning=local apps are the downstream target; deployed AI Hub is used only as remote worker relay and assistant actions route back to local Assistant"
;;
hybrid-prod-bridge)
echo "meaning=do not treat UI dialog as local write-path proof; worker/HUB/MCP topology is mixed"
echo "meaning=do not treat UI dialog as local write-path proof; topology is mixed or assistant action relay is not configured"
;;
local-ops-vertical)
echo "meaning=Gateway and Tasker local vertical checks are valid, but no live Codex worker e2e is proven"
@ -192,3 +227,10 @@ if [ "${REQUIRE_TRUE_E2E:-0}" = "1" ]; then
*) exit 2 ;;
esac
fi
if [ "${REQUIRE_LOCAL_REMOTE_WORKER_RELAY:-0}" = "1" ]; then
case "$classification" in
local-remote-worker-relay) exit 0 ;;
*) exit 2 ;;
esac
fi

147
infra/scripts/check-local-environment-safety.mjs Normal file
View File

@ -0,0 +1,147 @@
#!/usr/bin/env node
import fs from "node:fs";
import path from "node:path";
import { fileURLToPath } from "node:url";
const scriptDir = path.dirname(fileURLToPath(import.meta.url));
const platformRoot = path.resolve(scriptDir, "../..");
const monorepoRoot = path.resolve(platformRoot, "..");
const prodHosts = new Set([
"ai-hub.nodedc.ru",
"hub.nodedc.ru",
"engine.nodedc.ru",
"ops.nodedc.ru",
"id.nodedc.ru",
"ops-agents.nodedc.ru",
]);
const relayKeysAllowedInLocal = new Set([
"AI_WORKSPACE_HUB_PUBLIC_URL",
"AI_WORKSPACE_HUB_INTERNAL_URL",
"NDC_AI_WORKSPACE_HUB_URL",
"NDC_AI_WORKSPACE_HUB_HTTP_URL",
"AI_WORKSPACE_ASSISTANT_ACTION_GATEWAY_URL",
"NDC_AI_WORKSPACE_ASSISTANT_ACTION_GATEWAY_URL",
]);
const localOnlyFiles = [
{
file: path.join(platformRoot, "infra", ".env.example"),
required: true,
requiredKeys: ["NODEDC_ENV", "NODEDC_INTERNAL_ACCESS_TOKEN", "AI_WORKSPACE_HUB_PUBLIC_URL", "AI_WORKSPACE_HUB_INTERNAL_URL", "AI_WORKSPACE_ASSISTANT_ACTION_RELAY_ENABLED", "AI_WORKSPACE_ASSISTANT_ACTION_RELAY_ID"],
},
{
file: path.join(platformRoot, "infra", ".env"),
required: false,
requiredKeys: ["NODEDC_ENV", "NODEDC_INTERNAL_ACCESS_TOKEN", "AI_WORKSPACE_HUB_PUBLIC_URL", "AI_WORKSPACE_HUB_INTERNAL_URL", "AI_WORKSPACE_ASSISTANT_ACTION_RELAY_ENABLED", "AI_WORKSPACE_ASSISTANT_ACTION_RELAY_ID"],
},
{
file: path.join(monorepoRoot, "NODEDC_ENGINE_INFRA", "nodedc-source", "server", ".env.local"),
required: false,
requiredKeys: [
"NODEDC_ENV",
"NODEDC_LAUNCHER_INTERNAL_URL",
"NODEDC_LAUNCHER_ORIGIN",
"AUTHENTIK_PUBLIC_BASE_URL",
"NODEDC_AI_WORKSPACE_ASSISTANT_URL",
],
},
];
const failures = [];
const warnings = [];
const passes = [];
function parseEnvFile(file) {
const env = new Map();
const raw = fs.readFileSync(file, "utf8");
raw.split(/\r?\n/).forEach((line, index) => {
const trimmed = line.trim();
if (!trimmed || trimmed.startsWith("#")) return;
const match = /^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/.exec(trimmed);
if (!match) return;
let value = match[2].trim();
if (
(value.startsWith('"') && value.endsWith('"')) ||
(value.startsWith("'") && value.endsWith("'"))
) {
value = value.slice(1, -1);
}
env.set(match[1], { value, line: index + 1 });
});
return env;
}
function urlHost(value) {
try {
return new URL(value).hostname.toLowerCase();
} catch {
return "";
}
}
function isTunnelOrPrivateRelay(value) {
const host = urlHost(value);
return (
host.endsWith(".ts.net") ||
host.startsWith("100.") ||
host.startsWith("172.22.") ||
host.startsWith("192.168.") ||
host.startsWith("10.")
);
}
function checkLocalEnvFile({ file, required, requiredKeys }) {
if (!fs.existsSync(file)) {
if (required) failures.push(`${file}: missing required local env file`);
else warnings.push(`${file}: not present, skipped`);
return;
}
const env = parseEnvFile(file);
const profile = env.get("NODEDC_ENV")?.value || "local";
if (profile !== "local" && profile !== "tunnel-local-e2e") {
failures.push(`${file}: expected NODEDC_ENV=local or tunnel-local-e2e, got ${profile}`);
}
requiredKeys.forEach((key) => {
if (!env.get(key)?.value) failures.push(`${file}: missing required ${key}`);
});
for (const [key, entry] of env.entries()) {
const value = entry.value;
if (!/^https?:\/\//i.test(value) && !/^wss?:\/\//i.test(value)) continue;
const host = urlHost(value);
if (!host) continue;
if (prodHosts.has(host) && !relayKeysAllowedInLocal.has(key)) {
failures.push(`${file}:${entry.line}: ${key} points local profile at prod host ${host}`);
}
if (isTunnelOrPrivateRelay(value) && profile !== "tunnel-local-e2e") {
failures.push(`${file}:${entry.line}: ${key} uses tunnel/private host ${host}; set NODEDC_ENV=tunnel-local-e2e explicitly or use a normal local/public-relay URL`);
}
}
const hubInternal = env.get("AI_WORKSPACE_HUB_INTERNAL_URL")?.value || "";
if (hubInternal && profile === "local") {
const host = urlHost(hubInternal);
const allowed = host === "ai-hub.nodedc.ru" || host === "127.0.0.1" || host === "localhost";
if (!allowed) {
failures.push(`${file}: AI_WORKSPACE_HUB_INTERNAL_URL must be loopback or deployed relay in local profile, got ${hubInternal}`);
}
}
passes.push(`${file}: checked`);
}
localOnlyFiles.forEach(checkLocalEnvFile);
passes.forEach((item) => console.log(`PASS ${item}`));
warnings.forEach((item) => console.warn(`WARN ${item}`));
failures.forEach((item) => console.error(`FAIL ${item}`));
console.log(`summary: passed=${passes.length} warnings=${warnings.length} failed=${failures.length}`);
if (failures.length) process.exit(1);

183
infra/scripts/check-local-test-system.sh Executable file
View File

@ -0,0 +1,183 @@
#!/usr/bin/env sh
set -eu
SCRIPT_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
PLATFORM_ROOT=$(CDPATH= cd -- "$SCRIPT_DIR/../.." && pwd)
INFRA_DIR="$PLATFORM_ROOT/infra"
ASSISTANT_DIR="$PLATFORM_ROOT/services/ai-workspace-assistant"
HUB_DIR="$PLATFORM_ROOT/services/ai-workspace-hub"
ONTOLOGY_DIR="$PLATFORM_ROOT/services/ontology-core"
COMPOSE_ENV="${COMPOSE_ENV:-$INFRA_DIR/.env}"
if [ ! -f "$COMPOSE_ENV" ]; then
COMPOSE_ENV="$INFRA_DIR/.env.example"
fi
REQUIRE_RUNTIME="${REQUIRE_RUNTIME:-0}"
REQUIRE_REMOTE_WORKER_RELAY="${REQUIRE_REMOTE_WORKER_RELAY:-0}"
passed=0
failed=0
skipped=0
section() {
printf '\n== %s ==\n' "$1"
}
pass() {
passed=$((passed + 1))
printf 'PASS %s\n' "$1"
}
fail() {
failed=$((failed + 1))
printf 'FAIL %s\n' "$1" >&2
}
skip() {
skipped=$((skipped + 1))
printf 'SKIP %s\n' "$1"
}
run_cmd() {
label="$1"
shift
printf '\n$ %s\n' "$label"
set +e
"$@"
status=$?
set -e
if [ "$status" -eq 0 ]; then
pass "$label"
else
fail "$label (exit $status)"
fi
}
run_sh() {
label="$1"
dir="$2"
command="$3"
printf '\n$ %s\n' "$label"
set +e
(cd "$dir" && sh -lc "$command")
status=$?
set -e
if [ "$status" -eq 0 ]; then
pass "$label"
else
fail "$label (exit $status)"
fi
}
run_sh_quiet() {
label="$1"
dir="$2"
command="$3"
output_file=$(mktemp "${TMPDIR:-/tmp}/nodedc-check.XXXXXX")
printf '\n$ %s\n' "$label"
set +e
(cd "$dir" && sh -lc "$command") > "$output_file" 2>&1
status=$?
set -e
if [ "$status" -eq 0 ]; then
pass "$label"
rm -f "$output_file"
else
cat "$output_file"
rm -f "$output_file"
fail "$label (exit $status)"
fi
}
section "Static syntax"
run_cmd "Hub server syntax" node --check "$HUB_DIR/src/server.mjs"
run_cmd "Assistant server syntax" node --check "$ASSISTANT_DIR/src/server.mjs"
run_cmd "Local environment safety checker syntax" node --check "$INFRA_DIR/scripts/check-local-environment-safety.mjs"
run_sh "Shell scripts syntax" "$PLATFORM_ROOT" \
"sh -n infra/scripts/init-dev-env.sh infra/scripts/check-local-test-system.sh infra/scripts/check-ai-workspace-topology.sh infra/scripts/check-ai-workspace-config-contract.sh infra/scripts/check-ai-workspace-release-gates.sh"
if command -v bash >/dev/null 2>&1; then
run_sh "Synology hub-only deploy scripts syntax" "$PLATFORM_ROOT" \
"bash -n infra/synology/sync-ai-hub-relay.sh infra/synology/apply-ai-hub-relay.sh"
else
skip "Synology hub-only deploy scripts syntax (bash not installed)"
fi
section "Environment contracts"
run_cmd "Local environment safety" node "$INFRA_DIR/scripts/check-local-environment-safety.mjs"
run_cmd "AI Workspace config contract" "$INFRA_DIR/scripts/check-ai-workspace-config-contract.sh"
section "Compose boundary"
if command -v docker >/dev/null 2>&1; then
compose_tmp=$(mktemp "${TMPDIR:-/tmp}/nodedc-local-compose.XXXXXX")
if docker compose --env-file "$COMPOSE_ENV" -f "$INFRA_DIR/docker-compose.dev.yml" config > "$compose_tmp"; then
pass "Local compose config renders"
else
fail "Local compose config renders"
fi
rm -f "$compose_tmp"
if grep -Fq "env_file:" "$INFRA_DIR/docker-compose.dev.yml"; then
fail "Local compose must not inject the full .env into services"
else
pass "Local compose uses explicit service environment only"
fi
else
skip "Docker compose config render (docker not installed)"
fi
section "AI Workspace smokes"
run_sh_quiet "Assistant run-profile smoke" "$ASSISTANT_DIR" "npm run smoke:run-profile"
if [ -d "$ONTOLOGY_DIR" ]; then
run_sh_quiet "Ontology assistant caller smoke" "$ONTOLOGY_DIR" "npm run smoke:assistant-caller"
else
skip "Ontology assistant caller smoke (missing $ONTOLOGY_DIR)"
fi
section "Runtime classification"
topology_tmp=$(mktemp "${TMPDIR:-/tmp}/nodedc-topology.XXXXXX")
set +e
(cd "$PLATFORM_ROOT" && infra/scripts/check-ai-workspace-topology.sh) > "$topology_tmp"
topology_status=$?
set -e
cat "$topology_tmp"
classification=$(awk -F= '/^classification=/{print $2; exit}' "$topology_tmp")
rm -f "$topology_tmp"
if [ "$topology_status" -eq 0 ]; then
pass "Runtime topology classified as ${classification:-unknown}"
else
fail "Runtime topology classification failed (exit $topology_status)"
fi
if [ "$REQUIRE_RUNTIME" = "1" ]; then
case "$classification" in
true-local-e2e|tunnel-local-e2e|local-remote-worker-relay)
pass "Runtime requirement satisfied"
;;
*)
fail "Runtime requirement not satisfied (classification=${classification:-unknown})"
;;
esac
fi
if [ "$REQUIRE_REMOTE_WORKER_RELAY" = "1" ]; then
case "$classification" in
local-remote-worker-relay)
pass "Remote worker relay requirement satisfied"
;;
*)
fail "Remote worker relay requirement not satisfied (classification=${classification:-unknown})"
;;
esac
fi
section "Git hygiene"
run_sh "Platform diff hygiene" "$PLATFORM_ROOT" "git diff --check"
section "Summary"
printf 'passed=%s failed=%s skipped=%s\n' "$passed" "$failed" "$skipped"
if [ "$failed" -ne 0 ]; then
exit 1
fi

8
infra/scripts/init-dev-env.sh
View File

@ -16,6 +16,7 @@ rand() {
cat > "$ENV_FILE" <<EOF
# domains
NODEDC_ENV=local
AUTH_DOMAIN=auth.local.nodedc
LAUNCHER_DOMAIN=launcher.local.nodedc
TASK_DOMAIN=task.local.nodedc
@ -61,8 +62,9 @@ COOKIE_DOMAIN=.local.nodedc
COOKIE_SECURE=false
# AI Workspace shared registry and Hub.
# Generated local env uses the deployed relay by default. This is suitable for
# UI/contract smoke, not proof of local live-worker write-path e2e.
# Generated local env may use the deployed AI Hub only as a relay for remote
# Codex workers. Launcher/Engine/Ops/Auth downstream URLs must remain local.
# For Tailscale/ngrok-style relay URLs, set NODEDC_ENV=tunnel-local-e2e deliberately.
AI_WORKSPACE_PG_DB=nodedc_ai_workspace
AI_WORKSPACE_PG_USER=nodedc_ai_workspace
AI_WORKSPACE_PG_PASS=$(rand 36)
@ -70,6 +72,8 @@ AI_WORKSPACE_ASSISTANT_TOKEN=$(openssl rand -hex 48 | tr -d '\n')
AI_WORKSPACE_OPS_ENTITLEMENT_URL=http://host.docker.internal:4100/api/internal/v1/ai-workspace/entitlements
AI_WORKSPACE_OPS_ENTITLEMENT_TOKEN=replace-with-ops-agent-gateway-internal-token
AI_WORKSPACE_OPS_ENTITLEMENT_REQUIRED=false
AI_WORKSPACE_ASSISTANT_ACTION_RELAY_ENABLED=true
AI_WORKSPACE_ASSISTANT_ACTION_RELAY_ID=local-dev
AI_WORKSPACE_HUB_TOKEN=$(openssl rand -hex 48 | tr -d '\n')
AI_WORKSPACE_HUB_HOST_BIND=127.0.0.1:18081
AI_WORKSPACE_HUB_PUBLIC_URL=wss://ai-hub.nodedc.ru/api/ai-workspace/hub

3
infra/synology/.env.synology.example
View File

@ -6,9 +6,11 @@ AUTH_ADMIN_DOMAIN=auth-admin.nas.nodedc
AUTH_ADMIN_LAN_HOST=172.22.0.222
LAUNCHER_DOMAIN=launcher.nas.nodedc
TASK_DOMAIN=task.nas.nodedc
BIM_DOMAIN=bim.nodedc.tech
NODEDC_PUBLIC_HTTP_PORT=18080
PLATFORM_HTTP_PORT=18080
SYNOLOGY_TASK_MANAGER_UPSTREAM=host.docker.internal:18090
SYNOLOGY_BIM_VIEWER_UPSTREAM=host.docker.internal:18100
AUTHENTIK_IMAGE=ghcr.io/goauthentik/server
AUTHENTIK_TAG=2026.2.2
@ -25,6 +27,7 @@ AUTHENTIK_BOOTSTRAP_TOKEN=replace-with-random-synology-secret
LAUNCHER_BASE_URL=https://hub.nodedc.ru
TASK_BASE_URL=https://ops.nodedc.ru
NODEDC_BIM_VIEWER_PUBLIC_URL=https://bim.nodedc.tech
TASK_LOGOUT_URI=https://ops.nodedc.ru/logout
TASK_INTERNAL_LOGOUT_URL=https://ops.nodedc.ru/api/internal/nodedc/logout/
NODEDC_ENGINE_DOCKER_NETWORK=nodedc-demo_default

10
infra/synology/Caddyfile.http
View File

@ -48,6 +48,16 @@ http://{$TASK_DOMAIN} {
}
}
http://{$BIM_DOMAIN:bim.nodedc.tech} {
reverse_proxy {$SYNOLOGY_BIM_VIEWER_UPSTREAM:host.docker.internal:18100} {
header_up Host {http.request.host}
header_up X-Forwarded-Host {http.request.host}
header_up X-Forwarded-Proto https
header_up X-Forwarded-Port 443
header_up X-Forwarded-For {remote_host}
}
}
http://id.nodedc.ru {
@auth_admin path /if/admin /if/admin/*
respond @auth_admin 404

110
infra/synology/README.md
View File

@ -7,7 +7,7 @@
- Не выполнять `docker stop`, `docker restart`, `docker compose down`, `docker system prune` для старых проектов.
- Новый compose project: `nodedc-platform`.
- Новая папка на NAS: `/volume1/docker/nodedc-platform`.
- Внутренний HTTP edge использует `18080`, AI Workspace Hub — `18081`, Tasker upstream — `18090`, Ops Agents Gateway upstream — `18190`.
- Внутренний HTTP edge использует `18080`, AI Workspace Hub — `18081`, Tasker upstream — `18090`, BIM Viewer upstream — `18100`, Ops Agents Gateway upstream — `18190`.
- Старые порты `9000` и `5678` заняты старым `nodedc-demo` и не используются.
## Текущие внешние домены
@ -16,6 +16,7 @@
https://id.nodedc.ru -> Authentik
https://hub.nodedc.ru -> Launcher / Hub
https://ops.nodedc.ru -> Tasker / Operational Core
https://bim.nodedc.tech -> BIM Viewer
https://ops-agents.nodedc.ru -> Ops Agents Gateway / MCP
https://ai-hub.nodedc.ru -> AI Workspace Hub / WebSocket relay
```
@ -26,6 +27,8 @@ https://ai-hub.nodedc.ru -> AI Workspace Hub / WebSocket relay
В `Caddyfile.http` эти домены проксируются через локальный HTTP edge, но upstream получает `X-Forwarded-Proto: https` и `X-Forwarded-Port: 443`.
`bim.nodedc.tech` can either be routed by DSM directly to the BIM host port `172.22.0.222:18100`, or through the platform HTTP edge `172.22.0.222:18080`. When it goes through the platform edge, `BIM_DOMAIN=bim.nodedc.tech` and `SYNOLOGY_BIM_VIEWER_UPSTREAM=host.docker.internal:18100` keep the same target service.
## AI Workspace Hub / Assistant contract
`ai-workspace-hub` remains a thin public WebSocket relay. It is the only AI Workspace service exposed through DSM/Nginx as `https://ai-hub.nodedc.ru`.
@ -83,8 +86,8 @@ http://task.nas.nodedc:18090
- `docker-compose.platform-http.yml` поднимает новый Authentik, Launcher, Notification Core, AI Workspace Hub и Caddy edge.
- `Caddyfile.http` маршрутизирует локальные `auth/auth-admin/launcher/task.nas.nodedc`, IP fallback `172.22.0.222` для Authentik Admin и внешние `id/hub/ops.nodedc.ru`.
- `deploy-current.sh` синхронизирует compose, Caddyfile, Notification Core source, AI Workspace Hub source и опционально Launcher source в NAS mount. Authentik templates синхронизируются только при явном `SYNC_AUTHENTIK_TEMPLATES=1`.
- `backup-current.sh` делает snapshot Launcher runtime/uploads/Auth templates/config и готовит команду `pg_dump` для Authentik Postgres.
- `deploy-current.sh` синхронизирует compose, Caddyfile, Notification Core source, AI Workspace Hub source и опционально Launcher/BIM source в NAS mount. Authentik templates синхронизируются только при явном `SYNC_AUTHENTIK_TEMPLATES=1`.
- `backup-current.sh` делает snapshot Launcher runtime/uploads/Auth templates/config, BIM Viewer `server/data` и готовит команду `pg_dump` для Authentik Postgres.
- Tasker поднимается отдельным compose из `NODEDC_TASKMANAGER/plane-app/docker-compose.yaml` на порту `18090`.
- Ops Agents Gateway поднимается отдельным compose из `NODEDC_TASKMANAGER_CODEXAPI/docker-compose.synology.yml` на `172.22.0.222:18190`; Synology reverse proxy должен вести `ops-agents.nodedc.ru` на этот порт, а не на `18090`.
@ -137,6 +140,7 @@ exit 1
cd /Users/dcconstructions/Downloads/mnt/NODEDC/platform
NAS_ROOT=/Volumes/docker/nodedc-platform \
LAUNCHER_REPO=/Users/dcconstructions/Downloads/mnt/data/nodedc_launcher \
BIM_REPO=/Users/dcconstructions/Downloads/mnt/NODEDC/NODEDC_BIM_VIEWER \
TASKER_REPO=/Users/dcconstructions/Downloads/mnt/data/dc_taskmanager/NODEDC_TASKMANAGER \
TASKER_CHANGED_BASE=533f8c6 \
GATEWAY_REPO=/Users/dcconstructions/Downloads/mnt/data/NODEDC_TASKMANAGER_CODEXAPI \
@ -154,6 +158,7 @@ GATEWAY_REPO=/Users/dcconstructions/Downloads/mnt/data/NODEDC_TASKMANAGER_CODEXA
- AI Workspace Hub source в `/volume1/docker/nodedc-platform/platform/ai-workspace-hub`.
- Authentik templates только при `SYNC_AUTHENTIK_TEMPLATES=1`; по умолчанию они не трогаются, чтобы лёгкий Hub deploy не уносил экспериментальную тему/брендинг в prod.
- Launcher source в `/volume1/docker/nodedc-platform/launcher/source`.
- BIM Viewer source в `/volume1/docker/nodedc-platform/bim-viewer/source`; `server/data` не синхронизируется и остаётся live runtime-хранилищем моделей, shares, comments и refs.
- Tasker `plane-app/docker-compose.yaml` и, если задан `TASKER_CHANGED_BASE`, только изменённые source-файлы из диапазона `TASKER_CHANGED_BASE..HEAD`.
- Ops Agents Gateway source в `/volume1/docker/nodedc-platform/ops-agents`.
@ -166,11 +171,50 @@ TASKER_SYNC_SOURCE=1 ./infra/synology/deploy-current.sh
Секретные runtime env-файлы не перетираются:
- `/volume1/docker/nodedc-platform/platform/.env.synology`
- `/volume1/docker/nodedc-platform/bim-viewer/source/.env`
- `/volume1/docker/nodedc-platform/tasker/plane-app/.env.synology`
- `/volume1/docker/nodedc-platform/ops-agents/.env`
Если emergency-fix был сделан прямо на Synology в этих env-файлах, перенести sanitized-значение в `.env.synology.example`/docs, а секрет оставить только в live env.
## AI Hub relay-only deploy
Для локального тестирования с внешней Codex-машиной нельзя деплоить Launcher, Engine, Ops, Authentik или Tasker. Единственная допустимая удалённая точка в этой схеме — `ai-workspace-hub`, потому что удалённый worker должен иметь публичный WebSocket/HTTP relay.
С Mac, при смонтированном `/Volumes/docker`, синхронизировать только Hub source, compose и узкий apply-script:
```bash
cd /Users/dcconstructions/Downloads/mnt/NODEDC/platform
NAS_ROOT=/Volumes/docker/nodedc-platform ./infra/synology/sync-ai-hub-relay.sh
```
На Synology применить только `ai-workspace-hub`:
```bash
ssh dctouch@100.109.216.21 'cd /volume1/docker/nodedc-platform/platform && sudo bash apply-ai-hub-relay.sh'
```
Этот путь намеренно делает только:
- build `nodedc/ai-workspace-hub:local`;
- `docker compose up -d --no-deps --force-recreate ai-workspace-hub`;
- container health check;
- проверку `/api/ai-workspace/hub/v1/assistant-relays/<relayId>/poll`;
- public route check через `https://ai-hub.nodedc.ru`.
Он не меняет `.env.synology`, не синхронизирует Launcher/Tasker/Ops source, не пересоздаёт Authentik, reverse-proxy, базы, storage или product containers.
После успешного relay-only deploy локальная цепочка для теста должна быть такой:
```text
local Launcher/Engine/Ops/Auth/Assistant
-> deployed AI Hub relay: https://ai-hub.nodedc.ru
-> remote Codex worker
-> deployed AI Hub relay
-> local Assistant relay poll
-> local product services
```
## Лёгкое обновление Hub / Launcher
Для правок только в Launcher/BFF не пересоздавать Authentik, reverse-proxy, Tasker и Ops Agents:
@ -203,6 +247,66 @@ fi
echo 'launcher-pending-gate-ok'
```
## BIM Viewer deploy
`bim.nodedc.tech` на Synology можно вести напрямую через DSM Reverse Proxy на `172.22.0.222:18100`. В этом режиме Platform Caddy не участвует в публичном BIM-трафике, но `Caddyfile.http` всё равно содержит BIM route как запасной вариант для маршрута через `172.22.0.222:18080`.
Canonical BIM deploy now uses `nodedc-deploy` with `component=bim-viewer`; do not deploy BIM by manually running `docker compose up` from the source directory as the normal path.
Live BIM root:
```text
/volume1/docker/nodedc-platform/bim-viewer/source
```
Live env stays outside artifacts:
```text
/volume1/docker/nodedc-platform/bim-viewer/source/.env
```
Before the first canonical apply, prepare `.env` from `.env.synology.example` and verify that `NODEDC_INTERNAL_ACCESS_TOKEN` matches `platform/.env.synology`. After that, `.env` must not be included in deploy artifacts.
Canonical deploy commands:
```bash
sudo /usr/local/sbin/nodedc-deploy verify-install
sudo /usr/local/sbin/nodedc-deploy plan /volume1/docker/nodedc-deploy/inbox/<bim-artifact>.tgz
sudo /usr/local/sbin/nodedc-deploy apply /volume1/docker/nodedc-deploy/inbox/<bim-artifact>.tgz
```
The `bim-viewer` runner component:
- applies payload under `/volume1/docker/nodedc-platform/bim-viewer/source`;
- rejects `.env`, `server/data`, upload/model/comment/share runtime storage, `node_modules`, `.git`, shell hooks and backup files;
- prepares required live runtime directories under `server/data` before compose;
- builds `nodedc/bim-converter:local` from `converter/Dockerfile`;
- recreates only `ndc-beam-viewer` and `nodedc-bim-converter`;
- healthchecks `http://127.0.0.1:18100/api/auth/session`.
Минимальная проверка после apply:
```bash
curl -k -fsS http://127.0.0.1:18100/api/auth/session
curl -k -sS -o /dev/null -w '%{http_code}\n' https://bim.nodedc.tech/
```
Ожидаемо: `/api/auth/session` возвращает `authRequired: true`, а прямой public root без BIM-сессии отдаёт `302` в Launcher login/launch. Public share `/share/<token>` должен открываться без авторизации и без toolbar.
## Tasker / OPS BIM iframe rebuild
OPS web bundle получает BIM URL на build-time через `VITE_BEAM_VIEWER_BASE_URL` и `VITE_BEAM_API_BASE_URL`. После смены домена пересобрать только web image:
```bash
cd /volume1/docker/nodedc-platform/tasker/plane-src
VITE_BEAM_VIEWER_BASE_URL=https://bim.nodedc.tech \
VITE_BEAM_API_BASE_URL=https://bim.nodedc.tech \
BUILD_BACKEND=0 BUILD_WEB=1 BUILD_ADMIN=0 \
sh rebuild-nas-legacy.sh
```
Это пересоздаёт только `web` и не трогает PostgreSQL/MinIO volumes.
## Authentik Admin и Brand CSS
NODE.DC auth-flow CSS must stay template-scoped. Do not store it in Authentik `Brand.branding_custom_css`: Authentik passes that CSS into Admin/User web component runtime and breaks native controls.

218
infra/synology/apply-ai-hub-relay.sh Executable file
View File

@ -0,0 +1,218 @@
#!/usr/bin/env bash
set -euo pipefail
DOCKER_BIN="${DOCKER_BIN:-/usr/local/bin/docker}"
PLATFORM_DIR="${PLATFORM_DIR:-/volume1/docker/nodedc-platform/platform}"
ENV_FILE="${ENV_FILE:-${PLATFORM_DIR}/${NODEDC_SYNOLOGY_ENV_FILE:-.env.synology}}"
COMPOSE_FILE="${COMPOSE_FILE:-${PLATFORM_DIR}/docker-compose.platform-http.yml}"
HUB_DIR="${HUB_DIR:-${PLATFORM_DIR}/ai-workspace-hub}"
RELAY_ID="${AI_WORKSPACE_ASSISTANT_ACTION_RELAY_ID:-local-dev}"
PUBLIC_VERIFY_BASE_URL="${AI_WORKSPACE_HUB_VERIFY_BASE_URL:-https://ai-hub.nodedc.ru}"
VERIFY_PUBLIC="${VERIFY_PUBLIC:-1}"
if [[ ! -x "${DOCKER_BIN}" ]]; then
DOCKER_BIN="$(command -v docker)"
fi
read_env_value() {
local file="$1"
local key="$2"
awk -F= -v key="$key" '
$0 ~ "^[[:space:]]*#" { next }
$1 == key {
value = substr($0, index($0, "=") + 1)
gsub(/^[[:space:]]+|[[:space:]]+$/, "", value)
gsub(/^"|"$/, "", value)
print value
exit
}
' "$file"
}
require_file() {
local path="$1"
local label="$2"
if [[ ! -f "${path}" ]]; then
echo "${label} missing: ${path}" >&2
exit 1
fi
}
require_dir() {
local path="$1"
local label="$2"
if [[ ! -d "${path}" ]]; then
echo "${label} missing: ${path}" >&2
exit 1
fi
}
show_container_debug() {
local container_id="$1"
echo "== ai-workspace-hub debug =="
"${DOCKER_BIN}" ps --filter "id=${container_id}" --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}' || true
echo "-- recent logs --"
"${DOCKER_BIN}" logs --tail 120 "${container_id}" || true
}
check_container_health() {
local container_id="$1"
"${DOCKER_BIN}" exec "${container_id}" node -e '
fetch("http://127.0.0.1:18081/healthz")
.then(async (response) => {
const body = await response.text();
console.log(body);
process.exit(response.ok ? 0 : 1);
})
.catch(() => process.exit(2));
'
}
check_container_relay_route() {
local container_id="$1"
"${DOCKER_BIN}" exec \
-e RELAY_ID="${RELAY_ID}" \
-e RELAY_TOKEN="${relay_token}" \
"${container_id}" \
node -e '
const relayId = encodeURIComponent(process.env.RELAY_ID || "local-dev");
const token = process.env.RELAY_TOKEN || "";
fetch(`http://127.0.0.1:18081/api/ai-workspace/hub/v1/assistant-relays/${relayId}/poll`, {
method: "POST",
headers: {
authorization: `Bearer ${token}`,
accept: "application/json",
"content-type": "application/json",
},
body: JSON.stringify({ limit: 1, timeoutMs: 1 }),
})
.then(async (response) => {
const text = await response.text();
if (response.status !== 200) {
console.error(`relay route failed: status=${response.status} body=${text.slice(0, 300)}`);
process.exit(1);
}
let payload = {};
try {
payload = JSON.parse(text);
} catch {}
console.log(JSON.stringify({
ok: payload.ok === true,
relayId: payload.relayId,
calls: Array.isArray(payload.calls) ? payload.calls.length : null,
}));
})
.catch((error) => {
console.error(error);
process.exit(2);
});
'
}
echo "== ai hub relay preflight =="
require_dir "${PLATFORM_DIR}" "Platform directory"
require_dir "${HUB_DIR}" "AI Workspace Hub source directory"
require_file "${ENV_FILE}" "Synology env file"
require_file "${COMPOSE_FILE}" "Synology compose file"
require_file "${HUB_DIR}/Dockerfile" "AI Workspace Hub Dockerfile"
require_file "${HUB_DIR}/package.json" "AI Workspace Hub package.json"
require_file "${HUB_DIR}/src/server.mjs" "AI Workspace Hub server"
hub_token="${AI_WORKSPACE_HUB_TOKEN:-$(read_env_value "${ENV_FILE}" AI_WORKSPACE_HUB_TOKEN || true)}"
internal_token="${NODEDC_INTERNAL_ACCESS_TOKEN:-$(read_env_value "${ENV_FILE}" NODEDC_INTERNAL_ACCESS_TOKEN || true)}"
relay_token="${hub_token:-${internal_token}}"
if [[ -z "${relay_token}" ]]; then
echo "No AI_WORKSPACE_HUB_TOKEN or NODEDC_INTERNAL_ACCESS_TOKEN found for relay verification." >&2
exit 1
fi
cd "${PLATFORM_DIR}"
if ! "${DOCKER_BIN}" compose --env-file "${ENV_FILE}" -f "${COMPOSE_FILE}" config --services \
| grep -qx 'ai-workspace-hub'; then
echo "Compose service ai-workspace-hub is not available." >&2
exit 1
fi
echo "== build ai-workspace-hub only =="
"${DOCKER_BIN}" compose \
--env-file "${ENV_FILE}" \
-f "${COMPOSE_FILE}" \
build ai-workspace-hub
echo "== recreate ai-workspace-hub only =="
"${DOCKER_BIN}" compose \
--env-file "${ENV_FILE}" \
-f "${COMPOSE_FILE}" \
up -d --no-deps --force-recreate ai-workspace-hub
container_id="$(
"${DOCKER_BIN}" compose \
--env-file "${ENV_FILE}" \
-f "${COMPOSE_FILE}" \
ps -q ai-workspace-hub
)"
if [[ -z "${container_id}" ]]; then
echo "Cannot resolve ai-workspace-hub container id after apply." >&2
exit 1
fi
echo "== container health =="
health_ok=0
for attempt in $(seq 1 30); do
if check_container_health "${container_id}"; then
health_ok=1
break
fi
echo "ai-workspace-hub-not-ready attempt=${attempt}/30"
sleep 2
done
if [[ "${health_ok}" != "1" ]]; then
show_container_debug "${container_id}"
exit 1
fi
echo "== container relay route =="
relay_ok=0
for attempt in $(seq 1 10); do
if check_container_relay_route "${container_id}"; then
relay_ok=1
break
fi
echo "ai-workspace-hub-relay-not-ready attempt=${attempt}/10"
sleep 2
done
if [[ "${relay_ok}" != "1" ]]; then
show_container_debug "${container_id}"
exit 1
fi
if [[ "${VERIFY_PUBLIC}" == "1" ]]; then
if command -v curl >/dev/null 2>&1; then
echo "== public relay route =="
public_body="$(mktemp -t ai-hub-relay-public.XXXXXX)"
public_status="$(
curl -k -sS -m 20 \
-o "${public_body}" \
-w '%{http_code}' \
-X POST "${PUBLIC_VERIFY_BASE_URL%/}/api/ai-workspace/hub/v1/assistant-relays/${RELAY_ID}/poll" \
-H "Authorization: Bearer ${relay_token}" \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
--data '{"limit":1,"timeoutMs":1}'
)"
if [[ "${public_status}" != "200" ]]; then
echo "public relay route failed: status=${public_status}" >&2
head -c 300 "${public_body}" >&2 || true
echo >&2
rm -f "${public_body}"
exit 1
fi
rm -f "${public_body}"
echo "public-relay-route-ok"
else
echo "curl is not available; skipped public relay route check."
fi
fi
echo "ai-hub-relay-apply-ok"

10
infra/synology/backup-current.sh
View File

@ -16,7 +16,8 @@ mkdir -p "${BACKUP_DIR}/files/platform" \
"${BACKUP_DIR}/files/launcher" \
"${BACKUP_DIR}/files/authentik" \
"${BACKUP_DIR}/files/tasker" \
"${BACKUP_DIR}/files/ops-agents"
"${BACKUP_DIR}/files/ops-agents" \
"${BACKUP_DIR}/files/bim-viewer"
rsync_dir() {
local source="$1"
@ -47,6 +48,7 @@ rsync_dir "${NAS_ROOT}/platform/authentik/" "${BACKUP_DIR}/files/platform/authen
rsync_dir "${NAS_ROOT}/platform/notification-core/" "${BACKUP_DIR}/files/platform/notification-core/"
rsync_dir "${NAS_ROOT}/platform/ai-workspace-hub/" "${BACKUP_DIR}/files/platform/ai-workspace-hub/"
rsync_dir "${NAS_ROOT}/platform/ai-workspace-assistant/" "${BACKUP_DIR}/files/platform/ai-workspace-assistant/"
rsync_dir "${NAS_ROOT}/bim-viewer/source/server/data/" "${BACKUP_DIR}/files/bim-viewer/server-data/"
rsync_file "${NAS_ROOT}/platform/.env.synology" "${BACKUP_DIR}/files/platform/"
rsync_file "${NAS_ROOT}/platform/.env.synology.example" "${BACKUP_DIR}/files/platform/"
@ -61,6 +63,10 @@ rsync_file "${NAS_ROOT}/ops-agents/.env" "${BACKUP_DIR}/files/ops-agents/"
rsync_file "${NAS_ROOT}/ops-agents/.env.synology.example" "${BACKUP_DIR}/files/ops-agents/"
rsync_file "${NAS_ROOT}/ops-agents/docker-compose.synology.yml" "${BACKUP_DIR}/files/ops-agents/"
rsync_file "${NAS_ROOT}/bim-viewer/source/.env" "${BACKUP_DIR}/files/bim-viewer/"
rsync_file "${NAS_ROOT}/bim-viewer/source/.env.synology.example" "${BACKUP_DIR}/files/bim-viewer/"
rsync_file "${NAS_ROOT}/bim-viewer/source/docker-compose.beam.yml" "${BACKUP_DIR}/files/bim-viewer/"
cat > "${BACKUP_DIR}/manifest.txt" <<EOF
NODE.DC platform current backup
timestamp=${TIMESTAMP}
@ -77,11 +83,13 @@ Contains:
- AI Workspace Assistant source/config: platform/ai-workspace-assistant, platform compose/env
- Tasker runtime config: tasker/plane-app/.env.synology, compose, Synology override
- Ops Agents Gateway runtime config: ops-agents/.env, compose
- BIM Viewer runtime data/config: bim-viewer/source/server/data, .env, compose
Secrets:
- files/platform/.env.synology contains live secrets.
- files/tasker/.env.synology contains live secrets.
- files/ops-agents/.env contains live secrets.
- files/bim-viewer/.env contains live secrets.
- Keep this backup private.
EOF

55
infra/synology/deploy-current.sh
View File

@ -9,6 +9,7 @@ TASKER_REPO="${TASKER_REPO:-}"
TASKER_SYNC_SOURCE="${TASKER_SYNC_SOURCE:-0}"
TASKER_CHANGED_BASE="${TASKER_CHANGED_BASE:-}"
GATEWAY_REPO="${GATEWAY_REPO:-}"
BIM_REPO="${BIM_REPO:-}"
SYNC_AUTHENTIK_TEMPLATES="${SYNC_AUTHENTIK_TEMPLATES:-0}"
RSYNC_METADATA_ARGS=()
@ -24,6 +25,10 @@ fi
mkdir -p "${NAS_ROOT}/platform"
rsync -av "${RSYNC_METADATA_ARGS[@]}" \
"${PLATFORM_REPO}/infra/synology/.env.synology.example" \
"${NAS_ROOT}/platform/.env.synology.example"
rsync -av "${RSYNC_METADATA_ARGS[@]}" \
"${PLATFORM_REPO}/infra/synology/docker-compose.platform-http.yml" \
"${NAS_ROOT}/platform/docker-compose.platform-http.yml"
@ -64,6 +69,14 @@ rsync -av "${RSYNC_METADATA_ARGS[@]}" --delete \
"${PLATFORM_REPO}/services/ai-workspace-assistant/" \
"${NAS_ROOT}/platform/ai-workspace-assistant/"
mkdir -p "${NAS_ROOT}/platform/ai-workspace-assistant/ontology-core"
rsync -av "${RSYNC_METADATA_ARGS[@]}" --delete \
--exclude='node_modules/' \
--exclude='.env' \
--exclude='.env.*' \
"${PLATFORM_REPO}/services/ontology-core/" \
"${NAS_ROOT}/platform/ai-workspace-assistant/ontology-core/"
if [[ "${SYNC_AUTHENTIK_TEMPLATES}" == "1" ]]; then
mkdir -p "${NAS_ROOT}/authentik/custom-templates"
rsync -av "${RSYNC_METADATA_ARGS[@]}" --delete \
@ -82,6 +95,7 @@ if [[ -n "${LAUNCHER_REPO}" ]]; then
mkdir -p "${NAS_ROOT}/launcher/source"
rsync -av "${RSYNC_METADATA_ARGS[@]}" --delete \
--exclude='.git/' \
--exclude='.DS_Store' \
--exclude='node_modules/' \
--exclude='dist/' \
--exclude='server/storage/*' \
@ -92,6 +106,35 @@ else
echo "LAUNCHER_REPO is not set; launcher source was not synced."
fi
if [[ -n "${BIM_REPO}" ]]; then
if [[ ! -f "${BIM_REPO}/docker-compose.beam.yml" || ! -d "${BIM_REPO}/server" || ! -d "${BIM_REPO}/frontend" ]]; then
echo "BIM_REPO must point to NODEDC_BIM_VIEWER with docker-compose.beam.yml, server and frontend: ${BIM_REPO}" >&2
exit 1
fi
mkdir -p "${NAS_ROOT}/bim-viewer/source"
rm -rf \
"${NAS_ROOT}/bim-viewer/source/app" \
"${NAS_ROOT}/bim-viewer/source/docs"
rsync -av "${RSYNC_METADATA_ARGS[@]}" --delete \
--exclude='.git/' \
--exclude='.DS_Store' \
--exclude='node_modules/' \
--exclude='dist/' \
--exclude='app/' \
--exclude='docs/' \
--exclude='server/node_modules/' \
--exclude='frontend/node_modules/' \
--exclude='server/data/' \
--include='.env.synology.example' \
--exclude='.env' \
--exclude='.env.*' \
"${BIM_REPO}/" \
"${NAS_ROOT}/bim-viewer/source/"
else
echo "BIM_REPO is not set; BIM Viewer source was not synced."
fi
if [[ -n "${TASKER_REPO}" ]]; then
if [[ ! -d "${TASKER_REPO}/plane-src" || ! -d "${TASKER_REPO}/plane-app" ]]; then
echo "TASKER_REPO must point to NODEDC_TASKMANAGER with plane-src and plane-app: ${TASKER_REPO}" >&2
@ -200,6 +243,18 @@ If runtime was already applied and only verification is needed:
cd /volume1/docker/nodedc-platform/platform
sudo bash verify-current-runtime.sh
Optional BIM Viewer apply after BIM_REPO sync:
cd /volume1/docker/nodedc-platform/bim-viewer/source
sudo cp -n .env.synology.example .env
# Edit .env before first production start: NODEDC_INTERNAL_ACCESS_TOKEN must match platform .env.synology.
sudo /usr/local/bin/docker compose \
--env-file .env \
-f docker-compose.beam.yml \
up -d --build --force-recreate ndc-beam-viewer nodedc-bim-converter
curl -k -fsS http://127.0.0.1:18100/api/auth/session
Manual equivalent:
cd /volume1/docker/nodedc-platform/platform

2
infra/synology/docker-compose.platform-http.yml
View File

@ -142,6 +142,7 @@ services:
AI_WORKSPACE_HUB_INTERNAL_URL: ${AI_WORKSPACE_HUB_INTERNAL_URL:-https://ai-hub.nodedc.ru}
AI_WORKSPACE_HUB_TOKEN: ${AI_WORKSPACE_HUB_TOKEN:?ai workspace hub token required}
AI_WORKSPACE_HUB_FALLBACK_URLS: ${AI_WORKSPACE_HUB_FALLBACK_URLS:-}
NDC_ONTOLOGY_LAUNCHER_BASE_URL: http://launcher:5173
expose:
- "18082"
ports:
@ -165,6 +166,7 @@ services:
PORT: 18081
AI_WORKSPACE_HUB_TOKEN: ${AI_WORKSPACE_HUB_TOKEN:?ai workspace hub token required}
NODEDC_INTERNAL_ACCESS_TOKEN: ${NODEDC_INTERNAL_ACCESS_TOKEN:-}
NODEDC_AI_WORKSPACE_ASSISTANT_URL: http://ai-workspace-assistant:18082
AI_WORKSPACE_HUB_WS_PATH: /api/ai-workspace/hub
expose:
- "18081"

56
infra/synology/sync-ai-hub-relay.sh Executable file
View File

@ -0,0 +1,56 @@
#!/usr/bin/env bash
set -euo pipefail
SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
PLATFORM_REPO="$(cd -- "${SCRIPT_DIR}/../.." && pwd)"
NAS_ROOT="${NAS_ROOT:-/Volumes/docker/nodedc-platform}"
SSH_TARGET="${SSH_TARGET:-dctouch@100.109.216.21}"
RSYNC_METADATA_ARGS=()
if [[ "${RSYNC_PRESERVE_METADATA:-0}" != "1" ]]; then
RSYNC_METADATA_ARGS=(--no-times --no-perms --no-owner --no-group)
fi
if [[ ! -d "${NAS_ROOT}" ]]; then
echo "NAS_ROOT not found: ${NAS_ROOT}" >&2
echo "Set NAS_ROOT=/path/to/nodedc-platform when the Synology share is mounted elsewhere." >&2
exit 1
fi
if [[ ! -f "${PLATFORM_REPO}/infra/synology/docker-compose.platform-http.yml" ]]; then
echo "Synology compose is missing in local repo." >&2
exit 1
fi
if [[ ! -d "${PLATFORM_REPO}/services/ai-workspace-hub" ]]; then
echo "AI Workspace Hub source is missing in local repo." >&2
exit 1
fi
mkdir -p "${NAS_ROOT}/platform"
rsync -av "${RSYNC_METADATA_ARGS[@]}" \
"${PLATFORM_REPO}/infra/synology/docker-compose.platform-http.yml" \
"${NAS_ROOT}/platform/docker-compose.platform-http.yml"
rsync -av "${RSYNC_METADATA_ARGS[@]}" \
"${PLATFORM_REPO}/infra/synology/apply-ai-hub-relay.sh" \
"${NAS_ROOT}/platform/apply-ai-hub-relay.sh"
mkdir -p "${NAS_ROOT}/platform/ai-workspace-hub"
rsync -av "${RSYNC_METADATA_ARGS[@]}" --delete \
--exclude='node_modules/' \
--exclude='.env' \
--exclude='.env.*' \
"${PLATFORM_REPO}/services/ai-workspace-hub/" \
"${NAS_ROOT}/platform/ai-workspace-hub/"
cat <<EOF
AI Hub relay files synced to NAS mount.
Apply only AI Workspace Hub on Synology:
ssh ${SSH_TARGET} 'cd /volume1/docker/nodedc-platform/platform && sudo bash apply-ai-hub-relay.sh'
EOF

14
infra/synology/verify-current-runtime.sh
View File

@ -71,6 +71,20 @@ echo "== ai workspace assistant Ops entitlement adapter check =="
"${DOCKER_BIN}" exec nodedc-platform-ai-workspace-assistant-1 sh -lc \
'test "$AI_WORKSPACE_OPS_ENTITLEMENT_URL" = "http://172.22.0.222:18190/api/internal/v1/ai-workspace/entitlements" && test -n "$AI_WORKSPACE_OPS_ENTITLEMENT_TOKEN" && echo ai-workspace-ops-entitlement-env-ok'
echo "== BIM viewer auth/session check =="
bim_session="$(fetch_with_retry http://127.0.0.1:18100/api/auth/session)"
printf '%s' "$bim_session" | grep -aE '"authRequired":true|"loginUrl"'
echo "== BIM viewer public redirect check =="
bim_public_status="$(
curl -k -sS -o /dev/null -w '%{http_code}' https://bim.nodedc.tech/
)"
if [[ "$bim_public_status" != "302" ]]; then
echo "public BIM root did not redirect to Launcher auth: status=${bim_public_status}"
exit 1
fi
echo "bim-public-auth-redirect-ok"
echo "== auth flow check =="
auth_flow="$(fetch_with_retry https://id.nodedc.ru/if/flow/default-authentication-flow/)"
printf '%s' "$auth_flow" \

3
packages/auth-sdk/README.md
View File

@ -10,6 +10,7 @@
- нормализация claims;
- helper `requireAppAccess(groupName)`;
- helper `getCurrentUser()`;
- typed `ndcauth.session` helpers для cross-app login/logout/change revalidation events;
- typed `AuthUser`.
## Type contract
@ -29,3 +30,5 @@ export type AuthUser = {
Первый SDK рассчитан на Launcher backend и будущие Node.js/Next.js сервисы.
Для Plane fork на Python/Django нужна отдельная реализация middleware по тем же правилам, а этот пакет остается спецификацией для TypeScript приложений.
Session sync на 23.06.2026 не считается закрытым SDK-контрактом. Общий logout path уже существует в платформе, а BIM Viewer добавил BIM-first login-sync marker/revalidation slice. Перед подключением следующего сервиса нужно оформить общий `ndcauth.session` protocol здесь или в соседнем platform package, чтобы приложения не копировали BIM-specific логику.

1
services/ai-workspace-assistant/Dockerfile
View File

@ -6,6 +6,7 @@ COPY package*.json ./
RUN npm ci --omit=dev
COPY src ./src
COPY ontology-core /ontology-core
ENV NODE_ENV=production
EXPOSE 18082

15
services/ai-workspace-assistant/Dockerfile.dev Normal file
View File

@ -0,0 +1,15 @@
FROM node:22-alpine
WORKDIR /app/services/ai-workspace-assistant
COPY ai-workspace-assistant/package*.json ./
RUN npm ci --omit=dev
COPY ai-workspace-assistant/src ./src
COPY ai-workspace-assistant/docs ./docs
COPY ontology-core /app/services/ontology-core
ENV NODE_ENV=production
EXPOSE 18082
CMD ["npm", "start"]

45
services/ai-workspace-assistant/README.md
View File

@ -53,6 +53,49 @@ POST /api/ai-workspace/assistant/v1/threads/:threadId/messages
GET /api/ai-workspace/assistant/v1/threads/:threadId/messages
```
Assistant actions:
```text
POST /api/ai-workspace/assistant/v1/actions
```
This is the platform entrypoint for ontology-backed assistant tool calls. Natural-language chat dispatch still goes through the selected assistant model/executor first; `ontology-core` is the deterministic policy/action layer the assistant calls after it has interpreted the user's intent.
Request shape:
```json
{
"phase": "preview",
"input": {
"actionId": "hub.user.block",
"targetUserId": "user_123",
"confirmed": true,
"idempotencyKey": "hub.user.block:user_admin:user_123"
}
}
```
For write execution, first call `phase=preview`, show the returned `action.confirmation` to the user, then call `phase=execute` with `confirmationToken`. The final mutation still goes through the app-owned Launcher admin API guards; this service only routes the registered action.
Launcher action gateway configuration:
```text
NDC_ONTOLOGY_LAUNCHER_BASE_URL=http://launcher.local.nodedc
NDC_LAUNCHER_INTERNAL_ACCESS_TOKEN=...
```
If `NDC_LAUNCHER_INTERNAL_ACCESS_TOKEN` is not set, the service falls back to `NODEDC_INTERNAL_ACCESS_TOKEN`.
The first HUB action ids exposed to assistants are:
- `hub.user.read_admin_summary`
- `hub.invite.list_pending`
- `hub.access_request.list_pending`
Read actions can be executed without user confirmation after the assistant has selected the structured action. Privileged/write actions still require explicit preview, user confirmation, and execute.
App BFFs should pass active scope facts in action input (`clientId`, `coreAssistantRole`, `membershipRole`, `membershipStatus`) so policy stays data-driven instead of prompt-driven.
Supported initial surfaces:
- `engine`
@ -71,6 +114,8 @@ Supported initial tool packs:
Every dispatch builds an `ai-workspace.run-profile.v1` payload. The raw profile is sent only to the bridge worker; public API responses and run metadata keep MCP headers redacted.
The canonical cross-surface execution contract is [AI Workspace Protocol v1](./docs/AI_WORKSPACE_PROTOCOL_V1.md). It defines layer ownership, run profile shape, tool manifests, worker boundaries, Hub boundaries, app adapter rules, and the migration path from the current scaffold.
The worker uses `runProfile.toolProfile.mcpServers` to create an isolated per-run `CODEX_HOME/config.toml`. Install-time MCP config remains only as a legacy fallback when no dynamic profile is available.
Runtime deploy readiness is tracked in [TEST_MATRIX.md](./TEST_MATRIX.md). The `smoke:run-profile` script covers the entitlement adapter to run profile contract and public secret redaction.

434
services/ai-workspace-assistant/docs/AI_WORKSPACE_PROTOCOL_V1.md Normal file
View File

@ -0,0 +1,434 @@
# AI Workspace Protocol v1
Status: draft canonical contract.
Date: 2026-06-19
Owner: NODE.DC AI Workspace Assistant.
This document fixes the platform contract for cross-application assistant
execution. It exists to prevent assistant capabilities from spreading through
prompt-only rules, app-specific shortcuts, worker code, or transport glue.
## Goal
AI Workspace Protocol v1 defines how a user request from any NODE.DC surface
is converted into a safe, auditable capability call across HUB, OPS, ENGINE,
and future platform applications.
The protocol must support hundreds of functional blocks without changing the
worker for every new feature.
## Layer Ownership
### Client Surface
Examples: ENGINE UI, OPS UI, HUB UI, future platform apps.
Owns:
- visible UI state;
- current surface context;
- active selected objects;
- user-facing preview and confirmation UI.
Must not own:
- final permission enforcement;
- platform action registry;
- backend actor identity;
- raw internal tokens.
### AI Workspace Assistant
Owns:
- assistant thread/session metadata;
- selected executor;
- run profile construction;
- tool manifest construction;
- action routing entrypoint;
- policy prompts derived from structured contracts;
- run-scoped entitlement resolution;
- public redaction of run diagnostics.
Must be the only platform layer that decides which assistant tools are exposed
to a run.
### Ontology Core
Owns:
- canonical entities and relations;
- aliases and resolver rules;
- assistant access policy;
- assistant action registry;
- risk policy;
- confirmation policy;
- app-owned adapter descriptors.
Must not own:
- HUB user source data;
- OPS card source data;
- ENGINE workflow source data;
- transport routing;
- worker execution.
### AI Hub
Owns:
- remote worker rendezvous;
- pairing;
- dispatch relay;
- message delivery;
- proxying to trusted internal services when configured.
Must not own:
- assistant action catalog;
- business permissions;
- prompt policy;
- domain-specific decisions.
### Worker
Owns:
- local/remote executor runtime;
- Codex/model process launch;
- per-run isolated config;
- tool relay based on the received manifest;
- event/result streaming.
Must not own:
- HUB/OPS/ENGINE action IDs as hardcoded product knowledge;
- role rules;
- app-level permission decisions;
- long-lived platform tokens;
- app-owned adapters.
### App API / MCP
Examples: Launcher/HUB API, OPS Gateway, ENGINE API.
Owns:
- source-of-truth data;
- object-level ACL;
- final enforcement;
- app-native audit;
- app-owned adapter routes.
Must reject invalid or forged requests even when AI Workspace allowed the plan.
## Canonical Flow
```mermaid
flowchart LR
U["User request"] --> C["Client surface context"]
C --> A["AI Workspace Assistant"]
A --> O["Ontology Core: resolve capability and policy"]
O --> A
A --> P["Run profile + tool manifest"]
P --> W["Worker or in-process executor"]
W --> R["Tool relay"]
R --> API["App API / MCP"]
API --> AUD["Audit + result"]
AUD --> A
A --> C
```
Read actions may execute after the assistant selects a structured action.
Write or privileged actions must use preview first, then explicit confirmation,
then execute. Destructive actions are not exposed as assistant capabilities.
## Run Profile
Schema version:
```text
ai-workspace.run-profile.v1
```
Required top-level fields:
```json
{
"schemaVersion": "ai-workspace.run-profile.v1",
"runId": "uuid",
"createdAt": "2026-06-19T00:00:00.000Z",
"expiresAt": "2026-06-19T00:10:00.000Z",
"audience": "ai-workspace-worker",
"requestId": "uuid-or-nonce",
"owner": {},
"sourceSurface": "engine",
"activeContext": {},
"toolProfile": {},
"policyPrompt": "derived text",
"integrity": {}
}
```
Required rules:
- `expiresAt` must be short-lived.
- `requestId` must be unique enough for replay protection.
- `audience` must name the intended recipient class.
- `integrity` must contain a server-side hash/signature before production use.
- public diagnostics must redact tokens, headers, secrets, and raw internal URLs.
## Actor Claims
Actor claims are backend facts, not user text.
Canonical owner shape:
```json
{
"ownerKey": "email:dcctouch@gmail.com",
"userId": "platform-user-id",
"email": "dcctouch@gmail.com",
"role": "root-admin",
"groups": ["nodedc:superadmin"]
}
```
Rules:
- client-supplied actor headers are not trusted directly;
- trusted App BFF or AI Workspace must resolve actor claims;
- target App API must verify the actor again against app-native state;
- app adapters may receive claims, but never treat them as the only authority.
## Tool Profile
Schema version:
```text
ai-workspace.tool-profile.v1
```
Shape:
```json
{
"schemaVersion": "ai-workspace.tool-profile.v1",
"enabledToolPacks": ["engine", "ops", "ndc-agent-core"],
"mcpServers": [],
"assistantActions": {
"schemaVersion": "ai-workspace.assistant-actions.v1",
"endpoint": "/api/ai-workspace/assistant/v1/actions",
"actionIds": ["hub.user.read_admin_summary"],
"phases": ["preview", "execute"],
"tokenRef": "run-token:assistant-actions"
}
}
```
Rules:
- action IDs come from AI Workspace Assistant + Ontology Core, not from ENGINE
local routes or worker source code;
- worker may read and expose a generic tool based on this manifest;
- worker must not hardcode the product meaning of an action ID;
- `tokenRef` or server-side relay is preferred over embedding raw bearer tokens;
- if a bearer token is unavoidable during a scaffold phase, it must be
short-lived, run-scoped, redacted from public output, and removed before
production.
## Assistant Action Call
Endpoint:
```text
POST /api/ai-workspace/assistant/v1/actions
```
Preview request:
```json
{
"phase": "preview",
"input": {
"actionId": "hub.user.block",
"targetUserId": "user_123",
"idempotencyKey": "hub.user.block:actor:target"
}
}
```
Execute request:
```json
{
"phase": "execute",
"input": {
"actionId": "hub.user.block",
"targetUserId": "user_123",
"confirmationToken": "preview-token",
"idempotencyKey": "hub.user.block:actor:target"
}
}
```
Rules:
- the assistant selects `actionId` after understanding natural language;
- preview must return a human-readable expected effect;
- write execution must require a matching confirmation token;
- write execution must include an idempotency key;
- app-owned adapter must re-check permissions;
- delete/hard destructive requests resolve to forbidden with safe alternatives.
## Worker Protocol
The worker receives a run payload and starts the configured executor.
Worker responsibilities:
- create isolated per-run config;
- expose only tools described by the run profile;
- relay tool calls to AI Workspace or app MCP endpoints;
- stream model/tool events back to AI Workspace;
- redact runtime secrets from logs.
Worker non-responsibilities:
- it does not decide whether a HUB admin can block a user;
- it does not know all HUB/OPS/ENGINE action IDs in source code;
- it does not store internal platform tokens after a run;
- it does not bypass AI Workspace with raw app API calls.
## Hub Protocol
AI Hub may proxy:
- worker dispatch;
- worker events;
- assistant action requests to AI Workspace Assistant.
AI Hub must not:
- build action catalogs;
- evaluate assistant access policy;
- mutate app data directly;
- accept public actor claims as final truth.
## App Adapter Rules
Every app adapter must define:
- owning app: `hub`, `ops`, `engine`, or another platform app;
- allowed method/path list;
- read/write/destructive classification;
- required native scope or role;
- idempotency behavior for writes;
- audit event output;
- confirmation mode;
- safe alternatives for forbidden actions.
HUB examples:
- read admin summary;
- list pending invites;
- list pending access requests;
- block/unblock user;
- disable membership;
- change NDC Core Assistant role.
OPS examples:
- create/update card;
- append report/comment;
- read project/card context;
- update structured card blocks.
ENGINE examples:
- read workflow graph;
- select workflow/agent node;
- inspect workflow errors;
- change workflow ACL only through ENGINE-owned adapter.
## Security Requirements
Production requirements:
- all cross-service traffic uses TLS or an equivalent private secure channel;
- no long-lived internal token in worker, prompt, UI, or public diagnostics;
- run tokens are scoped by run, audience, capability, and expiry;
- run profile integrity is hash/signed by AI Workspace;
- writes require idempotency keys;
- privileged writes require preview and confirmation token;
- target App API performs final authorization;
- all writes produce audit events;
- app APIs reject forged actor headers from public clients;
- secret redaction is covered by smoke tests.
## Localhost vs Production
Localhost and production must use the same logical protocol:
```text
client -> AI Workspace Assistant -> Ontology Core -> AI Hub/Worker -> App API
```
Allowed differences:
- URLs;
- network transport;
- token issuer;
- deployment topology.
Not allowed:
- separate local-only business rules;
- Engine-only action catalog;
- worker-only permission model;
- production-only policy path that contradicts local behavior.
## Migration From Current Scaffold
Current scaffold deviations to remove:
1. ENGINE local bridge owns fallback `ASSISTANT_ACTION_TOOL_PROFILE`.
2. Worker prompt includes concrete HUB action IDs.
3. Worker receives or stores assistant action gateway bearer token.
4. Engine MCP server knows gateway URL/token and owner header rules.
5. AI Hub forwards owner headers without signed actor context.
Migration steps:
1. Move assistant action profile source of truth to AI Workspace Assistant.
2. Generate action IDs from Ontology Core action registry.
3. Replace raw token passthrough with run-scoped token or server-side relay.
4. Convert worker action support to generic manifest-driven relay.
5. Add protocol tests for boundary violations.
6. Mark current scaffold paths as legacy/fallback until removed.
## Boundary Tests
Minimum tests before production rollout:
- public run profile never exposes bearer tokens or internal secrets;
- worker source does not contain product action ID allowlists;
- ENGINE local routes do not contain HUB action registry;
- AI Hub does not evaluate business policy;
- forged public actor headers are rejected by app API;
- write execution without confirmation token is blocked;
- write replay with same idempotency key is safe;
- delete actions are unavailable and resolve to safe alternatives;
- local and production profiles share the same schema.
## Acceptance Criteria
The protocol is ready for product slices when:
- adding a new assistant function changes Ontology Core and the target app
adapter, not the worker;
- AI Workspace Assistant remains the only run profile source of truth;
- Hub remains transport-only;
- worker can be installed once and keep working as capabilities grow;
- target apps remain final enforcement owners;
- no prompt-only rule is required for safety-critical behavior.

24
services/ai-workspace-assistant/src/scripts/smoke-run-profile.mjs
View File

@ -44,6 +44,14 @@ const adapterPayload = {
const appGrants = normalizeEntitlementAdapterAppGrants(adapterPayload, adapter);
const mcpServers = runProfileMcpServersFromAppGrants({}, appGrants);
const appGrantSummary = summarizeRunAppGrants({ appGrants });
const assistantActions = {
schemaVersion: "ai-workspace.assistant-actions.v1",
endpoint: "/api/ai-workspace/hub/v1/assistant-relays/local-dev/actions",
gatewayUrl: "https://ai-hub.nodedc.ru/api/ai-workspace/hub/v1/assistant-relays/local-dev/actions",
gatewayToken: SECRET_TOKEN,
actionIds: ["hub.access_request.list_pending", "hub.user.read_admin_summary"],
phases: ["preview", "execute"],
};
const runProfile = {
schemaVersion: "ai-workspace.run-profile.v1",
runId: randomUUID(),
@ -71,6 +79,7 @@ const runProfile = {
mcpServers,
mcpServerNames: mcpServers.map((server) => server.serverName),
requiredMcpServerNames: mcpServers.filter((server) => server.required).map((server) => server.serverName),
assistantActions,
},
diagnostics: {
schemaVersion: "ai-workspace.run-profile.diagnostics.v1",
@ -106,6 +115,10 @@ assert.equal(publicProfile.toolProfile.mcpServers[0].serverName, "nodedc_ops_age
assert.equal(publicProfile.toolProfile.mcpServers[0].httpHeaders.Authorization, "<redacted>");
assert.equal(publicProfile.toolProfile.mcpServers[0].httpHeaders.Accept, "<redacted>");
assert.equal(publicProfile.toolProfile.mcpServers[0].headers, undefined);
assert.equal(publicProfile.toolProfile.assistantActions.endpoint, "/api/ai-workspace/hub/v1/assistant-relays/local-dev/actions");
assert.equal(publicProfile.toolProfile.assistantActions.gatewayUrl, "https://ai-hub.nodedc.ru/api/ai-workspace/hub/v1/assistant-relays/local-dev/actions");
assert.equal(publicProfile.toolProfile.assistantActions.gatewayToken, "<redacted>");
assert.deepEqual(publicProfile.toolProfile.assistantActions.actionIds, ["hub.access_request.list_pending", "hub.user.read_admin_summary"]);
assert.equal(JSON.stringify(publicProfile).includes(SECRET_TOKEN), false);
assert.match(runProfile.diagnostics.profileHash, /^[a-f0-9]{16}$/);
@ -114,7 +127,9 @@ console.log(JSON.stringify({
checks: [
"adapter_grant_normalized",
"token_scoped_ops_mcp_in_run_profile",
"assistant_action_relay_in_run_profile",
"public_run_profile_redacts_mcp_headers",
"public_run_profile_redacts_assistant_action_gateway_token",
"stable_public_profile_hash",
],
mcpServerNames: runProfile.toolProfile.mcpServerNames,
@ -276,6 +291,7 @@ function redactRunProfile(runProfile) {
appGrants: redactForPublicDiagnostics(runProfile.appGrants),
toolProfile: {
...(isPlainObject(runProfile.toolProfile) ? runProfile.toolProfile : {}),
assistantActions: redactAssistantActions(runProfile.toolProfile?.assistantActions),
mcpServers: Array.isArray(runProfile.toolProfile?.mcpServers)
? runProfile.toolProfile.mcpServers.map(redactMcpServer)
: [],
@ -283,6 +299,14 @@ function redactRunProfile(runProfile) {
};
}
function redactAssistantActions(value) {
if (!isPlainObject(value)) return value;
return {
...value,
...(value.gatewayToken ? { gatewayToken: "<redacted>" } : {}),
};
}
function redactMcpServer(server) {
if (!isPlainObject(server)) return {};
const headers = isPlainObject(server.httpHeaders) ? server.httpHeaders : {};

584
services/ai-workspace-assistant/src/server.mjs
View File

@ -3,6 +3,8 @@ import { createHash, randomUUID, timingSafeEqual } from "node:crypto";
import { readFile } from "node:fs/promises";
import { createServer } from "node:http";
import { Pool } from "pg";
import { handleAssistantCallerRequest } from "../../ontology-core/src/assistant-action-caller.mjs";
import { loadCatalog } from "../../ontology-core/src/catalog.mjs";
const SUPPORTED_SURFACES = new Set(["engine", "ops", "global"]);
const SUPPORTED_EXECUTOR_TYPES = new Set(["codex-remote", "ndc-agent-core"]);
@ -12,8 +14,25 @@ const SUPPORTED_THREAD_STATES = new Set(["active", "archived"]);
const SUPPORTED_MESSAGE_ROLES = new Set(["user", "assistant", "system", "tool"]);
const SUPPORTED_TOOL_PACKS = new Set(["engine", "ops", "ndc-agent-core", "deploy", "docs"]);
const SUPPORTED_RUN_STATUSES = new Set(["running", "completed", "failed", "timeout"]);
const ASSISTANT_ACTION_TOOL_PROFILE_BASE = {
schemaVersion: "ai-workspace.assistant-actions.v1",
endpoint: "/api/ai-workspace/assistant/v1/actions",
modelFlow: "interpret_user_intent_then_call_structured_action",
phases: ["preview", "execute"],
safety: {
read: "execute_after_structured_action_selection",
write: "preview_then_explicit_user_confirmation_then_execute",
destructive: "forbidden",
},
};
const ASSISTANT_ACTION_CACHE_TTL_MS = Number(process.env.AI_WORKSPACE_ASSISTANT_ACTION_CACHE_TTL_MS || 30_000);
const ASSISTANT_ACTION_RELAY_POLL_TIMEOUT_MS = Number(process.env.AI_WORKSPACE_ASSISTANT_RELAY_POLL_TIMEOUT_MS || 25_000);
const ASSISTANT_ACTION_RELAY_POLL_IDLE_MS = Number(process.env.AI_WORKSPACE_ASSISTANT_RELAY_POLL_IDLE_MS || 500);
const ASSISTANT_ACTION_RELAY_ERROR_BACKOFF_MS = Number(process.env.AI_WORKSPACE_ASSISTANT_RELAY_ERROR_BACKOFF_MS || 5_000);
const BRIDGE_RUN_MIRROR_POLL_MS = 1200;
const BRIDGE_RUN_MIRROR_MAX_MS = 12 * 60 * 60 * 1000;
let assistantActionIdsCache = { loadedAt: 0, actionIds: [] };
let assistantActionRelayStopping = false;
const config = readConfig();
const pool = new Pool({ connectionString: config.databaseUrl, max: config.databasePoolSize });
@ -47,6 +66,115 @@ app.patch("/api/ai-workspace/assistant/v1/settings", requireInternalApi, asyncRo
res.json({ ok: true, owner: publicOwner(owner), settings: publicOwnerSettings(settings) });
}));
app.post("/api/ai-workspace/assistant/v1/run-profile", requireInternalApi, asyncRoute(async (req, res) => {
const owner = getRequestOwner(req);
const command = sanitizeRunProfileCommand(req.body);
const ownerSettings = await getOwnerSettings(owner);
const executorId = command.selectedExecutorId || ownerSettings.selectedExecutorId;
if (!executorId) {
res.status(400).json({ ok: false, error: "ai_workspace_executor_required" });
return;
}
const executor = await getExecutor(owner, executorId);
if (!executor) {
res.status(404).json({ ok: false, error: "ai_workspace_executor_not_found" });
return;
}
const thread = {
id: command.threadId || randomUUID(),
title: command.threadTitle || "AI Workspace Bridge",
originSurface: command.originSurface || optionalString(command.context.surface) || "engine",
activeContext: {},
enabledToolPacks: command.enabledToolPacks,
};
const bridgePayload = {
context: command.context,
enabledToolPacks: command.enabledToolPacks,
workspacePath: command.workspacePath || executor.workspacePath || "",
client: command.client,
};
const runProfile = await buildRunProfile({ owner, thread, executor, ownerSettings, bridgePayload });
res.json({ ok: true, owner: publicOwner(owner), runProfile });
}));
app.post("/api/ai-workspace/assistant/v1/executors/:executorId/dispatch", requireInternalApi, asyncRoute(async (req, res) => {
const owner = getRequestOwner(req);
const executorId = sanitizeUuid(req.params.executorId, "executorId");
const executor = await getExecutor(owner, executorId);
if (!executor) {
res.status(404).json({ ok: false, error: "ai_workspace_executor_not_found" });
return;
}
const command = sanitizeBridgeDispatchCommand({ ...(isPlainObject(req.body) ? req.body : {}), selectedExecutorId: executorId });
if (!command.message) {
res.status(400).json({ ok: false, error: "ai_workspace_dispatch_requires_user_message" });
return;
}
const ownerSettings = await getOwnerSettings(owner);
const thread = {
id: command.threadId || randomUUID(),
title: command.threadTitle || "AI Workspace Bridge",
originSurface: command.originSurface || optionalString(command.context.surface) || "engine",
activeContext: {},
enabledToolPacks: command.enabledToolPacks,
};
const bridgePayload = {
threadId: thread.id,
threadTitle: thread.title,
workspacePath: command.workspacePath || executor.workspacePath || "",
message: command.message,
displayMessage: command.displayMessage || command.message,
publicUserMessage: command.publicUserMessage || command.message,
resume: command.resume,
history: command.history,
context: command.context,
enabledToolPacks: command.enabledToolPacks,
client: command.client,
};
bridgePayload.runProfile = await buildRunProfile({ owner, thread, executor, ownerSettings, bridgePayload });
const bridge = await dispatchExecutorMessage(executor, bridgePayload);
res.json({
ok: true,
owner: publicOwner(owner),
executorId: executor.id,
bridge,
runProfile: redactRunProfile(bridgePayload.runProfile),
});
}));
app.post("/api/ai-workspace/assistant/v1/executors/:executorId/stop", requireInternalApi, asyncRoute(async (req, res) => {
const owner = getRequestOwner(req);
const executorId = sanitizeUuid(req.params.executorId, "executorId");
const executor = await getExecutor(owner, executorId);
if (!executor) {
res.status(404).json({ ok: false, error: "ai_workspace_executor_not_found" });
return;
}
const command = sanitizeBridgeStopCommand(req.body);
if (!command.requestId && !command.threadId) {
res.status(400).json({ ok: false, error: "ai_workspace_stop_target_empty" });
return;
}
const bridge = await dispatchExecutorStop(executor, command);
res.json({
ok: true,
owner: publicOwner(owner),
executorId: executor.id,
bridge,
});
}));
app.post("/api/ai-workspace/assistant/v1/actions", requireInternalApi, asyncRoute(async (req, res) => {
const owner = getRequestOwner(req);
res.json(await executeAssistantActionRequest(req.body, owner));
}));
app.get("/api/ai-workspace/assistant/v1/executors", requireInternalApi, asyncRoute(async (req, res) => {
const owner = getRequestOwner(req);
const [executors, settings] = await Promise.all([
@ -397,6 +525,7 @@ await recoverBridgeRunMirrors();
httpServer.listen(config.port, "0.0.0.0", () => {
console.log(`NODE.DC AI Workspace Assistant listening on http://0.0.0.0:${config.port}`);
startAssistantActionRelayLoop();
});
process.on("SIGTERM", shutdown);
@ -1017,6 +1146,62 @@ async function dispatchExecutorMessage(executor, payload) {
};
}
async function dispatchExecutorStop(executor, payload) {
if (executor.connectionMode === "hub" || executor.pairingCode) {
const pairingCode = cleanPairingCode(executor.pairingCode);
if (!pairingCode) {
const error = new Error("bridge_pairing_code_empty");
error.status = 400;
throw error;
}
const response = await hubRequestJson(
`/api/ai-workspace/hub/v1/agents/${encodeURIComponent(pairingCode)}/dispatch`,
{
method: "POST",
body: {
command: "stop",
payload,
timeoutMs: 30000,
quiet: false,
},
},
10000
);
return {
ok: true,
accepted: true,
requestId: optionalString(response.requestId),
targetRequestId: payload.requestId,
threadId: payload.threadId,
mode: "hub",
};
}
const url = bridgeCommandUrl(executor.endpoint, "stop");
if (!url) {
const error = new Error("bridge_endpoint_required");
error.status = 400;
throw error;
}
const response = await fetchJson(
url,
{
method: "POST",
headers: { Accept: "application/json", "Content-Type": "application/json" },
body: JSON.stringify(payload),
},
10000
);
return {
ok: response?.ok !== false,
accepted: false,
response,
targetRequestId: payload.requestId,
threadId: payload.threadId,
mode: "direct",
};
}
async function createBridgeRun({ owner, thread, executor, bridge, payload }) {
const requestId = optionalString(bridge?.requestId);
if (!requestId || bridge?.accepted !== true || bridge?.mode !== "hub") return null;
@ -1447,6 +1632,7 @@ async function buildRunProfile({ owner, thread, executor, ownerSettings, bridgeP
const appGrants = summarizeRunAppGrants({ appGrants: grantResolution.appGrants });
const mcpServers = runProfileMcpServersFromAppGrants(ownerSettings, grantResolution.appGrants);
const mcpServerNames = mcpServers.map((server) => server.serverName).filter(Boolean);
const assistantActions = await assistantActionToolProfileForRun();
const requiredMcpServerNames = mcpServers
.filter((server) => server.required === true)
.map((server) => server.serverName)
@ -1464,6 +1650,8 @@ async function buildRunProfile({ owner, thread, executor, ownerSettings, bridgeP
entitlementAdapters: grantResolution.diagnostics,
mcpServerNames,
requiredMcpServerNames,
assistantActionIds: assistantActions.actionIds,
assistantActionGatewayConfigured: Boolean(assistantActions.gatewayUrl && assistantActions.gatewayToken),
missingContext: Array.isArray(context.missingContext)
? context.missingContext.map(optionalString).filter(Boolean)
: [],
@ -1490,14 +1678,164 @@ async function buildRunProfile({ owner, thread, executor, ownerSettings, bridgeP
mcpServers,
mcpServerNames,
requiredMcpServerNames,
assistantActions,
},
policyPrompt: buildRunProfilePolicyPrompt({ context, diagnostics }),
policyPrompt: buildRunProfilePolicyPrompt({ context, diagnostics, assistantActions }),
diagnostics,
};
runProfile.diagnostics.profileHash = runProfileHash(runProfile);
return runProfile;
}
async function assistantActionToolProfileForRun() {
const gatewayUrl = assistantActionGatewayUrlForRun();
const gatewayToken = optionalString(
process.env.NDC_AI_WORKSPACE_ASSISTANT_ACTION_GATEWAY_TOKEN ||
config.hubInternalAccessToken ||
config.internalAccessTokens[0] ||
""
);
const actionIds = await assistantActionIdsForRun();
return {
...ASSISTANT_ACTION_TOOL_PROFILE_BASE,
endpoint: actionGatewayEndpointPath(gatewayUrl) || ASSISTANT_ACTION_TOOL_PROFILE_BASE.endpoint,
actionIds,
...(gatewayUrl ? { gatewayUrl } : {}),
...(gatewayToken ? { gatewayToken } : {}),
};
}
function assistantActionGatewayUrlForRun() {
const explicit = cleanHttpEndpoint(process.env.NDC_AI_WORKSPACE_ASSISTANT_ACTION_GATEWAY_URL);
if (explicit) return explicit;
if (config.assistantActionRelayEnabled && config.assistantActionRelayId && config.hubInternalHttpUrl) {
return cleanHttpEndpoint(
`${config.hubInternalHttpUrl.replace(/\/+$/, "")}/api/ai-workspace/hub/v1/assistant-relays/${encodeURIComponent(config.assistantActionRelayId)}/actions`
);
}
return cleanHttpEndpoint(config.hubInternalHttpUrl || httpUrlFromWebSocketUrl(config.hubWebSocketUrl));
}
function actionGatewayEndpointPath(gatewayUrl) {
try {
const url = new URL(gatewayUrl);
return `${url.pathname}${url.search || ""}`;
} catch {
return "";
}
}
async function assistantActionIdsForRun() {
const now = Date.now();
if (
assistantActionIdsCache.actionIds.length &&
now - assistantActionIdsCache.loadedAt < ASSISTANT_ACTION_CACHE_TTL_MS
) {
return assistantActionIdsCache.actionIds;
}
try {
const catalog = await loadCatalog();
const actionIds = (Array.isArray(catalog?.assistantActions?.actions) ? catalog.assistantActions.actions : [])
.filter((action) => (
isPlainObject(action) &&
optionalString(action.id) &&
action.adapterStatus === "implemented" &&
action.confirmationMode !== "forbidden"
))
.map((action) => optionalString(action.id))
.filter(Boolean)
.sort();
assistantActionIdsCache = { loadedAt: now, actionIds };
return actionIds;
} catch {
assistantActionIdsCache = { loadedAt: now, actionIds: [] };
return [];
}
}
function startAssistantActionRelayLoop() {
if (!config.assistantActionRelayEnabled) return;
if (!config.assistantActionRelayId || !config.hubInternalHttpUrl || !config.hubInternalAccessToken) {
console.warn("Assistant action relay disabled: relay id, hub URL, or hub token is missing.");
return;
}
void assistantActionRelayLoop();
}
async function assistantActionRelayLoop() {
while (!assistantActionRelayStopping) {
try {
const payload = await hubRequestJson(
`/api/ai-workspace/hub/v1/assistant-relays/${encodeURIComponent(config.assistantActionRelayId)}/poll`,
{
method: "POST",
body: {
limit: 5,
timeoutMs: ASSISTANT_ACTION_RELAY_POLL_TIMEOUT_MS,
},
},
ASSISTANT_ACTION_RELAY_POLL_TIMEOUT_MS + 5000
);
const calls = Array.isArray(payload?.calls) ? payload.calls : [];
for (const call of calls) {
void handleAssistantActionRelayCall(call).catch((error) => {
console.error("Assistant action relay call failed:", errorMessage(error));
});
}
await delay(ASSISTANT_ACTION_RELAY_POLL_IDLE_MS);
} catch (error) {
if (!assistantActionRelayStopping) {
console.error("Assistant action relay poll failed:", errorMessage(error));
await delay(ASSISTANT_ACTION_RELAY_ERROR_BACKOFF_MS);
}
}
}
}
async function handleAssistantActionRelayCall(call) {
const callId = optionalString(call?.callId);
if (!callId) return;
let status = 200;
let body = null;
try {
const owner = getRequestOwner({ headers: relayCallHeaders(call?.headers), query: {} });
body = await executeAssistantActionRequest(isPlainObject(call?.payload) ? call.payload : {}, owner);
} catch (error) {
status = Number(error?.status || 500);
body = { ok: false, error: errorMessage(error) };
}
await hubRequestJson(
`/api/ai-workspace/hub/v1/assistant-relays/${encodeURIComponent(config.assistantActionRelayId)}/results/${encodeURIComponent(callId)}`,
{
method: "POST",
body: {
status,
body,
},
},
10000
);
}
function relayCallHeaders(value) {
const headers = {};
if (!isPlainObject(value)) return headers;
for (const [key, rawValue] of Object.entries(value)) {
const name = optionalString(key)?.toLowerCase();
const text = optionalString(rawValue);
if (!name || !text) continue;
headers[name] = text;
}
return headers;
}
function delay(ms) {
return new Promise((resolve) => setTimeout(resolve, Math.max(0, Number(ms || 0))));
}
async function resolveRunAppGrants({ owner, context, ownerSettings }) {
const metadata = isPlainObject(ownerSettings?.metadata) ? ownerSettings.metadata : {};
const staticAppGrants = isPlainObject(metadata.appGrants) ? metadata.appGrants : {};
@ -1709,7 +2047,7 @@ function summarizeRunAppGrants(metadata) {
return out;
}
function buildRunProfilePolicyPrompt({ context, diagnostics }) {
function buildRunProfilePolicyPrompt({ context, diagnostics, assistantActions }) {
const lines = [
"AI Workspace dynamic run profile:",
`- source surface: ${diagnostics.sourceSurface}`,
@ -1719,6 +2057,11 @@ function buildRunProfilePolicyPrompt({ context, diagnostics }) {
`- entitlement source: ${diagnostics.entitlementAdapters?.source || "settings"}`,
`- enabled tool packs: ${diagnostics.enabledToolPacks.length ? diagnostics.enabledToolPacks.join(", ") : "none"}`,
`- MCP servers available in this run: ${diagnostics.mcpServerNames.length ? diagnostics.mcpServerNames.join(", ") : "none"}`,
`- assistant action ids available: ${Array.isArray(assistantActions?.actionIds) ? assistantActions.actionIds.join(", ") : "none"}`,
"- Interpret the user's natural-language request first; call assistant actions only after selecting a structured action id.",
"- Read assistant actions may execute after structured action selection. Privileged/write assistant actions require preview, explicit user confirmation, then execute.",
"- Ops card actions advertised in this run are valid assistant actions: use ops.card.list_recent for reading cards, ops.card.create for creating cards, and ops.card.add_comment for comments instead of refusing because direct Ops MCP tools are absent.",
"- Destructive assistant actions are forbidden; offer safe alternatives such as block/disable instead of delete.",
"- MCP tokens and headers are runtime secrets and must never be printed in public answers.",
];
const opsContext = isPlainObject(context?.contexts?.ops) ? context.contexts.ops : {};
@ -1754,19 +2097,29 @@ function runProfileHash(runProfile) {
function redactRunProfile(runProfile) {
if (!isPlainObject(runProfile)) return null;
const toolProfile = isPlainObject(runProfile.toolProfile) ? runProfile.toolProfile : {};
return {
...runProfile,
targetContexts: redactForPublicDiagnostics(runProfile.targetContexts),
appGrants: redactForPublicDiagnostics(runProfile.appGrants),
toolProfile: {
...(isPlainObject(runProfile.toolProfile) ? runProfile.toolProfile : {}),
mcpServers: Array.isArray(runProfile.toolProfile?.mcpServers)
? runProfile.toolProfile.mcpServers.map(redactMcpServer)
...toolProfile,
assistantActions: redactAssistantActions(toolProfile.assistantActions),
mcpServers: Array.isArray(toolProfile.mcpServers)
? toolProfile.mcpServers.map(redactMcpServer)
: [],
},
};
}
function redactAssistantActions(value) {
if (!isPlainObject(value)) return value;
return {
...value,
...(value.gatewayToken ? { gatewayToken: "<redacted>" } : {}),
};
}
function redactMcpServer(server) {
if (!isPlainObject(server)) return {};
const headers = isPlainObject(server.httpHeaders) ? server.httpHeaders : {};
@ -2520,12 +2873,62 @@ function sanitizeOwnerSettingsCommand(payload) {
return command;
}
function sanitizeRunProfileCommand(payload) {
const source = isPlainObject(payload) ? payload : {};
const context = isPlainObject(source.context) ? source.context : {};
const client = isPlainObject(source.client) ? source.client : {};
const selectedExecutorId = source.selectedExecutorId || source.selected_executor_id || null;
const toolPacks = mergeToolPacks(
source.enabledToolPacks,
source.enabled_tool_packs,
context.enabledToolPacks,
);
return {
selectedExecutorId: selectedExecutorId ? sanitizeUuid(selectedExecutorId, "selectedExecutorId") : null,
threadId: optionalString(source.threadId || source.thread_id),
threadTitle: optionalString(source.threadTitle || source.thread_title),
workspacePath: optionalString(source.workspacePath || source.workspace_path),
originSurface: sanitizeSurface(source.originSurface || source.origin_surface || context.sourceSurface || context.surface || client.surface || "engine"),
context,
client,
enabledToolPacks: toolPacks,
};
}
function sanitizeBridgeDispatchCommand(payload) {
const source = isPlainObject(payload) ? payload : {};
const command = sanitizeRunProfileCommand(source);
return {
...command,
message: optionalString(source.message || source.content),
displayMessage: optionalString(source.displayMessage || source.display_message),
publicUserMessage: optionalString(source.publicUserMessage || source.public_user_message),
resume: source.resume === true,
history: Array.isArray(source.history)
? source.history.slice(-40).map((item) => ({
role: optionalString(item?.role),
text: optionalString(item?.text || item?.content),
})).filter((item) => item.role && item.text)
: [],
};
}
function sanitizeThreadKind(value) {
const text = normalizeKey(value || "all");
if (text === "shared" || text === "remote" || text === "all") return text;
return "all";
}
function sanitizeBridgeStopCommand(payload) {
const source = isPlainObject(payload) ? payload : {};
return {
requestId: optionalString(source.requestId || source.request_id),
threadId: optionalString(source.threadId || source.thread_id),
reason: optionalString(source.reason) || "user_stop",
client: isPlainObject(source.client) ? source.client : {},
};
}
function sanitizeMessageCommand(payload) {
const source = isPlainObject(payload) ? payload : {};
return {
@ -2573,6 +2976,111 @@ function getRequestOwner(req) {
};
}
function sanitizeAssistantActionCommand(body, owner) {
const source = isPlainObject(body) ? body : {};
const phase = normalizeKey(source.phase || source.mode || "preview");
if (!["preview", "dry-run", "execute"].includes(phase)) {
throw badRequest("assistant_action_phase_invalid");
}
const sourceInput = isPlainObject(source.input) ? source.input : source;
const input = { ...sourceInput };
delete input.phase;
delete input.mode;
delete input.input;
const ownerContext = assistantOwnerContext(owner, sourceInput);
input.actorUserId = owner.userId || null;
input.actorEmail = owner.email || null;
input.actorSubject = owner.key;
input.groups = owner.groups;
input.launcherGlobalRole = ownerContext.launcherGlobalRole;
input.membershipRole = ownerContext.membershipRole;
input.membershipStatus = ownerContext.membershipStatus;
input.launcherUserStatus = ownerContext.launcherUserStatus;
input.assistantRole = ownerContext.assistantRole;
const confirmationToken = optionalString(source.confirmationToken || sourceInput.confirmationToken || source.confirmation?.token);
if (confirmationToken) input.confirmationToken = confirmationToken;
return { phase, input };
}
async function executeAssistantActionRequest(body, owner) {
const command = sanitizeAssistantActionCommand(body, owner);
let opsGatewayToken = "";
if (command.phase === "execute") {
const ownerSettings = await getOwnerSettings(owner);
const grantResolution = await resolveRunAppGrants({
owner,
context: isPlainObject(ownerSettings.activeContext) ? ownerSettings.activeContext : {},
ownerSettings,
});
opsGatewayToken = opsGatewayTokenFromAppGrants(ownerSettings, grantResolution.appGrants, config.opsGatewayBaseUrl);
}
const action = await handleAssistantCallerRequest(command, {
baseUrl: config.ontologyLauncherBaseUrl,
launcherInternalToken: config.launcherInternalAccessToken,
opsGatewayBaseUrl: config.opsGatewayBaseUrl,
opsGatewayToken,
opsEntitlementUrl: config.opsEntitlementUrl,
opsEntitlementAuthorization: config.opsEntitlementAuthorization,
defaultOpsWorkspaceSlug: config.defaultOpsWorkspaceSlug,
defaultOpsProjectId: config.defaultOpsProjectId,
});
return { ok: true, owner: publicOwner(owner), action: publicAssistantCallerResult(action) };
}
function urlOrigin(value) {
try {
return new URL(value).origin;
} catch {
return "";
}
}
function opsGatewayTokenFromAppGrants(ownerSettings, appGrants, opsGatewayBaseUrl) {
const servers = runProfileMcpServersFromAppGrants(ownerSettings, appGrants);
const targetOrigin = urlOrigin(opsGatewayBaseUrl);
const preferred = servers.find((server) => (
server.appId === "ops" &&
(!targetOrigin || urlOrigin(server.url) === targetOrigin)
)) || servers.find((server) => server.appId === "ops");
return bearerTokenFromHeaders(preferred?.httpHeaders);
}
function assistantOwnerContext(owner, sourceInput = {}) {
const groups = new Set(owner.groups || []);
const ownerRole = normalizeKey(owner.role);
const isRoot = ownerRole === "root-admin" || ownerRole === "root_admin" || groups.has("nodedc:superadmin") || groups.has("nodedc:launcher:admin");
const membershipRole = launcherMembershipRoleFromOwner(ownerRole, sourceInput);
const assistantRole = assistantRoleFromOwner({ isRoot, sourceInput });
return {
assistantRole,
launcherGlobalRole: isRoot ? "root_admin" : ownerRole.replace(/-/g, "_"),
membershipRole,
membershipStatus: optionalString(sourceInput.membershipStatus) || "active",
launcherUserStatus: optionalString(sourceInput.launcherUserStatus || sourceInput.globalStatus) || "active",
};
}
function assistantRoleFromOwner({ isRoot, sourceInput }) {
if (isRoot) return "admin";
const value = normalizeKey(sourceInput.assistantRole || sourceInput.coreAssistantRole);
if (value === "assistant-admin" || value === "admin") return "admin";
if (value === "assistant-blocked" || value === "blocked") return "blocked";
return "member";
}
function launcherMembershipRoleFromOwner(ownerRole, sourceInput = {}) {
const role = ownerRole.replace(/-/g, "_");
if (["client_owner", "client_admin", "member"].includes(role)) return role;
const sourceRole = normalizeKey(sourceInput.membershipRole).replace(/-/g, "_");
if (["client_owner", "client_admin", "member"].includes(sourceRole)) return sourceRole;
return "member";
}
function publicOwner(owner) {
return {
ownerKey: owner.key,
@ -2583,6 +3091,12 @@ function publicOwner(owner) {
};
}
function publicAssistantCallerResult(result) {
if (!isPlainObject(result)) return result;
const { raw: _raw, ...publicResult } = result;
return publicResult;
}
function publicOwnerSettings(settings) {
if (!settings || !isPlainObject(settings)) return settings;
return {
@ -2874,6 +3388,11 @@ function isTruthy(value) {
return text === "1" || text === "true" || text === "yes" || text === "on";
}
function isFalsy(value) {
const text = optionalString(value)?.toLowerCase() || "";
return text === "0" || text === "false" || text === "no" || text === "off";
}
function normalizeEmail(value) {
const text = optionalString(value);
return text ? text.toLowerCase() : null;
@ -3051,6 +3570,7 @@ function cleanHttpEndpoint(value) {
}
function readConfig() {
const nodedcEnv = normalizeKey(process.env.NODEDC_ENV || process.env.NDC_ENV || process.env.NODE_ENV || "");
const databaseUrl =
process.env.DATABASE_URL ||
process.env.AI_WORKSPACE_ASSISTANT_DATABASE_URL ||
@ -3070,8 +3590,44 @@ function readConfig() {
optionalString(process.env.NDC_AI_WORKSPACE_HUB_TOKEN) ||
"";
const sharedInternalAccessToken = optionalString(process.env.NODEDC_INTERNAL_ACCESS_TOKEN) || "";
const defaultOntologyLauncherBaseUrl =
process.env.NODE_ENV === 'production' ? 'http://launcher:5173' : 'http://launcher.local.nodedc'
const ontologyLauncherBaseUrl =
optionalString(process.env.NDC_ONTOLOGY_LAUNCHER_BASE_URL) ||
optionalString(process.env.NDC_LAUNCHER_BASE_URL) ||
optionalString(process.env.NDC_LAUNCHER_INTERNAL_URL) ||
optionalString(process.env.LAUNCHER_INTERNAL_URL) ||
optionalString(process.env.LAUNCHER_BASE_URL) ||
defaultOntologyLauncherBaseUrl;
const launcherInternalAccessToken =
optionalString(process.env.NDC_LAUNCHER_INTERNAL_ACCESS_TOKEN) ||
optionalString(process.env.LAUNCHER_INTERNAL_TOKEN) ||
sharedInternalAccessToken;
const assistantActionRelayId =
optionalString(process.env.AI_WORKSPACE_ASSISTANT_ACTION_RELAY_ID) ||
optionalString(process.env.NDC_AI_WORKSPACE_ASSISTANT_ACTION_RELAY_ID) ||
(nodedcEnv === "local" || nodedcEnv === "tunnel-local-e2e" ? "local-dev" : "");
const assistantActionRelayEnabledRaw = optionalString(
process.env.AI_WORKSPACE_ASSISTANT_ACTION_RELAY_ENABLED ||
process.env.NDC_AI_WORKSPACE_ASSISTANT_ACTION_RELAY_ENABLED
);
const assistantActionRelayDefaultEnabled = Boolean(
assistantActionRelayId &&
(nodedcEnv === "local" || nodedcEnv === "tunnel-local-e2e") &&
isDeployedPublicHubUrl(hubInternalHttpUrl)
);
const assistantActionRelayEnabled = assistantActionRelayEnabledRaw
? isTruthy(assistantActionRelayEnabledRaw) && !isFalsy(assistantActionRelayEnabledRaw)
: assistantActionRelayDefaultEnabled;
const entitlementAdapters = parseEntitlementAdapters();
const opsEntitlementAdapter = entitlementAdapters.find((adapter) => adapter.appId === "ops") || null;
const opsGatewayBaseUrl =
optionalString(process.env.AI_WORKSPACE_OPS_GATEWAY_BASE_URL) ||
optionalString(process.env.NDC_AI_WORKSPACE_OPS_GATEWAY_BASE_URL) ||
"";
return {
nodedcEnv,
port: Number(process.env.PORT || process.env.AI_WORKSPACE_ASSISTANT_PORT || "18082"),
databaseUrl,
databasePoolSize: Number(process.env.AI_WORKSPACE_ASSISTANT_DATABASE_POOL_SIZE || "10"),
@ -3079,6 +3635,21 @@ function readConfig() {
hubInternalHttpUrl: hubInternalHttpUrl.replace(/\/+$/, ""),
hubInternalAccessToken:
explicitHubAccessToken || (isDeployedPublicHubUrl(hubInternalHttpUrl) ? "" : sharedInternalAccessToken),
ontologyLauncherBaseUrl: ontologyLauncherBaseUrl.replace(/\/+$/, ""),
launcherInternalAccessToken,
opsGatewayBaseUrl: opsGatewayBaseUrl.replace(/\/+$/, ""),
opsEntitlementUrl: opsEntitlementAdapter?.url || "",
opsEntitlementAuthorization: opsEntitlementAdapter?.authorization || "",
defaultOpsWorkspaceSlug:
optionalString(process.env.AI_WORKSPACE_OPS_DEFAULT_WORKSPACE_SLUG) ||
optionalString(process.env.NDC_AI_WORKSPACE_OPS_DEFAULT_WORKSPACE_SLUG) ||
"",
defaultOpsProjectId:
optionalString(process.env.AI_WORKSPACE_OPS_DEFAULT_PROJECT_ID) ||
optionalString(process.env.NDC_AI_WORKSPACE_OPS_DEFAULT_PROJECT_ID) ||
"",
assistantActionRelayEnabled,
assistantActionRelayId,
hubFallbackWebSocketUrls: String(
process.env.AI_WORKSPACE_HUB_FALLBACK_URLS ||
process.env.NDC_AI_WORKSPACE_HUB_FALLBACK_URLS ||
@ -3092,11 +3663,12 @@ function readConfig() {
process.env.NODEDC_INTERNAL_ACCESS_TOKEN,
process.env.NODEDC_PLATFORM_SERVICE_TOKEN,
]),
entitlementAdapters: parseEntitlementAdapters(),
entitlementAdapters,
};
}
async function shutdown() {
assistantActionRelayStopping = true;
try {
httpServer.close();
await pool.end();

318
services/ai-workspace-assistant/src/templates/install-windows.ps1
View File

@ -879,6 +879,26 @@ function cleanRunKey(value, limit = 160) {
return String(value || '').trim().slice(0, limit)
}
function terminateProcessTree(child, signal = 'SIGTERM') {
if (!child) return
if (process.platform === 'win32' && child.pid) {
try {
const args = ['/PID', String(child.pid), '/T']
if (signal === 'SIGKILL') args.push('/F')
const killer = spawn('taskkill', args, {
windowsHide: true,
stdio: 'ignore',
shell: false,
})
killer.unref?.()
return
} catch {}
}
try {
child.kill(signal)
} catch {}
}
function registerActiveCodexRun(control = {}, child, onEvent = () => {}) {
const requestId = cleanRunKey(control.requestId, 120)
const threadId = cleanRunKey(control.threadId, 160)
@ -898,14 +918,10 @@ function registerActiveCodexRun(control = {}, child, onEvent = () => {}) {
try {
run.onEvent({ kind: 'stopped', message: 'Codex stop requested.' })
} catch {}
try {
run.child.kill('SIGTERM')
} catch {}
terminateProcessTree(run.child, 'SIGTERM')
run.stopTimer = setTimeout(() => {
if (run.closed) return
try {
run.child.kill('SIGKILL')
} catch {}
terminateProcessTree(run.child, 'SIGKILL')
}, CODEX_STOP_GRACE_MS)
return true
},
@ -1049,6 +1065,13 @@ async function readConversations() {
function buildPrompt(payload) {
const context = payload?.context && typeof payload.context === 'object' ? payload.context : {}
const runProfile = payload?.runProfile && typeof payload.runProfile === 'object' ? payload.runProfile : {}
const toolProfile = runProfile.toolProfile && typeof runProfile.toolProfile === 'object' ? runProfile.toolProfile : {}
const assistantActions = toolProfile.assistantActions && typeof toolProfile.assistantActions === 'object'
? toolProfile.assistantActions
: {}
const assistantActionIds = Array.isArray(assistantActions.actionIds)
? assistantActions.actionIds.map((item) => String(item || '').trim()).filter(Boolean)
: []
const runProfilePolicyPrompt = String(runProfile.policyPrompt || '').trim()
const userMessage = String(payload?.message || '').trim()
const history = payload?.resume ? [] : normalizeHistory(payload?.history || [])
@ -1116,7 +1139,7 @@ function buildPrompt(payload) {
`- Selected agentNodeId: ${context.agentNodeId || 'unknown'}`,
'- Read the second-level graph with GET /subworkflow?workflowId=<workflowId>&nodeId=<agentNodeId>.',
'- Apply graph edits with POST /subworkflow/patch using JSON: { workflowId, nodeId, intent, operations }.',
'- Prefer the MCP tools exposed by the ndc_agent_core server: ndc_get_context, ndc_get_subworkflow, ndc_search_nodes, ndc_get_node_definition, ndc_apply_subworkflow_patch, ndc_validate_subworkflow.',
'- Prefer the MCP tools exposed by the ndc_agent_core server: ndc_get_context, ndc_get_subworkflow, ndc_search_nodes, ndc_get_node_definition, ndc_apply_subworkflow_patch, ndc_validate_subworkflow, assistant_action_call.',
'- Do not use direct NDC core runtime MCP servers, local workflow files, or shell probes for graph edits in this mode.',
'- Use only ndc_agent_core MCP tools for the selected second-level workflow and stop after a cancellation, fetch, or policy error with the exact tool name and error.',
'- In public answers, use only NDC labels: NDC workflow, NDC node, NDC node type, NDC nodebase, and NDC Agent Core.',
@ -1125,6 +1148,15 @@ function buildPrompt(payload) {
'- Prefer small patches and preserve existing node ids, node names, positions, parameters, and connections unless the user asks to change them.',
'- After saving through the Engine API, the open Engine canvas refreshes from dc.subworkflow.json; never edit local files or use shell fallbacks for graph changes in this mode.',
],
'',
'Assistant action routing contract:',
`- Assistant action ids available in this run: ${assistantActionIds.length ? assistantActionIds.join(', ') : 'none'}.`,
'- For Launcher/HUB/admin/access/users/invites/roles/service grants requests, use only the ndc_agent_core MCP tool assistant_action_call.',
'- Do not use codex_apps readonly connectors, read_handoff, local files, shell search, logs, or workspace scans for Launcher/HUB live administrative data.',
'- Use phase="execute" for read-only action calls after selecting the structured action id.',
'- Use phase="preview" before any privileged/write action, ask for explicit confirmation, then use phase="execute" only after confirmation.',
'- Useful read action ids when advertised: hub.access_request.list_pending, hub.invite.list_pending, hub.user.read_admin_summary.',
'- If assistant_action_call is unavailable or the gateway returns an error, report that exact tool/error and stop; do not guess from local files.',
] : [],
...(isOpsMode || opsContext.opsWorkspaceSlug || opsContext.opsProjectId ? [
'',
@ -1134,8 +1166,12 @@ function buildPrompt(payload) {
`- Selected Ops project id: ${opsContext.opsProjectId || 'unknown'}`,
`- Selected Ops project identifier: ${opsContext.opsProjectIdentifier || 'unknown'}`,
'- Prefer the MCP tools exposed for NODE.DC Ops when creating, updating, moving, or reading tasks.',
'- If assistant action ids include ops.card.list_recent, ops.card.create, or ops.card.add_comment, these are the canonical Ops card actions for this run.',
'- Use assistant_action_call phase="execute" for Ops card reads after selecting ops.card.list_recent.',
'- Use assistant_action_call phase="preview" before Ops card create/comment writes, ask for explicit confirmation, then call phase="execute" with the returned confirmation token.',
'- Before writing Ops tasks, use the Ops MCP project/context tools when available and include a unique idempotency key for write tools.',
'- If Ops MCP tools are unavailable in the Codex session, say that the Ops context is selected but the Ops MCP tools are unavailable.',
'- If direct Ops MCP tools are unavailable but the Ops assistant action ids are advertised, do not refuse; route through assistant_action_call.',
'- If neither direct Ops MCP tools nor Ops assistant action ids are available, say that the Ops context is selected but live Ops tools are unavailable.',
'- Do not claim that an Engine workflow or Engine agent node is required for Ops task writes.',
'- If the current request is about Ops tasks and Ops workspace/project are selected, treat that as the writable Ops target.',
'- In public answers, use NODE.DC/Ops labels and never expose internal vendor names.',
@ -1480,6 +1516,11 @@ function insertBeforePromptStdin(args, extras) {
function buildNdcAgentMcpContext(payload, cwd) {
const context = payload?.context && typeof payload.context === 'object' ? payload.context : {}
const runProfile = payload?.runProfile && typeof payload.runProfile === 'object' ? payload.runProfile : {}
const toolProfile = runProfile.toolProfile && typeof runProfile.toolProfile === 'object' ? runProfile.toolProfile : {}
const assistantActions = toolProfile.assistantActions && typeof toolProfile.assistantActions === 'object'
? toolProfile.assistantActions
: {}
const apiBaseUrl = deriveNdcAgentMcpApiBaseUrl(context)
return {
workflowId: String(context.workflowId || '').trim(),
@ -1492,6 +1533,14 @@ function buildNdcAgentMcpContext(payload, cwd) {
schemaVersion: 'v2.3.2',
n8nMcpRefPath: NDC_AGENT_MCP_REF_PATH,
workspacePath: cwd,
assistantActions: {
actionIds: Array.isArray(assistantActions.actionIds)
? assistantActions.actionIds.map((item) => String(item || '').trim()).filter(Boolean)
: [],
},
assistantActionOwner: runProfile.owner && typeof runProfile.owner === 'object' ? runProfile.owner : {},
assistantActionGatewayUrl: String(assistantActions.gatewayUrl || '').trim(),
assistantActionGatewayToken: String(assistantActions.gatewayToken || '').trim(),
}
}
@ -1502,6 +1551,7 @@ function deriveNdcAgentMcpApiBaseUrl(context) {
if (!isHttpUrl(explicit)) return hubDerived || DEFAULT_NDC_AGENT_MCP_API_BASE
if (hubDerived && isProtectedNodedcEngineUrl(explicit)) return hubDerived
if (isLoopbackUrl(explicit) && hubDerived) return hubDerived
if (isPrivateNetworkUrl(explicit) && hubDerived) return hubDerived
if (!explicit.endsWith('/api/ndc-agent-mcp')) return `${explicit.replace(/\/+$/, '')}/api/ndc-agent-mcp`
return explicit
}
@ -1521,6 +1571,21 @@ function isLoopbackUrl(value) {
}
}
function isPrivateNetworkUrl(value) {
try {
const url = new URL(value)
const host = url.hostname.toLowerCase()
if (host === 'localhost' || host === '0.0.0.0' || host === '::1' || host.startsWith('127.')) return true
if (host.startsWith('192.168.')) return true
if (host.startsWith('10.')) return true
if (host.startsWith('169.254.')) return true
const match = host.match(/^172\.(\d+)\./)
return Boolean(match && Number(match[1]) >= 16 && Number(match[1]) <= 31)
} catch {
return false
}
}
function isHttpUrl(value) {
try {
const url = new URL(value)
@ -1854,7 +1919,7 @@ async function prepareRunCodexHome({ payload = {}, cwd = CODEX_CWD, mcpContext =
: NDC_AGENT_CODEX_HOME
await fs.mkdir(codexHome, { recursive: true })
await copyIfExists(path.join(CODEX_HOME, 'auth.json'), path.join(codexHome, 'auth.json'))
const legacyOpsMcpConfig = needsNdcAgentCore && !hasDynamicMcp ? await readOptionalOpsMcpConfig() : ''
const legacyOpsMcpConfig = ''
const config = [
runtimeCodexConfig(),
needsNdcAgentCore ? ndcAgentMcpServerConfig(mcpContext, cwd) : '',
@ -1878,6 +1943,8 @@ async function codexInvocationForPayload(baseArgs, payload, cwd) {
NDC_AGENT_MCP_ROOT: CODEX_CWD,
NDC_AGENT_MCP_CONTEXT: JSON.stringify(mcpContext),
NDC_AGENT_MCP_API_BASE_URL: mcpContext.ndcAgentMcpApiBaseUrl,
NDC_AGENT_MCP_FETCH_TIMEOUT_MS: process.env.NDC_AGENT_MCP_FETCH_TIMEOUT_MS || '30000',
AI_WORKSPACE_ASSISTANT_ACTION_FETCH_TIMEOUT_MS: process.env.AI_WORKSPACE_ASSISTANT_ACTION_FETCH_TIMEOUT_MS || '45000',
AI_BRIDGE_PAIRING_CODE: PAIRING_CODE,
} : {}),
},
@ -2399,7 +2466,7 @@ function runCodex(prompt, args = CODEX_ARGS, onEvent = () => {}, timeoutMs = MES
const timeout = setTimeout(() => {
killed = true
onEvent({ kind: 'timeout', message: 'Codex process timed out.' })
child.kill('SIGTERM')
terminateProcessTree(child, 'SIGTERM')
}, timeoutMs)
child.stdout.on('data', (chunk) => {
@ -2431,7 +2498,7 @@ function runCodex(prompt, args = CODEX_ARGS, onEvent = () => {}, timeoutMs = MES
plainStdout += text
onEvent({ kind: 'stdout', stream: 'stdout', text })
}
if (Buffer.byteLength(stdout) > MAX_STDIO_BYTES) child.kill('SIGTERM')
if (Buffer.byteLength(stdout) > MAX_STDIO_BYTES) terminateProcessTree(child, 'SIGTERM')
})
child.stderr.on('data', (chunk) => {
const text = String(chunk)
@ -2441,7 +2508,7 @@ function runCodex(prompt, args = CODEX_ARGS, onEvent = () => {}, timeoutMs = MES
}
stderr += text
onEvent({ kind: 'stderr', stream: 'stderr', text: sanitizeCodexErrorText(text) })
if (Buffer.byteLength(stderr) > MAX_STDIO_BYTES) child.kill('SIGTERM')
if (Buffer.byteLength(stderr) > MAX_STDIO_BYTES) terminateProcessTree(child, 'SIGTERM')
})
child.on('error', (error) => {
clearTimeout(timeout)
@ -2927,6 +2994,8 @@ const ROOT = process.env.NDC_AGENT_MCP_ROOT || process.cwd()
const DEFAULT_API_BASE = 'http://127.0.0.1:3001/api/ndc-agent-mcp'
const DEFAULT_SCHEMA_VERSION = 'v2.3.2'
const ENGINE_FETCH_TIMEOUT_MS = Number(process.env.NDC_AGENT_MCP_FETCH_TIMEOUT_MS || 8000)
const DEFAULT_ASSISTANT_ACTION_GATEWAY_PATH = '/api/ai-workspace/assistant/v1/actions'
const ASSISTANT_ACTION_FETCH_TIMEOUT_MS = Number(process.env.AI_WORKSPACE_ASSISTANT_ACTION_FETCH_TIMEOUT_MS || ENGINE_FETCH_TIMEOUT_MS)
const context = parseContext()
const nodeCatalogCache = new Map()
let transportMode = null
@ -3025,8 +3094,13 @@ function parseContext() {
if (raw) {
try { parsed = JSON.parse(raw) || {} } catch {}
}
const assistantActions = parseObject(
parsed.assistantActions ||
process.env.AI_WORKSPACE_ASSISTANT_ACTIONS ||
{},
)
return {
modeId: 'ndc-agent-core',
modeId: cleanString(parsed.modeId || 'ndc-agent-core'),
workflowId: cleanString(parsed.workflowId || process.env.NDC_AGENT_MCP_WORKFLOW_ID || ''),
workflowTitle: cleanString(parsed.workflowTitle || process.env.NDC_AGENT_MCP_WORKFLOW_TITLE || ''),
agentNodeId: cleanString(parsed.agentNodeId || process.env.NDC_AGENT_MCP_NODE_ID || ''),
@ -3036,6 +3110,20 @@ function parseContext() {
apiBaseUrl: cleanApiBase(parsed.ndcAgentMcpApiBaseUrl || process.env.NDC_AGENT_MCP_API_BASE_URL || DEFAULT_API_BASE),
schemaVersion: cleanString(parsed.schemaVersion || process.env.NDC_AGENT_MCP_SCHEMA_VERSION || DEFAULT_SCHEMA_VERSION),
n8nMcpRefPath: cleanString(parsed.n8nMcpRefPath || process.env.NDC_AGENT_MCP_REF_PATH || path.resolve(ROOT, '..', 'tools', 'NDCMCP')),
assistantActions,
assistantActionOwner: parseObject(parsed.assistantActionOwner || {}),
assistantActionGatewayUrl: cleanHttpUrl(
parsed.assistantActionGatewayUrl ||
process.env.AI_WORKSPACE_ASSISTANT_ACTION_GATEWAY_URL ||
deriveAssistantActionGatewayUrlFromHub() ||
'',
),
assistantActionGatewayToken: cleanString(
parsed.assistantActionGatewayToken ||
process.env.AI_WORKSPACE_ASSISTANT_ACTION_GATEWAY_TOKEN ||
'',
4000,
),
}
}
@ -3043,6 +3131,32 @@ function cleanString(value, max = 1000) {
return String(value || '').trim().slice(0, max)
}
function parseObject(value, fallback = {}) {
if (value && typeof value === 'object' && !Array.isArray(value)) return value
const text = String(value || '').trim()
if (!text) return fallback
try {
const parsed = JSON.parse(text)
return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : fallback
} catch {
return fallback
}
}
function cleanHttpUrl(value) {
const text = cleanString(value, 2000).replace(/\/+$/, '')
if (!text) return ''
try {
const url = new URL(text)
if (url.protocol !== 'http:' && url.protocol !== 'https:') return ''
url.username = ''
url.password = ''
return url.toString().replace(/\/+$/, '')
} catch {
return ''
}
}
function cleanApiBase(value) {
const raw = cleanString(value || DEFAULT_API_BASE)
return raw.replace(/\/+$/, '') || DEFAULT_API_BASE
@ -3069,6 +3183,20 @@ function isLoopbackUrl(value) {
}
}
function isPrivateNetworkUrl(value) {
try {
const host = new URL(value).hostname.toLowerCase()
if (host === 'localhost' || host === '0.0.0.0' || host === '::1' || host.startsWith('127.')) return true
if (host.startsWith('192.168.')) return true
if (host.startsWith('10.')) return true
if (host.startsWith('169.254.')) return true
const match = host.match(/^172\.(\d+)\./)
return Boolean(match && Number(match[1]) >= 16 && Number(match[1]) <= 31)
} catch {
return false
}
}
function hubOriginToApiBase(value) {
try {
const url = new URL(cleanString(value, 1000))
@ -3091,6 +3219,32 @@ function hubOriginToApiBase(value) {
}
}
function hubOriginToAssistantActionGateway(value) {
try {
const url = new URL(cleanString(value, 1000))
const host = url.hostname.toLowerCase()
if (!host) return ''
if (url.protocol === 'wss:') url.protocol = 'https:'
else if (url.protocol === 'ws:') url.protocol = 'http:'
else if (url.protocol !== 'http:' && url.protocol !== 'https:') return ''
url.pathname = ''
url.search = ''
url.hash = ''
const origin = url.toString().replace(/\/+$/, '')
return `${origin}${DEFAULT_ASSISTANT_ACTION_GATEWAY_PATH}`
} catch {
return ''
}
}
function deriveAssistantActionGatewayUrlFromHub() {
const candidates = [
hubOriginToAssistantActionGateway(process.env.AI_BRIDGE_HUB_URL),
...splitList(process.env.AI_BRIDGE_HUB_URLS).map(hubOriginToAssistantActionGateway),
].filter(Boolean)
return uniqueStrings(candidates)[0] || ''
}
function cleanPairingCode(value) {
return cleanString(value, 100).toUpperCase().replace(/[^A-Z0-9]/g, '').slice(0, 32)
}
@ -3106,10 +3260,10 @@ function engineApiBaseCandidates() {
...splitList(process.env.AI_BRIDGE_HUB_URLS).map(hubOriginToApiBase),
]
const envBase = cleanString(process.env.NDC_AGENT_MCP_API_BASE_URL, 1000).replace(/\/+$/, '')
if (explicit && !isLoopbackUrl(explicit)) {
if (explicit && !isPrivateNetworkUrl(explicit)) {
return uniqueStrings([explicit, envBase])
}
if (envBase && !isLoopbackUrl(envBase)) {
if (envBase && !isPrivateNetworkUrl(envBase)) {
return uniqueStrings([envBase, explicit])
}
if (hubBases.some(Boolean)) {
@ -3191,6 +3345,88 @@ async function loadN8nMcpVersion() {
return pkg?.version ? String(pkg.version) : '2.33.2'
}
function assistantActionGatewayEndpoint() {
const base = cleanHttpUrl(context.assistantActionGatewayUrl)
if (!base) return ''
if (base.endsWith(DEFAULT_ASSISTANT_ACTION_GATEWAY_PATH) || base.endsWith('/actions')) return base
return `${base}${DEFAULT_ASSISTANT_ACTION_GATEWAY_PATH}`
}
function assistantActionIds() {
return Array.isArray(context.assistantActions?.actionIds)
? context.assistantActions.actionIds.map((item) => cleanString(item, 200)).filter(Boolean)
: []
}
function assistantActionOwnerHeaders() {
const owner = parseObject(context.assistantActionOwner, {})
const headers = {}
const put = (name, value) => {
const text = cleanString(value, 1000)
if (text) headers[name] = text
}
put('x-nodedc-user-id', owner.userId || owner.user_id)
put('x-nodedc-user-email', owner.email)
put('x-nodedc-user-role', owner.role)
const groups = Array.isArray(owner.groups)
? owner.groups.map((item) => cleanString(item, 120)).filter(Boolean).join(',')
: owner.groups
put('x-nodedc-user-groups', groups)
return headers
}
async function assistantActionFetch(payload = {}) {
const endpoint = assistantActionGatewayEndpoint()
const token = context.assistantActionGatewayToken
if (!endpoint || !token) {
return {
ok: false,
decision: 'assistant_action_gateway_unavailable',
reason: 'Assistant action gateway URL/token is not configured for this run.',
actionIds: assistantActionIds(),
}
}
let res = null
let text = ''
let json = null
try {
res = await fetch(endpoint, {
method: 'POST',
headers: {
Accept: 'application/json',
'Content-Type': 'application/json',
Authorization: `Bearer ${token}`,
...assistantActionOwnerHeaders(),
},
body: JSON.stringify(payload),
signal: AbortSignal.timeout(ASSISTANT_ACTION_FETCH_TIMEOUT_MS),
})
text = await res.text().catch(() => '')
try { json = text ? JSON.parse(text) : null } catch {}
} catch (error) {
const out = new Error(`assistant_action_gateway_fetch_failed:${fetchFailureText(error)}`)
out.payload = { decision: 'assistant_action_gateway_fetch_failed' }
throw out
}
if (!res.ok || json?.ok === false) {
const out = new Error(json?.message || json?.error || `assistant_action_http_${res.status}`)
out.status = res.status
out.payload = json && typeof json === 'object'
? json
: { status: res.status, preview: cleanString(text, 400) }
throw out
}
if (!json || typeof json !== 'object') {
const out = new Error(`assistant_action_non_json_response:${res.status}`)
out.status = 502
out.payload = { status: res.status, preview: cleanString(text, 400) }
throw out
}
return json
}
function engineApiUrl(pathname) {
return engineApiUrls(pathname)[0] || ''
}
@ -3365,6 +3601,7 @@ async function handleGetContext() {
...context,
apiBaseCandidates: engineApiBaseCandidates(),
n8nMcpVersion,
assistantActionGatewayConfigured: Boolean(context.assistantActionGatewayUrl && context.assistantActionGatewayToken),
contract: {
sourceOfTruth: 'Engine second-level dc.subworkflow.json',
writeApi: `${context.apiBaseUrl}/subworkflow/patch`,
@ -3375,6 +3612,40 @@ async function handleGetContext() {
}
}
async function handleAssistantActionCall(args = {}) {
const phase = cleanString(args.phase || args.mode || 'preview', 40)
if (!['preview', 'dry-run', 'execute'].includes(phase)) throw new Error('assistant_action_phase_invalid')
const input = parseObject(args.input || {}, {})
const actionId = cleanString(args.actionId || input.actionId || '', 240)
const intent = cleanString(args.intent || input.intent || '', 2000)
if (actionId) input.actionId = actionId
if (intent) input.intent = intent
const availableIds = assistantActionIds()
if (actionId && availableIds.length && !availableIds.includes(actionId)) {
throw new Error(`assistant_action_not_advertised:${actionId}`)
}
if (!actionId && !intent) {
throw new Error('assistant_action_input_required')
}
const confirmationToken = cleanString(
args.confirmationToken ||
args.confirmation?.token ||
input.confirmationToken ||
'',
2000,
)
if (confirmationToken) input.confirmationToken = confirmationToken
return assistantActionFetch({
phase,
input,
...(confirmationToken ? { confirmationToken } : {}),
})
}
async function handleGetSubworkflow(args) {
const target = targetFromArgs(args)
const q = new URLSearchParams(target)
@ -3571,6 +3842,22 @@ const tools = [
additionalProperties: false,
},
},
{
name: 'assistant_action_call',
description: 'Call the NODE.DC assistant action layer after interpreting user intent. Use execute for read actions after structured action selection; use preview before any privileged/write action and execute only after explicit confirmation.',
inputSchema: {
type: 'object',
properties: {
phase: { type: 'string', enum: ['preview', 'dry-run', 'execute'] },
actionId: { type: 'string' },
intent: { type: 'string' },
input: { type: 'object', additionalProperties: true },
confirmationToken: { type: 'string' },
confirmation: { type: 'object', additionalProperties: true },
},
additionalProperties: false,
},
},
]
async function callTool(name, args) {
@ -3580,6 +3867,7 @@ async function callTool(name, args) {
if (name === 'ndc_search_nodes') return handleSearchNodes(args)
if (name === 'ndc_get_node_definition') return handleGetNodeDefinition(args)
if (name === 'ndc_validate_subworkflow') return handleValidateSubworkflow(args)
if (name === 'assistant_action_call') return handleAssistantActionCall(args)
throw new Error(`unknown_tool:${name}`)
}

199
services/ai-workspace-hub/src/server.mjs
View File

@ -8,12 +8,17 @@ const MAX_EVENTS_PER_AGENT = 5000;
const MAX_REQUEST_META_PER_AGENT = 1000;
const HEARTBEAT_INTERVAL_MS = 30000;
const AGENT_STALE_MS = 75000;
const ASSISTANT_RELAY_POLL_TIMEOUT_MS = Number(process.env.AI_WORKSPACE_ASSISTANT_RELAY_POLL_TIMEOUT_MS || 25000);
const ASSISTANT_RELAY_ACTION_TIMEOUT_MS = Number(process.env.AI_WORKSPACE_ASSISTANT_RELAY_ACTION_TIMEOUT_MS || 45000);
const ASSISTANT_RELAY_MAX_PENDING = Number(process.env.AI_WORKSPACE_ASSISTANT_RELAY_MAX_PENDING || 200);
const ASSISTANT_RELAY_MAX_BATCH = Number(process.env.AI_WORKSPACE_ASSISTANT_RELAY_MAX_BATCH || 10);
const config = readConfig();
const app = express();
const httpServer = createServer(app);
const wss = new WebSocketServer({ noServer: true });
const agentsByCode = new Map();
const assistantRelaysById = new Map();
let eventSeq = 0;
app.disable("x-powered-by");
@ -25,6 +30,7 @@ app.get("/healthz", (_req, res) => {
service: "nodedc-ai-workspace-hub",
wsPath: config.wsPath,
agentsOnline: Array.from(agentsByCode.values()).filter(isAgentOnline).length,
assistantRelays: assistantRelaysById.size,
internalApiConfigured: config.internalAccessTokens.length > 0,
});
});
@ -60,6 +66,12 @@ app.post("/api/ai-workspace/hub/v1/agents/:pairingCode/dispatch", requireInterna
res.json({ ok: true, requestId: dispatch.requestId });
});
app.post("/api/ai-workspace/assistant/v1/actions", requireInternalApi, asyncRoute(proxyAssistantActions));
app.post("/api/ai-workspace/hub/v1/assistant-relays/:relayId/actions", requireInternalApi, asyncRoute(callAssistantRelayAction));
app.post("/api/ai-workspace/hub/v1/assistant-relays/:relayId/poll", requireInternalApi, asyncRoute(pollAssistantRelay));
app.post("/api/ai-workspace/hub/v1/assistant-relays/:relayId/results/:callId", requireInternalApi, asyncRoute(completeAssistantRelayCall));
app.use("/api/ai-workspace/hub/v1/ndc-agent-mcp/:pairingCode", asyncRoute(proxyNdcAgentMcp));
app.use((error, _req, res, _next) => {
@ -256,6 +268,179 @@ async function proxyNdcAgentMcp(req, res) {
res.send(text);
}
async function proxyAssistantActions(req, res) {
if (!config.assistantInternalUrl || !config.assistantInternalAccessToken) {
res.status(503).json({ ok: false, error: "assistant_action_proxy_not_configured" });
return;
}
const targetUrl = `${config.assistantInternalUrl.replace(/\/+$/, "")}/api/ai-workspace/assistant/v1/actions`;
const upstream = await fetch(targetUrl, {
method: "POST",
redirect: "manual",
headers: {
Accept: "application/json",
"Content-Type": "application/json",
Authorization: `Bearer ${config.assistantInternalAccessToken}`,
...forwardOwnerHeaders(req),
},
body: JSON.stringify(req.body || {}),
});
const contentType = upstream.headers.get("content-type") || "application/json; charset=utf-8";
const text = await upstream.text();
res.status(upstream.status);
res.setHeader("content-type", contentType);
res.send(text);
}
async function callAssistantRelayAction(req, res) {
const relayId = cleanRelayId(req.params.relayId);
if (!relayId) {
res.status(400).json({ ok: false, error: "assistant_relay_id_required" });
return;
}
const relay = getAssistantRelay(relayId);
pruneAssistantRelay(relay);
if (relay.calls.size >= ASSISTANT_RELAY_MAX_PENDING) {
res.status(429).json({ ok: false, error: "assistant_relay_backpressure" });
return;
}
const callId = crypto.randomUUID();
const timeoutMs = sanitizeTimeoutMs(req.body?.timeoutMs || req.query?.timeoutMs || ASSISTANT_RELAY_ACTION_TIMEOUT_MS, ASSISTANT_RELAY_ACTION_TIMEOUT_MS);
const createdAt = new Date().toISOString();
const call = {
callId,
relayId,
createdAt,
payload: req.body || {},
headers: forwardOwnerHeaders(req),
};
const result = await new Promise((resolve, reject) => {
const timeout = setTimeout(() => {
relay.calls.delete(callId);
relay.pending = relay.pending.filter((item) => item.callId !== callId);
const error = new Error("assistant_relay_timeout");
error.status = 504;
reject(error);
}, timeoutMs);
timeout.unref?.();
relay.calls.set(callId, { resolve, reject, timeout, createdAt: Date.now() });
relay.pending.push(call);
notifyAssistantRelayWaiters(relay);
});
res.status(result.status).json(result.body);
}
async function pollAssistantRelay(req, res) {
const relayId = cleanRelayId(req.params.relayId);
if (!relayId) {
res.status(400).json({ ok: false, error: "assistant_relay_id_required" });
return;
}
const relay = getAssistantRelay(relayId);
relay.lastSeenAt = new Date().toISOString();
const limit = sanitizeInteger(req.body?.limit, ASSISTANT_RELAY_MAX_BATCH, 1, ASSISTANT_RELAY_MAX_BATCH);
const timeoutMs = sanitizeTimeoutMs(req.body?.timeoutMs || req.query?.timeoutMs || ASSISTANT_RELAY_POLL_TIMEOUT_MS, ASSISTANT_RELAY_POLL_TIMEOUT_MS);
const calls = await waitForAssistantRelayCalls(relay, limit, timeoutMs);
res.json({ ok: true, relayId, calls });
}
async function completeAssistantRelayCall(req, res) {
const relayId = cleanRelayId(req.params.relayId);
const callId = cleanString(req.params.callId, 120);
const relay = assistantRelaysById.get(relayId);
const pending = relay?.calls.get(callId);
if (!relay || !pending) {
res.status(404).json({ ok: false, error: "assistant_relay_call_not_found" });
return;
}
relay.calls.delete(callId);
clearTimeout(pending.timeout);
pending.resolve({
status: sanitizeHttpStatus(req.body?.status),
body: req.body?.body === undefined ? { ok: true } : req.body.body,
});
res.json({ ok: true, relayId, callId });
}
function getAssistantRelay(relayId) {
const cleanId = cleanRelayId(relayId);
let relay = assistantRelaysById.get(cleanId);
if (!relay) {
relay = {
relayId: cleanId,
pending: [],
waiters: [],
calls: new Map(),
createdAt: new Date().toISOString(),
lastSeenAt: "",
};
assistantRelaysById.set(cleanId, relay);
}
return relay;
}
function waitForAssistantRelayCalls(relay, limit, timeoutMs) {
const ready = takeAssistantRelayCalls(relay, limit);
if (ready.length) return Promise.resolve(ready);
return new Promise((resolve) => {
const timeout = setTimeout(() => {
relay.waiters = relay.waiters.filter((waiter) => waiter.resolve !== resolve);
resolve([]);
}, timeoutMs);
timeout.unref?.();
relay.waiters.push({ resolve, timeout, limit });
});
}
function notifyAssistantRelayWaiters(relay) {
while (relay.waiters.length && relay.pending.length) {
const waiter = relay.waiters.shift();
clearTimeout(waiter.timeout);
waiter.resolve(takeAssistantRelayCalls(relay, waiter.limit));
}
}
function takeAssistantRelayCalls(relay, limit) {
const calls = [];
while (relay.pending.length && calls.length < limit) {
const call = relay.pending.shift();
if (relay.calls.has(call.callId)) calls.push(call);
}
return calls;
}
function pruneAssistantRelay(relay) {
relay.pending = relay.pending.filter((call) => relay.calls.has(call.callId));
}
function cleanRelayId(value) {
return String(value || "").trim().replace(/[^A-Za-z0-9_.:-]/g, "").slice(0, 120);
}
function sanitizeHttpStatus(value) {
const status = Number(value || 200);
return Number.isInteger(status) && status >= 100 && status <= 599 ? status : 200;
}
function forwardOwnerHeaders(req) {
const headers = {};
for (const name of [
"x-nodedc-user-id",
"x-nodedc-user-email",
"x-nodedc-user-role",
"x-nodedc-user-groups",
]) {
const value = req.headers[name];
if (typeof value === "string" && value.trim()) headers[name] = value.trim();
}
return headers;
}
function startAgentRequest(pairingCodeRaw, command, payload = {}, timeoutMs = 30000, options = {}) {
const pairingCode = cleanPairingCode(pairingCodeRaw);
const agent = agentsByCode.get(pairingCode);
@ -432,6 +617,12 @@ function sanitizeTimeoutMs(value, fallback) {
return Math.max(1000, Math.min(12 * 60 * 60 * 1000, numeric));
}
function sanitizeInteger(value, fallback, min, max) {
const numeric = Number(value || fallback);
if (!Number.isFinite(numeric)) return fallback;
return Math.min(Math.max(Math.trunc(numeric), min), max);
}
function elapsedLabel(startedAt) {
const elapsed = Math.max(0, Date.now() - Number(startedAt || Date.now()));
if (elapsed < 1000) return `${elapsed}ms`;
@ -473,6 +664,14 @@ function readConfig() {
internalAccessTokens,
engineInternalUrl: cleanString(process.env.NODEDC_ENGINE_INTERNAL_URL, 1000).replace(/\/+$/, ""),
engineInternalAccessToken: cleanString(process.env.NODEDC_INTERNAL_ACCESS_TOKEN, 1000),
assistantInternalUrl: cleanString(
process.env.NODEDC_AI_WORKSPACE_ASSISTANT_URL ||
process.env.NDC_AI_WORKSPACE_ASSISTANT_INTERNAL_URL ||
process.env.AI_WORKSPACE_ASSISTANT_INTERNAL_URL ||
"http://ai-workspace-assistant:18082",
1000,
).replace(/\/+$/, ""),
assistantInternalAccessToken: cleanString(process.env.NODEDC_INTERNAL_ACCESS_TOKEN, 1000),
};
}

165
services/ontology-core/README.md Normal file
View File

@ -0,0 +1,165 @@
# NODE.DC Ontology Core
Docs-first ontology service/module for NODE.DC.
Current status: `v0.4-pre` implementation slice.
This module owns:
- canonical entity catalog;
- relation catalog;
- alias registry;
- guardrails;
- evidence index;
- first context resolver rules for OPS -> ENGINE and ENGINE -> OPS.
- assistant access policy for NDC Core Assistant permissions.
- assistant action registry and risk policy for safe assistant-mediated operations.
It does not own:
- HUB users/clients/app access source data;
- OPS cards/projects source data;
- ENGINE workflows/runtime source data;
- OPS Gateway grants/tokens/scopes enforcement;
- runtime data, logs, dumps, storage, env, or secrets.
## Layout
```text
catalog/entities.json
catalog/relations.json
catalog/aliases.json
catalog/guardrails.json
catalog/evidence.json
catalog/resolver-rules.json
catalog/context-bindings.json
catalog/assistant-access-policy.json
catalog/assistant-actions.json
catalog/assistant-risk-policy.json
examples/*.json
docs/baseline/*.md
docs/CONTEXT_BINDINGS.md
docs/ASSISTANT_ACCESS_POLICY.md
docs/ASSISTANT_ACTION_REGISTRY.md
docs/ASSISTANT_CALLER_CONTRACT.md
docs/ASSISTANT_EXECUTION_GATEWAY.md
src/catalog.mjs
src/registry.mjs
src/validate.mjs
src/resolver.mjs
src/assistant-policy.mjs
src/assistant-action-resolver.mjs
src/assistant-action-plan.mjs
src/assistant-action-caller.mjs
src/assistant-action-executor.mjs
src/adapters/hub-launcher-admin.mjs
```
## Validate
```text
npm run validate
```
## Resolver Smoke
```text
npm run smoke:resolver
```
## Assistant Policy Smoke
```text
npm run smoke:assistant-policy
```
Resolve one assistant access input:
```text
npm run assistant:policy -- --input-json examples/assistant-access-admin-client.example.json
```
## Assistant Action Smoke
```text
npm run smoke:assistant-actions
npm run smoke:assistant-action-plan
npm run smoke:assistant-caller
npm run smoke:assistant-executor
```
Resolve one assistant action request:
```text
npm run assistant:action -- --input-json examples/assistant-action-block-user.example.json
npm run assistant:plan -- --input-json examples/assistant-action-block-user.example.json
npm run assistant:caller -- --input-json examples/assistant-caller-preview-block-user.example.json
npm run assistant:execute -- --input-json examples/assistant-action-block-user.example.json
```
The action resolver returns a policy decision such as `forbidden`, `denied`, `needs_confirmation`, `future_adapter`, or `allowed`.
The action planner returns a dry-run app-owned adapter request plan. It does not execute mutations.
The caller contract returns compact UI previews and confirmation tokens for write actions.
The executor validates the plan and defaults to `dry_run`; live write execution requires a matching confirmation token, internal gateway auth, and an implemented adapter.
## Resolve One Request
```text
npm run resolve -- --input-json examples/ops-card-to-engine-request.json
```
## Registry CLI
List known contexts:
```text
npm run registry -- list-contexts
```
Dry-run adding an Engine context:
```text
npm run registry -- add-context --input-json examples/engine-context.example.json --dry-run
```
After a real Engine `workflow_id` / `node_id` is known, create a real context JSON and run the same command without `--dry-run`.
Dry-run adding an OPS <-> ENGINE binding:
```text
npm run registry -- add-binding --input-json examples/ops-engine-binding.example.json --dry-run
```
Dry-run importing an Engine workflow manifest and optional OPS binding:
```text
npm run registry -- import-engine-context --input-json examples/engine-workflow-manifest.example.json --dry-run
```
The resolver returns:
- canonical input entity;
- matched source-system contexts;
- selected resolver rule;
- existing context bindings;
- missing binding types required for the selected route.
## First Implementation Target
The first useful resolver flows are:
- OPS -> ENGINE: resolve an OPS project/card request into Engine workflow/L1/L2 context.
- ENGINE -> OPS: resolve an Engine workflow/node request into target OPS project/card context.
Ontology Core advises context. OPS Gateway remains the permission/enforcement layer.
## Context Bindings
`catalog/context-bindings.json` is the bridge from stable ontology IDs to real source-system identifiers.
Current active seed contexts:
- OPS project `NDC PLATFORM`
- OPS card `Антология / Ontology Core`
Cross-surface bindings are intentionally empty until a real OPS card/project is linked to a real ENGINE workflow/node. The resolver already reports which binding type is missing, instead of pretending the link exists.

36
services/ontology-core/catalog/aliases.json Normal file
View File

@ -0,0 +1,36 @@
{
"version": "0.4-pre",
"updatedAt": "2026-06-19",
"aliases": [
{ "alias": "Plane Issue", "canonicalId": "ops.card" },
{ "alias": "issue", "canonicalId": "ops.card" },
{ "alias": "task", "canonicalId": "ops.card" },
{ "alias": "ticket", "canonicalId": "ops.card" },
{ "alias": "work item", "canonicalId": "ops.card" },
{ "alias": "карточка", "canonicalId": "ops.card" },
{ "alias": "задача", "canonicalId": "ops.card" },
{ "alias": "Authentik user", "canonicalId": "ndcauth.identity" },
{ "alias": "OIDC subject", "canonicalId": "ndcauth.identity" },
{ "alias": "JWT subject", "canonicalId": "ndcauth.identity" },
{ "alias": "Launcher service", "canonicalId": "hub.application" },
{ "alias": "app", "canonicalId": "hub.application" },
{ "alias": "application tile", "canonicalId": "hub.application_card" },
{ "alias": "app card", "canonicalId": "hub.application_card" },
{ "alias": "n8n workflow id", "canonicalId": "engine.workflow_l2_runtime_id" },
{ "alias": "runtime workflow id", "canonicalId": "engine.workflow_l2_runtime_id" },
{ "alias": "n8n execution", "canonicalId": "engine.l2_execution" },
{ "alias": "Engine-side OPS", "canonicalId": "engine.tech_debt.ops_layer" },
{ "alias": "Agent Monitor OPS", "canonicalId": "engine.tech_debt.ops_layer" },
{ "alias": "Tender Agent Monitor UI", "canonicalId": "engine.tech_debt.tender_domain_ui" },
{ "alias": "NOTG controller layer", "canonicalId": "future.interface_layer" },
{ "alias": "interface layer", "canonicalId": "future.interface_layer" },
{ "alias": "NDC Core Assistant", "canonicalId": "assistant.core_access" },
{ "alias": "Core Assistant", "canonicalId": "assistant.core_access" },
{ "alias": "assistant access", "canonicalId": "assistant.core_access" },
{ "alias": "assistant role", "canonicalId": "assistant.access_role" },
{ "alias": "assistant admin", "canonicalId": "assistant.access_role" },
{ "alias": "assistant action", "canonicalId": "assistant.action" },
{ "alias": "action card", "canonicalId": "assistant.action" },
{ "alias": "action registry", "canonicalId": "assistant.action_registry" }
]
}

241
services/ontology-core/catalog/assistant-access-policy.json Normal file
View File

@ -0,0 +1,241 @@
{
"version": "0.1.0",
"updatedAt": "2026-06-19",
"status": "draft-source-evidenced",
"summary": "NDC Core Assistant access overlay. It controls assistant visibility and assistant-mediated capabilities, but never bypasses Launcher/HUB admin guards or OPS Gateway enforcement.",
"roleVocabulary": [
{
"id": "assistant_blocked",
"name": "Blocked",
"summary": "No assistant icon, no assistant surface, no assistant capabilities."
},
{
"id": "assistant_member",
"name": "Member",
"summary": "Default personal assistant access for active users inside their allowed contexts."
},
{
"id": "assistant_admin",
"name": "Admin",
"summary": "Assistant-mediated administration, limited by existing Launcher root/client admin scope."
}
],
"roleAliases": [
{ "alias": "blocked", "roleId": "assistant_blocked" },
{ "alias": "off", "roleId": "assistant_blocked" },
{ "alias": "disabled", "roleId": "assistant_blocked" },
{ "alias": "member", "roleId": "assistant_member" },
{ "alias": "participant", "roleId": "assistant_member" },
{ "alias": "admin", "roleId": "assistant_admin" },
{ "alias": "administrator", "roleId": "assistant_admin" }
],
"defaultResolution": {
"activeUserDefaultRole": "assistant_member",
"blockedUserEffectiveRole": "assistant_blocked",
"disabledMembershipRemovesContextAdminScope": true,
"superAdminDefaultRole": "assistant_admin",
"assistantRoleDoesNotGrantLauncherAdmin": true
},
"sourceAuthorities": [
{
"id": "hub.launcher_global_role",
"entityIds": ["hub.user", "hub.role"],
"source": "/Users/dcconstructions/Downloads/mnt/data/nodedc_launcher/src/entities/user/types.ts",
"summary": "LauncherGlobalRole includes root_admin, support_admin, client_owner, client_admin, member."
},
{
"id": "hub.client_membership_role",
"entityIds": ["hub.membership", "hub.role"],
"source": "/Users/dcconstructions/Downloads/mnt/data/nodedc_launcher/src/entities/user/types.ts",
"summary": "ClientMembershipRole includes client_owner, client_admin, member; membership status includes active/disabled."
},
{
"id": "hub.resolve_admin_scope",
"entityIds": ["assistant.admin_scope", "hub.membership", "hub.role"],
"source": "/Users/dcconstructions/Downloads/mnt/data/nodedc_launcher/server/dev-server.mjs#resolveAdminScope",
"summary": "Root scope comes from nodedc:superadmin/nodedc:launcher:admin groups. Client scope comes from active client_owner/client_admin membership."
},
{
"id": "hub.admin_guards",
"entityIds": ["assistant.admin_scope", "hub.user", "hub.client_context"],
"source": "/Users/dcconstructions/Downloads/mnt/data/nodedc_launcher/server/dev-server.mjs#assertAdminCanManageClient/assertAdminCanManageUser/assertAdminCanManageAccessForUser",
"summary": "Launcher backend guards constrain which client, user, memberships, grants, and requests an admin can manage."
},
{
"id": "hub.admin_ui_access_matrix",
"entityIds": ["hub.application_access", "ops.workspace_member", "ops.project_member"],
"source": "/Users/dcconstructions/Downloads/mnt/data/nodedc_launcher/src/widgets/admin-overlay/AdminOverlay.tsx",
"summary": "Admin UI already exposes MAIN status, MAIN role, service access, Operational Core workspace/project roles, invites, and access requests."
}
],
"capabilities": [
{ "id": "assistant.visible", "entityId": "assistant.capability", "level": "surface", "summary": "Assistant icon/surface can be shown." },
{ "id": "assistant.use", "entityId": "assistant.capability", "level": "member", "summary": "User can talk to personal assistant in allowed contexts." },
{ "id": "assistant.resolve_context", "entityId": "assistant.capability", "level": "member", "summary": "Assistant can use ontology to resolve HUB/OPS Product/ENGINE context." },
{ "id": "assistant.read_own_context", "entityId": "assistant.capability", "level": "member", "summary": "Assistant can read current user's allowed context summaries through permitted tools." },
{ "id": "assistant.create_own_ops_card", "entityId": "assistant.capability", "level": "member", "summary": "Assistant can help create/update OPS Product cards in a user-authorized project." },
{ "id": "assistant.request_own_engine_workflow_action", "entityId": "assistant.capability", "level": "member", "summary": "Assistant can prepare/request actions for Engine workflow context available to the user." },
{ "id": "assistant.view_admin_summary", "entityId": "assistant.capability", "level": "admin", "summary": "Assistant can summarize admin-visible users, memberships, invites, requests, and access matrix state." },
{ "id": "assistant.manage_users", "entityId": "assistant.capability", "level": "admin", "summary": "Assistant can request user profile/status updates through Launcher admin guards." },
{ "id": "assistant.manage_client_memberships", "entityId": "assistant.capability", "level": "admin", "summary": "Assistant can request client membership role/status changes through Launcher admin guards." },
{ "id": "assistant.view_pending_invites", "entityId": "assistant.capability", "level": "admin", "summary": "Assistant can list pending invites visible in admin scope." },
{ "id": "assistant.manage_invites", "entityId": "assistant.capability", "level": "admin", "summary": "Assistant can create/update/revoke invites inside admin scope." },
{ "id": "assistant.view_access_requests", "entityId": "assistant.capability", "level": "admin", "summary": "Assistant can list pending access/workflow/tasker requests visible in admin scope." },
{ "id": "assistant.manage_ops_workspace_membership", "entityId": "assistant.capability", "level": "admin", "summary": "Assistant can request Operational Core workspace membership changes through Launcher admin guards." },
{ "id": "assistant.manage_ops_project_membership", "entityId": "assistant.capability", "level": "admin", "summary": "Assistant can request Operational Core project membership changes through Launcher admin guards." },
{ "id": "assistant.manage_engine_workflow_requests", "entityId": "assistant.capability", "level": "root", "summary": "Assistant can approve/reject Engine workflow access requests only when Launcher route remains root-only." },
{ "id": "assistant.manage_service_catalog", "entityId": "assistant.capability", "level": "root", "summary": "Assistant can request service catalog/settings mutations only for root scope." },
{ "id": "assistant.manage_assistant_access", "entityId": "assistant.capability", "level": "admin", "summary": "Assistant can request changes to assistant role assignments inside admin scope after this feature is implemented in HUB." }
],
"roleMatrix": [
{
"roleId": "assistant_blocked",
"visible": false,
"canUse": false,
"allowedCapabilities": [],
"deniedCapabilities": ["*"],
"summary": "Hard off."
},
{
"roleId": "assistant_member",
"visible": true,
"canUse": true,
"allowedCapabilities": [
"assistant.visible",
"assistant.use",
"assistant.resolve_context",
"assistant.read_own_context",
"assistant.create_own_ops_card",
"assistant.request_own_engine_workflow_action"
],
"deniedCapabilities": [
"assistant.view_admin_summary",
"assistant.manage_users",
"assistant.manage_client_memberships",
"assistant.view_pending_invites",
"assistant.manage_invites",
"assistant.view_access_requests",
"assistant.manage_ops_workspace_membership",
"assistant.manage_ops_project_membership",
"assistant.manage_engine_workflow_requests",
"assistant.manage_service_catalog",
"assistant.manage_assistant_access"
],
"summary": "Current default personal assistant behavior."
},
{
"roleId": "assistant_admin",
"visible": true,
"canUse": true,
"allowedCapabilities": [
"assistant.visible",
"assistant.use",
"assistant.resolve_context",
"assistant.read_own_context",
"assistant.create_own_ops_card",
"assistant.request_own_engine_workflow_action",
"assistant.view_admin_summary",
"assistant.manage_users",
"assistant.manage_client_memberships",
"assistant.view_pending_invites",
"assistant.manage_invites",
"assistant.view_access_requests",
"assistant.manage_ops_workspace_membership",
"assistant.manage_ops_project_membership",
"assistant.manage_assistant_access"
],
"conditionalCapabilities": [
{
"capabilityId": "assistant.manage_engine_workflow_requests",
"requires": "launcher_admin_scope.root"
},
{
"capabilityId": "assistant.manage_service_catalog",
"requires": "launcher_admin_scope.root"
}
],
"deniedWhenNoAdminScope": [
"assistant.view_admin_summary",
"assistant.manage_users",
"assistant.manage_client_memberships",
"assistant.view_pending_invites",
"assistant.manage_invites",
"assistant.view_access_requests",
"assistant.manage_ops_workspace_membership",
"assistant.manage_ops_project_membership",
"assistant.manage_engine_workflow_requests",
"assistant.manage_service_catalog",
"assistant.manage_assistant_access"
],
"summary": "Assistant-admin commands are enabled only when existing Launcher admin scope is present."
}
],
"operations": [
{
"id": "assistant.op.change_user_status",
"capabilityId": "assistant.manage_users",
"sourceEndpoints": ["PATCH /api/admin/users/:userId/profile"],
"requiredGuards": ["requireLauncherAdmin", "assertAdminCanManageUser"],
"summary": "Block/unblock/invite-state management for a user visible in admin scope."
},
{
"id": "assistant.op.change_client_membership",
"capabilityId": "assistant.manage_client_memberships",
"sourceEndpoints": ["PATCH /api/admin/memberships/:membershipId"],
"requiredGuards": ["requireLauncherAdmin", "assertAdminCanManageMembership"],
"summary": "Change client role/status for a visible membership."
},
{
"id": "assistant.op.list_pending_invites",
"capabilityId": "assistant.view_pending_invites",
"sourceEndpoints": ["GET /api/admin/control-plane"],
"requiredGuards": ["requireLauncherAdmin", "scopeControlPlaneData"],
"summary": "List pending invites visible after Launcher data scoping."
},
{
"id": "assistant.op.manage_ops_workspace_membership",
"capabilityId": "assistant.manage_ops_workspace_membership",
"sourceEndpoints": ["POST /api/admin/task-manager/workspace-memberships/ensure"],
"requiredGuards": ["requireLauncherAdmin", "assertAdminCanManageClient", "assertAdminCanManageAccessForUser"],
"hardDenies": ["assistant.deny.task_manager_admin_role_locked"],
"summary": "Ensure/revoke Operational Core workspace access without granting Task Manager admin role."
},
{
"id": "assistant.op.manage_ops_project_membership",
"capabilityId": "assistant.manage_ops_project_membership",
"sourceEndpoints": ["POST /api/admin/task-manager/project-memberships/ensure"],
"requiredGuards": ["requireLauncherAdmin", "assertAdminCanManageClient", "assertAdminCanManageAccessForUser"],
"hardDenies": ["assistant.deny.task_manager_admin_role_locked"],
"summary": "Ensure/revoke Operational Core project access without granting Task Manager admin role."
},
{
"id": "assistant.op.manage_engine_workflow_request",
"capabilityId": "assistant.manage_engine_workflow_requests",
"sourceEndpoints": ["PATCH /api/admin/engine-workflow-access-requests/:requestId/approve", "PATCH /api/admin/engine-workflow-access-requests/:requestId/reject"],
"requiredGuards": ["requireRootLauncherAdmin"],
"summary": "Root-only request management stays root-only."
}
],
"hardDenies": [
{
"id": "assistant.deny.task_manager_admin_role_locked",
"entityIds": ["ops.workspace_member", "ops.project_member"],
"summary": "Launcher source currently forbids requestedRole === admin for Task Manager workspace/project membership mutations."
},
{
"id": "assistant.deny.protected_user_root_locked",
"entityIds": ["hub.user"],
"summary": "Protected user_root cannot be managed by ordinary admins; source guards protect it."
},
{
"id": "assistant.deny.no_scope_escalation",
"entityIds": ["assistant.access_role", "assistant.admin_scope", "agent.grant"],
"summary": "Assistant role cannot create Launcher admin scope or Gateway grants by itself."
},
{
"id": "assistant.deny.root_only_stays_root_only",
"entityIds": ["hub.client_context", "hub.application", "engine.workflow_access_request"],
"summary": "Root-only backend endpoints remain root-only even when assistant role is assistant_admin."
}
]
}

317
services/ontology-core/catalog/assistant-actions.json Normal file
View File

@ -0,0 +1,317 @@
{
"version": "0.1.0",
"updatedAt": "2026-06-19",
"status": "draft-owner-confirmed",
"summary": "Declarative assistant action registry. Actions route requests to app-owned adapters after ontology context resolution and policy checks.",
"apps": [
{
"id": "hub",
"name": "HUB / Launcher",
"authorityEntityIds": ["hub.user", "hub.membership", "hub.invite", "hub.application_access"],
"adapterId": "adapter.hub.launcher_admin_api",
"summary": "Owns platform entry access, clients, memberships, invites, service access matrix, and assistant access role assignments."
},
{
"id": "ops",
"name": "OPS Product",
"authorityEntityIds": ["ops.workspace", "ops.project", "ops.card", "ops.workspace_member", "ops.project_member"],
"adapterId": "adapter.ops.product_api",
"summary": "Owns Operational Core workspace/project/card model and internal OPS roles."
},
{
"id": "engine",
"name": "ENGINE",
"authorityEntityIds": ["engine.workflow_l1", "engine.workflow_acl", "engine.workflow_share"],
"adapterId": "adapter.engine.workflow_api",
"summary": "Owns workflow ACL, workflow sharing, and Engine runtime/workflow context."
},
{
"id": "gateway",
"name": "OPS Gateway",
"authorityEntityIds": ["agent.identity", "agent.grant", "agent.scope", "agent.mcp_tool"],
"adapterId": "adapter.gateway.agent_api",
"summary": "Owns MCP/tool grants, idempotency, audit, and adapter execution envelope."
}
],
"adapterStatuses": [
"implemented",
"planned",
"future",
"forbidden"
],
"actions": [
{
"id": "assistant.action.resolve",
"app": "gateway",
"domain": "assistant",
"intentAliases": ["resolve action", "route command", "understand command"],
"entityIds": ["assistant.action_request", "assistant.action", "assistant.action_registry"],
"capabilityIds": ["assistant.resolve_context"],
"riskLevel": "read",
"confirmationMode": "none",
"selfActionPolicy": "allowed",
"adapterId": "adapter.gateway.agent_api",
"adapterStatus": "planned",
"summary": "Resolve natural-language user request into a known registered action before policy/execution."
},
{
"id": "hub.user.read_admin_summary",
"app": "hub",
"domain": "users",
"intentAliases": ["show users", "show user access", "summarize users", "покажи пользователей", "покажи доступы пользователя"],
"entityIds": ["hub.user", "hub.membership", "hub.application_access"],
"capabilityIds": ["assistant.view_admin_summary"],
"riskLevel": "read",
"confirmationMode": "none",
"selfActionPolicy": "allowed",
"requiredScopes": ["launcher_admin_scope.any"],
"adapterId": "adapter.hub.launcher_admin_api",
"adapterStatus": "implemented",
"summary": "Read scoped admin summary for HUB users, memberships, app access, and assistant access role."
},
{
"id": "hub.invite.list_pending",
"app": "hub",
"domain": "invites",
"intentAliases": ["pending invites", "show pending invites", "покажи инвайты", "покажи ожидающие инвайты"],
"entityIds": ["hub.invite", "hub.client_context", "hub.public_pool_context"],
"capabilityIds": ["assistant.view_access_requests"],
"riskLevel": "read",
"confirmationMode": "none",
"selfActionPolicy": "allowed",
"requiredScopes": ["launcher_admin_scope.any"],
"adapterId": "adapter.hub.launcher_admin_api",
"adapterStatus": "implemented",
"summary": "List pending invites visible inside current Launcher admin scope."
},
{
"id": "hub.access_request.list_pending",
"app": "hub",
"domain": "access_requests",
"intentAliases": ["pending access requests", "new access requests", "show access requests", "show launcher requests", "покажи заявки", "покажи новые заявки", "есть ли новые заявки", "заявки доступа", "заявки в лаунчере"],
"entityIds": ["hub.access_request", "hub.client_context", "hub.public_pool_context"],
"capabilityIds": ["assistant.view_access_requests"],
"riskLevel": "read",
"confirmationMode": "none",
"selfActionPolicy": "allowed",
"requiredScopes": ["launcher_admin_scope.any"],
"adapterId": "adapter.hub.launcher_admin_api",
"adapterStatus": "implemented",
"summary": "List pending public access requests visible inside current Launcher admin scope."
},
{
"id": "hub.user.block",
"app": "hub",
"domain": "users",
"intentAliases": ["block user", "disable user", "заблокируй пользователя", "отключи аккаунт"],
"entityIds": ["hub.user"],
"capabilityIds": ["assistant.manage_users"],
"riskLevel": "privileged",
"confirmationMode": "explicit",
"selfActionPolicy": "no_self_lockout",
"requiredScopes": ["launcher_admin_scope.can_manage_user"],
"adapterId": "adapter.hub.launcher_admin_api",
"adapterStatus": "implemented",
"sourceEndpoints": ["PATCH /api/admin/users/:userId/profile"],
"sourcePatch": { "globalStatus": "blocked" },
"hardDenyIds": ["assistant.action.deny.self_lockout"],
"summary": "Block HUB user account through existing Launcher admin guards."
},
{
"id": "hub.user.unblock",
"app": "hub",
"domain": "users",
"intentAliases": ["unblock user", "activate user", "разблокируй пользователя", "включи аккаунт"],
"entityIds": ["hub.user"],
"capabilityIds": ["assistant.manage_users"],
"riskLevel": "privileged",
"confirmationMode": "explicit",
"selfActionPolicy": "allowed",
"requiredScopes": ["launcher_admin_scope.can_manage_user"],
"adapterId": "adapter.hub.launcher_admin_api",
"adapterStatus": "implemented",
"sourceEndpoints": ["PATCH /api/admin/users/:userId/profile"],
"sourcePatch": { "globalStatus": "active" },
"summary": "Unblock HUB user account through existing Launcher admin guards."
},
{
"id": "hub.user.delete",
"app": "hub",
"domain": "users",
"intentAliases": ["delete user", "remove user", "удали пользователя", "сотри пользователя"],
"entityIds": ["hub.user"],
"capabilityIds": ["assistant.manage_users"],
"riskLevel": "destructive",
"confirmationMode": "forbidden",
"selfActionPolicy": "blocked",
"adapterId": "adapter.forbidden",
"adapterStatus": "forbidden",
"hardDenyIds": ["assistant.action.deny.delete_user", "assistant.action.deny.hard_delete_records"],
"safeAlternativeActionIds": ["hub.user.block", "hub.membership.disable"],
"refusal": "Я не удаляю пользователей. Могу заблокировать аккаунт или отключить доступ в конкретном контуре.",
"summary": "Explicit forbidden action card for user deletion requests."
},
{
"id": "hub.membership.change_role",
"app": "hub",
"domain": "memberships",
"intentAliases": ["change hub role", "change client role", "измени роль в хабе", "измени роль в контуре"],
"entityIds": ["hub.membership", "hub.role"],
"capabilityIds": ["assistant.manage_client_memberships"],
"riskLevel": "privileged",
"confirmationMode": "explicit",
"selfActionPolicy": "no_self_lockout",
"requiredScopes": ["launcher_admin_scope.can_manage_membership"],
"adapterId": "adapter.hub.launcher_admin_api",
"adapterStatus": "implemented",
"sourceEndpoints": ["PATCH /api/admin/memberships/:membershipId"],
"hardDenyIds": ["assistant.action.deny.self_lockout"],
"summary": "Change HUB/Launcher client membership role through existing Launcher admin guards."
},
{
"id": "hub.membership.disable",
"app": "hub",
"domain": "memberships",
"intentAliases": ["disable context access", "disable membership", "отключи доступ в контуре"],
"entityIds": ["hub.membership"],
"capabilityIds": ["assistant.manage_client_memberships"],
"riskLevel": "privileged",
"confirmationMode": "explicit",
"selfActionPolicy": "no_self_lockout",
"requiredScopes": ["launcher_admin_scope.can_manage_membership"],
"adapterId": "adapter.hub.launcher_admin_api",
"adapterStatus": "implemented",
"sourceEndpoints": ["PATCH /api/admin/memberships/:membershipId"],
"sourcePatch": { "status": "disabled" },
"hardDenyIds": ["assistant.action.deny.self_lockout"],
"summary": "Disable a user's membership in a HUB client/public context."
},
{
"id": "hub.assistant_access.change_role",
"app": "hub",
"domain": "assistant_access",
"intentAliases": ["change assistant role", "block assistant", "enable assistant admin", "измени роль ассистента", "отключи ассистента"],
"entityIds": ["assistant.core_access", "assistant.access_role", "hub.membership"],
"capabilityIds": ["assistant.manage_assistant_access"],
"riskLevel": "privileged",
"confirmationMode": "explicit",
"selfActionPolicy": "no_self_lockout",
"requiredScopes": ["launcher_admin_scope.can_manage_membership"],
"adapterId": "adapter.hub.launcher_admin_api",
"adapterStatus": "implemented",
"sourceEndpoints": ["PATCH /api/admin/memberships/:membershipId"],
"allowedValues": ["blocked", "member", "admin"],
"hardDenyIds": ["assistant.action.deny.self_lockout"],
"summary": "Change NDC Core Assistant access role stored on HUB membership."
},
{
"id": "ops.card.list_recent",
"app": "ops",
"domain": "cards",
"intentAliases": ["latest ops task", "last ops task", "recent ops cards", "show ops tasks", "show ops cards", "последняя задача в опсе", "последнюю задачу в опсе", "последние задачи в опсе", "задачи в опсе", "карточки в опсе", "покажи задачи ops", "покажи карточки ops"],
"entityIds": ["ops.card", "ops.project", "ops.workspace"],
"capabilityIds": ["assistant.read_own_context"],
"riskLevel": "read",
"confirmationMode": "none",
"selfActionPolicy": "allowed",
"requiredScopes": ["ops.project.can_read_card"],
"adapterId": "adapter.ops.product_api",
"adapterStatus": "implemented",
"sourceEndpoints": ["GET /api/v1/tools/issues"],
"summary": "Read recent OPS Product cards in the current user-authorized project through the local Ops Gateway."
},
{
"id": "ops.card.create",
"app": "ops",
"domain": "cards",
"intentAliases": ["create ops card", "create ops task", "create card in ops", "create task in ops", "create card", "create task", "создай карточку в опсе", "создай задачу в опсе", "заведи карточку в опсе", "заведи задачу в опсе", "создай карточку", "создай задачу"],
"entityIds": ["ops.card", "ops.project", "ops.workspace"],
"capabilityIds": ["assistant.create_own_ops_card"],
"riskLevel": "write",
"confirmationMode": "explicit",
"selfActionPolicy": "allowed",
"requiredScopes": ["ops.project.can_create_card"],
"adapterId": "adapter.ops.product_api",
"adapterStatus": "implemented",
"sourceEndpoints": ["POST /api/v1/tools/issues"],
"summary": "Create OPS Product card through OPS-owned Gateway adapter."
},
{
"id": "ops.card.add_comment",
"app": "ops",
"domain": "cards",
"intentAliases": ["add ops comment", "comment ops card", "comment ops task", "write in ops card", "write in ops task", "добавь комментарий в опсе", "добавь комментарий в задачу", "напиши в задаче опса", "напиши в карточке опса", "напиши в этой задаче", "запиши в карточку опса", "оставь комментарий в задаче"],
"entityIds": ["ops.card", "ops.card_comment", "ops.project", "ops.workspace"],
"capabilityIds": ["assistant.create_own_ops_card"],
"riskLevel": "write",
"confirmationMode": "explicit",
"selfActionPolicy": "allowed",
"requiredScopes": ["ops.card.can_comment"],
"adapterId": "adapter.ops.product_api",
"adapterStatus": "implemented",
"sourceEndpoints": ["POST /api/v1/tools/issues/:issueId/comments"],
"summary": "Append comment to OPS Product card through OPS-owned Gateway adapter."
},
{
"id": "ops.card.update_status",
"app": "ops",
"domain": "cards",
"intentAliases": ["update card status", "close card", "archive card safely", "измени статус карточки", "закрой карточку"],
"entityIds": ["ops.card", "ops.project", "ops.workspace"],
"capabilityIds": ["assistant.create_own_ops_card"],
"riskLevel": "write",
"confirmationMode": "explicit",
"selfActionPolicy": "allowed",
"requiredScopes": ["ops.card.can_update_status"],
"adapterId": "adapter.ops.product_api",
"adapterStatus": "planned",
"summary": "Update OPS Product card status through OPS-owned adapter. This is the safe alternative to destructive card deletion."
},
{
"id": "ops.project.grant_member",
"app": "ops",
"domain": "project_members",
"intentAliases": ["grant ops project", "add ops project member", "добавь в проект опса"],
"entityIds": ["ops.project_member", "ops.project", "ops.workspace_member"],
"capabilityIds": ["assistant.manage_ops_project_membership"],
"riskLevel": "privileged",
"confirmationMode": "explicit",
"selfActionPolicy": "app_owned",
"requiredScopes": ["ops.project.can_manage_members"],
"adapterId": "adapter.ops.product_api",
"adapterStatus": "future",
"hardDenyIds": ["assistant.action.deny.cross_app_role_ownership"],
"summary": "Grant OPS Product project access through OPS-owned role adapter, not HUB direct mutation."
},
{
"id": "engine.workflow.share",
"app": "engine",
"domain": "workflow_acl",
"intentAliases": ["share workflow", "grant engine workflow", "пошарь workflow", "дай доступ к workflow"],
"entityIds": ["engine.workflow_share", "engine.workflow_acl", "engine.workflow_l1"],
"capabilityIds": ["assistant.request_own_engine_workflow_action"],
"riskLevel": "privileged",
"confirmationMode": "explicit",
"selfActionPolicy": "app_owned",
"requiredScopes": ["engine.workflow.can_manage_acl"],
"adapterId": "adapter.engine.workflow_api",
"adapterStatus": "future",
"hardDenyIds": ["assistant.action.deny.cross_app_role_ownership"],
"summary": "Share ENGINE workflow through Engine-owned ACL adapter."
},
{
"id": "gateway.grant.select_tool_scope",
"app": "gateway",
"domain": "agent_grants",
"intentAliases": ["select gateway grant", "select mcp tool", "выбери mcp tool"],
"entityIds": ["agent.grant", "agent.scope", "agent.mcp_tool", "agent.idempotency_key"],
"capabilityIds": ["assistant.resolve_context"],
"riskLevel": "read",
"confirmationMode": "none",
"selfActionPolicy": "allowed",
"adapterId": "adapter.gateway.agent_api",
"adapterStatus": "planned",
"summary": "Select candidate Gateway grant/tool/scope before execution. Does not create grants."
}
]
}

135
services/ontology-core/catalog/assistant-risk-policy.json Normal file
View File

@ -0,0 +1,135 @@
{
"version": "0.1.0",
"updatedAt": "2026-06-19",
"status": "draft-owner-confirmed",
"summary": "Risk policy for assistant action routing. This policy is intentionally conservative: destructive actions are forbidden, privileged writes are scoped, and app-owned roles stay app-owned.",
"riskLevels": [
{
"id": "read",
"requiresConfirmation": false,
"summary": "Read or summarize data already visible to the actor."
},
{
"id": "write",
"requiresConfirmation": true,
"summary": "Create or update non-destructive state."
},
{
"id": "privileged",
"requiresConfirmation": true,
"summary": "Change users, roles, memberships, access, grants, workflow ACLs, or other privileged state."
},
{
"id": "destructive",
"requiresConfirmation": true,
"assistantAllowed": false,
"summary": "Delete, hard-remove, archive critical objects, or destroy production state. Forbidden for assistant execution."
},
{
"id": "root_only",
"requiresConfirmation": true,
"summary": "Root-only administrative action. Assistant may route only when source app also confirms root scope."
},
{
"id": "future",
"requiresConfirmation": false,
"assistantAllowed": false,
"summary": "Conceptual action not wired to an adapter yet."
}
],
"confirmationModes": [
{
"id": "none",
"summary": "No extra confirmation beyond ordinary chat request."
},
{
"id": "explicit",
"summary": "Assistant must show exact target, action, app, scope, and expected effect before execution."
},
{
"id": "typed",
"summary": "Reserved for very high-risk future flows. Requires typing a short confirmation phrase."
},
{
"id": "forbidden",
"summary": "Assistant refuses and should offer the nearest safe alternative."
}
],
"selfActionPolicies": [
{
"id": "allowed",
"summary": "Self-targeting is allowed."
},
{
"id": "blocked",
"summary": "Self-targeting is never allowed."
},
{
"id": "no_self_lockout",
"summary": "Self-targeting is allowed only when it cannot remove the actor's own last access/admin path."
},
{
"id": "app_owned",
"summary": "Self-targeting is delegated to the app adapter because the app owns the role model."
}
],
"hardDenies": [
{
"id": "assistant.action.deny.delete_user",
"summary": "Assistant must never delete a HUB/Launcher user. Offer block user or disable membership instead.",
"safeAlternatives": ["hub.user.block", "hub.membership.disable"]
},
{
"id": "assistant.action.deny.hard_delete_records",
"summary": "Assistant must never hard-delete records, database rows, files, runtime data, storage, backups, or production state.",
"safeAlternatives": ["hub.user.block", "hub.membership.disable", "ops.card.update_status"]
},
{
"id": "assistant.action.deny.self_lockout",
"summary": "Assistant must never let an actor remove their own last admin/access path.",
"safeAlternatives": ["hub.invite.list_pending", "hub.user.read_admin_summary"]
},
{
"id": "assistant.action.deny.cross_app_role_ownership",
"summary": "HUB action cannot mutate internal ENGINE workflow ACL or OPS Product project roles unless routed to the app-owned adapter.",
"safeAlternatives": ["engine.workflow.share", "ops.project.grant_member"]
},
{
"id": "assistant.action.deny.prompt_only_execution",
"summary": "Assistant must not execute actions from prompt text alone. It must resolve a registered action card and pass policy first.",
"safeAlternatives": ["assistant.action.resolve"]
}
],
"globalRules": [
{
"id": "assistant.rule.registered_action_required",
"severity": "error",
"summary": "Every executable request must resolve to an action in assistant-actions.json."
},
{
"id": "assistant.rule.destructive_forbidden",
"severity": "error",
"summary": "Actions with riskLevel=destructive or confirmationMode=forbidden are refused by default."
},
{
"id": "assistant.rule.privileged_requires_admin_role",
"severity": "error",
"summary": "Actions with riskLevel=privileged require assistant_admin plus app-owned admin scope."
},
{
"id": "assistant.rule.app_owned_roles_stay_app_owned",
"severity": "error",
"summary": "HUB may route but must not directly mutate OPS Product or ENGINE internal role models."
},
{
"id": "assistant.rule.write_requires_idempotency",
"severity": "error",
"summary": "Write actions executed through Gateway adapters require an idempotency key."
},
{
"id": "assistant.rule.audit_every_write",
"severity": "error",
"summary": "Write and privileged actions must emit app audit or gateway audit events."
}
]
}

65
services/ontology-core/catalog/context-bindings.json Normal file
View File

@ -0,0 +1,65 @@
{
"version": "0.1.0",
"updatedAt": "2026-06-19",
"contextStatuses": ["active", "planned", "deprecated"],
"bindingStatuses": ["active", "planned", "blocked"],
"contexts": [
{
"id": "context.ops.nodedc.ndc_platform",
"surface": "ops",
"entityId": "ops.project",
"sourceSystem": "tasker",
"label": "NDC PLATFORM",
"status": "active",
"refs": {
"workspace_slug": "nodedc",
"project_id": "86629a11-eaff-4ad2-9f89-e5245a344fcc"
}
},
{
"id": "context.ops.nodedc.ndc_platform.ontology_core_card",
"surface": "ops",
"entityId": "ops.card",
"sourceSystem": "tasker",
"label": "Антология / Ontology Core",
"status": "active",
"parentContextId": "context.ops.nodedc.ndc_platform",
"refs": {
"workspace_slug": "nodedc",
"project_id": "86629a11-eaff-4ad2-9f89-e5245a344fcc",
"issue_id": "1312519a-0eda-4ea0-9e34-2113c3724ecf",
"sequence_id": "43"
}
}
],
"bindingTypes": [
{
"id": "binding_type.ops_card_to_engine_workflow",
"relationId": "ontology.resolves_ops_card_to_engine_context",
"fromEntityIds": ["ops.card", "ops.project"],
"toEntityIds": ["engine.workflow_l1", "engine.node_l1", "engine.workflow_l2", "engine.workflow_l2_runtime_id"],
"requiredFromRefs": ["workspace_slug", "project_id"],
"requiredToRefs": ["workflow_id"],
"summary": "Binds OPS project/card context to Engine L1/L2 workflow context."
},
{
"id": "binding_type.engine_workflow_to_ops_project",
"relationId": "ontology.resolves_engine_context_to_ops_project",
"fromEntityIds": ["engine.workflow_l1", "engine.workflow_l2", "engine.node_l1"],
"toEntityIds": ["ops.project", "ops.card"],
"requiredFromRefs": ["workflow_id"],
"requiredToRefs": ["workspace_slug", "project_id"],
"summary": "Binds Engine workflow/node context to OPS project/card context."
},
{
"id": "binding_type.assistant_context_to_gateway_grant",
"relationId": "ontology.selects_gateway_grant_context",
"fromEntityIds": ["assistant.bridge", "assistant.executor"],
"toEntityIds": ["agent.grant", "agent.scope", "agent.mcp_tool"],
"requiredFromRefs": ["surface"],
"requiredToRefs": ["grant_id"],
"summary": "Binds resolved assistant context to Gateway grant/tool preflight."
}
],
"bindings": []
}

128
services/ontology-core/catalog/entities.json Normal file
View File

@ -0,0 +1,128 @@
{
"version": "0.4-pre",
"updatedAt": "2026-06-19",
"statusVocabulary": [
"source-confirmed",
"source-evidenced",
"owner-confirmed",
"product-required",
"future-concept",
"tech-debt-noncanonical",
"pending",
"source-adjacent"
],
"entities": [
{ "id": "hub.open_contour", "name": "HUB Open Contour", "surface": "hub", "status": ["source-evidenced", "owner-confirmed"], "authority": "HUB", "summary": "Public/open branch for simple users." },
{ "id": "hub.public_pool_context", "name": "HUB Public Pool Context", "surface": "hub", "status": ["source-confirmed"], "authority": "HUB", "summary": "Source-backed public context." },
{ "id": "hub.public_pool_client", "name": "HUB Public Pool Client", "surface": "hub", "status": ["source-confirmed"], "authority": "HUB", "summary": "Special source-backed Client, not ordinary company/client." },
{ "id": "hub.client_context", "name": "HUB Client Context", "surface": "hub", "status": ["source-confirmed"], "authority": "HUB", "summary": "Managed closed contour for companies/clients." },
{ "id": "hub.company_contour", "name": "HUB Company Contour", "surface": "hub", "status": ["source-evidenced"], "authority": "HUB", "summary": "Product wording over managed client context." },
{ "id": "hub.user", "name": "HUB User", "surface": "hub", "status": ["source-confirmed"], "authority": "HUB/NDCAuth", "summary": "Canonical launcher user." },
{ "id": "hub.public_user", "name": "HUB Public User Classification", "surface": "hub", "status": ["source-evidenced"], "authority": "HUB", "summary": "Classification of hub.user by public-pool context." },
{ "id": "hub.client_user", "name": "HUB Client User Classification", "surface": "hub", "status": ["source-evidenced"], "authority": "HUB", "summary": "Classification of hub.user by client/company membership." },
{ "id": "hub.membership", "name": "HUB Membership", "surface": "hub", "status": ["source-confirmed"], "authority": "HUB", "summary": "User-to-context relation." },
{ "id": "hub.public_membership", "name": "HUB Public Membership", "surface": "hub", "status": ["source-confirmed"], "authority": "HUB", "summary": "Membership in public pool context." },
{ "id": "hub.access_request", "name": "HUB Access Request", "surface": "hub", "status": ["source-confirmed"], "authority": "HUB", "summary": "Base access request entity." },
{ "id": "hub.public_access_request", "name": "HUB Public Access Request", "surface": "hub", "status": ["source-evidenced"], "authority": "HUB", "summary": "Public/open-contour access request subtype." },
{ "id": "hub.client_access_request", "name": "HUB Client Access Request", "surface": "hub", "status": ["source-evidenced"], "authority": "HUB", "summary": "Company/client-context access request subtype." },
{ "id": "hub.invite", "name": "HUB Invite", "surface": "hub", "status": ["source-confirmed"], "authority": "HUB", "summary": "Invitation into a context." },
{ "id": "hub.group", "name": "HUB Group", "surface": "hub", "status": ["source-confirmed"], "authority": "HUB", "summary": "Client-local group." },
{ "id": "hub.role", "name": "HUB Role", "surface": "hub", "status": ["source-confirmed"], "authority": "HUB", "summary": "Role vocabulary for user and membership decisions." },
{ "id": "hub.permission", "name": "HUB Permission", "surface": "hub", "status": ["source-confirmed"], "authority": "HUB", "summary": "Derived permission capability." },
{ "id": "hub.application", "name": "HUB Application", "surface": "hub", "status": ["source-confirmed"], "authority": "HUB", "summary": "Product application/service registered in launcher." },
{ "id": "hub.application_access", "name": "HUB Application Access", "surface": "hub", "status": ["source-confirmed"], "authority": "HUB", "summary": "Effective app access result." },
{ "id": "hub.app_grant", "name": "HUB App Grant", "surface": "hub", "status": ["source-confirmed"], "authority": "HUB", "summary": "Access authority input." },
{ "id": "hub.app_exception", "name": "HUB App Exception", "surface": "hub", "status": ["source-confirmed"], "authority": "HUB", "summary": "User-specific allow/deny override." },
{ "id": "hub.application_card", "name": "HUB Application Card", "surface": "hub", "status": ["source-confirmed"], "authority": "HUB UI", "summary": "Presentation over application/access state, not authority." },
{ "id": "ndcauth.identity", "name": "NDCAuth Identity", "surface": "ndcauth", "status": ["source-confirmed"], "authority": "NDCAuth/HUB", "summary": "Canonical auth identity." },
{ "id": "ndcauth.session", "name": "NDCAuth Session", "surface": "ndcauth", "status": ["source-confirmed"], "authority": "NDCAuth/HUB", "summary": "Runtime authenticated/unauthenticated session." },
{ "id": "ops.workspace", "name": "OPS Workspace", "surface": "ops", "status": ["source-confirmed"], "authority": "OPS Product", "summary": "Workspace/root collaboration context." },
{ "id": "ops.workspace_member", "name": "OPS Workspace Member", "surface": "ops", "status": ["source-confirmed"], "authority": "OPS Product", "summary": "User membership in workspace." },
{ "id": "ops.project", "name": "OPS Project", "surface": "ops", "status": ["source-confirmed"], "authority": "OPS Product", "summary": "Project inside workspace." },
{ "id": "ops.project_member", "name": "OPS Project Member", "surface": "ops", "status": ["source-confirmed"], "authority": "OPS Product", "summary": "User membership in project." },
{ "id": "ops.card", "name": "OPS Card", "surface": "ops", "status": ["source-confirmed", "owner-confirmed"], "authority": "OPS Product", "summary": "Canonical work object." },
{ "id": "ops.card_status", "name": "OPS Card Status", "surface": "ops", "status": ["source-confirmed"], "authority": "OPS Product", "summary": "State/status of a card." },
{ "id": "ops.card_priority", "name": "OPS Card Priority", "surface": "ops", "status": ["source-confirmed"], "authority": "OPS Product", "summary": "Card priority attribute." },
{ "id": "ops.card_assignment", "name": "OPS Card Assignment", "surface": "ops", "status": ["source-confirmed"], "authority": "OPS Product", "summary": "Relation between card and assignee." },
{ "id": "ops.assignee", "name": "OPS Assignee", "surface": "ops", "status": ["source-confirmed"], "authority": "OPS Product", "summary": "Assigned user/member." },
{ "id": "ops.responsible", "name": "OPS Responsible", "surface": "ops", "status": ["product-required", "source-adjacent"], "authority": "OPS Product", "summary": "Accountability role, not automatically assignee." },
{ "id": "ops.card_type", "name": "OPS Card Type", "surface": "ops", "status": ["source-evidenced", "pending"], "authority": "OPS Product", "summary": "Type/subtype of card." },
{ "id": "ops.card_relation", "name": "OPS Card Relation", "surface": "ops", "status": ["source-confirmed"], "authority": "OPS Product", "summary": "Dependency/link between cards." },
{ "id": "ops.external_ref", "name": "OPS External Reference", "surface": "ops", "status": ["source-confirmed"], "authority": "OPS Product", "summary": "Link to external/source object." },
{ "id": "ops.card_label", "name": "OPS Card Label", "surface": "ops", "status": ["source-confirmed"], "authority": "OPS Product", "summary": "Label/tag classification." },
{ "id": "ops.card_comment", "name": "OPS Card Comment", "surface": "ops", "status": ["source-confirmed"], "authority": "OPS Product", "summary": "Discussion/comment on a card." },
{ "id": "ops.card_activity", "name": "OPS Card Activity", "surface": "ops", "status": ["source-evidenced"], "authority": "OPS Product", "summary": "Change/activity history." },
{ "id": "ops.card_artifact_link", "name": "OPS Card Artifact Link", "surface": "ops", "status": ["source-evidenced"], "authority": "OPS Product", "summary": "Relation/link to output artifact." },
{ "id": "ops.file_asset", "name": "OPS File Asset", "surface": "ops", "status": ["source-evidenced"], "authority": "OPS Product", "summary": "File attached/linked through OPS." },
{ "id": "ops.stored_blob", "name": "OPS Stored Blob", "surface": "ops", "status": ["source-evidenced"], "authority": "OPS Product", "summary": "Storage-level blob behind file assets." },
{ "id": "agent.identity", "name": "Agent Identity", "surface": "agent", "status": ["source-confirmed"], "authority": "OPS Gateway", "summary": "Gateway execution identity, not user/persona." },
{ "id": "agent.token", "name": "Agent Token", "surface": "agent", "status": ["source-confirmed"], "authority": "OPS Gateway", "summary": "Opaque credential." },
{ "id": "agent.session", "name": "Agent Session", "surface": "agent", "status": ["source-confirmed"], "authority": "OPS Gateway", "summary": "Runtime/session envelope for agent operations." },
{ "id": "agent.grant", "name": "Agent Grant", "surface": "agent", "status": ["source-confirmed"], "authority": "OPS Gateway", "summary": "Permission grant for agent identity/session." },
{ "id": "agent.token_grant", "name": "Token Grant", "surface": "agent", "status": ["source-confirmed"], "authority": "OPS Gateway", "summary": "Token-to-grant binding." },
{ "id": "agent.scope", "name": "Agent Scope", "surface": "agent", "status": ["source-confirmed"], "authority": "OPS Gateway", "summary": "Tool/capability permission." },
{ "id": "agent.denied_capability", "name": "Denied Capability", "surface": "agent", "status": ["source-confirmed"], "authority": "OPS Gateway", "summary": "Explicitly unavailable operation." },
{ "id": "agent.mcp_tool", "name": "MCP Tool", "surface": "agent", "status": ["source-confirmed"], "authority": "OPS Gateway", "summary": "Exposed callable tool surface." },
{ "id": "agent.idempotency_key", "name": "Idempotency Key", "surface": "agent", "status": ["source-confirmed"], "authority": "OPS Gateway", "summary": "Required write-safety key." },
{ "id": "agent.audit_event", "name": "Agent Audit Event", "surface": "agent", "status": ["source-confirmed"], "authority": "OPS Gateway", "summary": "Audit trail for agent actions." },
{ "id": "agent.tasker_adapter", "name": "Tasker Adapter", "surface": "agent", "status": ["source-confirmed"], "authority": "OPS Gateway", "summary": "Adapter to Tasker/OPS product API." },
{ "id": "agent.setup_packet", "name": "Agent Setup Packet", "surface": "agent", "status": ["source-evidenced"], "authority": "OPS Gateway", "summary": "Setup payload for client app/tool access." },
{ "id": "agent.ai_workspace_entitlement", "name": "AI Workspace Entitlement", "surface": "agent", "status": ["source-evidenced", "pending"], "authority": "HUB/OPS Gateway", "summary": "Entitlement/access context for AI workspace." },
{ "id": "agent.pairing_code", "name": "Pairing Code", "surface": "agent", "status": ["source-evidenced", "pending"], "authority": "OPS Gateway", "summary": "Pairing/setup flow candidate." },
{ "id": "engine.workflow_l1", "name": "ENGINE L1 Workflow", "surface": "engine", "status": ["source-confirmed"], "authority": "ENGINE", "summary": "NodeDC canvas/workflow graph." },
{ "id": "engine.node_l1", "name": "ENGINE L1 Node", "surface": "engine", "status": ["source-confirmed"], "authority": "ENGINE", "summary": "React Flow node in L1 graph." },
{ "id": "engine.edge_l1", "name": "ENGINE L1 Edge", "surface": "engine", "status": ["source-confirmed"], "authority": "ENGINE", "summary": "React Flow edge in L1 graph." },
{ "id": "engine.node_type_l1", "name": "ENGINE L1 Node Type", "surface": "engine", "status": ["source-confirmed"], "authority": "ENGINE", "summary": "Auto-registered node type/module." },
{ "id": "engine.workflow_acl", "name": "ENGINE Workflow ACL", "surface": "engine", "status": ["source-confirmed"], "authority": "ENGINE", "summary": "Workflow-level ACL." },
{ "id": "engine.workflow_owner", "name": "ENGINE Workflow Owner", "surface": "engine", "status": ["source-confirmed"], "authority": "ENGINE", "summary": "Owner field in ACL." },
{ "id": "engine.workflow_share", "name": "ENGINE Workflow Share", "surface": "engine", "status": ["source-confirmed"], "authority": "ENGINE", "summary": "Share/invite/user access routes." },
{ "id": "engine.workflow_access_request", "name": "ENGINE Workflow Access Request", "surface": "engine", "status": ["source-confirmed"], "authority": "ENGINE", "summary": "Access request route/model for workflow access." },
{ "id": "engine.workflow_l2", "name": "ENGINE L2 Workflow", "surface": "engine", "status": ["source-evidenced"], "authority": "ENGINE/n8n bridge", "summary": "n8n subworkflow attached to L1 node." },
{ "id": "engine.node_l2", "name": "ENGINE L2 Node", "surface": "engine", "status": ["source-evidenced"], "authority": "ENGINE/n8n bridge", "summary": "Node inside compiled/deployed n8n workflow." },
{ "id": "engine.l2_runtime_core", "name": "ENGINE L2 Runtime Core", "surface": "engine", "status": ["source-evidenced"], "authority": "ENGINE/n8n bridge", "summary": "Target n8n runtime/core instance." },
{ "id": "engine.workflow_l2_runtime_id", "name": "ENGINE L2 Runtime Workflow ID", "surface": "engine", "status": ["source-confirmed"], "authority": "ENGINE/n8n bridge", "summary": "n8n runtime workflow id, separate from NodeDC workflow id." },
{ "id": "engine.l2_execution", "name": "ENGINE L2 Execution", "surface": "engine", "status": ["source-confirmed"], "authority": "ENGINE/n8n bridge", "summary": "n8n execution id mapped to run/execution records." },
{ "id": "engine.l2_run", "name": "ENGINE L2 Run", "surface": "engine", "status": ["source-confirmed"], "authority": "ENGINE-side OpsLayer", "summary": "Runtime run id; tech-debt-adjacent." },
{ "id": "engine.l2_session", "name": "ENGINE L2 Session", "surface": "engine", "status": ["source-confirmed"], "authority": "ENGINE-side OpsLayer", "summary": "Runtime session anchor." },
{ "id": "engine.l2_runtime_event", "name": "ENGINE L2 Runtime Event", "surface": "engine", "status": ["source-confirmed"], "authority": "ENGINE/n8n bridge", "summary": "Runtime event: workflow/node start/finish/success/error." },
{ "id": "engine.source_stamp", "name": "ENGINE Source Stamp", "surface": "engine", "status": ["pending"], "authority": "ENGINE", "summary": "Future source/version traceability candidate." },
{ "id": "assistant.assistant", "name": "Assistant", "surface": "assistant", "status": ["product-required", "pending"], "authority": "AI Workspace", "summary": "User-facing assistant capability/persona." },
{ "id": "assistant.provider", "name": "Assistant Provider", "surface": "assistant", "status": ["product-required", "pending"], "authority": "AI Workspace", "summary": "Model/provider integration boundary." },
{ "id": "assistant.executor", "name": "Assistant Executor", "surface": "assistant", "status": ["product-required", "pending"], "authority": "AI Workspace/Codex/MCP", "summary": "Execution adapter." },
{ "id": "assistant.thread", "name": "Assistant Thread", "surface": "assistant", "status": ["product-required", "pending"], "authority": "AI Workspace", "summary": "Conversation context." },
{ "id": "assistant.message", "name": "Assistant Message", "surface": "assistant", "status": ["product-required", "pending"], "authority": "AI Workspace", "summary": "Message unit in thread." },
{ "id": "assistant.bridge", "name": "Assistant Bridge", "surface": "assistant", "status": ["product-required", "pending"], "authority": "AI Workspace/OPS Gateway", "summary": "Bridge between assistant, ontology, gateway, Codex, and Engine." },
{ "id": "assistant.core_access", "name": "NDC Core Assistant Access", "surface": "assistant", "status": ["product-required", "owner-confirmed"], "authority": "HUB/Launcher", "summary": "Per-user assistant availability and permission overlay." },
{ "id": "assistant.access_role", "name": "Assistant Access Role", "surface": "assistant", "status": ["product-required", "owner-confirmed"], "authority": "HUB/Launcher", "summary": "Assistant role vocabulary: blocked, member, admin." },
{ "id": "assistant.role_assignment", "name": "Assistant Role Assignment", "surface": "assistant", "status": ["product-required", "pending"], "authority": "HUB/Launcher", "summary": "Scoped assignment of an assistant access role to a HUB user." },
{ "id": "assistant.capability", "name": "Assistant Capability", "surface": "assistant", "status": ["product-required", "owner-confirmed"], "authority": "Ontology Core/HUB/OPS Gateway", "summary": "Action-level capability exposed to an assistant." },
{ "id": "assistant.permission_policy", "name": "Assistant Permission Policy", "surface": "assistant", "status": ["product-required", "owner-confirmed"], "authority": "Ontology Core", "summary": "Policy that maps assistant role plus HUB admin scope to allowed capabilities." },
{ "id": "assistant.admin_scope", "name": "Assistant Admin Scope", "surface": "assistant", "status": ["product-required", "source-evidenced"], "authority": "HUB/Launcher", "summary": "Launcher-derived root/client admin boundary available to assistant-admin commands." },
{ "id": "assistant.action_request", "name": "Assistant Action Request", "surface": "assistant", "status": ["product-required", "pending"], "authority": "AI Workspace/OPS Gateway", "summary": "A requested assistant operation before policy and gateway enforcement." },
{ "id": "assistant.action", "name": "Assistant Action", "surface": "assistant", "status": ["product-required", "owner-confirmed"], "authority": "Ontology Core", "summary": "Declarative action card used by assistant command routing." },
{ "id": "assistant.action_registry", "name": "Assistant Action Registry", "surface": "assistant", "status": ["product-required", "owner-confirmed"], "authority": "Ontology Core", "summary": "Catalog of assistant actions across HUB, OPS Product, ENGINE, and Gateway." },
{ "id": "assistant.risk_policy", "name": "Assistant Risk Policy", "surface": "assistant", "status": ["product-required", "owner-confirmed"], "authority": "Ontology Core", "summary": "Risk classification and hard-deny policy for assistant actions." },
{ "id": "assistant.app_adapter", "name": "Assistant App Adapter", "surface": "assistant", "status": ["product-required", "pending"], "authority": "Platform Apps", "summary": "Application-owned execution adapter for an approved assistant action." },
{ "id": "assistant.confirmation_policy", "name": "Assistant Confirmation Policy", "surface": "assistant", "status": ["product-required", "owner-confirmed"], "authority": "Ontology Core", "summary": "Rules for when assistant actions require explicit confirmation." },
{ "id": "future.interface_layer", "name": "Future Interface Layer", "surface": "future", "status": ["owner-confirmed", "future-concept"], "authority": "Platform", "summary": "Dedicated automation UI/workview layer." },
{ "id": "future.interface_view", "name": "Interface View", "surface": "future", "status": ["future-concept"], "authority": "Interface Layer", "summary": "Generated/configured view over ontology-backed domain data." },
{ "id": "future.interface_widget", "name": "Interface Widget", "surface": "future", "status": ["future-concept"], "authority": "Interface Layer", "summary": "Map, table, analytics block, form, graph, control, etc." },
{ "id": "future.interface_binding", "name": "Interface Binding", "surface": "future", "status": ["future-concept"], "authority": "Interface Layer/ENGINE", "summary": "Binding from workflow/node output to interface layer." },
{ "id": "future.domain_package", "name": "Domain Ontology Package", "surface": "future", "status": ["future-concept"], "authority": "Ontology Core", "summary": "Domain extension package." },
{ "id": "engine.tech_debt.ops_layer", "name": "ENGINE OpsLayer Tech Debt", "surface": "engine", "status": ["tech-debt-noncanonical"], "authority": "ENGINE", "summary": "Current ENGINE-side operational/runtime layer; not OPS Product." },
{ "id": "engine.tech_debt.ops_agent_instance", "name": "ENGINE Ops Agent Instance", "surface": "engine", "status": ["tech-debt-noncanonical"], "authority": "ENGINE", "summary": "Local runtime agent instance; not OPS Gateway agent.identity." },
{ "id": "engine.tech_debt.agent_monitor_node", "name": "Agent Monitor Node", "surface": "engine", "status": ["tech-debt-noncanonical"], "authority": "ENGINE", "summary": "Current monitor/control UI experiment." },
{ "id": "engine.tech_debt.monitor_profile", "name": "Monitor Profile", "surface": "engine", "status": ["tech-debt-noncanonical"], "authority": "ENGINE", "summary": "Current profile/config around Agent Monitor." },
{ "id": "engine.tech_debt.tender_domain_ui", "name": "Tender Domain UI", "surface": "engine", "status": ["tech-debt-noncanonical"], "authority": "ENGINE", "summary": "Hardcoded tender/procurement UI in ENGINE." },
{ "id": "engine.tech_debt.tender_storage", "name": "Tender Storage", "surface": "engine", "status": ["tech-debt-noncanonical"], "authority": "ENGINE", "summary": "Current domain storage in ENGINE-side implementation." },
{ "id": "engine.tech_debt.tender_ai_review", "name": "Tender AI Review", "surface": "engine", "status": ["tech-debt-noncanonical"], "authority": "ENGINE", "summary": "Current AI review implementation for tender domain." },
{ "id": "engine.tech_debt.ops_tabs_control", "name": "ENGINE OPS Tabs Control", "surface": "engine", "status": ["tech-debt-noncanonical"], "authority": "ENGINE", "summary": "UI/control surface tied to current OpsLayer experiment." }
]
}

31
services/ontology-core/catalog/evidence.json Normal file
View File

@ -0,0 +1,31 @@
{
"version": "0.4-pre",
"updatedAt": "2026-06-19",
"sourceRoots": [
{ "surface": "hub", "path": "/Users/dcconstructions/Downloads/mnt/data/nodedc_launcher", "mode": "read-only source inspection" },
{ "surface": "ops", "path": "/Users/dcconstructions/Downloads/mnt/data/dc_taskmanager/NODEDC_TASKMANAGER", "mode": "read-only source inspection" },
{ "surface": "agent", "path": "/Users/dcconstructions/Downloads/mnt/data/NODEDC_TASKMANAGER_CODEXAPI", "mode": "read-only source inspection" },
{ "surface": "engine", "path": "/Users/dcconstructions/Downloads/mnt/NODEDC/NODEDC_ENGINE_INFRA/nodedc-source", "mode": "read-only source inspection" },
{ "surface": "ontology", "path": "/Users/dcconstructions/Downloads/mnt/NODEDC_ONTOLOGY", "mode": "documentation workspace" }
],
"ledgers": [
{ "id": "ledger.hub_p0", "path": "docs/baseline/EVIDENCE_LEDGER_HUB_P0.md", "entityIds": ["hub.open_contour", "hub.public_pool_context", "hub.public_pool_client", "hub.user", "hub.application", "ndcauth.identity", "ndcauth.session"] },
{ "id": "ledger.ops_p0", "path": "docs/baseline/EVIDENCE_LEDGER_OPS_P0.md", "entityIds": ["ops.workspace", "ops.project", "ops.card", "ops.card_status", "ops.card_priority", "ops.assignee", "ops.card_relation"] },
{ "id": "ledger.ops_gateway_p1", "path": "docs/baseline/EVIDENCE_LEDGER_OPS_GATEWAY_P1.md", "entityIds": ["agent.identity", "agent.token", "agent.grant", "agent.scope", "agent.mcp_tool", "agent.audit_event", "agent.idempotency_key"] },
{ "id": "ledger.engine_dirty_boundary_p1", "path": "docs/baseline/EVIDENCE_LEDGER_ENGINE_DIRTY_BOUNDARY_P1.md", "entityIds": ["engine.tech_debt.ops_layer", "engine.tech_debt.agent_monitor_node", "engine.tech_debt.tender_domain_ui", "future.interface_layer"] },
{ "id": "ledger.engine_workflow_p1", "path": "docs/baseline/EVIDENCE_LEDGER_ENGINE_WORKFLOW_P1.md", "entityIds": ["engine.workflow_l1", "engine.node_l1", "engine.edge_l1", "engine.workflow_l2", "engine.workflow_l2_runtime_id", "engine.l2_execution", "engine.l2_run", "engine.l2_session", "engine.l2_runtime_event"] }
],
"baselineDocs": [
"docs/baseline/CANONICAL_ENTITY_CATALOG.md",
"docs/baseline/RELATION_CATALOG.md",
"docs/baseline/GUARDRAILS.md",
"docs/baseline/TERMS_GLOSSARY.md",
"docs/baseline/IMPLEMENTATION_READINESS.md",
"docs/baseline/OPEN_QUESTIONS.md"
],
"restrictions": [
"Do not ingest env/secrets/runtime/data/storage/logs/dumps.",
"Do not edit HUB/OPS/Gateway/ENGINE source code from this service task.",
"Do not treat browser ChatGPT RFCs as source truth without evidence ledger update."
]
}

108
services/ontology-core/catalog/guardrails.json Normal file
View File

@ -0,0 +1,108 @@
{
"version": "0.4-pre",
"updatedAt": "2026-06-19",
"rules": [
{
"id": "guardrail.ops.must_qualify_ops_term",
"severity": "error",
"summary": "Do not say OPS without specifying OPS Product, OPS Gateway, or ENGINE-side OpsLayer.",
"entityIds": ["ops.card", "agent.identity", "engine.tech_debt.ops_layer"]
},
{
"id": "guardrail.ops.card_is_root_work_object",
"severity": "error",
"summary": "Use ops.card as canonical work object; issue/task/work item are aliases or subtypes.",
"entityIds": ["ops.card", "ops.card_type"]
},
{
"id": "guardrail.hub.open_contour_not_client_context",
"severity": "error",
"summary": "hub.open_contour is not an ordinary hub.client_context.",
"entityIds": ["hub.open_contour", "hub.client_context", "hub.public_pool_client"]
},
{
"id": "guardrail.hub.application_card_not_authority",
"severity": "error",
"summary": "hub.application_card is presentation only; access authority belongs to application_access/grant/exception.",
"entityIds": ["hub.application_card", "hub.application_access", "hub.app_grant", "hub.app_exception"]
},
{
"id": "guardrail.gateway.identity_not_user_or_assistant",
"severity": "error",
"summary": "agent.identity is Gateway execution identity, not human user and not assistant persona.",
"entityIds": ["agent.identity", "hub.user", "assistant.assistant"]
},
{
"id": "guardrail.gateway_enforces_permissions",
"severity": "error",
"summary": "Ontology advises context; OPS Gateway enforces grants, scopes, audit, and idempotency.",
"entityIds": ["agent.grant", "agent.scope", "agent.audit_event", "agent.idempotency_key", "assistant.bridge"]
},
{
"id": "guardrail.engine.l1_l2_runtime_ids_are_distinct",
"severity": "error",
"summary": "engine.workflow_l1 id, engine.workflow_l2, and engine.workflow_l2_runtime_id are distinct concepts.",
"entityIds": ["engine.workflow_l1", "engine.workflow_l2", "engine.workflow_l2_runtime_id"]
},
{
"id": "guardrail.engine.ops_layer_noncanonical",
"severity": "error",
"summary": "ENGINE-side OpsLayer/Agent Monitor/tender UI are current tech debt and must not define OPS Product ontology.",
"entityIds": ["engine.tech_debt.ops_layer", "engine.tech_debt.agent_monitor_node", "engine.tech_debt.tender_domain_ui", "ops.card"]
},
{
"id": "guardrail.interface_layer_not_engine_core_ui",
"severity": "warning",
"summary": "Future automation UI belongs in a dedicated Interface Layer, not hardcoded inside ENGINE core.",
"entityIds": ["future.interface_layer", "future.interface_view", "future.interface_binding", "engine.workflow_l1"]
},
{
"id": "guardrail.assistant_role_never_bypasses_launcher_scope",
"severity": "error",
"summary": "Assistant admin role unlocks assistant-admin commands only inside existing Launcher root/client admin scope.",
"entityIds": ["assistant.access_role", "assistant.admin_scope", "hub.membership", "hub.role"]
},
{
"id": "guardrail.assistant_blocked_hides_all_surfaces",
"severity": "error",
"summary": "Blocked assistant access means no assistant icon/surface and no assistant capability in HUB, OPS Product, ENGINE, or Gateway flows.",
"entityIds": ["assistant.core_access", "assistant.access_role", "assistant.capability"]
},
{
"id": "guardrail.assistant_member_not_admin",
"severity": "error",
"summary": "Assistant member mode allows personal/basic assistant use but not user, role, invite, or cross-user access administration.",
"entityIds": ["assistant.access_role", "assistant.capability", "hub.user", "hub.invite"]
},
{
"id": "guardrail.assistant_actions_must_be_registered",
"severity": "error",
"summary": "Assistant must resolve user requests to registered action cards before policy checks or execution.",
"entityIds": ["assistant.action_registry", "assistant.action", "assistant.action_request"]
},
{
"id": "guardrail.assistant_never_hard_deletes",
"severity": "error",
"summary": "Assistant actions must not hard-delete users, records, database rows, files, or production state.",
"entityIds": ["assistant.action", "assistant.risk_policy", "hub.user", "ops.card", "engine.workflow_l1"]
},
{
"id": "guardrail.assistant_no_self_lockout",
"severity": "error",
"summary": "Assistant must not allow a user to remove, block, or disable their own last admin/access path.",
"entityIds": ["assistant.action", "assistant.admin_scope", "hub.membership", "hub.user"]
}
],
"blockedConflations": [
["ops.card", "engine.tech_debt.ops_layer"],
["agent.identity", "hub.user"],
["agent.identity", "assistant.assistant"],
["assistant.access_role", "hub.role"],
["assistant.admin_scope", "agent.grant"],
["assistant.action", "assistant.capability"],
["hub.open_contour", "hub.client_context"],
["hub.application_card", "hub.application_access"],
["engine.workflow_l1", "engine.workflow_l2_runtime_id"],
["future.interface_layer", "engine.tech_debt.tender_domain_ui"]
]
}

81
services/ontology-core/catalog/relations.json Normal file
View File

@ -0,0 +1,81 @@
{
"version": "0.4-pre",
"updatedAt": "2026-06-19",
"relations": [
{ "id": "hub.open_contour.uses_public_pool", "from": ["hub.open_contour"], "to": ["hub.public_pool_context"], "status": "source-evidenced", "summary": "Open contour is implemented through public pool context." },
{ "id": "hub.public_pool_context.backed_by_client", "from": ["hub.public_pool_context"], "to": ["hub.public_pool_client"], "status": "source-confirmed", "summary": "Public pool context uses special source-backed Client." },
{ "id": "hub.user.has_membership", "from": ["hub.user"], "to": ["hub.membership"], "status": "source-confirmed", "summary": "User belongs to context through membership." },
{ "id": "hub.membership.in_context", "from": ["hub.membership"], "to": ["hub.client_context", "hub.public_pool_context"], "status": "source-confirmed", "summary": "Membership points to closed client context or public pool." },
{ "id": "hub.access_request.targets_context", "from": ["hub.access_request"], "to": ["hub.client_context", "hub.public_pool_context"], "status": "source-confirmed", "summary": "Request targets a context." },
{ "id": "hub.public_access_request.promotes_to_client_context", "from": ["hub.public_access_request"], "to": ["hub.client_context"], "status": "source-confirmed", "summary": "Public request can become client membership after approval." },
{ "id": "hub.invite.targets_context", "from": ["hub.invite"], "to": ["hub.client_context", "hub.public_pool_context"], "status": "source-confirmed", "summary": "Invite targets a context." },
{ "id": "hub.application.has_access_result", "from": ["hub.application"], "to": ["hub.application_access"], "status": "source-confirmed", "summary": "Application exposes effective access state." },
{ "id": "hub.app_grant.grants_access_to", "from": ["hub.app_grant"], "to": ["hub.application"], "status": "source-confirmed", "summary": "Grant contributes to effective access." },
{ "id": "hub.app_exception.overrides_access_to", "from": ["hub.app_exception"], "to": ["hub.application"], "status": "source-confirmed", "summary": "User-specific allow/deny exception." },
{ "id": "hub.application_card.presents", "from": ["hub.application_card"], "to": ["hub.application"], "status": "source-confirmed", "summary": "UI card presents app plus access state." },
{ "id": "ndcauth.identity.maps_to_hub_user", "from": ["ndcauth.identity"], "to": ["hub.user"], "status": "source-confirmed", "summary": "Auth subject resolves to launcher user." },
{ "id": "ops.workspace.contains_project", "from": ["ops.workspace"], "to": ["ops.project"], "status": "source-confirmed", "summary": "Project belongs to workspace." },
{ "id": "ops.workspace.has_member", "from": ["ops.workspace"], "to": ["ops.workspace_member"], "status": "source-confirmed", "summary": "Workspace membership." },
{ "id": "ops.project.has_member", "from": ["ops.project"], "to": ["ops.project_member"], "status": "source-confirmed", "summary": "Project membership." },
{ "id": "ops.project.contains_card", "from": ["ops.project"], "to": ["ops.card"], "status": "source-confirmed", "summary": "Card belongs to project." },
{ "id": "ops.card.has_status", "from": ["ops.card"], "to": ["ops.card_status"], "status": "source-confirmed", "summary": "Card state." },
{ "id": "ops.card.has_priority", "from": ["ops.card"], "to": ["ops.card_priority"], "status": "source-confirmed", "summary": "Card priority attribute." },
{ "id": "ops.card.assigned_to", "from": ["ops.card"], "to": ["ops.assignee"], "status": "source-confirmed", "summary": "Card assignment." },
{ "id": "ops.card.accountable_to", "from": ["ops.card"], "to": ["ops.responsible"], "status": "product-required", "summary": "Product-level responsibility relation." },
{ "id": "ops.card.typed_as", "from": ["ops.card"], "to": ["ops.card_type"], "status": "source-evidenced", "summary": "Card subtype/purpose." },
{ "id": "ops.card.related_to", "from": ["ops.card"], "to": ["ops.card_relation"], "status": "source-confirmed", "summary": "Relation/dependency between cards." },
{ "id": "ops.card.has_label", "from": ["ops.card"], "to": ["ops.card_label"], "status": "source-confirmed", "summary": "Label/tag classification." },
{ "id": "ops.card.has_comment", "from": ["ops.card"], "to": ["ops.card_comment"], "status": "source-confirmed", "summary": "Discussion/comment relation." },
{ "id": "ops.card.has_activity", "from": ["ops.card"], "to": ["ops.card_activity"], "status": "source-evidenced", "summary": "Timeline/change relation." },
{ "id": "ops.card.links_artifact", "from": ["ops.card"], "to": ["ops.card_artifact_link"], "status": "source-evidenced", "summary": "Links output artifacts or docs." },
{ "id": "ops.card.has_external_ref", "from": ["ops.card"], "to": ["ops.external_ref"], "status": "source-confirmed", "summary": "Links external/source object." },
{ "id": "agent.token.represents_identity", "from": ["agent.token"], "to": ["agent.identity"], "status": "source-confirmed", "summary": "Token authenticates agent identity, not user identity." },
{ "id": "agent.identity.has_grant", "from": ["agent.identity"], "to": ["agent.grant"], "status": "source-confirmed", "summary": "Identity receives grants." },
{ "id": "agent.token.has_token_grant", "from": ["agent.token"], "to": ["agent.token_grant"], "status": "source-confirmed", "summary": "Token-level grant binding." },
{ "id": "agent.grant.allows_scope", "from": ["agent.grant"], "to": ["agent.scope"], "status": "source-confirmed", "summary": "Grant enables tool/capability scope." },
{ "id": "agent.scope.exposes_tool", "from": ["agent.scope"], "to": ["agent.mcp_tool"], "status": "source-confirmed", "summary": "Scope controls MCP tool exposure." },
{ "id": "agent.mcp_tool.writes_via_adapter", "from": ["agent.mcp_tool"], "to": ["agent.tasker_adapter"], "status": "source-confirmed", "summary": "Gateway writes to OPS through adapter." },
{ "id": "agent.mcp_tool.requires_idempotency", "from": ["agent.mcp_tool"], "to": ["agent.idempotency_key"], "status": "source-confirmed", "summary": "Write operations require idempotency." },
{ "id": "agent.mcp_tool.emits_audit", "from": ["agent.mcp_tool"], "to": ["agent.audit_event"], "status": "source-confirmed", "summary": "Operations produce audit records." },
{ "id": "agent.setup_packet.provisions_token", "from": ["agent.setup_packet"], "to": ["agent.token"], "status": "source-evidenced", "summary": "Setup flow produces token/connect config." },
{ "id": "engine.workflow_l1.contains_node", "from": ["engine.workflow_l1"], "to": ["engine.node_l1"], "status": "source-confirmed", "summary": "L1 workflow graph contains nodes." },
{ "id": "engine.workflow_l1.contains_edge", "from": ["engine.workflow_l1"], "to": ["engine.edge_l1"], "status": "source-confirmed", "summary": "L1 workflow graph contains edges." },
{ "id": "engine.edge_l1.connects_nodes", "from": ["engine.edge_l1"], "to": ["engine.node_l1"], "status": "source-confirmed", "summary": "Edge connects source/target node handles." },
{ "id": "engine.node_l1.has_type", "from": ["engine.node_l1"], "to": ["engine.node_type_l1"], "status": "source-confirmed", "summary": "Node type comes from registry/module." },
{ "id": "engine.workflow_l1.has_acl", "from": ["engine.workflow_l1"], "to": ["engine.workflow_acl"], "status": "source-confirmed", "summary": "Workflow uses access control." },
{ "id": "engine.workflow_acl.has_owner", "from": ["engine.workflow_acl"], "to": ["engine.workflow_owner"], "status": "source-confirmed", "summary": "ACL owns owner field." },
{ "id": "engine.workflow_l1.has_share", "from": ["engine.workflow_l1"], "to": ["engine.workflow_share"], "status": "source-confirmed", "summary": "Workflow can be shared/invited." },
{ "id": "engine.workflow_l1.has_access_request", "from": ["engine.workflow_l1"], "to": ["engine.workflow_access_request"], "status": "source-confirmed", "summary": "Access requests target workflow." },
{ "id": "engine.node_l1.embeds_l2_workflow", "from": ["engine.node_l1"], "to": ["engine.workflow_l2"], "status": "source-evidenced", "summary": "n8n subworkflow is attached to L1 node." },
{ "id": "engine.workflow_l2.deployed_as_runtime_workflow", "from": ["engine.workflow_l2"], "to": ["engine.workflow_l2_runtime_id"], "status": "source-confirmed", "summary": "Compiled n8n workflow deploy returns runtime workflow id." },
{ "id": "engine.workflow_l2.runs_on_runtime_core", "from": ["engine.workflow_l2"], "to": ["engine.l2_runtime_core"], "status": "source-evidenced", "summary": "L2 workflow targets n8n instance/core." },
{ "id": "engine.l2_execution.belongs_to_runtime_workflow", "from": ["engine.l2_execution"], "to": ["engine.workflow_l2_runtime_id"], "status": "source-confirmed", "summary": "Execution is emitted for n8n workflow id." },
{ "id": "engine.l2_runtime_event.describes_execution", "from": ["engine.l2_runtime_event"], "to": ["engine.l2_execution"], "status": "source-confirmed", "summary": "Runtime events carry execution id." },
{ "id": "engine.l2_runtime_event.binds_run", "from": ["engine.l2_runtime_event"], "to": ["engine.l2_run"], "status": "source-confirmed", "summary": "Event binds to run id. Current storage is ENGINE-side OpsLayer." },
{ "id": "engine.l2_run.has_session", "from": ["engine.l2_run"], "to": ["engine.l2_session"], "status": "source-confirmed", "summary": "Session anchors related runtime events/runs." },
{ "id": "assistant.core_access.assigned_by_role_assignment", "from": ["assistant.core_access"], "to": ["assistant.role_assignment"], "status": "product-required", "summary": "Assistant access is materialized as a scoped role assignment." },
{ "id": "assistant.role_assignment.targets_user", "from": ["assistant.role_assignment"], "to": ["hub.user"], "status": "product-required", "summary": "Assistant role assignment targets a HUB user." },
{ "id": "assistant.role_assignment.has_role", "from": ["assistant.role_assignment"], "to": ["assistant.access_role"], "status": "product-required", "summary": "Assignment grants one assistant access role." },
{ "id": "assistant.role_assignment.scoped_to_context", "from": ["assistant.role_assignment"], "to": ["hub.client_context", "hub.public_pool_context"], "status": "product-required", "summary": "Assistant role assignment may be scoped to a client or public-pool context." },
{ "id": "assistant.access_role.allows_capability", "from": ["assistant.access_role"], "to": ["assistant.capability"], "status": "product-required", "summary": "Role contributes assistant capabilities before scope guards are applied." },
{ "id": "assistant.permission_policy.derives_admin_scope", "from": ["assistant.permission_policy"], "to": ["assistant.admin_scope"], "status": "source-evidenced", "summary": "Policy derives assistant-admin authority from Launcher admin scope." },
{ "id": "assistant.admin_scope.derived_from_hub_membership", "from": ["assistant.admin_scope"], "to": ["hub.membership", "hub.role"], "status": "source-evidenced", "summary": "Client admin scope comes from active client_owner/client_admin membership." },
{ "id": "assistant.action_request.checked_by_permission_policy", "from": ["assistant.action_request"], "to": ["assistant.permission_policy"], "status": "product-required", "summary": "Requested assistant action must pass assistant policy first." },
{ "id": "assistant.action_request.executes_through_bridge", "from": ["assistant.action_request"], "to": ["assistant.bridge", "agent.mcp_tool"], "status": "product-required", "summary": "Approved assistant action still executes through bridge/gateway tooling." },
{ "id": "assistant.action_registry.contains_action", "from": ["assistant.action_registry"], "to": ["assistant.action"], "status": "product-required", "summary": "Registry owns declarative assistant action cards." },
{ "id": "assistant.action.classified_by_risk_policy", "from": ["assistant.action"], "to": ["assistant.risk_policy"], "status": "product-required", "summary": "Every assistant action has risk classification and policy gates." },
{ "id": "assistant.action.requires_confirmation_policy", "from": ["assistant.action"], "to": ["assistant.confirmation_policy"], "status": "product-required", "summary": "Action card declares confirmation requirements before execution." },
{ "id": "assistant.action.executed_by_adapter", "from": ["assistant.action"], "to": ["assistant.app_adapter"], "status": "product-required", "summary": "Application-owned adapter executes an approved action." },
{ "id": "assistant.action_request.resolves_to_action", "from": ["assistant.action_request"], "to": ["assistant.action"], "status": "product-required", "summary": "Natural-language request must resolve to a known action card before any execution." },
{ "id": "ontology.resolves_ops_card_to_engine_context", "from": ["ops.card"], "to": ["engine.workflow_l1", "engine.workflow_l2"], "status": "product-required", "summary": "Assistant in OPS can route a request to Engine workflow context." },
{ "id": "ontology.resolves_engine_context_to_ops_project", "from": ["engine.workflow_l1", "engine.workflow_l2"], "to": ["ops.project"], "status": "product-required", "summary": "Assistant in Engine can create/update cards in the correct OPS project." },
{ "id": "ontology.resolves_hub_app_to_project_context", "from": ["hub.application"], "to": ["ops.project", "engine.workflow_l1"], "status": "product-required", "summary": "Application selection can suggest project/workflow context." },
{ "id": "ontology.selects_gateway_grant_context", "from": ["assistant.bridge"], "to": ["agent.grant"], "status": "product-required", "summary": "Ontology can help choose proper MCP/Gateway grant before tool calls." },
{ "id": "ontology.routes_interface_view_to_domain_package", "from": ["future.interface_view"], "to": ["future.domain_package"], "status": "future-concept", "summary": "Future UI layer renders domain-specific views from ontology-backed data." }
]
}

51
services/ontology-core/catalog/resolver-rules.json Normal file
View File

@ -0,0 +1,51 @@
{
"version": "0.1.0",
"updatedAt": "2026-06-19",
"rules": [
{
"id": "resolver.ops_to_engine.workflow_context",
"relationId": "ontology.resolves_ops_card_to_engine_context",
"fromSurface": "ops",
"inputEntityIds": ["ops.card", "ops.project"],
"intentHints": ["engine", "workflow", "l1", "l2", "n8n", "inspect", "switch", "runtime", "докодим", "воркфлоу"],
"outputSurface": "engine",
"outputEntityIds": ["engine.workflow_l1", "engine.node_l1", "engine.workflow_l2", "engine.workflow_l2_runtime_id"],
"requiredBindings": [
"ops.card -> ops.external_ref -> engine.workflow_l1|engine.workflow_l2",
"ops.project -> hub.application|engine.workflow_l1 context"
],
"status": "product-required",
"summary": "Route an OPS card/project request into Engine workflow context."
},
{
"id": "resolver.engine_to_ops.card_context",
"relationId": "ontology.resolves_engine_context_to_ops_project",
"fromSurface": "engine",
"inputEntityIds": ["engine.workflow_l1", "engine.node_l1", "engine.workflow_l2", "engine.l2_runtime_event"],
"intentHints": ["ops", "card", "task", "issue", "project", "report", "создай", "карточ", "задач"],
"outputSurface": "ops",
"outputEntityIds": ["ops.workspace", "ops.project", "ops.card", "ops.card_type"],
"requiredBindings": [
"engine.workflow_l1 -> ops.project",
"engine.workflow_l1|engine.node_l1 -> ops.card external_ref"
],
"status": "product-required",
"summary": "Route an Engine workflow/node request into OPS project/card context."
},
{
"id": "resolver.gateway_preflight.context_grant",
"relationId": "ontology.selects_gateway_grant_context",
"fromSurface": "assistant",
"inputEntityIds": ["assistant.bridge", "assistant.executor"],
"intentHints": ["mcp", "gateway", "grant", "tool", "token"],
"outputSurface": "agent",
"outputEntityIds": ["agent.grant", "agent.scope", "agent.mcp_tool", "agent.idempotency_key"],
"requiredBindings": [
"assistant.bridge -> target surface context",
"target context -> agent.grant"
],
"status": "product-required",
"summary": "Suggest Gateway grant/tool context before MCP calls; Gateway remains enforcement authority."
}
]
}

104
services/ontology-core/docs/ASSISTANT_ACCESS_POLICY.md Normal file
View File

@ -0,0 +1,104 @@
# NDC Core Assistant Access Policy
Status: draft source-evidenced slice.
This document defines assistant access as a thin policy overlay over the existing HUB/Launcher admin model. It does not replace Launcher roles, OPS Product permissions, Engine ACLs, or OPS Gateway grants.
## Roles
`assistant_blocked`
- no assistant icon;
- no assistant surface in HUB, OPS Product, ENGINE, or Gateway-mediated flows;
- no assistant capabilities.
`assistant_member`
- default for active users;
- matches the current personal assistant expectation;
- can use assistant in the user's allowed contexts;
- cannot manage users, invites, memberships, access requests, or other users' access.
`assistant_admin`
- enables assistant-mediated admin commands;
- works only when existing Launcher admin scope is present;
- never creates Launcher admin scope by itself;
- client admins stay inside their client scope;
- root-only backend operations stay root-only.
## Source-backed Launcher rules
Current HUB/Launcher source model has these authority inputs:
- `LauncherGlobalRole`: `root_admin`, `support_admin`, `client_owner`, `client_admin`, `member`;
- `LauncherUserStatus`: `invited`, `active`, `blocked`;
- `ClientMembershipRole`: `client_owner`, `client_admin`, `member`;
- `ClientMembershipStatus`: `active`, `disabled`.
Backend admin scope is source-backed by:
- root groups: `nodedc:superadmin`, `nodedc:launcher:admin`;
- active client admin membership: `client_owner` or `client_admin`;
- guard functions: `requireLauncherAdmin`, `requireRootLauncherAdmin`, `assertAdminCanManageClient`, `assertAdminCanManageUser`, `assertAdminCanManageAccessForUser`.
The important rule: `assistant_admin` can request only actions that the same user could already perform manually through Launcher admin endpoints.
## Practical first use case
The first useful implementation target is assistant-mediated access management:
- "block user X in Operational Core";
- "change user X to member/admin in this client";
- "show pending invites for today";
- "grant user X member access to this Operational Core workspace";
- "grant user X member/viewer access to this Operational Core project".
These are practical because Launcher already exposes equivalent manual flows in the admin overlay:
- MAIN status;
- MAIN role;
- service access matrix;
- Operational Core workspace/project memberships;
- invites;
- access requests.
## Hard denies
The assistant policy must keep these hard-deny rules:
- blocked assistant access hides all assistant UI and capabilities;
- blocked Launcher user means no effective assistant access;
- disabled membership removes context admin authority;
- `assistant_member` cannot administer users/access;
- `assistant_admin` does not bypass Launcher admin scope;
- protected `user_root` remains protected by source guards;
- Task Manager/Operational Core `admin` role is currently locked in Launcher mutation routes;
- root-only endpoints stay root-only.
## Planned HUB UI shape
The proposed Launcher admin UI addition is a column/control named `NDC Core Assistant`.
Initial values:
- `Blocked`;
- `Member`;
- `Admin`.
Recommended default:
- active ordinary users: `Member`;
- blocked users: effective `Blocked`;
- superadmin/root: effective `Admin`;
- explicit assignment should be stored later as assistant role assignment, not as a replacement for Launcher role.
## CLI checks
```text
npm run smoke:assistant-policy
npm run assistant:policy -- --input-json examples/assistant-access-member.example.json
npm run assistant:policy -- --input-json examples/assistant-access-admin-client.example.json
npm run assistant:policy -- --input-json examples/assistant-access-blocked.example.json
npm run assistant:policy -- --input-json examples/assistant-access-superadmin.example.json
```

184
services/ontology-core/docs/ASSISTANT_ACTION_REGISTRY.md Normal file
View File

@ -0,0 +1,184 @@
# Assistant Action Registry
Status: draft implementation contract.
Date: 2026-06-19
This document defines the scalable execution model for NDC Core Assistant actions.
The assistant must not grow through prompt-only rules. Every executable or refusible command should resolve to a registered action card, pass assistant access policy, pass risk policy, and then route to an app-owned adapter.
## Execution Pipeline
```mermaid
flowchart LR
A["User request"] --> B["Action resolver"]
B --> C["Ontology context"]
C --> D["Assistant access policy"]
D --> E["Risk policy"]
E --> F["App-owned adapter"]
F --> G["Confirmation"]
G --> H["Audit / idempotent execution"]
```
The resolver can return:
- `action_not_registered`: no action card exists;
- `forbidden`: the action is destructive or explicitly forbidden;
- `denied`: the actor lacks capability, admin scope, or self-action safety;
- `needs_confirmation`: policy allows the action, but explicit confirmation is required;
- `future_adapter`: the correct app boundary is known, but the adapter is not implemented yet;
- `allowed`: policy allows the action. `execution.executionReady` is true only when the adapter is implemented.
## Action Card
Action cards live in:
```text
catalog/assistant-actions.json
```
Each action card must define:
- `id`: stable action id, for example `hub.user.block`;
- `app`: authority boundary: `hub`, `ops`, `engine`, or `gateway`;
- `domain`: local functional area;
- `intentAliases`: phrases the resolver can match;
- `entityIds`: ontology entities touched by the action;
- `capabilityIds`: assistant capabilities required from `assistant-access-policy.json`;
- `riskLevel`: `read`, `write`, `privileged`, `destructive`, `root_only`, or `future`;
- `confirmationMode`: `none`, `explicit`, `typed`, or `forbidden`;
- `selfActionPolicy`: `allowed`, `blocked`, `no_self_lockout`, or `app_owned`;
- `requiredScopes`: source-app scope checks required for privileged actions;
- `adapterId` and `adapterStatus`: the app-owned execution boundary;
- `hardDenyIds` and `safeAlternativeActionIds` when relevant.
The validator rejects dangling entity, capability, risk, adapter-status, hard-deny, and safe-alternative references.
## App Boundaries
HUB / Launcher owns:
- entry access;
- users;
- client memberships;
- invites;
- service access matrix;
- NDC Core Assistant role assignment.
OPS Product owns:
- workspaces;
- projects;
- cards;
- workspace/project membership;
- OPS-internal role rules.
ENGINE owns:
- workflow context;
- workflow ACL;
- workflow sharing;
- runtime/workflow source of truth.
OPS Gateway owns:
- tool grants;
- MCP/tool scope selection;
- idempotency;
- audit envelope;
- adapter execution routing.
HUB may route to OPS or ENGINE, but must not directly mutate OPS Product roles or ENGINE workflow ACLs. Those mutations must go through app-owned adapters.
## Hard Denies
The assistant must never:
- delete HUB users;
- hard-delete database records, files, storage, backups, runtime data, or production state;
- let an actor remove their own last admin/access path;
- mutate app-owned roles through the wrong app boundary;
- execute a write command from prompt text alone without a registered action card.
Preferred safe alternatives:
- block a user instead of deleting the user;
- disable a membership instead of deleting access records;
- update/close an OPS card instead of deleting it;
- route ENGINE workflow ACL changes to an Engine-owned adapter.
## First Practical Block
The first implementation block should be HUB access administration:
- read admin-visible user/access summaries;
- list pending invites;
- block/unblock users;
- disable memberships;
- change `NDC Core Assistant` role between `blocked`, `member`, and `admin`.
This is the lowest-risk useful block because the Launcher already has manual admin flows and backend guards. The assistant adapter should call the same guarded routes and add idempotency/audit around them.
## Adding A New Functional Block
To add another block without prompt sprawl:
1. Add or reuse canonical entities in `catalog/entities.json`.
2. Add required capabilities to `catalog/assistant-access-policy.json`.
3. Add action cards to `catalog/assistant-actions.json`.
4. Classify risk and confirmation using `catalog/assistant-risk-policy.json`.
5. Add examples under `examples/assistant-action-*.json`.
6. Run validation and smoke tests.
7. Only then implement the app-owned adapter.
Commands:
```text
npm run validate
npm run smoke:assistant-policy
npm run smoke:assistant-actions
npm run smoke:assistant-action-plan
npm run smoke:assistant-caller
npm run smoke:assistant-executor
npm run assistant:action -- --input-json examples/assistant-action-block-user.example.json
npm run assistant:plan -- --input-json examples/assistant-action-block-user.example.json
npm run assistant:caller -- --input-json examples/assistant-caller-preview-block-user.example.json
npm run assistant:execute -- --input-json examples/assistant-action-block-user.example.json
```
## Current Limitation
Many non-HUB action cards are currently `adapterStatus=planned` or `adapterStatus=future`.
That is intentional. The ontology core can already answer whether an action is conceptually registered and policy-allowed, but actual mutation must wait for the app-owned adapter implementation.
The current HUB adapter maps the first implemented allowlist block:
```text
src/adapters/hub-launcher-admin.mjs
```
It maps allowed HUB actions to guarded Launcher backend routes:
- `GET /api/admin/control-plane`;
- `PATCH /api/admin/users/:userId/profile`;
- `PATCH /api/admin/memberships/:membershipId`.
It intentionally does not map existing Launcher `DELETE` routes. Deletion requests resolve to `forbidden` before a request plan is produced.
The UI/caller contract lives in:
```text
src/assistant-action-caller.mjs
docs/ASSISTANT_CALLER_CONTRACT.md
```
Callers should use it for preview/execute flows instead of calling the low-level executor directly.
The execution gateway lives in:
```text
src/assistant-action-executor.mjs
```
It defaults to dry-run, validates the request plan, requires confirmation tokens for write execution, and refuses network execution until the specific adapter is marked `implemented`.

157
services/ontology-core/docs/ASSISTANT_CALLER_CONTRACT.md Normal file
View File

@ -0,0 +1,157 @@
# Assistant Caller Contract
Status: first UI/caller contract.
Date: 2026-06-19
This contract sits above the low-level execution gateway. UI and assistant surfaces should call this layer instead of calling the executor directly.
## Phases
`preview`
- resolves the requested action;
- runs policy and route safety checks;
- does not make network requests;
- returns a compact preview for UI;
- returns a `confirmation.token` for write actions.
`execute`
- requires the same action input;
- requires `confirmationToken` for write actions;
- requires Launcher internal token for HUB gateway execution;
- returns a normalized execution result.
## Preview Request
```json
{
"phase": "preview",
"input": {
"actionId": "hub.user.block",
"assistantRole": "admin",
"membershipRole": "client_admin",
"actorUserId": "user_root",
"targetUserId": "user_silver_psih",
"confirmed": true,
"idempotencyKey": "ui:block:user_silver_psih:2026-06-19"
}
}
```
CLI:
```text
npm run assistant:caller -- --input-json examples/assistant-caller-preview-block-user.example.json
```
## Preview Response
Write preview returns:
```json
{
"ok": true,
"phase": "preview",
"decision": "preview_ready",
"preview": {
"app": "hub",
"actionId": "hub.user.block",
"riskLevel": "privileged",
"expectedEffect": "Block HUB user account through existing Launcher admin guards.",
"request": {
"method": "PATCH",
"path": "/api/admin/users/user_silver_psih/profile",
"body": {
"globalStatus": "blocked"
}
}
},
"confirmation": {
"token": "<preview token>",
"request": {
"method": "PATCH",
"path": "/api/admin/users/user_silver_psih/profile",
"idempotencyKey": "ui:block:user_silver_psih:2026-06-19"
}
},
"execution": {
"requiresUserConfirmation": true,
"requiresInternalToken": true
}
}
```
The UI must show the exact app/action/target/effect before execute. It must not silently execute privileged write previews.
## Execute Request
```json
{
"phase": "execute",
"confirmationToken": "<preview token>",
"input": {
"actionId": "hub.user.block",
"assistantRole": "admin",
"membershipRole": "client_admin",
"actorUserId": "user_root",
"targetUserId": "user_silver_psih",
"confirmed": true,
"idempotencyKey": "ui:block:user_silver_psih:2026-06-19"
}
}
```
CLI:
```text
NDC_LAUNCHER_INTERNAL_ACCESS_TOKEN=... npm run assistant:caller -- --base-url http://launcher.local.nodedc --input-json request.json
```
## Execute Response
Successful execution returns:
```json
{
"ok": true,
"phase": "execute",
"decision": "executed",
"result": {
"status": 200,
"method": "PATCH"
}
}
```
Blocked execution returns:
```json
{
"ok": false,
"phase": "execute",
"decision": "execution_blocked",
"reason": "write_confirmation_envelope_missing"
}
```
## Rules For Callers
- Never call `execute` for write actions without first showing `preview`.
- Never generate or modify `confirmationToken` in UI.
- Never reuse a token after changing action input, target, body, idempotency key, or actor.
- Never map delete requests to hidden alternatives. Show the refusal and safe alternatives from preview.
- Keep app ownership visible: HUB actions mutate HUB/Launcher only; OPS and ENGINE actions require their own adapters.
## Tests
```text
npm run smoke:assistant-caller
```
The smoke test covers:
- write preview returns confirmation token;
- execute without token is blocked;
- execute with token and mock internal token reaches the adapter;
- read preview does not require confirmation token.

171
services/ontology-core/docs/ASSISTANT_EXECUTION_GATEWAY.md Normal file
View File

@ -0,0 +1,171 @@
# Assistant Execution Gateway
Status: first HUB gateway execution path implemented.
Date: 2026-06-19
This document defines the execution boundary after an assistant request resolves to an action card and an app-owned request plan.
The gateway exists to keep assistant execution out of prompt-only logic. It is a code-level safety boundary.
UI and assistant surfaces should call the higher-level caller contract first:
```text
docs/ASSISTANT_CALLER_CONTRACT.md
src/assistant-action-caller.mjs
```
The low-level executor remains the final safety gate.
## Modes
`dry-run`
- default mode;
- builds the action plan;
- validates route/method/idempotency safety;
- for write requests, returns a confirmation envelope and token;
- does not make network requests.
`execute`
- available only when the caller explicitly passes execution mode;
- requires network execution to be enabled;
- requires `baseUrl`;
- refuses planned/future adapters unless an explicit unsafe dev override is set;
- for write requests, requires a matching confirmation envelope token from a previous preview;
- for `adapter.hub.launcher_admin_api`, requires Launcher internal token and assistant actor identity headers;
- still refuses forbidden/destructive actions and non-allowlisted routes.
## Current CLI
Dry-run:
```text
npm run assistant:execute -- --input-json examples/assistant-action-block-user.example.json
```
For write actions, dry-run returns:
```text
confirmationEnvelope.token: <preview token>
```
Attempted network execution:
```text
npm run assistant:execute -- --execute --base-url http://launcher.local.nodedc --input-json examples/assistant-action-block-user.example.json
```
For write actions, execution without the preview token returns:
```text
decision: execution_blocked
reason: write_confirmation_envelope_missing
```
Live write execution requires both:
- the matching `--confirmation-token` from dry-run;
- `NDC_LAUNCHER_INTERNAL_ACCESS_TOKEN` or `NODEDC_INTERNAL_ACCESS_TOKEN`;
- an input actor.
```text
NDC_LAUNCHER_INTERNAL_ACCESS_TOKEN=... npm run assistant:execute -- --execute --confirmation-token <preview token> --base-url http://launcher.local.nodedc --input-json examples/assistant-action-block-user.example.json
```
The executor sends the token as `Authorization: Bearer ...` plus:
```text
X-NODEDC-Assistant-Gateway: ontology-core
X-NODEDC-Assistant-Actor-User-Id: <actorUserId>
```
The Launcher BFF accepts this server-to-server path only for the allowlisted routes below. The actor still has to resolve to an active Launcher user with Launcher admin scope, and the request still passes the source route guards.
## Safety Checks
The executor validates:
- the plan is `ok`;
- method is allowlisted;
- path is under `/api/admin/`;
- route is explicitly allowlisted;
- `DELETE` is always forbidden;
- write requests include `Idempotency-Key`;
- write requests passed prior confirmation checks;
- write execution includes a matching confirmation envelope token;
- destructive/forbidden action decisions cannot execute;
- adapter safety flags are present.
Current HUB allowlist:
```text
GET /api/admin/control-plane
PATCH /api/admin/users/:userId/profile
PATCH /api/admin/memberships/:membershipId
```
## Execution Readiness
The current implementation is still conservative:
- action cards can be policy-allowed;
- request plans can be generated;
- executor can dry-run, return write confirmation envelope, and mock-execute;
- real network execution is available only for implemented HUB allowlist actions and only with gateway auth headers.
## Launcher Route Readiness
Current Launcher BFF status for the first HUB block:
- `GET /api/admin/control-plane` is behind `requireLauncherAdmin`;
- `PATCH /api/admin/users/:userId/profile` is behind `requireLauncherAdmin` and `assertAdminCanManageUser`;
- `PATCH /api/admin/memberships/:membershipId` is behind `requireLauncherAdmin` and `assertAdminCanManageMembership`;
- if no browser session exists, `requireLauncherAdmin` accepts assistant gateway auth only for the three allowlisted routes;
- assistant gateway auth requires the shared internal token and `X-NODEDC-Assistant-Gateway: ontology-core`;
- gateway actor identity is passed through `X-NODEDC-Assistant-Actor-*` headers and resolved to a real Launcher user before admin scope checks;
- both PATCH routes emit control-plane audit through `controlPlaneStore`;
- both PATCH routes now use an `Idempotency-Key` envelope with replay and conflict behavior;
- Launcher contract tests cover these route/guard/idempotency invariants.
The idempotency envelope is process-local and intended to protect immediate retries/replays. It is enough for the current local assistant execution scaffold. A persistent gateway-level idempotency ledger should be added before distributed or multi-process production execution.
The following HUB actions are marked `implemented` because they map only to the current allowlist:
```text
hub.user.read_admin_summary
hub.invite.list_pending
hub.user.block
hub.user.unblock
hub.membership.change_role
hub.membership.disable
hub.assistant_access.change_role
```
OPS, ENGINE, Gateway-level action resolver, and broader admin routes remain `planned` or `future`.
To mark a route production-ready:
1. Verify source app guards directly.
2. Verify auth identity propagation.
3. Verify audit event output.
4. Verify idempotency behavior.
5. Add integration tests against local Launcher.
6. Change only the specific action adapter status to `implemented`.
7. Keep the route in both executor and Launcher BFF allowlists.
## Tests
```text
npm run smoke:assistant-executor
```
The smoke test covers:
- default dry-run;
- write confirmation envelope generation;
- write execution blocked without confirmation envelope token;
- implemented adapter blocking execution without internal token;
- mock execution through allowlisted PATCH route with gateway auth headers;
- delete action blocked before network;
- corrupted DELETE plan rejected by safety validation.

91
services/ontology-core/docs/CONTEXT_BINDINGS.md Normal file
View File

@ -0,0 +1,91 @@
# Context Bindings
Status: first implementation slice
Date: 2026-06-19
`catalog/context-bindings.json` maps stable ontology concepts to real source-system identifiers.
It is intentionally separate from `catalog/entities.json`:
- `entities.json` says what concepts exist: `ops.card`, `engine.workflow_l1`, `engine.workflow_l2`.
- `context-bindings.json` says which concrete OPS card/project or Engine workflow/node is currently known.
## Current Seed Contexts
Active contexts currently seeded:
- OPS project `NDC PLATFORM`
- OPS card `Антология / Ontology Core`
These are real Tasker/OPS identifiers and are safe to use as the first resolver fixture.
## Current Cross-Surface Bindings
No active OPS <-> ENGINE binding is stored yet.
This is deliberate. The resolver should say:
```text
matched OPS context: yes
selected route: OPS -> ENGINE
missing binding: binding_type.ops_card_to_engine_workflow
```
That is better than pretending an Engine workflow is linked when it is not.
## Next Binding To Add
The first real productive binding should look like this, once the target Engine workflow/node is known:
```json
{
"id": "binding.ops.<card_or_project>.engine.<workflow>",
"typeId": "binding_type.ops_card_to_engine_workflow",
"status": "active",
"fromContextId": "context.ops.nodedc.ndc_platform.ontology_core_card",
"toContextId": "context.engine.<workflow_context_id>",
"summary": "Links OPS card/project context to the Engine workflow context."
}
```
Use the registry CLI instead of hand-editing when adding real contexts/bindings:
```text
npm run registry -- add-context --input-json examples/engine-context.example.json --dry-run
npm run registry -- add-binding --input-json examples/ops-engine-binding.example.json --dry-run
npm run registry -- import-engine-context --input-json examples/engine-workflow-manifest.example.json --dry-run
```
Remove `--dry-run` only after replacing example refs with real source-system identifiers.
Preferred workflow for ENGINE is `import-engine-context`: it generates the context id and optional OPS binding from a manifest, then validates the whole registry.
The corresponding Engine context should include at least:
```json
{
"surface": "engine",
"entityId": "engine.workflow_l1",
"sourceSystem": "nodedc-engine",
"refs": {
"workflow_id": "...",
"node_id": "..."
}
}
```
If L2 runtime is known, add:
```json
{
"runtime_workflow_id": "...",
"n8n_instance_id": "..."
}
```
## Rules
- Do not store secrets, tokens, env values, runtime payloads, logs, dumps, or database rows here.
- Store stable identifiers only.
- Prefer explicit context IDs over free-form names.
- Keep planned bindings as `planned`; use `active` only when the target source-system refs are confirmed.

164
services/ontology-core/docs/baseline/CANONICAL_ENTITY_CATALOG.md Normal file
View File

@ -0,0 +1,164 @@
# Canonical Entity Catalog v0.4-pre
Status: pre-release implementation baseline
Date: 2026-06-18
Scope: NodeDC core ontology for HUB, OPS, OPS Gateway, ENGINE, Assistant routing, and future interface layer.
This catalog is the current canonical naming baseline. It is intentionally compact:
implementation can start from it, while open items stay marked instead of being hidden.
## Evidence Status
- `source-confirmed`: direct code/schema evidence exists.
- `source-evidenced`: source supports the concept, but naming or boundary is partly product-level.
- `owner-confirmed`: confirmed by product/architecture discussion.
- `product-required`: needed for target platform behavior, not fully implemented yet.
- `future-concept`: planned service/domain concept, not a current source truth.
- `tech-debt-noncanonical`: current working code that must not define the canonical model.
- `pending`: keep as candidate until a deeper source pass confirms it.
## HUB / Launcher
| Entity ID | Canonical name | Status | Authority | Notes |
| --- | --- | --- | --- | --- |
| `hub.open_contour` | HUB Open Contour | source-evidenced / owner-confirmed | HUB | Public/open branch for simple users. Must be separate from company/client contour. |
| `hub.public_pool_context` | HUB Public Pool Context | source-confirmed | HUB | Source-backed public context. |
| `hub.public_pool_client` | HUB Public Pool Client | source-confirmed | HUB | Special source-backed `Client`, not an ordinary company/client. |
| `hub.client_context` | HUB Client Context | source-confirmed | HUB | Managed closed contour for companies/clients. |
| `hub.company_contour` | HUB Company Contour | source-evidenced alias/subtype | HUB | Product wording over managed `hub.client_context`. |
| `hub.user` | HUB User | source-confirmed | HUB / NDCAuth bridge | Canonical user in launcher domain. |
| `hub.public_user` | HUB Public User Classification | source-evidenced | HUB | Classification of `hub.user` by public-pool membership/origin. |
| `hub.client_user` | HUB Client User Classification | source-evidenced | HUB | Classification of `hub.user` by client/company membership. |
| `hub.membership` | HUB Membership | source-confirmed | HUB | User-to-client/context relation. |
| `hub.public_membership` | HUB Public Membership | source-confirmed | HUB | Membership in public pool context. |
| `hub.access_request` | HUB Access Request | source-confirmed | HUB | Base access request entity. |
| `hub.public_access_request` | HUB Public Access Request | source-evidenced | HUB | Public/open-contour access request subtype. |
| `hub.client_access_request` | HUB Client Access Request | source-evidenced | HUB | Company/client-context access request subtype. |
| `hub.invite` | HUB Invite | source-confirmed | HUB | Invitation into a context. |
| `hub.group` | HUB Group | source-confirmed | HUB | Client-local group. |
| `hub.role` | HUB Role | source-confirmed | HUB | Role vocabulary for user/membership decisions. |
| `hub.permission` | HUB Permission | source-confirmed | HUB | Derived permission capability. |
| `hub.application` | HUB Application | source-confirmed | HUB | Product application/service registered in launcher. |
| `hub.application_access` | HUB Application Access | source-confirmed | HUB | Effective app access result. |
| `hub.app_grant` | HUB App Grant | source-confirmed | HUB | Access authority input. |
| `hub.app_exception` | HUB App Exception | source-confirmed | HUB | User-specific allow/deny override. |
| `hub.application_card` | HUB Application Card | source-confirmed UI/view | HUB UI | Presentation over application/access state; not access authority. |
## NDCAuth
| Entity ID | Canonical name | Status | Authority | Notes |
| --- | --- | --- | --- | --- |
| `ndcauth.identity` | NDCAuth Identity | source-confirmed | NDCAuth / HUB | Canonical auth identity. Authentik/OIDC/JWT are implementation aliases. |
| `ndcauth.session` | NDCAuth Session | source-confirmed | NDCAuth / HUB | Runtime authenticated/unauthenticated session. |
## OPS Product
OPS Product is the operational project/work layer. It is not ENGINE-side OpsLayer, Agent Monitor, tender-agent config, or OPS Gateway.
| Entity ID | Canonical name | Status | Authority | Notes |
| --- | --- | --- | --- | --- |
| `ops.workspace` | OPS Workspace | source-confirmed | OPS Product | Workspace/root collaboration context. |
| `ops.workspace_member` | OPS Workspace Member | source-confirmed | OPS Product | User membership in workspace. |
| `ops.project` | OPS Project | source-confirmed | OPS Product | Project inside workspace. |
| `ops.project_member` | OPS Project Member | source-confirmed | OPS Product | User membership in project. |
| `ops.card` | OPS Card | source-confirmed / owner-confirmed | OPS Product | Canonical work object. Plane `Issue`, task, work item are aliases/types. |
| `ops.card_status` | OPS Card Status | source-confirmed | OPS Product | State/status of a card. |
| `ops.card_priority` | OPS Card Priority | source-confirmed | OPS Product | Attribute of `ops.card`, not a root domain object. |
| `ops.card_assignment` | OPS Card Assignment | source-confirmed | OPS Product | Relation between card and assignee. |
| `ops.assignee` | OPS Assignee | source-confirmed | OPS Product | Assigned user/member. |
| `ops.responsible` | OPS Responsible | product-required / source-adjacent | OPS Product | Product-needed accountability role; not identical to assignee until source semantics are hardened. |
| `ops.card_type` | OPS Card Type | source-evidenced / pending taxonomy | OPS Product | Type/subtype of card: task, report, milestone, mailstone, architecture block, etc. |
| `ops.card_relation` | OPS Card Relation | source-confirmed | OPS Product | Dependency/link between cards. |
| `ops.external_ref` | OPS External Reference | source-confirmed | OPS Product | Link to external/source object. |
| `ops.card_label` | OPS Card Label | source-confirmed | OPS Product | Label/tag classification. |
| `ops.card_comment` | OPS Card Comment | source-confirmed | OPS Product | Discussion/comment on a card. |
| `ops.card_activity` | OPS Card Activity | source-evidenced | OPS Product | Change/activity history. |
| `ops.card_artifact_link` | OPS Card Artifact Link | source-evidenced | OPS Product | Relation/link to output artifact; not a global artifact root. |
| `ops.file_asset` | OPS File Asset | source-evidenced | OPS Product | File attached/linked through OPS. |
| `ops.stored_blob` | OPS Stored Blob | source-evidenced | OPS Product | Storage-level blob behind file assets. |
## OPS Gateway / MCP Agent Access
OPS Gateway is the scoped MCP/API access layer for agents. It does not own OPS product truth.
| Entity ID | Canonical name | Status | Authority | Notes |
| --- | --- | --- | --- | --- |
| `agent.identity` | Agent Identity | source-confirmed | OPS Gateway | Execution identity for an agent/client in Gateway, not a universal assistant persona. |
| `agent.token` | Agent Token | source-confirmed | OPS Gateway | Opaque credential; not user identity. |
| `agent.session` | Agent Session | source-confirmed | OPS Gateway | Runtime/session envelope for agent operations. |
| `agent.grant` | Agent Grant | source-confirmed | OPS Gateway | Permission grant for agent identity/session. |
| `agent.token_grant` | Token Grant | source-confirmed | OPS Gateway | Token-to-grant binding. |
| `agent.scope` | Agent Scope | source-confirmed | OPS Gateway | Tool/capability permission, not OPS role. |
| `agent.denied_capability` | Denied Capability | source-confirmed | OPS Gateway | Explicitly unavailable operation. |
| `agent.mcp_tool` | MCP Tool | source-confirmed | OPS Gateway | Exposed callable tool surface. |
| `agent.idempotency_key` | Idempotency Key | source-confirmed | OPS Gateway | Required write-safety key. |
| `agent.audit_event` | Agent Audit Event | source-confirmed | OPS Gateway | Audit trail for agent actions. |
| `agent.tasker_adapter` | Tasker Adapter | source-confirmed | OPS Gateway | Adapter to Tasker/OPS product API. |
| `agent.setup_packet` | Agent Setup Packet | source-evidenced | OPS Gateway | Setup payload for creating client app/tool access. |
| `agent.ai_workspace_entitlement` | AI Workspace Entitlement | source-evidenced / pending boundary | HUB + OPS Gateway | Entitlement/access context for AI workspace; exact entity vs policy boundary needs hardening. |
| `agent.pairing_code` | Pairing Code | source-evidenced / pending route hardening | OPS Gateway | Pairing/setup flow candidate. |
## ENGINE / Workflow System
ENGINE remains workflow/dev environment. It may reference OPS and assistants, but it is not the place for heavy product UI.
| Entity ID | Canonical name | Status | Authority | Notes |
| --- | --- | --- | --- | --- |
| `engine.workflow_l1` | ENGINE L1 Workflow | source-confirmed | ENGINE | NodeDC canvas/workflow stored as workflow metadata and graph. |
| `engine.node_l1` | ENGINE L1 Node | source-confirmed | ENGINE | React Flow node in L1 graph. |
| `engine.edge_l1` | ENGINE L1 Edge | source-confirmed | ENGINE | React Flow edge in L1 graph. |
| `engine.node_type_l1` | ENGINE L1 Node Type | source-confirmed | ENGINE | Auto-registered node type/module. |
| `engine.workflow_acl` | ENGINE Workflow ACL | source-confirmed | ENGINE | Workflow-level ACL with viewer/editor/owner/admin roles. |
| `engine.workflow_owner` | ENGINE Workflow Owner | source-confirmed | ENGINE | Owner field in ACL. |
| `engine.workflow_share` | ENGINE Workflow Share | source-confirmed | ENGINE | Share/invite/user access routes. |
| `engine.workflow_access_request` | ENGINE Workflow Access Request | source-confirmed | ENGINE | Access request route/model for workflow access. |
| `engine.workflow_l2` | ENGINE L2 Workflow | source-evidenced | ENGINE / n8n bridge | n8n subworkflow attached to L1 node by `workflowId` + `nodeId`. |
| `engine.node_l2` | ENGINE L2 Node | source-evidenced | ENGINE / n8n bridge | Node inside compiled/deployed n8n workflow. |
| `engine.l2_runtime_core` | ENGINE L2 Runtime Core | source-evidenced | ENGINE / n8n bridge | Target n8n runtime/core instance. |
| `engine.workflow_l2_runtime_id` | ENGINE L2 Runtime Workflow ID | source-confirmed | ENGINE / n8n bridge | n8n runtime workflow id, separate from NodeDC workflow id. |
| `engine.l2_execution` | ENGINE L2 Execution | source-confirmed | ENGINE / n8n bridge | n8n execution id mapped to run/execution records. |
| `engine.l2_run` | ENGINE L2 Run | source-confirmed | ENGINE-side OpsLayer | Runtime run id used to bind execution/session. Current implementation is tech-debt-adjacent. |
| `engine.l2_session` | ENGINE L2 Session | source-confirmed | ENGINE-side OpsLayer | Runtime session anchor, often derived from run id if upstream omits session id. |
| `engine.l2_runtime_event` | ENGINE L2 Runtime Event | source-confirmed | ENGINE / n8n bridge | `workflow:start`, `workflow:finish`, `node:start`, `node:success`, `node:error`. |
| `engine.source_stamp` | ENGINE Source Stamp | pending | ENGINE | Candidate for future source/version traceability. |
## Assistant / AI Workspace
These entities are required by near-term routing, but need a dedicated AI Workspace evidence pass before they become fully source-confirmed.
| Entity ID | Canonical name | Status | Authority | Notes |
| --- | --- | --- | --- | --- |
| `assistant.assistant` | Assistant | product-required / pending source pass | AI Workspace | User-facing assistant capability/persona. |
| `assistant.provider` | Assistant Provider | product-required / pending source pass | AI Workspace | Model/provider integration boundary. |
| `assistant.executor` | Assistant Executor | product-required / pending source pass | AI Workspace / Codex / MCP | Execution adapter: Codex, MCP tools, local agent, browser app. |
| `assistant.thread` | Assistant Thread | product-required / pending source pass | AI Workspace | Conversation context. |
| `assistant.message` | Assistant Message | product-required / pending source pass | AI Workspace | Message unit in thread. |
| `assistant.bridge` | Assistant Bridge | product-required / pending source pass | AI Workspace / OPS Gateway | Bridge between assistant, ontology, OPS Gateway, Codex, and Engine. |
## Future Interface Layer
The future interface layer owns automation work views and UI compositions. It is motivated by the current ENGINE-side tender/Agent Monitor tech debt.
| Entity ID | Canonical name | Status | Authority | Notes |
| --- | --- | --- | --- | --- |
| `future.interface_layer` | Future Interface Layer | owner-confirmed future-concept | Platform | Dedicated layer for user-facing automation UIs, dashboards, maps, forms, and control panels. |
| `future.interface_view` | Interface View | future-concept | Interface Layer | A generated/configured view over ontology-backed domain data. |
| `future.interface_widget` | Interface Widget | future-concept | Interface Layer | Map, table, analytics block, form, graph, control, etc. |
| `future.interface_binding` | Interface Binding | future-concept | Interface Layer + ENGINE | Binding from workflow/node output to interface data/control layer. |
| `future.domain_package` | Domain Ontology Package | future-concept | Ontology Core | Procurement/tenders, ecology, transport analytics, robotics/Helius, ERP/business process, client-specific domains. |
## ENGINE Tech Debt / Non-Canonical Boundary
These names identify current working areas that must not leak into canonical core ontology.
| Entity ID | Canonical name | Status | Authority | Notes |
| --- | --- | --- | --- | --- |
| `engine.tech_debt.ops_layer` | ENGINE OpsLayer Tech Debt | tech-debt-noncanonical | ENGINE | Current ENGINE-side operational/runtime layer; do not confuse with OPS Product. |
| `engine.tech_debt.ops_agent_instance` | ENGINE Ops Agent Instance | tech-debt-noncanonical | ENGINE | Local runtime agent instance; not OPS Gateway `agent.identity`. |
| `engine.tech_debt.agent_monitor_node` | Agent Monitor Node | tech-debt-noncanonical | ENGINE | Current monitor/control UI experiment. |
| `engine.tech_debt.monitor_profile` | Monitor Profile | tech-debt-noncanonical | ENGINE | Current profile/config around Agent Monitor. |
| `engine.tech_debt.tender_domain_ui` | Tender Domain UI | tech-debt-noncanonical | ENGINE | Hardcoded tender/procurement UI in ENGINE. |
| `engine.tech_debt.tender_storage` | Tender Storage | tech-debt-noncanonical | ENGINE | Current domain storage in ENGINE-side implementation. |
| `engine.tech_debt.tender_ai_review` | Tender AI Review | tech-debt-noncanonical | ENGINE | Current AI review implementation for tender domain. |
| `engine.tech_debt.ops_tabs_control` | ENGINE OPS Tabs Control | tech-debt-noncanonical | ENGINE | UI/control surface tied to current OpsLayer experiment. |

806
services/ontology-core/docs/baseline/EVIDENCE_HARDENING_PLAN_V0_3_1.md Normal file
View File

@ -0,0 +1,806 @@
# Evidence Hardening Plan v0.3.1
Status: draft plan
Baseline: Compact Canonical Entity Catalog v0.3.1
Scope: documentation / ontology evidence only
## 1. Цель
Evidence hardening нужен, чтобы текущий canonical catalog v0.3.1 перестал быть только продуктовой договорённостью и получил проверяемую source-backed основу.
Для каждой ключевой сущности каталога нужно собрать прямое evidence:
```text
file path + line/section + короткое объяснение, почему этот фрагмент подтверждает entity или relation
```
Прямое evidence не обязано доказывать всю будущую продуктовую семантику. Оно должно честно фиксировать один из статусов:
- `source-confirmed` — сущность прямо представлена в source;
- `source-evidenced/context-derived` — сущность выводится из source-backed context/flow;
- `product-required` — сущность нужна продуктово, но source пока неполный;
- `future concept` — концепт оставлен на будущее;
- `tech debt / non-canonical` — существующий source есть, но он не является canonical truth.
## 2. Scope
### HUB
Readonly source:
```text
data/nodedc_launcher
```
Цель: укрепить evidence для `hub.open_contour`, `hub.public_pool_context`, `hub.public_pool_client`, `hub.user`, `hub.membership`, `hub.application`, `hub.application_access`, invite/access-request flows и NDCAuth aliases.
### OPS
Readonly source:
```text
data/dc_taskmanager/NODEDC_TASKMANAGER
```
Цель: укрепить evidence для `ops.card`, card submodel, workspace/project/member/status/assignment/labels/comments/files/activity/external refs.
### OPS Gateway
Readonly source:
```text
data/NODEDC_TASKMANAGER_CODEXAPI
```
Цель: укрепить evidence для `agent.identity`, grants, scopes, tokens, MCP tools, idempotency, audit, Tasker adapter, AI Workspace entitlement.
### ENGINE
Readonly source:
```text
NODEDC/NODEDC_ENGINE_INFRA
```
Цель: укрепить evidence для `engine.application_boundary`, Engine L1/L2 workflow entities, ACL/share, L2 runtime core/IDs/events/source stamps, Assistant/Provider/Executor split, and tech-debt boundary.
### Запреты
Не читать и не использовать как evidence:
```text
runtime/data/storage/env/secrets/logs/dumps/node_modules/build outputs
.env / .env.*
credentials / keys / pem / ssh
DB dumps / archives / backup contents
postgres/n8n runtime data
```
Не менять:
```text
source code
БД
миграции
docker files
package files
runtime config
```
Не запускать:
```text
bash
build
test
install
docker
migrations
servers
```
## 3. Entity groups needing direct evidence
### 3.1. HUB P0 — two-contour model
Entity ids:
```text
hub.open_contour
hub.public_pool_context
hub.public_pool_client
hub.client_context
hub.company_contour
```
Expected source files / search targets:
```text
data/nodedc_launcher/src/entities/public-pool/constants.ts
search: PUBLIC_POOL_CLIENT_ID
search: PUBLIC_POOL_CONTEXT_LABEL
search: PUBLIC_POOL_CONTEXT_DESCRIPTION
search: client_public_pool
data/nodedc_launcher/src/entities/client/types.ts
search: ClientType
search: ClientStatus
search: ClientTaskManagerWorkspaceBinding
data/nodedc_launcher/doc/base/nodedc_launcher_tz_frontend_mvp.md
search: Открытый контур
search: Клиент
search: Компания
```
Current confidence:
```text
source-evidenced/context-derived, owner-accepted baseline
```
Что надо проверить:
- что `client_public_pool` действительно source-backed special Client;
- что open contour не моделируется как ordinary `hub.client_context`;
- что closed managed context подтверждается через `Client`, memberships, groups, grants and TaskManager links.
Риск смешения терминов:
```text
Нельзя писать “hub.client inside hub.public_pool_context” как будто open contour является обычным managed client context.
Правильно: hub.public_pool_client is a source-backed special Client used by hub.public_pool_context.
```
### 3.2. HUB P0 — user, membership, access, application access
Entity ids:
```text
hub.user
hub.public_user
hub.client_user
hub.membership
hub.public_membership
hub.group
hub.role
hub.permission
hub.application
hub.application_access
hub.app_grant
hub.app_exception
hub.application_card
```
Expected source files / search targets:
```text
data/nodedc_launcher/src/entities/user/types.ts
search: LauncherUser
search: ClientMembership
search: ClientGroup
search: LauncherGlobalRole
search: ClientMembershipRole
data/nodedc_launcher/src/entities/access/types.ts
search: ServiceGrant
search: ServiceAccessException
search: EffectiveAccessResult
search: ServiceModuleEntitlement
data/nodedc_launcher/src/entities/access/computeEffectiveAccess.ts
search: computeEffectiveAccess
search: deny
search: allow
data/nodedc_launcher/src/entities/service/types.ts
search: Service
search: LauncherServiceView
data/nodedc_launcher/src/shared/lib/permissions.ts
search: resolvePermissions
search: LauncherPermissions
data/nodedc_launcher/src/widgets/service-rail/ServiceRail.tsx
search: ServiceRail
data/nodedc_launcher/src/widgets/service-stage/ServiceStage.tsx
search: ServiceStage
```
Current confidence:
```text
source-confirmed for base user/membership/group/application/access;
context-derived for public/client user classifications;
UI-confirmed for hub.application_card.
```
Что надо проверить:
- `hub.user` is source-backed by `LauncherUser`;
- `hub.public_user` and `hub.client_user` are classifications of `hub.user`, not hard entities;
- access authority belongs to `hub.application_access`, `hub.app_grant`, `hub.app_exception`;
- `hub.application_card` is presentation/UI only.
Риск смешения терминов:
```text
hub.application_card не является permission authority.
HUB app access не равен Engine workflow ACL.
```
### 3.3. HUB P1 — invite, access request, sync, NDCAuth aliases
Entity ids:
```text
hub.invite
hub.public_invite
hub.client_invite
hub.access_request
hub.public_access_request
hub.client_access_request
hub.sync_status
ndcauth.identity
ndcauth.session
```
Expected source files / search targets:
```text
data/nodedc_launcher/src/entities/invite/types.ts
search: InviteStatus
search: source
search: sourceTaskerInviteRequestId
data/nodedc_launcher/src/entities/access-request/types.ts
search: AccessRequest
search: targetClientId
search: approvedInviteId
data/nodedc_launcher/src/entities/sync/types.ts
search: SyncStatus
search: SyncTarget
data/nodedc_launcher/src/shared/api/authApi.ts
search: AuthUser
search: AuthSession
search: groups
search: /api/me
data/nodedc_launcher/server/dev-server.mjs
search: /api/access-requests
search: /api/invites
search: /api/internal/handoff/consume
search: /api/internal/access/check
```
Current confidence:
```text
source-confirmed for generic invite/access_request/sync/auth;
context-derived for public/client classifications.
```
Что надо проверить:
- access request can be classified by contour/context and target client;
- invite can be classified by contour/context and source/target;
- Authentik/OIDC/JWT names remain NDCAuth implementation aliases.
Риск смешения терминов:
```text
NDCAuth product names must not be replaced by Authentik/OIDC/JWT implementation aliases.
```
### 3.4. OPS P0 — card core
Entity ids:
```text
ops.workspace
ops.project
ops.card
ops.card_status
ops.card_priority
ops.card_assignment
ops.assignee
ops.responsible
ops.card_type
ops.card_relation
```
Expected source files / search targets:
```text
data/dc_taskmanager/NODEDC_TASKMANAGER/plane-src/apps/api/plane/db/models/workspace.py
search: class Workspace
search: class WorkspaceMember
data/dc_taskmanager/NODEDC_TASKMANAGER/plane-src/apps/api/plane/db/models/project.py
search: class Project
search: class ProjectMember
search: project_lead
search: default_assignee
data/dc_taskmanager/NODEDC_TASKMANAGER/plane-src/apps/api/plane/db/models/issue.py
search: class Issue
search: PRIORITY_CHOICES
search: state = models.ForeignKey
search: assignees = models.ManyToManyField
search: IssueAssignee
search: parent
search: type = models.ForeignKey
data/dc_taskmanager/NODEDC_TASKMANAGER/plane-src/apps/api/plane/db/models/state.py
search: class State
search: StateGroup
```
Current confidence:
```text
source-confirmed for workspace/project/card/status/priority/assignment/assignee;
product-required for responsible;
inferred/product-defined for card_type and card_relation until direct evidence is attached.
```
Что надо проверить:
- `Plane Issue` is source alias for canonical `ops.card`;
- `ops.card_priority` is card attribute, not global root;
- `ops.responsible` remains separate from `ops.assignee` and may be product-required;
- `IssueType` must not be overclaimed as source-confirmed unless direct evidence is strong.
Риск смешения терминов:
```text
task / issue / work item are aliases or card types, not canonical root.
Canonical root remains ops.card.
```
### 3.5. OPS P1 — card artifacts, activity, external refs
Entity ids:
```text
ops.card_label
ops.card_comment
ops.card_artifact_link
ops.file_asset
ops.stored_blob
ops.card_activity
ops.external_ref
```
Expected source files / search targets:
```text
data/dc_taskmanager/NODEDC_TASKMANAGER/plane-src/apps/api/plane/db/models/label.py
search: class Label
data/dc_taskmanager/NODEDC_TASKMANAGER/plane-src/apps/api/plane/db/models/issue.py
search: IssueLabel
search: IssueComment
search: IssueAttachment
search: IssueActivity
search: external_source
search: external_id
data/dc_taskmanager/NODEDC_TASKMANAGER/plane-src/apps/api/plane/db/models/asset.py
search: class FileAsset
search: class StoredBlob
search: sha256
search: canonical_object_key
search: storage_metadata
```
Current confidence:
```text
source-confirmed for labels/comments/attachments/file assets/stored blobs;
activity source-evidenced but exact event taxonomy needs hardening.
```
Что надо проверить:
- `ops.card_artifact_link` is relation/link, not global artifact root;
- `ops.file_asset` is OPS-local Plane `FileAsset`;
- `ops.stored_blob` is OPS-local `StoredBlob`;
- `ops.artifact` must not become a competing global artifact root.
Риск смешения терминов:
```text
Do not collide OPS-local file evidence with future global artifact layer.
```
### 3.6. OPS Gateway P1 — agent, grants, idempotency, audit
Entity ids:
```text
agent.identity
agent.token
agent.grant
agent.scope
agent.mcp_tool
agent.idempotency_key
agent.audit_event
agent.ai_workspace_entitlement
agent.tasker_adapter
```
Expected source files / search targets:
```text
data/NODEDC_TASKMANAGER_CODEXAPI/docs/ARCHITECTURE.md
search: Agent Gateway owns
search: agent
search: agent_token
search: agent_grant
search: pairing_code
search: agent_audit_event
search: idempotency_key
data/NODEDC_TASKMANAGER_CODEXAPI/docs/MCP_TOOLS_CONTRACT.md
search: tasker_
search: idempotency_key
search: denied tools
data/NODEDC_TASKMANAGER_CODEXAPI/src/repositories/agents.ts
search: agent_tokens
search: token_hash
search: agent_grants
search: idempotency_keys
data/NODEDC_TASKMANAGER_CODEXAPI/src/domain/scopes.ts
search: workspace:read
search: issue:create
data/NODEDC_TASKMANAGER_CODEXAPI/src/mcp/tool-runtime.ts
search: tasker_
search: claimIdempotencyKey
data/NODEDC_TASKMANAGER_CODEXAPI/src/routes/agents.ts
search: ai-workspace/entitlements
search: preflight
data/NODEDC_TASKMANAGER_CODEXAPI/src/tasker/client.ts
search: internal/nodedc/agent
```
Current confidence:
```text
source-confirmed for agent identity/tokens/grants/scopes/MCP/idempotency;
audit source-evidenced by docs and code search;
Tasker adapter source-confirmed by docs/API contract, exact code links pending.
```
Что надо проверить:
- Agent Identity is technical identity with owner, grants, scopes, tokens;
- Assistant/Agent split remains intact;
- MCP tools can request/perform scoped operations, not freely mutate OPS cards;
- writes require grants/scopes/idempotency/audit.
Риск смешения терминов:
```text
Codex is Assistant Provider, not Agent superclass.
Agent Identity is not Hub User.
```
### 3.7. ENGINE P0 — application boundary and tech debt boundary
Entity ids:
```text
engine.application_boundary
engine.tech_debt.ops_adapter
```
Expected source files / search targets:
```text
NODEDC/NODEDC_ENGINE_INFRA/nodedc-source/server/index.js
search: /auth/nodedc/handoff
search: NODEDC_LAUNCHER
search: /api/internal/access/check
NODEDC/NODEDC_ENGINE_INFRA/.ai-bridge/core-ontology-owner-decisions.md
search: engine.application_boundary
search: Engine-side OPS
search: Agent Monitor
search: tender-agent
NODEDC/NODEDC_ENGINE_INFRA/nodedc-source/server/routes/ops.js
search only, do not treat as canonical OPS:
search: opsAgentInstanceId
search: tender
search: activeTemplateId
NODEDC/NODEDC_ENGINE_INFRA/nodedc-source/src/driveinspector/nodes/AgentMonitor.definition.ts
search: AgentMonitor
```
Current confidence:
```text
owner-confirmed for application boundary;
tech debt / non-canonical for Engine-side OPS / Agent Monitor / tender config.
```
Что надо проверить:
- HUB to ENGINE goes through `engine.application_boundary`;
- no direct HUB relation to workflow internals;
- Engine-side OPS remains tech debt and non-canonical.
Риск смешения терминов:
```text
Do not use ENGINE server/routes/ops.js as OPS product truth.
```
### 3.8. ENGINE P1 — L1/L2 workflow/runtime IDs
Entity ids:
```text
engine.workflow_l1
engine.node_l1
engine.edge_l1
engine.node_type_l1
engine.workflow_acl
engine.workflow_owner
engine.workflow_share
engine.workflow_access_request
engine.workflow_l2
engine.node_l2
engine.l2_runtime_core
engine.workflow_l2_runtime_id
engine.l2_execution
engine.l2_run
engine.l2_session
engine.l2_runtime_event
engine.source_stamp
```
Expected source files / search targets:
```text
NODEDC/NODEDC_ENGINE_INFRA/nodedc-source/src/store.ts
search: nodes
search: edges
search: updateNodeData
search: sourceHandle
search: targetHandle
NODEDC/NODEDC_ENGINE_INFRA/nodedc-source/src/nodes/autoRegistry.ts
search: nodeTypes
search: meta.type
search: TYPE_LABEL
NODEDC/NODEDC_ENGINE_INFRA/nodedc-source/server/workflows/acl.js
search: ROLE_RANK
search: owner
search: users
search: groups
search: invites
search: canRead
search: canWrite
NODEDC/NODEDC_ENGINE_INFRA/nodedc-source/server/index.js
search: /api/workflows
search: /api/workflows/:id/share
search: workflow-access-requests
search: engine-role-access-requests
NODEDC/NODEDC_ENGINE_INFRA/nodedc-source/server/routes/n8n.js
search: runtimeWorkflowId
search: resolveNodeDcByRuntimeWorkflowId
search: resolveWorkflowIdByNodeDcBindingRest
search: executionId
NODEDC/NODEDC_ENGINE_INFRA/nodedc-source/server/ops/runtimeTap.js
search: runtimeWorkflowId
search: n8nCoreId
search: executionId
search: runId
search: sessionId
NODEDC/NODEDC_ENGINE_INFRA/nodedc-source/services/n8n/runtime-plugin/hooks.js
search: workflow:start
search: workflow:finish
search: node:start
search: node:success
search: node:error
NODEDC/NODEDC_ENGINE_INFRA/nodedc-source/server/routes/ndcAgentMcp.js
search: editedBy
search: editedAt
search: editIntent
```
Current confidence:
```text
source-evidenced by previous ENGINE pass; direct links pending.
```
Что надо проверить:
- L1 and L2 remain separate concrete workflow types;
- L2 runtime ID is not same as product workflow identity;
- runtime core/id/event concepts have direct source anchors.
Риск смешения терминов:
```text
n8n names are implementation aliases for Engine L2 runtime, not canonical product names.
```
### 3.9. ENGINE / Assistant P1 — Assistant, Provider, Executor, Bridge
Entity ids:
```text
assistant.assistant
assistant.provider
assistant.executor
assistant.thread
assistant.message
assistant.bridge
```
Expected source files / search targets:
```text
NODEDC/NODEDC_ENGINE_INFRA/nodedc-source/server/routes/aiWorkspace.js
search: EXECUTOR_TYPES
search: normalizeExecutor
search: thread
search: message
search: bridge
search: requestBridge
NODEDC/NODEDC_ENGINE_INFRA/nodedc-source/server/aiWorkspace/assistantRegistryClient.js
search: provider
search: executor
search: owner
NODEDC/NODEDC_ENGINE_INFRA/nodedc-source/src/components/ai/AIWorkspaceConsole.tsx
search: executor
search: thread
search: Ops workspace
search: Ops project
NODEDC/NODEDC_ENGINE_INFRA/nodedc-source/workers/ai-workspace-bridge/worker.mjs
search: workspaces
search: bridge
search: events
```
Current confidence:
```text
source-confirmed by previous ENGINE/AI Workspace pass; direct links should be hardened.
```
Что надо проверить:
- Assistant is product-facing interactive layer;
- Codex is Assistant Provider;
- Executor/Bridge are runtime/connection concepts;
- Agent Identity belongs to OPS Gateway and is not the Assistant superclass.
Риск смешения терминов:
```text
Do not model Codex as Agent superclass.
Do not collapse Assistant and Agent Identity.
```
## 4. Priority order
### P0
```text
HUB two-contour model
hub.user / membership / access / application access
ops.card core
ENGINE application boundary
Engine-side OPS tech debt boundary
```
### P1
```text
OPS artifacts / activity / external refs
OPS Gateway agent / grants / idempotency / audit
ENGINE L1/L2 workflow / runtime IDs
ENGINE Assistant / Provider / Executor split
```
### P2
```text
future concepts / product-required terms:
ops.responsible
ops.card_type taxonomy
ops.card_relation taxonomy
artifact.version / 3D model versioning
final global artifact/event layer
Agent Monitor future product role
```
## 5. Output artifacts
Следующие документы нужно создать после hardening passes:
```text
ontology/EVIDENCE_LEDGER.md
ontology/CANONICAL_ENTITY_CATALOG.md
ontology/RELATION_CATALOG.md
ontology/GUARDRAILS.md
ontology/OPEN_QUESTIONS.md
```
### ontology/EVIDENCE_LEDGER.md
Назначение: file+line ledger для каждой entity/relation.
Минимальная строка:
```text
Entity ID | Canonical name | Source root | Evidence file | Evidence line/section | Evidence status | Explanation | Notes
```
### ontology/CANONICAL_ENTITY_CATALOG.md
Назначение: frozen catalog после evidence hardening.
### ontology/RELATION_CATALOG.md
Назначение: canonical relations and boundaries.
### ontology/GUARDRAILS.md
Назначение: settled terminology and forbidden conflations.
### ontology/OPEN_QUESTIONS.md
Назначение: owner/product decisions not yet closed.
## 6. Next safe task
Следующая маленькая безопасная задача:
```text
Сделать HUB P0 evidence ledger section.
```
Scope следующей задачи:
```text
Только NodeDC HUB Readonly.
Только source/docs files, без runtime/data/storage/env/secrets/logs/dumps.
Собрать file+line evidence для:
- hub.open_contour
- hub.public_pool_context
- hub.public_pool_client
- hub.user
- hub.public_membership
- hub.membership
- hub.application
- hub.application_access
- hub.app_grant
- hub.app_exception
- hub.application_card
- ndcauth.identity
- ndcauth.session
```

49
services/ontology-core/docs/baseline/EVIDENCE_LEDGER.md Normal file
View File

@ -0,0 +1,49 @@
# Evidence Ledger Index v0.4-pre
Status: consolidated index
Date: 2026-06-18
This file indexes the source-backed evidence ledgers. It is not a replacement for the detailed ledger files.
## Ledger Files
| Ledger | Scope | Status | Main result |
| --- | --- | --- | --- |
| `EVIDENCE_LEDGER_HUB_P0.md` | HUB / Launcher / NDCAuth | source-backed P0 | Confirms open contour vs client/company contour, public pool client/context, user classifications, app access/card split. |
| `EVIDENCE_LEDGER_OPS_P0.md` | OPS Product | source-backed P0 | Confirms workspace/project/card model and `ops.card` as canonical work object. |
| `EVIDENCE_LEDGER_OPS_GATEWAY_P1.md` | OPS Gateway / MCP access | source-backed P1 | Confirms scoped agent identity/token/grant/scope/tool/idempotency/audit boundary. |
| `EVIDENCE_LEDGER_ENGINE_DIRTY_BOUNDARY_P1.md` | ENGINE-side OpsLayer / Agent Monitor / tender tech debt | source-backed P1 | Confirms this is non-canonical tech debt and must not define OPS Product. |
| `EVIDENCE_LEDGER_ENGINE_WORKFLOW_P1.md` | ENGINE L1/L2 workflow and runtime evidence | source-backed P1 | Confirms L1 graph, workflow ACL/share, L2 n8n runtime ids/events/run/session bridge. |
## Source Roots Used
| Surface | Source root | Notes |
| --- | --- | --- |
| HUB | `/Users/dcconstructions/Downloads/mnt/data/nodedc_launcher` | Read-only source inspection. |
| OPS Product | `/Users/dcconstructions/Downloads/mnt/data/dc_taskmanager/NODEDC_TASKMANAGER` | Read-only source inspection. |
| OPS Gateway | `/Users/dcconstructions/Downloads/mnt/data/NODEDC_TASKMANAGER_CODEXAPI` | Read-only source inspection. |
| ENGINE | `/Users/dcconstructions/Downloads/mnt/NODEDC/NODEDC_ENGINE_INFRA/nodedc-source` | Read-only source inspection; runtime/data/storage excluded. |
| Ontology workspace | `/Users/dcconstructions/Downloads/mnt/NODEDC_ONTOLOGY` | Documentation-only write workspace. |
## Accepted Evidence-Based Decisions
- HUB has two operational contours:
- open/public contour for simple users;
- managed closed company/client contour.
- `hub.public_pool_client` is a source-backed special Client, but it must not be modeled as ordinary company context.
- OPS Product canonical work object is `ops.card`.
- OPS Product, OPS Gateway, and ENGINE-side OpsLayer are three different things.
- ENGINE-side Agent Monitor/tender UI is working tech debt, not target architecture.
- ENGINE L1/L2 split is real enough for first ontology implementation:
- L1 = NodeDC canvas/workflow graph;
- L2 = n8n/subworkflow runtime attached to L1 node.
- Future interface layer is a planned platform service/layer, motivated by current ENGINE-side custom UI debt.
## Evidence Gaps That Remain Non-Blocking
- Assistant / AI Workspace needs a dedicated source pass before its entities become source-confirmed.
- `ops.responsible` needs exact source/product semantics.
- `ops.card_type` needs taxonomy.
- Gateway pairing/entitlement flow needs route-level hardening.
- Domain ontology packages need separate passes; core must not absorb domain-specific tender/ecology/transport concepts.

136
services/ontology-core/docs/baseline/EVIDENCE_LEDGER_ENGINE_DIRTY_BOUNDARY_P1.md Normal file
View File

@ -0,0 +1,136 @@
# Evidence Ledger — ENGINE Dirty Boundary P1
Status: source-backed tech-debt boundary note
Baseline: Compact Canonical Entity Catalog v0.3.1
Date: 2026-06-18
Scope: ENGINE-side OpsLayer / tender-agent / Agent Monitor boundary
Source root:
```text
/Users/dcconstructions/Downloads/mnt/NODEDC/NODEDC_ENGINE_INFRA/nodedc-source
```
Restrictions observed:
- Source inspection only.
- No runtime/data/storage/env/secrets/logs/dumps.
- No source code edits.
- No build/test/install/docker execution.
## Summary
This pass confirms an important ontology boundary:
```text
OPS product
!= OPS Gateway
!= ENGINE-side OpsLayer / tender-agent / Agent Monitor
```
The ENGINE repository contains a substantial embedded `OpsLayer` around n8n workflows, tender search/review, monitor profiles, agent runs, trace events, and Agent Monitor UI nodes.
This code is working product/legacy infrastructure, but it must be treated as:
```text
tech debt / non-canonical
```
It should not be promoted into canonical OPS product truth and should not define the final automation UI architecture.
## Boundary Evidence
| Boundary ID | Canonical treatment | Evidence status | Evidence file:line | Evidence explanation | Notes |
| --- | --- | --- | --- | --- | --- |
| `engine.tech_debt.ops_layer` | Engine-side legacy OpsLayer | source-confirmed tech debt | `server/index.js:25`, `server/index.js:333`, `server/routes/ops.js:1-34`, `server/routes/ops.js:6412-11855` | ENGINE imports `opsRouter` and mounts it at `/api/ops`; `routes/ops.js` implements a large set of run/result/tender/AI review/monitor endpoints. | This is not the separate OPS product / Tasker model. |
| `engine.tech_debt.ops_agent_instance` | Legacy Engine agent instance | source-confirmed tech debt | `server/ops/migrations/0001_init_opslayer.sql:89-137`, `src/store.ts:444-480`, `src/utils/opsApi.ts:759-855` | OpsLayer has `agents`, `agent_instances`, `agent_runs`; frontend prevents copied n8n nodes from inheriting `opsAgentInstanceId`; API can start/stop agent instances and record runs. | Do not merge with OPS Gateway `agent.identity`. |
| `engine.tech_debt.agent_monitor_node` | Agent Monitor canvas node | source-confirmed tech debt | `src/nodes/AgentMonitorNode.tsx:10-14`, `src/nodes/AgentMonitorNode.tsx:21-38`, `src/driveinspector/nodes/AgentMonitor.definition.ts:1-13` | ENGINE has a visible `agentMonitor` React Flow node and inspector definition that binds monitor profiles/agents through `opsApi`. | This is current UI embedding, not final interface layer. |
| `engine.tech_debt.monitor_profile` | Engine-side monitor profile | source-confirmed tech debt | `server/ops/migrations/0001_init_opslayer.sql:240-299`, `src/utils/opsApi.ts:260-360`, `src/utils/opsApi.ts:460-520` | OpsLayer stores monitor profiles, profile assignments, bound agent instances, n8n cores, and monitor nodes; frontend can list/create/update/bind profiles and save monitor layouts. | Useful evidence for future work-view requirements. |
| `engine.tech_debt.tender_domain_ui` | Tender-specific embedded UI/domain slice | source-confirmed tech debt | `server/routes/ops.js:45-63`, `server/routes/ops.js:75-145`, `src/n8n/N8nAgentMonitorPanel.tsx:1-44`, `src/n8n/N8nAgentMonitorPanel.tsx:1160-1245`, `src/n8n/tenderElectronicPlaceCountries.ts:1-12` | ENGINE includes Kontur tender URLs, tender categories/electronic places, tender search settings, and a large Agent Monitor panel. | Treat as procurement/tender domain evidence, not core ontology. |
| `engine.tech_debt.tender_storage` | Tender storage inside Engine OpsLayer | source-confirmed tech debt | `server/ops/migrations/0001_init_opslayer.sql:210-239`, `server/ops/migrations/0006_tender_dedup_registry.sql:1-17`, `server/ops/migrations/0007_tender_details.sql:1-24`, `server/ops/migrations/0008_tender_documents.sql:1-37` | OpsLayer stores tender results, dedup registry, details, and downloaded documents. | Do not confuse with future domain ontology persistence. |
| `engine.tech_debt.tender_ai_review` | Tender AI review workflow state | source-confirmed tech debt | `server/ops/migrations/0009_tender_ai_review.sql:1-90`, `src/n8n/N8nAgentMonitorPanel.tsx:1214-1238`, `src/utils/opsApi.ts:577-688` | OpsLayer stores AI review tasks/latest state; UI has default manual AI criteria/response format; API enqueues/retries review tasks. | Useful sample for domain-specific assistant review flows. |
| `engine.tech_debt.ops_tabs_control` | Engine inspector ops control | source-confirmed tech debt | `src/driveinspector/ControlRegistry.tsx:27-50` | Drive inspector registers `opsTabs` control. | Another marker that Ops UI is embedded in ENGINE editor controls. |
| `future.interface_layer` | Future platform UI/work-view layer | product-required / source-informed | `src/n8n/N8nAgentMonitorPanel.tsx:46-120`, `src/utils/opsApi.ts:460-520`, `server/ops/migrations/0001_init_opslayer.sql:240-299` | Current monitor panel/layout/profile code shows the kind of configurable work views the future interface layer must support. | Future home should be separate platform service/app, not Engine core. |
## Route / Surface Evidence
| Surface | Evidence status | Evidence file:line | Evidence explanation |
| --- | --- | --- | --- |
| `/api/ops` is mounted inside ENGINE server | source-confirmed | `server/index.js:25`, `server/index.js:333` | ENGINE server imports and mounts `opsRouter`. |
| Ops router owns runs/results/tender/AI review/monitor APIs | source-confirmed | `server/routes/ops.js:6412-11855` | Router exposes health, runs, tender results/details/docs, AI review, trace, monitor profiles/layout/admin, agent instance start/stop, actions, contour limits/search. |
| Agent Monitor is an ENGINE canvas node | source-confirmed | `src/nodes/AgentMonitorNode.tsx:10-14`, `src/nodes/AgentMonitorNode.tsx:73-170` | Node type is `agentMonitor`; UI opens monitor through n8n subworkflow event. |
| Agent Monitor panel directly consumes Ops APIs | source-confirmed | `src/n8n/N8nAgentMonitorPanel.tsx:5-31` | Panel imports many Ops API functions for tender details, AI review, layout, runs, trace, start/stop, take-in-work. |
| Engine graph copy logic special-cases Ops bindings | source-confirmed | `src/store.ts:444-480` | Copied n8n nodes clear `opsAgentInstanceId`; copied `agentMonitor` nodes clear monitor profile/binding fields. |
## Guardrails Confirmed
```text
Do not use ENGINE server/routes/ops.js as OPS product truth.
Do not use ENGINE OpsLayer agent_instances as OPS Gateway agent.identity.
Do not use Agent Monitor as the final automation UI model.
Do not put future custom product UI directly into ENGINE core.
Do not collapse tender/procurement domain concepts into core ontology roots.
```
Canonical separation:
```text
ops.*
= product OPS / Tasker / operational work system
agent.*
= OPS Gateway execution identity, token, grant, scope, tool boundary
engine.tech_debt.*
= current ENGINE-embedded OpsLayer / tender-agent / Agent Monitor legacy slice
future.interface_layer.*
= future platform UI/work-view/configurator surface, still not implemented
```
## Product / Architecture Notes
### Why this matters
The current Engine-side tender/Agent Monitor implementation proves the need for an ontology-backed interface layer:
- users need domain-specific work views;
- workflows need to emit structured data into user-facing controls;
- assistants will likely compose or modify these views;
- tender/procurement is only the first domain slice;
- future slices may include ecology, transport, robotics/Helius, ERP/business processes, and client-specific domains.
But the current implementation should remain a learning sample and migration source, not the target architecture.
### Future target
Recommended direction:
```text
ENGINE
owns workflow/node execution and development environment
future interface layer
owns configurable work views, dashboards, maps, analytics, forms, and domain UI composition
Ontology Core
resolves meanings, relations, aliases, domain schemas, and routing context
```
### Migration posture
Do not migrate or refactor this now.
Near-term treatment:
- document the boundary;
- avoid using these entities as canonical roots;
- use them as source-backed evidence for future interface/work-view requirements;
- preserve current working behavior until a real interface layer exists.
## Open Questions / Follow-up
1. Later ENGINE pass should separately document canonical workflow L1/L2 entities without mixing in OpsLayer.
2. Future interface-layer RFC should decide whether views/widgets/surfaces are core ontology entities or platform-service entities with ontology references.
3. Tender/procurement should become a domain ontology package, not a core ontology root.
4. Decide whether Engine-side OpsLayer data gets migrated, archived, or only bridged when the future interface layer exists.

67
services/ontology-core/docs/baseline/EVIDENCE_LEDGER_ENGINE_WORKFLOW_P1.md Normal file
View File

@ -0,0 +1,67 @@
# Evidence Ledger — ENGINE Workflow P1
Status: source-backed ledger section
Baseline: Canonical Entity Catalog v0.4-pre
Date: 2026-06-18
Scope: ENGINE L1/L2 workflow, ACL/share, n8n runtime bridge, runtime event tracking
Source root:
```text
/Users/dcconstructions/Downloads/mnt/NODEDC/NODEDC_ENGINE_INFRA/nodedc-source
```
Restrictions observed:
- Source inspection only.
- No runtime/data/storage/env/secrets/logs/dumps.
- No source code edits.
- No build/test/install/docker execution.
## Summary
This pass confirms the minimum ENGINE ontology needed for the first implementation:
- `engine.workflow_l1`, `engine.node_l1`, and `engine.edge_l1` exist as NodeDC/React Flow graph concepts.
- `engine.node_type_l1` is sourced from the auto node registry.
- Workflow ACL/share/access-request concepts are implemented in source.
- `engine.workflow_l2` is source-evidenced as an n8n subworkflow attached to an L1 workflow/node pair.
- Runtime events carry `workflowId`, `nodeId`, `runtimeWorkflowId`, `executionId`, `runId`, and `sessionId`.
- Current runtime run/session tracking is tied to ENGINE-side OpsLayer tables and should remain tech-debt-adjacent.
## Entity Evidence
| Entity ID | Evidence status | Evidence file:line | Evidence explanation |
| --- | --- | --- | --- |
| `engine.workflow_l1` | source-confirmed | `src/store.ts:603-680`, `server/index.js:768-840`, `server/index.js:2716-3045` | Client state stores graph `nodes`/`edges`; server stores workflow metadata/graph and exposes workflow list/read/create/update routes. |
| `engine.node_l1` | source-confirmed | `src/store.ts:603-680`, `src/store.ts:1510-1585`, `src/store.ts:1770-1845` | Store manages React Flow nodes, creates nodes from templates/types, and updates node data. |
| `engine.edge_l1` | source-confirmed | `src/store.ts:764-780`, `src/store.ts:1510-1549` | Edges have source/target handles and are normalized in store. |
| `engine.node_type_l1` | source-confirmed | `src/nodes/autoRegistry.ts:4-56` | Node modules expose `meta`, `runtime`, `ports`, `monitor`, and derive type/label from module metadata. |
| `engine.workflow_acl` | source-confirmed | `server/workflows/acl.js:5-13`, `server/workflows/acl.js:109-165`, `server/workflows/acl.js:259-303` | ACL stores owner/users/groups/invites and supports viewer/editor/owner/admin checks. |
| `engine.workflow_owner` | source-confirmed | `server/workflows/acl.js:109-165` | ACL owner field is normalized and role checked. |
| `engine.workflow_share` | source-confirmed | `server/index.js:3185-3245`, `server/index.js:3250-3312`, `server/index.js:3371-3635` | Workflow share routes expose owner/users/groups/invites and email/internal invite operations. |
| `engine.workflow_access_request` | source-confirmed | `server/index.js:2792`, `server/index.js:2860`, `server/index.js:2916`, `server/index.js:3314` | Workflow access request, approve, reject, and request routes are present. |
| `engine.workflow_l2` | source-evidenced | `server/routes/n8n.js:11661-11737` | `/api/n8n/subworkflow/deploy` loads subworkflow graph for `workflowId` + `nodeId`, compiles it, injects runtime events, and writes compiled n8n workflow. |
| `engine.node_l2` | source-evidenced | `server/routes/n8n.js:2288-2365`, `services/n8n/runtime-plugin/hooks.js:132-145` | Runtime event node and hooks capture n8n node name/id. |
| `engine.l2_runtime_core` | source-evidenced | `server/routes/n8n.js:11685-11696`, `server/routes/n8n.js:11739-11748` | Deploy resolves n8n target/base URL/instance and docker compose service/container. |
| `engine.workflow_l2_runtime_id` | source-confirmed | `services/n8n/runtime-plugin/hooks.js:52-61`, `server/routes/n8n.js:2323-2324`, `server/routes/n8n.js:12041-12055` | Runtime plugin extracts n8n workflow id; injected event uses `$workflow.id`; deploy sync stores resolved workflow id. |
| `engine.l2_execution` | source-confirmed | `services/n8n/runtime-plugin/hooks.js:77-86`, `server/routes/n8n.js:2323-2325`, `server/ops/runtimeTap.js:773-818`, `server/ops/runtimeTap.js:820-855` | Runtime events carry execution id; runtime tap writes trace event and run execution binding. |
| `engine.l2_run` | source-confirmed / tech-debt-adjacent | `services/n8n/runtime-plugin/hooks.js:88-106`, `server/ops/runtimeTap.js:247-270`, `server/ops/runtimeTap.js:467-542` | Hooks extract run id; runtime tap resolves/canonicalizes run id through ENGINE-side OpsLayer tables. |
| `engine.l2_session` | source-confirmed / tech-debt-adjacent | `services/n8n/runtime-plugin/hooks.js:108-130`, `server/ops/runtimeTap.js:272-289`, `server/ops/runtimeTap.js:354-430` | Hooks extract session id or fall back to run id; runtime tap resolves session anchors and can create session-workflow split runs. |
| `engine.l2_runtime_event` | source-confirmed | `services/n8n/runtime-plugin/hooks.js:220-231`, `services/n8n/runtime-plugin/hooks.js:233-279`, `services/n8n/runtime-plugin/hooks.js:285-387`, `server/routes/n8n.js:2298-2332`, `services/n8n/runtime-plugin/runtime-bridge.js:200-223` | Runtime events are emitted/enqueued for workflow/node start/finish/success/error and sent to NodeDC runtime endpoint with retry/failure handling. |
## Guardrails Confirmed
```text
engine.workflow_l1 id != engine.workflow_l2_runtime_id.
engine.workflow_l2 is attached through NodeDC workflowId + nodeId.
engine.l2_run and engine.l2_session are useful routing evidence but currently live in ENGINE-side OpsLayer tech debt.
Engine-side OpsLayer runtime tables do not define OPS Product ontology.
```
## Non-Blocking Follow-Up
- Harden `engine.source_stamp` after implementation needs are clearer.
- Separate stable L2 domain concepts from current n8n-specific deployment helpers.
- Decide whether runtime run/session belongs in future Ontology Core, Interface Layer, OPS Gateway, or a dedicated runtime observability package.

92
services/ontology-core/docs/baseline/EVIDENCE_LEDGER_HUB_P0.md Normal file
View File

@ -0,0 +1,92 @@
# Evidence Ledger — HUB P0
Status: first source-backed ledger section
Baseline: Compact Canonical Entity Catalog v0.3.1
Date: 2026-06-18
Scope: HUB / Launcher / NDCAuth P0 evidence
Source root:
```text
/Users/dcconstructions/Downloads/mnt/data/nodedc_launcher
```
Restrictions observed:
- Source inspection only.
- No runtime/data/storage/env/secrets/logs/dumps.
- No source code edits.
- No build/test/install/docker/bash execution for the source repos.
## Summary
This pass confirms the core HUB P0 ontology:
- `hub.open_contour` is the product-level open contour.
- `hub.public_pool_context` is the source-backed public pool context.
- `hub.public_pool_client` is a source-backed special `Client` with id `client_public_pool`.
- `hub.open_contour` must not be treated as an ordinary `hub.client_context`.
- `hub.user` is source-backed by `LauncherUser`.
- `hub.public_user` / `hub.client_user` are context classifications of `hub.user`, not separate hard user entities.
- `hub.application_access`, `hub.app_grant`, and `hub.app_exception` are permission/policy concepts.
- `hub.application_card` is UI/presentation over `LauncherServiceView`, not permission authority.
- `ndcauth.identity` and `ndcauth.session` are backed by Auth/OIDC session types; Authentik/OIDC/JWT remain implementation aliases.
## Entity Evidence
| Entity ID | Canonical name | Evidence status | Evidence file:line | Evidence explanation | Notes |
| --- | --- | --- | --- | --- | --- |
| `hub.open_contour` | Hub Open Contour | source-evidenced / owner-confirmed | `src/entities/public-pool/constants.ts:3-5` | Defines `PUBLIC_POOL_CLIENT_ID`, `PUBLIC_POOL_CONTEXT_LABEL = "Открытый контур"`, and `PUBLIC_POOL_CONTEXT_DESCRIPTION = "Public access pool"`. | Product-level canonical open contour. |
| `hub.public_pool_context` | Hub Public Pool Context | source-confirmed | `src/entities/public-pool/constants.ts:3-5` | Public pool constants define the concrete source-backed public context. | Source-backed context alias for open contour. |
| `hub.public_pool_client` | Hub Public Pool Client | source-confirmed special Client | `src/entities/public-pool/constants.ts:7-20` | `PUBLIC_POOL_CLIENT` is typed as `Client`, uses id `client_public_pool`, type `person`, label `Открытый контур`, and note says it is the system contour for public requests, public invites, and self-service users. | This confirms special source-backed Client, not ordinary client context. |
| `hub.client_context` | Hub Client Context | source-confirmed / context-derived | `src/entities/client/types.ts:1-36` | `Client` supports `company` and `person`, status fields, contract/demo fields, contact fields, and TaskManager workspace bindings. | Safer canonical name for closed managed context. |
| `hub.company_contour` | Hub Company Contour | alias / subtype | `src/widgets/admin-overlay/AdminOverlay.tsx:431-443` | Admin UI separates `Открытый контур` from a `Компании` selector backed by `data.clients`. | Product wording/subtype over managed `hub.client_context`. |
| `hub.user` | Hub User / Launcher User | source-confirmed | `src/entities/user/types.ts:10-22` | `LauncherUser` defines the source user entity with `id`, `authentikUserId`, email, name, global status, timestamps. | Core user entity. |
| `hub.public_user` | Hub Public User Classification | source-evidenced / context-derived | `src/widgets/admin-overlay/AdminOverlay.tsx:4760-4799` | `getPlatformUserOrigin` detects a public-pool membership and labels the same user as open-contour/self-service/access-request/invite origin. | Classification of `hub.user`, not hard user class. |
| `hub.client_user` | Hub Client User Classification | source-evidenced / context-derived | `src/widgets/admin-overlay/AdminOverlay.tsx:4801-4809` | If memberships exist outside public handling, UI labels the user as `Компания · ${client.name}` with client legal name. | Classification of `hub.user`, not hard user class. |
| `hub.membership` | Hub Client Membership | source-confirmed | `src/entities/user/types.ts:24-40` | `ClientMembership` links `clientId`, `userId`, role, status, invite/source metadata, and timestamps. | Main user-to-client/context link. |
| `hub.public_membership` | Hub Public Pool Membership | source-confirmed / context-derived | `server/control-plane-store.mjs:3368-3400` | `upsertAccessRequestMembership` defaults `clientId` to `publicPoolClientId`, creates membership with `source: "access_request"` and default disabled status. | Public status comes from membership context. |
| `hub.public_access_request` | Hub Public Access Request | source-evidenced / context-derived | `server/control-plane-store.mjs:713-793` | Public access request creation upserts user, creates disabled public-pool membership, and creates access request with `targetClientId: publicPoolClientId`. | Classification of `hub.access_request`. |
| `hub.client_access_request` | Hub Client Access Request | source-evidenced / context-derived | `server/control-plane-store.mjs:822-890` | Approval resolves target client, activates membership in the selected client, and removes pending public-pool membership when target client is not public pool. | Shows promotion from public request into managed client context. |
| `hub.access_request` | Hub Access Request | source-confirmed | `src/entities/access-request/types.ts:5-22` | `AccessRequest` has email/name/company, status, `targetClientId`, role, approval/review fields. | Base entity for public/client classifications. |
| `hub.invite` | Hub Invite | source-confirmed | `src/entities/invite/types.ts:5-21` | `Invite` has `clientId`, email, role, source, Tasker source refs, token, expiry, status. | Base entity for public/client invite classifications. |
| `hub.group` | Hub Client Group | source-confirmed | `src/entities/user/types.ts:42-50` | `ClientGroup` links group to `clientId` and `memberIds`. | Client-local group. |
| `hub.role` | Hub Role | source-confirmed | `src/entities/user/types.ts:1-6`, `src/entities/user/types.ts:24-25` | Defines global roles and membership roles. | Role vocabulary for HUB. |
| `hub.permission` | Hub Permission | source-confirmed | `src/shared/lib/permissions.ts:3-11`, `src/shared/lib/permissions.ts:21-39` | Defines `LauncherPermissions` and derives permissions from launcher role and membership status. | Permission resolution helper. |
| `hub.application` | Hub Application | source-confirmed | `src/entities/service/types.ts:7-36` | `Service` defines app/service catalog entity with slug/title/URL/status/media/Auth aliases. | Canonical product application/service concept. |
| `hub.application_access` | Hub Application Access | source-confirmed | `src/entities/access/types.ts:28-38` | `EffectiveAccessResult` stores service/user access outcome, visibility, open-enabled, app role, reason, source. | Policy/debug entity for effective app access. |
| `hub.app_grant` | Hub App Access Grant | source-confirmed | `src/entities/access/types.ts:1-14` | `ServiceGrant` targets `client`, `group`, or `user` and grants an app role for a service. | Authority input for app access. |
| `hub.app_exception` | Hub App Access Exception | source-confirmed | `src/entities/access/types.ts:16-26` | `ServiceAccessException` stores user-specific `deny` or `allow` exceptions. | Override layer for app access. |
| `hub.application_card` | Hub Application Card | source-confirmed UI/view only | `src/entities/service/types.ts:45-72`, `src/widgets/service-rail/ServiceRail.tsx:6-52`, `src/widgets/service-stage/ServiceStage.tsx:22-147` | `LauncherServiceView` includes display fields and `effectiveAccess`; `ServiceRail` renders service tiles; `ServiceStage` renders a launch/detail surface using `effectiveAccess`. | Presentation over `hub.application` + access state, not permission authority. |
| `ndcauth.identity` | NDCAuth Identity | source-confirmed with implementation aliases | `src/shared/api/authApi.ts:1-8`, `src/entities/user/types.ts:10-13` | `AuthUser` has `sub`, email/name/groups; `LauncherUser` stores `authentikUserId`. | Authentik/OIDC subject is implementation alias. |
| `ndcauth.session` | NDCAuth Session | source-confirmed | `src/shared/api/authApi.ts:10-23`, `server/dev-server.mjs:270-294` | `AuthSession` represents authenticated/unauthenticated session; `/api/me` returns authenticated runtime session user and groups or login URL. | Session model for launcher runtime. |
## Relation / Flow Evidence
| Relation / guardrail | Evidence status | Evidence file:line | Evidence explanation |
| --- | --- | --- | --- |
| `hub.open_contour` is not ordinary `hub.client_context` | source-evidenced / owner-confirmed | `src/widgets/admin-overlay/AdminOverlay.tsx:411-443` | Admin UI shows a dedicated public-pool context switcher and a separate `Компании` selector. |
| Public pool supports public requests/invites/self-service users | source-confirmed | `src/entities/public-pool/constants.ts:7-20` | The special Client note explicitly says it is the system contour for public requests, public invites, and self-service users. |
| Public access request creates disabled public-pool membership | source-confirmed | `server/control-plane-store.mjs:740-742`, `server/control-plane-store.mjs:3368-3400` | Request creation upserts user and membership; membership helper defaults to `publicPoolClientId` and disabled status. |
| Public request can promote into client/company context | source-confirmed | `server/control-plane-store.mjs:846-865` | Approval creates active membership for target client; if target is not public pool, pending public-pool membership is removed. |
| App access is derived from grants/exceptions, not UI cards | source-confirmed | `src/entities/access/computeEffectiveAccess.ts:31-132` | Effective access checks deny/allow exceptions, user grants, group grants, client grants, then blocks by default. |
| `hub.application_card` is presentation over access state | source-confirmed | `src/entities/service/types.ts:45-72`, `src/widgets/service-stage/ServiceStage.tsx:101-126` | UI view includes `effectiveAccess`; launch button checks `service.effectiveAccess.openEnabled`, but authority is from access computation. |
| NDCAuth uses OIDC/JWT/Auth implementation evidence | source-confirmed | `server/dev-server.mjs:2475-2505`, `server/dev-server.mjs:270-294` | Server verifies JWT/OIDC claims, normalizes `sub/email/groups`, and serves `/api/me`. |
## Guardrails Confirmed
```text
hub.public_pool_client is a source-backed special Client used by hub.public_pool_context.
hub.open_contour must not be treated as an ordinary hub.client_context.
hub.user is the core user entity.
hub.public_user and hub.client_user are context classifications of hub.user.
hub.application_card is UI/presentation only, not permission authority.
hub.application_access / hub.app_grant / hub.app_exception are the app-access policy concepts.
NDCAuth is canonical; Authentik/OIDC/JWT remain implementation aliases.
```
## Open Questions / Follow-up
1. `hub.client_access_request` is source-evidenced by target-client approval flow, but final product wording should decide whether it remains a formal classification or only a relation state of `hub.access_request`.
2. `hub.public_invite` / `hub.client_invite` have base source evidence through `Invite.clientId`; a later HUB P1 pass should harden exact classification rules by public-pool vs client target.
3. Add these rows into the future combined `ontology/EVIDENCE_LEDGER.md` after OPS/ENGINE evidence sections are ready.

138
services/ontology-core/docs/baseline/EVIDENCE_LEDGER_OPS_GATEWAY_P1.md Normal file
View File

@ -0,0 +1,138 @@
# Evidence Ledger — OPS Gateway P1
Status: first source-backed gateway ledger section
Baseline: Compact Canonical Entity Catalog v0.3.1
Date: 2026-06-18
Scope: OPS Gateway / Codex API / MCP agent boundary
Source root:
```text
/Users/dcconstructions/Downloads/mnt/data/NODEDC_TASKMANAGER_CODEXAPI
```
Restrictions observed:
- Source inspection only.
- No runtime/data/storage/env/secrets/logs/dumps.
- No source code edits.
- No build/test/install/docker execution.
## Summary
This pass confirms that OPS Gateway is not just a loose Codex config helper.
It is a separate boundary service that owns:
- agent identity;
- opaque agent tokens;
- project/workspace grants;
- tool scopes;
- MCP tool exposure;
- idempotency for write tools;
- audit events;
- a narrow Tasker adapter;
- AI Workspace entitlement projection into token-scoped MCP grants.
Ontology implication:
```text
agent.* entities belong to OPS Gateway.
They are not the same thing as Assistant, Codex, ChatGPT, or a human user.
```
## Entity Evidence
| Entity ID | Canonical name | Evidence status | Evidence file:line | Evidence explanation | Notes |
| --- | --- | --- | --- | --- | --- |
| `agent.identity` | OPS Gateway Agent | source-confirmed | `docs/ARCHITECTURE.md:72-89`, `migrations/001_initial.sql:8-17`, `src/repositories/agents.ts:15-24` | Agent Gateway owns agent profiles; `agents` table stores owner identity, display name, avatar, status, timestamps; `AgentRecord` mirrors those fields. | This is a gateway execution identity, not the assistant superclass. |
| `agent.token` | OPS Gateway Agent Token | source-confirmed | `docs/MCP_TOOLS_CONTRACT.md:19-50`, `migrations/001_initial.sql:38-47`, `src/repositories/agents.ts:488-545`, `src/security/tokens.ts:1-10` | Tokens are opaque bearer credentials; storage uses token hash/suffix/status/expiry; `createToken` stores hash and token grant scope; token strings use `ndcag_` prefix. | Token is not a user password and not a durable ontology identity. |
| `agent.session` | OPS Gateway Agent Session | source-confirmed | `src/repositories/agents.ts:50-55`, `src/repositories/agents.ts:579-630`, `src/routes/agents.ts:161-177` | Session joins active agent, active token, effective grants, and grant source; agent-session routes expose current session and setup packet. | Runtime auth context for MCP/tool calls. |
| `agent.grant` | OPS Gateway Grant | source-confirmed | `docs/ARCHITECTURE.md:134-143`, `migrations/001_initial.sql:22-33`, `src/repositories/agents.ts:26-36` | Grants bind an agent to workspace/project with scopes and mode. | Workspace-level grant is represented with empty/null project internally. |
| `agent.token_grant` | Token-scoped Run Grant | source-confirmed | `migrations/004_run_grants.sql:1-21`, `src/repositories/agents.ts:488-545`, `src/repositories/agents.ts:633-663`, `src/routes/agents.ts:964-972` | Tokens can have their own grant scope; token grants can reference source agent grants and intersect effective scopes. | Important for AI Workspace run-scoped access. |
| `agent.scope` | Agent Tool Scope | source-confirmed | `src/domain/scopes.ts:1-13`, `src/security/authorization.ts:11-39`, `src/mcp/tool-runtime.ts:540-557` | Allowed scopes list workspace/project/card operations; runtime checks both global scope and project grant scope before writes/reads. | Scopes are tool permissions, not product roles. |
| `agent.denied_capability` | Denied Gateway Capability | source-confirmed | `src/domain/scopes.ts:17-30`, `docs/ARCHITECTURE.md:91-107`, `docs/MCP_TOOLS_CONTRACT.md:321-333` | Delete/archive/settings/invite/raw Tasker API capabilities are explicitly denied. | Guardrail entity or policy list, not user-facing capability. |
| `agent.mcp_tool` | OPS MCP Tool | source-confirmed | `docs/MCP_TOOLS_CONTRACT.md:11-17`, `src/mcp/tool-runtime.ts:118-215`, `src/routes/mcp.ts:56-127` | Gateway exposes `/mcp`; supported methods include initialize/ping/tools/list/tools/call; runtime defines Tasker tools and required scopes. | Tools are filtered by effective session scopes. |
| `agent.idempotency_key` | Gateway Idempotency Key | source-confirmed | `docs/MCP_TOOLS_CONTRACT.md:303-319`, `migrations/001_initial.sql:77-86`, `src/repositories/agents.ts:676-765`, `src/mcp/tool-runtime.ts:390-448` | Write tools require idempotency key; Gateway stores processing/completed state, detects replay/conflict/in-progress, completes or releases keys. | Key is agent-scoped and protects Tasker writes from duplicate execution. |
| `agent.audit_event` | Gateway Audit Event | source-confirmed | `migrations/001_initial.sql:65-75`, `src/repositories/agents.ts:666-674`, `src/mcp/tool-runtime.ts:427-445`, `src/repositories/agents.ts:536-542` | Audit table stores event type/actor/metadata; tool executed/replayed/failed and token created events are recorded. | Required for trustworthy assistant/tool writes. |
| `agent.tasker_adapter` | Tasker Internal Adapter | source-confirmed | `docs/ARCHITECTURE.md:91-107`, `src/tasker/client.ts:104-203`, `src/tasker/client.ts:228-267` | Adapter exposes narrow intent-level Tasker operations and sends agent metadata/headers to Tasker internal endpoints. | Gateway must not call broad/raw Tasker APIs. |
| `agent.setup_packet` | Agent Setup Packet | source-confirmed | `docs/MCP_TOOLS_CONTRACT.md:335-350`, `src/routes/agents.ts:170-177`, `src/routes/agents.ts:1090-1128`, `src/routes/agents.ts:1153-1203` | Authenticated setup endpoint returns MCP server config template, available tools, and generated AGENTS.md rules. | Current Codex config workflow lives here; raw token is represented as placeholder in setup template. |
| `agent.ai_workspace_entitlement` | AI Workspace Entitlement Grant | source-confirmed | `src/routes/agents.ts:132-147`, `src/routes/agents.ts:179-249`, `src/routes/agents.ts:834-895`, `src/routes/agents.ts:942-972` | Internal AI Workspace route validates app/context/owner, selects matching grants, creates short-lived run token, records audit, and returns MCP server grant config. | This is the main future hook for ontology-assisted routing. |
| `agent.pairing_code` | Agent Pairing Code | storage-confirmed / route pending | `docs/ARCHITECTURE.md:74-83`, `docs/ARCHITECTURE.md:145-152`, `migrations/001_initial.sql:52-63` | Pairing codes are part of documented Gateway ownership and have storage table/status/expiry fields. | This pass did not confirm active route behavior; keep P2 pending. |
## Tool / Flow Evidence
| Flow / relation | Evidence status | Evidence file:line | Evidence explanation |
| --- | --- | --- | --- |
| `agent.session` exposes only scoped tools | source-confirmed | `src/mcp/tool-runtime.ts:373-375`, `src/routes/mcp.ts:92-106` | `getToolsForSession` filters tools by required scopes before `/mcp tools/list` returns them. |
| `agent.mcp_tool` executes through grants and scopes | source-confirmed | `src/mcp/tool-runtime.ts:450-557`, `src/security/authorization.ts:11-39` | Each tool validates args, scope, and project grant before calling Tasker adapter. |
| Write tools require idempotency | source-confirmed | `src/mcp/tool-runtime.ts:390-448`, `docs/MCP_TOOLS_CONTRACT.md:303-319` | Non-read tools fail without idempotency key and use claim/replay/conflict/in-progress behavior. |
| Gateway records write audit | source-confirmed | `src/mcp/tool-runtime.ts:427-445`, `src/repositories/agents.ts:666-674` | Successful, replayed, and failed tool attempts produce audit events. |
| Gateway calls Tasker through internal adapter | source-confirmed | `src/tasker/client.ts:104-203`, `src/tasker/client.ts:228-267` | Client calls internal Tasker endpoints and forwards agent id, owner user id, token id, and display metadata. |
| AI Workspace can receive token-scoped MCP grant | source-confirmed | `src/routes/agents.ts:179-249`, `src/routes/agents.ts:858-895` | Internal entitlement route returns an app grant with MCP server URL and bearer token for matching workspace/project grants. |
## Guardrails Confirmed
```text
agent.identity is an OPS Gateway execution identity, not a universal Assistant identity.
agent.token is an opaque credential and must not become a canonical user identity.
agent.scope is a tool permission model, not an OPS role model.
agent.grant binds agent/tool access to OPS workspace/project context.
agent.mcp_tool can request/perform scoped operations, not freely mutate OPS data.
All write tools require grants, scopes, idempotency, and audit.
Gateway should not expose raw Tasker API, delete/archive, workspace settings, invites, or arbitrary attachments.
Tasker remains source of truth for OPS cards/projects/states/labels/members/comments.
Launcher/HUB remains source of entitlement truth.
```
## Product / Architecture Notes
### Current MCP / Codex config path
The current path is workable but rough:
```text
AI Workspace or user setup
-> Agent Gateway setup packet / entitlement grant
-> MCP server config with bearer token
-> Codex or other MCP client
-> scoped Tasker tools
```
This should not be treated as final UX, but it is already a clean enough safety boundary:
- token is opaque and revocable;
- tools are scope-filtered;
- writes are idempotent;
- tool attempts are audited;
- Tasker calls go through a narrow adapter.
### Ontology hook for later
Ontology can improve the setup/routing layer without replacing Gateway:
```text
User asks from OPS / HUB / ENGINE / AI Workspace context
-> ontology resolves target workspace/project/card/workflow/application
-> Gateway issues or selects the correct token-scoped grant
-> Assistant receives only the tools/context it needs
```
Do not immediately rewrite the current Codex config flow. The future improvement is better context resolution and safer grant selection, not removing Gateway.
### Relation to future interface layer
The same pattern will matter for the future automation UI/interface layer:
- interface builder needs ontology-backed meanings;
- assistant may assemble views/widgets from domain entities;
- Gateway-style grants can bound which cards/projects/workflows/views can be mutated;
- Engine should emit structured automation data, not own every custom UI directly.
## Open Questions / Follow-up
1. Confirm active pairing-code route behavior or mark pairing as storage-only legacy/planned.
2. Decide whether `agent.ai_workspace_entitlement` should become a first-class ontology entity or remain a flow/policy object.
3. Map Gateway scopes to canonical OPS operations after the final OPS relation catalog exists.
4. Later, connect ontology resolver to AI Workspace entitlement context selection.
5. Keep `Assistant`, `Agent`, `MCP Client`, `Tool`, and `Gateway Token` as separate concepts.

146
services/ontology-core/docs/baseline/EVIDENCE_LEDGER_OPS_P0.md Normal file
View File

@ -0,0 +1,146 @@
# Evidence Ledger — OPS P0
Status: first source-backed ledger section
Baseline: Compact Canonical Entity Catalog v0.3.1
Date: 2026-06-18
Scope: OPS / TaskManager / Plane P0 evidence
Source root:
```text
/Users/dcconstructions/Downloads/mnt/data/dc_taskmanager/NODEDC_TASKMANAGER
```
Restrictions observed:
- Source inspection only.
- No runtime/data/storage/env/secrets/logs/dumps.
- No source code edits.
- No build/test/install/docker execution.
## Summary
This pass confirms the OPS P0 model:
- `ops.workspace` is source-backed by Plane `Workspace`.
- `ops.project` is source-backed by Plane `Project`.
- `ops.card` is the canonical NodeDC term for the Plane `Issue` work object.
- `ops.card_status` is backed by Plane `State` / `StateGroup`.
- `ops.card_priority` is a card attribute backed by `Issue.priority`.
- `ops.card_assignment` / `ops.assignee` are backed by `Issue.assignees` and `IssueAssignee`.
- `ops.card_relation` is backed by `IssueRelation` and relation choices.
- `ops.card_type` is source-backed by `IssueType`, but product taxonomy can grow beyond Plane's current naming.
- `ops.responsible` remains product-required/source-adjacent, not fully source-confirmed as a separate canonical entity.
## Entity Evidence
| Entity ID | Canonical name | Evidence status | Evidence file:line | Evidence explanation | Notes |
| --- | --- | --- | --- | --- | --- |
| `ops.workspace` | Ops Workspace | source-confirmed | `plane-src/apps/api/plane/db/models/workspace.py:119-183` | `Workspace` defines workspace name, owner, slug, timezone/storage fields and maps to `workspaces` table. | Plane source alias: `Workspace`. |
| `ops.workspace_member` | Ops Workspace Member | source-confirmed | `plane-src/apps/api/plane/db/models/workspace.py:200-233` | `WorkspaceMember` links workspace to member, role, active/banned state, and per-member props. | Membership context for workspace-level OPS access. |
| `ops.project` | Ops Project | source-confirmed | `plane-src/apps/api/plane/db/models/project.py:68-167` | `Project` links to workspace and defines name, identifier, project settings, default state, external refs. | Plane source alias: `Project`. |
| `ops.project_member` | Ops Project Member | source-confirmed | `plane-src/apps/api/plane/db/models/project.py:212-227` | `ProjectMember` links project/member with role, preferences, sort order, and active state. | Project-level OPS membership. |
| `ops.card` | Ops Card | source-confirmed canonical NodeDC term | `plane-src/apps/api/plane/db/models/issue.py:104-177` | Plane `Issue` defines the core work object with parent, state, name, description, priority, assignees, labels, dates, external refs, and type. | `Issue`, `task`, `work item` are aliases/types; canonical NodeDC term is `ops.card`. |
| `ops.card_status` | Ops Card Status | source-confirmed | `plane-src/apps/api/plane/db/models/state.py:14-20`, `plane-src/apps/api/plane/db/models/state.py:79-115`, `plane-src/apps/api/plane/db/models/issue.py:119-125` | `StateGroup` defines backlog/unstarted/started/completed/cancelled/triage; `State` is project-scoped; `Issue.state` links card to state. | Plane source aliases: `State`, `StateGroup`. |
| `ops.card_priority` | Ops Card Priority | source-confirmed card attribute | `plane-src/apps/api/plane/db/models/issue.py:105-111`, `plane-src/apps/api/plane/db/models/issue.py:140-145` | `Issue.PRIORITY_CHOICES` and `Issue.priority` define urgent/high/medium/low/none priority. | Rename from broad `ops.priority`; this is card-scoped. |
| `ops.card_assignment` | Ops Card Assignment | source-confirmed | `plane-src/apps/api/plane/db/models/issue.py:148-154`, `plane-src/apps/api/plane/db/models/issue.py:337-357` | `Issue.assignees` is a ManyToMany through `IssueAssignee`; `IssueAssignee` links issue to assignee. | Assignment relation/entity for card. |
| `ops.assignee` | Ops Assignee | source-confirmed | `plane-src/apps/api/plane/db/models/issue.py:337-360` | `IssueAssignee` links card to user and enforces uniqueness for non-deleted assignment. | Confirmed source term. |
| `ops.responsible` | Ops Responsible | product-required / source-adjacent | `plane-src/apps/api/plane/db/models/project.py:77-90` | `Project` has `default_assignee` and `project_lead`, which are adjacent to responsibility semantics but not the full product concept. | Keep separate from `ops.assignee`; do not mark fully source-confirmed yet. |
| `ops.card_type` | Ops Card Type | source-confirmed source anchor + product-defined taxonomy | `plane-src/apps/api/plane/db/models/issue.py:163-169`, `plane-src/apps/api/plane/db/models/issue_type.py:14-29`, `plane-src/apps/api/plane/db/models/issue_type.py:35-52` | `Issue.type` links to `IssueType`; `IssueType` has workspace-level name/description/default/active fields; `ProjectIssueType` maps types into projects. | Source-backed by Plane `IssueType`; NodeDC taxonomy can still include task/report/milestone/note/request as product-defined types. |
| `ops.card_relation` | Ops Card Relation | source-confirmed | `plane-src/apps/api/plane/db/models/issue.py:112-118`, `plane-src/apps/api/plane/db/models/issue.py:264-309` | `Issue.parent` supports hierarchy; `IssueRelationChoices` and `IssueRelation` model duplicate/relates_to/blocked_by/start_before/finish_before/implemented_by relations. | Relation taxonomy exists; product meaning may need curation. |
| `ops.external_ref` | Ops External Ref | source-confirmed cross-cutting field | `plane-src/apps/api/plane/db/models/issue.py:161-162`, `plane-src/apps/api/plane/db/models/project.py:120-122`, `plane-src/apps/api/plane/db/models/state.py:92-93`, `plane-src/apps/api/plane/db/models/issue_type.py:23-24` | Issue, Project, State, and IssueType all carry `external_source` / `external_id` fields. | Useful for future cross-app ontology links. |
## Supporting P1 Evidence Found During P0
| Entity ID | Canonical name | Evidence status | Evidence file:line | Evidence explanation | Notes |
| --- | --- | --- | --- | --- | --- |
| `ops.card_label` | Ops Card Label / Marker | source-confirmed | `plane-src/apps/api/plane/db/models/label.py:11-44`, `plane-src/apps/api/plane/db/models/issue.py:156`, `plane-src/apps/api/plane/db/models/issue.py:534-542` | `Label` is workspace/project-scoped; `Issue.labels` uses `IssueLabel`. | P1 but confirmed while reading card model. |
| `ops.card_comment` | Ops Card Comment | source-confirmed | `plane-src/apps/api/plane/db/models/issue.py:442-469` | `IssueComment` links to issue, actor, access, attachments, external refs, parent comment. | P1. |
| `ops.card_activity` | Ops Card Activity | source-confirmed | `plane-src/apps/api/plane/db/models/issue.py:406-435` | `IssueActivity` stores issue, verb, changed field, old/new values, comment/attachments, actor. | P1 event/activity evidence. |
| `ops.card_artifact_link` | Ops Card Artifact Link | source-confirmed | `plane-src/apps/api/plane/db/models/issue.py:389-399`, `plane-src/apps/api/plane/db/models/asset.py:28-75` | `IssueAttachment` links issue to file asset; `FileAsset` can link to issue and stores file metadata. | Relation/link, not global artifact root. |
| `ops.file_asset` | Ops File Asset | source-confirmed | `plane-src/apps/api/plane/db/models/asset.py:28-75` | `FileAsset` stores asset file, workspace/project/issue/comment links, entity type, external refs, metadata, blob ref. | OPS-local source entity. |
| `ops.stored_blob` | Ops Stored Blob | source-confirmed | `plane-src/apps/api/plane/db/models/asset.py:110-147` | `StoredBlob` is canonical stored object with workspace, sha256, size, mime type, canonical object key, status, ref count, metadata. | OPS-local stored binary/blob source entity. |
## Relation / Flow Evidence
| Relation / guardrail | Evidence status | Evidence file:line | Evidence explanation |
| --- | --- | --- | --- |
| `ops.workspace` contains `ops.project` | source-confirmed | `plane-src/apps/api/plane/db/models/project.py:68-76` | `Project.workspace` is a foreign key to workspace. |
| `ops.project` contains `ops.card` | source-confirmed | `plane-src/apps/api/plane/db/models/issue.py:104-177`, `plane-src/apps/api/plane/db/models/project.py:182-191` | `Issue` inherits `ProjectBaseModel`, which stores project and workspace; save copies workspace from project. |
| `ops.card` has status | source-confirmed | `plane-src/apps/api/plane/db/models/issue.py:119-125` | `Issue.state` links to `State`. |
| `ops.card` has priority | source-confirmed | `plane-src/apps/api/plane/db/models/issue.py:140-145` | `Issue.priority` is selected from `PRIORITY_CHOICES`. |
| `ops.card` has assignees | source-confirmed | `plane-src/apps/api/plane/db/models/issue.py:148-154`, `plane-src/apps/api/plane/db/models/issue.py:337-357` | `Issue.assignees` uses the `IssueAssignee` through model. |
| `ops.card` can have type | source-confirmed | `plane-src/apps/api/plane/db/models/issue.py:163-169`, `plane-src/apps/api/plane/db/models/issue_type.py:14-29` | `Issue.type` links to `IssueType`. |
| `ops.card` can relate to other cards | source-confirmed | `plane-src/apps/api/plane/db/models/issue.py:112-118`, `plane-src/apps/api/plane/db/models/issue.py:264-309` | `Issue.parent` and `IssueRelation` support hierarchical and typed cross-card relations. |
| `ops.card` can link to external systems | source-confirmed | `plane-src/apps/api/plane/db/models/issue.py:161-162` | `external_source` / `external_id` on Issue give source-backed external refs. |
## Guardrails Confirmed
```text
ops.card is the canonical NodeDC work object.
Plane Issue is a source alias for ops.card.
task / issue / work item are aliases or card types, not canonical roots.
ops.card_priority is a card attribute, not an OPS-wide root entity.
ops.card_type is source-backed by IssueType, but final NodeDC card type taxonomy is product-defined.
ops.responsible is not the same as ops.assignee.
ops.responsible remains product-required/source-adjacent until product semantics are defined.
ops.card_artifact_link is a relation/link, not a global artifact root.
ops.file_asset and ops.stored_blob are OPS-local source entities.
```
## Product / Architecture Notes
### OPS as assistant surface
OPS is likely the first high-value surface for ontology-backed assistant routing.
Near-term expected use:
```text
User is in OPS card/project context.
Assistant resolves workspace/project/card and can route requests to Engine or Gateway tools.
```
This requires:
- stable `ops.workspace` / `ops.project` / `ops.card` identifiers;
- aliases and external refs;
- clear relation from OPS card/project to Engine application/workflow context;
- scoped tool operations through OPS Gateway, not direct DB mutation.
### Responsible vs assignee
Current source confirms assignees strongly.
Source-adjacent evidence for broader responsibility exists at project level:
- `Project.default_assignee`
- `Project.project_lead`
But these do not fully define the product term `ops.responsible`.
Recommendation:
```text
Keep ops.responsible as product-required.
Define later whether it means owner, accountable person, reviewer, project lead, default assignee, or card-level responsibility role.
```
### Card type taxonomy
`IssueType` is source-confirmed, but NodeDC should not collapse product card semantics into raw Plane naming.
Recommendation:
```text
Use ops.card_type as canonical.
Map Plane IssueType into ops.card_type.
Allow future product taxonomy: task, report, milestone, note, request, automation output, etc.
```
## Open Questions / Follow-up
1. Define `ops.responsible` product semantics before implementing assistant routing around responsibility.
2. Decide canonical `ops.card_type` taxonomy and how it maps to Plane `IssueType`.
3. Later P1 pass should harden card artifacts/activity/external refs in a dedicated file.
4. OPS Gateway pass must confirm that assistant/tool writes happen through scoped operations, grants, idempotency, and audit.

77
services/ontology-core/docs/baseline/GUARDRAILS.md Normal file
View File

@ -0,0 +1,77 @@
# Ontology Guardrails v0.4-pre
Status: pre-release implementation baseline
Date: 2026-06-18
These rules exist to stop future agents and developers from merging similar-looking but different NodeDC concepts.
## Core Naming Rules
1. Use canonical IDs from `CANONICAL_ENTITY_CATALOG.md`.
2. Treat aliases as aliases, not new roots.
3. If source evidence is missing, mark the entity as `pending`; do not invent implementation facts.
4. Keep `source-confirmed`, `owner-confirmed`, `product-required`, and `future-concept` separate.
5. Use `ops.card` as the canonical work object. `Issue`, `task`, `work item`, and `ticket` are aliases or subtypes.
## HUB Guardrails
- `hub.open_contour` is not an ordinary `hub.client_context`.
- `hub.public_pool_client` is a special source-backed Client used by public pool context.
- `hub.public_user` and `hub.client_user` are classifications of `hub.user`, not separate hard user tables/classes unless future source proves otherwise.
- `hub.application_card` is presentation only. Access authority belongs to `hub.application_access`, `hub.app_grant`, and `hub.app_exception`.
- Authentik, OIDC, JWT, and provider-specific auth names are implementation aliases under `ndcauth.identity` / `ndcauth.session`.
## OPS Product Guardrails
- OPS Product is the operational work/project/card layer.
- OPS Product must not be derived from ENGINE-side `server/routes/ops.js` or Agent Monitor experiments.
- Plane `Issue` maps to canonical `ops.card`.
- `ops.card_priority` is a card attribute, not a global root entity.
- `ops.responsible` is not automatically equal to `ops.assignee`; keep the distinction until source/product semantics are finalized.
- `ops.card_artifact_link` is a relation/link to outputs, not a global artifact root.
## OPS Gateway Guardrails
- OPS Gateway is the scoped MCP/API access layer for agents.
- `agent.identity` is a Gateway execution identity, not a human user and not a universal assistant persona.
- `agent.token` is an opaque credential. Do not treat it as user identity.
- `agent.scope` is a tool/capability permission. Do not confuse it with HUB/OPS roles.
- Gateway writes must remain scoped, audited, and idempotent.
- Gateway does not own raw OPS product truth. Tasker/OPS remains source of truth for projects/cards.
- HUB remains source of truth for platform user/client/application entitlement.
## ENGINE Guardrails
- ENGINE is workflow/dev environment, not the final home for heavy product UIs.
- `engine.workflow_l1` is the NodeDC canvas/workflow graph.
- `engine.workflow_l2` is a runtime/subworkflow layer, currently n8n-backed.
- `engine.workflow_l2_runtime_id` is not the same as NodeDC `engine.workflow_l1` id.
- `engine.l2_run`, `engine.l2_session`, and current trace tables are useful evidence but are tech-debt-adjacent because they live in ENGINE-side OpsLayer.
- Do not turn ENGINE-side Agent Monitor/tender UI into core ontology roots.
- Procurement/tender concepts should later become a domain ontology package, not a core root.
## Future Interface Layer Guardrails
- Do not add new heavy custom product UI directly into ENGINE core.
- Future automation UI should live in a dedicated interface layer/service.
- ENGINE nodes may emit data/control bindings for that layer, but the layer owns views, widgets, dashboards, maps, forms, and control panels.
- Assistant-built interfaces must use ontology-backed meanings, not hardcoded one-off field guesses.
- Current tender/Agent Monitor UI is evidence of need and tech debt, not the target architecture.
## Assistant / MCP Routing Guardrails
- Assistant is not the same as Gateway identity.
- Codex, browser ChatGPT, MCP tool, local executor, and OPS Gateway are different execution surfaces.
- Ontology Core should help resolve target context before selecting grant/tool/workflow, especially for:
- OPS user asks to inspect or switch an Engine workflow.
- Engine user asks to create/update OPS cards.
- Assistant needs to choose project/workflow/card context by human-readable name.
- Browser ChatGPT can propose RFCs, but source evidence and accepted docs remain on disk.
## Data Safety Guardrails
- Do not read or copy env files, secrets, database dumps, storage, runtime buffers, logs, caches, build outputs, `node_modules`, or archives into ontology docs.
- Do not delete files unless explicitly asked by the user.
- Do not edit application source code from the ontology workspace.
- Do not run Docker/build/install/test for docs-only ontology work.

94
services/ontology-core/docs/baseline/IMPLEMENTATION_READINESS.md Normal file
View File

@ -0,0 +1,94 @@
# Implementation Readiness v0.4-pre
Status: ready to start first implementation phase
Date: 2026-06-18
This is the stop point for the current ontology design pass. The next phase is implementation planning/code, not more broad ontology discussion.
## Ready Baseline
The following documents form the implementation baseline:
- `CANONICAL_ENTITY_CATALOG.md`
- `RELATION_CATALOG.md`
- `GUARDRAILS.md`
- `TERMS_GLOSSARY.md`
- `EVIDENCE_LEDGER.md`
- `EVIDENCE_LEDGER_HUB_P0.md`
- `EVIDENCE_LEDGER_OPS_P0.md`
- `EVIDENCE_LEDGER_OPS_GATEWAY_P1.md`
- `EVIDENCE_LEDGER_ENGINE_DIRTY_BOUNDARY_P1.md`
- `EVIDENCE_LEDGER_ENGINE_WORKFLOW_P1.md`
- `ONTOLOGY_SERVICE_PLACEMENT_AND_USE_CASES.md`
- `OPEN_QUESTIONS.md`
## Target Home
Final platform home:
```text
/Users/dcconstructions/Downloads/mnt/NODEDC/platform/services/ontology-core
```
Current working home:
```text
/Users/dcconstructions/Downloads/mnt/NODEDC_ONTOLOGY
```
Do not move source repositories during this phase. The next implementation step can create a clean service skeleton under `platform/services/ontology-core` and copy accepted docs there.
## First Implementation Slice
1. Create `platform/services/ontology-core` as docs-first platform service/module.
2. Add machine-readable catalog files:
- `catalog/entities.json`
- `catalog/relations.json`
- `catalog/aliases.json`
- `catalog/guardrails.json`
- `catalog/evidence.json`
3. Add schema validation for entity/relation IDs and evidence statuses.
4. Add resolver MVP for two high-value flows:
- OPS -> ENGINE: resolve project/card/user request into Engine workflow/L1/L2 context.
- ENGINE -> OPS: resolve workflow/node/domain context into target OPS project/card path.
5. Add read-only lookup API or CLI only after schema and resolver rules are stable.
6. Wire OPS Gateway grant/tool preflight later; ontology advises context, Gateway enforces permission.
## Non-Goals For First Slice
- No database migration yet unless schema pressure requires it.
- No runtime refactor.
- No Engine-side OpsLayer cleanup.
- No tender/Agent Monitor rewrite.
- No full UI constructor yet.
- No broad domain ontology buildout.
- No secret/env/runtime/data/storage ingestion.
## First Useful Product Outcomes
- User in OPS can ask assistant to inspect, switch, or reason about an Engine workflow by human-readable project/workflow/card context.
- User in Engine can ask assistant to create/update the right OPS cards without manually switching OPS project context.
- Agents stop confusing:
- OPS Product;
- OPS Gateway;
- ENGINE-side OpsLayer.
- Future interface layer has a stable conceptual runway and does not repeat the current ENGINE hardcoded UI pattern.
## Handoff Prompt For Implementation
```text
Implement Ontology Core first slice as docs-first platform service at
/Users/dcconstructions/Downloads/mnt/NODEDC/platform/services/ontology-core.
Use /Users/dcconstructions/Downloads/mnt/NODEDC_ONTOLOGY/ontology as accepted baseline.
Do not edit HUB/OPS/Gateway/ENGINE source code in this task.
Create catalog JSON files and validation around canonical entity/relation/alias/guardrail data.
Focus first resolver MVP on OPS -> ENGINE and ENGINE -> OPS context routing.
Keep Gateway permissions as enforcement authority; ontology only resolves/advises context.
Do not read env/secrets/runtime/data/storage/logs/dumps.
```
## Stop Point
The ontology design pass should pause here. Additional browser ChatGPT creativity is useful only as RFC review against these files, not as a replacement for the accepted baseline.

340
services/ontology-core/docs/baseline/ONTOLOGY_SERVICE_PLACEMENT_AND_USE_CASES.md Normal file
View File

@ -0,0 +1,340 @@
# Ontology Service Placement and Near-Term Use Cases
Status: planning note
Date: 2026-06-18
Scope: architecture direction for NodeDC ontology work
## Current State
Current research workspace:
```text
/Users/dcconstructions/Downloads/mnt/NODEDC_ONTOLOGY
```
This workspace is a temporary documentation/write area for ontology design, evidence ledgers, guardrails, and open questions.
It should not be treated as the final production home.
Do not move it while the active ChatGPT `NodeDC Ontology Write` app points at this path. Moving it now would break the connector.
## Target Home
The ontology belongs in the platform layer, not as a random folder in `mnt`.
Recommended future home:
```text
/Users/dcconstructions/Downloads/mnt/NODEDC/platform/services/ontology-core
```
Alternative names:
```text
platform/services/ontology-registry
platform/services/context-registry
```
Recommended name for now:
```text
ontology-core
```
Reason:
- It is a platform service, not a feature of only HUB, OPS, or ENGINE.
- It should live near:
- `services/notification-core`
- `services/ai-workspace-assistant`
- `services/ai-workspace-hub`
- It should not own HUB/OPS/ENGINE domain data directly.
- It should own canonical cross-app meaning, aliases, relations, routing context, and guardrails.
## What Ontology Core Should Own
Ontology Core should own:
- canonical entity catalog;
- relation catalog;
- alias registry;
- evidence ledger;
- guardrails / forbidden conflations;
- cross-surface context mapping;
- future API for entity/relation resolution;
- future API for assistant/tool routing context.
Ontology Core should not own:
- Launcher users/clients/groups/access data;
- Plane/OPS cards/projects/workspaces/comments;
- Engine workflows/nodes/runtime events;
- Authentik identity/session data;
- Notification deliveries/read-state;
- actual source-code edits.
Domain data stays with the owning service. Ontology Core describes and connects meaning across services.
## Near-Term Product Use Case
The first practical value is cross-application assistant routing.
### OPS to ENGINE
Example:
```text
User is in OPS and asks Assistant:
"Replace the workflow for this project/card with another Engine workflow and then continue coding."
```
Expected future behavior:
1. Assistant knows current OPS surface context:
- workspace;
- project;
- card;
- selected assistant/project context.
2. Ontology resolves that OPS context to relevant Engine application boundary / workflow context.
3. Assistant can ask the correct Engine-side tool/action to inspect or switch workflow.
4. Engine remains owner of workflow internals.
5. OPS remains owner of card/project/task context.
6. The action is auditable and bounded by user permissions.
Ontology requirement:
```text
ops.card / ops.project / ops.workspace
can relate to
engine.application_boundary / engine.workflow_l1 / engine.workflow_l2
through explicit relation and permission context,
not by hardcoded UI assumptions.
```
### ENGINE to OPS
Example:
```text
User is in ENGINE and asks Assistant:
"Create OPS tasks for this workflow issue / describe next implementation steps in the right project."
```
Expected future behavior:
1. Assistant knows current Engine surface context:
- workflow;
- node;
- application boundary;
- selected assistant/project context.
2. Ontology resolves the target OPS workspace/project/card destination.
3. Assistant can create or update OPS cards through scoped OPS Gateway operations.
4. User should not have to manually switch assistant project if target can be resolved by name/context.
Ontology requirement:
```text
engine.workflow_l1 / engine.node_l1 / engine.application_boundary
can relate to
ops.workspace / ops.project / ops.card
through explicit routing relations and aliases.
```
## Why This Matters
Without ontology:
- Assistant context is surface-local.
- OPS assistant may not know the correct Engine workflow target.
- Engine assistant may not know the correct OPS project/card destination.
- Users must manually switch projects/surfaces.
- Workflows become hardcoded by UI glue and fragile assumptions.
With ontology:
- Assistant can resolve user intent across HUB, OPS, ENGINE, and platform services.
- Names, aliases, and relations can be normalized.
- Cross-app actions can be permissioned, audited, and routed.
- Future automation can target stable meanings instead of brittle file/UI paths.
## Design Guardrails
Ontology must stay flexible:
- Core ontology should stay small and stable.
- Task-specific entities can be added later per domain.
- Do not force every future use case into the first core catalog.
- Use statuses:
- `source-confirmed`
- `source-evidenced/context-derived`
- `product-required`
- `future concept`
- `tech debt / non-canonical`
- Dirty but working implementations should be marked as tech debt, not silently promoted into canonical product truth.
## Known Dirty Areas To Track
### Engine-side OPS / tender-agent / Agent Monitor
Status:
```text
tech debt / non-canonical
```
Do not use it as OPS product truth.
Future direction:
```text
automation control surface / UI constructor / automation work views
```
Automation nodes should emit structured data into a separate work/control layer rather than keeping heavy custom OPS-like UI inside ENGINE.
Clarification:
- `OPS product` means the separate operational system / Tasker surface with workspaces, projects, cards, statuses, labels, comments, and assignment.
- `Engine-side OPS / tender-agent / Agent Monitor` means the old custom workflow/UI implementation inside ENGINE. It is a working prototype/legacy slice, not the canonical OPS product model.
- Do not let the ontology merge these two meanings under one root.
- Treat the Engine-side tender UI as evidence for future interface needs, not as the final architecture.
### Future Interface / Automation UI Layer
Status:
```text
future concept / product-required soon
```
Strategic direction:
- ENGINE should remain a workflow/development environment.
- New heavy custom product interfaces should not be hardcoded inside ENGINE.
- Automation/workflow nodes should be able to emit structured data for a separate interface/control layer.
- A future platform service or app should own user-facing automation work views, dashboards, cards, maps, analytics panels, and other generated/custom UI surfaces.
- Assistants are expected to help assemble these interfaces from ontology-backed domain meanings and UI rules.
Possible future names:
```text
platform/services/interface-core
platform/services/automation-ui
platform/services/workview-core
platform/services/ui-workbench
```
No final name is selected yet.
The ontology must be ready to describe:
- domain entities and their aliases;
- workflow node outputs;
- UI view definitions;
- widget/control types;
- dashboard/work-view composition;
- source application and permission context;
- relation from OPS card/project or ENGINE workflow/node to the generated UI surface.
Near-term implication:
```text
Do not canonize the current tender-agent / Agent Monitor UI embedded in ENGINE.
Use it as a learning sample for what the future interface layer must support.
```
### Domain Ontology Expansion
Core ontology should stay compact, but it must leave a clean path for domain ontologies.
Expected domain families already visible from product direction:
- tenders / procurement;
- ecology;
- transport analytics;
- robotics / Helius-style analysis;
- business processes;
- ERP-like operational domains;
- future client-specific domains.
These domains should extend the core catalog rather than polluting the core roots.
Recommended shape:
```text
core ontology
-> platform/service/application/surface/user/card/workflow basics
domain ontology
-> domain-specific entities, fields, relations, UI views, and automation outputs
```
### Assistant Project / Surface Selection
Current concern:
```text
Assistant can be attached to one project/context at a time, forcing manual switching.
```
Ontology should support later resolution by:
- entity name;
- aliases;
- current surface;
- user permissions;
- project/workflow/card relation;
- explicit target override from the user.
This is a core near-term reason for building the ontology.
### MCP / Codex Config Routing
Current OPS Gateway already has a rough setup/config route:
```text
AI Workspace / Codex config
-> token-scoped MCP grant
-> OPS Gateway
-> Tasker internal adapter
```
Do not refactor this immediately.
Ontology can later improve this by resolving the correct target context before issuing or selecting grants:
- owner/user identity;
- active surface;
- OPS workspace/project/card;
- ENGINE application/workflow/node;
- explicit user target;
- aliases and product names;
- permitted tool/action set.
This keeps the current working MCP path while creating a path toward less manual config and safer assistant routing.
## Migration Plan
Short term:
1. Keep writing research docs in `NODEDC_ONTOLOGY`.
2. Finish evidence ledgers for HUB / OPS / OPS Gateway / ENGINE.
3. Create consolidated:
- `CANONICAL_ENTITY_CATALOG.md`
- `RELATION_CATALOG.md`
- `EVIDENCE_LEDGER.md`
- `GUARDRAILS.md`
- `OPEN_QUESTIONS.md`
Medium term:
1. Create `platform/services/ontology-core`.
2. Move accepted docs from `NODEDC_ONTOLOGY/ontology` into the service docs.
3. Reconnect ChatGPT write app to the final path.
4. Decide whether the service starts as docs-only, JSON registry, or API + DB.
Long term:
1. Add machine-readable catalog format.
2. Add resolver APIs for Assistant / OPS Gateway / Engine tools.
3. Add relation/evidence versioning.
4. Add permissions-aware context resolution.

63
services/ontology-core/docs/baseline/OPEN_QUESTIONS.md Normal file
View File

@ -0,0 +1,63 @@
# Open Questions v0.4-pre
Status: pre-release open question register
Date: 2026-06-18
No question below blocks the first Ontology Core implementation. These are the items to resolve during implementation or the next evidence pass.
## P0 Before First Code Merge
| ID | Question | Current stance |
| --- | --- | --- |
| `OQ-001` | What exact package/service shape starts `platform/services/ontology-core`? | Start docs-first + machine-readable catalog schema; add API/db only after resolver MVP needs it. |
| `OQ-002` | What is the first resolver use case? | OPS -> ENGINE workflow context and ENGINE -> OPS project/card context. |
| `OQ-003` | What is accepted source of truth for current docs? | `NODEDC_ONTOLOGY/ontology/*` until moved/copied into target platform service. |
## OPS Product Questions
| ID | Question | Current stance |
| --- | --- | --- |
| `OQ-101` | Exact `ops.responsible` semantics? | Keep distinct from `ops.assignee`; define during OPS card workflow hardening. |
| `OQ-102` | `ops.card_type` taxonomy? | Need explicit list: architecture block, task, report, milestone/mailstone, incident, decision, research, etc. |
| `OQ-103` | How should artifacts/files attach to cards? | Keep as `ops.card_artifact_link` until storage/file authority is clear. |
## OPS Gateway Questions
| ID | Question | Current stance |
| --- | --- | --- |
| `OQ-201` | Is `agent.ai_workspace_entitlement` a durable entity or a policy/flow? | Keep as source-evidenced pending boundary. |
| `OQ-202` | Pairing/setup flow exact route model? | Keep `agent.pairing_code` pending route hardening. |
| `OQ-203` | How should ontology select Gateway grants? | First version can be advisory/preflight; Gateway remains enforcement authority. |
## ENGINE Questions
| ID | Question | Current stance |
| --- | --- | --- |
| `OQ-301` | Should `engine.l2_run` and `engine.l2_session` be canonical long term? | They are source-confirmed but tech-debt-adjacent; keep but do not overbuild around current tables. |
| `OQ-302` | Where should future runtime observability live? | Candidate: dedicated runtime/observability package, not OPS Product and not final Interface Layer. |
| `OQ-303` | What is `engine.source_stamp` exactly? | Pending. Use only when implementation needs stable version/source traceability. |
| `OQ-304` | How to retire ENGINE-side tender/Agent Monitor UI? | Defer until Interface Layer MVP exists; mark as tech debt now. |
## Assistant / AI Workspace Questions
| ID | Question | Current stance |
| --- | --- | --- |
| `OQ-401` | Exact source entities for assistant/thread/message/provider/executor? | Dedicated AI Workspace source pass needed. |
| `OQ-402` | How much browser ChatGPT/codex bridge state becomes product state? | Treat current bridge as workflow/process, not product data model, until source exists. |
| `OQ-403` | Can ontology reduce MCP config/token routing pain? | Yes as resolver/preflight later; do not rewrite config flow in this phase. |
## Future Interface Layer Questions
| ID | Question | Current stance |
| --- | --- | --- |
| `OQ-501` | Final service name? | Candidate names: `interface-core`, `automation-ui`, `workview-core`, `ui-workbench`, `notg-controller-layer`. |
| `OQ-502` | First MVP view type? | Likely table/report/control panel over an Engine workflow output, not the full UI constructor. |
| `OQ-503` | How are view bindings emitted from Engine? | Future custom nodes should emit ontology-backed data/control bindings into a separate interface data layer. |
## Domain Ontology Questions
| ID | Question | Current stance |
| --- | --- | --- |
| `OQ-601` | Which domain package goes first? | Candidate: procurement/tenders because existing dirty implementation exposes many lessons. |
| `OQ-602` | How to handle ecology/transport/robotics/ERP domains? | Add as packages after core resolver and entity/relation schema stabilize. |

33
services/ontology-core/docs/baseline/README.md Normal file
View File

@ -0,0 +1,33 @@
# Ontology Documents
Primary documents:
- `CANONICAL_ENTITY_CATALOG.md`
- `RELATION_CATALOG.md`
- `EVIDENCE_LEDGER.md`
- `GUARDRAILS.md`
- `TERMS_GLOSSARY.md`
- `OPEN_QUESTIONS.md`
- `IMPLEMENTATION_READINESS.md`
Current accepted baseline:
- Canonical Entity Catalog v0.4-pre is the active pre-release baseline.
- HUB has an open contour and a managed client/company context.
- `hub.public_pool_client` is a source-backed special Client used by the public pool context.
- `hub.open_contour` must not be treated as an ordinary `hub.client_context`.
- `ops.card` is the canonical OPS work object.
- OPS Product, OPS Gateway, and ENGINE-side OpsLayer are different entities.
- ENGINE L1/L2 workflow split is source-evidenced enough for first resolver implementation.
- Engine-side OPS / Agent Monitor / tender-agent config is non-canonical tech debt.
- Future Interface Layer is a planned separate layer/service, not more custom UI inside ENGINE core.
Current working evidence artifacts:
- `EVIDENCE_HARDENING_PLAN_V0_3_1.md`
- `EVIDENCE_LEDGER_HUB_P0.md`
- `EVIDENCE_LEDGER_OPS_P0.md`
- `EVIDENCE_LEDGER_OPS_GATEWAY_P1.md`
- `EVIDENCE_LEDGER_ENGINE_DIRTY_BOUNDARY_P1.md`
- `EVIDENCE_LEDGER_ENGINE_WORKFLOW_P1.md`
- `ONTOLOGY_SERVICE_PLACEMENT_AND_USE_CASES.md`

90
services/ontology-core/docs/baseline/RELATION_CATALOG.md Normal file
View File

@ -0,0 +1,90 @@
# Relation Catalog v0.4-pre
Status: pre-release implementation baseline
Date: 2026-06-18
Relations are written as product-level semantics, not database foreign keys. Implementation can later map them to tables, APIs, MCP tools, or resolver rules.
## HUB Relations
| Relation ID | From | To | Meaning | Status |
| --- | --- | --- | --- | --- |
| `hub.open_contour.uses_public_pool` | `hub.open_contour` | `hub.public_pool_context` | Open contour is implemented through public pool context. | source-evidenced |
| `hub.public_pool_context.backed_by_client` | `hub.public_pool_context` | `hub.public_pool_client` | Public pool context uses a special source-backed Client. | source-confirmed |
| `hub.user.has_membership` | `hub.user` | `hub.membership` | User belongs to a context through membership. | source-confirmed |
| `hub.membership.in_context` | `hub.membership` | `hub.client_context` / `hub.public_pool_context` | Membership points to closed client context or public pool. | source-confirmed |
| `hub.access_request.targets_context` | `hub.access_request` | `hub.client_context` / `hub.public_pool_context` | Request targets a context. | source-confirmed |
| `hub.public_access_request.promotes_to_client_context` | `hub.public_access_request` | `hub.client_context` | Public request can become client membership after approval. | source-confirmed |
| `hub.invite.targets_context` | `hub.invite` | `hub.client_context` / `hub.public_pool_context` | Invite targets a context. | source-confirmed |
| `hub.application.has_access_result` | `hub.application` | `hub.application_access` | Application exposes effective access state. | source-confirmed |
| `hub.app_grant.grants_access_to` | `hub.app_grant` | `hub.application` | Grant contributes to effective access. | source-confirmed |
| `hub.app_exception.overrides_access_to` | `hub.app_exception` | `hub.application` | User-specific allow/deny exception. | source-confirmed |
| `hub.application_card.presents` | `hub.application_card` | `hub.application` | UI card presents app plus access state. | source-confirmed |
| `ndcauth.identity.maps_to_hub_user` | `ndcauth.identity` | `hub.user` | Auth subject resolves to launcher user. | source-confirmed |
## OPS Product Relations
| Relation ID | From | To | Meaning | Status |
| --- | --- | --- | --- | --- |
| `ops.workspace.contains_project` | `ops.workspace` | `ops.project` | Project belongs to workspace. | source-confirmed |
| `ops.workspace.has_member` | `ops.workspace` | `ops.workspace_member` | Workspace membership. | source-confirmed |
| `ops.project.has_member` | `ops.project` | `ops.project_member` | Project membership. | source-confirmed |
| `ops.project.contains_card` | `ops.project` | `ops.card` | Card belongs to project. | source-confirmed |
| `ops.card.has_status` | `ops.card` | `ops.card_status` | Card state. | source-confirmed |
| `ops.card.has_priority` | `ops.card` | `ops.card_priority` | Card priority attribute. | source-confirmed |
| `ops.card.assigned_to` | `ops.card` | `ops.assignee` | Card assignment. | source-confirmed |
| `ops.card.accountable_to` | `ops.card` | `ops.responsible` | Product-level responsibility relation. | product-required |
| `ops.card.typed_as` | `ops.card` | `ops.card_type` | Card subtype/purpose. | source-evidenced |
| `ops.card.related_to` | `ops.card` | `ops.card_relation` | Relation/dependency between cards. | source-confirmed |
| `ops.card.has_label` | `ops.card` | `ops.card_label` | Label/tag classification. | source-confirmed |
| `ops.card.has_comment` | `ops.card` | `ops.card_comment` | Discussion/comment relation. | source-confirmed |
| `ops.card.has_activity` | `ops.card` | `ops.card_activity` | Timeline/change relation. | source-evidenced |
| `ops.card.links_artifact` | `ops.card` | `ops.card_artifact_link` | Links output artifacts or docs. | source-evidenced |
| `ops.card.has_external_ref` | `ops.card` | `ops.external_ref` | Links external/source object. | source-confirmed |
## OPS Gateway Relations
| Relation ID | From | To | Meaning | Status |
| --- | --- | --- | --- | --- |
| `agent.token.represents_identity` | `agent.token` | `agent.identity` | Token authenticates agent identity, not user identity. | source-confirmed |
| `agent.identity.has_grant` | `agent.identity` | `agent.grant` | Identity receives grants. | source-confirmed |
| `agent.token.has_token_grant` | `agent.token` | `agent.token_grant` | Token-level grant binding. | source-confirmed |
| `agent.grant.allows_scope` | `agent.grant` | `agent.scope` | Grant enables tool/capability scope. | source-confirmed |
| `agent.scope.exposes_tool` | `agent.scope` | `agent.mcp_tool` | Scope controls MCP tool exposure. | source-confirmed |
| `agent.mcp_tool.writes_via_adapter` | `agent.mcp_tool` | `agent.tasker_adapter` | Gateway writes to OPS through adapter. | source-confirmed |
| `agent.mcp_tool.requires_idempotency` | `agent.mcp_tool` | `agent.idempotency_key` | Write operations require idempotency. | source-confirmed |
| `agent.mcp_tool.emits_audit` | `agent.mcp_tool` | `agent.audit_event` | Operations produce audit records. | source-confirmed |
| `agent.setup_packet.provisions_token` | `agent.setup_packet` | `agent.token` | Setup flow produces token/connect config. | source-evidenced |
## ENGINE Relations
| Relation ID | From | To | Meaning | Status |
| --- | --- | --- | --- | --- |
| `engine.workflow_l1.contains_node` | `engine.workflow_l1` | `engine.node_l1` | L1 workflow graph contains nodes. | source-confirmed |
| `engine.workflow_l1.contains_edge` | `engine.workflow_l1` | `engine.edge_l1` | L1 workflow graph contains edges. | source-confirmed |
| `engine.edge_l1.connects_nodes` | `engine.edge_l1` | `engine.node_l1` | Edge connects source/target node handles. | source-confirmed |
| `engine.node_l1.has_type` | `engine.node_l1` | `engine.node_type_l1` | Node type comes from registry/module. | source-confirmed |
| `engine.workflow_l1.has_acl` | `engine.workflow_l1` | `engine.workflow_acl` | Workflow uses access control. | source-confirmed |
| `engine.workflow_acl.has_owner` | `engine.workflow_acl` | `engine.workflow_owner` | ACL owns owner field. | source-confirmed |
| `engine.workflow_l1.has_share` | `engine.workflow_l1` | `engine.workflow_share` | Workflow can be shared/invited. | source-confirmed |
| `engine.workflow_l1.has_access_request` | `engine.workflow_l1` | `engine.workflow_access_request` | Access requests target workflow. | source-confirmed |
| `engine.node_l1.embeds_l2_workflow` | `engine.node_l1` | `engine.workflow_l2` | n8n subworkflow is attached to L1 node. | source-evidenced |
| `engine.workflow_l2.deployed_as_runtime_workflow` | `engine.workflow_l2` | `engine.workflow_l2_runtime_id` | Compiled n8n workflow deploy returns runtime workflow id. | source-confirmed |
| `engine.workflow_l2.runs_on_runtime_core` | `engine.workflow_l2` | `engine.l2_runtime_core` | L2 workflow targets n8n instance/core. | source-evidenced |
| `engine.l2_execution.belongs_to_runtime_workflow` | `engine.l2_execution` | `engine.workflow_l2_runtime_id` | Execution is emitted for n8n workflow id. | source-confirmed |
| `engine.l2_runtime_event.describes_execution` | `engine.l2_runtime_event` | `engine.l2_execution` | Runtime events carry execution id. | source-confirmed |
| `engine.l2_runtime_event.binds_run` | `engine.l2_runtime_event` | `engine.l2_run` | Event binds to run id. Current storage is ENGINE-side OpsLayer. | source-confirmed / tech-debt-adjacent |
| `engine.l2_run.has_session` | `engine.l2_run` | `engine.l2_session` | Session anchors related runtime events/runs. | source-confirmed / tech-debt-adjacent |
## Cross-Surface Relations Needed First
These are the first useful implementation targets for Ontology Core.
| Relation ID | From | To | Meaning | Status |
| --- | --- | --- | --- | --- |
| `ontology.resolves_ops_card_to_engine_context` | `ops.card` | `engine.workflow_l1` / `engine.workflow_l2` | Assistant in OPS can route a request to the correct Engine workflow context. | product-required |
| `ontology.resolves_engine_context_to_ops_project` | `engine.workflow_l1` / `engine.workflow_l2` | `ops.project` | Assistant in Engine can create/update cards in the correct OPS project. | product-required |
| `ontology.resolves_hub_app_to_project_context` | `hub.application` | `ops.project` / `engine.workflow_l1` | Application selection can suggest project/workflow context. | product-required |
| `ontology.selects_gateway_grant_context` | `assistant.bridge` | `agent.grant` | Ontology can help choose proper MCP/Gateway grant before tool calls. | product-required |
| `ontology.routes_interface_view_to_domain_package` | `future.interface_view` | `future.domain_package` | Future UI layer renders domain-specific views from ontology-backed data. | future-concept |

49
services/ontology-core/docs/baseline/TERMS_GLOSSARY.md Normal file
View File

@ -0,0 +1,49 @@
# Terms Glossary v0.4-pre
Status: pre-release glossary
Date: 2026-06-18
## Canonical Terms
| Term | Meaning |
| --- | --- |
| HUB | Launcher/application access layer with open and company/client contours. |
| Open contour | Public/open HUB branch for simple users and public pool access. |
| Client/company contour | Managed closed HUB context for companies/clients. |
| OPS Product | Operational work/project/card layer. |
| OPS Card | Canonical work object in OPS; Plane Issue/task/work item are aliases or subtypes. |
| OPS Gateway | Scoped MCP/API access layer for agents working with OPS. |
| Agent identity | Gateway execution identity, not a human user and not assistant persona. |
| Agent token | Opaque credential used by Gateway; not user identity. |
| ENGINE | Workflow/dev environment. |
| L1 workflow | NodeDC/React Flow canvas workflow. |
| L2 workflow | Runtime/subworkflow layer, currently n8n-backed. |
| Runtime workflow id | n8n runtime workflow id, separate from NodeDC L1 workflow id. |
| Runtime event | Event emitted by L2 runtime: workflow/node start/finish/success/error. |
| Assistant | Product assistant capability; exact source model pending AI Workspace pass. |
| Ontology Core | Future platform service/module for canonical entities, relations, aliases, evidence, and resolver rules. |
| Interface Layer | Future UI/workview layer for automation dashboards, maps, forms, and controls. |
| Domain package | Domain-specific ontology extension, e.g. tenders, ecology, transport, robotics, ERP. |
## Alias Rules
| Alias | Canonical term |
| --- | --- |
| Plane Issue | `ops.card` |
| task / ticket / work item | `ops.card` or `ops.card_type`, depending on context |
| Authentik user / OIDC subject / JWT subject | `ndcauth.identity` |
| Launcher service / app | `hub.application` |
| Application tile / app card | `hub.application_card` |
| n8n workflow id | `engine.workflow_l2_runtime_id` |
| n8n execution | `engine.l2_execution` |
| Engine-side OPS / Agent Monitor OPS | `engine.tech_debt.ops_layer`, not OPS Product |
| Tender Agent Monitor UI | `engine.tech_debt.tender_domain_ui`, not future Interface Layer |
## Forbidden Shortcuts
- Do not say "OPS" without specifying OPS Product, OPS Gateway, or ENGINE-side OpsLayer.
- Do not say "workflow" without specifying L1 workflow, L2 workflow, or runtime workflow id when ambiguity matters.
- Do not say "user" when the context needs HUB user, NDCAuth identity, OPS member, or Gateway agent identity.
- Do not say "task" as the root concept when the object is an OPS card.
- Do not treat current tender/Agent Monitor implementation as target architecture.

8
services/ontology-core/examples/assistant-access-admin-client.example.json Normal file
View File

@ -0,0 +1,8 @@
{
"assistantRole": "admin",
"launcherUserStatus": "active",
"launcherGlobalRole": "client_admin",
"membershipRole": "client_admin",
"membershipStatus": "active",
"groups": []
}

8
services/ontology-core/examples/assistant-access-blocked.example.json Normal file
View File

@ -0,0 +1,8 @@
{
"assistantRole": "admin",
"launcherUserStatus": "blocked",
"launcherGlobalRole": "client_admin",
"membershipRole": "client_admin",
"membershipStatus": "active",
"groups": []
}

8
services/ontology-core/examples/assistant-access-member.example.json Normal file
View File

@ -0,0 +1,8 @@
{
"assistantRole": "member",
"launcherUserStatus": "active",
"launcherGlobalRole": "member",
"membershipRole": "member",
"membershipStatus": "active",
"groups": []
}

6
services/ontology-core/examples/assistant-access-superadmin.example.json Normal file
View File

@ -0,0 +1,6 @@
{
"launcherUserStatus": "active",
"launcherGlobalRole": "root_admin",
"membershipStatus": "active",
"groups": ["nodedc:superadmin"]
}

8
services/ontology-core/examples/assistant-action-block-user.example.json Normal file
View File

@ -0,0 +1,8 @@
{
"intent": "заблокируй пользователя",
"assistantRole": "admin",
"membershipRole": "client_admin",
"actorUserId": "user_root",
"targetUserId": "user_silver_psih",
"confirmed": true
}

11
services/ontology-core/examples/assistant-action-change-assistant-role.example.json Normal file
View File

@ -0,0 +1,11 @@
{
"actionId": "hub.assistant_access.change_role",
"assistantRole": "admin",
"membershipRole": "client_admin",
"actorUserId": "user_root",
"targetUserId": "user_silver_psih",
"membershipId": "mem_client_public_pool_user_silver_psih",
"targetAssistantRole": "blocked",
"confirmed": true,
"idempotencyKey": "example:assistant-role:user_silver_psih:blocked"
}

8
services/ontology-core/examples/assistant-action-delete-user.example.json Normal file
View File

@ -0,0 +1,8 @@
{
"actionId": "hub.user.delete",
"assistantRole": "admin",
"membershipRole": "client_admin",
"actorUserId": "user_root",
"targetUserId": "user_silver_psih",
"confirmed": true
}

8
services/ontology-core/examples/assistant-action-engine-share.example.json Normal file
View File

@ -0,0 +1,8 @@
{
"actionId": "engine.workflow.share",
"assistantRole": "admin",
"membershipRole": "client_admin",
"actorUserId": "user_root",
"targetUserId": "user_silver_psih",
"confirmed": true
}

10
services/ontology-core/examples/assistant-action-self-lockout.example.json Normal file
View File

@ -0,0 +1,10 @@
{
"actionId": "hub.membership.disable",
"assistantRole": "admin",
"membershipRole": "client_admin",
"actorUserId": "user_root",
"targetUserId": "user_root",
"confirmed": true,
"removesOwnAccess": true,
"hasAlternativeAdminPath": false
}

12
services/ontology-core/examples/assistant-caller-preview-block-user.example.json Normal file
View File

@ -0,0 +1,12 @@
{
"phase": "preview",
"input": {
"actionId": "hub.user.block",
"assistantRole": "admin",
"membershipRole": "client_admin",
"actorUserId": "user_root",
"targetUserId": "user_silver_psih",
"confirmed": true,
"idempotencyKey": "example:caller:block:user_silver_psih"
}
}

12
services/ontology-core/examples/engine-context.example.json Normal file
View File

@ -0,0 +1,12 @@
{
"id": "context.engine.example.workflow",
"surface": "engine",
"entityId": "engine.workflow_l1",
"sourceSystem": "nodedc-engine",
"label": "Example Engine Workflow",
"status": "planned",
"refs": {
"workflow_id": "example-workflow-id",
"node_id": "example-node-id"
}
}

9
services/ontology-core/examples/engine-to-ops-request.json Normal file
View File

@ -0,0 +1,9 @@
{
"surface": "engine",
"entityId": "engine.workflow_l1",
"intent": "создай карточку в ops по текущему workflow",
"refs": {
"workflow_id": "example-workflow-id",
"node_id": "example-node-id"
}
}

19
services/ontology-core/examples/engine-workflow-manifest.example.json Normal file
View File

@ -0,0 +1,19 @@
{
"workflow": {
"id": "example-workflow-id",
"label": "Example Engine Workflow",
"nodeId": "example-node-id",
"runtimeWorkflowId": "example-n8n-runtime-workflow-id",
"n8nInstanceId": "example-n8n-instance"
},
"context": {
"status": "planned",
"sourceSystem": "nodedc-engine"
},
"bindToOps": {
"enabled": true,
"status": "planned",
"fromContextId": "context.ops.nodedc.ndc_platform.ontology_core_card",
"summary": "Example planned binding from Ontology Core OPS card to an Engine workflow context."
}
}

10
services/ontology-core/examples/ops-card-to-engine-request.json Normal file
View File

@ -0,0 +1,10 @@
{
"surface": "ops",
"alias": "issue",
"intent": "inspect engine workflow for this ontology card",
"refs": {
"workspace_slug": "nodedc",
"project_id": "86629a11-eaff-4ad2-9f89-e5245a344fcc",
"issue_id": "1312519a-0eda-4ea0-9e34-2113c3724ecf"
}
}

8
services/ontology-core/examples/ops-engine-binding.example.json Normal file
View File

@ -0,0 +1,8 @@
{
"id": "binding.ops.ontology_core_card.engine.example_workflow",
"typeId": "binding_type.ops_card_to_engine_workflow",
"status": "planned",
"fromContextId": "context.ops.nodedc.ndc_platform.ontology_core_card",
"toContextId": "context.engine.example.workflow",
"summary": "Example planned binding from Ontology Core OPS card to an Engine workflow context."
}

22
services/ontology-core/package.json Normal file
View File

@ -0,0 +1,22 @@
{
"name": "@nodedc/ontology-core",
"version": "0.1.0",
"private": true,
"type": "module",
"scripts": {
"assistant:action": "node src/assistant-action-resolver.mjs",
"assistant:caller": "node src/assistant-action-caller.mjs",
"assistant:execute": "node src/assistant-action-executor.mjs",
"assistant:plan": "node src/assistant-action-plan.mjs",
"assistant:policy": "node src/assistant-policy.mjs",
"registry": "node src/registry.mjs",
"resolve": "node src/resolver.mjs",
"validate": "node src/validate.mjs",
"smoke:assistant-action-plan": "node src/assistant-action-plan.mjs --smoke",
"smoke:assistant-caller": "node src/assistant-action-caller.mjs --smoke",
"smoke:assistant-executor": "node src/assistant-action-executor.mjs --smoke",
"smoke:assistant-actions": "node src/assistant-action-resolver.mjs --smoke",
"smoke:assistant-policy": "node src/assistant-policy.mjs --smoke",
"smoke:resolver": "node src/resolver.mjs --smoke"
}
}

199
services/ontology-core/src/adapters/hub-launcher-admin.mjs Normal file
View File

@ -0,0 +1,199 @@
import { resolveAssistantAction } from '../assistant-action-resolver.mjs'
const HUB_ACTIONS = new Set([
'hub.user.read_admin_summary',
'hub.invite.list_pending',
'hub.access_request.list_pending',
'hub.user.block',
'hub.user.unblock',
'hub.membership.change_role',
'hub.membership.disable',
'hub.assistant_access.change_role',
])
const MEMBERSHIP_ROLES = new Set(['client_owner', 'client_admin', 'member'])
const CORE_ASSISTANT_ROLES = new Set(['blocked', 'member', 'admin'])
function requireValue(input, key) {
const value = input[key]
if (value === undefined || value === null || String(value).trim() === '') {
throw new Error(`Missing required adapter input: ${key}`)
}
return String(value)
}
function encode(value) {
return encodeURIComponent(String(value))
}
function makeIdempotencyKey(actionId, input) {
if (input.idempotencyKey) return String(input.idempotencyKey)
return [
actionId,
input.actorUserId || 'actor_unknown',
input.targetUserId || input.membershipId || 'target_unknown',
input.targetRole || input.targetAssistantRole || input.targetStatus || 'default',
].join(':')
}
function patchPlan(actionId, input, path, body, summary) {
return {
method: 'PATCH',
path,
body,
headers: {
'Content-Type': 'application/json',
'Idempotency-Key': makeIdempotencyKey(actionId, input),
},
summary,
}
}
function buildPlanForAction(actionId, input) {
switch (actionId) {
case 'hub.user.read_admin_summary':
return {
method: 'GET',
path: '/api/admin/control-plane',
query: {
projection: 'users,memberships,services,grants,exceptions,invites,accessRequests',
clientId: input.clientId || null,
},
summary: 'Read admin-visible Launcher control-plane summary and filter in adapter output.',
}
case 'hub.invite.list_pending':
return {
method: 'GET',
path: '/api/admin/control-plane',
query: {
projection: 'invites',
status: 'pending',
clientId: input.clientId || null,
},
summary: 'Read Launcher invites and return pending invites visible in current admin scope.',
}
case 'hub.access_request.list_pending':
return {
method: 'GET',
path: '/api/admin/control-plane',
query: {
projection: 'accessRequests,engineWorkflowAccessRequests,users,clients',
status: 'pending',
clientId: input.clientId || null,
},
summary: 'Read Launcher access requests and return pending requests visible in current admin scope.',
}
case 'hub.user.block':
return patchPlan(
actionId,
input,
`/api/admin/users/${encode(requireValue(input, 'targetUserId'))}/profile`,
{ globalStatus: 'blocked' },
'Block Launcher user via guarded profile update route.',
)
case 'hub.user.unblock':
return patchPlan(
actionId,
input,
`/api/admin/users/${encode(requireValue(input, 'targetUserId'))}/profile`,
{ globalStatus: 'active' },
'Unblock Launcher user via guarded profile update route.',
)
case 'hub.membership.change_role': {
const targetRole = requireValue(input, 'targetRole')
if (!MEMBERSHIP_ROLES.has(targetRole)) {
throw new Error(`Invalid targetRole: ${targetRole}`)
}
return patchPlan(
actionId,
input,
`/api/admin/memberships/${encode(requireValue(input, 'membershipId'))}`,
{ role: targetRole },
'Change Launcher client membership role via guarded membership update route.',
)
}
case 'hub.membership.disable':
return patchPlan(
actionId,
input,
`/api/admin/memberships/${encode(requireValue(input, 'membershipId'))}`,
{ status: 'disabled' },
'Disable Launcher client membership via guarded membership update route.',
)
case 'hub.assistant_access.change_role': {
const targetAssistantRole = requireValue(input, 'targetAssistantRole')
if (!CORE_ASSISTANT_ROLES.has(targetAssistantRole)) {
throw new Error(`Invalid targetAssistantRole: ${targetAssistantRole}`)
}
return patchPlan(
actionId,
input,
`/api/admin/memberships/${encode(requireValue(input, 'membershipId'))}`,
{ coreAssistantRole: targetAssistantRole },
'Change NDC Core Assistant access role via guarded membership update route.',
)
}
default:
throw new Error(`Unsupported HUB action: ${actionId}`)
}
}
export async function buildHubLauncherAdminPlan(input = {}, options = {}) {
const decision = options.decision || await resolveAssistantAction(input, options)
const actionId = decision.action?.id
if (!actionId) {
return {
ok: false,
decision: 'unsupported_hub_action',
reason: 'Input did not resolve to a supported HUB Launcher admin action.',
actionDecision: decision,
}
}
if (
decision.decision !== 'allowed' &&
!(options.planPreview === true && decision.decision === 'needs_confirmation')
) {
return {
ok: false,
decision: decision.decision,
reason: decision.reason,
actionDecision: decision,
}
}
if (!HUB_ACTIONS.has(actionId)) {
return {
ok: false,
decision: 'unsupported_hub_action',
reason: 'Input did not resolve to a supported HUB Launcher admin action.',
actionDecision: decision,
}
}
const plan = buildPlanForAction(actionId, input)
const adapterReady = decision.action.adapterStatus === 'implemented'
return {
ok: true,
decision: 'planned',
adapterId: 'adapter.hub.launcher_admin_api',
adapterStatus: decision.action.adapterStatus,
executionReady: adapterReady,
dryRunOnly: !adapterReady,
gatewayActor: {
userId: input.actorUserId || null,
email: input.actorEmail || null,
subject: input.actorSubject || null,
},
safety: {
noDeleteRouteMapped: true,
requiresExternalExecutor: true,
sourceGuardedRoutesOnly: true,
confirmationAlreadyChecked: decision.execution.confirmed || options.planPreview === true,
},
request: plan,
actionDecision: decision,
}
}

303
services/ontology-core/src/adapters/ops-product-api.mjs Normal file
View File

@ -0,0 +1,303 @@
import { createHash } from 'node:crypto'
import { resolveAssistantAction } from '../assistant-action-resolver.mjs'
const OPS_PRODUCT_API_ADAPTER_ID = 'adapter.ops.product_api'
const OPS_ACTIONS = new Set([
'ops.card.list_recent',
'ops.card.create',
'ops.card.add_comment',
])
const OPS_CARD_PRIORITIES = new Set(['none', 'low', 'medium', 'high', 'urgent'])
function cleanString(value) {
return String(value || '').trim()
}
function cleanText(value, max = 4000) {
const text = cleanString(value)
if (!text) return ''
return text.length > max ? text.slice(0, max).trim() : text
}
function cleanLimit(value) {
const number = Number(value)
if (!Number.isFinite(number)) return 5
return Math.min(20, Math.max(1, Math.trunc(number)))
}
function firstString(...values) {
for (const value of values) {
const text = cleanString(value)
if (text) return text
}
return ''
}
function normalizeProjectQuery(input = {}) {
return {
workspaceSlug: firstString(
input.workspaceSlug,
input.workspace_slug,
input.opsWorkspaceSlug,
input.ops_workspace_slug,
input.context?.workspaceSlug,
input.context?.opsWorkspaceSlug,
),
projectId: firstString(
input.projectId,
input.project_id,
input.opsProjectId,
input.ops_project_id,
input.context?.projectId,
input.context?.opsProjectId,
),
}
}
function cleanPriority(value) {
const text = cleanString(value).toLowerCase()
return OPS_CARD_PRIORITIES.has(text) ? text : ''
}
function cleanIssueId(value) {
return cleanString(value).replace(/^#/, '')
}
function idempotencyKeyFor(actionId, input, fallbackParts = {}) {
const explicit = firstString(
input.idempotencyKey,
input.idempotency_key,
input.context?.idempotencyKey,
input.context?.idempotency_key,
)
if (explicit) return explicit
const digest = createHash('sha256')
.update(JSON.stringify({
actionId,
actorUserId: input.actorUserId || null,
actorEmail: input.actorEmail || null,
...fallbackParts,
}))
.digest('hex')
.slice(0, 24)
return `ai-workspace:${actionId}:${digest}`
}
function buildPlanForAction(actionId, input = {}, options = {}) {
switch (actionId) {
case 'ops.card.list_recent': {
const normalized = normalizeProjectQuery(input)
const workspaceSlug = normalized.workspaceSlug || cleanString(options.defaultOpsWorkspaceSlug)
const projectId = normalized.projectId || cleanString(options.defaultOpsProjectId)
const limit = cleanLimit(input.limit)
if (!projectId) {
return {
ok: false,
decision: 'ops_project_context_missing',
reason: 'OPS project id is required for reading cards.',
}
}
return {
ok: true,
request: {
method: 'GET',
path: '/api/v1/tools/issues',
query: {
project_id: projectId,
...(workspaceSlug ? { workspace_slug: workspaceSlug } : {}),
...(cleanString(input.query || input.search) ? { query: cleanString(input.query || input.search) } : {}),
},
summary: 'Read recent OPS Product cards through local Ops Gateway REST tool route.',
},
opsContext: {
workspaceSlug,
projectId,
limit,
},
}
}
case 'ops.card.create': {
const normalized = normalizeProjectQuery(input)
const workspaceSlug = normalized.workspaceSlug || cleanString(options.defaultOpsWorkspaceSlug)
const projectId = normalized.projectId || cleanString(options.defaultOpsProjectId)
const title = cleanText(
firstString(input.title, input.name, input.cardTitle, input.taskTitle, input.summary),
260,
)
const description = cleanText(
firstString(input.description, input.body, input.details, input.text, input.message),
12000,
)
const priority = cleanPriority(input.priority)
if (!projectId) {
return {
ok: false,
decision: 'ops_project_context_missing',
reason: 'OPS project id is required for creating a card.',
}
}
if (!title) {
return {
ok: false,
decision: 'ops_card_title_missing',
reason: 'OPS card title is required.',
}
}
const body = {
project_id: projectId,
...(workspaceSlug ? { workspace_slug: workspaceSlug } : {}),
title,
...(description ? { description } : {}),
...(priority ? { priority } : {}),
}
return {
ok: true,
request: {
method: 'POST',
path: '/api/v1/tools/issues',
headers: {
'Idempotency-Key': idempotencyKeyFor(actionId, input, body),
},
body,
summary: 'Create OPS Product card through local Ops Gateway REST tool route.',
},
opsContext: {
workspaceSlug,
projectId,
},
}
}
case 'ops.card.add_comment': {
const normalized = normalizeProjectQuery(input)
const workspaceSlug = normalized.workspaceSlug || cleanString(options.defaultOpsWorkspaceSlug)
const projectId = normalized.projectId || cleanString(options.defaultOpsProjectId)
const issueId = cleanIssueId(firstString(
input.issueId,
input.issue_id,
input.cardId,
input.card_id,
input.targetCardId,
input.target_card_id,
input.context?.issueId,
input.context?.issue_id,
input.context?.cardId,
input.context?.card_id,
))
const bodyText = cleanText(
firstString(input.body, input.comment, input.text, input.message),
12000,
)
if (!projectId) {
return {
ok: false,
decision: 'ops_project_context_missing',
reason: 'OPS project id is required for commenting on a card.',
}
}
if (!issueId) {
return {
ok: false,
decision: 'ops_issue_id_missing',
reason: 'OPS issue id is required for commenting on a card.',
}
}
if (!bodyText) {
return {
ok: false,
decision: 'ops_comment_body_missing',
reason: 'OPS comment body is required.',
}
}
const body = {
project_id: projectId,
...(workspaceSlug ? { workspace_slug: workspaceSlug } : {}),
body: bodyText,
}
return {
ok: true,
request: {
method: 'POST',
path: `/api/v1/tools/issues/${encodeURIComponent(issueId)}/comments`,
headers: {
'Idempotency-Key': idempotencyKeyFor(actionId, input, { issueId, ...body }),
},
body,
summary: 'Append comment to OPS Product card through local Ops Gateway REST tool route.',
},
opsContext: {
workspaceSlug,
projectId,
issueId,
},
}
}
default:
return {
ok: false,
decision: 'unsupported_ops_action',
reason: `Unsupported OPS action: ${actionId}`,
}
}
}
export async function buildOpsProductPlan(input = {}, options = {}) {
const decision = options.decision || await resolveAssistantAction(input, options)
const actionId = decision.action?.id
if (!actionId || !OPS_ACTIONS.has(actionId)) {
return {
ok: false,
decision: 'unsupported_ops_action',
reason: 'Input did not resolve to a supported OPS Product action.',
actionDecision: decision,
}
}
if (decision.decision !== 'allowed') {
return {
ok: false,
decision: decision.decision,
reason: decision.reason,
actionDecision: decision,
}
}
const actionPlan = buildPlanForAction(actionId, input, options)
if (!actionPlan.ok) {
return {
...actionPlan,
actionDecision: decision,
}
}
return {
ok: true,
decision: 'planned',
adapterId: OPS_PRODUCT_API_ADAPTER_ID,
adapterStatus: decision.action.adapterStatus,
executionReady: decision.execution?.executionReady === true,
dryRunOnly: decision.action.adapterStatus !== 'implemented',
actionDecision: decision,
gatewayActor: {
userId: input.actorUserId || null,
email: input.actorEmail || null,
subject: input.actorSubject || null,
},
request: actionPlan.request,
opsContext: actionPlan.opsContext,
safety: {
noDeleteRouteMapped: true,
sourceGuardedRoutesOnly: true,
confirmationAlreadyChecked: true,
},
}
}

268
services/ontology-core/src/assistant-action-caller.mjs Normal file
View File

@ -0,0 +1,268 @@
import fs from 'node:fs/promises'
import { executeAssistantAction } from './assistant-action-executor.mjs'
import { validateCatalog } from './validate.mjs'
function actionFromResult(result) {
return result?.plan?.actionDecision?.action || null
}
function actorFromResult(result) {
return result?.plan?.actionDecision?.actor || null
}
function requestFromResult(result) {
return result?.plan?.request || null
}
function executionStateFromResult(result) {
const action = actionFromResult(result)
const request = requestFromResult(result)
const confirmationEnvelope = result?.confirmationEnvelope || null
return {
adapterId: result?.plan?.adapterId || action?.adapterId || null,
adapterStatus: result?.plan?.adapterStatus || action?.adapterStatus || null,
executionReady: Boolean(result?.plan?.executionReady),
requiresUserConfirmation: Boolean(confirmationEnvelope),
requiresInternalToken: Boolean(result?.plan?.adapterId === 'adapter.hub.launcher_admin_api'),
method: request?.method || null,
path: request?.path || null,
idempotencyKey: request?.headers?.['Idempotency-Key'] || request?.headers?.['idempotency-key'] || null,
}
}
function previewFromDryRun(result) {
const action = actionFromResult(result)
const actor = actorFromResult(result)
const request = requestFromResult(result)
const confirmationEnvelope = result?.confirmationEnvelope || null
return {
ok: Boolean(result?.ok),
phase: 'preview',
decision: result?.ok ? 'preview_ready' : result?.decision || 'preview_blocked',
reason: result?.reason || null,
action,
actor,
preview: {
app: action?.app || null,
actionId: action?.id || null,
riskLevel: action?.riskLevel || null,
confirmationMode: action?.confirmationMode || null,
expectedEffect: confirmationEnvelope?.expectedEffect || action?.summary || request?.summary || null,
request: request ? {
method: request.method,
path: request.path,
query: request.query || null,
body: request.body ?? null,
} : null,
safeAlternatives: result?.plan?.actionDecision?.safeAlternatives || [],
},
confirmation: confirmationEnvelope ? {
token: confirmationEnvelope.token,
version: confirmationEnvelope.version,
expectedEffect: confirmationEnvelope.expectedEffect,
summary: confirmationEnvelope.summary,
request: confirmationEnvelope.request,
} : null,
execution: executionStateFromResult(result),
raw: result,
}
}
function executeResponseFromResult(result) {
const action = actionFromResult(result)
const request = requestFromResult(result)
return {
ok: Boolean(result?.ok),
phase: 'execute',
decision: result?.decision || 'execution_unknown',
reason: result?.reason || null,
action,
execution: executionStateFromResult(result),
request: request ? {
method: request.method,
path: request.path,
query: request.query || null,
body: request.body ?? null,
} : null,
result: result?.result || null,
confirmation: result?.confirmationEnvelope ? {
token: result.confirmationEnvelope.token,
version: result.confirmationEnvelope.version,
expectedEffect: result.confirmationEnvelope.expectedEffect,
} : null,
raw: result,
}
}
export async function previewAssistantAction(input = {}, options = {}) {
// Preview must build the write plan and confirmation envelope without doing I/O.
// The actual execute phase still requires the returned confirmation token.
const dryRun = await executeAssistantAction({
...input,
confirmed: true,
}, {
...options,
planPreview: true,
mode: 'dry-run',
allowNetworkExecution: false,
})
return previewFromDryRun(dryRun)
}
export async function executeAssistantCallerAction(input = {}, options = {}) {
const executed = await executeAssistantAction({
...input,
confirmed: true,
}, {
...options,
mode: 'execute',
allowNetworkExecution: true,
confirmationToken: options.confirmationToken || input.confirmationToken || input.confirmation?.token || null,
})
return executeResponseFromResult(executed)
}
export async function handleAssistantCallerRequest(payload = {}, options = {}) {
const phase = payload.phase || payload.mode || 'preview'
const input = payload.input || payload
if (phase === 'preview' || phase === 'dry-run') {
return previewAssistantAction(input, options)
}
if (phase === 'execute') {
return executeAssistantCallerAction(input, {
...options,
confirmationToken: payload.confirmationToken || input.confirmationToken || options.confirmationToken || null,
})
}
return {
ok: false,
phase,
decision: 'caller_phase_unknown',
reason: `Unsupported assistant caller phase: ${phase}`,
}
}
async function readInputJson() {
const inputIndex = process.argv.indexOf('--input-json')
if (inputIndex >= 0) {
const inputPath = process.argv[inputIndex + 1]
if (!inputPath) throw new Error('--input-json requires a path')
return JSON.parse(await fs.readFile(inputPath, 'utf8'))
}
const inlineIndex = process.argv.indexOf('--input')
if (inlineIndex >= 0) {
return JSON.parse(process.argv[inlineIndex + 1] || '{}')
}
return null
}
function readArg(name) {
const index = process.argv.indexOf(name)
if (index === -1) return null
return process.argv[index + 1] || null
}
function assertSmoke(condition, message) {
if (!condition) throw new Error(message)
}
async function runSmoke() {
const validation = await validateCatalog()
assertSmoke(validation.ok, 'catalog must validate before caller smoke')
const writeInput = {
actionId: 'hub.user.block',
assistantRole: 'admin',
membershipRole: 'client_admin',
actorUserId: 'user_root',
targetUserId: 'user_pupa',
confirmed: true,
idempotencyKey: 'smoke:caller:block:user_pupa',
}
const preview = await previewAssistantAction(writeInput)
const executeWithoutToken = await executeAssistantCallerAction(writeInput, {
baseUrl: 'http://launcher.local.test',
launcherInternalToken: 'smoke-token',
fetchImpl: async () => {
throw new Error('fetch must not run without confirmation token')
},
})
const mockCalls = []
const executeWithToken = await executeAssistantCallerAction({
...writeInput,
confirmationToken: preview.confirmation?.token,
}, {
baseUrl: 'http://launcher.local.test',
launcherInternalToken: 'smoke-token',
fetchImpl: async (url, init) => {
mockCalls.push({ url: String(url), init })
return {
ok: true,
status: 200,
statusText: 'OK',
headers: { get: () => 'application/json' },
text: async () => JSON.stringify({ ok: true, source: 'mock-launcher' }),
}
},
})
const readPreview = await previewAssistantAction({
actionId: 'hub.user.read_admin_summary',
assistantRole: 'admin',
groups: ['nodedc:superadmin'],
actorUserId: 'user_root',
})
assertSmoke(preview.decision === 'preview_ready', 'write preview should be ready')
assertSmoke(Boolean(preview.confirmation?.token), 'write preview should include confirmation token')
assertSmoke(preview.execution.requiresUserConfirmation, 'write preview should require user confirmation')
assertSmoke(executeWithoutToken.reason === 'write_confirmation_envelope_missing', 'execute without token must be blocked')
assertSmoke(executeWithToken.decision === 'executed', 'execute with token should call adapter')
assertSmoke(mockCalls.length === 1, 'execute with token should issue one request')
assertSmoke(readPreview.decision === 'preview_ready', 'read preview should be ready')
assertSmoke(readPreview.confirmation === null, 'read preview should not require confirmation token')
return {
ok: true,
validation: validation.counts,
cases: {
preview,
executeWithoutToken,
executeWithToken,
readPreview,
},
}
}
if (import.meta.url === `file://${process.argv[1]}`) {
if (process.argv.includes('--smoke')) {
console.log(JSON.stringify(await runSmoke(), null, 2))
} else {
const payload = await readInputJson()
if (!payload) throw new Error('Use --smoke, --input <json>, or --input-json <path>')
const output = await handleAssistantCallerRequest(payload, {
baseUrl: readArg('--base-url') || process.env.NDC_LAUNCHER_BASE_URL || null,
confirmationToken: readArg('--confirmation-token') || null,
launcherInternalToken:
readArg('--launcher-internal-token') ||
readArg('--internal-token') ||
process.env.NDC_LAUNCHER_INTERNAL_ACCESS_TOKEN ||
process.env.NODEDC_INTERNAL_ACCESS_TOKEN ||
process.env.NODEDC_PLATFORM_SERVICE_TOKEN ||
null,
})
console.log(JSON.stringify(output, null, 2))
}
}

994
services/ontology-core/src/assistant-action-executor.mjs Normal file
View File

@ -0,0 +1,994 @@
import fs from 'node:fs/promises'
import { createHash } from 'node:crypto'
import { buildHubLauncherAdminPlan } from './adapters/hub-launcher-admin.mjs'
import { buildOpsProductPlan } from './adapters/ops-product-api.mjs'
import { resolveAssistantAction } from './assistant-action-resolver.mjs'
import { validateCatalog } from './validate.mjs'
const WRITE_METHODS = new Set(['PATCH', 'POST', 'PUT'])
const HUB_LAUNCHER_ADMIN_ADAPTER_ID = 'adapter.hub.launcher_admin_api'
const OPS_PRODUCT_API_ADAPTER_ID = 'adapter.ops.product_api'
const ASSISTANT_GATEWAY_NAME = 'ontology-core'
const CONFIRMATION_ENVELOPE_VERSION = 'assistant-write-confirmation-v1'
const ALLOWED_ROUTES = [
{ method: 'GET', pattern: /^\/api\/admin\/control-plane$/ },
{ method: 'PATCH', pattern: /^\/api\/admin\/users\/[^/?#]+\/profile$/ },
{ method: 'PATCH', pattern: /^\/api\/admin\/memberships\/[^/?#]+$/ },
]
const OPS_ALLOWED_ROUTES = [
{ method: 'GET', pattern: /^\/api\/v1\/tools\/issues$/ },
{ method: 'POST', pattern: /^\/api\/v1\/tools\/issues$/ },
{ method: 'POST', pattern: /^\/api\/v1\/tools\/issues\/[^/?#]+\/comments$/ },
]
function headerValue(headers, key) {
const wanted = key.toLowerCase()
for (const [candidateKey, value] of Object.entries(headers || {})) {
if (candidateKey.toLowerCase() === wanted) return value
}
return null
}
function normalizeMethod(method) {
return String(method || '').trim().toUpperCase()
}
function isAllowedRoute(method, path) {
return ALLOWED_ROUTES.some((route) => route.method === method && route.pattern.test(path))
}
function isAllowedOpsRoute(method, path) {
return OPS_ALLOWED_ROUTES.some((route) => route.method === method && route.pattern.test(path))
}
function appendQuery(url, query = {}) {
for (const [key, value] of Object.entries(query || {})) {
if (value === null || value === undefined || value === '') continue
url.searchParams.set(key, String(value))
}
}
function buildRequestUrl(baseUrl, request) {
if (!baseUrl) throw new Error('baseUrl is required for network execution')
const url = new URL(request.path, baseUrl.endsWith('/') ? baseUrl : `${baseUrl}/`)
appendQuery(url, request.query)
return url
}
function readResponseHeader(headers, key) {
if (!headers) return ''
if (typeof headers.get === 'function') return headers.get(key) || ''
return headerValue(headers, key) || ''
}
function normalizeHeaderString(value) {
return String(value || '').trim()
}
function stableJson(value) {
if (Array.isArray(value)) {
return `[${value.map((item) => stableJson(item)).join(',')}]`
}
if (value && typeof value === 'object') {
return `{${Object.keys(value)
.sort()
.map((key) => `${JSON.stringify(key)}:${stableJson(value[key])}`)
.join(',')}}`
}
return JSON.stringify(value)
}
function confirmationDigest(payload) {
return createHash('sha256').update(stableJson(payload)).digest('hex').slice(0, 24)
}
function buildWriteConfirmationEnvelope(plan) {
const request = plan?.request || {}
const method = normalizeMethod(request.method)
if (!WRITE_METHODS.has(method)) return null
const action = plan?.actionDecision?.action || {}
const actor = plan?.gatewayActor || {}
const payload = {
version: CONFIRMATION_ENVELOPE_VERSION,
actionId: action.id || null,
app: action.app || null,
adapterId: plan?.adapterId || null,
actor: {
userId: actor.userId || null,
email: actor.email || null,
subject: actor.subject || null,
},
request: {
method,
path: String(request.path || ''),
body: request.body ?? null,
idempotencyKey: headerValue(request.headers, 'Idempotency-Key') || null,
},
}
return {
...payload,
token: confirmationDigest(payload),
riskLevel: action.riskLevel || null,
confirmationMode: action.confirmationMode || null,
expectedEffect: action.summary || request.summary || null,
summary: request.summary || null,
}
}
function readConfirmationToken(input = {}, options = {}) {
return normalizeHeaderString(
options.confirmationToken ||
input.confirmationToken ||
input.confirmation?.token ||
input.confirmationEnvelope?.token,
)
}
function verifyWriteConfirmationEnvelope(input, options, envelope) {
if (!envelope) return { ok: true }
const providedToken = readConfirmationToken(input, options)
if (!providedToken) {
return {
ok: false,
reason: 'write_confirmation_envelope_missing',
}
}
if (providedToken !== envelope.token) {
return {
ok: false,
reason: 'write_confirmation_envelope_mismatch',
}
}
return { ok: true }
}
function buildBearerHeader(token) {
const value = normalizeHeaderString(token)
if (!value) return ''
return /^Bearer\s+/i.test(value) ? value : `Bearer ${value}`
}
function buildHubLauncherGatewayHeaders(plan, options = {}) {
if (plan?.adapterId !== HUB_LAUNCHER_ADMIN_ADAPTER_ID) {
return { ok: true, headers: {} }
}
const token = normalizeHeaderString(options.launcherInternalToken || options.internalAccessToken)
if (!token) {
return {
ok: false,
reason: 'launcher_internal_token_missing',
}
}
const actor = options.gatewayActor || plan.gatewayActor || {}
const actorUserId = normalizeHeaderString(actor.userId)
const actorEmail = normalizeHeaderString(actor.email)
const actorSubject = normalizeHeaderString(actor.subject)
if (!actorUserId && !actorEmail && !actorSubject) {
return {
ok: false,
reason: 'assistant_gateway_actor_missing',
}
}
return {
ok: true,
headers: {
Authorization: buildBearerHeader(token),
'X-NODEDC-Assistant-Gateway': ASSISTANT_GATEWAY_NAME,
...(actorUserId ? { 'X-NODEDC-Assistant-Actor-User-Id': actorUserId } : {}),
...(actorEmail ? { 'X-NODEDC-Assistant-Actor-Email': actorEmail } : {}),
...(actorSubject ? { 'X-NODEDC-Assistant-Actor-Subject': actorSubject } : {}),
},
}
}
function endpointOrigin(value) {
try {
return new URL(value).origin
} catch {
return ''
}
}
function firstArray(...values) {
for (const value of values) {
if (Array.isArray(value)) return value
}
return []
}
function entitlementOpsGrant(payload) {
const grants = payload?.appGrants || payload?.grant || payload?.appGrant || payload?.entitlement || payload?.entitlements
if (grants?.ops && typeof grants.ops === 'object') return grants.ops
if (payload?.ops && typeof payload.ops === 'object') return payload.ops
return null
}
function authorizationFromOpsGrant(grant) {
const servers = firstArray(grant?.mcpServers, grant?.mcp_servers)
for (const server of servers) {
const headers = server?.httpHeaders || server?.headers || {}
const authorization = normalizeHeaderString(headerValue(headers, 'Authorization'))
if (authorization) return authorization
}
return ''
}
function omitEmptyObject(value = {}) {
const out = {}
for (const [key, raw] of Object.entries(value || {})) {
const text = normalizeHeaderString(raw)
if (text) out[key] = text
}
return out
}
async function resolveOpsAuthorization(plan, options = {}) {
const explicit = buildBearerHeader(options.opsRunToken || options.opsGatewayToken)
if (explicit) return { ok: true, authorization: explicit }
const entitlementUrl = normalizeHeaderString(options.opsEntitlementUrl)
const entitlementAuthorization = normalizeHeaderString(
options.opsEntitlementAuthorization || buildBearerHeader(options.opsEntitlementToken),
)
if (!entitlementUrl || !entitlementAuthorization) {
return {
ok: false,
reason: 'ops_entitlement_not_configured',
}
}
const actor = options.gatewayActor || plan.gatewayActor || {}
const opsContext = plan.opsContext || {}
const fetchImpl = options.fetchImpl || globalThis.fetch
if (typeof fetchImpl !== 'function') {
throw new Error('No fetch implementation available')
}
const owner = omitEmptyObject({
userId: actor.userId,
email: actor.email,
ownerKey: actor.subject,
})
const ops = omitEmptyObject({
workspaceSlug: opsContext.workspaceSlug,
projectId: opsContext.projectId,
})
const response = await fetchImpl(entitlementUrl, {
method: 'POST',
headers: {
Accept: 'application/json',
'Content-Type': 'application/json',
Authorization: entitlementAuthorization,
},
body: JSON.stringify({
schemaVersion: 'ai-workspace.entitlement-request.v1',
appId: 'ops',
owner,
runContext: {
...(Object.keys(ops).length ? { ops } : {}),
...omitEmptyObject({
opsWorkspaceSlug: opsContext.workspaceSlug,
opsProjectId: opsContext.projectId,
}),
},
activeContext: {},
requestedAt: new Date().toISOString(),
}),
})
const payload = await readResponsePayload(response)
if (!response.ok || payload?.ok === false) {
return {
ok: false,
reason: payload?.error || payload?.message || `ops_entitlement_http_${response.status}`,
}
}
const grant = entitlementOpsGrant(payload)
const authorization = authorizationFromOpsGrant(grant)
if (!authorization) {
return {
ok: false,
reason: grant?.status || 'ops_entitlement_token_missing',
grantStatus: grant?.status || null,
grantContext: grant?.context || null,
}
}
return { ok: true, authorization }
}
async function buildGatewayHeaders(plan, options = {}) {
if (plan?.adapterId === HUB_LAUNCHER_ADMIN_ADAPTER_ID) {
return buildHubLauncherGatewayHeaders(plan, options)
}
if (plan?.adapterId === OPS_PRODUCT_API_ADAPTER_ID) {
const resolved = await resolveOpsAuthorization(plan, options)
if (!resolved.ok) return resolved
return {
ok: true,
headers: {
Authorization: resolved.authorization,
Accept: 'application/json',
},
}
}
return { ok: true, headers: {} }
}
async function readResponsePayload(response) {
const raw = typeof response.text === 'function' ? await response.text() : ''
const contentType = readResponseHeader(response.headers, 'content-type')
if (!raw) return null
if (contentType.includes('application/json')) {
try {
return JSON.parse(raw)
} catch {
return raw
}
}
return raw
}
function planActionId(plan) {
return String(plan?.actionDecision?.action?.id || '').trim()
}
function dataArray(payload, key) {
const value = payload?.data?.[key]
return Array.isArray(value) ? value : []
}
function isPendingLikeStatus(value) {
const status = String(value || '').trim().toLowerCase()
return ['new', 'pending', 'requested', 'open', 'waiting', 'submitted'].includes(status)
}
function compactAccessRequest(item = {}) {
return {
id: item.id || null,
email: item.email || null,
name: [item.lastName, item.firstName, item.middleName].filter(Boolean).join(' ').trim() || null,
company: item.company || null,
phone: item.phone || null,
status: item.status || null,
targetClientId: item.targetClientId || null,
role: item.role || null,
createdAt: item.createdAt || null,
updatedAt: item.updatedAt || null,
}
}
function compactInvite(item = {}) {
return {
id: item.id || null,
email: item.email || item.inviteeEmail || null,
status: item.status || null,
clientId: item.clientId || item.targetClientId || null,
role: item.role || null,
createdAt: item.createdAt || null,
updatedAt: item.updatedAt || null,
}
}
function compactUser(item = {}) {
return {
id: item.id || null,
name: item.name || null,
email: item.email || null,
globalStatus: item.globalStatus || null,
}
}
function compactMembership(item = {}) {
return {
id: item.id || null,
clientId: item.clientId || null,
userId: item.userId || null,
role: item.role || null,
status: item.status || null,
coreAssistantRole: item.coreAssistantRole || null,
}
}
function firstIssueArray(payload) {
return firstArray(
payload?.issues,
payload?.items,
payload?.results,
payload?.data?.issues,
payload?.data?.items,
payload?.data?.results,
Array.isArray(payload?.data) ? payload.data : null,
)
}
function firstObject(...values) {
for (const value of values) {
if (value && typeof value === 'object' && !Array.isArray(value)) return value
}
return null
}
function issueTimestamp(item = {}) {
const value = item.updatedAt || item.updated_at || item.createdAt || item.created_at || item.created || item.updated
const time = Date.parse(value)
return Number.isFinite(time) ? time : 0
}
function compactIssue(item = {}) {
const state = item.state && typeof item.state === 'object' ? item.state : null
const project = item.project && typeof item.project === 'object' ? item.project : null
return {
id: item.id || item.issue_id || null,
identifier: item.identifier || item.sequence_id || item.issueIdentifier || item.issue_identifier || null,
title: item.title || item.name || item.subject || null,
description: item.description || null,
state: state?.name || item.stateName || item.state_name || item.state || null,
priority: item.priority || null,
projectId: item.project_id || item.projectId || project?.id || null,
projectName: item.project_name || item.projectName || project?.name || null,
createdAt: item.createdAt || item.created_at || item.created || null,
updatedAt: item.updatedAt || item.updated_at || item.updated || null,
url: item.url || item.web_url || item.webUrl || null,
}
}
function compactComment(item = {}) {
return {
id: item.id || item.comment_id || item.commentId || null,
issueId: item.issue_id || item.issueId || item.issue?.id || null,
body: item.body || item.comment || item.text || null,
createdAt: item.createdAt || item.created_at || item.created || null,
updatedAt: item.updatedAt || item.updated_at || item.updated || null,
}
}
function normalizeOpsPayload(plan, payload) {
if (!payload || typeof payload !== 'object') return payload
const actionId = planActionId(plan)
if (actionId === 'ops.card.create') {
const issue = firstObject(
payload.issue,
payload.card,
payload.data?.issue,
payload.data?.card,
payload.data,
)
return {
card: issue ? compactIssue(issue) : null,
source: 'ops-agent-gateway',
context: plan.opsContext || null,
rawOk: payload.ok ?? null,
}
}
if (actionId === 'ops.card.add_comment') {
const comment = firstObject(
payload.comment,
payload.issueComment,
payload.data?.comment,
payload.data?.issueComment,
payload.data,
)
return {
comment: comment ? compactComment(comment) : null,
source: 'ops-agent-gateway',
context: plan.opsContext || null,
rawOk: payload.ok ?? null,
}
}
if (actionId !== 'ops.card.list_recent') return payload
const limit = Number(plan?.opsContext?.limit || 5)
const issues = firstIssueArray(payload)
.slice()
.sort((a, b) => issueTimestamp(b) - issueTimestamp(a))
.slice(0, Math.max(1, Math.min(20, Number.isFinite(limit) ? limit : 5)))
.map(compactIssue)
return {
counts: {
cards: issues.length,
},
latestCard: issues[0] || null,
cards: issues,
source: 'ops-agent-gateway',
context: plan.opsContext || null,
}
}
function normalizeExecutionPayload(plan, payload) {
if (plan?.adapterId === OPS_PRODUCT_API_ADAPTER_ID) {
return normalizeOpsPayload(plan, payload)
}
return normalizeControlPlanePayload(plan, payload)
}
function normalizeControlPlanePayload(plan, payload) {
if (!payload || typeof payload !== 'object') return payload
const actionId = planActionId(plan)
const counts = payload.counts && typeof payload.counts === 'object' ? payload.counts : {}
const accessRequests = dataArray(payload, 'accessRequests')
const pendingAccessRequests = accessRequests.filter((item) => isPendingLikeStatus(item?.status))
const engineRequests = dataArray(payload, 'engineWorkflowAccessRequests')
const pendingEngineRequests = engineRequests.filter((item) => isPendingLikeStatus(item?.status))
const invites = dataArray(payload, 'invites')
const pendingInvites = invites.filter((item) => isPendingLikeStatus(item?.status))
if (actionId === 'hub.access_request.list_pending') {
return {
actor: payload.actor || null,
counts: {
accessRequests: counts.accessRequests ?? accessRequests.length,
engineWorkflowAccessRequests: counts.engineWorkflowAccessRequests ?? engineRequests.length,
},
summary: {
accessRequests: accessRequests.length,
pendingAccessRequests: pendingAccessRequests.length,
engineWorkflowAccessRequests: engineRequests.length,
pendingEngineWorkflowAccessRequests: pendingEngineRequests.length,
newAccessRequests: pendingAccessRequests.map((item) => item.email).filter(Boolean),
},
accessRequests: pendingAccessRequests.map(compactAccessRequest),
engineWorkflowAccessRequests: pendingEngineRequests.map(compactAccessRequest),
}
}
if (actionId === 'hub.invite.list_pending') {
return {
actor: payload.actor || null,
counts: {
invites: counts.invites ?? invites.length,
},
summary: {
invites: invites.length,
pendingInvites: pendingInvites.length,
pendingInviteEmails: pendingInvites.map((item) => item.email || item.inviteeEmail).filter(Boolean),
},
invites: pendingInvites.map(compactInvite),
}
}
if (actionId === 'hub.user.read_admin_summary') {
return {
actor: payload.actor || null,
counts,
summary: {
users: counts.users ?? dataArray(payload, 'users').length,
memberships: counts.memberships ?? dataArray(payload, 'memberships').length,
services: counts.services ?? dataArray(payload, 'services').length,
grants: counts.grants ?? dataArray(payload, 'grants').length,
invites: counts.invites ?? invites.length,
accessRequests: counts.accessRequests ?? accessRequests.length,
pendingAccessRequests: pendingAccessRequests.length,
newAccessRequests: pendingAccessRequests.map((item) => item.email).filter(Boolean),
},
users: dataArray(payload, 'users').map(compactUser),
memberships: dataArray(payload, 'memberships').map(compactMembership),
accessRequests: pendingAccessRequests.map(compactAccessRequest),
}
}
return payload
}
export function validateExecutionPlan(plan) {
const errors = []
const warnings = []
const request = plan?.request || {}
const method = normalizeMethod(request.method)
const path = String(request.path || '')
const adapterId = plan?.adapterId || plan?.actionDecision?.action?.adapterId || ''
if (!plan?.ok) {
errors.push('plan_not_ok')
}
if (!method) {
errors.push('request_method_missing')
}
if (method === 'DELETE') {
errors.push('delete_method_forbidden')
}
if (adapterId === OPS_PRODUCT_API_ADAPTER_ID) {
if (!path.startsWith('/api/v1/tools/')) {
errors.push('request_path_not_ops_tools_api')
}
if (!['GET', 'POST'].includes(method)) {
errors.push(`method_not_allowed:${method || 'empty'}`)
}
if (method && path && !isAllowedOpsRoute(method, path)) {
errors.push(`route_not_allowlisted:${method} ${path}`)
}
if (method === 'GET' && !request.query?.project_id) {
errors.push('ops_project_id_missing')
}
if (method === 'POST' && !request.body?.project_id) {
errors.push('ops_project_id_missing')
}
} else {
if (!path.startsWith('/api/admin/')) {
errors.push('request_path_not_admin_api')
}
if (!['GET', 'PATCH'].includes(method)) {
errors.push(`method_not_allowed:${method || 'empty'}`)
}
if (method && path && !isAllowedRoute(method, path)) {
errors.push(`route_not_allowlisted:${method} ${path}`)
}
}
if (WRITE_METHODS.has(method) && !headerValue(request.headers, 'Idempotency-Key')) {
errors.push('write_requires_idempotency_key')
}
if (WRITE_METHODS.has(method) && plan?.safety?.confirmationAlreadyChecked !== true) {
errors.push('write_requires_prior_confirmation_check')
}
if (plan?.actionDecision?.action?.riskLevel === 'destructive') {
errors.push('destructive_action_forbidden')
}
if (plan?.actionDecision?.decision === 'forbidden') {
errors.push('forbidden_action_decision')
}
if (plan?.safety?.noDeleteRouteMapped !== true) {
warnings.push('no_delete_route_mapping_not_asserted')
}
if (plan?.safety?.sourceGuardedRoutesOnly !== true) {
warnings.push('source_guarded_routes_only_not_asserted')
}
return {
ok: errors.length === 0,
errors,
warnings,
method,
path,
}
}
async function executeHttpPlan(plan, options) {
const request = plan.request
const method = normalizeMethod(request.method)
const url = buildRequestUrl(options.baseUrl, request)
const headers = {
...(request.headers || {}),
...(options.headers || {}),
}
const init = {
method,
headers,
}
if (method !== 'GET' && request.body !== undefined) {
if (!headerValue(headers, 'Content-Type')) {
headers['Content-Type'] = 'application/json'
}
if (!headerValue(headers, 'Accept')) {
headers.Accept = 'application/json'
}
init.body = JSON.stringify(request.body)
}
const fetchImpl = options.fetchImpl || globalThis.fetch
if (typeof fetchImpl !== 'function') {
throw new Error('No fetch implementation available')
}
const response = await fetchImpl(url, init)
const payload = normalizeExecutionPayload(plan, await readResponsePayload(response))
return {
ok: Boolean(response.ok),
status: response.status,
statusText: response.statusText || '',
url: String(url),
method,
payload,
}
}
async function buildAssistantExecutionPlan(input = {}, options = {}) {
const decision = options.decision || await resolveAssistantAction(input, options)
const adapterId = decision?.action?.adapterId
if (adapterId === OPS_PRODUCT_API_ADAPTER_ID) {
return buildOpsProductPlan(input, { ...options, decision })
}
return buildHubLauncherAdminPlan(input, { ...options, decision })
}
function executionBaseUrlForPlan(plan, options = {}) {
if (plan?.adapterId === OPS_PRODUCT_API_ADAPTER_ID) {
return normalizeHeaderString(options.opsGatewayBaseUrl) || endpointOrigin(options.opsEntitlementUrl)
}
return normalizeHeaderString(options.baseUrl)
}
export async function executeAssistantAction(input = {}, options = {}) {
const mode = options.mode || 'dry-run'
const plan = options.plan || await buildAssistantExecutionPlan(input, options)
const safety = validateExecutionPlan(plan)
const confirmationEnvelope = buildWriteConfirmationEnvelope(plan)
if (!safety.ok) {
return {
ok: false,
decision: 'execution_blocked',
reason: 'execution_safety_check_failed',
safety,
confirmationEnvelope,
plan,
}
}
if (mode !== 'execute') {
return {
ok: true,
decision: 'dry_run',
reason: 'network_execution_not_requested',
safety,
confirmationEnvelope,
plan,
result: null,
}
}
if (!options.allowNetworkExecution) {
return {
ok: false,
decision: 'execution_blocked',
reason: 'network_execution_not_enabled',
safety,
confirmationEnvelope,
plan,
}
}
if ((plan.dryRunOnly || plan.adapterStatus !== 'implemented') && !options.allowPlannedAdapterExecution) {
return {
ok: false,
decision: 'execution_blocked',
reason: 'adapter_not_marked_implemented',
safety,
confirmationEnvelope,
plan,
}
}
const baseUrl = executionBaseUrlForPlan(plan, options)
if (!baseUrl) {
return {
ok: false,
decision: 'execution_blocked',
reason: plan?.adapterId === OPS_PRODUCT_API_ADAPTER_ID ? 'ops_gateway_base_url_missing' : 'base_url_missing',
safety,
confirmationEnvelope,
plan,
}
}
const confirmationCheck = verifyWriteConfirmationEnvelope(input, options, confirmationEnvelope)
if (!confirmationCheck.ok) {
return {
ok: false,
decision: 'execution_blocked',
reason: confirmationCheck.reason,
safety,
confirmationEnvelope,
plan,
}
}
const gatewayHeaders = await buildGatewayHeaders(plan, options)
if (!gatewayHeaders.ok) {
return {
ok: false,
decision: 'execution_blocked',
reason: gatewayHeaders.reason,
safety,
confirmationEnvelope,
plan,
}
}
const result = await executeHttpPlan(plan, {
...options,
baseUrl,
headers: {
...(options.headers || {}),
...gatewayHeaders.headers,
},
})
return {
ok: result.ok,
decision: result.ok ? 'executed' : 'execution_failed',
safety,
confirmationEnvelope,
plan,
result,
}
}
async function readInputJson() {
const inputIndex = process.argv.indexOf('--input-json')
if (inputIndex >= 0) {
const inputPath = process.argv[inputIndex + 1]
if (!inputPath) throw new Error('--input-json requires a path')
return JSON.parse(await fs.readFile(inputPath, 'utf8'))
}
const inlineIndex = process.argv.indexOf('--input')
if (inlineIndex >= 0) {
return JSON.parse(process.argv[inlineIndex + 1] || '{}')
}
return null
}
function readArg(name) {
const index = process.argv.indexOf(name)
if (index === -1) return null
return process.argv[index + 1] || null
}
function assertSmoke(condition, message) {
if (!condition) throw new Error(message)
}
async function runSmoke() {
const validation = await validateCatalog()
assertSmoke(validation.ok, 'catalog must validate before executor smoke')
const blockInput = {
actionId: 'hub.user.block',
assistantRole: 'admin',
membershipRole: 'client_admin',
actorUserId: 'user_root',
targetUserId: 'user_pupa',
confirmed: true,
idempotencyKey: 'smoke:execute:block:user_pupa',
}
const dryRun = await executeAssistantAction(blockInput)
const executeWithoutConfirmation = await executeAssistantAction(blockInput, {
mode: 'execute',
allowNetworkExecution: true,
baseUrl: 'http://launcher.local.test',
})
const confirmedBlockInput = {
...blockInput,
confirmationToken: dryRun.confirmationEnvelope?.token,
}
const executeBlocked = await executeAssistantAction(confirmedBlockInput, {
mode: 'execute',
allowNetworkExecution: true,
baseUrl: 'http://launcher.local.test',
})
const mockCalls = []
const mockFetch = async (url, init) => {
mockCalls.push({ url: String(url), init })
return {
ok: true,
status: 200,
statusText: 'OK',
headers: { get: () => 'application/json' },
text: async () => JSON.stringify({ ok: true, source: 'mock-launcher' }),
}
}
const mockExecuted = await executeAssistantAction(confirmedBlockInput, {
mode: 'execute',
allowNetworkExecution: true,
baseUrl: 'http://launcher.local.test',
launcherInternalToken: 'smoke-token',
fetchImpl: mockFetch,
})
const deleteBlocked = await executeAssistantAction({
actionId: 'hub.user.delete',
assistantRole: 'admin',
membershipRole: 'client_admin',
actorUserId: 'user_root',
targetUserId: 'user_pupa',
confirmed: true,
}, {
mode: 'execute',
allowNetworkExecution: true,
allowPlannedAdapterExecution: true,
baseUrl: 'http://launcher.local.test',
fetchImpl: mockFetch,
})
const badDeletePlanSafety = validateExecutionPlan({
ok: true,
adapterStatus: 'implemented',
dryRunOnly: false,
safety: {
noDeleteRouteMapped: false,
sourceGuardedRoutesOnly: false,
confirmationAlreadyChecked: true,
},
actionDecision: {
decision: 'allowed',
action: { riskLevel: 'privileged' },
},
request: {
method: 'DELETE',
path: '/api/admin/users/user_pupa',
headers: { 'Idempotency-Key': 'bad-delete' },
},
})
assertSmoke(dryRun.decision === 'dry_run', 'default executor mode must be dry_run')
assertSmoke(Boolean(dryRun.confirmationEnvelope?.token), 'dry-run write should return confirmation envelope token')
assertSmoke(executeWithoutConfirmation.reason === 'write_confirmation_envelope_missing', 'write execution must require confirmation envelope token')
assertSmoke(executeBlocked.reason === 'launcher_internal_token_missing', 'confirmed implemented gateway adapter must require an internal token')
assertSmoke(mockExecuted.decision === 'executed', 'mock execution should execute with gateway auth headers')
assertSmoke(mockCalls.length === 1, 'mock execution should issue exactly one request')
assertSmoke(mockCalls[0].init.method === 'PATCH', 'mock execution should use PATCH')
assertSmoke(mockCalls[0].url === 'http://launcher.local.test/api/admin/users/user_pupa/profile', 'mock execution should hit profile route')
assertSmoke(mockCalls[0].init.headers.Authorization === 'Bearer smoke-token', 'mock execution should send internal bearer token')
assertSmoke(mockCalls[0].init.headers['X-NODEDC-Assistant-Gateway'] === ASSISTANT_GATEWAY_NAME, 'mock execution should send assistant gateway header')
assertSmoke(mockCalls[0].init.headers['X-NODEDC-Assistant-Actor-User-Id'] === 'user_root', 'mock execution should send actor user id')
assertSmoke(deleteBlocked.decision === 'execution_blocked', 'delete action must block before network execution')
assertSmoke(!badDeletePlanSafety.ok && badDeletePlanSafety.errors.includes('delete_method_forbidden'), 'DELETE plan must fail safety check')
return {
ok: true,
validation: validation.counts,
cases: {
dryRun,
executeWithoutConfirmation,
executeBlocked,
mockExecuted,
deleteBlocked,
badDeletePlanSafety,
},
}
}
if (import.meta.url === `file://${process.argv[1]}`) {
if (process.argv.includes('--smoke')) {
console.log(JSON.stringify(await runSmoke(), null, 2))
} else {
const input = await readInputJson()
if (!input) throw new Error('Use --smoke, --input <json>, or --input-json <path>')
const allowPlannedAdapterExecution =
process.argv.includes('--allow-planned-adapter-execution') &&
process.env.NDC_ASSISTANT_EXECUTOR_UNSAFE_DEV === '1'
const output = await executeAssistantAction(input, {
mode: process.argv.includes('--execute') ? 'execute' : 'dry-run',
allowNetworkExecution: process.argv.includes('--execute'),
allowPlannedAdapterExecution,
baseUrl: readArg('--base-url') || process.env.NDC_LAUNCHER_BASE_URL || null,
confirmationToken: readArg('--confirmation-token') || null,
launcherInternalToken:
readArg('--launcher-internal-token') ||
readArg('--internal-token') ||
process.env.NDC_LAUNCHER_INTERNAL_ACCESS_TOKEN ||
process.env.NODEDC_INTERNAL_ACCESS_TOKEN ||
process.env.NODEDC_PLATFORM_SERVICE_TOKEN ||
null,
})
console.log(JSON.stringify(output, null, 2))
}
}

78
services/ontology-core/src/assistant-action-plan.mjs Normal file
View File

@ -0,0 +1,78 @@
import fs from 'node:fs/promises'
import { buildHubLauncherAdminPlan } from './adapters/hub-launcher-admin.mjs'
import { validateCatalog } from './validate.mjs'
async function readInputJson() {
const inputIndex = process.argv.indexOf('--input-json')
if (inputIndex >= 0) {
const inputPath = process.argv[inputIndex + 1]
if (!inputPath) throw new Error('--input-json requires a path')
return JSON.parse(await fs.readFile(inputPath, 'utf8'))
}
const inlineIndex = process.argv.indexOf('--input')
if (inlineIndex >= 0) {
return JSON.parse(process.argv[inlineIndex + 1] || '{}')
}
return null
}
function assertSmoke(condition, message) {
if (!condition) throw new Error(message)
}
async function runSmoke() {
const validation = await validateCatalog()
assertSmoke(validation.ok, 'catalog must validate before adapter plan smoke')
const cases = {
blockUser: await buildHubLauncherAdminPlan({
actionId: 'hub.user.block',
assistantRole: 'admin',
membershipRole: 'client_admin',
actorUserId: 'user_root',
targetUserId: 'user_pupa',
confirmed: true,
idempotencyKey: 'smoke:block:user_pupa',
}),
assistantRole: await buildHubLauncherAdminPlan({
actionId: 'hub.assistant_access.change_role',
assistantRole: 'admin',
membershipRole: 'client_admin',
actorUserId: 'user_root',
targetUserId: 'user_pupa',
membershipId: 'mem_client_public_pool_user_pupa',
targetAssistantRole: 'blocked',
confirmed: true,
idempotencyKey: 'smoke:assistant-role:user_pupa',
}),
deleteUser: await buildHubLauncherAdminPlan({
actionId: 'hub.user.delete',
assistantRole: 'admin',
membershipRole: 'client_admin',
actorUserId: 'user_root',
targetUserId: 'user_pupa',
confirmed: true,
}),
}
assertSmoke(cases.blockUser.ok, 'block user should produce a HUB adapter plan')
assertSmoke(cases.blockUser.request.method === 'PATCH', 'block user should use PATCH')
assertSmoke(cases.blockUser.request.body.globalStatus === 'blocked', 'block user should set globalStatus=blocked')
assertSmoke(cases.assistantRole.ok, 'assistant role change should produce a HUB adapter plan')
assertSmoke(cases.assistantRole.request.body.coreAssistantRole === 'blocked', 'assistant role should set coreAssistantRole=blocked')
assertSmoke(!cases.deleteUser.ok, 'delete user must not produce an adapter plan')
return { ok: true, validation: validation.counts, cases }
}
if (import.meta.url === `file://${process.argv[1]}`) {
if (process.argv.includes('--smoke')) {
console.log(JSON.stringify(await runSmoke(), null, 2))
} else {
const input = await readInputJson()
if (!input) throw new Error('Use --smoke, --input <json>, or --input-json <path>')
console.log(JSON.stringify(await buildHubLauncherAdminPlan(input), null, 2))
}
}

331
services/ontology-core/src/assistant-action-resolver.mjs Normal file
View File

@ -0,0 +1,331 @@
import fs from 'node:fs/promises'
import { loadCatalog } from './catalog.mjs'
import { resolveAssistantAccess } from './assistant-policy.mjs'
import { validateCatalog } from './validate.mjs'
function normalizeText(value) {
return String(value || '').trim().toLowerCase()
}
function tokenize(value) {
return normalizeText(value)
.split(/[^a-zа-яё0-9_]+/iu)
.filter(Boolean)
}
function unique(values) {
return [...new Set(values)]
}
function actionSearchText(action) {
return [
action.id,
action.app,
action.domain,
action.summary,
...(action.intentAliases || []),
].join(' ')
}
function scoreAction(action, input) {
if (input.actionId && input.actionId === action.id) return 1000
const query = normalizeText(input.intent || input.term || input.text || input.query)
if (!query) return 0
const aliases = (action.intentAliases || []).map(normalizeText)
if (aliases.includes(query)) return 200
if (aliases.some((alias) => alias && query.includes(alias))) return 160
const queryTokens = new Set(tokenize(query))
if (!queryTokens.size) return 0
const actionTokens = new Set(tokenize(actionSearchText(action)))
let score = 0
for (const token of queryTokens) {
if (actionTokens.has(token)) score += 10
}
if (input.app && input.app === action.app) score += 20
return score
}
function findAction(catalog, input) {
const candidates = catalog.assistantActions.actions
.map((action) => ({ action, score: scoreAction(action, input) }))
.filter((candidate) => candidate.score > 0)
.sort((a, b) => b.score - a.score || a.action.id.localeCompare(b.action.id))
return {
selected: candidates[0]?.action || null,
candidates: candidates.slice(0, 5).map(({ action, score }) => ({
id: action.id,
app: action.app,
riskLevel: action.riskLevel,
confirmationMode: action.confirmationMode,
adapterStatus: action.adapterStatus,
score,
summary: action.summary,
})),
}
}
function collectSafeAlternativeIds(action, riskPolicy) {
const ids = [...(action.safeAlternativeActionIds || [])]
for (const denyId of action.hardDenyIds || []) {
const deny = riskPolicy.hardDenies.find((candidate) => candidate.id === denyId)
ids.push(...(deny?.safeAlternatives || []))
}
return unique(ids.filter((id) => id !== action.id))
}
function describeAlternatives(ids, actionById) {
return ids.map((id) => {
const action = actionById.get(id)
return {
id,
app: action?.app || null,
riskLevel: action?.riskLevel || null,
confirmationMode: action?.confirmationMode || null,
summary: action?.summary || null,
}
})
}
function missingCapabilities(action, access) {
const allowed = new Set(access.allowedCapabilities || [])
return (action.capabilityIds || []).filter((capabilityId) => !allowed.has(capabilityId))
}
function isSelfTarget(input) {
if (!input.actorUserId || !input.targetUserId) return false
return String(input.actorUserId) === String(input.targetUserId)
}
function makeDecision(decision, action, input, access, extra = {}) {
return {
ok: decision === 'allowed',
decision,
action: action ? {
id: action.id,
app: action.app,
domain: action.domain,
riskLevel: action.riskLevel,
confirmationMode: action.confirmationMode,
selfActionPolicy: action.selfActionPolicy,
adapterId: action.adapterId,
adapterStatus: action.adapterStatus,
requiredScopes: action.requiredScopes || [],
capabilityIds: action.capabilityIds || [],
summary: action.summary,
} : null,
actor: {
assistantRole: input.assistantRole || null,
effectiveRole: access?.effectiveRole || null,
adminScope: access?.adminScope || null,
},
execution: action ? {
policyAllowed: decision === 'allowed',
adapterReady: action.adapterStatus === 'implemented',
executionReady: decision === 'allowed' && action.adapterStatus === 'implemented',
requiresConfirmation: action.confirmationMode === 'explicit' || action.confirmationMode === 'typed',
confirmed: Boolean(input.confirmed),
} : null,
...extra,
}
}
export async function resolveAssistantAction(input = {}, options = {}) {
const catalog = options.catalog || await loadCatalog()
const actionById = new Map(catalog.assistantActions.actions.map((action) => [action.id, action]))
const riskPolicy = catalog.assistantRiskPolicy
const found = findAction(catalog, input)
const action = found.selected
if (!action) {
return {
ok: false,
decision: 'action_not_registered',
reason: 'Request did not resolve to a registered assistant action card.',
candidates: found.candidates,
}
}
const access = await resolveAssistantAccess(input, { policy: catalog.assistantAccessPolicy })
const safeAlternativeIds = collectSafeAlternativeIds(action, riskPolicy)
const safeAlternatives = describeAlternatives(safeAlternativeIds, actionById)
if (action.riskLevel === 'destructive' || action.confirmationMode === 'forbidden' || action.adapterStatus === 'forbidden') {
return makeDecision('forbidden', action, input, access, {
reason: 'destructive_or_forbidden_action',
refusal: action.refusal || 'Assistant action is forbidden by risk policy.',
hardDenyIds: action.hardDenyIds || [],
safeAlternatives,
candidates: found.candidates,
})
}
if (action.selfActionPolicy === 'blocked' && isSelfTarget(input)) {
return makeDecision('denied', action, input, access, {
reason: 'self_targeting_blocked',
hardDenyIds: action.hardDenyIds || [],
safeAlternatives,
candidates: found.candidates,
})
}
if (action.selfActionPolicy === 'no_self_lockout' && isSelfTarget(input)) {
const removesOwnAccess = Boolean(input.removesOwnAccess || input.targetRole === 'assistant_blocked' || input.targetStatus === 'disabled' || input.globalStatus === 'blocked')
const hasAlternativeAdminPath = Boolean(input.hasAlternativeAdminPath)
if (removesOwnAccess && !hasAlternativeAdminPath) {
return makeDecision('denied', action, input, access, {
reason: 'self_lockout_denied',
hardDenyIds: unique([...(action.hardDenyIds || []), 'assistant.action.deny.self_lockout']),
safeAlternatives,
candidates: found.candidates,
})
}
}
const missing = missingCapabilities(action, access)
if (missing.length) {
return makeDecision('denied', action, input, access, {
reason: 'assistant_role_missing_capability',
missingCapabilities: missing,
safeAlternatives,
candidates: found.candidates,
})
}
if (action.riskLevel === 'privileged' && access.effectiveRole !== 'assistant_admin') {
return makeDecision('denied', action, input, access, {
reason: 'privileged_action_requires_assistant_admin',
safeAlternatives,
candidates: found.candidates,
})
}
if (action.adapterStatus === 'future') {
return makeDecision('future_adapter', action, input, access, {
reason: 'app_owned_adapter_not_available_yet',
safeAlternatives,
candidates: found.candidates,
})
}
if ((action.confirmationMode === 'explicit' || action.confirmationMode === 'typed') && !input.confirmed) {
return makeDecision('needs_confirmation', action, input, access, {
reason: 'explicit_confirmation_required',
confirmationRequest: {
actionId: action.id,
app: action.app,
targetUserId: input.targetUserId || null,
expectedEffect: action.summary,
},
safeAlternatives,
candidates: found.candidates,
})
}
return makeDecision('allowed', action, input, access, {
reason: action.adapterStatus === 'implemented' ? 'policy_and_adapter_ready' : 'policy_allowed_adapter_not_implemented',
safeAlternatives,
candidates: found.candidates,
})
}
async function readInputJson() {
const inputIndex = process.argv.indexOf('--input-json')
if (inputIndex >= 0) {
const inputPath = process.argv[inputIndex + 1]
if (!inputPath) throw new Error('--input-json requires a path')
return JSON.parse(await fs.readFile(inputPath, 'utf8'))
}
const inlineIndex = process.argv.indexOf('--input')
if (inlineIndex >= 0) {
return JSON.parse(process.argv[inlineIndex + 1] || '{}')
}
return null
}
function assertSmoke(condition, message) {
if (!condition) throw new Error(message)
}
async function runSmoke() {
const validation = await validateCatalog()
assertSmoke(validation.ok, 'catalog must validate before assistant action smoke')
const cases = {
deleteUser: await resolveAssistantAction({
actionId: 'hub.user.delete',
assistantRole: 'admin',
membershipRole: 'client_admin',
actorUserId: 'user_root',
targetUserId: 'user_pupa',
confirmed: true,
}),
blockAsMember: await resolveAssistantAction({
actionId: 'hub.user.block',
assistantRole: 'member',
membershipRole: 'member',
actorUserId: 'user_root',
targetUserId: 'user_pupa',
confirmed: true,
}),
blockNeedsConfirmation: await resolveAssistantAction({
actionId: 'hub.user.block',
assistantRole: 'admin',
membershipRole: 'client_admin',
actorUserId: 'user_root',
targetUserId: 'user_pupa',
}),
blockAllowed: await resolveAssistantAction({
actionId: 'hub.user.block',
assistantRole: 'admin',
membershipRole: 'client_admin',
actorUserId: 'user_root',
targetUserId: 'user_pupa',
confirmed: true,
}),
selfLockout: await resolveAssistantAction({
actionId: 'hub.membership.disable',
assistantRole: 'admin',
membershipRole: 'client_admin',
actorUserId: 'user_root',
targetUserId: 'user_root',
removesOwnAccess: true,
hasAlternativeAdminPath: false,
confirmed: true,
}),
futureEngineAdapter: await resolveAssistantAction({
actionId: 'engine.workflow.share',
assistantRole: 'admin',
membershipRole: 'client_admin',
actorUserId: 'user_root',
targetUserId: 'user_pupa',
confirmed: true,
}),
}
assertSmoke(cases.deleteUser.decision === 'forbidden', 'delete user must be forbidden')
assertSmoke(cases.blockAsMember.decision === 'denied', 'member must not block users')
assertSmoke(cases.blockNeedsConfirmation.decision === 'needs_confirmation', 'privileged write must require confirmation')
assertSmoke(cases.blockAllowed.decision === 'allowed', 'confirmed assistant admin block should be policy-allowed')
assertSmoke(cases.blockAllowed.execution.executionReady, 'implemented HUB allowlist adapter should be execution-ready after policy')
assertSmoke(cases.selfLockout.decision === 'denied', 'self lockout must be denied')
assertSmoke(cases.futureEngineAdapter.decision === 'future_adapter', 'future engine adapter must not execute')
return { ok: true, validation: validation.counts, cases }
}
if (import.meta.url === `file://${process.argv[1]}`) {
if (process.argv.includes('--smoke')) {
console.log(JSON.stringify(await runSmoke(), null, 2))
} else {
const input = await readInputJson()
if (!input) throw new Error('Use --smoke, --input <json>, or --input-json <path>')
console.log(JSON.stringify(await resolveAssistantAction(input), null, 2))
}
}

195
services/ontology-core/src/assistant-policy.mjs Normal file
View File

@ -0,0 +1,195 @@
import { readJson } from './catalog.mjs'
const LAUNCHER_ROOT_GROUPS = new Set(['nodedc:superadmin', 'nodedc:launcher:admin'])
const LAUNCHER_ROOT_ROLES = new Set(['root_admin'])
const LAUNCHER_CLIENT_ADMIN_ROLES = new Set(['client_owner', 'client_admin'])
export async function loadAssistantAccessPolicy() {
return readJson('catalog/assistant-access-policy.json')
}
function normalizeString(value) {
return String(value || '').trim()
}
function normalizeRole(value, policy) {
const raw = normalizeString(value).toLowerCase()
if (!raw) return ''
const roleIds = new Set(policy.roleVocabulary.map((role) => role.id))
if (roleIds.has(raw)) return raw
const alias = policy.roleAliases.find((candidate) => candidate.alias.toLowerCase() === raw)
return alias?.roleId || raw
}
function toStringSet(value) {
if (!Array.isArray(value)) return new Set()
return new Set(value.map((item) => String(item)))
}
function resolveLauncherAdminScope(input) {
const groups = toStringSet(input.groups)
const launcherGlobalRole = normalizeString(input.launcherGlobalRole)
const membershipRole = normalizeString(input.membershipRole)
const membershipStatus = normalizeString(input.membershipStatus || 'active')
const isRoot = Boolean(input.isRoot || input.isSuperAdmin || LAUNCHER_ROOT_ROLES.has(launcherGlobalRole) || [...groups].some((group) => LAUNCHER_ROOT_GROUPS.has(group)))
const isClientAdmin = membershipStatus === 'active' && LAUNCHER_CLIENT_ADMIN_ROLES.has(membershipRole)
return {
isRoot,
isClientAdmin,
present: isRoot || isClientAdmin,
reason: isRoot ? 'launcher_root_scope' : isClientAdmin ? 'launcher_client_admin_scope' : 'no_launcher_admin_scope',
}
}
function uniqueSorted(values) {
return [...new Set(values)].sort()
}
export async function resolveAssistantAccess(input, options = {}) {
const policy = options.policy || await loadAssistantAccessPolicy()
const launcherUserStatus = normalizeString(input.launcherUserStatus || input.globalStatus || 'active')
const membershipStatus = normalizeString(input.membershipStatus || 'active')
const adminScope = resolveLauncherAdminScope(input)
let requestedRole = normalizeRole(input.assistantRole, policy)
if (!requestedRole) {
requestedRole = adminScope.isRoot
? policy.defaultResolution.superAdminDefaultRole
: policy.defaultResolution.activeUserDefaultRole
}
const forcedBlocked = launcherUserStatus === 'blocked' || membershipStatus === 'disabled'
const effectiveRole = forcedBlocked ? policy.defaultResolution.blockedUserEffectiveRole : requestedRole
const matrix = policy.roleMatrix.find((entry) => entry.roleId === effectiveRole)
if (!matrix) {
throw new Error(`Unknown assistant role: ${effectiveRole}`)
}
const allCapabilities = policy.capabilities.map((capability) => capability.id)
let allowedCapabilities = matrix.deniedCapabilities?.includes('*') ? [] : [...(matrix.allowedCapabilities || [])]
const deniedCapabilities = new Set(matrix.deniedCapabilities?.includes('*') ? allCapabilities : matrix.deniedCapabilities || [])
const limitations = []
for (const conditional of matrix.conditionalCapabilities || []) {
if (conditional.requires === 'launcher_admin_scope.root' && adminScope.isRoot) {
allowedCapabilities.push(conditional.capabilityId)
deniedCapabilities.delete(conditional.capabilityId)
} else {
deniedCapabilities.add(conditional.capabilityId)
limitations.push({
capabilityId: conditional.capabilityId,
reason: conditional.requires,
})
}
}
if (effectiveRole === 'assistant_admin' && !adminScope.present) {
for (const capabilityId of matrix.deniedWhenNoAdminScope || []) {
deniedCapabilities.add(capabilityId)
allowedCapabilities = allowedCapabilities.filter((candidate) => candidate !== capabilityId)
}
limitations.push({
reason: 'assistant_admin_requires_existing_launcher_admin_scope',
})
}
if (forcedBlocked) {
allowedCapabilities = []
for (const capabilityId of allCapabilities) {
deniedCapabilities.add(capabilityId)
}
limitations.push({
reason: launcherUserStatus === 'blocked' ? 'launcher_user_blocked' : 'membership_disabled',
})
}
allowedCapabilities = uniqueSorted(allowedCapabilities.filter((capabilityId) => !deniedCapabilities.has(capabilityId)))
return {
ok: true,
requestedRole,
effectiveRole,
visible: Boolean(matrix.visible && !forcedBlocked),
canUse: Boolean(matrix.canUse && !forcedBlocked),
launcherUserStatus,
membershipStatus,
adminScope,
allowedCapabilities,
deniedCapabilities: uniqueSorted([...deniedCapabilities]),
limitations,
hardDenies: policy.hardDenies.map((deny) => deny.id),
}
}
async function readInputJson() {
const inputIndex = process.argv.indexOf('--input-json')
if (inputIndex === -1) return null
const inputPath = process.argv[inputIndex + 1]
if (!inputPath) {
throw new Error('--input-json requires a path')
}
return readJson(inputPath)
}
function assertSmoke(condition, message) {
if (!condition) {
throw new Error(message)
}
}
async function runSmoke() {
const policy = await loadAssistantAccessPolicy()
const member = await resolveAssistantAccess({
assistantRole: 'member',
launcherUserStatus: 'active',
membershipRole: 'member',
}, { policy })
const clientAdmin = await resolveAssistantAccess({
assistantRole: 'admin',
launcherUserStatus: 'active',
membershipRole: 'client_admin',
membershipStatus: 'active',
}, { policy })
const blocked = await resolveAssistantAccess({
assistantRole: 'admin',
launcherUserStatus: 'blocked',
membershipRole: 'client_admin',
}, { policy })
const superAdmin = await resolveAssistantAccess({
groups: ['nodedc:superadmin'],
launcherUserStatus: 'active',
}, { policy })
assertSmoke(member.visible, 'member assistant should be visible')
assertSmoke(!member.allowedCapabilities.includes('assistant.manage_users'), 'member assistant must not manage users')
assertSmoke(clientAdmin.allowedCapabilities.includes('assistant.manage_users'), 'client assistant admin should manage users inside Launcher scope')
assertSmoke(!clientAdmin.allowedCapabilities.includes('assistant.manage_service_catalog'), 'client assistant admin must not get root service catalog capability')
assertSmoke(!blocked.visible && !blocked.canUse, 'blocked assistant must be hidden and unusable')
assertSmoke(superAdmin.effectiveRole === 'assistant_admin', 'superadmin should default to assistant_admin')
assertSmoke(superAdmin.allowedCapabilities.includes('assistant.manage_service_catalog'), 'superadmin should receive root conditional capabilities')
return {
ok: true,
cases: { member, clientAdmin, blocked, superAdmin },
}
}
if (import.meta.url === `file://${process.argv[1]}`) {
if (process.argv.includes('--smoke')) {
console.log(JSON.stringify(await runSmoke(), null, 2))
} else {
const input = await readInputJson()
if (!input) {
throw new Error('Use --smoke or --input-json <path>')
}
console.log(JSON.stringify(await resolveAssistantAccess(input), null, 2))
}
}

76
services/ontology-core/src/catalog.mjs Normal file
View File

@ -0,0 +1,76 @@
import fs from 'node:fs/promises'
import path from 'node:path'
import { fileURLToPath } from 'node:url'
const __filename = fileURLToPath(import.meta.url)
const __dirname = path.dirname(__filename)
export const serviceRoot = path.resolve(__dirname, '..')
export const catalogRoot = path.join(serviceRoot, 'catalog')
export async function readJson(relativePath) {
const fullPath = path.join(serviceRoot, relativePath)
const raw = await fs.readFile(fullPath, 'utf8')
return JSON.parse(raw)
}
export async function loadCatalog() {
const [
entities,
relations,
aliases,
guardrails,
evidence,
resolverRules,
assistantAccessPolicy,
assistantActions,
assistantRiskPolicy,
] = await Promise.all([
readJson('catalog/entities.json'),
readJson('catalog/relations.json'),
readJson('catalog/aliases.json'),
readJson('catalog/guardrails.json'),
readJson('catalog/evidence.json'),
readJson('catalog/resolver-rules.json'),
readJson('catalog/assistant-access-policy.json'),
readJson('catalog/assistant-actions.json'),
readJson('catalog/assistant-risk-policy.json'),
])
const contextBindings = await readJson('catalog/context-bindings.json')
const entityById = new Map(entities.entities.map((entity) => [entity.id, entity]))
const relationById = new Map(relations.relations.map((relation) => [relation.id, relation]))
const contextById = new Map(contextBindings.contexts.map((context) => [context.id, context]))
const bindingTypeById = new Map(contextBindings.bindingTypes.map((bindingType) => [bindingType.id, bindingType]))
const aliasByKey = new Map(
aliases.aliases.map((alias) => [normalizeAlias(alias.alias), alias.canonicalId]),
)
return {
entities,
relations,
aliases,
guardrails,
evidence,
resolverRules,
assistantAccessPolicy,
assistantActions,
assistantRiskPolicy,
contextBindings,
entityById,
relationById,
contextById,
bindingTypeById,
aliasByKey,
}
}
export function normalizeAlias(value) {
return String(value || '').trim().toLowerCase()
}
export function canonicalizeEntityId(value, catalog) {
const raw = String(value || '').trim()
if (!raw) return ''
if (catalog.entityById.has(raw)) return raw
return catalog.aliasByKey.get(normalizeAlias(raw)) || raw
}

280
services/ontology-core/src/registry.mjs Normal file
View File

@ -0,0 +1,280 @@
import fs from 'node:fs/promises'
import path from 'node:path'
import { fileURLToPath } from 'node:url'
import { loadCatalog, serviceRoot } from './catalog.mjs'
import { validateCatalog } from './validate.mjs'
const __filename = fileURLToPath(import.meta.url)
const __dirname = path.dirname(__filename)
const contextBindingsPath = path.resolve(__dirname, '..', 'catalog', 'context-bindings.json')
function usage() {
return [
'Usage:',
' node src/registry.mjs list-contexts',
' node src/registry.mjs list-bindings',
' node src/registry.mjs add-context --input-json examples/engine-context.example.json [--dry-run]',
' node src/registry.mjs add-binding --input-json examples/ops-engine-binding.example.json [--dry-run]',
' node src/registry.mjs import-engine-context --input-json examples/engine-workflow-manifest.example.json [--dry-run]',
].join('\n')
}
function argValue(name) {
const index = process.argv.indexOf(name)
if (index < 0) return ''
return process.argv[index + 1] || ''
}
async function readInputJson() {
const inputPath = argValue('--input-json')
const inputRaw = argValue('--input')
if (inputRaw) return JSON.parse(inputRaw)
if (!inputPath) throw new Error('missing --input-json or --input')
const fullPath = path.resolve(process.cwd(), inputPath)
return JSON.parse(await fs.readFile(fullPath, 'utf8'))
}
async function readContextBindings() {
return JSON.parse(await fs.readFile(contextBindingsPath, 'utf8'))
}
async function writeContextBindings(next) {
const raw = `${JSON.stringify(next, null, 2)}\n`
await fs.writeFile(contextBindingsPath, raw, 'utf8')
}
function required(value, label) {
if (value === undefined || value === null || String(value).trim() === '') {
throw new Error(`${label} is required`)
}
}
function isObject(value) {
return value && typeof value === 'object' && !Array.isArray(value)
}
function slugPart(value) {
return String(value || '')
.trim()
.toLowerCase()
.replace(/[^a-z0-9а-яё]+/giu, '_')
.replace(/^_+|_+$/g, '')
.slice(0, 64) || 'unknown'
}
function validateDraftContext(draft, catalog, registry) {
required(draft.id, 'context.id')
required(draft.surface, 'context.surface')
required(draft.entityId, 'context.entityId')
required(draft.sourceSystem, 'context.sourceSystem')
required(draft.label, 'context.label')
required(draft.status, 'context.status')
if (!catalog.entityById.has(draft.entityId)) throw new Error(`unknown context.entityId: ${draft.entityId}`)
if (!registry.contextStatuses.includes(draft.status)) throw new Error(`invalid context.status: ${draft.status}`)
if (!isObject(draft.refs)) throw new Error('context.refs must be an object')
if (draft.parentContextId && !catalog.contextById.has(draft.parentContextId)) {
throw new Error(`unknown context.parentContextId: ${draft.parentContextId}`)
}
}
function validateDraftBinding(draft, catalog, registry) {
required(draft.id, 'binding.id')
required(draft.typeId, 'binding.typeId')
required(draft.status, 'binding.status')
required(draft.fromContextId, 'binding.fromContextId')
required(draft.toContextId, 'binding.toContextId')
if (!registry.bindingStatuses.includes(draft.status)) throw new Error(`invalid binding.status: ${draft.status}`)
if (!catalog.bindingTypeById.has(draft.typeId)) throw new Error(`unknown binding.typeId: ${draft.typeId}`)
if (!catalog.contextById.has(draft.fromContextId)) throw new Error(`unknown binding.fromContextId: ${draft.fromContextId}`)
if (!catalog.contextById.has(draft.toContextId)) throw new Error(`unknown binding.toContextId: ${draft.toContextId}`)
}
function validateDraftBindingWithKnownContextIds(draft, catalog, registry, knownContextIds) {
required(draft.id, 'binding.id')
required(draft.typeId, 'binding.typeId')
required(draft.status, 'binding.status')
required(draft.fromContextId, 'binding.fromContextId')
required(draft.toContextId, 'binding.toContextId')
if (!registry.bindingStatuses.includes(draft.status)) throw new Error(`invalid binding.status: ${draft.status}`)
if (!catalog.bindingTypeById.has(draft.typeId)) throw new Error(`unknown binding.typeId: ${draft.typeId}`)
if (!knownContextIds.has(draft.fromContextId)) throw new Error(`unknown binding.fromContextId: ${draft.fromContextId}`)
if (!knownContextIds.has(draft.toContextId)) throw new Error(`unknown binding.toContextId: ${draft.toContextId}`)
}
function upsertById(list, item) {
const index = list.findIndex((existing) => existing.id === item.id)
if (index >= 0) {
const next = [...list]
next[index] = item
return { list: next, action: 'updated' }
}
return { list: [...list, item], action: 'created' }
}
async function updateRegistry(mutator, dryRun) {
const beforeRaw = await fs.readFile(contextBindingsPath, 'utf8')
const registry = JSON.parse(beforeRaw)
const next = structuredClone(registry)
const result = mutator(next)
if (dryRun) return { dryRun: true, ...result, registry: next }
await writeContextBindings(next)
const validation = await validateCatalog()
if (!validation.ok) {
await fs.writeFile(contextBindingsPath, beforeRaw, 'utf8')
const err = new Error('registry validation failed; reverted context-bindings.json')
err.validation = validation
throw err
}
return { dryRun: false, ...result, validation: validation.counts }
}
async function listContexts() {
const catalog = await loadCatalog()
return catalog.contextBindings.contexts.map((context) => ({
id: context.id,
surface: context.surface,
entityId: context.entityId,
sourceSystem: context.sourceSystem,
label: context.label,
status: context.status,
refs: context.refs,
parentContextId: context.parentContextId || null,
}))
}
async function listBindings() {
const catalog = await loadCatalog()
return catalog.contextBindings.bindings.map((binding) => ({
id: binding.id,
typeId: binding.typeId,
status: binding.status,
fromContextId: binding.fromContextId,
toContextId: binding.toContextId,
summary: binding.summary || '',
}))
}
async function addContext(dryRun) {
const draft = await readInputJson()
const catalog = await loadCatalog()
const registry = await readContextBindings()
validateDraftContext(draft, catalog, registry)
return updateRegistry((next) => {
const out = upsertById(next.contexts, draft)
next.contexts = out.list
return { action: out.action, context: draft }
}, dryRun)
}
async function addBinding(dryRun) {
const draft = await readInputJson()
const catalog = await loadCatalog()
const registry = await readContextBindings()
validateDraftBinding(draft, catalog, registry)
return updateRegistry((next) => {
const out = upsertById(next.bindings, draft)
next.bindings = out.list
return { action: out.action, binding: draft }
}, dryRun)
}
function buildEngineContextFromManifest(manifest) {
if (!isObject(manifest)) throw new Error('manifest must be an object')
const workflow = manifest.workflow || {}
required(workflow.id, 'workflow.id')
required(workflow.label, 'workflow.label')
const refs = {
workflow_id: String(workflow.id),
}
if (workflow.nodeId) refs.node_id = String(workflow.nodeId)
if (workflow.runtimeWorkflowId) refs.runtime_workflow_id = String(workflow.runtimeWorkflowId)
if (workflow.n8nInstanceId) refs.n8n_instance_id = String(workflow.n8nInstanceId)
return {
id: `context.engine.${slugPart(workflow.id)}`,
surface: 'engine',
entityId: workflow.runtimeWorkflowId ? 'engine.workflow_l2' : 'engine.workflow_l1',
sourceSystem: String(manifest.context?.sourceSystem || 'nodedc-engine'),
label: String(workflow.label),
status: String(manifest.context?.status || 'planned'),
refs,
}
}
function buildOpsEngineBindingFromManifest(manifest, engineContext) {
const bind = manifest.bindToOps || {}
if (bind.enabled !== true) return null
required(bind.fromContextId, 'bindToOps.fromContextId')
return {
id: `binding.ops.${slugPart(bind.fromContextId)}.engine.${slugPart(engineContext.id)}`,
typeId: 'binding_type.ops_card_to_engine_workflow',
status: String(bind.status || 'planned'),
fromContextId: String(bind.fromContextId),
toContextId: engineContext.id,
summary: String(bind.summary || `Binds ${bind.fromContextId} to ${engineContext.id}.`),
}
}
async function importEngineContext(dryRun) {
const manifest = await readInputJson()
const catalog = await loadCatalog()
const registry = await readContextBindings()
const engineContext = buildEngineContextFromManifest(manifest)
const binding = buildOpsEngineBindingFromManifest(manifest, engineContext)
validateDraftContext(engineContext, catalog, registry)
if (binding) {
const knownContextIds = new Set([
...catalog.contextById.keys(),
engineContext.id,
])
validateDraftBindingWithKnownContextIds(binding, catalog, registry, knownContextIds)
}
return updateRegistry((next) => {
const contextOut = upsertById(next.contexts, engineContext)
next.contexts = contextOut.list
let bindingOut = null
if (binding) {
bindingOut = upsertById(next.bindings, binding)
next.bindings = bindingOut.list
}
return {
action: bindingOut ? `${contextOut.action}_context_${bindingOut.action}_binding` : `${contextOut.action}_context`,
context: engineContext,
binding,
}
}, dryRun)
}
async function main() {
const command = process.argv[2]
const dryRun = process.argv.includes('--dry-run')
let output
if (command === 'list-contexts') output = await listContexts()
else if (command === 'list-bindings') output = await listBindings()
else if (command === 'add-context') output = await addContext(dryRun)
else if (command === 'add-binding') output = await addBinding(dryRun)
else if (command === 'import-engine-context') output = await importEngineContext(dryRun)
else {
console.error(usage())
process.exit(2)
}
console.log(JSON.stringify({ ok: true, serviceRoot, command, output }, null, 2))
}
if (import.meta.url === `file://${process.argv[1]}`) {
main().catch((err) => {
console.error(JSON.stringify({
ok: false,
error: err.message || String(err),
validation: err.validation || undefined,
}, null, 2))
process.exit(1)
})
}

212
services/ontology-core/src/resolver.mjs Normal file
View File

@ -0,0 +1,212 @@
import fs from 'node:fs/promises'
import { canonicalizeEntityId, loadCatalog } from './catalog.mjs'
import { validateCatalog } from './validate.mjs'
function tokenize(value) {
return String(value || '')
.toLowerCase()
.split(/[^a-zа-яё0-9_]+/iu)
.filter(Boolean)
}
function scoreRule(rule, input) {
let score = 0
const entityId = input.entityId || ''
if (entityId && rule.inputEntityIds.includes(entityId)) score += 10
if (input.surface && input.surface === rule.fromSurface) score += 6
if (score === 0) return 0
const intentTokens = new Set(tokenize(input.intent))
for (const hint of rule.intentHints || []) {
const hintTokens = tokenize(hint)
if (hintTokens.some((token) => intentTokens.has(token))) score += 2
}
return score
}
function refMatches(candidateRefs = {}, inputRefs = {}) {
const candidateEntries = Object.entries(candidateRefs || {}).filter(([, value]) => value !== undefined && value !== null && String(value).trim() !== '')
const inputEntries = Object.entries(inputRefs || {}).filter(([, value]) => value !== undefined && value !== null && String(value).trim() !== '')
if (!candidateEntries.length || !inputEntries.length) return false
const matches = (entries, refs) => entries.every(([key, value]) => String(refs[key] || '') === String(value))
const candidateInsideInput = matches(candidateEntries, inputRefs)
const inputInsideCandidate = matches(inputEntries, candidateRefs)
if (!candidateInsideInput && !inputInsideCandidate) return false
const matchedKeys = candidateEntries
.map(([key]) => key)
.filter((key) => inputRefs[key] !== undefined && String(inputRefs[key]) === String(candidateRefs[key]))
const hasStrongRef = ['issue_id', 'workflow_id', 'runtime_workflow_id', 'node_id', 'grant_id'].some((key) => matchedKeys.includes(key))
return hasStrongRef || matchedKeys.length >= 2
}
function contextScore(context, input) {
let score = 0
if (input.contextId && input.contextId === context.id) score += 100
if (refMatches(context.refs, input.refs)) score += 40
if (score === 0) return 0
if (input.surface && input.surface === context.surface) score += 10
if (input.entityId && input.entityId === context.entityId) score += 10
return score
}
function findMatchingContexts(catalog, input) {
return catalog.contextBindings.contexts
.map((context) => ({ context, score: contextScore(context, input) }))
.filter((item) => item.score > 0)
.sort((a, b) => b.score - a.score || a.context.id.localeCompare(b.context.id))
}
function bindingTouchesContext(binding, contextIds) {
return contextIds.has(binding.fromContextId) || contextIds.has(binding.toContextId)
}
function findBindingsForContexts(catalog, contexts) {
const contextIds = new Set(contexts.map(({ context }) => context.id))
return catalog.contextBindings.bindings
.filter((binding) => bindingTouchesContext(binding, contextIds))
.map((binding) => ({
...binding,
type: catalog.bindingTypeById.get(binding.typeId) || null,
fromContext: catalog.contextById.get(binding.fromContextId) || null,
toContext: catalog.contextById.get(binding.toContextId) || null,
}))
}
function findRequiredBindingTypes(catalog, selectedRule) {
if (!selectedRule) return []
return catalog.contextBindings.bindingTypes.filter((bindingType) => bindingType.relationId === selectedRule.relationId)
}
export async function resolveContext(input = {}) {
const catalog = await loadCatalog()
const entityId = canonicalizeEntityId(input.entityId || input.alias || input.term, catalog)
const normalizedInput = {
...input,
entityId,
}
const matchedContexts = findMatchingContexts(catalog, normalizedInput)
if (!normalizedInput.entityId && matchedContexts[0]?.context?.entityId) {
normalizedInput.entityId = matchedContexts[0].context.entityId
}
const candidates = catalog.resolverRules.rules
.map((rule) => ({ rule, score: scoreRule(rule, normalizedInput) }))
.filter((item) => item.score > 0)
.sort((a, b) => b.score - a.score || a.rule.id.localeCompare(b.rule.id))
const selected = candidates[0]?.rule || null
const bindings = findBindingsForContexts(catalog, matchedContexts)
const requiredBindingTypes = findRequiredBindingTypes(catalog, selected)
const existingBindingTypeIds = new Set(bindings.map((binding) => binding.typeId))
const missingBindingTypes = requiredBindingTypes.filter((bindingType) => !existingBindingTypeIds.has(bindingType.id))
return {
input: normalizedInput,
canonicalEntity: catalog.entityById.get(normalizedInput.entityId) || null,
matchedContexts: matchedContexts.map(({ context, score }) => ({
id: context.id,
score,
surface: context.surface,
entityId: context.entityId,
label: context.label,
sourceSystem: context.sourceSystem,
refs: context.refs,
status: context.status,
})),
bindings: bindings.map((binding) => ({
id: binding.id,
typeId: binding.typeId,
status: binding.status,
fromContextId: binding.fromContextId,
toContextId: binding.toContextId,
relationId: binding.type?.relationId || null,
summary: binding.summary || binding.type?.summary || '',
})),
missingBindingTypes: missingBindingTypes.map((bindingType) => ({
id: bindingType.id,
relationId: bindingType.relationId,
requiredFromRefs: bindingType.requiredFromRefs || [],
requiredToRefs: bindingType.requiredToRefs || [],
summary: bindingType.summary,
})),
selectedRule: selected,
candidates: candidates.map(({ rule, score }) => ({
id: rule.id,
score,
outputSurface: rule.outputSurface,
outputEntityIds: rule.outputEntityIds,
requiredBindings: rule.requiredBindings,
summary: rule.summary,
})),
}
}
async function resolveFromCli() {
const inputIndex = process.argv.indexOf('--input')
const inputJsonIndex = process.argv.indexOf('--input-json')
let input = null
if (inputIndex >= 0) {
input = JSON.parse(process.argv[inputIndex + 1] || '{}')
} else if (inputJsonIndex >= 0) {
const raw = await fs.readFile(process.argv[inputJsonIndex + 1], 'utf8')
input = JSON.parse(raw)
}
if (!input) {
console.error('Usage: node src/resolver.mjs --input-json examples/ops-card-to-engine-request.json')
process.exit(2)
}
const out = await resolveContext(input)
console.log(JSON.stringify(out, null, 2))
}
async function runSmoke() {
const validation = await validateCatalog()
if (!validation.ok) {
console.error(JSON.stringify(validation, null, 2))
process.exit(1)
}
const samples = [
{ surface: 'ops', alias: 'issue', intent: 'inspect engine workflow for this card' },
{
surface: 'ops',
alias: 'issue',
intent: 'inspect engine workflow for this ontology card',
refs: {
workspace_slug: 'nodedc',
project_id: '86629a11-eaff-4ad2-9f89-e5245a344fcc',
issue_id: '1312519a-0eda-4ea0-9e34-2113c3724ecf',
},
},
{ surface: 'engine', entityId: 'engine.workflow_l1', intent: 'создай карточку в ops по текущему workflow' },
{ surface: 'assistant', entityId: 'assistant.bridge', intent: 'select mcp gateway grant and tool' },
{ term: 'n8n workflow id', intent: 'runtime workflow id lookup' },
]
const results = []
for (const sample of samples) {
const out = await resolveContext(sample)
results.push({
sample,
canonicalEntityId: out.canonicalEntity?.id || out.input.entityId || null,
selectedRuleId: out.selectedRule?.id || null,
outputSurface: out.selectedRule?.outputSurface || null,
outputEntityIds: out.selectedRule?.outputEntityIds || [],
matchedContextIds: out.matchedContexts.map((context) => context.id),
missingBindingTypeIds: out.missingBindingTypes.map((bindingType) => bindingType.id),
})
}
console.log(JSON.stringify({ ok: true, validation: validation.counts, results }, null, 2))
}
if (import.meta.url === `file://${process.argv[1]}` && process.argv.includes('--smoke')) {
await runSmoke()
} else if (import.meta.url === `file://${process.argv[1]}`) {
await resolveFromCli()
}

Some files were not shown because too many files have changed in this diff Show More