Ontology Manager prototype alignment¶

How the ontology-manager prototype informs openKMS three Suite Apps — adopt / adapt / skip decisions with rationale.

Decision framework¶

Each UI or IA choice must answer:

Does it map to a distinct user task (schema / instances / code)?
Does it reduce registry vs implementation confusion?
Would it remove a shipped openKMS capability?
Does it require infrastructure we lack (Git repos, multi-ontology, global draft)?
Does it conflict with Header + App Rail + design-system?
If the prototype omits it but Palantir ships it, follow Palantir.

Acceptance: § canonical scope in the implementation plan — not pixel parity with the prototype.

Platform vs domain content¶

Category	Owner	Examples
Platform (Ontology Manager / Logic)	Product engineering	OT/LT CRUD, dataset bind, Neo4j index, Function author→publish→run, Action type registry
Domain ontology (tenant content)	Operators / domain owners (DIY)	Stock / Watchlist types, `screenStocks` source, Tushare mapping choices, analysis notes

Domain market-analysis schemas and Functions are not openKMS product deliverables. Learn concepts in Understanding the ontology; operators follow the Tushare case study; agents use openkms-skill Workflow G.

Capability audit (shipped vs DIY blockers)¶

Shipped — enough for DIY read/compute ontology¶

Capability	Status
Three Suite Apps (Manager / Object Explorer / Function Editor)	✅
Groups CRUD + assign object types	✅
Object types: create, properties, dataset bind, master, sharing, Index Neo4j	✅
Link types + junction/FK + Index	✅
Datasets CRUD (+ Console data sources; Connectors incl. Tushare)	✅
Functions: Editor author / validate / Live Preview; Manager Publish / Observability / execute	✅
Action types: create, bind published Function, activate, execute + audit log	✅ (see blockers)
openkms-skill: data-sources, datasets, connectors, jobs, functions, action-types	✅

Verdict: Building a dataset-backed master type (e.g. Stock), indexing it, and publishing read-only Functions needs no further Manager feature work.

DIY blockers (platform hard gaps)¶

Gap	Impact	Evidence
Action `object_id` for dataset / Neo4j synthetic ids	Explorer rows for dataset/Neo4j-backed objects use synthetic ids (e.g. key property). Triggering an Action with that id 404s	Action execute resolves hand-created / Explorer instance ids only
Action link create/delete apply	Object instance CRUD via edits ships; link-edge edits are not yet an edit-batch op	`edit_apply_service` (objects only)
Action “Rules” ≈ Function binder	Not full submission criteria / parameter forms / multi-step edit rules	Manager Action Rules UI

DIY without waiting on blockers: schema + FoO reads + Action object write-back (create / modify / delete) on Explorer-created instances (e.g. Kanban WorkItem).
Still blocked: Object Explorer row Actions that persist against dataset-backed masters (synthetic object_id).

Soft gaps (P1–P2 UX) — deferred, decoupled from domain DIY¶

Item	Priority	Notes
Explorer Home by group	P1	Adopt list above; not required for Stock + Functions
Manager Discover cards	P2	Overview List/Graph first
Manager top bar ⌘K / Discard·Save draft	P2	Needs draft infra
Global ontology Draft	Skipped	Function-level publish is enough
OT wizard Action stubs without auto-bind	Soft	Bind Functions manually on Action types
Kanban / board UI in Suite Apps	Out of product	Build your own UI; optionally register as a hosted Apps module — not Object Explorer

Do not schedule soft UX with market-analysis work.

Product decision: Action write-back (B1)¶

Decision (2026-08-17): ship object-instance create / modify / delete apply; keep synthetic dataset object_id deferred.

Storage (2026-08-17 follow-up): For object types without a linked dataset:

Role	Store
Apply queue	Postgres `object_instances` — Action/REST edits always land here first
Query SoT	Ontology Neo4j data source — list/get/Apps never read the queue table
Same-request sync	When a Neo4j DS exists, MERGE/DELETE queue changes into Neo4j in the same Action/REST request (no background sync worker; no `synced_at` flag in v1)
Drain	`POST …/index-to-neo4j` on a no-dataset type merges all current queue rows (e.g. after Neo4j is configured later)

Dataset-backed types: Dataset remains the source; Neo4j is an index projection. Action edits against dataset-backed types are rejected.

Choice Meaning

Shipped After a successful Action OFS run, output.edits with op in create / modify / delete apply onto the queue (primary_key = instance id; create may omit primary_key and receive a generated UUID), then same-request Neo4j sync when a Neo4j DS exists. Response includes applied (created_ids / modified_ids / deleted_ids). Neo4j sync failure marks the Action as error (queue transaction rolled back).

Still deferred Action write-back that mutates Dataset rows; link create/delete as edit ops; ofs Client write methods.

Rationale: Kanban DIY and any external board UI need full card CRUD on Explorer-created objects, with Neo4j as the graph/query surface and object_instances as a durable apply queue (including when Neo4j is not yet configured).

Earlier (2026-08-16) modify-only shipping is superseded for object-instance edits.

Adopt¶

Item	Prototype	Rationale	openKMS
Three apps	Platform sidebar: Manager / Code Repos / Explorer	Semantic vs instance vs logic separation	`ontology-manager`, `object-explorer`, `function-editor`
entity-view	Function detail left nav + tabs	Complex entities need stable detail shell	Manager OT / LT / Dataset / Function / Action type detail (`EntityViewShell`)
Function dual surface	Manager registry + Code Repo IDE	Governance ≠ authoring	Manager + Function Editor; single PG store
IDE bottom preview	`FunctionsHelper` Live Preview	Short feedback loop for authors	`function-editor-bottom-panel`
Group browsing	OE Home by group	Business users start from type collections	Explorer Home P1 (deferred)
Manager resource nav	OT / LT / Functions / Action types	Palantir Resources pattern	ManagerNavRail (`/action-types`)

Adapt¶

Item	Prototype	Why not copy	openKMS
Platform shell	`PlatformShell` + Foundry rail	Header + App Rail already exist	Suite apps in App Rail only
Explorer nav	OE top bar only	Prototype incomplete; we have Cypher investment	NavRail: Objects / Links / Explore
Manager home	Discover cards	P0 = schema publish; engineers need overview	Overview List/Graph; Discover P2 (deferred)
Manager top bar	⌘K, Discard/Save P0	Overlaps global search; draft needs P2 infra	P0 list `+ New`; top bar P2 (deferred)
Function workspace	Code Repositories + Git	No VCS backend	Function Editor; PG versions
List pages	`ResourceListPage`	`ontology-admin` already wired to APIs	Reuse pages; unify tokens
Styling	4k-line standalone CSS	design-system consistency	`ontology-admin.scss` + exceptions

Skip¶

Item	Rationale
FoundryHome	openKMS Home + Header
Multi-ontology selector	Single-tenant product boundary
Shared properties	No domain model yet
Fake Git branch/tag	Versions = `ontology_function_versions` + Publish
Published run in Editor	Published runs via Manager / API
localStorage split stores	Backend is source of truth
Global ontology Draft P0	Function-level publish first
Shipping domain ontologies (e.g. market/Tushare Stock)	Tenant DIY content — not product

Current openKMS vs plan¶

Area	Status
Three apps + redirects	✅ Shipped
Cypher Explore in Object Explorer	✅
OT/LT/datasets in Manager	✅
Groups / Functions / Action types	✅ Registry + execute + create/modify/delete apply
Edit link create/delete + synthetic Action object_id	⏸ Deferred (see product decision)
Discover / group Home / global draft chrome	⏸ P1–P2 / skip