Object Ecosystem & Ontologic Contracts

KDCube has moved beyond an app-plus-tools model. The current platform lets independently built subsystems become one interactive ecosystem by exposing canonical object refs, named-service operations, external events, scene surfaces, and block policies. A chat agent, canvas, memory viewer, task widget, file handler, or future subsystem can meet an unfamiliar object through the same contract instead of hardcoded component logic.

The runtime connects those objects through two planes. The event bus carries discrete notifications such as tool calls, tool results, protocol errors, external events, canvas updates, and provider UI events. The data bus carries heavier payloads such as hosted files, materialized named-service objects, search result batches, canvas snapshots, and block-policy projections. The processor binds identity and applies app event-firewall policy before browser clients receive event-bus messages; surfaces fetch data-bus payloads by stable refs when they need full object data.

Core idea: a namespace such as mem, task, fi, or cnv owns object identity. Surfaces render and move those objects. Providers explain how to search, open, materialize, and render them.

Terminology: the public product term is app. Some internal APIs and descriptors still use the older word bundle, for example bundle_id, bundles.yaml, and /bundles/.... In this documentation, “app” means that packaged KDCube application unit.

Named services

Providers publish namespace metadata, schemas, search scopes, object actions, and optional block policies. Consumers use one CRUD/action/search surface for many object systems.

External events

Widgets, integrations, and services can emit typed events with attachments or object refs. Event lanes preserve the boundary between the source system and the agent timeline.

Interactive scene

A scene composes chat, canvas, memory, tasks, and other surfaces. Context pins and drops use canonical refs; the resolver decides which surface should open the object.

Event bus and data bus

The event bus carries live UI-visible events and recorded timeline signals. The data bus carries typed subsystem payloads, hosted files, materialized objects, and coordination payloads that are not just chat text.

Named-Service Journey

The same journey works for memory records, task issues, hosted files, canvas objects, or another namespace an app provides.

1
Object ref appears
A user, widget, event, search result, or agent sees a canonical ref such as mem:record:... or task:issue:....
2
Consumer checks policy
The app config declares which namespaces and operations are available. Tool traits classify operations as exploration, neutral, or exploitation, with namespace-specific overrides when needed.
3
Discovery resolves provider
The named-service registry maps namespace and operation to a provider. Discovery metadata includes about/schema details and fast search-scope hints for tool catalogs.
4
Action, search, or materialization runs
object.search returns refs and display metadata, object.action returns a UI event or file response, and object.get can be used by react.pull to materialize a readable file.
5
Read blocks are produced
The materialized artifact preserves meta.object_ref. When ReAct reads it, namespace-owned block production can turn raw JSON or event payloads into bounded model-readable blocks.
6
Timeline projection can render
If a provider declares block.render, the renderer can ask it to patch the blocks it owns for the model or UI audience. Calls are traced as declared, called, rendered, empty, or error.

ref: mem:record:123
  -> named service discovery: namespace mem
  -> react.pull materializes fi:turn/.../mem_123.json
  -> artifact meta.object_ref = mem:record:123
  -> react.read invokes block production for mem
  -> timeline projection can invoke block.render for mem-owned blocks

Scene Journey

The scene is an orchestration layer for surfaces. It is not a memory component, task component, or canvas component. It brokers context and reactions between surfaces that agree on the canonical context-pin contract.

Source surface
  emits { type: "kdcube.context.attach", contexts: [{ ref: "task:issue:..." }] }
      |
      v
Scene host
  tracks active drag context, namespace styles, and registered target surfaces
      |
      v
Drop target
  canvas: pin the object
  owning widget: call generic object.action(open, object_ref)
      |
      v
Named-service provider
  returns ui_event.target_surface and payload
      |
      v
Target surface
  opens the issue, memory record, file, conversation, or other object

Namespace color and labeling belong to shared namespace configuration. A canvas card, chat context pin, search-result item, and widget preview should style the same namespace consistently.

Agent Tool Governance

ReAct tools are not only function names. The tool catalog carries operational traits that tell the runtime and the model how a call behaves.

Trait	Meaning	Typical examples
`exploration`	Read-only discovery or inspection.	provider about, object schema, list, search, pull/read.
`neutral`	Bookkeeping or low-risk operations compatible with same-round close actions.	memory upsert/proposal in configurations that classify it as neutral.
`exploitation`	Mutation, side effect, deletion, hosting, or external action.	object upsert, delete, host file, send, publish.

These traits support safer batching, clearer protocol violations, and UI-visible tool lifecycle steps. The client can see what tool was proposed, whether the runtime executed or rejected it, and what result or error came back.

Provider and Consumer Checklists

Provider publishes

Namespace, object kinds, labels, and namespace style metadata.
provider.about and object.schema for onboarding.
Search scopes and filter schema for object.search.
Object actions such as open, download, confirm, retire, or custom effects.
Default open-effect action for click behavior.
Block production/render policies when raw objects need model-specific projection.

Consumer configures

Allowed namespaces and operations.
Per-tool and per-namespace traits where defaults need refinement.
Discovery endpoint and provider routing.
Scene surface registry and namespace styles.
Drop behavior through object refs and object actions, not surface-specific guesses.
Identity, budget, and rate-limit context for provider calls.